Find root

Collaboration diagram for Find root:

Functions
int	RootBracket (int(*Function)(double, void *, double *), void *AuxilliaryData, double *LowerBound, double *UpperBound, double *LowerSample, double *UpperSample, double Tolerance, int *ValidBracket, int *Status)
int	RootFindBisection (int(*Function)(double, void *, double *), void *AuxilliaryData, double *Root, double LowerBound, double UpperBound, double Tolerance, int *Status)
int	RootFindBrent (int(*Function)(double, void *, double *), void *AuxilliaryData, double *Root, double LowerBound, double UpperBound, double Tolerance, int *Status)

Detailed Description

Function Documentation

RootBracket()

int RootBracket	(	int(*)(double, void *, double *)	Function,
		void *	AuxilliaryData,
		double *	LowerBound,
		double *	UpperBound,
		double *	LowerSample,
		double *	UpperSample,
		double	Tolerance,
		int *	ValidBracket,
		int *	Status
	)

Find root by bracketing. Bracketing of a root of (Function) inside the interval [LowerBound, UpperBound]. The purpose is to search for a pair of arguments for which 'Function' differs in sign. The search is conducted within [LowerBound, UpperBound]. At most [(UpperBound - LowerBound) / Tolerance] function evaluations are performed. Even-order roots cannot be bracketed. The evaluation of Function at LowerBound (UpperBound) is returned in LowerSample (UpperSample)

success: return(!ERROR); failure: return(ERROR)

the function 'Function' must be declared as follows:

extern int myFunction(double myArgument, void *AuxilliaryData, double *myResult);

It must return ERROR upon failure, and !ERROR upon success

It is evaluated for the value of the variable 'myArgument'. The result of the function evaluation must be returned in 'myResult'. The generic pointer 'AuxilliaryData' can be used to pass additional parameters.

What follows is a developed example of the function f(x) = a * x^2 + b * x + c (a, b, and c are free parameters)

struct myStruct {
   double a, b, c;
};

extern int myFunction (
   double  myArgument,
   void    *AuxilliaryData,
   double  *myResult) {
   struct myStruct myData;

   myData = *((struct myStruct *)AuxilliaryData);
   *myResult = myArgument * (myArgument * myData.a + myData.b) + myData.c;
   return(!ERROR);
}

int main() {
   struct myStruct myData;
   double LowerBound = -100.0, UpperBound = 100.0;
   double LowerSample, UpperSample;
   double Tolerance = FLT_EPSILON;
   int    ValidBracket;
   int    Status;

   myData.a = 1.0;
   myData.b = 5.0;
   myData.c = 4.0;
   RootBracket(*myFunction, (void *)&myData, &LowerBound, &UpperBound,
      &LowerSample, &UpperSample, Tolerance, &ValidBracket, &Status);
   return(0);
}

RootFindBisection()

int RootFindBisection	(	int(*)(double, void *, double *)	Function,
		void *	AuxilliaryData,
		double *	Root,
		double	LowerBound,
		double	UpperBound,
		double	Tolerance,
		int *	Status
	)

Find a root by bisection. Search for a root of (Function) inside the bracketing interval [LowerBound, UpperBound]. The strategy proceeds by iteratively cutting the interval in two equal parts. Even-order roots generally cannot be found. Only one root is returned, even if there are several ones. Tolerance is relative to the size of the bracketing interval

success: return(!ERROR); failure: return(ERROR)

The function 'Function' must be declared as follows:

extern int myFunction(double myArgument, void *AuxilliaryData, double *myResult);

It must return ERROR upon failure, and !ERROR upon success. It is evaluated for the value of the variable 'myArgument'. The result of the function evaluation must be returned in 'myResult'. The generic pointer 'AuxilliaryData' can be used to pass additional parameters.

What follows is a developed example of the function f(x) = a * x^2 + b * x + c (a, b, and c are free parameters)

struct myStruct {
   double a, b, c;
};

extern int myFunction (
   double  myArgument,
   void    *AuxilliaryData,
   double  *myResult) {
   struct myStruct myData;

   myData = *((struct myStruct *)AuxilliaryData);
   *myResult = myArgument * (myArgument * myData.a + myData.b) + myData.c;
   return(!ERROR);
}

int main() {
   struct myStruct myData;
   double LowerBound = -100.0, UpperBound = 100.0;
   double Root;
   double Tolerance = FLT_EPSILON;
   int    Status;

   myData.a = 1.0;
   myData.b = 5.0;
   myData.c = 4.0;
   RootBracket(*myFunction, (void *)&myData, &LowerBound, &UpperBound, Tolerance, &Status);
   RootFindBisection(*myFunction, (void *)&myData, &Root, LowerBound,
      UpperBound, Tolerance, &Status);
   return(0);
}

RootFindBrent()

int RootFindBrent	(	int(*)(double, void *, double *)	Function,
		void *	AuxilliaryData,
		double *	Root,
		double	LowerBound,
		double	UpperBound,
		double	Tolerance,
		int *	Status
	)

Find root using Brent algorithm. Search for a root of (Function) inside the bracketing interval [LowerBound, UpperBound]. The strategy proceeds by fitting an inverse quadratic function and by using the root that belong to the interval. If any even-order roots generally cannot be found. Only one root is returned, even if there are several ones. Tolerance is relative to the size of the bracketing interval.

success: return(!ERROR); failure: return(ERROR)

The function 'Function' must be declared as follows:

extern int myFunction(double myArgument, void *AuxilliaryData, double *myResult);

It must return ERROR upon failure, and !ERROR upon success. It is evaluated for the value of the variable 'myArgument'. The result of the function evaluation must be returned in 'myResult'. The generic pointer 'AuxilliaryData' can be used to pass additional parameters.

What follows is a developed example of the function f(x) = a * x^2 + b * x + c (a, b, and c are free parameters)

struct myStruct {
   double a, b, c;
};

extern int myFunction (
   double  myArgument,
   void    *AuxilliaryData,
   double  *myResult) {
   struct myStruct myData;

   myData = *((struct myStruct *)AuxilliaryData);
   *myResult = myArgument * (myArgument * myData.a + myData.b) + myData.c;
   return(!ERROR);
}

int main() {
   struct myStruct myData;
   double LowerBound = -100.0, UpperBound = 100.0;
   double Root;
   double Tolerance = FLT_EPSILON;
   int    Status;

   myData.a = 1.0;
   myData.b = 5.0;
   myData.c = 4.0;
   RootBracket(*myFunction, (void *)&myData, &LowerBound, &UpperBound, Tolerance, &Status);
   RootFindBisection(*myFunction, (void *)&myData, &Root, LowerBound,
      UpperBound, Tolerance, &Status);
   return(0);
}