--- title: Artifacts status: partial doc_kind: reference audience: user owner: fullmag-public-docs --- (public-docs-python-api-runtime-artifacts)= # Artifacts (python-api-runtime-artifacts-problem-statement)= ## Contract Artifacts are the persisted run outputs: the output directory, saved magnetization states, tables, and field snapshots written by the runtime. (python-api-runtime-artifacts-governing-equations)= ## Governing equations No physical equation is owned here. (python-api-runtime-artifacts-symbols-and-si-units)= ## Symbols and SI units Magnetization state is stored with its own unit metadata; table quantities carry the units defined by the corresponding observables. (python-api-runtime-artifacts-assumptions-and-validity)= ## Assumptions and validity State formats are validated against the supported set (`json`, `zarr`, `h5`); format is inferred from the path extension when `"auto"` is requested. (python-api-runtime-artifacts-python-api)= ## Python API | Python | Type | Default | SI unit | Validation | Meaning | Backend support | ProblemIR | | --- | --- | --- | --- | --- | --- | --- | --- | | --- | --- | --- | $1$ | --- | --- | FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative | --- | | `Result.output_dir` | `str \| None` | `None` | $1$ | Directory path | Directory for run artifacts | FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative | output dir | | `Result.save_state(path, format=..., dataset=...)` | method | `format="auto"`, `dataset="values"` | $1$ | Requires `final_magnetization` | Persist final state | FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative | n/a (runtime output) | | `save_magnetization(path, values, ...)` | function | `format="auto"` | $1$ | `json`, `zarr`, or `h5` | Low-level state writer | FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative | n/a | ### Complete stage-first context ```python # %% Stage-first study whose executed result can persist final state import fullmag as fm nm = 1.0e-9 study = fm.study("artifacts_api_example") study.engine("fdm") study.device("cpu", precision="double") study.mode("strict") study.objects.mesh.defaults(cell_size=(2 * nm, 2 * nm, 5 * nm)) film = study.geometry(fm.Box(100 * nm, 20 * nm, 5 * nm), name="film") film.Ms = 800.0e3 film.Aex = 13.0e-12 film.alpha = 0.02 film.m = fm.init.UniformMagnetization((1.0, 0.0, 0.0)) study.exchange() study.stages.add_run(stage_id="run", until=1.0e-12) # After execution with a final magnetization, the result persists state: # result.save_state("relaxed_m.zarr", format="zarr") ``` (python-api-runtime-artifacts-problem-ir)= ## ProblemIR Artifacts are runtime outputs; they are not authoring inputs and have no lowering destination. (python-api-runtime-artifacts-round-trip-and-failure-semantics)= ## Round-trip and failure semantics Requested intent is the value authored by Python and preserved in ProblemIR; resolved execution is the planner or realization result. Validation errors identify the violated domain rule, and unsupported combinations are rejected explicitly rather than silently substituted. Saving without `final_magnetization` raises immediately. Unsupported formats raise rather than writing a best-effort file. (python-api-runtime-artifacts-discrete-realization)= ## Discrete realization State serialization lives in `fullmag/init/state_io.py` and supports JSON, Zarr, and HDF5. (python-api-runtime-artifacts-implementation-mapping)= ## Implementation mapping Anchors: `packages/fullmag-py/src/fullmag/runtime/simulation.py` (`Result.save_state`) and `packages/fullmag-py/src/fullmag/init/state_io.py` (`save_magnetization`). (python-api-runtime-artifacts-validation)= ## Validation State round-trip is covered by read/write tests; ownership tests validate the source map. (python-api-runtime-artifacts-limitations)= ## Limitations Artifact format support does not guarantee interchange with other tools; readers must honor the stored unit and dataset metadata. (python-api-runtime-artifacts-scientific-bibliography)= ## Scientific bibliography No physical model is introduced. (python-api-runtime-artifacts-source-code-index)= ## Control Room crosswalk Status: Runtime and provenance data are inspection-only; they are not standalone authoring controls. | Python/API surface | Control Room path | Status | Transaction | |---|---|---|---| | Parameters documented on this page | `Model Explorer -> Runtime` | `inspection-only` | No runtime-authoring transaction | | Parameters without a named UI field | `Model Explorer -> Runtime` | `not implemented` | Python-only until implemented | not implemented: frontend support for runtime-selection and artifact-publication parameters. See [Control Room capability register](/frontend/capability-register) for the support matrix and not implemented policy. Frontend source owner: `apps/control-room/src/modules/inspector/panels/RuntimeExplorerInspectorPanels.tsx (RuntimeExplorerInspectorPanels)`. ## Source-code index | Claim | Path | Stable symbol | Responsibility | Evidence | |---|---|---|---|---| | State persistence | `packages/fullmag-py/src/fullmag/runtime/simulation.py` | `Result.save_state` | Public save entrypoint | Ownership test | | Serialization formats | `packages/fullmag-py/src/fullmag/init/state_io.py` | `save_magnetization`, `load_magnetization` | JSON/Zarr/HDF5 round-trip | Read/write tests | ### Source-map coverage | Claim | Path | Stable symbol | Responsibility | Evidence | |---|---|---|---|---| | Runtime artifact access and state persistence entrypoint. | `packages/fullmag-py/src/fullmag/runtime/simulation.py` | `class Result` | Runtime artifact access and state persistence entrypoint. | Source-map validator and focused API tests | | Magnetization artifact serialization. | `packages/fullmag-py/src/fullmag/init/state_io.py` | `save_magnetization` | Magnetization artifact serialization. | Source-map validator and focused API tests |