Module sw 

Spherical vector waves: mode labels, translation coefficients of mode pairs, expansion matrices between bases and over lattices, and the cylindrical waves radiated by a z-periodic chain of spheres.

Upstream: treams.sw, and treams.special.tl_vsw_A, tl_vsw_B, tl_vsw_rA and tl_vsw_rB.

File	Contents	Upstream
coupling.rs	degree terms (p, weight) of one mode pair, from Wigner 3j symbols	special._tl_vsw_helper, the sums of tl_vsw_A and tl_vsw_B
polar.rs	PolarTranslation and polar_translation_array: coefficients at polar arguments (kr, theta, phi)	sw.translate, special.tl_vsw_*
cartesian.rs	cartesian_translation: one coefficient at a Cartesian displacement, with its derivatives	treams-rs extension
plan.rs	the couplings of whole mode blocks, shared by every pair of positions	the loops of sw.translate over a basis
expansion.rs	expansion(), lattice_expansion and lattice_expansion_from_table	Expand, ExpandLattice, sw.translate_periodic
periodic_to_cw.rs	periodic_to_cw() and periodic_to_cw_matrix	sw.periodic_to_cw, ExpandLattice to a cylindrical basis

Conventions:

• A translation from a source position to a destination position takes the displacement destination - source. Lattice sums run over source - destination, the argument of crate::lattice::sum; the lattice paths negate the displacement where they call it.
• pol is the polarization index, 0 or 1. With helicity true, 1 is positive and 0 negative helicity; with helicity false, 1 is TM (the N multipoles) and 0 TE (the M multipoles). Bases list pol 1 before pol 0, as treams does.
• Radial::Regular and Radial::Singular are the treams modetype values ‘regular’ and ‘singular’; singular waves use the outgoing Hankel function.
• In a derivative struct such as CartesianTranslation, every field other than value holds the derivative of value with respect to the input it is named after; position holds the derivatives with respect to the displacement components.

The inline tests modules check how each file computes its results; the physical and adjoint identities of translations and expansions are in properties/waves.rs.

Modules

cartesian 🔒

Spherical translation coefficients of single mode pairs at Cartesian displacements, with their displacement and wavenumber derivatives.

coupling 🔒

Degree terms (p, weight) of the spherical translation coefficients, from the Wigner 3j couplings of a source and a destination mode.

expansion 🔒

Spherical expansion matrices between two bases and over a lattice, with analytic pullbacks. Each pair of a destination and a source position forms one block, and blocks with the same modes share one TranslationPlan.

periodic_to_cw 🔒

Outgoing cylindrical expansion of z-periodic spherical arrays, including displaced positions.

plan 🔒

Couplings of complete mode blocks, computed once and shared by every pair of positions, with the radial functions and harmonics evaluated once per displacement.

polar 🔒

Spherical translation coefficients of mode pairs in polar coordinates (kr, theta, phi), broadcast over arrays, with analytic pullbacks.

Structs

CartesianTranslation

Translation coefficient with its Cartesian and wavenumber derivatives.

ExpansionResidual

What expansion saves for its pullback: the bases, the wavenumbers, the radial kind and every block with its translation plan. The pullback recomputes the derivative tables per block.

LatticeExpansionFromTableResidual

What lattice_expansion_from_table saves for its pullback: the sparse angular weights, never the table values. The pullback runs in block order and gives the same result every run.

LatticeExpansionResidual

What lattice_expansion saves for its pullback: the bases, the wavenumbers, the lattice, the split and the blocks, whose angular plans every position pair shares.

Mode

One spherical-wave mode: degree l, order m and polarization index pol.

PeriodicToCwGradient

Position, medium, per-output-mode axial wavenumber, and period cotangents.

PeriodicToCwResidual

What periodic_to_cw_matrix saves for its pullback: the bases, the wavenumbers, the period and the polarization convention.

PolarTranslation

Fixed spherical mode-pair couplings shared across displacements and pullbacks.

PolarTranslationResidual

What polar_translation_array saves for its pullback: the arguments and one coupling plan per distinct mode pair.

Functions

cartesian_translation

Translation coefficient of the source mode from to the destination mode to, with its derivatives.

expansion

Construct a regular or singular spherical expansion matrix, which maps source coefficients to destination coefficients.

lattice_expansion

Periodic outgoing-to-regular spherical coupling, including nonzero lattice images of self blocks.

lattice_expansion_from_table

The lattice expansion matrix from a table of lattice sums, a linear map of the table.

modes

The modes of every degree up to lmax, ordered by degree, then order, then pol 1 before pol 0.

periodic_to_cw

Direct outgoing spherical-to-cylindrical coefficient of a z-periodic array.

periodic_to_cw_matrix

Outgoing cylindrical expansion of a z-periodic spherical source array. Axial Fourier wavenumbers are independent inputs; compose kz=kpar+2pin/period for diffraction orders.

polar_translation_array

Broadcast polar translations, preserving scalar arguments and fixed mode pairs.

Type Aliases

Basis

Spherical modes at Cartesian expansion positions.