solprop.driver.tdse_consistency#

Check a haCC model’s weak-field linear response against optmat’s helium (SEP 20).

Because the haCC current is the whole atom’s and nothing rescales it, every haCC configuration is checked before propagation (SEP 20 sections 4.8, 4.9 and 5.4). A fixed synthetic weak pulse drives one row; the per-atom first-order dipole p_1 = j_1 / (i omega) gives the model’s susceptibility alpha_haCC = p_1 / (eps0 E) in m^3, and the ratio kappa_1 = alpha_optmat / alpha_haCC is formed over the supported band. Its largest |kappa_1 - 1| passes, warns or refuses; an invalid extraction always refuses. The measured values are cached per configuration and provider revision, never per build.

The cubic ratio kappa_3 is evidence only (validation level L3), extracted by cubic_evidence() over the fundamental band and never part of the gate.

Fourier convention. Inside this module a hat is NumPy’s forward DFT, under which d/dt becomes +i omega (the internal convention of docs/dev/conventions.md section 2). optmat’s susceptibility is in the optics convention, so its complex value is conjugated before comparison; the real and imaginary parts are compared together, never the real part alone.

Module Attributes

PROTOCOL_VERSION

Version of the frozen kappa_1 protocol below; any change invalidates every cache.

Functions

`apply_outcome`(result)	Warn for a warned or skipped result, raise for a refused or invalid one.
`cache_directory`()	Return the consistency cache directory (SEP 20 section 6.5).
`check_consistency`(response, execution, *, ...)	Run the haCC weak-field linear check on its own, without a propagation.
`cubic_evidence`(spacing, drive, remainders, ...)	Extract kappa_3 and the leakage figure from an amplitude ladder (L3).
`describe`(result)	Return the human-readable summary used in warnings and refusals.
`evaluate_consistency`(source, basis, policy, ...)	Obtain kappa_1 from the cache or by one diagnostic call, then decide.
`gate_run`(binding, response, *, ...)	Run the gate before a haCC run's first propagation call.
`protocol_field`(reference_wavelength)	Return the protocol's spacing and synthetic weak field (version 1).
`reduce_linear`(spacing, drive, first_order, ...)	Form kappa_1 from a first-order current and a reference susceptibility.

Classes

`ConsistencyResult`(outcome, model, preset, ...)	Record one haCC consistency decision and its provenance (SEP 20, 5.4).
`CubicEvidence`(kappa_3, residual, ...)	Hold the L3 kappa_3 evidence of one model (SEP 20 section 4.8; not gated).
`DiagnosticSource`(args, *kwargs)	Run one charged diagnostic row on an open haCC model.
`GateBinding`(args, *kwargs)	A run's binding as the gate needs it: a diagnostic row and its record.
`LinearReduction`(valid, reason[, wavelength, ...])	Hold one kappa_1 extraction and its validity (SEP 20 section 4.8).

class solprop.driver.tdse_consistency.ConsistencyResult(outcome, model, preset, reduction, protocol_version, cache_key, from_cache, computed, warn, refuse, enforce, ledger=None, cubic_evidence=None)[source]#

Bases: object

Record one haCC consistency decision and its provenance (SEP 20, 5.4).

Attributes:

outcome{‘passed’, ‘warned’, ‘refused’, ‘invalid’, ‘skipped’}: The decision.
modelstr: The model’s label, for example haCC(1) or haCC(5) (custom).
presetstr or None: The provider preset identity, or None for a custom basis.
reductionLinearReduction or None: The kappa_1 extraction; None when skipped.
protocol_versionint: Version of the frozen protocol.
cache_keystr or None: The cache entry’s key; None when skipped.
from_cachebool: Whether the reduction was read from the cache.
computedMapping or None: Execution space, build and threads of the computation that produced the values, with its wall and CPU time.
warn, refusefloat: The bounds applied.
enforcebool: Whether the check ran.
ledgerAtomicCallLedger or None: Calls charged by this check (zero on a cache hit); None when the check ran inside a run, whose ledger holds them.
cubic_evidenceMapping or None: For a preset, the reference to its L3 kappa_3 evidence; never gated.

cache_key: str | None#

computed: Mapping[str, object] | None#

cubic_evidence: Mapping[str, object] | None = None#

enforce: bool#

from_cache: bool#

ledger: AtomicCallLedger | None = None#

model: str#

outcome: Literal['passed', 'warned', 'refused', 'invalid', 'skipped']#

preset: str | None#

protocol_version: int#

reduction: LinearReduction | None#

refuse: float#

to_record()[source]#

Return the JSON-compatible record stored under tdse.consistency.

Returns:

dict: Plain values.

warn: float#

class solprop.driver.tdse_consistency.CubicEvidence(kappa_3, residual, ladder_residual, ladder_ok, leakage, seventh_order_floor, leakage_resolved, band_wavelength)[source]#

Bases: object

Hold the L3 kappa_3 evidence of one model (SEP 20 section 4.8; not gated).

Attributes:

kappa_3float: Real least-squares scale with F[j3_ref] ~ kappa_3 F[c3_hat] over the fundamental band, j3_ref = eps0 gamma3 d/dt(E^3).
residualfloat: ||F[j3_ref] - kappa_3 F[c3_hat]|| / ||F[j3_ref]|| on that band.
ladder_residualfloat: ||r_4 - (64 c3_hat + 1024 c5_hat)|| / ||r_4||: how well the c3 + c5 model predicts the lambda = 4 row.
ladder_okbool: Whether ladder_residual is at most the stated bound, 1e-4.
leakagefloat: ||c_1|| / ||c_3|| of the three-term fit r_a = a c1 + a^3 c3 + a^5 c5: the shadow’s first-order leakage relative to the cubic term (Q15).
seventh_order_floorfloat: The fit’s floor for that leakage, relative to ||c_3||: a seventh order c7 enters the fitted c1 as exactly 64 c7, which three rows cannot separate from a leak. It is estimated from the measured order ratio as 64 (||c5_hat|| / ||c3_hat||)^2; a leakage at or below it is not resolved.
leakage_resolvedbool: Whether leakage exceeds seventh_order_floor.
band_wavelengthtuple of float: The fundamental band’s wavelength limits in m.

band_wavelength: tuple[float, float]#

kappa_3: float#

ladder_ok: bool#

ladder_residual: float#

leakage: float#

leakage_resolved: bool#

residual: float#

seventh_order_floor: float#

class solprop.driver.tdse_consistency.DiagnosticSource(*args, **kwargs)[source]#

Bases: Protocol

Run one charged diagnostic row on an open haCC model.

diagnostic_currents(field, spacing)[source]#

Return j_tot and j_1 for one row.

Parameters:

fieldnumpy.ndarray: Field in V/m, shape (1, n_samples).
spacingfloat: Spacing in s.

Returns:

tuple of numpy.ndarray: Currents in C m/s.

class solprop.driver.tdse_consistency.GateBinding(*args, **kwargs)[source]#

Bases: DiagnosticSource, Protocol

A run’s binding as the gate needs it: a diagnostic row and its record.

build_plans()[source]#

Build the deferred propagation plans after the check.

metadata()[source]#

Return the binding’s provenance, including its native build.

Returns:

Mapping[str, object]: JSON-compatible record.

property plans_built: bool[source]#

Return whether the propagation plans exist.

Returns:

bool: False while a deferred binding awaits build_plans().

record_consistency(record)[source]#

Attach the consistency record to the binding’s provenance.

Parameters:

recordMapping[str, object]: JSON-compatible consistency record.

class solprop.driver.tdse_consistency.LinearReduction(valid, reason, wavelength=(), kappa_real=(), kappa_imag=(), deviation=None, worst_wavelength=None, worst_kappa=None)[source]#

Bases: object

Hold one kappa_1 extraction and its validity (SEP 20 section 4.8).

Attributes:

validbool: Whether every validity condition held.
reasonstr or None: Why the extraction is invalid, or None.
wavelengthtuple of float: Band wavelengths in m, ascending frequency.
kappa_real, kappa_imagtuple of float: kappa_1 = alpha_optmat / alpha_haCC on the band.
deviationfloat or None: Largest |kappa_1 - 1| on the band.
worst_wavelengthfloat or None: Wavelength in m of that largest deviation.
worst_kappatuple of float or None: (Re, Im) of kappa_1 there.

deviation: float | None = None#

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

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

reason: str | None#

valid: bool#

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

worst_kappa: tuple[float, float] | None = None#

worst_wavelength: float | None = None#

solprop.driver.tdse_consistency.PROTOCOL_VERSION = 1#: Version of the frozen kappa_1 protocol below; any change invalidates every cache.

solprop.driver.tdse_consistency.apply_outcome(result)[source]#

Warn for a warned or skipped result, raise for a refused or invalid one.

Parameters:

resultConsistencyResult: The decided result.

Raises:

TDSEConsistencyError: For refused and invalid, with the result attached as result.

solprop.driver.tdse_consistency.cache_directory()[source]#

Return the consistency cache directory (SEP 20 section 6.5).

Returns:

pathlib.Path: $SOLPROP_CACHE_DIR/tdse-consistency when that is set, else $XDG_CACHE_HOME/solprop/tdse-consistency, else ~/.cache/solprop/tdse-consistency. Deleting it is always safe.

solprop.driver.tdse_consistency.check_consistency(response, execution, *, reference_wavelength, refresh=False, tdse_archive=None)[source]#

Run the haCC weak-field linear check on its own, without a propagation.

The same protocol and cache as a run’s gate (SEP 20 sections 4.9 and 6.5): a cache hit makes no atomic call; a miss prepares the model alone, makes one one-row diagnostic call within execution’s budget and memory limit, and writes the entry. No warning or refusal is raised here: the outcome is returned. With tdse_archive, the call is archived with the diagnostic role in a new archive of its own (SEP 20 section 5.8); a cache hit writes no evaluation.

Parameters:

responseTDSEGasResponse: A haCC response; its consistency policy supplies the bounds.
executionTDSEExecution: Device, memory limit and explicit call budget of the check.
reference_wavelengthfloat: Carrier wavelength of the protocol pulse in m (the run’s lambda0).
refreshbool, optional: Recompute and overwrite an existing cache entry.
tdse_archivesolprop.output.TDSEArchive or None, optional: Archive the provider call in this new HDF5 file; an existing file is refused, never overwritten.

Returns:

ConsistencyResult: Outcome, kappa_1 values, cache use, provenance and the check’s own ledger.

Raises:

BackendError: If the response is not haCC, or the provider is missing, stale or fails.
TDSEArchiveError: If the archive’s path exists, or a write to it fails.

solprop.driver.tdse_consistency.cubic_evidence(spacing, drive, remainders, gamma3)[source]#

Extract kappa_3 and the leakage figure from an amplitude ladder (L3).

With the remainders r_a = j_tot - j_1 of the same base field scaled by a in {1, 2, 4}, c3_hat = (32 r_1 - r_2) / 24 = c3 - 4 c7 + ... and c5_hat = (r_2 - 8 r_1) / 24 neglect the first-order leakage c1. kappa_3 is compared over the fundamental band only, where the third-harmonic component of the cubic response is negligible.

Parameters:

spacingfloat: Sample spacing in s.
drivenumpy.ndarray: The base (a = 1) field in V/m.
remaindersmapping: {1: r_1, 2: r_2, 4: r_4} in C m/s per atom, each like drive.
gamma3float: The per-atom Kerr coefficient of optmat at the carrier, m^5/V^2.

Returns:

CubicEvidence: The reported, never gated, evidence.

Raises:

BackendError: If the ladder is incomplete, mis-shaped, non-finite or degenerate.

solprop.driver.tdse_consistency.describe(result)[source]#

Return the human-readable summary used in warnings and refusals.

Parameters:

resultConsistencyResult: A decided, warned, refused or invalid result.

Returns:

str: Model, worst wavelength and kappa_1, and the bounds.

solprop.driver.tdse_consistency.evaluate_consistency(source, basis, policy, *, reference_wavelength, provider_revision, computed_on, refresh=False)[source]#

Obtain kappa_1 from the cache or by one diagnostic call, then decide.

Parameters:

sourceobject or None: Open haCC binding or session; None only when the check is skipped.
basisHaccBasis: The configuration checked.
policyTDSEConsistency: The decision bounds and switch.
reference_wavelengthfloat: Carrier of the protocol pulse in m.
provider_revisionstr: Provider source revision; part of the cache key.
computed_onmapping: Execution space, build fingerprint and threads; recorded, not keyed.
refreshbool, optional: Recompute and overwrite the cache entry.

Returns:

ConsistencyResult: The decision with its provenance. Nothing is raised or warned here.

solprop.driver.tdse_consistency.gate_run(binding, response, *, reference_wavelength, provider_revision, computed_on)[source]#

Run the gate before a haCC run’s first propagation call.

Parameters:

bindingobject: The run’s open binding; a computed check is charged to its ledger.
responseTDSEGasResponse: The declared haCC response, carrying the policy.
reference_wavelengthfloat: The run’s reference wavelength in m.
provider_revisionstr: Pinned provider revision.
computed_onmapping: The binding’s execution space, build and threads.

Returns:

ConsistencyResult: The decision; ledger is None because the run’s ledger holds the call. The caller records it and then calls apply_outcome().

solprop.driver.tdse_consistency.protocol_field(reference_wavelength)[source]#

Return the protocol’s spacing and synthetic weak field (version 1).

Parameters:

reference_wavelengthfloat: Carrier wavelength in m, positive and finite.

Returns:

spacingfloat: Sample spacing in s; sample m lies at m * spacing.
fieldnumpy.ndarray: Real field in V/m, shape (1601,), over a 40 fs window.

Raises:

BackendError: If the wavelength is not positive and finite.

solprop.driver.tdse_consistency.reduce_linear(spacing, drive, first_order, reference, support)[source]#

Form kappa_1 from a first-order current and a reference susceptibility.

Parameters:

spacingfloat: Sample spacing in s.
drivenumpy.ndarray: Real field in V/m.
first_ordernumpy.ndarray: The model’s first-order current per atom, C m/s, same shape.
referencecallable: Per-atom susceptibility in m^3 at angular frequencies in rad/s, in the optics convention (conjugated here).
supporttuple of float: Lowest and highest angular frequency in rad/s where the reference is valid.

Returns:

LinearReduction: The kappa_1 values over the band, or an invalid record naming the failed condition: non-finite or mismatched input, a zero current, endpoint leakage, an empty band, a band bin below the rounding floor, or a non-finite ratio. DC is always excluded from the division by i omega.