Skip to content

treams_rs.pw

Coefficients of plane waves: translation, expansion and axis permutation.

Mirrors treams.pw. A plane wave has a wavevector (kx, ky, kz) and a polarization index pol (0 or 1). Each coefficient relates a source mode to a destination mode, and the destination comes first: to_sw and to_cw take the spherical or cylindrical destination, then the plane-wave source. Label arguments broadcast like NumPy ufunc arguments, and further positional and keyword arguments (out, where) go to the ufunc.

  • translate: the phase exp(i k . r) of a translation by r.
  • to_sw and to_cw: the expansion of a plane wave in regular spherical or cylindrical waves at the origin.
  • permute_xyz: the polarization coefficients of a plane wave after a cyclic permutation of the Cartesian axes.

poltype selects the polarization convention: "helicity" (the default when omitted), where pol 0 is negative and 1 positive helicity, or "parity", where pol 0 is the transverse-electric and 1 the transverse-magnetic wave. translate and to_cw are the same in both.

Autodiff holds the axial-label matching in to_cw fixed. If the axial wavenumber varies, use that same parameter for both kzcw and kzpw. Changing whether the labels match is a discrete transition without a derivative. With matching labels the coefficient is independent of their shared axial wavenumber.

Differences from treams

  • Invalid modes and nonfinite arguments raise ValueError; treams returns NaN for them, for example in to_sw with |m| > l.
  • There is no config.POLTYPE: poltype=None always means "helicity".

Example:

import numpy as np
from treams_rs import pw

k, r = np.array([0.3, 0.2, 0.9]), np.array([1.0, 2.0, 3.0])
assert np.isclose(pw.translate(*k, *r), np.exp(1j * k @ r))
# Helicity survives the permutation of the axes.
assert pw.permute_xyz(*k, 1, 0) == 0

permute_xyz

permute_xyz(kx: ArrayLike, ky: ArrayLike, kz: ArrayLike, p: ArrayLike, q: ArrayLike, poltype: str | None=None, inverse: bool=False, *args: object, **kwargs: object) -> complex | NDArray[np.complex128]

Polarization coefficient of a plane wave in cyclically permuted axes.

Mirrors treams.pw.permute_xyz. The permuted axes are (x', y', z') = (z, x, y), in which the wavevector reads (kz, kx, ky). The coefficient is the amplitude of polarization p in the permuted axes for a wave of polarization q in the original axes. inverse=True uses (x', y', z') = (y, z, x) instead. The values equal treams'; the treams docstring writes (y, z, x) for inverse=False.

Args

  • kx: x component of the wavevector, real or complex.
  • ky: y component of the wavevector, real or complex.
  • kz: z component of the wavevector, real or complex.
  • p: Polarization index in the permuted axes (destination).
  • q: Polarization index in the original axes (source).
  • poltype: "helicity" (default) or "parity".
  • inverse: If True, use the inverse permutation.
  • *args: Further ufunc arguments, such as out.
  • **kwargs: Further ufunc keywords, such as where.

Returns

complex128 array with the broadcast shape of the arguments. Python numbers give one complex number.

to_cw

to_cw(kzcw, m, polcw, kx, ky, kzpw, polpw, /, out=None, *, where=True)

The amplitude of the regular cylindrical wave (kzcw, m, polcw) in the plane wave (kx, ky, kzpw, polpw), and 0 unless kzcw == kzpw.

Mirrors treams.pw.to_cw.

Differences from treams: orders |m| up to 128; ValueError for non-finite input.

to_sw

to_sw(l: ArrayLike, m: ArrayLike, polsw: ArrayLike, kx: ArrayLike, ky: ArrayLike, kz: ArrayLike, polpw: ArrayLike, poltype: str | None=None, *args: object, **kwargs: object) -> complex | NDArray[np.complex128]

Coefficient of a plane wave in regular spherical waves.

Mirrors treams.pw.to_sw. The spherical wave is centred at the origin. The spherical destination mode comes first.

Args

  • l: Degree of the spherical destination mode.
  • m: Order of the spherical destination mode.
  • polsw: Polarization index of the spherical destination mode.
  • kx: x component of the source wavevector.
  • ky: y component of the source wavevector.
  • kz: z component of the source wavevector.
  • polpw: Polarization index of the plane-wave source mode.
  • poltype: "helicity" (default) or "parity".
  • *args: Further ufunc arguments, such as out.
  • **kwargs: Further ufunc keywords, such as where.

Returns

complex128 array with the broadcast shape of the label arguments.

Differences from treams

|m| > l raises ValueError; treams returns NaN.

translate

translate(kx, ky, kz, x, y, z, *args, **kwargs)

Plane-wave translation phase exp(i k.r) with array broadcasting.

Python scalars take a direct native path that also accepts complex positions with zero imaginary part. Arrays and ufunc options use the ufunc of the same name, which requires real positions.

Mirrors treams.pw.translate.

Differences from treams: real positions; ValueError for non-finite input.