scpn_fusion.io – Data Interop

The IO subpackage provides data-interoperability adapters for the IMAS (Integrated Modelling & Analysis Suite) data exchange standard used in the fusion community.

Complete FAIR-MAST Magnetic Archives

The complete magnetic archive surface preserves every source object, decoded array and native clock. It is evidence transport only and carries no actuation authority.

Strict canonical codec for complete FAIR-MAST magnetic archive envelopes.

class scpn_fusion.io.mast_magnetic_archive_codec.MastCompleteMagneticArchiveEnvelope(_canonical_bytes)[source]

Bases: object

Validated immutable transport bytes for one complete magnetic archive group.

Parameters:

_canonical_bytes (bytes)

to_bytes()[source]

Return the exact canonical UTF-8 transport bytes.

Return type:

bytes

property sha256: str

Return the SHA-256 identity of the complete envelope bytes.

property document: dict[str, None | bool | int | float | str | list[None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]] | dict[str, None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]]]

Return a defensive copy of the validated JSON document.

property payload: dict[str, None | bool | int | float | str | list[None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]] | dict[str, None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]]]

Return a defensive copy of the validated payload.

exception scpn_fusion.io.mast_magnetic_archive_codec.MastMagneticArchiveValidationError[source]

Bases: ValueError

Raised when a magnetic archive envelope is incomplete or noncanonical.

scpn_fusion.io.mast_magnetic_archive_codec.canonical_json_bytes(value)[source]

Encode finite JSON with sorted keys, compact separators and one newline.

Return type:

bytes

Parameters:

value (None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue])

scpn_fusion.io.mast_magnetic_archive_codec.decode_mast_complete_magnetic_archive_envelope(data)[source]

Decode canonical bytes and reject any structural or semantic drift.

Return type:

MastCompleteMagneticArchiveEnvelope

Parameters:

data (bytes)

scpn_fusion.io.mast_magnetic_archive_codec.encode_mast_complete_magnetic_archive_envelope(payload)[source]

Validate a complete payload and bind it to canonical transport bytes.

Return type:

MastCompleteMagneticArchiveEnvelope

Parameters:

payload (Mapping[str, None | bool | int | float | str | list[None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]] | dict[str, None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]]])

scpn_fusion.io.mast_magnetic_archive_codec.mast_complete_magnetic_archive_sha256(data)[source]

Return the SHA-256 digest of transport or source bytes.

Return type:

str

Parameters:

data (bytes)

scpn_fusion.io.mast_magnetic_archive_codec.validate_mast_complete_magnetic_archive_payload(payload)[source]

Validate completeness, source fidelity and permanent non-actuating authority.

Return type:

None

Parameters:

payload (dict[str, None | bool | int | float | str | list[None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]] | dict[str, None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]]])

Capture every object and decoded array in a FAIR-MAST magnetics group.

exception scpn_fusion.io.mast_magnetic_archive.MastMagneticArchiveDependencyError[source]

Bases: ImportError

Raised when the safe Zarr-v3 MAST dependency profile is unavailable.

scpn_fusion.io.mast_magnetic_archive.build_mast_complete_magnetic_archive_envelope(provenance_path, shot_archive_root)[source]

Verify, decode and describe one complete authentic magnetic archive group.

Parameters:

  • provenance_path (Path) – Exact tracked parent provenance manifest containing every source object.

  • shot_archive_root (Path) – Local root of the fully materialised <shot>.zarr archive.

Returns:

Canonical review-only envelope binding all archive objects and arrays.

Return type:

MastCompleteMagneticArchiveEnvelope

Raises:
scpn_fusion.io.mast_magnetic_archive.verify_mast_complete_magnetic_archive_source(envelope, shot_archive_root)[source]

Reverify every declared object and reject undeclared local archive objects.

Return type:

None

Parameters:

Materialise a complete FAIR-MAST magnetic group from a tracked manifest.

exception scpn_fusion.io.mast_magnetic_archive_acquisition.MastMagneticArchiveAcquisitionError[source]

Bases: RuntimeError

Raised when a complete authenticated source group cannot be acquired.

scpn_fusion.io.mast_magnetic_archive_acquisition.acquire_mast_complete_magnetic_archive(provenance_path, archive_parent, *, attempts=3, timeout_seconds=60.0)[source]

Download every declared magnetic object and return its verified envelope.

Existing objects are reused only after exact byte-count and SHA-256 checks. A corrupt object is atomically replaced; undeclared local objects are never removed and cause the final complete-group verifier to fail closed.

Return type:

MastCompleteMagneticArchiveEnvelope

Parameters:

  • provenance_path (Path)

  • archive_parent (Path)

  • attempts (int)

  • timeout_seconds (float)

The separate qualification surface derives every supported mapping, applied transform, Level-2 archive-grid, empirical-quality, identifier-correspondence, source-validity and unresolved-field fact without granting phase or actuation authority.

Canonical codec for FAIR-MAST magnetic diagnostic qualification evidence.

exception scpn_fusion.io.mast_magnetic_qualification_codec.MastMagneticDiagnosticQualificationError[source]

Bases: ValueError

Raised when diagnostic qualification evidence is incomplete or noncanonical.

class scpn_fusion.io.mast_magnetic_qualification_codec.MastMagneticDiagnosticQualification(_canonical_bytes)[source]

Bases: object

Validated immutable qualification evidence for one complete archive envelope.

Parameters:

_canonical_bytes (bytes)

to_bytes()[source]

Return the exact canonical UTF-8 bytes.

Return type:

bytes

property sha256: str

Return the SHA-256 identity of the canonical document.

property document: dict[str, None | bool | int | float | str | list[None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]] | dict[str, None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]]]

Return a defensive copy of the qualification document.

property payload: dict[str, None | bool | int | float | str | list[None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]] | dict[str, None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]]]

Return a defensive copy of the validated payload.

scpn_fusion.io.mast_magnetic_qualification_codec.encode_mast_magnetic_diagnostic_qualification(payload)[source]

Validate qualification evidence and bind it to canonical transport bytes.

Return type:

MastMagneticDiagnosticQualification

Parameters:

payload (Mapping[str, None | bool | int | float | str | list[None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]] | dict[str, None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]]])

scpn_fusion.io.mast_magnetic_qualification_codec.decode_mast_magnetic_diagnostic_qualification(data)[source]

Decode canonical qualification bytes and reject structural or semantic drift.

Return type:

MastMagneticDiagnosticQualification

Parameters:

data (bytes)

scpn_fusion.io.mast_magnetic_qualification_codec.validate_mast_magnetic_diagnostic_qualification_payload(payload)[source]

Validate exact source binding, evidence completeness and non-actuating authority.

Return type:

None

Parameters:

payload (dict[str, None | bool | int | float | str | list[None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]] | dict[str, None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]]])

Derive source-bound qualification evidence without inventing diagnostic authority.

scpn_fusion.io.mast_magnetic_qualification.build_mast_magnetic_diagnostic_qualification(archive_envelope, shot_archive_root, ingestion_mapping_path)[source]

Build diagnostic qualification evidence for one complete FAIR-MAST archive.

Parameters:

  • archive_envelope (MastCompleteMagneticArchiveEnvelope | bytes) – Validated complete magnetic archive envelope or its canonical bytes.

  • shot_archive_root (Path) – Fully materialised <shot>.zarr root used to measure data quality.

  • ingestion_mapping_path (Path) – Exact mappings/level2/mast.yml from the envelope’s source revision.

Returns:

Canonical review-only evidence binding every archive array and measurement.

Return type:

MastMagneticDiagnosticQualification

Raises:
scpn_fusion.io.mast_magnetic_qualification.verify_mast_magnetic_diagnostic_qualification(expected, archive_envelope, shot_archive_root, ingestion_mapping_path)[source]

Rebuild qualification evidence and require byte-identical canonical output.

Return type:

None

Parameters:

IMAS Connector

Facade API for IMAS/IDS adapter modules.

This module intentionally stays as a stable import surface while implementation is decomposed into focused submodules:

  • imas_connector_common: validation/coercion primitives

  • imas_connector_digital_twin: summary/state IDS mappings

  • imas_connector_equilibrium: GEQDSK <-> IMAS equilibrium

  • imas_connector_transport: core_profiles/summary/core_transport

  • imas_connector_storage: JSON I/O helpers

  • imas_connector_omas: OMAS bridge

  • omas_free_boundary_inputs: strict PF/magnetics acquisition contract

scpn_fusion.io.imas_connector.validate_ids_payload(payload)[source]

Validate a complete IDS payload shape and units.

Ensures required top-level fields, nested structures, and numeric coercion constraints are satisfied. This function performs strict checks for time-slice ordering at the millisecond level and required equilibrium / performance keys.

Return type:

None

Parameters:

payload (Mapping[str, Any])

scpn_fusion.io.imas_connector.digital_twin_summary_to_ids(summary, *, machine='ITER', shot=0, run=0)[source]

Map an internal digital-twin summary into an IDS-like payload.

Returns a shallow canonicalised mapping that includes the equilibrium and performance fields required by validate_ids_payload().

Return type:

dict[str, Any]

Parameters:
scpn_fusion.io.imas_connector.digital_twin_state_to_ids(state, *, machine='ITER', shot=0, run=0)[source]

Map a detailed digital-twin state + profiles into an IDS-like payload.

Accepts full internal state records, including optional 1-D profile fields, and delegates to digital_twin_summary_to_ids() before attaching the validated equilibrium.profiles_1d payload.

Return type:

dict[str, Any]

Parameters:
scpn_fusion.io.imas_connector.ids_to_digital_twin_summary(payload)[source]

Convert an IDS-like payload into internal digital-twin summary shape.

Return type:

dict[str, Any]

Parameters:

payload (Mapping[str, Any])

scpn_fusion.io.imas_connector.ids_to_digital_twin_state(payload)[source]

Convert IDS payload into detailed digital-twin state with optional profiles.

Return type:

dict[str, Any]

Parameters:

payload (Mapping[str, Any])

scpn_fusion.io.imas_connector.digital_twin_history_to_ids(history, *, machine='ITER', shot=0, run=0)[source]

Convert a local digital-twin history into IDS payload sequence form.

Return type:

list[dict[str, Any]]

Parameters:
scpn_fusion.io.imas_connector.digital_twin_history_to_ids_pulse(history, *, machine='ITER', shot=0, run=0)[source]

Convert digital-twin history into a single IDS pulse payload.

Return type:

dict[str, Any]

Parameters:
scpn_fusion.io.imas_connector.ids_to_digital_twin_history(payloads)[source]

Convert a sequence of IDS payloads back to digital-twin snapshots.

Return type:

list[dict[str, Any]]

Parameters:

payloads (Sequence[Mapping[str, Any]])

scpn_fusion.io.imas_connector.ids_pulse_to_digital_twin_history(pulse)[source]

Convert IDS pulse payload into a sequence of digital-twin snapshots.

Return type:

list[dict[str, Any]]

Parameters:

pulse (Mapping[str, Any])

scpn_fusion.io.imas_connector.validate_ids_payload_sequence(payloads)[source]

Validate a strictly monotonic sequence of IDS payloads.

The function enforces: - required payload schema fields - shared machine / shot / run identity across the sequence - strictly increasing time index and time value

Return type:

None

Parameters:

payloads (Sequence[Mapping[str, Any]])

scpn_fusion.io.imas_connector.validate_ids_pulse_payload(pulse)[source]

Validate IDS pulse payload integrity and consistency constraints.

Return type:

None

Parameters:

pulse (Mapping[str, Any])

scpn_fusion.io.imas_connector.geqdsk_to_imas_equilibrium(eq, *, time_s=0.0, shot=0, run=0)[source]

Convert a GEqdsk equilibrium to an IMAS Data Dictionary equilibrium IDS.

Return type:

dict[str, Any]

Parameters:
scpn_fusion.io.imas_connector.imas_equilibrium_to_geqdsk(ids)[source]

Convert an IMAS Data Dictionary equilibrium IDS back to a GEqdsk.

Return type:

GEqdsk

Parameters:

ids (Mapping[str, Any])

scpn_fusion.io.imas_connector.state_to_imas_core_profiles(state, *, time_s=0.0)[source]

Convert a plasma state dict to an IMAS core_profiles IDS.

Return type:

dict[str, Any]

Parameters:
scpn_fusion.io.imas_connector.state_to_imas_summary(state)[source]

Convert a performance/state dict to an IMAS summary IDS.

Return type:

dict[str, Any]

Parameters:

state (Mapping[str, Any])

scpn_fusion.io.imas_connector.state_to_imas_core_transport(state, *, time_s=0.0)[source]

Convert a plasma state dict to an IMAS core_transport IDS.

Return type:

dict[str, Any]

Parameters:
scpn_fusion.io.imas_connector.imas_core_transport_to_state(ids)[source]

Convert an IMAS core_transport IDS back to a state dict.

Return type:

dict[str, Any]

Parameters:

ids (Mapping[str, Any])

scpn_fusion.io.imas_connector.write_ids(ids_dict, path)[source]

Write an IDS dict to a JSON file with schema validation.

Return type:

None

Parameters:
scpn_fusion.io.imas_connector.read_ids(path)[source]

Read an IDS JSON file and validate minimal schema.

Return type:

dict[str, Any]

Parameters:

path (str | Path)

scpn_fusion.io.imas_connector.ids_to_omas_core_profiles(ids_dict)[source]

Convert an IMAS core_profiles IDS dict to an OMAS ODS.

Return type:

Any

Parameters:

ids_dict (Mapping[str, Any])

scpn_fusion.io.imas_connector.ids_to_omas_equilibrium(ids_dict)[source]

Convert an IMAS equilibrium IDS dict to an OMAS ODS.

Return type:

Any

Parameters:

ids_dict (Mapping[str, Any])

scpn_fusion.io.imas_connector.omas_core_profiles_to_ids(ods)[source]

Convert OMAS ODS core_profiles data back to an IDS dict.

Return type:

dict[str, Any]

Parameters:

ods (Any)

scpn_fusion.io.imas_connector.omas_equilibrium_to_ids(ods)[source]

Convert OMAS ODS equilibrium data back to an IDS dict.

Return type:

dict[str, Any]

Parameters:

ods (Any)

class scpn_fusion.io.imas_connector.FluxLoopInput(identifier, r_m, z_m, flux_wb)[source]

Bases: object

Flux-loop geometry and poloidal-flux history.

Parameters:
identifier: str
r_m: tuple[float, ...]
z_m: tuple[float, ...]
flux_wb: TimeSeriesSI
class scpn_fusion.io.imas_connector.OmasFreeBoundaryInputs(schema, cocos, imas_version, provenance, time_alignment, pf_coils, bpol_probes, flux_loops, ingestion_blockers, ingestion_ready, tier0_claim_blockers, tier0_claim_admission_ready, payload_sha256)[source]

Bases: object

Validated OMAS channels with distinct ingestion and Tier-0 states.

Parameters:
schema: str
cocos: int
imas_version: str | None
provenance: OmasSourceProvenance | None
time_alignment: Literal['native_unaligned', 'exact_common_axis']
pf_coils: tuple[PfCoilInput, ...]
bpol_probes: tuple[PoloidalFieldProbeInput, ...]
flux_loops: tuple[FluxLoopInput, ...]
ingestion_blockers: tuple[str, ...]
ingestion_ready: bool
tier0_claim_blockers: tuple[str, ...]
tier0_claim_admission_ready: Literal[False]
payload_sha256: str
class scpn_fusion.io.imas_connector.OmasSourceProvenance(machine, shot_id, run_id, source_uri, source_sha256, license_id)[source]

Bases: object

External binding that an ODS alone cannot prove reliably.

Parameters:

  • machine (str)

  • shot_id (int)

  • run_id (int)

  • source_uri (str)

  • source_sha256 (str)

  • license_id (str)

machine: str
shot_id: int
run_id: int
source_uri: str
source_sha256: str
license_id: str
class scpn_fusion.io.imas_connector.PfCoilInput(identifier, elements, current_a)[source]

Bases: object

PF-coil current history and matching signed geometry.

Parameters:
identifier: str
elements: tuple[PfElementGeometry, ...]
current_a: TimeSeriesSI
class scpn_fusion.io.imas_connector.PfElementGeometry(identifier, turns_with_sign, geometry_type, r_m, z_m, width_m, height_m)[source]

Bases: object

One signed PF element with an explicit IMAS geometry representation.

Parameters:
identifier: str
turns_with_sign: float
geometry_type: Literal[1, 2]
r_m: tuple[float, ...]
z_m: tuple[float, ...]
width_m: float | None
height_m: float | None
class scpn_fusion.io.imas_connector.PoloidalFieldProbeInput(identifier, r_m, z_m, poloidal_angle_rad, length_m, field_t)[source]

Bases: object

Poloidal-field probe position, orientation, and field history.

Parameters:
identifier: str
r_m: float
z_m: float
poloidal_angle_rad: float
length_m: float
field_t: TimeSeriesSI
class scpn_fusion.io.imas_connector.TimeSeriesSI(time_s, values, error_lower, error_upper, validity)[source]

Bases: object

One finite, strictly ordered SI-unit time series.

Parameters:
time_s: tuple[float, ...]
values: tuple[float, ...]
error_lower: tuple[float, ...] | None
error_upper: tuple[float, ...] | None
validity: int | None
scpn_fusion.io.imas_connector.extract_omas_free_boundary_inputs(ods, *, provenance=None, cocos=None, time_alignment='native_unaligned', require_ingestion_ready=True)[source]

Extract strict SI-unit PF and magnetics channels from an OMAS ODS.

Parameters:

  • ods (ODSLike) – OMAS ODS (or compatible dotted-path mapping). IMAS schema units are preserved: seconds, amperes, metres, radians, tesla, and webers.

  • provenance (OmasSourceProvenance | None) – Immutable source binding supplied by the acquisition layer.

  • cocos (int | None) – Canonical COCOS index. When omitted, ods.cocos is used.

  • time_alignment (Literal['native_unaligned', 'exact_common_axis']) – Declare whether every channel was acquired on one exact time axis. The adapter verifies an exact_common_axis declaration byte-for-byte.

  • require_ingestion_ready (bool) – Raise when any provenance, uncertainty, validity, channel, or alignment gate is missing. Set false only for explicit development inspection.

Returns:

Immutable extracted inputs, ingestion blockers, readiness state, and digest. Full Tier-0 claim admission remains explicitly false.

Return type:

OmasFreeBoundaryInputs

Raises:

ValueError – If the ODS is structurally malformed or strict ingestion is blocked.

Equilibrium DeepONet Training Data

Coordinate, statistics, minibatch, and held-out metric preparation.

scpn_fusion.io.deeponet_training_data.deterministic_probe(*, seed, sample_count, coordinate_count, available_samples, available_coordinates)[source]

Select a reproducible validation-only shot and coordinate probe.

Parameters:

  • seed (int) – Run seed used to derive the probe generator.

  • sample_count (int) – Requested probe sizes.

  • coordinate_count (int) – Requested probe sizes.

  • available_samples (int) – Bounds of the validation and coordinate populations.

  • available_coordinates (int) – Bounds of the validation and coordinate populations.

Returns:

Sorted unique sample positions and coordinate indices.

Return type:

tuple[IndexArray, IndexArray]

scpn_fusion.io.deeponet_training_data.extract_targets(data, sample_indices, coordinate_indices, field_mean, field_scale)[source]

Read and normalise a rectangular shot-coordinate target selection.

Parameters:

  • data (MachineConditionedTrainingData) – Authenticated field cohort.

  • sample_indices (IndexArray) – Shot rows and flattened Z-R positions to select.

  • coordinate_indices (IndexArray) – Shot rows and flattened Z-R positions to select.

  • field_mean (FloatArray) – Training-only flattened spatial mean in Wb/rad.

  • field_scale (float) – Positive training-only global scale in Wb/rad.

Returns:

Dimensionless targets with shape (shots, coordinates).

Return type:

FloatArray

scpn_fusion.io.deeponet_training_data.field_metrics(runtime, data, indices, *, chunk_rows)[source]

Measure full-field error and retain row-wise relative-L2 scores.

Parameters:

  • runtime (DeepONetEquilibriumAccelerator) – Loaded runtime used for production-path inference.

  • data (MachineConditionedTrainingData) – Authenticated truth fields in Wb/rad.

  • indices (IndexArray) – Held-out shot rows to evaluate.

  • chunk_rows (int) – Maximum inference rows per chunk.

Returns:

Field RMSE and relative-L2 summary, plus one relative-L2 score per row.

Return type:

tuple[dict[str, float], FloatArray]

Raises:

ValueError – If no held-out rows are supplied or chunk_rows is not positive.

scpn_fusion.io.deeponet_training_data.load_coordinates(data)[source]

Load the authenticated R/Z grid in flattened field order.

Parameters:

data (MachineConditionedTrainingData) – Verified dataset whose manifest declares the coordinate arrays.

Returns:

Metre-valued coordinates with shape (n_z * n_r, 2).

Return type:

FloatArray

Raises:

ValueError – If the coordinate vectors disagree with the authenticated field grid.

scpn_fusion.io.deeponet_training_data.runtime_backend_parity(native, reference, data, indices, *, chunk_rows, relative_tolerance=1e-14, absolute_tolerance=1e-14)[source]

Compare native and NumPy inference over an authenticated held-out split.

Parameters:

  • native (DeepONetEquilibriumAccelerator) – Loaded runtimes for the Rust-first and NumPy-only execution paths.

  • reference (DeepONetEquilibriumAccelerator) – Loaded runtimes for the Rust-first and NumPy-only execution paths.

  • data (MachineConditionedTrainingData) – Authenticated causal inputs associated with the evaluated split.

  • indices (IndexArray) – Untouched held-out rows; every row is evaluated exactly once.

  • chunk_rows (int) – Maximum number of shot predictions materialised per runtime call.

  • relative_tolerance (float) – Element-wise parity bounds in Wb/rad, applied as abs(delta) <= atol + rtol * abs(reference).

  • absolute_tolerance (float) – Element-wise parity bounds in Wb/rad, applied as abs(delta) <= atol + rtol * abs(reference).

Returns:

Maximum absolute, normalised-tolerance, and IEEE-754 ULP differences. Metrics are unavailable when the compiled Rust backend is not loaded.

Return type:

RuntimeBackendParity

Raises:

ValueError – If the split is empty, the chunk size or a tolerance is not positive, or the reference runtime is not NumPy.

scpn_fusion.io.deeponet_training_data.training_batch(*, step, seed, data, train_indices, normalised_inputs, normalised_coordinates, field_mean, field_scale, sample_weights, shot_batch_size, coordinate_batch_size)[source]

Build a deterministic physical minibatch from an absolute step.

Parameters:

  • step (int) – One-based optimiser step and fixed run seed.

  • seed (int) – One-based optimiser step and fixed run seed.

  • data (MachineConditionedTrainingData) – Authenticated cohort used to read physical targets.

  • train_indices (IndexArray) – Rows assigned exclusively to training.

  • normalised_inputs (FloatArray) – Training controls and coordinate grid after training-only scaling.

  • normalised_coordinates (FloatArray) – Training controls and coordinate grid after training-only scaling.

  • field_mean (FloatArray) – Training-only flattened spatial mean in Wb/rad.

  • field_scale (float) – Positive training-only residual scale in Wb/rad.

  • sample_weights (FloatArray) – One relative-field weight per training row.

  • shot_batch_size (int) – Maximum sampled shots and coordinates.

  • coordinate_batch_size (int) – Maximum sampled shots and coordinates.

Returns:

Input rows, coordinate rows, normalised targets, and shot weights.

Return type:

TrainingBatch

scpn_fusion.io.deeponet_training_data.training_statistics(data, train_indices, *, chunk_rows)[source]

Fit field mean, residual scale, and norms on training rows.

Parameters:

  • data (MachineConditionedTrainingData) – Authenticated field cohort in Wb/rad.

  • train_indices (IndexArray) – Rows assigned exclusively to training.

  • chunk_rows (int) – Maximum number of fields materialised per streaming chunk.

Returns:

Flattened spatial mean in Wb/rad, positive global residual scale in Wb/rad, and one squared field norm per training row.

Return type:

tuple[FloatArray, float, FloatArray]

Equilibrium DeepONet Recovery

Identity-bound statistics, optimiser recovery, and artifact serialisation.

class scpn_fusion.io.deeponet_training_recovery.OptimizerRecovery[source]

Bases: TypedDict

Authenticated pointer to one optimiser recovery stage.

schema_version: str
completed_steps: int
stage_file: str
stage_sha256: str
class scpn_fusion.io.deeponet_training_recovery.OptimizerState(params, first_moment, second_moment, best_params, completed_steps, final_training_loss, best_validation_loss, best_step, evaluations_without_improvement, evaluation_steps, training_losses, validation_losses)[source]

Bases: object

Mutable state required for exact AdamW continuation.

The state retains current parameters and both optimiser-moment trees, validation-selected parameters, absolute completed/selected steps, latest training and best validation objectives, validation-patience state, and loss histories aligned with the recorded evaluation steps.

Parameters:
params: dict[str, list[dict[str, Array]]]
first_moment: dict[str, list[dict[str, Array]]]
second_moment: dict[str, list[dict[str, Array]]]
best_params: dict[str, list[dict[str, Array]]]
completed_steps: int
final_training_loss: float
best_validation_loss: float
best_step: int
evaluations_without_improvement: int
evaluation_steps: list[int]
training_losses: list[float]
validation_losses: list[float]
scpn_fusion.io.deeponet_training_recovery.load_optimizer(checkpoint_dir, *, identity)[source]

Authenticate and restore one exact optimiser continuation point.

Parameters:

  • checkpoint_dir (Path) – Directory containing the JSON pointer and declared NPZ stage.

  • identity (Mapping[str, Any]) – Expected trajectory identity for every embedded member.

Returns:

Exact parameters, moments, selection state, and loss history.

Return type:

OptimizerState

Raises:

ValueError – If metadata, stage bytes, identity, or completed-step values disagree.

scpn_fusion.io.deeponet_training_recovery.load_optimizer_recovery(checkpoint_dir)[source]

Load and validate an optimiser recovery pointer.

Parameters:

checkpoint_dir (Path) – Directory containing optimizer_recovery.json.

Returns:

Validated schema, stage filename, digest, and completed step.

Return type:

OptimizerRecovery

Raises:

ValueError – If the JSON root or required metadata violates the pointer contract.

scpn_fusion.io.deeponet_training_recovery.load_or_compute_statistics(data, train_indices, *, chunk_rows, checkpoint_dir, identity, resume)[source]

Load authenticated statistics or fit and checkpoint them atomically.

Parameters:

  • data (MachineConditionedTrainingData) – Authenticated cohort used for training-only statistics.

  • train_indices (ndarray[int64]) – Rows assigned exclusively to training.

  • chunk_rows (int) – Maximum fields materialised per statistics chunk.

  • checkpoint_dir (Path) – Local recovery directory.

  • identity (Mapping[str, Any]) – Expected dataset, split, and source identity arrays.

  • resume (bool) – Load existing state when true; compute and save otherwise.

Returns:

Field mean, residual scale, training-row norms, and statistics digest.

Return type:

tuple[ndarray[float64], float, ndarray[float64], str]

Raises:

ValueError – If recovery metadata, bytes, or identity do not authenticate.

scpn_fusion.io.deeponet_training_recovery.optimizer_identity(*, data, split_hashes, statistics_sha256, seed, branch_hidden, trunk_hidden, basis_width, shot_batch_size, coordinate_batch_size, validation_probe_samples, validation_probe_coordinates, learning_rate, weight_decay, gradient_clip, evaluation_every, early_stopping_patience, source_paths, repo_root)[source]

Bind every trajectory-affecting input into optimiser recovery.

Parameters:

  • data (MachineConditionedTrainingData) – Authenticated cohort and manifest digest.

  • split_hashes (Mapping[str, str]) – SHA-256 digest for every split role.

  • statistics_sha256 (str) – Digest of the authenticated training-only statistics stage.

  • seed (int) – Run seed.

  • branch_hidden (tuple[int, ...]) – Network hidden widths.

  • trunk_hidden (tuple[int, ...]) – Network hidden widths.

  • basis_width (int) – Operator width and minibatch sizes.

  • shot_batch_size (int) – Operator width and minibatch sizes.

  • coordinate_batch_size (int) – Operator width and minibatch sizes.

  • validation_probe_samples (ndarray[int64]) – Frozen validation probe identities.

  • validation_probe_coordinates (ndarray[int64]) – Frozen validation probe identities.

  • learning_rate (float) – AdamW and gradient-clipping parameters.

  • weight_decay (float) – AdamW and gradient-clipping parameters.

  • gradient_clip (float) – AdamW and gradient-clipping parameters.

  • evaluation_every (int) – Validation schedule and selection patience.

  • early_stopping_patience (int) – Validation schedule and selection patience.

  • source_paths (tuple[Path, ...]) – Exact implementation files whose bytes affect the trajectory.

  • repo_root (Path) – Root used for portable relative source names.

Returns:

Pickle-free identity arrays stored in every optimiser stage.

Return type:

dict[str, Any]

scpn_fusion.io.deeponet_training_recovery.save_optimizer(checkpoint_dir, *, identity, state)[source]

Atomically save one complete optimiser continuation point.

Parameters:

  • checkpoint_dir (Path) – Local directory receiving the NPZ stage and JSON recovery pointer.

  • identity (Mapping[str, Any]) – Expected trajectory identity embedded in the stage.

  • state (OptimizerState) – Parameters, moments, selection state, and loss history to persist.

Return type:

None

scpn_fusion.io.deeponet_training_recovery.serialize_network(payload, prefix, params)[source]

Append one dense network to a pickle-free NPZ payload.

Parameters:

  • payload (dict[str, Any]) – Mutable array mapping that will be written with numpy.savez.

  • prefix (str) – Stable namespace for layer-count, weight, and bias members.

  • params (Params) – Ordered dense layers to serialise as float64 arrays.

Return type:

None

scpn_fusion.io.deeponet_training_recovery.statistics_identity(data, train_indices, source_paths, *, repo_root)[source]

Build the immutable identity of training-only field statistics.

Parameters:

  • data (MachineConditionedTrainingData) – Authenticated cohort and manifest digests.

  • train_indices (ndarray[int64]) – Rows assigned exclusively to training.

  • source_paths (tuple[Path, ...]) – Exact implementation files whose bytes affect the result.

  • repo_root (Path) – Root used to store portable relative source names.

Returns:

Pickle-free arrays binding dataset, split, and source SHA-256 values.

Return type:

dict[str, Any]

Equilibrium DeepONet Reports

Running evidence, artifact payload, and completed-report composition.

scpn_fusion.io.deeponet_training_report.artifact_payload(prepared, config, state, *, artifact_schema, training_schema)[source]

Compose the pickle-free manifest-bound runtime artifact.

Parameters:

  • prepared (PreparedTraining) – Authenticated data, transforms, split hashes, and source identity.

  • config (TrainingConfig) – Immutable run configuration.

  • state (OptimizerState) – Completed optimiser state with validation-selected parameters.

  • artifact_schema (str) – Versioned runtime and training schema identifiers.

  • training_schema (str) – Versioned runtime and training schema identifiers.

Returns:

NumPy-compatible arrays for the production runtime NPZ.

Return type:

dict[str, Any]

scpn_fusion.io.deeponet_training_report.completed_report_sections(prepared, config, state, *, stopped_early, elapsed_seconds, validation_metrics, calibration_metrics, test_metrics, conformal_alpha, conformal_rank, conformal_bound, test_coverage, recovery, runtime_prediction, runtime_parity, runtime_backend, backend_parity)[source]

Compose final evidence after held-out evaluation has completed.

Parameters:

  • prepared (PreparedTraining) – Frozen data, transforms, split, and recovery identity.

  • config (TrainingConfig) – Immutable run configuration.

  • state (OptimizerState) – Final optimiser and validation-selection state.

  • stopped_early (bool) – Whether validation patience ended optimisation before steps.

  • elapsed_seconds (float) – Local wall-clock training duration.

  • validation_metrics (dict[str, float]) – Full-field metrics measured on each held-out role.

  • calibration_metrics (dict[str, float]) – Full-field metrics measured on each held-out role.

  • test_metrics (dict[str, float]) – Full-field metrics measured on each held-out role.

  • conformal_alpha (float) – Miscoverage target used for split-conformal calibration.

  • conformal_rank (int) – One-based finite-sample order-statistic rank.

  • conformal_bound (float) – Calibrated relative-L2 bound and untouched-test empirical coverage.

  • test_coverage (float) – Calibrated relative-L2 bound and untouched-test empirical coverage.

  • recovery (OptimizerRecovery) – Authenticated optimiser recovery pointer.

  • runtime_prediction (ndarray[float64]) – Production-runtime parity probe.

  • runtime_parity (float) – Maximum absolute Wb/rad difference from the JAX training path.

  • runtime_backend (str) – Selected production inference tier, rust or numpy.

  • backend_parity (RuntimeBackendParity) – Rust-versus-NumPy evidence over every untouched-test row.

Returns:

JSON-compatible final report sections.

Return type:

dict[str, Any]

scpn_fusion.io.deeponet_training_report.running_report(data, split, split_hashes, config, statistics_sha256, *, training_schema)[source]

Compose fail-closed evidence before optimisation starts.

Parameters:

  • data (MachineConditionedTrainingData) – Authenticated cohort and provenance.

  • split (MachineConditionedSplit) – Four disjoint role assignments.

  • split_hashes (dict[str, str]) – SHA-256 digest for each role’s ordered indices.

  • config (TrainingConfig) – Immutable run configuration.

  • statistics_sha256 (str) – Digest of the training-only statistics stage.

  • training_schema (str) – Versioned report schema identifier.

Returns:

JSON-compatible running report with claims closed by default.

Return type:

dict[str, Any]

Equilibrium DeepONet CLI

Argument adapter for the manifest-bound equilibrium DeepONet trainer.

scpn_fusion.io.machine_conditioned_deeponet_cli.run_deeponet_cli(train, *, default_basis_width)[source]

Parse the command-line contract and invoke the DeepONet trainer.

Parameters:

  • train (TrainingCallable) – Production training entry point accepting the parsed keyword contract.

  • default_basis_width (int) – Positive default branch/trunk output width.

Raises:

  • SystemExit – If command-line arguments are missing or invalid.

  • OSError – If dataset, recovery, artifact, or report storage fails.

  • ValueError – If data, configuration, or recovery authentication fails.

Return type:

None