Antenna Configuration
- class Antenna
Bases:
SerializableModel of a single antenna.
A set of antenna models defines an antenna array model.
- yaml_tag: Optional[str] = 'Antenna'
YAML serialization tag.
- property_blacklist: Set[str] = {'pos'}
Set of properties to be ignored during serialization.
- property array: Optional[AntennaArray]
Array this antenna belongs to.
- Returns
The array this antenna belong to. None if this antenna is considered floating.
- Return type
Optional[AntennaArray]
- property pos: ndarray
Local position of the antenna within its local coordinate system.
- Returns
Three-dimensional cartesian position vector.
- Return type
np.ndarray
- Raises
ValueError – Floating error if the antenna is not attached to an array.
- transmit(signal)
Transmit a signal over this antenna.
The transmission may be distorted by the antennas impulse response / frequency characteristics.
- receive(signal)
Receive a signal over this antenna.
The reception may be distorted by the antennas impulse response / frequency characteristics.
- abstract polarization(azimuth, elevation)
Generate a single sample of the antenna’s polarization characteristics.
\[\begin{split}\mathbf{F}(\phi, \theta) = \begin{pmatrix} F_{\mathrm{V}}(\phi, \theta) \\ F_{\mathrm{H}}(\phi, \theta) \\ \end{pmatrix}\end{split}\]- Parameters
azimuth (float) – Considered horizontal wave angle in radians \(\phi\).
elevation (float) – Considered vertical wave angle in radians \(\theta\).
- Returns
Vertical and horizontal polarization components of the antenna response.
- Return type
Tuple[float, float]
- plot_polarization(angle_resolution=180)
Visualize the antenna polarization depending on the angles of interest.
- Parameters
angle_resolution (int, optional) – Resolution of the polarization visualization.
- Returns
The created matplotlib figure.
- Return type
np.Figure
- Raises
ValueError – If angle_resolution is smaller than one.
- plot_gain(angle_resolution=180)
Visualize the antenna gain depending on the angles of interest.
- Parameters
angle_resolution (int, optional) – Resolution of the polarization visualization.
- Returns
The created matplotlib figure.
- Return type
np.Figure
- Raises
ValueError – If angle_resolution is smaller than one.
- class IdealAntenna
Bases:
AntennaTheoretic model of an ideal antenna.
Ideal Antenna Characteristics
The assumed characteristic is
\[\begin{split}\mathbf{F}(\phi, \theta) = \begin{pmatrix} \sqrt{2} \\ \sqrt{2} \\ \end{pmatrix}\end{split}\]resulting in unit gain in every direction.
- yaml_tag: Optional[str] = 'IdealAntenna'
YAML serialization tag
- polarization(azimuth, elevation)
Generate a single sample of the antenna’s polarization characteristics.
\[\begin{split}\mathbf{F}(\phi, \theta) = \begin{pmatrix} F_{\mathrm{V}}(\phi, \theta) \\ F_{\mathrm{H}}(\phi, \theta) \\ \end{pmatrix}\end{split}\]- Parameters
azimuth (float) – Considered horizontal wave angle in radians \(\phi\).
elevation (float) – Considered vertical wave angle in radians \(\theta\).
- Returns
Vertical and horizontal polarization components of the antenna response.
- Return type
Tuple[float, float]
- class PatchAntenna
Bases:
AntennaRealistic model of a vertically polarized patch antenna.
Patch Antenna Characteristics
Refer to Jaeckel et al.1 for further information.
- yaml_tag: Optional[str] = 'PatchAntenna'
YAML serialization tag
- polarization(azimuth, elevation)
Generate a single sample of the antenna’s polarization characteristics.
\[\begin{split}\mathbf{F}(\phi, \theta) = \begin{pmatrix} F_{\mathrm{V}}(\phi, \theta) \\ F_{\mathrm{H}}(\phi, \theta) \\ \end{pmatrix}\end{split}\]- Parameters
azimuth (float) – Considered horizontal wave angle in radians \(\phi\).
elevation (float) – Considered vertical wave angle in radians \(\theta\).
- Returns
Vertical and horizontal polarization components of the antenna response.
- Return type
Tuple[float, float]
- class Dipole
Bases:
AntennaModel of vertically polarized half-wavelength dipole antenna.
Dipole Antenna Characteristics
The assumed characteristic is
\[\begin{split}F_\mathrm{V}(\phi, \theta) &= \frac{ \cos( \frac{\pi}{2} \cos(\theta)) }{ \sin(\theta) } \\ F_\mathrm{H}(\phi, \theta) &= 0\end{split}\]- yaml_tag: Optional[str] = 'DipoleAntenna'
YAML serialization tag
- polarization(azimuth, elevation)
Generate a single sample of the antenna’s polarization characteristics.
\[\begin{split}\mathbf{F}(\phi, \theta) = \begin{pmatrix} F_{\mathrm{V}}(\phi, \theta) \\ F_{\mathrm{H}}(\phi, \theta) \\ \end{pmatrix}\end{split}\]- Parameters
azimuth (float) – Considered horizontal wave angle in radians \(\phi\).
elevation (float) – Considered vertical wave angle in radians \(\theta\).
- Returns
Vertical and horizontal polarization components of the antenna response.
- Return type
Tuple[float, float]
- class AntennaArrayBase
Bases:
objectBase class of a model of a set of antennas.
- abstract property num_antennas: int
Number of antenna elements within this array.
- Returns
Number of antenna elements.
- Return type
int
- property num_transmit_antennas: int
Number of transmitting antenna elements within this array.
Returns: Number of transmitting elements.
- Return type
int
- property num_receive_antennas: int
Number of receiving antenna elements within this array.
Returns: Number of receiving elements.
- Return type
int
- abstract property topology: ndarray
Sensor array topology.
Access the array topology as a \(M \times 3\) matrix indicating the cartesian locations of each antenna element within the local coordinate system.
- Returns
math:M times 3 topology matrix, where \(M\) is the number of antenna elements.
- Return type
np.ndarray
- abstract polarization(azimuth, elevation)
Sensor array polarizations towards a certain angle.
- Parameters
azimuth (float) – Azimuth angle of interest in radians.
elevation (float) – Elevation angle of interest in radians.
- Returns
math:M times 2 topology matrix, where \(M\) is the number of antenna elements.
- Return type
np.ndarray
- plot_topology()
Plot a scatter representation of the array topology.
- Returns
The created figure.
- Return type
plt.Figure
- cartesian_response(carrier_frequency, position)
Response of the sensor array towards an impinging point source within its far-field.
Assuming a point source at position \(\mathbf{t} \in \mathbb{R}^{3}\) within the sensor array’s far field, so that \(\lVert \mathbf{t} \rVert_2 \gg 0\), the \(m\)-th array element at position \(\mathbf{q}_m \in \mathbb{R}^{3}\) responds with a factor
\[a_{m} = e^{ \mathrm{j} \frac{2 \pi f_\mathrm{c}}{\mathrm{c}} \lVert \mathbf{t} - \mathbf{q}_{m} \rVert_2 }\]to an electromagnetic waveform emitted with center frequency \(f_\mathrm{c}\). The full array response vector is therefore
\[\mathbf{a} = \left[ a_1, a_2, \dots, a_{M} \right]^{\intercal} \in \mathbb{C}^{M} \mathrm{.}\]- Parameters
carrier_frequency (float) – Center frequency \(f_\mathrm{c}\) of the assumed transmitted signal in Hz.
position (np.ndarray) – Cartesian location \(\mathbf{t}\) of the impinging target within the array’s local coordinate system.
- Returns
The sensor array response vector \(\mathbf{a}\). A one-dimensional, complex-valued numpy array modeling the phase responses of each antenna element.
- Return type
np.ndarray
- Raises
ValueError – If position is not a cartesian vector.
- horizontal_response(carrier_frequency, azimuth, elevation)
Response of the sensor array towards an impinging point source within its far-field.
Assuming a far-field point source impinges onto the sensor array from horizontal angles of arrival azimuth \(\phi \in [0, 2\pi)\) and elevation \(\theta \in [-\pi, \pi]\), the wave vector
\[\begin{split}\mathbf{k}(\phi, \theta) = \frac{2 \pi f_\mathrm{c}}{\mathrm{c}} \begin{pmatrix} \cos( \phi ) \cos( \theta ) \\ \sin( \phi) \cos( \theta ) \\ \sin( \theta ) \end{pmatrix}\end{split}\]defines the phase of a planar wave in horizontal coordinates. The \(m\)-th array element at position \(\mathbf{q}_m \in \mathbb{R}^{3}\) responds with a factor
\[a_{m}(\phi, \theta) = e^{\mathrm{j} \mathbf{k}^\intercal(\phi, \theta)\mathbf{q}_{m} }\]to an electromagnetic waveform emitted with center frequency \(f_\mathrm{c}\). The full array response vector is therefore
\[\mathbf{a}(\phi, \theta) = \left[ a_1(\phi, \theta) , a_2(\phi, \theta) , \dots, a_{M}(\phi, \theta) \right]^{\intercal} \in \mathbb{C}^{M} \mathrm{.}\]- Parameters
carrier_frequency (float) – Center frequency \(f_\mathrm{c}\) of the assumed transmitted signal in Hz.
azimuth (float) – Azimuth angle \(\phi\) in radians.
elevation (float) – Elevation angle \(\theta\) in radians.
- Returns
The sensor array response vector \(\mathbf{a}\). A one-dimensional, complex-valued numpy array modeling the phase responses of each antenna element.
- Return type
np.ndarray
- spherical_response(carrier_frequency, azimuth, zenith)
Response of the sensor array towards an impinging point source within its far-field.
Assuming a far-field point source impinges onto the sensor array from spherical angles of arrival azimuth \(\phi \in [0, 2\pi)\) and zenith \(\theta \in [0, \pi]\), the wave vector
\[\begin{split}\mathbf{k}(\phi, \theta) = \frac{2 \pi f_\mathrm{c}}{\mathrm{c}} \begin{pmatrix} \cos( \phi ) \sin( \theta ) \\ \sin( \phi) \sin( \theta ) \\ \cos( \theta ) \end{pmatrix}\end{split}\]defines the phase of a planar wave in horizontal coordinates. The \(m\)-th array element at position \(\mathbf{q}_m \in \mathbb{R}^{3}\) responds with a factor
\[a_{m}(\phi, \theta) = e^{\mathrm{j} \mathbf{k}^\intercal(\phi, \theta)\mathbf{q}_{m} }\]to an electromagnetic waveform emitted with center frequency \(f_\mathrm{c}\). The full array response vector is therefore
\[\mathbf{a}(\phi, \theta) = \left[ a_1(\phi, \theta) , a_2(\phi, \theta) , \dots, a_{M}(\phi, \theta) \right]^{\intercal} \in \mathbb{C}^{M} \mathrm{.}\]- Parameters
carrier_frequency (float) – Center frequency \(f_\mathrm{c}\) of the assumed transmitted signal in Hz.
azimuth (float) – Azimuth angle \(\phi\) in radians.
zenith (float) – Zenith angle \(\theta\) in radians.
- Returns
The sensor array response vector \(\mathbf{a}\). A one-dimensional, complex-valued numpy array modeling the phase responses of each antenna element.
- Return type
np.ndarray
- class UniformArray(antenna, spacing, dimensions)
Bases:
AntennaArrayBase,SerializableModel of a Uniform Antenna Array.
- Parameters
antenna (Antenna) – The anntenna model this uniform array assumes.
spacing (float) – Spacing between the antenna elements in m.
dimensions (Tuple[int, ... # pragma no cover]) – The number of antennas in x-, y-, and z-dimension.
- yaml_tag: Optional[str] = 'UniformArray'
YAML serialization tag.
- property_blacklist: Set[str] = {'topology'}
Set of properties to be ignored during serialization.
- property spacing: float
Spacing between the antenna elements.
- Returns
Spacing in m.
- Return type
float
- Raises
ValueError – If spacing is less or equal to zero.
- property num_antennas: int
Number of antenna elements within this array.
- Returns
Number of antenna elements.
- Return type
int
- property dimensions: Tuple[int, int, int]
Number of antennas in x-, y-, and z-dimension.
- Returns
Number of antennas in each direction.
- Return type
Tuple[int, int, int]
- property topology: ndarray
Sensor array topology.
Access the array topology as a \(M \times 3\) matrix indicating the cartesian locations of each antenna element within the local coordinate system.
- Returns
math:M times 3 topology matrix, where \(M\) is the number of antenna elements.
- Return type
np.ndarray
- polarization(azimuth, elevation)
Sensor array polarizations towards a certain angle.
- Parameters
azimuth (float) – Azimuth angle of interest in radians.
elevation (float) – Elevation angle of interest in radians.
- Returns
math:M times 2 topology matrix, where \(M\) is the number of antenna elements.
- Return type
np.ndarray
- class AntennaArray(antennas=None, positions=None, orientations=None)
Bases:
AntennaArrayBase,SerializableModel of a set of arbitrary antennas.
- Parameters
antennas (List[Antenna], optional) – Antenna models of each array element.
positions (List[np.ndarray], optional) – Antenna positions of each array element.
orientations (List[np.ndarray], optional) – Antenna orientation of each array element.
- Raises
ValueError – If the argument lists contain an unequal amount of objects.
- yaml_tag: Optional[str] = 'CustomArray'
YAML serialization tag.
- property antennas: List[Antenna]
Antennas within this array.
- Returns
List of antenna elements.
- Return type
List[Antenna]
- property num_antennas: int
Number of antenna elements within this array.
- Returns
Number of antenna elements.
- Return type
int
- property positions: List[ndarray]
Antenna positions within the array
Returns: List of carthesian vectors.
- Return type
List[ndarray]
- property orientations: List[ndarray]
Antenna orientations within the array
Returns: List of horizaontal orientation vectors.
- Return type
List[ndarray]
- add_antenna(antenna, position, orientation)
Add a new antenna element to this array.
- Parameters
antenna (Antenna) – The new antenna to be added.
position (np.ndarray) – Position of the antenna within the local coordinate system.
orientation (np.ndarray, optional) – Orientation of the antenna within the local coordinate system.
- Raises
ValueError – If the position is not a three-dimensional vector. If the specified orientation is not a tuple of azimuth and elevation angles.
- Return type
None
- remove_antenna(antenna)
Remove an antenna element from this array.
- Parameters
antenna (Antenna) – The antenna element to be removed.
- Return type
None
- property topology: ndarray
Sensor array topology.
Access the array topology as a \(M \times 3\) matrix indicating the cartesian locations of each antenna element within the local coordinate system.
- Returns
math:M times 3 topology matrix, where \(M\) is the number of antenna elements.
- Return type
np.ndarray
- polarization(azimuth, elevation)
Sensor array polarizations towards a certain angle.
- Parameters
azimuth (float) – Azimuth angle of interest in radians.
elevation (float) – Elevation angle of interest in radians.
- Returns
math:M times 2 topology matrix, where \(M\) is the number of antenna elements.
- Return type
np.ndarray
- classmethod to_yaml(representer, node)
Serialize a serializable object to YAML.
- Parameters
representer (SafeRepresenter) – A handle to a representer used to generate valid YAML code. The representer gets passed down the serialization tree to each node.
node (AntennaArray) – The channel instance to be serialized.
Returns: The serialized YAML node.
- Return type
MappingNode
- classmethod from_yaml(constructor, node)
Recall a new serializable class instance from YAML.
- Parameters
constructor (SafeConstructor) – A handle to the constructor extracting the YAML information.
node (Node) – YAML node representing the AntennaArray serialization.
Returns: The de-serialized object.
- Return type
- 1
Stephan Jaeckel, Kai Borner, Lars Thiele, and Volker Jungnickel. A geometric polarization rotation model for the 3-d spatial channel model. IEEE Transactions on Antennas and Propagation, 60(12):5966–5977, 2012. doi:10.1109/TAP.2012.2214017.