bump and document

ChrisRackauckas · ChrisRackauckas · commit 22f206adb77b · 2022-12-02T14:33:03.000+01:00
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "PreallocationTools"
 uuid = "d236fae5-4411-538c-8e31-a6e3d9e00b46"
 authors = ["Chris Rackauckas <accounts@chrisrackauckas.com>"]
-version = "0.4.5"
+version = "0.4.6"
 
 [deps]
 Adapt = "79e6a3ab-5dfb-504d-930d-738a2a938a0e"
diff --git a/README.md b/README.md
@@ -16,62 +16,62 @@ edge cases of automatic differentiation to make it easier for users to get
 high performance even in the cases where code generation may change the
 function that is being called.
 
-## dualcache
+## DiffCache
 
-`dualcache` is a method for generating doubly-preallocated vectors which are
+`DiffCache` is a type for doubly-preallocated vectors which are
 compatible with non-allocating forward-mode automatic differentiation by
 ForwardDiff.jl. Since ForwardDiff uses chunked duals in its forward pass, two
 vector sizes are required in order for the arrays to be properly defined.
-`dualcache` creates a dispatching type to solve this, so that by passing a
+`DiffCache` creates a dispatching type to solve this, so that by passing a
 qualifier it can automatically switch between the required cache. This method
 is fully type-stable and non-dynamic, made for when the highest performance is
 needed.
 
-### Using dualcache
+### Using DiffCache
 
 ```julia
-dualcache(u::AbstractArray, N::Int=ForwardDiff.pickchunksize(length(u)); levels::Int = 1)
-dualcache(u::AbstractArray, N::AbstractArray{<:Int})
+DiffCache(u::AbstractArray, N::Int=ForwardDiff.pickchunksize(length(u)); levels::Int = 1)
+DiffCache(u::AbstractArray, N::AbstractArray{<:Int})
 ```
 
-The `dualcache` function builds a `DualCache` object that stores both a version
+The `DiffCache` function builds a `DiffCache` object that stores both a version
 of the cache for `u` and for the `Dual` version of `u`, allowing use of
 pre-cached vectors with forward-mode automatic differentiation. Note that
-`dualcache`, due to its design, is only compatible with arrays that contain concretely
+`DiffCache`, due to its design, is only compatible with arrays that contain concretely
 typed elements.
 
 To access the caches, one uses:
 
 ```julia
-get_tmp(tmp::DualCache, u)
+get_tmp(tmp::DiffCache, u)
 ```
 
 When `u` has an element subtype of `Dual` numbers, then it returns the `Dual`
 version of the cache. Otherwise it returns the standard cache (for use in the
 calls without automatic differentiation).
 
-In order to preallocate to the right size, the `dualcache` needs to be specified
-to have the correct `N` matching the chunk size of the dual numbers or larger. 
-If the chunk size `N` specified is too large, `get_tmp` will automatically resize 
-when dispatching; this remains type-stable and non-allocating, but comes at the 
+In order to preallocate to the right size, the `DiffCache` needs to be specified
+to have the correct `N` matching the chunk size of the dual numbers or larger.
+If the chunk size `N` specified is too large, `get_tmp` will automatically resize
+when dispatching; this remains type-stable and non-allocating, but comes at the
 expense of additional memory.
 
 In a differential equation, optimization, etc., the default chunk size is computed
-from the state vector `u`, and thus if one creates the `dualcache` via
-`dualcache(u)` it will match the default chunking of the solver libraries.
+from the state vector `u`, and thus if one creates the `DiffCache` via
+`DiffCache(u)` it will match the default chunking of the solver libraries.
 
-`dualcache` is also compatible with nested automatic differentiation calls through
-the `levels` keyword (`N` for each level computed using based on the size of the 
+`DiffCache` is also compatible with nested automatic differentiation calls through
+the `levels` keyword (`N` for each level computed using based on the size of the
 state vector) or by specifying `N` as an array of integers of chunk sizes, which
 enables full control of chunk sizes on all differentation levels.
 
-### dualcache Example 1: Direct Usage
+### DiffCache Example 1: Direct Usage
 
 ```julia
 using ForwardDiff, PreallocationTools
 randmat = rand(5, 3)
 sto = similar(randmat)
-stod = dualcache(sto)
+stod = DiffCache(sto)
 
 function claytonsample!(sto, τ, α; randmat=randmat)
     sto = get_tmp(sto, τ)
@@ -93,13 +93,13 @@ ForwardDiff.jacobian(x -> claytonsample!(stod, x[1], x[2]), [0.3; 0.0])
 ```
 
 In the above, the chunk size of the dual numbers has been selected based on the size
-of `randmat`, resulting in a chunk size of 8 in this case. However, since the derivative 
-is calculated with respect to τ and the Jacobian is calculated with respect to τ and α, 
-specifying the `dualcache` with `stod = dualcache(sto, 1)` or `stod = dualcache(sto, 2)`, 
+of `randmat`, resulting in a chunk size of 8 in this case. However, since the derivative
+is calculated with respect to τ and the Jacobian is calculated with respect to τ and α,
+specifying the `DiffCache` with `stod = DiffCache(sto, 1)` or `stod = DiffCache(sto, 2)`,
 respectively, would have been the most memory efficient way of performing these calculations
 (only really relevant for much larger problems).
 
-### dualcache Example 2: ODEs
+### DiffCache Example 2: ODEs
 
 ```julia
 using LinearAlgebra, OrdinaryDiffEq
@@ -125,7 +125,7 @@ function foo(du, u, (A, tmp), t)
     nothing
 end
 chunk_size = 5
-prob = ODEProblem(foo, ones(5, 5), (0., 1.0), (ones(5,5), dualcache(zeros(5,5), chunk_size)))
+prob = ODEProblem(foo, ones(5, 5), (0., 1.0), (ones(5,5), DiffCache(zeros(5,5), chunk_size)))
 solve(prob, TRBDF2(chunk_size=chunk_size))
 ```
 
@@ -140,10 +140,10 @@ function foo(du, u, (A, tmp), t)
     nothing
 end
 chunk_size = 5
-prob = ODEProblem(foo, ones(5, 5), (0., 1.0), (ones(5,5), dualcache(zeros(5,5))))
+prob = ODEProblem(foo, ones(5, 5), (0., 1.0), (ones(5,5), DiffCache(zeros(5,5))))
 solve(prob, TRBDF2())
 ```
-### dualcache Example 3: Nested AD calls in an optimization problem involving a Hessian matrix
+### DiffCache Example 3: Nested AD calls in an optimization problem involving a Hessian matrix
 
 ```julia
 using LinearAlgebra, OrdinaryDiffEq, PreallocationTools, Optim, Optimization
@@ -157,7 +157,7 @@ function foo(du, u, p, t)
 end
 
 coeffs = -collect(0.1:0.1:0.4)
-cache = dualcache(zeros(2,2), levels = 3)
+cache = DiffCache(zeros(2,2), levels = 3)
 prob = ODEProblem(foo, ones(2, 2), (0., 1.0), (coeffs, cache))
 realsol = solve(prob, TRBDF2(), saveat = 0.0:0.1:10.0, reltol = 1e-8)
 
@@ -170,7 +170,7 @@ function objfun(x, prob, realsol, cache)
         ofv = 1e12
     else
         ofv = sum((sol.-realsol).^2)
-    end    
+    end
     return ofv
 end
 fn(x,p) = objfun(x, p[1], p[2], p[3])
@@ -179,10 +179,29 @@ optprob = OptimizationProblem(optfun, zeros(length(coeffs)), (prob, realsol, cac
 solve(optprob, Newton())
 ```
 Solves an optimization problem for the coefficients, `coeffs`, appearing in a differential equation.
-The optimization is done with [Optim.jl](https://github.com/JuliaNLSolvers/Optim.jl)'s `Newton()` 
-algorithm. Since this involves automatic differentiation in the ODE solver and the calculation 
-of Hessians, three automatic differentiations are nested within each other. Therefore, the `dualcache` 
-is specified with `levels = 3`. 
+The optimization is done with [Optim.jl](https://github.com/JuliaNLSolvers/Optim.jl)'s `Newton()`
+algorithm. Since this involves automatic differentiation in the ODE solver and the calculation
+of Hessians, three automatic differentiations are nested within each other. Therefore, the `DiffCache`
+is specified with `levels = 3`.
+
+## FixedSizeDiffCache
+
+`FixedSizeDiffCache` is a lot like `DiffCache`, but it stores dual numbers in its caches
+instead of a flat array. Because of this, it can avoid a view, making it a little bit
+more performant for generating caches of non-`Array` types. However, it is a lot less
+flexible than `DiffCache`, and is thus only recommended for cases where the chunk size
+is known in advance (for example, ODE solvers) and where `u` is not an `Array`.
+
+The interface is almost exactly the same, except with the constructor:
+
+```julia
+FixedSizeDiffCache(u::AbstractArray, chunk_size = Val{ForwardDiff.pickchunksize(length(u))})
+FixedSizeDiffCache(u::AbstractArray, chunk_size::Integer)
+```
+
+Note that the `FixedSizeDiffCache` can support duals that are of a small chunk size than
+the preallocated ones, but not a larger size. Nested duals are not supported with this
+construct.
 
 ## LazyBufferCache
 
@@ -215,7 +234,7 @@ prob = ODEProblem(foo, ones(5, 5), (0., 1.0), (ones(5,5), LazyBufferCache()))
 solve(prob, TRBDF2())
 ```
 
-## Note About ReverseDiff Support for LazyBuffer 
+## Note About ReverseDiff Support for LazyBuffer
 
 ReverseDiff support is done in SciMLSensitivity.jl to reduce the AD requirements on this package.
 Load that package if ReverseDiff overloads are required.
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -6,62 +6,62 @@ edge cases of automatic differentiation to make it easier for users to get
 high performance even in the cases where code generation may change the
 function that is being called.
 
-## dualcache
+## DiffCache
 
-`dualcache` is a method for generating doubly-preallocated vectors which are
+`DiffCache` is a method for generating doubly-preallocated vectors which are
 compatible with non-allocating forward-mode automatic differentiation by
 ForwardDiff.jl. Since ForwardDiff uses chunked duals in its forward pass, two
 vector sizes are required in order for the arrays to be properly defined.
-`dualcache` creates a dispatching type to solve this, so that by passing a
+`DiffCache` creates a dispatching type to solve this, so that by passing a
 qualifier it can automatically switch between the required cache. This method
 is fully type-stable and non-dynamic, made for when the highest performance is
 needed.
 
-### Using dualcache
+### Using DiffCache
 
 ```julia
-dualcache(u::AbstractArray, N::Int=ForwardDiff.pickchunksize(length(u)); levels::Int = 1)
-dualcache(u::AbstractArray, N::AbstractArray{<:Int})
+DiffCache(u::AbstractArray, N::Int=ForwardDiff.pickchunksize(length(u)); levels::Int = 1)
+DiffCache(u::AbstractArray, N::AbstractArray{<:Int})
 ```
 
-The `dualcache` function builds a `DualCache` object that stores both a version
+The `DiffCache` function builds a `DiffCache` object that stores both a version
 of the cache for `u` and for the `Dual` version of `u`, allowing use of
 pre-cached vectors with forward-mode automatic differentiation. Note that
-`dualcache`, due to its design, is only compatible with arrays that contain concretely
+`DiffCache`, due to its design, is only compatible with arrays that contain concretely
 typed elements.
 
 To access the caches, one uses:
 
 ```julia
-get_tmp(tmp::DualCache, u)
+get_tmp(tmp::DiffCache, u)
 ```
 
 When `u` has an element subtype of `Dual` numbers, then it returns the `Dual`
 version of the cache. Otherwise it returns the standard cache (for use in the
 calls without automatic differentiation).
 
-In order to preallocate to the right size, the `dualcache` needs to be specified
-to have the correct `N` matching the chunk size of the dual numbers or larger. 
-If the chunk size `N` specified is too large, `get_tmp` will automatically resize 
-when dispatching; this remains type-stable and non-allocating, but comes at the 
+In order to preallocate to the right size, the `DiffCache` needs to be specified
+to have the correct `N` matching the chunk size of the dual numbers or larger.
+If the chunk size `N` specified is too large, `get_tmp` will automatically resize
+when dispatching; this remains type-stable and non-allocating, but comes at the
 expense of additional memory.
 
 In a differential equation, optimization, etc., the default chunk size is computed
-from the state vector `u`, and thus if one creates the `dualcache` via
-`dualcache(u)` it will match the default chunking of the solver libraries.
+from the state vector `u`, and thus if one creates the `DiffCache` via
+`DiffCache(u)` it will match the default chunking of the solver libraries.
 
-`dualcache` is also compatible with nested automatic differentiation calls through
-the `levels` keyword (`N` for each level computed using based on the size of the 
+`DiffCache` is also compatible with nested automatic differentiation calls through
+the `levels` keyword (`N` for each level computed using based on the size of the
 state vector) or by specifying `N` as an array of integers of chunk sizes, which
 enables full control of chunk sizes on all differentation levels.
 
-### dualcache Example 1: Direct Usage
+### DiffCache Example 1: Direct Usage
 
 ```julia
 using ForwardDiff, PreallocationTools
 randmat = rand(5, 3)
 sto = similar(randmat)
-stod = dualcache(sto)
+stod = DiffCache(sto)
 
 function claytonsample!(sto, τ, α; randmat=randmat)
     sto = get_tmp(sto, τ)
@@ -83,13 +83,13 @@ ForwardDiff.jacobian(x -> claytonsample!(stod, x[1], x[2]), [0.3; 0.0])
 ```
 
 In the above, the chunk size of the dual numbers has been selected based on the size
-of `randmat`, resulting in a chunk size of 8 in this case. However, since the derivative 
-is calculated with respect to τ and the Jacobian is calculated with respect to τ and α, 
-specifying the `dualcache` with `stod = dualcache(sto, 1)` or `stod = dualcache(sto, 2)`, 
+of `randmat`, resulting in a chunk size of 8 in this case. However, since the derivative
+is calculated with respect to τ and the Jacobian is calculated with respect to τ and α,
+specifying the `DiffCache` with `stod = DiffCache(sto, 1)` or `stod = DiffCache(sto, 2)`,
 respectively, would have been the most memory efficient way of performing these calculations
 (only really relevant for much larger problems).
 
-### dualcache Example 2: ODEs
+### DiffCache Example 2: ODEs
 
 ```julia
 using LinearAlgebra, OrdinaryDiffEq
@@ -115,7 +115,7 @@ function foo(du, u, (A, tmp), t)
     nothing
 end
 chunk_size = 5
-prob = ODEProblem(foo, ones(5, 5), (0., 1.0), (ones(5,5), dualcache(zeros(5,5), chunk_size)))
+prob = ODEProblem(foo, ones(5, 5), (0., 1.0), (ones(5,5), DiffCache(zeros(5,5), chunk_size)))
 solve(prob, TRBDF2(chunk_size=chunk_size))
 ```
 
@@ -130,10 +130,10 @@ function foo(du, u, (A, tmp), t)
     nothing
 end
 chunk_size = 5
-prob = ODEProblem(foo, ones(5, 5), (0., 1.0), (ones(5,5), dualcache(zeros(5,5))))
+prob = ODEProblem(foo, ones(5, 5), (0., 1.0), (ones(5,5), DiffCache(zeros(5,5))))
 solve(prob, TRBDF2())
 ```
-### dualcache Example 3: Nested AD calls in an optimization problem involving a Hessian matrix
+### DiffCache Example 3: Nested AD calls in an optimization problem involving a Hessian matrix
 
 ```julia
 using LinearAlgebra, OrdinaryDiffEq, PreallocationTools, Optim, Optimization
@@ -147,7 +147,7 @@ function foo(du, u, p, t)
 end
 
 coeffs = -collect(0.1:0.1:0.4)
-cache = dualcache(zeros(2,2), levels = 3)
+cache = DiffCache(zeros(2,2), levels = 3)
 prob = ODEProblem(foo, ones(2, 2), (0., 1.0), (coeffs, cache))
 realsol = solve(prob, TRBDF2(), saveat = 0.0:0.1:10.0, reltol = 1e-8)
 
@@ -160,7 +160,7 @@ function objfun(x, prob, realsol, cache)
         ofv = 1e12
     else
         ofv = sum((sol.-realsol).^2)
-    end    
+    end
     return ofv
 end
 fn(x,p) = objfun(x, p[1], p[2], p[3])
@@ -169,10 +169,29 @@ optprob = OptimizationProblem(optfun, zeros(length(coeffs)), (prob, realsol, cac
 solve(optprob, Newton())
 ```
 Solves an optimization problem for the coefficients, `coeffs`, appearing in a differential equation.
-The optimization is done with [Optim.jl](https://github.com/JuliaNLSolvers/Optim.jl)'s `Newton()` 
-algorithm. Since this involves automatic differentiation in the ODE solver and the calculation 
-of Hessians, three automatic differentiations are nested within each other. Therefore, the `dualcache` 
-is specified with `levels = 3`. 
+The optimization is done with [Optim.jl](https://github.com/JuliaNLSolvers/Optim.jl)'s `Newton()`
+algorithm. Since this involves automatic differentiation in the ODE solver and the calculation
+of Hessians, three automatic differentiations are nested within each other. Therefore, the `DiffCache`
+is specified with `levels = 3`.
+
+## FixedSizeDiffCache
+
+`FixedSizeDiffCache` is a lot like `DiffCache`, but it stores dual numbers in its caches
+instead of a flat array. Because of this, it can avoid a view, making it a little bit
+more performant for generating caches of non-`Array` types. However, it is a lot less
+flexible than `DiffCache`, and is thus only recommended for cases where the chunk size
+is known in advance (for example, ODE solvers) and where `u` is not an `Array`.
+
+The interface is almost exactly the same, except with the constructor:
+
+```julia
+FixedSizeDiffCache(u::AbstractArray, chunk_size = Val{ForwardDiff.pickchunksize(length(u))})
+FixedSizeDiffCache(u::AbstractArray, chunk_size::Integer)
+```
+
+Note that the `FixedSizeDiffCache` can support duals that are of a small chunk size than
+the preallocated ones, but not a larger size. Nested duals are not supported with this
+construct.
 
 ## LazyBufferCache
 
@@ -205,7 +224,7 @@ prob = ODEProblem(foo, ones(5, 5), (0., 1.0), (ones(5,5), LazyBufferCache()))
 solve(prob, TRBDF2())
 ```
 
-## Note About ReverseDiff Support for LazyBuffer 
+## Note About ReverseDiff Support for LazyBuffer
 
 ReverseDiff support is done in SciMLSensitivity.jl to reduce the AD requirements on this package.
 Load that package if ReverseDiff overloads are required.
@@ -263,7 +282,7 @@ Pkg.status(;mode = PKGMODE_MANIFEST) # hide
 </details>
 ```
 ```@raw html
-You can also download the 
+You can also download the
 <a href="
 ```
 ```@eval
