Module special 

Special functions: Bessel, Legendre, Ferrers and Wigner functions, solid harmonics, incomplete gamma and Kambe integrals, and coordinate transforms.

Upstream: treams.special.

File	Contents	treams source
bessel	Cylindrical and spherical Bessel functions and radial jets	jv, yv, hankel1, hankel2 and spherical_* (scipy), _bessel.pyx
legendre	Associated Legendre functions and the angular functions pi and tau	lpmv, pi_fun, tau_fun of _waves.pyx
ferrers	Ferrers functions of real, non-integer degree	treams.special.lpmv
wigner	Wigner 3j symbols and Wigner small-d and D functions	_wigner3j.pyx, _wignerd.pyx
harmonics	Cartesian solid harmonics and the spherical-harmonic normalization	none: a treams-rs addition for translations and lattice sums
coordinates	Point and vector-component transforms between charts	_coord.pyx
integrals	Upper incomplete gamma function and Kambe integrals	_integrals.pyx
polarization	Helicity and parity combinations of vector waves	the vsw_A convention of _waves.pyx

Label bounds

treams accepts any degree. Here the multipole degree, the integer-order radial jets and the Kambe and Wigner labels have fixed bounds, so the caches and tables that serve them have a fixed size:

• MAX_DEGREE = 128 bounds the multipole degree l.
• MAX_ORDER = 256 = 2 MAX_DEGREE bounds the integer-order radial jets and the log-factorial cache, since translations couple degrees l1 + l2.
• MAX_LABEL = 260 bounds Kambe orders, and Wigner labels at the Python interface. Lattice sums and their derivatives take Kambe orders n up to |n| = 2 MAX_DEGREE + 3 = 259, which the derivatives of 1D spherical sums reach; the bound keeps one order of margin.
• SERIES_RADIUS = 0.5 is the argument modulus below which regular radial functions use their power series instead of AMOS evaluations.

Two kinds of jet

A jet is a value together with some of its derivatives. RadialJet holds a radial function and its first two derivatives in its one complex argument, as the vector waves need them. numerics::Jet<N> holds a value and its first derivatives along N inputs; kernels generic in N use it to evaluate (N = 0) and to differentiate with one code path. spherical_radial and cylindrical_radial return a RadialJet, and radial_jet turns one into a Jet<N> by the chain rule.

Modules

bessel 🔒

Bessel functions and radial jets with analytic argument derivatives.

coordinates

Coordinate and vector-component transformations in orthonormal local frames.

ferrers 🔒

Real-degree Ferrers functions of the first kind with integer order.

harmonics 🔒

Cartesian solid harmonics r^l P_l^m(z/r) e^(i m phi) with their gradients and Hessians, singly or tabulated for every degree and order, their values and tangential gradients on the unit sphere, and the normalization of spherical harmonics.

integrals 🔒

Incomplete gamma and Kambe integrals used by the Ewald lattice sums. Recurrences follow DLMF 8.8 and Kambe (1968), as in treams.

legendre 🔒

Associated Legendre functions of integer degree and the vector-wave angular functions pi and tau, with analytic argument derivatives. Real-degree Legendre values come from the Ferrers functions in ferrers.

polarization 🔒

Polarization conventions of vector waves: how the polarization index pol combines the two multipole parts M and N of a wave.

wigner 🔒

Wigner 3j symbols from the Schulten-Gordon recurrence in j3, continued in each direction while the symbols grow, and the Wigner small-d and D functions in the z-y-z convention.

Structs

AngularResidual

What angular_array saves for its pullback: the degrees, orders, arguments and function. The pullback recomputes the local derivatives.

BesselResidual

What bessel_array saves for its pullback: the orders, the arguments and the function. Only the arguments get gradients.

IncgammaResidual

What incgamma_array saves for its pullback: the degrees and the arguments. Only the arguments get gradients.

IntkambeResidual

What intkambe_array saves for its pullback: the orders and the arguments. The pullback uses the adjacent-order recurrence and the endpoint integrand.

RadialJet

A radial function and its first two argument derivatives: a second-order jet in one complex variable, unlike the crate’s first-order jets numerics::Jet in several.

WignerDResidual

What wigner_d_array saves for its pullback: the labels and the Euler angles. The pullback applies the local chain rules.

Enums

Angular

Associated Legendre polynomial or one of the two vector-wave angular functions.

Bessel

Cylindrical Bessel solution, also used at half order for spherical functions.

Radial

Radial kind of multipole waves: regular or singular.

Constants

MAX_LABEL

The largest |n| of an integer special-function label (Kambe orders, Wigner labels).

MAX_ORDER 🔒

The largest order of the integer-order radial jets (spherical_radial, spherical_radial_sequence, cylindrical_radial) and of the order difference of cylindrical translations: translations couple degrees l1 + l2 up to 2 MAX_DEGREE, and cylindrical translations reach orders m1 - m2 of the same size. bessel() takes any finite order.

SERIES_RADIUS 🔒

The radius |z| below which regular radial functions use their power series instead of AMOS Bessel evaluations.

Functions

angular_array

Broadcast angular values and a complex-argument residual; labels stay fixed.

angular_value

Angular function at a cosine argument; real Legendre values also accept real degrees.

bessel

Bessel value or one of its first two complex-argument derivatives.

bessel_array

Evaluate elementwise Bessel functions, broadcasting either scalar input.

cylindrical_radial

Integer-order cylindrical J (regular) or outgoing H1 (singular), with its first two derivatives.

factorial_ratio_sqrt 🔒

sqrt((l - m)! / (l + m)!), the order factor of spherical-harmonic normalizations.

incgamma

Upper incomplete gamma function Gamma(n, z) = integral_z^infinity t^(n-1) e^-t dt.

incgamma_array

incgamma over arrays, each input one value or one value per element, with the residual of their argument gradient.

intkambe

The Kambe integral I_n(z, eta) = integral_eta^infinity t^n exp(-z^2 t^2/2 + 1/(2t^2)) dt.

intkambe_array

intkambe over arrays, each input one value or one value per element, with the residual of their z and eta gradients; the integer order has none.

log_factorial 🔒

ln n!: libm’s lgamma(n + 1), cached for 0 <= n <= MAX_ORDER. The factorials of wave labels recur in every normalization, lattice image and angular closed form, so the cache computes each one once.

lpmv_real

Associated Legendre function P_degree^order(x) of a real argument, as a real value.

pol_index

The polarization index of an integer label, which must be 0 or 1.

spherical_radial

Evaluate a spherical radial function and its first two derivatives: j_l for regular and h1_l for singular waves.

wigner3j

Wigner 3j symbol (j1 j2 j3; m1 m2 m3), zero outside the admissible labels.

wigner_d

Wigner D element D^l_(mk)(phi, theta, psi) = e^(-i m phi) d^l_(mk)(theta) e^(-i k psi) in the z-y-z convention, allowing complex Euler angles.

wigner_d_array

Broadcast wigner_d values with all three Euler angles differentiable: each input is either one value or one value per element.

wigner_small_d

Wigner small-d element d^l_(mk)(theta) at a real or complex angle, without a matrix. Orders with |m| > l or |k| > l give zero.