solprop.driver.tdse#

Own the optional TDSE runtime behind the provider-free response seam.

The provider’s whole-electron currents and shadow dipoles remain unscaled SI arrays. Source assembly applies the calibration and density separately. Native imports, persistent plans, resource admission and call accounting live here.

Two atomic models are bound (SEP 12, SEP 20): the single-active-electron (SAE) response plan, and the helium haCC response plan, either from one of the provider’s qualified presets or from a custom basis. An atomic window drives the atom over part of the lattice: the binding passes the retained samples multiplied by the window’s gate and pads the returned currents with zeros, so a TDSEResult always spans the full lattice.

Functions

`basis_from_preset`(target, preset)	Resolve a provider preset into an immutable, serializable SI basis.
`estimate_binding_memory`(descriptor, ...[, ...])	Estimate atomic storage without importing the optional provider.
`hacc_basis`(atom, basis, gauge, cut_energy, ...)	Convert provider haCC objects into a custom, unqualified `HaccBasis`.
`hacc_preset`(ions[, variant])	Resolve one of the provider's qualified helium haCC presets.
`pinned_revision`()	Return the provider source revision this solprop is pinned to.
`prepare_binding`(descriptor, execution, ...)	Prepare persistent, stably chunked atomic plans for one response lattice.

Classes

`DiagnosticSession`(basis, execution, *[, archive])	Prepare a haCC model alone for a standalone consistency check.
`HaccPreset`(basis, variant, step_margin, ...)	Hold a provider's qualified helium haCC preset as solprop records (SEP 20).

class solprop.driver.tdse.DiagnosticSession(basis, execution, *, archive=None)[source]#

Bases: object

Prepare a haCC model alone for a standalone consistency check.

Used by solprop.driver.tdse_consistency.check_consistency(), which needs one diagnostic row and no propagation plans. Close it when done.

Parameters:

basisHaccBasis: Validated preset or custom record.
executionTDSEExecution: Device, memory limit and the explicit call budget of the check.
archiveTDSEArchiveWriter or None, optional: Archive session receiving the diagnostic call, labelled diagnostic.

close()[source]#

Close the model; repeated calls are harmless.

diagnostic_currents(field, spacing)[source]#

Evaluate one charged diagnostic row on the prepared model.

Parameters:

fieldnumpy.ndarray: Finite float64 field in V/m, shape (1, n_samples).
spacingfloat: Protocol spacing in s.

Returns:

tuple of numpy.ndarray: j_tot and j_1 in C m/s per atom.

property ledger: AtomicCallLedger[source]#

Return the check’s attempted-call accounting.

Returns:

AtomicCallLedger: Diagnostic charges, including failures.

metadata()[source]#

Return the session’s model, build, ledger and failure records.

Returns:

mapping: JSON-compatible provenance.

class solprop.driver.tdse.HaccPreset(basis, variant, step_margin, max_atomic_step, accuracy, box_sensitivity, gauge_sensitivity, max_peak_intensity, wavelength, window, device_admissible, identity, source)[source]#

Bases: object

Hold a provider’s qualified helium haCC preset as solprop records (SEP 20).

Attributes:

basisHaccBasis: Frozen copy of the preset’s model and basis, with its provider identity.
variant{‘standard’, ‘fast’}: The provider’s numerics variant: 'standard' (cut 200 hartree, RK4 step at most 0.0088 au) or 'fast' (cut 125 hartree, step at most 0.02045 au, about 2.3 times fewer RK4 steps per call), each with its own identity and measured records.
step_marginfloat: The step ceiling over the largest stable RK4 step the provider measured at the preset’s cut on the qualifying field: 0.62 (standard) or 0.9 (fast).
max_atomic_stepfloat: Largest RK4 step in s, basis.max_step_au converted with solprop’s atomic unit of time; pass it as TDSEGasResponse.max_atomic_step.
accuracyfloat: Largest relative change of the closed total current, max_t |dJ| / max_t |J|, across the preset’s numerical ladders (lmax, finite-element order, cut, step) on the qualifying waveform, up to 8 fs after its centre. For the fast variant, the standard value plus the measured largest fast-to-standard change (1.5e-4 of the peak), a triangle-inequality bound.
box_sensitivityfloat: The same measure across the R0 ladder (80, 120 and 160 bohr).
gauge_sensitivityfloat: The same measure across the Rg ladder (12, 20 and 28 bohr).
max_peak_intensityfloat: Largest qualified peak intensity in W/m^2.
wavelengthfloat: Carrier wavelength of the qualifying drive in m.
windowfloat: Atomic-window duration the accuracy ladders drove, in s.
device_admissiblebool: Whether the provider’s device route admits the preset’s lattice.
identitystr: The provider’s preset identity, equal to basis.preset.
sourcestr: The provider’s evidence record.

Notes

The sensitivities are measured on one sampled configuration and waveform; they are not error bounds on the helium response or on a propagated spectrum.

accuracy: float#

basis: HaccBasis#

box_sensitivity: float#

calibration()[source]#

Return the research calibration record documenting the preset’s evidence.

Returns:

TDSECalibration: Research status, no uncertainty (the sensitivities are not certified uncertainties), the 62 nm to 1.6 um admission band, and limitations naming the window, the intensity bound, the shadow’s finite-tail qualification, the diagnostic-only bound and the measured sensitivities with their metric and waveform.

device_admissible: bool#

gauge_sensitivity: float#

identity: str#

max_atomic_step: float#

max_peak_intensity: float#

source: str#

step_margin: float#

variant: Literal['standard', 'fast']#

wavelength: float#

window: float#

solprop.driver.tdse.basis_from_preset(target, preset)[source]#

Resolve a provider preset into an immutable, serializable SI basis.

Parameters:

targetstr: Atomic target, currently helium only.
preset{‘production’, ‘high_accuracy’, ‘strong_field’}: Name of the pinned provider’s measured basis and spectral cut.

Returns:

TDSEBasis: Fully resolved radial, angular, potential and spectral parameters. The preset’s atomic step is deliberately separate from this basis.

Raises:

MaterialError: If the target or preset is unsupported.
BackendError: If the optional provider is missing or its native revision is stale.

solprop.driver.tdse.estimate_binding_memory(descriptor, execution, n_nodes, *, archive=None)[source]#

Estimate atomic storage without importing the optional provider.

Parameters:

descriptorTDSEDescriptor: Resolved basis, fixed time lattice and requested response products.
executionTDSEExecution: Stable maximum chunk size, determining the persistent plan shapes.
n_nodesint: Positive total number of radial rows.
archive{‘full’, ‘required’} or None, optional: The output selection of a raw archive, whose writer buffers are added and whose full selection widens the provider histories; None without one.

Returns:

mapping of str to int: Conservative atomic host and device data estimates in bytes. Optical host storage is excluded and must be added for a shared run budget. Vendor allocation overhead and setup workspaces are not hard bounded. A haCC model has no estimate before preparation; its measured ledgers are admitted after preparation.

Raises:

BackendError: If the total row count is invalid.

solprop.driver.tdse.hacc_basis(atom, basis, gauge, cut_energy, max_step_au, *, source)[source]#

Convert provider haCC objects into a custom, unqualified HaccBasis.

The “accept any provider model” path (SEP 20 section 5.1): the record’s identity is derived from its full definition, and it is warned and recorded as unqualified when a run prepares it. Build its calibration record yourself, with status="research", no uncertainty and the limitation that the basis is unqualified.

Parameters:

atompyroraptor.hacc.Helium: The atom and its ion count (1 or 2).
basispyroraptor.hacc.Basis: Radial axis in m, irECS and angular limit.
gaugepyroraptor.hacc.MixedGauge or pyroraptor.hacc.VelocityGauge: The gauge; the velocity gauge becomes gauge_radius=None.
cut_energyfloat: Spectral cut in J.
max_step_aufloat: RK4 step ceiling in atomic units of time.
sourcestr: Why this basis was chosen; recorded in its identity.

Returns:

HaccBasis: Custom record with preset=None.

Raises:

MaterialError: For argon, an ion count other than 1 or 2, or any field the record cannot represent.
BackendError: If the optional provider is missing or has no haCC surface.

solprop.driver.tdse.hacc_preset(ions, variant='standard')[source]#

Resolve one of the provider’s qualified helium haCC presets.

Parameters:

ions{1, 2}: 1 for haCC(1) (the He+ 1s channel), 2 for haCC(5) (He+ n <= 2).
variant{‘standard’, ‘fast’}, optional: The provider’s numerics variant (hacc.helium_preset(ions, variant)). 'fast' lowers the cut to 125 hartree and raises the RK4 step ceiling to 0.02045 au, with the same lattice, box, gauge and validity domain: about 2.3 times fewer RK4 steps per call, and a closed current within 1.5e-4 of the standard variant’s peak on the qualifying field. It has its own identity, so its own consistency cache entry.

Returns:

HaccPreset: SI records of the preset’s model, accuracy and validity domain. No model is prepared.

Raises:

MaterialError: If ions is not the integer 1 or 2, or variant is not 'standard' or 'fast'.
BackendError: If the optional provider is missing, stale or has no haCC surface, or its preset’s variant disagrees with the request.

Examples

>>> from solprop.driver.tdse import hacc_preset
>>> preset = hacc_preset(1, "fast")
>>> preset.basis.label, preset.basis.preset
('haCC(1) fast', 'hacc-helium-1-fast-v1-e38292e1b30729c1')

solprop.driver.tdse.pinned_revision()[source]#

Return the provider source revision this solprop is pinned to.

Returns:

str: Full Git revision; an installed build must report a prefix of it.

solprop.driver.tdse.prepare_binding(descriptor, execution, n_nodes, *, host_memory_bytes=0, defer_plans=False, archive=None)[source]#

Prepare persistent, stably chunked atomic plans for one response lattice.

Parameters:

descriptorTDSEDescriptor: Resolved scientific description and fixed fine time lattice in SI.
executionTDSEExecution: Device, memory limit, stable maximum row count and atomic-call limit.
n_nodesint: Positive total number of radial rows; fixed for the binding’s lifetime.
host_memory_bytesint, optional: Nonnegative optical host-storage estimate in bytes. Admission combines it with atomic host/device storage under execution.memory_limit. It is not repeated in the binding’s own memory ledger.
defer_plansbool, optional: For a haCC model, prepare and admit the model only, and build the propagation plans when build_plans() is called. The run uses this so the consistency check’s temporary one-row plan is built and closed before the propagation plans exist, and peak memory is the larger of the two, not their sum. Ignored for SAE, whose plans are always built here.
archiveTDSEArchiveWriter or None, optional: An open archive session (SEP 20 section 5.8). Every provider evaluation is written to it, input first and raw result before validation; a full archive builds the plans with the provider’s full record. The caller owns and closes it. Its buffers are admitted with the binding’s memory.

Returns:

TDSEBinding: Owning runtime adapter. Close it when the propagation ends. Evaluation requires a successful reservation of all logical calls in the trial.

Raises:

BackendError: If the provider, device, scientific identity or prepared state is invalid.
MemoryBudgetError: If estimated or measured persistent data exceed the declared byte limit.