solprop.backends.numpy_ref.passes.transforms#

The transform passes of a stage: between the modal spectrum and the node fields.

Passes 2, 3, 5 and 6 of docs/dev/architecture.md section 8, each one batched operation over every modal column: to_time() pads the coarse spectrum onto the fine grid and transforms it to time, synthesise() forms the field at a chunk of quadrature nodes (one GEMM over the mode axis), project() takes a chunk’s polarisation back onto the modes (one GEMM, weights folded in), and to_frequency() transforms the modal polarisation and crops it to the coarse grid. The pad and crop scales are already inside the contract’s matrices and prefactor, so none of these applies a scale of its own (solprop.backends.numpy_ref.passes).

Functions

project(polarisation_t, projection, taper, n_pol)

Project a chunk's polarisation back onto the modes.

synthesise(modal_t, synthesis, taper, n_pol)

Synthesise the physical field on a chunk of quadrature nodes.

to_frequency(polarisation_t, crop_index, *, kind)

Transform the modal polarisation to frequency and crop to the coarse grid.

to_time(spectrum, crop_index, n_to, *, kind)

Pad onto the fine grid and transform every modal column to time.

solprop.backends.numpy_ref.passes.transforms.project(polarisation_t, projection, taper, n_pol)[source]#

Project a chunk’s polarisation back onto the modes.

Pass 5 of architecture.md section 8: P[m, t] = sum_{i, p} W[m, i n_pol + p] P[i, p, t] / tau(z), one GEMM with the quadrature weights already folded into projection. The caller accumulates over chunks, which is what makes the space-domain buffers bounded by the chunk rather than by the node count (architecture.md section 13).

Parameters:
polarisation_tnumpy.ndarray

The polarisation at the chunk’s nodes, shape (n_nodes_chunk, n_pol_node, n_to), in C/m^2.

projectionnumpy.ndarray

The chunk’s columns of the projection matrix, float64, shape (n_modes, n_nodes_chunk * n_pol), weights folded in.

taperfloat

The rescaling at this position, transform.taper_scale(z), or 1.0. The projection is divided by it, as the synthesis is multiplied by it.

n_polint

Transverse components the transform resolves at each node, 1 or 2.

Returns:
numpy.ndarray

The modal polarisation on the fine time grid, shape (n_modes, n_pol, n_to).

Examples

>>> import numpy as np
>>> from solprop.backends.numpy_ref.passes.transforms import project
>>> nodes = np.ones((2, 1, 4))
>>> project(nodes, np.array([[1.0, 3.0]]), 1.0, 1).shape
(1, 1, 4)
solprop.backends.numpy_ref.passes.transforms.synthesise(modal_t, synthesis, taper, n_pol)[source]#

Synthesise the physical field on a chunk of quadrature nodes.

Pass 3 of architecture.md section 8: E[i, p, t] = tau(z) sum_m S[i n_pol + p, m] a[m, t], one GEMM over the mode axis. synthesis is the chunk’s rows of transform.synthesis, which already carry the oversampling pad scale, and taper is transform.taper_scale(z), the exact rescaling a scale-invariant waveguide needs (solprop.modes.quadrature.ModeMatrices.rescaled()).

The transverse components are carried by the rows of synthesis or by the state’s polarisation axis and never by both (kernel-contract.md section 5), so the returned polarisation axis has n_pol times the state’s length and one of the two factors is one.

Parameters:
modal_tnumpy.ndarray

The modal field on the fine time grid from to_time(), shape (n_modes, n_pol, n_to), in the square root of watts.

synthesisnumpy.ndarray

The chunk’s rows of the synthesis matrix, float64, shape (n_nodes_chunk * n_pol, n_modes), in V/(m sqrt(W)), already carrying the pad scale.

taperfloat

The rescaling at this position, transform.taper_scale(z), or 1.0 for a waveguide whose cross-section does not move.

n_polint

Transverse components the transform resolves at each node, 1 or 2.

Returns:
numpy.ndarray

The field at the chunk’s nodes, shape (n_nodes_chunk, n_pol_node, n_to), in V/m: real on a field grid, complex on an envelope grid.

Examples

>>> import numpy as np
>>> from solprop.backends.numpy_ref.passes.transforms import synthesise
>>> modal = np.ones((1, 1, 4))
>>> synthesise(modal, np.array([[2.0], [3.0]]), 1.0, 1).shape
(2, 1, 4)
solprop.backends.numpy_ref.passes.transforms.to_frequency(polarisation_t, crop_index, *, kind)[source]#

Transform the modal polarisation to frequency and crop to the coarse grid.

Pass 6 of architecture.md section 8: one batched forward transform of all n_modes * n_pol columns. The crop takes the coarse bins out of the fine spectrum at crop_index with no scale factor: the crop scale n_t/n_to is inside responses.prefactor (kernel-contract.md section 5), which stage_output() applies next.

Parameters:
polarisation_tnumpy.ndarray

The modal polarisation on the fine time grid, accumulated over the chunks by project(), shape (n_modes, n_pol, n_to), in C/m^2.

crop_indexnumpy.ndarray

Where each coarse bin sits in the fine spectrum, numpy.intp, shape (n_omega,).

kind{‘field’, ‘envelope’}

Spectral layout.

Returns:
numpy.ndarray

The modal polarisation on the coarse grid, complex128, shape (n_modes, n_pol, n_omega).

Examples

>>> import numpy as np
>>> from solprop.backends.numpy_ref.passes.transforms import to_frequency
>>> samples = np.ones((1, 1, 8))
>>> index = np.arange(3, dtype=np.intp)
>>> to_frequency(samples, index, kind="field").real
array([[[8., 0., 0.]]])
solprop.backends.numpy_ref.passes.transforms.to_time(spectrum, crop_index, n_to, *, kind)[source]#

Pad onto the fine grid and transform every modal column to time.

Pass 2 of architecture.md section 8: one batched inverse transform of all n_modes * n_pol columns, whatever the quadrature does next. The coarse bins are scattered into the fine spectrum at crop_index with no scale factor: the pad scale n_to/n_t is inside transform.synthesis (kernel-contract.md section 4), so that every response sees the field in volts per metre whatever its degree in the field.

The mode and polarisation axes are folded together for the transform, so the columns a scalar problem transforms are exactly the ones it transformed before the polarisation axis existed.

Parameters:
spectrumnumpy.ndarray

Coarse modal spectrum, complex128, shape (n_modes, n_pol, n_omega), in the square root of watts.

crop_indexnumpy.ndarray

Where each coarse bin sits in the fine spectrum, numpy.intp, shape (n_omega,).

n_toint

Number of fine time samples, positive.

kind{‘field’, ‘envelope’}

Spectral layout, which selects the complex-to-real or complex-to-complex transform.

Returns:
numpy.ndarray

The modal field on the fine time grid, shape (n_modes, n_pol, n_to), in the square root of watts: real on a field grid, complex on an envelope grid.

Examples

>>> import numpy as np
>>> from solprop.backends.numpy_ref.passes.transforms import to_time
>>> spectrum = np.array([[[1.0 + 0.0j, 0.0 + 0.0j, 0.0 + 0.0j]]])
>>> index = np.arange(3, dtype=np.intp)
>>> to_time(spectrum, index, 8, kind="field")
array([[[0.125, 0.125, 0.125, 0.125, 0.125, 0.125, 0.125, 0.125]]])