Merge branch 'master' into aec/integrating-callback-performance-optim…

…ization

.JuliaFormatter.toml

@@ -1 +1,2 @@
-style = "sciml"
+style = "sciml"
+format_markdown = true

LICENSE.md

@@ -19,4 +19,3 @@ The DiffEqCallbacks.jl package is licensed under the MIT "Expat" License:
 > LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 > OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 > SOFTWARE.
-> 

Project.toml

@@ -1,12 +1,11 @@
 name = "DiffEqCallbacks"
 uuid = "459566f4-90b8-5000-8ac3-15dfb0a30def"
 authors = ["Chris Rackauckas <[email protected]>"]
-version = "2.26.1"
+version = "2.27.0"
 
 [deps]
 DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
 DiffEqBase = "2b5f629d-d688-5b77-993f-72d75c75574e"
-OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
@@ -17,26 +16,34 @@ RecursiveArrayTools = "731186ca-8d62-57ce-b412-fbd966d074cd"
 SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
 StaticArraysCore = "1e83bf80-4336-4d27-bf5d-d5a4f845583c"
 
+[weakdeps]
+OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
+Sundials = "c3572dad-4567-51f8-b174-8c6c989267f4"
+
 [compat]
 DataStructures = "0.18"
-DiffEqBase = "6.11"
+DiffEqBase = "6.53.3"
 ForwardDiff = "0.10"
 NLsolve = "4.2"
 OrdinaryDiffEq = "6.14"
 Parameters = "0.12"
 RecipesBase = "0.7, 0.8, 1.0"
 RecursiveArrayTools = "2"
 SciMLBase = "1.48.1"
+Sundials = "4.19.2"
 StaticArraysCore = "1.4"
 julia = "1.6"
 
 [extras]
 ODEProblemLibrary = "fdc4e326-1af4-4b90-96e7-779fcce2daa5"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
+QuadGK = "1fd47b50-473d-5c70-9696-f719f8f3bcdc"
 SciMLSensitivity = "1ed8b502-d754-442c-8d5d-10ac956f44a1"
+Sundials = "c3572dad-4567-51f8-b174-8c6c989267f4"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 Tracker = "9f7883ad-71c0-57eb-9f7f-b5c9e6d3789c"
+Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
 
 [targets]
-test = ["OrdinaryDiffEq", "ODEProblemLibrary", "Test", "SciMLSensitivity", "StaticArrays", "Tracker"]
+test = ["OrdinaryDiffEq", "ODEProblemLibrary", "Test", "QuadGK", "SciMLSensitivity", "StaticArrays", "Tracker", "Zygote"]

README.md

@@ -6,7 +6,7 @@
 [![codecov](https://codecov.io/gh/SciML/DiffEqCallbacks.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/SciML/DiffEqCallbacks.jl)
 [![Build Status](https://github.com/SciML/DiffEqCallbacks.jl/workflows/CI/badge.svg)](https://github.com/SciML/DiffEqCallbacks.jl/actions?query=workflow%3ACI)
 
-[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
+[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor%27s%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
 [![SciML Code Style](https://img.shields.io/static/v1?label=code%20style&message=SciML&color=9558b2&labelColor=389826)](https://github.com/SciML/SciMLStyle)
 
 [DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/) has an expressive callback system
@@ -27,20 +27,20 @@ Here we solve the harmonic oscillator:
 
 ```julia
 u0 = ones(2)
-function f(du,u,p,t)
-  du[1] = u[2]
-  du[2] = -u[1]
+function f(du, u, p, t)
+    du[1] = u[2]
+    du[2] = -u[1]
 end
-prob = ODEProblem(f,u0,(0.0,100.0))
+prob = ODEProblem(f, u0, (0.0, 100.0))
 ```
 
 However, this problem is supposed to conserve energy, and thus we define our manifold
 to conserve the sum of squares:
 
 ```julia
-function g(resid,u,p,t)
-  resid[1] = u[2]^2 + u[1]^2 - 2
-  resid[2] = 0
+function g(resid, u, p, t)
+    resid[1] = u[2]^2 + u[1]^2 - 2
+    resid[2] = 0
 end
 ```
 
@@ -56,7 +56,7 @@ standard saving occurs after the step and before the callback, and thus we set
 save after the projection is applied.
 
 ```julia
-sol = solve(prob,Vern7(),save_everystep=false,callback=cb)
+sol = solve(prob, Vern7(), save_everystep = false, callback = cb)
 @test sol[end][1]^2 + sol[end][2]^2 ≈ 2
 ```
 

docs/make.jl

@@ -10,21 +10,25 @@ using Plots
 include("pages.jl")
 
 makedocs(sitename = "DiffEqCallbacks.jl",
-         authors = "Chris Rackauckas",
-         modules = [DiffEqCallbacks],
-         strict = [
-             :doctest,
-             :linkcheck,
-             :parse_error,
-             :example_block,
-             # Other available options are
-             # :autodocs_block, :cross_references, :docs_block, :eval_block, :example_block, :footnote, :meta_block, :missing_docs, :setup_block
-         ],
-         clean = true, doctest = false,
-         format = Documenter.HTML(analytics = "UA-90474609-3",
-                                  assets = ["assets/favicon.ico"],
-                                  canonical = "https://docs.sciml.ai/DiffEqCallbacks/stable/"),
-         pages = pages)
+    authors = "Chris Rackauckas",
+    modules = [DiffEqCallbacks],
+    linkcheck = true,
+    linkcheck_ignore = [
+        "https://www.sciencedirect.com/science/article/pii/S0096300304009683",
+    ],
+    strict = [
+        :doctest,
+        :linkcheck,
+        :parse_error,
+        :example_block,
+        # Other available options are
+        # :autodocs_block, :cross_references, :docs_block, :eval_block, :example_block, :footnote, :meta_block, :missing_docs, :setup_block
+    ],
+    clean = true, doctest = false,
+    format = Documenter.HTML(analytics = "UA-90474609-3",
+        assets = ["assets/favicon.ico"],
+        canonical = "https://docs.sciml.ai/DiffEqCallbacks/stable/"),
+    pages = pages)
 
 deploydocs(repo = "github.com/SciML/DiffEqCallbacks.jl.git";
-           push_preview = true)
+    push_preview = true)

docs/pages.jl

@@ -3,6 +3,7 @@
 pages = [
     "Home" => "index.md",
     "output_saving.md",
+    "integrating.md",
     "timed_callbacks.md",
     "steady_state.md",
     "step_control.md",

docs/src/index.md

@@ -20,7 +20,7 @@ To use the callbacks provided in this library with  solvers, simply pass the cal
 the solver via the `callback` keyword argument:
 
 ```julia
-sol = solve(prob,alg;callback=cb)
+sol = solve(prob, alg; callback = cb)
 ```
 
 For more information on using callbacks,
@@ -34,66 +34,87 @@ the callback system. Callbacks are defined in the SciML interface at SciMLBase.j
 
 ## Contributing
 
-- Please refer to the
-  [SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md)
-  for guidance on PRs, issues, and other matters relating to contributing to SciML.
-- There are a few community forums:
-    - the #diffeq-bridged channel in the [Julia Slack](https://julialang.org/slack/)
-    - [JuliaDiffEq](https://gitter.im/JuliaDiffEq/Lobby) on Gitter
-    - on the [Julia Discourse forums](https://discourse.julialang.org)
-    - see also [SciML Community page](https://sciml.ai/community/)
+  - Please refer to the
+    [SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md)
+    for guidance on PRs, issues, and other matters relating to contributing to SciML.
+
+  - See the [SciML Style Guide](https://github.com/SciML/SciMLStyle) for common coding practices and other style decisions.
+  - There are a few community forums:
+
+      + The #diffeq-bridged and #sciml-bridged channels in the
+        [Julia Slack](https://julialang.org/slack/)
+      + The #diffeq-bridged and #sciml-bridged channels in the
+        [Julia Zulip](https://julialang.zulipchat.com/#narrow/stream/279055-sciml-bridged)
+      + On the [Julia Discourse forums](https://discourse.julialang.org)
+      + See also [SciML Community page](https://sciml.ai/community/)
 
 ## Reproducibility
+
 ```@raw html
 <details><summary>The documentation of this SciML package was built using these direct dependencies,</summary>
 ```
+
 ```@example
 using Pkg # hide
 Pkg.status() # hide
 ```
+
 ```@raw html
 </details>
 ```
+
 ```@raw html
 <details><summary>and using this machine and Julia version.</summary>
 ```
+
 ```@example
 using InteractiveUtils # hide
 versioninfo() # hide
 ```
+
 ```@raw html
 </details>
 ```
+
 ```@raw html
 <details><summary>A more complete overview of all dependencies and their versions is also provided.</summary>
 ```
+
 ```@example
 using Pkg # hide
-Pkg.status(;mode = PKGMODE_MANIFEST) # hide
+Pkg.status(; mode = PKGMODE_MANIFEST) # hide
 ```
+
 ```@raw html
 </details>
 ```
+
 ```@raw html
 You can also download the 
 <a href="
 ```
+
 ```@eval
 using TOML
-version = TOML.parse(read("../../Project.toml",String))["version"]
-name = TOML.parse(read("../../Project.toml",String))["name"]
-link = "https://github.com/SciML/"*name*".jl/tree/gh-pages/v"*version*"/assets/Manifest.toml"
+version = TOML.parse(read("../../Project.toml", String))["version"]
+name = TOML.parse(read("../../Project.toml", String))["name"]
+link = "https://github.com/SciML/" * name * ".jl/tree/gh-pages/v" * version *
+       "/assets/Manifest.toml"
 ```
+
 ```@raw html
 ">manifest</a> file and the
 <a href="
 ```
+
 ```@eval
 using TOML
-version = TOML.parse(read("../../Project.toml",String))["version"]
-name = TOML.parse(read("../../Project.toml",String))["name"]
-link = "https://github.com/SciML/"*name*".jl/tree/gh-pages/v"*version*"/assets/Project.toml"
+version = TOML.parse(read("../../Project.toml", String))["version"]
+name = TOML.parse(read("../../Project.toml", String))["name"]
+link = "https://github.com/SciML/" * name * ".jl/tree/gh-pages/v" * version *
+       "/assets/Project.toml"
 ```
+
 ```@raw html
 ">project</a> file.
-```
+```

docs/src/integrating.md

@@ -0,0 +1,30 @@
+# Numerical Integration Callbacks
+
+Sometimes one may want to solve an integral simultaniously to the solution of a differential equation. For example,
+assume we want to solve:
+
+```math
+u^\prime = f(u,p,t)
+h = \int_{t_0}^{t_f} g(u,p,t) dt
+```
+
+While one can use the ODE solver's dense solution to call an integration scheme on `sol(t)` after the solve, this can
+be memory intensive. Another way one can solve this problem is by extending the system, i.e.:
+
+```math
+u^\prime = f(u,p,t)
+h^\prime = g(u,p,t)
+```
+
+with $h(t_0) = 0$, so then $h(t_f)$ would be the solution to the integral. However, many differential equation solvers
+scale superlinearly with the equation size and thus this could add an extra cost to the solver process.
+
+The `IntegratingCallback` allows one to be able to solve such definite integrals in a way that is both memory and compute
+efficient. It uses the free local interpolation of a given step in order to approximate the Gaussian quadrature for a given
+step to the order of the numerical differential equation solve, thus achieving accuracy while not requiring the post-solution
+dense interpolation to be saved. By doing this via a callback, this method is able to easily integrate with functionality
+that introduces discontinuities, like other callbacks, in a way that is more accurate than a direct integration post solve.
+
+```@docs
+IntegratingCallback
+```

docs/src/output_saving.md

@@ -9,17 +9,17 @@ FunctionCallingCallback
 
 ### Saving Example
 
-In this example we will solve a matrix equation and at each step save a tuple
+In this example, we will solve a matrix equation and at each step save a tuple
 of values which contains the current trace and the norm of the matrix. We build
 the `SavedValues` cache to use `Float64` for time and `Tuple{Float64,Float64}`
 for the saved values, and then call the solver with the callback.
 
 ```@example saving
 using DiffEqCallbacks, OrdinaryDiffEq, LinearAlgebra
-prob = ODEProblem((du,u,p,t) -> du .= u, rand(4,4), (0.0,1.0))
-saved_values = SavedValues(Float64, Tuple{Float64,Float64})
-cb = SavingCallback((u,t,integrator)->(tr(u),norm(u)), saved_values)
-sol = solve(prob, Tsit5(), callback=cb)
+prob = ODEProblem((du, u, p, t) -> du .= u, rand(4, 4), (0.0, 1.0))
+saved_values = SavedValues(Float64, Tuple{Float64, Float64})
+cb = SavingCallback((u, t, integrator) -> (tr(u), norm(u)), saved_values)
+sol = solve(prob, Tsit5(), callback = cb)
 
 print(saved_values.saveval)
 ```
@@ -29,9 +29,10 @@ Note that the values are retrieved from the cache as `.saveval`, and the time po
 `saveat` act analogously to how they act in the `solve` function.
 
 ```@example saving
-saved_values = SavedValues(Float64, Tuple{Float64,Float64})
-cb = SavingCallback((u,t,integrator)->(tr(u),norm(u)), saved_values, saveat=0.0:0.1:1.0)
-sol = solve(prob, Tsit5(), callback=cb)
+saved_values = SavedValues(Float64, Tuple{Float64, Float64})
+cb = SavingCallback((u, t, integrator) -> (tr(u), norm(u)), saved_values,
+    saveat = 0.0:0.1:1.0)
+sol = solve(prob, Tsit5(), callback = cb)
 print(saved_values.saveval)
 print(saved_values.t)
 ```

docs/src/projection.md

@@ -15,20 +15,20 @@ Here we solve the harmonic oscillator:
 using OrdinaryDiffEq, DiffEqCallbacks, Plots
 
 u0 = ones(2)
-function f(du,u,p,t)
-  du[1] = u[2]
-  du[2] = -u[1]
+function f(du, u, p, t)
+    du[1] = u[2]
+    du[2] = -u[1]
 end
-prob = ODEProblem(f,u0,(0.0,100.0))
+prob = ODEProblem(f, u0, (0.0, 100.0))
 ```
 
 However, this problem is supposed to conserve energy, and thus we define our manifold
 to conserve the sum of squares:
 
 ```@example manifold
-function g(resid,u,p,t)
-  resid[1] = u[2]^2 + u[1]^2 - 2
-  resid[2] = 0
+function g(resid, u, p, t)
+    resid[1] = u[2]^2 + u[1]^2 - 2
+    resid[2] = 0
 end
 ```
 
@@ -44,11 +44,11 @@ standard saving occurs after the step and before the callback, and thus we set
 save after the projection is applied.
 
 ```@example manifold
-sol = solve(prob,Vern7(),save_everystep=false,callback=cb)
+sol = solve(prob, Vern7(), save_everystep = false, callback = cb)
 @show sol[end][1]^2 + sol[end][2]^2 ≈ 2
 ```
 
 ```@example manifold
 using Plots
-plot(sol,idxs=(1,2))
+plot(sol, idxs = (1, 2))
 ```

docs/src/step_control.md

@@ -1,7 +1,7 @@
 # Step Control Callbacks
 
 The following callbacks allow for more refined controls of stepping behavior, allowing for
-preserving geometric properties and precise error defintiions.
+preserving geometric properties and precise error definitions.
 
 ```@docs
 StepsizeLimiter