com.hedgehog.math.functions
Class OneVariableFunction

java.lang.Object
  com.hedgehog.HObject
      com.hedgehog.math.functions.Function
          com.hedgehog.math.functions.OneVariableFunction

All Implemented Interfaces:

java.lang.Comparable, java.util.Comparator

Direct Known Subclasses:

EFunction, EllipticIntegralFunction, OneVariablePeriodicFunction, OneVariableTrigFunction, SqrtFunction

public class OneVariableFunction
extends Function

Title: OneVariableFunction - represents a 1-variable function of signature HDouble function(HDouble x).

Description: Represents a one-argument method of form: HDouble function(HDouble x). Note that HDouble is used as opposed to Double because Double has no setValue() method which makes it difficult to use when returning values via reference.

Copyright: Copyright (c) Hedgehog Software 2007-2009.

Company: Hedgehog Software

Since:

1.0

Version:

1.1

Field Summary

Fields inherited from class com.hedgehog.math.functions.Function

method

Fields inherited from class com.hedgehog.HObject

mID, mName

Constructor Summary

OneVariableFunction()
Default constructor.

OneVariableFunction(java.lang.reflect.Method method)
Constructor.

OneVariableFunction(OneVariableFunction object)
Copy constructor.

OneVariableFunction(java.lang.String className, java.lang.String methodName)
Constructor.

Method Summary

double	bisection(java.lang.Object object, double x1, double x2, int max_iterations, double tolerance, HBoolean converged) Returns the root of this function using the bisection method.
HDouble	evaluate(java.lang.Object object, HDouble x) Evaluates the method for the supplied invoking object and argument.
double	firstOrderNewtonRaphson(java.lang.Object object, double x0, double h, int noOfDerivativePoints, int max_iterations, double tolerance, HInteger iterations_to_converge, HBoolean converged) Performs Newton-Raphson method on a function without a specified first-derivative function.
double	firstOrderNewtonRaphson(java.lang.Object object, double x0, java.lang.reflect.Method derivative, int max_iterations, double tolerance, HInteger iterations_to_converge, HBoolean converged) Performs Newton-Raphson method on a function with a specified first-derivative function.
double	gaussChebyshevIntegration(java.lang.Object object, Interval interval, int order) Gauss-Chebyshev integration over the interval [a:b] ; i.e., Int w(x)y(x)dx where w(x)=1/sqrt(1-x^2).
double	gaussianIntegration(java.lang.Object object, Interval interval, int order) Gaussian integration over the interval [a:b] order restricted to range [1:10] and a
boolean	isValid() Tests whether or not a valid object.
static boolean	isValid(java.lang.reflect.Method m) Static version of isValid().
PairDouble	optimisationBFGS(java.lang.Object object, Interval interval, double x0, java.lang.reflect.Method firstDerivative) Returns the minimum/maximum of the 1-variable function within the specified interval.
double	optimisationGA(java.lang.Object object, Interval interval, int populationSize, int maxAllowedEvolutions, java.lang.String xmlPathFileName, HDouble bestSolutionFitnessValue) Returns the maximum/minimum of the 1-variable function within the specified interval.
java.util.Vector<TripleIntDoubleDouble>	optimisationSwarm(java.lang.Object object, Interval interval, int nParticles, int nIterations, int neighbourhoodSize) Performs a particle-swarm optimisation of this function of one variable.
double	parabolicInterpolationMinimum(java.lang.Object object, double x1, double x2, double x3, HDouble xmin, HBoolean collinearPoints) Returns the minimum function value of a parabola through the three points f(x1), f(x2) and f(x3) at the minimum xmin.
double	richardsonFirstDerivative(java.lang.Object object, double x0, double r, double h) Returns the first derivative of the function at point x0 using Richardson extrapolation.
double	simpsonsIntegration(java.lang.Object object, double a, double b, int even_no_subintervals) Simpson's rule of integration over the interval [a,b].
double	taylorsSeriesFirstDerivative(java.lang.Object object, double x0, double h, int nPoints) Returns the first derivative using Taylor's series for either 2 or 4 points.
double	taylorsSeriesSecondDerivative(java.lang.Object object, double x0, double h, int nPoints) Returns the second derivative using Taylor's series for either 3 or 5 points.
double	trapezoidalIntegration(java.lang.Object object, Interval interval, int no_subintervals) Trapeziodal rule of integration over the interval [a,b]
int	turningPoint(java.lang.Object object, double xMinMaxInflexionPoint) Determines whether the function at the specified point is a maxima, minima or point of inflexion.

Methods inherited from class com.hedgehog.math.functions.Function

getMethod, setMethod, toString

Methods inherited from class com.hedgehog.HObject

clone, compare, compareTo, copy, equals, getID, getName, hashCode, hasID, hasName, setID, setName

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

OneVariableFunction

public OneVariableFunction()

Default constructor.

OneVariableFunction

public OneVariableFunction(java.lang.reflect.Method method)
                    throws java.lang.IllegalArgumentException

Constructor. Sets the function to the specified method. Encapsulated method is set to null if an invalid object is specified. For example:

 Class c = Class.forName("com.hedgehog.X") ;
 Class funcArg = Class.forName("com.hedgehog.types.HDouble");
 Class[] funcArgs = { funcArg } ;
 Method function = c.getMethod("function",funcArgs) ;
 OneVariableFunction ovf = new OneVariableFunction(function);
 

Parameters:

method - Function operated-on.

Throws:

java.lang.IllegalArgumentException - Thrown if an invalid method is supplied. If exception thrown then encapsulated method is set to null.

OneVariableFunction

public OneVariableFunction(java.lang.String className,
                           java.lang.String methodName)
                    throws java.lang.IllegalArgumentException

Constructor. Sets the function to the specified method, methodName by its String name. The class name, className, is also required and must be fully qualified. For example: OneVariableFunction ovf = new OneVariableFunction("com.hedgehog.X","function"); and specifically: com.hedgehog.math.functions.OneVariableFunction ovf = new com.hedgehog.math.functions.OneVariableFunction("com.hedgehog.math.functions.library.SinFunction","evaluate"); Encapsulated method is set to null if an invalid object is specified.

Parameters:

className - Fully qualified name of class that method belongs to.

methodName - Name of function operated-on.

Throws:

java.lang.IllegalArgumentException - Thrown if an invalid method is supplied. If exception thrown then encapsulated method is set to null.

OneVariableFunction

public OneVariableFunction(OneVariableFunction object)

Copy constructor.

Parameters:

object - Object to copy.

Method Detail

evaluate

public HDouble evaluate(java.lang.Object object,
                        HDouble x)

Evaluates the method for the supplied invoking object and argument. Facilitates evaluating the method by placing the try-catch block inside evaluate().

Parameters:

object - Invoking object.

x - Argument value.

Returns:

Evaluation of the method call with the supplied argument. If an error occurs invoking the method then a null object is returned.

firstOrderNewtonRaphson

public double firstOrderNewtonRaphson(java.lang.Object object,
                                      double x0,
                                      java.lang.reflect.Method derivative,
                                      int max_iterations,
                                      double tolerance,
                                      HInteger iterations_to_converge,
                                      HBoolean converged)
                               throws java.lang.IllegalArgumentException,
                                      java.lang.IllegalAccessException,
                                      java.lang.reflect.InvocationTargetException

Performs Newton-Raphson method on a function with a specified first-derivative function.

 For example, to compute the square root of 2:

 double x0=2.0;
 HInteger iterations_to_converge = new HInteger(0);
 HBoolean converged = new HBoolean(false);
 double nr = ovf.firstOrderNewtonRaphson(this,x0,derivative,100,1e-06,iterations_to_converge,converged);

 with function and derivative:

 public static Double function(Double x)
 {
   double xv = x.doubleValue();
   return new Double(xv*xv-2.0);
 }
 public static Double derivative(Double x)
 {
   double xv = x.doubleValue();
   return new Double(2.0*xv);
 }
 

Parameters:

object - Invoking object.

x0 - Initial starting point.

derivative - Derivative function. Must of type Double derivative(Double x).

max_iterations - Maximum number of iterations.

tolerance - Required tolerance; typically 1e-03.

iterations_to_converge - Set upon return to the number of iterations to acheive requested convergence.

converged - Set upon return to whether or not the routine converged.

Returns:

The solution of the Newton-Raphson method.

Throws:

java.lang.IllegalArgumentException - Thrown if the derivative function is invalid according to isValid().

java.lang.IllegalAccessException - Thrown if problem accessing the derivative function.

java.lang.reflect.InvocationTargetException - Thrown if problem invoking the derivative function.

firstOrderNewtonRaphson

public double firstOrderNewtonRaphson(java.lang.Object object,
                                      double x0,
                                      double h,
                                      int noOfDerivativePoints,
                                      int max_iterations,
                                      double tolerance,
                                      HInteger iterations_to_converge,
                                      HBoolean converged)
                               throws java.lang.IllegalArgumentException

Performs Newton-Raphson method on a function without a specified first-derivative function.

Parameters:

object - Invoking object.

x0 - Initial starting point.

h - Value of h for Taylor's series derivative.

noOfDerivativePoints - Number of points in Taylor's series derivative; either 2 or 4.

max_iterations - Maximum number of iterations.

tolerance - Required tolerance; typically 1e-03.

iterations_to_converge - Set upon return to the number of iterations to acheive requested convergence.

converged - Set upon return to whether or not the routine converged.

Returns:

The solution of the Newton-Raphson method.

Throws:

java.lang.IllegalArgumentException - Thrown if noOfDerivativePoints is not 2 or 4.

bisection

public double bisection(java.lang.Object object,
                        double x1,
                        double x2,
                        int max_iterations,
                        double tolerance,
                        HBoolean converged)

Returns the root of this function using the bisection method.

Parameters:

object - Invoking object.

x1 - Lower interval value.

x2 - Upper interval value.

max_iterations - Maximum number of iterations.

tolerance - Required tolerance.

converged - Set upon return to logical-true if a root is found, else logical-false.

Returns:

The root or NaN if no root is found.

gaussChebyshevIntegration

public double gaussChebyshevIntegration(java.lang.Object object,
                                        Interval interval,
                                        int order)
                                 throws java.lang.IllegalArgumentException

Gauss-Chebyshev integration over the interval [a:b] ; i.e., Int w(x)y(x)dx where w(x)=1/sqrt(1-x^2).

Parameters:

object - Invoking object.

interval - Interval of intergration.

order - Order of integration; restricted to range [1:10].

Returns:

Evaluation of the Gauss-Chebyshev integration.

Throws:

java.lang.IllegalArgumentException - exception if order < 1 or b

gaussianIntegration

public double gaussianIntegration(java.lang.Object object,
                                  Interval interval,
                                  int order)
                           throws java.lang.IllegalArgumentException

Gaussian integration over the interval [a:b] order restricted to range [1:10] and a

Parameters:

object - Invoking object.

interval - Interval of intergration.

order - Order of integration. Must be in range [1:10].

Returns:

The integration of a function for the specified interval, order and point.

Throws:

java.lang.IllegalArgumentException - Thrown if order<1 or order>10, interval is null or b

isValid

public boolean isValid()

Tests whether or not a valid object. Tests if the supplied method has 1 argument of type HDouble and returns type HDouble.

Specified by:

isValid in class Function

Returns:

Logical-true if a valid object, else logical-false.

isValid

public static boolean isValid(java.lang.reflect.Method m)

Static version of isValid(). Tests whether or not a valid object. Tests if the supplied method has 1 argument of type HDouble and returns type HDouble.

Parameters:

m - Method to test validity of.

Returns:

Logical-true if a valid object, else logical-false.

optimisationGA

public double optimisationGA(java.lang.Object object,
                             Interval interval,
                             int populationSize,
                             int maxAllowedEvolutions,
                             java.lang.String xmlPathFileName,
                             HDouble bestSolutionFitnessValue)
                      throws java.lang.Exception

Returns the maximum/minimum of the 1-variable function within the specified interval. Uses the GA solution technique.

Parameters:

object - Invoking object.

interval - Interval within which solution is sought.

populationSize - Number of chromosomes. The more Chromosomes the larger number of potential solutions (which is good for finding the answer), but the longer it will take to evolve the population. If a negative or zero value is specified then it is set to 500.

maxAllowedEvolutions - Maximum number of evolutions allowed. If a negative or zero value is specified then it is set to 50.

xmlPathFileName - XML path and file name to save solution for later reuse.

bestSolutionFitnessValue - Returns, via reference, the function evaluation (eg f(xmin)) of the best solution obtained.

Returns:

Minimum/maximum solution (eg xmin).

Throws:

java.lang.Exception - Thrown in XML error.

parabolicInterpolationMinimum

public double parabolicInterpolationMinimum(java.lang.Object object,
                                            double x1,
                                            double x2,
                                            double x3,
                                            HDouble xmin,
                                            HBoolean collinearPoints)
                                     throws java.lang.IllegalArgumentException

Returns the minimum function value of a parabola through the three points f(x1), f(x2) and f(x3) at the minimum xmin. Refer to Numerical Recipes, Chapter 10.

Parameters:

object - Invoking object.

x1 - Point 1.

x2 - point 2.

x3 - Point 3.

xmin - Set upon return to the point at which the minimum occurs.

collinearPoints - Set upon return to logical-true if the three points are collinear, else logical-false.

Returns:

Value of function at xmin.

Throws:

java.lang.IllegalArgumentException - Thrown if x1

optimisationBFGS

public PairDouble optimisationBFGS(java.lang.Object object,
                                   Interval interval,
                                   double x0,
                                   java.lang.reflect.Method firstDerivative)
                            throws FunctionEvaluationException

Returns the minimum/maximum of the 1-variable function within the specified interval. Uses the BFGS solution technique. Note that the BFGS method is inherently a minimisation algorithm.

Example:

  try
        {
            hedgehog.utility.Interval                   sinfInterval = new hedgehog.utility.Interval(180,360);
            hedgehog.math.functions.library.SinFunction sinf         = new hedgehog.math.functions.library.SinFunction(sinfInterval,true);
            hedgehog.math.functions.OneVariableFunction ovf          = new hedgehog.math.functions.OneVariableFunction("hedgehog.math.functions.library.SinFunction","evaluate");
            double x0 = 200.0;
            hedgehog.utility.PairDouble xmin_approx_deriv = ovf.optimisationBFGS(sinf,sinfInterval,x0,null);
            java.lang.System.out.println("sinf min using approx deriv: " + xmin_approx_deriv);
        }
        catch (hedgehog.math.exceptions.FunctionEvaluationException e)
        {
            java.lang.System.out.println("error performing optimisation");
        }

 with output (exact minimum occurring at x=270 and sin(x)=-1):

 sinf min using approx deriv: PairDouble -1 {(269.9999922533225,-0.9999999999999909)}

 For further information refer to Gill, Murray and Wright(1981) "Practical Optimization", Academic Press and
 Press et al () "Numerical Recipes in C++" (chapter 10), Cambridge University Press.
 

Parameters:

object - Invoking object.

interval - Interval over which the optimisation is to be performed.

x0 - Initial evaluation of x for function minimum/maximum.

firstDerivative - Function first derivative. If unknown then set to null and the 4-point version of taylorsSeriesFirstDerivative() will be used.

Returns:

Pair holding the minimum/maximum values of .

Throws:

FunctionEvaluationException - Thrown if an internal error occurred evaluating the min/max value.

optimisationSwarm

public java.util.Vector<TripleIntDoubleDouble> optimisationSwarm(java.lang.Object object,
                                                                 Interval interval,
                                                                 int nParticles,
                                                                 int nIterations,
                                                                 int neighbourhoodSize)
                                                          throws java.lang.IllegalArgumentException

Performs a particle-swarm optimisation of this function of one variable. Note that the swarm optimiser is inherently a maximisation algorithm.

Parameters:

object - Invoking object.

interval - Solution interval.

nParticles - Number of particles.

nIterations - Maximum number of iterations.

neighbourhoodSize - Particle neighbourhood size.

Returns:

Vector of best particle solutions .

Throws:

java.lang.IllegalArgumentException - Thrown if 1) object is null, 2) interval is null, 3) nParticles<=0, 4) nIterations<=0 or 5) neighbourhoodSize<=0.

richardsonFirstDerivative

public double richardsonFirstDerivative(java.lang.Object object,
                                        double x0,
                                        double r,
                                        double h)
                                 throws java.lang.IllegalArgumentException

Returns the first derivative of the function at point x0 using Richardson extrapolation. Refer to Atkinson et al. (1989).

Parameters:

object - Invoking object.

x0 - Point at which first derivative is to be evaluated.

r - Value r.

h - Value h.

Returns:

The first derivative of a function.

Throws:

java.lang.IllegalArgumentException - Thrown if h <0.

simpsonsIntegration

public double simpsonsIntegration(java.lang.Object object,
                                  double a,
                                  double b,
                                  int even_no_subintervals)
                           throws java.lang.IllegalArgumentException

Simpson's rule of integration over the interval [a,b].

Parameters:

object - Object invoked by method.

a - Minimum of interval [a:b].

b - Maximum of interval [a:b].

even_no_subintervals - Even number of subintervals.

Returns:

The integration over the specified interval and subintervals.

Throws:

java.lang.IllegalArgumentException - Thrown if any of the following are true: 1) even_no_subintervals<=0 or even_no_subintervals not even or 2) b < a.

taylorsSeriesFirstDerivative

public double taylorsSeriesFirstDerivative(java.lang.Object object,
                                           double x0,
                                           double h,
                                           int nPoints)
                                    throws java.lang.IllegalArgumentException

Returns the first derivative using Taylor's series for either 2 or 4 points.

Parameters:

object - Invoking object.

x0 - Point at whch derivative evaluated.

h - Value of h. Typically 0.01 is sufficient.

nPoints - The number of sample points at which the function is evaluated (2 or 4).

Returns:

The first derivative.

Throws:

java.lang.IllegalArgumentException - Thrown if object==null, h

taylorsSeriesSecondDerivative

public double taylorsSeriesSecondDerivative(java.lang.Object object,
                                            double x0,
                                            double h,
                                            int nPoints)
                                     throws java.lang.IllegalArgumentException

Returns the second derivative using Taylor's series for either 3 or 5 points.

Parameters:

object - Invoking object.

x0 - Point at whch derivative evaluated.

h - Value of h. Typically 0.01 is sufficient.

nPoints - The number of sample points at which the function is evaluated (3 or 5)

Returns:

The 1st derivative.

Throws:

java.lang.IllegalArgumentException - Thrown if object==null, h

trapezoidalIntegration

public double trapezoidalIntegration(java.lang.Object object,
                                     Interval interval,
                                     int no_subintervals)
                              throws java.lang.IllegalArgumentException

Trapeziodal rule of integration over the interval [a,b]

Parameters:

object - Invoking object.

interval - Interval in which integration is to be evaluated.

no_subintervals - Number of sub-intervals.

Returns:

The integration of a function for the specified interval and number of sub-intervals.

Throws:

java.lang.IllegalArgumentException - Thrown if no_subintervals<0, interval is null or b

turningPoint

public int turningPoint(java.lang.Object object,
                        double xMinMaxInflexionPoint)
                 throws java.lang.IllegalArgumentException

Determines whether the function at the specified point is a maxima, minima or point of inflexion. Simply tests sign of second derivative using taylorsSeriesSecondDerivative(). Thus, ensure that the specified point is either a maximum or minimum by using the value returned by a routine such as optimisationGA().

Parameters:

object - Invoking object.

xMinMaxInflexionPoint - Point at which to evaluate function to test if maxima, minima or inflexion point.

Returns:

0 if inflexion. -1 if maximum. +1 if minimum.

Throws:

java.lang.IllegalArgumentException - Thrown if object is null.