API

DiffCache(u::AbstractArray, N::Int = forwarddiff_compat_chunk_size(length(u)); levels::Int = 1)DiffCache(u::AbstractArray; N::AbstractArray{<:Int})

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 via ForwardDiff.jl (when available). Supports nested AD via keyword levels or specifying an array of chunk sizes.

The DiffCache also supports sparsity detection via SparseConnectivityTracer.jl.

FixedSizeDiffCache(u::AbstractArray, N = Val{default_cache_size(length(u))})

Builds a FixedSizeDiffCache 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.

b = GeneralLazyBufferCache(f=identity)

A lazily allocated buffer object. Given an array u, b[u] returns a cache object generated by f(u), but the generator is only run the first time (and all subsequent times it reuses the same cache)

Limitation

The main limitation of this method is that its return is not type-inferred, and thus it can be slower than some other preallocation techniques. However, if used correct using things like function barriers, then this is a general technique that is sufficiently fast.

b = LazyBufferCache(f = identity; initializer! = identity)

A lazily allocated buffer object. Given an array u, b[u] returns an array of the same type and size f(size(u)) (defaulting to the same size), which is allocated as needed and then cached within b for subsequent usage.

By default the created buffers are not initialized, but a function initializer! can be supplied which is applied to the buffer when it is created, for instance buf -> fill!(buf, 0.0).

Optionally, the size can be explicitly given at calltime using b[u,s], which will return a cache of size s.

fill!(dc::DiffCache, val)

Fill all allocated buffers in the DiffCache with the given value.

fill!(dc::FixedSizeDiffCache, val)

Fill all allocated buffers in the FixedSizeDiffCache with the given value.

fill!(glbc::GeneralLazyBufferCache, val)

Fill all allocated buffers in the GeneralLazyBufferCache with the given value.

fill!(lbc::LazyBufferCache, val)

Fill all allocated buffers in the LazyBufferCache with the given value.

_restructure(normal_cache::AbstractArray, duals)

Internal function that reshapes a flat array of dual numbers to match the shape of the normal cache array. For standard Array types, uses reshape. For other AbstractArray types, delegates to ArrayInterface.restructure to handle custom array types properly.

get_tmp(dc::FixedSizeDiffCache, u::Union{Number, AbstractArray})

Returns the appropriate cache array from the FixedSizeDiffCache based on the type of u.

If u is a regular array or number, returns the standard cache dc.du. If u contains dual numbers (e.g., from ForwardDiff.jl), returns the dual cache array. The function automatically handles type promotion and resizing of internal caches as needed.

This function enables seamless switching between regular and automatic differentiation computations without manual cache management.