Relaxation¶

Contract¶

This page records the public Python authoring contract and canonical lowering for the energy-minimization study type; physical algorithms and numerical realizations belong to the relaxation numerical pages.

Governing equations¶

Relaxation drives the magnetization toward \(\mathbf m\times\mathbf H_{\mathrm{eff}}\approx 0\) under the constraint \(|\mathbf m|=1\); the underlying equation is LLG with precession disabled for the overdamped lane and the sphere-product descent condition for direct minimizers. Equations are owned by Relaxation.

Symbols and SI units¶

Every owned input has its SI unit below; \(1\) denotes dimensionless data. Torque tolerance is accepted and reported in tesla, with the derived A/m value recorded in the stop contract.

Assumptions and validity¶

Constructor checks run immediately. Lowering and planning additionally check algorithm support, mesh cardinality, capability, stop-contract consistency, and backend legality.

Python API¶

# %% Zero-field projected-gradient relaxation
import fullmag as fm

nm = 1.0e-9

# %% Study and execution lane
study = fm.study("relaxation_api_example")
study.engine("fdm")
study.device("cpu", precision="double")
study.mode("strict")

# %% Geometry, material, initial state, and interactions
study.objects.mesh.defaults(cell_size=(2 * nm, 2 * nm, 5 * nm))
film = study.geometry(fm.Box(100 * nm, 20 * nm, 5 * nm), name="film")
film.Ms = 800.0e3
film.Aex = 13.0e-12
film.alpha = 1.0
film.m = fm.init.UniformMagnetization((1.0, 0.1, 0.0))
study.exchange()

# %% Relaxation stage with table autosave
study.stages.add_relax(
    stage_id="relax",
    algorithm="projected_gradient_bb",
    max_steps=2000,
    tolT=5.8349e-9,
).autosave(
    fm.StageAutosave(
        table=fm.TableAutosave(
            every_steps=10,
            quantities=["step", "mx", "my", "mz", "e_ex", "e_total", "max_torque_T"],
        ),
        fields=[],
    )
)

ProblemIR¶

Relaxation.to_ir() emits {"kind": "relaxation", ...} with algorithm, stop, sampling, and, for the overdamped lane, dynamics. The final column above gives each serialized destination.

Round-trip and failure semantics¶

Requested intent is the value authored by Python and preserved in ProblemIR; resolved execution is the planner or realization result. Validation errors identify the violated domain rule, and unsupported combinations are rejected explicitly rather than silently substituted.

Requested intent (algorithm choice, authored tolerances, time bound) is preserved in Python and IR. Resolved execution (backend, device, precision, solver) is selected by the planner. Validation errors reject unsupported algorithms, non-positive tolerances/step counts, conflicting legacy and RelaxStop values, and dynamics supplied to a direct minimizer. Unsupported combinations fail capability checks without silent fallback.

Discrete realization¶

This page owns authoring and lowering only. Numerical realization is documented in Relaxation.

Implementation mapping¶

The adjacent map anchors claims to packages/fullmag-py/src/fullmag/model/study.py (class Relaxation, RelaxStop, RelaxStep) and the stage surface in packages/fullmag-py/src/fullmag/world.py (StudyStagesBuilder.add_relax).

Validation¶

Ownership tests compare this inventory with live signatures and validate the adjacent source map. The canonical scenario tests/standard_problems/mumag/sp4/fem/scenarios/relax_projected_gradient_bb.py is the executed style reference.

Limitations¶

Representability does not prove every backend combination executable. tangent_plane_implicit is a reserved FEM-only identifier and is not yet executable; planner capabilities are authoritative.

Scientific bibliography¶

Algorithm references are owned by the relaxation numerical pages; no independent physical model is introduced here.

Control Room crosswalk¶

Status: Stage authoring and inspection are partial; the stage editor exposes only its advertised fields.

not implemented: frontend support for study parameters not rendered by the stage editor. See Control Room capability register for the support matrix and not implemented policy. Frontend source owner: apps/control-room/src/modules/inspector/panels/StudyStageDraftEditor.tsx (StudyStageDraftEditor).

Source-code index¶