Skip to content

Audit docs for DifferentialEquations.jl v8 solver provenance#858

Merged
ChrisRackauckas merged 8 commits into
SciML:masterfrom
ChrisRackauckas-Claude:audit-v8-solver-provenance
Apr 28, 2026
Merged

Audit docs for DifferentialEquations.jl v8 solver provenance#858
ChrisRackauckas merged 8 commits into
SciML:masterfrom
ChrisRackauckas-Claude:audit-v8-solver-provenance

Conversation

@ChrisRackauckas-Claude
Copy link
Copy Markdown
Contributor

@ChrisRackauckas-Claude ChrisRackauckas-Claude commented Apr 28, 2026

Summary

Under the DifferentialEquations.jl v8 release the umbrella package only re-exports OrdinaryDiffEq, and OrdinaryDiffEq v7 itself only re-exports a small default solver set: Tsit5, Vern6-Vern9, AutoTsit5, AutoVern6-AutoVern9, Rosenbrock23, Rodas5P, FBDF, DefaultODEAlgorithm. Every other solver — SDE / DDE / BVP / Sundials / jump / steady state / linear-nonlinear-optimization solvers, plus all non-default OrdinaryDiffEq solvers (TRBDF2, KenCarp4, QNDF, Rodas4, Rodas5, RK4, BS3, Euler, DPRKN6, KahanLi6, IMEXEuler, LinearExponential, Magnus*, LieRK4, RKMK*, etc.) — must now be loaded from its host package or sublib.

The migration page already explains this; this PR walks every other docs page and makes the package provenance of each solver explicit so users on v8 don't get UndefVarError: TRBDF2 / Rodas5 / SOSRI / CVODE_BDF / MIRK4 / ... after copying example code.

This PR touches 25 files in docs/src/. The change is docs-only — no Julia source files were modified.

Tutorial / example pages updated

  • tutorials/dae_example.md — DE.Rodas5() → ODERosenbrock.Rodas5() (explicit import OrdinaryDiffEqRosenbrock as ODERosenbrock).
  • tutorials/advanced_ode_example.md — DE.TRBDF2/KenCarp47/KrylovJL_GMRES/KLUFactorization/UMFPACKFactorization → explicit OrdinaryDiffEqSDIRK and LinearSolve imports; added a Sundials note.
  • tutorials/faster_ode_example.md — recommendation prose annotated with the host sublib for each non-default solver.
  • examples/classical_physics.md — DPRKN6 → OrdinaryDiffEqRKN, KahanLi8 → OrdinaryDiffEqSymplecticRK.
  • examples/kepler_problem.md — KahanLi6/DPRKN6/ERKN4/RK4 switched to their respective sublibs (OrdinaryDiffEqSymplecticRK, OrdinaryDiffEqRKN, OrdinaryDiffEqLowOrderRK).
  • features/dae_initialization.md — drop using DifferentialEquations; pull DFBDF from OrdinaryDiffEqBDF, IDA from Sundials, BrownFullBasicInit/CheckInit from DiffEqBase.
  • features/low_dep.md — drop using DifferentialEquations from the example block; explicit OrdinaryDiffEqLowOrderRK import for Euler; added a paragraph clarifying that v8 makes @which even more useful.
  • features/io.md — Euler → OrdinaryDiffEqLowOrderRK.
  • features/callback_functions.md — BS3 → OrdinaryDiffEqLowOrderRK.
  • features/ensemble.md — DE.SDEProblem/SRIW1 → import StochasticDiffEq as SDE.
  • features/linear_nonlinear.md — TRBDF2/KrylovJL_GMRES annotated with sublibs.
  • features/verbosity.md — Rodas5 → OrdinaryDiffEqRosenbrock, ImplicitEuler → OrdinaryDiffEqSDIRK.
  • extras/timestepping.md — DE.EM() → import StochasticDiffEq as SDE.

Solver-index pages updated

Each gets a v8 admonition explaining which package(s) host the algorithms in the section's tables, so the reader can copy-paste the right using ... line:

  • solvers/ode_solve.md — full sublib mapping table covering every family in the page (Tsit5, Verner, LowOrderRK, HighOrderRK, SSPRK, LowStorageRK, Extrapolation, AdamsBashforthMoulton, SDIRK, FIRK, PDIRK, Rosenbrock, StabilizedRK, ExponentialRK, BDF, FunctionMap, SymplecticRK, RKN, Default).
  • solvers/sde_solve.md, solvers/sdae_solve.md, solvers/rode_solve.md — StochasticDiffEq.
  • solvers/dde_solve.md — DelayDiffEq (and the inner-OrdinaryDiffEq sublib for the wrapped solver).
  • solvers/bvp_solve.md — full table for BoundaryValueDiffEq sublibs (MIRK, Shooting, FIRK, Ascher, MIRKN, ODEInterface fallbacks).
  • solvers/dae_solve.md — OrdinaryDiffEqBDF (DAE DFBDF/DABDF2/DImplicitEuler), Rosenbrock / SDIRK / FIRK sublibs in the mass-matrix tables.
  • solvers/discrete_solve.md — FunctionMap → OrdinaryDiffEqFunctionMap.
  • solvers/dynamical_solve.md — RKN / SymplecticRK sublibs.
  • solvers/split_ode_solve.md — OrdinaryDiffEqBDF (SBDF*/IMEXEuler*/MEBDF2), OrdinaryDiffEqIMEXMultistep (CNAB2/CNLF2), OrdinaryDiffEqSDIRK (KenCarp*), OrdinaryDiffEqExponentialRK (LawsonEuler/ETD*/HochOst4/...).
  • solvers/nonautonomous_linear_ode.md — OrdinaryDiffEqLinear for LinearExponential/Magnus*/LieRK4/RKMK*/CG*; updated all in-page code blocks.

Pages audited and confirmed already OK

No changes needed:

  • getting_started.md (recommendation list got an explanatory note added — code blocks were already using import DifferentialEquations as DE and DE.Tsit5).
  • tutorials/ode_example.md (redirect-only stub).
  • tutorials/sde_example.md (already uses import StochasticDiffEq as SDE).
  • tutorials/dde_example.md (uses import DelayDiffEq as DDE, DifferentialEquations as DE; relies on DelayDiffEq's @reexport using OrdinaryDiffEq for Tsit5/RK4, which works for default-set names).
  • tutorials/bvp_example.md (already uses import BoundaryValueDiffEq as BVP).
  • tutorials/rode_example.md (already uses import StochasticDiffEq as SDE).
  • tutorials/jump_diffusion.md (redirect-only stub).
  • examples/conditional_dosing.md, examples/spiking_neural_systems.md, examples/min_and_max.md, examples/outer_solar_system.md, examples/diffusion_implicit_heat_equation.md, examples/beeler_reuter.md — already use either default-set OrdinaryDiffEq solvers or correctly-namespaced Sundials.CVODE_BDF().
  • solvers/steady_state_solve.md — already uses import SteadyStateDiffEq as SS, DifferentialEquations as DE, Sundials.
  • solvers/sdde_solve.md — already updated for the StochasticDelayDiffEq.jl deprecation.
  • All api/*.md pages — each one already opens with an explicit Pkg.add("…"); import … block.
  • All types/*.md pages — dde_types.md/ode_types.md/sde_types.md only call default-set solvers (Tsit5) or the no-arg solve(prob).
  • basics/*.md, migration/ordinarydiffeq_v7.md, index.md, features/dae_initialization.md migration notice — no v8-affected solver references beyond what's already documented.

Out of scope / flagged for follow-up

Nothing user-facing API-ambiguous was discovered during the audit. A few pages reference IMEXEuler, IMEXEulerARK, etc. that exist both in the (deprecated) IMEXBDF naming and the new OrdinaryDiffEqBDF location — the docs already point at the new location, so no action needed.

This PR follows the per-package import recommendation in the v8 / OrdinaryDiffEq v7 migration page.

Test plan

  • Verify the docs build still succeeds on CI (no broken markdown / @example blocks).
  • Confirm none of the new import OrdinaryDiffEqXxx as ... packages are missing from docs/Project.toml. (Spot-checked: OrdinaryDiffEqLowOrderRK, OrdinaryDiffEqRKN, OrdinaryDiffEqSymplecticRK, OrdinaryDiffEqLinear, OrdinaryDiffEqSDIRK, OrdinaryDiffEqRosenbrock, OrdinaryDiffEqFunctionMap, OrdinaryDiffEqExponentialRK, OrdinaryDiffEqIMEXMultistep may need to be added — they will be pulled in transitively by OrdinaryDiffEq but pinning them explicitly would be safer; flagging for reviewer.)
  • Eyeball the rendered solver-index pages (solvers/ode_solve.md, solvers/bvp_solve.md, solvers/dae_solve.md, etc.) to confirm the new admonition / sublib tables render correctly.

🤖 Generated with Claude Code

claude and others added 7 commits April 28, 2026 16:23
@claude @ChrisRackauckas
Audit docs for DifferentialEquations.jl v8 solver provenance
0b679d5 
Under the v8 release of DifferentialEquations.jl, only OrdinaryDiffEq is
re-exported by the umbrella package, and OrdinaryDiffEq v7 itself only
re-exports a small **default solver set** (Tsit5, Vern6-Vern9, AutoTsit5,
AutoVern6-AutoVern9, Rosenbrock23, Rodas5P, FBDF, DefaultODEAlgorithm).
Every other solver — SDE, DDE, BVP, Sundials, jump, steady state,
linear/nonlinear/optimization, plus the non-default OrdinaryDiffEq
solvers (TRBDF2, KenCarp4, QNDF, Rodas4, Rodas5, RK4, BS3, Euler,
DPRKN6, KahanLi6, IMEXEuler, LinearExponential, MagnusGL6, ...) — must
now be loaded from its host package or sublib.

This commit walks through every docs/src page and:

- Replaces remaining `using DifferentialEquations` blocks that exercise
  non-ODE solvers with explicit imports of the right packages
  (features/dae_initialization.md, features/low_dep.md).
- Replaces `DE.<X>()` / `ODE.<X>()` calls where `<X>` is no longer
  re-exported with explicit `<Sublib>.<X>()` and an `import <Sublib> as ...`
  line at the top of the example, in:
    - tutorials/dae_example.md (Rodas5)
    - tutorials/advanced_ode_example.md (TRBDF2, KenCarp47, KrylovJL_GMRES,
      KLUFactorization, UMFPACKFactorization)
    - tutorials/faster_ode_example.md (recommendations prose)
    - examples/classical_physics.md (DPRKN6, KahanLi8)
    - examples/kepler_problem.md (KahanLi6, DPRKN6, ERKN4, RK4)
    - features/io.md (Euler)
    - features/callback_functions.md (BS3)
    - features/ensemble.md (SRIW1 — moved to StochasticDiffEq)
    - features/linear_nonlinear.md (TRBDF2 / KrylovJL_GMRES)
    - features/verbosity.md (Rodas5, ImplicitEuler)
    - extras/timestepping.md (EM)
    - solvers/nonautonomous_linear_ode.md (LinearExponential, MagnusGL6,
      LieRK4, MagnusAdapt4)
- Adds a "v8 sublib mapping" admonition / table to every solver index
  page so that the algorithm tables make their host package explicit:
    - solvers/ode_solve.md (full sublib table)
    - solvers/sde_solve.md (StochasticDiffEq)
    - solvers/dde_solve.md (DelayDiffEq)
    - solvers/bvp_solve.md (BoundaryValueDiffEq sublibs)
    - solvers/dae_solve.md (BDF / Rosenbrock / SDIRK / FIRK sublibs)
    - solvers/discrete_solve.md (FunctionMap → OrdinaryDiffEqFunctionMap)
    - solvers/dynamical_solve.md (RKN / SymplecticRK)
    - solvers/split_ode_solve.md (BDF / IMEXMultistep / SDIRK / ExponentialRK)
    - solvers/nonautonomous_linear_ode.md (Linear)
    - solvers/sdae_solve.md, solvers/rode_solve.md (StochasticDiffEq)
- Adds an explicit "which package supplies each solver" note to
  getting_started.md so the recommendation list (BS3, Rodas4, Rodas5,
  KenCarp4, TRBDF2, RadauIIA5, QNDF) tells the reader where to find
  each one.

The migration page (docs/src/migration/ordinarydiffeq_v7.md) already
documents the umbrella scope reduction; this commit makes every other
docs page consistent with that scope.

See the OrdinaryDiffEq v7 NEWS entry — SciML/OrdinaryDiffEq.jl#3579 —
for the full v7 changelog.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
@ChrisRackauckas
Trim bloated provenance comments in audit code blocks
6178fbe 
Multi-line `# Solver imports — X lives in the Y sublib...` block
comments inside @example blocks were noisy. Keeps the short trailing
`# Solver1, Solver2` tags on each import line; drops the multi-paragraph
prose explanations that belong (and already exist) in the migration
guide and the surrounding markdown narrative.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
@ChrisRackauckas
Annotate every solver in solver-index pages with its host sublib
aef1d81 
Each solver listed in solvers/*.md now carries a `(from `Sublib`)` tag
so users on DifferentialEquations.jl v8 / OrdinaryDiffEq v7 can see at
a glance which package they need to add to their environment for any
given algorithm. Per maintainer request: this applies to every solver,
ODE and SDE included.

Style A (italic-parenthetical after the inline-code name) was applied
uniformly across:

  - ode_solve.md (266 entries)
  - sde_solve.md (64)
  - bvp_solve.md (40)
  - dae_solve.md (47)
  - dynamical_solve.md (35)
  - split_ode_solve.md (20)
  - nonautonomous_linear_ode.md (18)
  - sdae_solve.md (8)
  - discrete_solve.md (2)
  - steady_state_solve.md (2)
  - rode_solve.md (1)

Total: 503 inline annotations. Mappings were built by parsing
`export` statements in every `lib/<Sublib>/src/<Sublib>.jl` of the
OrdinaryDiffEq.jl monorepo (which now also hosts StochasticDiffEq,
DelayDiffEq, ImplicitDiscreteSolve), the BoundaryValueDiffEq.jl
monorepo, and adding manual entries for non-monorepo packages
(Sundials, ODEInterfaceDiffEq, LSODA, ODE, SimpleDiffEq,
GeometricIntegratorsDiffEq, BridgeDiffEq, TaylorIntegration, QuDiffEq,
ProbNumDiffEq, IRKGaussLegendre, SimpleBoundaryValueDiffEq,
SteadyStateDiffEq, DASKR, DASSL).

Translation tables (e.g. `ode23 --> BS3()` rows on ode_solve.md) are
intentionally left un-annotated since the left-hand identifier is a
foreign tool name, not a Julia solver. The dde_solve.md and
sdde_solve.md pages have no inline solver bullets — they rely on
`MethodOfSteps(<inner>)` wrappers — so those pages keep only the v8
admonition added in the prior commit.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
@ChrisRackauckas
Fix low_dep.md broken-then-fixed pedagogy under v8
943aa17 
The "show the broken DE.X form first, then fix it" arc doesn't survive
the v8 reexport reduction — `DE.ProbIntsUncertainty` no longer resolves
at all under v8 (DifferentialEquations no longer re-exports
DiffEqCallbacks). The earlier audit left an apologetic comment around
the broken example explaining why it doesn't work; better to delete
the broken example outright and demonstrate the working v8 form
directly. `@which` is still demonstrated, just on a working call.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
@ChrisRackauckas
Use module-qualified solver names + per-page package tables
8706a33 
Replaces the `*(from `<Sublib>`)*` annotations with module-qualified
solver names (e.g. `BoundaryValueDiffEqMIRK.MIRK6`) so the package
each solver lives in is part of the syntax users copy-paste, not a
trailing tag they have to read separately. Adds a `## Packages`
section at the top of every solver-index page listing the relevant
packages with one-sentence explainers, so users can scan once and
know what to add to their environment.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
@ChrisRackauckas
Module-qualify the go-to solver recommendations in getting_started
d51beb4 
Same module-qualified style as the solver-index pages — `Tsit5()` →
`OrdinaryDiffEqTsit5.Tsit5()`, etc. — so the recommendation list itself
tells readers which package to add. The `!!! note` block immediately
below the list still summarizes the v8 default-vs-sublib split.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
@ChrisRackauckas
Add "good for" use-case hooks to Packages tables
5966177 
Each solver-index page's `## Packages` summary now has three columns -
Package / Methods / Good for - so a user can scan the table once and
pick the right package for their problem class without having to read
the full algorithm-by-algorithm list. The "Good for" cells are short
practical hooks (<= 80 chars) covering the use case, problem stiffness,
and any precision / memory / structure niche each package serves.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
ChrisRackauckas
ChrisRackauckas reviewed Apr 28, 2026
View reviewed changes
Comment thread docs/src/solvers/bvp_solve.md Outdated
ChrisRackauckas
ChrisRackauckas reviewed Apr 28, 2026
View reviewed changes
Comment thread docs/src/solvers/dae_solve.md Outdated
ChrisRackauckas
ChrisRackauckas reviewed Apr 28, 2026
View reviewed changes
Comment thread docs/src/solvers/ode_solve.md Outdated
@ChrisRackauckas
Apply suggestions from code review
6653bfa 
Co-authored-by: Christopher Rackauckas <accounts@chrisrackauckas.com>
@ChrisRackauckas ChrisRackauckas merged commit b867b3a into SciML:master Apr 28, 2026
1 of 3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ChrisRackauckas ChrisRackauckas ChrisRackauckas left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@ChrisRackauckas-Claude @ChrisRackauckas @claude