The SWMM3 Orifice Test File: A Historical Reference for Modern Hydraulic Modeling
This test file holds special historical significance in the development of stormwater modeling. Originally published in the 1981 EXTRAN 3 manual by CDM (now CDM Smith), it was specifically designed to validate orifice calculations in hydraulic networks. The file served as a critical quality assurance tool during the evolution of SWMM, supporting the transition from SWMM3 through SWMM4 and into the current SWMM5.
I documented this file's importance in a 2009 Posthaven blog post, which I have updated using various AI tools to maintain its relevance. Today, this historical test case continues to prove valuable across multiple modern modeling platforms, such as ICM SWMM—as an example. It is also on the EPA GitHub as a test model.
To make this valuable reference more accessible to the hydraulic modeling community, I've prepared several modern implementations:
1. A newly formatted PID RT version compatible with SWMM5
2. A GitHub repository containing the file and its documentation
3. Imported versions for both InfoWorks ICM and ICM SWMM Network platforms
As part of this article, you can download the original test file to explore this piece of stormwater modeling history yourself or use it for your own quality assurance testing.
Example Real-Time Control (RTC) rule for an Orifice in SWMM5
RULE Orifice1
IF SIMULATION CLOCKTIME >= 01:00:00
AND SIMULATION CLOCKTIME <= 2:00:00
THEN ORIFICE OR1@82309b-15009b SETTING = 1
ELSE ORIFICE OR1@82309b-15009b SETTING = 0
PRIORITY 1
; Opens up the orifice at hour 1 of the simulation
Explanation of Components:
- RULE Orifice1:
- IF SIMULATION CLOCKTIME >= 01:00:00:
- AND SIMULATION CLOCKTIME <= 2:00:00:
- THEN ORIFICE OR1@82309b-15009b SETTING = 1:
- ELSE ORIFICE OR1@82309b-15009b SETTING = 0:
- PRIORITY 1:
- ; Opens up the orifice at hour 1 of the simulation:
Functionality:
This rule effectively opens the orifice "OR1@82309b-15009b" fully at 1:00:00 AM (one hour into the simulation) and keeps it open until 2:00:00 AM. After 2:00:00 AM, the orifice is fully closed.
Variations, Improvements, and Considerations:
- Partial Opening:
- Time-Based Gradual Opening/Closing:
- Sensor-Based Control:
- Multiple Conditions:
- Multiple Orifices:
- Rule Interaction
- Saving RTC Rules:
- RTC rules are typically written in a separate text file (e.g., "rules.txt") and then referenced in the SWMM5 input file (.inp) under the [RULES] section. You would add a line like: [RULES] FILE "rules.txt" Or you can paste the rules directly into the [RULES] section of the .inp file.
Example of a More Advanced Rule (Conceptual)
Let's say you want to implement a rule that mimics a PID (Proportional-Integral-Derivative) controller to maintain a target water level in a storage unit by adjusting an orifice:
RULE Orifice_PID_Like
; This is a simplified example and not a true PID implementation
; Constants (tune these based on your system)
CONSTANT Kp 0.1 ; Proportional gain
CONSTANT Ki 0.01 ; Integral gain
CONSTANT Kd 0.05 ; Derivative gain
CONSTANT TargetDepth 5 ; Target water depth in feet
; Variables to store values across time steps
VARIABLE ErrorSum 0 ; Accumulated error
VARIABLE PrevError 0 ; Error from the previous time step
IF SIMULATION START
THEN VARIABLE ErrorSum 0
THEN VARIABLE PrevError 0
; Calculate error
VARIABLE CurrentDepth NODE StorageUnit DEPTH
VARIABLE Error = TargetDepth - CurrentDepth
; Update accumulated error (integral term)
VARIABLE ErrorSum = ErrorSum + Error
; Calculate the change in error (derivative term)
VARIABLE DeltaError = Error - PrevError
; Calculate the orifice setting adjustment (PID-like control)
VARIABLE Adjustment = Kp * Error + Ki * ErrorSum + Kd * DeltaError
; Limit adjustment to prevent overshooting or unrealistic changes
VARIABLE Adjustment = MIN(MAX(Adjustment, -0.2), 0.2)
; Get current orifice setting and apply adjustment
VARIABLE CurrentSetting ORIFICE OR1@82309b-15009b SETTING
VARIABLE NewSetting = CurrentSetting + Adjustment
; Make sure the setting is within bounds [0, 1]
VARIABLE NewSetting = MIN(MAX(NewSetting, 0), 1)
; Apply the new orifice setting
THEN ORIFICE OR1@82309b-15009b SETTING = NewSetting
; Store the current error for the next time step's derivative calculation
THEN VARIABLE PrevError = Error
PRIORITY 1
Explanation of the Advanced Rule
- Constants: Kp, Ki, and Kd are tuning parameters that determine the controller's response. TargetDepth is the desired water level.
- Variables: ErrorSum keeps track of the accumulated error over time (integral term), and PrevError stores the error from the previous time step (for the derivative term).
- Initialization: At the start of the simulation (IF SIMULATION START), initialize ErrorSum and PrevError to 0.
- Error Calculation: The error is the difference between the TargetDepth and the CurrentDepth at the storage unit.
- Integral Term: The ErrorSum is updated by adding the current Error.
- Derivative Term: The DeltaError is calculated as the difference between the current Error and the PrevError.
- PID-like Control: The Adjustment is calculated using a formula similar to a PID controller, but without proper time-based integration and differentiation.
- Adjustment Limiting: The Adjustment is limited to prevent drastic changes in the orifice setting.
- Setting Application: The calculated NewSetting is applied to the orifice after being constrained to the valid range [0, 1].
- Storing Previous Error: The current Error is stored in PrevError for use in the next time step.
Important Notes About the Advanced Rule
- This is a simplified example and not a true PID implementation because SWMM5's basic RTC rules don't directly support time-based calculations required for accurate integral and derivative terms.
- Proper PID control would typically involve dividing the integral term by the time step and multiplying the derivative term by the time step.
- Tuning the Kp, Ki, and Kd constants is crucial for stable and effective control.
- This type of rule might require smaller simulation time steps for better performance.
- You can set the value of a variable using the THEN portion of a rule.
In Conclusion
SWMM5's RTC rules provide a powerful way to simulate the dynamic control of hydraulic structures like orifices. You can create rules that range from simple time-based operations to more complex sensor-based and feedback control systems. Remember to carefully consider rule interactions, priorities, and potential improvements to create robust and realistic simulations. While basic RTC rules have limitations, especially for advanced control strategies, understanding the fundamentals will help you leverage their capabilities effectively in your SWMM5 models.
SWMM5 Output Graph
The PID RTC SWMM5 version of the original SWMM3 Model
[TITLE]
;;Project Title/Notes
Example 3 of Extran Manual -
Sump Orifice
[OPTIONS]
;;Option Value
FLOW_UNITS CFS
INFILTRATION HORTON
FLOW_ROUTING DYNWAVE
LINK_OFFSETS DEPTH
MIN_SLOPE 0
ALLOW_PONDING NO
SKIP_STEADY_STATE NO
START_DATE 01/01/2002
START_TIME 00:00:00
REPORT_START_DATE 01/01/2002
REPORT_START_TIME 00:00:00
END_DATE 01/01/2002
END_TIME 08:00:00
SWEEP_START 01/01
SWEEP_END 12/31
DRY_DAYS 0
REPORT_STEP 00:05:00
WET_STEP 00:15:00
DRY_STEP 01:00:00
ROUTING_STEP 0:00:20
RULE_STEP 00:00:00
INERTIAL_DAMPING NONE
NORMAL_FLOW_LIMITED BOTH
FORCE_MAIN_EQUATION H-W
VARIABLE_STEP 0.00
LENGTHENING_STEP 0
MIN_SURFAREA 12.557
MAX_TRIALS 8
HEAD_TOLERANCE 0.005
SYS_FLOW_TOL 5
LAT_FLOW_TOL 5
MINIMUM_STEP 0.5
THREADS 1
[EVAPORATION]
;;Data Source Parameters
;;-------------- ----------------
CONSTANT 0.0
DRY_ONLY NO
[JUNCTIONS]
;;Name Elevation MaxDepth InitDepth SurDepth Aponded
;;-------------- ---------- ---------- ---------- ---------- ----------
80408 124.6 13.4 0 0 0
80608 118.3 16.7 0 0 0
81009 128.2 8.8 0 0 0
81309 117.5 12.5 0 0 0
82309 112.3 42.7 0 0 0
10309 101.6 9.4 0 0 0
15009 111.5 13.5 0 0 0
16009 102 18 0 0 0
16109 102.8 22.2 0 0 0
[OUTFALLS]
;;Name Elevation Type Stage Data Gated Route To
;;-------------- ---------- ---------- ---------------- -------- ----------------
10208 89.9 FREE NO
[CONDUITS]
;;Name From Node To Node Length Roughness InOffset OutOffset InitFlow MaxFlow
;;-------------- ---------------- ---------------- ---------- ---------- ---------- ---------- ---------- ----------
8040 80408 80608 1800 0.015 0 0 0 0
8060 80608 82309 2075 0.015 0 2.2 0 0
8100 81009 81309 5100 0.015 0 0 0 0
8130 81309 15009 3500 0.015 0 0 0 0
1030 10309 10208 4500 0.016 0 0 0 0
1570 15009 16009 5000 0.0154 0 0 0 0
1600 16109 16009 500 0.015 0 0 0 0
1630 16009 10309 300 0.015 0 0 0 0
1602 82309 16109 5000 0.034 0 0 0 0
[ORIFICES]
;;Name From Node To Node Type Offset Qcoeff Gated CloseTime
;;-------------- ---------------- ---------------- ------------ ---------- ---------- -------- ----------
90010 82309 15009 SIDE 1 0.85 NO 0
[XSECTIONS]
;;Link Shape Geom1 Geom2 Geom3 Geom4 Barrels Culvert
;;-------------- ------------ ---------------- ---------- ---------- ---------- ---------- ----------
8040 CIRCULAR 4 0 0 0 1
8060 CIRCULAR 4 0 0 0 1
8100 CIRCULAR 4.5 0 0 0 1
8130 CIRCULAR 4.5 0 0 0 1
1030 TRAPEZOIDAL 9 0 3 3 1
1570 CIRCULAR 5.5 0 0 0 1
1600 CIRCULAR 6 0 0 0 1
1630 TRAPEZOIDAL 9 0 3 3 1
1602 CIRCULAR 5 0 0 0 1
90010 CIRCULAR 2 0 0 0
[CONTROLS]
RULE PID_Orifice
; the PID controller adjusts the orifice opening to have a
; depth of 3 feet in Node 82309
IF NODE 82309 DEPTH <> 3
THEN ORIFICE 90010 SETTING = PID .1 -0.01 -0.01
; kp ki kd
PRIORITY 1
[INFLOWS]
;;Node Constituent Time Series Type Mfactor Sfactor Baseline Pattern
;;-------------- ---------------- ---------------- -------- -------- -------- -------- --------
80408 FLOW 80408 FLOW 1.0 1.0
81009 FLOW 81009 FLOW 1.0 1.0
82309 FLOW 82309 FLOW 1.0 1.0
[TIMESERIES]
;;Name Date Time Value
;;-------------- ---------- ---------- ----------
82309 0 0
82309 0.25 40
82309 3.0 40
82309 3.25 0
82309 12.0 0
;
80408 0 0
80408 0.25 45
80408 3.0 45
80408 3.25 0
80408 12 0
;
81009 0 0
81009 0.25 50
81009 3.0 50
81009 3.25 0
81009 12 0
[REPORT]
;;Reporting Options
CONTROLS YES
SUBCATCHMENTS ALL
NODES ALL
LINKS ALL
[TAGS]
[MAP]
DIMENSIONS -1113.687 0.000 10650.527 10000.000
Units None
[COORDINATES]
;;Node X-Coord Y-Coord
;;-------------- ------------------ ------------------
80408 10115.790 7536.840
80608 7463.160 7536.840
81009 9989.470 2421.050
81309 7568.420 2421.050
82309 4957.890 7536.840
10309 389.470 2421.050
15009 4978.950 2421.050
16009 2494.740 2421.050
16109 2494.740 7536.840
10208 -578.950 4947.370
[VERTICES]
;;Link X-Coord Y-Coord
;;-------------- ------------------ ------------------
[Polygons]
[LABELS]
;;X-Coord Y-Coord Label
2431.580 1052.630 "EXAMPLE 3 OF EXTRAN MANUAL" "" "Arial" 12 1 1
9780.790 8183.720 "Inflow" "" "Arial" 10 0 0
4645.090 8183.720 "Inflow" "" "Arial" 10 0 0
9694.740 2084.210 "Inflow" "" "Arial" 10 0 0
How does this look in ICM InfoWorks and ICM SWMM?
InfoSWMM Engine == OneSWMM for InfoDrainage and ICM SWMM