EngeePhased.CustomAntennaElement

Custom antenna element.

Library

EngeePhased

Description

The EngeePhased.CustomAntennaElement system object models an antenna element with a custom spatial pattern. The pattern can be defined for polarised or unpolarised fields.

To create a custom antenna element, follow the steps below:

Create an EngeePhased.CustomAntennaElement object and set its properties.
Call the object with arguments as if it were a function.

Syntax

Creation

object = EngeePhased.CustomAntennaElement creates an antenna element with by default property values. By default, the response model is spatially isotropic. Example:
```
antenna = EngeePhased.CustomAntennaElement
```
object = EngeePhased.CustomAntennaElement(Name=Value) creates a custom antenna element with each specified Name (name) property set to the specified Value (value). You can specify additional arguments as a name-value pair in any order (Name1=Value1,…,NameN=ValueN). For example, the output response of an antenna depends on whether polarisation is set or not.
- To create an unpolarised pattern, set the SpecifyPolarizationPattern property to false (by default. Then use the MagnitudePattern and PhasePattern properties to define the response pattern.
- To create a polarised pattern, set the SpecifyPolarizationPattern property to true. Then use any or all of the HorizontalMagnitudePattern, HorizontalPhasePattern, VerticalMagnitudePattern and VerticalPhasePattern properties to define the directional pattern. Example:
  antenna = EngeePhased.CustomAntennaElement ()

Usage

RESP = object(FREQ,ANG) returns the antenna voltage characteristic to the RESP argument at the operating frequencies specified in the FREQ argument and the directions specified in the ANG argument. The shape of the RESP value depends on whether the antenna element supports polarisation as defined in the SpecifyPolarizationPattern property.
- If the Specify Polarisation Pattern property is set to false, it is accordingly an M by L matrix containing the antenna response at the angles specified in the ANG argument and at the L frequencies specified in the FREQ argument.
- If the Specify Polarisation Pattern property is set to true, this is a structure containing two fields, RESP.H and RESP.V, representing the antenna response in horizontal and vertical polarisation respectively. Each field is an M by L matrix containing the antenna response at the angles specified in the ANG argument and at the L frequencies specified in the FREQ argument.

When the RESP object is first called, it is initialised. This initialisation fixes the non-configurable properties and input characteristics such as size, complexity and input data type. If you change an unconfigurable property or input specification, the system object generates an error. To change an unconfigurable property or input specification, you must first call the release method to unlock the object.

Properties

FrequencyVector - operating frequency range vector
[0 1e20] (by default) | ` row vector 1 to L`

Details

The frequencies at which the frequency response and antenna patterns are to be obtained, given as a vector of strings 1 by L. The elements of the vector shall be in ascending order. The antenna element has no response outside the frequency range given by the minimum and maximum elements of the frequency vector.

The units of measurement are Hz.

Example: [200:50:300]*1e6.

Data types: Float64

FrequencyResponse — frequency characteristics of the antenna element
[0 0] (by default) | ` real vector 1 on L`

Details

Frequency characteristics at the frequencies defined by the FrequencyVector property, specified as a vector with strings of 1 on L. L is equal to the length of the vector specified by the FrequencyVector property.

The units of measurement are dB.

Example: [0 6 0].

Data types: Float64

PatternCoordinateSystem - coordinate system of the user antenna pattern
az-el (by default) | phi-theta

Details

The user antenna pattern coordinate system specified as az-el or phi-theta.

If you set the PatternCoordinateSystem property to az-el, use the AzimuthAngles and ElevationAngles properties to specify the pattern coordinate system.

If you set the PatternCoordinateSystem property to phi-theta, use the PhiAngles and ThetaAngles properties to specify the pattern coordinate system.

Data types: char

AzimuthAngles - azimuth angles
[-180:180] (by default) | ` real vector of length P`

Details

Specify the azimuthal angles as a vector of length P. These angles are the azimuth angles at which the custom radiation pattern is specified.

P must be greater than 2. The azimuth angles must lie in the range from -180° to 180° and be in strictly ascending order.

The units of measurement are degrees.

Example: [30 40 40 50].

Dependencies

To enable this property, set the PatternCoordinateSystem property to az-el.

Data types: Float64

ElevationAngles - elevation angles
[-90:90] (by default) | ` real vector of length Q`

Details

Specify the angles of elevation as a vector of length Q. These angles are the elevation angles at which the custom radiation pattern is specified. Q must be greater than 2. The elevation angles must lie in the range from -90° to 90° and be in strictly ascending order.

The units of measurement are degrees.

Example: [-30 0 +30].

Dependencies

To enable this property, set the PatternCoordinateSystem property to az-el.

Data types: Float64

PhiAngles - Phi angles in the phi-theta coordinate system
0:360+ (by default) | ` real vector of length P`

Details

The phi angles used to represent the response pattern of an element in the phi-theta coordinate system, given as a real vector of length P. The phi angles lie in the range 0° to 360°. P must be greater than 2.

Example: [90:180].

Dependencies

To enable this property, set the PatternCoordinateSystem property to phi-theta.

Data types: Float64

ThetaAngles theta angle in the phi-theta coordinate system
0:180 (by default) | real vector of length Q

Details

Theta angle used to represent the response pattern of an element in phi-theta coordinates, given as a real vector of length Q. Theta angle ranges from 0° to 180°. Q must be greater than 2.

Example: [40:80].

Dependencies

To enable this property, set the PatternCoordinateSystem property to phi-theta.

Data types: Float64

SpecifyPolarisationPattern — polarised array response
false (by default) | true

Details

Polarised array response specified as false or true.

If the SpecifyPolarisationPattern property is set to false, the antenna element transmits or receives unpolarised radiation. In this case, use the MagnitudePattern property to set the antenna pattern.
If the SpecifyPolarisationPattern property is set to true, the antenna element transmits or receives polarised radiation. In this case, use the HorizontalMagnitudePattern and HorizontalPhasePattern properties to set the horizontal polarisation pattern and the VerticalMagnitudePattern and VerticalPhasePattern properties to set the vertical polarisation pattern.

Data types: logical

MagnitudePattern - magnitude of the radiation pattern of the combined antenna
zeros(181,361) (by default) | real matrix Q on P | real array Q on P on L

Details

The magnitude of the radiation pattern of a compound polarisation antenna specified as a matrix Q on P or an array of Q on P on L. This property is only used if the SpecifyPolarisationPattern property is set to false.

The unit of measurement of the value is dB.

If the value of the MagnitudePattern property is a Q by P matrix, the same value is applied to all frequencies specified in the FrequencyVector property.
If the value of the MagnitudePattern property is a Q by P by L array, each Q by P array structure defines a pattern for the appropriate frequency specified in the FrequencyVector property.

If the pattern contains a NaN value in any azimuth and elevation direction, it is converted to Inf, indicating a null response in that direction.

The EngeePhased.CustomAntennaElement system object uses interpolation to estimate the antenna response in a given direction. To avoid interpolation errors, the custom response pattern must contain azimuth angles in the range [-180,180] degrees. Set the elevation angle range to [-90,90] degrees.

Data types: Float64

PhasePattern - phase pattern of the combined antenna radiation pattern
zeros(181,361) (by default) | real matrix Q on P | real array Q on P on L

Details

The phase radiation pattern of a combined polarisation antenna, given as a matrix Q on P or an array of Q on P on L. This property is only used if the SpecifyPolarisationPattern property is set to false.

The units of measurement are degrees.

If the value of the PhasePattern property is a matrix of Q on P, the same pattern is applied to all frequencies specified in the FrequencyVector property.
If the value of the PhasePattern property is a Q by P by L array, each Q by P array structure defines a pattern for the appropriate frequency specified in the FrequencyVector property.

The EngeePhased.CustomAntennaElement system object uses interpolation to estimate the antenna response in a given direction. To avoid interpolation errors, the custom response pattern must contain azimuth angles in the range [-180,180]. Specify an elevation angle range of [-90°,90°] degrees.

Data types: Float64

HorizontalMagnitudePattern - value of the horizontal polarisation component of the antenna radiation pattern
zeros(181,361) (by default) | real matrix Q on P | real array Q on P on L

Details

The magnitude of the horizontal polarisation component of the antenna radiation pattern, given as a matrix Q on P or an array Q on P on L.

The unit of measurement is dB.

If the value of the HorizontalMagnitudePattern property is a Q by P matrix, the same pattern is applied to all_ frequencies specified in the FrequencyVector property.
If the value of the HorizontalMagnitudePattern property is a Q by P by L array, each Q by P array structure defines a pattern for the corresponding frequency specified in the FrequencyVector property.

If the pattern contains NaN in any azimuth and elevation direction, it is converted to Inf, indicating a null response in that direction.

The EngeePhased.CustomAntennaElement system object uses interpolation to estimate the antenna response in a given direction. To avoid interpolation errors, the custom pattern must contain azimuth angles in the range [-180,180] and elevation angles in the range [-90,90] degrees.

Dependencies

To enable this property, set the SpecifyPolarisationPattern property to true.

Data types: Float64

HorizontalPhasePattern -. phase pattern of the horizontal polarisation component of the antenna radiation pattern

+ zeros(181,361) (by default) | real matrix Q on P | real array Q on P on L

Details

The phase of the horizontal polarisation component of the antenna radiation pattern, given as a matrix Q on P or an array Q on P on L. This property is only used if the SpecifyPolarisationPattern property is set to true.

The units of measurement are degrees.

If the value of the HorizontalPhasePattern property is a Q by P matrix, the same pattern is applied to all frequencies specified in the FrequencyVector property.
If the value of the HorizontalPhasePattern property is a Q by P by L array, each Q by P array structure defines a pattern for the appropriate frequency specified in the FrequencyVector property.

The EngeePhased.CustomAntennaElement system object uses interpolation to estimate the antenna response in a given direction. To avoid interpolation errors, the custom response pattern must contain azimuth angles in the range [-180,180] and elevation angles in the range [-90,90] degrees.

Dependencies

To enable this property, set the SpecifyPolarisationPattern property to true.

Data types: Float64

VerticalMagnitudePattern - value of the vertical polarisation component of the antenna radiation pattern
zeros(181,361) (by default) | real matrix Q on P | real array Q on P on L

Details

The magnitude of the vertical polarisation component of the antenna radiation pattern, given as a matrix Q on P or an array Q on P on L. This property is only used if the SpecifyPolarisationPattern property is set to true.

The units of measurement are dB.

If the value of the VerticalMagnitudePattern property is a Q by P matrix, the same pattern is applied to all frequencies specified in the FrequencyVector property.
If the value of the VerticalMagnitudePattern property is a Q by P by L array, each Q by P array structure defines a pattern for the appropriate frequency specified in the FrequencyVector property.

If the pattern contains a NaN value in any azimuth and elevation direction, it is converted to Inf, indicating a null response in that direction.

The EngeePhased.CustomAntennaElement system object uses interpolation to estimate the antenna response in a given direction. To avoid interpolation errors, the custom response pattern must contain azimuth angles in the range [-180,180] and elevation angles in the range [-90,90] degrees.

Dependencies

To enable this property, set the SpecifyPolarisationPattern property to true.

Data types: Float64

VerticalPhasePattern -. phase pattern of the vertical polarisation component of the antenna radiation pattern
zeros(181,361) (by default) | real matrix Q on P | real array Q on P on L

Details

The phase of the vertical polarisation component of the antenna radiation pattern, given as a matrix Q on P or an array Q on P on L. This property is only used if the SpecifyPolarisationPattern property is set to true.

The units of measurement are degrees.

If the value of the VerticalPhasePattern property is a matrix of Q on P, the same pattern is applied to all frequencies specified in the FrequencyVector property.
If the value of the VerticalPhasePattern property is a Q by P by L array, each Q by P array structure defines a pattern for the appropriate frequency specified in the FrequencyVector property.

The EngeePhased.CustomAntennaElement system object uses interpolation to estimate the antenna response in a given direction. To avoid interpolation errors, the custom response pattern must contain azimuth angles in the range [-180,180] and elevation angles in the range [-90,90] degrees.

Dependencies

To enable this property, set the SpecifyPolarisationPattern property to true.

Data types: Float64

MatchArrayNormal - match element normal to array normal
true (by default) | false

Details

Set the MatchArrayNormal property to true to align the antenna element to the array normal. The antenna pattern is rotated so that the axis of the element’s coordinate system points along the array normal. This property is only used if the antenna element belongs to the array.

Set the MatchArrayNormal property to false to use the element template without rotation.

Data types: logical

Arguments

Input

FREQ -. operating frequency of the antenna element
non-negative scalar | non-negative real vector 1 on L lines

Details

The operating frequency of the antenna element given as a non-negative scalar or a non-negative real vector 1 on L lines.

The units of measurement are Hz.

FREQ must lie within the range of values specified by the FrequencyRange property of the element. Otherwise, the element fails to respond and the response is returned as -Inf. Element objects use the FrequencyRange property, except for phased.CustomAntennaElement, which uses the FrequencyVector property.

*Example: [1e8 2e6].

Data types: Float64

ANG - azimuth and altitude angles of response directions
` real vector of rows 1 on M` | ` real matrix 2 on M`

Details

Azimuthal and altitude angles of the answer directions given as a real vector of strings 1 by M or a real matrix 2 by M, where M is the number of angular directions.

The units of measurement are degrees.

The azimuth angle must lie in the range from -180° to 180° inclusive. Elevation angle shall lie in the range from -90° to 90° inclusive.

If ANG is a vector 1 on M, each element specifies an azimuthal angle of direction. In this case, the corresponding elevation angle is assumed to be zero.

If ANG is a matrix 2 on M, each column of the matrix specifies a direction in the form [azimuth;elevation].

The azimuth angle is the angle between the x-axis and the projection of the direction vector onto the xy plane. This angle is positive when measured from the x-axis towards the y-axis. Elevation angle is the angle between the direction vector and the xy plane. This angle is positive when measured in the z-axis direction.

*Example: [110 125; 15 10]

Data types: Float64

Output

RESP — antenna pattern
`complex matrix M on L

Details

The voltage response of the antenna element, returned as a complex matrix M on L. In this matrix, M is the number of angles specified in ANG and L is the number of frequencies specified in FREQ.

Data types: Float64

Methods

Common for all system objects

`step!`	Starts the system object’s operating algorithm
`release!`	Permission to change the value of a system object property
`reset!`	Reset the internal states of the system object

Optional

*Algorithms.

The overall response of a custom antenna element is a combination of its frequency and spatial characteristics.

The EngeePhased.CustomAntennaElement system object calculates both responses using nearest neighbour interpolation and then multiplies them to form the overall response.