Developer API

dualarraycreator(u::AbstractArray, size, ::Type{Val{N}})

Construct the automatic-differentiation workspace of a FixedSizeDiffCache.

Interface

This is a versioned developer interface for an AD package or array package, not an end-user customization point. An extension may add a method only when it owns the concrete type of u or the AD scalar stored by the result. Define a method with the following shape:

PreallocationTools.dualarraycreator(
    u::MyArray{T}, size, ::Type{Val{N}}
) where {T, N}

FixedSizeDiffCache calls this hook while constructing its dual workspace. The method must not extend an array representation or scalar type owned by an unrelated package.

Arguments

• u: primal cache prototype. Its representation and axes define the representation expected from the returned workspace.
• size: dimensions of the workspace to allocate. It is a tuple of nonnegative integer dimensions supplied by the constructor.
• N: nonnegative AD chunk size encoded by Val.

Returns

Return a newly allocated AbstractArray with dimensions size, whose element type can represent the extension's AD values with chunk size N. The result must preserve the array representation and axes required by u; it must not alias u. For vector-backed caches, provide a resizable result when callers need to use resize! on the cache.

Failure Behavior

Do not define a method for unsupported representations. A constructor for which no extension provides a workspace fails normally rather than silently creating an incompatible cache.

Example

PreallocationTools.dualarraycreator(
    u::MyAD.Array{T}, size, ::Type{Val{N}}
) where {T, N} = MyAD.Array{MyAD.Dual{T, N}}(undef, size)

forwarddiff_compat_chunk_size(n::Integer)

Return the default AD chunk size for a cache with n primal elements.

Interface

This is a versioned developer interface used by DiffCache and FixedSizeDiffCache when callers omit N. An AD backend that provides the process-wide default may specialize forwarddiff_compat_chunk_size(n::Int). Because the argument is a built-in integer, only one active backend should provide that default; packages that need a different chunk size should pass N explicitly to the constructor.

Arguments

• n: number of primal elements in the requested cache. It is nonnegative.

Returns

Return a nonnegative Int accepted by the backend. The fallback returns 0, which represents no preallocated dual partials.

Failure Behavior

Returning a negative value or a value unsupported by the backend violates the interface and may make cache construction fail.

Example

PreallocationTools.forwarddiff_compat_chunk_size(n::Int) = MyAD.default_chunk_size(n)

chunksize(::Type{T})

Return the AD chunk size encoded by scalar type T.

Interface

This is a versioned developer interface for AD scalar types. An extension may specialize chunksize(::Type{MyADScalar}) only for scalar types it owns. The result lets FixedSizeDiffCache decide whether its dual workspace can be reused for a requested scalar type.

Arguments

• T: a scalar type. T may encode an AD chunk size in its type parameters.

Returns

Return the nonnegative Int chunk size encoded by T. Return 0 when T does not encode chunk-size information; this is the fallback behavior.

Failure Behavior

Do not return a chunk size different from the representation encoded by T. An incorrect result can select a workspace with incompatible capacity.

Example

PreallocationTools.chunksize(::Type{MyAD.Dual{T, N}}) where {T, N} = N

_restructure(normal_cache::AbstractArray, duals)

Give AD workspace storage the representation and shape of normal_cache.

Interface

This is a versioned developer interface for AD or array extensions, not an end-user customization point. An extension may specialize _restructure(normal_cache::MyArray, duals) only when it owns the concrete array representation of normal_cache. The default uses reshape for ordinary arrays and ArrayInterface.restructure for custom representations.

Arguments

• normal_cache: primal workspace whose representation and axes must be preserved.
• duals: AD storage containing at least length(normal_cache) logical values in linear-index order.

Returns

Return an AbstractArray with axes(result) == axes(normal_cache). Its values must correspond to duals in linear-index order, and mutations through the result must update the supplied duals; implementations must not copy the workspace merely to change its representation.

Failure Behavior

Throw a clear error when duals cannot represent the requested axes or when the extension cannot preserve the required array representation.

Example

PreallocationTools._restructure(cache::MyAD.Array, duals) = MyAD.Array(duals, axes(cache))

enlargediffcache!(dc::DiffCache, nelem::Integer)

Resize the dual workspace owned by a DiffCache.

Interface

This is a versioned developer interface for AD extensions. Call it from a specialized get_tmp method only after establishing that the requested AD representation needs additional storage. The extension must own the scalar type used to select that representation. It must not resize dc.dual_du directly, because this helper applies the cache's warning policy.

Arguments

• dc: DiffCache whose dual workspace is vector-backed and resizable.
• nelem: required number of elements in dc.dual_du. It must be at least the current capacity and nonnegative.

Returns

Return the resized dc.dual_du workspace. The returned storage remains owned by dc; callers must use _restructure before exposing it with the primal cache's representation.

Failure Behavior

Calling this hook for a non-resizable dual workspace, or with an invalid capacity, is unsupported and may throw from resize!.

Example

needed = chunksize(ADScalar) * length(cache.du)
needed > length(cache.dual_du) && enlargediffcache!(cache, needed)