Module smatrix 

Planar scattering matrices of plane-wave modes and their analytic pullbacks.

Covers Redheffer composition, chiral Fresnel and Cartesian interfaces, propagation, multilayer stacks, internal illumination between stacks, periodic transfer matrices and Bloch bands, radiation of periodic multipole arrays, port transmittance and reflectance, and chirality-density forms.

Upstream: treams.SMatrices, treams.coeffs.fresnel and treams.chirality_density (see Upstream counterparts).

Sides and directions

• The negative side lies below the structure (z < 0 for a z normal); in add it holds the lower operand. The positive side lies above and holds the upper operand.
• Direction 0 is up, towards the positive side; direction 1 is down.
• Blocks index outgoing, then incident direction: [S00, S01, S10, S11].
• fresnel, interface() and layer_stack take their media in the order (negative side, positive side).
• tr() numbers its ports the other way: port 0 is the positive side, as in the material order (above, below) of upstream SMatrices.

Upstream counterparts

treams-rs	treams
add	SMatrices.add
periodic(), bands	SMatrices.periodic, SMatrices.bands_kz
from_array	SMatrices.from_array
illuminate(), illuminate_value	SMatrices.illuminate
tr(), tr_value	SMatrices.tr
fresnel	coeffs.fresnel
interface(), propagation	SMatrices.interface, SMatrices.propagation
layer_stack	SMatrices.stack of interfaces and propagations
chirality_density, oriented_chirality	chirality_density
Blocks	the four SMatrix blocks of one SMatrices

Modules

array 🔒

Plane-port radiation of periodic multipole arrays.

chirality 🔒

Chirality-density forms of plane-wave modes, averaged over an interval.

compose 🔒

Redheffer composition of two adjacent S-matrices.

illuminate 🔒

Illumination of a pair of adjacent stacks: the outgoing fields and the internal fields between them, with the pullback of both.

interface 🔒

Chiral Fresnel and Cartesian planar interfaces, and propagation of up/down reference planes.

layers 🔒

S-matrices of planar multilayer stacks: one S-matrix of 2-by-2 blocks per transverse wavevector, built from interface() and add, with analytic pullbacks.

periodic 🔒

Periodic transfer matrices of an S-matrix and the Bloch bands of its repetition.

saved 🔒

Shared fixed-layout numerical state helpers for planar residuals.

solve 🔒

The internal fields between two adjacent stacks: a certified Krylov or pivoted LU solve of (I - L1 U2) up = rhs, kept for the pullback.

tr 🔒

Transmittance and reflectance of plane-wave S-matrix columns between two ports.

Structs

AddGradient

Cotangents of the inputs of add, in the order of its arguments.

AddResidual

What add saves for its pullback: four of the eight input blocks, the internal fields and their factorization.

BandsGradient

Cotangents of the inputs of bands, in the order of its arguments.

BandsResidual

What bands saves for its pullback: the residuals of the transfer matrix and of its eigensystem, the period and the Bloch wavenumbers.

ChiralityDensityGradient

Complex full/normal wavenumber and real interval-endpoint cotangents.

ChiralityDensityResidual

What chirality_density saves for its pullback: the full and normal wavenumbers and the interval.

FresnelGradient

Cotangents of the inputs of fresnel, in the order of its arguments; each array lists the medium on the negative side (below), then the positive side (above).

FresnelResidual

What fresnel saves for its pullback: the wavenumbers, the normal wavenumbers and the impedances. The pullback differentiates the closed forms again instead of keeping a Jacobian.

FromArrayGradient

Cotangents of the inputs of from_array, in the order of its arguments.

FromArrayResidual

What from_array saves for its pullback: the response, the channel arrays and the scattered fields.

IlluminateGradient

Cotangents of the inputs of illuminate, in the order of its arguments.

IlluminateResidual

What illuminate saves for its pullback: copies of the blocks of both stacks, the incoming fields, the internal-field solve and the downgoing internal fields.

InterfaceGradient

Cotangents of the inputs of interface, in the order of its arguments; the media are listed negative side (below), then positive side (above).

InterfaceResidual

What interface() saves for its pullback: the media, the transverse wavevector, the axis, the inverse of the tangential-field matching matrix and the blocks.

LayerStackGradient

Multilayer parameter cotangents under the real Hermitian pairing.

LayerStackResidual

What layer_stack saves for its pullback: the solves of every transverse wavevector, each on its own, without a dense matrix over all of them.

OrientedChiralityGradient

Real transverse, complex normal and real interval-endpoint cotangents.

OrientedChiralityResidual

What oriented_chirality saves for its pullback: the real transverse components, the normal wavenumbers, the polarizations, the axis and the interval.

PeriodicResidual

What periodic() saves for its pullback: the upper rows of the transfer matrix, the reflection block S10 and the solve with S11.

PropagationGradient

Cotangents of the inputs of propagation, in the order of its arguments.

PropagationResidual

What propagation saves for its pullback: the wavevectors, the displacement and the diagonal phases.

StoredBlock 🔒

Owned square block that preserves its input memory order.

TrGradient

S-matrix, illumination, port wavenumber/impedance and transverse-wavevector cotangents.

TrPorts

The two plane-wave ports of tr and tr_value: port 0 on the positive side (above), port 1 on the negative side (below).

TrResidual

What tr saves for its pullback: copies of the transmission and reflection blocks of the illumination direction, the incident fields, the ports and the forward results.

Functions

add

Place upper above lower, eliminating their internal incident fields.

any_nonfinite 🔒

Whether any entry is not finite, scanning contiguous storage without early exit so the scan vectorizes.

bands

Bloch modes of a periodically repeated S matrix with positive repeat distance.

checked_dimension 🔒

The dimension of cotangent blocks, which must match the forward expected one.

chirality_density

Up, down and coherent cross coefficients, shape (3, modes), before polarization.

dimension 🔒

The common dimension n of four finite, nonempty n-by-n blocks.

fresnel

Planar interface from full and normal wavenumbers and impedances, each indexed by medium (negative side, then positive side) and then by polarization.

from_array

Compose an effective response with incident/emitted, up/down channel arrays.

identity_blocks 🔒

Scattering blocks of n unscattered modes: identity transmission, no reflection.

illuminate

Illuminate a pair of stacks. Returns outgoing up/down and internal up/down fields; each input and output matrix has one column per independent illumination.

illuminate_value

The fields of illuminate without the data its pullback needs. Inputs can be row- or column-major; only the operator and thin fields are owned.

interface

Interface from wavenumbers and impedances, indexed by medium (negative side, then positive side), and the real transverse wavevector q.

layer_stack

Stack layers independently for each transverse wavevector; the output is one S-matrix of four 2-by-2 blocks per wavevector.

oriented_chirality

Signed helicity up/down/cross forms, shape (3, modes), for any Cartesian normal.

periodic

Convert scattering blocks to the transfer matrix used for periodic bands.

propagation

Propagate by a Cartesian displacement, given upgoing wavevectors for every mode.

storage_order 🔒

The matrix in its memory order: the transpose of row-major storage, which then reads column by column, and whether it was transposed.

tr

Transmittance and reflectance of S-matrix columns between two plane-wave ports.

tr_value

The transmittance and reflectance of tr without the data its pullback needs. Matrix views are the transmission and reflection blocks for the illumination direction.

Type Aliases

Blocks

The four scattering blocks of one S-matrix.

Channels

The four multipole-by-plane-wave channel arrays of from_array, in the order incident up, incident down, emitted up, emitted down.