SWMM5 odesolve.c and odesolve.h Summary

 The odesolve.c and odesolve.h files in SWMM5 (Storm Water Management Model) implement an ODE (Ordinary Differential Equation) solver using the Runge-Kutta-Cash-Karp method. This method is a fifth-order integration technique with adaptive step size control. The solver is designed to compute the values of system states (e.g., flow, pollutant concentrations) over time in dynamic simulations of hydrological processes.

Key Features:

1. Runge-Kutta-Cash-Karp Method:

• RKCK Method is used for solving systems of ODEs. It is a high-accuracy method with adaptive step size control, adjusting the step size to maintain the desired precision.
• It uses intermediate steps to calculate the final result at each time step, improving accuracy.
• This method is used in many applications that require solving time-dependent systems with complex interactions, such as hydrological modeling in SWMM5.

2. Adaptive Step Size Control:

• The step size is adjusted dynamically based on the estimated error at each step. If the error exceeds a threshold, the step size is reduced, and if the error is small, the step size is increased.
• This feature ensures efficient computation and allows for high accuracy without unnecessarily small steps.

3. Main Functions in odesolve.c:

• odesolve_open(int n): Initializes the system, allocating memory for the arrays that hold state variables, derivatives, error estimates, and scaling factors for the ODE solver.
• odesolve_close(): Frees the memory used by the ODE solver after the integration is complete.
• odesolve_integrate(): The primary function that performs the integration of the system of ODEs from an initial state (ystart[]) to a final time point (x2). It uses the rkqs() function for adaptive step size control.
• rkqs(): Performs the Runge-Kutta integration step and adjusts the step size to meet the desired accuracy. It also monitors the error in the integration process and reduces the step size if necessary.
• rkck(): Implements the Runge-Kutta-Cash-Karp method for the integration. It computes the new state values at each time step, using intermediate values and coefficients.

4. Auxiliary Functions:

• rkqs(): This function handles the integration step. It computes the new state values using the RKCK method and adjusts the step size based on the error. If the error is too large, the function reduces the step size and tries again.
• rkck(): Performs the integration step using intermediate values calculated from the system's state variables and their derivatives. This function uses the Runge-Kutta coefficients to compute the next state values accurately.
• derivs(): A user-supplied function that computes the derivatives of the system's state variables (the right-hand side of the ODE system).

5. Error Control and Step Size Adjustment:

• The solver uses an error control mechanism to monitor the accuracy of the integration at each step. The error is estimated based on the difference between two different approximations, and if the error exceeds the allowed tolerance (eps), the step size is reduced.
• The step size is adapted based on the error and the local truncation error to balance between accuracy and efficiency.

6. Function Definitions:

• odesolve_open(): Allocates memory for state variables, scaling factors, error estimates, and intermediate results used in the integration process.
• odesolve_close(): Frees the memory allocated by the solver.
• odesolve_integrate(): Main function to integrate the system of ODEs, using the RKCK method with adaptive step size control.
• rkqs(): Performs one step of integration and adjusts the step size based on the error.
• rkck(): Performs the Runge-Kutta-Cash-Karp step, calculating intermediate values and updating state variables.

Integration Flow:

1. Initialization:

   • The solver is initialized by allocating memory for the necessary variables (state variables, derivatives, error estimates, etc.).
   • The initial state (ystart[]) is set based on the starting conditions of the system.

2. Integration Process:

   • The odesolve_integrate() function is called to integrate the system from the initial time (x1) to the final time (x2).
   • rkqs() and rkck() perform the integration, adjusting the step size as needed and monitoring the error to maintain accuracy.

3. Error Monitoring:

   • The errmax value is computed at each step to monitor the local truncation error. If the error exceeds the specified tolerance, the step size is reduced, and the integration is repeated with the new step size.

4. Completion:

   • Once the final time point is reached, the values of the state variables are stored in ystart[], and the memory used by the solver is freed.

Summary:

The odesolve.c file provides a robust and efficient method for solving systems of ODEs using the Runge-Kutta-Cash-Karp method with adaptive step size control. This is essential for dynamic simulations in SWMM5, where the state variables evolve over time based on complex hydrological processes. The adaptive step size ensures efficient computation while maintaining the required accuracy for the simulation, making it a critical component in modeling the behavior of stormwater systems over time.