TimeEvolution Study and add_time Stage Contract¶
Last changes: Documentation changelog
1. Physical problem and overview¶
fm.TimeEvolution (and the stage-workflow builder study.stages.add_time(...) / world.time_stage(...)) defines a physical time-domain integration study or stage that evolves the magnetization field \(\mathbf{m}(\mathbf{x}, t)\) over a finite time interval \([t_0, t_0 + T]\) under the Landau–Lifshitz–Gilbert (LLG) equation with precession enabled (\(s_{\mathrm{prec}} = 1\)). It owns the LLG dynamics policy, field/scalar output schedules (outputs), optional tabular autosave (table_autosave), and stage-applicable FrozenSpins constraints.
2. Governing equations¶
Over a time-evolution stage of duration \(T = t_{\mathrm{end}} - t_0 > 0\), each active magnetic degree of freedom \(i \in \mathcal{A}\) (\(M_{s,i} > 0\)) integrates
subject to \(\|\mathbf{m}_i(t)\|_2 = 1\) and \(\dot{\mathbf{m}}_j(t) = \mathbf{0}\) on any degree of freedom \(j\) belonging to an active FrozenSpins constraint set.
3. Symbols and SI units¶
Symbol |
Meaning |
SI unit |
|---|---|---|
\(\mathbf{m}_i\) |
Reduced magnetization unit vector at active node/cell \(i\) |
\(1\) |
\(\mathbf{H}_{\mathrm{eff},i}\) |
Total effective magnetic field at node/cell \(i\) |
\(\mathrm{A\,m^{-1}}\) |
\(\gamma_0\) |
Reduced gyromagnetic ratio ( |
\(\mathrm{m\,A^{-1}\,s^{-1}}\) |
\(\alpha_i\) |
Dimensionless Gilbert damping parameter |
\(1\) |
\(\boldsymbol{\tau}_{\mathrm{direct},i}\) |
Direct current-induced spin-torque rate |
\(\mathrm{s^{-1}}\) |
\(t_0\) |
Stage initial physical time |
\(\mathrm{s}\) |
\(T\) |
Stage physical duration ( |
\(\mathrm{s}\) |
\(t\) |
Physical simulation time |
\(\mathrm{s}\) |
4. Assumptions and limits of validity¶
Full precessional dynamics: Unlike
Relaxation(algorithm="llg_overdamped"),TimeEvolutionalways retains the conservative precessional torque \(-\gamma_0(1+\alpha^2)^{-1}\mathbf{m}\times\mathbf{H}_{\mathrm{eff}}\).Output horizon requirement: Standalone
TimeEvolutionstudies require either a non-emptyoutputssequence with positive time horizon or a validtable_autosaveschedule so that the integration interval is well-defined; in stage workflows (study.stages.add_time(duration=...)), the explicitdurationparameter sets \(T > 0\).
5. Python API and parameter contract¶
Constructor and stage-builder signatures¶
fm.TimeEvolution(
*,
dynamics: LLG,
outputs: Sequence[TimeOutputSpec],
constraints: Sequence[FrozenSpins] = (),
table_autosave: TableAutosave | None = None,
)
study.stages.add_time(
*,
name: str | None = None,
duration: float,
Bx: float | None = None,
By: float | None = None,
Bz: float | None = None,
save_m_every: float | None = None,
save_table_every: float | None = None,
outputs: Sequence[TimeOutputSpec] = (),
constraints: Sequence[FrozenSpins] = (),
)
Parameter reference¶
Python parameter |
Type |
Default |
SI unit |
Validation |
Meaning |
Backend support |
|
|---|---|---|---|---|---|---|---|
|
|
required |
mixed |
typed dynamics policy |
time-domain equation and integrator |
planner-dependent |
|
|
|
required |
mixed |
typed outputs; empty sequence legal |
requested field/scalar/snapshot sampling |
planner-dependent |
|
|
|
|
\(1\) |
typed frozen-spin constraints; references resolved at problem/planner boundary |
stage-applicable magnetization constraints |
capability-gated by target and lane |
canonical magnetization constraints associated with the study |
|
|
|
mixed |
typed autosave policy |
optional scalar-table sampling |
planner/runtime-dependent |
|
Executable Python example¶
# %%
import fullmag as fm
world = fm.World(
dx=5e-9,
dy=5e-9,
dz=5e-9,
nx=20,
ny=5,
nz=1,
boundaries=fm.BoundaryConfig.open(method="fft"),
)
world.add_box(
"strip",
size=(100e-9, 25e-9, 5e-9),
material=fm.Material.permalloy(Ms=8.0e5, Aex=1.3e-11, alpha=0.02),
m_init=fm.VectorFieldSpec.uniform((1.0, 0.05, 0.0)),
demag=True,
)
study = fm.study(world, target="fdm", device="cpu", precision="fp64")
study.solver(
integrator="rk45",
gamma=2.211e5,
adaptive_timestep=fm.AdaptiveTimestep(
atol=1e-6,
rtol=1e-4,
dt_initial=1e-13,
dt_min=1e-15,
dt_max=2e-12,
),
)
study.stages.add_time(
name="rf_pulse",
duration=0.5e-9,
Bx=20e-3,
By=3e-3,
Bz=0.0,
save_m_every=50e-12,
save_table_every=10e-12,
)
ir = study.to_problem_ir()
assert ir["study"]["kind"] == "stage_workflow"
assert ir["study"]["stages"][0]["kind"] == "time"
assert ir["study"]["stages"][0]["duration"] == 0.5e-9
6. ProblemIR and canonical script representation¶
{
"study": {
"kind": "stage_workflow",
"dynamics": {
"equation": "llg",
"gyromagnetic_ratio": 221100.0,
"integrator": "rk45",
"fixed_timestep": null,
"adaptive_timestep": {
"atol": 1e-06,
"rtol": 0.0001,
"dt_initial": 1e-13,
"dt_min": 1e-15,
"dt_max": 2e-12,
"safety": 0.9,
"growth_limit": 2.0,
"shrink_limit": 0.2,
"max_spin_rotation": null,
"norm_tolerance": null
},
"field_refresh": null
},
"stages": [
{
"kind": "time",
"name": "rf_pulse",
"duration": 5e-10
}
]
}
}
7. Round-trip, provenance, and failure semantics¶
Requested intent vs. resolved execution:
TimeEvolutionandadd_timestages preserve the user’sdynamics,outputs,constraints, andtable_autosaveinProblemIR(requested intent) while recording resolved stepper decisions and sample counts in the execution receipt (resolved execution).Validation errors: Non-
LLGdynamics, invalidTimeOutputSpecorFrozenSpinsitems, or non-positive stagedurationraise immediateTypeError/ValueErrorvalidation errors in Python.Unsupported combinations: Combining
FrozenSpinsor coupled elastodynamics with an unqualified backend/integrator lane is rejected as an unsupported combination by the planner.
8. Discrete realization and numerical operators¶
FEM CPU & GPU: Advances nodal magnetization via
context_step_explicit_rk_mfem(CPU) orgpu_rk_device_resident_step(GPU) and records scheduled field/scalar snapshots at accepted step boundaries.FDM CPU & GPU: Advances Cartesian SoA/AoS magnetization via explicit RK,
abm3, orcoupled_imex_ark2incrates/fullmag-runner/src/solvers/fdm/workflows/time_domain/.
9. Backend and device implementation mapping¶
Solver |
Device |
Status |
Notes |
|---|---|---|---|
FEM |
CPU |
|
Native MFEM explicit RK time-domain loop and snapshot emission. |
FEM |
GPU |
|
Device-resident CUDA RK loop ( |
FDM |
CPU |
|
Cartesian SoA time-domain workflow ( |
FDM |
GPU |
|
CUDA time-domain workflow and FFT demagnetization. |
10. Validation and benchmark gates¶
Validated in
packages/fullmag-py/tests/test_llg_solver_contract.py,test_standard_problem_4_fem.py,test_standard_problem_5_fdm.py, andtest_standard_problem_5_fem.py.
11. Known limitations and operational constraints¶
Snapshot and table sampling intervals are evaluated at accepted step boundaries; set
dt_maxat or below the finest sampling interval when exact uniform temporal spacing is required without interpolation.
12. Scientific bibliography¶
M. J. Donahue and D. G. Porter, OOMMF User’s Guide, Version 1.0, NISTIR 6376 (1999).
Control Room crosswalk¶
Status: Time-evolution stage authoring, live scalar time-series charts, and interactive stage re-execution are partial; custom stopping predicates (fm.run_until), low-level integrator hooks, or specialized stage closures remain not implemented in the form editor.
Python/API surface |
Control Room path |
Status |
Transaction |
|---|---|---|---|
Stage duration, timestep / integrator policy, & |
|
|
|
Live magnetization, energy & torque traces |
|
|
Binary FMTB stream + WebSocket |
Per-stage texture overrides ( |
|
|
Staged draft mutation on |
Python-only constraints or programmatic callbacks |
|
|
Authored via Python script or live |
See Control Room capability register and Study Authoring, Stages & Interactive Re-Execution.
Frontend source owners: apps/control-room/src/modules/inspector/panels/stages/RunStageInspector.tsx, apps/control-room/src/modules/inspector/panels/studyStageApplyAndRun.ts, and apps/control-room/src/modules/live-charts/LiveChartsView.tsx.
13. Source-code index¶
Layer |
File |
Symbol / entrypoint |
Responsibility |
|---|---|---|---|
Python DSL |
Owns dynamics, outputs, frozen-spin constraints, autosave, and lowering |
||
Python DSL |
Stage-workflow |
||
Native FEM CPU |
Native FEM CPU explicit RK step execution |
||
Native FEM GPU |
Native FEM GPU device-resident explicit RK step execution |