solprop.translate.tdse#

Define the provider-free host contract for the helium TDSE response.

The seam holds immutable descriptors and owning SI arrays. The driver owns the optional native runtime, stable row chunks and transactional call reservations. No physical subtraction, calibration or density factor is applied here.

Module Attributes

`HACC_NORM_GROWTH_LIMIT`	The provider's gross-failure norm-growth limit pinned in every haCC setup record.
`TDSEPurpose`	The relation of an evaluated field to the optical integration or diagnostics.
`DESCRIPTOR_SCHEMA`	The one TDSE descriptor schema solprop writes and reads.

Functions

`lattice_times`(samples, spacing)	Return the fine response lattice's sample times exactly as the grid forms them.
`refine_response_grid`(grid, sampling)	Refine the fine lattice while preserving every coarse coordinate and collar.
`resolve_atomic_window`(window, samples, spacing)	Resolve a declared window on a fine response lattice.
`waveform_identity`(fields)	Hash the exact real host waveforms and their shape for diagnostic reuse.

Classes

`AtomicCallBudget`(limit, calls_per_evaluation)	Reserve whole trials and charge every provider attempt before invocation.
`AtomicCallLedger`(limit, attempted, reserved, ...)	Snapshot the binding's charged attempts and remaining trial reservation.
`AtomicWindowRecord`(duration, taper, start, ...)	Hold an atomic window resolved on one fine response lattice (SEP 20, 5.3).
`TDSEBinding`(args, *kwargs)	Provide the driver's explicit, resource-owning host atomic service.
`TDSEDescriptor`(configuration_json, identity, ...)	Carry a resolved response identity and primitive values across the seam.
`TDSEResult`(total_current, ...[, ...])	Own validated, read-only microscopic responses for all requested nodes.

class solprop.translate.tdse.AtomicCallBudget(limit, calls_per_evaluation)[source]#

Bases: object

Reserve whole trials and charge every provider attempt before invocation.

The binding calls reserve before a trial, begin_evaluation once for each all-node evaluation, and charge immediately before each chunk’s provider call. On failure it calls record_failure; a finally block releases unused reservations. Charges are never rolled back.

Attributes:

limitint or None: Positive maximum attempted calls, or no explicit limit.
calls_per_evaluationint: Fixed number of provider chunks required for all radial rows.

begin_evaluation(*, purpose, calls=None)[source]#

Count one complete all-node request before its first provider chunk.

Parameters:

purpose{‘startup’, ‘predictor’, ‘corrected’, ‘diagnostic’}: Relationship of the driving field to the optical step.
callsint or None: Provider calls of this evaluation; None uses calls_per_evaluation.

Raises:

BackendError: If the previous evaluation is unfinished or sufficient chunks were not reserved, or the purpose is unknown.

calls_per_evaluation: int#

charge(*, purpose, z=0.0)[source]#

Charge one reserved provider attempt immediately before invoking it.

Parameters:

purpose{‘startup’, ‘predictor’, ‘corrected’, ‘diagnostic’}: Must match the current all-node evaluation’s label.
zfloat: Position in m, retained in a misuse diagnostic.

Raises:

BackendError: If the call is unreserved or carries the wrong evaluation label.

limit: int | None#

record_failure()[source]#

Mark the last charged provider attempt failed without refunding it.

Raises:

BackendError: If there is no charged call or the last call was already marked failed.

release_reservation()[source]#

Release unspent trial calls after success, rejection or an exception.

reserve(logical_calls, *, z=0.0, calls=None)[source]#

Reserve all chunks of the next trial before any source evaluation.

Parameters:

logical_callsint: Positive number of all-node source evaluations the trial may need.
zfloat: Last accepted position in m, attached to an insufficient-budget error.
callsint or None: Provider calls per evaluation, for a diagnostic with its own chunking (the haCC consistency check’s single row); None uses calls_per_evaluation.

Raises:

ResponseBudgetError: If the entire trial cannot be paid for. The driver attaches its state.
BackendError: If a reservation is already active or the count is invalid.

restore(ledger)[source]#

Restore cumulative charges while releasing an interrupted reservation.

The new execution configuration supplies the limit: it may explicitly increase the old cap, but it cannot be below calls already attempted.

Parameters:

ledgerAtomicCallLedger: Snapshot saved at the previous run’s last accepted checkpoint.

Raises:

BackendError: If counts are invalid, the new limit is insufficient, or this budget has already begun work. Restoring never resets cumulative charges.

snapshot()[source]#

Return an immutable copy of the current accounting state.

Returns:

AtomicCallLedger: Counts including all successful, diagnostic and failed attempts.

class solprop.translate.tdse.AtomicCallLedger(limit, attempted, reserved, logical_evaluations, diagnostic_calls, failed_calls)[source]#

Bases: object

Snapshot the binding’s charged attempts and remaining trial reservation.

Attributes:

limitint or None: Declared maximum attempted provider calls, or unlimited.
attemptedint: Calls charged immediately before invocation, successful or failed.
reservedint: Unspent calls held for the current whole trial.
logical_evaluationsint: All-node evaluations begun, counted once independently of row chunks.
diagnostic_callsint: Attempted provider calls labelled as explicit diagnostics.
failed_callsint: Attempted provider calls with exceptions or invalid response rows.

attempted: int#

diagnostic_calls: int#

failed_calls: int#

classmethod from_record(record)[source]#

Validate a persisted atomic-call accounting record.

Parameters:

recordMapping[str, object]: Exact primitive snapshot fields, with counts in actual provider calls.

Returns:

AtomicCallLedger: Validated immutable snapshot. Reservations remain recorded here; AtomicCallBudget.restore releases them before new work.

Raises:

BackendError: If fields are missing or unknown, counts are not nonnegative plain integers, subcounts exceed attempts, or the old cap is exceeded.

limit: int | None#

logical_evaluations: int#

reserved: int#

class solprop.translate.tdse.AtomicWindowRecord(duration, taper, start, stop, first, last, t_s, t_e, gate)[source]#

Bases: object

Hold an atomic window resolved on one fine response lattice (SEP 20, 5.3).

Attributes:

durationfloat: Nominal duration T_a in s.
taperfloat: Width of each inner Planck taper in s.
start, stopfloat: Nominal bounds t_- = -T_a / 2 and t_+ = T_a / 2 in s.
first, lastint: Inclusive lattice indices of t_s, the first sample at or after t_-, and t_e, the last at or before t_+.
t_s, t_efloat: Times of those samples in s; provider time zero is t_s.
gatetuple of float: Planck breakpoints (t_-, t_- + w, t_+ - w, t_+) in s, never stretched to the sample endpoints.

property atomic_duration: float[source]#

Return the realised atomic duration t_e - t_s.

Returns:

float: Duration in s, compared with a preset’s tested window.

duration: float#

first: int#

gate: tuple[float, float, float, float]#

gate_derivative(times)[source]#

Evaluate the analytic derivative g'(t) of the window’s gate.

Parameters:

timesnumpy.ndarray: Times in s, shape (n,).

Returns:

numpy.ndarray: dg/dt in 1/s: positive on the leading taper, negative on the trailing one, zero elsewhere (solprop.grid.planck_taper_derivative()).

gate_values(times)[source]#

Evaluate the window’s gate g(t) at absolute lattice times.

Parameters:

timesnumpy.ndarray: Times in s, shape (n,).

Returns:

numpy.ndarray: g in [0, 1]: zero outside [t_-, t_+], one between the tapers.

last: int#

property samples: int[source]#

Return the number of retained samples last - first + 1.

Returns:

int: Atomic samples passed to the provider.

start: float#

stop: float#

t_e: float#

t_s: float#

taper: float#

to_json()[source]#

Return the primitive record stored in a descriptor’s lattice.

Returns:

dict: Plain JSON values: SI times and integer indices.

solprop.translate.tdse.DESCRIPTOR_SCHEMA = 'solprop.tdse-descriptor.v5'#

The one TDSE descriptor schema solprop writes and reads.

Its response record carries every field of the response but the consistency policy: model and atomic_window (null for the full lattice), with a kind-tagged haCC basis. Version 5 is SEP 26’s version-4 layout without the source_filter key: the source form follows from kerr_model, the native closure’s source being always the edge-free gated one. Earlier versions are not read.

solprop.translate.tdse.HACC_NORM_GROWTH_LIMIT = 2.0#: The provider’s gross-failure norm-growth limit pinned in every haCC setup record.

class solprop.translate.tdse.TDSEBinding(*args, **kwargs)[source]#

Bases: Protocol

Provide the driver’s explicit, resource-owning host atomic service.

close()[source]#

Close every provider resource owned by the binding.

evaluate(fields, *, z, purpose, density=None)[source]#

Evaluate all radial rows using the binding’s stable provider chunks.

Parameters:

fieldsnumpy.ndarray: Real host fields in V/m, shape (n_nodes, n_to).
zfloat: Optical position in m for provenance and failures.
purpose{‘startup’, ‘predictor’, ‘corrected’, ‘diagnostic’}: Label of the evaluated optical field.
densityfloat or None, optional: Number density at z in m^-3, a provenance label only (the source applies the density itself); None when the caller has none.

Returns:

TDSEResult: Validated owning microscopic arrays with no density or calibration.

property ledger: AtomicCallLedger[source]#

Return the current immutable atomic-call accounting snapshot.

Returns:

AtomicCallLedger: Binding-local budget and attempted-call counts.

memory_ledger()[source]#

Return named persistent allocations in bytes without native handles.

Returns:

Mapping[str, int]: Allocation names and byte counts.

metadata()[source]#

Return serializable runtime, scientific and call-accounting records.

Returns:

Mapping[str, object]: Public provider configuration and actual execution provenance.

record_trial(*, accepted)[source]#

Record the stepper’s decision on the most recently reserved trial.

A provenance event only: it changes no accounting and no atomic state. The stepper reports every attempt, including one rejected before any call.

Parameters:

acceptedbool: Whether the trial’s step was accepted.

release_reservation()[source]#

Release unused calls while retaining every attempted-call charge.

reserve(logical_calls)[source]#

Reserve every atomic chunk needed by an upcoming optical trial.

Each reservation opens a new optical trial: its evaluations carry the trial’s label until the next reservation (SEP 20 section 5.8).

Parameters:

logical_callsint: Positive maximum number of all-node source evaluations.

restore_ledger(ledger)[source]#

Restore cumulative attempted calls before a same-model resumed run.

Parameters:

ledgerAtomicCallLedger: Previous checkpoint’s accounting; unused reservations are released.

class solprop.translate.tdse.TDSEDescriptor(configuration_json, identity, kerr_model, remainder_scale, cubic_scale, shadow_order, outputs, samples, spacing, time_origin, max_atomic_step, initial_l=0, initial_index=0, growing='remove', growth_tolerance=0.001, window_duration=None, accept_removed_component=False)[source]#

Bases: object

Carry a resolved response identity and primitive values across the seam.

Construct with from_response() after resolving the fine grid. Native handles and physics objects are absent; configuration_json is sufficient to reconstruct the declared public provider basis during preparation.

Attributes:

configuration_jsonstr: Canonical JSON scientific specification, resolved lattice and pinned provider setup policy. Quantities are SI unless dimensionless.
identitystr: SHA-256 of that exact JSON string.
kerr_modelstr: Cubic-source policy.
remainder_scalefloat: Dimensionless remainder scale, applied by source assembly only.
cubic_scalefloat or None: Dimensionless third-order dipole scale, or absent.
shadow_orderint: Requested highest shadow order, 1 or 3.
outputs{‘full’, ‘total_current’}: Minimal required provider result contract.
samplesint: Response samples, equal to the resolved fine FFT size.
spacingfloat: Positive response spacing in s.
time_originfloat: Optical label in s of provider time zero; no sample values are shifted.
max_atomic_stepfloat: Requested positive maximum atomic step in s.
initial_l, initial_indexint: Prepared ground-state selection, both zero.
growingstr: Pinned provider growing-mode policy, remove.
growth_tolerancefloat: Pinned provider default dimensionless threshold, 1e-3.
window_durationfloat or None: Provider setup’s declared growing-mode window in s, the atomic run duration (samples - 1) * spacing. None only for a bare descriptor without a configuration; admission requires the run duration.
accept_removed_componentbool: False: preparation must satisfy the provider’s removed-component check.
Every descriptor has the one schema :data:`DESCRIPTOR_SCHEMA`: the complete
response record (``model``, a ``kind``-tagged haCC basis and ``atomic_window``), the
exact SI collar breakpoints in ``lattice.time_collar``, ``lattice.atomic_window``
when a window is set (its gate replacing the collar), and, for haCC, the pinned
``setup`` record of SEP 20 section 6.2. Raw atomic histories retain
``tail_policy=”unchanged”``. A native descriptor’s source is gated and edge-free
(:attr:`gated`); its gate is admitted by the steady-current certificate when the
problem is validated.

accept_removed_component: bool = False#

property atomic_window: AtomicWindowRecord | None[source]#

Return the resolved atomic window, or None for the full lattice.

Returns:

AtomicWindowRecord or None: Sample range, endpoint times and gate breakpoints in s.

configuration_json: str#

cubic_scale: float | None#

classmethod from_response(response, grid)[source]#

Resolve one scientific response on an already refined field grid.

Parameters:

responseTDSEGasResponse: Validated scientific specification. An atomic window must have a resolved duration.
gridFieldGrid: Result of refine_response_grid(), used by source transforms.

Returns:

TDSEDescriptor: Immutable descriptor with no imported provider or native handle.

Raises:

TranslationError: If the window’s duration is unresolved, exceeds the lattice period or holds fewer than four samples, or the grid’s fine times are not the standard lattice.

property gated: bool[source]#

Return whether the source is gated and edge-free (SEP 26).

Returns:

bool: True for the native closure, whose remainder current is gated by the window or grid collar with the edge term removed; False for the cubic replacements, whose sources are never gated.

growing: str = 'remove'#

growth_tolerance: float = 0.001#

identity: str#

initial_index: int = 0#

initial_l: int = 0#

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

max_atomic_step: float#

property model: Literal['sae', 'hacc'][source]#

Return the atomic model family recorded in the configuration.

Returns:

{‘sae’, ‘hacc’}: The recorded response.model.

outputs: Literal['full', 'total_current']#

remainder_scale: float#

property response: TDSEGasResponse[source]#

Return the revalidated scientific response this descriptor carries.

Returns:

TDSEGasResponse: Reconstructed record; its consistency policy is the default, because policy never enters a descriptor.

samples: int#

shadow_order: int#

source_breakpoints()[source]#

Return the Planck breakpoints of the gate a gated source uses.

Returns:

tuple of float: (z_-, o_-, o_+, z_+) in s: the atomic window’s gate when one is set, else the recorded fine temporal collar. Never moved to samples.

source_gate()[source]#

Return the window’s gate on the full lattice, or None without a window.

Returns:

numpy.ndarray or None: Read-only g(t_n), shape (samples,), evaluated at the absolute lattice times of lattice_times().

source_gate_derivative()[source]#

Return the analytic derivative of the gated source’s gate on the lattice.

Returns:

numpy.ndarray: Read-only g'(t_n) in 1/s, shape (samples,), of the gate of source_breakpoints(), at the absolute lattice times (solprop.grid.planck_taper_derivative()).

source_gate_derivative_error()[source]#

Return the rounding bound of source_gate_derivative() on the lattice.

Returns:

numpy.ndarray: Read-only nonnegative bound in 1/s, shape (samples,) (solprop.grid.planck_taper_derivative_error()).

spacing: float#

time_origin: float#

window_duration: float | None = None#

solprop.translate.tdse.TDSEPurpose#

The relation of an evaluated field to the optical integration or diagnostics.

alias of Literal[‘startup’, ‘predictor’, ‘corrected’, ‘diagnostic’]

class solprop.translate.tdse.TDSEResult(total_current, first_order_current, *, input_identity, configuration_identity, valid, shadow_orders, third_order_current=None, third_order_dipole=None, monitors_json='{}', outcomes_json='[]')[source]#

Bases: object

Own validated, read-only microscopic responses for all requested nodes.

All current arrays are in C m/s per represented atom and the dipole is in C m per represented atom. No calibration or density factor is present. Invalid samples are refused before this record can be consumed; the adapter records native failure information before constructing a normalized result.

Attributes:

total_currentnumpy.ndarray: Completed current, float64, shape (n_nodes, n_to).
first_order_currentnumpy.ndarray: Exact same-map first-order current with the same shape.
input_identitystr: Exact input-waveform identity.
configuration_identitystr: Resolved descriptor identity.
validnumpy.ndarray: Boolean validity at every row and sample, shape (n_nodes, n_to).
shadow_orderstuple of int: Available odd orders, including 1 and matching optional third-order data.
third_order_currentnumpy.ndarray or None: Exact same-map third-order current, required for cubic replacements.
third_order_dipolenumpy.ndarray or None: Third-order charge dipole, required for calibrated-dipole replacement.
monitors_jsonstr: Immutable JSON object describing available numerical monitors.
outcomes_jsonstr: Immutable JSON list of per-row provider outcomes.

configuration_identity: str#

first_order_current: Float[ndarray, 'n_nodes_first n_to_first']#

input_identity: str#

monitors_json: str = '{}'#

outcomes_json: str = '[]'#

shadow_orders: tuple[int, ...]#

third_order_current: Float[ndarray, 'n_nodes_third n_to_third'] | None = None#

third_order_dipole: Float[ndarray, 'n_nodes_dipole n_to_dipole'] | None = None#

total_current: Float[ndarray, 'n_nodes_total n_to_total']#

valid: Bool[ndarray, 'n_nodes_valid n_to_valid']#

solprop.translate.tdse.lattice_times(samples, spacing)[source]#

Return the fine response lattice’s sample times exactly as the grid forms them.

Parameters:

samplesint: Positive even number of fine samples.
spacingfloat: Positive fine spacing in s.

Returns:

numpy.ndarray: (n - samples / 2) * spacing in s, the same arithmetic as solprop.grid.FieldGrid.from_limits() and refine_response_grid().

solprop.translate.tdse.refine_response_grid(grid, sampling)[source]#

Refine the fine lattice while preserving every coarse coordinate and collar.

Parameters:

gridTimeGrid: Existing field grid, with its already realized physical time window.
samplingTDSESampling: Power-of-two refinement of the existing fine sample count.

Returns:

FieldGrid: Validated grid with unchanged coarse axes, period and collars. A factor of one returns the original grid. No duplicate endpoint is appended.

Raises:

TranslationError: If an envelope or an inconsistent grid is supplied.

solprop.translate.tdse.resolve_atomic_window(window, samples, spacing)[source]#

Resolve a declared window on a fine response lattice.

Parameters:

windowTDSEAtomicWindow: Declared duration and taper in s; the duration must be resolved.
samplesint: Fine samples of the full optical lattice.
spacingfloat: Fine spacing in s.

Returns:

AtomicWindowRecord: Sample range, endpoint times and gate breakpoints.

Raises:

TranslationError: If the duration is unresolved or exceeds the lattice period, or the window holds fewer than the provider’s four samples.

solprop.translate.tdse.waveform_identity(fields)[source]#

Hash the exact real host waveforms and their shape for diagnostic reuse.

Parameters:

fieldsnumpy.ndarray: Finite float64 fields in V/m, shape (n_nodes, n_to).

Returns:

str: SHA-256 identity independent of input strides and writeability.

Raises:

BackendError: If the field is empty, nonfinite, complex or not float64.