Beamforming

lyceanem.electromagnetics.beamforming.AnimatedPatterns(pattern_list, command_vectors, field_radius=1.0, plot_scalar='Poynting_Vector_(Magnitude_(W/m2))', log_type='power', plot_max=None, filename='BeamformingExport.mp4')[source]

Create an animated plot of the beamforming patterns, with a command vector overlay.

Parameters:

  • pattern_list (list) – A list of meshio.Mesh objects, each containing the field data for a different beamformed response.

  • command_vectors (numpy.ndarray of float) – The (N,Azimuth,Elevation) command vectors for each pattern in the pattern_list, where N is the number of patterns.

  • field_radius (float) – The radius of the field, used to scale the normals and points in the mesh, the maximum of the selected data will be scaled to this value.

  • plot_scalar (str, optional) – The label for the data to be plotted, this should be a key in the point_data of the field_data mesh. Defaults to “Poynting_Vector_(Magnitude_(W/m2))”.

  • log_type (str, optional) – The type of logarithm to use for the data, either “amplitude” or “power”. Defaults to “power”.

  • plot_max (float, optional) – The maximum value for the plot, if None, it will be calculated as the maximum of the log data rounded up to the nearest 5. Defaults to None.

  • filename (str, optional) – The filename for the output video file, defaults to “BeamformingExport.mp4”.

Returns:

This function creates an animated video file of the beamforming patterns, which will be saved to the specified filename.

Return type:

None

lyceanem.electromagnetics.beamforming.ArbitaryCoherenceWeights(source_coords, target_coord, wavelength)[source]

Generate Wavefront coherence weights based upon the desired wavelength and the coordinates of the target point

Parameters:

  • source_coords (numpy.ndarray of float) – The coordinates of the elements, arranged in terms of x, y, and z coordinates

  • target_coord (numpy.ndarray of float) – The target coordinate for the beamforming, arranged in terms of x, y, and z coordinates

  • wavelength (float) – The wavelength of interest, used to calculate the phase delays

Returns:

weights – The wavefront coherence weights for the specified target coordinate, arranged as a 1D array of complex numbers

Return type:

numpy.ndarray of complex

lyceanem.electromagnetics.beamforming.EGCWeights(Etheta, Ephi, command_angles, polarization_switch='Etheta', az_range=None, elev_range=None)[source]

calculate the equal gain combining weights for a given set of element coordinates, wavelength, and command angles (az,elev)

Parameters:

  • Etheta (numpy.ndarray of complex) – The Etheta polarisation farfield patterns, arranged in terms of the number of elements, azimuth resolution, and elevation resolution

  • Ephi (numpy.ndarray of complex) – The Ephi polarisation farfield patterns, arranged in terms of the number of elements, azimuth resolution, and elevation resolution

  • command_angles (numpy.ndarray of float) – The command angles for the beamfroming, arranged as [azimuth,elevation]

  • polarization_switch (str) – The polarisation to be used for the beamforming, either [Etheta] or [Ephi]. Default is [Etheta]

  • az_range (numpy.ndarray of float) – The azimuth values for the farfield mesh, arranged from smallest to largest

  • elev_range (numpy.ndarray of float) – The elevation values for the farfield mesh, arranged from smallest to largest

Returns:

weights – The equal gain combining weights for the specified command angles, arranged as a 1D array of complex numbers

Return type:

numpy.ndarray of complex

lyceanem.electromagnetics.beamforming.MaximumDirectivityMap(Etheta, Ephi, source_coords, wavelength, az_range=None, elev_range=None, az_index=None, elev_index=None, forming='Total', total_solid_angle=12.566370614359172, phase_resolution=24)[source]

Uses wavefront beamsteering, and equal gain combining algorithms to steer the antenna array to each possible command angle in the farfield, mapping out the maximum achieved directivity at the command angle for each command angle set.

Parameters:

  • Etheta (numpy.ndarray of complex) – The E\theta polarisation farfield patterns, arranged in terms of the number of elements, azimuth resolution, and elevation resolution

  • Ephi (numpy.ndarray of complex) – The E\phi polarisation farfield patterns, arranged in terms of the number of elements, azimuth resolution, and elevation resolution

  • source_coords (meshio.Mesh) – The source coordinates of each element, corresponding to the order of element patterns in E\theta or E\phi. Units should be m

  • wavelength (float) – The wavelength of interest

  • az_range (numpy.ndarray of float) – The azimuth values for the farfield mesh, arranged from smallest to largest

  • elev_range (numpy.ndarray of float) – The elevation values for the farfield mesh, arranged from smallest to largest

  • az_index (numpy.ndarray of int) – optional parameter, can be specified as an index of the azimuth values of interest via indexing, defaults to [None], which ensures all values are covered

  • elev_index (numpy.ndarray of int) – optional parameter, can be specified as an index of the elevation values of interest via indexing, defaults to [None], which ensures all values are covered

  • forming (str) – Which polarisation should be beamformed, the default is [Total], beamforming the total directivity pattern, avoiding issues with elements which have a strongly E\theta or E\phi pattern. This can also be set to [Etheta] or [Ephi]

  • total_solid_angle (float) – the total solid angle covered by the farfield patterns, this defaults to 4\pi for a full spherical pattern

  • phase_resolution (int) – the desired phase resolution of the beamforming architecture in bits. Default is [24], which means no practical truncation will occur. If beam mapping at a single resolution is required, then this can be set between 2 and 24. If multiple values are required, it may be more efficient to use lyceanem.electromagnetics.beamforming.MaximumDirectivityMapDiscrete(), which allows a 1D array of resolutions to be supplied, and produces a maximum directivity map for each.

Returns:

directivity_map – The achieved maximum directivity map. At each point the directivity corresponds to the achieved directivity at that command angle. Arranged as elev axis, azimuth axis, Dtheta,Dphi,Dtot

Return type:

numpy.ndarray of float

lyceanem.electromagnetics.beamforming.MaximumDirectivityMapDiscrete(Etheta, Ephi, source_coords, wavelength, az_range=None, elev_range=None, az_index=None, elev_index=None, forming='Total', total_solid_angle=12.566370614359172, phase_resolution=array([24]))[source]

Uses wavefront beamsteering, and equal gain combining algorithms to steer the antenna array to each possible command angle in the farfield, mapping out the maximum achieved directivity at the command angle for each command angle set.

Parameters:

  • Etheta (numpy.ndarray of complex) – The E\theta polarisation farfield patterns, arranged in terms of the number of elements, azimuth resolution, and elevation resolution

  • Ephi (numpy.ndarray of complex) – The E\phi polarisation farfield patterns, arranged in terms of the number of elements, azimuth resolution, and elevation resolution

  • source_coords (meshio.Mesh) – The source coordinates of each element, corresponding to the order of element patterns in E heta and E\phi. Units should be m

  • wavelength (float) – The wavelength of interest

  • az_res (int) – Azimuth resolution

  • elev_res (int) – Elevation resolution

  • az_range (numpy.ndarray of float) – The azimuth values for the farfield mesh, arranged from smallest to largest

  • elev_range (numpy.ndarray of float) – The elevation values for the farfield mesh, arranged from smallest to largest

  • forming (str) – Which polarisation should be beamformed, the default is [Total], beamforming the total directivity pattern, avoiding issues with elements which have a strongly $E heta$ or $Ephi$ pattern. This can also be set to [Etheta] or [Ephi]

  • total_solid_angle (float) – the total solid angle covered by the farfield patterns, this defaults to 4\pi for a full spherical pattern

  • phase_resolution (numpy.ndarray of int) – the desired phase resolution of the beamforming architecture in bits. Default is [24], which means no practical truncation will occur. If beam mapping is desired at a single resolution is required, then this can be set between 2 and 24, if more than one resolution value is required, then a 1D array of values can be specified. resolutions to be supplied, and produces a maximum directivity map for each.

Returns:

directivity_map – The achieved maximum directivity map (a 3D numpy array for each phase resolution) . For each phase resolution for each point the directivity corresponds to the achieved directivity at that command angle.

Return type:

numpy.ndarray of float

lyceanem.electromagnetics.beamforming.OAMFourier(Ex, Ey, Ez, coordinates, mode_limit, first_dimension, second_dimension, coord_format='AzEl')[source]

Compute the mode index, mode coefficients, and mode probabilities with the co and crosspolar (Etheta,Ephi), tentatively also supports for Ex,Ey,Ez

Parameters:

  • Ex (numpy.ndarray of complex) – The Ex component of the electric field, arranged in terms of azimuth resolution and elevation resolution

  • Ey (numpy.ndarray of complex) – The Ey component of the electric field, arranged in terms of azimuth resolution and elevation resolution

  • Ez (numpy.ndarray of complex) – The Ez component of the electric field, arranged in terms of azimuth resolution and elevation resolution

  • coordinates (numpy.ndarray of float) – The coordinates of the elements, arranged in terms of x, y, and z coordinates

  • mode_limit (int) – The maximum OAM mode to be considered for the calculation, should be an integer value

  • first_dimension (numpy.ndarray of float) – if the coordinate system is spherical, this should be the azimuth range

  • second_dimension (numpy.ndarray of float) – if the coordinate system is spherical, this should be the elevation range

  • coord_format (str) – The coordinate system to be used for the calculation, either [xyz] or [AzEl]. Default is [AzEl]

Returns:

  • mode_index (numpy.ndarray of int) – The OAM mode index, arranged as a 1D array of integers

  • mode_coefficients (numpy.ndarray of float) – The OAM mode coefficients, arranged in terms of the number of modes and the number of polarisation components

  • mode_probabilites (numpy.ndarray of float) – The OAM mode probabilities, arranged in terms of the number of modes and the number of polarisation components

lyceanem.electromagnetics.beamforming.OAMWeights(x, y, mode)[source]

Generate Orbital Angular Momentum (OAM) mode weights, based upon the radial angle of each element.

Parameters:

  • x (numpy.ndarray of float) – The x coordinates of the elements

  • y (numpy.ndarray of float) – The y coordinates of the elements

  • mode (int) – The OAM mode to be used for the weights, should be an integer value

Returns:

weights – The OAM weights for the specified mode, arranged as a 1D array of complex numbers

Return type:

numpy.ndarray of complex

lyceanem.electromagnetics.beamforming.PatternPlot(data, az, elev, pattern_min=-40, plot_max=0.0, plottype='Polar', logtype='amplitude', ticknum=6, title_text=None)[source]

Plot the relevant 3D data in relative power (dB) or normalised directivity (dBi)

Parameters:

  • data (numpy.ndarray of float) – the data to plot

  • az (numpy.ndarray of float) – the azimuth angles for each datapoint in [data] in degrees

  • elev (numpy.ndarray of float) – the elevation angles for each datapoint in [data] in degrees

  • pattern_min (float) – the desired scale minimum in dB, default is [-40]

  • plot_max (float) – the desired scale maximum in dB, default is [0]

  • plottype (str) – the plot type, either [Polar], [Cartesian-Surf], or [Contour]. The default is [Polar]

  • logtype (str) – the type of data being considered, either [amplitude] or [power], to ensure the correct logarithm is used, default is [amplitude]

  • ticknum (int) – the number of ticks on the colorbar, default is [6]

  • title_text (str) – the graph title, defaults to [None]

Return type:

None

lyceanem.electromagnetics.beamforming.PatternPlot2D(data, az, pattern_min=-40, plot_max=0.0, logtype='amplitude', ticknum=6, line_labels=None, title_text=None, fontsize=16)[source]

Plot the relevant 2D data in relative power (dB) or normalised directivity (dBi) in a polar plot.

Parameters:

  • data (numpy.ndarray of float) – The data to plot, should be a 1D array for a single line or a 2D array for multiple lines.

  • az (numpy.ndarray of float) – The azimuth angles for each datapoint in [data] in degrees.

  • pattern_min (float) – The desired scale minimum in dB, default is [-40].

  • plot_max (float) – The desired scale maximum in dB, default is [0].

  • logtype (str) – The type of data being considered, either “amplitude” or “power”, to ensure the correct logarithm is used, default is “amplitude”.

  • ticknum (int) – The number of ticks on the radial axis, default is [6].

  • line_labels (list of str, optional) – Labels for each line in the plot, if provided, will be used in the legend.

  • title_text (str, optional) – The graph title, defaults to [None].

  • fontsize (int, optional) – The font size for the plot, default is [16].

Return type:

None

lyceanem.electromagnetics.beamforming.Steering_Efficiency(Dtheta, Dphi, Dtot, first_dimension_angle, second_dimension_angle, angular_coverage)[source]

Calculate Steering Efficiency for the provided pattern, in radians

Parameters:

  • Dtheta (numpy.ndarray of complex or float) – Directivity for the E\theta polarisation.

  • Dphi (numpy.ndarray of complex or float) – Directivity for the E\phi polarisation.

  • Dtot (numpy.ndarray of complex or float) – Total Directivity pattern

  • first_dimension_angle (float) – the angle in radians of the first dimension, should be 2\pi for a full azimuth sweep

  • second_dimension_angle (float) – the angle in radians of the second dimension, should be \pi for a full elevation sweep

  • angular_coverage (float) – the total angular coverage to be considered, should be 4\pi steradians for a full sphere.

Returns:

  • setheta (float) – steering efficiency in Dtheta

  • sephi (float) – steering efficiency in Dphi

  • setot (float) – steering efficiency in Dtotal

lyceanem.electromagnetics.beamforming.TimeDelayBeamform(excitation_function, weights, sampling_rate)[source]

The time delay beamform function takes an n by 2 or n by 3 array, and applies the supplied time delay weights to each by rolling each slice of the array by the required number of sampling intervals. Only positive time delays should be applied, but if positive and negative values are required for weighting, a constant value should be applied so that no delay is less than 0ns.

Parameters:

  • excitation_function (numpy.ndarray of float) – excitation function for time domain antenna array

  • weights (numpy.ndarray of complex) – magnitude is the real part, while the imaginary part is the time_delay in ns

  • sampling_rate (float) – sampling rate in Hz, used to calculate the shifts to align the excitation function.

Returns:

beamformed_function – The beamformed excitation function, with the time delays applied.

Return type:

numpy.ndarray of float

lyceanem.electromagnetics.beamforming.TimeDelayWeights(source_coords, steering_vector, magnitude=1.0, maximum_delay=10)[source]

Generate time delay weights to focus on a target coordinate, with delays in nanoseconds

Parameters:

  • source_coords (numpy.ndarray of float) – The coordinates of the elements, arranged in terms of x, y, and z coordinates

  • steering_vector (numpy.ndarray of float) – The steering vector for the beamforming, arranged in terms of x, y, and z coordinates

  • magnitude (numpy.ndarray of float) – The magnitude of the weights, default is 1.0 but can be set to any value to allow for both calibrated transmit power, and amplitude weighting.

  • maximum_delay (float) – The maximum delay to be applied to the weights, in nanoseconds. This is used to ensure that no delay is less than 0ns.

Returns:

weights – The time delay weights for the specified steering vector, arranged as a 1D array of complex numbers. For these weights for convineince the magnitude is the real part, while the time delay is the imaginary part.

Return type:

numpy.ndarray of complex

lyceanem.electromagnetics.beamforming.WavefrontWeights(source_coords, steering_vector, wavelength)[source]

calculate the weights for a given set of element coordinates, wavelength, and steering vector (cartesian)

Parameters:

  • source_coords (numpy.ndarray of float) – The coordinates of the elements, arranged in terms of x, y, and z coordinates

  • steering_vector (numpy.ndarray of float) – The steering vector for the beamforming, arranged in terms of x, y, and z coordinates

  • wavelength (float) – The wavelength of interest, used to calculate the phase delays

Returns:

weights – The wavefront weights for the specified steering vector, arranged as a 1D array of complex numbers

Return type:

numpy.ndarray of complex

lyceanem.electromagnetics.beamforming.create_display_mesh(field_data, field_radius=1.0, label='Poynting_Vector_(Magnitude_(W/m2))', log_type='power', plot_max=None, dynamic_range=40)[source]

Create a display mesh for the field data, with normals and scaled points based on the field radius.

Parameters:

  • field_data (meshio.Mesh) – The field data to create the display mesh

  • field_radius (float) – The radius of the field, used to scale the normals and points in the mesh, the maximum of the selected data will be scaled to this value.

  • label (str) – The label for the data to be plotted, this should be a key in the point_data of the field_data mesh.

  • log_type (str) – The type of logarithm to use for the data, either “amplitude” or “power”. Defaults to “power”.

  • plot_max (float, optional) – The maximum value for the plot, if None, it will be calculated as the maximum of the log data rounded up to the nearest 5. Defaults to None.

  • dynamic_range (float) – The desired maximum plot range in decibels. The default is 40dB.

Returns:

A PyVista PolyData object containing the display mesh with normals and scaled points.

Return type:

pyvista.PolyData

lyceanem.electromagnetics.beamforming.directivity_transform(Etheta, Ephi, az_range=None, elev_range=None, total_solid_angle=12.566370614359172)[source]

Transform the Etheta and Ephi field vectors into antenna directivity. The directivity is defined in terms of the power radiated in a specific direction, over the average radiated power

Parameters:

  • Etheta (numpy.ndarray of complex) – The E\theta polarisation farfield patterns, arranged in terms of the number of elements, azimuth resolution, and elevation resolution

  • Ephi (numpy.ndarray of complex) – The E\phi polarisation farfield patterns, arranged in terms of the number of elements, azimuth resolution, and elevation resolution

  • az_range (numpy.ndarray of float) – The azimuth values for the farfield mesh, arranged from smallest to largest

  • elev_range (numpy.ndarray of float) – The elevation values for the farfield mesh, arranged from smallest to largest

  • total_solid_angle (float) – the total solid angle covered by the farfield patterns, this defaults to $4pi$ for a full spherical pattern

Returns:

  • Dtheta (numpy.ndarray of float) – Directivity for the E\theta polarisation.

  • Dphi (numpy.ndarray of float) – Directivity for the E\phi polarisation.

  • Dtot (numpy.ndarray of float) – The achieved directivity map for the total polarisation.

  • Dmax (numpy.ndarray of float) – The maximum directivity for each polarisation.