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.
TDSEDescriptor: the resolved response identity the route carries (solprop.translate.routes.TDSESource), with itsAtomicWindowRecord(resolve_atomic_window()) on the fine response lattice (refine_response_grid(),lattice_times()).TDSEBinding: the driver’s resource-owning atomic service, returningTDSEResultresponses and charging calls throughAtomicCallBudgetandAtomicCallLedger.waveform_identity()hashes host waveforms for diagnostic reuse.
The manual page is docs/guide/media/tdse.md; the binding is
docs/dev/kernel-contract.md section 6.
Module Attributes
The provider's gross-failure norm-growth limit pinned in every haCC setup record. |
|
The relation of an evaluated field to the optical integration or diagnostics. |
|
The one TDSE descriptor schema solprop writes and reads. |
Functions
|
Return the fine response lattice's sample times exactly as the grid forms them. |
|
Refine the fine lattice while preserving every coarse coordinate and collar. |
|
Resolve a declared window on a fine response lattice. |
|
Hash the exact real host waveforms and their shape for diagnostic reuse. |
Classes
|
Reserve whole trials and charge every provider attempt before invocation. |
|
Snapshot the binding's charged attempts and remaining trial reservation. |
|
Hold an atomic window resolved on one fine response lattice (SEP 20, 5.3). |
|
Provide the driver's explicit, resource-owning host atomic service. |
|
Carry a resolved response identity and primitive values across the seam. |
|
Own validated, read-only microscopic responses for all requested nodes. |
- class solprop.translate.tdse.AtomicCallBudget(limit, calls_per_evaluation)[source]#
Bases:
objectReserve whole trials and charge every provider attempt before invocation.
The binding calls
reservebefore a trial,begin_evaluationonce for each all-node evaluation, andchargeimmediately before each chunk’s provider call. On failure it callsrecord_failure; afinallyblock 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.
- 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.
- 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.
- class solprop.translate.tdse.AtomicCallLedger(limit, attempted, reserved, logical_evaluations, diagnostic_calls, failed_calls)[source]#
Bases:
objectSnapshot 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.
- 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.restorereleases 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.
- class solprop.translate.tdse.AtomicWindowRecord(duration, taper, start, stop, first, last, t_s, t_e, gate)[source]#
Bases:
objectHold an atomic window resolved on one fine response lattice (SEP 20, 5.3).
- Attributes:
- durationfloat
Nominal duration
T_ain s.- taperfloat
Width of each inner Planck taper in s.
- start, stopfloat
Nominal bounds
t_- = -T_a / 2andt_+ = T_a / 2in s.- first, lastint
Inclusive lattice indices of
t_s, the first sample at or aftert_-, andt_e, the last at or beforet_+.- 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]#
Realised atomic duration
t_e - t_s, s.Compared with a preset’s tested window.
- 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/dtin 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
gin[0, 1]: zero outside[t_-, t_+], one between the tapers.
- 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:
modelandatomic_window(nullfor the full lattice), with akind-tagged haCC basis. Version 5 is SEP 26’s version-4 layout without thesource_filterkey: the source form follows fromkerr_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:
ProtocolProvide the driver’s explicit, resource-owning host atomic service.
- 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);
Nonewhen the caller has none.
- Returns:
- TDSEResult
Validated owning microscopic arrays with no density or calibration.
- property ledger: AtomicCallLedger[source]#
Current immutable atomic-call accounting snapshot.
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.
- 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.
- 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:
objectCarry 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_jsonis 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.
- property atomic_window: AtomicWindowRecord | None[source]#
Resolved atomic window, or None for the full lattice.
Sample range, endpoint times and gate breakpoints in s.
- 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]#
Whether the source is gated and edge-free (SEP 26).
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.
- property model: Literal['sae', 'hacc'][source]#
Atomic model family recorded in the configuration.
The recorded
response.model.
- property response: TDSEGasResponse[source]#
Revalidated scientific response this descriptor carries.
Reconstructed record; its consistency policy is the default, because policy never enters a descriptor.
- 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 oflattice_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 ofsource_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()).
- 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:
objectOwn 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.
- first_order_current: Float[ndarray, 'n_nodes_first n_to_first']#
- 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) * spacingin s, the same arithmetic assolprop.grid.FieldGrid.from_limits()andrefine_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.