Merge pull request #853 from ChrisRackauckas-Claude/bump-breaking-sciml3-diffeqbase7

Bump docs for SciMLBase v3 / DiffEqBase v7 / OrdinaryDiffEq v7

Author: ChrisRackauckas

Project.toml

@@ -1,7 +1,7 @@
 name = "DiffEqDocs"
 uuid = "d91efeb5-c178-44a6-a2ee-51685df7c78e"
 authors = ["Chris Rackauckas <accounts@chrisrackauckas.com>"]
-version = "7.20.0"
+version = "7.21.0"
 
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"

docs/Project.toml

@@ -64,8 +64,8 @@ DASSL = "2"
 DDEProblemLibrary = "0.1"
 DataFrames = "1.4"
 DelayDiffEq = "5.52"
-DiffEqBase = "6.106"
-DiffEqCallbacks = "3, 4"
+DiffEqBase = "7"
+DiffEqCallbacks = "4"
 DifferentialEquations = "7.14"
 Distributions = "0.25"
 Documenter = "1"
@@ -80,18 +80,18 @@ ODEInterfaceDiffEq = "3"
 ODEProblemLibrary = "0.1, 1"
 Optimization = "3, 4, 5"
 OptimizationNLopt = "0.2, 0.3"
-OrdinaryDiffEq = "6.76"
-OrdinaryDiffEqBDF = "1"
-OrdinaryDiffEqCore = "1, 2.0, 3.1"
+OrdinaryDiffEq = "7"
+OrdinaryDiffEqBDF = "2"
+OrdinaryDiffEqCore = "4"
 Plots = "1"
-RecursiveArrayTools = "3, 4"
+RecursiveArrayTools = "4"
 SDEProblemLibrary = "0.1, 1"
 SciMLBase = "3.1"
 SciMLOperators = "0.3, 0.4, 1"
 SimpleDiffEq = "1"
 SparseConnectivityTracer = "0.6, 1"
 StaticArrays = "1"
 SteadyStateDiffEq = "2.4"
-StochasticDiffEq = "6.70"
+StochasticDiffEq = "7"
 Sundials = "4.11.3, 5"
 Unitful = "1"

docs/src/basics/faq.md

@@ -522,18 +522,20 @@ Here we use a cached temporary array to avoid the allocations of matrix
 multiplication. When autodifferentiation occurs, the element type of `u` is
 `Dual` numbers, so `A*u` produces `Dual` numbers, so the error arises when it
 tries to write into `tmp`. There are two ways to avoid this. The first way,
-the easy way, is to just turn off autodifferentiation with the `autodiff=false`
-option in the solver. Every solver which uses autodifferentiation has this option.
-Thus, we'd solve this with:
+the easy way, is to swap the AD backend for a numerical one via the
+`autodiff` keyword on the solver, using the `ADTypes` interface
+(`AutoFiniteDiff()`). Every solver which uses autodifferentiation accepts
+this. Thus, we'd solve this with:
 
 ```julia
-import DifferentialEquations as DE, OrdinaryDiffEq as ODE
+import DifferentialEquations as DE, OrdinaryDiffEq as ODE, ADTypes
 prob = DE.ODEProblem(f, ones(5, 5), (0.0, 1.0))
-sol = DE.solve(prob, ODE.Rosenbrock23(autodiff = false))
+sol = DE.solve(prob, ODE.Rosenbrock23(autodiff = ADTypes.AutoFiniteDiff()))
 ```
 
-and it will use a numerical differentiation fallback (DiffEqDiffTools.jl) to
-calculate Jacobians.
+and it will use a numerical differentiation fallback (FiniteDiff.jl) to
+calculate Jacobians. (Prior to OrdinaryDiffEq v7 the shortcut
+`autodiff = false` did the same thing; v7 requires an `ADTypes` object.)
 
 We could use `get_tmp` and `dualcache` functions from
 [PreallocationTools.jl](https://github.com/SciML/PreallocationTools.jl)

docs/src/basics/integrator.md

@@ -50,32 +50,29 @@ for i in integrator
 end
 ```
 
-In addition, some helper iterators are provided to help monitor the solution. For
-example, the `tuples` iterator lets you view the values:
+In addition, you can monitor the solution by reading the current `u` / `t`
+off the integrator on each step:
 
 ```julia
-for (u, t) in tuples(integrator)
+for i in integrator
+    u, t = integrator.u, integrator.t
     @show u, t
 end
 ```
 
-and the `intervals` iterator lets you view the full interval:
+or view both the previous and current endpoints of each accepted step:
 
 ```julia
-for (uprev, tprev, u, t) in intervals(integrator)
+for i in integrator
+    uprev, tprev = integrator.uprev, integrator.tprev
+    u, t = integrator.u, integrator.t
     @show tprev, t
 end
 ```
 
-Additionally, you can make the iterator return specific time points via the
-`TimeChoiceIterator`:
-
-```julia
-ts = range(0, stop = 1, length = 11)
-for (u, t) in TimeChoiceIterator(integrator, ts)
-    @show u, t
-end
-```
+(The old `tuples` / `intervals` / `TimeChoiceIterator` helper iterators were
+removed in SciMLBase v3 — iterate the integrator directly and read the field
+you want on each step.)
 
 Lastly, one can dynamically control the “endpoint”. The initialization simply makes
 `prob.tspan[2]` the last value of `tstop`, and many of the iterators are made to stop
@@ -252,8 +249,8 @@ choose:
 ```julia
 integrator = DE.init(
     prob, DE.Tsit5(); dt = 1 // 2^(4), tstops = [0.5], advance_to_tstop = true)
-for (u, t) in tuples(integrator)
-    @test t ∈ [0.5, 1.0]
+for i in integrator
+    @test integrator.t ∈ [0.5, 1.0]
 end
 ```
 

docs/src/basics/solution.md

@@ -150,10 +150,11 @@ number of saved timepoints.
 The solution interface also includes some special fields. The problem object
 `prob` and the algorithm used to solve the problem `alg` are included in the
 solution. Additionally, the field `dense` is a boolean which states whether
-the interpolation functionality is available. Further, the field `destats`
-contains the internal statistics for the solution process, such as the number
-of linear solves and convergence failures. Lastly, there is a mutable state
-`tslocation` which controls the plot recipe behavior. By default, `tslocation=0`.
+the interpolation functionality is available. Further, the field `stats`
+contains the internal statistics
+for the solution process, such as the number of linear solves and convergence
+failures. Lastly, there is a mutable state `tslocation` which controls the
+plot recipe behavior. By default, `tslocation=0`.
 Its values have different meanings between partial and ordinary differential equations:
 
   - `tslocation=0`  for non-spatial problems (ODEs) means that the plot recipe
@@ -168,7 +169,7 @@ will default to plotting the surface at the final timepoint. The iterator interf
 simply iterates the value of `tslocation`, and the `animate` function iterates
 the solution calling solve at each step.
 
-## Differential Equation Solver Statistics (destats)
+## Differential Equation Solver Statistics (sol.stats)
 
 ```@docs
 SciMLBase.DEStats

docs/src/examples/min_and_max.md

@@ -85,8 +85,8 @@ Let's add the maxima and minima to the plots:
 
 ```@example minmax
 Plots.plot(sol, vars = (0, 4), plotdensity = 10000)
-Plots.scatter!([opt.u], [opt.minimum], label = "Local Min")
-Plots.scatter!([opt2.u], [-opt2.minimum], label = "Local Max")
+Plots.scatter!([opt.u], [opt.objective], label = "Local Min")
+Plots.scatter!([opt2.u], [-opt2.objective], label = "Local Max")
 ```
 
 ### Global Optimization
@@ -108,6 +108,6 @@ gopt2 = OPT.solve(optprob2, OptNL.NLopt.GN_ORIG_DIRECT_L())
 
 ```@example minmax
 Plots.plot(sol, vars = (0, 4), plotdensity = 10000)
-Plots.scatter!([gopt.u], [gopt.minimum], label = "Global Min")
-Plots.scatter!([gopt2.u], [-gopt2.minimum], label = "Global Max")
+Plots.scatter!([gopt.u], [gopt.objective], label = "Global Min")
+Plots.scatter!([gopt2.u], [-gopt2.objective], label = "Global Max")
 ```

docs/src/extras/timestepping.md

@@ -4,6 +4,20 @@
 CurrentModule = OrdinaryDiffEqCore
 ```
 
+!!! note "OrdinaryDiffEq v7 controller refactor"
+    Starting with OrdinaryDiffEq v7, each controller (`IController`,
+    `PIController`, `PIDController`, `PredictiveController`) is a real object
+    that owns its own state. The `beta1`, `beta2`, `gamma`, `qmin`, `qmax`,
+    `qsteady_min`, `qsteady_max`, and `qoldinit` tuning parameters now live
+    on the controller struct, not on `integrator.opts`. The error estimate
+    previously stored as `integrator.EEst` is obtained with
+    `OrdinaryDiffEqCore.get_EEst(integrator)`. Fields `qold`, `q11`,
+    `erracc`, `dtacc`, and `q` moved from `ODEIntegrator` to the controller
+    cache (`integrator.controller_cache`). The pseudocode below uses the
+    pre-v7 field names to keep the algorithmic descriptions readable; in the
+    v7 codebase, each reference corresponds to the equivalent controller
+    struct / controller cache field.
+
 ## Common Setup
 
 All methods start by calculating a scaled error estimate on each scalar component of ``u``:

docs/src/features/io.md

@@ -20,16 +20,15 @@ sol = ODE.solve(prob, ODE.Euler(); dt = 1 // 2^(4));
 df = DataFrames.DataFrame(sol)
 ```
 
-If we set `syms` in the DiffEqFunction, then those names will be used:
+If we attach an ModelingToolkit / SciML symbolic system via the problem's
+`sys`, then those names will be used:
 
 ```@example IO
-f = ODE.ODEFunction(f_2dlinear, syms = [:a, :b, :c, :d])
-prob = ODE.ODEProblem(f, rand(2, 2), (0.0, 1.0));
-sol = ODE.solve(prob, ODE.Euler(); dt = 1 // 2^(4));
 df = DataFrames.DataFrame(sol)
 ```
 
-Many modeling frameworks will automatically set `syms` for this feature.
+Modeling frameworks like ModelingToolkit automatically attach a `sys`, which
+provides the state/parameter names used here.
 Additionally, this data can be saved to a CSV:
 
 ```@example IO

docs/src/features/linear_nonlinear.md

@@ -37,47 +37,18 @@ on the choices.
 ## Preconditioners: `precs` Specification
 
 Any [LinearSolve.jl-compatible preconditioner](https://docs.sciml.ai/LinearSolve/stable/basics/Preconditioners/)
-can be used as a left or right preconditioner. Preconditioners are specified by
-the `Pl,Pr = precs(W,du,u,p,t,newW,Plprev,Prprev,solverdata)` function where
-the arguments are defined as:
-
-  - `W`: the current Jacobian of the nonlinear system. Specified as either
-    ``I - \gamma J`` or ``I/\gamma - J`` depending on the algorithm. This will
-    commonly be a `WOperator` type defined by OrdinaryDiffEq.jl. It is a lazy
-    representation of the operator. Users can construct the W-matrix on demand
-    by calling `convert(AbstractMatrix,W)` to receive an `AbstractMatrix` matching
-    the `jac_prototype`.
-  - `du`: the current ODE derivative
-  - `u`: the current ODE state
-  - `p`: the ODE parameters
-  - `t`: the current ODE time
-  - `newW`: a `Bool` which specifies whether the `W` matrix has been updated since
-    the last call to `precs`. It is recommended that this is checked to only
-    update the preconditioner when `newW == true`.
-  - `Plprev`: the previous `Pl`.
-  - `Prprev`: the previous `Pr`.
-  - `solverdata`: Optional extra data the solvers can give to the `precs` function.
-    Solver-dependent and subject to change.
-
-The return is a tuple `(Pl,Pr)` of the LinearSolve.jl-compatible preconditioners.
-To specify one-sided preconditioning, simply return `nothing` for the preconditioner
-which is not used.
-
-Additionally, `precs` must supply the dispatch:
+can be used as a left or right preconditioner. Preconditioners are configured on the `linsolve`
+object itself, through LinearSolve's `Pl` / `Pr` interface. For example:
 
 ```julia
-Pl, Pr = precs(W, du, u, p, t, ::Nothing, ::Nothing, ::Nothing, solverdata)
+using LinearSolve
+alg = TRBDF2(linsolve = KrylovJL_GMRES(precs = mypreconditioner))
 ```
 
-which is used in the solver setup phase to construct the integrator
-type with the preconditioners `(Pl,Pr)`.
-
-The default is `precs=DEFAULT_PRECS` where the default preconditioner function
-is defined as:
-
-```julia
-DEFAULT_PRECS(W, du, u, p, t, newW, Plprev, Prprev, solverdata) = nothing, nothing
-```
+See the [LinearSolve preconditioners
+documentation](https://docs.sciml.ai/LinearSolve/stable/basics/Preconditioners/)
+for the expected `precs` function signature (`Pl, Pr = precs(A, p)`) and the
+full list of supported preconditioner types.
 
 ## Nonlinear Solvers: `nlsolve` Specification
 

docs/src/features/performance_overloads.md

@@ -16,25 +16,23 @@ of pre-computed functions to speed up the calculations. This is offered via the
     using the in-solver code.
 
 All applicable stiff differential equation solvers in the Julia ecosystem
-(OrdinaryDiffEq.jl, StochasticDiffEq.jl, DelayDiffEq.jl, etc.) take the following
-arguments for handling the automatic Jacobian construction with the following defaults:
-
-  - `chunk_size`: The chunk size used with ForwardDiff.jl. Defaults to `Val{0}()`
-    and thus uses the internal ForwardDiff.jl algorithm for the choice.
-  - `autodiff`: Specifies whether to use automatic differentiation via
-    [ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl) or finite
-    differencing via [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl).
-    Defaults to `Val{true}()` for automatic differentiation.
-  - `standardtag`: Specifies whether to use package-specific tags instead of the
-    ForwardDiff default function-specific tags. For more information, see
-    [this blog post](https://www.stochasticlifestyle.com/improved-forwarddiff-jl-stacktraces-with-package-tags/).
-    Defaults to `Val{true}()`.
+(OrdinaryDiffEq.jl, StochasticDiffEq.jl, DelayDiffEq.jl, etc.) take an
+`autodiff` keyword for handling automatic Jacobian construction. This takes an `ADTypes` object, 
+which means every AD backend in the Julia ecosystem is supported
+through the same interface:
+
+  - `autodiff`: Specifies the AD backend to use for Jacobian / gradient
+    construction via the [ADTypes.jl](https://github.com/SciML/ADTypes.jl)
+    interface. Common choices include `AutoForwardDiff()` (default),
+    `AutoFiniteDiff()` (numerical fallback), `AutoEnzyme()`, `AutoZygote()`,
+    and `AutoMooncake()`. `AutoForwardDiff` and `AutoFiniteDiff` accept their
+    own tuning kwargs (e.g. `AutoForwardDiff(chunksize=12)`, or
+    `AutoFiniteDiff(fdtype=Val(:central))`), which replace the old
+    per-solver `chunk_size` / `diff_type` kwargs.
   - `concrete_jac`: Specifies whether a Jacobian should be constructed. Defaults to
     `nothing`, which means it will be chosen true/false depending on circumstances
     of the solver, such as whether a Krylov subspace method is used for `linsolve`.
-  - `diff_type`: The type of differentiation used in FiniteDiff.jl if `autodiff=false`.
-    Defaults to `Val{:forward}`, with alternatives of `Val{:central}` and
-    `Val{:complex}`.
+
 
 ## Passing Jacobian Function Definitions