gemseo / utils / derivatives

Hide inherited members

finite_differences module

Gradient approximation by finite differences.

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

Bases: GradientApproximator

First-order finite differences approximator.

\[\begin{split}\frac{df(x)}{dx}\approx\frac{f(x+\\delta x)-f(x)}{\\delta x}\end{split}\]
Parameters:

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

  • step (float | ndarray | None) – The default differentiation step.

  • design_space (DesignSpace | None) – The design space containing the upper bounds of the input variables. If None, consider that the input variables are unbounded.

  • normalize (bool) –

    Whether to normalize the function.

    By default it is set to True.

  • parallel (bool) –

    Whether to differentiate the function in parallel.

    By default it is set to False.

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

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

Compute the gradient by real step.

Parameters:

  • x_vect (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 (float | ndarray | None) – The differentiation step. If None, use the default differentiation step.

  • x_indices (Sequence[int] | None) – The components of the input vector to be used for the differentiation. If None, use all the components.

  • **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 (ndarray) – The input vector.

  • x_indices (Sequence[int] | None) – The components of the input vector to be used for the differentiation. If None, use all the components.

  • step (float | None) – The differentiation step. If None, use the default differentiation step.

Returns:

  • The input perturbations.

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

Return type:

tuple[ndarray, float | ndarray]

f_pointer: Callable[[ndarray], ndarray]

The pointer to the function to derive.

property step: float

The default approximation step.