comyx.network

`comyx.network`#

Package Summary#

Classes#

`BaseStation`	Represents a base station in the modelled environment.
`Link`	Represents a link in the modelled environment.
`RIS`	Represents a reconfigurable intelligent surface (RIS).
`STAR_RIS`	Represents a STAR-RIS (Simultaneously Transmitting and Reflecting RIS).
`Transceiver`	Represents a transceiver in the modelled environment.
`UserEquipment`	Represents a user equipment in the modelled environment.

Functions#

`cascaded_channel_gain`(→ NDArrayComplex)	Calculate the cascaded channel gain.
`effective_channel_gain`(→ NDArrayComplex)	Calculate the effective channel gain.

Reference#

class comyx.network.BaseStation(id_: str, n_antennas: int, position: List[float] | None = None, t_power: float | None = None, r_sensitivity: float | None = None, radius: float | None = None)[source]#

Bases: comyx.network.transceiver.Transceiver

Represents a base station in the modelled environment.

Identifiers may be of the form “BSx”, where x is a positive integer. The first two characters indicate the type of transceiver, i.e., “BS” for base station. The remaining characters are the unique identifier of the base station. For example, “BS1” is a base station with identifier 1.

property radius: float#: Return the radius of the base station.

class comyx.network.Link(tx: Transceiver | RIS, rx: Transceiver | RIS, fading_args: dict[str, Any], pathloss_args: dict[str, Any], shape: Tuple[int, Ellipsis], rician_args: dict[str, Any] | None = None, custom_rvs: NDArrayComplex | None = None, distance: float | None = None, seed: int | None = None)[source]#

Represents a link in the modelled environment.

A link is a connection between two transceivers. It is characterized by the distance between the two transceivers, the path loss, and the channel gain.

If rician_args are provided, the fading_args are used for the NLOS component and the rician_args are used for the LOS component.

Mathematically, the channel gain is given by

\[h_{t,r} = g_{t,r} \sqrt{PL(d_{t,r})},\]

where $g_{t,r}$ is the small-scale fading (sampled from a distribution), $PL(d_{t,r})$ is the path loss, and $d_{t,r}$ is the distance between the transceivers.

tx#: Transmitter of the link.

rx#: Receiver of the link.

shape#: Number of shape for the channel gain.

property channel_gain: NDArrayComplex#: Channel gain between the transceivers.

property distance: float#: Distance between the transceivers.

property magnitude: NDArrayFloat#: Magnitude of the channel

property pathloss: NDArrayFloat#: Path loss between the transceivers.

property phase: NDArrayFloat#: Phase of the channel

generate_rvs(custom_rvs: NDArrayComplex | None = None, seed: int = None) → None[source]#

Generate random variables for the channel gain.

Not private to allow for the generation of new channel gains for more flexible simulations.

rician_fading(K: float, order: str = 'post') → NDArrayComplex[source]#

Generate Rician fading channel gain between the transceivers.

Parameters:

K – Rician K-factor.
pos_a – Position of the first transceiver.
pos_b – Position of the second transceiver.
order – Order of RIS in the link. Possible values are ‘post’ and ‘pre’.

Returns:

Rician fading channel gain.

update_channel(distance: float | None = None, custom_rvs: NDArrayComplex | None = None, ex_pathloss: bool = False, ex_rvs: bool = False, seed: int | None = None) → None[source]#

Update the channel gain.

Parameters:

distance – New distance between the transceivers.
custom_rvs – New random variables for the channel gain.
ex_pathloss – Whether to exclude distance-based params from the update.
ex_rvs – Whether to exclude the random variables from the update.
seed – Seed for the random number generator.

update_params(distance: float | None = None) → None[source]#

Update the parameters of the link.

Parameters:: distance – New distance between the transceivers.

class comyx.network.RIS(id_: str, n_elements: int, position: List[float] | None = None)[source]#

Represents a reconfigurable intelligent surface (RIS).

An RIS is a surface with a large number of elements that can be electronically controlled to reflect the incoming signal in a desired direction.

Mathematically, the reflection matrix of the RIS is given by

\[\mathbf{R} = \text{diag}(\mathbf{a} \odot \exp(j \mathbf{\Phi})),\]

where $\mathbf{a}$ is the vector of amplitudes, $\mathbf{\Phi}$ is the vector of phase shifts, and $\odot$ is the Hadamard product.

property amplitudes: NDArrayFloat#: Return the amplitudes of the RIS.

property id: str#: Return the unique identifier of the RIS.

property n_elements: int#: Return the number of elements of the RIS.

property phase_shifts: NDArrayFloat#: Return the phase shifts of the RIS.

property position: List[float]#: Return the position of the RIS in the environment.

property reflection_matrix: NDArrayComplex#

Return the reflection matrix of the RIS.

The reflection matrix is a diagonal matrix with the phase shifts and amplitudes as its diagonal elements. The phase shifts and amplitudes must be set before accessing the reflection matrix.

The diagonality of the reflection matrix is due to the fact that the each element of the RIS reflects the incoming signal independently of the other elements.

Returns:: The reflection matrix of the RIS.

class comyx.network.STAR_RIS(id_: str, n_elements: int, position: List[float] | None = None)[source]#

Represents a STAR-RIS (Simultaneously Transmitting and Reflecting RIS).

An STAR-RIS is a surface with a large number of elements that can be electronically controlled to reflect and transmit the incoming signal in a both spaces.

Mathematically, the characteristic matrices of the STAR-RIS is given by

\[\mathbf{R}^{n} = \text{diag}(\mathbf{a}^{n} \odot \exp(j \mathbf{\Phi}^{n})),\]

where $n \in \{t, r\}$ and represents the transmission and reflection mode, respectively. Furthermore, $mathbf{a}^{n}$ is the vector of amplitudes, $\mathbf{\Phi}^{n}$ is the vector of phase shifts, and $odot$ is the Hadamard product.

Note that STAR-RIS must satisfy the law of conservation of energy, that is, $\forall i \in \{1, \ldots, N\}$ (where $N$ is the number of elements of the STAR-RIS), $(a^{t}_{i})^2 + (a^{r}_{i})^2 = 1$.

property id: str#: Return the unique identifier of the STAR-RIS.

property n_elements: int#: Return the number of antennas of the STAR-RIS.

property position: List[float]#: Return the position of the STAR-RIS in the environment.

property reflection_amplitudes: NDArrayFloat#: Return the reflection amplitudes of the STAR-RIS.

property reflection_matrix: NDArrayComplex#

Return the reflection matrix of the STAR-RIS.

The reflection matrix is a diagonal matrix with the phase shifts and amplitudes as its diagonal elements. The phase shifts and amplitudes must be set before accessing the reflection matrix.

The diagonality of the reflection matrix is due to the fact that the each element of the RIS reflects the incoming signal independently of the other elements.

Returns:: The reflection matrix of the RIS.

property reflection_phases: NDArrayFloat#: Return the reflection phase shifts of the STAR-RIS.

property transmission_amplitudes: NDArrayFloat#: Return the transmission amplitudes of the STAR-RIS.

property transmission_matrix: NDArrayComplex#

Return the transmission matrix of the STAR-RIS.

The transmission matrix is a diagonal matrix with the phase shifts and amplitudes as its diagonal elements. The phase shifts and amplitudes must be set before accessing the transmission matrix.

The diagonality of the transmission matrix is due to the fact that the each element of the RIS reflects the incoming signal independently of the other elements.

Returns:: The transmission matrix of the STAR-RIS.

property transmission_phases: NDArrayFloat#: Return the transmission phase shifts of the STAR-RIS.

class comyx.network.Transceiver(id_: str, n_antennas: int, position: List[float] | None = None, t_power: float | None = None, r_sensitivity: float | None = None)[source]#

Represents a transceiver in the modelled environment.

Fundamental class of Comyx environments; can be used to model both the base stations and the mobile stations/users.

All transceivers have a unique identifier, a position in the environment, number of antennas, and optionally a transmit power and a sensitivity. The transmit power is the power at which a transceiver transmits signals, and the sensitivity is the minimum power at which a transceiver can receive signals.

property id: str#: Return the unique identifier of the transceiver.

property n_antennas: int#: Return the number of antennas of the transceiver.

property position: List[float]#: Return the position of the transceiver in the environment.

property r_sensitivity: float | None#: Return the sensitivity of the transceiver.

property t_power: float | NDArrayFloat | None#: Return the transmit power of the transceiver.

class comyx.network.UserEquipment(id_: str, n_antennas: int, position: List[float] | None = None, t_power: float | None = None, r_sensitivity: float | None = None)[source]#

Bases: comyx.network.transceiver.Transceiver

Represents a user equipment in the modelled environment.

Identifiers may be of the form “UEx”, where x is a positive integer. The first two characters indicate the type of transceiver, i.e., “UE” for user equipment. The remaining characters are the unique identifier of the user equipment. For example, “UE42” is a user equipment with identifier 42.

property rate: NDArrayFloat#

Calculate the rate of the transceiver (Shannon formula)

Parameters:: mean_axis – Axis along which the mean is calculated. Default is -1 (last axis, i.e., over all realizations).
Returns:: Rate of the transceiver.

classmethod from_base_station(base_station: BaseStation, id_: str, n_antennas: int, t_power: float | None = None, r_sensitivity: float | None = None, height: float = 0, tolerance: float = 0) → UserEquipment[source]#

Create a user equipment within the coverage area of a base station.

Parameters:

id – Unique identifier of the user equipment.
n_antennas – Number of antennas of the user equipment.
base_station – Base station to create the user equipment from.
height – Height of the user equipment. Defaults to 0.
tolerance – Tolerance from the edge of the coverage area. Defaults to 0.

Returns:

Randomly positioned user equipment.

comyx.network.cascaded_channel_gain(tR_link: Link, Rr_link: Link, style: str = 'sum') → NDArrayComplex[source]#

Calculate the cascaded channel gain.

The cascaded channel gain is the channel gain between the transmitter and the receiver through the RIS. Mathematically, the cascaded channel gain through the RIS is given by

\[h_{csc}= \mathbf{h}_{R,r}^T \mathbf{R} \mathbf{h}_{t,R},\]

where $\mathbf{h}_{t,R}$ is the channel gain between the transmitter and the RIS, $\mathbf{h}_{R,r}$ is the channel gain between the RIS and the receiver, and $\mathbf{R}$ is the reflection matrix of the RIS. The superscript $T$ denotes the transpose operator.

If channel_gain_tR is of shape (Nt, K, Mc), and channel_gain_Rr is of shape (K, Nr, Mc), where Nt is the number of transmit antennas, K is the number of RIS elements, Nr is the number of receive antennas, and Mc is the number of channel realizations, then the cascaded channel gain is of shape (Nt, Nr, Mc). For SISO links, the cascaded channel gain is of shape (1, 1, Mc).

Parameters:

ris_link – RIS link.
style – Formula used to calculate the cascaded channel gain. Possible values are ‘sum’ and ‘matrix’.

Returns:

Cascaded channel gain.

comyx.network.effective_channel_gain(tr_link: Link, tR_link: Link, Rr_link: Link, style: str = 'sum') → NDArrayComplex[source]#

Calculate the effective channel gain.

The effective channel gain is the channel gain between the transceiver and the receiver through the RIS. Mathematically, the effective channel gain through the RIS is given by

\[h_{eff}= h_{t,r} + \mathbf{h}_{R,r}^T \mathbf{R} \mathbf{h}_{t,R},\]

where $\mathbf{h}_{t,R}$ is the channel gain between the transmitter and the RIS, $\mathbf{h}_{R,r}$ is the channel gain between the RIS and the receiver, $\mathbf{R}$ is the reflection matrix of the RIS, and $h_{t,r}$ is the channel gain between the transmitter and the receiver. The superscript $T$ denotes the transpose operator.

Parameters:

tr – Direct link.
tR – Link between the transmitter and the RIS.
Rr – Link between the RIS and the receiver.
style – Formula used to calculate the cascaded channel gain. Possible values are ‘sum’ and ‘matrix’.

Returns:

Effective channel gain.

comyx.network

Contents

comyx.network#

Package Summary#

Classes#

Functions#

Reference#

`comyx.network`#