solprop.nonlinear.tdse#

Declare the immutable, provider-independent helium TDSE response specification.

All physical quantities use SI. The optional atomic package is imported only by its runtime adapter, never by these records. See SEP 12 for the distinct linear, cubic and ionisation calibrations and the restricted first implementation, and SEP 20 for the haCC two-electron model (HaccBasis), the atomic time window (TDSEAtomicWindow) and the weak-field consistency policy (TDSEConsistency).

Module Attributes

`TDSEKerrModel`	The three explicit cubic retention or replacement policies of SEP 12.
`TDSEModel`	The atomic model family: single active electron, or two-electron haCC (SEP 20).

Classes

`HaccBasis`(ions, neutral_square, ...[, preset])	Describe a helium haCC model and basis, a provider preset or a custom one.
`TDSEAtomicWindow`([duration, taper])	Drive the atom only over an interval of the optical lattice (SEP 20, 4.6).
`TDSEBasis`(name, radial_edges, radial_orders, ...)	Describe a fully resolved helium atomic basis without native objects.
`TDSECalibration`(identity, status, ...[, ...])	Record the qualification status and domain of one calibration.
`TDSEConsistency`([warn, refuse, enforce])	Set the policy of the haCC weak-field linear consistency check (SEP 20, 5.4).
`TDSEExecution`([device, memory_limit, ...])	Declare runtime resources separately from the atomic scientific model.
`TDSEGasResponse`(target, basis, ...[, ...])	Own the complete electronic nonlinear response of scalar helium.
`TDSESampling`([refinement])	Specify integer refinement of the existing fine response lattice.

class solprop.nonlinear.tdse.HaccBasis(ions, neutral_square, radial_edges, radial_orders, angular_limit, angular_order, scaling_radius, scaling_angle, infinite_order, decay, gauge_radius, cut_energy, max_step_au, *, source, preset=None)[source]#

Bases: object

Describe a helium haCC model and basis, a provider preset or a custom one.

haCC (hybrid anti-symmetrised coupled channels; Majety, Zielinski and Scrinzi, New J. Phys. 17, 063002, 2015, doi:10.1088/1367-2630/17/6/063002) expands the two-electron state as a correlated neutral plus antisymmetrised products of frozen He+ channels with an active electron on a radial finite-element axis absorbed by infinite-range exterior complex scaling beyond scaling_radius. Every field is SI except max_step_au, an explicitly named exception that preserves the provider’s exact binary step ceiling in atomic units of time.

Attributes:

ions{1, 2}: Frozen He+ shells n <= ions: 1 is haCC(1) (the 1s channel), 2 is haCC(5) (1s, 2s, 2p0 and 2p+-1).
neutral_squareint: Largest l of the correlated neutral’s (l, l, 0) squares, 0 to 7.
radial_edgestuple of float: Element boundaries in m, from zero, strictly increasing.
radial_orderstuple of int: Points per element, each 2 to 64.
angular_limit{‘particle’, ‘total’}: Whether angular_order bounds the active electron’s l or the total L.
angular_orderint: The angular bound, 1 to 120.
scaling_radiusfloat: R0 in m, exactly a nonzero radial edge, where irECS starts.
scaling_anglefloat: irECS angle in rad, strictly between 0 and pi/2.
infinite_orderint: Points of the infinite element, 1 to 64.
decayfloat: Positive infinite-element decay exponent in 1/m.
gauge_radiusfloat or None: Rg in m, a radial edge strictly inside R0: length gauge inside, velocity gauge outside (the mixed gauge). None is the pure velocity-gauge control, representable only for a custom basis.
cut_energyfloat: Positive spectral cut above the ground root in J.
max_step_aufloat: Positive largest RK4 step in atomic units of time.
sourcestr: Provenance: the preset’s evidence, or the user’s reasons for a custom basis.
presetstr or None: The provider’s preset identity, hacc-helium-<1|5>-v<version>-<16 hex> for the standard numerics or hacc-helium-<1|5>-fast-v<version>-<16 hex> for the fast variant, or None for a custom basis. Its model number must agree with ions.

Raises:

MaterialError: If a field is out of range, of the wrong type or inconsistent.

Examples

>>> from solprop.nonlinear.tdse import HaccBasis
>>> a0 = 5.29177210544e-11
>>> basis = HaccBasis(
...     1, 1, tuple(x * a0 for x in (0.0, 1.0, 4.0, 12.0)), (6, 6, 6),
...     "particle", 2, 12 * a0, 0.15, 6, 1.0 / a0, 4 * a0, 1e-16, 0.05,
...     source="tiny unconverged custom basis",
... )
>>> basis.label, basis.qualified
('haCC(1) (custom)', False)

angular_limit: Literal['particle', 'total']#

angular_order: int#

cut_energy: float#

decay: float#

gauge_radius: float | None#

property identity: str[source]#

Return the SHA-256 identity of every field, tagged as a haCC basis.

The kind tag keeps a haCC identity distinct from any SAE TDSEBasis identity; preset distinguishes a preset from a custom basis with the same numbers.

Returns:

str: Hexadecimal digest of canonical JSON with kind="hacc_helium".

infinite_order: int#

ions: Literal[1, 2]#

property label: str[source]#

Return the model’s name, with (custom) for a non-preset basis.

Returns:

str: haCC(1) or haCC(5), followed by `` fast`` for the fast preset variant and by `` (custom)`` when preset is None.

max_step_au: float#

neutral_square: int#

preset: str | None = None#

property qualified: bool[source]#

Return whether the record claims a provider preset’s qualification.

The claim is verified against the installed provider when the binding prepares the model; a custom basis is never qualified.

Returns:

bool: True exactly when preset is set.

radial_edges: tuple[float, ...]#

radial_orders: tuple[int, ...]#

scaling_angle: float#

scaling_radius: float#

source: str#

property variant: Literal['standard', 'fast'] | None[source]#

Return the preset’s numerics variant, read from its identity.

Returns:

{‘standard’, ‘fast’} or None: 'fast' for a hacc-helium-<1|5>-fast-... identity, 'standard' for any other preset, None for a custom basis.

class solprop.nonlinear.tdse.TDSEAtomicWindow(duration=None, taper=5e-15)[source]#

Bases: object

Drive the atom only over an interval of the optical lattice (SEP 20, 4.6).

The atom starts from its ground state at the first lattice sample at or after -duration / 2 and stops at the last at or before +duration / 2. The drive and the nonlinear source are both multiplied by the same gate: a Planck taper of width taper inside each end, one between the tapers and zero outside. The gate is the source gate of the windowed response, so a window needs the native closure, whose source is gated. Dropping the field outside the window is a finite-memory approximation, not a property of FFT padding.

Attributes:

durationfloat or None: Nominal atomic duration in s, finite and positive. None is resolved from the capillary request’s trange; a direct construction must give it.
taperfloat: Width of each inner Planck taper in s, finite and positive; it must be less than half the duration.

Raises:

MaterialError: If a value is non-finite, non-positive, boolean, or the taper is not shorter than half the duration.

duration: float | None = None#

taper: float = 5e-15#

class solprop.nonlinear.tdse.TDSEBasis(name, radial_edges, radial_orders, lmax, cut_energy, *, source, m=0, potential='helium_tong05', potential_version=1, scaling_radius=None, scaling_angle=None, infinite_order=None, decay=None, cuts=())[source]#

Bases: object

Describe a fully resolved helium atomic basis without native objects.

Attributes:

namestr: Descriptive preset or custom-basis name; numerical fields are authoritative.
radial_edgestuple of float: Increasing finite-element boundaries in m, beginning at zero.
radial_orderstuple of int: Gauss-Lobatto points per finite element, each between 2 and 64.
lmaxint: Largest angular momentum, nonnegative and at most 4096.
cut_energyfloat: Positive spectral cut in J.
sourcestr: Provenance for the numerical choices.
mint: Magnetic quantum number; the initial helium route requires zero.
potentialstr: Built-in provider identity, initially helium_tong05 only.
potential_versionint: Positive revision of the provider’s potential definition.
scaling_radiusfloat or None: Exterior-complex-scaling boundary in m, exactly a positive radial edge.
scaling_anglefloat or None: Scaling angle in rad, strictly between zero and pi/2.
infinite_orderint or None: Infinite-element points, between 1 and 64.
decayfloat or None: Positive infinite-element decay exponent in 1/m.
cutstuple of float: Optional observation boundaries in m, increasing positive edges below the physical boundary. Scaling fields must all be given or all absent.

cut_energy: float#

cuts: tuple[float, ...] = ()#

decay: float | None = None#

property identity: str[source]#

Return the stable SHA-256 identity of all resolved basis fields.

Returns:

str: Hexadecimal digest of canonical JSON, including the source record.

infinite_order: int | None = None#

lmax: int#

m: int = 0#

name: str#

potential: str = 'helium_tong05'#

potential_version: int = 1#

radial_edges: tuple[float, ...]#

radial_orders: tuple[int, ...]#

scaling_angle: float | None = None#

scaling_radius: float | None = None#

source: str#

class solprop.nonlinear.tdse.TDSECalibration(identity, status, basis_identity, wavelength_range, *, source, uncertainty=None, limitations=())[source]#

Bases: object

Record the qualification status and domain of one calibration.

Attributes:

identitystr: Persistent identity of the measured or explicitly provisional record.
status{‘research’, ‘qualified’}: Whether the declared domain has supporting qualification evidence.
basis_identitystr: Identity of the resolved basis used for that record.
wavelength_rangetuple of float: Increasing positive wavelength bounds in m; these describe the stated calibration, not arbitrary broadband frequency mixing.
sourcestr: Evidence reference, including the source of a research hypothesis.
uncertaintyfloat or None: Nonnegative finite relative uncertainty; required for a qualified record.
limitationstuple of str: Explicit interpretation limits; a research record requires at least one.

basis_identity: str#

identity: str#

limitations: tuple[str, ...] = ()#

source: str#

status: Literal['research', 'qualified']#

uncertainty: float | None = None#

wavelength_range: tuple[float, float]#

class solprop.nonlinear.tdse.TDSEConsistency(warn=0.1, refuse=0.3, enforce=True)[source]#

Bases: object

Set the policy of the haCC weak-field linear consistency check (SEP 20, 5.4).

Before the first propagation call of a haCC run the per-atom linear susceptibility of the model is compared with optmat’s helium through the ratio kappa_1. |kappa_1 - 1| <= warn passes, up to refuse warns, above it refuses; an invalid extraction always refuses. These are policy, not physics: they never enter a descriptor, identity or resume key.

Attributes:

warnfloat: Positive finite warning bound on |kappa_1 - 1|; default 0.1.
refusefloat: Finite refusal bound, at least warn; default 0.3, the range of gross errors (an electron count applied twice, a sign, a unit).
enforcebool: False skips the check entirely, with a warning: no atomic call, no cache.

Raises:

MaterialError: If a bound is boolean, non-finite, non-positive or warn > refuse.

enforce: bool = True#

refuse: float = 0.3#

warn: float = 0.1#

class solprop.nonlinear.tdse.TDSEExecution(device='cpu', memory_limit=None, max_batch_rows=32, max_atomic_calls=None, complement='deterministic')[source]#

Bases: object

Declare runtime resources separately from the atomic scientific model.

Attributes:

device{‘cpu’, ‘cuda’, ‘hip’}: Required installed provider execution family; there is no implicit fallback.
memory_limitint or None: Positive persistent-memory budget in bytes, or no explicit limit.
max_batch_rowsint: Positive maximum number of radial rows in one provider call.
max_atomic_callsint or None: Positive limit on attempted provider calls, including failures and diagnostics.
complement{‘deterministic’, ‘vendor_blas’}: Explicit provider projector arithmetic; availability is checked at preparation.

complement: Literal['deterministic', 'vendor_blas'] = 'deterministic'#

device: Literal['cpu', 'cuda', 'hip'] = 'cpu'#

max_atomic_calls: int | None = None#

max_batch_rows: int = 32#

memory_limit: int | None = None#

class solprop.nonlinear.tdse.TDSEGasResponse(target, basis, max_atomic_step, kerr_model, remainder_scale, calibration, sampling, *, cubic_scale=None, model='sae', atomic_window='auto', consistency=TDSEConsistency(warn=0.1, refuse=0.3, enforce=True))[source]#

Bases: object

Own the complete electronic nonlinear response of scalar helium.

Attributes:

targetstr: Initially helium only, in its prepared ground state.
basisTDSEBasis or HaccBasis: Fully resolved atomic specification: an SAE radial, angular, spectral-cut and potential record for model="sae", a haCC model and basis for model="hacc".
max_atomic_stepfloat: Positive maximum internal atomic step in s; actual subdivision is recorded. For haCC it must equal basis.max_step_au in seconds within two units in the last place; the provider receives basis.max_step_au itself.
kerr_model{‘optmat_cubic’, ‘tdse_shadow’, ‘tdse_native’}: Cubic replacement policy. The native option retains the complete native nonlinear current after first-order subtraction, with explicit scaling, and its source is always gated and edge-free (SEP 26): the remainder S is multiplied by the fine-grid temporal Planck collar, or by the atomic window’s gate when one is set, and the edge term is subtracted, F[g S] - F[g' S] / (i omega) on the active bins, the transform of the current held at its taper-weighted value after the window rather than switched off. The gate needs a steady-current certificate of at most 1e-10 on the lattice and band, checked at translation. Raw provider currents are unchanged; the cubic replacements are never gated. haCC admits tdse_native only: the provider has no third order of its closed whole-atom current.
remainder_scalefloat: Positive finite dimensionless current-remainder scale. Applied after subtracting the raw first-order current for tdse_native, or the raw first- and third-order currents for the other policies. Native scale 1 retains the unscaled nonlinearity; any other positive value is explicit. haCC requires exactly 1.0: its current is already the whole atom’s.
calibrationTDSECalibration: Separate evidence identity and domain; never an implicit electron multiplier.
samplingTDSESampling: Response-lattice refinement policy.
cubic_scalefloat or None: Positive finite dimensionless third-order dipole scale, required only for tdse_shadow. It is independent of remainder_scale.
model{‘sae’, ‘hacc’}: Atomic model family, which must match the basis type.
atomic_windowTDSEAtomicWindow, ‘auto’ or None: Interval of the optical lattice the atom is driven over. "auto" resolves to None (the full lattice) for SAE and to TDSEAtomicWindow() (the requested duration, 5 fs tapers) for haCC. An explicit None selects the full lattice for haCC too.
consistencyTDSEConsistency: Policy of the haCC weak-field linear check; only the default is admitted for SAE. Never part of a descriptor, identity or resume key.

atomic_window: TDSEAtomicWindow | Literal['auto'] | None = 'auto'#

basis: TDSEBasis | HaccBasis#

calibration: TDSECalibration#

consistency: TDSEConsistency = TDSEConsistency(warn=0.1, refuse=0.3, enforce=True)#

cubic_scale: float | None = None#

kerr_model: Literal['optmat_cubic', 'tdse_shadow', 'tdse_native']#

max_atomic_step: float#

model: Literal['sae', 'hacc'] = 'sae'#

remainder_scale: float#

sampling: TDSESampling#

target: str#

property traits: ResponseTraits[source]#

Return the scalar real-field memory response traits.

Returns:

ResponseTraits: Field-grid, scalar, density-dependent temporal response.

solprop.nonlinear.tdse.TDSEKerrModel#

The three explicit cubic retention or replacement policies of SEP 12.

alias of Literal[‘optmat_cubic’, ‘tdse_shadow’, ‘tdse_native’]

solprop.nonlinear.tdse.TDSEModel#

The atomic model family: single active electron, or two-electron haCC (SEP 20).

alias of Literal[‘sae’, ‘hacc’]

class solprop.nonlinear.tdse.TDSESampling(refinement=1)[source]#

Bases: object

Specify integer refinement of the existing fine response lattice.

Attributes:

refinementint: Positive power of two multiplying the existing fine sample count. The coarse spectrum, time window and collars stay fixed. No tail taper, endpoint duplication or field-area correction is applied.

refinement: int = 1#