EM

metasurface_py.em

Electromagnetic modeling: array factor, far-field, steering, leaky waves.

LeakyWaveMode dataclass

Complex leaky-wave mode of a sinusoidally modulated reactance.

Attributes:

Name	Type	Description
beta	float	Phase constant of the fundamental (0-indexed) harmonic [rad/m].
alpha	float	Attenuation (leakage) constant [Np/m], alpha >= 0.
beta_sw	float	Unmodulated surface-wave phase constant [rad/m].
converged	bool	True if the Newton iteration and mode-count check passed.
n_modes	int	Floquet harmonics per side used in the truncation.

beta_delta property

Modulation-induced shift beta - beta_sw [rad/m].

k_lw property

Complex leaky wavenumber beta - j*alpha [rad/m].

SurfaceWaveSolution dataclass

Self-consistent TM surface-wave solution on sheet + grounded slab.

Attributes:

Name	Type	Description
beta	float	Surface-wave phase constant [rad/m].
x_op	float	Equivalent opaque (impenetrable) reactance [ohm].
x_slab	float	Grounded-slab input reactance at beta [ohm].
x_sheet	float	Transparent sheet reactance used [ohm].
freq	float	Frequency [Hz].

afm_surface_current(rho, k_local)

0-mode surface-wave current J_rho(rho) of the adiabatic Floquet model.

J(rho) = H_1^(2)( int_0^rho k_local(rho') drho' ), the cylindrical outgoing-wave form of Faenzi et al. (2019) Eq. (3) for the n=0 mode, with the local complex wavenumber accumulated adiabatically along the radius. The imaginary part of k_local (leakage alpha) produces the radial amplitude decay.

Parameters:

Name	Type	Description	Default
rho	RealArray	Radial samples, increasing, shape (n,) [m].	required
k_local	ComplexArray	Local complex wavenumber beta(rho) - j*alpha(rho), shape (n,).	required

Returns:

Type	Description
ComplexArray	Complex current profile, shape (n,) (unnormalized).

alpha_for_taper(rho, amplitude, efficiency=0.9)

Radial leakage profile alpha(rho) for a target aperture amplitude.

Cylindrical leaky-wave illumination synthesis: 2alpha(rho) = rho|A|^2 / ((1/eta_s)*int_0^a rho'|A|^2 drho' - int_0^rho rho'|A|^2 drho') where eta_s is the fraction of surface-wave power radiated over the aperture (Minatti et al., IEEE TAP 64(9), 3907-3919, 2016).

Parameters:

Name	Type	Description	Default
rho	NDArray[floating[Any]]	Radial samples, increasing, shape (n,) [m].	required
amplitude	NDArray[floating[Any]]	Target aperture amplitude |A(rho)|, shape (n,).	required
efficiency	float	Fraction of SW power radiated (0 < eta_s < 1).	0.9

Returns:

Type	Description
NDArray[floating[Any]]	alpha(rho) [Np/m], shape (n,).

aperture_flux_power(e_x, e_y, cell_areas)

Power carried by a tangential aperture field [W].

P = (1/(2*eta0)) * sum(|E_x|^2 + |E_y|^2) * dA. For electrically large apertures this matches the integrated radiated power of :func:radiate_aperture to within the quadrature error.

apply_coupling(element_response, coupling_matrix)

Modify element responses to account for mutual coupling.

The coupled response is: w_coupled = C @ w_isolated where C is the coupling matrix.

Parameters:

Name	Type	Description	Default
element_response	NDArray[complexfloating[Any, Any]]	Isolated element responses, shape (N,).	required
coupling_matrix	NDArray[complexfloating[Any, Any]]	N x N coupling matrix.	required

Returns:

Type	Description
NDArray[complexfloating[Any, Any]]	Coupled element responses, shape (N,).

directivity(pattern)

Compute directivity from a far-field pattern.

D(theta, phi) = 4*pi * |AF|^2 / integral(|AF|^2 * sin(theta) dtheta dphi)

Parameters:

Name	Type	Description	Default
pattern	DataArray	Complex far-field pattern with dims (theta, phi).	required

Returns:

Type	Description
DataArray	Directivity pattern (linear) with same dims.

dispersion_map(x_op, m_values, period, freq, n_modes=7)

Leaky-wave beta and alpha versus modulation index.

Reproduces Fig. 10-style maps from Faenzi et al. (2019): the propagation and attenuation constants of the leaky wave as functions of the modulation index.

Parameters:

Name	Type	Description	Default
x_op	float	Average opaque reactance [ohm].	required
m_values	NDArray[floating[Any]]	Modulation indices, shape (n_m,).	required
period	float	Modulation period [m].	required
freq	float	Frequency [Hz].	required
n_modes	int	Floquet truncation per side.	7

Returns:

Type	Description
Dataset	xr.Dataset with dim m and data_vars beta_over_k0,
Dataset	alpha_over_k0, converged; attrs carry x_op, period, freq.

dispersion_modulated_reactance(x_op, m, period, freq, n_modes=7)

Complex leaky-wave mode of X(x) = x_op(1 + mcos(2pix/period)).

Solves the truncated Floquet transverse-resonance determinant by complex Newton iteration with continuation in the modulation index (steps of <= 0.05 starting from the analytic m=0 surface wave).

Parameters:

Name	Type	Description	Default
x_op	float	Average opaque reactance [ohm], > 0.	required
m	float	Modulation index (0 <= m < 1).	required
period	float	Modulation period d [m]; K = 2*pi/d.	required
freq	float	Frequency [Hz].	required
n_modes	int	Floquet harmonics per side in the truncation.	7

Returns:

Type	Description
LeakyWaveMode	LeakyWaveMode with beta, alpha and convergence status. converged
LeakyWaveMode	also requires the root to move < 1e-5*k0 when n_modes is increased
LeakyWaveMode	by 2.

References

Oliner & Hessel, IRE Trans. Antennas Propag. 7, 201-208 (1959). Minatti et al., IEEE Trans. Antennas Propag. 64(9), 3896-3906 (2016).

far_field_pattern(surface, state, freq, angles, theta_inc=0.0, phi_inc=0.0)

Compute the far-field radiation pattern of a metasurface.

Combines element response (from the cell model) with the array factor.

Parameters:

Name	Type	Description	Default
surface	Metasurface	The metasurface object.	required
state	SurfaceState	Current surface state.	required
freq	float	Frequency [Hz].	required
angles	AngleGrid	Observation angles.	required
theta_inc	float	Incident polar angle [rad].	0.0
phi_inc	float	Incident azimuthal angle [rad].	0.0

Returns:

Type	Description
DataArray	Complex far-field pattern as labeled xr.DataArray with dims (theta, phi).
DataArray	Attributes include unit="complex_field".

focusing_phase(lattice, focal_point, freq)

Compute phase for near-field focusing at a point.

Phase at element n: phi_n = -k0 * |focal_point - r_n| (spherical wave conjugation).

Parameters:

Name	Type	Description	Default
lattice	SupportsLattice	Element positions.	required
focal_point	NDArray[floating[Any]] | tuple[float, float, float]	Target focal point (x, y, z) [meters].	required
freq	float	Frequency [Hz].	required

Returns:

Type	Description
NDArray[floating[Any]]	Phase values per element [rad], shape (N,).

gain_bandwidth_product(v_g_over_c, radius_lambda, uniform=True)

Gain-bandwidth product estimate for modulated MTS antennas.

GB ~= 22(v_g/c)a_lambda for uniform amplitude modulation and GB ~= 47(v_g/c)a_lambda/(a_lambda + 2) for optimal amplitude tapering, with G linear and B = delta_f/f0 (Faenzi et al. 2019, citing Minatti et al., IEEE TAP 65(6), 2836-2842, 2017).

Parameters:

Name	Type	Description	Default
v_g_over_c	float	Normalized SW group velocity.	required
radius_lambda	float	Aperture radius in free-space wavelengths.	required
uniform	bool	True for uniform modulation, False for optimal tapering.	True

Returns:

Type	Description
float	Gain-bandwidth product (linear gain times relative bandwidth).

grounded_slab_reactance_tm(freq, eps_r, thickness, beta)

TM input reactance of a grounded dielectric slab at the top face.

X_slab = (k_z1 / (omega * eps0 * eps_r)) * tan(k_z1 * h), with k_z1 = sqrt(eps_r*k0^2 - beta^2). Positive (inductive) for thin slabs below the first thickness resonance.

Parameters:

Name	Type	Description	Default
freq	float	Frequency [Hz].	required
eps_r	float	Slab relative permittivity.	required
thickness	float	Slab thickness [m].	required
beta	float	Transverse propagation constant along the surface [rad/m].	required

Returns:

Type	Description
float	Input reactance [ohm] (sign carries inductive/capacitive).

half_power_beamwidth(pattern, cut_phi=0.0)

Compute half-power beamwidth (HPBW) for a given phi cut [rad].

Parameters:

Name	Type	Description	Default
pattern	DataArray	Complex far-field pattern.	required
cut_phi	float	Phi value for the cut plane [rad].	0.0

Returns:

Type	Description
float	HPBW in radians. Returns NaN if cannot be determined.

modulated_aperture_field(rho, phi, j0_current, x_avg, big_k, m_rho_rho, m_rho_phi, spiral_turns, phase_offset=0.0, delta_rho_phi=-np.pi / 2.0, extra_phase=None)

Radiating -1-harmonic aperture field of the modulated reactance.

The e^{+j(K s + Phi)} half of the modulation cos(K s + Phi) multiplies the 0-mode current to produce the fast (radiating) harmonic: E_rho = jx_avg(m_rr/2)exp(j(Krho + Phi_rr(phi)))J(rho), with Phi_rr = spiral_turns*phi + phase_offset, and analogously E_phi from the rho-phi tensor entry with Phi_rp = Phi_rr + delta_rho_phi.

With spiral_turns = -1 and delta_rho_phi = -pi/2 the aperture field is (rho_hat - jphi_hat)A(rho)e^{-jphi} = (x_hat - jy_hat)A(rho), i.e. uniform RHCP for a broadside design.

Parameters:

Name	Type	Description	Default
rho	RealArray	Radial samples, shape (n_rho,) [m].	required
phi	RealArray	Azimuthal samples, shape (n_phi,) [rad].	required
j0_current	ComplexArray	0-mode current J(rho), shape (n_rho,).	required
x_avg	float	Average transparent reactance [ohm].	required
big_k	float	Modulation wavenumber K = 2*pi/period [rad/m].	required
m_rho_rho	RealArray	Modulation index profile for the rho-rho entry, shape (n_rho,).	required
m_rho_phi	RealArray	Modulation index profile for the rho-phi entry, shape (n_rho,); zeros for a scalar (isotropic) modulation.	required
spiral_turns	int	Azimuthal spiral index n in Phi = n*phi (+-1 gives CP).	required
phase_offset	float	Constant modulation phase [rad].	0.0
delta_rho_phi	float	Phase of the rho-phi entry relative to rho-rho [rad].	-pi / 2.0
extra_phase	RealArray | None	Optional additional modulation phase on the (rho, phi) grid, shape (n_rho, n_phi) [rad]. Used for tilted pencil beams, where the modulation phase carries a -k0sin(theta0)rho*cos(phi - phi0) term.	None

Returns:

Type	Description
(e_rho, e_phi)	complex aperture fields, each shape (n_rho, n_phi).

multi_beam_phase(lattice, directions, weights, freq)

Compute phase for multi-beam synthesis (superposition approximation).

Combines steering vectors for multiple beam directions with optional weights. This produces an approximate multi-beam pattern; the result should be optimized for best performance.

Parameters:

Name	Type	Description	Default
directions	list[tuple[float, float]]	List of (theta, phi) steering angles [rad].	required
weights	list[float] | None	Optional amplitude weights per beam. Defaults to uniform.	required
freq	float	Frequency [Hz].	required

Returns:

Type	Description
NDArray[floating[Any]]	Phase values per element [rad], shape (N,).

mutual_impedance_approx(lattice, freq, method='canonical_dipole')

Compute approximate mutual impedance matrix.

Uses canonical minimum-scattering dipole model for inter-element coupling. The coupling coefficient between elements i and j is approximated as: Z_ij ~ exp(-jkd_ij) / (k*d_ij) for i != j.

Parameters:

Name	Type	Description	Default
lattice	SupportsLattice	Element positions.	required
freq	float	Frequency [Hz].	required
method	str	Coupling model ("canonical_dipole").	'canonical_dipole'

Returns:

Type	Description
NDArray[complexfloating[Any, Any]]	N x N complex coupling matrix (diagonal = 1).

opaque_to_transparent(x_op, x_slab)

Inverse of :func:transparent_to_opaque.

pattern_directivity(pattern)

Directivity (linear) of a two-component E_theta/E_phi pattern.

peak_gain_db(pattern)

Peak directivity/gain in dBi from a far-field pattern.

Parameters:

Name	Type	Description	Default
pattern	DataArray	Complex far-field pattern.	required

Returns:

Type	Description
float	Peak directivity in dBi.

radiate_aperture(positions, e_x, e_y, cell_areas, freq, angles)

Far field of a tangential aperture field over a ground plane.

Vector radiation integral (Balanis, Antenna Theory 4th ed., Ch. 12.5, exp(+jomegat) form): with f_{x,y}(theta, phi) = sum_n E_{x,y,n} * dA_n * exp(+jk0r_hat . r_n),

E_theta = (j*k0/(2*pi)) * (f_x*cos(phi) + f_y*sin(phi))
E_phi   = (j*k0/(2*pi)) * cos(theta) * (f_y*cos(phi) - f_x*sin(phi))

The returned fields are rE [V]: multiply by exp(-jk0r)/r for the field at distance r. Radiated power follows from :func:radiated_power, and D = 4pi|rE|^2 / (2eta0*P).

Parameters:

Name	Type	Description	Default
positions	RealArray	Aperture sample positions, shape (N, 3) [m].	required
e_x	ComplexArray	Aperture E_x at the samples, shape (N,) [V/m].	required
e_y	ComplexArray	Aperture E_y at the samples, shape (N,) [V/m].	required
cell_areas	RealArray	Quadrature areas, shape (N,) [m^2].	required
freq	float	Frequency [Hz].	required
angles	AngleGrid	Observation angles (theta in [0, pi/2] for the half-space).	required

Returns:

Type	Description
Dataset	xr.Dataset with complex data_vars E_theta, E_phi [V]
Dataset	over dims (theta, phi); attrs carry freq and normalization.

radiated_power(pattern)

Total radiated power [W] from an r*E pattern Dataset.

P = (1/(2*eta0)) * integral(|E_theta|^2 + |E_phi|^2) sin(theta) dtheta dphi.

relative_bandwidth(v_g_over_c, radius_lambda)

Maximum relative bandwidth B ~= 0.95*(v_g/c)/a_lambda (uniform modulation).

sidelobe_level(pattern, main_beam_theta, main_beam_phi, exclusion_radius_rad=0.1)

Compute peak sidelobe level relative to main beam [dB].

Parameters:

Name	Type	Description	Default
pattern	DataArray	Complex far-field pattern.	required
main_beam_theta	float	Main beam polar angle [rad].	required
main_beam_phi	float	Main beam azimuthal angle [rad].	required
exclusion_radius_rad	float	Angular radius around main beam to exclude [rad].	0.1

Returns:

Type	Description
float	Peak sidelobe level in dB (negative value = sidelobes below main beam).

solve_sw_transparent(x_sheet, freq, eps_r, thickness)

Self-consistent TM surface wave for a transparent sheet on a grounded slab.

Solves the transverse-resonance condition X_op(beta) = sqrt(beta^2 - k0^2) / (omega * eps0), where X_op(beta) is the parallel combination of the sheet with the slab reactance at beta.

Parameters:

Name	Type	Description	Default
x_sheet	float	Transparent sheet reactance [ohm] (capacitive: < 0).	required
freq	float	Frequency [Hz].	required
eps_r	float	Slab relative permittivity.	required
thickness	float	Slab thickness [m].	required

Returns:

Type	Description
SurfaceWaveSolution	SurfaceWaveSolution with beta, x_op, x_slab.

Raises:

Type	Description
ValueError	If no TM surface-wave root exists in (k0, sqrt(eps_r)*k0).

steering_phase(lattice, theta_steer, phi_steer, freq)

Compute progressive phase shift for beam steering.

For a reflective surface with normal incidence, the required phase at element n is: phi_n = -k0 * (x_nu + y_nv) where (u, v) = (sin(theta)cos(phi), sin(theta)sin(phi)).

The negative sign ensures constructive interference in the target direction under our exp(-jomegat) convention.

Parameters:

Name	Type	Description	Default
lattice	SupportsLattice	Element positions.	required
theta_steer	float	Target polar angle [rad].	required
phi_steer	float	Target azimuthal angle [rad].	required
freq	float	Frequency [Hz].	required

Returns:

Type	Description
NDArray[floating[Any]]	Phase values per element [rad], shape (N,).

sw_group_velocity(x_sheet, freq, eps_r, thickness, rel_step=0.001)

Normalized surface-wave group velocity v_g/c.

Central finite difference of the surface-wave dispersion beta(omega). The transparent sheet is treated as a quasi-static capacitance, so x_sheet scales as f_ref/f at the stencil points (Faenzi et al. 2019, wideband section).

Parameters:

Name	Type	Description	Default
x_sheet	float	Transparent sheet reactance at freq [ohm].	required
freq	float	Frequency [Hz].	required
eps_r	float	Slab relative permittivity.	required
thickness	float	Slab thickness [m].	required
rel_step	float	Relative frequency step for the stencil.	0.001

Returns:

Type	Description
float	v_g / c (dimensionless, in (0, 1]).

sw_wavenumber_tm(x_op, freq)

TM surface-wave phase constant on an impenetrable reactance boundary.

beta_sw / k0 = sqrt(1 + (x_op / eta0)^2), valid for inductive x_op > 0.

Parameters:

Name	Type	Description	Default
x_op	float	Opaque (impenetrable) surface reactance [ohm], must be > 0.	required
freq	float	Frequency [Hz].	required

Returns:

Type	Description
float	beta_sw [rad/m].

total_field(pattern)

Total field magnitude sqrt(|E_theta|^2 + |E_phi|^2) as a DataArray.

Suitable input for :func:metasurface_py.em.array_factor.directivity and the other scalar pattern metrics.

transparent_to_opaque(x_sheet, x_slab)

Opaque reactance from transparent sheet + slab (parallel combination).

jX_op = (jx_sheet * jx_slab) / (jx_sheet + j*x_slab). A capacitive sheet (x_sheet < 0) in parallel with the inductive slab yields the inductive opaque reactance that supports the TM surface wave.