Time Integrator Selection (LLG.integrator)¶
Last changes: Documentation changelog
1. Physical problem and overview¶
LLG.integrator (and study.solver(integrator=...)) selects the numerical time-integration scheme used to advance the semi-discrete Landau–Lifshitz–Gilbert (LLG) equation across time-evolution and overdamped relaxation stages. Fullmag distinguishes fixed-step schemes (heun, rk4, abm3, coupled_imex_ark2), embedded adaptive Runge–Kutta pairs (rk23, rk45), and the planner-resolved "auto" mode.
2. Governing equations¶
For an \(S\)-stage explicit Runge–Kutta scheme with Butcher tableau \((a_{j\ell}, b_j, \widetilde{b}_j, c_j)\), advancing active spin state \(y_n = \{\mathbf{m}_i(t_n)\}_{i \in \mathcal{A}}\) by \(\Delta t\) evaluates
where \(\mathcal{N}(\cdot)\) normalizes each active 3-vector onto \(\mathbb{S}^2\). For the 3-step Adams–Bashforth–Moulton predictor–corrector (abm3 on FDM CPU), after a three-step rk4 bootstrap at fixed step \(\Delta t\), the predictor–corrector update is
3. Symbols and SI units¶
Symbol |
Meaning |
SI unit |
|---|---|---|
\(y_n\) |
Accepted normalized magnetization state at step \(n\) |
\(1\) |
\(Y_j\) |
Normalized stage state at Runge–Kutta stage \(j\) |
\(1\) |
\(K_j\) |
Stage LLG right-hand side derivative |
\(\mathrm{s^{-1}}\) |
\(F_n\) |
Stored step LLG right-hand side derivative at \(t_n\) |
\(\mathrm{s^{-1}}\) |
\(\Delta t\) |
Time step size |
\(\mathrm{s}\) |
\(a_{j\ell}\) |
Runge–Kutta stage coupling coefficient |
\(1\) |
\(b_j\) |
High-order Runge–Kutta output weight |
\(1\) |
\(c_j\) |
Runge–Kutta stage abscissa |
\(1\) |
\(t_n\) |
Accepted step start time |
\(\mathrm{s}\) |
4. Assumptions and limits of validity¶
Alias normalization:
"euler"normalizes to"heun"(two-stage second-order predictor–corrector) and"dopri5"normalizes to"rk45"(Dormand–Prince 5(4)).Fixed vs. adaptive exclusivity: Fixed-step integrators (
heun,rk4,abm3,coupled_imex_ark2) requirefixed_timestepand rejectadaptive_timestep; adaptive pairs (rk23,rk45) rejectfixed_timestep.Provenance preservation:
"auto"is preserved verbatim inProblemIR(requested intent) and resolved by the planner to"rk45"(or the appropriate lane default) in the execution plan and receipt (resolved execution).
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 |
|
|---|---|---|---|---|---|---|---|
|
|
|
\(1\) |
One of |
Time integration scheme |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
|
|
|
\(\mathrm{m\,A^{-1}\,s^{-1}}\) |
Positive |
Gyromagnetic ratio |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
|
|
|
\(\mathrm{s}\) |
Positive; exclusive with adaptive step |
Fixed step size |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
|
|
|
\(1\) |
Adaptive integrator required |
Embedded error control |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
Executable Python example¶
# %%
import fullmag as fm
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,
)
# Compare Dormand-Prince RK45 and fixed-step ABM3 configurations
study = fm.study(world, target="fdm", device="cpu", precision="fp64")
study.solver(
integrator="rk45",
adaptive_timestep=fm.AdaptiveTimestep(atol=1e-6, rtol=1e-4, dt_min=1e-15, dt_max=2e-12),
)
study.stages.add_time(name="rk45_run", duration=0.1e-9, By=5e-3, save_m_every=50e-12)
study_abm3 = fm.study(world, target="fdm", device="cpu", precision="fp64")
study_abm3.solver(integrator="abm3", fixed_timestep=5e-14)
study_abm3.stages.add_time(name="abm3_run", duration=0.1e-9, By=5e-3, save_m_every=50e-12)
assert study.to_problem_ir()["study"]["dynamics"]["integrator"] == "rk45"
assert study_abm3.to_problem_ir()["study"]["dynamics"]["integrator"] == "abm3"
6. ProblemIR and canonical script representation¶
{
"dynamics": {
"equation": "llg",
"gyromagnetic_ratio": 221100.0,
"integrator": "abm3",
"fixed_timestep": 5e-14,
"adaptive_timestep": null,
"field_refresh": null
}
}
7. Round-trip, provenance, and failure semantics¶
Requested intent vs. resolved execution:
ProblemIRstores the canonicalizedintegratorstring (requested intent), while the execution plan and receipt record the concrete backend stepper (resolved execution).Validation errors: Unknown integrator strings or mismatched
fixed_timestep/adaptive_timesteppairings raiseValueErrorvalidation errors in Python.Unsupported combinations: Requesting
abm3orcoupled_imex_ark2ontarget="fem"is rejected as an unsupported combination by the planner.
8. Discrete realization and numerical operators¶
FEM CPU:
context_step_explicit_rk_mfem(heun,rk4,rk23,rk45).FEM GPU:
gpu_rk_device_resident_step(heun,rk4,rk23,rk45).FDM CPU:
heun,rk4,rk23,rk45,abm3(abm3_step_soa_state_buf), andcoupled_imex_ark2.FDM GPU: CUDA
heun,rk4,rk23,rk45, andcoupled_imex_ark2.
9. Backend and device implementation mapping¶
Solver |
Device |
Status |
Supported integrators |
|---|---|---|---|
FEM |
CPU |
|
|
FEM |
GPU |
|
|
FDM |
CPU |
|
|
FDM |
GPU |
|
|
10. Validation and benchmark gates¶
Validated in
packages/fullmag-py/tests/test_llg_solver_contract.pyandbackends/fem/tests/rk_explicit_contract.cpp.
11. Known limitations and operational constraints¶
abm3requires uniform \(\Delta t\) across steps; changing external stage fields discontinuously across stage boundaries resets the multistep history unless resumed from a matchingFdmCpuSolverCheckpointV1.
12. Scientific bibliography¶
J. R. Dormand and P. J. Prince, A family of embedded Runge–Kutta formulae, J. Comput. Appl. Math. 6, 19–26 (1980).
P. Bogacki and L. F. Shampine, A 3(2) pair of Runge–Kutta formulas, Appl. Math. Lett. 2, 321–325 (1989).
13. Source-code index¶
Layer |
File |
Symbol / entrypoint |
Responsibility |
|---|---|---|---|
Python DSL |
Integrator selection, validation, and dynamics IR lowering |
||
Native FEM CPU |
Native FEM CPU explicit RK step driver |
||
Native FEM GPU |
Native FEM GPU device-resident RK step driver |
||
FDM CPU Engine |
FDM CPU |