# perturbations

Perturbations defined on array

Since R2022a

## Syntax

``perts = perturbations(array)``
``perts = perturbations(array,prop)``
``perts = perturbations(array,prop,'None')``
``perts = perturbations(array,prop,'Normal',mean,sigma)``
``perts = perturbations(array,prop,'Uniform',minval,maxval)``
``perts = perturbations(array,prop,'RandomFail',failprob)``

## Description

````perts = perturbations(array)` returns a table of all allowed perturbations `perts` defined for the `array`. This table contains a list of all properties that can be perturbed, the probability type of applied perturbation, and the parameters of the probability type.```
````perts = perturbations(array,prop)` lets you view the current perturbation defined for the array property `prop`.```

example

````perts = perturbations(array,prop,'None')` specifies that the property `prop` is not perturbed.```
````perts = perturbations(array,prop,'Normal',mean,sigma)` specifies that the perturbation is drawn from a normal probability distribution defined by its `mean` and standard deviation `sigma`. To use this syntax, set `prop` to `'ElementPositions'`, `'TaperMagnitude'`, or `'TaperPhase'`. ```

example

````perts = perturbations(array,prop,'Uniform',minval,maxval)` specifies that the perturbation is drawn from a uniform probability distribution with a range defined by the interval [`minval`,`maxval`]. To use this syntax, set `prop` to `'ElementPositions'`, `'TaperMagnitude'`, or `'TaperPhase'`.```
````perts = perturbations(array,prop,'RandomFail',failprob)` specifies that the perturbation is a mask indicating whether an element is functioning based on the element fail property `failprob`. To use this syntax, set prop to `'ElementFailure'`.```

## Examples

collapse all

Create an 8-by-3 uniform rectangular array (URA). The array operates at 300 MHz and its elements are spaced one-half wavelength apart.

```freq = 300.0e6; lambda = physconst('Lightspeed')/freq; d = lambda/2; array = phased.URA(8,3,ElementSpacing=[d,d]);```

Initially, there are no perturbations to the array.

`perts = perturbations(array)`
```perts=4×3 table Property Type Value ___________________ ________ __________________ {'ElementPosition'} {'None'} {[NaN]} {[NaN]} {'TaperMagnitude' } {'None'} {[NaN]} {[NaN]} {'TaperPhase' } {'None'} {[NaN]} {[NaN]} {'ElementFailure' } {'None'} {[NaN]} {[NaN]} ```

Randomly perturb the element positions according to a normal distribution. Use a position variance of 16th of a wavelength.

`perts = perturbations(array,'ElementPosition','Normal',0,lambda/16)`
```perts=4×3 table Property Type Value ___________________ __________ _____________________ {'ElementPosition'} {'Normal'} {[ 0]} {[0.0625]} {'TaperMagnitude' } {'None' } {[NaN]} {[ NaN]} {'TaperPhase' } {'None' } {[NaN]} {[ NaN]} {'ElementFailure' } {'None' } {[NaN]} {[ NaN]} ```

Then perturb the magnitude of the element weights according to a normal distribution with a mean value of 0.1 and a variance of 0.02.

`perts = perturbations(array,'TaperMagnitude','Normal',0.1,0.02)`
```perts=4×3 table Property Type Value ___________________ __________ ________________________ {'ElementPosition'} {'Normal'} {[ 0]} {[0.0625]} {'TaperMagnitude' } {'Normal'} {[0.1000]} {[0.0200]} {'TaperPhase' } {'None' } {[ NaN]} {[ NaN]} {'ElementFailure' } {'None' } {[ NaN]} {[ NaN]} ```

Perturb the phase of the element weights according to a uniform distribution between $-\frac{\pi }{3}$ and $\frac{\pi }{3}$ degrees.

`perts = perturbations(array,'TaperPhase','Uniform',-pi/3,pi/3)`
```perts=4×3 table Property Type Value ___________________ ___________ _________________________ {'ElementPosition'} {'Normal' } {[ 0]} {[0.0625]} {'TaperMagnitude' } {'Normal' } {[ 0.1000]} {[0.0200]} {'TaperPhase' } {'Uniform'} {[-1.0472]} {[1.0472]} {'ElementFailure' } {'None' } {[ NaN]} {[ NaN]} ```

Set a 20$%$ percent failure rate for the elements.

`perts = perturbations(array,'ElementFailure','RandomFail',0.2)`
```perts=4×3 table Property Type Value ___________________ ______________ _________________________ {'ElementPosition'} {'Normal' } {[ 0]} {[0.0625]} {'TaperMagnitude' } {'Normal' } {[ 0.1000]} {[0.0200]} {'TaperPhase' } {'Uniform' } {[-1.0472]} {[1.0472]} {'ElementFailure' } {'RandomFail'} {[ 0.2000]} {[ NaN]} ```

## Input Arguments

collapse all

Phased array, specified as a Phased Array System Toolbox System object.

Perturbed property of array, specified as `'ElementPosition'`, `'TaperMagnitude'`, `'TaperPhase'`, or `'ElementFailure'`.

Example: `'TaperPhase'`

Data Types: `string`

Mean value of normal distribution, specified as a scalar. Units depend on the property `prop`.

 `'ElementPosition'` meters `'TaperMagnitude'` dimensionless `'TaperPhase'` radians

Example: `12`

#### Dependencies

To enable this argument, set the perturbed array property `prop` to `'ElementPosition'`, `'TaperMagnitude'`, or `'TaperPhase'` and the perturbation `type` to `'Normal'`.

Data Types: `double`

Standard deviation of normal distribution, specified as a positive scalar. Units depend on the property `prop`.

 `'ElementPosition'` meters `'TaperMagnitude'` dimensionless `'TaperPhase'` radians

Example: 1.0

#### Dependencies

To enable this argument, set the perturbed array property `prop` to `'ElementPosition'`, `'TaperMagnitude'`, `or 'TaperPhase'` and the perturbation `type` to `'Normal'`.

Data Types: `double`

Minimum value of range of uniform probability distribution, specified as a scalar. When applied to the `'TaperPhase'` property. the difference between `minval` and `maxval` should be less than or equal to 2π. Units depend on the property `prop`.

 `'ElementPosition'` meters `'TaperMagnitude'` dimensionless `'TaperPhase'` radians

Example: `0`

#### Dependencies

To enable this argument, set the perturbed array property `prop` to `'ElementPosition'`, `'TaperMagnitude'`, `or 'TaperPhase'` and the perturbation `type` to `'Uniform'`.

Data Types: `double`

Maximum value of range of uniform probability distribution

Example: `1`

#### Dependencies

Maximum value of range of uniform probability distribution, specified as a scalar. When applied to the `'TaperPhase'` property. the difference between `minval` and `maxval` should be less than or equal to 2π. Units depend on the property `prop`.

 `'ElementPosition'` meters `'TaperMagnitude'` dimensionless `'TaperPhase'` radians

Data Types: `double`

Probability of failure, specified as a non-negative scalar greater than or equal to zero and less than one. Zero means that the elements will never fail. Otherwise, there is a some probability of failure.

Example: `0.01`

#### Dependencies

To enable this argument, set the array property `prop` to `'ElementFailure'` and the perturbation type to `'RandomFail'`.

Data Types: `double`

## Output Arguments

collapse all

List of possible perturbations, returned as a MATLAB `table`. See Perturbed properties and perturbation types for a list of perturbations properties and types.

Data Types: `table`

collapse all

### Perturbed properties and perturbation types

You can perturb the array by selecting one of the properties to be perturbed and then applying the type of perturbation. Each type of perturbation has specific arguments.

PropertyPerturbation TypeArguments
`'ElementPosition'`
 `'None'` `'Normal'` `'Uniform'`
 - `mean`, `sigma` `minval`, `maxval`
`'TaperMagnitude'`
 `'None'` `'Normal'` `'Uniform'`
 - `mean`, `sigma` `minval`, `maxval`
`'TaperPhase'`
 `'None'` `'Normal'` `'Uniform'`
 - `mean`, `sigma` `minval`, `maxval`
`'ElementFailure'`
 `'None'` `'RandomFail'`
 - `probfail`

## Version History

Introduced in R2022a