# Differentiation API

## Derivatives of `f(x::Real)::Union{Real,AbstractArray}`

`ForwardDiff.derivative`

— Function`ForwardDiff.derivative(f, x::Real)`

Return `df/dx`

evaluated at `x`

, assuming `f`

is called as `f(x)`

.

This method assumes that `isa(f(x), Union{Real,AbstractArray})`

.

`ForwardDiff.derivative(f!, y::AbstractArray, x::Real, cfg::DerivativeConfig = DerivativeConfig(f!, y, x), check=Val{true}())`

Return `df!/dx`

evaluated at `x`

, assuming `f!`

is called as `f!(y, x)`

where the result is stored in `y`

.

Set `check`

to `Val{false}()`

to disable tag checking. This can lead to perturbation confusion, so should be used with care.

`ForwardDiff.derivative!`

— Function`ForwardDiff.derivative!(result::Union{AbstractArray,DiffResult}, f, x::Real)`

Compute `df/dx`

evaluated at `x`

and store the result(s) in `result`

, assuming `f`

is called as `f(x)`

.

This method assumes that `isa(f(x), Union{Real,AbstractArray})`

.

`ForwardDiff.derivative!(result::Union{AbstractArray,DiffResult}, f!, y::AbstractArray, x::Real, cfg::DerivativeConfig = DerivativeConfig(f!, y, x), check=Val{true}())`

Compute `df!/dx`

evaluated at `x`

and store the result(s) in `result`

, assuming `f!`

is called as `f!(y, x)`

where the result is stored in `y`

.

Set `check`

to `Val{false}()`

to disable tag checking. This can lead to perturbation confusion, so should be used with care.

## Gradients of `f(x::AbstractArray)::Real`

`ForwardDiff.gradient`

— Function`ForwardDiff.gradient(f, x::AbstractArray, cfg::GradientConfig = GradientConfig(f, x), check=Val{true}())`

Return `∇f`

evaluated at `x`

, assuming `f`

is called as `f(x)`

. The array `∇f`

has the same shape as `x`

, and its elements are `∇f[j, k, ...] = ∂f/∂x[j, k, ...]`

.

This method assumes that `isa(f(x), Real)`

.

Set `check`

to `Val{false}()`

to disable tag checking. This can lead to perturbation confusion, so should be used with care.

`ForwardDiff.gradient!`

— Function`ForwardDiff.gradient!(result::Union{AbstractArray,DiffResult}, f, x::AbstractArray, cfg::GradientConfig = GradientConfig(f, x), check=Val{true}())`

Compute `∇f`

evaluated at `x`

and store the result(s) in `result`

, assuming `f`

is called as `f(x)`

.

This method assumes that `isa(f(x), Real)`

.

## Jacobians of `f(x::AbstractArray)::AbstractArray`

`ForwardDiff.jacobian`

— Function`ForwardDiff.jacobian(f, x::AbstractArray, cfg::JacobianConfig = JacobianConfig(f, x), check=Val{true}())`

Return `J(f)`

evaluated at `x`

, assuming `f`

is called as `f(x)`

. Multidimensional arrays are flattened in iteration order: the array `J(f)`

has shape `length(f(x)) × length(x)`

, and its elements are `J(f)[j,k] = ∂f(x)[j]/∂x[k]`

. When `x`

is a vector, this means that `jacobian(x->[f(x)], x)`

is the transpose of `gradient(f, x)`

.

This method assumes that `isa(f(x), AbstractArray)`

.

`check`

to `Val{false}()`

to disable tag checking. This can lead to perturbation confusion, so should be used with care.

`ForwardDiff.jacobian(f!, y::AbstractArray, x::AbstractArray, cfg::JacobianConfig = JacobianConfig(f!, y, x), check=Val{true}())`

Return `J(f!)`

evaluated at `x`

, assuming `f!`

is called as `f!(y, x)`

where the result is stored in `y`

.

`check`

to `Val{false}()`

to disable tag checking. This can lead to perturbation confusion, so should be used with care.

`ForwardDiff.jacobian!`

— Function`ForwardDiff.jacobian!(result::Union{AbstractArray,DiffResult}, f, x::AbstractArray, cfg::JacobianConfig = JacobianConfig(f, x), check=Val{true}())`

Compute `J(f)`

evaluated at `x`

and store the result(s) in `result`

, assuming `f`

is called as `f(x)`

.

This method assumes that `isa(f(x), AbstractArray)`

.

`check`

to `Val{false}()`

to disable tag checking. This can lead to perturbation confusion, so should be used with care.

`ForwardDiff.jacobian!(result::Union{AbstractArray,DiffResult}, f!, y::AbstractArray, x::AbstractArray, cfg::JacobianConfig = JacobianConfig(f!, y, x), check=Val{true}())`

Compute `J(f!)`

evaluated at `x`

and store the result(s) in `result`

, assuming `f!`

is called as `f!(y, x)`

where the result is stored in `y`

.

This method assumes that `isa(f(x), AbstractArray)`

.

`check`

to `Val{false}()`

to disable tag checking. This can lead to perturbation confusion, so should be used with care.

## Hessians of `f(x::AbstractArray)::Real`

`ForwardDiff.hessian`

— Function`ForwardDiff.hessian(f, x::AbstractArray, cfg::HessianConfig = HessianConfig(f, x), check=Val{true}())`

Return `H(f)`

(i.e. `J(∇(f))`

) evaluated at `x`

, assuming `f`

is called as `f(x)`

.

This method assumes that `isa(f(x), Real)`

.

`check`

to `Val{false}()`

to disable tag checking. This can lead to perturbation confusion, so should be used with care.

`ForwardDiff.hessian!`

— Function`ForwardDiff.hessian!(result::AbstractArray, f, x::AbstractArray, cfg::HessianConfig = HessianConfig(f, x), check=Val{true}())`

Compute `H(f)`

(i.e. `J(∇(f))`

) evaluated at `x`

and store the result(s) in `result`

, assuming `f`

is called as `f(x)`

.

This method assumes that `isa(f(x), Real)`

.

`check`

to `Val{false}()`

to disable tag checking. This can lead to perturbation confusion, so should be used with care.

`ForwardDiff.hessian!(result::DiffResult, f, x::AbstractArray, cfg::HessianConfig = HessianConfig(f, result, x), check=Val{true}())`

Exactly like `ForwardDiff.hessian!(result::AbstractArray, f, x::AbstractArray, cfg::HessianConfig)`

, but because `isa(result, DiffResult)`

, `cfg`

is constructed as `HessianConfig(f, result, x)`

instead of `HessianConfig(f, x)`

.

`check`

to `Val{false}()`

to disable tag checking. This can lead to perturbation confusion, so should be used with care.

## Preallocating/Configuring Work Buffers

For the sake of convenience and performance, all "extra" information used by ForwardDiff's API methods is bundled up in the `ForwardDiff.AbstractConfig`

family of types. These types allow the user to easily feed several different parameters to ForwardDiff's API methods, such as chunk size, work buffers, and perturbation seed configurations.

ForwardDiff's basic API methods will allocate these types automatically by default, but you can drastically reduce memory usage if you preallocate them yourself.

Note that for all constructors below, the chunk size `N`

may be explicitly provided, or omitted, in which case ForwardDiff will automatically select a chunk size for you. However, it is highly recommended to specify the chunk size manually when possible (see Configuring Chunk Size).

Note also that configurations constructed for a specific function `f`

cannot be reused to differentiate other functions (though can be reused to differentiate `f`

at different values). To construct a configuration which can be reused to differentiate any function, you can pass `nothing`

as the function argument. While this is more flexible, it decreases ForwardDiff's ability to catch and prevent perturbation confusion.

`ForwardDiff.DerivativeConfig`

— Type`ForwardDiff.DerivativeConfig(f!, y::AbstractArray, x::AbstractArray)`

Return a `DerivativeConfig`

instance based on the type of `f!`

, and the types/shapes of the output vector `y`

and the input vector `x`

.

The returned `DerivativeConfig`

instance contains all the work buffers required by `ForwardDiff.derivative`

and `ForwardDiff.derivative!`

when the target function takes the form `f!(y, x)`

.

If `f!`

is `nothing`

instead of the actual target function, then the returned instance can be used with any target function. However, this will reduce ForwardDiff's ability to catch and prevent perturbation confusion (see https://github.com/JuliaDiff/ForwardDiff.jl/issues/83).

This constructor does not store/modify `y`

or `x`

.

`ForwardDiff.GradientConfig`

— Type`ForwardDiff.GradientConfig(f, x::AbstractArray, chunk::Chunk = Chunk(x))`

Return a `GradientConfig`

instance based on the type of `f`

and type/shape of the input vector `x`

.

The returned `GradientConfig`

instance contains all the work buffers required by `ForwardDiff.gradient`

and `ForwardDiff.gradient!`

.

If `f`

is `nothing`

instead of the actual target function, then the returned instance can be used with any target function. However, this will reduce ForwardDiff's ability to catch and prevent perturbation confusion (see https://github.com/JuliaDiff/ForwardDiff.jl/issues/83).

This constructor does not store/modify `x`

.

`ForwardDiff.JacobianConfig`

— Type`ForwardDiff.JacobianConfig(f, x::AbstractArray, chunk::Chunk = Chunk(x))`

Return a `JacobianConfig`

instance based on the type of `f`

and type/shape of the input vector `x`

.

The returned `JacobianConfig`

instance contains all the work buffers required by `ForwardDiff.jacobian`

and `ForwardDiff.jacobian!`

when the target function takes the form `f(x)`

.

If `f`

is `nothing`

instead of the actual target function, then the returned instance can be used with any target function. However, this will reduce ForwardDiff's ability to catch and prevent perturbation confusion (see https://github.com/JuliaDiff/ForwardDiff.jl/issues/83).

This constructor does not store/modify `x`

.

`ForwardDiff.JacobianConfig(f!, y::AbstractArray, x::AbstractArray, chunk::Chunk = Chunk(x))`

Return a `JacobianConfig`

instance based on the type of `f!`

, and the types/shapes of the output vector `y`

and the input vector `x`

.

The returned `JacobianConfig`

instance contains all the work buffers required by `ForwardDiff.jacobian`

and `ForwardDiff.jacobian!`

when the target function takes the form `f!(y, x)`

.

If `f!`

is `nothing`

instead of the actual target function, then the returned instance can be used with any target function. However, this will reduce ForwardDiff's ability to catch and prevent perturbation confusion (see https://github.com/JuliaDiff/ForwardDiff.jl/issues/83).

This constructor does not store/modify `y`

or `x`

.

`ForwardDiff.HessianConfig`

— Type`ForwardDiff.HessianConfig(f, x::AbstractArray, chunk::Chunk = Chunk(x))`

Return a `HessianConfig`

instance based on the type of `f`

and type/shape of the input vector `x`

.

The returned `HessianConfig`

instance contains all the work buffers required by `ForwardDiff.hessian`

and `ForwardDiff.hessian!`

. For the latter, the buffers are configured for the case where the `result`

argument is an `AbstractArray`

. If it is a `DiffResult`

, the `HessianConfig`

should instead be constructed via `ForwardDiff.HessianConfig(f, result, x, chunk)`

.

If `f`

is `nothing`

instead of the actual target function, then the returned instance can be used with any target function. However, this will reduce ForwardDiff's ability to catch and prevent perturbation confusion (see https://github.com/JuliaDiff/ForwardDiff.jl/issues/83).

This constructor does not store/modify `x`

.

`ForwardDiff.HessianConfig(f, result::DiffResult, x::AbstractArray, chunk::Chunk = Chunk(x))`

Return a `HessianConfig`

instance based on the type of `f`

, types/storage in `result`

, and type/shape of the input vector `x`

.

The returned `HessianConfig`

instance contains all the work buffers required by `ForwardDiff.hessian!`

for the case where the `result`

argument is an `DiffResult`

.

`f`

is `nothing`

instead of the actual target function, then the returned instance can be used with any target function. However, this will reduce ForwardDiff's ability to catch and prevent perturbation confusion (see https://github.com/JuliaDiff/ForwardDiff.jl/issues/83).

This constructor does not store/modify `x`

.