Time integration¶

Numerical problem¶

After FDM or FEM spatial discretization, Fullmag exposes a state vector \(y(t)\) and a right-hand side \(F(y,t)\). For reduced magnetization,

The spatial backend owns \(\mathbf H_{\mathrm{eff}}\) and any enabled torque. The temporal method owns stage construction, field refreshes, acceptance/rejection, time advancement, and endpoint publication. It must not change interaction signs, SI units, material coefficients, or boundary conditions.

The exact continuum equation and conventions are documented under Landau–Lifshitz–Gilbert equation. This section documents only the numerical temporal realization.

Required invariants and diagnostics¶

A correct time integrator must preserve the following execution semantics even when floating-point trajectories differ between lanes:

• only accepted steps advance physical time and accepted-step counters;

• rejected adaptive trials do not publish outputs or continuation artifacts;

• requested output times are reached according to the documented endpoint/interpolation policy;

• non-finite stage states, fields, errors, or norms terminate with an explicit failure reason;

• the resolved integrator, step policy, field-refresh count, precision, and device are recorded;

• magnetization-norm drift is measured and controlled by an explicit backend policy rather than hidden state mutation.

The unit-length constraint is geometric. For the exact LLG flow, \(\mathbf m\cdot\dot{\mathbf m}=0\). Generic explicit Runge–Kutta stage states do not preserve this identity exactly, so endpoint normalization and norm diagnostics, where present, are numerical policies that must be reported.

Public method vocabulary¶

A method name shared by CPU and GPU means the same Butcher tableau and acceptance semantics, not bit-identical stage values. Field evaluation order, reduction order, fused kernels, host/device ownership, and precision can change the last bits and eventually the trajectory of a nonlinear system.

Explicit Runge–Kutta formulation¶

For an \(s\)-stage explicit method,

and the accepted candidate is

For an embedded pair,

Explicit Runge–Kutta integration records the public parameters, exact source owners, lane matrix, validation requirements, and the distinction between reusable FEM stage workspaces and FDM structured-grid kernels.

Adaptive acceptance and controller¶

For active point \(i\), Fullmag’s documented normalized error is

The trial is accepted exactly when \(\eta\leq1\). For estimator order \(q\), the proposed next step is

followed by the absolute dt_min and optional dt_max bounds. The public defaults are \(a_{\mathrm{tol}}=10^{-6}\), \(r_{\mathrm{tol}}=10^{-3}\), \(\Delta t_{\min}=10^{-15}\,\mathrm s\), safety \(s=0.9\), growth limit \(2.0\), and shrink limit \(0.2\). Hitting dt_min while \(\eta>1\) is a controlled failure, not permission to accept an inaccurate step.

Adaptive control estimates temporal local error for the current spatial discretization. It does not estimate mesh error, demagnetization truncation, linear-solver error, material uncertainty, or model-form error. See Adaptive time stepping.

Stiffness and step selection¶

The fastest resolved exchange modes usually grow as the inverse square of the smallest spatial length. Consequently, explicit stability can become more restrictive approximately as

up to stencil, damping, geometry, and method-dependent constants. This relation is a scaling guide, not a Fullmag acceptance formula. A smaller mesh can therefore require both more spatial degrees of freedom and more time steps.

Practical convergence requires two independent studies:

1. reduce the accepted time-step scale or tighten adaptive tolerances at fixed mesh;

2. refine the spatial discretization at a temporally converged setting.

Agreement under only one of these studies is insufficient.

Tangent-plane methods¶

At a normalized state \(\boldsymbol\mu_i\), the tangent projector is

A tangent-plane method solves for an increment in the plane orthogonal to \(\boldsymbol\mu_i\) and retracts or normalizes the updated state. This avoids treating the unit-length constraint as three independent unconstrained scalar equations. Fullmag’s public tangent_plane_implicit vocabulary is FEM-only in the current contract. Its source-visible presence must not be interpreted as FDM or universally qualified GPU support. See Tangent-plane methods.

Public Python contract¶

The normal authoring path configures the solver once and appends a physical-time stage:

# %% Adaptive RK45 physical-time integration
import fullmag as fm

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

film = study.geometry(fm.Box(100 * nm, 30 * nm, 5 * nm), name="film")
film.Ms = 800.0e3
film.Aex = 13.0e-12
film.alpha = 0.02
film.m = fm.texture.uniform(1.0, 0.0, 0.0)
study.exchange()
study.demag()

study.solver(
    integrator="rk45",
    gamma=2.211e5,
    adaptive_timestep=fm.AdaptiveTimestep(
        atol=1.0e-7,
        rtol=1.0e-3,
        dt_initial=1.0e-14,
        dt_min=1.0e-15,
        dt_max=1.0e-12,
    ),
)
study.stages.add_run(stage_id="transient", until=2.0e-9)

Important public parameters are:

The terminal pages own the exact ProblemIR paths and compatibility rules. In particular, a fixed step and an incompatible adaptive object are rejected rather than silently reconciled.

Realization matrix¶

abm3, tangent-plane, coupled spin-transport, mixed precision, multilayer FDM, and interaction- specific GPU restrictions are capability dimensions. The planner must reject an illegal product of these dimensions instead of falling back to a different algorithm.

Implementation mapping¶

Validation requirements¶

Limitations¶

• Explicit methods remain conditionally stable and may be inefficient for exchange-stiff systems.

• Adaptive state error is not a physical observable error estimator.

• tangent_plane_implicit is not an FDM method in the current public contract.

• coupled_imex_ark2 requires the transient spin-transport module and must not be advertised as a standalone LLG fallback.

• Source-visible GPU kernels do not establish that a specific run remained device-resident.

• The documentation does not claim symplecticity, exact norm preservation, or unconditional energy stability for generic explicit RK trajectories.

Scientific bibliography¶

1. J. L. Dormand and P. J. Prince, “A family of embedded Runge–Kutta formulae,” Journal of Computational and Applied Mathematics 6, 19–26 (1980), doi:10.1016/0771-050X(80)90013-3.

2. P. Bogacki and L. F. Shampine, “A 3(2) pair of Runge–Kutta formulas,” Applied Mathematics Letters 2, 321–325 (1989), doi:10.1016/0893-9659(89)90079-7.

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

4. S. Bartels and A. Prohl, “Convergence of an implicit finite element method for the Landau–Lifshitz–Gilbert equation,” SIAM Journal on Numerical Analysis 44, 1405–1419 (2006), doi:10.1137/050631070.

5. L. Baňas, S. Bartels, and A. Prohl, “A convergent implicit finite element discretization of the Maxwell–Landau–Lifshitz–Gilbert equation,” SIAM Journal on Numerical Analysis 46, 1399–1422 (2008), doi:10.1137/070683064.

Control Room crosswalk¶

This is a navigation page; use the terminal page named by the selected stage or solver. The category itself has no standalone editor. 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¶

This is a navigation page and introduces no standalone implementation symbol. The exact source-code index is maintained by the selected terminal page.