API Reference

jacobian_sparsity(f, x, sd::AbstractSparsityDetector)::AbstractMatrix{Bool}
jacobian_sparsity(f!, y, x, sd::AbstractSparsityDetector)::AbstractMatrix{Bool}

Use detector sd to construct a (typically sparse) matrix S describing the pattern of nonzeroes in the Jacobian of f (resp. f!) applied at x (resp. (y, x)).

hessian_sparsity(f, x, sd::AbstractSparsityDetector)::AbstractMatrix{Bool}

Use detector sd to construct a (typically sparse) matrix S describing the pattern of nonzeroes in the Hessian of f applied at x.

TracerSparsityDetector()

Global sparsity detection over the entire input domain using SparseConnectivityTracer.jl. For use with ADTypes.jl's AbstractSparsityDetector interface.

For local sparsity patterns, use TracerLocalSparsityDetector.

Keyword arguments

• gradient_pattern_type::Type: Data structure used for bookkeeping of gradient sparsity patters, used in jacobian_sparsity. Supports concrete subtypes of AbstactSet{<:Integer}. Defaults to BitSet.
• hessian_pattern_type::Type: Data structure used for bookkeeping of Hessian sparsity patters, used in hessian_sparsity. Supports concrete subtypes of AbstractDict{I, AbstractSet{I}} or AbstractSet{Tuple{I, I}}, where I <: Integer. Defaults to Dict{Int64, BitSet}.
• shared_hessian_pattern::Bool: Indicate whether second-order information in Hessian sparsity patterns always shares memory and whether operators are allowed to mutate HessianTracers. Defaults to false.

If support for further pattern representations is needed, please open a feature request: https://github.com/adrhill/SparseConnectivityTracer.jl/issues

Example

julia> using SparseConnectivityTracer

julia> detector = TracerSparsityDetector()
TracerSparsityDetector()

julia> jacobian_sparsity(diff, rand(4), detector)
3×4 SparseArrays.SparseMatrixCSC{Bool, Int64} with 6 stored entries:
 1  1  ⋅  ⋅
 ⋅  1  1  ⋅
 ⋅  ⋅  1  1

julia> f(x) = x[1] + x[2]*x[3] + 1/x[4];

julia> hessian_sparsity(f, rand(4), detector)
4×4 SparseArrays.SparseMatrixCSC{Bool, Int64} with 3 stored entries:
 ⋅  ⋅  ⋅  ⋅
 ⋅  ⋅  1  ⋅
 ⋅  1  ⋅  ⋅
 ⋅  ⋅  ⋅  1

TracerLocalSparsityDetector()

Local sparsity detection using SparseConnectivityTracer.jl. For use with ADTypes.jl's AbstractSparsityDetector interface.

For global sparsity patterns, use TracerSparsityDetector.

Keyword arguments

• gradient_pattern_type::Type: Data structure used for bookkeeping of gradient sparsity patters, used in jacobian_sparsity. Supports concrete subtypes of AbstactSet{<:Integer}. Defaults to BitSet.
• hessian_pattern_type::Type: Data structure used for bookkeeping of Hessian sparsity patters, used in hessian_sparsity. Supports concrete subtypes of AbstractDict{I, AbstractSet{I}} or AbstractSet{Tuple{I, I}}, where I <: Integer. Defaults to Dict{Int64, BitSet}.
• shared_hessian_pattern::Bool: Indicate whether second-order information in Hessian sparsity patterns always shares memory and whether operators are allowed to mutate HessianTracers. Defaults to false.

If support for further pattern representations is needed, please open a feature request: https://github.com/adrhill/SparseConnectivityTracer.jl/issues

Example

Local sparsity patterns are less convervative than global patterns and need to be recomputed for each input x:

julia> using SparseConnectivityTracer

julia> detector = TracerLocalSparsityDetector()
TracerLocalSparsityDetector()

julia> f(x) = x[1] * x[2]; # J_f = [x[2], x[1]]

julia> jacobian_sparsity(f, [1, 0], detector)
1×2 SparseArrays.SparseMatrixCSC{Bool, Int64} with 1 stored entry:
 ⋅  1

julia> jacobian_sparsity(f, [0, 1], detector)
1×2 SparseArrays.SparseMatrixCSC{Bool, Int64} with 1 stored entry:
 1  ⋅

julia> jacobian_sparsity(f, [0, 0], detector)
1×2 SparseArrays.SparseMatrixCSC{Bool, Int64} with 0 stored entries:
 ⋅  ⋅

julia> jacobian_sparsity(f, [1, 1], detector)
1×2 SparseArrays.SparseMatrixCSC{Bool, Int64} with 2 stored entries:
 1  1

jacobian_eltype(x, detector)

Act like eltype(x) but return the matching number type used inside Jacobian sparsity detection.

hessian_eltype(x, detector)

Act like eltype(x) but return the matching number type used inside Hessian sparsity detection.

jacobian_buffer(x, detector)

Allocate a buffer similiar to x with the required tracer type for Jacobian sparsity detection. Thin wrapper around similar that doesn't expose internal types.

hessian_buffer(x, detector)

Allocate a buffer similiar to x with the required tracer type for Hessian sparsity detection. Thin wrapper around similar that doesn't expose internal types.