solprop.output.tdse_archive#

Archive every raw TDSE provider evaluation of a run in an HDF5 sidecar (SEP 20).

A TDSE run’s optical output holds the propagated field; this append-only sidecar holds what the atomic provider actually returned for each evaluation, before any validation, shadow subtraction, scaling, padding or reduction, beside the exact input it was given. It is a history of evaluations, not a restart store: the optical file’s call ledger stays authoritative for calls, budgets and resume, and the sidecar does no charge accounting.

Layout (schema TDSE_ARCHIVE_SCHEMA). The root carries schema and run_uuid. sessions/session_NNNNNN is one run or resume (or one standalone consistency check), with its context and, once it closes, the bytes written and the write time. Inside it evaluations/evaluation_NNNNNNNNN is one logical provider evaluation: its labels as attributes, prewindow_field (the full nodal field of the evaluation, V/m), gate when an atomic window applies, one chunk_NNN group per provider call holding drive (the exact float64 field passed, V/m) and raw (the returned record, through a versioned serializer), an exception group when the evaluation raised, and finally the outcome attribute. trials/trial_NNNNNNNNN records whether an optical trial was accepted or rejected, appended when the stepper decides. Shared immutable values – sample times, gates and structured records – are stored once per session under shared and hard-linked where they are used, so they read back unchanged.

Truncation. Groups are flushed as they complete. A crash leaves every earlier evaluation readable; an evaluation without its outcome, or missing a chunk or a dataset, is reported as incomplete by TDSEArchiveReader rather than failing the read.

The manual page is docs/guide/media/tdse.md.

Module Attributes

`TDSE_ARCHIVE_SCHEMA`	Schema identifier stored at the root of every archive this module writes.
`ARCHIVE_METADATA_CACHE_BYTES`	Upper bound of the HDF5 metadata cache of one open archive, bytes.
`SAE_GRID_RESPONSE`	The SAE provider's full record: dipole, currents, accelerations, plasma, shadow.
`SAE_TOTAL_CURRENT_RESPONSE`	The SAE provider's compact record: the total current and its odd shadow orders.
`HACC_GRID_RESPONSE`	The haCC provider's full record: dipole, in-box and total currents, lost norm.
`HACC_TOTAL_CURRENT_RESPONSE`	The haCC provider's compact record: the total current and its order one.

Functions

`open_tdse_archive`(path)	Open a TDSE archive for streaming reads.
`record_serializer`(model, outputs)	Return the serializer of a model's record for a native output selection.
`structured_json`(value)	Encode a structured provider record as sorted, valid JSON.
`writer_memory`(*, rows, samples)	Return an archive writer's bounded host buffers, for memory admission.

Classes

`ArchivedChunk`(index, row_start, row_stop, ...)	Describe one provider call of an archived evaluation.
`ArchivedEvaluation`(evaluation_id, session, ...)	Describe one archived provider evaluation without loading its arrays.
`ArchivedSession`(index, kind, run_uuid, ...)	Describe one session: a run, a resume or a standalone consistency check.
`RecordField`(name, kind[, unit, axes, ...])	Describe one attribute of a provider record and how it is stored.
`RecordSchema`(name, version, fields)	Name, version and fields of one explicit provider-record serializer.
`TDSEArchive`(path, *[, outputs])	Ask a TDSE run to archive every raw provider evaluation (SEP 20 section 5.8).
`TDSEArchiveReader`(path)	Read a TDSE archive one evaluation at a time.
`TDSEArchiveWriter`(file, archive, *, ...)	Write one session of a TDSE archive: one synchronous, append-only writer.

solprop.output.tdse_archive.ARCHIVE_METADATA_CACHE_BYTES = 4194304#

Upper bound of the HDF5 metadata cache of one open archive, bytes.

The writer stores every array as a contiguous, uncompressed dataset, so HDF5 keeps no raw-data chunk cache for it; its metadata cache is capped at this size when the file is opened. It is admitted with the binding’s memory.

class solprop.output.tdse_archive.ArchivedChunk(index, row_start, row_stop, serializer, absent)[source]#

Bases: object

Describe one provider call of an archived evaluation.

Attributes:

indexint: Chunk index within the evaluation.
row_start, row_stopint: Its radial rows, start inclusive, stop exclusive.
serializerstr or None: The serializer of its stored record, or None when no record was stored (the call raised, or the group is incomplete).
absenttuple of str: Optional top-level fields the provider returned as None.

absent: tuple[str, ...]#

index: int#

row_start: int#

row_stop: int#

serializer: str | None#

class solprop.output.tdse_archive.ArchivedEvaluation(evaluation_id, session, trial, role, evaluated_role, trial_outcome, z, density, labels, chunks, outcome, error, complete)[source]#

Bases: object

Describe one archived provider evaluation without loading its arrays.

Attributes:

evaluation_idint: Increasing through the file.
sessionint: The session it belongs to.
trialint or None: The optical trial within its session, or None for a consistency diagnostic.
role{‘startup’, ‘predictor’, ‘corrector’, ‘diagnostic’, ‘rejected’}: The evaluation’s role, rejected for a predictor or corrector whose trial the stepper then rejected.
evaluated_rolestr: The role as evaluated, before any rejection.
trial_outcome{‘accepted’, ‘rejected’} or None: The stepper’s decision on the trial, or None when none was recorded.
zfloat or None: Optical position in m, or None for a consistency diagnostic.
densityfloat or None: Number density at the evaluation in m^-3, or None when not supplied.
labelsmapping: Every stored label: identities, model, output selections and time map.
chunkstuple of ArchivedChunk: The provider calls, in row order.
outcome{‘returned’, ‘raised’} or None: How the evaluation ended; None for an incomplete group.
errormapping or None: The exception record of an evaluation that raised.
completebool: Whether the group holds everything its outcome promises; False for a group truncated by a crash or a failed write.

chunks: tuple[ArchivedChunk, ...]#

complete: bool#

density: float | None#

error: Mapping[str, object] | None#

evaluated_role: str#

evaluation_id: int#

labels: Mapping[str, object]#

outcome: Literal['returned', 'raised'] | None#

role: Literal['startup', 'predictor', 'corrector', 'diagnostic', 'rejected']#

session: int#

trial: int | None#

trial_outcome: Literal['accepted', 'rejected'] | None#

z: float | None#

class solprop.output.tdse_archive.ArchivedSession(index, kind, run_uuid, started, outputs, optical_reference, context, trials, closed, totals)[source]#

Bases: object

Describe one session: a run, a resume or a standalone consistency check.

Attributes:

indexint: Position in the file.
kind{‘run’, ‘resume’, ‘consistency_check’}: What it records.
run_uuidstr: The run’s identity.
startedstr: ISO 8601 start time.
outputs{‘full’, ‘required’}: The output selection.
optical_referencemapping or None: The archive’s path as the optical file records it, or None.
contextmapping: The session’s descriptor, quadrature, execution and provider facts.
trialsmapping of int to str: Each decided trial’s outcome.
closedbool: Whether the session closed normally and recorded its totals.
totalsmapping: bytes_written, array_bytes, write_seconds and evaluations of a closed session; empty otherwise.

closed: bool#

context: Mapping[str, object]#

index: int#

kind: Literal['run', 'resume', 'consistency_check']#

optical_reference: Mapping[str, object] | None#

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

run_uuid: str#

started: str#

totals: Mapping[str, object]#

trials: Mapping[int, str]#

solprop.output.tdse_archive.HACC_GRID_RESPONSE = RecordSchema(name='hacc.grid_response', version=1, fields=(RecordField(name='time', kind='array', unit='s', axes='n_time', optional=False, record=None), RecordField(name='vector_potential', kind='array', unit='V s/m', axes='n_row n_time', optional=False, record=None), RecordField(name='electric_field', kind='array', unit='V/m', axes='n_row n_time', optional=False, record=None), RecordField(name='charge_dipole', kind='array', unit='C m', axes='n_row n_time', optional=False, record=None), RecordField(name='current', kind='array', unit='C m/s', axes='n_row n_time', optional=False, record=None), RecordField(name='total_current', kind='array', unit='C m/s', axes='n_row n_time', optional=False, record=None), RecordField(name='outside', kind='array', unit='1', axes='n_row n_time', optional=False, record=None), RecordField(name='neglected_current_bound', kind='array', unit='C m/s', axes='n_row n_time', optional=True, record=None), RecordField(name='monitors', kind='record', unit='', axes='', optional=False, record=RecordSchema(name='hacc.row_monitors', version=1, fields=(RecordField(name='initial_norm', kind='array', unit='1', axes='n_row', optional=False, record=None), RecordField(name='norm', kind='array', unit='1', axes='n_row', optional=False, record=None), RecordField(name='peak_norm', kind='array', unit='1', axes='n_row', optional=False, record=None), RecordField(name='monitored_step', kind='array', unit='', axes='n_row', optional=False, record=None), RecordField(name='non_finite', kind='array', unit='', axes='n_row', optional=False, record=None)))), RecordField(name='outcomes', kind='outcomes', unit='', axes='', optional=False, record=None), RecordField(name='valid', kind='array', unit='', axes='n_row n_time', optional=False, record=None), RecordField(name='info', kind='structured', unit='', axes='', optional=False, record=None), RecordField(name='shadow', kind='record', unit='', axes='', optional=True, record=RecordSchema(name='hacc.shadow', version=1, fields=(RecordField(name='orders', kind='labels', unit='', axes='', optional=False, record=None), RecordField(name='charge_dipole', kind='array', unit='C m', axes='n_row n_order n_time', optional=False, record=None), RecordField(name='current', kind='array', unit='C m/s', axes='n_row n_order n_time', optional=False, record=None), RecordField(name='total_current', kind='array', unit='C m/s', axes='n_row n_order n_time', optional=True, record=None))))))#: The haCC provider’s full record: dipole, in-box and total currents, lost norm.

solprop.output.tdse_archive.HACC_TOTAL_CURRENT_RESPONSE = RecordSchema(name='hacc.total_current_response', version=1, fields=(RecordField(name='time', kind='array', unit='s', axes='n_time', optional=False, record=None), RecordField(name='total_current', kind='array', unit='C m/s', axes='n_row n_time', optional=False, record=None), RecordField(name='shadow_total_current', kind='array', unit='C m/s', axes='n_row n_order n_time', optional=True, record=None), RecordField(name='shadow_orders', kind='labels', unit='', axes='', optional=False, record=None), RecordField(name='radius', kind='scalar', unit='m', axes='', optional=False, record=None), RecordField(name='neglected_current_bound', kind='array', unit='C m/s', axes='n_row n_time', optional=True, record=None), RecordField(name='monitors', kind='record', unit='', axes='', optional=False, record=RecordSchema(name='hacc.row_monitors', version=1, fields=(RecordField(name='initial_norm', kind='array', unit='1', axes='n_row', optional=False, record=None), RecordField(name='norm', kind='array', unit='1', axes='n_row', optional=False, record=None), RecordField(name='peak_norm', kind='array', unit='1', axes='n_row', optional=False, record=None), RecordField(name='monitored_step', kind='array', unit='', axes='n_row', optional=False, record=None), RecordField(name='non_finite', kind='array', unit='', axes='n_row', optional=False, record=None)))), RecordField(name='outcomes', kind='outcomes', unit='', axes='', optional=False, record=None), RecordField(name='valid', kind='array', unit='', axes='n_row n_time', optional=False, record=None), RecordField(name='info', kind='structured', unit='', axes='', optional=False, record=None)))#: The haCC provider’s compact record: the total current and its order one.

class solprop.output.tdse_archive.RecordField(name, kind, unit='', axes='', optional=False, record=None)[source]#

Bases: object

Describe one attribute of a provider record and how it is stored.

Attributes:

namestr: The attribute name on the provider record.
kind{‘array’, ‘scalar’, ‘labels’, ‘outcomes’, ‘structured’, ‘record’}: An owning array stored with its dtype and shape; a number stored as a zero-dimensional dataset of its dtype; a tuple of integer order labels; the per-row outcome records; a structured record (info) stored as JSON; or a nested record with its own schema.
unitstr: SI unit of an array or scalar ("1" for a dimensionless one, "" for none, such as a validity mask or a step index).
axesstr: Axis names of an array, in the shared vocabulary.
optionalbool: Whether the provider may return None; an absent value is listed in the stored group’s absent attribute.
recordRecordSchema or None: The schema of a nested record.

axes: str = ''#

kind: Literal['array', 'scalar', 'labels', 'outcomes', 'structured', 'record']#

name: str#

optional: bool = False#

record: RecordSchema | None = None#

unit: str = ''#

class solprop.output.tdse_archive.RecordSchema(name, version, fields)[source]#

Bases: object

Name, version and fields of one explicit provider-record serializer.

Attributes:

namestr: Record name, such as "sae.grid_response".
versionint: Serializer version; a change of the stored fields or their meaning bumps it.
fieldstuple of RecordField: Every attribute stored, in order.

fields: tuple[RecordField, ...]#

name: str#

property serializer: str[source]#

Return the identifier written beside every record stored with this schema.

Returns:

str: solprop.tdse-archive.<name>.v<version>.

version: int#

solprop.output.tdse_archive.SAE_GRID_RESPONSE = RecordSchema(name='sae.grid_response', version=1, fields=(RecordField(name='time', kind='array', unit='s', axes='n_time', optional=False, record=None), RecordField(name='vector_potential', kind='array', unit='V s/m', axes='n_row n_time', optional=False, record=None), RecordField(name='electric_field', kind='array', unit='V/m', axes='n_row n_time', optional=False, record=None), RecordField(name='charge_dipole', kind='array', unit='C m', axes='n_row n_time', optional=False, record=None), RecordField(name='current', kind='array', unit='C m/s', axes='n_row n_time', optional=False, record=None), RecordField(name='dipole_acceleration', kind='array', unit='C m/s^2', axes='n_row n_time', optional=False, record=None), RecordField(name='outside', kind='array', unit='1', axes='n_row n_time', optional=False, record=None), RecordField(name='plasma', kind='record', unit='', axes='', optional=False, record=RecordSchema(name='sae.plasma_response', version=1, fields=(RecordField(name='radius', kind='scalar', unit='m', axes='', optional=False, record=None), RecordField(name='potential_slope_bound', kind='scalar', unit='J/m', axes='', optional=False, record=None), RecordField(name='inbox_acceleration', kind='array', unit='C m/s^2', axes='n_row n_time', optional=False, record=None), RecordField(name='free_acceleration', kind='array', unit='C m/s^2', axes='n_row n_time', optional=False, record=None), RecordField(name='total_acceleration', kind='array', unit='C m/s^2', axes='n_row n_time', optional=False, record=None), RecordField(name='inbox_current', kind='array', unit='C m/s', axes='n_row n_time', optional=False, record=None), RecordField(name='free_current', kind='array', unit='C m/s', axes='n_row n_time', optional=False, record=None), RecordField(name='total_current', kind='array', unit='C m/s', axes='n_row n_time', optional=False, record=None), RecordField(name='outside_integral', kind='array', unit='s', axes='n_row n_time', optional=False, record=None), RecordField(name='neglected_acceleration_bound', kind='array', unit='C m/s^2', axes='n_row n_time', optional=False, record=None), RecordField(name='neglected_current_bound', kind='array', unit='C m/s', axes='n_row n_time', optional=False, record=None)))), RecordField(name='cut_term', kind='scalar', unit='1', axes='', optional=False, record=None), RecordField(name='monitors', kind='record', unit='', axes='', optional=False, record=RecordSchema(name='sae.row_monitors', version=1, fields=(RecordField(name='initial_norm', kind='array', unit='1', axes='n_row', optional=False, record=None), RecordField(name='norm', kind='array', unit='1', axes='n_row', optional=False, record=None), RecordField(name='peak_norm', kind='array', unit='1', axes='n_row', optional=False, record=None), RecordField(name='field_free_energy', kind='array', unit='J', axes='n_row', optional=False, record=None), RecordField(name='monitored_step', kind='array', unit='', axes='n_row', optional=False, record=None), RecordField(name='removed_component', kind='array', unit='1', axes='n_row', optional=True, record=None), RecordField(name='step_error_estimate', kind='array', unit='1', axes='n_row', optional=True, record=None), RecordField(name='peak_step_error_estimate', kind='array', unit='1', axes='n_row', optional=True, record=None)))), RecordField(name='outcomes', kind='outcomes', unit='', axes='', optional=False, record=None), RecordField(name='valid', kind='array', unit='', axes='n_row n_time', optional=False, record=None), RecordField(name='info', kind='structured', unit='', axes='', optional=False, record=None), RecordField(name='shadow', kind='record', unit='', axes='', optional=True, record=RecordSchema(name='sae.perturbative_shadow', version=1, fields=(RecordField(name='orders', kind='labels', unit='', axes='', optional=False, record=None), RecordField(name='radius', kind='scalar', unit='m', axes='', optional=False, record=None), RecordField(name='charge_dipole', kind='array', unit='C m', axes='n_row n_order n_time', optional=False, record=None), RecordField(name='current', kind='array', unit='C m/s', axes='n_row n_order n_time', optional=False, record=None), RecordField(name='total_acceleration', kind='array', unit='C m/s^2', axes='n_row n_order n_time', optional=False, record=None), RecordField(name='total_current', kind='array', unit='C m/s', axes='n_row n_order n_time', optional=True, record=None))))))#: The SAE provider’s full record: dipole, currents, accelerations, plasma, shadow.

solprop.output.tdse_archive.SAE_TOTAL_CURRENT_RESPONSE = RecordSchema(name='sae.total_current_response', version=1, fields=(RecordField(name='time', kind='array', unit='s', axes='n_time', optional=False, record=None), RecordField(name='total_current', kind='array', unit='C m/s', axes='n_row n_time', optional=False, record=None), RecordField(name='shadow_total_current', kind='array', unit='C m/s', axes='n_row n_order n_time', optional=True, record=None), RecordField(name='shadow_orders', kind='labels', unit='', axes='', optional=False, record=None), RecordField(name='radius', kind='scalar', unit='m', axes='', optional=False, record=None), RecordField(name='potential_slope_bound', kind='scalar', unit='J/m', axes='', optional=False, record=None), RecordField(name='neglected_acceleration_bound', kind='array', unit='C m/s^2', axes='n_row n_time', optional=False, record=None), RecordField(name='neglected_current_bound', kind='array', unit='C m/s', axes='n_row n_time', optional=False, record=None), RecordField(name='monitors', kind='record', unit='', axes='', optional=False, record=RecordSchema(name='sae.row_monitors', version=1, fields=(RecordField(name='initial_norm', kind='array', unit='1', axes='n_row', optional=False, record=None), RecordField(name='norm', kind='array', unit='1', axes='n_row', optional=False, record=None), RecordField(name='peak_norm', kind='array', unit='1', axes='n_row', optional=False, record=None), RecordField(name='field_free_energy', kind='array', unit='J', axes='n_row', optional=False, record=None), RecordField(name='monitored_step', kind='array', unit='', axes='n_row', optional=False, record=None), RecordField(name='removed_component', kind='array', unit='1', axes='n_row', optional=True, record=None), RecordField(name='step_error_estimate', kind='array', unit='1', axes='n_row', optional=True, record=None), RecordField(name='peak_step_error_estimate', kind='array', unit='1', axes='n_row', optional=True, record=None)))), RecordField(name='outcomes', kind='outcomes', unit='', axes='', optional=False, record=None), RecordField(name='valid', kind='array', unit='', axes='n_row n_time', optional=False, record=None), RecordField(name='info', kind='structured', unit='', axes='', optional=False, record=None)))#: The SAE provider’s compact record: the total current and its odd shadow orders.

class solprop.output.tdse_archive.TDSEArchive(path, *, outputs='full')[source]#

Bases: object

Ask a TDSE run to archive every raw provider evaluation (SEP 20 section 5.8).

Passed as tdse_archive= to solprop.driver.simulation.Simulation.run(), solprop.driver.interface.prop_capillary() or solprop.driver.tdse_consistency.check_consistency(). The archive is a separate, append-only HDF5 file; it changes neither the propagation nor the call ledger, and its path and output selection are execution provenance, not part of any physical identity.

Parameters:

pathpathlib.Path or str: Where the archive is written. It must differ from the optical HDF5 file. An existing file is continued only when it is this run’s archive (a resume); any other existing file is refused, never overwritten.
outputs{‘full’, ‘required’}, optional: "full" (the default) asks the same provider evaluations for the provider’s full observable record and stores all of it; "required" keeps the provider’s output selection that the source policy needs and stores every field it returns. Neither adds a provider call, a shadow order or a change to the atomic state.

Attributes:

pathpathlib.Path: The archive’s path, as given.
outputs{‘full’, ‘required’}: The output selection.

Raises:

TypeError: If path is not a path or a string.
ValueError: If path is empty or outputs is neither selection.

Examples

>>> from solprop.output import TDSEArchive
>>> archive = TDSEArchive("run.tdse.h5", outputs="required")
>>> archive.path.name, archive.outputs
('run.tdse.h5', 'required')

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

path: Path#

class solprop.output.tdse_archive.TDSEArchiveReader(path)[source]#

Bases: object

Read a TDSE archive one evaluation at a time.

Built by open_tdse_archive(). Enumerating sessions and evaluations reads only their labels; arrays are loaded on request, one at a time, so a reader never holds a whole run. Use it as a context manager or call close().

Parameters:

pathpathlib.Path or str: The archive.

Raises:

TDSEArchiveError: If the file is not a TDSE archive of a known schema.

close()[source]#

Close the file; repeated calls are harmless.

evaluations()[source]#

Yield every evaluation of every session in order, labels only.

Yields:

ArchivedEvaluation: One per evaluation group; an incomplete group is yielded with complete=False, not raised.

load(evaluation, name, *, chunk=None)[source]#

Load one array of an evaluation, exactly as stored.

Parameters:

evaluationArchivedEvaluation: The evaluation, from evaluations().
namestr: "prewindow_field" or "gate" without a chunk; with a chunk, "drive" or a path into the raw record, such as "total_current", "plasma/total_current" or "shadow/current".
chunkint or None, optional: The chunk index, for a chunk’s arrays.

Returns:

numpy.ndarray: The array with its stored dtype and shape (zero-dimensional for a scalar).

Raises:

TDSEArchiveError: If no such array was stored.

raw(evaluation, chunk)[source]#

Load one chunk’s whole stored record.

Parameters:

evaluationArchivedEvaluation: The evaluation.
chunkint: The chunk index.

Returns:

dict: Field name to array (stored dtype), scalar, order labels (tuple), outcomes (list of dicts), info (dict) or nested record (dict); an absent optional field is None. The serializer key names the serializer.

Raises:

TDSEArchiveError: If the chunk stored no record.

property run_uuid: str[source]#

Return the run’s identity, shared with its optical file.

Returns:

str: The UUID.

property schema: str[source]#

Return the archive’s schema identifier.

Returns:

str: TDSE_ARCHIVE_SCHEMA.

property sessions: tuple[ArchivedSession, ...][source]#

Return every session of the archive, in order.

Returns:

tuple of ArchivedSession: Their labels, trial decisions and totals.

property truncated: bool[source]#

Return whether any evaluation group is incomplete.

Returns:

bool: True when a crash or a failed write left a group incomplete.

class solprop.output.tdse_archive.TDSEArchiveWriter(file, archive, *, run_uuid, session, index, first_evaluation, optical, start_size)[source]#

Bases: object

Write one session of a TDSE archive: one synchronous, append-only writer.

Built with open(). Every method writes through to the file and flushes at the end of each group, keeping no array after it returns. The first failure marks the writer failed: every later write, and ensure_writable(), which the binding calls before each provider call, raise TDSEArchiveError, so the run stops before its next provider call.

Parameters:

fileh5py.File: The open archive.
archiveTDSEArchive: The request.
run_uuidstr: The run’s identity, shared with the optical file.
sessionh5py.Group: This session’s group.
indexint: This session’s index in the file.
first_evaluationint: The identifier of this session’s first evaluation.
opticalpathlib.Path or None: The optical HDF5 file, for the relative reference.
start_sizeint: The file’s size before this session, bytes.

begin_evaluation(labels, *, prewindow, drives, gate, binding)[source]#

Begin one evaluation group with its labels and complete input.

Written before the first provider call of the evaluation, so an evaluation that raises still has its input.

Parameters:

labelsmapping: Scalar labels: role, trial, z, density, identities, time map.
prewindownumpy.ndarray: The evaluation’s full nodal field in V/m, before slicing and gating.
drivessequence of tuple: (row_start, row_stop, drive) for every provider chunk, with the exact float64 field it will be passed, V/m.
gatenumpy.ndarray or None: The atomic window’s gate on the lattice, or None.
bindingmapping: Build, execution, plan and chunk records, stored once per session.

Returns:

int: The evaluation’s identifier, increasing through the file.

Raises:

TDSEArchiveError: If the input cannot be written.

close()[source]#

Record the session’s totals and close the file; repeated calls are harmless.

Raises:

TDSEArchiveError: If totals or closure fail. Closure is always attempted; a handle that cannot close retains writer ownership until a successful retry.

ensure_writable()[source]#

Refuse to continue after a write failure.

Raises:

TDSEArchiveError: The first failure, again, so no provider call follows it.

property failed: bool[source]#

Return whether a write has failed.

Returns:

bool: True once any write raised.

finish_evaluation(evaluation, outcome)[source]#

Mark an evaluation complete: the last write of its group.

Parameters:

evaluationint: The evaluation identifier.
outcome{‘returned’, ‘raised’}: Whether every chunk returned and validated, or the evaluation raised.

Raises:

TDSEArchiveError: If the attribute cannot be written.

memory_ledger(*, rows, samples)[source]#

Return the writer’s bounded host buffers for memory admission.

Parameters:

rowsint: Largest provider chunk, rows.
samplesint: Largest per-row sample count.

Returns:

dict: writer_memory() of the largest chunk.

classmethod open(archive, *, run_uuid, kind, optical, context, resume=False)[source]#

Open or create the archive and append a new session group.

Parameters:

archiveTDSEArchive: Path and output selection.
run_uuidstr: The run’s identity. An existing file is continued only with resume and only when it carries this identity.
kind{‘run’, ‘resume’, ‘consistency_check’}: What the session records.
opticalpathlib.Path or None: The optical HDF5 file, or None.
contextmapping: JSON-compatible facts of the session: the descriptor, quadrature, execution and provider pin.
resumebool, optional: Whether an existing archive of this run may be continued.

Returns:

TDSEArchiveWriter: The writer of the new session.

Raises:

TDSEArchiveError: If the path exists and is not this run’s archive (or is not to be continued), or the file cannot be created or written.

property outputs: Literal['full', 'required'][source]#

Return the output selection.

Returns:

{‘full’, ‘required’}: The request’s selection.

property path: Path[source]#

Return the archive’s path.

Returns:

pathlib.Path: As requested.

record_trial(trial, *, accepted, evaluations)[source]#

Append the decision on one optical trial.

Parameters:

trialint: The trial’s identifier in this session.
acceptedbool: Whether the stepper accepted it.
evaluationssequence of int: The evaluations made in it.

Raises:

TDSEArchiveError: If the record cannot be written.

reference()[source]#

Return the record of this archive the optical file keeps.

Returns:

dict: The schema, the run identity, the path (relative to the optical file when there is one), the output selection, the session, and the bytes written, array bytes, write time and evaluation count so far.

reopen()[source]#

Reopen the same session, retaining all evaluation and trial identifiers.

Raises:

TDSEArchiveError: If the file changed or cannot be reopened safely.

property run_uuid: str[source]#

Return the run’s identity.

Returns:

str: Shared with the optical file.

suspend()[source]#

Close the handle without ending this session or releasing ownership.

Raises:

TDSEArchiveError: If an evaluation is in flight or the writer cannot be suspended.

write_failure(evaluation, *, chunk, error, classification)[source]#

Store the exception that ended an evaluation.

Parameters:

evaluationint: The evaluation identifier.
chunkint or None: The chunk whose call or validation raised, or None.
errorBaseException: The exception.
classificationstr: native, interface, contract or unexpected.

Raises:

TDSEArchiveError: If the record cannot be written; the caller keeps its own error primary.

write_result(evaluation, chunk, raw, schema)[source]#

Store one provider chunk’s returned record, before any validation.

Parameters:

evaluationint: The evaluation identifier.
chunkint: The chunk index.
rawobject: The provider’s returned record, exactly as returned.
schemaRecordSchema: Its explicit serializer.

Raises:

TDSEArchiveError: If the record does not match its serializer, or cannot be written.

solprop.output.tdse_archive.TDSE_ARCHIVE_SCHEMA = 'solprop.tdse-archive.v1'#: Schema identifier stored at the root of every archive this module writes.

solprop.output.tdse_archive.open_tdse_archive(path)[source]#

Open a TDSE archive for streaming reads.

Parameters:

pathpathlib.Path or str: The archive written beside a run.

Returns:

TDSEArchiveReader: The reader; close it, or use it as a context manager.

Raises:

TDSEArchiveError: If the file cannot be read or is not a TDSE archive.

Examples

>>> from solprop.output import open_tdse_archive
>>> with open_tdse_archive(path) as archive:
...     for evaluation in archive.evaluations():
...         current = archive.load(evaluation, "total_current", chunk=0)

solprop.output.tdse_archive.record_serializer(model, outputs)[source]#

Return the serializer of a model’s record for a native output selection.

Parameters:

model{‘sae’, ‘hacc’}: The atomic model.
outputs{‘full’, ‘total_current’}: The provider’s construction-time output selection.

Returns:

RecordSchema: The explicit, versioned serializer.

Raises:

TDSEArchiveError: If no serializer exists for the pair.

Examples

>>> from solprop.output.tdse_archive import record_serializer
>>> record_serializer("hacc", "full").serializer
'solprop.tdse-archive.hacc.grid_response.v1'

solprop.output.tdse_archive.structured_json(value)[source]#

Encode a structured provider record as sorted, valid JSON.

Dataclasses and namespaces become objects, arrays and tuples become lists, non-finite floats become the strings "nonfinite:nan", "nonfinite:inf" and "nonfinite:-inf", and any other object becomes {"type": ..., "repr": ...}, so a structured diagnostic never stops the archive.

Parameters:

valueobject: The record.

Returns:

str: JSON text.

solprop.output.tdse_archive.writer_memory(*, rows, samples)[source]#

Return an archive writer’s bounded host buffers, for memory admission.

Parameters:

rowsint: Largest provider chunk, rows.
samplesint: Largest per-row sample count.

Returns:

dict: archive.metadata_cache, the HDF5 metadata cache cap (ARCHIVE_METADATA_CACHE_BYTES), and archive.conversion_buffer, one copy of the largest stored array (an (n_row, n_order, n_time) float64 shadow of up to three orders), bytes. The writer keeps no array after a write returns.

Examples

>>> from solprop.output.tdse_archive import writer_memory
>>> writer_memory(rows=2, samples=100)["archive.conversion_buffer"]
4800