The array object is used to represent an antenna array. Currently, MFM only supports isotropic antenna elements.

An antenna array is largely characterized by the relative geometry of its elements. MFM’s array object is not restricted to creating uniform linear arrays or uniform planar arrays; the array’s elements can be placed arbitrarily, and MFM will automatically compute the array response based on their placement. This means users can easily experiment with abnormal/arbitrary array designs.

### Creating an Array

There are a few different ways to create an array object.

#### Empty Array

To create an empty array object, you can simply call

a = array.create()


#### Uniform Linear Array

To create an N-element, half-wavelength spaced uniform linear array, use

a = array.create(N,ax)


where ax is either 'x' (default), 'y', or 'z' specifying which axis to create the ULA along.

#### Uniform Planar Array

To create a half-wavelength spaced uniform planar array with N rows of M elements, use

a = array.create(N,M,plane)


where plane is either 'xz' (default), 'xy', or 'yz', defining which plane to create the array in.

By default, ULAs and UPAs are centered at the origin when created.

### Viewing the Array

To view the array elements in 2-D space (in the x-z plane by default), use

a.show_2d()


or

a.show_2d([],plane)


where plane is either 'xz' (default), 'xy', or 'yz' specifying which plane to plot the array in.

To view the array elements in 3-D space, use

a.show_3d()


### Adding and Removing Elements

To add elements to an array object a, use

a.add_element(x,y,z)


where x, y, and z are vectors of (x,y,z) coordinates of the elements (in wavelengths) to add to the array.

Since antenna arrays are characterized by the elements’ positions relative to the carrier frequency, all Cartesian coordinates associated with an array are in units of carrier wavelengths.

To remove an element from the array object a, use

a.remove_element(idx)


where idx is the index of the element to remove. If idx is not passed, the last element of the array will be removed.

### Modifying the Array

To shift all elements of an array object a, use

a.translate(x,y,z)


where x, y, and z are the amounts (in wavelengths) to move all the array elements in the x, y, and z directions.

If x, y, and z are not passed, then the following

a.translate()


centers the array at the origin.

To rotate the entire array object a about the three axes, use

a.rotate(rot_x,rot_y,rot_z)


where rot_x, rot_y, and rot_z are rotations to make along the x-, y-, and z-axes, respectively, in radians.

### Geting the Array Response

The relative phase shift experienced by the $i$-th array element located at some $(x_i,y_i,z_i)$ from the origin due to a plane wave in the direction $(\theta,\phi)$ is

where $\lambda$ is the carrier wavelength and

Instead of referencing the true origin to compute the array response, MFM refers the location of each antenna element to that of the first element in the antenna array. Thus, the array response vector is constructed by collecting the relative phase shift seen by each of the array’s $N$ elements as

To obtain the array response—the relative phase shift across elements—at a particular azimuth angle and elevation angle, use

v = a.get_array_response(az,el)


where az and el are azimuth and elevation angles in radians and v is the consequent array response (a column vector). MFM will compute the array response behind-the-scenes.

### Weighting the Array

To set the array weights, use

a.set_weights(w)


where w is a vector of complex weights where the i-th array element is weighted by the i-th weight in w.

### Array Gain

The array gain $g$ in a particular direction can be described mathematically by stating that the gain of an array with weights $\mathbf{w}$ in the direction $(\theta,\phi)$ is

where $(\cdot)^{\mathrm{T}}$ denotes the transpose operation (not conjugate transpose).

In MFM, to evaluate the gain of the array (with weights applied) in a particular azimuth and elevation, use

g = a.get_array_gain(az,el)


where az and el are azimuth and elevation angles in radians and g is the complex gain of the weighted array.

### Geting the Weighted Array Response

The array response vector with array weights applied is simply the array response vector multiplied element-wise by the array weights

To retrieve the weighted array response, simply use

v = a.get_weighted_array_response(az,el)


where az and el are azimuth and elevation angles in radians and v is the consequent weighted array response (a column vector).

By using this, the array weights can be used more broadly than for beamforming—e.g., for capturing phase or gain inconsistencies across array elements.

### Viewing the Array Pattern

The array object has several functions that can be used to view its array pattern—the array response (magnitude and phase) as a function of azimuth angle and elevation angle.

Note that these all plot the weighted array pattern, meaning they capture any weights set to the array.

#### Azimuth and Elevation Cuts

To view the magnitude and phase of the array response as a function of azimuth angle and elevation angle, use

a.show_array_pattern()


or

a.show_array_pattern(az,el)


where el is the elevation angle (in radians) to use when evaluating the azimuth pattern and az is the azimuth angle (in radians) to use when evaluating the elevation pattern.

#### Azimuth Cut

To view the magnitude of the array response as a function of azimuth angle alone, use

a.show_array_pattern_azimuth()


or

a.show_array_pattern_azimuth([],el)


where el is the elevation angle (in radians) to use when evaluating the azimuth pattern.

#### Elevation Cut

To view the magnitude of the array response as a function of elevation angle alone, use

a.show_array_pattern_elevation()


or

a.show_array_pattern_elevation([],az)


where az is the azimuth angle (in radians) to use when evaluating the elevation pattern.

#### Azimuth Cut and Elevation Cut in a Polar Plot

To view the array patterns in a polar plot, use

a.show_polar_array_pattern_azimuth()
a.show_polar_array_pattern_elevation()


or

a.show_polar_array_pattern_azimuth([],el)
a.show_polar_array_pattern_elevation([],az)


which shows the magnitude of the array response as a function of azimuth angle and of elevation angle.

### List of Properties

The array object contains the following properties:

• array.num_antennas
• array.x
• array.y
• array.z
• array.weights
• array.marker

### List of Methods

The array object contains the following methods:

### Methods Documentation

#### add_element(x,y,z)

Adds an element or group of elements to the array based on their (x,y,z)-coordinates (in wavelengths).

Usage:
add_element(x,y,z)
Input Arguments:
x — a scalar or vector of scalars of element x-coordinate(s)
y — a scalar or vector of scalars of element y-coordinate(s)
z — a scalar or vector of scalars of element z-coordinate(s)
Notes:
If x, y, and z are not of equal length, an error is thrown.

Back to methods

#### array(N,M,plane)

Creates an instance of an array object.

Usage:
obj = array()
obj = array(N)
obj = array(N,M)
obj = array(N,[])
obj = array(N,M,plane)
obj = array(N,[],plane)
Input Arguments:
N — (optional) number of elements in the array; or number of rows in a planar array if a second argument is passed
M — (optional) number of columns in a planar array
plane — (optional) a string specifying the plane to create the planar array in (either ‘xz’, ‘xy’, or ‘yz’); if not passed, ‘xz’ will be used
Return Values:
obj — an array object
Notes:
obj = ARRAY() Creates an empty array object.
obj = ARRAY(N) Creates an array object where N array elements are uniformly spaced one-half wavelength apart along the x-axis.
obj = ARRAY(N,M) Creates an array object representing a uniform planar array comprised of N rows of M elements, uniformly spaced one-half wavelength apart in the x-z plane.

Back to methods

#### create(N,M,plane)

Creates an antenna array object.

Usage:
obj = array.create()
obj = array.create(N)
obj = array.create(N,M)
obj = array.create(N,[])
obj = array.create(N,M,plane)
obj = array.create(N,[],plane)
Input Arguments:
N — (optional) number of elements in the array; or number of rows in a planar array if a second argument is passed
M — (optional) a string specifying which axis to create the linear array; or number of columns in a planar array
plane — (optional) a string specifying the plane to create the planar array in (either ‘xz’, ‘xy’, or ‘yz’); if not passed, ‘xz’ will be used
Return Values:
obj — an array object

Back to methods

#### get_array_gain(az,el)

Returns the array gain in a given direction (azimuth and elevation) with the current array weights applied.

Usage:
gain = get_array_gain()
gain = get_array_gain(az)
gain = get_array_gain([],el)
gain = get_array_gain(az,el)
Input Arguments:
az — (optional) azimuth angle of interest (radians); if not passed, 0 is used
el — (optional) elevation angle of interest (radians); if not passed, 0 is used
Return Values:
g — complex gain of the weighted array in the azimuth and elevation of interest

Back to methods

#### get_array_pattern_azimuth(el,N,full)

Returns the weighted array pattern as a function of azimuth angle for some fixed elevation angle.

Usage:
[x,az] = get_array_pattern_azimuth()
[x,az] = get_array_pattern_azimuth(el)
[x,az] = get_array_pattern_azimuth(el,N)
[x,az] = get_array_pattern_azimuth(el,N,full)
Input Arguments:
el — (optional) elevation angle to use when evaluating the azimuth array pattern (radians); if not passed, 0 is used
N — (optional) number of azimuth points used to evaluate array pattern; if not passed, 1024 is used
full — (optional) a boolean specifying if the full azimuth sweep should be executed (true) or half (false); default is false; a full azimuth sweep is from [-pi,+pi); a half azimuth sweep is from [-pi/2,+pi/2)
Return Values:
x — weighted array pattern as a function of azimuth angle
az — azimuth angles (radians) used to assess the array pattern

Back to methods

#### get_array_pattern_elevation(az,N,full)

Returns the weighted array pattern as a function of elevation angle for some fixed azimuth angle.

Usage:
[x,el] = get_array_pattern_elevation()
[x,el] = get_array_pattern_elevation(az)
[x,el] = get_array_pattern_elevation(az,N)
[x,el] = get_array_pattern_elevation(az,N,full)
Input Arguments:
az — (optional) azimuth angle to use when evaluating the elevation array pattern (radians); if not passed, 0 is used
N — (optional) number of elevation points used to evaluate array pattern; if not passed, 1024 is used
full — (optional) a boolean specifying if the full elevation sweep should be executed (true) or half (false); default is false; a full elevation sweep is from [-pi,+pi); a half elevation sweep is from [-pi/2,+pi/2)
Return Values:
x — weighted array pattern as a function of elevation angle
el — elevation angles (radians) used to assess the array pattern

Back to methods

#### get_array_response(az,el)

Returns the array response vector at a given azimuth and elevation. This response is simply the phase shifts experienced by the elements on an incoming plane wave at a given azimuth and elevation, normalized to the first element in the array.

Usage:
a = get_array_response()
a = get_array_response(az)
a = get_array_response([],el)
a = get_array_response(az,el)
Input Arguments:
az — (optional) azimuth angle of interest (radians); if not passed, 0 is used
el — (optional) elevation angle of interest (radians); if not passed, 0 is used
Return Values:
a — the array response vector at the azimuth and elevation of interest

Back to methods

#### get_conjugate_beamformer(az,el)

Returns the conjugate beamforming weights for steering in particular azimuth and elevation directions.

Usage:
w = get_conjugate_beamformer()
w = get_conjugate_beamformer(az)
w = get_conjugate_beamformer([],el)
w = get_conjugate_beamformer(az,el)
Input Arguments:
az — (optional) azimuth angle of interest (radians); if not passed, 0 is used
el — (optional) elevation angle of interest (radians); if not passed, 0 is used
Return Values:
w — array weights corresponding to the conjugate beamformer that steers toward the azimuth and elevation of interest

Back to methods

#### get_conjugate_beamformer_azimuth_matrix(N,el)

Returns a matrix whose columns are phased array beamformers in various directions of azimuth.

Usage:
[A,th] = GET_PHASED_ARRAY_BEAMFORMER_AZIMUTH_MATRIX()
[A,th] = GET_PHASED_ARRAY_BEAMFORMER_AZIMUTH_MATRIX(N)
[A,th] = GET_PHASED_ARRAY_BEAMFORMER_AZIMUTH_MATRIX(N,el)
Input Arguments:
N — number of beamformers to return in matrix (number of columns in A)
el — elevation angle used when giving the azimuth conjugate beamformer (optional, default of 0 radians)
Return Values:
A — matrix of size Na-by-N whose columns are the array response vectors for the azimuth angles of interest at the fixed elevation angle
th — correpsonding azimuth angles which A is used for estimation

Back to methods

#### get_element_pattern_azimuth()

Returns the element pattern as a function of azimuth.

Usage:
[xx,th] = get_element_pattern_azimuth()
Return Values:
xx — the element pattern as a function of azimuth angle
th — azimuth angles corresponding to the values in xx (radians)

Back to methods

#### get_element_pattern_elevation()

Returns the element pattern as a function of elevation.

Usage:
[xx,ph] = get_element_pattern_elevation()
Return Values:
xx — the element pattern as a function of elevation angle
ph — elevation angles corresponding to the values in xx (radians)

Back to methods

Back to methods

#### get_weighted_array_response(az,el)

Returns the weighted array response vector at a given azimuth and elevation.

Usage:
a = get_weighted_array_response()
a = get_weighted_array_response(az)
a = get_weighted_array_response([],el)
a = get_weighted_array_response(az,el)
Input Arguments:
az — (optional) azimuth angle of interest (radians); if not passed, 0 is used
el — (optional) elevation angle of interest (radians); if not passed, 0 is used
Return Values:
a — the array response vector at the azimuth and elevation of interest, incorporating array weights

Back to methods

#### get_zero_forcing_beamformer(az_des,el_des,az_int,el_int)

Returns the zero-forcing beamformer that accepts energy in one or more desired directions and rejects energy in one or more interfering directions.

Usage:
w = get_zero_forcing_beamformer(az_des,el_des,az_int,el_int)
Input Arguments:
az_des — desired azimuth angle(s) in radians
el_des — desired elevation angles(s) in radians
az_int — interfering azimuth angle(s) in radians
el_int — interfering elevation angle(s) in radians
Return Values:
w — a beamformer that attempts to accept energy in the desired directions while rejecting energy in the interfering directions

Back to methods

#### initialize_ula(N,ax)

Resets the array and creates a half-wavelength spaced, uniform linear array along a desired axis.

Usage:
initialize_ula(N)
initialize_ula(N,ax)
Input Arguments:
N — the number of array elements in the array
ax — (optional) a string specifying which axis to create the ULA along (either ‘x’, ‘y’, or ‘z’); if not passed, ‘x’ will be used

Back to methods

#### initialize_upa(nrows,ncols,plane)

Resets the array and creates a half-wavelength spaced, uniform planar array in a desired plane.

Usage:
initialize_upa(nrows)
initialize_upa(nrows,ncols)
initialize_upa(nrows,[],plane)
initialize_upa(nrows,ncols,plane)
Input Arguments:
nrows — number of rows (second axis) in the planar array
ncols — (optional) number of columns (first axis) in the planar array; if not passed, the number of rows (nrows) will be used
plane — (optional) a string specifying which plane to create the UPA in (either ‘xy’, ‘xz’, or ‘yz’); if not passed, ‘xz’ will be used

Back to methods

#### remove_element(idx)

Removes an element from the array.

Usage:
remove_element()
remove_element(idx)
Input Arguments:
idx — (optional) index of the element to remove from the array; if not passed, the last element will be removed

Back to methods

#### reset()

Removes all array elements from the array.

Usage:
reset()

Back to methods

#### rotate(rot_x,rot_y,rot_z,inplace)

Rotates the array in 3-D space along the x-, y-, and z-axes by some specified rotations (in radians).

Usage:
rotate(rot_x)
rotate(rot_x,rot_y)
rotate(rot_x,rot_y,rot_z)
rotate(rot_x,rot_y,rot_z,inplace)
Input Arguments:
rot_x — rotation around x-axis (radians)
rot_y — (optional) rotation around y-axis (radians); if not passed, 0 is used
rot_z — (optional) rotation around z-axis (radians); if not passed, 0 is used
inplace — (optional) a boolean indicating if the rotation should made about the true origin (0,0,0) (false) or the array’s center (true); if not passed, false is used

Back to methods

#### set_element_gain(power_gain_dB)

Sets the gain of each element in the array. Does not account for element’s radiation pattern; merely scales the isotropic pattern. Can be used when considering uniform gain over a range of directions (e.g., 3 dB gain from -60 degrees to +60 degrees).

Usage:
set_element_gain(power_gain_dB)
Input Arguments:
power_gain_dB — the element’s power gain in dB

Back to methods

#### set_marker(marker)

Sets the marker used when plotting the array elements.

Usage:
set_marker()
set_marker(marker)
Input Arguments:
marker — (optional) a string specifying the plot marker to use; in addition to MATLAB’s plot markers (e.g., ‘kx’), ‘transmit’ or ‘receive’ are also valid; if not passed, ‘kx’ is used

Back to methods

#### set_weights(w)

Applies complex weights to each array element. Note that these weights are applied directly and not conjugated beforehand.

Usage:
set_weights()
set_weights(w)
Input Arguments:
w — (optional) a weight vector where the i-th array element is weighted by the i-th element in w; if not passed, a vector of ones is used

Back to methods

#### show_2d(ax,plane)

Plots the array elements in 2-D space.

Usage:
[fig,ax] = SHOW2D()
[fig,ax] = SHOW2D(ax)
[fig,ax] = SHOW2D(ax,plane)
[fig,ax] = SHOW2D([],plane)
Input Arguments:
ax — (optional) an axes handle to plot on
plane — (optional) a string specifying which plane to show (either ‘xy’, ‘xz’, or ‘yz’); if not passed, ‘xz’ is used.
Return Values:
fig — a figure handle
ax — an axes handle

Back to methods

#### show_3d(ax)

Plots the array elements in 3-D space.

Usage:
[fig,ax] = SHOW3D()
[fig,ax] = SHOW3D(ax)
Input Arguments:
ax — (optional) existing axes to plot on
Return Values:
fig — a figure handle
ax — an axes handle

Back to methods

#### show_array_pattern(az,el,N,full)

Plots the array pattern as a function of azimuth for a fixed elevation and as a function of elevation for a fixed azimuth.

Usage:
show_array_pattern()
show_array_pattern(az)
show_array_pattern(az,el)
show_array_pattern(az,el,N)
show_array_pattern(az,el,N,full)
Input Arguments:
az — (optional) the azimuth angle (in radians) to use when evaluating the array elevation pattern; if not passed, the default is used
el — (optional) the elevation angle (in radians) to use when evaluating the array azimuth pattern; if not passed, the default is used
N — (optional) number of points to take when evaluating the array pattern; if not passed, the default is used
full — (optional) a boolean specifying if the full sweep should be executed (true) or half (false); default is false; a full sweep is from [-pi,+pi); a half sweep is from [-pi/2,+pi/2)

Back to methods

#### show_array_pattern_azimuth(ax,el,N,full)

Plots the magnitude of the array pattern as a function of azimuth angle.

Usage:
show_array_pattern_azimuth()
show_array_pattern_azimuth(ax)
show_array_pattern_azimuth(ax,el)
show_array_pattern_azimuth(ax,el,N)
show_array_pattern_azimuth(ax,el,N,full)
Input Arguments:
ax — (optional) an axes handle; if not passed, a new one will be created
el — (optional) the elevation angle (in radians) to use when evaluating the array azimuth pattern; if not passed, the default is used
N — (optional) number of points to take when evaluating the array pattern; if not passed, the default is used
full — (optional) a boolean specifying if the full azimuth sweep should be executed (true) or half (false); default is false; a full azimuth sweep is from [-pi,+pi); a half azimuth sweep is from [-pi/2,+pi/2)

Back to methods

#### show_array_pattern_elevation(ax,az,N,full)

Plots the magnitude of the array pattern as a function of elevation angle.

Usage:
show_array_pattern_elevation()
show_array_pattern_elevation(ax)
show_array_pattern_elevation(ax,az)
show_array_pattern_elevation(ax,az,N)
show_array_pattern_elevation(ax,az,N,full)
Input Arguments:
ax — (optional) an existing axes handle; if not passed, a new one will be created
az — (optional) the azimuth angle (in radians) to use when evaluating the array elevation pattern; if not passed, the default is used
N — (optional) number of points to take when evaluating the array pattern; if not passed, the default is used
full — (optional) a boolean specifying if the full elevation sweep should be executed (true) or half (false); default is false; a full elevation sweep is from [-pi,+pi); a half elevation sweep is from [-pi/2,+pi/2)

Back to methods

#### show_beamformer_pattern(w)

Plots the resulting beam pattern when the array employs a specific set of beamforming weights. The array weights are not overwritten.

Usage:
show_beamformer_pattern(w)
Input Arguments:
w — a vector of complex beamforming weights

Back to methods

#### show_element_pattern()

Plots the element pattern as a function of azimuth and elevation.

Usage:
show_element_pattern()

Back to methods

#### show_polar_array_pattern_azimuth(ax,el,N,full)

Plots the azimuth array pattern in a polar plot.

Usage:
show_polar_array_pattern_azimuth()
show_polar_array_pattern_azimuth(ax)
show_polar_array_pattern_azimuth(ax,el)
show_polar_array_pattern_azimuth(ax,el,N)
show_polar_array_pattern_azimuth(ax,el,N,full)
Input Arguments:
ax — (optional) axes handle to plot on; if not provided, will create a new figure and axes to plot on
el — (optional) the elevation angle (radians) to use when evaluating the azimuth pattern
N — (optional) number of points to take when evaluating the array pattern; if not passed, the default is used
full — (optional) a boolean specifying if the full sweep should be executed (true) or half (false); default is false; a full sweep is from [-pi,+pi); a half sweep is from [-pi/2,+pi/2)

Back to methods

#### show_polar_array_pattern_elevation(ax,az,N,full)

Plots the elevation array pattern in a polar plot.

Usage:
show_polar_array_pattern_elevation()
Usage:
show_polar_array_pattern_elevation()
show_polar_array_pattern_elevation(ax)
show_polar_array_pattern_elevation(ax,az)
show_polar_array_pattern_elevation(ax,az,N)
show_polar_array_pattern_elevation(ax,az,N,full)
Input Arguments:
ax — (optional) axes handle to plot on; if not provided, will create a new figure and axis to plot on
az — (optional) the azimuth angle (radians) to use when evaluating the elevation pattern
N — (optional) number of points to take when evaluating the array pattern; if not passed, the default is used
full — (optional) a boolean specifying if the full sweep should be executed (true) or half (false); default is false; a full sweep is from [-pi,+pi); a half sweep is from [-pi/2,+pi/2)

Back to methods

Back to methods

#### translate(x,y,z)

Shifts the location of all elements in the array by some change in the x, y, and z directions (in wavelengths). When x, y, and z are not passed, the array will be centered at the origin.

Usage:
translate()
translate(x)
translate(x,y)
translate(x,y,z)
Input Arguments:
x — (optional) wavelengths to move in the x direction; if not passed, the negative mean x coordinate is used which will center the array in the x direction
y — (optional) wavelengths to move in the y direction; if not passed, the negative mean y coordinate is used which will center the array in the y direction
z — (optional) wavelengths to move in the z direction; if not passed, the negative mean z coordinate is used which will center the array in the z direction

Back to methods