Description

The derivative function is used to compute the derivative of a univariate function that maps $\mathbb{R}$ to $\mathbb{R}$. For example, x -> sin(x) is a univariate function that might be passed to the derivative function.

The derivative function comes in three core variants:

• A pure function that directly computes the derivative of a function f at a fixed numeric value of x and returns a number as a result.
• A mutating function that computes the derivative of a function f at a fixed numeric value of x and stores the result into a user-provided output array. This function returns nothing since its action is focused on mutation.
• A higher-order function that constructs a new function f_prime that will compute the derivative of f at any point x that is provided as an argument to f_prime. This newly constructed function is the return value for this variant of the derivative function.

In addition, the derivative function allows one to chose the mode of numerical differentiation that is used to compute an approximate derivative. The default is use central finite differences, which evaluates f at two nearby points and provides much higher accuracy than other strategies at a cost of roughly double the amount of computation. Other modes of numerical differentiation are available, but must be opted-in to explicitly.

Primary Methods

The primary methods that most users will want to use are the following:

• Use derivative(f::Function, x::AbstractFloat) to approximate the derivative of f at x. This is the pure variant described above. Calling this function is equivalent to calling derivative(f::Function, x::AbstractFloat, ::CentralMode), but leaves the selection of the finite difference mode up to the package author's discretion.
• Use derivative!(output::AbstractArray, f::Function, x::AbstractFloat) to approximate the derivative of f at x and store the result into the output array.
• Use derivative(f::Function) to generate a new function that approximates the true derivative function of f. The new function f_prime can be evaluated at any point x that is desired after it is constructed.

Detailed Method-Level Documentation

# FiniteDiff.derivative — Method.

derivative(f::Function, x::AbstractFloat)

Description

Evaluate the derivative of f at x using finite differences without specifying the mode of finite differences. Defaults to using central finite differences, which is equivalent to the user calling derivative(f, x, CentralMode()) instead of derivative(f, x).

See the documentation for derivative(f, x, CentralMode()) for more details.

Arguments

• f::Function: The function to be differentiated.
• x::AbstractFloat: The point at which to evaluate the derivative of f. Its type must implement eps.

Returns

• y::Real: The derivative of f evaluated at x.

Examples

import FiniteDiff: derivative
y = derivative(sin, 0.0)

source

# FiniteDiff.derivative! — Function.

derivative!(
    output::AbstractArray,
    f::Function,
    x::AbstractFloat,
    m::Mode = CentralMode(),
)

Description

Evaluate the derivative of f at x using finite differences. The first argument output will be mutated so that its first element will contain the result.

See the documentation for the non-mutating versions of derivative for additional information about the effects of choosing a specific mode of finite differences.

Arguments

• output::AbstractArray: An array whose first element will be mutated.
• f::Function: The function to be differentiated.
• x::AbstractFloat: The point at which to evaluate the derivative of f. Its type must implement eps.
• m::Mode: An instance of the Mode type. This will determine the mode of finite differences that will be used.

Returns

• nothing::Void: This function is called for its side effects.

Examples

import FiniteDiff: derivative, CentralMode
y = Array(Float64, 1)
derivative!(y, sin, 0.0, CentralMode())

source

# FiniteDiff.derivative — Function.

derivative(f::Function, mode::Mode = CentralMode(); mutates::Bool=false)

Description

Construct a new function that will evaluate the derivative of f at any value of x using finite differences. The user can specify the mode of finite differences to use by providing a second positional argument. The user can also indicate whether to return a mutating or non-mutating function using the keyword argument, mutates, which should be either true or false.

Arguments

• f::Function: The function to be differentiated.
• m::Mode: An instance of the Mode type. This will determine the mode of finite differences that will be used.

Keyword Arguments

• mutates::Bool = false: Determine whether the resulting function will mutate its inputs or will be a pure function.

Examples

import FiniteDiff: derivative
f′ = derivative(sin)
f′(0.0)

source

# FiniteDiff.derivative — Method.

derivative(f::Function, x::AbstractFloat, ::ForwardMode)

Description

Evaluate the derivative of f at x using forward finite differences. In mathematical notation, we calculate,

$$\frac{f(x + \epsilon) - f(x)}{\epsilon},$$

where $\epsilon$ is chosen to be small enough to approximate the derivative, but not so small as to suffer from extreme numerical inaccuracy.

Arguments

• f::Function: The function to be differentiated.
• x::AbstractFloat: The point at which to evaluate the derivative of f. Its type must implement eps.
• ::ForwardMode: An instance of the ForwardMode type.

Returns

• y::Real: The derivative of f evaluated at x.

Examples

import FiniteDiff: derivative, ForwardMode
y = derivative(sin, 0.0, ForwardMode())

source

# FiniteDiff.derivative — Method.

derivative(f::Function, x::AbstractFloat, ::BackwardMode)

Description

Evaluate the derivative of f at x using backward finite differences. In mathematical notation, we calculate,

$$\frac{f(x) - f(x - \epsilon)}{\epsilon},$$

where $\epsilon$ is chosen to be small enough to approximate the derivative, but not so small as to suffer from extreme numerical inaccuracy.

Arguments

• f::Function: The function to be differentiated.
• x::AbstractFloat: The point at which to evaluate the derivative of f. Its type must implement eps.
• ::BackwardMode: An instance of the BackwardMode type.

Returns

• y::Real: The derivative of f evaluated at x.

Examples

import FiniteDiff: derivative, BackwardMode
y = derivative(sin, 0.0, BackwardMode())

source

# FiniteDiff.derivative — Method.

derivative(f::Function, x::AbstractFloat, ::CentralMode)

Description

Evaluate the derivative of f at x using central finite differences. In mathematical notation, we calculate,

$$\frac{f(x + \epsilon) - f(x - \epsilon)}{2 \epsilon},$$

where $\epsilon$ is chosen to be small enough to approximate the derivative, but not so small as to suffer from extreme numerical inaccuracy.

Arguments

• f::Function: The function to be differentiated.
• x::AbstractFloat: The point at which to evaluate the derivative of f. Its type must implement eps.
• ::CentralMode: An instance of the CentralMode type.

Returns

• y::Real: The derivative of f evaluated at x.

Examples

import FiniteDiff: derivative, CentralMode
y = derivative(sin, 0.0, CentralMode())

source

# FiniteDiff.derivative — Method.

derivative(f::Function, x::AbstractFloat, ::ComplexMode)

Description

Evaluate the derivative of f at x using complex finite differences. In mathematical notation, we calculate,

$$\frac{\operatorname{Im}(f(x + \epsilon i))}{\epsilon}$$

where $\epsilon$ is chosen to be as small as possible.

NOTE: This mode of finite differences will work correctly only when:

• f supports complex inputs.
• f is an analytic function in the complex analysis sense of the word.

Arguments

• f::Function: The function to be differentiated.
• x::AbstractFloat: The point at which to evaluate the derivative of f. Its type must implement eps.
• ::ForwardMode: An instance of the ForwardMode type.

Returns

• y::Real: The derivative of f evaluated at x.

Examples

import FiniteDiff: derivative, ComplexMode
y = derivative(sin, 0.0, ComplexMode())

source