solprop.backends.numpy_ref.passes.responses#

The response passes: the polarisation of the field at a chunk of nodes.

Pass 4 of docs/dev/architecture.md section 8. nonlinear_sources() walks responses.response_order stage by stage and returns NonlinearSources, the collared local polarisation and, separately, the ungated plasma current, which a stage assembles in frequency (held_plasma_spectrum()). Its stages are the named functions here and in plasma: kerr_polarisation() (the instantaneous cubic), dispersive_kerr_polarisation() (SEP 6), raman_polarisation() (the delayed term on the doubled grid, scalar or vector) with the kernel spectra it convolves with (raman_spectrum(), mixture_raman_spectrum(), tensor_raman_spectrum()). nonlinear_polarisation() is the time-domain total, the physical-polarisation oracle that tests hold the responses to.

Functions

dispersive_kerr_polarisation(field_t, terms, ...)

Evaluate SEP 6's dispersive electronic polarisation at every node of a chunk.

kerr_polarisation(field_t, kerr, density[, ...])

Evaluate the instantaneous Kerr polarisation at every node of a chunk.

mixture_raman_spectrum(components, rates, ...)

Form one amplitude-weighted kernel spectrum for all Raman components.

nonlinear_polarisation(field_t, responses, ...)

Return the total physical polarisation of a chunk of nodes, windowed.

nonlinear_sources(field_t, responses, ...[, ...])

Separate the collared local polarisation and the ungated plasma current.

raman_polarisation(field_t, spectrum, *, ...)

Evaluate the delayed Raman polarisation at every node of a chunk.

raman_spectrum(undamped, rates, fraction, dt)

Damp each undamped Raman row at its own rate, sum, scale and transform.

tensor_raman_spectrum(components, rates, ...)

Form effective trace and traceless spectra from independently damped terms.

Classes

NonlinearSources(polarisation, current)

Carry the separate local polarisation and field-plasma current.

class solprop.backends.numpy_ref.passes.responses.NonlinearSources(polarisation, current)[source]#

Bases: object

Carry the separate local polarisation and field-plasma current.

Attributes:
polarisationnumpy.ndarray

Collared Kerr and Raman polarisation, including the separately collared dispersive Kerr, in C/m^2, shape (n_nodes_chunk, n_pol, n_to).

currentnumpy.ndarray or None

Total ungated plasma current density in A/m^2 with the same shape; None when no field plasma is compiled. Every channel and both currents enter once.

current: Float[ndarray, 'n_nodes_chunk n_pol n_to'] | None#
polarisation: Num[ndarray, 'n_nodes_chunk n_pol n_to']#
solprop.backends.numpy_ref.passes.responses.dispersive_kerr_polarisation(field_t, terms, densities, *, kind, carrier=None, window=None)[source]#

Evaluate SEP 6’s dispersive electronic polarisation at every node of a chunk.

The dispersive_kerr stage of the fused pass: per channel, the transforms of the field the evaluator’s forms need, the products of the filtered fields in the leaf’s sector, the temporal collar on each product, the output multipliers and one inverse transform, by solprop.nonlinear.responses.dispersive_cubic(), which is the arithmetic of the reference evaluate() on the leaf’s sampled multipliers. The polynomial’s channels add, P = sum_s c_s rho_s cubic_s(E); the symmetric evaluator’s mixture takes one filter built from its species’ densities at this stage, P = F G_mix[w (G_mix E)^3] (evaluations()). It reads the bare field and touches no other response’s source.

Parameters:
field_tnumpy.ndarray

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

termssolprop.translate.responses.DispersiveKerrTerms

The compiled leaf.

densitiessequence of float

Each channel’s number density at this position, m^-3, in the leaf’s order.

kind{‘field’, ‘envelope’}

The spectral layout.

carriernumpy.ndarray or None, optional

exp(2 i omega_0 t) on the fine time grid, shape (n_to,); required when the leaf’s carrier is set.

windownumpy.ndarray or None, optional

The temporal collar, shape (n_to,), applied to each product before the output multipliers, G[w (G E)^3]; None is a unit collar.

Returns:
numpy.ndarray

The polarisation in C/m^2, shape (n_nodes_chunk, n_pol, n_to), real on a field grid and complex on an envelope grid, the collar already inside it.

Raises:
BackendError

If the densities do not match the channels, or the carrier is missing.

solprop.backends.numpy_ref.passes.responses.kerr_polarisation(field_t, kerr, density, carrier=None)[source]#

Evaluate the instantaneous Kerr polarisation at every node of a chunk.

The kerr stage of the fused pass. The formulas are the two cubic forms of solprop.translate.responses.KerrCoefficients, which were read off solprop.nonlinear.responses.KerrResponse.evaluate() rather than re-derived:

real

P_p = c rho (sum_q E_q^2) E_p – the full cubic of a real field, which already carries the third harmonic and the counter-rotating terms.

analytic

P_p = c rho [s (sum_q |a_q|^2) a_p + k (sum_q a_q^2) conj(a_p)], plus c rho m exp(2 i omega_0 t) (sum_q a_q^2) a_p when the envelope grid radiates the harmonic, with s, k and m the self, conjugate and harmonic factors. For one component the first collapses to (3/4)|a|^2 a.

The sums run over the polarisation axis of one node, which is what the vector-isotropic coupling means: two components of the field at one point of the cross-section, never two different points.

Parameters:
field_tnumpy.ndarray

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

kerrsolprop.translate.responses.KerrCoefficients

The compiled coefficients, whose coefficient is eps0 chi3 per unit of the density path.

densityfloat

The density path at this position, responses.density(z): a number density in m^-3 for a gas, 1.0 for a medium whose chi3 is already absolute. Non-negative.

carriernumpy.ndarray or None, optional

exp(2 i omega_0 t) on the fine time grid, shape (n_to,). Required when kerr.harmonic_factor is not zero; the harmonic term is added whenever a carrier is given, and None selects the fundamental cubic alone.

Returns:
numpy.ndarray

The polarisation in C/m^2, shape (n_nodes_chunk, n_pol, n_to), real on a field grid and complex on an envelope grid.

Examples

>>> import numpy as np
>>> from solprop.backends.numpy_ref.passes.responses import kerr_polarisation
>>> from solprop.translate.responses import KerrCoefficients
>>> coefficients = KerrCoefficients(1.0, "analytic", 0.5, 0.25, 0.0, False, False)
>>> field = np.array([[[2.0 + 0.0j]]])
>>> polarisation = kerr_polarisation(field, coefficients, 1.0)
>>> bool(np.allclose(polarisation, 0.75 * abs(2.0) ** 2 * 2.0))
True
solprop.backends.numpy_ref.passes.responses.mixture_raman_spectrum(components, rates, densities, dt)[source]#

Form one amplitude-weighted kernel spectrum for all Raman components.

Parameters:
componentstuple of RamanCoefficients

Raman-active populations in mixture order.

ratestuple of float

Decay rates in s^-1, flattened by component then kernel row.

densitiestuple of float

Component amplitude densities in m^-3.

dtfloat

Fine-grid sample spacing in s.

Returns:
numpy.ndarray

One damped kernel spectrum including densities and dt.

Raises:
BackendError

If the amplitude or decay-rate counts disagree with the components.

solprop.backends.numpy_ref.passes.responses.nonlinear_polarisation(field_t, responses, t_window_fine, *, kind, density, preionisation, dt, carrier=None, raman_spectrum=None, scalars=None)[source]#

Return the total physical polarisation of a chunk of nodes, windowed.

nonlinear_sources()’ collared local polarisation plus the plasma current integrated along t by the problem’s running-integral rule and collared: the time-domain form the oracles of solprop.nonlinear.responses.PlasmaResponse.evaluate() compare against. A stage never takes it: the stage assembles the current in frequency instead (held_plasma_spectrum(), SEP 27).

Parameters:
field_tnumpy.ndarray

The field at the chunk’s nodes from synthesise(), shape (n_nodes_chunk, n_pol, n_to), in V/m.

responsessolprop.translate.responses.CompiledResponses

Section 5 of the kernel contract: the order, the coefficients and the tables.

t_window_finenumpy.ndarray

The temporal collar profile in [0, 1], float64, shape (n_to,).

kind{‘field’, ‘envelope’}

The spectral layout, which the Raman drive depends on.

densityfloat

The density path at this position, responses.density(z), non-negative.

preionisationfloat

The pre-ionised fraction at this position, in [0, 1]. Ignored when no plasma is compiled.

dtfloat

Sample spacing of the fine time grid, s, positive.

carriernumpy.ndarray or None, optional

exp(2 i omega_0 t) on the fine time grid, for an envelope-grid harmonic term.

raman_spectrumnumpy.ndarray or None, optional

The damped Raman kernel spectrum at this position from raman_spectrum(), shape (n_to + 1,). Required when the order names raman_drive; the caller forms it once per stage rather than once per chunk, because it does not depend on the nodes.

scalarsStageScalars or None, optional

Labelled component densities and preionisations at the stage. Required for multiple plasma channels; None retains the standalone single-response call.

Returns:
numpy.ndarray

The total polarisation in C/m^2, shape (n_nodes_chunk, n_pol, n_to), real on a field grid and complex on an envelope grid.

Examples

>>> import numpy as np
>>> from solprop.backends.numpy_ref.passes.responses import nonlinear_polarisation
>>> from solprop.grid import FieldGrid
>>> from solprop.nonlinear.gnlse import SpecifiedMode
>>> from solprop.nonlinear.responses import KerrResponse
>>> from solprop.profiles import Constant
>>> from solprop.translate.responses import compile_responses
>>> grid = FieldGrid.from_limits(1.0, 800e-9, (400e-9, 2e-6), 400e-15)
>>> mode = SpecifiedMode.from_taylor(
...     [0.0], omega_ref=grid.omega0, aeff=1e-10
... )
>>> compiled = compile_responses(
...     [KerrResponse(chi3=1.0)],
...     grid,
...     mode,
...     density=Constant(1.0),
...     z_max=1.0,
...     prefactor_index=1.0,
... )
>>> field = np.full((1, 1, 4), 2.0)
>>> out = nonlinear_polarisation(
...     field, compiled, np.ones(4), kind="field", density=1.0, preionisation=0.0,
...     dt=grid.dt_fine,
... )
>>> bool(np.allclose(out, compiled.kerr_coefficients.coefficient * 8.0))
True
solprop.backends.numpy_ref.passes.responses.nonlinear_sources(field_t, responses, t_window_fine, *, kind, density, preionisation, dt, carrier=None, raman_spectrum=None, scalars=None)[source]#

Separate the collared local polarisation and the ungated plasma current.

Pass 4 of architecture.md section 8: the traversal responses.response_order names, term by term, accumulating P(t) and applying the temporal collar at the end – but for SEP 6’s dispersive response, whose collar acts on its products before its output multipliers (dispersive_kerr_polarisation()) and which is added after. Each stage is one of the named functions of this module, so the order the translation layer compiled is the order that runs, and a term this backend cannot execute is refused at construction rather than dropped here.

Parameters:
field_tnumpy.ndarray

The field at the chunk’s nodes from synthesise(), shape (n_nodes_chunk, n_pol, n_to), in V/m.

responsessolprop.translate.responses.CompiledResponses

Section 5 of the kernel contract: the order, the coefficients and the tables.

t_window_finenumpy.ndarray

The temporal collar profile in [0, 1], float64, shape (n_to,).

kind{‘field’, ‘envelope’}

The spectral layout, which the Raman drive depends on.

densityfloat

The density path at this position, responses.density(z), non-negative.

preionisationfloat

The pre-ionised fraction at this position, in [0, 1]. Ignored when no plasma is compiled.

dtfloat

Sample spacing of the fine time grid, s, positive.

carriernumpy.ndarray or None, optional

exp(2 i omega_0 t) on the fine time grid, for an envelope-grid harmonic term.

raman_spectrumnumpy.ndarray or None, optional

The damped Raman kernel spectrum at this position from raman_spectrum(), shape (n_to + 1,). Required when the order names raman_drive; the caller forms it once per stage rather than once per chunk, because it does not depend on the nodes.

scalarsStageScalars or None, optional

Labelled component densities and preionisations at the stage. Required for multiple plasma channels; None retains the standalone single-response call.

Returns:
NonlinearSources

The collared non-plasma polarisation and total ungated current density.

solprop.backends.numpy_ref.passes.responses.raman_polarisation(field_t, spectrum, *, kind, thg, density)[source]#

Evaluate the delayed Raman polarisation at every node of a chunk.

The scalar reduction preserves the formula of solprop.nonlinear.raman.RamanResponse.evaluate() in its original order of operations:

\[P(t) = \varepsilon_0\,\rho\,E(t) \int h(t - t')\,D(t')\,\mathrm{d}t' ,\]

with D the real drive solprop.nonlinear.raman.raman_drive() chooses for the grid – E^2 on a field grid that keeps the harmonic, |E_a|^2/2 on one that does not, |A|^2/2 on an envelope grid.

The convolution runs on a doubled, zero-padded grid, because a transform product is a circular convolution and a rotational coherence outlives the window by orders of magnitude: hydrogen’s lives about 2.9 ns at one bar against a window of tens of picoseconds, so the wrapped tail would be almost the whole response. The drive and the kernel occupy the first half of an array of twice the length, which makes the product the linear convolution exactly (docs/guide/media/raman-numerics.md, “The doubled grid”).

For two Cartesian components, convolve the trace, difference and twice the off-diagonal entry of the real quadratic tensor, then apply the resulting symmetric matrix to the field. Isotropic-only declarations need just the trace history. Each history is real on both grids and uses one real transform pair. numpy.fft preserves the scalar oracle’s transform arithmetic.

Parameters:
field_tnumpy.ndarray

Field at the chunk’s nodes, shape (n_nodes_chunk, n_pol, n_to), in V/m: real on a field grid, complex on an envelope grid. One or two physical Cartesian components.

spectrumnumpy.ndarray

Damped complex128 kernels with dt included. Scalar fields use shape (n_to + 1,) from raman_spectrum(); vector fields use shape (n_raman_kernels, n_to + 1) from tensor_raman_spectrum(), with one trace kernel or the trace/traceless pair.

kind{‘field’, ‘envelope’}

The spectral layout the samples belong to.

thgbool

Whether a field grid’s drive keeps the 2 omega beat, and so radiates a third harmonic through the later multiplication by the field. Ignored on an envelope grid, which cannot carry it in a quadratic drive.

densityfloat

The density path at this position, responses.density(z), in m^-3 for a gas and 1.0 for a medium whose kernel is already absolute. Non-negative.

Returns:
numpy.ndarray

Raman polarisation in C/m^2, shape (n_nodes_chunk, n_pol, n_to), real on a field grid and complex on an envelope grid.

Raises:
BackendError

If the component count or effective kernel shape is incompatible with the doubled temporal grid.

Examples

>>> import numpy as np
>>> from solprop.backends.numpy_ref.passes.responses import raman_polarisation
>>> field = np.ones((1, 1, 4))
>>> flat = np.zeros(5, dtype=complex)
>>> polarisation = raman_polarisation(
...     field, flat, kind="field", thg=True, density=1.0
... )
>>> bool(np.all(polarisation == 0.0))
True
solprop.backends.numpy_ref.passes.responses.raman_spectrum(undamped, rates, fraction, dt)[source]#

Damp each undamped Raman row at its own rate, sum, scale and transform.

The half of the kernel that moves along z. raman_kernel_undamped holds one causal, tapered row per independently damped term and raman_decay_rates one scalar path per row (kernel-contract.md section 5); this forms f_R sum_k u_k(t) exp(-gamma_k t) on the doubled grid and hands it to solprop.translate.raman.kernel_spectrum(), which folds in the sample spacing the discrete sum needs to become an integral. There is one statement of that normalisation and this is not it.

Damping each term separately is the whole reason the contract carries rows rather than one array: a molecular gas’s rotational and vibrational coherences decay 3.5 times (H2) to 17 times (N2) apart at one bar, so damping their sum once would be wrong for every such gas (docs/guide/media/raman-numerics.md).

The terms are summed in the order of the rows and the fraction multiplies the sum, which is the arithmetic of solprop.translate.raman.sample_kernel() operation for operation, so the two spectra agree to the last bit. The padding half of each row is zero, so damping it costs nothing and changes nothing.

Parameters:
undampednumpy.ndarray

responses.raman_kernel_undamped, float64, shape (n_terms, 2 n_to), in m^5 V^-2 s^-1.

ratesarray_like

The decay rate of each term at this position, s^-1, non-negative, one per row: [table(z) for table in responses.raman_decay_rates].

fractionfloat

responses.raman_fraction, in (0, 1]; 1 for an absolute molecular response.

dtfloat

Sample spacing of the fine time grid, s, positive.

Returns:
numpy.ndarray

The damped kernel spectrum with the dt scaling folded in, complex128, shape (n_to + 1,), in the internal convention.

Raises:
BackendError

If there is not one rate per row.

Examples

>>> import numpy as np
>>> from solprop.backends.numpy_ref.passes.responses import raman_spectrum
>>> rows = np.zeros((1, 8))
>>> rows[0, 1] = 1.0
>>> spectrum = raman_spectrum(rows, [0.0], 1.0, 2.0)
>>> spectrum.shape, bool(np.isclose(spectrum[0], 2.0))
((5,), True)
solprop.backends.numpy_ref.passes.responses.tensor_raman_spectrum(components, rates, densities, dt)[source]#

Form effective trace and traceless spectra from independently damped terms.

Parameters:
componentstuple of RamanCoefficients

Tensor-capable components in mixture order, with per-row numeric weights.

ratestuple of float

Decay rates in s^-1, flattened by component then kernel row.

densitiestuple of float

Amplitude densities in m^-3. Supply (1.0,) when a single component’s density is multiplied outside the convolution.

dtfloat

Fine-grid sample spacing in s.

Returns:
numpy.ndarray

Shape (n_raman_kernels, n_to + 1) with dt included. One trace kernel for isotropic-only declarations; otherwise trace and traceless rows.

Raises:
BackendError

If counts disagree or any term lacks a vector contraction.