Gradient, Jacobian and Hessian¶
Estimagic wraps numdifftools to provide functions to calculate very precise gradients, jacobians and hessians of functions. The precision is achieved by evaluating numerical derivatives at different step sizes and using Richardson extrapolations. While this increases the computational cost, it works for any function, whereas other approaches that would yield a similar precision, like complex step derivatives, have stronger requirements.
-
estimagic.differentiation.differentiation.gradient(func, params, method='central', extrapolation=True, func_kwargs=None, step_options=None)[source]¶ Calculate the gradient of func.
- Parameters
func (function) – A function that maps params into a float.
params (DataFrame) – see The params Argument
method (str) – The method for the computation of the derivative. Default is central as it gives the highest accuracy.
extrapolation (bool) – This variable allows to specify the use of the richardson extrapolation.
func_kwargs (dict) – additional positional arguments for func.
step_options (dict) – Options for the numdifftools step generator. See Influencing the Step Size
- Returns
- The index is the index of params, the values contain the estimated
gradient.
- Return type
Series
-
estimagic.differentiation.differentiation.jacobian(func, params, method='central', extrapolation=True, func_kwargs=None, step_options=None)[source]¶ Calculate the jacobian of func.
- Parameters
func (function) – A function that maps params into a numpy array or pd.Series.
params (DataFrame) – see The params Argument
method (string) – The method for the computation of the derivative. Default is central as it gives the highest accuracy.
extrapolation (bool) – This variable allows to specify the use of the richardson extrapolation.
func_kwargs (dict) – additional positional arguments for func.
step_options (dict) – Options for the numdifftools step generator. See Influencing the Step Size
- Returns
If func returns a Series, the index is the index of this Series or the index is 0,1,2… if func returns a numpy array. The columns are the index of params.
- Return type
DataFrame
-
estimagic.differentiation.differentiation.hessian(func, params, method='central', extrapolation=True, func_kwargs=None, step_options=None)[source]¶ Calculate the hessian of func.
- Parameters
func (function) – A function that maps params into a float.
params (DataFrame) – see The params Argument
method (string) – The method for the computation of the derivative. Default is central as it gives the highest accuracy.
extrapolation (bool) – Use richardson extrapolations.
func_kwargs (dict) – additional positional arguments for func.
step_options (dict) – Options for the numdifftools step generator. See Influencing the Step Size
- Returns
- The index and columns are the index of params. The data is
the estimated hessian.
- Return type
DataFrame
Influencing the Step Size¶
As mentioned before, we use numdifftools for all numerical differentiations with Richardson extrapolations. numdifftools offers many ways of influencing the step size of the extrapolation:
- base_step (float, array-like, optional):
Defines the maximum step, if None, the value is set to
EPS**(1/scale)``
- step_ratio (float , optional):
Ratio between sequential steps generated. Must be > 1. If None then
step_ratiois 2 for first order derivatives, otherwise it is 1.6
- num_steps (scalar integer, optional):
default
min_num_steps + num_extrap. Defines number of steps generated. It should be larger thanmin_num_steps = (n + order - 1) / factwherefactis 1, 2 or 4 depending on differentiation method used.
- offset (float, optional):
offset to the base step.
- num_extrap (int):
number of points used for extrapolation. Numdifftools Documentation says that the default is 0 but that would be surprising.
- scale (float, array like):
scale used in base step. If not None it will override the default computed with the default_scale function.