BalancedFrequencyStorm¶
HEC-HMS Frequency Storm (balanced / nested, alternating-block) hyetograph
generation from a depth-duration-frequency table. This is an external generator,
validated only against the documented HEC-HMS 4.13 fixture cases; see
tests/fixtures/hms_frequency_storm/README.md.
Unlike FrequencyStorm (fixed HCFCD temporal pattern scaled
to one total depth), this class uses the depths at every duration, area
reduction, optional partial-to-annual conversion, log-log interpolation and the
alternating block method.
Basis and validation boundary¶
The implementation follows the description of a balanced Frequency Storm in the HEC-HMS Technical Reference Manual, §5.2.6 and §5.2.6.1 and the Frequency Storm parameter descriptions in the HEC-HMS 4.13 User's Manual, Precipitation. The fixture cases also cover selected 4.13 release behavior for missing depths and the re-sort option described in the 4.13 release notes.
Tests assert at most 0.001 in difference for every interval and total depth in 68 public-default/off HEC-HMS 4.13 cases (the observed maximum is approximately 5e-12 in). Two additional perturbed-DDF fixtures run HMS with re-sort on and off. This is evidence for those cases, not a claim of general numerical equivalence across HMS versions or settings.
Not validated or implemented: user-specified area-reduction functions; spatial
distribution by subbasin, precipitation-frequency grids, or depth-area analysis;
metric units; and direct .met parsing/writing. The public generator accepts
depth mappings or sequences only. It implements log-log interpolation between
the supplied DDF durations, so omitted intermediate durations can affect the
result; that behavior is only partly validated. It still requires explicit
depths at the selected interval and total duration. The HEC-HMS re-sort option
is not a public switch and is not represented as an equivalent API behavior.
Observed HMS details¶
For the default (re-sort off), block placement follows HMS 4.13 duration order, including the non-monotone-increment fixtures. This differs from the Technical Reference Manual wording that describes descending order. The paired perturbed re-sort fixtures show that re-sort on changes the output; they are retained as HMS evidence only, not as validation of an API option.
HMS 4.13 applies the 30-minute storm-area reduction factor below 30 minutes. This differs from the Technical Reference Manual wording; the short-interval area fixtures cover that observed behavior. The TP-40/TP-49 depth-area curves are documented through 400 mi²; the API logs a warning above that area, although HMS 4.13 accepts larger values in the fixture matrix.
from hms_commander import BalancedFrequencyStorm
depths = {5: 1.17, 10: 1.88, 15: 2.32, 30: 3.20, 60: 4.27, 120: 5.77,
180: 6.82, 360: 8.63, 720: 10.3, 1440: 12.1} # Kerrville TX, 100-yr PDS
hyeto = BalancedFrequencyStorm.generate_hyetograph(
depths, total_duration_min=1440, time_interval_min=15,
peak_position_pct=50, storm_area_sqmi=0)
hms_commander.BalancedFrequencyStorm
¶
BalancedFrequencyStorm - HEC-HMS "Frequency Storm" (balanced / nested) hyetographs.
This module reproduces the HEC-HMS Frequency Storm meteorologic method
(Precipitation Method: Frequency Based Hypothetical in the .met file) so
that a hyetograph can be built from a depth-duration-frequency (DDF) table
outside of HMS and compared to HMS output.
It is distinct from :class:hms_commander.FrequencyStorm, which scales a fixed
HCFCD/Houston temporal pattern to a single total depth. The two classes are
kept separate so that existing FrequencyStorm behavior is unchanged.
Algorithm (HEC-HMS Technical Reference Manual, section 5.2.6, verified against
HEC-HMS 4.13 output; see tests/fixtures/hms_frequency_storm):
- Depths for the standard durations (5 min ... 10 days) are supplied for one
exceedance probability. Per the TRM, 10-min and 30-min depths are estimated
with the HYDRO-35 relationships
P10 = 0.59*P15 + 0.41*P5andP30 = 0.49*P60 + 0.51*P15. In HMS 4.13 this only happens for legacy (3.x-format) met files without 10/30-min entries; a native 4.13 file uses the supplied durations as given and does NOT augment blanks, soaugment=Falseis the default here (augment=Truereproduces legacy). - Depths are reduced for storm area (
storm_area_sqmi) with the HMS TP-40/TP-49 depth-area curves (see :meth:areal_reduction_factor). - Optional partial-duration to annual-duration conversion with the Table 11 factors (0.88 / 0.96 / 0.99 for 50 / 20 / 10 percent exceedance).
- Cumulative depth is interpolated at every multiple of the time interval, linearly in log(duration)-log(depth) space; successive differences give the incremental blocks.
- Blocks are arranged with the alternating block method: the first nested block is placed at the peak-intensity position and the remaining blocks alternate before/after it in duration order. This follows observed HMS 4.13 behavior for non-monotone increments; it differs from the TRM wording that describes descending order.
Time Axis
Output DataFrames follow the repository convention (a t=0 zero-sentinel row
followed by interval-end rows), see _hyetograph.build_hyetograph_frame.
Example
from hms_commander import BalancedFrequencyStorm depths = {5: 1.17, 10: 1.88, 15: 2.32, 30: 3.20, 60: 4.27, 120: 5.77, ... 180: 6.82, 360: 8.63, 720: 10.3, 1440: 12.1} hyeto = BalancedFrequencyStorm.generate_hyetograph( ... depths, total_duration_min=1440, time_interval_min=15, ... peak_position_pct=50) round(hyeto["incremental_depth"].sum(), 6) 12.1
BalancedFrequencyStorm
¶
HEC-HMS Frequency Storm (balanced hyetograph) generator.
All methods are static.
Source code in hms_commander/BalancedFrequencyStorm.py
66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 | |
areal_reduction_factor(duration_min, storm_area_sqmi)
staticmethod
¶
HMS TP-40/TP-49 depth-area reduction factor (1.0 for a point storm).
HMS 4.13 uses the 30-minute factor for shorter durations; this differs from the Technical Reference Manual wording. The TP-40/TP-49 depth-area curves are documented through 400 square miles.
Source code in hms_commander/BalancedFrequencyStorm.py
augment_depths(depths)
staticmethod
¶
Add HYDRO-35 estimated 10-min and 30-min depths when they are absent.
Source code in hms_commander/BalancedFrequencyStorm.py
cumulative_depths(depths, total_duration_min, time_interval_min)
staticmethod
¶
Log-log interpolated cumulative depth at each interval end time.
Source code in hms_commander/BalancedFrequencyStorm.py
alternating_blocks(increments, peak_position_pct=50.0)
staticmethod
¶
Arrange incremental blocks with the HMS alternating block method.
increments must be in time order of the nested storm, i.e. block k
is depth(k*dt) - depth((k-1)*dt). HMS places them in that order
(it does not re-sort by value), which matters only where the
interpolated increments are not monotone (at changes of slope between
depth-duration table knots). The non-monotone HMS 4.13 fixtures support
this behavior; it differs from the Technical Reference Manual's
descending-order wording.
Source code in hms_commander/BalancedFrequencyStorm.py
generate_hyetograph(depths, total_duration_min=1440, time_interval_min=15, peak_position_pct=50.0, storm_area_sqmi=0.0, exceedance_pct=None, convert_partial_to_annual=False, durations_min=None, augment=False, area_reduction='tp40_tp49')
staticmethod
¶
Generate an HMS Frequency Storm hyetograph.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
depths
|
Union[Mapping[int, float], Sequence[float]]
|
Point depths (inches) by duration. Either a mapping
|
required |
total_duration_min
|
int
|
Storm duration (minutes); must have a depth. |
1440
|
time_interval_min
|
int
|
Computation/intensity interval (minutes); must have a depth. |
15
|
peak_position_pct
|
float
|
Percent of the storm before the peak block (25, 33, 50, 67 or 75 in HMS). |
50.0
|
storm_area_sqmi
|
float
|
Storm area for depth-area reduction (0 = point). A warning is logged above 400 sq mi, the documented extent of the TP-40/TP-49 depth-area curves. |
0.0
|
exceedance_pct
|
Optional[float]
|
Exceedance probability in percent (50, 20, 10 are the only values for which HMS applies a conversion factor). |
None
|
convert_partial_to_annual
|
bool
|
Apply the HMS partial -> annual factor (HMS "Convert to Annual Series: Yes", input assumed partial). |
False
|
durations_min
|
Optional[Sequence[int]]
|
Durations for a sequence |
None
|
area_reduction
|
str
|
|
'tp40_tp49'
|
augment
|
bool
|
Estimate missing 10-min/30-min depths with HYDRO-35 (TRM
5.2.6.1). Default False: HEC-HMS 4.13 does not augment when it reads
a native 4.13 |
False
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
DataFrame with |
DataFrame
|
|
Notes
Cumulative depths are interpolated linearly in log(duration)- log(depth) space between supplied durations. Omitting intermediate durations is therefore supported by the implementation, but is only partly validated against HMS 4.13; the selected interval and total duration must still be supplied explicitly.
Blocks follow the observed HMS 4.13 duration order. This differs from the Technical Reference Manual's descending-order wording; the HMS re-sort setting is not exposed by this API.
Source code in hms_commander/BalancedFrequencyStorm.py
210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 | |