Overdamped LLG relaxation¶

Scope and purpose¶

This page documents the source-backed overdamped LLG relaxation stage, its accepted-step integrators, adaptive error policy and independent equilibrium stop contract.

Scientific and numerical model¶

The implemented model is pure damping of the LLG right-hand side with the complete active effective field; adaptive acceptance and accepted-state torque completion remain separate predicates.

Physical problem¶

llg_overdamped reuses the LLG right-hand-side and time-integration pipeline while disabling precession. It is a relaxation coordinate, not a physical switching experiment: its stage clock controls convergence and is not carried into a later run stage. The magnetization remains normalized pointwise, and the accepted state is tested using the effective-field torque.

Governing equations¶

For reduced magnetization \(\mathbf m=\mathbf M/M_s\) and effective field \(\mathbf H_{\mathrm{eff}}\), the implemented pure-damping equation is

The effective field is assembled from the active energy terms:

The stopping metric is the maximum accepted-state torque,

The time integrator can be fixed-step, adaptive embedded RK23/RK45, or the FDM/reference ABM3 multistep method. The adaptive error policy is distinct from the physical torque criterion: the local vector error controls step acceptance, while \(\tau_{\max}\) controls relaxation completion.

Integrator families and exact step control¶

The following names are accepted by the Python LLG object and by the relaxation stage builder. The table describes the numerical method, not merely a label stored in metadata.

solver=None and solver="auto" resolve to rk23 at the Python relaxation boundary. A fixed step is selected with dt=<positive seconds>. Adaptive stepping is selected with dt="auto" or with an explicit AdaptiveTimestep; executable adaptive stages require an explicit positive dt_min and dt_max. dt="auto", max_err, and max_error reject fixed-only integrators. coupled_imex_ark2 is not a fourth relaxation algorithm: ProblemIR rejects it for a plain relaxation problem unless the transient spin-transport contract is also present.

For an embedded method the implementation first forms a vector error at every active magnetic cell/node. If \(k_{s,i}\) is the stage right-hand side at point \(i\) and \(b_s^{\mathrm{hi}}\) and \(b_s^{\mathrm{lo}}\) are the two tableau weights, the error vector and its mixed tolerance scale are

\(\mathcal A\) is the active magnetic-node/cell mask; air or inactive FEM nodes do not enter the maximum. A trial is accepted exactly when \(\rho\leq1\). When rtol=0, the scale is the absolute atol value. The optional norm_tolerance and max_spin_rotation guards are folded into the same acceptance metric by taking the maximum of their normalized defects. Non-finite vectors, non-positive scales, zero active norms, or a non-finite combined metric fail closed.

The native FEM CPU/GPU and FDM CUDA controllers use the following shared scalar proposal. Let \(\rho_{k-1}\) be the previous accepted non-zero error ratio, when history exists, and let \(p\) be the embedded error-estimate order. The unclamped factor is

Here \(s\) is safety, \(q_{\min}\) is shrink_limit, and \(q_{\max}\) is growth_limit. A rejected trial is restored and retried with the smaller proposal; it does not update accepted-state stop history or previous-error history. If the error is still above one at dt_min, the attempt fails with dt_min_exhausted. Native FEM receives a rejection budget of 50 from the runner; FDM lanes use the shared typed dt_min_exhausted decision and do not expose a separate public rejection counter. The older Rust FEM reference engine has an internal 128-attempt guard and is documented as a reference path, not as the native FEM contract.

The Rust helper pi_controller_dt is a stateless reference helper: it evaluates only the single-history-free branch. It is not a substitute for the native controller above. FDM CPU’s engine implementation and native FEM/CUDA both retain the previous accepted error and use the history branch when available. FDM CPU’s absolute-only mode compares the unscaled norm directly with max_error; its mixed mode uses the normalized \(\rho\) definition above. The vector norm and reduction are lane-specific, but the resolved tolerance, controller branch, attempted/accepted steps, and actual backend/device must be recorded together.

For the public stage builder, solver=None resolves to rk23; solver="auto" has the same resolution. An executable adaptive stage must provide an explicit dt_min and dt_max. The deprecated max_error spelling is accepted only as an alias for max_err, and neither may be combined with adaptive_timestep or fixed dt controls.

Symbols and SI units¶

The reduced gyromagnetic ratio is gamma in the Python LLG object. The damping coefficient in the equation is the resolved stage-local relax_alpha when supplied; otherwise the material damping is used. The stage default is relax_alpha=1.0, which is a numerical pure-damping choice, not a claim that the material’s physical \(\alpha\) has changed globally.

Assumptions and validity¶

• The stage is deterministic and has no thermal noise unless another explicitly supported interaction changes the model.

• llg_overdamped disables only precession; it does not remove the effective-field terms.

• A fixed step is not unconditionally stable. An adaptive error pass is not a proof of physical convergence, so both adaptive acceptance and the torque stop contract are recorded.

• tolT and tolA are mutually exclusive. tolT is the public default in tesla and is converted to the canonical field residual in A/m using \(\tau_{\mathrm{A/m}}=\tau_{\mathrm T}/\mu_0\).

• A failed step, exhausted adaptive floor, invalid field solve, or non-finite state is a failure; it must not be published as a converged relaxation.

One accepted LLG relaxation step¶

For each attempt the backend follows this ownership sequence:

1. Read the current normalized magnetization and assemble the complete effective field from the interaction list. Relaxation does not remove demagnetization, exchange, anisotropy, DMI or applied-field terms.

2. Evaluate the pure-damping right-hand side. The precession term is disabled by the resolved relaxation mode; relax_alpha is a stage-local damping coefficient and does not mutate the material model stored for later stages.

3. Execute the selected tableau (Heun, RK4, RK23, RK45 or ABM3). For RK23/RK45, compare the embedded estimates, reject and retry when the normalized error exceeds one, and clamp the next step to dt_min/dt_max. For ABM3, retain the required history and use the FDM/reference path; native FEM GPU fails closed before dispatch.

4. Normalize the committed spin state, refresh the field required by the resolved field policy, and publish accepted-step observables. Only now are the torque confirmation counter, energy plateau and max_steps/time budgets advanced.

The adaptive error test controls local integration error. It cannot certify an equilibrium: the accepted state must still pass the independent torque and optional energy criteria in stopping-criteria.md.

Python API¶

This is the repository-owned stage pattern. The solver, timestep and adaptive controls below belong only to llg_overdamped. The direct minimizers do not accept an LLG dynamics object or these timestep controls; they select their line-search policy internally.

# %% Configure a FEM relaxation scenario
import fullmag as fm

nm = 1.0e-9
study = fm.study("overdamped_llg_relaxation")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")
study.universe(mode="manual", size=(700 * nm, 250 * nm, 250 * nm))

film = study.geometry(
    fm.Box(size=(500 * nm, 125 * nm, 3 * nm), name="film"),
    name="film",
)
film.Ms = 8.0e5
film.Aex = 1.3e-11
film.alpha = 0.02
film.m = fm.init.UniformMagnetization((1.0, 0.1, 0.0))
study.exchange()
study.stages.add_relax(
    stage_id="relax",
    algorithm="llg_overdamped",
    solver="rk45",
    dt_initial=1.0e-15,
    dt_min=1.0e-17,
    dt_max=1.0e-14,
    max_err=1.0e-7,
    relax_alpha=1.0,
    tolT=1.0e-6,
    max_steps=50_000,
)

AdaptiveTimestep itself has the complete fields atol, rtol, dt_initial, dt_min, dt_max, safety, growth_limit, shrink_limit, max_spin_rotation, and norm_tolerance. atol and rtol are dimensionless normalized-state error limits; dt_* are seconds; safety and growth or shrink limits are dimensionless; optional spin-rotation and norm limits are positive dimensionless guards. dt_max may not be below dt_min, and dt_initial must lie in the interval when set. FieldRefreshPolicy.demag_interval_s is a positive seconds cadence. These fields are not accepted by direct minimizer algorithms.

Parameters¶

The executable controls are the stage algorithm, integrator, fixed or adaptive timestep, damping override, stop criteria and work or time ceilings. The Python-to-ProblemIR table above is the authoritative parameter list.

ProblemIR¶

The stage request lowers to the existing relaxation payload. The numeric values below are representative of the example and show the destination, not a hand-written substitute for the serializer:

{
  "kind": "relaxation",
  "algorithm": "llg_overdamped",
  "dynamics": {
    "integrator": "rk45",
    "fixed_timestep": null,
    "adaptive_timestep": {
      "atol": 1e-7,
      "rtol": 0.0,
      "dt_initial": 1e-15,
      "dt_min": 1e-17,
      "dt_max": 1e-14,
      "tolerance_mode": "max_error"
    }
  },
  "stop": {
    "torque_tolerance_apm": 0.7957747154594767,
    "max_steps": 50000
  }
}

tolT is retained as requested intent and normalized to torque_tolerance_apm for execution. The canonical RelaxStop payload also carries energy_tolerance_j, max_steps, and, only for this algorithm, max_relaxation_time_s. The resolved execution record additionally identifies FEM/FDM, CPU/GPU, precision, selected integrator, adaptive policy, and actual device. The serialized request alone is not runtime proof.

Diagnostics and failure semantics¶

Record attempted and accepted steps, local-error ratios, rejection causes, field refreshes, accepted-state torque confirmation, completion reason and executed backend/device. A failed solve, non-finite state or exhausted adaptive floor cannot be published as converged.

Round-trip and failure semantics¶

The script exporter emits the stage-first study.stages.add_relax(...) call and preserves the algorithm, integrator, stopping policy, and requested backend. Validation errors include unknown integrators, non-positive timestep bounds, mixed fixed/adaptive controls, missing adaptive bounds, both tolT and tolA, legacy tol, and LLG-only controls used with a direct minimizer. Unsupported combinations are rejected by the planner; there is no silent fallback to rk23, CPU, or a different algorithm after an explicit request. Requested intent, resolved execution, and provenance are three different records.

Discrete realization¶

FDM uses grid-local field evaluation. FEM uses the assembled finite-element field and the native MFEM/CUDA operator path. The equation and stop metric are shared; interpolation, mass weighting, field-solve refresh, precision, and runtime ownership are not.

The FDM CPU/reference lane evaluates the effective field on the Cartesian grid and advances the same damping-only RHS through its grid integrator. The FDM CUDA lane keeps the state and field updates in CUDA-owned buffers when the selected plan permits it. FEM CPU assembles/evaluates the MFEM field on the magnetic-node space; FEM GPU uses the native device operator and records device residency. None of these descriptions is a claim that all four lanes have identical tolerances, reductions, or runtime qualification.

Implementation mapping¶

The Python stage builder calls relax_stage; the public Relaxation and RelaxStop objects validate and serialize the shared contract. Backend runners resolve pure damping through the relaxation convergence module and use their own time-step and field-evaluation realizations.

Validation¶

Required evidence is split into four gates: equation/sign and unit tests; stage-to-IR round-trip; algorithmic convergence and energy/torque metrics; and executed backend/device qualification. A passing Python capture proves authoring and lowering only. It does not prove an FEM solve, GPU execution, or parity.

Limitations¶

This page does not claim a physical switching time, unconditional stability, universal GPU parity, or convergence to a global minimum. The result may be a metastable equilibrium. Direct minimizers and their line-search contracts are described separately.

Scientific bibliography¶

• W. F. Brown, Jr., Micromagnetics, Wiley, 1963.

• T. L. Gilbert, “A phenomenological theory of damping in ferromagnetic materials,” IEEE Transactions on Magnetics 40 (2004), DOI: 10.1109/TMAG.2004.836740.

• Fullmag canonical contracts: 0500-fdm-relaxation-algorithms.md, 0510-fem-relaxation-algorithms-mfem-gpu.md, 0580-canonical-relaxation-equilibrium-contract.md.

Control Room workflow¶

Use the stage editor to select overdamped LLG and expose only integrator, timestep, adaptive, stop and field-refresh controls present in the current stage draft. Inspect resolved execution and completion telemetry before treating the stage as converged.

Control Room crosswalk¶

Use Model Explorer -> Stages -> Add stage -> <stage kind> for stage-level controls when the terminal page identifies a matching field. The current editor is partial: only fields surfaced by the stage draft are authorable. 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.

Where this is implemented¶

The source-code index below records public validation, stage lowering, adaptive controllers, backend execution and completion semantics. Each sidecar entry names a stable declaration rather than a line range.

Source-code index¶