Documentation

Overview ¶

Package fd provides functions to approximate derivatives using finite differences.

Constants ¶

This section is empty.

Variables ¶

var Backward = Formula{
Stencil:    []Point{{Loc: -1, Coeff: -1}, {Loc: 0, Coeff: 1}},
Derivative: 1,
Step:       2e-8,
}

Backward represents a first-order accurate backward approximation to the first derivative.

var Backward2nd = Formula{
Stencil:    []Point{{Loc: 0, Coeff: 1}, {Loc: -1, Coeff: -2}, {Loc: -2, Coeff: 1}},
Derivative: 2,
Step:       1e-4,
}

Backward2nd represents a first-order accurate forward approximation to the second derivative.

var Central = Formula{
Stencil:    []Point{{Loc: -1, Coeff: -0.5}, {Loc: 1, Coeff: 0.5}},
Derivative: 1,
Step:       6e-6,
}

Central represents a second-order accurate centered approximation to the first derivative.

var Central2nd = Formula{
Stencil:    []Point{{Loc: -1, Coeff: 1}, {Loc: 0, Coeff: -2}, {Loc: 1, Coeff: 1}},
Derivative: 2,
Step:       1e-4,
}

Central2nd represents a secord-order accurate centered approximation to the second derivative.

var Forward = Formula{
Stencil:    []Point{{Loc: 0, Coeff: -1}, {Loc: 1, Coeff: 1}},
Derivative: 1,
Step:       2e-8,
}

Forward represents a first-order accurate forward approximation to the first derivative.

var Forward2nd = Formula{
Stencil:    []Point{{Loc: 0, Coeff: 1}, {Loc: 1, Coeff: -2}, {Loc: 2, Coeff: 1}},
Derivative: 2,
Step:       1e-4,
}

Forward2nd represents a first-order accurate forward approximation to the second derivative.

Functions ¶

func CrossLaplacian¶

func CrossLaplacian(f func(x, y []float64) float64, x, y []float64, settings *Settings) float64

CrossLaplacian computes a Laplacian-like quantity for a function of two vectors at the locations x and y. It computes

∇_y · ∇_x f(x,y) = \sum_i ∂^2 f(x,y)/∂x_i ∂y_i


The two input vector lengths must be the same.

Finite difference formula and other options are specified by settings. If settings is nil, CrossLaplacian will be estimated using the Forward formula and a default step size.

CrossLaplacian panics if the two input vectors are not the same length, or if the derivative order of the formula is not 1.

func Derivative¶

func Derivative(f func(float64) float64, x float64, settings *Settings) float64

Derivative estimates the derivative of the function f at the given location. The finite difference formula, the step size, and other options are specified by settings. If settings is nil, the first derivative will be estimated using the Forward formula and a default step size.

Example

Code:

package main

import (
"fmt"
"gonum.org/v1/gonum/diff/fd"
"math"
)

func main() {
f := func(x float64) float64 {
return math.Sin(x)
}
// Compute the first derivative of f at 0 using the default settings.
fmt.Println("f'(0) ≈", fd.Derivative(f, 0, nil))
// Compute the first derivative of f at 0 using the forward approximation
// with a custom step size.
df := fd.Derivative(f, 0, &fd.Settings{
Formula: fd.Forward,
Step:    1e-3,
})
fmt.Println("f'(0) ≈", df)

f = func(x float64) float64 {
return math.Pow(math.Cos(x), 3)
}
// Compute the second derivative of f at 0 using
// the centered approximation, concurrent evaluation,
// and a known function value at x.
df = fd.Derivative(f, 0, &fd.Settings{
Formula:     fd.Central2nd,
Concurrent:  true,
OriginKnown: true,
OriginValue: f(0),
})
fmt.Println("f''(0) ≈", df)

}

f'(0) ≈ 1
f'(0) ≈ 0.9999998333333416
f''(0) ≈ -2.999999981767587


func Gradient(dst []float64, f func([]float64) float64, x []float64, settings *Settings) []float64

Gradient estimates the gradient of the multivariate function f at the location x. If dst is not nil, the result will be stored in-place into dst and returned, otherwise a new slice will be allocated first. Finite difference formula and other options are specified by settings. If settings is nil, the gradient will be estimated using the Forward formula and a default step size.

Gradient panics if the length of dst and x is not equal, or if the derivative order of the formula is not 1.

func Hessian¶

func Hessian(dst *mat.SymDense, f func(x []float64) float64, x []float64, settings *Settings)

Hessian approximates the Hessian matrix of the multivariate function f at the location x. That is

H_{i,j} = ∂^2 f(x)/∂x_i ∂x_j


The resulting H will be stored in dst. Finite difference formula and other options are specified by settings. If settings is nil, the Hessian will be estimated using the Forward formula and a default step size.

If the dst matrix is empty it will be resized to the correct dimensions, otherwise the dimensions of dst must match the length of x or Hessian will panic. Hessian will panic if the derivative order of the formula is not 1.

func Jacobian¶

func Jacobian(dst *mat.Dense, f func(y, x []float64), x []float64, settings *JacobianSettings)

Jacobian approximates the Jacobian matrix of a vector-valued function f at the location x and stores the result in-place into dst.

Finite difference formula and other options are specified by settings. If settings is nil, the Jacobian will be estimated using the Forward formula and a default step size.

The Jacobian matrix J is the matrix of all first-order partial derivatives of f. If f maps an n-dimensional vector x to an m-dimensional vector y = f(x), J is an m×n matrix whose elements are given as

J_{i,j} = ∂f_i/∂x_j,


or expanded out

    [ ∂f_1/∂x_1 ... ∂f_1/∂x_n ]
[     .  .          .     ]
J = [     .      .      .     ]
[     .          .  .     ]
[ ∂f_m/∂x_1 ... ∂f_m/∂x_n ]


dst must be non-nil, the number of its columns must equal the length of x, and the derivative order of the formula must be 1, otherwise Jacobian will panic.

Example

Code:

package main

import (
"fmt"
"gonum.org/v1/gonum/diff/fd"
"gonum.org/v1/gonum/mat"
"math"
)

func main() {
f := func(dst, x []float64) {
dst[0] = x[0] + 1
dst[1] = 5 * x[2]
dst[2] = 4*x[1]*x[1] - 2*x[2]
dst[3] = x[2] * math.Sin(x[0])
}
jac := mat.NewDense(4, 3, nil)
fd.Jacobian(jac, f, []float64{1, 2, 3}, &fd.JacobianSettings{
Formula:    fd.Central,
Concurrent: true,
})
fmt.Printf("J ≈ %.6v\n", mat.Formatted(jac, mat.Prefix("    ")))

}

J ≈ ⎡       1         0         0⎤
⎢       0         0         5⎥
⎢       0        16        -2⎥
⎣ 1.62091         0  0.841471⎦


func Laplacian¶

func Laplacian(f func(x []float64) float64, x []float64, settings *Settings) float64

Laplacian computes the Laplacian of the multivariate function f at the location x. That is, Laplacian returns

∆ f(x) = ∇ · ∇ f(x) = \sum_i ∂^2 f(x)/∂x_i^2


The finite difference formula and other options are specified by settings. The order of the difference formula must be 2 or Laplacian will panic.

Types ¶

type Formula¶

type Formula struct {
// Stencil is the set of sampling Points which are used to estimate the
// derivative. The locations will be scaled by Step and are relative to x.
Stencil    []Point
Derivative int     // The order of the approximated derivative.
Step       float64 // Default step size for the formula.
}

Formula represents a finite difference formula on a regularly spaced grid that approximates the derivative of order k of a function f at x as

d^k f(x) ≈ (1 / Step^k) * \sum_i Coeff_i * f(x + Step * Loc_i).


Step must be positive, or the finite difference formula will panic.

type JacobianSettings¶

type JacobianSettings struct {
Formula     Formula
OriginValue []float64
Step        float64
Concurrent  bool
}

type Point¶

type Point struct {
Loc   float64
Coeff float64
}

A Point is a stencil location in a finite difference formula.

type Settings¶

type Settings struct {
// Formula is the finite difference formula used
// for approximating the derivative.
// Zero value indicates a default formula.
Formula Formula
// Step is the distance between points of the stencil.
// If equal to 0, formula's default step will be used.
Step float64

OriginKnown bool    // Flag that the value at the origin x is known.
OriginValue float64 // Value at the origin (only used if OriginKnown is true).

Concurrent bool // Should the function calls be executed concurrently.
}

Settings is the settings structure for computing finite differences.