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.

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.

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 pth 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.

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 pth 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.

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 pth 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.

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.

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.

UnadaptedFiniteDifferenceMethod{P,Q} <: FiniteDifferenceMethod{P,Q}

A finite difference method that estimates a Qth 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.

AdaptedFiniteDifferenceMethod{
    P, Q, E<:FiniteDifferenceMethod
} <: FiniteDifferenceMethod{P,Q}

A finite difference method that estimates a Qth 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 Pth 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 Pth 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 Pth 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

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

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

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.

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.

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 ẋ.

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.

to_vec(x)

Transform x into a Vector, and return the vector, and a closure which inverts the transformation.