LLG Dynamics Contract¶
Last changes: Documentation changelog
1. Physical problem and overview¶
fm.LLG is the public Python DSL contract that parameterizes the Landau–Lifshitz–Gilbert (LLG) equation of motion for time-domain evolution and overdamped LLG relaxation (algorithm="llg_overdamped"). It binds the H-field gyromagnetic ratio \(\gamma_0\), the requested time-integration scheme (integrator), the mutually exclusive fixed (fixed_timestep) or embedded adaptive (adaptive_timestep) step-size controller, and the optional demagnetization refresh cadence (field_refresh).
2. Governing equations¶
On active magnetic degrees of freedom \(i \in \mathcal{A}\) (\(M_{s,i} > 0\)), LLG specifies the explicit normalized Landau–Lifshitz–Gilbert right-hand side:
3. Symbols and SI units¶
Symbol |
Meaning |
SI unit |
|---|---|---|
\(\mathbf{m}_i\) |
Reduced magnetization unit vector at active node/cell \(i\) |
\(1\) |
\(\mathbf{H}_{\mathrm{eff},i}\) |
Total effective magnetic field at node/cell \(i\) |
\(\mathrm{A\,m^{-1}}\) |
\(\gamma_0\) |
Reduced gyromagnetic ratio ( |
\(\mathrm{m\,A^{-1}\,s^{-1}}\) |
\(\alpha_i\) |
Dimensionless Gilbert damping parameter ( |
\(1\) |
\(s_{\mathrm{prec}}\) |
Precession switch (\(1\) in time evolution, \(0\) in pure-damping relaxation) |
\(1\) |
\(\boldsymbol{\tau}_{\mathrm{direct},i}\) |
Optional direct current-driven spin torque rate |
\(\mathrm{s^{-1}}\) |
\(t\) |
Physical simulation time |
\(\mathrm{s}\) |
4. Assumptions and limits of validity¶
H-field gyromagnetic convention:
LLG.gammais expressed in \(\mathrm{m\,A^{-1}\,s^{-1}}\) (default \(2.211\times 10^5\,\mathrm{m\,A^{-1}\,s^{-1}} \approx \mu_0 |\gamma_e|\)) so that \(\gamma_0 \mathbf{H}_{\mathrm{eff}}\) has units of \(\mathrm{s^{-1}}\).Stepping exclusivity: Fixed-step integrators (
heun,rk4,abm3,coupled_imex_ark2) requirefixed_timestepand rejectadaptive_timestep, whereas embedded adaptive pairs (rk23,rk45) rejectfixed_timestep.Alias normalization: Passing
"euler"normalizes to"heun", and passing"dopri5"normalizes to"rk45".
5. Python API and parameter contract¶
Constructor signature¶
fm.LLG(
*,
gamma: float = 2.211e5,
integrator: str = "auto",
fixed_timestep: float | None = None,
adaptive_timestep: AdaptiveTimestep | None = None,
field_refresh: FieldRefreshPolicy | None = None,
)
Parameter reference¶
Python parameter |
Type |
Default |
SI unit |
Validation |
Meaning |
Backend support |
|
|---|---|---|---|---|---|---|---|
|
|
|
\(\mathrm{m\,A^{-1}\,s^{-1}}\) |
Positive finite gyromagnetic ratio used by the H-field LLG convention. |
Positive finite gyromagnetic ratio used by the H-field LLG convention. |
FEM/FDM CPU/GPU; planner checks combinations |
|
|
|
|
\(1\) |
Canonical supported integrator identifier or |
Canonical supported integrator identifier or |
FEM/FDM CPU/GPU; planner checks combinations |
|
|
|
|
\(\mathrm{s}\) |
Positive fixed step when supplied; mutually constrained with adaptive stepping. |
Positive fixed step when supplied; mutually constrained with adaptive stepping. |
FEM/FDM CPU/GPU; planner checks combinations |
|
|
|
|
\(1\) |
Optional adaptive-step contract. |
Optional adaptive-step contract. |
FEM/FDM CPU/GPU; planner checks combinations |
|
|
|
|
\(1\) |
Optional field-refresh policy. |
Optional field-refresh policy. |
FEM/FDM CPU/GPU; planner checks combinations |
|
Executable Python example¶
# %%
import fullmag as fm
dynamics = fm.LLG(
gamma=2.211e5,
integrator="rk45",
adaptive_timestep=fm.AdaptiveTimestep(
atol=1e-6,
rtol=1e-4,
dt_initial=1e-13,
dt_min=1e-15,
dt_max=2e-12,
),
)
world = fm.World(
dx=5e-9,
dy=5e-9,
dz=5e-9,
nx=16,
ny=4,
nz=1,
boundaries=fm.BoundaryConfig.open(method="fft"),
)
world.add_box(
"strip",
size=(80e-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.05, 0.0)),
demag=True,
)
study = fm.study(world, target="fdm", device="cpu", precision="fp64")
study.solver(
integrator=dynamics.integrator,
gamma=dynamics.gamma,
adaptive_timestep=dynamics.adaptive_timestep,
)
study.stages.add_time(name="pulse", duration=0.2e-9, By=5e-3, save_m_every=50e-12)
ir = study.to_problem_ir()
assert ir["study"]["dynamics"]["equation"] == "llg"
assert ir["study"]["dynamics"]["integrator"] == "rk45"
6. ProblemIR and canonical script representation¶
{
"study": {
"kind": "stage_workflow",
"dynamics": {
"equation": "llg",
"gyromagnetic_ratio": 221100.0,
"integrator": "rk45",
"fixed_timestep": null,
"adaptive_timestep": {
"atol": 1e-06,
"rtol": 0.0001,
"dt_initial": 1e-13,
"dt_min": 1e-15,
"dt_max": 2e-12,
"safety": 0.9,
"growth_limit": 2.0,
"shrink_limit": 0.2,
"max_spin_rotation": null,
"norm_tolerance": null
},
"field_refresh": null
}
}
}
7. Round-trip, provenance, and failure semantics¶
Requested intent vs. resolved execution:
LLG.to_dict()preservesintegrator="auto"inProblemIR(requested intent) while the planner and execution receipt record the concrete resolved integrator and device lane (resolved execution).Validation errors: Non-positive or non-finite
gamma, unknownintegratornames, or supplying bothfixed_timestepandadaptive_timestepraise immediateValueErrorvalidation errors.Unsupported combinations: Attaching
fixed_timesteptork23/rk45, attachingadaptive_timesteptoheun/rk4/abm3/coupled_imex_ark2, or requesting FDM-only integrators (abm3,coupled_imex_ark2) ontarget="fem"is rejected as an unsupported combination.
8. Discrete realization and numerical operators¶
FEM CPU & GPU: Evaluates nodewise LLG torques (
llg_rhs_aoson CPU andfullmag_cuda_llg_rhs_fusedon GPU) and advances the state via explicit Runge–Kutta tableaus (heun,rk4,rk23,rk45).FDM CPU & GPU: Evaluates cell-centered SoA/AoS LLG torques across active magnetic cells and advances via explicit RK,
abm3multistep, orcoupled_imex_ark2.
9. Backend and device implementation mapping¶
Solver |
Device |
Status |
Notes |
|---|---|---|---|
FEM |
CPU |
|
Native MFEM |
FEM |
GPU |
|
CUDA |
FDM |
CPU |
|
Reference Cartesian SoA LLG and RK/ABM3/IMEX steppers. |
FDM |
GPU |
|
CUDA LLG and adaptive reduction kernels. |
10. Validation and benchmark gates¶
Validated in
packages/fullmag-py/tests/test_llg_solver_contract.pyandpackages/fullmag-py/tests/test_problem_ir.py.
11. Known limitations and operational constraints¶
Direct energy minimizers (
projected_gradient_bb,nonlinear_cg,tangent_plane_implicit) do not use anLLGdynamics payload; passingdynamicsto a direct-minimizerRelaxationstudy raises aValueError.
12. Scientific bibliography¶
T. L. Gilbert, A phenomenological theory of damping in ferromagnetic materials, IEEE Trans. Magn. 40, 3443 (2004).
13. Source-code index¶
Layer |
File |
Symbol / entrypoint |
Responsibility |
|---|---|---|---|
Python DSL |
Owns the documented public API, validation, and lowering |
||
Python DSL |
Stage-workflow |
||
Native FEM CPU |
Native FEM CPU nodewise LLG right-hand-side evaluation |
||
Native FEM GPU |
Native FEM CUDA fused LLG right-hand-side kernel |