public class DerivativeStructure extends Object implements RealFieldElement<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
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 FormConstructor and Description |
---|
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.
|
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)
Compute this + a.
|
DerivativeStructure |
add(double a)
'+' operator.
|
DerivativeStructure |
asin()
Arc sine operation.
|
DerivativeStructure |
asinh()
Inverse hyperbolic sine operation.
|
DerivativeStructure |
atan()
Arc tangent operation.
|
DerivativeStructure |
atan2(DerivativeStructure x)
Two arguments 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(DerivativeStructure sign)
Returns the instance with the sign of the argument.
|
DerivativeStructure |
copySign(double sign)
Returns the instance with the sign of the argument.
|
DerivativeStructure |
cos()
Cosine operation.
|
DerivativeStructure |
cosh()
Hyperbolic cosine operation.
|
DerivativeStructure |
createConstant(double c)
Create a constant compatible with instance order and number of parameters.
|
DerivativeStructure |
divide(DerivativeStructure a)
Compute this ÷ a.
|
DerivativeStructure |
divide(double a)
'÷' operator.
|
boolean |
equals(Object other)
Test for the equality of two derivative structures.
|
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 |
getReal()
Get the real value of the number.
|
double |
getValue()
Get the value part of the derivative structure.
|
int |
hashCode()
Get a hashCode for the derivative structure.
|
DerivativeStructure |
hypot(DerivativeStructure y)
Returns the hypotenuse of a triangle with sides
this and y
- sqrt(this2 +y2)
avoiding intermediate overflow or underflow. |
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 |
linearCombination(DerivativeStructure[] a,
DerivativeStructure[] b)
Compute a linear combination.
|
DerivativeStructure |
linearCombination(DerivativeStructure a1,
DerivativeStructure b1,
DerivativeStructure a2,
DerivativeStructure b2)
Compute a linear combination.
|
DerivativeStructure |
linearCombination(DerivativeStructure a1,
DerivativeStructure b1,
DerivativeStructure a2,
DerivativeStructure b2,
DerivativeStructure a3,
DerivativeStructure b3)
Compute a linear combination.
|
DerivativeStructure |
linearCombination(DerivativeStructure a1,
DerivativeStructure b1,
DerivativeStructure a2,
DerivativeStructure b2,
DerivativeStructure a3,
DerivativeStructure b3,
DerivativeStructure a4,
DerivativeStructure b4)
Compute a linear combination.
|
DerivativeStructure |
linearCombination(double[] a,
DerivativeStructure[] b)
Compute a linear combination.
|
DerivativeStructure |
linearCombination(double a1,
DerivativeStructure b1,
double a2,
DerivativeStructure b2)
Compute a linear combination.
|
DerivativeStructure |
linearCombination(double a1,
DerivativeStructure b1,
double a2,
DerivativeStructure b2,
double a3,
DerivativeStructure b3)
Compute a linear combination.
|
DerivativeStructure |
linearCombination(double a1,
DerivativeStructure b1,
double a2,
DerivativeStructure b2,
double a3,
DerivativeStructure b3,
double a4,
DerivativeStructure b4)
Compute a linear combination.
|
DerivativeStructure |
log()
Natural logarithm.
|
DerivativeStructure |
log10()
Base 10 logarithm.
|
DerivativeStructure |
log1p()
Shifted natural logarithm.
|
DerivativeStructure |
multiply(DerivativeStructure a)
Compute this × a.
|
DerivativeStructure |
multiply(double a)
'×' operator.
|
DerivativeStructure |
multiply(int n)
Compute n × this.
|
DerivativeStructure |
negate()
Returns the additive inverse of
this element. |
DerivativeStructure |
pow(DerivativeStructure e)
Power operation.
|
DerivativeStructure |
pow(double p)
Power operation.
|
static DerivativeStructure |
pow(double a,
DerivativeStructure x)
Compute ax where a is a double and x a
DerivativeStructure |
DerivativeStructure |
pow(int n)
Integer power operation.
|
DerivativeStructure |
reciprocal()
Returns the multiplicative inverse of
this element. |
DerivativeStructure |
remainder(DerivativeStructure a)
IEEE remainder operator.
|
DerivativeStructure |
remainder(double a)
IEEE remainder 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)
Compute this - a.
|
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
|
public DerivativeStructure(int parameters, int order) throws NumberIsTooLargeException
parameters
- number of free parametersorder
- derivation orderNumberIsTooLargeException
- if order is too largepublic DerivativeStructure(int parameters, int order, double value) throws NumberIsTooLargeException
parameters
- number of free parametersorder
- derivation ordervalue
- value of the constantNumberIsTooLargeException
- if order is too largeDerivativeStructure(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, NumberIsTooLargeException
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 compilerNumberIsTooLargeException
- if order is too largegetAllDerivatives()
public int getFreeParameters()
public int getOrder()
public DerivativeStructure createConstant(double c)
This method is a convenience factory method, it simply calls
new DerivativeStructure(getFreeParameters(), getOrder(), c)
c
- value of the constantDerivativeStructure(int, int, double)
public double getReal()
getReal
in interface RealFieldElement<DerivativeStructure>
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)
add
in interface RealFieldElement<DerivativeStructure>
a
- right hand side parameter of the operatorpublic DerivativeStructure add(DerivativeStructure a) throws DimensionMismatchException
add
in interface FieldElement<DerivativeStructure>
a
- element to addDimensionMismatchException
- if number of free parameters
or orders do not matchpublic DerivativeStructure subtract(double a)
subtract
in interface RealFieldElement<DerivativeStructure>
a
- right hand side parameter of the operatorpublic DerivativeStructure subtract(DerivativeStructure a) throws DimensionMismatchException
subtract
in interface FieldElement<DerivativeStructure>
a
- element to subtractDimensionMismatchException
- if number of free parameters
or orders do not matchpublic DerivativeStructure multiply(int n)
multiply
in interface FieldElement<DerivativeStructure>
n
- Number of times this
must be added to itself.public DerivativeStructure multiply(double a)
multiply
in interface RealFieldElement<DerivativeStructure>
a
- right hand side parameter of the operatorpublic DerivativeStructure multiply(DerivativeStructure a) throws DimensionMismatchException
multiply
in interface FieldElement<DerivativeStructure>
a
- element to multiplyDimensionMismatchException
- if number of free parameters
or orders do not matchpublic DerivativeStructure divide(double a)
divide
in interface RealFieldElement<DerivativeStructure>
a
- right hand side parameter of the operatorpublic DerivativeStructure divide(DerivativeStructure a) throws DimensionMismatchException
divide
in interface FieldElement<DerivativeStructure>
a
- element to divide byDimensionMismatchException
- if number of free parameters
or orders do not matchpublic DerivativeStructure remainder(double a)
remainder
in interface RealFieldElement<DerivativeStructure>
a
- right hand side parameter of the operatorpublic DerivativeStructure remainder(DerivativeStructure a) throws DimensionMismatchException
remainder
in interface RealFieldElement<DerivativeStructure>
a
- right hand side parameter of the operatorDimensionMismatchException
- if number of free parameters
or orders do not matchpublic DerivativeStructure negate()
this
element.negate
in interface FieldElement<DerivativeStructure>
this
.public DerivativeStructure abs()
abs
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure ceil()
ceil
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure floor()
floor
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure rint()
rint
in interface RealFieldElement<DerivativeStructure>
public long round()
round
in interface RealFieldElement<DerivativeStructure>
RealFieldElement.getReal()
public DerivativeStructure signum()
signum
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure copySign(DerivativeStructure sign)
sign
argument is treated as positive.copySign
in interface RealFieldElement<DerivativeStructure>
sign
- the sign for the returned valuesign
argumentpublic DerivativeStructure copySign(double sign)
sign
argument is treated as positive.copySign
in interface RealFieldElement<DerivativeStructure>
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)
scalb
in interface RealFieldElement<DerivativeStructure>
n
- power of 2public DerivativeStructure hypot(DerivativeStructure y) throws DimensionMismatchException
this
and y
- sqrt(this2 +y2)
avoiding intermediate overflow or underflow.
hypot
in interface RealFieldElement<DerivativeStructure>
y
- a valueDimensionMismatchException
- if number of free parameters
or orders do not matchpublic static DerivativeStructure hypot(DerivativeStructure x, DerivativeStructure y) throws DimensionMismatchException
x
and y
- sqrt(x2 +y2)
avoiding intermediate overflow or underflow.
x
- a valuey
- a valueDimensionMismatchException
- if number of free parameters
or orders do not matchpublic DerivativeStructure compose(double... f) throws DimensionMismatchException
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>
reciprocal
in interface RealFieldElement<DerivativeStructure>
this
.public DerivativeStructure sqrt()
sqrt
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure cbrt()
cbrt
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure rootN(int n)
rootN
in interface RealFieldElement<DerivativeStructure>
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 static DerivativeStructure pow(double a, DerivativeStructure x)
DerivativeStructure
a
- number to exponentiatex
- power to applypublic DerivativeStructure pow(double p)
pow
in interface RealFieldElement<DerivativeStructure>
p
- power to applypublic DerivativeStructure pow(int n)
pow
in interface RealFieldElement<DerivativeStructure>
n
- power to applypublic DerivativeStructure pow(DerivativeStructure e) throws DimensionMismatchException
pow
in interface RealFieldElement<DerivativeStructure>
e
- exponentDimensionMismatchException
- if number of free parameters
or orders do not matchpublic DerivativeStructure exp()
exp
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure expm1()
expm1
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure log()
log
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure log1p()
log1p
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure log10()
public DerivativeStructure cos()
cos
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure sin()
sin
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure tan()
tan
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure acos()
acos
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure asin()
asin
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure atan()
atan
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure atan2(DerivativeStructure x) throws DimensionMismatchException
atan2
in interface RealFieldElement<DerivativeStructure>
x
- second argument of the arc tangentDimensionMismatchException
- if number of free parameters or orders are inconsistentpublic 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 do not matchpublic DerivativeStructure cosh()
cosh
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure sinh()
sinh
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure tanh()
tanh
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure acosh()
acosh
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure asinh()
asinh
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure atanh()
atanh
in interface RealFieldElement<DerivativeStructure>
public DerivativeStructure toDegrees()
public DerivativeStructure toRadians()
public double taylor(double... delta) throws MathArithmeticException
delta
- parameters offsets (Δx, Δy, ...)MathArithmeticException
- if factorials becomes too largepublic DerivativeStructure linearCombination(DerivativeStructure[] a, DerivativeStructure[] b) throws DimensionMismatchException
linearCombination
in interface RealFieldElement<DerivativeStructure>
a
- Factors.b
- Factors.Σi ai bi
.DimensionMismatchException
- if number of free parameters
or orders do not matchpublic DerivativeStructure linearCombination(double[] a, DerivativeStructure[] b) throws DimensionMismatchException
linearCombination
in interface RealFieldElement<DerivativeStructure>
a
- Factors.b
- Factors.Σi ai bi
.DimensionMismatchException
- if number of free parameters
or orders do not matchpublic DerivativeStructure linearCombination(DerivativeStructure a1, DerivativeStructure b1, DerivativeStructure a2, DerivativeStructure b2) throws DimensionMismatchException
linearCombination
in interface RealFieldElement<DerivativeStructure>
a1
- first factor of the first termb1
- second factor of the first terma2
- first factor of the second termb2
- second factor of the second termDimensionMismatchException
- if number of free parameters
or orders do not matchRealFieldElement.linearCombination(Object, Object, Object, Object, Object, Object)
,
RealFieldElement.linearCombination(Object, Object, Object, Object, Object, Object, Object, Object)
public DerivativeStructure linearCombination(double a1, DerivativeStructure b1, double a2, DerivativeStructure b2) throws DimensionMismatchException
linearCombination
in interface RealFieldElement<DerivativeStructure>
a1
- first factor of the first termb1
- second factor of the first terma2
- first factor of the second termb2
- second factor of the second termDimensionMismatchException
- if number of free parameters
or orders do not matchRealFieldElement.linearCombination(double, Object, double, Object, double, Object)
,
RealFieldElement.linearCombination(double, Object, double, Object, double, Object, double, Object)
public DerivativeStructure linearCombination(DerivativeStructure a1, DerivativeStructure b1, DerivativeStructure a2, DerivativeStructure b2, DerivativeStructure a3, DerivativeStructure b3) throws DimensionMismatchException
linearCombination
in interface RealFieldElement<DerivativeStructure>
a1
- first factor of the first termb1
- second factor of the first terma2
- first factor of the second termb2
- second factor of the second terma3
- first factor of the third termb3
- second factor of the third termDimensionMismatchException
- if number of free parameters
or orders do not matchRealFieldElement.linearCombination(Object, Object, Object, Object)
,
RealFieldElement.linearCombination(Object, Object, Object, Object, Object, Object, Object, Object)
public DerivativeStructure linearCombination(double a1, DerivativeStructure b1, double a2, DerivativeStructure b2, double a3, DerivativeStructure b3) throws DimensionMismatchException
linearCombination
in interface RealFieldElement<DerivativeStructure>
a1
- first factor of the first termb1
- second factor of the first terma2
- first factor of the second termb2
- second factor of the second terma3
- first factor of the third termb3
- second factor of the third termDimensionMismatchException
- if number of free parameters
or orders do not matchRealFieldElement.linearCombination(double, Object, double, Object)
,
RealFieldElement.linearCombination(double, Object, double, Object, double, Object, double, Object)
public DerivativeStructure linearCombination(DerivativeStructure a1, DerivativeStructure b1, DerivativeStructure a2, DerivativeStructure b2, DerivativeStructure a3, DerivativeStructure b3, DerivativeStructure a4, DerivativeStructure b4) throws DimensionMismatchException
linearCombination
in interface RealFieldElement<DerivativeStructure>
a1
- first factor of the first termb1
- second factor of the first terma2
- first factor of the second termb2
- second factor of the second terma3
- first factor of the third termb3
- second factor of the third terma4
- first factor of the third termb4
- second factor of the third termDimensionMismatchException
- if number of free parameters
or orders do not matchRealFieldElement.linearCombination(Object, Object, Object, Object)
,
RealFieldElement.linearCombination(Object, Object, Object, Object, Object, Object)
public DerivativeStructure linearCombination(double a1, DerivativeStructure b1, double a2, DerivativeStructure b2, double a3, DerivativeStructure b3, double a4, DerivativeStructure b4) throws DimensionMismatchException
linearCombination
in interface RealFieldElement<DerivativeStructure>
a1
- first factor of the first termb1
- second factor of the first terma2
- first factor of the second termb2
- second factor of the second terma3
- first factor of the third termb3
- second factor of the third terma4
- first factor of the third termb4
- second factor of the third termDimensionMismatchException
- if number of free parameters
or orders do not matchRealFieldElement.linearCombination(double, Object, double, Object)
,
RealFieldElement.linearCombination(double, Object, double, Object, double, Object)
public boolean equals(Object other)
Derivative structures are considered equal if they have the same number of free parameters, the same derivation order, and the same derivatives.
Copyright © 2003–2016 The Apache Software Foundation. All rights reserved.