Adaptive Time-Stepping and History PI Controller¶
Last changes: Documentation changelog
Scope and purpose¶
This chapter specifies the canonical adaptive time-stepping contract (0960: LLG-TD-POLICY-V1 through LLG-TD-ATOMIC-V1) used by Fullmag’s embedded Runge–Kutta integrators (rk23 and rk45). It defines the active-node mixed error norm, the order-aware proportional–integral (PI) step-size controller with memory of the previous accepted error ratio, optional spin-rotation and norm-drift guards, first-step selection, stiffness diagnostics, and atomic rollback on step rejection across FEM and FDM CPU/GPU realizations.
Scientific and numerical model¶
For an embedded Runge–Kutta pair of error order \(p\) (\(p=2\) for Bogacki–Shampine rk23, \(p=4\) for Dormand–Prince rk45), let \(\mathbf{m}_i^{\mathrm{old}}\) denote the accepted state at the beginning of attempted step \(k\), \(\mathbf{m}_i^{\mathrm{high}}\) the high-order candidate state before final renormalization, and \(e_i = \Delta t_k \sum_{s=1}^{S}(b_s^{\mathrm{hi}} - b_s^{\mathrm{lo}})\mathbf{k}_{s,i}\) the local embedded 3-vector error at active magnetic cell or node \(i \in \mathcal{A}\) (\(M_{s,i} > 0\)).
Each active degree of freedom is scaled by the mixed absolute/relative tolerance (LLG-TD-MAX-ERR-V1):
The global normalized error ratio for the attempted step is the active-set maximum norm:
An attempted step is accepted only when \(\eta \le 1\), all stage states are finite, and any configured geometric guards (max_spin_rotation and norm_tolerance) are satisfied. Given the error-estimator order \(p\) (so the local truncation error scales as \(\mathcal{O}(\Delta t^q)\) with \(q = p + 1\)), safety factor \(s \in (0, 1]\), current error ratio \(\eta_k = \eta\), and previous accepted non-zero error ratio \(\eta_{k-1}\), the backend-neutral decision policy (decide_adaptive_step in native/include/fullmag_adaptive_step_decision.hpp) proposes the next step size via the order-aware history PI controller (LLG-TD-POLICY-V1):
Symbols and SI units¶
Symbol |
Meaning |
SI unit |
|---|---|---|
\(e_i\) |
embedded error vector at active point i |
\(1\) |
\(a_{\mathrm{tol}}\) |
absolute tolerance |
\(1\) |
\(r_{\mathrm{tol}}\) |
relative tolerance |
\(1\) |
\(\eta_i\) |
local normalized error |
\(1\) |
\(\eta\) |
global normalized error metric |
\(1\) |
\(m_i\) |
reduced magnetization at active point i |
\(1\) |
\(\Delta t\) |
current time step |
\(\mathrm{s}\) |
\(s\) |
controller safety factor |
\(1\) |
\(q\) |
error-estimator order |
\(1\) |
\(\rho_{\mathrm{shrink}}\) |
lower step-ratio limit |
\(1\) |
\(\rho_{\mathrm{growth}}\) |
upper step-ratio limit |
\(1\) |
Canonical adaptive solver invariants (0960)¶
First-step selection (
LLG-TD-FIRST-DT-V1): Whendt_initialis explicitly supplied, it must lie within \([\Delta t_{\min}, \Delta t_{\max}]\) and seeds attempt \(k=0\) directly; otherwise the runtime derives a conservative initial step from the initial torque scale \(\|\mathbf{f}(\mathbf{m}_0, t_0)\|_{\infty}\) clamped to \([\Delta t_{\min}, \Delta t_{\max}]\).Geometric and norm guards (
LLG-TD-MAX-ERR-V1): Whenmax_spin_rotation(\(\theta_{\max}\), in radians) ornorm_tolerance(\(\varepsilon_{\mathrm{norm}}\)) is set, the step is rejected if \(\max_{i\in\mathcal{A}} \arccos(\mathbf{m}_i^{\mathrm{old}}\cdot\mathbf{m}_i^{\mathrm{new}}) > \theta_{\max}\) or \(\max_{i\in\mathcal{A}} |\|\mathbf{m}_i^{\mathrm{high}}\|_2 - 1| > \varepsilon_{\mathrm{norm}}\), even if \(\eta \le 1\).Atomic step rollback (
LLG-TD-ATOMIC-V1): A rejected attempt restores the magnetization state, effective-field buffers, FSAL derivative cache, and simulation clock to their exact pre-attempt values before retrying with \(\Delta t_{\mathrm{new}}\).Underflow and stiffness diagnostics (
LLG-TD-ATTEMPT-V1,LLG-TD-STIFF-V1): If \(\eta > 1\) at \(\Delta t = \Delta t_{\min}\), the solver fails closed with a typeddt_minunderflow diagnostic rather than accepting an inaccurate step. Persistent step rejections near the exchange stability ceiling are tracked in step statistics.
Discrete realization and backend support matrix¶
Solver |
Device |
Status |
Realization notes |
|---|---|---|---|
FEM |
CPU |
|
Nodewise mixed error reduction ( |
FEM |
GPU |
|
Device block reduction ( |
FDM |
CPU |
|
Active-cell error reduction ( |
FDM |
GPU |
|
Device-side reductions ( |
Parameters¶
Python surface |
Type |
Default |
SI unit |
Validation / constraints |
Meaning |
Backend support |
|
|---|---|---|---|---|---|---|---|
|
|
|
\(1\) |
non-negative; not both tolerances zero |
absolute error component |
RK23/RK45 lanes |
|
|
|
|
\(1\) |
non-negative; not both tolerances zero |
relative error component |
RK23/RK45 lanes |
|
|
|
|
\(\mathrm{s}\) |
positive and within bounds when set |
first proposed step |
lane-dependent |
|
|
|
|
\(\mathrm{s}\) |
positive |
minimum allowed step |
RK23/RK45 lanes |
|
|
|
|
\(\mathrm{s}\) |
positive and \(\ge \Delta t_{\min}\) |
maximum allowed step |
RK23/RK45 lanes |
|
|
|
|
\(1\) |
safety factor in \((0, 1]\) |
conservative controller factor |
RK23/RK45 lanes |
|
|
|
|
\(1\) |
|
maximum step growth ratio |
RK23/RK45 lanes |
|
|
|
|
\(1\) |
|
minimum step ratio |
RK23/RK45 lanes |
|
|
|
|
\(\mathrm{rad}\) |
positive when set |
per-step maximum spin-angle rotation guard |
RK23/RK45 lanes |
|
|
|
|
\(1\) |
positive when set |
pre-normalization unit-length drift guard |
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.1, 0.0)),
demag=True,
)
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_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=0.35,
norm_tolerance=1e-3,
),
)
study.stages.add_time(name="adaptive_pulse", duration=0.2e-9, By=8e-3, save_m_every=50e-12)
ProblemIR excerpt¶
{
"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": 0.35,
"norm_tolerance": 0.001
}
}
Control Room workflow¶
Solver Inspector: Exposes
atol,rtol,dt_initial,dt_min,dt_max,safety,growth_limit,shrink_limit,max_spin_rotation, andnorm_tolerancewhenever an adaptive integrator (auto,rk45,rk23) is selected.Diagnostics Panel: Displays real-time \(\Delta t_k\), normalized error \(\eta_k\), accepted/rejected step counts, and stiffness indicators.
Diagnostics and failure semantics¶
Requested intent and resolved execution:
ProblemIRrecords the fullAdaptiveTimesteppolicy (requested intent), while runtime receipts record the resolved integrator, accepted/rejected attempt counts, and terminal \(\Delta t\) (resolved execution).Validation errors: Setting both
atol == 0andrtol == 0, inverted step bounds (dt_max < dt_minordt_initialoutside[dt_min, dt_max]),safetyoutside(0, 1],growth_limit <= 1, orshrink_limitoutside(0, 1)raises immediateValueErrorvalidation errors.Unsupported combinations: Attaching
AdaptiveTimestepto fixed-step integrators (heun,rk4,abm3,coupled_imex_ark2) is rejected as an unsupported combination at both Python construction and Rust planning boundaries.
Scientific bibliography¶
G. Söderlind, Automatic control and adaptive time-stepping, Numer. Algorithms 31, 281–310 (2002).
E. Hairer, S. P. Nørsett, and G. Wanner, Solving Ordinary Differential Equations I: Nonstiff Problems, 2nd ed., Springer (1993).
Where this is implemented¶
Layer |
File |
Symbol |
Responsibility |
|---|---|---|---|
Python DSL |
Public adaptive controller validation and IR |
||
Python DSL |
Compatibility of integrator and adaptive policy |
||
Shared Native Header |
Backend-neutral history-aware scalar accept/retry/dt-min policy |
||
Native FEM CPU |
Native FEM nodewise mixed error norm and fail-closed guards |
||
Native FEM CPU |
Native FEM history-aware scalar controller and rejection accounting |
||
Native FEM GPU |
|
Native FEM GPU device reduction of the nodewise error norm |
|
FDM CPU Engine |
FDM CPU history-aware bounded proposal and dt-min decision |
||
FDM GPU CUDA |
FDM GPU device-side adaptive error policy |
||
FDM GPU CUDA |
FDM GPU scalar reduction implementation |