AIBECS.jl: A tool for exploring global marine biogeochemical cycles

AIBECS v0.20.0

Diff since v0.19.6

Breaking changes

CTKAlg's default convergence criterion changed from the NonlinearSolveBase AbsNormSafeBestTerminationMode (absolute, unit-blind) to NormTerminationMode (scale-aware), with new tolerance defaults:

| kwarg | old default | new default | | ----------------------- | --------------------------------------------- | ------------------------------------------------- | | termination_condition | AbsNormSafeBestTerminationMode(maximum∘abs) | NormTerminationMode(maximum∘abs) | | abstol | nothing → NSB default (≈ 3e-13 for Float64) | 0.0 | | reltol | nothing → NSB default (≈ 3e-13 for Float64) | 1 / ustrip(s, 1Myr) ≈ 3.17e-14 (τstop = 1 Myr) |

The new rule is

‖F‖∞ ≤ abstol     ||     ‖F‖∞ ≤ reltol · ‖F + x‖∞

With abstol = 0 the active branch is the relative one — equivalent to ‖x‖/‖F‖ ≥ τstop, the same physically meaningful "system is steady on timescales longer than τstop" criterion as the original τstop kwarg before AIBECS adopted NonlinearSolveBase termination modes.

Why it changed. The previous default was unit-blind and broke in opposite directions on tutorial problems:

• Radiocarbon: ‖F₀‖∞ ≈ 1e-13 already met the absolute tolerance on the first call, so Newton ran zero iterations. Required a manual abstol = … workaround in the tutorial.
• Ideal age: ‖F‖∞ floored at eps · cond(J) ≈ 1e-10, never met abstol, and NSB safe-best stall detection could not fire inside maxItNewton = 50 (patience = 100, max_stalled_steps = nothing). Solver ground to MaxIters.

The relative criterion side-steps both — ‖x‖∞ provides the scale.

Migration

• Default users: no action required. Both tutorial problems and the test suite converge with the new defaults.
• Users who set abstol explicitly: the new default reltol ≈ 3.17e-14 is now also checked (OR semantics) — for typical AIBECS problems with ‖x‖ ≫ 1 this is the looser branch and your abstol still governs. Pass reltol = 0 to suppress the relative branch entirely.
• Users who relied on AbsNormSafeBest-specific behaviour (best-iterate tracking, stall-based StalledSuccess): pass termination_condition = AbsNormSafeBestTerminationMode(maximum∘abs) explicitly.

Other changes

• CTKAlg now emits an @warn when it returns a non-success retcode, reporting retcode, residual ∞-norm, abstol, reltol, and maxItNewton. Silent MaxIters / Unstable failures are now visible.
• The radiocarbon tutorial no longer needs the manual abstol = ustrip(upreferred(1e-8·Ratm/yr)) workaround — solve(prob, CTKAlg()) is enough.