solprop.backends.tdse_source#

Assemble the TDSE response’s macroscopic source at one evaluation (SEP 49).

The host source both backends call: from the lab-frame modal field to the nodal fields the atomic binding takes (node_fields()), from the binding’s unscaled microscopic histories to the macroscopic polarisation, current and edge arrays (atomic_sources(), atomic_edge_source()), and from those to the projected spectral source with its diagnostics (project_atomic_sources()). Each backend then applies the spectral collar, its in-stage absorber term and, in the interaction formulation, its inverse propagator, as for every source. It imports nothing from either backend.

The gated, edge-free source (SEP 26) multiplies the remainder current S by its gate g before the transform and subtracts the edge term DFT[g' S] / (i omega) on the active bins, so that the current is held after the window instead of switched off.

The TDSE route is one scalar mode on a field grid (PropagationProblem._check_tdse), so every transform here is the real-to-complex one and the polarisation axis has length one.

Module Attributes

FFT_ERROR_CONSTANT

Constant c_F of the forward FFT's normwise relative bound c_F eps log2 N.

Functions

`atomic_edge_source`(result, problem, bundle)	Form a gated source's edge array `g' S`, scaled exactly as its current.
`atomic_sources`(fields, result, problem, bundle)	Subtract discrete shadows and apply the declared density and scales once.
`node_fields`(problem, lab, bundle)	Synthesise the real field at every radial node, as the atomic binding takes it.
`project_atomic_sources`(polarisation, ...[, edge])	Project both sources and reuse atomic rows for an embedded radial indicator.
`source_record`(problem)	Record a TDSE run's source filter and, for the gated one, its certificate.

solprop.backends.tdse_source.FFT_ERROR_CONSTANT = 8.0#

Constant c_F of the forward FFT’s normwise relative bound c_F eps log2 N.

Higham (2002), Theorem 24.2: a radix-2 Cooley-Tukey transform with twiddles accurate to mu has ||y - fl(y)|| / ||y|| <= log2(N) eta / (1 - log2(N) eta), eta = mu + gamma_4 (sqrt 2 + mu), about 3.4 eps per level with correctly rounded twiddles. A radix-3 or radix-5 butterfly does more operations per level, but spans log2 3 or log2 5 levels of log2 N; 8 covers the 2-, 3- and 5-smooth sizes solprop’s lattices use (SEP 26 section 4.5). The SEP 26 T3 test measures the constant at a power-of-two and at a 2^a 3^b 5^c size; any other size is flagged in the diagnostic as unqualified. doi:10.1137/1.9780898718027

solprop.backends.tdse_source.atomic_edge_source(result, problem, bundle)[source]#

Form a gated source’s edge array g' S, scaled exactly as its current.

S = J - j_1 is the same unscaled remainder atomic_sources() gates (the gated filter admits tdse_native only), g' the analytic derivative of the same gate (SEP 26 section 4.2), and density and remainder_scale enter once, as for the current. Nothing here is differentiated numerically.

Parameters:

resultTDSEResult: Owning microscopic SI histories, already matched to this configuration.
problemPropagationProblem: Compiled optical and atomic scientific specification.
bundleStageScalars: Density and other scalars at this evaluation’s absolute position.

Returns:

numpy.ndarray or None: rho s g'(t) S(t) in A/(m² s), shape (n_nodes, 1, n_to), for a gated (native) source; None for a cubic replacement, which has no gate.

Raises:

BackendError: If the descriptor is absent, the result is not this configuration’s, or the array is not finite.

solprop.backends.tdse_source.atomic_sources(fields, result, problem, bundle)[source]#

Subtract discrete shadows and apply the declared density and scales once.

Parameters:

fieldsnumpy.ndarray: Chronological real physical fields in V/m, shape (n_nodes, n_to).
resultTDSEResult: Owning microscopic SI histories for these exact inputs.
problemPropagationProblem: Compiled optical and atomic scientific specification.
bundleStageScalars: Density and other scalars at this evaluation’s absolute position.

Returns:

tuple of numpy.ndarray: Polarisation in C/m² and current in A/m², each with a scalar component axis. These new arrays never alias or mutate the provider’s histories.

Raises:

BackendError: If an identity, shape or required observable does not match the model.

solprop.backends.tdse_source.node_fields(problem, lab, bundle)[source]#

Synthesise the real field at every radial node, as the atomic binding takes it.

Step 1 of an evaluation: the lab-frame modal spectrum, its input noise already added, is placed on the fine grid’s bins with no scale (the pad scale is inside transform.synthesis), transformed to time and synthesised on the nodes with the taper scale at the evaluation’s position (kernel-contract.md sections 4 and 5).

Parameters:

problemPropagationProblem: A TDSE problem: one scalar mode on a field grid.
labnumpy.ndarray: Lab-frame modal spectrum in the square root of watts, shape (n_modes, 1, n_omega).
bundleStageScalars: Scalars at the evaluation’s position; its taper_scale is read.

Returns:

numpy.ndarray: C-contiguous float64 fields in V/m, shape (n_nodes, n_to).

Raises:

BackendError: If the spectrum has more than one polarisation.

solprop.backends.tdse_source.project_atomic_sources(polarisation, current, result, problem, bundle, prefactor, *, edge=None)[source]#

Project both sources and reuse atomic rows for an embedded radial indicator.

For a gated (native) source the current’s spectrum is the edge-free X - E / (i omega) on the active bins (SEP 26 section 4.4), X and E the raw transforms of the projected gated current and edge array, before the current factor; 1/(i omega) is never formed at the zero or inactive bins, where the current factor is zero anyway.

Parameters:

polarisationnumpy.ndarray: Already calibrated macroscopic polarisation in C/m², shape (n_nodes, 1, n_to).
currentnumpy.ndarray: Already scaled macroscopic remainder current in A/m², same shape.
resultTDSEResult: Unscaled microscopic operands used to derive an absolute cancellation floor.
problemPropagationProblem: Resolved modal maps, crop, spectral collar and independent current numerator.
bundleStageScalars: Stage position in m, density in m⁻³ and modal taper scale.
prefactornumpy.ndarray: Stage polarisation factor, including the crop scale and effective index, shape (n_modes, 1, n_omega).
edgenumpy.ndarray or None, optional: atomic_edge_source()’s g' S, same shape as current. Required for a gated (native) source and refused for an ungated one.

Returns:

sourcenumpy.ndarray: Complete spectral derivative before the spectral collar and interaction propagator, shape (n_modes, 1, n_omega). The caller applies these once.
diagnosticsdict: JSON-compatible complete-source and remainder-source norms after the spectral collar, in the same raw FFT modal derivative units. Each reports the embedded discrepancy, an absolute floating-point floor, and no relative score when the fine source is floor dominated. available=False means there is no distinct embedded map. This same-row indicator is not the independent 17-versus-33-node qualification screen. A gated source adds the edge entry of SEP 26 section 5, on the fine projection.

Raises:

BackendError: If a required descriptor, map or source shape is absent or nonfinite.

solprop.backends.tdse_source.source_record(problem)[source]#

Record a TDSE run’s source filter and, for the gated one, its certificate.

The steady-current certificate (SEP 26 section 4.4) is refused above its limit at translation. It is run metadata, never part of the descriptor or any identity; both backends record it as tdse_source.

Parameters:

problemPropagationProblem: A TDSE problem.

Returns:

dict: gated, and for a gated source the certificate, its limit and the taper breakpoints in s.