Adaptive time stepping¶

Scope and purpose¶

This page documents the public adaptive-step policy for accepted physical-time LLG stages. It specifies temporal error control and its provenance boundary; spatial discretization and executed device qualification remain separate concerns.

Scientific and numerical model¶

For an embedded pair, two approximations of different order are computed from the same stage right-hand sides. The difference controls acceptance and the next proposed step. Rejected steps must not advance physical time or duplicate output artifacts.

Governing equations¶

The normalized error used by the adaptive policy is

The global decision metric is

For estimator order \(q\), the unconstrained next step is

Symbols and SI units¶

Assumptions and validity¶

• The error estimate is a temporal estimator for the current spatial mesh and active physics.

• Both tolerances are dimensionless because the reduced magnetization state is dimensionless.

• dt_min is a hard lower bound. Hitting it while the error remains above one is a controlled failure, not silent acceptance.

• Rejected steps may evaluate fields, but they must not be reported as accepted physical states.

Python API¶

# %% Configure an adaptive physical-time study
import fullmag as fm

nm = 1.0e-9
study = fm.study("adaptive_rk45")
study.engine("fdm")
study.device("gpu", precision="double")
study.mode("strict")
study.objects.mesh.defaults(cell_size=(2 * nm, 2 * nm, 5 * nm))
body = study.geometry(fm.Box(80 * 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-7,
        rtol=1.0e-3,
        dt_min=1.0e-15,
        dt_max=1.0e-12,
    ),
    gamma=2.211e5,
)
study.stages.add_run(until=2.0e-9)

The study.solver(...) call is the only user-facing solver configuration shown in this workflow. It lowers the adaptive policy into the canonical llg dynamics node; the resolved integrator, bounds, tolerances, and device remain part of execution provenance.

Parameters¶

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

ProblemIR¶

The policy lowers to an adaptive_timestep object nested under the llg dynamics node. Defaults are materialized by the Python constructor, while omitted dt_max, dt_initial, spin-rotation, and norm controls remain null/absent according to the serializer. rk23 and rk45 are the only explicit adaptive method names accepted by the current LLG validator.

Diagnostics and failure semantics¶

Round-trip export preserves requested intent, requested tolerances, and bounds, then records resolved execution separately. Validation errors cover both zero tolerances, invalid bounds, invalid safety or growth/shrink ratios, and fixed/adaptive timestep conflicts. Unsupported combinations are reported by the planner; the runtime must not silently downgrade an adaptive request to a fixed step. A step that reaches dt_min without meeting the error policy is a failed execution state.

FDM/FEM and CPU/GPU realization¶

The GPU distinction is material: error reductions and stage data can remain device-resident, whereas the CPU reference uses host-visible state. These are two realizations of the same accept/reject semantics, not two different tolerance meanings.

Where this is implemented¶

AdaptiveTimestep owns public validation and IR serialization. FDM CUDA reductions provide the device-side error scalar and the integrator consumes it. FEM integrator modules own stage workspace and endpoint refresh policy.

Validation¶

The relevant checks are Python constructor tests, FDM adaptive error-reduction contracts, and FEM explicit-RK contracts. Runtime qualification must record accepted/rejected step counts, resolved dt, tolerance values, field-refresh policy, device identity, and final observable agreement. A green structural test is not a physical convergence proof.

Limitations¶

Adaptive time stepping does not adapt mesh size, demagnetization accuracy, linear-solver rtol, or material parameters. The current policy does not expose a user-defined controller formula. Tolerances are dimensionless state tolerances, not SI field tolerances.

Scientific bibliography¶

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

• J. R. Dormand, P. J. Prince, “A family of embedded Runge-Kutta formulae,” Journal of Computational and Applied Mathematics 6 (1980), DOI: 10.1016/0771-050X(80)90013-3.

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¶