Description

The hessian function is used to compute the Hessian of a multivariate function that maps $\mathbb{R}^n$ to $\mathbb{R}$. For example, x -> sin(x[1]) + cos(x[2]) is a multivariate function that might be passed to the hessian function.

The hessian function comes in three core variants:

  • A pure function that directly computes the Hessian of a function f at a fixed value of x and returns a newly allocated array as a result.
  • A mutating function that computes the Hessian of a function f at a fixed value of x and stores the result into a user-provided output array. This function returns nothing since its action is focused on mutation. To ensure thread safety, this mutating variant also requires that a buffer be provided that is part of the internal implementation of the function, but can be provided explicitly to minimize unnecessary memory allocations.
  • A higher-order function that constructs a new function f_prime that will compute the Hessian 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 hessian function.

Primary Methods

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

  • Use hessian(f::Function, x::AbstractArray) to approximate the Hessian of f at x. This is the pure variant described above.
  • Use hessian!(output::AbstractArray, f::Function, x::AbstractArray, buffer::AbstractArray) to approximate the Hessian of f at x and store the result into the output array.
  • Use hessian(f::Function) to generate a new function that approximates the true Hessian 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.hessian! — Method.

hessian!{T <: AbstractFloat}(
    output::AbstractArray,
    f::Function,
    x::AbstractArray{T},
    buffer::AbstractArray{T},
)

Description

Evaluate the Hessian of f at x using finite differences. Store the results into output. Work with a user-provided buffer to ensure that we can work without copies, but also without mutating x. In Rust jargon, we take ownership of both output and buffer, but do not require ownership of x. We just need read-only access to x.

Arguments

  • output::AbstractArray: An array that will be mutated to contain the gradient.
  • f::Function: The function to be differentiated.
  • x::AbstractArray{T}: The value of x at which to evaluate the Hessian of f.
  • buffer::AbstractArray{T}: A buffer that is equivalent to similar(x). Used as a temporary copy of x that can be mutated.

Returns

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

Examples

import FiniteDiff: hessian!
x = [0.0, 0.0]
output, buffer = similar(x, 2, 2), similar(x, 2)
hessian!(output, x -> sin(x[1]) + 2 * sin(x[2]), x, buffer)

source

# FiniteDiff.hessian — Method.

hessian{T <: AbstractFloat}(f::Function, x::AbstractArray{T})

Description

Evaluate the Hessian of f at x using finite differences. See hessian!(f, x, buffer) for more details.

Arguments

  • f::Function: The function to be differentiated.
  • x::AbstractArray{T <: AbstractArray}: The value of x at which to evaluate the Hessian of f.

Returns

  • output::Array{T <: AbstractArray}: The Hessian of f at x.

Examples

import FiniteDiff: hessian
x = [0.0, 0.0]
H = hessian(x -> sin(x[1]) + 2 * sin(x[2]), x)

source

# FiniteDiff.hessian — Method.

hessian(f::Function; mutates::Bool = false)

Description

Construct a new function that will evaluate the Hessian of f at any value of x. The user can whether to return a mutating or non-mutating function using a keyword argument.

Arguments

  • f::Function: The function to be differentiated.

Keyword Arguments

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

Returns

  • h::Function: A function that will evaluate the Hessian of f at any x.

Examples

import FiniteDiff: hessian
h = hessian(x -> sin(x[1]) + 2 * sin(x[2]), mutates = false)
x = [0.0, 0.0]
h(x)

source