# Module Scientific.Functions.Derivatives

This module provides automatic differentiation for functions with any number of variables up to any order. An instance of the class DerivVar represents the value of a function and the values of its partial derivatives with respect to a list of variables. All common mathematical operations and functions are available for these numbers. There is no restriction on the type of the numbers fed into the code; it works for real and complex numbers as well as for any Python type that implements the necessary operations.

If only first-order derivatives are required, the module FirstDerivatives should be used. It is compatible to this one, but significantly faster.

Example:

`print sin(DerivVar(2))`

produces the output

`(0.909297426826, [-0.416146836547])`

The first number is the value of sin(2); the number in the following list is the value of the derivative of sin(x) at x=2, i.e. cos(2).

When there is more than one variable, DerivVar must be called with an integer second argument that specifies the number of the variable.

Example:

    x = DerivVar(7., 0)
    y = DerivVar(42., 1)
    z = DerivVar(pi, 2)
    print (sqrt(pow(x,2)+pow(y,2)+pow(z,2)))

produces the output

    (42.6950770511, [0.163953328662, 0.98371997197, 0.0735820818365])

The numbers in the list are the partial derivatives with respect to x, y, and z, respectively.

Higher-order derivatives are requested with an optional third argument to DerivVar.

Example:

    x = DerivVar(3., 0, 3)
    y = DerivVar(5., 1, 3)
    print sqrt(x*y)

produces the output

    (3.87298334621,
        [0.645497224368, 0.387298334621],
          [[-0.107582870728, 0.0645497224368],
            [0.0645497224368, -0.0387298334621]],
              [[[0.053791435364, -0.0107582870728],
                [-0.0107582870728, -0.00645497224368]],
               [[-0.0107582870728, -0.00645497224368],
                [-0.00645497224368, 0.0116189500386]]])

The individual orders can be extracted by indexing:

    print sqrt(x*y)[0]
    3.87298334621
    print sqrt(x*y)[1]
    [0.645497224368, 0.387298334621]

An n-th order derivative is represented by a nested list of depth n.

When variables with different differentiation orders are mixed, the result has the lower one of the two orders. An exception are zeroth-order variables, which are treated as constants.

Caution: Higher-order derivatives are implemented by recursively using DerivVars to represent derivatives. This makes the code very slow for high orders.

Note: It doesn't make sense to use multiple DerivVar objects with different values for the same variable index in one calculation, but there is no check for this. I.e.

    print DerivVar(3, 0)+DerivVar(5, 0)

produces

    (8, [2])

but this result is meaningless.

## Functions

- isDerivVar()

  Returns 1 if x is a DerivVar object.

- DerivVector()

  Returns a vector whose components are DerivVar objects.

  x, y, z

    vector components (numbers)

  index

    the DerivVar index for the x component. The y and z components receive consecutive indices.

  order

    the derivative order

## Class DerivVar: Variable with derivatives

Constructor: DerivVar(value, index = 0, order = 1)

value

  the numerical value of the variable

index

  the variable index (an integer), which serves to distinguish between variables and as an index for the derivative lists. Each explicitly created instance of DerivVar must have a unique index.

order

  the derivative order

Indexing with an integer yields the derivatives of the corresponding order.

Methods:

- toOrder(order)

  Returns a DerivVar object with a lower derivative order.