Fix docs build for OrdinaryDiffEq v7 / DifferentialEquations v8 (+ #868 AlgebraicMultigrid bump)#869
Merged
ChrisRackauckas merged 3 commits intoJun 15, 2026
Conversation
OrdinaryDiffEq v7 dropped its blanket @reexport, so `OrdinaryDiffEq.OrdinaryDiffEqXXX` no longer resolves and `make.jl` died with `UndefVarError` at the makedocs `modules` list. Load each OrdinaryDiffEq *and* StochasticDiffEq solver subpackage by bare name and list them directly (mirroring OrdinaryDiffEq.jl's own docs build), rather than relying on the meta-packages to reexport them; add them as deps + compat. Also in this commit: - Bump AlgebraicMultigrid compat to allow v2 (PR SciML#868). v2's SPQR coarse solver fixes the non-SPD preconditioner crash that v1's Pinv/SVD coarse solver hits. - Add LinearSolve as a docs dependency (used by advanced_ode_example.md, previously only available transitively). - Bring the OrdinaryDiffEqCore controller API symbols into Main so the unqualified @ref links in the copied controllers.md resolve. - Drop OrdinaryDiffEq's contributor-internal devtools pages from the user docs: their @eval blocks read paths relative to OrdinaryDiffEq's own build layout and cannot build when embedded in DiffEqDocs. - Guard the StochasticDiffEq API nav section, which is empty now that StochasticDiffEq ships no docs/ directory in the v7 monorepo. Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com> Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ArrayTools v4 With OrdinaryDiffEq v7 pinned, the resolver takes DifferentialEquations v8, which now only `@reexport`s SciMLBase + OrdinaryDiffEq (documented in index.md/getting_started.md). Executed @example blocks that reached for symbols no longer reexported through `DE.` therefore errored. Source each from the package it now lives in: - ensemble.md: `DE.SRIW1` -> `SDE.SRIW1` (StochasticDiffEq) - dde_example.md: `DE.RK4` -> `ODELow.RK4` (OrdinaryDiffEqLowOrderRK) - callback_functions.md, spiking_neural_systems.md: `DE.PresetTimeCallback` -> `CB.PresetTimeCallback` (DiffEqCallbacks) - callback_functions.md: `DE.resize!` -> `resize!` (Base, extended for integrators) Also: - advanced_ode_example.md: preconditioner `precs` functions returned `(Pl, nothing)`, but Krylov.jl now calls `ldiv!` on the right preconditioner; return `(Pl, I)` so the identity right-preconditioner has an `ldiv!` method. (LinearSolve `import` was already used here; LinearSolve is added as a docs dep in the previous commit.) - faq.md: `solve(...)[end]` returned a scalar under RecursiveArrayTools v4 (AbstractArray indexing), breaking the downstream ForwardDiff/FiniteDiff jacobian blocks; use `.u[end]` to get the final state vector. Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com> Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The Spell Check (typos) job has been failing on master and every PR. Fix the two real typos and allowlist the proper noun so the check passes: - classical_physics.md: ContiunousCallback -> ContinuousCallback - bvp_solve.md: prblem -> problem - .typos.toml: allowlist `Lamba` (the surname in the Lamba & Rackauckas methods LambaEM / LambaEulerHeun; typos mis-flags it as "Lambda") Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com> Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ChrisRackauckas-Claude
pushed a commit
to ChrisRackauckas-Claude/DiffEqDocs.jl
that referenced
this pull request
Jun 16, 2026
…iffEq)
The Documentation build failed in env-setup on a stale ~/.julia/dev/StochasticDiffEq
checkout:
ERROR: empty intersection between StochasticDiffEq@6.100.0 and project compatibility 7
[13] top-level scope @ docs/make.jl:31
The real issue is that `make.jl` `Pkg.develop`s StochasticDiffEq at all. As of v7,
StochasticDiffEq is a subpackage of the OrdinaryDiffEq.jl monorepo
(`repo = OrdinaryDiffEq.jl`, `subdir = lib/StochasticDiffEq`), so:
- `Pkg.develop("StochasticDiffEq")` clones the *same* monorepo as
`Pkg.develop("OrdinaryDiffEq")` — redundant.
- `lib/StochasticDiffEq` ships no `docs/`, and the monorepo's root `docs/` is
ODE-only, so the StochasticDiffEq doc-copy in make.jl finds nothing and the
"StochasticDiffEq.jl API" nav section is already dropped (added in SciML#869).
- The stale `6.100.0` was a leftover checkout of the old, now-frozen separate
`SciML/StochasticDiffEq.jl` repo.
So StochasticDiffEq is just resolved from the registry like every other solver
package (it is still `using`-loaded and listed in `modules`; its non-API docs live
directly in DiffEqDocs). Dropping the develop removes the redundant clone and the
entire stale-checkout failure mode — no env-setup re-clone dance needed.
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ChrisRackauckas-Claude
pushed a commit
to ChrisRackauckas-Claude/DiffEqDocs.jl
that referenced
this pull request
Jun 16, 2026
Drop the `Pkg.develop` of OrdinaryDiffEq and StochasticDiffEq in the docs build
(and the env-setup re-clone dance), resolving them — and all the solver
subpackages — from the registry at their released versions instead of master.
Why:
- StochasticDiffEq is a subpackage of the OrdinaryDiffEq.jl monorepo as of v7
(registry `repo = OrdinaryDiffEq.jl`, `subdir = lib/StochasticDiffEq`), so
`Pkg.develop("StochasticDiffEq")` re-cloned the same monorepo and the stale
leftover checkout of the old `SciML/StochasticDiffEq.jl` repo (6.100.0) broke
resolution against the docs `[compat] = "7"`:
ERROR: empty intersection between StochasticDiffEq@6.100.0 and compat 7
- `Pkg.develop`ing the monorepo master also risks version skew: the dev'd
master meta-package's subpackage [compat] must be satisfiable by the
*registered* subpackages (sources don't propagate to the docs project), which
breaks whenever master races ahead of the registry.
- The released packages already ship their `docs/` (OrdinaryDiffEq 7.0.0's
tarball includes `docs/` with pages.jl + src + common_*_steps.jl), so the API
docs can be copied from the installed stable packages with no dev checkout.
Net effect: the stable docs reflect released versions, the stale-checkout failure
mode and the monorepo skew are both gone, and env-setup is just instantiate.
(StochasticDiffEq's registered tarball does not yet ship `docs/` — its docs/ needs
to be migrated into lib/StochasticDiffEq in the monorepo; until then the
"StochasticDiffEq.jl API" section stays dropped, as added in SciML#869.)
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ChrisRackauckas
added a commit
that referenced
this pull request
Jun 16, 2026
…fix) (#872) * docs: build against released (registry) OrdinaryDiffEq/StochasticDiffEq Drop the `Pkg.develop` of OrdinaryDiffEq and StochasticDiffEq in the docs build (and the env-setup re-clone dance), resolving them — and all the solver subpackages — from the registry at their released versions instead of master. Why: - StochasticDiffEq is a subpackage of the OrdinaryDiffEq.jl monorepo as of v7 (registry `repo = OrdinaryDiffEq.jl`, `subdir = lib/StochasticDiffEq`), so `Pkg.develop("StochasticDiffEq")` re-cloned the same monorepo and the stale leftover checkout of the old `SciML/StochasticDiffEq.jl` repo (6.100.0) broke resolution against the docs `[compat] = "7"`: ERROR: empty intersection between StochasticDiffEq@6.100.0 and compat 7 - `Pkg.develop`ing the monorepo master also risks version skew: the dev'd master meta-package's subpackage [compat] must be satisfiable by the *registered* subpackages (sources don't propagate to the docs project), which breaks whenever master races ahead of the registry. - The released packages already ship their `docs/` (OrdinaryDiffEq 7.0.0's tarball includes `docs/` with pages.jl + src + common_*_steps.jl), so the API docs can be copied from the installed stable packages with no dev checkout. Net effect: the stable docs reflect released versions, the stale-checkout failure mode and the monorepo skew are both gone, and env-setup is just instantiate. (StochasticDiffEq's registered tarball does not yet ship `docs/` — its docs/ needs to be migrated into lib/StochasticDiffEq in the monorepo; until then the "StochasticDiffEq.jl API" section stays dropped, as added in #869.) Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com> Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: source EnsembleProblem from SciMLBase in the low_dep example Building against the stable release (previous commit) surfaced that OrdinaryDiffEq 7.0.0 does not re-export `EnsembleProblem` (master does), so the low-dependency example's `ODE.EnsembleProblem` was an `UndefVarError`. Source it from SciMLBase, which defines it — consistent with this page's own point that "you will always need SciMLBase.jl, since it defines all of the fundamental types." This is the only docs `@example` affected: across all of docs/src the only OrdinaryDiffEq-exported-on-master-but-not-7.0.0 symbol used via the alias is `EnsembleProblem`, here. Verified locally on the released stack (OrdinaryDiffEq 7.0.0 + OrdinaryDiffEqLowOrderRK + DiffEqCallbacks + SciMLBase): the example's ensemble solve runs successfully. Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com> Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: ChrisRackauckas-Claude <accounts@chrisrackauckas.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Note
Draft — please ignore until reviewed by @ChrisRackauckas.
What was stopping the build
The Documentation build was failing at
docs/make.jlwith:OrdinaryDiffEq v7 became a monorepo and dropped its blanket
@reexport, so theOrdinaryDiffEq.OrdinaryDiffEqXXXaccess pattern used throughout themakedocsmoduleslist no longer resolves.Fixing that exposed a second wall: with OrdinaryDiffEq v7 pinned, the resolver takes DifferentialEquations v8, which now only
@reexports SciMLBase + OrdinaryDiffEq (as already documented inindex.md/getting_started.md). Several executed@exampleblocks reached for symbols no longer reexported throughDE..Changes
Module wiring (commit 1):
modules(mirrors OrdinaryDiffEq.jl's own docs), instead of relying on the meta-packages to reexport — the exact fragility v7 just demonstrated. Added as deps + compat.AlgebraicMultigridcompat to allow v2 (Update AlgebraicMultigrid requirement from 0.5, 0.6, 1 to 0.5, 0.6, 1, 2.0 in /docs in the all-julia-packages group across 1 directory #868). AMG v2's SPQR coarse solver fixes the non-SPD preconditioner crash v1's Pinv/SVD hits.LinearSolveas a docs dep (used byadvanced_ode_example.md, previously only transitive →import LinearSolvefailed).OrdinaryDiffEqCorecontroller symbols intoMainso the copiedcontrollers.md@refs resolve.devtoolspages (their@evalblocks read paths relative to OrdinaryDiffEq's own build layout).docs/dir in the v7 monorepo).Executed examples (commit 2) — source each symbol from where it now lives:
ensemble.md:DE.SRIW1→SDE.SRIW1dde_example.md:DE.RK4→ODELow.RK4callback_functions.md,spiking_neural_systems.md:DE.PresetTimeCallback→CB.PresetTimeCallbackcallback_functions.md:DE.resize!→resize!advanced_ode_example.md: preconditionerprecsreturn(Pl, nothing)→(Pl, I)(Krylov.jl nowldiv!s the right preconditioner)faq.md:solve(...)[end]→.u[end](RecursiveArrayTools v4 indexing change broke the downstream jacobian blocks)Verification
Verified locally (scoped envs): the
moduleslist resolves under OrdinaryDiffEq v7; all six example fixes run;faqindexing; AMG v2 API. A full localmakedocsconfirmed everything green except the AlgebraicMultigrid preconditioner blocks.Those AMG blocks: AMG v2.0.0 was registered 2026-06-12 with
LinearSolve = "2 - 3"(allows 3.85) — so on a current registry the resolver should pick AMG v2.0.0 (SPQR coarse solver, nogesdd!crash) and they pass. My local machine's registry predates that registration and won't refresh, so I forced AMG v1.x locally (→ the Pinv crash). CI's fresh registry is the real test of the AMG blocks.🤖 Generated with Claude Code