Antenna Configuration

class Antenna(pose=None)

Bases: Transformable, Serializable

Model of a single antenna.

A set of antenna models defines an antenna array model.

Parameters:

pose (Transformation, optional) – The antenna’s position and orientation with respect to its array.

yaml_tag: Optional[str] = 'Antenna'

YAML serialization tag.

property array: AntennaArray | None

Array this antenna belongs to.

Returns:

The array this antenna belong to. None if this antenna is considered floating.

Return type:

Optional[AntennaArray]

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(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 local_characteristics(azimuth, elevation)

Generate a single sample of the antenna’s characteristics.

The polarization is characterized by the angle-dependant field vector

\[\begin{split}\mathbf{F}(\phi, \theta) = \begin{pmatrix} F_{\mathrm{H}}(\phi, \theta) \\ F_{\mathrm{V}}(\phi, \theta) \\ \end{pmatrix}\end{split}\]

denoting the horizontal and vertical field components. The directional antenna gain can be computed from the polarization vector magnitude

\[\begin{split}A(\phi, \theta) &= \lVert \mathbf{F}(\phi, \theta) \rVert \\ &= \sqrt{ F_{\mathrm{H}}(\phi, \theta)^2 + F_{\mathrm{V}}(\phi, \theta)^2 }\end{split}\]

Parameters:

• azimuth (float) – Considered horizontal wave angle in radians \(\phi\).

• elevation (float) – Considered vertical wave angle in radians \(\theta\).

Return type:

ndarray

Returns:

Two dimensional numpy array denoting the horizontal and vertical ploarization components of the antenna response vector.

global_characteristics(global_direction)

Query the antenna’s polarization characteristics towards a certain direction of interest.

Parameters:

global_direction (Direction) – Cartesian direction unit vector of interest.

Return type:

ndarray

Returns:

Two-dimensional numpy vector representing the antenna’s polarization components.

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.

Return type:

Figure

Returns:

The created matplotlib 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.

Return type:

Figure

Returns:

The created matplotlib figure.

Raises:

ValueError – If angle_resolution is smaller than one.

class IdealAntenna(pose=None)

Bases: Antenna

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

Parameters:

pose (Transformation, optional) – The antenna’s position and orientation with respect to its array.

yaml_tag: Optional[str] = 'IdealAntenna'

YAML serialization tag

local_characteristics(azimuth, elevation)

Generate a single sample of the antenna’s characteristics.

The polarization is characterized by the angle-dependant field vector

\[\begin{split}\mathbf{F}(\phi, \theta) = \begin{pmatrix} F_{\mathrm{H}}(\phi, \theta) \\ F_{\mathrm{V}}(\phi, \theta) \\ \end{pmatrix}\end{split}\]

denoting the horizontal and vertical field components. The directional antenna gain can be computed from the polarization vector magnitude

\[\begin{split}A(\phi, \theta) &= \lVert \mathbf{F}(\phi, \theta) \rVert \\ &= \sqrt{ F_{\mathrm{H}}(\phi, \theta)^2 + F_{\mathrm{V}}(\phi, \theta)^2 }\end{split}\]

Parameters:

• azimuth (float) – Considered horizontal wave angle in radians \(\phi\).

• elevation (float) – Considered vertical wave angle in radians \(\theta\).

Return type:

ndarray

Returns:

Two dimensional numpy array denoting the horizontal and vertical ploarization components of the antenna response vector.

class LinearAntenna(slant=0.0, pose=None)

Bases: Antenna

Model of a linearly polarized ideal antenna.

The assumed characteristic is

\[\begin{split}\mathbf{F}(\theta, \phi, \zeta) = \begin{pmatrix} \cos (\zeta) \\ \sin (\zeta) \\ \end{pmatrix}\end{split}\]

with \(zeta = 0\) resulting in vertical polarization and \(zeta = \pi / 2\) resulting in horizontal polarization.

Initialize a new linear antenna.

Parameters:

• slant (float) – Slant of the antenna in radians.

• pose (Transformation, optional) – Pose of the antenna.

yaml_tag: Optional[str] = 'LinearAntenna'

YAML serialization tag.

property slant: float

Slant of the antenna in radians.

local_characteristics(azimuth, zenith)

Generate a single sample of the antenna’s characteristics.

The polarization is characterized by the angle-dependant field vector

\[\begin{split}\mathbf{F}(\phi, \theta) = \begin{pmatrix} F_{\mathrm{H}}(\phi, \theta) \\ F_{\mathrm{V}}(\phi, \theta) \\ \end{pmatrix}\end{split}\]

denoting the horizontal and vertical field components. The directional antenna gain can be computed from the polarization vector magnitude

\[\begin{split}A(\phi, \theta) &= \lVert \mathbf{F}(\phi, \theta) \rVert \\ &= \sqrt{ F_{\mathrm{H}}(\phi, \theta)^2 + F_{\mathrm{V}}(\phi, \theta)^2 }\end{split}\]

Parameters:

• azimuth (float) – Considered horizontal wave angle in radians \(\phi\).

• elevation (float) – Considered vertical wave angle in radians \(\theta\).

Return type:

ndarray

Returns:

Two dimensional numpy array denoting the horizontal and vertical ploarization components of the antenna response vector.

class PatchAntenna(pose=None)

Bases: Antenna

Realistic model of a vertically polarized patch antenna.

Patch Antenna Characteristics

Refer to Jaeckel et al.[1] for further information.

Parameters:

pose (Transformation, optional) – The antenna’s position and orientation with respect to its array.

yaml_tag: Optional[str] = 'PatchAntenna'

YAML serialization tag

local_characteristics(azimuth, elevation)

Generate a single sample of the antenna’s characteristics.

The polarization is characterized by the angle-dependant field vector

\[\begin{split}\mathbf{F}(\phi, \theta) = \begin{pmatrix} F_{\mathrm{H}}(\phi, \theta) \\ F_{\mathrm{V}}(\phi, \theta) \\ \end{pmatrix}\end{split}\]

denoting the horizontal and vertical field components. The directional antenna gain can be computed from the polarization vector magnitude

\[\begin{split}A(\phi, \theta) &= \lVert \mathbf{F}(\phi, \theta) \rVert \\ &= \sqrt{ F_{\mathrm{H}}(\phi, \theta)^2 + F_{\mathrm{V}}(\phi, \theta)^2 }\end{split}\]

Parameters:

• azimuth (float) – Considered horizontal wave angle in radians \(\phi\).

• elevation (float) – Considered vertical wave angle in radians \(\theta\).

Return type:

ndarray

Returns:

Two dimensional numpy array denoting the horizontal and vertical ploarization components of the antenna response vector.

class Dipole(pose=None)

Bases: Antenna

Model 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}\]

Parameters:

pose (Transformation, optional) – The antenna’s position and orientation with respect to its array.

yaml_tag: Optional[str] = 'DipoleAntenna'

YAML serialization tag

local_characteristics(azimuth, elevation)

Generate a single sample of the antenna’s characteristics.

The polarization is characterized by the angle-dependant field vector

\[\begin{split}\mathbf{F}(\phi, \theta) = \begin{pmatrix} F_{\mathrm{H}}(\phi, \theta) \\ F_{\mathrm{V}}(\phi, \theta) \\ \end{pmatrix}\end{split}\]

denoting the horizontal and vertical field components. The directional antenna gain can be computed from the polarization vector magnitude

\[\begin{split}A(\phi, \theta) &= \lVert \mathbf{F}(\phi, \theta) \rVert \\ &= \sqrt{ F_{\mathrm{H}}(\phi, \theta)^2 + F_{\mathrm{V}}(\phi, \theta)^2 }\end{split}\]

Parameters:

• azimuth (float) – Considered horizontal wave angle in radians \(\phi\).

• elevation (float) – Considered vertical wave angle in radians \(\theta\).

Return type:

ndarray

Returns:

Two dimensional numpy array denoting the horizontal and vertical ploarization components of the antenna response vector.

class AntennaArrayBase(pose=None)

Bases: Transformable

Base class of a model of a set of antennas.

Parameters:

pose (Transformation, optional) – Transformation of the transformable with respect to its reference frame. By default, no transformation is considered, i.e. Transformation.No()

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.

property num_receive_antennas: int

Number of receiving antenna elements within this array.

Returns: Number of receiving elements.

abstract property antennas: List[Antenna]

All individual antenna elements within this array.

Returns: List of antennas.

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:

\(M \times 3\) topology matrix, where \(M\) is the number of antenna elements.

Return type:

np.ndarray

characteristics(arg_0, frame='local')

Return type:

ndarray

plot_topology()

Plot a scatter representation of the array topology.

Returns:

The created figure.

Return type:

plt.Figure

cartesian_phase_response(carrier_frequency, position, frame='local')

Phase 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 the,refore

\[\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.

• frame (Literal['local', 'global']) – Coordinate system reference frame. local by default. local assumes position to be in the antenna array’s native coordiante system. global assumes position to be in the antenna array’s root coordinate system.

Return type:

ndarray

Returns:

The sensor array response vector \(\mathbf{a}\). A one-dimensional, complex-valued numpy array modeling the phase responses of each antenna element.

Raises:

ValueError – If position is not a cartesian vector.

cartesian_array_response(carrier_frequency, position, frame='local')

Sensor array charactersitcis towards an impinging point source within its far-field.

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.

• frame (Literal['local', 'global']) – Coordinate system reference frame. global by default. local assumes position to be in the antenna array’s native coordiante system. global assumes position to be in the antenna array’s root coordinate system.

Return type:

ndarray

Returns:

The sensor array response matrix \(\mathbf{A} \in \mathbb{C}^{M \times 2}\). A one-dimensional, complex-valued numpy matrix modeling the far-field charactersitics of each antenna element.

Raises:

ValueError – If position is not a cartesian vector.

horizontal_phase_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_phase_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, pose=None)

Bases: AntennaArrayBase, Serializable

Model of a Uniform Antenna Array.

Parameters:

• antenna (Type[Antenna] | Antenna) – The anntenna model this uniform array assumes.

• spacing (float) – Spacing between the antenna elements in m.

• dimensions (Sequence[int]) – The number of antennas in x-, y-, and z-dimension.

• pose (Tranformation, optional) – The anntena array’s transformation with respect to its device.

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, ...]

Number of antennas in x-, y-, and z-dimension.

Returns: Number of antennas in each direction.

property antennas: List[Antenna]

All individual antenna elements within this array.

Returns: List of antennas.

property antenna: Type[Antenna] | Antenna

The assumed antenna model.

Returns: The antenna model.

class AntennaArray(antennas=None, pose=None)

Bases: AntennaArrayBase, Serializable

Model of a set of arbitrary antennas.

Parameters:

• antennas (List[Antenna], optional) – Antenna models of each array element.

• pose (Transformation, optional) – The anntena array’s transformation with respect to its device.

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

add_antenna(antenna)

Add a new antenna element to this array.

Parameters:

antenna (Antenna) – The new antenna to be added.

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

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