# Antenna Configuration

class Antenna

Bases: Serializable

Model 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.

Parameters

signal (Signal) – received The signal model to be transmitted.

Returns

The actually transmitted (distorted) signal model.

Return type

Signal

Receive a signal over this antenna.

The reception may be distorted by the antennas impulse response / frequency characteristics.

Parameters

signal (Signal) – The signal model to be received.

Returns

The actually received (distorted) signal model.

Return type

Signal

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: Antenna

Theoretic model of an ideal antenna.

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: Antenna

Realistic model of a vertically polarized patch antenna.

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: Antenna

Model of vertically polarized half-wavelength dipole antenna.

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: object

Base 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

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)

Model 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

property antenna: Antenna

The assumed antenna model.

Returns: The antenna model.

Return type

Antenna

class AntennaArray(antennas=None, positions=None, orientations=None)

Model 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 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

AntennaArray

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.