org.apache.commons.math3.analysis.differentiation

## Class DerivativeStructure

- java.lang.Object
- - org.apache.commons.math3.analysis.differentiation.DerivativeStructure

All Implemented Interfaces:
  java.io.Serializable, FieldElement<DerivativeStructure>

    public class DerivativeStructure
    extends java.lang.Object
    implements FieldElement<DerivativeStructure>, java.io.Serializable

Class representing both the value and the differentials of a function.

This class is the workhorse of the differentiation package.

This class is an implementation of the extension to Rall's numbers described in Dan Kalman's paper Doubly Recursive Multivariate Automatic Differentiation, Mathematics Magazine, vol. 75, no. 3, June 2002.

. Rall's numbers are an extension to the real numbers used throughout mathematical expressions; they hold the derivative together with the value of a function. Dan Kalman's derivative structures hold all partial derivatives up to any specified order, with respect to any number of free parameters. Rall's numbers therefore can be seen as derivative structures for order one derivative and one free parameter, and real numbers can be seen as derivative structures with zero order derivative and no free parameters.

`DerivativeStructure` instances can be used directly thanks to the arithmetic operators to the mathematical functions provided as static methods by this class (+, -, *, /, %, sin, cos ...).

Implementing complex expressions by hand using these classes is a tedious and error-prone task but has the advantage of having no limitation on the derivation order despite no requiring users to compute the derivatives by themselves. Implementing complex expression can also be done by developing computation code using standard primitive double values and to use `differentiators` to create the `DerivativeStructure`-based instances. This method is simpler but may be limited in the accuracy and derivation orders and may be computationally intensive (this is typically the case for `finite differences differentiator`.

Instances of this class are guaranteed to be immutable.

Since:
  3.1
Version:
  $Id: DerivativeStructure.java 1416643 2012-12-03 19:37:14Z tn $
See Also:
  `DSCompiler`, Serialized Form

### Nested Class Summary

Nested Classes
`private static class` `DerivativeStructure.DataTransferObject` Internal class used only for serialization.

### Field Summary

Fields
`private DSCompiler` `compiler` Compiler for the current dimensions.
`private double[]` `data` Combined array holding all values.
`private static long` `serialVersionUID` Serializable UID.

### Constructor Summary

Constructors
`private` `DerivativeStructure(DerivativeStructure ds)` Copy constructor.
`` `DerivativeStructure(double a1, DerivativeStructure ds1, double a2, DerivativeStructure ds2)` Linear combination constructor.
`` `DerivativeStructure(double a1, DerivativeStructure ds1, double a2, DerivativeStructure ds2, double a3, DerivativeStructure ds3)` Linear combination constructor.
`` `DerivativeStructure(double a1, DerivativeStructure ds1, double a2, DerivativeStructure ds2, double a3, DerivativeStructure ds3, double a4, DerivativeStructure ds4)` Linear combination constructor.
`private` `DerivativeStructure(DSCompiler compiler)` Build an instance with all values and derivatives set to 0.
`` `DerivativeStructure(int parameters, int order)` Build an instance with all values and derivatives set to 0.
`` `DerivativeStructure(int parameters, int order, double... derivatives)` Build an instance from all its derivatives.
`` `DerivativeStructure(int parameters, int order, double value)` Build an instance representing a constant value.
`` `DerivativeStructure(int parameters, int order, int index, double value)` Build an instance representing a variable.

### Method Summary

Methods
`DerivativeStructure` `abs()` absolute value.
`DerivativeStructure` `acos()` Arc cosine operation.
`DerivativeStructure` `acosh()` Inverse hyperbolic cosine operation.
`DerivativeStructure` `add(DerivativeStructure a)` '+' operator.
`DerivativeStructure` `add(double a)` '+' operator.
`DerivativeStructure` `asin()` Arc sine operation.
`DerivativeStructure` `asinh()` Inverse hyperbolic sine operation.
`DerivativeStructure` `atan()` Arc tangent operation.
`static DerivativeStructure` `atan2(DerivativeStructure y, DerivativeStructure x)` Two arguments arc tangent operation.
`DerivativeStructure` `atanh()` Inverse hyperbolic tangent operation.
`DerivativeStructure` `cbrt()` Cubic root.
`DerivativeStructure` `ceil()` Get the smallest whole number larger than instance.
`DerivativeStructure` `compose(double... f)` Compute composition of the instance by a univariate function.
`DerivativeStructure` `copySign(double sign)` Returns the instance with the sign of the argument.
`DerivativeStructure` `cos()` Cosine operation.
`DerivativeStructure` `cosh()` Hyperbolic cosine operation.
`DerivativeStructure` `divide(DerivativeStructure a)` '÷s;' operator.
`DerivativeStructure` `divide(double a)` '÷s;' operator.
`DerivativeStructure` `exp()` Exponential.
`DerivativeStructure` `expm1()` Exponential minus 1.
`DerivativeStructure` `floor()` Get the largest whole number smaller than instance.
`double[]` `getAllDerivatives()` Get all partial derivatives.
`int` `getExponent()` Return the exponent of the instance value, removing the bias.
`Field<DerivativeStructure>` `getField()` Get the `Field` to which the instance belongs.
`int` `getFreeParameters()` Get the number of free parameters.
`int` `getOrder()` Get the derivation order.
`double` `getPartialDerivative(int... orders)` Get a partial derivative.
`double` `getValue()` Get the value part of the derivative structure.
`static DerivativeStructure` `hypot(DerivativeStructure x, DerivativeStructure y)` Returns the hypotenuse of a triangle with sides `x` and `y` - sqrt(x2 +y2) avoiding intermediate overflow or underflow.
`DerivativeStructure` `log()` Natural logarithm.
`DerivativeStructure` `log10()` Base 10 logarithm.
`DerivativeStructure` `log1p()` Shifted natural logarithm.
`DerivativeStructure` `multiply(DerivativeStructure a)` '×' operator.
`DerivativeStructure` `multiply(double a)` '×' operator.
`DerivativeStructure` `multiply(int n)` Compute n × this.
`DerivativeStructure` `negate()` unary '-' operator.
`DerivativeStructure` `pow(DerivativeStructure e)` Power operation.
`DerivativeStructure` `pow(double p)` Power operation.
`DerivativeStructure` `pow(int n)` Integer power operation.
`DerivativeStructure` `reciprocal()` Returns the multiplicative inverse of `this` element.
`DerivativeStructure` `remainder(DerivativeStructure a)` '%' operator.
`DerivativeStructure` `remainder(double a)` '%' operator.
`DerivativeStructure` `rint()` Get the whole number that is the nearest to the instance, or the even one if x is exactly half way between two integers.
`DerivativeStructure` `rootN(int n)` Nth root.
`long` `round()` Get the closest long to instance value.
`DerivativeStructure` `scalb(int n)` Multiply the instance by a power of 2.
`DerivativeStructure` `signum()` Compute the signum of the instance.
`DerivativeStructure` `sin()` Sine operation.
`DerivativeStructure` `sinh()` Hyperbolic sine operation.
`DerivativeStructure` `sqrt()` Square root.
`DerivativeStructure` `subtract(DerivativeStructure a)` '-' operator.
`DerivativeStructure` `subtract(double a)` '-' operator.
`DerivativeStructure` `tan()` Tangent operation.
`DerivativeStructure` `tanh()` Hyperbolic tangent operation.
`double` `taylor(double... delta)` Evaluate Taylor expansion a derivative structure.
`DerivativeStructure` `toDegrees()` Convert radians to degrees, with error of less than 0.5 ULP
`DerivativeStructure` `toRadians()` Convert degrees to radians, with error of less than 0.5 ULP
`private java.lang.Object` `writeReplace()` Replace the instance with a data transfer object for serialization.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### serialVersionUID

    private static final long serialVersionUID

Serializable UID.

See Also:
  Constant Field Values

#### compiler

    private transient DSCompiler compiler

Compiler for the current dimensions.

#### data

    private final double[] data

Combined array holding all values.

### Constructor Detail

#### DerivativeStructure

    private DerivativeStructure(DSCompiler compiler)

Build an instance with all values and derivatives set to 0.

Parameters:
  `compiler` - compiler to use for computation

#### DerivativeStructure

    public DerivativeStructure(int parameters,
                       int order)

Build an instance with all values and derivatives set to 0.

Parameters:
  `parameters` - number of free parameters
  `order` - derivation order

#### DerivativeStructure

    public DerivativeStructure(int parameters,
                       int order,
                       double value)

Build an instance representing a constant value.

Parameters:
  `parameters` - number of free parameters
  `order` - derivation order
  `value` - value of the constant
See Also:
  `DerivativeStructure(int, int, int, double)`

#### DerivativeStructure

    public DerivativeStructure(int parameters,
                       int order,
                       int index,
                       double value)
                        throws NumberIsTooLargeException

Build an instance representing a variable.

Instances built using this constructor are considered to be the free variables with respect to which differentials are computed. As such, their differential with respect to themselves is +1.

Parameters:
  `parameters` - number of free parameters
  `order` - derivation order
  `index` - index of the variable (from 0 to `parameters - 1`)
  `value` - value of the variable
Throws:
  `NumberIsTooLargeException` - if `index >= parameters`.
See Also:
  `DerivativeStructure(int, int, double)`

#### DerivativeStructure

    public DerivativeStructure(double a1,
                       DerivativeStructure ds1,
                       double a2,
                       DerivativeStructure ds2)
                        throws DimensionMismatchException

Linear combination constructor. The derivative structure built will be a1 * ds1 + a2 * ds2

Parameters:
  `a1` - first scale factor
  `ds1` - first base (unscaled) derivative structure
  `a2` - second scale factor
  `ds2` - second base (unscaled) derivative structure
Throws:
  `DimensionMismatchException` - if number of free parameters or orders are inconsistent

#### DerivativeStructure

    public DerivativeStructure(double a1,
                       DerivativeStructure ds1,
                       double a2,
                       DerivativeStructure ds2,
                       double a3,
                       DerivativeStructure ds3)
                        throws DimensionMismatchException

Linear combination constructor. The derivative structure built will be a1 * ds1 + a2 * ds2 + a3 * ds3

Parameters:
  `a1` - first scale factor
  `ds1` - first base (unscaled) derivative structure
  `a2` - second scale factor
  `ds2` - second base (unscaled) derivative structure
  `a3` - third scale factor
  `ds3` - third base (unscaled) derivative structure
Throws:
  `DimensionMismatchException` - if number of free parameters or orders are inconsistent

#### DerivativeStructure

    public DerivativeStructure(double a1,
                       DerivativeStructure ds1,
                       double a2,
                       DerivativeStructure ds2,
                       double a3,
                       DerivativeStructure ds3,
                       double a4,
                       DerivativeStructure ds4)
                        throws DimensionMismatchException

Linear combination constructor. The derivative structure built will be a1 * ds1 + a2 * ds2 + a3 * ds3 + a4 * ds4

Parameters:
  `a1` - first scale factor
  `ds1` - first base (unscaled) derivative structure
  `a2` - second scale factor
  `ds2` - second base (unscaled) derivative structure
  `a3` - third scale factor
  `ds3` - third base (unscaled) derivative structure
  `a4` - fourth scale factor
  `ds4` - fourth base (unscaled) derivative structure
Throws:
  `DimensionMismatchException` - if number of free parameters or orders are inconsistent

#### DerivativeStructure

    public DerivativeStructure(int parameters,
                       int order,
                       double... derivatives)
                        throws DimensionMismatchException

Build an instance from all its derivatives.

Parameters:
  `parameters` - number of free parameters
  `order` - derivation order
  `derivatives` - derivatives sorted according to `DSCompiler.getPartialDerivativeIndex(int...)`
Throws:
  `DimensionMismatchException` - if derivatives array does not match the `size` expected by the compiler
See Also:
  `getAllDerivatives()`

#### DerivativeStructure

    private DerivativeStructure(DerivativeStructure ds)

Copy constructor.

Parameters:
  `ds` - instance to copy

### Method Detail

#### getFreeParameters

    public int getFreeParameters()

Get the number of free parameters.

Returns:
  number of free parameters

#### getOrder

    public int getOrder()

Get the derivation order.

Returns:
  derivation order

#### getValue

    public double getValue()

Get the value part of the derivative structure.

Returns:
  value part of the derivative structure
See Also:
  `getPartialDerivative(int...)`

#### getPartialDerivative

    public double getPartialDerivative(int... orders)
                                throws DimensionMismatchException,
                                       NumberIsTooLargeException

Get a partial derivative.

Parameters:
  `orders` - derivation orders with respect to each variable (if all orders are 0, the value is returned)
Returns:
  partial derivative
Throws:
  `DimensionMismatchException` - if the numbers of variables does not match the instance
  `NumberIsTooLargeException` - if sum of derivation orders is larger than the instance limits
See Also:
  `getValue()`

#### getAllDerivatives

    public double[] getAllDerivatives()

Get all partial derivatives.

Returns:
  a fresh copy of partial derivatives, in an array sorted according to `DSCompiler.getPartialDerivativeIndex(int...)`

#### add

    public DerivativeStructure add(double a)

'+' operator.

Parameters:
  `a` - right hand side parameter of the operator
Returns:
  this+a

#### add

    public DerivativeStructure add(DerivativeStructure a)
                            throws DimensionMismatchException

'+' operator.

Specified by:
  `add` in interface `FieldElement<DerivativeStructure>`
Parameters:
  `a` - right hand side parameter of the operator
Returns:
  this+a
Throws:
  `DimensionMismatchException` - if number of free parameters or orders are inconsistent

#### subtract

    public DerivativeStructure subtract(double a)

'-' operator.

Parameters:
  `a` - right hand side parameter of the operator
Returns:
  this-a

#### subtract

    public DerivativeStructure subtract(DerivativeStructure a)
                                 throws DimensionMismatchException

'-' operator.

Specified by:
  `subtract` in interface `FieldElement<DerivativeStructure>`
Parameters:
  `a` - right hand side parameter of the operator
Returns:
  this-a
Throws:
  `DimensionMismatchException` - if number of free parameters or orders are inconsistent

#### multiply

    public DerivativeStructure multiply(int n)

Compute n × this. Multiplication by an integer number is defined as the following sum
n × this = ∑i=1n this.

Specified by:
  `multiply` in interface `FieldElement<DerivativeStructure>`
Parameters:
  `n` - Number of times `this` must be added to itself.
Returns:
  A new element representing n × this.

#### multiply

    public DerivativeStructure multiply(double a)

'×' operator.

Parameters:
  `a` - right hand side parameter of the operator
Returns:
  this×a

#### multiply

    public DerivativeStructure multiply(DerivativeStructure a)
                                 throws DimensionMismatchException

'×' operator.

Specified by:
  `multiply` in interface `FieldElement<DerivativeStructure>`
Parameters:
  `a` - right hand side parameter of the operator
Returns:
  this×a
Throws:
  `DimensionMismatchException` - if number of free parameters or orders are inconsistent

#### divide

    public DerivativeStructure divide(double a)

'÷s;' operator.

Parameters:
  `a` - right hand side parameter of the operator
Returns:
  this÷s;a

#### divide

    public DerivativeStructure divide(DerivativeStructure a)
                               throws DimensionMismatchException

'÷s;' operator.

Specified by:
  `divide` in interface `FieldElement<DerivativeStructure>`
Parameters:
  `a` - right hand side parameter of the operator
Returns:
  this÷s;a
Throws:
  `DimensionMismatchException` - if number of free parameters or orders are inconsistent

#### remainder

    public DerivativeStructure remainder(double a)

'%' operator.

Parameters:
  `a` - right hand side parameter of the operator
Returns:
  this%a

#### remainder

    public DerivativeStructure remainder(DerivativeStructure a)
                                  throws DimensionMismatchException

'%' operator.

Parameters:
  `a` - right hand side parameter of the operator
Returns:
  this%a
Throws:
  `DimensionMismatchException` - if number of free parameters or orders are inconsistent

#### negate

    public DerivativeStructure negate()

unary '-' operator.

Specified by:
  `negate` in interface `FieldElement<DerivativeStructure>`
Returns:
  -this

#### abs

    public DerivativeStructure abs()

absolute value.

Returns:
  abs(this)

#### ceil

    public DerivativeStructure ceil()

Get the smallest whole number larger than instance.

Returns:
  ceil(this)

#### floor

    public DerivativeStructure floor()

Get the largest whole number smaller than instance.

Returns:
  floor(this)

#### rint

    public DerivativeStructure rint()

Get the whole number that is the nearest to the instance, or the even one if x is exactly half way between two integers.

Returns:
  a double number r such that r is an integer r - 0.5 <= this <= r + 0.5

#### round

    public long round()

Get the closest long to instance value.

Returns:
  closest long to `getValue()`

#### signum

    public DerivativeStructure signum()

Compute the signum of the instance. The signum is -1 for negative numbers, +1 for positive numbers and 0 otherwise

Returns:
  -1.0, -0.0, +0.0, +1.0 or NaN depending on sign of a

#### copySign

    public DerivativeStructure copySign(double sign)

Returns the instance with the sign of the argument. A NaN `sign` argument is treated as positive.

Parameters:
  `sign` - the sign for the returned value
Returns:
  the instance with the same sign as the `sign` argument

#### getExponent

    public int getExponent()

Return the exponent of the instance value, removing the bias.

For double numbers of the form 2x, the unbiased exponent is exactly x.

Returns:
  exponent for instance in IEEE754 representation, without bias

#### scalb

    public DerivativeStructure scalb(int n)

Multiply the instance by a power of 2.

Parameters:
  `n` - power of 2
Returns:
  this × 2n

#### hypot

    public static DerivativeStructure hypot(DerivativeStructure x,
                            DerivativeStructure y)
                                     throws DimensionMismatchException

Returns the hypotenuse of a triangle with sides `x` and `y` - sqrt(x2 +y2)
avoiding intermediate overflow or underflow.

- If either argument is infinite, then the result is positive infinity.
- else, if either argument is NaN then the result is NaN.

Parameters:
  `x` - a value
  `y` - a value
Returns:
  sqrt(x2 +y2)
Throws:
  `DimensionMismatchException` - if number of free parameters or orders are inconsistent

#### compose

    public DerivativeStructure compose(double... f)

Compute composition of the instance by a univariate function.

Parameters:
  `f` - array of value and derivatives of the function at the current point (i.e. [f(`getValue()`), f'(`getValue()`), f''(`getValue()`)...]).
Returns:
  f(this)
Throws:
  `DimensionMismatchException` - if the number of derivatives in the array is not equal to `order` + 1

#### reciprocal

    public DerivativeStructure reciprocal()

Returns the multiplicative inverse of `this` element.

Specified by:
  `reciprocal` in interface `FieldElement<DerivativeStructure>`
Returns:
  the inverse of `this`.

#### sqrt

    public DerivativeStructure sqrt()

Square root.

Returns:
  square root of the instance

#### cbrt

    public DerivativeStructure cbrt()

Cubic root.

Returns:
  cubic root of the instance

#### rootN

    public DerivativeStructure rootN(int n)

Nth root.

Parameters:
  `n` - order of the root
Returns:
  nth root of the instance

#### getField

    public Field<DerivativeStructure> getField()

Get the `Field` to which the instance belongs.

Specified by:
  `getField` in interface `FieldElement<DerivativeStructure>`
Returns:
  `Field` to which the instance belongs

#### pow

    public DerivativeStructure pow(double p)

Power operation.

Parameters:
  `p` - power to apply
Returns:
  thisp

#### pow

    public DerivativeStructure pow(int n)

Integer power operation.

Parameters:
  `n` - power to apply
Returns:
  thisn

#### pow

    public DerivativeStructure pow(DerivativeStructure e)
                            throws DimensionMismatchException

Power operation.

Parameters:
  `e` - exponent
Returns:
  thise
Throws:
  `DimensionMismatchException` - if number of free parameters or orders are inconsistent

#### exp

    public DerivativeStructure exp()

Exponential.

Returns:
  exponential of the instance

#### expm1

    public DerivativeStructure expm1()

Exponential minus 1.

Returns:
  exponential minus one of the instance

#### log

    public DerivativeStructure log()

Natural logarithm.

Returns:
  logarithm of the instance

#### log1p

    public DerivativeStructure log1p()

Shifted natural logarithm.

Returns:
  logarithm of one plus the instance

#### log10

    public DerivativeStructure log10()

Base 10 logarithm.

Returns:
  base 10 logarithm of the instance

#### cos

    public DerivativeStructure cos()

Cosine operation.

Returns:
  cos(this)

#### sin

    public DerivativeStructure sin()

Sine operation.

Returns:
  sin(this)

#### tan

    public DerivativeStructure tan()

Tangent operation.

Returns:
  tan(this)

#### acos

    public DerivativeStructure acos()

Arc cosine operation.

Returns:
  acos(this)

#### asin

    public DerivativeStructure asin()

Arc sine operation.

Returns:
  asin(this)

#### atan

    public DerivativeStructure atan()

Arc tangent operation.

Returns:
  atan(this)

#### atan2

    public static DerivativeStructure atan2(DerivativeStructure y,
                            DerivativeStructure x)
                                     throws DimensionMismatchException

Two arguments arc tangent operation.

Parameters:
  `y` - first argument of the arc tangent
  `x` - second argument of the arc tangent
Returns:
  atan2(y, x)
Throws:
  `DimensionMismatchException` - if number of free parameters or orders are inconsistent

#### cosh

    public DerivativeStructure cosh()

Hyperbolic cosine operation.

Returns:
  cosh(this)

#### sinh

    public DerivativeStructure sinh()

Hyperbolic sine operation.

Returns:
  sinh(this)

#### tanh

    public DerivativeStructure tanh()

Hyperbolic tangent operation.

Returns:
  tanh(this)

#### acosh

    public DerivativeStructure acosh()

Inverse hyperbolic cosine operation.

Returns:
  acosh(this)

#### asinh

    public DerivativeStructure asinh()

Inverse hyperbolic sine operation.

Returns:
  asin(this)

#### atanh

    public DerivativeStructure atanh()

Inverse hyperbolic tangent operation.

Returns:
  atanh(this)

#### toDegrees

    public DerivativeStructure toDegrees()

Convert radians to degrees, with error of less than 0.5 ULP

Returns:
  instance converted into degrees

#### toRadians

    public DerivativeStructure toRadians()

Convert degrees to radians, with error of less than 0.5 ULP

Returns:
  instance converted into radians

#### taylor

    public double taylor(double... delta)

Evaluate Taylor expansion a derivative structure.

Parameters:
  `delta` - parameters offsets (Δx, Δy, ...)
Returns:
  value of the Taylor expansion at x + Δx, y + Δy, ...

#### writeReplace

    private java.lang.Object writeReplace()

Replace the instance with a data transfer object for serialization.

Returns:
  data transfer object that will be serialized