Snapshots

Last changes: Documentation changelog

Contract

This page records the periodic field-component snapshot output.

Governing equations

No physical equation is introduced; snapshots persist field components at a cadence.

Symbols and SI units

every is in seconds; the stored component carries the field’s unit.

Assumptions and validity

Field, component, and positive cadence are validated immediately.

Python API

Python

Type

Default

SI unit

Validation

Meaning

Backend support

ProblemIR

—

—

—

\(1\)

—

—

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

—

Snapshot.field

str

required

\(1\)

Known field id

Base field

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

snapshot.field

Snapshot.component

str

required

\(1\)

x, y, z, or 3D

Component selector

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

snapshot.component

Snapshot.every

float

required

\(\mathrm{s}\)

Positive

Save interval

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

snapshot.every_seconds

Snapshot.layer

str | None

None

\(1\)

Non-empty when set

Layer/region scope

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

snapshot.layer

Complete stage-first example

# %% Periodic full-vector magnetization snapshot
import fullmag as fm

nm = 1.0e-9

study = fm.study("snapshots_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.snapshot("m", every=1.0e-13)  # full 3D magnetization snapshot
study.stages.add_run(stage_id="run", until=1.0e-12)

ProblemIR

Snapshot.to_ir() emits {"kind": "snapshot", "field": ..., "component": ..., "every_seconds": ...} plus optional layer.

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 fields, invalid components, and non-positive cadences fail immediately.

Discrete realization

Snapshots are materialized by the runtime field-store writer at the requested cadence.

Implementation mapping

Anchor: packages/fullmag-py/src/fullmag/model/outputs.py (class Snapshot, parse_snapshot_quantity).

Validation

Ownership tests compare this inventory with live signatures.

Limitations

A snapshot request is an output contract; availability of a given field still depends on the selected interaction and lane.

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

Snapshot output

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

class Snapshot

Field-component output

Ownership test

Source-map coverage

Claim

Path

Stable symbol

Responsibility

Evidence

Snapshot field/component selection and lowering.

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

class Snapshot

Snapshot field/component selection and lowering.

Source-map validator and focused API tests