Explicit Runge–Kutta integration¶

Scope and purpose¶

This page documents explicit Runge–Kutta stepping after FDM or FEM spatial discretization. It defines the temporal update contract and its qualification boundary; it does not make a universal CPU/GPU or method-availability claim.

Scientific and numerical model¶

After FDM or FEM spatial discretization, the magnetization state is represented by a vector \(y(t)\) and the backend exposes a right-hand side \(F(y,t)\). The integrator must advance this state while preserving the LLG tangent-flow contract, reporting the actual field evaluations, and leaving the requested output state reproducible.

Governing equations¶

The reduced-magnetization LLG right-hand side is

For an explicit \(s\)-stage RK method, stage \(j\) and its right-hand side are

The accepted state is

For embedded adaptive pairs the companion estimate is

Symbols and SI units¶

Assumptions and validity¶

• The spatial operator returns the same physical effective field used by the LLG RHS; the integrator does not reinterpret field signs or units.

• Explicit RK stability remains conditional. A high-order method does not remove the exchange or demagnetization time-step restriction.

• rk23 and rk45 are embedded adaptive families. heun and rk4 are fixed-step families in the current public LLG contract.

• The discrete stage state can deviate from \(|\mathbf m|=1\) in finite precision. Norm control and diagnostics are backend policies, not a license to change the physical equation.

Python API¶

The stage-first workflow below is directly copyable into a notebook. It requests an FDM CPU double-precision run; it does not claim that the local request itself proves device execution.

# %% Imports and SI constants
import fullmag as fm

nm = 1.0e-9
study = fm.study("rk_time_integration")
study.engine("fdm")
study.device("cpu", precision="double")
study.mode("strict")
study.objects.mesh.defaults(cell_size=(2 * nm, 2 * nm, 5 * nm))

# %% Physical domain and interaction request
body = study.geometry(fm.Box(100 * nm, 20 * nm, 5 * nm), name="film")
body.Ms = 800.0e3
body.Aex = 13.0e-12
body.alpha = 0.02
body.m = fm.texture.uniform(1.0, 0.0, 0.0)
study.exchange()

# %% Solver policy and ordered physical-time stage
study.solver(
    integrator="rk45",
    adaptive_timestep=fm.AdaptiveTimestep(
        atol=1.0e-6,
        rtol=1.0e-3,
        dt_min=1.0e-15,
        dt_max=1.0e-12,
    ),
    gamma=2.211e5,
)
study.stages.add_run(until=1.0e-9)

study.solver(...) is the canonical user-facing solver-policy call in the stage workflow. It lowers the requested method and adaptive policy into the canonical llg dynamics node. There is no second object-constructor workflow in this page.

Parameters¶

The following rows are the public solver and adaptive-policy arguments used by the example. Defaults, validation and ProblemIR keys are mirrored by the adjacent source map.

ProblemIR and normalization¶

The stage request above lowers to the following canonical dynamics fragment:

{
  "kind": "llg",
  "gyromagnetic_ratio": 221100.0,
  "integrator": "rk45",
  "fixed_timestep": null,
  "adaptive_timestep": {
    "tolerance_mode": "advanced",
    "atol": 1e-06,
    "rtol": 0.001,
    "dt_initial": null,
    "dt_min": 1e-15,
    "safety": 0.9,
    "growth_limit": 2.0,
    "shrink_limit": 0.2
  }
}

study.solver(...) normalizes the requested method into the canonical dynamics node. dp54 normalizes to rk45 and bs23 normalizes to rk23 before lowering. auto remains requested intent until planner resolution; the resolved execution records the selected method, device, precision, and field-refresh policy as provenance.

Diagnostics and failure semantics¶

The canonical export preserves requested intent separately from resolved execution. Validation errors are raised before execution for unknown integrators, non-positive gamma, non-positive step bounds, conflicting fixed and adaptive policies, or an adaptive policy attached to a non-adaptive integrator. Unsupported combinations are planner failures, not silent fallback; the error must identify the solver, device, precision, and requested method.

Discrete realization by solver and device¶

FSAL reuse is allowed only when the cached RHS belongs to the accepted endpoint and the source state is unchanged between endpoint and next-stage evaluation. A thermal or time-dependent source can disable reuse. A final field refresh is part of reported work when exact final-state observables are requested.

Where this is implemented¶

The public model is lowered by LLG.to_ir; the stage builder captures ordered run stages. FEM keeps RK workspace and stage RHS evaluation in integrator modules rather than embedding them in the global context. FDM CUDA kernels own the lane-specific stage arithmetic and reductions.

Validation¶

Validation is split into structural contract tests, numerical order tests, and executed-runtime qualification. backends/fem/tests/rk_explicit_contract.cpp checks module ownership and RK workspace boundaries. FDM adaptive/error-reduction tests check step-decision behavior. A passing source or unit test does not by itself prove CPU/GPU physical parity; that requires a managed run with recorded device identity, precision, tolerances, accepted/rejected steps, and observable agreement.

Limitations and qualification boundary¶

Explicit RK is not an unconditional stiff solver. The public method names do not imply that all four lanes support every method at every precision. auto is a request for planner resolution, not a promise of a particular tableau. Tangent-plane and fully implicit methods are documented separately and must not be inferred from the explicit RK page.

Scientific bibliography¶

• J. C. Butcher, Numerical Methods for Ordinary Differential Equations, 3rd ed., Wiley, 2016, DOI: 10.1002/9781119121534.

• E. Hairer, S. P. Nørsett, G. Wanner, Solving Ordinary Differential Equations I, 2nd ed., Springer, 1993, DOI: 10.1007/978-3-540-78862-1.

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

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¶