findroot.h File Reference

Header file for root finding method. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef void(*	newton_callback) (double x, double *f, double *df, void *p)
	Callback function for Newton-Raphson root finder.
typedef double(*	ridder_callback) (double x, void *p)
	Callback function for Ridder's root finder.

Functions
int	findroot_Newton (double x1, double x2, double *rts, double xacc, newton_callback func, void *p)
	Finds the root of a function using Newton's method.
double	findroot_Ridder (double x1, double x2, double xacc, ridder_callback func, void *p)
	Finds the root of a function using Ridder's method.

Detailed Description

Header file for root finding method.

Author

L. Rossman

Date

Created: 2013-11-19

Last updated: 2025-01-02

Author

Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com (OpenSWMM maintenance and extensions)

Copyright

Copyright (c) 2026 Caleb Buahin. OpenSWMM contributions only; original EPA SWMM credits are retained.

License

Apache-2.0 for OpenSWMM contributions; original EPA SWMM provenance is retained.

Typedef Documentation

newton_callback

typedef void(* newton_callback) (double x, double *f, double *df, void *p)

Callback function for Newton-Raphson root finder.

Parameters

x	Value of the independent variable.
f	Value of the function at x.
df	Value of the derivative of the function at x.
p	Pointer to additional data.

ridder_callback

typedef double(* ridder_callback) (double x, void *p)

Callback function for Ridder's root finder.

Parameters

x	Value of the independent variable.
p	Pointer to additional data.

Function Documentation

findroot_Newton()

int findroot_Newton	(	double	x1,
		double	x2,
		double *	rts,
		double	xacc,
		newton_callback	func,
		void *	p )

Finds the root of a function using Newton's method.

Parameters

x1	Lower bound of the bracketing interval.
x2	Upper bound of the bracketing interval.
rts	Pointer to the root.
xacc	Desired accuracy of the root.
func	Callback function for the function and its derivative.
p	Pointer to additional data.

Returns

Number of function evaluations used or 0 if the maximum allowed iterations were exceeded.

Finds the root of a function using Newton's method.

Implementation arguments

• x1 (in): Bracket endpoint where the callback function is negative.
• x2 (in): Bracket endpoint where the callback function is positive; coordinate order may be reversed to obtain this sign ordering.
• rts (in,out): Non-null initial guess within the bracket, overwritten with the last estimate on convergence or iteration exhaustion.
• xacc (in): Positive absolute step tolerance in the coordinate units.
• func (in): Non-null synchronous callback filling f and df/dx; it must not retain the solver's temporary output pointers.
• p (in): Borrowed opaque callback context, passed through unchanged; may be NULL when the callback does not require it.

Returns

Evaluation count, or zero after more than MAXIT evaluations. A stationary floating-point estimate also ends iteration.

Precondition

The caller validates/orients the bracket. Endpoints are not evaluated before the initial guess, preserving the legacy callback sequence.

findroot_Ridder()

double findroot_Ridder	(	double	x1,
		double	x2,
		double	xacc,
		ridder_callback	func,
		void *	p )

Finds the root of a function using Ridder's method.

Parameters

x1	Lower bound of the bracketing interval.
x2	Upper bound of the bracketing interval.
xacc	Desired accuracy of the root.
func	Callback function for the function.
p	Pointer to additional data.

Returns

The root of the function.

Finds the root of a function using Ridder's method.

Implementation arguments

• x1 (in): First bracket coordinate.
• x2 (in): Second bracket coordinate; endpoint function values must have opposite signs unless an endpoint is already a root.
• xacc (in): Positive absolute tolerance in the coordinate units.
• func (in): Non-null synchronous evaluator; called at both endpoints and successive trial points, without retaining the callback.
• p (in): Borrowed opaque callback context; may be NULL if unused.

Returns

Exact endpoint root, the last approximate root, or -1.0e20 for an unbracketed root. Exhaustion has no separate failure status.

Note

When a newly calculated root is within xacc of the previous estimate, the previous estimate is returned; the last callback point may differ.