biogeme.tools.derivatives module

class biogeme.tools.derivatives.CheckDerivativesResults(function, analytical_gradient, analytical_hessian, finite_differences_gradient, finite_differences_hessian, errors_gradient, errors_hessian)

Bases: NamedTuple

Parameters:

• function (float)

• analytical_gradient (ndarray)

• analytical_hessian (ndarray)

• finite_differences_gradient (ndarray)

• finite_differences_hessian (ndarray)

• errors_gradient (ndarray)

• errors_hessian (ndarray)

analytical_gradient: ndarray

Alias for field number 1

analytical_hessian: ndarray

Alias for field number 2

errors_gradient: ndarray

Alias for field number 5

errors_hessian: ndarray

Alias for field number 6

finite_differences_gradient: ndarray

Alias for field number 3

finite_differences_hessian: ndarray

Alias for field number 4

function: float

Alias for field number 0

biogeme.tools.derivatives.check_derivatives(the_function, x, names=None, logg=False)

Verifies the analytical derivatives of a function by comparing them with finite difference approximations.

Parameters:

• the_function (CallableExpression) –

  A function object that takes a vector as an argument, and returns a tuple:

  • The first element of the tuple is the value of the function \(f\),

  • the second is the gradient of the function,

  • the third is the hessian.

• x (ndarray) – arguments of the function

• names (list[str] | None) – the names of the entries of x (for reporting).

• logg (bool | None) – if True, messages will be displayed.

Return type:

CheckDerivativesResults

Returns:

tuple f, g, h, gdiff, hdiff where

• f is the value of the function at x,

• g is the analytical gradient,

• h is the analytical hessian,

• gdiff is the difference between the analytical gradient and the finite difference approximation

• hdiff is the difference between the analytical hessian and the finite difference approximation

biogeme.tools.derivatives.findiff_g(the_function, x)

Calculates the gradient of a function \(f\) using finite differences

Parameters:

• the_function (CallableExpression) – A function object that takes a vector as an argument, and returns a tuple. The first element of the tuple is the value of the function \(f\). The other elements are not used.

• x (ndarray) – argument of the function

Return type:

ndarray

Returns:

numpy vector, same dimension as x, containing the gradient calculated by finite differences.

biogeme.tools.derivatives.findiff_h(the_function, x)

Calculates the hessian of a function \(f\) using finite differences

Parameters:

• the_function (CallableExpression) – A function object that takes a vector as an argument, and returns a tuple. The first element of the tuple is the value of the function \(f\), and the second is the gradient of the function. The other elements are not used.

• x (ndarray) – argument of the function

Return type:

ndarray

Returns:

numpy matrix containing the hessian calculated by finite differences.