Round Trip¶

Contract¶

Round trip covers authoring-to-IR lowering and the reverse normalization paths that keep the Python surface, canonical ProblemIR, and exports consistent.

Governing equations¶

This page introduces no governing equation.

Symbols and SI units¶

Units carried by parameters follow their owning pages; exact lowering is unit-preserving.

Assumptions and validity¶

Lowering resolves runtime selection and converts authored parameters to canonical quantities without changing requested intent. Validation failures happen at authoring or planning time.

Python API¶

# %% Stage-first study ready for lowering
import fullmag as fm

nm = 1.0e-9

study = fm.study("round_trip_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-9)

ProblemIR¶

Problem.to_ir() builds the request with resolved runtime, geometry assets, materials, regions, study pipeline, and builder/script-sync manifests while preserving script-source hashing.

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.

Requested and resolved descriptors remain distinct. An FDM selection with FEM-only policy such as pbc.demag="periodic_airbox_k0" fails lowering rather than being silently converted.

Discrete realization¶

Lowering is runtime-independent and exercised by authoring tests.

Implementation mapping¶

Anchor: packages/fullmag-py/src/fullmag/model/problem.py (Problem.to_ir, RuntimeSelection.resolved, RuntimeSelection.to_runtime_metadata).

Validation¶

Authoring and graph round-trip tests exercise the same lowering as the public export.

Limitations¶

Exact serialized output shape may evolve with IR_VERSION; consumers must read the version field instead of assuming a frozen layout.

Scientific bibliography¶

No physical model is introduced.

Control Room crosswalk¶

Status: The Control Room authors a study and lowers it to ProblemIR; direct Problem/IR editing is not exposed.

not implemented: frontend support for standalone Problem/ProblemIR authoring. See Control Room capability register for the support matrix and not implemented policy. Frontend source owner: apps/control-room/src/modules/inspector/panels/StudyInspectorPanel.tsx (StudyInspectorPanel).

Source-code index¶