Elements

metasurface_py.elements

Unit-cell response models and state representations.

AmplitudePhaseCell dataclass

Element with coupled amplitude-phase response.

Common in varactor-based designs where the amplitude and phase are both functions of the control voltage/state.

Parameters:

Name	Type	Description	Default
state_space	StateSpace	Admissible state space.	required
amplitude_vs_state	NDArray[floating[Any]]	Amplitude values at codebook points.	required
phase_vs_state	NDArray[floating[Any]]	Phase values [rad] at codebook points.	required
control_points	NDArray[floating[Any]] | None	Control state values corresponding to amplitude/phase arrays. If None, uses uniform spacing over [0, 2*pi].	None

num_states property

Number of discrete states, or None for continuous.

response(state, freq, theta_inc=0.0, phi_inc=0.0)

Compute coupled amplitude-phase response.

Interpolates amplitude and phase as functions of the control state.

Parameters:

Name	Type	Description	Default
state	NDArray[floating[Any]]	Control state values, shape (N,).	required
freq	float	Frequency [Hz] (unused in this model).	required
theta_inc	float	Incident angle [rad] (unused).	0.0
phi_inc	float	Incident angle [rad] (unused).	0.0

Returns:

Type	Description
NDArray[complexfloating[Any, Any]]	Complex response, shape (N,).

LookupTableCell dataclass

Unit-cell model based on a lookup table of measured/simulated responses.

The table stores complex response indexed by (state, freq, theta_inc). Interpolation is used for intermediate values.

This is the Level 1 model: angle- and frequency-dependent element response.

Parameters:

Name	Type	Description	Default
table	DataArray	Complex response data with dims (state, freq, theta).	required
state_space	StateSpace	The state space derived from the table.	required

num_states property

Number of discrete states.

from_csv(path, state_col='state', freq_col='freq', theta_col='theta', mag_col='magnitude', phase_col='phase_deg') classmethod

Load lookup table from a CSV file.

Expects columns for state, frequency, theta, magnitude, and phase.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to CSV file.	required
state_col	str	Column name for state values.	'state'
freq_col	str	Column name for frequency values [Hz].	'freq'
theta_col	str	Column name for incidence angle [degrees].	'theta'
mag_col	str	Column name for response magnitude (linear).	'magnitude'
phase_col	str	Column name for response phase [degrees].	'phase_deg'

from_hdf5(path) classmethod

Load lookup table from an HDF5/NetCDF file.

from_xarray(table) classmethod

Create from an xarray DataArray with dims (state, freq, theta).

The 'state' coordinate should contain phase values in radians or codebook indices.

response(state, freq, theta_inc=0.0, phi_inc=0.0)

Compute interpolated complex response.

Parameters:

Name	Type	Description	Default
state	NDArray[floating[Any]]	Phase values in radians, shape (N,).	required
freq	float	Frequency [Hz].	required
theta_inc	float	Incident polar angle [rad].	0.0
phi_inc	float	Incident azimuthal angle [rad] (unused — table is phi-symmetric).	0.0

Returns:

Type	Description
NDArray[complexfloating[Any, Any]]	Complex response coefficients, shape (N,).

PhaseOnlyCell dataclass

Ideal phase-shifting element.

Each element applies a pure phase shift with optional fixed amplitude. This is the simplest model (Level 0): no frequency or angle dependence.

Parameters:

Name	Type	Description	Default
state_space	StateSpace	Admissible state space (continuous or discrete phase).	required
amplitude	float	Fixed amplitude for all elements (default 1.0 = lossless).	1.0

num_states property

Number of discrete states, or None for continuous.

response(state, freq, theta_inc=0.0, phi_inc=0.0)

Compute complex response: amplitude * exp(j * phase).

Parameters:

Name	Type	Description	Default
state	NDArray[floating[Any]]	Phase values in radians, shape (N,).	required
freq	float	Frequency [Hz] (unused in this model).	required
theta_inc	float	Incident polar angle [rad] (unused in this model).	0.0
phi_inc	float	Incident azimuthal angle [rad] (unused in this model).	0.0

Returns:

Type	Description
NDArray[complexfloating[Any, Any]]	Complex reflection/transmission coefficients, shape (N,).

StateSpace dataclass

Base state space description.

Parameters:

Name	Type	Description	Default
kind	Literal['continuous', 'discrete']	"continuous" or "discrete".	required
num_bits	int | None	Number of bits for discrete states (None for continuous).	None
codebook	NDArray[complexfloating[Any, Any]] | None	Complex codebook values for discrete states.	None
bounds	tuple[float, float] | None	(lower, upper) bounds for continuous states.	None

UnitCellModel

Bases: Protocol

Protocol for any unit-cell response model.

A UnitCellModel maps control state + incident conditions to complex reflection or transmission coefficients.

num_states property

Number of discrete states, or None for continuous.

state_space property

The admissible state space for this cell.

response(state, freq, theta_inc=0.0, phi_inc=0.0)

Compute complex response for given states and incident conditions.

Parameters:

Name	Type	Description	Default
state	NDArray[floating[Any]]	Control state values, shape (N,) where N is number of elements. For phase-only cells, values are phases in radians. For discrete cells, values are codebook indices (as floats).	required
freq	float	Frequency [Hz].	required
theta_inc	float	Incident polar angle [rad].	0.0
phi_inc	float	Incident azimuthal angle [rad].	0.0

Returns:

Type	Description
NDArray[complexfloating[Any, Any]]	Complex response coefficients, shape (N,).

ContinuousPhaseSpace(bounds=(0.0, 2 * np.pi))

Create a continuous phase state space.

Parameters:

Name	Type	Description	Default
bounds	tuple[float, float]	(lower, upper) phase bounds in radians.	(0.0, 2 * pi)

CustomCodebook(values)

Create a discrete state space from an arbitrary complex codebook.

Parameters:

Name	Type	Description	Default
values	NDArray[complexfloating[Any, Any]]	Complex codebook entries, shape (num_states,).	required

DiscretePhaseSpace(num_bits)

Create a discrete uniform-phase state space.

Generates a uniform codebook with 2^num_bits states evenly spaced around the unit circle.

Parameters:

Name	Type	Description	Default
num_bits	int	Number of quantization bits (1 -> 2 states, 2 -> 4 states, etc.).	required

quantize(continuous_state, codebook)

Project continuous phase values to nearest codebook entries.

Parameters:

Name	Type	Description	Default
continuous_state	NDArray[floating[Any]]	Phase values in radians, shape (N,).	required
codebook	NDArray[complexfloating[Any, Any]]	Complex codebook entries, shape (M,).	required

Returns:

Type	Description
NDArray[floating[Any]]	Quantized phase values in radians, shape (N,).

random_state(space, shape, rng=None)

Generate random states from a state space.

Parameters:

Name	Type	Description	Default
space	StateSpace	The state space to sample from.	required
shape	int | tuple[int, ...]	Shape of the output array.	required
rng	Generator | None	Random number generator. Uses default if None.	None

Returns:

Type	Description
NDArray[floating[Any]]	Random state values (phases in radians for phase spaces).