Antenna Configuration

class Antenna

Bases: hermespy.core.factory.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 array: Optional[hermespy.core.antennas.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: numpy.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(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: hermespy.core.antennas.Antenna

Theoretic model of an ideal antenna.

Ideal Antenna Gain

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.

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: hermespy.core.antennas.Antenna

Realistic model of a vertically polarized patch antenna.

Patch Antenna Gain

Patch Antenna Characteristics

Refer to Jaeckel et al.1 for further information.

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: hermespy.core.antennas.Antenna

Model of vertically polarized half-wavelength dipole antenna.

Dipole Antenna Gain

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

abstract property topology: numpy.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: hermespy.core.antennas.AntennaArrayBase, hermespy.core.factory.Serializable

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, ...]) – The number of antennas in x-, y-, and z-dimension.

yaml_tag: Optional[str] = 'UniformArray'

YAML serialization tag.

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: numpy.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

Bases: hermespy.core.factory.Serializable

Model of a set of arbitrary antennas.

property antennas: List[hermespy.core.antennas.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, 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: numpy.ndarray
Return type

ndarray

polarization(azimuth, elevation)
Return type

ndarray

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.