Tangent-Plane Projection and Linearly Implicit Relaxation¶
Last changes: Documentation changelog
Scope and purpose¶
This chapter documents the tangent-plane projection formalism and the native FEM linearly implicit tangent-plane relaxation method (tangent_plane_implicit in backends/fem/cpu/mfem/relaxation/tangent_plane_implicit.cpp). Because the reduced magnetization \(\mu_i \in \mathbb{S}^2\) evolves on the unit sphere, any physically admissible velocity or quasi-Newton step \(\delta\mu_i\) must lie in the local tangent space \(T_{\mu_i}\mathbb{S}^2\). tangent_plane_implicit solves a global tangent-space mass-plus-exchange linear system at each step, retracts the trial increment back onto \(\mathbb{S}^2\), and enforces a strict Armijo energy-decrease gate with roundoff bounds.
Scientific and numerical model¶
At each active magnetic node \(i \in \mathcal{A}\) with unit magnetization \(\mu_i \in \mathbb{S}^2\) (\(\|\mu_i\|_2 = 1\)), the orthogonal projector onto the local tangent plane \(T_{\mu_i}\mathbb{S}^2 = \{v \in \mathbb{R}^3 : \mu_i \cdot v = 0\}\) is
Projecting the local effective magnetic field \(H_{\mathrm{eff},i}\) onto \(T_{\mu_i}\mathbb{S}^2\) isolates the steepest-descent component of the negative energy gradient on the sphere:
In run_tangent_plane_implicit_step (backends/fem/cpu/mfem/relaxation/tangent_plane_implicit.cpp), each active node \(i\) is equipped with an orthonormal tangent frame \((\mathbf{e}_{1,i}, \mathbf{e}_{2,i})\) spanning \(T_{\mu_i}\mathbb{S}^2\). Writing the trial tangent increment as \(\delta\mu_i = w_{1,i}\mathbf{e}_{1,i} + w_{2,i}\mathbf{e}_{2,i}\) treats the stiff exchange operator implicitly in the \(2N_{\mathcal{A}}\)-dimensional tangent space while evaluating non-exchange interactions explicitly from the current \(H_{\mathrm{eff}}\) snapshot:
The retracted trial state \(\mu^{\mathrm{trial}}(\tau)\) is accepted only when the certified upper bound on the energy change \(\Delta E + \varepsilon_{\mathrm{roundoff}}\) satisfies the Armijo descent condition; otherwise \(\tau\) is halved and the pre-trial state is restored via restore_after_rejected_trial.
Symbols and SI units¶
Symbol |
Meaning |
SI unit |
|---|---|---|
\(\mu_i\) |
normalized magnetization at point i |
\(1\) |
\(P_i\) |
tangent-space projector |
\(1\) |
\(I\) |
three-dimensional identity tensor |
\(1\) |
\(H_{\mathrm{eff},i}\) |
effective magnetic field |
\(\mathrm{A\,m^{-1}}\) |
\(H_i^{\perp}\) |
projected effective field |
\(\mathrm{A\,m^{-1}}\) |
\(M_{\perp}\) |
tangent-space lumped/consistent mass operator |
\(\mathrm{J}\) |
\(K_{\mathrm{ex},\perp}\) |
tangent-space projected exchange stiffness operator |
\(\mathrm{J\,s^{-1}}\) |
\(w\) |
two-component tangent-frame increment coordinates |
\(1\) |
\(r_{\perp}\) |
tangent-projected energy-gradient residual |
\(\mathrm{J}\) |
\(\tau\) |
implicit tangent-plane trial step size |
\(1\) |
Assumptions, Armijo certification, and lane scope¶
Orthonormal tangent basis: At each step,
TangentFrameconstructs \((\mathbf{e}_{1,i}, \mathbf{e}_{2,i})\) orthogonal to \(\mu_i\) so that \(\mu_i \cdot \delta\mu_i = 0\) holds to machine precision before retraction.Armijo energy gate with roundoff certification:
run_tangent_plane_implicit_steprequires \(\Delta E + \varepsilon_{\mathrm{roundoff}} \le \Delta E_{\mathrm{Armijo}} \le 0\) and validates the accepted tangent gradient before advancing.Development-lane scope:
tangent_plane_implicitis an extended-mode FEM CPU/MFEM algorithm (target="fem",execution_mode="extended"). It is rejected on FDM, forced GPU lanes, andexecution_mode="strict".
Discrete realization and backend support matrix¶
Solver |
Device |
Status |
Realization notes |
|---|---|---|---|
FEM |
CPU |
|
Native MFEM tangent-space assembly, CG linear solve, unit-sphere retraction, and Armijo line search in |
FEM |
GPU |
|
|
FDM |
CPU |
|
The public contract marks |
FDM |
GPU |
|
The public contract marks |
Parameters¶
Python surface |
Type |
Default |
SI unit |
Validation / constraints |
Meaning |
Backend support |
|
|---|---|---|---|---|---|---|---|
|
|
|
\(1\) |
supported identifier; unknown names rejected |
relaxation algorithm request |
FEM CPU extended lane for |
|
|
|
|
\(\mathrm{A\,m^{-1}}\) |
positive when set |
torque stopping threshold |
FEM/FDM relaxation stop contract |
|
|
|
|
\(1\) |
positive integer when set |
iteration limit |
FEM/FDM relaxation stop contract |
|
Python API¶
# %%
import fullmag as fm
world = fm.World(
dx=5e-9,
dy=5e-9,
dz=5e-9,
nx=10,
ny=4,
nz=1,
boundaries=fm.BoundaryConfig.open(method="poisson_robin"),
)
world.add_box(
"nanodot",
size=(50e-9, 20e-9, 5e-9),
material=fm.Material.permalloy(Ms=8.0e5, Aex=1.3e-11, alpha=0.02),
m_init=fm.VectorFieldSpec.uniform((1.0, 0.2, 0.1)),
demag=True,
)
study = fm.study(
world,
target="fem",
device="cpu",
precision="fp64",
execution_mode="extended",
)
study.stages.add_relax(
name="tpi_relax",
algorithm="tangent_plane_implicit",
tolT=1e-6,
max_steps=2000,
)
ir = study.to_problem_ir()
assert ir["study"]["stages"][0]["algorithm"] == "tangent_plane_implicit"
ProblemIR excerpt¶
{
"study": {
"kind": "stage_workflow",
"stages": [
{
"kind": "relax",
"name": "tpi_relax",
"algorithm": "tangent_plane_implicit",
"stop": {
"torque_tolerance_apm": 0.7957747154594768,
"energy_tolerance_j": null,
"max_steps": 2000,
"max_time_s": null
}
}
]
}
}
Control Room workflow¶
Relaxation Stage Inspector: Exposes
algorithm="tangent_plane_implicit"whentarget="fem"andexecution_mode="extended"are selected, along with stopping thresholds (torque_tolerance_apm,energy_tolerance_j,max_steps).Execution Provenance: Records
requested_energy_minimizer="tangent_plane_implicit"andresolved_energy_minimizer="tangent_plane_implicit"in the relaxation stage receipt.
Diagnostics and failure semantics¶
Requested intent and resolved execution:
ProblemIRrecordsalgorithm="tangent_plane_implicit"(requested intent), and the FEM runner records the CPU/MFEM development lane in the execution receipt (resolved execution).Validation errors: Unknown algorithm names or non-positive stopping tolerances raise immediate
ValueErrorvalidation errors in Python and planner diagnostics in Rust.Unsupported combinations: Requesting
tangent_plane_implicitontarget="fdm",execution_mode="strict", ordevice="gpu"is rejected as an unsupported combination with an explicit diagnostic (crates/fullmag-plan/src/validate.rs).
Scientific bibliography¶
S. Bartels and A. Prohl, Convergence of an implicit finite element method for the Landau–Lifshitz–Gilbert equation, SIAM J. Numer. Anal. 44, 1405–1419 (2006).
F. Alouges, A new finite element scheme for Landau–Lifshitz equations, Discrete Contin. Dyn. Syst. Ser. S 1, 187–196 (2008).
Where this is implemented¶
Layer |
File |
Symbol |
Responsibility |
|---|---|---|---|
Python DSL |
Public relaxation algorithm validation and IR lowering |
||
Python DSL |
Ordered stage capture and validation |
||
Native FEM CPU |
Native FEM CPU/MFEM tangent-plane implicit linear solve, retraction, and Armijo gate |