Numdifftools

https://numdifftools.readthedocs.io/en/latest/
Admin
Numdifftools provides tools for numerical differentiation and computation of Jacobians, Hessians,...
Tokens:165,618
Snippets:1,189
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Verify Python Installation

Source: https://numdifftools.readthedocs.io/en/latest/_sources/tutorials/install.rst.txt

Check if Python is installed and its version. This output is an example and may vary.

```console
Python 3.6.3 (64-bit)| (default, Oct 15 2017, 03:27:45)
[MSC v.1900 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>>
```

--------------------------------

### Example: Limit of sin(x)/x at x=0

Source: https://numdifftools.readthedocs.io/en/latest/reference/generated/numdifftools.limits.Limit.html

Demonstrates computing the limit of sin(x)/x as x approaches 0. It shows how to get both the limit value and the error estimate.

```python
import numpy as np
from numdifftools.limits import Limit
def f(x): return np.sin(x)/x
lim_f0, err = Limit(f, full_output=True)(0)
print(np.allclose(lim_f0, 1))
print(np.allclose(err.error_estimate, 1.77249444610966e-15))
```

--------------------------------

### BasicMaxStepGenerator Example

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/step_generators.html

Generates a sequence of steps with decreasing magnitudes. Steps are calculated as `base_step * step_ratio ** (-i + offset)`. Useful for methods requiring a decreasing sequence of steps starting from a maximum.

```python
from numdifftools.step_generators import BasicMaxStepGenerator

# Example usage:
step_gen = BasicMaxStepGenerator(base_step=2.0, step_ratio=2, num_steps=4)
steps = [s for s in step_gen()]
print(f"Generated steps: {steps}")
```

--------------------------------

### MinStepGenerator Example

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/step_generators.html

Creates a MinStepGenerator instance with a specified number of steps and scale. This is a basic example demonstrating the instantiation of a step generator.

```python
one_step = MinStepGenerator(num_steps=1, scale=None, step_nom=None)
```

--------------------------------

### LogRule Forward Difference Rule Examples

Source: https://numdifftools.readthedocs.io/en/latest/reference/numdifftools.html

Shows examples of using LogRule with the 'forward' method for error orders 2, 4, and 6. It verifies the computed rule coefficients.

```python
>>> np.allclose(LogRule(n=1, method='forward', order=2).rule(step_ratio=2.), [-1.,  4.])
True

>>> np.allclose(LogRule(n=1, method='forward', order=4).rule(step_ratio=2.),
...             [ -0.04761905,   1.33333333, -10.66666667,  24.38095238])
True
>>> np.allclose(LogRule(n=1, method='forward', order=6).rule(step_ratio=2.),
...    [ -1.02406554e-04,   1.26984127e-02,  -5.07936508e-01,
...       8.12698413e+00,  -5.20126984e+01,   1.07381055e+02])
True
```

--------------------------------

### Install Sphinx for HTML documentation

Source: https://numdifftools.readthedocs.io/en/latest/_sources/tutorials/whatsnext.rst.txt

Install the Sphinx documentation generator using pip, which is required to build the HTML version of the numdifftools documentation.

```console
$ pip install Sphinx
```

--------------------------------

### BasicMinStepGenerator Example

Source: https://numdifftools.readthedocs.io/en/latest/reference/numdifftools.html

Generates a sequence of steps with decreasing magnitudes ending at a minimum step. This is useful when a specific minimum step size is required.

```python
>>> from numdifftools.step_generators import BasicMinStepGenerator
>>> step_gen = BasicMinStepGenerator(base_step=0.25, step_ratio=2,
...                                  num_steps=4)
>>> [s for s in step_gen()]
[2.0, 1.0, 0.5, 0.25]
```

--------------------------------

### Verify Python Installation

Source: https://numdifftools.readthedocs.io/en/latest/tutorials/install.html

This code block shows the expected output when verifying a Python installation from the command shell.

```text
Python 3.6.3 (64-bit)| (default, Oct 15 2017, 03:27:45)
[MSC v.1900 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>>

```

--------------------------------

### Start pydoc HTTP server

Source: https://numdifftools.readthedocs.io/en/latest/tutorials/whatsnext.html

Run pydoc with the -b flag to start an HTTP server for accessing documentation via a web browser. This also opens a browser to the module index page.

```bash
$ pydoc -b

```

--------------------------------

### Start pydoc HTTP server

Source: https://numdifftools.readthedocs.io/en/latest/_sources/tutorials/whatsnext.rst.txt

Run pydoc with the -b flag to start an HTTP server and open a web browser to the module index page. Type 'quit' to stop the server.

```console
$ pydoc -b 
```

```console
$ quit 
```

--------------------------------

### Install numdifftools

Source: https://numdifftools.readthedocs.io/en/latest/_sources/tutorials/install.rst.txt

Install the latest stable version of numdifftools using pip. This command also installs all required dependencies.

```console
$ pip install numdifftools
```

--------------------------------

### Gradient Initialization and Usage

Source: https://numdifftools.readthedocs.io/en/latest/reference/generated/numdifftools.core.Gradient.html

Demonstrates how to initialize the Gradient class with a function and compute its gradient. The example shows calculating the gradient of the Rosenbrock function at its minimum.

```APIDOC
## Gradient

### Description
Computes the gradient of a scalar function of one or more variables.

### Method Signature
`Gradient(fun, step=None, method='central', order=2, n=1, **options)`

### Parameters
*   **fun** (callable) - The function for which to compute the gradient.
*   **step** (float or array_like, optional) - The step spacing(s) used in the approximation. Defaults to None.
*   **method** (str, optional) - Defines the method used in the finite difference approximation. Defaults to 'central'.
*   **order** (int, optional) - Defines the order of the error term in the Taylor approximation used. Defaults to 2.
*   **n** (int, optional) - Order of the derivative. Defaults to 1.
*   **options** - Additional keyword arguments.

### Methods
*   `__init__(fun, step=None, method='central', order=2, n=1, **options)`: Initializes the Gradient object.
*   `set_richardson_rule(step_ratio, num_terms)`: Set Richardson extrapolation options.

### Attributes
*   `method`: Defines the method used in the finite difference approximation.
*   `method_order`: Defines the leading order of the error term in the Richardson extrapolation method.
*   `n`: Order of the derivative.
*   `order`: Defines the order of the error term in the Taylor approximation used.
*   `step`: The step spacing(s) used in the approximation.

### Example
```python
import numdifftools as nd
import numpy as np

# Define the Rosenbrock function
rosen = lambda x : (1-x[0])**2 + 105.*(x[1]-x[0]**2)**2

# Compute the gradient
grad_rosen = nd.Gradient(rosen)

# Evaluate the gradient at a point (e.g., the minimum [1, 1])
x, y = 1, 1
df_dx, df_dy = grad_rosen([x, y])

# Check if the gradient is close to zero
print(np.allclose([df_dx, df_dy], [0, 0]))
# Expected output: True
```
```

--------------------------------

### LogJacobianRule Examples

Source: https://numdifftools.readthedocs.io/en/latest/reference/numdifftools.html

Illustrates the use of LogJacobianRule for calculating finite difference Jacobian rules. It demonstrates different orders and methods, verifying results with numpy.allclose.

```python
from numdifftools.finite_difference import LogJacobianRule as Rule
```

```python
np.allclose(Rule(n=1, method='central', order=2).rule(step_ratio=2.0), 1)
```

```python
np.allclose(Rule(n=1, method='central', order=4).rule(step_ratio=2.),
            [-0.33333333,  2.66666667])
```

```python
np.allclose(Rule(n=1, method='central', order=6).rule(step_ratio=2.),
            [ 0.02222222, -0.88888889,  5.68888889])
```

```python
np.allclose(Rule(n=1, method='forward', order=2).rule(step_ratio=2.), [-1.,  4.])
```

```python
np.allclose(Rule(n=1, method='forward', order=4).rule(step_ratio=2.),
            [ -0.04761905,   1.33333333, -10.66666667,  24.38095238])
```

--------------------------------

### BasicMaxStepGenerator Example

Source: https://numdifftools.readthedocs.io/en/latest/reference/generated/numdifftools.step_generators.BasicMaxStepGenerator.html

Demonstrates how to create and use BasicMaxStepGenerator to generate a sequence of decreasing steps. The generator produces steps based on a base step, a step ratio, and the number of steps.

```python
from numdifftools.step_generators import BasicMaxStepGenerator
step_gen = BasicMaxStepGenerator(base_step=2.0, step_ratio=2,
                                 num_steps=4)
[s for s in step_gen()]

```

--------------------------------

### Build HTML Documentation with Make

Source: https://numdifftools.readthedocs.io/en/latest/tutorials/whatsnext.html

Generate local HTML documentation from plain text using the included Makefile. Navigate to the docs directory and run 'make html'. This requires GNU Make to be installed.

```bash
$ cd path/to/numdifftools/docs
$ make html

```

--------------------------------

### Test numdifftools Installation

Source: https://numdifftools.readthedocs.io/en/latest/_sources/tutorials/install.rst.txt

Run doctests to confirm that the numdifftools toolbox is functioning correctly.

```python
nd.test('--doctest-module')
```

--------------------------------

### Import numdifftools and Check Version

Source: https://numdifftools.readthedocs.io/en/latest/_sources/tutorials/install.rst.txt

Verify that numdifftools is installed and accessible by importing it in Python and printing its version.

```python
>>> import numdifftools as nd
>>> print(nd.__version__)
|release|
```

--------------------------------

### Numerical Integration Example

Source: https://numdifftools.readthedocs.io/en/latest/reference/numdifftools.html

This snippet demonstrates numerical integration of sin(x) from 0 to pi/2 using the trapz function and numdifftools for error estimation.

```python
>>> import numpy as np
>>> import numdifftools as nd
>>> Ei= np.zeros(3)
>>> linfun = lambda i : np.linspace(0, np.pi/2., 2**(i+5)+1)
>>> for k in np.arange(3):
...    x = linfun(k)
...    Ei[k] = trapz(np.sin(x),x)
>>> [En, err] = nd.dea3(Ei[0], Ei[1], Ei[2])
>>> truErr = np.abs(En-1.)
>>> bool(np.all(truErr < err))
True
>>> np.allclose(En, 1)
True
>>> bool(np.all(np.abs(Ei-1)<1e-3))
True

```

--------------------------------

### Example: Derivative of cos(x) at x=pi/2

Source: https://numdifftools.readthedocs.io/en/latest/reference/generated/numdifftools.limits.Limit.html

Illustrates computing the derivative of cos(x) at x = pi/2 by finding the limit of the difference quotient. The expected result is -1.

```python
x0 = np.pi/2
def g(x): return (np.cos(x0+x)-np.cos(x0))/x
lim_g0, err = Limit(g, full_output=True)(0)
print(np.allclose(lim_g0, -1))
print(bool(err.error_estimate < 1e-14))
```

--------------------------------

### Derivative Class Example

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/nd_algopy.html

Demonstrates calculating the 1st and 5th derivatives of exp(x) and the 1st derivative of x^3 + x^4 using the Derivative class.

```Python
import numpy as np
import numdifftools.nd_algopy as nda
fd = nda.Derivative(np.exp)              # 1'st derivative
print(np.allclose(fd(1), 2.718281828459045))
fd5 = nda.Derivative(np.exp, n=5)         # 5'th derivative
print(np.allclose(fd5(1), 2.718281828459045))

fun = lambda x: x**3 + x**4
fd3 = nda.Derivative(fun)
print(np.allclose(fd3([0,1]), [ 0.,  7.]))
```

--------------------------------

### Estimate Derivative with Small Step Size

Source: https://numdifftools.readthedocs.io/en/latest/src/numerical/derivest.html

This example demonstrates the impact of forcing a very small step size (step=1e-10) on the derivative estimation of exp(x) at x=1, showing how noise can dominate the result.

```python
f = nd.Derivative(exp, step=1e-10, full_output=True)
val, info = f(1)
np.allclose(val, 2.71828093)
np.allclose(val - exp(1), -8.97648138e-07)
np.allclose(info.final_step, 1.0000000e-10)

```

--------------------------------

### Gradient Class Example

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/nd_algopy.html

Demonstrates calculating the gradient of a sum of squares function and a more complex function involving sin and exp.

```Python
import numpy as np
import numdifftools.nd_algopy as nda
fun = lambda x: np.sum(x**2)
df = nda.Gradient(fun, method='reverse')
print(np.allclose(df([1,2,3]), [ 2.,  4.,  6.]))

sin = np.sin; exp = np.exp
z = lambda xy: sin(xy[0]-xy[1]) + xy[1]*exp(xy[0])
dz = nda.Gradient(z)
grad2 = dz([1, 1])
print(np.allclose(grad2, [ 3.71828183,  1.71828183]))
```

--------------------------------

### LogRule Forward Difference Rule Examples

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/finite_difference.html

Illustrates the use of LogRule for forward difference approximations. The `rule` method calculates the coefficients for the finite difference approximation.

```python
np.allclose(LogRule(n=1, method='forward', order=2).rule(step_ratio=2.), [-1.,  4.])
True
```

```python
np.allclose(LogRule(n=1, method='forward', order=4).rule(step_ratio=2.),
            [ -0.04761905,   1.33333333, -10.66666667,  24.38095238])
True
```

```python
np.allclose(LogRule(n=1, method='forward', order=6).rule(step_ratio=2.),
   [ -1.02406554e-04,   1.26984127e-02,  -5.07936508e-01,
      8.12698413e+00,  -5.20126984e+01,   1.07381055e+02])
True
```

--------------------------------

### Calculate Jacobian of a multi-output function

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/nd_algopy.html

Shows how to compute the Jacobian for a function that returns multiple outputs. Includes examples with different input arrays.

```python
import numdifftools.nd_algopy as nda
import numpy as np

def fun3(x):
    n = int(np.prod(np.shape(x[0])))
    out = nda.algopy.zeros((2, n), dtype=x)
    out[0] = x[0]*x[1]*x[2]**2
    out[1] = x[0]*x[1]*x[2]
    return out

Jfun3 = nda.Jacobian(fun3)

print(np.allclose(Jfun3([1., 2., 3.]), [[[18., 9., 12.]], [[6., 3., 2.]]]))
print(np.allclose(Jfun3([4., 5., 6.]), [[[180., 144., 240.]],
                                      [[30., 24., 20.]]]))
print(np.allclose(Jfun3(np.array([[1.,2.,3.], [4., 5., 6.]]).T),
            [[[18.,    0.,    9.,    0.,   12.,    0.],
              [0.,  180.,    0.,  144.,    0.,  240.]],
             [[6.,    0.,    3.,    0.,    2.,    0.],
              [0.,   30.,    0.,   24.,    0.,   20.]]]))

```

--------------------------------

### Example: Limit with subtractive cancellation

Source: https://numdifftools.readthedocs.io/en/latest/reference/generated/numdifftools.limits.Limit.html

Demonstrates computing a limit where significant subtractive cancellation occurs at the limit point. The true limit is expected to be 0.5.

```python
def k(x): return (x*np.exp(x)-np.expm1(x))/x**2
lim_k0,err = Limit(k, full_output=True)(0)
print(np.allclose(lim_k0, 0.5))
print(bool(err.error_estimate < 1.0e-8))
```

--------------------------------

### Define Example Functions for Testing

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/tests/test_fornberg.html

Defines a class `ExampleFunctions` containing various static methods, each representing a different mathematical function. These functions are used for testing derivative calculations.

```python
class ExampleFunctions(object):


    @staticmethod
    def fun0(z):
        return np.exp(z)


    @staticmethod
    def fun1(z):
        return np.exp(z) / (np.sin(z) ** 3 + np.cos(z) ** 3)


    @staticmethod
    def fun2(z):
        return np.exp(1.0j * z)


    @staticmethod
    def fun3(z):
        return z**6


    @staticmethod
    def fun4(z):
        return z * (0.5 + 1.0 / np.expm1(z))


    @staticmethod
    def fun5(z):
        return np.tan(z)


    @staticmethod
    def fun6(z):
        return 1.0j + z + 1.0j * z**2


    @staticmethod
    def fun7(z):
        return 1.0 / (1.0 - z)


    @staticmethod
    def fun8(z):
        return (1 + z) ** 10 * np.log1p(z)


    @staticmethod
    def fun9(z):
        return 10 * 5 + 1.0 / (1 - z)


    @staticmethod
    def fun10(z):
        return 1.0 / (1 - z)


    @staticmethod
    def fun11(z):
        return np.sqrt(z)


    @staticmethod
    def fun12(z):
        return np.arcsinh(z)


    @staticmethod
    def fun13(z):
        return np.cos(z)


    @staticmethod
    def fun14(z):
        return np.log1p(z)
```

--------------------------------

### Richardson Extrapolation Example

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/extrapolation.html

Demonstrates the use of the Richardson extrapolation class to improve the accuracy of numerical integration. It compares the extrapolated result with the true error and checks for convergence.

```python
import numpy as np
import numdifftools as nd
n = 3
Ei = np.zeros((n,1))
h = np.zeros((n,1))
linfun = lambda i : np.linspace(0, np.pi/2., 2**(i+5)+1)
for k in np.arange(n):
   x = linfun(k)
   h[k] = x[1]
   Ei[k] = trapz(np.sin(x),x)
En, err, step = nd.Richardson(step=1, order=1)(Ei, h)
truErr = np.abs(En-1.)
bool(np.all(truErr < err))
bool(np.all(np.abs(Ei-1)<1e-3))
np.allclose(En, 1)
```

--------------------------------

### LogHessdiagRule Examples

Source: https://numdifftools.readthedocs.io/en/latest/reference/numdifftools.html

Demonstrates the usage of LogHessdiagRule for calculating finite difference rules with different methods and orders. It shows how to apply the rule with various step ratios and verifies the results using numpy.allclose.

```python
import numpy as np
from numdifftools.finite_difference import LogHessdiagRule as Rule
```

```python
np.allclose(Rule(method='central', order=2).rule(step_ratio=2.0), 2)
```

```python
np.allclose(Rule(method='central', order=4).rule(step_ratio=2.),
            [-0.66666667, 10.66666667])
```

```python
np.allclose(Rule(method='central', order=6).rule(step_ratio=2.),
            [ 4.44444444e-02, -3.55555556e+00,  4.55111111e+01])
```

```python
np.allclose(Rule(method='forward', order=2).rule(step_ratio=2.), [ -4.,  40., -64.])
```

```python
np.allclose(Rule(method='forward', order=4).rule(step_ratio=2.),
         [-1.90476190e-01,  1.10476190e+01, -1.92000000e+02,
         1.12152381e+03, -1.56038095e+03])
```

```python
np.allclose(Rule(method='forward', order=6).rule(step_ratio=2.),
   [-4.09626216e-04,  1.02406554e-01, -8.33015873e+00,  2.76317460e+02,
    -3.84893968e+03,  2.04024004e+04, -2.74895500e+04])
```

```python
step_ratio=2.0
fd_rule = Rule(method='forward', order=4)
steps = 0.002*(1./step_ratio)**np.arange(6)
x0 = np.array([0., 0.])
f = lambda xy : np.cos(xy[0]-xy[1])
f_x0 = f(x0)
f_del = [f(x0+h) - f_x0  for h in steps] # forward difference
f_del = [fd_rule.diff(f, f_x0, x0, h) for h in steps]  # or alternatively
fder, h, shape = fd_rule.apply(f_del, steps, step_ratio)
```

```python
np.allclose(fder, [[-1., -1.], [-1., -1.]])
```

--------------------------------

### LogRule Central Difference Rule Examples

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/finite_difference.html

Demonstrates the application of LogRule for central difference approximations with varying orders of accuracy. The `rule` method returns the coefficients for the finite difference approximation.

```python
from numdifftools.finite_difference import LogRule
np.allclose(LogRule(n=1, method='central', order=2).rule(step_ratio=2.0), 1)
True
```

```python
np.allclose(LogRule(n=1, method='central', order=4).rule(step_ratio=2.),
            [-0.33333333,  2.66666667])
True
```

```python
np.allclose(LogRule(n=1, method='central', order=6).rule(step_ratio=2.),
            [ 0.02222222, -0.88888889,  5.68888889])
True
```

--------------------------------

### Build HTML Documentation with Make on Windows

Source: https://numdifftools.readthedocs.io/en/latest/tutorials/whatsnext.html

On Windows, use the included batch file 'make.bat' to generate local HTML documentation. Navigate to the docs directory and execute 'make.bat html'.

```bash
$ cd path\to\numdifftools\docs
$ make.bat html

```

--------------------------------

### Install Packages into a Virtual Environment

Source: https://numdifftools.readthedocs.io/en/latest/_sources/how-to/create_virtual_env_with_conda.rst.txt

Add new packages to a specific conda virtual environment. Ensure you specify the environment name with '-n yourenvname' to avoid installing into the root Python installation. Replace '[package]' with the package name.

```bash
conda install -n yourenvname [package]
```

--------------------------------

### Check Conda Installation

Source: https://numdifftools.readthedocs.io/en/latest/_sources/how-to/create_virtual_env_with_conda.rst.txt

Verify if conda is installed and accessible by checking its version. This command should be run in a terminal client.

```bash
conda -V
```

--------------------------------

### Build HTML documentation with Make

Source: https://numdifftools.readthedocs.io/en/latest/_sources/tutorials/whatsnext.rst.txt

Navigate to the numdifftools documentation directory and use the `make html` command to generate local HTML documentation. Requires GNU Make.

```console
$ cd path/to/numdifftools/docs
$ make html
```

--------------------------------

### Calculate First Derivative and Output Info

Source: https://numdifftools.readthedocs.io/en/latest/_sources/topics/finite_difference_derivatives.rst.txt

Demonstrates how to compute the first derivative of a function using a specified step size and retrieve detailed output information, including the final step size used.

```python
import numdifftools as nd
from numpy import exp, allclose

f = nd.Derivative(exp, step=1e-10, full_output=True)
val, info = f(1)
print(allclose(val, 2.71828093))
print(allclose(val - exp(1), -8.97648138e-07))
print(allclose(info.final_step, 1.0000000e-10))
```

--------------------------------

### Install Packages into a Conda Environment

Source: https://numdifftools.readthedocs.io/en/latest/how-to/create_virtual_env_with_conda.html

Add new packages to a specific Conda environment. Omitting '-n yourenvname' will install the package into the base environment.

```bash
conda install -n yourenvname [package]

```

--------------------------------

### High-Order Derivative Approximation Setup

Source: https://numdifftools.readthedocs.io/en/latest/src/numerical/derivest.html

This system of linear equations is used to construct high-order derivative approximations. By inserting three different step sizes (δ, δ/2, δ/4) into the odd-order Taylor expansion, we can solve for the coefficients of the derivative and its higher-order odd terms.

```mathematica
[113!15!1213!2315!251413!4315!45][δf′(x0)δ3f(3)(x0)δ5f(5)(x0)]=[fodd(δ)fodd(δ/2)fodd(δ/4)]
```

--------------------------------

### DEA3 Extrapolation Example

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/extrapolation.html

Example demonstrating the use of the dea3 function for extrapolating a slowly convergent sequence. It integrates sin(x) from 0 to pi/2 and uses dea3 to obtain a more accurate estimate of the integral's limit.

```python
import numpy as np
import numdifftools as nd
from scipy.integrate import trapz

Ei= np.zeros(3)
linfun = lambda i : np.linspace(0, np.pi/2., 2**(i+5)+1)
for k in np.arange(3):
   x = linfun(k)
   Ei[k] = trapz(np.sin(x),x)
[En, err] = nd.dea3(Ei[0], Ei[1], Ei[2])
truErr = np.abs(En-1.)
print(bool(np.all(truErr < err)))
print(np.allclose(En, 1))
print(bool(np.all(np.abs(Ei-1)<1e-3)))
```

--------------------------------

### BasicMinStepGenerator Example

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/step_generators.html

Generates a sequence of steps with decreasing magnitudes, but in reverse order compared to `BasicMaxStepGenerator`. Steps are calculated as `base_step * step_ratio ** (i + offset)`, where `i` counts down. Useful for methods requiring an increasing sequence of steps ending at a minimum.

```python
from numdifftools.step_generators import BasicMinStepGenerator

# Example usage:
step_gen = BasicMinStepGenerator(base_step=0.25, step_ratio=2, num_steps=4)
steps = [s for s in step_gen()]
print(f"Generated steps: {steps}")
```

--------------------------------

### Test Low Order Derivative on Example Functions

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/tests/test_fornberg.html

Iterates through a list of predefined example functions and calculates their low-order derivatives using the `derivative` function. It prints the computed derivatives, error estimates, and function counts for each function. Requires `numdifftools.fornberg.derivative`.

```python
def test_low_order_derivative_on_example_functions():
    for j in range(15):
        fun = getattr(ExampleFunctions, "fun{}".format(j))
        der, info = derivative(fun, z0=0.0, r=0.06, n=10, max_iter=30, full_output=True, step_ratio=1.6)
        print(info)
        print("answer:")
        msg = "{0:3d}: {1:24.18f} + {2:24.18f}j ({3:g})"
        print(info.function_count)
        for i, der_i in enumerate(der):
            err = info.error_estimate[i]
            print(msg.format(i, der_i.real, der_i.imag, err))
```

--------------------------------

### Upgrade Pip

Source: https://numdifftools.readthedocs.io/en/latest/_sources/tutorials/install.rst.txt

Ensure you have the latest version of pip for reliable installations.

```console
$ pip install --upgrade pip
```

--------------------------------

### Epsilon Algorithm (Epsalg) Demo

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/extrapolation.html

Demonstrates the epsilon algorithm (epsalg) for accelerating sequence convergence. It applies the algorithm to the sequence of trapezoidal approximations of the integral of sin(x).

```python
from numdifftools.extrapolation import EpsAlg
import numpy as np
from scipy.integrate import trapz

def linfun(i):
    return np.linspace(0, np.pi / 2.0, 2**i + 1)

dea = EpsAlg()
print("NO. PANELS      TRAP. APPROX          APPROX W/EA           abserr")
txt = "{0:5d} {1:20.8f}  {2:20.8f}  {3:20.8f}"
for k in np.arange(10):
    x = linfun(k)
    val = trapz(np.sin(x), x)
    vale = dea(val)
    err = np.abs(1.0 - vale)
    print(txt.format(len(x) - 1, val, vale, err))
```

--------------------------------

### Upgrade Pip

Source: https://numdifftools.readthedocs.io/en/latest/tutorials/install.html

Ensure your pip installer is up-to-date for better reliability by running this command in your shell.

```bash
$ pip install --upgrade pip

```

--------------------------------

### Example: Another difficult limit

Source: https://numdifftools.readthedocs.io/en/latest/reference/generated/numdifftools.limits.Limit.html

Computes a limit involving subtractive cancellation, where the true limit is 1/6.

```python
def h(x): return  (x-np.sin(x))/x**3
lim_h0, err = Limit(h, full_output=True)(0)
print(np.allclose(lim_h0, 1./6))
print(bool(err.error_estimate < 1e-8))
```

--------------------------------

### Directional Derivative Example

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/nd_algopy.html

Computes the directional derivative of the Rosenbrock function at its global minimizer. Requires numpy and numdifftools.nd_algopy.

```python
import numpy as np
import numdifftools.nd_algopy as nda
vec = np.r_[1, 2]
rosen = lambda x: (1-x[0])**2 + 105*(x[1]-x[0]**2)**2
dd = nda.directionaldiff(rosen, [1, 1], vec)
np.allclose(dd, 0)
```

--------------------------------

### Build HTML documentation with Make on Windows

Source: https://numdifftools.readthedocs.io/en/latest/_sources/tutorials/whatsnext.rst.txt

On Windows, use the included `make.bat html` command to generate local HTML documentation from the numdifftools documentation directory.

```bat
$ cd path\to\numdifftools\docs
$ make.bat html
```

--------------------------------

### Generate Decreasing Steps with BasicMinStepGenerator

Source: https://numdifftools.readthedocs.io/en/latest/reference/generated/numdifftools.step_generators.BasicMinStepGenerator.html

Demonstrates how to instantiate and use BasicMinStepGenerator to create a sequence of steps. The steps decrease in magnitude based on the provided base_step, step_ratio, and num_steps.

```python
from numdifftools.step_generators import BasicMinStepGenerator
step_gen = BasicMinStepGenerator(base_step=0.25, step_ratio=2,
                                 num_steps=4)
[s for s in step_gen()]
[2.0, 1.0, 0.5, 0.25]
```

--------------------------------

### Jacobian for a multi-output function

Source: https://numdifftools.readthedocs.io/en/latest/reference/generated/numdifftools.nd_scipy.Jacobian.html

Calculates the Jacobian for a function that returns a vector. This example shows how to handle functions with multiple outputs.

```python
fun3 = lambda x : np.vstack((x[0]*x[1]*x[2]**2, x[0]*x[1]*x[2]))

# TODO: The following does not work:
# der3 = nd.Jacobian(fun3)([1., 2., 3.])
# np.allclose(der3, ... [[18., 9., 12.], [6., 3., 2.]])
# True
# np.allclose(nd.Jacobian(fun3)([4., 5., 6.]), ... [[180., 144., 240.], [30., 24., 20.]])
# True
np.allclose(nd.Jacobian(fun3)(np.array([[1.,2.,3.], [4., 5., 6.]]).T), ... [[[ 18., 180.], ... [ 9., 144.], ... [ 12., 240.]], ... [[ 6., 30.], ... [ 3., 24.], ... [ 2., 20.]]])
True
```

--------------------------------

### Initialize MinStepGenerator

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/step_generators.html

Initializes the MinStepGenerator with various parameters to control step generation. Parameters include base_step, step_ratio, num_steps, step_nom, offset, num_extrap, check_num_steps, use_exact_steps, and scale.

```python
min_num_steps = (n + order - 1) / fact where fact is 1, 2 or 4
        depending on differentiation method used.
    step_nom :  default maximum(log(exp(1)+|x|), 1)
        Nominal step where x is supplied at runtime through the __call__ method.
    offset : real scalar, optional, default 0
        offset to the base step
    num_extrap : scalar integer, default 0
        number of points used for extrapolation
    check_num_steps : boolean, default True
        If True make sure num_steps is larger than the minimum required steps.
    use_exact_steps : boolean, default True
        If true make sure exact steps are generated
    scale : real scalar, optional
        scale used in base step. If not None it will override the default
        computed with the default_scale function.
    """

    _step_generator = BasicMinStepGenerator



[docs]
def __init__(
        self,
        base_step=None,
        step_ratio=None,
        num_steps=None,
        step_nom=None,
        offset=0,
        num_extrap=0,
        use_exact_steps=True,
        check_num_steps=True,
        scale=None,
    ):
        self.base_step = base_step
        self.step_nom = step_nom
        self.num_steps = num_steps
        self.step_ratio = step_ratio
        self.offset = offset
        self.num_extrap = num_extrap
        self.check_num_steps = check_num_steps
        self.use_exact_steps = use_exact_steps
        self.scale = scale

        self._state = _STATE(x=np.asarray(1), method="forward", n=1, order=2)
```

--------------------------------

### Richardson Extrapolation Demo

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/extrapolation.html

Demonstrates the Richardson extrapolation process using the Richardson class to approximate the integral of sin(x). It shows how the approximation improves with an increasing number of panels.

```python
from numdifftools.extrapolation import Richardson
import numpy as np
from scipy.integrate import trapz

def linfun(i):
    return np.linspace(0, np.pi / 2.0, 2**i + 1)

h = []
e_i = []

print("NO. PANELS      TRAP. APPROX          APPROX W/R            abserr")
txt = "{0:5d} {1:20.8f}  {2:20.8f}  {3:20.8f}"
for k in np.arange(10):
    x = linfun(k)
    val = trapz(np.sin(x), x)
    h.append(x[1])
    e_i.append(val)
    vale, _err0, _step = Richardson(step=1, order=1)(np.array(e_i), np.array(h))

    err = np.abs(1.0 - vale)
    print(txt.format(len(x) - 1, val, vale[-1], err[-1]))
```

--------------------------------

### Semi-Definite Hessian Matrix Example

Source: https://numdifftools.readthedocs.io/en/latest/_sources/tutorials/getting_started.rst.txt

Computes the Hessian matrix for the cosine function and checks for eigenvalues close to zero, indicating semi-definiteness.

```python
import numpy as np
import numdifftools as nd
H = nd.Hessian(lambda xy: np.cos(xy[0] - xy[1]))([0, 0])
[abs(val) < 1e-12 for val in np.linalg.eig(H)[0]]
```

--------------------------------

### Richardson Extrapolation Demo

Source: https://numdifftools.readthedocs.io/en/latest/reference/numdifftools.html

Runs a demonstration of Richardson extrapolation using `richardson_demo`. Compares trapezoidal approximations with Richardson extrapolation results and their errors.

```python
from numdifftools.extrapolation import richardson_demo
richardson_demo()
```

--------------------------------

### Derivative Calculation Example

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/core.html

Demonstrates how to calculate the n-th derivative of a function using the Derivative class. It shows basic usage with default parameters.

```python
import numdifftools as nd
import numpy as np

def f(x):
    return np.sin(x)

derivative_calculator = nd.Derivative(f)
derivative_at_pi_over_2 = derivative_calculator(np.pi/2)
print(f"The derivative of sin(x) at pi/2 is: {derivative_at_pi_over_2}")

# Calculate the second derivative
second_derivative_calculator = nd.Derivative(f, n=2)
second_derivative_at_pi_over_2 = second_derivative_calculator(np.pi/2)
print(f"The second derivative of sin(x) at pi/2 is: {second_derivative_at_pi_over_2}")
```

--------------------------------

### Calculate Jacobian for a 2D array input

Source: https://numdifftools.readthedocs.io/en/latest/reference/numdifftools.html

Example of calculating the Jacobian when the input to the function is a 2D array, transposed for processing. Uses numdifftools and numpy.

```python
>>> import numpy as np
>>> import numdifftools.nd_statsmodels as nd
>>> fun3 = lambda x : np.vstack((x[0]*x[1]*x[2]**2, x[0]*x[1]*x[2]))
>>> np.allclose(nd.Jacobian(fun3)(np.array([[1.,2.,3.], [4., 5., 6.]]).T),
...            [[[  18.,  180.],
...              [   9.,  144.],
...              [  12.,  240.]],
...             [[   6.,   30.],
...              [   3.,   24.],
...              [   2.,   20.]]])
True
```

--------------------------------

### Epsilon Algorithm Demo

Source: https://numdifftools.readthedocs.io/en/latest/reference/numdifftools.html

Executes a demonstration of the Epsilon Algorithm using `epsalg_demo`. Displays trapezoidal approximations and their corresponding errors.

```python
from numdifftools.extrapolation import epsalg_demo
epsalg_demo()
```

--------------------------------

### Applying a LogRule Forward Difference Rule

Source: https://numdifftools.readthedocs.io/en/latest/reference/numdifftools.html

Demonstrates applying a LogRule with the 'forward' method to calculate derivatives. It includes manual difference calculation and using the Rule's diff method.

```python
>>> step_ratio=2.0
>>> fd_rule = LogRule(n=2, method='forward', order=4)
>>> h = 0.002*(1./step_ratio)**np.arange(6)
>>> x0 = 1.
>>> f = np.exp
>>> f_x0 = f(x0)
>>> f_del = f(x0+h) - f_x0  # forward difference
>>> f_del = fd_rule.diff(f, f_x0, x0, h)  # or alternatively
>>> fder, h, shape = fd_rule.apply(f_del, h, step_ratio)
>>> np.allclose(fder, f(x0))
True
```

--------------------------------

### Limit Class Initialization and Usage

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/limits.html

Demonstrates how to initialize and use the `Limit` class to compute the limit of a function. It takes a callable function, step generator, and method ('above' or 'below') as parameters.

```python
class Limit(_Limit):
    """
    Compute limit of a function at a given point

    Parameters
    ----------
    fun : callable
        function fun(z, `*args`, `**kwds`) to compute the limit for z->z0.
        The function, fun, is assumed to return a result of the same shape and
        size as its input, `z`.
    step: float, complex, array-like or StepGenerator object, optional
        Defines the spacing used in the approximation.
        Default is CStepGenerator(base_step=step, **options)
    method : {'above', 'below'}
        defines if the limit is taken from `above` or `below`
    order: positive scalar integer, optional.
        defines the order of approximation used to find the specified limit.
        The order must be member of [1 2 3 4 5 6 7 8]. 4 is a good compromise.
    full_output: bool
        If true return additional info.
    options:
        options to pass on to CStepGenerator

    Returns
    -------
    limit_fz: array like
        estimated limit of f(z) as z --> z0
    info:
        Only given if full_output is True and contains the following:

        error estimate: ndarray
            95 % uncertainty estimate around the limit, such that
            abs(limit_fz - lim z->z0 f(z)) < error_estimate
        final_step: ndarray
            final step used in approximation

    Notes
    -----
    `Limit` computes the limit of a given function at a specified
    point, z0. When the function is evaluable at the point in question,
    this is a simple task. But when the function cannot be evaluated
    at that location due to a singularity, you may need a tool to
    compute the limit. `Limit` does this, as well as produce an
    uncertainty estimate in the final result.

    The methods used by `Limit` are Richardson extrapolation in a combination
    with Wynn's epsilon algorithm which also yield an error estimate.
    The user can specify the method order, as well as the path into
    z0. z0 may be real or complex. `Limit` uses a proportionally cascaded
    
```

--------------------------------

### Calculate Jacobian using numdifftools.nd_algopy

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/nd_algopy.html

Demonstrates calculating the Jacobian of a function using the Jacobian class. It shows examples with default method and 'reverse' method.

```python
import numdifftools.nd_algopy as nda
import numpy as np

def fun(x):
    return x[0]*x[1]*x[2]**2

Jfun2 = nda.Jacobian(fun)
print(np.allclose(Jfun2([1., 2., 3.]), [[ 18., 9., 12.]]))

Jfun21 = nda.Jacobian(fun, method='reverse')
print(np.allclose(Jfun21([1., 2., 3.]), [[ 18., 9., 12.]]))

```

--------------------------------

### _Limit Initialization

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/limits.html

Initializes the _Limit base class, setting up the step generator and a Richardson extrapolation object. The step parameter can be a step generator instance or a tuple containing the step value and associated options.

```python
def __init__(self, step=None, **options):
        self.step = step, options

        self.richardson = Richardson(step_ratio=1.6, step=1, order=1, num_terms=2)
```

--------------------------------

### Running Docstring Tests

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/step_generators.html

Executes the docstring tests for the numdifftools library. This is typically run as part of a testing suite to ensure documentation examples are correct.

```python
from numdifftools.testing import test_docstrings

test_docstrings()
```

--------------------------------

### CStepGenerator Initialization

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/limits.html

Initializes the CStepGenerator with various parameters to control step generation for limit calculations. Options like 'path' and 'dtheta' can be passed to customize the step generation strategy.

```python
def __init__(
        self,
        base_step=None,
        step_ratio=4.0,
        num_steps=None,
        step_nom=None,
        offset=0,
        scale=1.2,
        **options
    ):
        self.path = options.pop("path", "radial")
        self.dtheta = options.pop("dtheta", np.pi / 8)
        super(CStepGenerator, self).__init__(
            base_step=base_step,
            step_ratio=step_ratio,
            num_steps=num_steps,
            step_nom=step_nom,
            offset=offset,
            scale=scale,
            **options,
        )
        self._check_path()
```

--------------------------------

### Gradient Example: Rosenbrock Function

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/nd_scipy.html

Computes the gradient of the Rosenbrock function at its global minimizer. The gradient should be close to zero, demonstrating the accuracy of the numerical approximation.

```python
rosen = lambda x : (1-x[0])**2 + 105.*(x[1]-x[0]**2)**2
rd = nd.Gradient(rosen)
grad3 = rd([1,1])
np.allclose(grad3,[0, 0], atol=1e-7)
```

--------------------------------

### Gradient Example: Sum of Squares

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/nd_scipy.html

Demonstrates calculating the gradient of a simple function that sums the squares of its input elements. The Gradient class is used for this purpose.

```python
import numpy as np
import numdifftools.nd_scipy as nd

fun = lambda x: np.sum(x**2)
dfun = nd.Gradient(fun)
np.allclose(dfun([1,2,3]), [ 2.,  4.,  6.])
```

--------------------------------

### Jacobian Example: Simple Scalar Function

Source: https://numdifftools.readthedocs.io/en/latest/_modules/numdifftools/nd_scipy.html

Illustrates computing the Jacobian of a simple scalar function of three variables. The function is defined, and its Jacobian is calculated.

```python
fun2 = lambda x : x[0]*x[1]*x[2]**2
dfun2 = nd.Jacobian(fun2)
np.allclose(dfun2([1.,2.,3.]), [[18., 9., 12.]])
```

--------------------------------

### Calculate Jacobian of a function returning a stacked array

Source: https://numdifftools.readthedocs.io/en/latest/reference/numdifftools.html

Shows how to compute the Jacobian when the function returns a vertically stacked array. This example uses numdifftools and numpy.

```python
>>> import numpy as np
>>> import numdifftools.nd_statsmodels as nd
>>> fun3 = lambda x : np.vstack((x[0]*x[1]*x[2]**2, x[0]*x[1]*x[2]))
>>> np.allclose(nd.Jacobian(fun3)([1., 2., 3.]), [[[18.], [9.], [12.]], [[6.], [3.], [2.]]])
True
>>> np.allclose(nd.Jacobian(fun3)([4., 5., 6.]),
...            [[[180.], [144.], [240.]], [[30.], [24.], [20.]]])
True
```
Tokens:
Raw