Relaxation stopping criteria and completion¶

Scope and purpose¶

This page defines the shared accepted-state completion contract for relaxation and separates torque, optional energy, work budgets, failure states and output cadence.

Scientific and numerical model¶

Completion is evaluated after an accepted state and field refresh. Torque is mandatory; an energy plateau is an additional conjunction rather than a replacement criterion.

Completion problem¶

Relaxation completion is a contract over the accepted state, not a label attached after an iteration budget expires. The canonical policy combines a torque residual with optional energy and time/step budgets. A budget limits work; it does not by itself prove equilibrium.

Governing equations¶

The primary residual is the maximum effective-field torque:

If an energy criterion is configured, the accepted energy sequence is checked over the implementation window \(W_E\):

In the shared runner, \(W_E\) is exactly 50 accepted energy samples. The combined torque predicate (and, when configured, the energy-window predicate) is then observed on fresh accepted states. torque_confirmed becomes true after at least three consecutive accepted samples satisfy that combined predicate; the counter is not capped at three. A failed sample resets the consecutive counter to zero. This confirmation is independent of output cadence: sparse saved output cannot change the authoritative completion record.

The logical completion rule is conjunction, not disjunction:

max_steps and max_relaxation_time_s are ceilings. If a ceiling is reached before the residual rule is true, the result is budget-exhausted or non-converged, never converged by budget alone.

Symbols and SI units¶

max_pseudotime_s and max_physical_time_s are Python aliases for the same canonical \(T_{\mathrm{relax}}\) field. They are accepted only when they agree with max_relaxation_time_s, and only llg_overdamped may use the field. Direct minimizers report time=0, dt=0, and no pseudo-time.

Assumptions and validity¶

• The torque is evaluated after the accepted state has been committed and after the effective field has been refreshed according to the selected field-refresh policy.

• The field residual is in A/m internally. A tolT request is converted through \(\mu_0\) and the requested unit is retained in provenance.

• energy_tolerance is an optional secondary condition. Setting it does not remove the torque requirement.

• max_steps is an integer work budget. max_relaxation_time_s is meaningful only for llg_overdamped; direct minimizers have no time coordinate.

• A failed field solve, invalid state, failed line search, or non-finite metric is a failure and cannot satisfy the stop contract.

Python API¶

# %% Configure explicit accepted-state completion criteria
import fullmag as fm

nm = 1.0e-9
study = fm.study("relaxation_stop_contract")
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="nonlinear_cg",
    stop=fm.RelaxStop(
        torque_tolerance_apm=0.7957747154594767,
        energy_tolerance_j=1.0e-18,
        max_steps=50_000,
    ),
)

The stop= object is the canonical grouped form. Scalar aliases are accepted on study.stages.add_relax, but mixing a scalar with a conflicting field in RelaxStop is rejected. The legacy tol parameter is removed and must not be documented as usable.

RelaxStop accepts at least one criterion. Its default object contains both the canonical torque threshold and the default accepted-step budget, so an otherwise empty add_relax call is still bounded. max_pseudotime_s and max_physical_time_s are constructor aliases only; serialization always emits the single canonical max_relaxation_time_s key. Supplying two aliases with different values is a validation error rather than a precedence rule.

Parameters¶

The executable controls are the grouped RelaxStop fields and scalar stage aliases listed in the Python table. The canonical payload stores torque, optional energy, step and LLG-only time criteria; budgets never imply convergence.

ProblemIR¶

The grouped stop object lowers to a canonical payload:

{
  "stop": {
    "torque_tolerance_apm": 0.7957747154594767,
    "energy_tolerance_j": 1e-18,
    "max_steps": 50000
  }
}

Normalization converts tolT to A/m before runtime comparison. Requested unit and authored field remain provenance metadata; resolved execution stores the canonical A/m threshold and the actual completion reason.

Diagnostics and failure semantics¶

Record accepted-state torque, energy-window samples, confirmation count, field-refresh policy, budget counters, stop reason and failure or cancellation status. Non-finite metrics, invalid state, failed field solves and failed line searches cannot satisfy completion.

Round-trip and failure semantics¶

Script export preserves the grouped RelaxStop values or the equivalent scalar stage arguments. Validation errors cover non-positive tolerances, non-positive step/time ceilings, conflicting stop aliases, a stop with no criterion, energy-only completion assumptions, and time limits on direct minimizers. Unsupported combinations are rejected instead of weakening the completion rule. The result must identify requested intent, converged, stop_reason, stop_metric, stop_value, and stop_threshold; a budget-exhausted result is not a converged result.

The authoritative completion reasons include torque (at-least-three-sample torque confirmation, plus any configured energy plateau), max_steps, max_physical_time, gradient for numerical stagnation, backend_error, user_cancelled, and an unset reason while a stage remains incomplete. The energy metric alone never produces convergence because torque is mandatory in the canonical stop contract.

Discrete realization¶

The shared stop semantics do not imply identical floating-point reductions. Each lane must record precision, mesh/grid identity, field refresh, and runtime provenance with its metrics.

For direct minimizers, max_steps counts accepted minimizer steps; rejected Armijo trials do not advance it. For LLG, max_steps counts accepted integration steps and the relaxation-time ceiling is checked against the stage relaxation coordinate. A failure or cancellation is mapped before any budget predicate, so it cannot be reclassified as converged.

The FDM reference direct-minimizer loops contain an early torque-only exit before the first accepted step. When an energy tolerance is also requested, that internal converged flag does not constitute canonical completion because no 50-sample energy window exists yet; the shared resolve_stage_completion record remains authoritative and leaves the stage non-converged until the conjunction is actually evaluable. This distinction is intentional provenance: backend-local loop flags are not interchangeable with the public completion result.

Implementation mapping¶

RelaxStop owns public validation and serialization. The runner convergence module owns accepted state completion, torque confirmation, energy-window policy, budget handling, and pure-damping mode selection. Backend-specific reducers provide the metrics consumed by that shared policy.

Validation¶

Tests must prove: torque conversion from T to A/m; conjunction of torque and energy criteria; rejection of budget-only completion; exact zero torque behavior; confirmation on accepted states; failure on non-finite metrics; and round-trip preservation of requested/resolved stop policy. Runtime qualification adds backend/device identity and artifact evidence.

Limitations¶

The stop contract does not prove a global energy minimum, physical-time equilibrium uniqueness, or cross-mesh trajectory equality. The energy window is a numerical completion criterion, not a proof that the continuous functional has reached its global minimum.

Scientific bibliography¶

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

• J. Nocedal and S. J. Wright, Numerical Optimization, 2nd ed., Springer, 2006, DOI: 10.1007/978-0-387-40065-5.

• Fullmag canonical equilibrium contract: 0580-canonical-relaxation-equilibrium-contract.md.

Control Room workflow¶

Use the stage editor to configure torque, optional energy and work-budget fields, then inspect the resolved completion reason and metrics. A direct minimizer must not receive an LLG physical-time limit.

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 the public stop object, flat-stage normalization and shared accepted-state completion declarations used by this contract.

Source-code index¶