ead_simulation

ead_simulation(
    stage_damage,
    impact_area_id=1,
    flow_frequency=None,
    flow_stage=None,
    frequency_stage=None,
    threshold=None,
    levee=None,
    min_iterations=100,
    max_iterations=100000,
    deterministic=False,
    non_failure_stage_damage=None,
)

Seeded Monte Carlo expected annual damage (EAD) simulation.

The HEC-FDA impact-area EAD compute over the ported ImpactAreaScenarioSimulation. Random seeds are fixed per-curve constants ported from the C#, so results are reproducible and identical across R, Python, and the upstream HEC-FDA. Supply either flow_frequency + flow_stage, or frequency_stage.

Parameters

Name	Type	Description	Default
stage_damage	list of dict	Stage-damage curve specs: `{"x", "dist", "params", "damage_category", "asset_category"}`.	required
impact_area_id	int		`1`
flow_frequency	dict	`{"dist", "params"}` analytical flow frequency.	`None`
flow_stage	dict	Curve spec transforming flow to stage.	`None`
frequency_stage	dict	Graphical stage frequency: `{"probabilities", "stages", "erl", "damage_category", "asset_category"}`.	`None`
threshold	dict	`{"id", "value"}` exterior-stage performance threshold.	`None`
levee	dict	Levee fragility curve spec plus `top_of_levee_elevation`.	`None`
min_iterations	int	Monte Carlo convergence bounds; use `1, 1` with `deterministic=True` for a single mean-value pass.	`100`
max_iterations	int	Monte Carlo convergence bounds; use `1, 1` with `deterministic=True` for a single mean-value pass.	`100`
deterministic	bool	When True, every distribution collapses to its mean (no sampling).	`False`
non_failure_stage_damage	list of dict	Stage damage curves used when the system does not fail. Uses the same schema as `stage_damage`. HEC-FDA 2.1 stores these results under the `Non_Fail` identity.	`None`

Returns

Name	Type	Description
	dict	The legacy aggregate `ead`, `total_ead`, and `mean_aep` entries, followed by `ead_by_risk`. The additive table has `damage_category`, `asset_category`, `risk_type`, and `mean_ead` columns in that order. `Fail` and `Non_Fail` are stored row identities; the aggregate uses `Total` only as a query wildcard. Existing failure-only calls retain their 0.1.1 entries and column order.