Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English version of the page.

To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

# directivity

System object: phased.ShortDipoleAntennaElement
Package: phased

Directivity of short-dipole antenna element

## Syntax

```D = directivity(H,FREQ,ANGLE) ```

## Description

`D = directivity(H,FREQ,ANGLE)` returns the Directivity (dBi) of a short-dipole antenna element, `H`, at frequencies specified by `FREQ` and in direction angles specified by `ANGLE`.

## Input Arguments

expand all

Short-dipole antenna element specified as a `phased.ShortDipoleAntennaElement` System object.

Example: `H = phased.ShortDipoleAntennaElement;`

Frequencies for computing directivity and patterns, specified as a positive scalar or 1-by-L real-valued row vector. Frequency units are in hertz.

• For an antenna, microphone, or sonar hydrophone or projector element, `FREQ` must lie within the range of values specified by the `FrequencyRange` or `FrequencyVector` property of the element. Otherwise, the element produces no response and the directivity is returned as `–Inf`. Most elements use the `FrequencyRange` property except for `phased.CustomAntennaElement` and `phased.CustomMicrophoneElement`, which use the `FrequencyVector` property.

• For an array of elements, `FREQ` must lie within the frequency range of the elements that make up the array. Otherwise, the array produces no response and the directivity is returned as `–Inf`.

Example: `[1e8 2e6]`

Data Types: `double`

Angles for computing directivity, specified as a 1-by-M real-valued row vector or a 2-by-M real-valued matrix, where M is the number of angular directions. Angle units are in degrees. If `ANGLE` is a 2-by-M matrix, then each column specifies a direction in azimuth and elevation, `[az;el]`. The azimuth angle must lie between –180° and 180°. The elevation angle must lie between –90° and 90°.

If `ANGLE` is a 1-by-M vector, then each entry represents an azimuth angle, with the elevation angle assumed to be zero.

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 toward the y-axis. The elevation angle is the angle between the direction vector and xy plane. This angle is positive when measured towards the z-axis. See Azimuth and Elevation Angles.

Example: `[45 60; 0 10]`

Data Types: `double`

## Output Arguments

expand all

Directivity, returned as an M-by-L matrix. Each row corresponds to one of the M angles specified by `ANGLE`. Each column corresponds to one of the L frequency values specified in `FREQ`. Directivity units are in dBi where dBi is defined as the gain of an element relative to an isotropic radiator.

## Examples

expand all

Compute the directivity of a z-directed short-dipole antenna element as a function of elevation.

Create the crossed-dipole antenna element system object.

```myAnt = phased.ShortDipoleAntennaElement; myAnt.AxisDirection = 'Z'; myAnt.FrequencyRange = [0,10e9];```

Select the desired angles of interest to be at constant azimuth angle at zero degrees. Set the elevation angles to center around boresight (zero degrees azimuth and zero degrees elevation). Set the frequency to 1 GHz.

```elev = [-30:30]; azm = zeros(size(elev)); ang = [azm;elev]; freq = 1e9;```

Plot the directivity along the constant azimuth cut.

```d = directivity(myAnt,freq,ang); plot(elev,d) xlabel('Elevation (deg)'); ylabel('Directivity (dBi)');```