Antennas and arrays

This page covers the antenna and array result types in witwin.maxwell. Import them from the top-level package (import witwin.maxwell as mw). You need them after an FDTD run that drives one or more lumped ports and records a ClosedSurfaceMonitor (a closed near-field box used for the near-to-far-field transform).

You do not usually construct these classes yourself. They come from these calls:

All pattern tensors use the order [frequency, theta, phi], written [F, T, P]. Array tensors add a port axis N and, for codebooks, a beam axis B. Angles are in radians, powers in watts, fields in V/m. Tensors stay on the device of the run and keep their autograd graph.

import witwin.maxwell as mw
 
simulation = mw.Simulation.fdtd(
    scene,  # one LumpedPort "feed" and a ClosedSurfaceMonitor "radiation"
    frequencies=[3.0e9],
    excitations=mw.PortExcitation(
        "feed", source_time=mw.GaussianPulse(frequency=3.0e9, fwidth=1.5e9)
    ),
)
result = simulation.run()
data = result.antenna(surface="radiation", driven_port="feed")
print(data.realized_gain_max, data.radiation_efficiency)

AntennaData#

class AntennaData(frequencies, theta, phi, e_theta, e_phi, observation_radius,
                  wave_impedance, radiation_intensity, p_rad, p_accepted, p_incident,
                  directivity, gain, realized_gain, radiation_efficiency,
                  mismatch_efficiency, system_efficiency, eirp, co_polarized,
                  cross_polarized, axial_ratio, phase_center, frame,
                  polarization_basis, driven_port_name, surface_currents=None,
                  field_basis='spherical_theta_phi', power_normalization=..., phasor_convention=...)

Frozen dataclass with frequency-domain antenna metrics for one driven port. All tensors must sit on one device; the constructor checks shapes and raises ValueError or TypeError on a mismatch.

Gain is referenced to accepted power, realized gain to incident power. Fields are peak phasors with exp(-i*omega*t) time dependence. Radiation intensity is U = r^2 * (|E_theta|^2 + |E_phi|^2) / (2 * eta) in W/sr.

The optional fields e_theta, e_phi, observation_radius, wave_impedance, co_polarized, cross_polarized, and axial_ratio are either all present or all None. They are None when the data was built from radiation intensity alone.

AntennaData properties#

data = result.antenna(surface="radiation", driven_port="feed", theta_points=91, phi_points=73)
peak_dbi = 10.0 * torch.log10(data.gain_max)
loss = -data.realized_gain[:, 45, 0].mean()   # differentiable objective

Ludwig3#

class Ludwig3(reference_angle=0.0)

Frozen dataclass for the Ludwig-3 co/cross-polarization basis. With reference_angle=0, the co-polarized direction is the x-axis of AntennaData.frame at boresight.

Ludwig3.project#

Ludwig3.project(e_theta, e_phi, phi) -> tuple[torch.Tensor, torch.Tensor]

Projects spherical field components onto the Ludwig-3 basis.

Returns (co_polarized, cross_polarized), where co = e_theta*cos(a) - e_phi*sin(a) and cross = e_theta*sin(a) + e_phi*cos(a) with a = phi - reference_angle.

data = result.antenna(
    surface="radiation", driven_port="feed", polarization=mw.Ludwig3(reference_angle=0.5 * math.pi)
)

ArrayBasisData#

class ArrayBasisData(network, embedded_patterns, fingerprint, metadata={}, radiated_power_matrix=None)

Frozen dataclass holding a reusable N-port basis for one physical scene: the full scattering matrix plus one power-normalized embedded element pattern per port. You get it from result.array_basis(monitor=...) after an FDTD PortSweep run. Once you have it, combine forms any beam without running the field solver again.

Raises TypeError or ValueError when the network is incomplete, when network and patterns disagree, or when radiated_power_matrix has the wrong shape, dtype, device, or is not Hermitian.

sweep = mw.PortSweep(source_time=mw.GaussianPulse(frequency=2.5e9, fwidth=1.0e9))
result = mw.Simulation.fdtd(scene, frequency=2.5e9, excitations=sweep).run()
basis = result.array_basis(monitor="array_nf2ff", theta_points=31, phi_points=61)
print(basis.port_names, basis.eep.e_theta.shape)   # [F, N, T, P]

ArrayBasisData properties#

ArrayBasisData.combine#

ArrayBasisData.combine(weights) -> BeamData

Combines incident power-wave weights with the stored basis. Runs no field-solver steps.

Returns a BeamData. For [N] or [F, N] weights, the beam axis is dropped from every result tensor.

Raises ValueError if any beam has zero incident power at any frequency, or if the shape, device, or dtype is wrong.

weights = torch.ones(len(basis.port_names), device=basis.device, dtype=basis.dtype)
beam = basis.combine(weights)
print(beam.antenna.realized_gain.shape)          # [F, T, P]
print(beam.network.active_impedance)             # [F, N], ohms

ArrayBasisData.mimo#

ArrayBasisData.mimo(environment) -> MIMOData

Computes field-based MIMO metrics from the dual-polarized embedded patterns, integrated over the full sphere against the environment's angular power spectrum and cross-polar ratio.

Returns a MIMOData.

Raises ValueError if the angular grids differ, if the power density integrates to zero, or if any port's pattern carries no power.

ArrayBasisData.ecc_from_scattering#

ArrayBasisData.ecc_from_scattering() -> torch.Tensor

Returns the S-parameter envelope correlation coefficient approximation, shape [F, N, N]: ecc_ij = |sum_n conj(S_ni) S_nj|^2 / prod_k (1 - sum_n |S_nk|^2).

Raises ValueError if 1 - sum_n |S_ni|^2 is zero or negative for any port.

ArrayBasisData.scene_gradient_vjp#

ArrayBasisData.scene_gradient_vjp(*, columns, weights, parameters, objective=None,
                                  field_cotangents=None, reduction_order=None,
                                  retain_graph=False)

Aggregates scene-parameter gradients through the N-column basis. The stored basis is detached, so you must re-run the per-column forwards under autograd and pass the live columns here.

Returns the gradient: one tensor if parameters is a single tensor, otherwise a tuple aligned with parameters.

Raises ValueError if both or neither of objective and field_cotangents are given, if the column count is not N, or if no column depends on parameters.

ArrayBasisData.save and load#

ArrayBasisData.save(path)
ArrayBasisData.load(path, map_location=None) -> ArrayBasisData   # classmethod

save writes a detached CPU snapshot (network, embedded patterns, fingerprint, metadata, and radiated_power_matrix) and creates parent folders. The live autograd graph is not saved. load reads it with torch.load(weights_only=True) and moves tensors to map_location. Metadata must contain only primitive values and tensors.

basis.save("runs/array_basis.pt")
restored = mw.ArrayBasisData.load("runs/array_basis.pt", map_location="cuda")

EmbeddedElementPatternData#

class EmbeddedElementPatternData(frequencies, port_names, theta, phi, e_theta, e_phi,
                                 phase_center, frame, observation_radius=1.0,
                                 wave_impedance=ETA_0, polarization_basis=Ludwig3(),
                                 phase_center_source='explicit', ...)

Frozen dataclass with one far-field pattern per port. Each column is the field radiated when that port receives a unit incident power wave (1 sqrt(W)) and every other port is matched. Field units are V/m per sqrt(W).

The remaining fields (field_basis, power_normalization, phasor_convention, power_wave_convention, field_units) record conventions. The constructor accepts only their default values.

Properties: device, dtype (complex dtype of the fields), and the aliases E_theta and E_phi. save(path) and the classmethod load(path, map_location=None) behave like the ArrayBasisData versions.

BeamWeights#

class BeamWeights(values)

Frozen wrapper for complex incident power-wave amplitudes, port axis last.

beam = basis.combine(mw.BeamWeights(torch.ones(4, dtype=basis.dtype, device=basis.device)))

BeamCodebook#

class BeamCodebook(weights, names, target_angles=None, metadata={})

A named set of beam weight vectors for one basis. It holds no solver state; pass it to ArrayBasisData.combine.

Property beam_count returns B.

BeamCodebook.from_scan_angles#

BeamCodebook.from_scan_angles(*, element_positions, frequencies, theta, phi,
                              amplitude=1.0, speed_of_light=C_0,
                              name_prefix='scan') -> BeamCodebook   # classmethod

Builds progressive-phase steering weights a[b, n] = amplitude[n] * exp(+j k (r_n . d_b)), where d_b is the unit vector toward scan direction b. Element positions are not read from the scene; you supply them.

Returns a codebook with weights [B, F, N] (complex128 for float64 positions, otherwise complex64) and target_angles set.

codebook = mw.BeamCodebook.from_scan_angles(
    element_positions=positions,          # [N, 3], metres
    frequencies=basis.frequencies,
    theta=torch.full((16,), math.pi / 2, dtype=torch.float64),
    phi=torch.linspace(-0.5, 0.5, 16, dtype=torch.float64),
)
beams = basis.combine(codebook)
envelope = beams.max_hold("realized_gain")

BeamCodebook.to_weights#

BeamCodebook.to_weights(*, frequency_count, port_count, device, dtype) -> torch.Tensor

Returns the weights as [B, F, N], expanding frequency-flat weights. Raises ValueError or TypeError if the shape, device, or dtype does not match.

BeamData#

class BeamData(weights, network, far_field, antenna, frequencies, names=None, metadata={}, ...)

Frozen result of ArrayBasisData.combine. You read it; you do not build it. When you combine a batch, every tensor below has a leading beam axis B; for a single beam it does not.

network fields: a, b (reflected waves), incident_power_per_port, reflected_power_per_port, accepted_power_per_port (shape [..., F, N], W), incident_power, reflected_power, accepted_power (shape [..., F], W), active_reflection and active_impedance (ohms; NaN for ports with zero drive), active_mask, z0, port_names, frequencies.

far_field fields: e_theta, e_phi ([..., F, T, P], V/m) with aliases E_theta, E_phi, plus theta, phi, phase_center, frame, observation_radius, wave_impedance, polarization_basis.

antenna fields: radiation_intensity, directivity, gain, realized_gain ([..., F, T, P]), and p_rad, radiation_efficiency, mismatch_efficiency, system_efficiency, eirp, radiation_valid, accepted_power_valid ([..., F]). Directivity and gain are NaN where radiated or accepted power is not positive.

Properties: device, and is_batched (True when weights has rank 3).

BeamData.max_hold#

BeamData.max_hold(metric='realized_gain') -> MaxHoldComposite

Takes the per-direction maximum of a metric across the beam axis. The envelope value is differentiable through the winning beam; the winning-beam index is not.

Raises ValueError if the result is not batched, if metric is unknown, or if any beam has a NaN value for the metric.

MaxHoldComposite#

class MaxHoldComposite(metric, envelope, winning_beam, frequencies, names=None)

Frozen envelope returned by BeamData.max_hold.

Property device returns the envelope device.

MultipathEnvironment#

class MultipathEnvironment(theta, phi, power_density=1.0, cross_polar_ratio_db=0.0,
                           polarization_correlation=0.0)

Frozen description of the angular power spectrum and polarization statistics of the incident field, used by ArrayBasisData.mimo.

Public helper methods: resolved_power_density(*, device, dtype) returns the [T, P] density tensor, cross_polar_ratio(*, device, dtype) returns the linear ratio, polarization_correlation_value(*, device, dtype) returns the complex scalar, and metadata_snapshot() returns a dict describing the environment.

environment = mw.MultipathEnvironment(
    theta=basis.eep.theta, phi=basis.eep.phi, cross_polar_ratio_db=6.0
)
mimo = basis.mimo(environment)
print(mimo.ecc[0])   # [N, N] at the first frequency

MIMOData#

class MIMOData(correlation, ecc, diversity_gain, mean_effective_gain, frequencies,
               port_names, environment_metadata, source)

Frozen MIMO correlation metrics returned by ArrayBasisData.mimo.

Property device returns the device of correlation.

Related pages#