AdaptiveTimestep Contract¶
Last changes: Documentation changelog
1. Physical problem and overview¶
fm.AdaptiveTimestep configures the embedded Runge–Kutta error tolerances, step-size bounds, proportional–integral (PI) controller gains/limits, and optional spin-rotation and norm-drift guards used by rk23, rk45, and auto time integration across FEM and FDM CPU/GPU realizations (0960: LLG-TD-POLICY-V1 through LLG-TD-ATOMIC-V1).
2. Governing equations¶
For an attempted step \(\Delta t_k\) on an embedded Runge–Kutta pair of error order \(p\) (\(p=2\) for rk23, \(p=4\) for rk45), the active-node normalized error metric (LLG-TD-MAX-ERR-V1) is
and the history-aware PI step-size update (LLG-TD-POLICY-V1) is
3. Symbols and SI units¶
Symbol |
Meaning |
SI unit |
|---|---|---|
\(\mathbf{e}_i\) |
Embedded high-minus-low vector error at active point \(i\) |
\(1\) |
\(\mathbf{m}_i^{\mathrm{old}}\) |
Accepted magnetization state at the start of step \(k\) |
\(1\) |
\(\mathbf{m}_i^{\mathrm{high}}\) |
High-order candidate magnetization state before final normalization |
\(1\) |
\(\mathrm{atol}\) |
Absolute normalized-state error tolerance |
\(1\) |
\(\mathrm{rtol}\) |
Relative normalized-state error tolerance |
\(1\) |
\(\rho_k\) |
Maximum normalized local error ratio at attempt \(k\) |
\(1\) |
\(\rho_{k-1}\) |
Previous accepted non-zero normalized error ratio |
\(1\) |
\(p\) |
Embedded error-estimator order (\(2\) for |
\(1\) |
\(s\) |
Controller safety factor ( |
\(1\) |
\(q_k\) |
Raw adaptive step-size multiplier |
\(1\) |
\(q_{\min}\) |
Minimum step-size shrink ratio ( |
\(1\) |
\(q_{\max}\) |
Maximum step-size growth ratio ( |
\(1\) |
\(\Delta t_k\) |
Attempted time step |
\(\mathrm{s}\) |
\(\Delta t_{\min}\) |
Minimum allowed time step ( |
\(\mathrm{s}\) |
\(\Delta t_{\max}\) |
Maximum allowed time step ( |
\(\mathrm{s}\) |
\(\mathcal{A}\) |
Active magnetic cell/node index set (\(M_{s,i} > 0\)) |
\(1\) |
4. Assumptions and limits of validity¶
Non-degenerate tolerance scale: Both
atolandrtolmust be non-negative and at least one must be strictly positive so that the denominator in (1) is positive on active magnetic nodes.Step-bound ordering: When
dt_maxis supplied, \(\Delta t_{\max} \ge \Delta t_{\min} > 0\); whendt_initialis supplied, \(\Delta t_{\min} \le \Delta t_{\mathrm{initial}} \le \Delta t_{\max}\).Atomic rejection and
dt_minfloor: Rejected steps (\(\rho_k > 1\) or violatedmax_spin_rotation/norm_tolerance) restore the pre-attempt state and retry with \(\Delta t_{k+1}\). If \(\rho_k > 1\) at \(\Delta t_k = \Delta t_{\min}\), execution fails closed with a typeddt_minunderflow error.
5. Python API and parameter contract¶
Constructor signature¶
fm.AdaptiveTimestep(
*,
atol: float = 1e-6,
rtol: float = 1e-3,
dt_initial: float | None = None,
dt_min: float = 1e-15,
dt_max: float | None = None,
safety: float = 0.9,
growth_limit: float = 2.0,
shrink_limit: float = 0.2,
max_spin_rotation: float | None = None,
norm_tolerance: float | None = None,
)
Parameter reference¶
Python parameter |
Type |
Default |
SI unit |
Validation |
Meaning |
Backend support |
|
|---|---|---|---|---|---|---|---|
|
|
|
\(1\) |
Non-negative; one of atol/rtol positive |
Absolute tolerance |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
|
|
|
\(1\) |
Non-negative |
Relative tolerance |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
|
|
|
\(\mathrm{s}\) |
Within |
Initial step |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
|
|
|
\(\mathrm{s}\) |
Positive |
Minimum step |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
|
|
|
\(\mathrm{s}\) |
|
Maximum step |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
|
|
|
\(1\) |
|
Step safety factor |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
|
|
|
\(1\) |
|
Growth limit |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
|
|
|
\(1\) |
|
Shrink limit |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
|
|
|
\(\mathrm{rad}\) |
Positive |
Spin-rotation cap |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
|
|
|
\(1\) |
Positive |
Norm tolerance |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
Executable Python example¶
# %%
import fullmag as fm
adaptive = 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,
)
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,
)
study = fm.study(world, target="fdm", device="cpu", precision="fp64")
study.solver(integrator="rk45", adaptive_timestep=adaptive)
study.stages.add_time(name="pulse", duration=0.2e-9, By=5e-3, save_m_every=50e-12)
ir = study.to_problem_ir()
assert ir["study"]["dynamics"]["adaptive_timestep"]["atol"] == 1e-6
assert ir["study"]["dynamics"]["adaptive_timestep"]["max_spin_rotation"] == 0.35
6. ProblemIR and canonical script representation¶
{
"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
}
}
7. Round-trip, provenance, and failure semantics¶
Requested intent vs. resolved execution:
AdaptiveTimestepfields serialize verbatim intoProblemIR(requested intent) and are recorded alongside the resolved integrator and step statistics in the execution receipt (resolved execution).Validation errors: Negative tolerances,
atol == 0andrtol == 0,dt_min <= 0,dt_max < dt_min,dt_initialoutside[dt_min, dt_max],safetyoutside(0, 1],growth_limit <= 1, orshrink_limitoutside(0, 1)raise immediateValueErrorvalidation errors.Unsupported combinations: Supplying
AdaptiveTimestepalongsidefixed_timestepor with a fixed-step integrator (heun,rk4,abm3,coupled_imex_ark2) is rejected as an unsupported combination.
8. Discrete realization and numerical operators¶
Shared PI decision header:
decide_adaptive_stepinnative/include/fullmag_adaptive_step_decision.hpp.FEM CPU & GPU:
compute_adaptive_error_norm/adaptive_pi_step(CPU) andadaptive_error_norm_blocks_kernel/gpu_rk_adaptive_pi_step(GPU).FDM CPU & GPU:
max_error_norm_buf/decide_adaptive_step(CPU) andreduce_adaptive_error_policy(GPU).
9. Backend and device implementation mapping¶
Solver |
Device |
Status |
Notes |
|---|---|---|---|
FEM |
CPU |
|
Nodewise mixed tolerance reduction and history PI controller in |
FEM |
GPU |
|
Device block reduction ( |
FDM |
CPU |
|
Active-cell error reduction and history PI controller in |
FDM |
GPU |
|
CUDA |
10. Validation and benchmark gates¶
Validated in
packages/fullmag-py/tests/test_llg_solver_contract.py,backends/fem/tests/adaptive_dt_contract.cpp, andbackends/fem/tests/adaptive_error_policy_contract.cpp.
11. Known limitations and operational constraints¶
Local truncation error control bounds single-step error but does not by itself certify static equilibrium in
Relaxationstages; equilibrium requires the independent torque and energy stopping criteria (RelaxStop).
12. Scientific bibliography¶
G. Söderlind, Automatic control and adaptive time-stepping, Numer. Algorithms 31, 281–310 (2002).
13. Source-code index¶
Layer |
File |
Symbol / entrypoint |
Responsibility |
|---|---|---|---|
Python DSL |
Adaptive-step parameters, validation, and IR lowering |
||
Shared Native Header |
Backend-neutral order-aware history PI step decision |
||
Native FEM CPU |
Native FEM nodewise mixed error norm and geometric guards |
||
Native FEM GPU |
|
Native FEM GPU block reduction for the active-node error norm |
|
FDM CPU Engine |
FDM CPU history-aware PI step decision |
||
FDM GPU CUDA |
FDM GPU adaptive error reduction and dt-min policy |