Explicit Runge–Kutta Methods¶
Last changes: Documentation changelog
Scope and purpose¶
This chapter documents the explicit Runge–Kutta (heun, rk4, rk23, rk45) and fixed-step multistep (abm3, coupled_imex_ark2) time integrators used by Fullmag to advance the semi-discrete Landau–Lifshitz–Gilbert (LLG) equation. It covers the stage equations, embedded error estimators, First-Same-As-Last (FSAL) stage reuse policy, unit-sphere stage normalization, reusable workspace allocation, and cross-lane source mapping across FEM and FDM CPU/GPU realizations.
Scientific and numerical model¶
Let \(y(t) = \{\mathbf{m}_i(t)\}_{i \in \mathcal{A}}\) denote the assembled semi-discrete magnetization state on active magnetic degrees of freedom \(i \in \mathcal{A}\) (\(M_{s,i} > 0\)). The semi-discrete LLG right-hand side is
Given an accepted state \(y_n\) at time \(t_n\) and an attempted step size \(\Delta t > 0\), an \(S\)-stage explicit Runge–Kutta method with Butcher tableau \((a_{j\ell}, b_j, \widetilde{b}_j, c_j)\) evaluates intermediate stage states \(Y_j\) and stage derivatives \(K_j\) for \(j = 1, \dots, S\):
where \(\mathcal{N}(\cdot)\) normalizes each active 3-vector \(\mathbf{m}_i\) back onto the unit sphere \(\mathbb{S}^2\) (\(\|\mathbf{m}_i\|_2 = 1\)) while keeping non-magnetic entries zero. The high-order candidate state at \(t_n + \Delta t\) is formed and normalized as
For embedded adaptive pairs (rk23 Bogacki–Shampine 3(2) with \(S=4, p=2\) and rk45 Dormand–Prince 5(4) with \(S=7, p=4\)), the unnormalized local truncation error vector at each active point is the difference between the high-order (\(b_j\)) and embedded low-order (\(\widetilde{b}_j\)) stage combinations:
Symbols and SI units¶
Symbol |
Meaning |
SI unit |
|---|---|---|
\(\mathbf m\) |
reduced magnetization |
\(1\) |
\(y\) |
assembled semi-discrete magnetization state |
\(1\) |
\(F\) |
semi-discrete LLG right-hand side |
\(\mathrm{s^{-1}}\) |
\(\mathbf H_{\mathrm{eff}}\) |
effective magnetic field |
\(\mathrm{A\,m^{-1}}\) |
\(\gamma\) |
gyromagnetic ratio |
\(\mathrm{m\,A^{-1}\,s^{-1}}\) |
\(\alpha\) |
Gilbert damping parameter |
\(1\) |
\(t_n\) |
beginning of the accepted step |
\(\mathrm{s}\) |
\(\Delta t\) |
proposed time step |
\(\mathrm{s}\) |
\(Y_j\) |
state at RK stage j |
\(1\) |
\(K_j\) |
right-hand side at RK stage j |
\(\mathrm{s^{-1}}\) |
\(a_{j\ell}\) |
explicit RK stage coefficient |
\(1\) |
\(b_j\) |
accepted RK output coefficient |
\(1\) |
\(c_j\) |
RK stage time coefficient |
\(1\) |
\(\widetilde b_j\) |
embedded RK output coefficient |
\(1\) |
\(e_{n+1}\) |
embedded local error estimate |
\(1\) |
Assumptions, FSAL reuse, and multistep checkpointing¶
First-Same-As-Last (FSAL) reuse (
rk23,rk45): Both Bogacki–Shampine 3(2) and Dormand–Prince 5(4) satisfy \(a_{S,\ell} = b_\ell\), so stage \(S\) is evaluated at the candidate state prior to final endpoint normalization. On GPU (gpu_rk_rhs_allows_fsal_reuse), FSAL reuse is enabled only when operator signatures match and neither stochastic Brown thermal fields, stage callbacks, frozen-spin projections, nor unqualified periodic projections are active.Three-step Adams–Bashforth–Moulton (
abm3on FDM CPU): Bootstraps the first three steps withrk4, then advances via the 3-step predictor–corrector (abm3_step_soa_state_buf). Exact multistep history is serialized inFdmCpuSolverCheckpointV1and restored byresume_reference_fdm_from_abm3_checkpoint.Stability limits (
LLG-TD-STIFF-V1): Explicit Runge–Kutta schemes have bounded absolute stability regions along the imaginary and negative real axes; exchange stiffness scales as \(\mathcal{O}(A_{\mathrm{ex}} / (M_s h_{\min}^2))\).
Discrete realization and backend support matrix¶
Solver |
Device |
Status |
Realization notes |
|---|---|---|---|
FEM |
CPU |
|
Native MFEM explicit RK workspace ( |
FEM |
GPU |
|
Device-resident CUDA RK driver ( |
FDM |
CPU |
|
SoA explicit RK ( |
FDM |
GPU |
|
CUDA explicit RK stage kernels and fp64/fp32 reductions; parity and qualification depend on precision and active interactions. |
Parameters¶
Python surface |
Type |
Default |
SI unit |
Validation / constraints |
Meaning |
Backend support |
|
|---|---|---|---|---|---|---|---|
|
|
|
\(\mathrm{m\,A^{-1}\,s^{-1}}\) |
finite and \(> 0\) |
gyromagnetic ratio |
FEM/FDM CPU/GPU |
|
|
|
|
\(1\) |
|
temporal method request |
lane-dependent |
|
|
|
|
\(\mathrm{s}\) |
finite and \(> 0\); incompatible with |
requested fixed step |
FEM/FDM CPU/GPU subject to lane support |
|
|
|
|
\(1\) |
non-negative; not both tolerances zero |
absolute error tolerance |
RK23/RK45 lanes |
|
|
|
|
\(1\) |
non-negative; not both tolerances zero |
relative error tolerance |
RK23/RK45 lanes |
|
|
|
|
\(\mathrm{s}\) |
positive |
lower step bound |
RK23/RK45 lanes |
|
|
|
|
\(\mathrm{s}\) |
positive and \(\ge \Delta t_{\min}\) |
upper step bound |
RK23/RK45 lanes |
|
|
|
|
\(1\) |
validated integrator name; aliases normalize |
stage-workflow solver method request |
FEM/FDM lanes according to planner |
|
|
|
|
\(1\) |
mutually exclusive with fixed/convenience controls |
stage-workflow adaptive policy |
RK23/RK45 lanes |
|
Python API¶
# %%
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,
)
# Adaptive Dormand-Prince RK45 configuration
study = fm.study(world, target="fdm", device="cpu", precision="fp64")
study.solver(
integrator="rk45",
gamma=2.211e5,
adaptive_timestep=fm.AdaptiveTimestep(
atol=1e-6,
rtol=1e-4,
dt_initial=1e-13,
dt_min=1e-15,
dt_max=2e-12,
),
)
study.stages.add_time(name="ringdown", duration=0.2e-9, Bx=15e-3, save_m_every=50e-12)
# Fixed-step RK4 configuration
study_rk4 = fm.study(world, target="fdm", device="cpu", precision="fp64")
study_rk4.solver(integrator="rk4", gamma=2.211e5, fixed_timestep=1e-13)
study_rk4.stages.add_time(name="fixed_pulse", duration=0.1e-9, By=5e-3, save_m_every=25e-12)
ProblemIR excerpt¶
{
"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
}
}
}
Control Room workflow¶
Solver Inspector: Selects
integrator(auto,rk45,rk23,rk4,heun,abm3,coupled_imex_ark2) and switches between fixed-step (fixed_timestep) and adaptive (AdaptiveTimestep) controls.Stage Execution Diagnostics: Displays accepted steps, rejected step attempts, active \(\Delta t\), total stage RHS evaluations, and FSAL reuse counters.
Diagnostics and failure semantics¶
Requested intent and resolved execution:
ProblemIRpreserves the user’srequested intent(integrator="auto"or explicit scheme), while the planner and execution receipt record the concreteresolved executionmethod and device lane.Validation errors: Combining
fixed_timestepwithrk23/rk45oradaptive_timestepwithheun/rk4/abm3/coupled_imex_ark2raises immediateValueErrorvalidation errors in Python and planner rejection in Rust.Unsupported combinations: Requesting
abm3ontarget="fem"orcoupled_imex_ark2without coupled magnetoelastic dynamics is rejected as an unsupported combination before solver startup.Atomic stage failure (
LLG-TD-ATOMIC-V1): Non-finite stage fields or RHS evaluations immediately abort the attempted step and restore the pre-attempt magnetization and effective-field snapshot (rk_step_transaction.hpp).
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).
Where this is implemented¶
Layer |
File |
Symbol |
Responsibility |
|---|---|---|---|
Python DSL |
Public LLG integrator contract and |
||
Python DSL |
Adaptive tolerance and step-bound validation |
||
Python DSL |
Canonical stage-workflow solver-policy facade |
||
Native FEM CPU |
FEM stage right-hand-side evaluation |
||
Native FEM CPU |
FEM explicit RK step execution |
||
Native FEM CPU |
FEM reusable explicit-RK workspace implementation |
||
Native FEM GPU |
Device-resident GPU RK step orchestration |
||
Native FEM GPU |
GPU RK accepted-attempt loop and atomic rollback |
||
Native FEM GPU |
Host-side FSAL eligibility and operator-signature policy |
||
FDM Engine |
FDM CPU multistep ( |
||
FDM Runner |
Resumes FDM CPU |