IGLib  1.7.2
The IGLib base library EXTENDED - with other lilbraries and applications.
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Events Macros
Meta.Numerics.Analysis.FunctionMath Class Reference

Contains methods for the analysis of functions. More...

+ Collaboration diagram for Meta.Numerics.Analysis.FunctionMath:

Static Public Member Functions

static Extremum FindMaximum (Func< double, double > f, double x)
 Maximizes a function in the vicinity of a given point. More...
 
static Extremum FindMaximum (Func< double, double > f, double x, EvaluationSettings settings)
 Maximizes a function in the vicinity of a given point, subject to the given evaluation settings. More...
 
static Extremum FindMinimum (Func< double, double > f, double x)
 Minimizes a function in the vicinity of a given point. More...
 
static Extremum FindMinimum (Func< double, double > f, double x, EvaluationSettings settings)
 Minimizes a function in the vicinity of a given point subject to the given evaluation settings. More...
 
static Extremum FindMaximum (Func< double, double > f, Interval r)
 Maximizes a function on the given interval. More...
 
static Extremum FindMaximum (Func< double, double > f, Interval r, EvaluationSettings settings)
 Maximizes a function on the given interval, subject to the given evaluation settings. More...
 
static Extremum FindMinimum (Func< double, double > f, Interval r)
 Minimizes a function on the given interval. More...
 
static Extremum FindMinimum (Func< double, double > f, Interval r, EvaluationSettings settings)
 Minimizes a function on the given interval, subject to the given evaluation settings. More...
 
static double Integrate (Func< double, double > integrand, Interval range)
 Evaluates a definite integral. More...
 
static IntegrationResult Integrate (Func< double, double > integrand, Interval range, EvaluationSettings settings)
 Evaluates a definite integral with the given evaluation settings. More...
 
static SpaceExtremum FindMinimum (Func< double[], double > f, double[] x)
 Minimizes a function on a multi-dimensional space in the vicinity of a given point. More...
 
static SpaceExtremum FindMinimum (Func< double[], double > f, double[] x, EvaluationSettings settings)
 Minimizes a function on a multi-dimensional space in the vicinity of a given point, subject to the given settings. More...
 
static SpaceExtremum FindMaximum (Func< double[], double > f, double[] x, EvaluationSettings settings)
 Maximizes a function on a multi-dimensional space in the vicinity of a given point, subject to the given settings. More...
 
static double FindZero (Func< double, double > f, double x)
 Isolates a root in the vicinity of a given point. More...
 
static double FindZero (Func< double, double > f, Interval bracket)
 Isolates a root within a given interval. More...
 
static double[] FindZero (Func< double[], double[]> f, double[] x0)
 Finds a vector argument which makes a vector function zero. More...
 

Static Private Member Functions

static Extremum FindMinimum (Functor f, double x, EvaluationSettings settings)
 
static Extremum FindMinimum (Functor f, double x, double fx, double d, EvaluationSettings settings)
 
static Extremum FindMinimum (Functor f, double a, double b, EvaluationSettings settings)
 
static Extremum FindMinimum (Functor f, double a, double b, double u, double fu, double v, double fv, double w, double fw, EvaluationSettings settings)
 
static void ParabolicFit (double x1, double f1, double x2, double f2, double x3, double f3, out double x0, out double fpp)
 
static IntegrationResult Integrate_Adaptive (IAdaptiveIntegrator integrator, EvaluationSettings s)
 
static SymmetricMatrix ComputeCurvature (Func< double[], double > f, double[] x)
 
static double FindZero (Func< double, double > f, double x1, double f1, double x2, double f2)
 
static SquareMatrix ApproximateJacobian (Func< double[], double[]> f, double[] x0)
 

Static Private Attributes

static readonly double RelativePrecision = Math.Pow(2.0, -48)
 
static readonly double AbsolutePrecision = Math.Pow(2.0, -192)
 
static readonly EvaluationSettings DefaultExtremaSettings = new EvaluationSettings() { EvaluationBudget = 128, RelativePrecision = 0.0, AbsolutePrecision = 0.0 }
 

Detailed Description

Contains methods for the analysis of functions.

Function analysis includes integration, finding maxima and minima, and finding roots.

This class contains methods for the analysis of functions that both accept a single real argument and return a single real value. For the analysis of multi-dimensional functions, see the MultiFunctionMath class.

Member Function Documentation

static Extremum Meta.Numerics.Analysis.FunctionMath.FindMaximum ( Func< double, double >  f,
double  x 
)
inlinestatic

Maximizes a function in the vicinity of a given point.

Parameters
fThe function.
xA point suspected to be near the maximum. The search begins at this point.
Returns
The maximum.
Exceptions
ArgumentNullExceptionf is null.
NonconvergenceExceptionMore than the maximum allowed number of function evaluations occured without a maximum being determined.

Referenced by Test.ExtremaTest.FindMaximaFromInterval(), and Test.ExtremaTest.FindMaximaFromPoint().

static Extremum Meta.Numerics.Analysis.FunctionMath.FindMaximum ( Func< double, double >  f,
double  x,
EvaluationSettings  settings 
)
inlinestatic

Maximizes a function in the vicinity of a given point, subject to the given evaluation settings.

Parameters
fThe function.
xA point suspected to be near the maximum. The search begins at this point.
settingsThe settings to use when searching for the maximum.
Returns
The maximum.
Exceptions
ArgumentNullExceptionf is null or settings is null.
NonconvergenceExceptionMore than the maximum allowed number of function evaluations occured without a maximum being determined to the prescribed precision.

When you supply settings , note that the supplied EvaluationSettings.RelativePrecision and EvaluationSettings.AbsolutePrecision values refer to argument (i.e. x) values, not function (i.e. f) values. Note also that, for typical functions, the best attainable relative precision is of the order of the square root of machine precision (about 10-7), i.e. half the number of digits in a Double. This is because to identify an extremum we need to resolve changes in the function value, and near an extremum &#x3B4;f &#x223C; (&#x3B4;x)2, so changes in the function value &#x3B4;f &#x223C; &#x3B5; correspond to changes in the argument value &#x3B4;x &#x223C; &#x221A;&#x3B5;. If you supply zero values for both precision settings, the method will adaptively approximate the best attainable precision for the supplied function and locate the extremum to that resolution. This is our suggested practice unless you know that you require a less precise determination.

static Extremum Meta.Numerics.Analysis.FunctionMath.FindMinimum ( Func< double, double >  f,
double  x 
)
inlinestatic

Minimizes a function in the vicinity of a given point.

Parameters
fThe function.
xA point suspected to be near the minimum. The search begins at this point.
Returns
The minimum.
Exceptions
ArgumentNullExceptionf is null.
NonconvergenceExceptionMore than the maximum allowed number of function evaluations occured without a minimum being determined.

Referenced by Test.ExtremaTest.FindMinimaFromInterval(), Test.ExtremaTest.FindMinimaFromPoint(), Test.ExtremaTest.FindMinimumOfGamma(), Test.ExtremaTest.FindSpaceMinimumOfRosenbock(), Meta.Numerics.Statistics.UncertainMeasurementSample< T >.FitToFunction(), Meta.Numerics.Statistics.Sample.MaximumLikelihoodFit(), Test.ExtremaTest.MinimizeGoldsteinPrice(), Test.MultiExtremumTest.Quadratic(), and FutureTest.FutureTest.TestOldMinimization().

static Extremum Meta.Numerics.Analysis.FunctionMath.FindMinimum ( Func< double, double >  f,
double  x,
EvaluationSettings  settings 
)
inlinestatic

Minimizes a function in the vicinity of a given point subject to the given evaluation settings.

Parameters
fThe function.
xA point suspected to be near the minimum. The search begins at this point.
settingsThe settings to use when searching for the minimum.
Returns
The minimum.
Exceptions
ArgumentNullExceptionf is null or settings is null.
NonconvergenceExceptionMore than the maximum allowed number of function evaluations occured without a minimum being determined to the prescribed precision.

When you supply settings , note that the supplied EvaluationSettings.RelativePrecision and EvaluationSettings.AbsolutePrecision values refer to argument (i.e. x) values, not function (i.e. f) values. Note also that, for typical functions, the best attainable relative precision is of the order of the square root of machine precision (about 10-7), i.e. half the number of digits in a Double. This is because to identify an extremum we need to resolve changes in the function value, and near an extremum &#x3B4;f &#x223C; (&#x3B4;x)2, so changes in the function value &#x3B4;f &#x223C; &#x3B5; correspond to changes in the argument value &#x3B4;x &#x223C; &#x221A;&#x3B5;. If you supply zero values for both precision settings, the method will adaptively approximate the best attainable precision for the supplied function and locate the extremum to that resolution. This is our suggested practice unless you know that you require a less precise determination.

Since the search algorithm begins by evaluating f at points near x , it can fail if x is near a singularity or other point at which the evaluation of f could fail. If you can reliably bracket an extremum, the FindMinimum(Func{Double,Double},Interval,EvaluationSettings) overload of this method is safer and, if your bracket is any good, usually slightly faster.

static Extremum Meta.Numerics.Analysis.FunctionMath.FindMinimum ( Functor  f,
double  x,
EvaluationSettings  settings 
)
inlinestaticprivate
static Extremum Meta.Numerics.Analysis.FunctionMath.FindMinimum ( Functor  f,
double  x,
double  fx,
double  d,
EvaluationSettings  settings 
)
inlinestaticprivate
static Extremum Meta.Numerics.Analysis.FunctionMath.FindMaximum ( Func< double, double >  f,
Interval  r 
)
inlinestatic

Maximizes a function on the given interval.

Parameters
fThe function.
rThe interval.
Returns
The maximum.
Exceptions
ArgumentNullExceptionf is null.
NonconvergenceExceptionMore than the maximum allowed number of function evaluations occured without a minimum being determined.
static Extremum Meta.Numerics.Analysis.FunctionMath.FindMaximum ( Func< double, double >  f,
Interval  r,
EvaluationSettings  settings 
)
inlinestatic

Maximizes a function on the given interval, subject to the given evaluation settings.

Parameters
fThe function.
rThe interval.
settingsThe settings used when searching for the maximum.
Returns
The maximum.
Exceptions
ArgumentNullExceptionf is null or settings is null.
NonconvergenceExceptionMore than the maximum allowed number of function evaluations occured without a maximum being determined to the prescribed precision.

When you supply settings , note that the supplied EvaluationSettings.RelativePrecision and EvaluationSettings.AbsolutePrecision values refer to argument (i.e. x) values, not function (i.e. f) values. Note also that, for typical functions, the best attainable relative precision is of the order of the square root of machine precision (about 10-7), i.e. half the number of digits in a Double. This is because to identify an extremum we need to resolve changes in the function value, and near an extremum &#x3B4;f &#x223C; (&#x3B4;x)2, so changes in the function value &#x3B4;f &#x223C; &#x3B5; correspond to changes in the argument value &#x3B4;x &#x223C; &#x221A;&#x3B5;. If you supply zero values for both precision settings, the method will adaptively approximate the best attainable precision for the supplied function and locate the extremum to that resolution. This is our suggested practice unless you know that you require a less precise determination.

References Meta.Numerics.Interval.LeftEndpoint, and Meta.Numerics.Interval.RightEndpoint.

static Extremum Meta.Numerics.Analysis.FunctionMath.FindMinimum ( Func< double, double >  f,
Interval  r 
)
inlinestatic

Minimizes a function on the given interval.

Parameters
fThe function.
rThe interval.
Returns
The minimum.
Exceptions
ArgumentNullExceptionf is null.
NonconvergenceExceptionMore than the maximum allowed number of function evaluations occured without a minimum being determined.
static Extremum Meta.Numerics.Analysis.FunctionMath.FindMinimum ( Func< double, double >  f,
Interval  r,
EvaluationSettings  settings 
)
inlinestatic

Minimizes a function on the given interval, subject to the given evaluation settings.

Parameters
fThe function.
rThe interval.
settingsThe settings used when searching for the minimum.
Returns
The minimum.
Exceptions
ArgumentNullExceptionf is null or settings is null.
NonconvergenceExceptionMore than the maximum allowed number of function evaluations occured without a minimum being determined to the prescribed precision.

When you supply settings , note that the supplied EvaluationSettings.RelativePrecision and EvaluationSettings.AbsolutePrecision values refer to argument (i.e. x) values, not function (i.e. f) values. Note also that, for typical functions, the best attainable relative precision is of the order of the square root of machine precision (about 10-7), i.e. half the number of digits in a Double. This is because to identify an extremum we need to resolve changes in the function value, and near an extremum &#x3B4;f &#x223C; (&#x3B4;x)2, so changes in the function value &#x3B4;f &#x223C; &#x3B5; correspond to changes in the argument value &#x3B4;x &#x223C; &#x221A;&#x3B5;. If you supply zero values for both precision settings, the method will adaptively approximate the best attainable precision for the supplied function and locate the extremum to that resolution. This is our suggested practice unless you know that you require a less precise determination.

References Meta.Numerics.Interval.LeftEndpoint, and Meta.Numerics.Interval.RightEndpoint.

static Extremum Meta.Numerics.Analysis.FunctionMath.FindMinimum ( Functor  f,
double  a,
double  b,
EvaluationSettings  settings 
)
inlinestaticprivate
static Extremum Meta.Numerics.Analysis.FunctionMath.FindMinimum ( Functor  f,
double  a,
double  b,
double  u,
double  fu,
double  v,
double  fv,
double  w,
double  fw,
EvaluationSettings  settings 
)
inlinestaticprivate
static void Meta.Numerics.Analysis.FunctionMath.ParabolicFit ( double  x1,
double  f1,
double  x2,
double  f2,
double  x3,
double  f3,
out double  x0,
out double  fpp 
)
inlinestaticprivate
static double Meta.Numerics.Analysis.FunctionMath.Integrate ( Func< double, double >  integrand,
Interval  range 
)
inlinestatic

Evaluates a definite integral.

Parameters
integrandThe function to be integrated.
rangeThe range of integration.
Returns
A numerical estimate of the given integral.

Integral values are accurate to within about a digit of full double precision.

To do integrals over infinite regions, simply set the lower bound of the range to System.Double.NegativeInfinity or the upper bound to System.Double.PositiveInfinity.

Our numerical integrator uses a Gauss-Kronrod rule that can integrate efficiently, combined with an adaptive strategy that limits function evaluations to those regions required to achieve the desired accuracy.

Our integrator handles smooth functions extremely efficiently. It handles integrands with discontinuities, or discontinuities of derivatives, at the price of slightly more evaluations of the integrand. It handles oscilatory functions, so long as not too many periods contribute significantly to the integral. It can integrate logarithmic and mild power-law singularities.

Strong power-law singularities will cause the alrorighm to fail with a NonconvergenceException. This is unavoidable for essentially any double-precision numerical integrator. Consider, for example, the integrable singularity 1/&#x221A;x. Since &#x3B5; = &#x222B;0&#x3B4; x-1/2 dx = 2 &#x3B4;1/2, points within &#x3B4; &#x223C; 10-16 of the end-points, which as a close as you can get to a point in double precision without being on top of it, contribute at the &#x3B5; &#x223C; 10-8 level to our integral, well beyond limit that nearly-full double precision requires. Said differently, to know the value of the integral to &#x3B5; &#x223C; 10-16 prescision, we would need to evaluate the contributions of points within &#x3B4; &#x223C; 10-32 of the endpoints, far closer than we can get.

If you need to evaluate an integral with such a strong singularity, make an analytic change of variable to absorb the singularity before attempting numerical integration. For example, to evaluate I = &#x222B;0b f(x) x-1/2 dx, substitute y = x1/2 to obtain I = 2 &#x222B;0&#x221A;b f(y2) dy.

Referenced by Test.AdvancedMathTest.AiryBairyIntegral(), Test.AdvancedMathTest.AiryIntegral(), Test.AdvancedMathTest.AiryIntegrals(), Test.OrthogonalPolynomialsTest.AssociatedLaguerreOrthonormality(), Test.OrthogonalPolynomialsTest.AssociatedLegendreOrthonormalityL(), Test.AdvancedMathTest.BesselJ0Integral(), Test.AdvancedMathTest.BesselKapteynIntegral(), Test.AdvancedMathTest.BesselLipshitzIntegral(), Test.AdvancedMathTest.BesselWeberIntegral(), Test.AdvancedMathTest.BesselY0Integral(), Test.AdvancedMathTest.BetaIntegral(), Test.AdvancedMathTest.CatalanIntegralTest(), Test.AdvancedMathTest.ClausenIntegral(), Test.AdvancedMathTest.DawsonIntegralTest(), Test.AdvancedMathTest.DiLogExpIntegral(), Test.AdvancedMathTest.DiLogLogIntegral(), Test.DistributionTest.DistributionCentralMomentIntegral(), Test.DistributionTest.DistributionMeanIntegral(), Test.DistributionTest.DistributionProbabilityIntegral(), Test.DistributionTest.DistributionRawMomentIntegral(), Test.DistributionTest.DistributionUnitarityIntegral(), Test.DistributionTest.DistributionVarianceIntegral(), Test.AdvancedMathTest.EllipticEIntegration(), Test.AdvancedMathTest.EllipticFIntegral(), Test.AdvancedMathTest.EllipticFIntegration(), Test.AdvancedMathTest.EllipticKCatalanIntegral(), Test.AdvancedMathTest.EllipticKIntegration(), Test.AdvancedMathTest.ErfcIntegral(), Test.AdvancedMathTest.ErfIntegralTest(), Meta.Numerics.Statistics.Distributions.Distribution.ExpectationValue(), Test.AdvancedMathTest.FresnelCIntegralTest(), Test.AdvancedMathTest.FresnelSIntegralTest(), Test.AdvancedMathTest.GammaIntegral(), Test.OrthogonalPolynomialsTest.HermiteOrthonormality(), Test.AdvancedMathTest.IntegerBesselJIntegral(), Test.AdvancedMathTest.IntegralCiSiIntegrals(), Test.AdvancedMathTest.IntegralEIntegral(), Test.AdvancedMathTest.IntegralSiDefinition(), Test.IntegrateTest.IntegrateTestIntegrals(), Test.AdvancedMathTest.InverseErfIntegralTest(), Test.OrthogonalPolynomialsTest.LaguerreOrthonormality(), Meta.Numerics.Statistics.Distributions.Distribution.LeftProbability(), Test.OrthogonalPolynomialsTest.LegendreOrthonormality(), Test.AdvancedMathTest.ModifiedBesselIntegralTest(), Test.AdvancedMathTest.PolyGammaIntegral(), Test.AdvancedMathTest.PolyLogIntegration(), Test.PolynomialTest.PolynomialCalculus(), Test.AdvancedMathTest.RealBesselJIntegral(), Test.SampleTest.TestMoments(), FutureTest.FutureTest.TestNormalOrderStatistic(), Test.SpinTest.ThreeJLegendreIntegral(), Test.OrthogonalPolynomialsTest.ZernikeBessel(), and Test.OrthogonalPolynomialsTest.ZernikeOrthonormality().

static IntegrationResult Meta.Numerics.Analysis.FunctionMath.Integrate ( Func< double, double >  integrand,
Interval  range,
EvaluationSettings  settings 
)
inlinestatic

Evaluates a definite integral with the given evaluation settings.

Parameters
integrandThe function to be integrated.
rangeThe range of integration.
settingsThe settings which control the evaulation of the integal.
Returns
The result of the integral, which includes an estimated value and estimated uncertainty of that value.

References Meta.Numerics.Interval.FromEndpoints(), Meta.Numerics.Interval.LeftEndpoint, and Meta.Numerics.Interval.RightEndpoint.

static SpaceExtremum Meta.Numerics.Analysis.FunctionMath.FindMinimum ( Func< double[], double >  f,
double[]  x 
)
inlinestatic

Minimizes a function on a multi-dimensional space in the vicinity of a given point.

Parameters
fThe function.
xThe starting point for the search.
Returns
The minimum.
Exceptions
ArgumentNullExceptionf or x is null
NonconvergenceExceptionThe minimum was not found to the required precision within the budgeted number of function evaluations.
static SpaceExtremum Meta.Numerics.Analysis.FunctionMath.FindMinimum ( Func< double[], double >  f,
double[]  x,
EvaluationSettings  settings 
)
inlinestatic

Minimizes a function on a multi-dimensional space in the vicinity of a given point, subject to the given settings.

Parameters
fThe function.
xThe starting point for the search.
settingsThe evaluation settings.
Returns
The minimum.
Exceptions
ArgumentNullExceptionf , x , or settings is null.
NonconvergenceExceptionThe minimum was not found to the required precision within the budgeted number of function evaluations.

References Meta.Numerics.Analysis.EvaluationSettings.AbsolutePrecision, Meta.Numerics.Analysis.Extremum.Curvature, Meta.Numerics.Analysis.EvaluationSettings.EvaluationBudget, Meta.Numerics.Analysis.Extremum.Location, Meta.Numerics.Analysis.EvaluationSettings.RelativePrecision, and Meta.Numerics.Analysis.Extremum.Value.

static SymmetricMatrix Meta.Numerics.Analysis.FunctionMath.ComputeCurvature ( Func< double[], double >  f,
double[]  x 
)
inlinestaticprivate
static SpaceExtremum Meta.Numerics.Analysis.FunctionMath.FindMaximum ( Func< double[], double >  f,
double[]  x,
EvaluationSettings  settings 
)
inlinestatic

Maximizes a function on a multi-dimensional space in the vicinity of a given point, subject to the given settings.

Parameters
fThe function.
xThe starting point for the search.
settingsThe evaluation settings.
Returns
The maximum.
Exceptions
ArgumentNullExceptionf , x , or settings is null.
NonconvergenceExceptionThe maximum was not found to the required precision within the budgeted number of function evaluations.
static double Meta.Numerics.Analysis.FunctionMath.FindZero ( Func< double, double >  f,
Interval  bracket 
)
inlinestatic

Isolates a root within a given interval.

Parameters
fThe function whoose zero is sought.
bracketAn interval bracketing the root.
Returns
An ordinate within the bracket at which the function has a zero.
Exceptions
InvalidOperationExceptionThe function does not change sign across the given interval.

References Meta.Numerics.Interval.LeftEndpoint, and Meta.Numerics.Interval.RightEndpoint.

static double Meta.Numerics.Analysis.FunctionMath.FindZero ( Func< double, double >  f,
double  x1,
double  f1,
double  x2,
double  f2 
)
inlinestaticprivate
static double [] Meta.Numerics.Analysis.FunctionMath.FindZero ( Func< double[], double[]>  f,
double[]  x0 
)
inlinestatic

Finds a vector argument which makes a vector function zero.

Parameters
fThe vector function.
x0The vector argument.
Returns
The vector argument which makes all components of the vector function zero.
Exceptions
ArgumentNullExceptionf or x0 is null.
DimensionMismatchExceptionThe dimension of f is not equal to the dimension of x0 .

References Meta.Numerics.Matrices.VectorBase.Dimension, Meta.Numerics.Matrices.AnyRectangularMatrix.InfinityNorm(), Meta.Numerics.Matrices.SquareMatrix.LUDecomposition(), Meta.Numerics.Matrices.VectorBase.Norm(), Meta.Numerics.Matrices.LUDecomposition.Solve(), Meta.Numerics.Matrices.VectorBase.ToArray(), and Meta.Numerics.Matrices.RectangularMatrix.Transpose().

static SquareMatrix Meta.Numerics.Analysis.FunctionMath.ApproximateJacobian ( Func< double[], double[]>  f,
double[]  x0 
)
inlinestaticprivate

Member Data Documentation

readonly double Meta.Numerics.Analysis.FunctionMath.RelativePrecision = Math.Pow(2.0, -48)
staticprivate
readonly double Meta.Numerics.Analysis.FunctionMath.AbsolutePrecision = Math.Pow(2.0, -192)
staticprivate
readonly EvaluationSettings Meta.Numerics.Analysis.FunctionMath.DefaultExtremaSettings = new EvaluationSettings() { EvaluationBudget = 128, RelativePrecision = 0.0, AbsolutePrecision = 0.0 }
staticprivate

The documentation for this class was generated from the following files: