Runtime Selection¶

Contract¶

Runtime selection declares the requested backend, device, precision, and execution policy before stages are authored. Requested selection is preserved separately from resolved execution.

Governing equations¶

This page introduces no physical equation; it owns the runtime descriptor and its lowering.

Symbols and SI units¶

All fields are identifiers or counts; no physical units are owned here.

Assumptions and validity¶

Selection values are validated immediately. The planner resolves the final backend/device lane and fails capability checks when the request cannot be satisfied.

Python API¶

# %% Runtime selection before authoring
import fullmag as fm

nm = 1.0e-9

study = fm.study("runtime_selection_api_example")
study.engine("fdm")
study.device("cpu", precision="double")
study.mode("strict")
study.threads(4)

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¶

The runtime descriptor lowers into the runtime block carrying backend_target, device_target, gpu_count, device_index, cpu_threads, execution_mode, and execution_precision.

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 intent is preserved verbatim. Resolved execution is the planner’s capability result and must be recorded separately in provenance. Invalid values fail immediately; unsatisfiable lanes fail capability checks without silent fallback.

Discrete realization¶

This page owns authoring and lowering only.

Implementation mapping¶

Anchors: packages/fullmag-py/src/fullmag/model/problem.py (class RuntimeSelection) and the module-level selection functions in packages/fullmag-py/src/fullmag/world.py.

Validation¶

Ownership tests compare this inventory with live signatures and validate the adjacent source map.

Limitations¶

Multi-GPU (gpu_count > 1) is rejected as unimplemented. GPU source presence and compilation do not replace executed-device qualification.

Scientific bibliography¶

No physical model is introduced.

Control Room crosswalk¶

Status: Runtime and provenance data are inspection-only; they are not standalone authoring controls.

not implemented: frontend support for runtime-selection and artifact-publication parameters. See Control Room 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¶