public class NumericalDerivatives extends Object implements Serializable, Cloneable
NumericalDerivatives uses divided finite differences to
compute the Jacobian. This class is designed for use in numerical methods
for solving nonlinear problems where a Jacobian is evaluated repeatedly at
neighboring arguments. For example this occurs in a Gauss-Newton method for
solving non-linear least squares problems or a non-linear optimization
NumericalDerivatives is suited for applications where the
Jacobian is a dense matrix. All cases ,
, or are allowed.
Both one-sided and central divided differences can be used.
The design allows for computation of derivatives in a variety of contexts.
Note that a gradient should be considered as the special case with
, . A derivative of a
single function of one variable is the case ,
. Any non-linear solving routine that optionally
requests a Jacobian or gradient can use
This should be considered if there are special properties or scaling issues
associated with . Use the method
setDifferencingMethods to specify different differencing
options for numerical differentiation. These can be combined with some
analytic subexpressions or other known relationships.
The divided differences are computed using values of the independent
variables at the initial point , and differenced
points . Here the
, are the unit coordinate vectors.
The value for each difference del depends on the variable j,
the differencing method, and the scaling for that variable. This difference
is computed internally. See
computational details. The evaluation of is
normally done by the user-provided method
using the values . The index j and values
are arguments to
The computational kernel of
evaluateJ performs the following
in step 3. The user may choose to override the
method to extend the capability of the class beyond the default.
There are six examples provided which illustrate various ways to use
NumericalDerivatives. A discussion of the expected errors for
these difference methods is found in A First Course in Numerical Analysis,
Anthony Ralston, McGraw-Hill, NY, (1965).
|Modifier and Type||Class and Description|
Public interface function.
Public interface for the user-supplied function to compute the Jacobian.
|Modifier and Type||Field and Description|
Indicates the accumulation of the result from whatever type of differences have been specified previously into initial values of the Jacobian.
Indicates central differences.
Indicates one sided differences.
Indicates a variable to be skipped.
|Constructor and Description|
|Modifier and Type||Method and Description|
This method is provided by the user to compute the function values at the current independent variable values
Evaluates the Jacobian for a system of (m) equations in (n) variables.
Returns the percentage factor for differencing.
Returns the scaling factors for the
Returns status information.
Sets the methods used to compute the derivatives
Set the initial function values.
Sets the percentage factor for differencing
Sets the scaling factors for the
public static final int ACCUMULATE
public static final int CENTRAL
public static final int ONE_SIDED
public static final int SKIP
public NumericalDerivatives(NumericalDerivatives.Function fcn)
Functionobject which is a user-supplied function to evaluate the equations at the point
protected double evaluateF(int varIndex, double y)
y. If the user does not override the
NumericalDerivatives.Function.fis used to compute the function values.
intwhich indicates the index of the variable to perturb.
doublearray of length n, the point at which the function is to be evaluated.
doublearray of length m. The equations evaluated at the point
public double evaluateJ(double y)
doublearray of length n, the point at which the Jacobian is to be evaluated.
doublematrix containing the Jacobian. Columns that are accumulated must have the additive term defined on entry or else be set to zero. Columns that are skipped can be defined either before or after the
evaluateJmethod is invoked.
public double getPercentageFactor()
doublearray containing the percentage factor for differencing. See
setPercentageFactorfor more detail.
public double getScalingFactors()
doublearray containing the scaling factors.
public int getStatus()
intarray containing the ten diagnostic values described in the following table. These values can be used to monitor the progress or expense of the Jacobian computation.
|0||the number of times a function evaluation was computed.|
|1||the number of columns in which three attempts were
made to increase a percentage factor for differencing (i.e. a component
|2||the number of columns in which the computed del was
zero to machine precision because
|3||the number of Jacobian columns which had to be recomputed
because the largest difference formed in the column was close to zero
relative to scale, where
and i denotes the row index of the largest difference in the column currently being processed. index = 9 gives the last column where this occurred.
|4||the number of columns whose largest difference is close to zero relative to scale after the column has been recomputed.|
|5||the number of times scale information was not available
for use in the roundoff and truncation error tests. This occurs when
where i is the index of the largest difference for the column currently being processed.
|6||the number of times the increment for differencing (del)
was computed and had to be increased because (
|7||the number of times a component of the
|8||the index of the last column where the corresponding
component of the
|9||the index of the last column where the difference was small and the column had to be recomputed with an adjusted increment (see index = 3). The largest derivative in this column may be inaccurate due to excessive roundoff error.|
public void setDifferencingMethods(int options)
intarray of length n, containing the methods used to compute the derivatives.
options[i]is the method to be used for the i-th variable.
options[i]can be one of the values in the table which follows. The default is to use
ONE_SIDEDdifferences for each variable.
||Indicates one sided differences.|
||Indicates central differences.|
||Indicates the accumulation of the result from whatever type of differences have been specified previously into initial values of the Jacobian.|
||Indicates a variable to be skipped.|
public void setInitialF(double valueF)
doublearray of length m containing the initial function values, . Default: all values are 0.0.
public void setPercentageFactor(double factor)
For each divided difference for variable j the increment used
is del. The value of del is computed as follows: First
define . If the
user has set the elements of array
scale to non-default
values, then define
. Finally compute
. By changing
the sign of
scale[j-1], the difference del can have
any desired orientation, such as staying within bounds on variable
j. For central differences, a reduced factor is used for
del that normally results in relative errors as small as machine
precision to the 2/3 power.
doublearray of length n containing the percentage factor for differencing. Except for initialization, the
factorarray should not be altered in the
evaluateFmethod. The elements of
factormust be such that
where 1.8189894035458565e-12 is machine precision to the three-fourths power.
factorare set to 1.4901161193847656e-8, which is the square root of machine precision.
public void setScalingFactors(double scale)
yvalues. The user can also use
scaleto provide appropriate signs for the increments.
doublearray of length n containing the scaling factors. Default: all values are 1.0.
Copyright © 1970-2015 Rogue Wave Software
Built October 13 2015.