Quantities

Last changes: Documentation changelog

Contract

This page records the canonical quantity identifiers and the generic quantity-driven output used to persist them.

Governing equations

Quantity definitions belong to the interaction and observable pages; this page owns identity and output lowering.

Symbols and SI units

Fields and energies carry the units defined in their owning pages; magnitude reductions preserve those units.

Assumptions and validity

Quantity ids and optional reductions/components are validated immediately against canonical sets.

Python API

Python

Type

Default

SI unit

Validation

Meaning

Backend support

ProblemIR

—

—

—

\(1\)

—

—

FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative

—

SaveQuantity.quantity_id

str

required

\(1\)

Canonical id; uppercase M normalizes to m

Quantity to save

FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative

quantity id

SaveQuantity.every

float

required

\(\mathrm{s}\)

Positive

Save interval

FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative

cadence

SaveQuantity.reduction

str | None

None

\(1\)

average, sum, min, max, or magnitude

Spatial reduction

FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative

reduction

SaveQuantity.component

str | None

None

\(1\)

x, y, z, magnitude, or 3D

Component selector

FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative

component

Canonical ids include magnetization and effective-field vectors, energy scalars, and transport fields (V_electric, J_charge, spin_potential, spin_current_tensor among others).

Complete stage-first example

# %% Generic quantity-driven output
import fullmag as fm

nm = 1.0e-9

study = fm.study("quantities_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.save("m", every=1.0e-13)
study.stages.add_run(stage_id="run", until=1.0e-12)

ProblemIR

SaveQuantity.to_ir() emits the quantity id, cadence, and optional reduction/component.

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.

Unknown ids and invalid reductions/components fail immediately; legacy M is normalized, never silently reinterpreted.

Discrete realization

Canonical ids must match the fullmag-quantities Rust crate so transport and storage agree.

Implementation mapping

Anchor: packages/fullmag-py/src/fullmag/model/outputs.py (class SaveQuantity, _KNOWN_QUANTITY_IDS).

Validation

Ownership tests compare this inventory with live ids and reduction sets.

Limitations

Requesting a quantity does not guarantee the configured interactions materialize it; planner legality is authoritative.

Scientific bibliography

No physical model is introduced.

Control Room crosswalk

Status: Table/field autosave and result inspection are partial; unsupported output formats remain not implemented.

Python/API surface

Control Room path

Status

Transaction

Parameters documented on this page

Model Explorer -> Stages -> <stage> -> Autosave

partial

Submit autosave draft; output resources are revised after execution

Parameters without a named UI field

Model Explorer -> Stages -> <stage> -> Autosave

not implemented

Python-only until implemented

not implemented: frontend support for output parameters not rendered by the autosave/result inspectors. See Control Room capability register for the support matrix and not implemented policy. Frontend source owner: apps/control-room/src/modules/inspector/panels/stages/AutosaveStageInspector.tsx (AutosaveStageInspector).

Source-code index

Claim

Path

Stable symbol

Responsibility

Evidence

Quantity output

packages/fullmag-py/src/fullmag/model/outputs.py

class SaveQuantity

Id-driven output

Ownership test

Source-map coverage

Claim

Path

Stable symbol

Responsibility

Evidence

Generic quantity output validation and lowering.

packages/fullmag-py/src/fullmag/model/outputs.py

class SaveQuantity

Generic quantity output validation and lowering.

Source-map validator and focused API tests