Surfaces

`metasurface_py.surfaces`

Metasurface objects and surface state management.

`BandwidthGainResult` `dataclass`

Closed-form bandwidth and gain-bandwidth estimates.

Attributes:

Name	Type	Description
`freq`	`float`	Frequency [Hz].
`radius_lambda`	`float`	Aperture radius in free-space wavelengths.
`v_g_over_c`	`float`	Normalized surface-wave group velocity.
`gb_uniform`	`float`	Gain-bandwidth product, uniform modulation (linear).
`gb_tapered`	`float`	Gain-bandwidth product, optimal tapering (linear).
`bandwidth`	`float`	Maximum relative bandwidth delta_f/f0 (uniform).

`Metasurface` `dataclass`

A finite programmable metasurface aperture.

Combines a lattice (element positions) with a unit-cell model (element response).

Parameters:

Name	Type	Description	Default
`lattice`	`SupportsLattice`	Element placement geometry.	required
`cell`	`UnitCellModel`	Unit-cell response model.	required
`mode`	`Literal['reflect', 'transmit']`	Operating mode ("reflect" or "transmit").	`'reflect'`

`num_elements` `property`

Number of active elements.

`positions` `property`

Element positions, shape (N, 3).

`far_field(state, freq, angles, theta_inc=0.0, phi_inc=0.0)`

Compute far-field pattern (convenience wrapper).

Delegates to em.array_factor.far_field_pattern.

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

Compute per-element complex response.

Parameters:

Name	Type	Description	Default
`state`	`SurfaceState`	Surface state.	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 element responses, shape (N,).

`set_state(phase)`

Create a SurfaceState from phase values.

Parameters:

Name	Type	Description	Default
`phase`	`NDArray[floating[Any]]`	Phase values in radians. Shape (N,) or (nx, ny). Flattened if 2D.	required

Returns:

Type	Description
`SurfaceState`	A SurfaceState object.

`ModulatedMetasurfaceAntenna` `dataclass`

Circular surface-wave-fed modulated metasurface antenna.

Parameters:

Name	Type	Description	Default
`radius`	`float`	Aperture radius [m].	required
`x_transparent`	`float`	Average transparent sheet reactance [ohm] (capacitive: negative).	required
`substrate`	`SubstrateInfo`	Grounded slab; `eps_r` and `thickness_mm` are used in the dispersion computation.	required
`modulation`	`ModulationLike`	Scalar or tensor sinusoidal modulation.	required
`launch_efficiency`	`float`	Fraction of feed power launched into the surface wave (the monopole itself is not modeled).	`1.0`
`n_rho`	`int`	Radial aperture samples.	`512`
`n_phi`	`int`	Azimuthal aperture samples.	`256`

`aperture` `property`

Polar sampling grid over the aperture.

`aperture_field(freq)`

AFM aperture field (radiating -1 harmonic) at freq.

Returns:

Type	Description
`Dataset`	xr.Dataset with dims (rho, phi_ap): complex `e_rho`,
`Dataset`	`e_phi` and the 0-mode current `j0_rho`; attrs carry
`Dataset`	beta_sw, x_op, K and freq.

`bandwidth_gain(freq)`

Closed-form gain-bandwidth estimates (Faenzi et al. 2019).

`dispersion(freq, m_values=None)`

Leaky-wave dispersion versus modulation index at freq.

Defaults to a sweep from 0 to the maximum modulation index of this antenna's profile (Fig. 10-style map).

`far_field(freq, angles)`

Far-field E_theta / E_phi pattern (r*E [V]) at freq.

`surface_wave(freq)`

Self-consistent TM surface-wave solution (beta_sw, x_op, x_slab).

`SinusoidalModulation` `dataclass`

Scalar (isotropic) sinusoidal reactance modulation.

X(rho, phi) = x_avg * (1 + m(rho) * cos(psi)), with modulation phase psi = Krho + spiral_turnsphi + phase_offset - k0sin(tilt_theta)rhocos(phi - tilt_phi), K = 2pi/period. A pure radial period (tilt_theta = 0) with K = beta_lw - k0*sin(theta0) produces a conical beam at theta0; a pencil beam at (theta0, phi0) requires K = beta_lw plus the linear tilt term (this is the slowly varying s(rho) of Faenzi et al. Eq. 2).

Parameters:

Name	Type	Description	Default
`m`	`ProfileLike`	Modulation index, constant or radial profile m(rho).	required
`period`	`float`	Modulation period [m].	required
`spiral_turns`	`int`	Azimuthal spiral index n in Phi = n*phi.	`0`
`phase_offset`	`float`	Constant modulation phase [rad].	`0.0`
`tilt_theta`	`float`	Pencil-beam polar tilt angle [rad].	`0.0`
`tilt_phi`	`float`	Pencil-beam azimuth [rad].	`0.0`

`for_broadside(x_op, freq, m, spiral_turns=0, phase_offset=0.0)` `classmethod`

Period matched to the leaky wave (K = beta_lw) for a broadside beam.

`for_tilted_beam(x_op, freq, m, theta0, phi0=0.0, spiral_turns=0, phase_offset=0.0)` `classmethod`

Pencil beam tilted to (theta0, phi0) [rad].

`SurfaceState` `dataclass`

A concrete realization of programmable element controls.

Parameters:

Name	Type	Description	Default
`values`	`NDArray[floating[Any]]`	Phase/control values per element, shape (N,) in radians.	required
`space`	`StateSpace`	The state space these values belong to.	required
`mask`	`NDArray[bool_] \| None`	Boolean mask (True = active), shape (N,), or None.	`None`

`num_elements` `property`

Number of elements (including masked-out ones).

`apply_grouping(group_map)`

Enforce bias-line grouping: all elements in a group share the same state.

The group state is the circular mean of member phases.

Parameters:

Name	Type	Description	Default
`group_map`	`NDArray[integer[NBitBase]]`	Integer array mapping each element to a group ID, shape (N,).	required

Returns:

Type	Description
`Self`	New SurfaceState with grouped values.

`quantize(codebook=None)`

Project to nearest discrete states.

Parameters:

Name	Type	Description	Default
`codebook`	`NDArray[complexfloating[Any, Any]] \| None`	Complex codebook to quantize to. If None, uses the state space's codebook.	`None`

Returns:

Type	Description
`Self`	New SurfaceState with quantized values.

`with_defects(defect_mask)`

Zero out dead elements.

Parameters:

Name	Type	Description	Default
`defect_mask`	`NDArray[bool_]`	Boolean array, True = active, False = defective.	required

Returns:

Type	Description
`Self`	New SurfaceState with defective elements set to zero phase.

`TensorModulation` `dataclass`

Anisotropic sinusoidal reactance modulation (circular polarization).

Tensor entries (Faenzi et al. 2019, Eq. 1-2): X_rr = x_avg(1 + m_rho_rhocos(Krho + Phi_rr)), X_rp = x_avgm_rho_phicos(Krho + Phi_rr + delta_rho_phi), with Phi_rr = spiral_turns*phi + phase_offset. With spiral_turns = -1 and delta_rho_phi = -pi/2 the radiating -1 harmonic is uniform RHCP at broadside; spiral_turns = +1, delta_rho_phi = +pi/2 gives LHCP.

The rho-rho entry governs the TM leaky-wave dispersion; the rho-phi entry adds the orthogonal aperture-field component.

`circular_broadside(x_op, freq, m, hand='rhcp')` `classmethod`

Broadside circularly polarized design (spiral modulation).

`circular_tilted(x_op, freq, m, theta0, phi0=0.0, hand='rhcp')` `classmethod`

Circularly polarized pencil beam tilted to (theta0, phi0) [rad].

`add_manufacturing_noise(state, std_dev, rng=None)`

Add Gaussian phase noise to simulate manufacturing variability.

Parameters:

Name	Type	Description	Default
`state`	`NDArray[floating[Any]]`	Phase values, shape (N,).	required
`std_dev`	`float`	Standard deviation of phase noise [rad].	required
`rng`	`Generator \| None`	Random number generator. Uses default if None.	`None`

Returns:

Type	Description
`NDArray[floating[Any]]`	Noisy phase values, shape (N,).

`apply_group_constraint(state, groups)`

Enforce grouping: elements in the same group share the majority phase.

Parameters:

Name	Type	Description	Default
`state`	`NDArray[floating[Any]]`	Phase values, shape (N,).	required
`groups`	`NDArray[integer[Any]]`	Group ID per element, shape (N,).	required

Returns:

Type	Description
`NDArray[floating[Any]]`	Constrained phase values, shape (N,).

`apply_mask(state, mask)`

Zero out masked (inactive) elements.

Parameters:

Name	Type	Description	Default
`state`	`NDArray[floating[Any]]`	Phase values, shape (N,).	required
`mask`	`NDArray[bool_]`	Boolean mask, True = active, shape (N,).	required

Returns:

Type	Description
`NDArray[floating[Any]]`	State with inactive elements set to zero.

`dual_band_reactance_map(x_avg, modulations, centers, extent, n=256)`

Superposed spiral-modulation reactance map (Faenzi et al. Eqs. 4-6).

Synthesis-only: evaluates the rho-rho reactance entry of a superposition of sinusoidal modulations, each referred to its own feed center, over a Cartesian grid. Reproduces the interference layout of the dual-band antenna (paper Fig. 9 inset).

Parameters:

Name	Type	Description	Default
`x_avg`	`float`	Average transparent reactance [ohm].	required
`modulations`	`Sequence[ModulationLike]`	One modulation per band.	required
`centers`	`Sequence[tuple[float, float]]`	Feed center (x, y) of each modulation [m].	required
`extent`	`float`	Half-size of the square evaluation window [m].	required
`n`	`int`	Grid points per axis.	`256`

Returns:

Type	Description
`Dataset`	xr.Dataset with dims (y, x) and data_var `x_rr` [ohm].

`phase_quantize(state, num_bits)`

Quantize continuous phases to uniform discrete levels.

Parameters:

Name	Type	Description	Default
`state`	`NDArray[floating[Any]]`	Phase values in radians, shape (N,).	required
`num_bits`	`int`	Number of quantization bits (1, 2, 3, ...).	required

Returns:

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

Surfaces

metasurface_py.surfaces

BandwidthGainResult dataclass

Metasurface dataclass

num_elements property

positions property

far_field(state, freq, angles, theta_inc=0.0, phi_inc=0.0)

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

set_state(phase)

ModulatedMetasurfaceAntenna dataclass

aperture property

aperture_field(freq)

bandwidth_gain(freq)

dispersion(freq, m_values=None)

far_field(freq, angles)

surface_wave(freq)

SinusoidalModulation dataclass

for_broadside(x_op, freq, m, spiral_turns=0, phase_offset=0.0) classmethod

for_tilted_beam(x_op, freq, m, theta0, phi0=0.0, spiral_turns=0, phase_offset=0.0) classmethod

SurfaceState dataclass

num_elements property

apply_grouping(group_map)

quantize(codebook=None)

with_defects(defect_mask)

TensorModulation dataclass

circular_broadside(x_op, freq, m, hand='rhcp') classmethod

circular_tilted(x_op, freq, m, theta0, phi0=0.0, hand='rhcp') classmethod

add_manufacturing_noise(state, std_dev, rng=None)

apply_group_constraint(state, groups)

apply_mask(state, mask)

dual_band_reactance_map(x_avg, modulations, centers, extent, n=256)

phase_quantize(state, num_bits)

`metasurface_py.surfaces`

`BandwidthGainResult` `dataclass`

`Metasurface` `dataclass`

`num_elements` `property`

`positions` `property`

`far_field(state, freq, angles, theta_inc=0.0, phi_inc=0.0)`

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

`set_state(phase)`

`ModulatedMetasurfaceAntenna` `dataclass`

`aperture` `property`

`aperture_field(freq)`

`bandwidth_gain(freq)`

`dispersion(freq, m_values=None)`

`far_field(freq, angles)`

`surface_wave(freq)`

`SinusoidalModulation` `dataclass`

`for_broadside(x_op, freq, m, spiral_turns=0, phase_offset=0.0)` `classmethod`

`for_tilted_beam(x_op, freq, m, theta0, phi0=0.0, spiral_turns=0, phase_offset=0.0)` `classmethod`

`SurfaceState` `dataclass`

`num_elements` `property`

`apply_grouping(group_map)`

`quantize(codebook=None)`

`with_defects(defect_mask)`

`TensorModulation` `dataclass`

`circular_broadside(x_op, freq, m, hand='rhcp')` `classmethod`

`circular_tilted(x_op, freq, m, theta0, phi0=0.0, hand='rhcp')` `classmethod`

`add_manufacturing_noise(state, std_dev, rng=None)`

`apply_group_constraint(state, groups)`

`apply_mask(state, mask)`

`dual_band_reactance_map(x_avg, modulations, centers, extent, n=256)`

`phase_quantize(state, num_bits)`