Module pw 

Plane waves: polarization vectors, fields, translation phases, cyclic permutations of the Cartesian axes, and the expansion of plane waves in regular spherical and cylindrical waves.

Upstream: treams.pw, treams.misc.wave_vec_z, and treams.special.vpw_M, vpw_N and vpw_A.

File	Contents	Upstream
polarization.rs	polarization(), field_value and wave_vector_z; the private Direction jets of a wavevector	special.vpw_*, misc.wave_vec_z
field.rs	translate, phases and field()	pw.translate, special.vpw_*
permute.rs	permute_xyz and permutation	pw.permute_xyz
expand.rs	to_sw, to_cw and expansion	pw.to_sw, pw.to_cw, the Expand operator from a plane-wave basis
saved.rs	Fixed numerical layouts for derivative state	treams-rs extension

Conventions:

• A plane wave is p exp(i k·r) with a complex wavevector k = (kx, ky, kz), which may be evanescent. Its wavenumber is the algebraic norm sqrt(kx^2 + ky^2 + kz^2), not the Hermitian length.
• pol is the polarization index, 0 or 1: with helicity true, 1 is positive and 0 negative helicity; with helicity false, 1 is the N and 0 the M polarization, as for crate::sw.
• Gradients with respect to a complex wavevector use the pairing dL = Re Σ conj(g)·dk, so a real input takes the real part of its gradient.

The physical and adjoint identities of plane waves are tested in properties/plane.rs, which compares the expansions with the single-wave references of expand.rs.

Modules

expand 🔒

Regular spherical and cylindrical expansions of plane waves, with analytic pullbacks.

field 🔒

Plane-wave translation phases and fields, with analytic pullbacks.

permute 🔒

Polarization coefficients of plane waves under cyclic permutations of the Cartesian axes.

polarization 🔒

Plane-wave polarization vectors, their wavevector derivatives and the normal wavenumber.

saved 🔒

Fixed numerical layouts for plane-wave derivative state. treams-rs extension.

Structs

ExpansionGradient

Plane-expansion cotangents.

ExpansionResidual

What expansion saves for its pullback: its inputs. The pullback recomputes the coefficients instead of keeping a Jacobian.

FieldGradient

Cotangents in the real Hermitian pairing.

FieldResidual

What field saves for its pullback: its inputs, for weighted fields or for the matrix that samples every mode.

PermutationResidual

What permutation saves for its pullback: the wavevectors, the polarizations, the number of turns and the polarization convention.

PhasesGradient

Cotangents of real displacements and complex full wavevectors.

PhasesResidual

What phases saves for its pullback: the points and the wavevectors, without the phases of every point and mode.

Functions

expansion

Expand multiple plane waves in a regular multipole basis: column j holds the amplitudes of plane wave j at the basis positions.

field

Evaluate weighted plane fields, or the full operator when coefficients are absent.

field_value

The field polarization exp(i k·position) of a plane wave from its polarization vector, which polarization gives.

permutation

Polarization coefficients of plane modes under turns cyclic permutations of the axes, shape (2, modes).

permute_xyz

One cyclic-coordinate polarization coefficient without allocating a matrix: the coefficient of polarization destination in the permuted plane wave for an input of polarization source.

phases

Plane-wave translation phases with shape (displacements, wavevectors).

polarization

Plane-wave electric vector at the origin in treams normalization.

to_cw

One plane-to-cylindrical coefficient with exact axial-label matching.

to_sw

Spherical expansion coefficient for a unit-amplitude plane wave.

translate

Direct scalar plane translation phase.

wave_vector_z

The normal wavenumber kz = sqrt(k^2 - kx^2 - ky^2) on the root with a nonnegative imaginary part, so the wave propagates or decays toward +z; zero at a cutoff.