org.apache.commons.math3.analysis.differentiation
Class DerivativeStructure

java.lang.Object
  extended by org.apache.commons.math3.analysis.differentiation.DerivativeStructure
All Implemented Interfaces:
Serializable, FieldElement<DerivativeStructure>

public class DerivativeStructure
extends Object
implements FieldElement<DerivativeStructure>, 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

Constructor Summary
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.
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
 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
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

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()
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.

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, ...


Copyright © 2003-2012 The Apache Software Foundation. All Rights Reserved.