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.
DerivativeStructureinstances 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
differentiatorsto 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 thesizeexpected 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:
getRealin 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:
addin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
add
public DerivativeStructure add(DerivativeStructure a)
- Specified by:
addin interfaceFieldElement<DerivativeStructure>- Throws:
DimensionMismatchException- if number of free parameters or orders do not match.
-
subtract
public DerivativeStructure subtract(double a)
- Specified by:
subtractin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
subtract
public DerivativeStructure subtract(DerivativeStructure a)
- Specified by:
subtractin interfaceFieldElement<DerivativeStructure>- Throws:
DimensionMismatchException- if number of free parameters or orders do not match
-
multiply
public DerivativeStructure multiply(int n)
- Specified by:
multiplyin interfaceFieldElement<DerivativeStructure>
-
multiply
public DerivativeStructure multiply(double a)
- Specified by:
multiplyin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
multiply
public DerivativeStructure multiply(DerivativeStructure a)
- Specified by:
multiplyin interfaceFieldElement<DerivativeStructure>- Throws:
DimensionMismatchException- if number of free parameters or orders do not match
-
divide
public DerivativeStructure divide(double a)
- Specified by:
dividein interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
divide
public DerivativeStructure divide(DerivativeStructure a)
- Specified by:
dividein interfaceFieldElement<DerivativeStructure>- Throws:
DimensionMismatchException- if number of free parameters or orders do not match
-
remainder
public DerivativeStructure remainder(double a)
- Specified by:
remainderin interfaceRealFieldElement<DerivativeStructure>
-
remainder
public DerivativeStructure remainder(DerivativeStructure a)
- Specified by:
remainderin interfaceRealFieldElement<DerivativeStructure>- Throws:
DimensionMismatchException- if number of free parameters or orders do not match- Since:
- 3.2
-
negate
public DerivativeStructure negate()
- Specified by:
negatein interfaceFieldElement<DerivativeStructure>
-
abs
public DerivativeStructure abs()
- Specified by:
absin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
ceil
public DerivativeStructure ceil()
- Specified by:
ceilin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
floor
public DerivativeStructure floor()
- Specified by:
floorin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
rint
public DerivativeStructure rint()
- Specified by:
rintin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
round
public long round()
- Specified by:
roundin interfaceRealFieldElement<DerivativeStructure>
-
signum
public DerivativeStructure signum()
- Specified by:
signumin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
copySign
public DerivativeStructure copySign(DerivativeStructure sign)
- Specified by:
copySignin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
copySign
public DerivativeStructure copySign(double sign)
- Specified by:
copySignin 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:
scalbin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
hypot
public DerivativeStructure hypot(DerivativeStructure y)
- Specified by:
hypotin 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 sidesxandy- 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:
reciprocalin interfaceFieldElement<DerivativeStructure>- Specified by:
reciprocalin interfaceRealFieldElement<DerivativeStructure>
-
sqrt
public DerivativeStructure sqrt()
- Specified by:
sqrtin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
cbrt
public DerivativeStructure cbrt()
- Specified by:
cbrtin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
rootN
public DerivativeStructure rootN(int n)
- Specified by:
rootNin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
getField
public Field<DerivativeStructure> getField()
- Specified by:
getFieldin 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:
powin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
pow
public DerivativeStructure pow(int n)
- Specified by:
powin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
pow
public DerivativeStructure pow(DerivativeStructure e)
- Specified by:
powin interfaceRealFieldElement<DerivativeStructure>- Throws:
DimensionMismatchException- if number of free parameters or orders do not match- Since:
- 3.2
-
exp
public DerivativeStructure exp()
- Specified by:
expin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
expm1
public DerivativeStructure expm1()
- Specified by:
expm1in interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
log
public DerivativeStructure log()
- Specified by:
login interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
log1p
public DerivativeStructure log1p()
- Specified by:
log1pin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
log10
public DerivativeStructure log10()
Base 10 logarithm.- Specified by:
log10in interfaceRealFieldElement<DerivativeStructure>- Returns:
- base 10 logarithm of the instance
-
cos
public DerivativeStructure cos()
- Specified by:
cosin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
sin
public DerivativeStructure sin()
- Specified by:
sinin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
tan
public DerivativeStructure tan()
- Specified by:
tanin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
acos
public DerivativeStructure acos()
- Specified by:
acosin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
asin
public DerivativeStructure asin()
- Specified by:
asinin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
atan
public DerivativeStructure atan()
- Specified by:
atanin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
atan2
public DerivativeStructure atan2(DerivativeStructure x)
- Specified by:
atan2in 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:
coshin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
sinh
public DerivativeStructure sinh()
- Specified by:
sinhin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
tanh
public DerivativeStructure tanh()
- Specified by:
tanhin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
acosh
public DerivativeStructure acosh()
- Specified by:
acoshin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
asinh
public DerivativeStructure asinh()
- Specified by:
asinhin interfaceRealFieldElement<DerivativeStructure>- Since:
- 3.2
-
atanh
public DerivativeStructure atanh()
- Specified by:
atanhin 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:
linearCombinationin 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:
linearCombinationin 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:
linearCombinationin 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:
linearCombinationin 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:
linearCombinationin 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:
linearCombinationin 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:
linearCombinationin 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:
linearCombinationin 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.
-
-