FiniteDiff

Overview

This package is for calculating derivatives, gradients, Jacobians, Hessians, etc. numerically. This library is for maximizing speed while giving a usable interface to end users in a way that specializes on array types and sparsity. Included is:

Fully non-allocating mutable forms for fast array support
Fully non-mutating forms for static array support
Coloring vectors for efficient calculation of sparse Jacobians
GPU-compatible, to the extent that you can be with finite differencing.

If you want the fastest versions, create a cache and repeatedly call the differencing functions at different x values (or with different f functions), while if you want a quick and dirty numerical answer, directly call a differencing function.

For analogous sparse differentiation with automatic differentiation, see SparseDiffTools.jl.

FiniteDiff.jl vs FiniteDifferences.jl

FiniteDiff.jl and FiniteDifferences.jl are similar libraries: both calculate approximate derivatives numerically. You should definitely use one or the other, rather than the legacy Calculus.jl finite differencing, or reimplementing it yourself. At some point in the future they might merge, or one might depend on the other. Right now here are the differences:

FiniteDifferences.jl supports basically any type, where as FiniteDiff.jl supports only array-ish types
FiniteDifferences.jl supports higher order approximation
FiniteDiff.jl is carefully optimized to minimize allocations
FiniteDiff.jl supports coloring vectors for efficient calculation of sparse Jacobians

General structure

The general structure of the library is as follows. You can call the differencing functions directly and this will allocate a temporary cache to solve the problem with. To make this non-allocating for repeat calls, you can call the cache construction functions. Each cache construction function has two possibilities: one version where you give it prototype arrays and it generates the cache variables, and one fully non-allocating version where you give it the cache variables. This is summarized as:

Just want a quick derivative? Calculating once? Call the differencing function.
Going to calculate the derivative multiple times but don't have cache arrays around? Use the allocating cache and then pass this into the differencing function (this will allocate only in the one cache construction).
Have cache variables around from your own algorithm and want to re-use them in the differencing functions? Use the non-allocating cache construction and pass the cache to the differencing function.

See the documentation for details on the API.

Function definitions

In all functions, the inplace form is f!(dx,x) while the out of place form is dx = f(x).

Coloring vectors

Coloring vectors are allowed to be supplied to the Jacobian routines, and these are the directional derivatives for constructing the Jacobian. For example, an accurate NxN tridiagonal Jacobian can be computed in just 4 f calls by using colorvec=repeat(1:3,N÷3). For information on automatically generating coloring vectors of sparse matrices, see SparseMatrixColorings.jl and the now deprecated SparseDiffTools.jl.

Contributing

Please refer to the SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages for guidance on PRs, issues, and other matters relating to contributing to SciML.
See the SciML Style Guide for common coding practices and other style decisions.
There are a few community forums:
- The #diffeq-bridged and #sciml-bridged channels in the Julia Slack
- The #diffeq-bridged and #sciml-bridged channels in the Julia Zulip
- On the Julia Discourse forums
- See also SciML Community page

Reproducibility

The documentation of this SciML package was built using these direct dependencies,

Status `~/work/FiniteDiff.jl/FiniteDiff.jl/docs/Project.toml`
  [e30172f5] Documenter v1.16.1
  [6a86dc24] FiniteDiff v2.29.0 `~/work/FiniteDiff.jl/FiniteDiff.jl`

and using this machine and Julia version.

Julia Version 1.12.2
Commit ca9b6662be4 (2025-11-20 16:25 UTC)
Build Info:
  Official https://julialang.org release
Platform Info:
  OS: Linux (x86_64-linux-gnu)
  CPU: 4 × AMD EPYC 7763 64-Core Processor
  WORD_SIZE: 64
  LLVM: libLLVM-18.1.7 (ORCJIT, znver3)
  GC: Built with stock GC
Threads: 1 default, 1 interactive, 1 GC (on 4 virtual cores)

A more complete overview of all dependencies and their versions is also provided.

Status `~/work/FiniteDiff.jl/FiniteDiff.jl/docs/Manifest.toml`
  [a4c015fc] ANSIColoredPrinters v0.0.1
  [1520ce14] AbstractTrees v0.4.5
  [79e6a3ab] Adapt v4.4.0
  [4fba245c] ArrayInterface v7.22.0
  [944b1d66] CodecZlib v0.7.8
  [187b0558] ConstructionBase v1.6.0
  [ffbed154] DocStringExtensions v0.9.5
  [e30172f5] Documenter v1.16.1
  [6a86dc24] FiniteDiff v2.29.0 `~/work/FiniteDiff.jl/FiniteDiff.jl`
  [d7ba0133] Git v1.5.0
  [b5f81e59] IOCapture v1.0.0
  [692b3bcd] JLLWrappers v1.7.1
  [682c06a0] JSON v1.3.0
  [0e77f7df] LazilyInitializedFields v1.3.0
  [1914dd2f] MacroTools v0.5.16
  [d0879d2d] MarkdownAST v0.1.2
  [69de0a69] Parsers v2.8.3
  [aea7be01] PrecompileTools v1.3.3
  [21216c6a] Preferences v1.5.0
  [2792f1a3] RegistryInstances v0.1.0
  [ae029012] Requires v1.3.1
  [efcf1570] Setfield v1.1.2
  [1e83bf80] StaticArraysCore v1.4.4
  [ec057cc2] StructUtils v2.6.0
  [3bb67fe8] TranscodingStreams v0.11.3
  [2e619515] Expat_jll v2.7.3+0
  [020c3dae] Git_LFS_jll v3.7.0+0
  [f8c6e375] Git_jll v2.51.3+0
  [94ce4f54] Libiconv_jll v1.18.0+0
  [9bd350c2] OpenSSH_jll v10.2.1+0
  [0dad84c5] ArgTools v1.1.2
  [56f22d72] Artifacts v1.11.0
  [2a0f44e3] Base64 v1.11.0
  [ade2ca70] Dates v1.11.0
  [f43a241f] Downloads v1.7.0
  [7b1f6079] FileWatching v1.11.0
  [9fa8497b] Future v1.11.0
  [b77e0a4c] InteractiveUtils v1.11.0
  [ac6e5ff7] JuliaSyntaxHighlighting v1.12.0
  [b27032c2] LibCURL v0.6.4
  [76f85450] LibGit2 v1.11.0
  [8f399da3] Libdl v1.11.0
  [37e2e46d] LinearAlgebra v1.12.0
  [56ddb016] Logging v1.11.0
  [d6f4376e] Markdown v1.11.0
  [ca575930] NetworkOptions v1.3.0
  [44cfe95a] Pkg v1.12.0
  [de0858da] Printf v1.11.0
  [3fa0cd96] REPL v1.11.0
  [9a3f8284] Random v1.11.0
  [ea8e919c] SHA v0.7.0
  [9e88b42a] Serialization v1.11.0
  [6462fe0b] Sockets v1.11.0
  [f489334b] StyledStrings v1.11.0
  [fa267f1f] TOML v1.0.3
  [a4e569a6] Tar v1.10.0
  [8dfed614] Test v1.11.0
  [cf7118a7] UUIDs v1.11.0
  [4ec0a83e] Unicode v1.11.0
  [e66e0078] CompilerSupportLibraries_jll v1.3.0+1
  [deac9b47] LibCURL_jll v8.15.0+0
  [e37daf67] LibGit2_jll v1.9.0+0
  [29816b5a] LibSSH2_jll v1.11.3+1
  [14a3606d] MozillaCACerts_jll v2025.5.20
  [4536629a] OpenBLAS_jll v0.3.29+0
  [458c3c95] OpenSSL_jll v3.5.4+0
  [efcefdf7] PCRE2_jll v10.44.0+1
  [83775a58] Zlib_jll v1.3.1+2
  [8e850b90] libblastrampoline_jll v5.15.0+0
  [8e850ede] nghttp2_jll v1.64.0+1
  [3f19e933] p7zip_jll v17.7.0+0

You can also download the manifest file and the project file.