## Finite Differences

`FiniteDifferences.FiniteDifferenceMethod`

— Type```
FiniteDifferenceMethod(
grid::AbstractVector{Int},
q::Int;
condition::Real=DEFAULT_CONDITION,
factor::Real=DEFAULT_FACTOR,
max_range::Real=Inf
)
```

Construct a finite difference method.

**Arguments**

`grid::Vector{Int}`

: The grid. See`AdaptedFiniteDifferenceMethod`

or`UnadaptedFiniteDifferenceMethod`

.`q::Int`

: Order of the derivative to estimate.

**Keywords**

`condition::Real`

: Condition number. See`DEFAULT_CONDITION`

.`factor::Real`

: Factor number. See`DEFAULT_FACTOR`

.`max_range::Real=Inf`

: Maximum distance that a function is evaluated from the input at which the derivative is estimated.

**Returns**

`FiniteDifferenceMethod`

: Specified finite difference method.

`FiniteDifferences.estimate_step`

— Function```
function estimate_step(
m::FiniteDifferenceMethod,
f,
x::T
) where T<:AbstractFloat
```

Estimate the step size for a finite difference method `m`

. Also estimates the error of the estimate of the derivative.

**Arguments**

`m::FiniteDifferenceMethod`

: Finite difference method to estimate the step size for.`f`

: Function to evaluate the derivative of.`x::T`

: Point to estimate the derivative at.

**Returns**

`Tuple{<:AbstractFloat, <:AbstractFloat}`

: Estimated step size and an estimate of the error of the finite difference estimate. The error will be`NaN`

if the method failed to estimate the error.

`FiniteDifferences.central_fdm`

— Function```
central_fdm(
p::Int,
q::Int;
adapt::Int=1,
condition::Real=DEFAULT_CONDITION,
factor::Real=DEFAULT_FACTOR,
max_range::Real=Inf,
geom::Bool=false
)
```

Contruct a finite difference method at a central grid of `p`

points.

**Arguments**

`p::Int`

: Number of grid points.`q::Int`

: Order of the derivative to estimate.

**Keywords**

`adapt::Int=1`

: Use another finite difference method to estimate the magnitude of the`p`

th order derivative, which is important for the step size computation. Recurse this procedure`adapt`

times.`condition::Real`

: Condition number. See`DEFAULT_CONDITION`

.`factor::Real`

: Factor number. See`DEFAULT_FACTOR`

.`max_range::Real=Inf`

: Maximum distance that a function is evaluated from the input at which the derivative is estimated.`geom::Bool`

: Use geometrically spaced points instead of linearly spaced points.

**Returns**

`FiniteDifferenceMethod`

: The specified finite difference method.

`FiniteDifferences.forward_fdm`

— Function```
forward_fdm(
p::Int,
q::Int;
adapt::Int=1,
condition::Real=DEFAULT_CONDITION,
factor::Real=DEFAULT_FACTOR,
max_range::Real=Inf,
geom::Bool=false
)
```

Contruct a finite difference method at a forward grid of `p`

points.

**Arguments**

`p::Int`

: Number of grid points.`q::Int`

: Order of the derivative to estimate.

**Keywords**

`adapt::Int=1`

: Use another finite difference method to estimate the magnitude of the`p`

th order derivative, which is important for the step size computation. Recurse this procedure`adapt`

times.`condition::Real`

: Condition number. See`DEFAULT_CONDITION`

.`factor::Real`

: Factor number. See`DEFAULT_FACTOR`

.`max_range::Real=Inf`

: Maximum distance that a function is evaluated from the input at which the derivative is estimated.`geom::Bool`

: Use geometrically spaced points instead of linearly spaced points.

**Returns**

`FiniteDifferenceMethod`

: The specified finite difference method.

`FiniteDifferences.backward_fdm`

— Function```
backward_fdm(
p::Int,
q::Int;
adapt::Int=1,
condition::Real=DEFAULT_CONDITION,
factor::Real=DEFAULT_FACTOR,
max_range::Real=Inf,
geom::Bool=false
)
```

Contruct a finite difference method at a backward grid of `p`

points.

**Arguments**

`p::Int`

: Number of grid points.`q::Int`

: Order of the derivative to estimate.

**Keywords**

`adapt::Int=1`

: Use another finite difference method to estimate the magnitude of the`p`

th order derivative, which is important for the step size computation. Recurse this procedure`adapt`

times.`condition::Real`

: Condition number. See`DEFAULT_CONDITION`

.`factor::Real`

: Factor number. See`DEFAULT_FACTOR`

.`max_range::Real=Inf`

: Maximum distance that a function is evaluated from the input at which the derivative is estimated.`geom::Bool`

: Use geometrically spaced points instead of linearly spaced points.

**Returns**

`FiniteDifferenceMethod`

: The specified finite difference method.

`FiniteDifferences.extrapolate_fdm`

— Function```
extrapolate_fdm(
m::FiniteDifferenceMethod,
f,
x::Real,
initial_step::Real=10,
power::Int=1,
breaktol::Real=Inf,
kw_args...
)
```

Use Richardson extrapolation to extrapolate a finite difference method.

Takes further in keyword arguments for `Richardson.extrapolate`

. This method automatically sets `power = 2`

if `m`

is symmetric and `power = 1`

. Moreover, it defaults `breaktol = Inf`

.

**Arguments**

`m::FiniteDifferenceMethod`

: Finite difference method to estimate the step size for.`f`

: Function to evaluate the derivative of.`x::Real`

: Point to estimate the derivative at.`initial_step::Real=10`

: Initial step size.

**Returns**

`Tuple{<:AbstractFloat, <:AbstractFloat}`

: Estimate of the derivative and error.

`FiniteDifferences.assert_approx_equal`

— Function`assert_approx_equal(x, y, ε_abs, ε_rel[, desc])`

Assert that `x`

is approximately equal to `y`

.

Let `eps_z = eps_abs / eps_rel`

. Call `x`

and `y`

small if `abs(x) < eps_z`

and `abs(y) < eps_z`

, and call `x`

and `y`

large otherwise. If this function returns `True`

, then it is guaranteed that `abs(x - y) < 2 eps_rel max(abs(x), abs(y))`

if `x`

and `y`

are large, and `abs(x - y) < 2 eps_abs`

if `x`

and `y`

are small.

**Arguments**

`x`

: First object to compare.`y`

: Second object to compare.`ε_abs`

: Absolute tolerance.`ε_rel`

: Relative tolerance.`desc`

: Description of the comparison. Omit or set to`false`

to have no description.

`FiniteDifferences.UnadaptedFiniteDifferenceMethod`

— Type`UnadaptedFiniteDifferenceMethod{P,Q} <: FiniteDifferenceMethod{P,Q}`

A finite difference method that estimates a `Q`

th order derivative from `P`

function evaluations. This method does not dynamically adapt its step size.

**Fields**

`grid::SVector{P,Int}`

: Multiples of the step size that the function will be evaluated at.`coefs::SVector{P,Float64}`

: Coefficients corresponding to the grid functions that the function evaluations will be weighted by.`coefs_neighbourhood::NTuple{3,SVector{P,Float64}}`

: Sets of coefficients used for estimating the magnitude of the derivative in a neighbourhood.`bound_estimator::FiniteDifferenceMethod`

: A finite difference method that is tuned to perform adaptation for this finite difference method.`condition::Float64`

: Condition number. See See`DEFAULT_CONDITION`

.`factor::Float64`

: Factor number. See See`DEFAULT_FACTOR`

.`max_range::Float64`

: Maximum distance that a function is evaluated from the input at which the derivative is estimated.`∇f_magnitude_mult::Float64`

: Internally computed quantity.`f_error_mult::Float64`

: Internally computed quantity.

`FiniteDifferences.AdaptedFiniteDifferenceMethod`

— Type```
AdaptedFiniteDifferenceMethod{
P, Q, E<:FiniteDifferenceMethod
} <: FiniteDifferenceMethod{P,Q}
```

A finite difference method that estimates a `Q`

th order derivative from `P`

function evaluations.

This method dynamically adapts its step size. The adaptation works by explicitly estimating the truncation error and round-off error, and choosing the step size to optimally balance those. The truncation error is given by the magnitude of the `P`

th order derivative, which will be estimated with another finite difference method (`bound_estimator`

). This finite difference method, `bound_estimator`

, will be tasked with estimating the `P`

th order derivative in a *neighbourhood*, not just at some `x`

. To do this, it will use a careful reweighting of the function evaluations to estimate the `P`

th order derivative at, in the case of a central method, `x - h`

, `x`

, and `x + h`

, where `h`

is the step size. The coeffients for this estimate, the *neighbourhood estimate*, are given by the three sets of coeffients in `bound_estimator.coefs_neighbourhood`

. The round-off error is estimated by the round-off error of the function evaluations performed by `bound_estimator`

. The trunction error is amplified by `condition`

, and the round-off error is amplified by `factor`

. The quantities `∇f_magnitude_mult`

and `f_error_mult`

are precomputed quantities that facilitate the step size adaptation procedure.

**Fields**

`grid::SVector{P,Int}`

: Multiples of the step size that the function will be evaluated at.`coefs::SVector{P,Float64}`

: Coefficients corresponding to the grid functions that the function evaluations will be weighted by.`coefs_neighbourhood::NTuple{3,SVector{P,Float64}}`

: Sets of coefficients used for estimating the magnitude of the derivative in a neighbourhood.`condition::Float64`

: Condition number. See See`DEFAULT_CONDITION`

.`factor::Float64`

: Factor number. See See`DEFAULT_FACTOR`

.`max_range::Float64`

: Maximum distance that a function is evaluated from the input at which the derivative is estimated.`∇f_magnitude_mult::Float64`

: Internally computed quantity.`f_error_mult::Float64`

: Internally computed quantity.`bound_estimator::FiniteDifferenceMethod`

: A finite difference method that is tuned to perform adaptation for this finite difference method.

`FiniteDifferences.DEFAULT_CONDITION`

— Constant`FiniteDifferences.DEFAULT_CONDITION`

The default value for the condition number of finite difference method. The condition number specifies the amplification of the ∞-norm when passed to the function's derivative.

`FiniteDifferences.DEFAULT_FACTOR`

— Constant`FiniteDifferences.DEFAULT_FACTOR`

The default factor number. The factor number specifies the multiple to amplify the estimated round-off errors by.

## Gradients

`FiniteDifferences.grad`

— Function`grad(fdm, f, xs...)`

Compute the gradient of `f`

for any `xs`

for which `to_vec`

is defined.

Return tuple of gradients, one for each argument.

`FiniteDifferences.jacobian`

— Function`jacobian(fdm, f, x...)`

Approximate the Jacobian of `f`

at `x`

using `fdm`

. Results will be returned as a `Matrix{<:Real}`

of `size(length(y_vec), length(x_vec))`

where `x_vec`

is the flattened version of `x`

, and `y_vec`

the flattened version of `f(x...)`

. Flattening performed by `to_vec`

.

`FiniteDifferences.jvp`

— Function`jvp(fdm, f, xẋs::Tuple{Any, Any}...)`

Compute a Jacobian-vector product with any types of arguments for which `to_vec`

is defined. Each 2-`Tuple`

in `xẋs`

contains the value `x`

and its tangent `ẋ`

.

`FiniteDifferences.j′vp`

— Function`j′vp(fdm, f, ȳ, x...)`

Compute an adjoint with any types of arguments `x`

for which `to_vec`

is defined.

Return tuple of gradients, one for each argument.

`FiniteDifferences.to_vec`

— Function`to_vec(x)`

Transform `x`

into a `Vector`

, and return the vector, and a closure which inverts the transformation.