SWMM5 kinwave.c Summary

 Here's a concise summary of how the kinwave.c file in SWMM is structured and used:

---

1. Purpose of kinwave.c

kinwave.c implements the Kinematic Wave flow-routing method for a single conduit, computing the outflow hydrograph at each time step based on the inflow at the upstream end. It solves the finite difference form of the continuity equation for unsteady, 1D flow under the assumptions of negligible inertial and pressure forces.

---

2. Key Routines in kinwave.c

1. kinwave_execute

   • Called each time step for each conduit that is assigned Kinematic Wave routing.
   • Inputs: (i) link index j; (ii) pointer to inflow/outflow; (iii) time step tStep.
   • Outputs: updated outflow (and internally updated flow area) for the conduit.
   • Main steps:
     1. Retrieve the subindex into the Conduit array and relevant cross-section data.
     2. Normalize flows/areas to dimensionless form (i.e., fraction of full flow/area).
     3. Form a finite-difference equation of continuity with the kinematic wave relationship, adjusting for infiltration and evaporation losses.
     4. Solve for the new outlet area (and thus outflow) using solveContinuity.
     5. Convert flows/areas back to dimensional units and store them in the SWMM data structures.

2. solveContinuity

   • Solves the continuity equation: $$f(a) = \beta_1 \cdot S(a) \;+\; C_1 \cdot a \;+\; C_2 \;=\; 0$$ for the outlet dimensionless area $a$.
   • Picks upper/lower bounds on $a$ so that $f(a)$ crosses zero.
   • Calls findroot_Newton (a general-purpose Newton-Raphson routine) from findroot.c.
   • Returns an integer code:
     • $\ge 0$: number of function evaluations used
     • $-1$: continuity equation not solved
     • $-2$: flow above max. flow
     • $-3$: flow below zero

3. evalContinuity

   • The user-supplied function to compute $f(a)$ (and derivative $df(a)$) for findroot_Newton.
   • Combines partial derivatives of Kinematic-Wave formula with partial derivatives of cross-sectional area.
   • $\beta_1, C_1, C_2$ are module-level variables assigned in kinwave_execute.

---

3. Local vs. Shared Variables

Local variables in kinwave_execute:

• q1, q2, qin: normalized flow states at previous time steps / upstream boundary
• a1, a2, ain, aout: normalized cross-section area states

Shared / Module-level variables:

• Beta1, C1, C2: constants in the finite difference continuity equation
• pXsect: pointer to the conduit’s cross-section object
• Afull, Qfull: full flow area and full flow rate used to normalize flows

---

4. Flow Path through the Code

1. kinwave_execute is triggered from flowrout_execute (in flowrout.c) for each conduit that uses Kinematic Wave routing.
2. It sets up dimensionless flows/areas, calls solveContinuity to find the new outlet area, and returns the final computed outflow.
3. solveContinuity calls findroot_Newton, passing evalContinuity for function evaluation and derivative.
4. The root finder finds the new area $a$.
5. kinwave_execute uses a to find outflow $(q_\text{out} = \beta_1 \times S(a))$.
6. SWMM updates the link’s flow/area records.

---

5. Handling Losses

• A small call is made to link_getLossRate with the parameter KW to handle evaporation and infiltration losses.
• The returned value is then subtracted from the flow.

---

6. Newton-Raphson ODE Approach

• The function evalContinuity(a, f, df, p) returns the function $f(a)$ and its derivative $df/da$.
  • $f(a) = \beta_1 \cdot S(a) + C_1 \cdot a + C_2$.
  • The derivative is $df/da = \beta_1 \cdot dS/da + C_1$.

---

7. Practical Limitations

• The kinematic wave approach ignores dynamic wave backwater/inertial effects.
• Appropriate for mild or steep open channels with supercritical flows and no significant flooding or surcharging.

---

8. In Summary

• kinwave.c focuses on one main routine, kinwave_execute, which implements Kinematic Wave routing for a single conduit.
• It uses dimensionless flow/area states, a finite-difference continuity approximation, and a root-finding approach for updated area/outflow.
• The Newton function from findroot.c is plugged in with evalContinuity.
• This approach is simpler computationally than the full Dynamic Wave solver, suitable for many open-channel, non-backwater conditions.