Relaxation Study, RelaxStop, and add_relax Stage Contract¶
Last changes: Documentation changelog
1. Physical problem and overview¶
fm.Relaxation (together with fm.RelaxStop and the stage-workflow builder study.stages.add_relax(...) / world.relax_stage(...)) defines a micromagnetic equilibrium relaxation study or stage. It drives the magnetization field \(\mathbf{m}(\mathbf{x})\) to a local minimum of the total micromagnetic energy \(E[\mathbf{m}]\) where the local torque residual \(\|\mathbf{m}_i \times \mathbf{H}_{\mathrm{eff},i}\|_2\) falls below the canonical stopping threshold \(\varepsilon_{\tau}\) across at least three consecutive accepted states.
Fullmag supports four relaxation algorithm families (Relaxation.algorithm):
"llg_overdamped"— pure-damping Landau–Lifshitz–Gilbert integration (\(s_{\mathrm{prec}} = 0\)) with explicit Runge–Kutta (heun,rk4,rk23,rk45) orabm3stepping,"projected_gradient_bb"— Riemannian projected gradient descent on \(\mathbb{S}^2\) with Barzilai–Borwein step sizes and non-monotone/monotone Armijo line search,"nonlinear_cg"— Riemannian nonlinear conjugate gradient minimization on \(\mathbb{S}^2\) with vector transport and Armijo line search,"tangent_plane_implicit"— linearly implicit tangent-space mass-plus-exchange solve with unit-sphere retraction and Armijo certification on the FEM CPU/MFEM development lane (execution_mode="extended").
2. Governing equations¶
At a local equilibrium on \(\mathbb{S}^2\), the tangential component of the effective magnetic field vanishes at every active magnetic node or cell \(i \in \mathcal{A}\) (\(M_{s,i} > 0\)):
When a user supplies torque_tolerance in tesla (\(\tau_{\mathrm{T}}\) via tolT), RelaxStop normalizes it to the canonical field-residual threshold in \(\mathrm{A\,m^{-1}}\) via vacuum permeability \(\mu_0\):
3. Symbols and SI units¶
Symbol |
Meaning |
SI unit |
|---|---|---|
\(\mathbf{m}_i\) |
Reduced magnetization unit vector at active point \(i\) |
\(1\) |
\(\mathbf{H}_{\mathrm{eff},i}\) |
Total effective magnetic field at point \(i\) |
\(\mathrm{A\,m^{-1}}\) |
\(\boldsymbol{\tau}_i\) |
Local effective-field torque residual \(\mathbf{m}_i \times \mathbf{H}_{\mathrm{eff},i}\) |
\(\mathrm{A\,m^{-1}}\) |
\(\tau_{\max}\) |
Maximum active-set torque residual norm |
\(\mathrm{A\,m^{-1}}\) |
\(\varepsilon_{\tau}\) |
Canonical torque stopping threshold ( |
\(\mathrm{A\,m^{-1}}\) |
\(\tau_{\mathrm{T}}\) |
User-facing magnetic induction torque threshold ( |
\(\mathrm{T}\) |
\(\mu_0\) |
Vacuum permeability (\(4\pi \times 10^{-7}\,\mathrm{N\,A^{-2}}\)) |
\(\mathrm{N\,A^{-2}}\) |
\(\mathcal{A}\) |
Active magnetic cell/node index set (\(M_{s,i} > 0\)) |
\(1\) |
4. Assumptions and limits of validity¶
Local vs. global minimum: All four relaxation algorithms converge to a local minimum (or stationary point) of \(E[\mathbf{m}]\) within the basin of attraction of the initial state \(\mathbf{m}_0\).
Three-consecutive-sample confirmation: To prevent premature termination during transient zero crossings,
RelaxationTorqueConfirmation::observerequires at least three consecutive accepted states satisfying \(\tau_{\max} \le \varepsilon_{\tau}\) (and \(\Delta E \le \varepsilon_E\) whenenergy_tolerance_jis active).Direct-minimizer exclusivity with
LLGdynamics: Direct energy minimizers (projected_gradient_bb,nonlinear_cg,tangent_plane_implicit) manage their own line-search step sizes and reject an explicitLLGdynamics payload.
5. Python API and parameter contract¶
Constructor and stage-builder signatures¶
fm.RelaxStop(
*,
torque_tolerance_apm: float | None = 0.7957747154594767,
energy_tolerance_j: float | None = None,
max_steps: int | None = 50000,
max_time_s: float | None = None,
)
fm.Relaxation(
*,
outputs: Sequence[TimeOutputSpec],
algorithm: str = "llg_overdamped",
stop: RelaxStop | None = None,
torque_tolerance: float | None = None,
energy_tolerance: float | None = None,
max_steps: int | None = None,
dynamics: LLG | None = None,
constraints: Sequence[FrozenSpins] = (),
table_autosave: TableAutosave | None = None,
)
study.stages.add_relax(
*,
name: str | None = None,
algorithm: str = "llg_overdamped",
tolT: float | None = None,
tolA: float | None = None,
energy_tolerance_j: float | None = None,
max_steps: int = 50000,
Bx: float | None = None,
By: float | None = None,
Bz: float | None = None,
)
Parameter reference¶
Python parameter |
Type |
Default |
SI unit |
Validation |
Meaning |
Backend support |
|
|---|---|---|---|---|---|---|---|
|
|
|
\(1\) |
Field/scalar outputs; an empty sequence is valid |
Output requests recorded during relaxation |
FEM/FDM CPU/GPU; planner checks materialization |
|
|
|
|
\(1\) |
One of |
Relaxation algorithm identifier |
FEM/FDM CPU/GPU for |
|
|
|
|
mixed |
Positive tolerances and step counts; one time bound at most |
Canonical stop contract |
FEM/FDM CPU/GPU |
|
|
|
|
\(\mathrm{T}\) |
Positive; conflicts with |
Convergence threshold on torque |
FEM/FDM CPU/GPU |
|
|
|
|
\(\mathrm{J}\) |
Positive when set |
Energy-delta stop bound |
FEM/FDM CPU/GPU |
|
|
|
|
\(1\) |
Positive integer |
Maximum relaxation iterations |
FEM/FDM CPU/GPU |
|
|
|
|
mixed |
Required by |
LLG parameters for the overdamped lane |
FDM/FEM CPU/GPU |
|
|
|
|
mixed |
See Autosave |
Tabular autosave policy |
FEM/FDM CPU/GPU |
|
Executable Python example¶
# %%
import fullmag as fm
world = fm.World(
dx=5e-9,
dy=5e-9,
dz=5e-9,
nx=16,
ny=4,
nz=1,
boundaries=fm.BoundaryConfig.open(method="fft"),
)
world.add_box(
"strip",
size=(80e-9, 20e-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.2, 0.05)),
demag=True,
)
study = fm.study(world, target="fdm", device="cpu", precision="fp64")
study.stages.add_relax(
name="ground_state",
algorithm="projected_gradient_bb",
tolT=1e-6,
max_steps=5000,
)
ir = study.to_problem_ir()
assert ir["study"]["stages"][0]["kind"] == "relax"
assert ir["study"]["stages"][0]["algorithm"] == "projected_gradient_bb"
6. ProblemIR and canonical script representation¶
{
"study": {
"kind": "stage_workflow",
"stages": [
{
"kind": "relax",
"name": "ground_state",
"algorithm": "projected_gradient_bb",
"stop": {
"torque_tolerance_apm": 0.7957747154594768,
"energy_tolerance_j": null,
"max_steps": 5000,
"max_time_s": null
}
}
]
}
}
7. Round-trip, provenance, and failure semantics¶
Requested intent vs. resolved execution:
ProblemIRstores the canonicalalgorithmandstoppayload (requested intent), while the execution receipt records the resolved minimizer/integrator, terminal torque \(\tau_{\max}\), accepted step count, and convergence status (resolved execution).Validation errors: Supplying both
tolTandtolA, supplyingdynamicsto a direct minimizer (projected_gradient_bb,nonlinear_cg,tangent_plane_implicit), or non-positive tolerances/step limits raise immediateValueErrorvalidation errors.Unsupported combinations: Requesting
tangent_plane_implicitontarget="fdm",device="gpu", orexecution_mode="strict"is rejected as an unsupported combination by the planner.
8. Discrete realization and numerical operators¶
Overdamped LLG (
llg_overdamped): Disables precession (\(s_{\mathrm{prec}} = 0\)) viallg_overdamped_uses_pure_dampingand integrates the pure-damping ODE with adaptive (rk45,rk23) or fixed (heun,rk4,abm3) stepping.Direct Riemannian minimizers (
projected_gradient_bb,nonlinear_cg): Compute the sphere-projected gradient and advance with certified Armijo energy decrease on FEM CPU/GPU (backends/fem/gpu/cuda/relaxation/pgbb.cpp,nonlinear_cg.cpp) and FDM CPU/GPU (execute_projected_gradient_bb,execute_nonlinear_cg).Tangent-plane implicit (
tangent_plane_implicit): Solves the tangent-space mass-plus-exchange linear system inrun_tangent_plane_implicit_step(backends/fem/cpu/mfem/relaxation/tangent_plane_implicit.cpp).
9. Backend and device implementation mapping¶
Solver |
Device |
Status |
Supported algorithms |
|---|---|---|---|
FEM |
CPU |
|
|
FEM |
GPU |
|
|
FDM |
CPU |
|
|
FDM |
GPU |
|
|
10. Validation and benchmark gates¶
Validated in
backends/fem/tests/relaxation_operator_contract.cpp,backends/fem/tests/relaxation_energy_derivative_contract.cpp, andpackages/fullmag-py/tests/test_problem_ir.py.
11. Known limitations and operational constraints¶
Reaching
max_stepsormax_time_swithout satisfying the three-sample torque/energy predicate fails closed and marks the relaxation stage as unconverged.
12. Scientific bibliography¶
J. Barzilai and J. M. Borwein, Two-point step size gradient methods, IMA J. Numer. Anal. 8, 141–148 (1988).
S. Bartels and A. Prohl, Convergence of an implicit finite element method for the Landau–Lifshitz–Gilbert equation, SIAM J. Numer. Anal. 44, 1405–1419 (2006).
Control Room crosswalk¶
Status: Stage authoring, initial-state handoff, and convergence inspection are partial; specialized Python constraint closures and custom stop-policy extensions without dedicated UI controls remain not implemented in the stage editor.
Python/API surface |
Control Room path |
Status |
Transaction |
|---|---|---|---|
Core relaxation parameters ( |
|
|
Apply stage draft and run |
Live convergence trace & scalar readback |
|
|
FMTB table stream over |
Python-authored |
|
|
Edited in Python or authored in |
See Control Room capability register and Study Authoring, Stages & Interactive Re-Execution.
Frontend source owners: apps/control-room/src/modules/inspector/panels/StudyStageDraftEditor.tsx, apps/control-room/src/modules/inspector/panels/stages/RelaxStageInspector.tsx, and apps/control-room/src/modules/inspector/panels/studyStageApplyAndRun.ts.
13. Source-code index¶
Layer |
File |
Symbol / entrypoint |
Responsibility |
|---|---|---|---|
Python DSL |
Relaxation study and algorithm policy lowering |
||
Python DSL |
Relaxation stop criteria normalization |
||
Python DSL |
Stage-workflow relaxation builder and lowering |
||
Shared Runner |
Accepted-state torque and energy convergence predicate |
||
FEM Runner |
Native FEM overdamped LLG relaxation execution |
||
Native FEM CPU |
Native FEM CPU/MFEM tangent-plane implicit relaxation step |