Core

metasurface_py.core

Core physics conventions, data types, and shared utilities.

EPS_0 = 1.0 / (MU_0 * SPEED_OF_LIGHT ** 2) module-attribute

Permittivity of free space [F/m].

ETA_0 = MU_0 * SPEED_OF_LIGHT module-attribute

Intrinsic impedance of free space [ohms]. Approximately 376.73 ohms.

MU_0 = 4e-07 * math.pi module-attribute

Permeability of free space [H/m].

SPEED_OF_LIGHT = 299792458.0 module-attribute

Speed of light in vacuum [m/s].

AngleGrid dataclass

A grid of angular observation directions.

Angles are stored in radians (ISO spherical convention).

Parameters:

Name	Type	Description	Default
theta	NDArray[floating[Any]]	Polar angles from +z axis [rad].	required
phi	NDArray[floating[Any]]	Azimuthal angles from +x axis [rad].	required

phi_deg property

Phi values in degrees.

theta_deg property

Theta values in degrees.

from_degrees(theta, phi) classmethod

Create from angles in degrees.

CoordinateSystem

Bases: Enum

Supported coordinate systems for angular quantities.

SPHERICAL_ISO = 'spherical_iso' class-attribute instance-attribute

ISO/physics spherical: theta from +z, phi from +x toward +y.

FrequencyGrid dataclass

A set of frequency points with derived quantities.

Parameters:

Name	Type	Description	Default
values	NDArray[floating[Any]]	Frequency values in Hz.	required

k0 property

Free-space wavenumbers [rad/m].

num_freqs property

Number of frequency points.

wavelengths property

Free-space wavelengths [m].

from_ghz(values) classmethod

Create from values in GHz.

NormalizationMode

Bases: Enum

Far-field pattern normalization modes.

DIRECTIVITY = 'directivity' class-attribute instance-attribute

Absolute directivity [dBi].

PEAK = 'peak' class-attribute instance-attribute

Normalize to peak value (0 dB at maximum).

REALIZED_GAIN = 'realized_gain' class-attribute instance-attribute

Realized gain including mismatch and efficiency.

PolarizationBasis

Bases: Enum

Supported polarization decompositions.

LUDWIG3 = 'ludwig3' class-attribute instance-attribute

Ludwig-3 co/cross-pol definition.

RHCP_LHCP = 'rhcp_lhcp' class-attribute instance-attribute

Right-hand / left-hand circular polarization.

THETA_PHI = 'theta_phi' class-attribute instance-attribute

Standard spherical basis vectors (Ludwig-2).

Position3D dataclass

A point in 3D Cartesian space [meters].

direction_to(other)

Unit vector pointing from self toward other.

distance_to(other)

Euclidean distance to another point.

to_array()

Return as (3,) numpy array.

SubstrateInfo dataclass

Optional metadata describing the substrate (for documentation, not computation).

In reduced-order models, substrate properties are baked into the unit-cell response data. This exists only for provenance tracking.

axial_ratio_db(e_theta, e_phi, floor_db=60.0)

Axial ratio [dB] of the polarization ellipse, per observation angle.

AR = (|E_R| + |E_L|) / ||E_R| - |E_L||, expressed as 20*log10(AR). Pure circular polarization gives 0 dB; pure linear gives +inf, clipped at floor_db.

Parameters:

Name	Type	Description	Default
e_theta	DataArray	Complex E_theta pattern.	required
e_phi	DataArray	Complex E_phi pattern with the same dims/coords.	required
floor_db	float	Clip value for (near-)linear polarization [dB].	60.0

Returns:

Type	Description
DataArray	Real DataArray of axial ratio in dB, same dims as the inputs.

circular_components(e_theta, e_phi)

Decompose a theta/phi far field into RHCP and LHCP components.

Parameters:

Name	Type	Description	Default
e_theta	DataArray	Complex E_theta pattern (any dims, typically (theta, phi)).	required
e_phi	DataArray	Complex E_phi pattern with the same dims/coords.	required

Returns:

Type	Description
Dataset	xr.Dataset with data_vars e_rhcp and e_lhcp (complex),
Dataset	same dims/coords as the inputs. Total power is preserved:
Dataset	|e_rhcp|^2 + |e_lhcp|^2 = |e_theta|^2 + |e_phi|^2.

k0(freq)

Free-space wavenumber [rad/m] for a given frequency [Hz].

wavelength(freq)

Free-space wavelength [m] for a given frequency [Hz].