org.apache.commons.math3.analysis.differentiation
public class DerivativeStructure extends Object implements FieldElement<DerivativeStructure>, Serializable
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.
DSCompiler
,
Serialized FormModifier and Type | Class and Description |
---|---|
private static class |
DerivativeStructure.DataTransferObject
Internal class used only for serialization.
|
Modifier and Type | Field and Description |
---|---|
private DSCompiler |
compiler
Compiler for the current dimensions.
|
private double[] |
data
Combined array holding all values.
|
private static long |
serialVersionUID
Serializable UID.
|
Modifier | Constructor and Description |
---|---|
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.
|
Modifier and Type | Method and Description |
---|---|
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 Object |
writeReplace()
Replace the instance with a data transfer object for serialization.
|
private static final long serialVersionUID
private transient DSCompiler compiler
private final double[] data
private DerivativeStructure(DSCompiler compiler)
compiler
- compiler to use for computationpublic DerivativeStructure(int parameters, int order)
parameters
- number of free parametersorder
- derivation orderpublic DerivativeStructure(int parameters, int order, double value)
parameters
- number of free parametersorder
- derivation ordervalue
- value of the constantDerivativeStructure(int, int, int, double)
public DerivativeStructure(int parameters, int order, int index, double value) throws NumberIsTooLargeException
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
- number of free parametersorder
- derivation orderindex
- index of the variable (from 0 to parameters - 1
)value
- value of the variableNumberIsTooLargeException
- if index >= parameters
.DerivativeStructure(int, int, double)
public DerivativeStructure(double a1, DerivativeStructure ds1, double a2, DerivativeStructure ds2) throws DimensionMismatchException
a1
- first scale factords1
- first base (unscaled) derivative structurea2
- second scale factords2
- second base (unscaled) derivative structureDimensionMismatchException
- if number of free parameters or orders are inconsistentpublic DerivativeStructure(double a1, DerivativeStructure ds1, double a2, DerivativeStructure ds2, double a3, DerivativeStructure ds3) throws DimensionMismatchException
a1
- first scale factords1
- first base (unscaled) derivative structurea2
- second scale factords2
- second base (unscaled) derivative structurea3
- third scale factords3
- third base (unscaled) derivative structureDimensionMismatchException
- if number of free parameters or orders are inconsistentpublic DerivativeStructure(double a1, DerivativeStructure ds1, double a2, DerivativeStructure ds2, double a3, DerivativeStructure ds3, double a4, DerivativeStructure ds4) throws DimensionMismatchException
a1
- first scale factords1
- first base (unscaled) derivative structurea2
- second scale factords2
- second base (unscaled) derivative structurea3
- third scale factords3
- third base (unscaled) derivative structurea4
- fourth scale factords4
- fourth base (unscaled) derivative structureDimensionMismatchException
- if number of free parameters or orders are inconsistentpublic DerivativeStructure(int parameters, int order, double... derivatives) throws DimensionMismatchException
parameters
- number of free parametersorder
- derivation orderderivatives
- derivatives sorted according to
DSCompiler.getPartialDerivativeIndex(int...)
DimensionMismatchException
- if derivatives array does not match the
size
expected by the compilergetAllDerivatives()
private DerivativeStructure(DerivativeStructure ds)
ds
- instance to copypublic int getFreeParameters()
public int getOrder()
public double getValue()
getPartialDerivative(int...)
public double getPartialDerivative(int... orders) throws DimensionMismatchException, NumberIsTooLargeException
orders
- derivation orders with respect to each variable (if all orders are 0,
the value is returned)DimensionMismatchException
- if the numbers of variables does not
match the instanceNumberIsTooLargeException
- if sum of derivation orders is larger
than the instance limitsgetValue()
public double[] getAllDerivatives()
DSCompiler.getPartialDerivativeIndex(int...)
public DerivativeStructure add(double a)
a
- right hand side parameter of the operatorpublic DerivativeStructure add(DerivativeStructure a) throws DimensionMismatchException
add
in interface FieldElement<DerivativeStructure>
a
- right hand side parameter of the operatorDimensionMismatchException
- if number of free parameters or orders are inconsistentpublic DerivativeStructure subtract(double a)
a
- right hand side parameter of the operatorpublic DerivativeStructure subtract(DerivativeStructure a) throws DimensionMismatchException
subtract
in interface FieldElement<DerivativeStructure>
a
- right hand side parameter of the operatorDimensionMismatchException
- if number of free parameters or orders are inconsistentpublic DerivativeStructure multiply(int n)
multiply
in interface FieldElement<DerivativeStructure>
n
- Number of times this
must be added to itself.public DerivativeStructure multiply(double a)
a
- right hand side parameter of the operatorpublic DerivativeStructure multiply(DerivativeStructure a) throws DimensionMismatchException
multiply
in interface FieldElement<DerivativeStructure>
a
- right hand side parameter of the operatorDimensionMismatchException
- if number of free parameters or orders are inconsistentpublic DerivativeStructure divide(double a)
a
- right hand side parameter of the operatorpublic DerivativeStructure divide(DerivativeStructure a) throws DimensionMismatchException
divide
in interface FieldElement<DerivativeStructure>
a
- right hand side parameter of the operatorDimensionMismatchException
- if number of free parameters or orders are inconsistentpublic DerivativeStructure remainder(double a)
a
- right hand side parameter of the operatorpublic DerivativeStructure remainder(DerivativeStructure a) throws DimensionMismatchException
a
- right hand side parameter of the operatorDimensionMismatchException
- if number of free parameters or orders are inconsistentpublic DerivativeStructure negate()
negate
in interface FieldElement<DerivativeStructure>
public DerivativeStructure abs()
public DerivativeStructure ceil()
public DerivativeStructure floor()
public DerivativeStructure rint()
public long round()
getValue()
public DerivativeStructure signum()
public DerivativeStructure copySign(double sign)
sign
argument is treated as positive.sign
- the sign for the returned valuesign
argumentpublic int getExponent()
For double numbers of the form 2x, the unbiased exponent is exactly x.
public DerivativeStructure scalb(int n)
n
- power of 2public static DerivativeStructure hypot(DerivativeStructure x, DerivativeStructure y) throws DimensionMismatchException
x
and y
- sqrt(x2 +y2)x
- a valuey
- a valueDimensionMismatchException
- if number of free parameters or orders are inconsistentpublic DerivativeStructure compose(double... f)
f
- array of value and derivatives of the function at
the current point (i.e. [f(getValue()
),
f'(getValue()
), f''(getValue()
)...]).DimensionMismatchException
- if the number of derivatives
in the array is not equal to order
+ 1public DerivativeStructure reciprocal()
this
element.reciprocal
in interface FieldElement<DerivativeStructure>
this
.public DerivativeStructure sqrt()
public DerivativeStructure cbrt()
public DerivativeStructure rootN(int n)
n
- order of the rootpublic Field<DerivativeStructure> getField()
Field
to which the instance belongs.getField
in interface FieldElement<DerivativeStructure>
Field
to which the instance belongspublic DerivativeStructure pow(double p)
p
- power to applypublic DerivativeStructure pow(int n)
n
- power to applypublic DerivativeStructure pow(DerivativeStructure e) throws DimensionMismatchException
e
- exponentDimensionMismatchException
- if number of free parameters or orders are inconsistentpublic DerivativeStructure exp()
public DerivativeStructure expm1()
public DerivativeStructure log()
public DerivativeStructure log1p()
public DerivativeStructure log10()
public DerivativeStructure cos()
public DerivativeStructure sin()
public DerivativeStructure tan()
public DerivativeStructure acos()
public DerivativeStructure asin()
public DerivativeStructure atan()
public static DerivativeStructure atan2(DerivativeStructure y, DerivativeStructure x) throws DimensionMismatchException
y
- first argument of the arc tangentx
- second argument of the arc tangentDimensionMismatchException
- if number of free parameters or orders are inconsistentpublic DerivativeStructure cosh()
public DerivativeStructure sinh()
public DerivativeStructure tanh()
public DerivativeStructure acosh()
public DerivativeStructure asinh()
public DerivativeStructure atanh()
public DerivativeStructure toDegrees()
public DerivativeStructure toRadians()
public double taylor(double... delta)
delta
- parameters offsets (Δx, Δy, ...)private Object writeReplace()
Copyright (c) 2003-2013 Apache Software Foundation