openswmm::ode Namespace Reference

Namespaces
namespace	detail

Typedefs
using	DerivFunc = std::function<void(double x, const double* y, double* dydx)>
	Synchronous derivative evaluator for an n-equation ODE system.
using	BatchDerivFunc
	Synchronous derivative evaluator for a batch of two-state systems.

Functions
int	integrate (double *y, int n, double x1, double x2, double eps, double h1, const DerivFunc &derivs)
	Advance an ODE system with adaptive Cash-Karp RK45 steps.
int	integrate_batch_2eq (double *y0, double *y1, int n_sys, double x1, double x2, double eps, double h1, const BatchDerivFunc &derivs)
	Advance independent two-state systems with one explicit Euler step.
template<typename F>
int	integrateCallable (double *y, int n, double x1, double x2, double eps, double h1, F &&derivs)
	Integrate with a concrete synchronous derivative callable.

Variables
constexpr int	MAXSTP = 10000
	Maximum integration steps.
constexpr double	TINY = 1.0e-30
	Underflow protection.
constexpr double	SAFETY = 0.9
	Step adjustment safety factor.
constexpr double	PGROW = -0.2
	Exponent for step increase.
constexpr double	PSHRNK = -0.25
	Exponent for step decrease.
constexpr double	ERRCON = 1.89e-4
	= (5/SAFETY)^(1/PGROW)
constexpr int	ODE_OK = 0
	Success.
constexpr int	ODE_TOO_MANY = 1
	n > allocated max
constexpr int	ODE_UNDERFLOW = 2
	Step size underflowed.
constexpr int	ODE_MAX_STEPS = 3
	Exceeded MAXSTP.

Typedef Documentation

BatchDerivFunc

using openswmm::ode::BatchDerivFunc

Initial value:

 std::function<void(double x, const double* y0, const double* y1, double* dy0,
                                          double* dy1, int n_sys)>

Synchronous derivative evaluator for a batch of two-state systems.

Parameters

[in]	x	Independent variable, in caller-selected units.
[in]	y0	Borrowed array of n_sys first-state values.
[in]	y1	Borrowed array of n_sys second-state values.
[out]	dy0	Borrowed array to fill with n_sys first-state derivatives.
[out]	dy1	Borrowed array to fill with n_sys second-state derivatives.
[in]	n_sys	Number of independent systems; nonnegative.

Note

Derivative units are state units divided by x units. No array may be retained by the callback.

DerivFunc

using openswmm::ode::DerivFunc = std::function<void(double x, const double* y, double* dydx)>

Synchronous derivative evaluator for an n-equation ODE system.

Parameters

[in]	x	Independent variable, commonly elapsed time in seconds.
[in]	y	Borrowed, non-null array of n states at x; do not modify or retain.
[out]	dydx	Borrowed, non-null array of n derivatives dy_i/dx; write every component before returning and do not retain the pointer.

Note

Units of each derivative are the state units divided by x units.

Function Documentation

integrate()

int openswmm::ode::integrate	(	double *	y,
		int	n,
		double	x1,
		double	x2,
		double	eps,
		double	h1,
		const DerivFunc &	derivs )

Advance an ODE system with adaptive Cash-Karp RK45 steps.

Parameters

[in,out]	y	Non-null array of n initial states at x1. Replaced with states at x2 only on ODE_OK; error returns leave the caller's array unchanged.
[in]	n	Positive number of equations; controls all callback array lengths.
[in]	x1	Finite start of the integration interval, in caller-selected units.
[in]	x2	Finite end in the same units; forward and reverse intervals are supported when h1 has the corresponding sign.
[in]	eps	Positive dimensionless local error tolerance, relative to abs(y_i) + abs(h * dy_i/dx) + TINY at each attempted step.
[in]	h1	Nonzero initial step guess, in x units, directed from x1 to x2.
[in]	derivs	Nonempty derivative callback. Called synchronously with borrowed workspace arrays; not retained, and exceptions propagate.

Returns

ODE_OK on success, ODE_UNDERFLOW if a proposed next step is zero, or ODE_MAX_STEPS after exhaustion or an underflow inside step rejection. ODE_TOO_MANY is returned if workspace capacity remains below n.

Workspace is reused per thread and released at thread exit. The solver is not reentrant on the same thread: derivs must not recursively call integrate(). Allocation failures are not translated into an ODE status.

Here is the call graph for this function:

integrate_batch_2eq()

int openswmm::ode::integrate_batch_2eq	(	double *	y0,
		double *	y1,
		int	n_sys,
		double	x1,
		double	x2,
		double	eps,
		double	h1,
		const BatchDerivFunc &	derivs )

Advance independent two-state systems with one explicit Euler step.

Parameters

[in,out]	y0	Array of n_sys first-state values; updated by dy0 * (x2 - x1).
[in,out]	y1	Distinct array of n_sys second-state values; updated by dy1 * (x2 - x1). Arrays must be writable when n_sys > 0.
[in]	n_sys	Nonnegative number of systems and length of each array.
[in]	x1	Finite start coordinate, also the sole derivative evaluation time.
[in]	x2	Finite end coordinate in the same units as x1.
[in]	eps	Unused; this helper performs no tolerance or error control.
[in]	h1	Unused; the only step has length x2 - x1.
[in]	derivs	Nonempty callback invoked once for the entire batch. Pointers are borrowed for that call; callback exceptions propagate.

Returns

ODE_OK after all states are updated. Workspace allocation may throw.

Note

This is not the adaptive RK45 algorithm used by integrate(). Thread-local derivative buffers make recursive calls on one thread unsafe.

integrateCallable()

template<typename F>

int openswmm::ode::integrateCallable	(	double *	y,
		int	n,
		double	x1,
		double	x2,
		double	eps,
		double	h1,
		F &&	derivs )

Integrate with a concrete synchronous derivative callable.

Note

Uses the same Cash-Karp arithmetic, adaptive controls, commit/return behavior and shared per-thread workspace as integrate(). The same non-reentrancy contract applies. No callback is retained or converted to std::function.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

ERRCON

double openswmm::ode::ERRCON = 1.89e-4

constexpr

= (5/SAFETY)^(1/PGROW)

MAXSTP

int openswmm::ode::MAXSTP = 10000

constexpr

Maximum integration steps.

ODE_MAX_STEPS

int openswmm::ode::ODE_MAX_STEPS = 3

constexpr

Exceeded MAXSTP.

ODE_OK

int openswmm::ode::ODE_OK = 0

constexpr

Success.

ODE_TOO_MANY

int openswmm::ode::ODE_TOO_MANY = 1

constexpr

n > allocated max

ODE_UNDERFLOW

int openswmm::ode::ODE_UNDERFLOW = 2

constexpr

Step size underflowed.

PGROW

double openswmm::ode::PGROW = -0.2

constexpr

Exponent for step increase.

PSHRNK

double openswmm::ode::PSHRNK = -0.25

constexpr

Exponent for step decrease.

SAFETY

double openswmm::ode::SAFETY = 0.9

constexpr

Step adjustment safety factor.

TINY

double openswmm::ode::TINY = 1.0e-30

constexpr

Underflow protection.