The device object is used to represent a wireless terminal with transmit and/or receive capability.

device objects having transmit capability are fittingly referred to as “transmitters”. Those with receive capability are referred to as “receivers”. Those with both transmit and receive capability are termed “transceivers”.

The device object can be thought of as “one layer above” the transmitter and receiver objects within the architecture of MFM.

### Creating a Device

To create a device object, use

d = device.create(type)


where type is either 'transmitter', 'receiver', or 'transceiver'.

By default, this will create a device object having a fully-digital transmitter and fully-digital receiver.

To create a device with a hybrid digital/analog transmitter (transmitter_hybrid) and hybrid digital/analog receiver (receiver_hybrid), use

d = device.create(type,'hybrid')


### Key Properties

A device object d contains a few important properties.

The transmitter and receiver at d exist (as applicable) in its properties

d.transmitter


The type property is a string describing the transmit/receive capability of the device

d.type


which can be either 'transmitter', 'receiver', or 'transceiver'.

The location of d is specified by its coordinate property

d.coordinate


which is a vector representing the $(x,y,z)$ coordinate of the device in 3-D space (in meters).

### Setting the Transmitter

To set the transmitter at a device object d, use

d.set_transmitter(tx)


where tx is a transmitter object.

To set the receiver at a device object d, use

d.set_receiver(rx)


where rx is a receiver object.

### Setting the Device Location

The location of a device object d can be set using

d.set_coordinate([x,y,z])


where [x,y,z] is a vector of x, y, and z coordinates (in meters).

### Example Setup

The typical setup for a device object is of the form

d = device.create('transceiver')
d.set_transmitter(tx)
d.set_coordinate([x,y,z])


### Checking Device Type

To see if a device object d has transmit capability, use

val = d.istransmitter()


To see if it has receive capability, use

val = d.isreceiver()


To see if it has both transmit and receive capability, use

val = d.istransceiver()


where, in all three cases, val is a boolean if d has the capability (true) or not (false).

### Passthrough Methods

Since the device object contains a transmitter and/or receiver, we have supplied so-called passthrough methods that allow the user to set parameters of a device’s transmitter and/or receiver from the device itself—rather than having to set them at the transmitter or receiver.

For example, to set the transmit power of a device object d’s transmitter to 30 dBm, one could use

d.transmitter.set_transmit_power(30,'dBm')


Using the device’s passthrough methods, this can also be achieved via

d.set_transmit_power(30,'dBm')


#### For the Transmitter

The following passthrough methods exist pertaining to the transmitter of device object d:

• d.set_transmit_symbol_bandwidth(B)
• d.set_transmit_num_streams(Ns)
• d.set_transmit_symbol(s)
• d.set_transmit_array(a)
• d.set_transmit_num_rf_chains(Lt)
• d.set_transmit_power(P,unit)
• d.set_transmit_symbol_covariance(Rs)
• d.set_transmit_channel_state_information(csi)
• d.set_transmit_strategy(strategy)
• d.configure_transmitter(strategy)

The following passthrough methods exist pertaining to the receiver of device object d:

• d.set_receive_symbol_bandwidth(B)
• d.set_receive_num_streams(Ns)
• d.set_receive_symbol(s)
• d.set_received_signal(y)
• d.set_receive_array(a)
• d.set_receive_num_rf_chains(Lr)
• d.set_noise(n)
• d.set_noise_power_per_Hz(noise_psd,unit)
• d.set_receive_channel_state_information(csi)
• d.set_receive_strategy(strategy)
• d.configure_receiver(strategy)

#### For the Transmitter and Receiver

The following passthrough methods can be used to set values at the transmitter and receiver of the device object d simultaneously:

• d.set_symbol_bandwidth(B)
• d.set_num_streams(Ns)
• d.set_arrays(transmit_array,receive_array)
• d.set_num_rf_chains(Lt,Lr)

### Shorthand Methods

To provide convenient ways to retrieve common MIMO-related quantities from a device’s transmitter and receiver, there exist the following so-called shorthand methods.

• d.F — Returns the precoding matrix.
• d.W — Returns the combining matrix.
• d.Ns_tx — Returns the number of streams at the transmitter.
• d.Ns_rx — Returns the number of streams at the receiver.
• d.Nt — Returns the number of transmit antennas.
• d.Nr — Returns the number of receive antennas.
• d.Ptx — Returns the transmit energy per symbol (joules per symbol).
• d.Rs — Returns the transmit symbol covariance matrix at the transmitter.
• d.Rn — Returns the noise covariance matrix at the receiver.
• d.N0 — Returns the noise energy per symbol at the receiver.
• d.s_tx — Returns the transmit symbol.
• d.s_rx — Returns the receive symbol.
• d.x — Returns the signal vector transmitted from the transmitter.
• d.y — Returns the signal vector arriving at the receiver.

### List of Properties

The device object contains the following properties:

• device.name
• device.type
• device.coordinate
• device.transmitter
• device.receiver
• device.marker
• device.duplexing
• device.source
• device.destination
• device.carrier_frequency
• device.carrier_wavelength
• device.propagation_velocity

### List of Methods

The device object contains the following methods:

#### F()

Returns the precoding matrix.

Usage:
val = F()
Return Values:
val — the precoding matrix

Back to methods

#### N0()

Returns the noise energy per symbol of the receiver.

Usage:
val = N0()
Return Values:
val — the noise energy per symbol

Back to methods

#### Nr()

Returns the number of receive antennas.

Usage:
val = Nr()
Return Values:
val — the number of receive antennas

Back to methods

#### Ns_rx()

Returns the number of streams at the receiver.

Usage:
val = Ns_rx()
Return Values:
val — the number of streams at the receiver

Back to methods

#### Ns_tx()

Returns the number of streams at the transmitter.

Usage:
val = Ns_tx()
Return Values:
val — the number of streams at the transmitter

Back to methods

#### Nt()

Returns the number of transmit antennas.

Usage:
val = Nt()
Return Values:
val — the number of transmit antennas

Back to methods

#### Rn()

Returns the noise covariance matrix at the receiver.

Usage:
val = Rn()
Return Values:
val — the noise covariance matrix

Back to methods

#### Rs()

Returns the transmit symbol covariance matrix at the transmitter.

Usage:
val = Rs()
Return Values:
val — the transmit symbol covariance matrix at the transmitter

Back to methods

#### W()

Returns the combining matrix.

Usage:
val = W()
Return Values:
val — the combining matrix

Back to methods

#### configure_receiver(strategy)

Configures the device’s receiver according to the current/specified receive strategy, incorporating channel state information as applicable.

Usage:
configure_receiver()
configure_receiver(strategy)
Input Arguments:
strategy — (optional) receive strategy to use; if not passed, the current receive strategy will be used

Back to methods

#### configure_transmitter(strategy)

Configures the device’s transmitter according to the current/specified transmit strategy, incorporating channel state information as applicable.

Usage:
configure_transmitter()
configure_transmitter(strategy)
Input Arguments:
strategy — (optional) transmit strategy to use; if not passed, the current transmit strategy will be used

Back to methods

#### create(type,digital_hybrid)

Creates a device of specific type.

Usage:
obj = create()
obj = create(type)
obj = create(type,digital_hybrid)
obj = create([],digital_hybrid)
Input Arguments:
type — (optional) ‘transmitter’, ‘receiver’, or ‘transceiver’
digital_hybrid — (optional) ‘digital’ or ‘hybrid’
Return Values:
obj — a device object of the desired type

Back to methods

#### device(name)

Creates a device object.

Usage:
obj = device()
obj = device(name)
Input Arguments:
name — an optional name for the device
Return Values:
obj — an object representing a device

Back to methods

#### isreceiver()

Returns a boolean indicating if the device has receive capability (i.e., is either a receiver or transceiver type).

Usage:
out = isreceiver()
Return Values:
out — a boolean

Back to methods

#### istransceiver()

Returns a boolean indicating if the device has transmit and receive capability (i.e., is a transceiver).

Usage:
out = istransceiver()
Return Values:
out — a boolean

Back to methods

#### istransmitter()

Returns a boolean indicating if the device has transmit capability (i.e., is either a transmitter or transceiver type).

Usage:
out = istransmitter()
Return Values:
out — a boolean

Back to methods

#### n()

Returns the noise vector (per-antenna).

Usage:
val = n()
Return Values:
val — the noise vector (per-antenna)

Back to methods

#### s_rx()

Usage:
val = s_rx()
Return Values:
val — the receive symbol vector

Back to methods

#### s_tx()

Returns the transmit symbol vector.

Usage:
val = s_tx()
Return Values:
val — the transmit symbol vector

Back to methods

#### set_arrays(transmit_array,receive_array)

Sets the transmit and receive arrays.

Usage:
set_arrays(transmit_array)
set_arrays(transmit_array,receive_array)
Input Arguments:
transmit_array — array object to use at the transmitter
receive_array — array object to use at the receiver; if not passed, the transmit array is used

Back to methods

#### set_carrier_frequency(fc)

Sets the carrier frequency of the device.

Usage:
set_carrier_frequency(fc)
Input Arguments:
fc — carrier frequency (Hz)
Notes:

Back to methods

#### set_combiner(W)

Sets the combining matrix used at the receiver.

Usage:
set_combiner(W)
Input Arguments:
W — a combining matrix

Back to methods

#### set_coordinate(x,y,z,move_arrays)

Sets the device’s position in 3-D space.

Usage:
set_coordinate()
set_coordinate(x)
set_coordinate(x,y)
set_coordinate(x,y,z)
set_coordinate(x,y,z,move_arrays)
Input Arguments:
x — x-coordinate of the device’s position
y — y-coordinate of the device’s position
z — z-coordinate of the device’s position
move_arrays — (optional) a boolean indicating if the array(s) should be moved (relatively) to the new coordinate; if not passed, true is used
Notes:
If no arguments are passed, the device’s current coordinate will be used.
If only x and y are given, z is taken to be 0. Both x and y need to be singletons.
If only x is given and is a singleton, y and z are taken to be 0. If only x is given and has two elements, y = x(2), x = x(1), and z = 0. If only x is given and has three elements, z = x(3), y = x(2), and x = x(1).
All other options are invalid.
When the arrays are shifted according to the device coordinate, they are shifted relative to the device’s previous location. This maintains any relative geometry between the transmit and receive arrays, assuming they have already been added to the device before its coordinate is set.

Back to methods

#### set_destination(device_destination)

Sets the destination (the receive device the device aims to serve).

Usage:
set_destination(device_destination)
Input Arguments:
device_destination — a device object

Back to methods

#### set_duplexing(duplex)

Sets the device as either a half-duplex or full-duplex device.

Usage:
set_duplexing(duplex)
Input Arguments:
duplex — either ‘half’ or ‘full’, specifying the duplexing nature of the device
Notes:
Setting the device to be full-duplex does not bestow it the ability to transmit and receive simultaneously and in-band losslessly, but rather sets it to attempt to. Its performance when doing so will depend on the design of the transmitter and receiver.

Back to methods

#### set_marker(marker)

Sets the device marker.

Usage:
set_marker(marker)
Input Arguments:
marker — a MATLAB-compliant plot marker

Back to methods

#### set_name()

Sets the device’s name.

Usage:
set_name()
set_name(name)

Back to methods

#### set_noise(n)

Sets the noise vector at the receive array.

Usage:
set_noise()
set_noise(n)
Input Arguments:
n — (optional) a noise vector; if not passed, noise will be generated according to the noise power

Back to methods

#### set_noise_power_per_Hz(noise_psd,unit)

Sets the noise power per Hz at the receiver.

Usage:
set_noise_power_per_Hz(noise_psd)
set_noise_power_per_Hz(noise_psd,unit)
Input Arguments:
noise_psd — the noise power spectral density
unit — (optional) a string specifying the units of noise_psd (e.g., ‘dBm_Hz’ or ‘watts_Hz’); if not passed, the default will be used

Back to methods

#### set_num_rf_chains(Lt,Lr)

Sets the number of transmit and receive RF chains at the device.

Usage:
set_num_rf_chains(Lt,Lr)
Input Arguments:
Lt — number of transmit RF chains
Lr — (optional) number of receive RF chains; if not passed, the number of transmit RF chains is used

Back to methods

#### set_num_streams(num_streams)

Sets the number of streams at the transmitter and receiver.

Usage:
set_num_streams(num_streams)
Input Arguments:
num_streams — number of streams to multiplex at the transmitter and receiver

Back to methods

#### set_precoder(F)

Sets the precoding matrix used at the transmitter.

Usage:
set_precoder(F)
Input Arguments:
F — a precoding matrix

Back to methods

#### set_propagation_velocity(val)

Sets the propagation velocity of the signals the device.

Usage:
set_propagation_velocity(val)
Input Arguments:
val — propagation velocity (meters/sec)

Back to methods

#### set_receive_array(array)

Usage:
set_receive_array(array)
Input Arguments:
array — array object to use at the receiver

Back to methods

#### set_receive_channel_state_information(csi)

Sets the channel state information at the receiver.

Usage:
set_receive_channel_state_information(csi)
Input Arguments:
csi — a struct of channel state information

Back to methods

#### set_receive_num_rf_chains(Lr)

Sets the number of receive RF chains at the device.

Usage:
set_receive_num_rf_chains(Lr)
Input Arguments:
Lr — number of receive RF chains

Back to methods

#### set_receive_num_streams(Ns)

Sets the number of streams at the receiver.

Usage:
SET_NUM_STREAMS(Ns)
Input Arguments:
Ns — number of streams to multiplex at the receiver

Back to methods

#### set_receive_strategy(strategy)

Usage:
set_receive_strategy(strategy)
Input Arguments:
strategy — a string specifying the receive strategy

Back to methods

#### set_receive_symbol(s)

Usage:
set_receive_symbol(s)
Input Arguments:
s — receive symbol vector

Back to methods

#### set_receive_symbol_bandwidth(B)

Sets the symbol bandwidth at the receiver.

Usage:
set_receive_symbol_bandwidth(B)
Input Arguments:
B — the symbol bandwidth (in Hertz)

Back to methods

#### set_received_signal(y)

Usage:
set_received_signal(y)
Input Arguments:
y — received signal vector

Back to methods

#### set_receiver(rx)

Sets the receiver for the device.

Usage:
set_receiver(rx)
Input Arguments:
rx — a receiver object

Back to methods

#### set_source(device_source)

Sets the source (the transmit device the device aims to serve).

Usage:
set_source(device_source)
Input Arguments:
device_source — a device object

Back to methods

#### set_symbol_bandwidth(B)

Sets the symbol bandwidth at the transmitter and receiver.

Usage:
set_symbol_bandwidth(B)
Input Arguments:
B — the symbol bandwidth (in Hertz)

Back to methods

#### set_transmit_array(array)

Sets the transmit array.

Usage:
set_transmit_array(array)
Input Arguments:
array — array object to use at the transmitter

Back to methods

#### set_transmit_channel_state_information(csi)

Sets the channel state information at the transmitter.

Usage:
set_transmit_channel_state_information(csi)
Input Arguments:
csi — a struct of channel state information

Back to methods

#### set_transmit_num_rf_chains(Lt)

Sets the number of transmit RF chains at the device.

Usage:
set_transmit_num_rf_chains(Lt)
Input Arguments:
Lt — number of transmit RF chains

Back to methods

#### set_transmit_num_streams(Ns)

Sets the number of streams at the transmitter.

Usage:
SET_NUM_STREAMS(Ns)
Input Arguments:
Ns — number of streams to multiplex at the transmitter

Back to methods

#### set_transmit_power(P,unit)

Sets the transmit power of the device.

Usage:
set_transmit_power(P)
set_transmit_power(P,unit)
Input Arguments:
P — transmit power (e.g., in watts or dBm)
unit — (optional) a string specifying the units of P (e.g., ‘dBm’); if not passed, the default is used.

Back to methods

#### set_transmit_strategy(strategy)

Sets the transmit strategy.

Usage:
set_transmit_strategy(strategy)
Input Arguments:
strategy — a string specifying the transmit strategy

Back to methods

#### set_transmit_symbol(s)

Sets the transmit symbol vector.

Usage:
set_transmit_symbol(s)
Input Arguments:
s — transmit symbol vector

Back to methods

#### set_transmit_symbol_bandwidth(B)

Sets the symbol bandwidth at the transmitter.

Usage:
set_transmit_symbol_bandwidth(B)
Input Arguments:
B — the symbol bandwidth (in Hertz)

Back to methods

#### set_transmit_symbol_covariance(Rs)

Sets the transmit covariance of the device.

Usage:
set_transmit_symbol_covariance(Rs)
Input Arguments:
Rs — a covariance matrix

Back to methods

#### set_transmitter(tx)

Sets the transmitter for the device.

Usage:
set_transmitter(tx)
Input Arguments:
tx — a transmitter object

Back to methods

#### set_type(type,dh)

Sets the device as either a fully-digital or hybrid digital/analog transmitter, receiver, or transceiver.

Usage:
set_type(type)
set_type(type,dh)
Input Arguments:
type — a string specifying the type of device; either ‘transmitter’, ‘receiver’, or ‘transceiver’
dh — a string specifying the digital or hybrid digital/analog beamforming nature of the device; either ‘digital’ or ‘hybrid’
Notes:
Overwrites any existing transmitter or receiver that is present in the device.

Back to methods

#### show_transmit_receive_arrays_3d(fignum)

Plots the transmit array and receive array in 3-D space.

Usage:
[fig,ax] = show_transmit_receive_arrays_3d()
[fig,ax] = show_transmit_receive_arrays_3d(fignum)
Input Arguments:
fignum — optional figure number to use when creating plotting
Return Values:
fig — a figure handle of the plot
ax — an axis handle of the plot

Back to methods

#### turn_off_receive()

Usage:
turn_off_receive()

Back to methods

#### turn_off_transmit()

Turns off the device’s transmitter.

Usage:
turn_off_transmit()

Back to methods

#### x()

Returns the transmitted signal vector.

Usage:
val = x()
Return Values:
val — the transmitted signal vector

Back to methods

#### y()

val = y()
val — the received signal vector