gemseo / utils / derivatives

finite_differences module

Gradient approximation by finite differences.

Classes:

FirstOrderFD(f_pointer[, step, parallel, ...])

First-order finite differences approximator.

Functions:

approx_hess(f_p, f_x, f_m, step)

Compute the second-order approximation of the Hessian matrix \(d^2f/dx^2\).

comp_best_step(f_p, f_x, f_m, step[, ...])

Compute the optimal step for finite differentiation.

compute_cancellation_error(f_x, step[, ...])

Estimate the cancellation error.

compute_truncature_error(hess, step)

Estimate the truncation error.

class gemseo.utils.derivatives.finite_differences.FirstOrderFD(f_pointer, step=1e-06, parallel=False, design_space=None, normalize=True, **parallel_args)[source]

Bases: gemseo.utils.derivatives.gradient_approximator.GradientApproximator

First-order finite differences approximator.

\[\]

rac{df(x)}{dx}pprox rac{f(x+delta x)-f(x)}{delta x}

f_pointer

The pointer to the function to derive.

Type

Callable

Initialize self. See help(type(self)) for accurate signature.

Parameters
  • f_pointer (Callable[[ndarray],ndarray]) – The pointer to the function to derive.

  • step (Union[float,ndarray]) –

    The default differentiation step.

    By default it is set to 1e-06.

  • parallel (bool) –

    Whether to differentiate the function in parallel.

    By default it is set to False.

  • design_space (Optional[DesignSpace]) –

    The design space containing the upper bounds of the input variables. If None, consider that the input variables are unbounded.

    By default it is set to None.

  • normalize (bool) –

    If True, then the functions are normalized.

    By default it is set to True.

  • **parallel_args (Union[int,bool,float]) – The parallel execution options, see gemseo.core.parallel_execution.

Return type

None

Attributes:

ALIAS

step

The default approximation step.

Methods:

compute_optimal_step(x_vect[, numerical_error])

Compute the gradient by real step.

f_gradient(x_vect[, step, x_indices])

Approximate the gradient of the function for a given input vector.

generate_perturbations(n_dim, x_vect[, ...])

Generate the input perturbations from the differentiation step.

ALIAS = 'finite_differences'
compute_optimal_step(x_vect, numerical_error=2.220446049250313e-16, **kwargs)[source]

Compute the gradient by real step.

Parameters
  • x_vect (numpy.ndarray) – The input vector.

  • numerical_error (float) –

    The numerical error associated to the calculation of \(f\). By default machine epsilon (appx 1e-16), but can be higher. when the calculation of \(f\) requires a numerical resolution.

    By default it is set to 2.220446049250313e-16.

  • **kwargs – The additional arguments passed to the function.

Returns

  • The optimal steps.

  • The errors.

Return type

Tuple[numpy.ndarray, numpy.ndarray]

f_gradient(x_vect, step=None, x_indices=None, **kwargs)[source]

Approximate the gradient of the function for a given input vector.

Parameters
  • x_vect (ndarray) – The input vector.

  • step (Optional[float,ndarray]) –

    The differentiation step. If None, use the default differentiation step.

    By default it is set to None.

  • x_indices (Optional[Sequence[int]]) –

    The components of the input vector to be used for the differentiation. If None, use all the components.

    By default it is set to None.

  • **kwargs (Any) – The optional arguments for the function.

Returns

The approximated gradient.

Return type

ndarray

generate_perturbations(n_dim, x_vect, x_indices=None, step=None)

Generate the input perturbations from the differentiation step.

These perturbations will be used to compute the output ones.

Parameters
  • n_dim (int) – The input dimension.

  • x_vect (numpy.ndarray) – The input vector.

  • x_indices (Optional[Sequence[int]]) –

    The components of the input vector to be used for the differentiation. If None, use all the components.

    By default it is set to None.

  • step (Optional[float]) –

    The differentiation step. If None, use the default differentiation step.

    By default it is set to None.

Returns

  • The input perturbations.

  • The differentiation step, either one global step or one step by input component.

Return type

Tuple[numpy.ndarray, Union[float, numpy.ndarray]]

property step

The default approximation step.

gemseo.utils.derivatives.finite_differences.approx_hess(f_p, f_x, f_m, step)[source]

Compute the second-order approximation of the Hessian matrix \(d^2f/dx^2\).

Parameters
  • f_p (numpy.ndarray) – The value of the function \(f\) at the next step \(x+\\delta_x\).

  • f_x (numpy.ndarray) – The value of the function \(f\) at the current step \(x\).

  • f_m (numpy.ndarray) – The value of the function \(f\) at the previous step \(x-\\delta_x\).

  • step (float) – The differentiation step \(\\delta_x\).

Returns

The approximation of the Hessian matrix at the current step \(x\).

Return type

numpy.ndarray

gemseo.utils.derivatives.finite_differences.comp_best_step(f_p, f_x, f_m, step, epsilon_mach=2.220446049250313e-16)[source]

Compute the optimal step for finite differentiation.

Applied to a forward first order finite differences gradient approximation.

Require a first evaluation of the perturbed functions values.

The optimal step is reached when the truncation error (cut in the Taylor development), and the numerical cancellation errors (round-off when doing \(f(x+step)-f(x))\) are equal.

See: - https://en.wikipedia.org/wiki/Numerical_differentiation - Numerical Algorithms and Digital Representation,

Knut Morken, Chapter 11, “Numerical Differenciation”

Parameters
  • f_p (numpy.ndarray) – The value of the function \(f\) at the next step \(x+\\delta_x\).

  • f_x (numpy.ndarray) – The value of the function \(f\) at the current step \(x\).

  • f_m (numpy.ndarray) – The value of the function \(f\) at the previous step \(x-\\delta_x\).

  • step (float) – The differentiation step \(\\delta_x\).

  • epsilon_mach (float) –

    By default it is set to 2.220446049250313e-16.

Returns

  • The estimation of the truncation error. None if the Hessian approximation is too small to compute the optimal step.

  • The estimation of the cancellation error. None if the Hessian approximation is too small to compute the optimal step.

  • The optimal step.

Return type

Tuple[Optional[numpy.ndarray], Optional[numpy.ndarray], float]

gemseo.utils.derivatives.finite_differences.compute_cancellation_error(f_x, step, epsilon_mach=2.220446049250313e-16)[source]

Estimate the cancellation error.

This is the round-off when doing \(f(x+\\delta_x)-f(x)\).

Parameters
  • f_x (numpy.ndarray) – The value of the function at the current step \(x\).

  • step (float) – The step used for the calculations of the perturbed functions values.

  • epsilon_mach

    The machine epsilon.

    By default it is set to 2.220446049250313e-16.

Returns

The cancellation error.

Return type

numpy.ndarray

gemseo.utils.derivatives.finite_differences.compute_truncature_error(hess, step)[source]

Estimate the truncation error.

Defined for a first order finite differences scheme.

Parameters
  • hess (numpy.ndarray) – The second-order derivative \(d^2f/dx^2\).

  • step (float) – The differentiation step.

Returns

The truncation error.

Return type

numpy.ndarray