Migrate showcase docs to v8 sub-package syntax (HOLD: waits on AdvancedHMC OrdinaryDiffEq v7 compat)#338
Merged
ChrisRackauckas merged 6 commits intoMay 12, 2026
Conversation
DifferentialEquations.jl v8 only re-exports SciMLBase + OrdinaryDiffEq, and OrdinaryDiffEq v7 trims its umbrella exports to Tsit5/Vern6-9/ Rosenbrock23/Rodas5P/FBDF only. The remaining `import DifferentialEquations as DE` callsites that touched RK4/ROCK2/etc would silently break the moment the resolver picks OrdinaryDiffEq v7. Migrate every executable showcase to the per-sub-package idiom DiffEqDocs already uses: - import OrdinaryDiffEq as ODE for umbrella ODE algorithms - import OrdinaryDiffEqLowOrderRK for RK4 - import OrdinaryDiffEqStabilizedRK for ROCK2 - import StochasticDiffEq as SDE for SRIW1 (already done in SciML#337) - import SciMLBase for EnsembleProblem/EnsembleThreads/terminate! (these aren't in OrdinaryDiffEq's `using SciMLBase: ...` list) docs/Project.toml pins DifferentialEquations to "8" and OrdinaryDiffEq to "6.111, 7" so the resolver is allowed to pick the trimmed v7 once upstream blockers (currently AdvancedHMC 0.8 capping at v6.111) lift. The two new sub-packages are added with compat "1, 2". Verified locally: a fresh env on the new Project.toml resolves DE 8.0.0 + OrdinaryDiffEq 6.111.0 + SciMLBase 2.155.1, and a smoke test mirroring each migrated import block + first solve call passes. Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Author
|
Status update — AdvancedHMC blocker cleared, next blocker is StochasticDiffEq. Re-resolved on this branch with JuliaRegistries/General#155178 merged (AdvancedHMC v0.8.4, which dropped the Forcing i.e. once Holding this PR until SciML/StochasticDiffEq.jl ships that release, then re-running the resolver will tell us whether anything else surfaces. |
Upstream is now unblocked (AdvancedHMC 0.8.4 dropped the OrdinaryDiffEq umbrella dep, StochasticDiffEq 7.0.0 is registered with the DiffEqBase 7 ecosystem). Resolution now cleanly yields: OrdinaryDiffEq 7.0.0, OrdinaryDiffEqLowOrderRK 2.1.0, OrdinaryDiffEqStabilizedRK 2.1.0, StochasticDiffEq 7.0.0, SciMLBase 3.9.1, DiffEqBase 7.3.0, AdvancedHMC 0.8.4, DifferentialEquations 8.0.0. - Pin OrdinaryDiffEq = "7" and StochasticDiffEq = "7" so the resolver must land on the trimmed v7 stack the migration was designed for. - Revert the prob_func arity in the two showcase EnsembleProblem examples to the 2-arg `(prob, ctx)` form. SciMLBase v3 calls prob_func with `(prob, ctx::EnsembleContext)`; the earlier `(prob, i, repeat)` form (added in SciML#337 against SciMLBase v2.x) now errors as MethodError. The closures don't read i/repeat, so just taking `ctx` (and `ctx.sim_id` / `ctx.repeat` when needed) is forward-compatible. Verified locally on the v7 stack: smoke-test mirroring each migrated import block + first solve call passes, including the EnsembleProblem path. Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Author
|
Status: unblocked. Pushed 0db86cd. StochasticDiffEq v7.0.0 was already registered — I had Verifying against the v7 stack surfaced a second wrinkle: SciMLBase v3 changed the So this PR also reverts the two showcase
Neither callsite reads Ready for CI / review. |
CI on the v7/v8 stack surfaced four more cases that were latent under the old v6 umbrella: - blackhole.md uses ODE.RK4() in eight places. RK4 is no longer in OrdinaryDiffEq v7's umbrella exports; switch to the sub-package OrdinaryDiffEqLowOrderRK.RK4 (already added to Project.toml). - brusselator.md uses ODE.TRBDF2() in five places. Same story — TRBDF2 moved to OrdinaryDiffEqSDIRK. Add OrdinaryDiffEqSDIRK to docs/Project.toml ([deps] + [compat]) and route the callsites to it. - gpu_spde.md plots via sol[end][:, :, k]. SciMLBase v3's ODESolution.getindex is scalar (returns the i-th element of the flattened state, here a Float64), not the full state vector at time index i. The supported way to get the final state is sol.u[end]. - optimization_under_uncertainty.md does `import SciMLBase` for EnsembleProblem / EnsembleThreads / terminate! but SciMLBase was not a direct dep of docs/Project.toml, so Documenter raised `Package SciMLBase not found in current path`. Add it ([deps] + [compat = "3"]). Verified locally on the same pinned v7/v8 env: RK4 / TRBDF2 / ROCK2 load from their sub-packages, `sol.u[end]` returns the (2,2,3) array on a 3D-state problem, and the full smoke test still passes. Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
…emble iter Another round of v3 API drift surfaced in the last CI run: - OptimizationSolution.minimizer was removed in SciMLBase v3 — the solution vector is now in .u. blackhole.md was using .u for res1 but still had .minimizer for res2 in two places; align both to .u. - Plot recipes drop the legacy `vars` keyword in favor of `idxs`. ODESolution recipe still tolerates `vars`, but EnsembleSolution's recipe raises `BoundsError ... at index [1, 2, 1]` because it re-dispatches to a scalar getindex path on the inner solutions. Switch `vars = (1, 3)` → `idxs = (1, 3)` in optimization_under_ uncertainty.md (×9) and `vars = MTK.unknowns(traced_sys)` → `idxs = MTK.unknowns(traced_sys)` in symbolic_analysis.md (×3). - EnsembleSolution iteration semantics in v3 now flatten to scalars, so `for sol in ensemblesol` yields `::Float64`, not `::ODESolution`, and `sol[3, end]` errors as `BoundsError: ... attempt to access Float64 at index [3, 1]`. Iterate `ensemblesol.u` to recover the per-trajectory ODESolutions. No `@test_broken` / tolerance loosening. Local smoke test still passes on the same pinned v7/v8 stack. Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
The Plots recipe for AbstractEnsembleSolution in SciMLBase v3 uses
`trajectories = eachindex(sim)` as its default trajectory iterator,
but `eachindex(::EnsembleSolution)` in v3 returns the 3-D
CartesianIndices over the flattened (state × time × trajectory)
representation. The recipe then does `sim.u[i]` with that 3-D index,
which errors as `BoundsError: ... at index [1, 2, 1]` against the
underlying `Vector{ODESolution}`.
Pass `trajectories = 1:length(ensemblesol.u)` explicitly to all four
EnsembleSolution plot calls in `optimization_under_uncertainty.md` so
the recipe gets a flat trajectory range and skips the buggy default.
Reproduced and verified locally: the default kwarg raises BoundsError,
the explicit form plots cleanly.
This is a workaround for an upstream SciMLBase v3 recipe bug that
should also be fixed upstream (filing follow-up there).
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Author
|
Pushed 9be3f3f. Next round of v3 fallout from the CI run:
Verified locally with the same pinned v7/v8 env: `Plots.plot(esol)` with the recipe default raises `BoundsError`, the explicit-trajectories form plots cleanly. |
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.
Please ignore until reviewed by @ChrisRackauckas.
This is the follow-up to #337 (which only patched the SDE block to unblock the build). The previous fix kept
import DifferentialEquations as DEeverywhere; that pattern still works only as long as Pkg picksOrdinaryDiffEqv6 (which re-exports every algorithm). As soon as the resolver selectsOrdinaryDiffEqv7 — which dramatically trims its umbrella exports to justTsit5,Vern6-9,Rosenbrock23,Rodas5P,FBDF— the docs break forDE.RK4,DE.ROCK2,DE.TRBDF2, etc. This PR migrates the showcase code to the v8-friendly per-sub-package pattern that DiffEqDocs uses.Summary
import DifferentialEquations as DE→import OrdinaryDiffEq as ODEacross every executable showcase that previously used the umbrella alias.RK4→OrdinaryDiffEqLowOrderRK.RK4(docs/src/showcase/ode_types.md)ROCK2→OrdinaryDiffEqStabilizedRK.ROCK2(docs/src/showcase/gpu_spde.md)SciMLBase(and weren'tusing-imported intoOrdinaryDiffEq) are accessed through an explicitimport SciMLBase:EnsembleProblem,EnsembleThreads,terminate!indocs/src/showcase/optimization_under_uncertainty.mddocs/Project.toml:DifferentialEquations = "8"(was"7, 8") andOrdinaryDiffEq = "6.111, 7".OrdinaryDiffEqLowOrderRK = "1, 2"andOrdinaryDiffEqStabilizedRK = "1, 2".Files touched (code, not prose):
docs/src/getting_started/first_simulation.mddocs/src/getting_started/fit_simulation.mddocs/src/showcase/bayesian_neural_ode.mddocs/src/showcase/gpu_spde.mddocs/src/showcase/ode_types.mddocs/src/showcase/optimization_under_uncertainty.mdmissing_physics.md,blackhole.md,massively_parallel_gpu.md,brusselator.md,symbolic_analysis.mdalready usedimport OrdinaryDiffEq as ODEand didn't need migration.Status — hold for upstream
Local verification: a fresh env on the new
docs/Project.tomlresolves to DifferentialEquations 8.0.0, OrdinaryDiffEq 6.111.0, SciMLBase 2.155.1. Averify.jlscript that mirrors each migrated import block + first solve call passes. Full Documenter build was not run end-to-end locally (CI build time on the GPU runner is ~1h40m); the validation here is the import + solve smoke test.The reason this resolves to
OrdinaryDiffEq 6.111rather than the trimmed7.xis AdvancedHMC 0.8 still pinningOrdinaryDiffEqto6.0 - 6.111. So this PR's compat allows the trimmed v7 but the resolver can't pick it until upstream loosens. This PR is intentionally drafted to wait for:OrdinaryDiffEqupper bound to allow v7.Once upstream releases land, CompatHelper / a manual
Pkg.updateshould resolve toOrdinaryDiffEq 7.xand the v8 sub-package style in this PR will be the only thing keeping the build green.Test plan
OrdinaryDiffEq 7.xresolution becomes possible, re-run CI to confirm the trimmed-v7 path also builds.