Channels

metasurface_py.channels

Channel models for RIS-assisted communication links.

LinkBudgetResult dataclass

Result of an RIS-assisted link budget computation.

Parameters:

Name	Type	Description	Default
rx_power_dbm	float	Received power [dBm].	required
snr_db	float	Signal-to-noise ratio [dB].	required
path_loss_direct_db	float	Direct TX-RX path loss [dB].	required
path_loss_ris_db	float	Effective RIS-assisted path loss [dB].	required
ris_gain_db	float	Improvement over direct link [dB].	required
state	SurfaceState	The surface state used.	required

MIMORISLink dataclass

MIMO RIS-assisted narrowband link.

Extends the SISO model to multi-antenna TX and RX

H_ris = H_sr @ diag(phi) @ H_ri H_total = H_ris + H_direct (if included)

Parameters:

Name	Type	Description	Default
surface	Metasurface	Metasurface (RIS).	required
tx_positions	NDArray[floating[Any]]	TX antenna positions, shape (M_tx, 3).	required
rx_positions	NDArray[floating[Any]]	RX antenna positions, shape (M_rx, 3).	required
freq	float	Operating frequency [Hz].	required
include_direct	bool	Include direct TX-RX path.	True

num_rx property

Number of RX antennas.

num_tx property

Number of TX antennas.

capacity(state, snr_linear=100.0)

MIMO capacity [bits/s/Hz].

C = log2(det(I + (snr/M_tx) * H @ H^H))

Parameters:

Name	Type	Description	Default
state	SurfaceState	RIS configuration.	required
snr_linear	float	Total SNR (linear).	100.0

Returns:

Type	Description
float	Capacity in bits/s/Hz.

channel_matrix(state)

Compute MIMO channel matrix H_total.

H_total = H_sr @ diag(phi) @ H_ri [+ H_direct]

Parameters:

Name	Type	Description	Default
state	SurfaceState	RIS phase configuration.	required

Returns:

Type	Description
NDArray[complexfloating[Any, Any]]	Channel matrix, shape (M_rx, M_tx), complex.

optimal_state_continuous()

Optimal RIS phases via dominant singular vector alignment.

For MIMO, aligns each element's phase to maximize the dominant singular value of H_ris. Uses rank-1 approximation: phi_n = -(angle(h_ri_n @ v1) + angle(u1^H @ h_sr_n)) where u1, v1 are dominant left/right singular vectors of H_sr @ H_ri (without RIS phases).

Returns:

Type	Description
SurfaceState	SurfaceState with optimal continuous phases.

RISLink dataclass

Narrowband SISO RIS-assisted free-space link.

Models the cascaded channel: TX -> RIS -> RX, plus an optional direct TX -> RX path.

Uses the standard model from Wu & Zhang (2019): h_ris = h_sr^H @ diag(Phi) @ h_ri where h_ri is TX-to-RIS, h_sr is RIS-to-RX, and Phi is the diagonal RIS response matrix.

Parameters:

Name	Type	Description	Default
surface	Metasurface	The metasurface (RIS).	required
tx	Position3D	Transmitter position.	required
rx	Position3D	Receiver position.	required
freq	float	Operating frequency [Hz].	required
include_direct	bool	Whether to include the direct TX-RX path.	True

link_budget(state, tx_power_dbm=30.0, noise_dbm=-90.0)

Compute full link budget.

Parameters:

Name	Type	Description	Default
state	SurfaceState	Surface configuration.	required
tx_power_dbm	float	Transmit power [dBm].	30.0
noise_dbm	float	Noise power [dBm].	-90.0

Returns:

Type	Description
LinkBudgetResult	LinkBudgetResult with all metrics.

optimal_state_continuous()

Compute analytically optimal continuous phase configuration.

For free-space SISO, the optimal phases align all element contributions in phase at the receiver: phi_n = -(angle(h_ri_n) + angle(h_sr_n))

Returns:

Type	Description
SurfaceState	SurfaceState with optimal continuous phases.

received_power(state)

Compute received power (linear) for a given surface state.

Assumes unit transmit power.

Parameters:

Name	Type	Description	Default
state	SurfaceState	Current surface configuration.	required

Returns:

Type	Description
float	Received power [linear, relative to unit Tx power].

snr_db(state, tx_power_dbm=30.0, noise_dbm=-90.0)

Compute SNR in dB.

Parameters:

Name	Type	Description	Default
state	SurfaceState	Surface configuration.	required
tx_power_dbm	float	Transmit power [dBm].	30.0
noise_dbm	float	Noise power [dBm].	-90.0

Returns:

Type	Description
float	SNR [dB].

UniformLinearArray dataclass

Uniform linear array (ULA) of antennas.

Parameters:

Name	Type	Description	Default
num_antennas	int	Number of antenna elements.	required
spacing	float	Inter-element spacing [meters].	required
center	Position3D	Center position of the array.	required
axis	NDArray[floating[Any]] | None	Unit vector along array axis. Default [1,0,0] (x-axis).	None

positions property

Antenna positions, shape (M, 3) [meters].

WidebandRISLink dataclass

Wideband/OFDM RIS-assisted SISO link.

Evaluates the RIS-assisted channel at each subcarrier frequency. A single RIS phase configuration applies to all subcarriers (frequency-flat RIS control, which is physical reality).

Parameters:

Name	Type	Description	Default
surface	Metasurface	Metasurface (RIS).	required
tx	Position3D	Transmitter position.	required
rx	Position3D	Receiver position.	required
frequencies	FrequencyGrid	OFDM subcarrier frequencies.	required
include_direct	bool	Include direct TX-RX path.	True

channel_vs_frequency(state)

Channel coefficient at each subcarrier.

Parameters:

Name	Type	Description	Default
state	SurfaceState	RIS phase configuration.	required

Returns:

Type	Description
NDArray[complexfloating[Any, Any]]	Complex channel, shape (n_freq,).

ofdm_capacity(state, snr_linear=100.0)

OFDM sum-rate capacity [bits/s/Hz].

C = (1/K) * sum_k log2(1 + snr * |h[k]|^2)

Parameters:

Name	Type	Description	Default
state	SurfaceState	RIS configuration.	required
snr_linear	float	SNR per subcarrier (linear).	100.0

Returns:

Type	Description
float	Capacity in bits/s/Hz.

received_power_vs_frequency(state)

Received power at each subcarrier (linear).

Parameters:

Name	Type	Description	Default
state	SurfaceState	RIS configuration.	required

Returns:

Type	Description
NDArray[floating[Any]]	Power per subcarrier, shape (n_freq,).

free_space_path_loss(distance, freq)

Friis free-space path loss (linear scale).

FSPL = (4 * pi * d * f / c)^2

Parameters:

Name	Type	Description	Default
distance	float	Distance [meters].	required
freq	float	Frequency [Hz].	required

Returns:

Type	Description
float	Path loss as a linear ratio (>= 1).

free_space_path_loss_db(distance, freq)

Friis free-space path loss in dB.

Parameters:

Name	Type	Description	Default
distance	float	Distance [meters].	required
freq	float	Frequency [Hz].	required

Returns:

Type	Description
float	Path loss in dB (positive value).