Class Gradient
- All Implemented Interfaces:
Serializable,Derivative<Gradient>,Derivative1<Gradient>,DifferentialAlgebra,CalculusFieldElement<Gradient>,FieldElement<Gradient>
This class is a stripped-down version of DerivativeStructure
with derivation order limited to one.
It should have less overhead than DerivativeStructure in its domain.
This class is an implementation of Rall's numbers. 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.
Gradient 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 Derivative-based
classes (or in fact any CalculusFieldElement class) is
a tedious and error-prone task but has the advantage of not requiring users
to compute the derivatives by themselves and allowing to switch for one
derivative implementation to another as they all share the same filed API.
Instances of this class are guaranteed to be immutable.
- Since:
- 1.7
- See Also:
-
Constructor Summary
ConstructorsConstructorDescriptionGradient(double value, double... gradient) Build an instance with values and derivative.Build an instance from aDerivativeStructure. -
Method Summary
Modifier and TypeMethodDescriptionabs()absolute value.Compute this + a.Two arguments arc tangent operation.compose(double... f) Compute composition of the instance by a univariate function.compose(double f0, double f1) Compute composition of the instance by a univariate function differentiable at order 1.static Gradientconstant(int freeParameters, double value) Build an instance corresponding to a constant value.copySign(double sign) Returns the instance with the sign of the argument.Returns the instance with the sign of the argument.divide(double a) '÷' operator.Compute this ÷ a.booleanTest for the equality of two univariate derivatives.Get the addendum to the real value of the number.getField()Get theFieldto which the instance belongs.intGet the number of free parameters.double[]Get the gradient part of the function.doublegetPartialDerivative(int n) Get the partial derivative with respect to one parameter.doublegetPartialDerivative(int... orders) Get a partial derivative.doublegetValue()Get the value part of the function.inthashCode()Get a hashCode for the univariate derivative.Returns the hypotenuse of a triangle with sidesthisandy- sqrt(this2 +y2) avoiding intermediate overflow or underflow.linearCombination(double[] a, Gradient[] b) Compute a linear combination.linearCombination(double a1, Gradient b1, double a2, Gradient b2) Compute a linear combination.linearCombination(double a1, Gradient b1, double a2, Gradient b2, double a3, Gradient b3) Compute a linear combination.linearCombination(double a1, Gradient b1, double a2, Gradient b2, double a3, Gradient b3, double a4, Gradient b4) Compute a linear combination.linearCombination(Gradient[] a, Gradient[] b) Compute a linear combination.linearCombination(Gradient a1, Gradient b1, Gradient a2, Gradient b2) Compute a linear combination.Compute a linear combination.linearCombination(Gradient a1, Gradient b1, Gradient a2, Gradient b2, Gradient a3, Gradient b3, Gradient a4, Gradient b4) Compute a linear combination.multiply(double a) '×' operator.multiply(int n) Compute n × this.Compute this × a.negate()Returns the additive inverse ofthiselement.newInstance(double c) Create an instance corresponding to a constant real value.pow(double p) Power operation.static GradientCompute ax where a is a double and x aGradientpow(int n) Integer power operation.IEEE remainder operator.scalb(int n) Multiply the instance by a power of 2.sinCos()Combined Sine and Cosine operation.sinhCosh()Combined hyperbolic sine and cosine operation.Add an independent variable to the Taylor expansion.Compute this - a.doubletaylor(double... delta) Evaluate Taylor expansion a derivative structure.Convert radians to degrees, with error of less than 0.5 ULPConvert the instance to aDerivativeStructure.Convert degrees to radians, with error of less than 0.5 ULPstatic Gradientvariable(int freeParameters, int index, double value) Build aGradientrepresenting a variable.withValue(double v) Create a new object with new value (zeroth-order derivative, as passed as input) and same derivatives of order one and above.Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, waitMethods inherited from interface org.hipparchus.CalculusFieldElement
ceil, floor, getPi, isFinite, isInfinite, isNaN, norm, rint, round, sign, ulpMethods inherited from interface org.hipparchus.analysis.differentiation.Derivative
add, getExponent, getReal, pow, remainder, subtractMethods inherited from interface org.hipparchus.analysis.differentiation.Derivative1
acos, acosh, asin, asinh, atan, atanh, cbrt, cos, cosh, exp, expm1, getOrder, log, log10, log1p, reciprocal, rootN, sin, sinh, sqrt, square, tan, tanhMethods inherited from interface org.hipparchus.FieldElement
isZero
-
Constructor Details
-
Gradient
public Gradient(double value, double... gradient) Build an instance with values and derivative.- Parameters:
value- value of the functiongradient- gradient of the function
-
Gradient
Build an instance from aDerivativeStructure.- Parameters:
ds- derivative structure- Throws:
MathIllegalArgumentException- ifdsorder is not 1
-
-
Method Details
-
constant
Build an instance corresponding to a constant value.- Parameters:
freeParameters- number of free parameters (i.e. dimension of the gradient)value- constant value of the function- Returns:
- a
Gradientwith a constant value and all derivatives set to 0.0
-
variable
Build aGradientrepresenting a variable.Instances built using this method 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:
freeParameters- number of free parameters (i.e. dimension of the gradient)index- index of the variable (from 0 togetFreeParameters()- 1)value- value of the variable- Returns:
- a
Gradientwith a constant value and all derivatives set to 0.0 except the one atindexwhich will be set to 1.0
-
newInstance
Create an instance corresponding to a constant real value.- Specified by:
newInstancein interfaceCalculusFieldElement<Gradient>- Parameters:
c- constant real value- Returns:
- instance corresponding to a constant real value
-
withValue
Create a new object with new value (zeroth-order derivative, as passed as input) and same derivatives of order one and above.This default implementation is there so that no API gets broken by the next release, which is not a major one. Custom inheritors should probably overwrite it.
- Specified by:
withValuein interfaceDerivative<Gradient>- Parameters:
v- zeroth-order derivative of new represented function- Returns:
- new object with changed value
-
getAddendum
Get the addendum to the real value of the number.The addendum is considered to be the part that when added back to the
real partrecovers the instance. This means that whene.getReal()is finite (i.e. neither infinite nor NaN), thene.getAddendum().add(e.getReal())iseande.subtract(e.getReal())ise.getAddendum(). Beware that for non-finite numbers, these two equalities may not hold. The first equality (with the addition), always holds even for infinity and NaNs if the real part is independent of the addendum (this is the case for all derivatives types, as well as for complex and Dfp, but it is not the case for Tuple and FieldTuple). The second equality (with the subtraction), generally doesn't hold for non-finite numbers, because the subtraction generates NaNs.- Specified by:
getAddendumin interfaceCalculusFieldElement<Gradient>- Returns:
- real value
-
getValue
public double getValue()Get the value part of the function.- Specified by:
getValuein interfaceDerivative<Gradient>- Returns:
- value part of the value of the function
-
getGradient
public double[] getGradient()Get the gradient part of the function.- Returns:
- gradient part of the value of the function
- See Also:
-
getFreeParameters
public int getFreeParameters()Get the number of free parameters.- Specified by:
getFreeParametersin interfaceDifferentialAlgebra- Returns:
- number of free parameters
-
getPartialDerivative
Get a partial derivative.- Specified by:
getPartialDerivativein interfaceDerivative<Gradient>- Parameters:
orders- derivation orders with respect to each variable (if all orders are 0, the value is returned)- Returns:
- partial derivative
- Throws:
MathIllegalArgumentException- if the numbers of variables does not match the instanceMathIllegalArgumentException- if sum of derivation orders is larger than the instance limits- See Also:
-
getPartialDerivative
Get the partial derivative with respect to one parameter.- Parameters:
n- index of the parameter (counting from 0)- Returns:
- partial derivative with respect to the nth parameter
- Throws:
MathIllegalArgumentException- if n is either negative or larger or equal togetFreeParameters()
-
toDerivativeStructure
Convert the instance to aDerivativeStructure.- Returns:
- derivative structure with same value and derivative as the instance
-
add
Compute this + a.- Specified by:
addin interfaceFieldElement<Gradient>- Parameters:
a- element to add- Returns:
- a new element representing this + a
-
subtract
Compute this - a.- Specified by:
subtractin interfaceCalculusFieldElement<Gradient>- Specified by:
subtractin interfaceFieldElement<Gradient>- Parameters:
a- element to subtract- Returns:
- a new element representing this - a
-
multiply
Compute n × this. Multiplication by an integer number is defined as the following sum \[ n \times \mathrm{this} = \sum_{i=1}^n \mathrm{this} \]- Specified by:
multiplyin interfaceCalculusFieldElement<Gradient>- Specified by:
multiplyin interfaceFieldElement<Gradient>- Parameters:
n- Number of timesthismust be added to itself.- Returns:
- A new element representing n × this.
-
multiply
'×' operator.- Specified by:
multiplyin interfaceCalculusFieldElement<Gradient>- Parameters:
a- right hand side parameter of the operator- Returns:
- this×a
-
multiply
Compute this × a.- Specified by:
multiplyin interfaceFieldElement<Gradient>- Parameters:
a- element to multiply- Returns:
- a new element representing this × a
-
divide
'÷' operator.- Specified by:
dividein interfaceCalculusFieldElement<Gradient>- Parameters:
a- right hand side parameter of the operator- Returns:
- this÷a
-
divide
Compute this ÷ a.- Specified by:
dividein interfaceCalculusFieldElement<Gradient>- Specified by:
dividein interfaceFieldElement<Gradient>- Parameters:
a- element to divide by- Returns:
- a new element representing this ÷ a
-
remainder
IEEE remainder operator.- Specified by:
remainderin interfaceCalculusFieldElement<Gradient>- Parameters:
a- right hand side parameter of the operator- Returns:
- this - n × a where n is the closest integer to this/a
-
negate
Returns the additive inverse ofthiselement.- Specified by:
negatein interfaceFieldElement<Gradient>- Returns:
- the opposite of
this.
-
abs
absolute value.- Specified by:
absin interfaceCalculusFieldElement<Gradient>- Returns:
- abs(this)
-
copySign
Returns the instance with the sign of the argument. A NaNsignargument is treated as positive.- Specified by:
copySignin interfaceCalculusFieldElement<Gradient>- Parameters:
sign- the sign for the returned value- Returns:
- the instance with the same sign as the
signargument
-
copySign
Returns the instance with the sign of the argument. A NaNsignargument is treated as positive.- Specified by:
copySignin interfaceCalculusFieldElement<Gradient>- Parameters:
sign- the sign for the returned value- Returns:
- the instance with the same sign as the
signargument
-
scalb
Multiply the instance by a power of 2.- Specified by:
scalbin interfaceCalculusFieldElement<Gradient>- Parameters:
n- power of 2- Returns:
- this × 2n
-
hypot
Returns the hypotenuse of a triangle with sidesthisandy- sqrt(this2 +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.
- Specified by:
hypotin interfaceCalculusFieldElement<Gradient>- Parameters:
y- a value- Returns:
- sqrt(this2 +y2)
-
compose
Compute composition of the instance by a univariate function.- Specified by:
composein interfaceDerivative<Gradient>- Parameters:
f- array of value and derivatives of the function at the current point (i.e. [f(Derivative.getValue()), f'(Derivative.getValue()), f''(Derivative.getValue())...]).- Returns:
- f(this)
-
compose
Compute composition of the instance by a univariate function differentiable at order 1.- Specified by:
composein interfaceDerivative1<Gradient>- Parameters:
f0- value of functionf1- first-order derivative- Returns:
- f(this)
-
getField
Get theFieldto which the instance belongs.- Specified by:
getFieldin interfaceFieldElement<Gradient>- Returns:
Fieldto which the instance belongs
-
pow
Compute ax where a is a double and x aGradient- Parameters:
a- number to exponentiatex- power to apply- Returns:
- ax
-
pow
Power operation.- Specified by:
powin interfaceCalculusFieldElement<Gradient>- Parameters:
p- power to apply- Returns:
- thisp
-
pow
Integer power operation.- Specified by:
powin interfaceCalculusFieldElement<Gradient>- Parameters:
n- power to apply- Returns:
- thisn
-
sinCos
Combined Sine and Cosine operation.- Specified by:
sinCosin interfaceCalculusFieldElement<Gradient>- Specified by:
sinCosin interfaceDerivative1<Gradient>- Returns:
- [sin(this), cos(this)]
-
atan2
Two arguments arc tangent operation.Beware of the order or arguments! As this is based on a two-arguments functions, in order to be consistent with arguments order, the instance is the first argument and the single provided argument is the second argument. In order to be consistent with programming languages
atan2, this method computesatan2(this, x), i.e. the instance represents theyargument and thexargument is the one passed as a single argument. This may seem confusing especially for users of Wolfram alpha, as this site is not consistent with programming languagesatan2two-arguments arc tangent and putsxas its first argument.- Specified by:
atan2in interfaceCalculusFieldElement<Gradient>- Parameters:
x- second argument of the arc tangent- Returns:
- atan2(this, x)
-
sinhCosh
Combined hyperbolic sine and cosine operation.- Specified by:
sinhCoshin interfaceCalculusFieldElement<Gradient>- Specified by:
sinhCoshin interfaceDerivative1<Gradient>- Returns:
- [sinh(this), cosh(this)]
-
toDegrees
Convert radians to degrees, with error of less than 0.5 ULP- Specified by:
toDegreesin interfaceCalculusFieldElement<Gradient>- Returns:
- instance converted into degrees
-
toRadians
Convert degrees to radians, with error of less than 0.5 ULP- Specified by:
toRadiansin interfaceCalculusFieldElement<Gradient>- 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, ...
-
linearCombination
Compute a linear combination.- Specified by:
linearCombinationin interfaceCalculusFieldElement<Gradient>- Parameters:
a- Factors.b- Factors.- Returns:
Σi ai bi.
-
linearCombination
Compute a linear combination.- Specified by:
linearCombinationin interfaceCalculusFieldElement<Gradient>- Parameters:
a- Factors.b- Factors.- Returns:
Σi ai bi.
-
linearCombination
Compute a linear combination.- Specified by:
linearCombinationin interfaceCalculusFieldElement<Gradient>- Parameters:
a1- first factor of the first termb1- second factor of the first terma2- first factor of the second termb2- second factor of the second term- Returns:
- a1×b1 + a2×b2
- See Also:
-
linearCombination
Compute a linear combination.- Specified by:
linearCombinationin interfaceCalculusFieldElement<Gradient>- Parameters:
a1- first factor of the first termb1- second factor of the first terma2- first factor of the second termb2- second factor of the second term- Returns:
- a1×b1 + a2×b2
- See Also:
-
linearCombination
public Gradient linearCombination(Gradient a1, Gradient b1, Gradient a2, Gradient b2, Gradient a3, Gradient b3) Compute a linear combination.- Specified by:
linearCombinationin interfaceCalculusFieldElement<Gradient>- Parameters:
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 term- Returns:
- a1×b1 + a2×b2 + a3×b3
- See Also:
-
linearCombination
public Gradient linearCombination(double a1, Gradient b1, double a2, Gradient b2, double a3, Gradient b3) Compute a linear combination.- Specified by:
linearCombinationin interfaceCalculusFieldElement<Gradient>- Parameters:
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 term- Returns:
- a1×b1 + a2×b2 + a3×b3
- See Also:
-
linearCombination
public Gradient linearCombination(Gradient a1, Gradient b1, Gradient a2, Gradient b2, Gradient a3, Gradient b3, Gradient a4, Gradient b4) Compute a linear combination.- Specified by:
linearCombinationin interfaceCalculusFieldElement<Gradient>- Parameters:
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 fourth termb4- second factor of the fourth term- Returns:
- a1×b1 + a2×b2 + a3×b3 + a4×b4
- See Also:
-
linearCombination
public Gradient linearCombination(double a1, Gradient b1, double a2, Gradient b2, double a3, Gradient b3, double a4, Gradient b4) Compute a linear combination.- Specified by:
linearCombinationin interfaceCalculusFieldElement<Gradient>- Parameters:
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 fourth termb4- second factor of the fourth term- Returns:
- a1×b1 + a2×b2 + a3×b3 + a4×b4
- See Also:
-
stackVariable
Add an independent variable to the Taylor expansion.- Returns:
- object with one more variable
- Since:
- 4.0
-
equals
Test for the equality of two univariate derivatives.univariate derivatives are considered equal if they have the same derivatives.
-
hashCode
public int hashCode()Get a hashCode for the univariate derivative.
-