Detailed Description

Root finding routines.

Synopsis

#include <lal/FindRoot.h>

This header covers the routines for root finding.

Description

The routine LALSBracketRoot() expands the specified domain until a root is contained. The routine LALDBracketRoot() is the same but for a double-precision function.

The routine LALSBisectionFindRoot() bisects the domain (which must contain one root) until the root is found with the desired accuracy. The routine LALDBisectionFindRoot() is the same but for a double-precision function.

Operating Instructions

Suppose we want to find the root of the function \(y = F(x;y_0) = y_0 + x^2\). Define the function:

static void F( LALStatus *status, REAL4 *y, REAL4 x, void *y0 )
{
INITSTATUS(status);
ASSERT( y0, status, 1, "Null pointer" );
y = *(REAL4 *)y0 + x*x;
RETURN( status );
}

Then use the following code to bracket and find the root \(x_0=1\) where \(F(x_0;y_0=-1)=0\):

static LALStatus status;
SFindRootIn      input;
REAL4            y0;
REAL4            x0;
 
y0             = -1;
input.function = F;
input.xmin     = 0.1;
input.xmax     = 0.2;
input.xacc     = 1e-5;
 
/\* expand domain until a root is bracketed *\/
LALSBracketRoot( &status, &input, &y0 );
 
/\* bisect domain until root is found *\/
LALSBisectionFindRoot( &status, &x0, &input, &y0 );

Algorithm

This is an implementation of the root bracketing and bisection finding routines zbrac and rtbis in Numerical Recipes [22] .

Prototypes
void	LALSBracketRoot (LALStatus status, SFindRootIn inout, void *params)

int	XLALDBracketRoot (REAL8(y)(REAL8, void ), REAL8 xmin, REAL8 xmax, void *params)

void	LALDBracketRoot (LALStatus status, DFindRootIn inout, void *params)

void	LALSBisectionFindRoot (LALStatus status, REAL4 root, SFindRootIn input, void params)

REAL8	XLALDBisectionFindRoot (REAL8(y)(REAL8, void ), REAL8 xmin, REAL8 xmax, REAL8 xacc, void *params)

void	LALDBisectionFindRoot (LALStatus status, REAL8 root, DFindRootIn input, void params)

Data Structures
struct	SFindRootIn
	These are function pointers to functions that map REAL4 numbers to REAL4 numbers. More...

struct	DFindRootIn
	These are function pointers to functions that map REAL8 numbers to REAL8 numbers. More...

Files
file	FindRootTest.c
	Tests the routines in FindRoot.h.

Error Codes
#define	FINDROOTH_ENULL 1
	Null pointer. More...

#define	FINDROOTH_EIDOM 2
	Invalid initial domain. More...

#define	FINDROOTH_EMXIT 4
	Maximum iterations exceeded. More...

#define	FINDROOTH_EBRKT 8
	Root not bracketed. More...

Function Documentation

◆ LALSBracketRoot()

void LALSBracketRoot	(	LALStatus *	status,
		SFindRootIn *	inout,
		void *	params
	)

See also: See Header FindRoot.h for documentation

Definition at line 29 of file FindRoot.c.

◆ XLALDBracketRoot()

int XLALDBracketRoot	(	REAL8()(REAL8, void )	y,
		REAL8 *	xmin,
		REAL8 *	xmax,
		void *	params
	)

See also: See Header FindRoot.h for documentation

Definition at line 97 of file FindRoot.c.

◆ LALDBracketRoot()

void LALDBracketRoot	(	LALStatus *	status,
		DFindRootIn *	inout,
		void *	params
	)

See also: See Header FindRoot.h for documentation

Definition at line 147 of file FindRoot.c.

◆ LALSBisectionFindRoot()

void LALSBisectionFindRoot	(	LALStatus *	status,
		REAL4 *	root,
		SFindRootIn *	input,
		void *	params
	)

See also: See Header FindRoot.h for documentation

Definition at line 215 of file FindRoot.c.

◆ XLALDBisectionFindRoot()

REAL8 XLALDBisectionFindRoot	(	REAL8()(REAL8, void )	y,
		REAL8	xmin,
		REAL8	xmax,
		REAL8	xacc,
		void *	params
	)

See also: See Header FindRoot.h for documentation

Definition at line 308 of file FindRoot.c.

◆ LALDBisectionFindRoot()

void LALDBisectionFindRoot	(	LALStatus *	status,
		REAL8 *	root,
		DFindRootIn *	input,
		void *	params
	)

See also: See Header FindRoot.h for documentation

Definition at line 381 of file FindRoot.c.

Macro Definition Documentation

◆ FINDROOTH_ENULL

#define FINDROOTH_ENULL 1

Null pointer.

Definition at line 99 of file FindRoot.h.

◆ FINDROOTH_EIDOM

#define FINDROOTH_EIDOM 2

Invalid initial domain.

Definition at line 100 of file FindRoot.h.

◆ FINDROOTH_EMXIT

#define FINDROOTH_EMXIT 4

Maximum iterations exceeded.

Definition at line 101 of file FindRoot.h.

◆ FINDROOTH_EBRKT

#define FINDROOTH_EBRKT 8

Root not bracketed.

Definition at line 102 of file FindRoot.h.