External Solver Integrations

TORAX runtime

The TORAX caller surface is process-isolated. Importing these contracts does not import TORAX or JAX. Runtime outcomes preserve the complete backend DataTree, while semantic consumers use the deterministic review-only envelope.

Stable, TORAX-free caller surface for real TORAX execution.

class scpn_fusion.integrations.torax.ToraxArtifact(sidecar_path, sidecar_sha256, sidecar_bytes, manifest_path, manifest_sha256, format='NetCDF-DataTree')[source]

Bases: object

Checksummed complete TORAX output and its inventory manifest.

Parameters:

  • sidecar_path (str)

  • sidecar_sha256 (str)

  • sidecar_bytes (int)

  • manifest_path (str)

  • manifest_sha256 (str)

  • format (str)

format: str = 'NetCDF-DataTree'
classmethod from_dict(value)[source]

Parse strict artifact custody fields.

Return type:

ToraxArtifact

Parameters:

value (object)

to_dict()[source]

Serialize artifact custody fields.

Return type:

dict[str, object]

sidecar_path: str
sidecar_sha256: str
sidecar_bytes: int
manifest_path: str
manifest_sha256: str
class scpn_fusion.integrations.torax.ToraxClock(domain, epoch, initial_ns, final_ns, timeout_s, max_steps, reset_policy)[source]

Bases: object

Exact simulation-monotonic clock and bounded execution policy.

Parameters:
classmethod from_dict(value)[source]

Parse a strict clock object.

Return type:

ToraxClock

Parameters:

value (object)

to_dict()[source]

Serialize the clock without converting integer nanoseconds to floats.

Return type:

dict[str, object]

domain: str
epoch: str
initial_ns: int
final_ns: int
timeout_s: float
max_steps: int
reset_policy: str
class scpn_fusion.integrations.torax.ToraxConfigBinding(name, config_path, unit, interpretation, value)[source]

Bases: object

Exact typed-to-backend overlap assertion using a JSON object path.

Parameters:
classmethod from_dict(value, *, label='binding')[source]

Parse one strict configuration binding.

Return type:

ToraxConfigBinding

Parameters:
to_dict()[source]

Serialize one exact configuration binding.

Return type:

dict[str, object]

name: str
config_path: tuple[str, ...]
unit: str
interpretation: str
value: object
class scpn_fusion.integrations.torax.ToraxFailureCode(*values)[source]

Bases: str, Enum

Stable failure codes exposed independently of TORAX implementation types.

classmethod from_sim_error(name)[source]

Map every TORAX 1.4.3 SimError name one-to-one.

Return type:

ToraxFailureCode | None

Parameters:

name (str)

INVALID_REQUEST = 'INVALID_REQUEST'
BACKEND_UNAVAILABLE = 'BACKEND_UNAVAILABLE'
BACKEND_VERSION_MISMATCH = 'BACKEND_VERSION_MISMATCH'
CONFIGURATION_REJECTED = 'CONFIGURATION_REJECTED'
TIMEOUT = 'TIMEOUT'
PROCESS_FAILURE = 'PROCESS_FAILURE'
OUTPUT_SCHEMA_MISMATCH = 'OUTPUT_SCHEMA_MISMATCH'
PROVENANCE_FAILURE = 'PROVENANCE_FAILURE'
NAN_DETECTED = 'NAN_DETECTED'
QUASINEUTRALITY_BROKEN = 'QUASINEUTRALITY_BROKEN'
NEGATIVE_CORE_PROFILES = 'NEGATIVE_CORE_PROFILES'
REACHED_MIN_DT = 'REACHED_MIN_DT'
LOW_TEMPERATURE_COLLAPSE = 'LOW_TEMPERATURE_COLLAPSE'
DID_NOT_REACH_T_FINAL = 'DID_NOT_REACH_T_FINAL'
class scpn_fusion.integrations.torax.ToraxGeometry(kind, frame, major_radius_m, minor_radius_m, magnetic_field_t, radial_coordinate='rho_norm', radial_coordinate_unit='1')[source]

Bases: object

Typed geometry identity shared with external consumers.

Parameters:

  • kind (str)

  • frame (str)

  • major_radius_m (float)

  • minor_radius_m (float)

  • magnetic_field_t (float)

  • radial_coordinate (str)

  • radial_coordinate_unit (str)

classmethod from_dict(value)[source]

Parse a strict geometry object.

Return type:

ToraxGeometry

Parameters:

value (object)

radial_coordinate: str = 'rho_norm'
radial_coordinate_unit: str = '1'
to_dict()[source]

Serialize the geometry vocabulary and SI values.

Return type:

dict[str, object]

kind: str
frame: str
major_radius_m: float
minor_radius_m: float
magnetic_field_t: float
class scpn_fusion.integrations.torax.ToraxProjection(time_ns, rho_norm, profiles, profile_units, source_totals, source_units, state_budgets, budget_units, numerics, uncertainty, scientific_sha256)[source]

Bases: object

Consumer-critical, unit-bearing projection of one complete TORAX run.

Parameters:
classmethod from_dict(value)[source]

Parse a strict critical projection.

Return type:

ToraxProjection

Parameters:

value (object)

to_dict()[source]

Serialize the critical projection.

Return type:

dict[str, object]

time_ns: tuple[int, ...]
rho_norm: tuple[float, ...]
profiles: Mapping[str, tuple[tuple[float, ...], ...]]
profile_units: Mapping[str, str]
source_totals: Mapping[str, tuple[float, ...]]
source_units: Mapping[str, str]
state_budgets: tuple[Mapping[str, float], ...]
budget_units: Mapping[str, str]
numerics: Mapping[str, object]
uncertainty: Mapping[str, object]
scientific_sha256: str
class scpn_fusion.integrations.torax.ToraxProvenance(torax_version, torax_license, source_repo_commit, python_version, platform, runtime_backend, precision, request_sha256, config_sha256, deck_sha256, runner_sha256, started_at_utc, finished_at_utc)[source]

Bases: object

Runtime and source identity needed to reproduce one TORAX outcome.

Parameters:

  • torax_version (str)

  • torax_license (str)

  • source_repo_commit (str)

  • python_version (str)

  • platform (str)

  • runtime_backend (str)

  • precision (str)

  • request_sha256 (str)

  • config_sha256 (str)

  • deck_sha256 (str)

  • runner_sha256 (str)

  • started_at_utc (str)

  • finished_at_utc (str)

classmethod from_dict(value)[source]

Parse strict runtime provenance.

Return type:

ToraxProvenance

Parameters:

value (object)

to_dict()[source]

Serialize runtime provenance.

Return type:

dict[str, object]

torax_version: str
torax_license: str
source_repo_commit: str
python_version: str
platform: str
runtime_backend: str
precision: str
request_sha256: str
config_sha256: str
deck_sha256: str
runner_sha256: str
started_at_utc: str
finished_at_utc: str
class scpn_fusion.integrations.torax.ToraxRunOutcome(request_id, event_id, complete, reached_time_ns, sim_error, provenance, projection, artifact, failure_code, failure_message, schema='scpn-fusion-core.torax-runtime-outcome.v1')[source]

Bases: object

Discriminated success/failure result for one TORAX request.

Parameters:
classmethod from_dict(value)[source]

Parse and validate a v1 outcome with unknown-field refusal.

Return type:

ToraxRunOutcome

Parameters:

value (object)

require_success()[source]

Return this outcome or raise a stable typed runtime exception.

Return type:

ToraxRunOutcome

schema: str = 'scpn-fusion-core.torax-runtime-outcome.v1'
property success: bool

Return whether the solver and all output/custody gates passed.

to_dict()[source]

Serialize the discriminated outcome.

Return type:

dict[str, object]

request_id: str
event_id: str
complete: bool
reached_time_ns: int
sim_error: str
provenance: ToraxProvenance
projection: ToraxProjection | None
artifact: ToraxArtifact | None
failure_code: ToraxFailureCode | None
failure_message: str | None
class scpn_fusion.integrations.torax.ToraxRunRequest(request_id, event_id, model_id, scenario_id, reactor_family, reactor_id, configuration_id, clock, geometry, initial_state, controls, models, torax_config, bindings, custody, expected_torax_version='1.4.3', schema='scpn-fusion-core.torax-runtime-request.v1')[source]

Bases: object

Complete TORAX configuration plus a checked typed consumer view.

Parameters:
expected_torax_version: str = '1.4.3'
classmethod from_dict(value)[source]

Parse and validate a v1 request with unknown-field refusal.

Return type:

ToraxRunRequest

Parameters:

value (object)

schema: str = 'scpn-fusion-core.torax-runtime-request.v1'
to_dict()[source]

Serialize the complete request without losing backend configuration fields.

Return type:

dict[str, object]

request_id: str
event_id: str
model_id: str
scenario_id: str
reactor_family: str
reactor_id: str
configuration_id: str
clock: ToraxClock
geometry: ToraxGeometry
initial_state: tuple[ToraxSignal, ...]
controls: tuple[ToraxSignal, ...]
models: Mapping[str, object]
torax_config: Mapping[str, object]
bindings: tuple[ToraxConfigBinding, ...]
custody: Mapping[str, object]
class scpn_fusion.integrations.torax.ToraxReviewEnvelope(source_schema, source_revision, model_intersection_schema, event_id, payload, provenance, payload_sha256, schema='scpn-fusion-core.torax-runtime-review-envelope.v1')[source]

Bases: object

Canonical review-only projection with numerical-refinement uncertainty.

Parameters:
classmethod from_dict(value)[source]

Parse and verify a deterministic review envelope.

Return type:

ToraxReviewEnvelope

Parameters:

value (object)

schema: str = 'scpn-fusion-core.torax-runtime-review-envelope.v1'
to_dict()[source]

Serialize the canonical review envelope.

Return type:

dict[str, object]

to_dict_without_digest()[source]

Return deterministic fields other than the derived payload digest.

Return type:

dict[str, object]

source_schema: str
source_revision: str
model_intersection_schema: str
event_id: str
payload: Mapping[str, object]
provenance: Mapping[str, object]
payload_sha256: str
class scpn_fusion.integrations.torax.ToraxRuntimeClient(python_executable, working_directory=None)[source]

Bases: object

Launch a supplied TORAX Python interpreter through the public CLI.

Parameters:

  • python_executable (Path)

  • working_directory (Path | None)

load_verified_outcome(*, result_path, expected_sidecar_path)[source]

Load an outcome and verify every declared sidecar custody digest.

Return type:

ToraxRunOutcome

Parameters:

  • result_path (Path)

  • expected_sidecar_path (Path)

run(request, *, request_path, result_path, sidecar_path, environment=None)[source]

Execute one request with a whole-process-group wall-time bound.

Return type:

ToraxRunOutcome

Parameters:
working_directory: Path | None = None
python_executable: Path
exception scpn_fusion.integrations.torax.ToraxRuntimeError(code, message)[source]

Bases: RuntimeError

Raised by ToraxRunOutcome.require_success() for typed failures.

Parameters:
Return type:

None

class scpn_fusion.integrations.torax.ToraxSignal(name, role, unit, frame, time_ns, coordinate_name, coordinate_unit, coordinate, values, binding_name, calibration, provenance, uncertainty_kind, uncertainty, application_semantics, model_delay_ns, saturation_minimum, saturation_maximum, maximum_slew_per_s, hardware_limits_status, validity='VALID')[source]

Bases: object

Unit-bearing profile or scalar trajectory bound to one configuration value.

Parameters:
classmethod from_dict(value, *, label='signal')[source]

Parse one strict typed signal.

Return type:

ToraxSignal

Parameters:
to_dict()[source]

Serialize the signal using arrays rather than implementation tuples.

Return type:

dict[str, object]

validity: str = 'VALID'
name: str
role: str
unit: str
frame: str
time_ns: tuple[int, ...]
coordinate_name: str
coordinate_unit: str
coordinate: tuple[float, ...]
values: tuple[tuple[float, ...], ...]
binding_name: str
calibration: str
provenance: str
uncertainty_kind: str
uncertainty: tuple[tuple[float, ...], ...] | None
application_semantics: str
model_delay_ns: int
saturation_minimum: float | None
saturation_maximum: float | None
maximum_slew_per_s: float | None
hardware_limits_status: str
scpn_fusion.integrations.torax.build_review_envelope(*, request, refined_request, primary, refined, primary_dt_ns, refined_dt_ns, source_revision, runtime_source_sha256, artifact_content_sha256, manifest_inventory_sha256)[source]

Build a deterministic, review-only envelope from two real TORAX runs.

The producer derives all twelve uncertainty records from primary and refined projections aligned at the primary sample times. The D-D reaction value is only the fuel-class identity supported by the deuterium-only deck; it does not claim that fusion burn or fusion power was modeled.

Raises:

ValueError – If request identity, timing, projection vocabulary, shape, units, or numerical-refinement evidence differs from the frozen U1 contract.

Return type:

ToraxReviewEnvelope

Parameters:
scpn_fusion.integrations.torax.review_envelope_from_bytes(payload, *, expected_sha256=None)[source]

Decode canonical bytes and refuse size, digest, duplicate, or encoding drift.

Return type:

ToraxReviewEnvelope

Parameters:

  • payload (bytes)

  • expected_sha256 (str | None)

scpn_fusion.integrations.torax.review_envelope_sha256(envelope)[source]

Hash the exact canonical review-envelope bytes.

Return type:

str

Parameters:

envelope (ToraxReviewEnvelope)

scpn_fusion.integrations.torax.review_envelope_to_bytes(envelope)[source]

Return the unique canonical UTF-8 representation of an envelope.

Return type:

bytes

Parameters:

envelope (ToraxReviewEnvelope)

Runtime client

Bounded process-isolated client that never imports TORAX or JAX.

class scpn_fusion.integrations.torax.client.ToraxRuntimeClient(python_executable, working_directory=None)[source]

Bases: object

Launch a supplied TORAX Python interpreter through the public CLI.

Parameters:

  • python_executable (Path)

  • working_directory (Path | None)

python_executable: Path
working_directory: Path | None = None
run(request, *, request_path, result_path, sidecar_path, environment=None)[source]

Execute one request with a whole-process-group wall-time bound.

Return type:

ToraxRunOutcome

Parameters:
load_verified_outcome(*, result_path, expected_sidecar_path)[source]

Load an outcome and verify every declared sidecar custody digest.

Return type:

ToraxRunOutcome

Parameters:

  • result_path (Path)

  • expected_sidecar_path (Path)

Contracts

Immutable, versioned contracts for process-isolated TORAX execution.

class scpn_fusion.integrations.torax.contracts.ToraxArtifact(sidecar_path, sidecar_sha256, sidecar_bytes, manifest_path, manifest_sha256, format='NetCDF-DataTree')[source]

Bases: object

Checksummed complete TORAX output and its inventory manifest.

Parameters:

  • sidecar_path (str)

  • sidecar_sha256 (str)

  • sidecar_bytes (int)

  • manifest_path (str)

  • manifest_sha256 (str)

  • format (str)

sidecar_path: str
sidecar_sha256: str
sidecar_bytes: int
manifest_path: str
manifest_sha256: str
format: str = 'NetCDF-DataTree'
to_dict()[source]

Serialize artifact custody fields.

Return type:

dict[str, object]

classmethod from_dict(value)[source]

Parse strict artifact custody fields.

Return type:

ToraxArtifact

Parameters:

value (object)

class scpn_fusion.integrations.torax.contracts.ToraxClock(domain, epoch, initial_ns, final_ns, timeout_s, max_steps, reset_policy)[source]

Bases: object

Exact simulation-monotonic clock and bounded execution policy.

Parameters:
domain: str
epoch: str
initial_ns: int
final_ns: int
timeout_s: float
max_steps: int
reset_policy: str
to_dict()[source]

Serialize the clock without converting integer nanoseconds to floats.

Return type:

dict[str, object]

classmethod from_dict(value)[source]

Parse a strict clock object.

Return type:

ToraxClock

Parameters:

value (object)

class scpn_fusion.integrations.torax.contracts.ToraxConfigBinding(name, config_path, unit, interpretation, value)[source]

Bases: object

Exact typed-to-backend overlap assertion using a JSON object path.

Parameters:
name: str
config_path: tuple[str, ...]
unit: str
interpretation: str
value: object
to_dict()[source]

Serialize one exact configuration binding.

Return type:

dict[str, object]

classmethod from_dict(value, *, label='binding')[source]

Parse one strict configuration binding.

Return type:

ToraxConfigBinding

Parameters:
class scpn_fusion.integrations.torax.contracts.ToraxFailureCode(*values)[source]

Bases: str, Enum

Stable failure codes exposed independently of TORAX implementation types.

INVALID_REQUEST = 'INVALID_REQUEST'
BACKEND_UNAVAILABLE = 'BACKEND_UNAVAILABLE'
BACKEND_VERSION_MISMATCH = 'BACKEND_VERSION_MISMATCH'
CONFIGURATION_REJECTED = 'CONFIGURATION_REJECTED'
TIMEOUT = 'TIMEOUT'
PROCESS_FAILURE = 'PROCESS_FAILURE'
OUTPUT_SCHEMA_MISMATCH = 'OUTPUT_SCHEMA_MISMATCH'
PROVENANCE_FAILURE = 'PROVENANCE_FAILURE'
NAN_DETECTED = 'NAN_DETECTED'
QUASINEUTRALITY_BROKEN = 'QUASINEUTRALITY_BROKEN'
NEGATIVE_CORE_PROFILES = 'NEGATIVE_CORE_PROFILES'
REACHED_MIN_DT = 'REACHED_MIN_DT'
LOW_TEMPERATURE_COLLAPSE = 'LOW_TEMPERATURE_COLLAPSE'
DID_NOT_REACH_T_FINAL = 'DID_NOT_REACH_T_FINAL'
classmethod from_sim_error(name)[source]

Map every TORAX 1.4.3 SimError name one-to-one.

Return type:

ToraxFailureCode | None

Parameters:

name (str)

class scpn_fusion.integrations.torax.contracts.ToraxGeometry(kind, frame, major_radius_m, minor_radius_m, magnetic_field_t, radial_coordinate='rho_norm', radial_coordinate_unit='1')[source]

Bases: object

Typed geometry identity shared with external consumers.

Parameters:

  • kind (str)

  • frame (str)

  • major_radius_m (float)

  • minor_radius_m (float)

  • magnetic_field_t (float)

  • radial_coordinate (str)

  • radial_coordinate_unit (str)

kind: str
frame: str
major_radius_m: float
minor_radius_m: float
magnetic_field_t: float
radial_coordinate: str = 'rho_norm'
radial_coordinate_unit: str = '1'
to_dict()[source]

Serialize the geometry vocabulary and SI values.

Return type:

dict[str, object]

classmethod from_dict(value)[source]

Parse a strict geometry object.

Return type:

ToraxGeometry

Parameters:

value (object)

class scpn_fusion.integrations.torax.contracts.ToraxProjection(time_ns, rho_norm, profiles, profile_units, source_totals, source_units, state_budgets, budget_units, numerics, uncertainty, scientific_sha256)[source]

Bases: object

Consumer-critical, unit-bearing projection of one complete TORAX run.

Parameters:
time_ns: tuple[int, ...]
rho_norm: tuple[float, ...]
profiles: Mapping[str, tuple[tuple[float, ...], ...]]
profile_units: Mapping[str, str]
source_totals: Mapping[str, tuple[float, ...]]
source_units: Mapping[str, str]
state_budgets: tuple[Mapping[str, float], ...]
budget_units: Mapping[str, str]
numerics: Mapping[str, object]
uncertainty: Mapping[str, object]
scientific_sha256: str
to_dict()[source]

Serialize the critical projection.

Return type:

dict[str, object]

classmethod from_dict(value)[source]

Parse a strict critical projection.

Return type:

ToraxProjection

Parameters:

value (object)

class scpn_fusion.integrations.torax.contracts.ToraxProvenance(torax_version, torax_license, source_repo_commit, python_version, platform, runtime_backend, precision, request_sha256, config_sha256, deck_sha256, runner_sha256, started_at_utc, finished_at_utc)[source]

Bases: object

Runtime and source identity needed to reproduce one TORAX outcome.

Parameters:

  • torax_version (str)

  • torax_license (str)

  • source_repo_commit (str)

  • python_version (str)

  • platform (str)

  • runtime_backend (str)

  • precision (str)

  • request_sha256 (str)

  • config_sha256 (str)

  • deck_sha256 (str)

  • runner_sha256 (str)

  • started_at_utc (str)

  • finished_at_utc (str)

torax_version: str
torax_license: str
source_repo_commit: str
python_version: str
platform: str
runtime_backend: str
precision: str
request_sha256: str
config_sha256: str
deck_sha256: str
runner_sha256: str
started_at_utc: str
finished_at_utc: str
to_dict()[source]

Serialize runtime provenance.

Return type:

dict[str, object]

classmethod from_dict(value)[source]

Parse strict runtime provenance.

Return type:

ToraxProvenance

Parameters:

value (object)

class scpn_fusion.integrations.torax.contracts.ToraxRunOutcome(request_id, event_id, complete, reached_time_ns, sim_error, provenance, projection, artifact, failure_code, failure_message, schema='scpn-fusion-core.torax-runtime-outcome.v1')[source]

Bases: object

Discriminated success/failure result for one TORAX request.

Parameters:
request_id: str
event_id: str
complete: bool
reached_time_ns: int
sim_error: str
provenance: ToraxProvenance
projection: ToraxProjection | None
artifact: ToraxArtifact | None
failure_code: ToraxFailureCode | None
failure_message: str | None
schema: str = 'scpn-fusion-core.torax-runtime-outcome.v1'
property success: bool

Return whether the solver and all output/custody gates passed.

require_success()[source]

Return this outcome or raise a stable typed runtime exception.

Return type:

ToraxRunOutcome

to_dict()[source]

Serialize the discriminated outcome.

Return type:

dict[str, object]

classmethod from_dict(value)[source]

Parse and validate a v1 outcome with unknown-field refusal.

Return type:

ToraxRunOutcome

Parameters:

value (object)

class scpn_fusion.integrations.torax.contracts.ToraxRunRequest(request_id, event_id, model_id, scenario_id, reactor_family, reactor_id, configuration_id, clock, geometry, initial_state, controls, models, torax_config, bindings, custody, expected_torax_version='1.4.3', schema='scpn-fusion-core.torax-runtime-request.v1')[source]

Bases: object

Complete TORAX configuration plus a checked typed consumer view.

Parameters:
request_id: str
event_id: str
model_id: str
scenario_id: str
reactor_family: str
reactor_id: str
configuration_id: str
clock: ToraxClock
geometry: ToraxGeometry
initial_state: tuple[ToraxSignal, ...]
controls: tuple[ToraxSignal, ...]
models: Mapping[str, object]
torax_config: Mapping[str, object]
bindings: tuple[ToraxConfigBinding, ...]
custody: Mapping[str, object]
expected_torax_version: str = '1.4.3'
schema: str = 'scpn-fusion-core.torax-runtime-request.v1'
to_dict()[source]

Serialize the complete request without losing backend configuration fields.

Return type:

dict[str, object]

classmethod from_dict(value)[source]

Parse and validate a v1 request with unknown-field refusal.

Return type:

ToraxRunRequest

Parameters:

value (object)

exception scpn_fusion.integrations.torax.contracts.ToraxRuntimeError(code, message)[source]

Bases: RuntimeError

Raised by ToraxRunOutcome.require_success() for typed failures.

Parameters:
Return type:

None

class scpn_fusion.integrations.torax.contracts.ToraxSignal(name, role, unit, frame, time_ns, coordinate_name, coordinate_unit, coordinate, values, binding_name, calibration, provenance, uncertainty_kind, uncertainty, application_semantics, model_delay_ns, saturation_minimum, saturation_maximum, maximum_slew_per_s, hardware_limits_status, validity='VALID')[source]

Bases: object

Unit-bearing profile or scalar trajectory bound to one configuration value.

Parameters:
name: str
role: str
unit: str
frame: str
time_ns: tuple[int, ...]
coordinate_name: str
coordinate_unit: str
coordinate: tuple[float, ...]
values: tuple[tuple[float, ...], ...]
binding_name: str
calibration: str
provenance: str
uncertainty_kind: str
uncertainty: tuple[tuple[float, ...], ...] | None
application_semantics: str
model_delay_ns: int
saturation_minimum: float | None
saturation_maximum: float | None
maximum_slew_per_s: float | None
hardware_limits_status: str
validity: str = 'VALID'
to_dict()[source]

Serialize the signal using arrays rather than implementation tuples.

Return type:

dict[str, object]

classmethod from_dict(value, *, label='signal')[source]

Parse one strict typed signal.

Return type:

ToraxSignal

Parameters:

Deterministic review envelope

Deterministic, non-actuating TORAX evidence envelope for SPO consumers.

class scpn_fusion.integrations.torax.review.ToraxReviewEnvelope(source_schema, source_revision, model_intersection_schema, event_id, payload, provenance, payload_sha256, schema='scpn-fusion-core.torax-runtime-review-envelope.v1')[source]

Bases: object

Canonical review-only projection with numerical-refinement uncertainty.

Parameters:
source_schema: str
source_revision: str
model_intersection_schema: str
event_id: str
payload: Mapping[str, object]
provenance: Mapping[str, object]
payload_sha256: str
schema: str = 'scpn-fusion-core.torax-runtime-review-envelope.v1'
to_dict_without_digest()[source]

Return deterministic fields other than the derived payload digest.

Return type:

dict[str, object]

to_dict()[source]

Serialize the canonical review envelope.

Return type:

dict[str, object]

classmethod from_dict(value)[source]

Parse and verify a deterministic review envelope.

Return type:

ToraxReviewEnvelope

Parameters:

value (object)

scpn_fusion.integrations.torax.review.build_review_envelope(*, request, refined_request, primary, refined, primary_dt_ns, refined_dt_ns, source_revision, runtime_source_sha256, artifact_content_sha256, manifest_inventory_sha256)[source]

Build a deterministic, review-only envelope from two real TORAX runs.

The producer derives all twelve uncertainty records from primary and refined projections aligned at the primary sample times. The D-D reaction value is only the fuel-class identity supported by the deuterium-only deck; it does not claim that fusion burn or fusion power was modeled.

Raises:

ValueError – If request identity, timing, projection vocabulary, shape, units, or numerical-refinement evidence differs from the frozen U1 contract.

Return type:

ToraxReviewEnvelope

Parameters:
scpn_fusion.integrations.torax.review.review_envelope_from_bytes(payload, *, expected_sha256=None)[source]

Decode canonical bytes and refuse size, digest, duplicate, or encoding drift.

Return type:

ToraxReviewEnvelope

Parameters:

  • payload (bytes)

  • expected_sha256 (str | None)

scpn_fusion.integrations.torax.review.review_envelope_sha256(envelope)[source]

Hash the exact canonical review-envelope bytes.

Return type:

str

Parameters:

envelope (ToraxReviewEnvelope)

scpn_fusion.integrations.torax.review.review_envelope_to_bytes(envelope)[source]

Return the unique canonical UTF-8 representation of an envelope.

Return type:

bytes

Parameters:

envelope (ToraxReviewEnvelope)

Uniform-DT operating maps

Run a source-pinned, uniform-DT scoping map through public cfspopcon APIs.

Equal D/T, Ti=Te and uniform density/temperature are prescribed. ITER98y2 sets total loss power; alpha heating and prescribed ohmic heating determine required auxiliary power. This is code comparison, not experimental evidence.

validation.cfspopcon_operating_map.verify_upstream(package_root)[source]

Verify installed Python/YAML bytes against the reviewed upstream manifest.

Parameters:

package_root (Path) – Root of the cfspopcon package being used.

Returns:

Exact source commit and manifest digest.

Return type:

dict[str, str]

Raises:

ValueError – If a source file is absent, added or changed.

validation.cfspopcon_operating_map.validate_request(request)[source]

Reject unsupported modes, nonfinite values and grids above 256 points.

Parameters:

request (Mapping[str, object]) – Exact schema plus SI geometry, MA/MW powers and keV temperature axes.

Raises:

ValueError – If keys, numeric domains or bounded grid dimensions are invalid.

Return type:

None

validation.cfspopcon_operating_map.run_operating_map(request, *, reference_python, reference_root=None)[source]

Calculate all requested points without promoting results to evidence.

Parameters:

  • request (Mapping[str, object]) – A validated uniform-DT request; see the committed reference input.

  • reference_python (Path) – Python executable in the existing SCPN environment. The public local reactivity API runs in this separate process to isolate NumPy versions.

  • reference_root (Path, optional) – SCPN checkout to compare; defaults to this checkout. The actual imported source hash is retained, including for a candidate under review.

Returns:

Source-bound design-only results, including every refused point.

Return type:

dict[str, Any]

Raises:

  • ValueError – If inputs or installed source custody do not match the contract.

  • ModuleNotFoundError – If the optional upstream runtime has not been installed.

validation.cfspopcon_operating_map.main()[source]

Write a finite JSON operating map from an explicit JSON request path.

Return type:

None

PROCESS power diagnostics

Read actual PROCESS power records without turning convergence into admission.

validation.process_power_report.read_process_power_report(path, *, expected_sha256, expected_constraints, equality_tolerance)[source]

Inspect every scan in a caller-identified PROCESS MFILE artifact.

Parameters:

  • path (Path) – Actual PROCESS MFILE.DAT output, read through its public MFile parser.

  • expected_sha256 (str) – Digest recorded by the producing run; mismatched artifacts are rejected.

  • expected_constraints (tuple[int, ...]) – Exact active constraint IDs from the input case, including equalities.

  • equality_tolerance (float) – Explicit finite positive bound for the recorded equality residual norm.

Returns:

All scan values, inequality violations and separate recorded-check results. These are diagnostics, not source-provenance or physical admission proof. Plasma/reactor/plant imbalance limits use upstream’s 0.1 MW diagnostic threshold. Electrical arithmetic is checked with the same bound.

Return type:

dict[str, Any]

Raises:

  • ValueError – For bad custody, missing constraints/fields, inconsistent scan counts, nonfinite values, conflicting repeated diagnostics, or invalid caller configuration.

  • ModuleNotFoundError – If the optional PROCESS runtime is unavailable.

Source-bound PROCESS execution

Run the pinned real PROCESS evaluation case and preserve diagnostics and custody.

validation.process_reference_run.verify_process_source()[source]

Verify installed package source/data against the immutable reference manifest.

Returns:

Source commit, manifest digest, installed version and generated-version hash.

Return type:

dict[str, Any]

Raises:

  • ModuleNotFoundError – When the optional upstream package is unavailable.

  • ValueError – When installed source/data differ, are absent or include unexpected files.

Notes

Python/Numba caches are excluded. The unused build-generated _version.py is recorded separately; all 220 upstream package source/data files are checked. This does not certify transitive dependencies or physical model validity.

validation.process_reference_run.run_process_reference(case, output_dir, *, equality_tolerance, timeout_seconds=240.0)[source]

Execute the pinned case in a separate process, retaining even rejected results.

Parameters:

  • case (Path) – Unmodified upstream large_tokamak_eval_IN.DAT from the pinned snapshot.

  • output_dir (Path) – New directory exclusively created for inputs, log, outputs and JSON receipt.

  • equality_tolerance (float) – Caller-declared positive finite equality diagnostic tolerance.

  • timeout_seconds (float) – Finite positive child execution limit in seconds; defaults to 240.

Returns:

Power diagnostics with local execution/source/file custody. Scientific and control authority remain false regardless of convergence or recorded checks.

Return type:

dict[str, Any]

Raises:

  • ValueError – For input/source mismatch or malformed output diagnostics.

  • FileExistsError – If the requested output directory exists; nothing is overwritten.

  • subprocess.SubprocessError – If execution fails or exceeds the timeout. Existing log/input stay available.

Notes

Run this API in the isolated PROCESS environment. The child uses its exact interpreter with two OpenBLAS/Numba threads and a noninteractive plotting backend. Verification is local observed custody, not a signed third-party attestation.

validation.process_reference_run.main()[source]

Run one pinned case and write a source-bound diagnostic report via the CLI.

Return type:

None

RustBCA particle-surface diagnostics

These optional APIs retain local build and run observations. They do not establish independent source attestation or physical/material validation.

Validate bounded ion/material sampling requests before starting RustBCA.

validation.rustbca_request.validate_rustbca_request(request)[source]

Return an independent normalized request for the ergonomic RustBCA APIs.

Parameters:

request (object) – JSON-shaped mapping with schema, ion, target, energies_eV, angles_deg, samples_per_seed, seeds and threads. Species use Z, mass m in amu, cutoff Ec and surface binding Es in eV; target also requires bulk binding Eb in eV and number density n in m^-3. Both require label and provenance.

Returns:

Detached request with finite floating-point material/grid values and integer atomic numbers, sample counts, seeds and thread count.

Return type:

dict[str, Any]

Raises:

ValueError – For missing/unknown keys, invalid numeric/text values, duplicate grid or seed entries, or requests exceeding the computational sampling contract.

Notes

The contract allows at most eight energies below 100 keV and eight angles from zero up to but excluding 90 degrees, two to sixteen unique unsigned 64-bit seeds, one to eight threads and up to one million incident histories per observable over the grid. These are workload bounds, not physics validity limits. Each energy must exceed the incident-ion cutoff. At least two seeds permit empirical batch dispersion; they do not guarantee a confidence bound. Provenance is caller-supplied attribution, not authenticated material evidence. No defaults, clipping, species inference or source/physical admission occurs.

Execute caller-identified RustBCA binaries and retain per-seed diagnostics.

validation.rustbca_reference.run_rustbca_reference(request, output_dir, *, python, expected_binary_sha256, timeout_seconds=240.0, build_receipt=None, expected_build_receipt_sha256=None)[source]

Run every energy/angle/seed point with a bounded, identified real backend.

Parameters:

  • request (object) – Mapping accepted by validate_rustbca_request. Caller attribution is kept.

  • output_dir (Path) – New directory for the normalized request, per-seed inputs, logs and outputs.

  • python (Path) – Interpreter in the separately installed optional RustBCA environment.

  • expected_binary_sha256 (str) – Previously recorded SHA256 of the runtime extension. Each child verifies it.

  • timeout_seconds (float) – Total execution budget in (0, 3600] seconds, including every batch.

  • build_receipt (Path or None) – Optional retained native build observation, verified before and after the run.

  • expected_build_receipt_sha256 (str or None) – Required caller-pinned digest when build_receipt is supplied.

Returns:

Complete seed batches and empirical means/standard errors with local file hashes. No source, material, physical or actuation approval is inferred.

Return type:

dict[str, Any]

Raises:

  • ValueError – For invalid requests, digest syntax, execution limits or changed custody.

  • FileExistsError – If the output directory already exists.

  • subprocess.SubprocessError – For child failure or exhausted execution budget; previous files are retained.

Notes

Binary identity is caller-supplied, not source/build attestation. The two upstream observables use different recoil settings and are not one cascade energy ledger. Seed-batch standard errors describe sampling dispersion only; zero observed events or zero dispersion do not establish zero uncertainty or a confidence bound.

validation.rustbca_reference.main()[source]

Execute an internal worker or a caller-identified RustBCA request from JSON.

Return type:

None

Check retained native build inputs without claiming independent attestation.

validation.rustbca_build_receipt.verify_rustbca_build_receipt(receipt, *, expected_receipt_sha256, expected_binary_sha256)[source]

Verify a pinned local build observation and its retained file dependencies.

Parameters:

  • receipt (Path) – Native build result.json beside source/, build.log and build_source.py. The recorded binary path must still resolve to the observed build output.

  • expected_receipt_sha256 (str) – Previously captured SHA256 of the exact observation, supplied by the caller.

  • expected_binary_sha256 (str) – SHA256 independently selected for the runtime extension to execute.

Returns:

Input-custody status and pinned identities. Independent attestation and physical admission remain false, even when every file matches.

Return type:

dict[str, Any]

Raises:

  • ValueError – If identities, source inventory, build outcome or retained bytes disagree.

  • OSError – If any required retained file cannot be read.

Notes

This validates the local record’s consistency, not who produced it or whether its asserted compilation occurred. The source inventory is pinned separately from the caller’s record. Host toolchain hermeticity and binary reproducibility are not established. Recheck after execution to detect changed retained inputs.

Build an optional RustBCA wheel and retain source-to-binary observations.

tools.build_rustbca_reference.build_rustbca_reference(source_archive, output, *, python, cargo, rustc, timeout_seconds=600.0, fetch_dependencies=False)[source]

Build a fresh frozen native library, local-platform wheel and custody receipt.

Parameters:

  • source_archive (Path) – Exact pinned upstream tar.gz, already acquired by the caller.

  • output (Path) – New retained build directory. Existing directories are never overwritten.

  • python (Path) – CPython interpreter whose ABI the optional extension targets.

  • cargo (Path) – Explicit compiler executable paths, hashed before and after compilation. Required dependencies must already be available to Cargo’s frozen resolver.

  • rustc (Path) – Explicit compiler executable paths, hashed before and after compilation. Required dependencies must already be available to Cargo’s frozen resolver.

  • timeout_seconds (float) – Finite total subprocess budget in seconds, greater than zero and at most 1800. Failed phases additionally allow at most five seconds to reap their leader; failure receipts retain the PID and any signalling or reaping error.

  • fetch_dependencies (bool) – Explicitly permit Cargo fetch –locked before frozen compilation. Both phases share the deadline; downloaded dependencies remain pinned by the lockfile.

Returns:

Local observation binding sources, compiler identities, binary and wheel. This does not certify hermetic builds, independent attestation or physics.

Return type:

dict[str, Any]

Raises:

  • ValueError – For invalid limits, source identity, unsupported runtime or changed inputs.

  • FileExistsError – If output already exists.

  • subprocess.SubprocessError – If a compiler/probe fails or exceeds the remaining deadline.

  • OSError – If required input files or executables are unavailable.

Notes

The builder uses two Cargo jobs and a fresh target directory. On failure it retains result.json with a failure status, signals its compiler process group and attempts bounded leader reaping. The receipt distinguishes an unreaped leader from successful reaping; reaping alone does not prove group absence. wheel 0.47.0 is required to write checked RECORD entries. The generated wheel uses the local platform tag, never an unaudited manylinux claim.

tools.build_rustbca_reference.main()[source]

Build the pinned optional reference from caller-selected local tools and archive.

Return type:

None