Jacobians

Functions for computing Jacobian matrices of vector-valued functions.

Function Types

Jacobians support the following function signatures:

Out-of-place: fx = f(x) where both x and fx are vectors
In-place: f!(fx, x) where f! modifies fx in-place

Sparse Jacobians

FiniteDiff.jl provides efficient sparse Jacobian computation using graph coloring:

Pass a colorvec of matrix colors to enable column compression
Provide sparsity as a sparse (e.g. the default SparseMatrixCSC) or structured matrix (Tridiagonal, Banded, etc.)
Supports automatic sparsity pattern detection via ArrayInterfaceCore.jl
Results are automatically decompressed unless sparsity=nothing

Performance Notes

Forward differences: O(n) function evaluations, O(h) accuracy
Central differences: O(2n) function evaluations, O(h²) accuracy
Complex step: O(n) function evaluations, machine precision accuracy
Sparse Jacobians: Use graph coloring to reduce function evaluations significantly

For non-square Jacobians, specify the output vector fx when creating the cache to ensure proper sizing.

Functions

FiniteDiff.finite_difference_jacobian — Function

FiniteDiff.finite_difference_jacobian(
    f,
    x          :: AbstractArray{<:Number},
    fdtype     :: Type{T1} = Val{:forward},
    returntype :: Type{T2} = eltype(x),
    f_in                   = nothing;
    relstep       = default_relstep(fdtype, eltype(x)),
    absstep       = relstep,
    colorvec      = 1:length(x),
    sparsity      = nothing,
    jac_prototype = nothing,
    dir           = true)

Compute the Jacobian matrix of function f at point x using finite differences.

This is the cache-less version that allocates temporary arrays internally. The Jacobian J[i,j] = ∂f[i]/∂x[j] is computed using the specified finite difference method. Supports sparse Jacobians via graph coloring.

Arguments

f: Function to differentiate (vector→vector map)
x::AbstractArray{<:Number}: Point at which to evaluate the Jacobian
fdtype::Type{T1}=Val{:forward}: Finite difference method (:forward, :central, :complex)
returntype::Type{T2}=eltype(x): Element type of the function output
f_in=nothing: Pre-computed f(x) value (if available)

Keyword Arguments

relstep: Relative step size (default: method-dependent optimal value)
absstep=relstep: Absolute step size fallback
colorvec=1:length(x): Column coloring for sparse Jacobians
sparsity=nothing: Sparsity pattern for the Jacobian
jac_prototype=nothing: Prototype matrix defining Jacobian structure
dir=true: Direction for step size (typically ±1)

Returns

Jacobian matrix J where J[i,j] = ∂f[i]/∂x[j]

Examples

f(x) = [x[1]^2 + x[2], x[1] * x[2]]
x = [1.0, 2.0]
J = finite_difference_jacobian(f, x)  # 2×2 matrix

Notes

Forward differences: O(n) function evaluations, O(h) accuracy
Central differences: O(2n) function evaluations, O(h²) accuracy
Complex step: O(n) function evaluations, machine precision accuracy
Sparse Jacobians use graph coloring to reduce function evaluations

source

FiniteDiff.finite_difference_jacobian(
    f,
    x,
    cache::JacobianCache;
    relstep       = default_relstep(fdtype, eltype(x)),
    absstep       = relstep,
    colorvec      = cache.colorvec,
    sparsity      = cache.sparsity,
    jac_prototype = nothing,
    dir           = true)

Cached.

source

FiniteDiff.finite_difference_jacobian! — Function

finite_difference_jacobian!(
    J          :: AbstractMatrix,
    f,
    x          :: AbstractArray{<:Number},
    fdtype     :: Type{T1} = Val{:forward},
    returntype :: Type{T2} = eltype(x),
    f_in       :: Union{T2,Nothing}=nothing;
    relstep  = default_relstep(fdtype, eltype(x)),
    absstep  = relstep,
    colorvec = 1:length(x),
    sparsity = ArrayInterfaceCore.has_sparsestruct(J) ? J : nothing)

Cache-less.

source

FiniteDiff.finite_difference_jacobian!(
    J     :: AbstractMatrix{<:Number},
    f,
    x     :: AbstractArray{<:Number},
    cache :: JacobianCache;
    relstep  = default_relstep(fdtype, eltype(x)),
    absstep  = relstep,
    colorvec = cache.colorvec,
    sparsity = cache.sparsity,
    dir      = true)

Cached.

source

Cache

FiniteDiff.JacobianCache — Type

FiniteDiff.JacobianCache(
    x,
    fdtype     :: Type{T1} = Val{:central},
    returntype :: Type{T2} = eltype(x),
    colorvec = 1:length(x)
    sparsity = nothing)

Allocating Cache Constructor.

This assumes the Jacobian is square.

source

FiniteDiff.JacobianCache(
    x1,
    fx,
    fx1,
    fdtype     :: Type{T1} = Val{:central},
    returntype :: Type{T2} = eltype(fx);
    colorvec = 1:length(x1),
    sparsity = nothing)

Non-Allocating Cache Constructor.

source