Documentation

# phased.CustomAntennaElement

Custom antenna element

## Description

The `phased.CustomAntennaElement` object models an antenna element with a custom response pattern. The response pattern can be defined for polarized or non-polarized fields.

To compute the response of the antenna element for specified directions:

1. Define and set up your custom antenna element. See Construction.

2. Call `step` to compute the antenna response according to the properties of `phased.CustomAntennaElement`. The behavior of `step` is specific to each object in the toolbox.

### Note

Starting in R2016b, instead of using the `step` method to perform the operation defined by the System object™, call the object with arguments, as if it were a function. For example, ```y = step(obj,x)``` and `y = obj(x)` perform equivalent operations.

## Construction

`H = phased.CustomAntennaElement` creates a system object, `H`, to model an antenna element with a custom response pattern. How the response pattern is specified depends upon whether polarization is desired or not. The default pattern has an isotropic spatial response.

• To create a nonpolarized response pattern, set the `SpecifyPolarizationPattern` property to `false` (default). Then, use the `MagnitudePattern` property to set the response pattern.

• To create a polarized response pattern, set the `SpecifyPolarizationPattern` property to `true`. Then, use any or all of the `HorizontalMagnitudePattern`, `HorizontalPhasePattern`, `VerticalMagnitudePattern`, and `VerticalPhasePattern` properties to set the response pattern.

The output response of the `step` method depends on whether polarization is set or not.

`H = phased.CustomAntennaElement(Name,Value)` creates a custom antenna object, `H`, with each specified property Name set to the specified Value. You can specify additional name-value pair arguments in any order as (`Name1`,`Value1`,...,`NameN`,`ValueN`).

## Properties

 `FrequencyVector` Response and pattern frequency vector Specify the frequencies (in Hz) at which the frequency response and antenna patterns are to be returned, as a 1-by-L row vector. The elements of the vector must be in increasing order. The antenna element has no response outside the frequency range specified by the minimum and maximum elements of the frequency vector. Default: `[0 1e20]` `AzimuthAngles` Azimuth angles Specify the azimuth angles (in degrees) as a length-P vector. These values are the azimuth angles where the custom radiation pattern is to be specified. P must be greater than 2. The azimuth angles must lie between –180° and 180° and be in strictly increasing order. Default: `[-180:180]` `ElevationAngles` Elevation angles Specify the elevation angles (in degrees) as a length-Q vector. These values are the elevation angles where the custom radiation pattern is to be specified. Q must be greater than 2. The elevation angles must lie between –90° and 90° and be in strictly increasing order. Default: `[-90:90]` `FrequencyResponse` Frequency responses of antenna element Specify the frequency responses in decibels measured at the frequencies defined in `FrequencyVector` property as a 1-by-L row vector. L equals the length of the vector specified in the `FrequencyVector` property. Default: `[0 0]` `SpecifyPolarizationPattern` Polarized array response When the `SpecifyPolarizationPattern` property is set to `false`, the antenna element transmits or receives non-polarized radiation. In this case, use the `MagnitudePattern` property to set the antenna response pattern.When the `SpecifyPolarizationPattern` property is set to `true`, the antenna element transmits or receives polarized radiation. In this case, use the `HorizontalMagnitudePattern` and `HorizontalPhasePattern` properties to set the horizontal polarization response pattern and the `VerticalMagnitudePattern` and `VerticalPhasePattern` properties to set the vertical polarization response pattern. Default: `false` `MagnitudePattern` Magnitude of combined antenna radiation pattern The magnitude of the combined polarization antenna radiation pattern specified as a Q-by-P matrix or a Q-by-P-by-L array. This property is used only when the `SpecifyPolarizationPattern` property is set to `false`. Magnitude units are in dB. If the value of this property is a Q-by-P matrix, the same pattern is applied to all frequencies specified in the `FrequencyVector` property.If the value is a Q-by-P-by-L array, each Q-by-P page of the array specifies a pattern for the corresponding frequency specified in the `FrequencyVector` property. If the pattern contains a `NaN` at any azimuth and elevation direction, it is converted to `-Inf`, indicating zero response in that direction. The custom antenna object uses interpolation to estimate the response of the antenna at a given direction. To avoid interpolation errors, the custom response pattern must contain azimuth angles in the range `[–180,180]` degrees. Set the range of elevation angles to `[–90,90]` degrees. Default: A 181-by-361 matrix with all elements equal to 0 dB `PhasePattern` Phase of combined antenna radiation pattern The phase of the combined polarization antenna radiation pattern specified as a Q-by-P matrix or a Q-by-P-by-L array. This property is used only when the `SpecifyPolarizationPattern` property is set to `false`. Phase units are in degrees. If the value of this property is a Q-by-P matrix, the same pattern is applied to all frequencies specified in the `FrequencyVector` property.If the value is a Q-by-P-by-L array, each Q-by-P page of the array specifies a pattern for the corresponding frequency specified in the `FrequencyVector` property. The custom antenna object uses interpolation to estimate the response of the antenna at a given direction. To avoid interpolation errors, the custom response pattern must contain azimuth angles in the range [–180°,180°]. Set the range of elevation angles to [–90°,90°]. Default: A 181-by-361 matrix with all elements equal to 0 `HorizontalMagnitudePattern` Magnitude of horizontal polarization component of antenna radiation pattern The magnitude of the horizontal polarization component of the antenna radiation pattern specified as a Q-by-P matrix or a Q-by-P-by-L array. This property is used only when the `SpecifyPolarizationPattern` property is set to `true`. Magnitude units are in dB. If the value of this property is a Q-by-P matrix, the same pattern is applied to all frequencies specified in the `FrequencyVector` property.If the value is a Q-by-P-by-L array, each Q-by-P page of the array specifies a pattern for the corresponding frequency specified in the `FrequencyVector` property. If the magnitude pattern contains a `NaN` at any azimuth and elevation direction, it is converted to `-Inf`, indicating zero response in that direction. The custom antenna object uses interpolation to estimate the response of the antenna at 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]°`. Default: A 181-by-361 matrix with all elements equal to 0 dB `HorizontalPhasePattern` Phase of horizontal polarization component of antenna radiation pattern The phase of the horizontal polarization component of the antenna radiation pattern specified as a Q-by-P matrix or a Q-by-P-by-L array. This property is used only when the `SpecifyPolarizationPattern` property is set to `true`. Phase units are in degrees. If the value of this property is a Q-by-P matrix, the same pattern is applied to all frequencies specified in the `FrequencyVector` property.If the value is a Q-by-P-by-L array, each Q-by-P page of the array specifies a pattern for the corresponding frequency specified in the `FrequencyVector` property. The custom antenna object uses interpolation to estimate the response of the antenna at 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]°`. Default: A 181-by-361 matrix with all elements equal to 0° `VerticalMagnitudePattern` Magnitude of vertical polarization component of antenna radiation pattern The magnitude of the vertical polarization component of the antenna radiation pattern specified as a Q-by-P matrix or a Q-by-P-by-L array. This property is used only when the `SpecifyPolarizationPattern` property is set to `true`. Magnitude units are in dB. If the value of this property is a Q-by-P matrix, the same pattern is applied to all frequencies specified in the `FrequencyVector` property.If the value is a Q-by-P-by-L array, each Q-by-P page of the array specifies a pattern for the corresponding frequency specified in the `FrequencyVector` property. If the pattern contains a `NaN` at any azimuth and elevation direction, it is converted to `-Inf`, indicating zero response in that direction. The custom antenna object uses interpolation to estimate the response of the antenna at 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]°`. Default: A 181-by-361 matrix with all elements equal to 0 dB `VerticalPhasePattern` Phase of vertical polarization component of antenna radiation pattern The phase of the vertical polarization component of the antenna radiation pattern specified as a Q-by-P matrix or a Q-by-P-by-L array. This property is used only when the `SpecifyPolarizationPattern` property is set to `true`. Phase units are in degrees. If the value of this property is a Q-by-P matrix, the same pattern is applied to all frequencies specified in the `FrequencyVector` property.If the value is a Q-by-P-by-L array, each Q-by-P page of the array specifies a pattern for the corresponding frequency specified in the `FrequencyVector` property. The custom antenna object uses interpolation to estimate the response of the antenna at 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]°`. Default: A 181-by-361 matrix with all elements equal to 0° `MatchArrayNormal` Match element normal to array normal Set this property to `true` to align the antenna element to an array normal. The antenna pattern is rotated so that the x-axis of the element coordinate system points along the array normal. This property is used only when the antenna element belongs to an array. Use the property in conjunction with the `ArrayNormal` property of the `phased.URA` and `phased.UCA` System objects. Set this property to `false` to use the element pattern without rotation. The default value is `true`.

## Methods

 directivity Directivity of custom antenna element isPolarizationCapable Polarization capability pattern Plot custom antenna element directivity and patterns patternAzimuth Plot custom antenna element directivity or pattern versus azimuth patternElevation Plot custom antenna element directivity or pattern versus elevation plotResponse Plot response pattern of antenna step Output response of antenna element
Common to All System Objects
`release`

Allow System object property value changes

## Examples

expand all

Create a user-defined antenna with a cosine pattern. Then, plot an elevation cut of the antenna's power response.

The user-defined pattern is omnidirectional in the azimuth direction and has a cosine pattern in the elevation direction. Assume the antenna operates at 1 GHz. Obtain the response at 20° azimuth and 30° elevation.

```fc = 1e9; azang = -180:180; elang = -90:90; magpattern = mag2db(repmat(cosd(elang)',1,numel(azang))); phasepattern = zeros(size(magpattern)); antenna = phased.CustomAntennaElement('AzimuthAngles',azang, ... 'ElevationAngles',elang,'MagnitudePattern',magpattern, ... 'PhasePattern',phasepattern); resp = antenna(fc,[20;30])```
```resp = 0.8660 ```

Plot an elevation cut of the power response.

`pattern(antenna,fc,20,-90:90,'CoordinateSystem','polar','Type','powerdb')`

Plot an elevation cut of the directivity.

`pattern(antenna,fc,20,-90:90,'CoordinateSystem','polar','Type','directivity')`

Define a custom antenna in u-v space. Then, calculate and plot the response.

Define the radiation pattern (in dB) of an antenna in terms of u and v coordinates within the unit circle.

```u = -1:0.01:1; v = -1:0.01:1; [u_grid,v_grid] = meshgrid(u,v); pat_uv = sqrt(1 - u_grid.^2 - v_grid.^2); pat_uv(hypot(u_grid,v_grid) >= 1) = 0;```

Create an antenna with this radiation pattern. Convert u-v coordinates to azimuth and elevation coordinates.

```[pat_azel,az,el] = uv2azelpat(pat_uv,u,v); array = phased.CustomAntennaElement('AzimuthAngles',az,'ElevationAngles',el, ... 'MagnitudePattern',mag2db(pat_azel),'PhasePattern',45*ones(size(pat_azel)));```

Calculate the response in the direction u = 0.5, v = 0. Assume the antenna operates at 1 GHz. The output of the step method is in linear units.

```dir_uv = [0.5;0]; dir_azel = uv2azel(dir_uv); fc = 1e9; resp = array(fc,dir_azel)```
```resp = 0.6124 + 0.6124i ```

Plot the 3D response in u-v coordinates.

`pattern(array,fc,[-1:.01:1],[-1:.01:1],'CoordinateSystem','uv','Type','powerdb')`

Display the antenna response as a line plot in u-v coordinates.

`pattern(array,fc,[-1:.01:1],0,'CoordinateSystem','uv','Type','powerdb')`

Model a short dipole antenna oriented along the $x$-axis of the local antenna coordinate system. For this type of antenna, the horizontal and vertical components of the electric field are given by ${E}_{H}=\frac{j\omega \mu IL}{4\pi r}\mathrm{sin}\left(az\right)$ and ${E}_{V}=-\frac{j\omega \mu IL}{4\pi r}\mathrm{sin}\left(el\right)\mathrm{cos}\left(az\right)$.

Specify a normalized radiation pattern of a short dipole antenna terms of azimuth, $az$, and elevation, $el$, coordinates. The vertical and horizontal radiation patterns are normalized to a maximum of unity.

```az = [-180:180]; el = [-90:90]; [az_grid,el_grid] = meshgrid(az,el); horz_pat_azel = ... mag2db(abs(sind(az_grid))); vert_pat_azel = ... mag2db(abs(sind(el_grid).*cosd(az_grid)));```

Set up the antenna. Specify the `SpecifyPolarizationPattern` property to produce polarized radiation. In addition, use the `HorizontalMagnitudePattern` and `VerticalMagnitudePattern` properties to specify the pattern magnitude values. The `HorizontalPhasePattern` and `VerticalPhasePattern` properties take default values of zero.

```sCust = phased.CustomAntennaElement(... 'AzimuthAngles',az,'ElevationAngles',el,... 'SpecifyPolarizationPattern',true,... 'HorizontalMagnitudePattern',horz_pat_azel,... 'VerticalMagnitudePattern',vert_pat_azel);```

Assume the antenna operates at 1 GHz.

`fc = 1e9;`

Display the vertical response pattern.

```pattern(sCust,fc,[-180:180],[-90:90],... 'CoordinateSystem','polar',... 'Type','powerdb',... 'Polarization','V')```

Display the horizontal response pattern.

```pattern(sCust,fc,[-180:180],[-90:90],... 'CoordinateSystem','polar',... 'Type','powerdb',... 'Polarization','H')```

The combined polarization response, shown below, illustrates the $x$-axis null of the dipole.

```pattern(sCust,fc,[-180:180],[-90:90],... 'CoordinateSystem','polar',... 'Type','powerdb',... 'Polarization','combined')```

Define a custom antenna in u-v space. Show how the array response pattern is affected by the choice of the `MatchArrayNormal` property of the `phased.CustomAntennaElement`.

Define the response pattern (in dB) of an antenna as a function of u and v coordinates within the unit circle. The antenna operates at 1 GHz.

```fc = 1e9; c = physconst('LightSpeed'); u = -1:0.01:1; v = -1:0.01:1; [u_grid,v_grid] = meshgrid(u,v); pat_uv = sqrt(1 - u_grid.^2 - v_grid.^2); pat_uv(hypot(u_grid,v_grid) >= 1) = 0;```

Create a custom antenna with this pattern. Convert u-v coordinates to azimuth and elevation coordinates. Set `MatchArrayNormal` to `false`.

```[pat_azel,az,el] = uv2azelpat(pat_uv,u,v); element = phased.CustomAntennaElement('AzimuthAngles',az,'ElevationAngles',el, ... 'MagnitudePattern',mag2db(pat_azel),'PhasePattern',45*ones(size(pat_azel)), ... "MatchArrayNormal",false);```

Construct a 3-by-3 URA with this element and display the antenna pattern in 3-D polar coordinates. The element spacing is one-half wavelength. The array normal points along the y-axis.

```lam = c/fc; array = phased.URA('Element',element,'Size',[3 3],'ElementSpacing', ... [lam/2 lam/2],'ArrayNormal','y'); pattern(array,fc,-180:180,-90:90,'PropagationSpeed',c, ... 'CoordinateSystem','polar','Type','powerdb','Normalize',true)```

The pattern shows the interplay between the element pattern pointing along the x-axis and the array pattern pointing along the y-axis.

Create another custom antenna with the same radiation pattern. Set `MatchArrayNormal` to true. Then create another array with this element.

```element2 = phased.CustomAntennaElement('AzimuthAngles',az,'ElevationAngles',el, ... 'MagnitudePattern',mag2db(pat_azel),'PhasePattern',45*ones(size(pat_azel)), ... "MatchArrayNormal",true); array2 = phased.URA('Element',element2,'Size',[3 3],'ElementSpacing', ... [lam/2 lam/2],'ArrayNormal','y'); pattern(array2,fc,-180:180,-90:90,'PropagationSpeed',c, ... 'CoordinateSystem','polar','Type','powerdb','Normalize',true)```

This pattern shows the aligned element and array patterns pointing along the y-axis.

## Algorithms

The total response of a custom antenna element is a combination of its frequency response and spatial response. `phased.CustomAntennaElement` calculates both responses using nearest neighbor interpolation, and then multiplies the responses to form the total response.