Tangent-plane methods¶

Scope and purpose¶

This page documents the tangent-plane relaxation contract and its boundary with physical-time integration. The current public API exposes tangent_plane_implicit as a relaxation algorithm; it does not expose a general tangent-plane LLG.integrator.

Scientific and numerical model¶

At a normalized magnetization \(μ_i\), admissible first-order variations satisfy \(\mu_i\cdot\delta\mu_i=0\). A tangent-plane relaxation method solves for an increment in this subspace and then updates the state while enforcing the sphere constraint.

Governing equations¶

The tangent projector at point \(i\) is

The projected effective field is

The current public contract describes the implicit tangent-plane method as a relaxation algorithm; its complete nonlinear linearization and production solver details are therefore reported as a separate backend qualification item rather than invented here.

Symbols and SI units¶

Assumptions and validity¶

• The input state is non-zero and is interpreted as a unit magnetization after normalization by the surrounding relaxation contract.

• This page does not claim a physical-time tangent-plane integrator.

• FEM-only availability is a public algorithm contract; FDM lanes must reject the request unless a future capability declaration explicitly enables it.

Python API¶

# %% Configure a tangent-plane relaxation request
import fullmag as fm

nm = 1.0e-9
study = fm.study("tangent_plane_relaxation")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")
film = study.geometry(fm.Box(40 * nm, 20 * nm, 5 * nm), name="film")
film.Ms = 800.0e3
film.Aex = 13.0e-12
film.alpha = 0.02
film.m = fm.init.UniformMagnetization((1.0, 0.0, 0.0))
study.exchange()
study.solver(integrator="rk45", fix_dt=1.0e-15, gamma=2.211e5)
study.stages.add_relax(
    algorithm="tangent_plane_implicit",
    tolT=1.0e-6,
    max_steps=50_000,
)

Parameters¶

The following rows are the public relaxation and stopping parameters used by the example. The FDM rows remain explicitly unsupported for this algorithm, as recorded in the source map.

ProblemIR¶

The requested algorithm lowers to:

{"kind": "relaxation", "algorithm": "tangent_plane_implicit", "stop": {"torque_tolerance_apm": 0.7957747154594767, "max_steps": 50000}}

The planner resolves whether the selected FEM lane can execute it. The JSON request is not proof that a native tangent-plane solve was run.

Diagnostics and failure semantics¶

Round-trip preserves requested intent, the algorithm request, and stop policy. Validation errors cover unknown algorithm names, non-positive stop values, and incompatible time-limit parameters. Unsupported combinations combinations are explicit: the FDM planner must reject tangent_plane_implicit rather than silently selecting llg_overdamped. Requested intent and resolved execution remain separate in provenance.

Discrete realization¶

Where this is implemented¶

The public algorithm set and validation live in Relaxation; the stage builder lowers the request through relax_stage. Backend implementation status is resolved by planner capabilities, not by the Python string alone.

Validation¶

Validation must separate projector algebra, relaxation convergence, and runtime lane qualification. A source-level algorithm identifier is not numerical evidence. The minimum report contains torque norm, energy change, iteration count, final norm defect, selected FEM lane, precision, and whether the GPU device actually executed.

Limitations¶

The public documentation does not claim that this method is a general dynamic integrator, an FDM method, or a universally qualified FEM GPU method. The full linear-system policy and preconditioner controls must be added only when their public and native contracts are present.

Scientific bibliography¶

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

• J. E. Marsden, T. J. R. Hughes, Mathematical Foundations of Elasticity, Dover, 1994, for constrained variational discretization principles.

Control Room workflow¶

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.

Source-code index¶