API

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

Build a cache with storage for both the element type of u and the corresponding forward-mode automatic differentiation dual type.

Use get_tmp(cache, u) to retrieve storage matching the element type of u. The levels keyword or vector-valued N supports nested automatic differentiation. Set warn_on_resize = false to suppress the warning emitted when get_tmp enlarges the dual cache, which can be useful when adaptive algorithms are expected to resize the cache.

DiffCache also supports sparsity detection via SparseConnectivityTracer.jl.

For vector-backed caches, resize!(cache, n) resizes the primal and nested-dual scratch storage while preserving the current dual-storage capacity per primal element, then returns cache. Resizing a cache with a non-vector primal workspace throws ArgumentError.

Arguments

• u: prototype array whose primal storage is cached.
• N: ForwardDiff chunk size, or one chunk size per nested AD level.

Keywords

• levels: number of nested forward-mode AD levels when N is scalar.
• warn_on_resize: whether to emit a one-time warning if dual storage grows.

Fields

• du::T: primal workspace.
• dual_du::S: dual-number workspace, enlarged on demand when necessary.
• typed_du::Dict{DataType, Any}: lazily allocated persistent workspaces for element types that can reuse neither du nor dual_du (e.g. sparsity tracers), keyed by element type.
• warn_on_resize: controls the resize warning policy.

Returns

Return a DiffCache containing the primal and dual workspaces for u.

Examples

cache = DiffCache(zeros(3), 2)
workspace = get_tmp(cache, zeros(3))

FixedSizeDiffCache(
    u::AbstractArray,
    ::Type{Val{N}} = Val{forwarddiff_compat_chunk_size(length(u))}
) where {N}
FixedSizeDiffCache(u::AbstractArray, N::Integer)

Build a fixed-size cache with storage for both the element type of u and the corresponding forward-mode automatic differentiation dual type.

Use get_tmp(cache, u) to retrieve the cache matching the element type of u. FixedSizeDiffCache is most useful when the dual chunk size is known in advance and the cache size does not need to grow during differentiation.

For vector-backed caches, resize!(cache, n) resizes the primal, dual, and nested-dual scratch storage and returns cache. Resizing a cache with a non-vector primal workspace throws ArgumentError; an extension-provided dual workspace must support resize! when callers need this operation.

Arguments

• u: prototype array whose shape and primal element type determine the cache.
• N: ForwardDiff chunk size. Pass Val{N} to encode it in the cache type, or an integer as a convenience constructor.

Fields

• du::T: primal workspace with the shape and storage type of u.
• dual_du::S: workspace for dual-number evaluations.
• typed_du::Dict{DataType, Any}: lazily allocated persistent workspaces for element types that can reuse neither du nor dual_du, keyed by element type.

Returns

Return a FixedSizeDiffCache containing the primal and dual workspaces for u.

Examples

cache = FixedSizeDiffCache(zeros(3), 2)
workspace = get_tmp(cache, zeros(3))

LazyBufferCache(f = identity; initializer! = identity)

A lazily allocated buffer cache. Given an array u, b[u] or get_tmp(b, u) returns an array with a shape chosen from size(u). The cache allocates that buffer on its first matching lookup and returns the same object on later lookups.

Arguments

• f: maps size(u) to the requested buffer dimensions. The default, identity, preserves the input shape.

Keywords

• initializer!: function applied once to each newly allocated buffer. The default leaves the buffer uninitialized; use, for example, buf -> fill!(buf, 0.0) when callers require initialized scratch storage.

Fields

• bufs::Dict{Any, Any}: cache from prototype array type and requested dimensions to a reusable buffer.
• sizemap::F: shape-mapping function supplied as f.
• initializer!::I: initialization function applied to newly allocated buffers.

Returns

Return a LazyBufferCache configured with f and initializer!.

Pass an explicit shape as b[u, s] or get_tmp(b, u, s) to override f for one cache entry. Scratch buffers are shared for matching keys, so callers must overwrite them before reading.

Examples

julia> using PreallocationTools

julia> cache = LazyBufferCache();

julia> size(get_tmp(cache, zeros(2), (3,)))
(3,)

GeneralLazyBufferCache(f = identity)

A lazily allocated cache keyed by the concrete type of its input. Given u, b[u] or get_tmp(b, u) calls f(u) on the first lookup for typeof(u) and returns that same cached object for later lookups of the type.

Arguments

• f: function used to construct a cache object from the first input of each concrete type. The default is identity.

Fields

• bufs::Dict{Any, Any}: map from concrete input type to the reusable object produced by f.
• f::F: cache-construction function.

Returns

Return a GeneralLazyBufferCache configured with f.

Limitation

The result is not type-inferred because the backing map has Any values. Use a function barrier around the lookup when inference matters.

Examples

julia> using PreallocationTools

julia> cache = GeneralLazyBufferCache(T -> Vector{T}(undef, 2));

julia> get_tmp(cache, Float64) === get_tmp(cache, Float64)
true

get_tmp(cache, u)
get_tmp(cache, u, size)

Return cache storage appropriate for u.

For DiffCache and FixedSizeDiffCache, this returns normal storage when u has the cached primal element type and dual-compatible storage when u carries automatic differentiation element types. For LazyBufferCache and GeneralLazyBufferCache, this lazily creates and reuses storage keyed by the type and size requested. For the generic fallback, it returns cache unchanged.

Arguments

• cache: a cache created by this package, or another object handled by the generic fallback.
• u: for DiffCache and FixedSizeDiffCache, a number, array, or scalar type describing the requested element type; for LazyBufferCache, an array prototype; for GeneralLazyBufferCache, the value used to construct storage.
• size: optional lazy-buffer shape; it is accepted only by LazyBufferCache.

Returns

For a cache type, return storage owned by cache and reused by later matching lookups. For the generic fallback, return cache itself. Callers must fully overwrite scratch storage before reading it and must not retain it across calls that can request the same cache entry.

Developer Interface

An AD extension may specialize get_tmp for DiffCache or FixedSizeDiffCache and a scalar type that it owns. The method must return scratch storage with the cache's logical axes and an element representation compatible with the requested scalar type. It must use only the public cache fields and developer hooks documented on the Developer API page, and it must not return storage that aliases the primal workspace unless that representation explicitly permits it.

Examples

julia> using PreallocationTools

julia> cache = DiffCache(zeros(2), 1);

julia> get_tmp(cache, zeros(2)) === cache.du
true

dualcache(args...; warn_on_resize::Bool = true, kwargs...)

Deprecated alias for DiffCache(args...; warn_on_resize, kwargs...). Use DiffCache in new code.

Arguments

• args: positional arguments accepted by DiffCache.

Keywords

• warn_on_resize: forwarded to DiffCache; controls whether an undersized dual workspace emits its one-time resize warning.
• kwargs: additional keywords accepted by DiffCache.

Returns

Return the DiffCache constructed from the forwarded arguments.

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.

reshape(dc::DiffCache, dims...)
reshape(dc::DiffCache, dims)

Return a DiffCache whose normal cache has shape dims.

This is useful for vector-backed caches that need to be resized. Resize the backing DiffCache with resize!, then call reshape again with the updated dimensions. The returned cache shares the normal cache storage with dc; the raw dual cache storage remains vector-backed so get_tmp can reinterpret it for the requested automatic differentiation element type.

resize!(cache::DiffCache, n::Integer)
resize!(cache::FixedSizeDiffCache, n::Integer)

Resize a vector-backed cache to n primal elements.

Arguments

• cache: a DiffCache or FixedSizeDiffCache whose primal workspace is a vector.
• n: nonnegative target length for the primal workspace.

Returns

Return the same cache object. DiffCache preserves its current dual-storage capacity per primal element; FixedSizeDiffCache resizes vector-backed dual storage to n. Both methods resize the nested-dual scratch vector to n.

Developer Interface

An extension that supplies vector-backed dual storage through dualarraycreator must implement resize! for that storage when it expects callers to resize the enclosing cache. It must preserve the storage's element representation after resizing.

Failure Behavior

Resizing is unsupported for caches with non-vector primal storage and throws ArgumentError.