# directivity

System object: phased.PartitionedArray
Package: phased

Directivity of partitioned array

## Syntax

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

## Description

`D = directivity(H,FREQ,ANGLE)` returns the Directivity of a partitioned array of antenna or microphone elements, `H`, at frequencies specified by `FREQ` and in angles of direction specified by `ANGLE`.

The integration used when computing array directivity has a minimum sampling grid of 0.1 degrees. If an array pattern has a beamwidth smaller than this, the directivity value will be inaccurate.

`D = directivity(H,FREQ,ANGLE,Name,Value)` returns the directivity with additional options specified by one or more `Name,Value` pair arguments.

## Input Arguments

expand all

Partitioned array, specified as a `phased.PartitionedArray` System object.

Example: `H = phased.PartitionedArray;`

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`

### Name-Value Arguments

Specify optional pairs of arguments as `Name1=Value1,...,NameN=ValueN`, where `Name` is the argument name and `Value` is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose `Name` in quotes.

Signal propagation speed, specified as the comma-separated pair consisting of `'PropagationSpeed'` and a positive scalar in meters per second.

Example: `'PropagationSpeed',physconst('LightSpeed')`

Data Types: `double`

Subarray weights, specified as the comma-separated pair consisting of `'Weights`' and an N-by-1 complex-valued column vector or N-by-M complex-valued matrix. The dimension N is the number of subarrays in the array. The dimension L is the number of frequencies specified by the `FREQ` argument.

`Weights` dimension`FREQ` dimensionPurpose
N-by-1 complex-valued column vectorScalar or 1-by-L row vectorApplies a set of weights for the single frequency or for all L frequencies.
N-by-L complex-valued matrix1-by-L row vectorApplies each of the L columns of `‘Weights’` for the corresponding frequency in the `FREQ` argument.

Example: `'Weights',ones(N,M)`

Data Types: `double`

Subarray steering angle, specified as the comma-separated pair consisting of `'SteerAngle'` and a scalar or a 2-by-1 column vector.

If `'SteerAngle'` is a 2-by-1 column vector, it has the form `[azimuth; elevation]`. The azimuth angle must be between –180° and 180°, inclusive. The elevation angle must be between –90° and 90°, inclusive.

If `'SteerAngle'` is a scalar, it specifies the azimuth angle only. In this case, the elevation angle is assumed to be 0.

This option applies only when the `'SubarraySteering'` property of the System object is set to `'Phase'` or `'Time'`.

Example: `'SteerAngle',[20;30]`

Data Types: `double`

Subarray element weights, specified as complex-valued NSE-by-N matrix or 1-by-N cell array. Weights are applied to the individual elements within a subarray. Subarrays can have different dimensions and sizes.

If `ElementWeights` is a complex-valued NSE-by-N matrix, NSE is the number of elements in the largest subarray and N is the number of subarrays. Each column of the matrix specifies the weights for the corresponding subarray. Only the first K entries in each column are applied as weights where K is the number of elements in the corresponding subarray.

If `ElementWeights` is a 1-by-N cell array. Each cell contains a complex-valued column vector of weights for the corresponding subarray. The column vectors have lengths equal to the number of elements in the corresponding subarray.

#### Dependencies

To enable this name-value pair, set the `SubarraySteering` property of the array to `'Custom'`.

Data Types: `double`
Complex Number Support: Yes

## 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 partitioned array formed from a single 20-element ULA with elements spaced one-quarter wavelength apart. The subarrays are then phase-steered towards 30 degrees azimuth. The directivities are computed at azimuth angles from 0 to 60 degrees.

```c = physconst('LightSpeed'); fc = 3e8; lambda = c/fc; angsteer = [30;0]; ang = [0:10:60;0,0,0,0,0,0,0];```

Create a partitioned ULA array using the `SubarraySelection` property.

```myArray = phased.PartitionedArray('Array',... phased.ULA(20,lambda/4),'SubarraySelection',... [ones(1,10) zeros(1,10);zeros(1,10) ones(1,10)],... 'SubarraySteering','Phase','PhaseShifterFrequency',fc);```

Create the steering vector and compute the directivity.

```myStv = phased.SteeringVector('SensorArray',myArray,... 'PropagationSpeed',c); d = directivity(myArray,fc,ang,'PropagationSpeed',c,'Weights',... step(myStv,fc,angsteer),'SteerAngle',angsteer)```
```d = 7×1 -7.5778 -4.7676 -2.0211 10.0996 0.9714 -3.5575 -10.8439 ```