Class DerivativeStructure
- java.lang.Object
-
- org.apache.commons.math4.legacy.analysis.differentiation.DerivativeStructure
-
- All Implemented Interfaces:
FieldElement<DerivativeStructure>
,RealFieldElement<DerivativeStructure>
public class DerivativeStructure extends Object implements RealFieldElement<DerivativeStructure>
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 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 not 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 theDerivativeStructure
-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 forfinite differences differentiator
.Instances of this class are guaranteed to be immutable.
- Since:
- 3.1
- See Also:
DSCompiler
-
-
Constructor Summary
Constructors Constructor 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 value)
Build an instance representing a constant value.DerivativeStructure(int parameters, int order, double... derivatives)
Build an instance from all its derivatives.DerivativeStructure(int parameters, int order, int index, double value)
Build an instance representing a variable.
-
Method Summary
-
-
-
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 parametersorder
- derivation order- Throws:
NumberIsTooLargeException
- if order is too large.
-
DerivativeStructure
public DerivativeStructure(int parameters, int order, double value)
Build an instance representing a constant value.- Parameters:
parameters
- number of free parametersorder
- derivation ordervalue
- value of the constant- Throws:
NumberIsTooLargeException
- if order is too large.- See Also:
DerivativeStructure(int, int, int, double)
-
DerivativeStructure
public DerivativeStructure(int parameters, int order, int index, double value)
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 parametersorder
- derivation orderindex
- index of the variable (from 0 toparameters - 1
)value
- value of the variable- Throws:
NumberIsTooLargeException
- ifindex ≥ parameters
.- See Also:
DerivativeStructure(int, int, double)
-
DerivativeStructure
public DerivativeStructure(double a1, DerivativeStructure ds1, double a2, DerivativeStructure ds2)
Linear combination constructor. The derivative structure built will be a1 * ds1 + a2 * ds2- Parameters:
a1
- first scale factords1
- first base (unscaled) derivative structurea2
- second scale factords2
- 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)
Linear combination constructor. The derivative structure built will be a1 * ds1 + a2 * ds2 + a3 * ds3- Parameters:
a1
- first scale factords1
- first base (unscaled) derivative structurea2
- second scale factords2
- second base (unscaled) derivative structurea3
- third scale factords3
- 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)
Linear combination constructor. The derivative structure built will be a1 * ds1 + a2 * ds2 + a3 * ds3 + a4 * ds4- Parameters:
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 structure- Throws:
DimensionMismatchException
- if number of free parameters or orders are inconsistent.
-
DerivativeStructure
public DerivativeStructure(int parameters, int order, double... derivatives)
Build an instance from all its derivatives.- Parameters:
parameters
- number of free parametersorder
- derivation orderderivatives
- derivatives sorted according toDSCompiler.getPartialDerivativeIndex(int...)
- Throws:
DimensionMismatchException
- if derivatives array does not match thesize
expected by the compiler.NumberIsTooLargeException
- if order is too large.- 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
-
createConstant
public DerivativeStructure createConstant(double c)
Create a constant compatible with instance order and number of parameters.This method is a convenience factory method, it simply calls
new DerivativeStructure(getFreeParameters(), getOrder(), c)
- Parameters:
c
- value of the constant- Returns:
- a constant compatible with instance order and number of parameters
- Since:
- 3.3
- See Also:
DerivativeStructure(int, int, double)
-
getReal
public double getReal()
- Specified by:
getReal
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
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)
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 the 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)
- Specified by:
add
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
add
public DerivativeStructure add(DerivativeStructure a)
- Specified by:
add
in interfaceFieldElement<DerivativeStructure>
- Throws:
DimensionMismatchException
- if number of free parameters or orders do not match.
-
subtract
public DerivativeStructure subtract(double a)
- Specified by:
subtract
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
subtract
public DerivativeStructure subtract(DerivativeStructure a)
- Specified by:
subtract
in interfaceFieldElement<DerivativeStructure>
- Throws:
DimensionMismatchException
- if number of free parameters or orders do not match
-
multiply
public DerivativeStructure multiply(int n)
- Specified by:
multiply
in interfaceFieldElement<DerivativeStructure>
-
multiply
public DerivativeStructure multiply(double a)
- Specified by:
multiply
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
multiply
public DerivativeStructure multiply(DerivativeStructure a)
- Specified by:
multiply
in interfaceFieldElement<DerivativeStructure>
- Throws:
DimensionMismatchException
- if number of free parameters or orders do not match
-
divide
public DerivativeStructure divide(double a)
- Specified by:
divide
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
divide
public DerivativeStructure divide(DerivativeStructure a)
- Specified by:
divide
in interfaceFieldElement<DerivativeStructure>
- Throws:
DimensionMismatchException
- if number of free parameters or orders do not match
-
remainder
public DerivativeStructure remainder(double a)
- Specified by:
remainder
in interfaceRealFieldElement<DerivativeStructure>
-
remainder
public DerivativeStructure remainder(DerivativeStructure a)
- Specified by:
remainder
in interfaceRealFieldElement<DerivativeStructure>
- Throws:
DimensionMismatchException
- if number of free parameters or orders do not match- Since:
- 3.2
-
negate
public DerivativeStructure negate()
- Specified by:
negate
in interfaceFieldElement<DerivativeStructure>
-
abs
public DerivativeStructure abs()
- Specified by:
abs
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
ceil
public DerivativeStructure ceil()
- Specified by:
ceil
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
floor
public DerivativeStructure floor()
- Specified by:
floor
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
rint
public DerivativeStructure rint()
- Specified by:
rint
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
round
public long round()
- Specified by:
round
in interfaceRealFieldElement<DerivativeStructure>
-
signum
public DerivativeStructure signum()
- Specified by:
signum
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
copySign
public DerivativeStructure copySign(DerivativeStructure sign)
- Specified by:
copySign
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
copySign
public DerivativeStructure copySign(double sign)
- Specified by:
copySign
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
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)
- Specified by:
scalb
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
hypot
public DerivativeStructure hypot(DerivativeStructure y)
- Specified by:
hypot
in interfaceRealFieldElement<DerivativeStructure>
- Throws:
DimensionMismatchException
- if number of free parameters or orders do not match- Since:
- 3.2
-
hypot
public static DerivativeStructure hypot(DerivativeStructure x, DerivativeStructure y)
Returns the hypotenuse of a triangle with sidesx
andy
- 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 valuey
- a value- Returns:
- sqrt(x2 +y2)
- Throws:
DimensionMismatchException
- if number of free parameters or orders do not match- Since:
- 3.2
-
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 toorder
+ 1
-
reciprocal
public DerivativeStructure reciprocal()
- Specified by:
reciprocal
in interfaceFieldElement<DerivativeStructure>
- Specified by:
reciprocal
in interfaceRealFieldElement<DerivativeStructure>
-
sqrt
public DerivativeStructure sqrt()
- Specified by:
sqrt
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
cbrt
public DerivativeStructure cbrt()
- Specified by:
cbrt
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
rootN
public DerivativeStructure rootN(int n)
- Specified by:
rootN
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
getField
public Field<DerivativeStructure> getField()
- Specified by:
getField
in interfaceFieldElement<DerivativeStructure>
-
pow
public static DerivativeStructure pow(double a, DerivativeStructure x)
Compute ax where a is a double and x aDerivativeStructure
.- Parameters:
a
- number to exponentiatex
- power to apply- Returns:
- ax
- Since:
- 3.3
-
pow
public DerivativeStructure pow(double p)
- Specified by:
pow
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
pow
public DerivativeStructure pow(int n)
- Specified by:
pow
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
pow
public DerivativeStructure pow(DerivativeStructure e)
- Specified by:
pow
in interfaceRealFieldElement<DerivativeStructure>
- Throws:
DimensionMismatchException
- if number of free parameters or orders do not match- Since:
- 3.2
-
exp
public DerivativeStructure exp()
- Specified by:
exp
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
expm1
public DerivativeStructure expm1()
- Specified by:
expm1
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
log
public DerivativeStructure log()
- Specified by:
log
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
log1p
public DerivativeStructure log1p()
- Specified by:
log1p
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
log10
public DerivativeStructure log10()
Base 10 logarithm.- Specified by:
log10
in interfaceRealFieldElement<DerivativeStructure>
- Returns:
- base 10 logarithm of the instance
-
cos
public DerivativeStructure cos()
- Specified by:
cos
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
sin
public DerivativeStructure sin()
- Specified by:
sin
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
tan
public DerivativeStructure tan()
- Specified by:
tan
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
acos
public DerivativeStructure acos()
- Specified by:
acos
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
asin
public DerivativeStructure asin()
- Specified by:
asin
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
atan
public DerivativeStructure atan()
- Specified by:
atan
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
atan2
public DerivativeStructure atan2(DerivativeStructure x)
- Specified by:
atan2
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
atan2
public static DerivativeStructure atan2(DerivativeStructure y, DerivativeStructure x)
Two arguments arc tangent operation.- Parameters:
y
- first argument of the arc tangentx
- second argument of the arc tangent- Returns:
- atan2(y, x)
- Throws:
DimensionMismatchException
- if number of free parameters or orders do not match- Since:
- 3.2
-
cosh
public DerivativeStructure cosh()
- Specified by:
cosh
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
sinh
public DerivativeStructure sinh()
- Specified by:
sinh
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
tanh
public DerivativeStructure tanh()
- Specified by:
tanh
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
acosh
public DerivativeStructure acosh()
- Specified by:
acosh
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
asinh
public DerivativeStructure asinh()
- Specified by:
asinh
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
atanh
public DerivativeStructure atanh()
- Specified by:
atanh
in interfaceRealFieldElement<DerivativeStructure>
- Since:
- 3.2
-
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, ...
- Throws:
MathArithmeticException
- if factorials becomes too large
-
linearCombination
public DerivativeStructure linearCombination(DerivativeStructure[] a, DerivativeStructure[] b)
- Specified by:
linearCombination
in interfaceRealFieldElement<DerivativeStructure>
- Throws:
DimensionMismatchException
- if number of free parameters or orders do not match- Since:
- 3.2
-
linearCombination
public DerivativeStructure linearCombination(double[] a, DerivativeStructure[] b)
- Specified by:
linearCombination
in interfaceRealFieldElement<DerivativeStructure>
- Throws:
DimensionMismatchException
- if number of free parameters or orders do not match- Since:
- 3.2
-
linearCombination
public DerivativeStructure linearCombination(DerivativeStructure a1, DerivativeStructure b1, DerivativeStructure a2, DerivativeStructure b2)
- Specified by:
linearCombination
in interfaceRealFieldElement<DerivativeStructure>
- Throws:
DimensionMismatchException
- if number of free parameters or orders do not match- Since:
- 3.2
-
linearCombination
public DerivativeStructure linearCombination(double a1, DerivativeStructure b1, double a2, DerivativeStructure b2)
- Specified by:
linearCombination
in interfaceRealFieldElement<DerivativeStructure>
- Throws:
DimensionMismatchException
- if number of free parameters or orders do not match- Since:
- 3.2
-
linearCombination
public DerivativeStructure linearCombination(DerivativeStructure a1, DerivativeStructure b1, DerivativeStructure a2, DerivativeStructure b2, DerivativeStructure a3, DerivativeStructure b3)
- Specified by:
linearCombination
in interfaceRealFieldElement<DerivativeStructure>
- Throws:
DimensionMismatchException
- if number of free parameters or orders do not match- Since:
- 3.2
-
linearCombination
public DerivativeStructure linearCombination(double a1, DerivativeStructure b1, double a2, DerivativeStructure b2, double a3, DerivativeStructure b3)
- Specified by:
linearCombination
in interfaceRealFieldElement<DerivativeStructure>
- Throws:
DimensionMismatchException
- if number of free parameters or orders do not match- Since:
- 3.2
-
linearCombination
public DerivativeStructure linearCombination(DerivativeStructure a1, DerivativeStructure b1, DerivativeStructure a2, DerivativeStructure b2, DerivativeStructure a3, DerivativeStructure b3, DerivativeStructure a4, DerivativeStructure b4)
- Specified by:
linearCombination
in interfaceRealFieldElement<DerivativeStructure>
- Throws:
DimensionMismatchException
- if number of free parameters or orders do not match- Since:
- 3.2
-
linearCombination
public DerivativeStructure linearCombination(double a1, DerivativeStructure b1, double a2, DerivativeStructure b2, double a3, DerivativeStructure b3, double a4, DerivativeStructure b4)
- Specified by:
linearCombination
in interfaceRealFieldElement<DerivativeStructure>
- Throws:
DimensionMismatchException
- if number of free parameters or orders do not match- Since:
- 3.2
-
equals
public boolean equals(Object other)
Test for the equality of two derivative structures.Derivative structures are considered equal if they have the same number of free parameters, the same derivation order, and the same derivatives.
-
-