ICOW.jl
Island City on a Wedge
This package is under active development and the API may change.
What is iCOW?
Coastal cities face a difficult decision problem: how much to invest in flood protection, and what combination of strategies to use. The answer depends on uncertain future storm hazards, the cost structures of different interventions, and the decision-maker’s tolerance for risk (Keller, Helgeson, and Srikrishnan 2021).
ICOW.jl is a Julia implementation of the “Island City on a Wedge” (iCOW) model from Ceres, Forest, and Keller (2019). It provides a flood risk modeling framework of intermediate complexity – fast enough to evaluate millions of strategy combinations, yet rich enough to capture the nonlinear interactions between withdrawal, resistance, and dike protection that simpler models miss.
This package is designed for researchers and students working on climate risk management and decision making under uncertainty. If you study how communities should invest in flood protection under uncertain hazards, iCOW provides a fast, transparent test bed for exploring strategy portfolios and their sensitivity to assumptions. No prior flood modeling experience is needed – the Quickstart guide walks through a complete analysis.
Why iCOW?
iCOW bridges the gap between two extremes in flood risk modeling:
| Model Type | Pros | Cons |
|---|---|---|
| Simple models (1956) | Fast, analytical | Single strategy (dikes only), binary damage |
| Regional models | Realistic, site-specific | Computationally expensive, requires extensive data |
| iCOW | Fast enough for optimization | Captures multiple strategies and realistic damage |
SimOptDecisions Framework
ICOW.jl uses the SimOptDecisions.jl framework for sequential decision-making under uncertainty. If you are new to SimOptDecisions, here is a brief overview of its key concepts as they appear in iCOW:
| Concept | In iCOW | Description |
|---|---|---|
| Config | StochasticConfig / EADConfig |
City parameters the decision-maker cannot control (28 physical constants) |
| Scenario | StochasticScenario / EADScenario |
Uncertainty representation (surge sequences or GEV parameters) |
| Policy | StaticPolicy |
A rule for choosing flood defenses; reparameterized for optimization |
| State | StochasticState / EADState |
Current protection levels (tracks FloodDefenses) |
| Outcome | StochasticOutcome / EADOutcome |
Final result: investment cost + damage |
This separation enables:
- Modularity: Swap forcing scenarios without changing policy logic
- Exploration: Use
explore()to evaluate many policies across many scenarios - Extensibility: Add adaptive policies that respond to observed storms
See the SimOptDecisions documentation for more on the underlying framework.
Simulation Modes
ICOW supports two simulation modes for evaluating policies:
| Mode | How It Works | Best For |
|---|---|---|
| EAD | Integrates damage over the surge distribution (analytical inner expectation) | Rapid optimization, risk-neutral policy comparison |
| Stochastic | Simulates realized damage from sampled surge sequences with stochastic dike failure | Tail risk (99th percentile loss), robustness analysis |
Both modes converge to the same expected values by the Law of Large Numbers. The key difference is that Stochastic mode reveals the variance and tail behavior of outcomes.
Use EAD mode when you want fast, deterministic expected values for comparing strategies or sweeping over scenarios.
Use Stochastic mode when you care about the distribution of outcomes – e.g., how often a strategy leads to catastrophic losses.
Installation
Requires Julia 1.10 or later.
using Pkg
Pkg.add(url="https://github.com/dossgollin-lab/ICOW.jl")Next Steps
New to iCOW? Start with the Quickstart for a hands-on walkthrough.
Ready to dive into the details?
- Equations – Full mathematical formulation
- EAD Walkthrough – Expected annual damage mode
- Stochastic Walkthrough – Stochastic simulation mode
- API Reference – Function signatures and docstrings