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

AIBECS v0.18.0

Diff since v0.17.1

Breaking changes

• CTKAlg's default linsolve field now eagerly defaults to UMFPACKFactorization() instead of nothing. Runtime behaviour is unchanged (the previous === nothing branch fell back to UMFPACK too), but the type parameter CTKAlg{L} is now CTKAlg{UMFPACKFactorization} by default rather than CTKAlg{Nothing}. Any downstream code dispatching on CTKAlg{Nothing} will need updating.

New features

• Analytical ∂Gs/∂G keyword on AIBECSFunction — supply closed-form derivatives of the source–sink term G to skip the per-block ForwardDiff.derivative call in Jacobian assembly. Strictly opt-in; omitting the keyword keeps the existing ForwardDiff path. Tuple-of-tuples shape for multi-tracer; check_∂Gs(Gs, ∂Gs, x, p, nb) is exported to validate analytical derivatives against ForwardDiff.

• AD-through-the-solve for CTKAlg — new solve(::SteadyStateProblem{…,Dual,…}, ::CTKAlg) dispatch peels the duals, runs the primal Newton–Chord–Shamanskii at Float64, and reconstructs ∂u*/∂p via the implicit function theorem (Jᵤ z = −Jₚ). Nested-Dual (Hessian) calls recurse one Dual layer per level, routed through LinearSolve's DualLinearCache so the sparse factorisation is reused — no densification. ForwardDiff.gradient(p -> sum(solve(SteadyStateProblem(F, x, p), CTKAlg()).u), p) now Just Works on AIBECS's sparse Jacobian.

• AIBECS.nonlinearproblem Dual-stripping — the sparse jac_prototype builder now strips Duals before construction, so the SciML NonlinearSolve IFT path also works with ForwardDiff over an AIBECS steady-state solve.

Caveats

• The IFT dispatch reuses three NonlinearSolveBase symbols (nodual_value, nonlinearsolve_∂f_∂p, nonlinearsolve_dual_solution) that are public-but-internal-feeling. A one-shot @warn surfaces this on first AD-through-solve call.
• IFT-reconstructed partials inherit the primal Newton residual; for machine-precision derivatives the solver must be forced past its stopping rule (abstol=0, run to maxItNewton). Not practical at production grid sizes — use F1Method's analytical gradient/Hessian there.

Merged pull requests:

• feat: analytical ∂Gs for G + AD-through-the-solve via IFT for CTKAlg (#124) (@briochemc)