Relaxation¶

LLG integrator vocabulary (only for llg_overdamped)¶

The solver keyword selects the integrator used by the damping-only LLG stage. It does not select one of the three relaxation algorithms. The Python DSL canonicalizes dp54 to rk45 and bs23 to rk23; the canonical name is what is written to ProblemIR and provenance. None and "auto" resolve to rk23 when the stage is lowered.

coupled_imex_ark2 is accepted by the shared dynamics vocabulary because it belongs to the transient spin-transport contract. A standalone relaxation stage without a transient spin_transport module is rejected by ProblemIR validation; it must not be presented as a fourth relaxation algorithm. abm3 is available on FDM and reference FEM paths, but the native FEM GPU ABI deliberately rejects it. The exact resolved lane is part of execution provenance.

What one relaxation iteration means¶

The three algorithms share the same accepted-state observation but differ in the state update:

1. Refresh the effective field and evaluate the accepted-state torque. The torque threshold is checked in A/m after converting a tolT request through \(\mu_0\).

2. For llg_overdamped, advance the pure-damping ODE with the requested fixed/adaptive integrator. A rejected adaptive trial does not advance the relaxation clock or accepted-step counter.

3. For projected_gradient_bb, form a tangent gradient, choose the alternating BB step, retract \(\mathbf m-\lambda\mathbf g\), and apply the 20-rejection Armijo limit.

4. For nonlinear_cg, transport the previous tangent vectors, form PR+, enforce a descent direction, retract \(\mathbf m+\lambda\mathbf p\), and apply the 30-rejection Armijo limit.

5. Commit only an accepted state. Update the 50-sample energy window and the at-least-three- consecutive-sample torque confirmation, then resolve convergence or the applicable budget/failure reason.

Rejected trial states, failed field evaluations, non-finite metrics, and backend errors never become accepted relaxation states and never satisfy the completion contract.

Shared physical contract¶

All three algorithms use the same normalized magnetization and effective-field convention. For each active cell or finite-element node,

The accepted state is constrained by \(\lVert\mathbf m_i\rVert_2=1\). The public default tolT=1e-6 is a torque threshold in tesla; the runtime comparison is made against \(\varepsilon_{\tau,\mathrm{A/m}}=10^{-6}/\mu_0=0.7957747154594767\ \mathrm{A\,m^{-1}}\). The energy criterion, when present, is conjunctive with torque. max_steps and the LLG-only time ceiling are budgets, never proofs of equilibrium.

Algorithm selection and exact internal policy¶

The constants in the table are implementation policy, not public keyword arguments. They are recorded as resolved provenance when a backend exposes them. tangent_plane_implicit remains a reserved vocabulary value and is not included in this three-algorithm public contract.

Common stage API and IR boundary¶

The canonical authoring form is study.stages.add_relax(...). The complete keyword surface is tol, tolA, tolT, max_steps, algorithm, energy_tolerance, max_relaxation_time_s, max_pseudotime_s, max_physical_time_s, relax_alpha, solver, dt, max_error, dt_min, dt_max, dt_initial, max_err, adaptive_timestep, field_refresh, and stop. tol is retained only as a rejected migration sentinel; use tolT or tolA. The time aliases must agree and are valid only for llg_overdamped; all LLG controls are rejected for the two direct minimizers.

Every algorithm lowers to the same shape, with dynamics present only for overdamped LLG:

{
  "kind": "relaxation",
  "algorithm": "nonlinear_cg",
  "stop": {"torque_tolerance_apm": 0.7957747154594767, "max_steps": 50000},
  "sampling": {"outputs": []}
}

This is an explanatory projection of Relaxation.to_ir(), not an alternative authoring format. Planner resolution (solver family, FDM/FEM, CPU/GPU, precision, mesh/grid and field policy) and runtime completion/provenance are separate records.

Four implementation lanes¶

These are source/architecture statements, not blanket qualification claims. In particular, the public multilayer FDM planner currently allows only llg_overdamped; single-layer/native direct minimizer paths and executed GPU evidence must be checked separately.

What differs between FDM/FEM and CPU/GPU¶

The equations and public algorithm names are shared, but the discrete owners are not:

Consequently, “the same algorithm” means the same constrained continuum contract and acceptance inequality, not bit-identical trajectories. A CPU/GPU parity claim must include mesh/grid identity, precision, interaction list, stop policy, field-refresh policy, accepted-step metrics and resolved device provenance. A source file or to_ir() result alone is not evidence that a GPU execution occurred.

Workflow¶

The canonical user workflow is an executable fm.study(...) scenario. Geometry, material state, interaction registration, solver policy, and the ordered relaxation stage are visible in one file:

The three algorithm pages define their own equations, symbols and SI units, complete parameters, ProblemIR mapping, failure semantics, realization matrix, and source-code index. The stopping page defines the shared accepted-state completion contract. The physical contract is shared with docs/physics/0500-fdm-relaxation-algorithms.md, docs/physics/0510-fem-relaxation-algorithms-mfem-gpu.md, and docs/physics/0580-canonical-relaxation-equilibrium-contract.md.

Control Room crosswalk¶

This is a navigation page; use the terminal page named by the selected stage or solver. The category itself has no standalone editor. Numerical parameters without a matching control are not implemented in the frontend. Do not infer frontend support from Python or backend availability. See {doc}/frontend/capability-register for the current register and exact source owner.

Bibliography¶

No independent scientific model is introduced by this navigation page. Use the bibliography on the selected terminal page; this statement is an explicit applicability boundary, not an omitted reference.

Source-code index¶

This is a navigation page and introduces no standalone implementation symbol. The exact source-code index is maintained by the selected terminal page.