Core API

Pure Physics Functions

The ICOW.Core module contains pure numeric functions that implement the iCOW model equations. All functions take individual numeric parameters (not structs) and are validated against the C++ reference implementation.

base_zone_damage

base_zone_damage(z_low, z_high, value, h_surge, b_basement, H_bldg, f_damage) -> damage

Calculate base damage for a zone before modifiers (Equation 9). See _background/equations.md.

dike_cost

dike_cost(V_dike, c_d)

Calculate dike construction cost (Equation 7). See _background/equations.md.

dike_failure_probability

dike_failure_probability(h_surge, D, t_fail, p_min)

Calculate dike failure probability (Equation 8). See background/equations.md. hsurge should be surge height above dike base.

dike_volume

dike_volume(H_city, D_city, D_startup, s_dike, w_d, W_city, D)

Calculate dike material volume using simplified geometric formula. Replaces paper’s Equation 6 which is numerically unstable. See _background/equations.md.

effective_surge

effective_surge(h_raw, H_seawall, f_runup)

Calculate effective surge after seawall and runup. See _background/equations.md.

expected_damage_given_surge

expected_damage_given_surge(h_raw, bounds, values, H_seawall, f_runup, W, B, D, t_fail, p_min, b_basement, H_bldg, f_damage, P, f_intact, f_failed, d_thresh, f_thresh, gamma_thresh)

Calculate expected damage for a single surge height, integrating over dike failure. Returns: pfail dfailed + (1-pfail) * d*intact

resistance_cost

resistance_cost(V_w, f_cR, H_bldg, H_city, W, R, B, b_basement)

Calculate flood-proofing cost (Equations 4-5). See background/equations.md. Vw is value after withdrawal, f_cR is resistance cost fraction.

resistance_cost_fraction

resistance_cost_fraction(f_adj, f_lin, f_exp, t_exp, P)

Calculate unitless resistance cost fraction (Equation 3). See _background/equations.md.

total_event_damage

total_event_damage(bounds, values, h_surge, ..., dike_failed) -> damage

Calculate total damage for a single surge event across all zones. See _background/equations.md.

value_after_withdrawal

value_after_withdrawal(V_city, H_city, f_l, W)

Calculate city value remaining after withdrawal (Equation 2). See _background/equations.md.

withdrawal_cost

withdrawal_cost(V_city, H_city, f_w, W)

Calculate withdrawal cost (Equation 1). See _background/equations.md.

zone_boundaries

zone_boundaries(H_city, W, R, B, D) -> NTuple{10}

Calculate zone boundary elevations (Figure 3). See _background/equations.md.

zone_damage

zone_damage(zone_idx, z_low, z_high, value, h_surge, b_basement, H_bldg, f_damage, P, f_intact, f_failed, dike_failed) -> damage

Calculate damage for a single zone with zone-specific modifiers (Equation 9). See _background/equations.md.

zone_values

zone_values(V_w, H_city, W, R, B, D, r_prot, r_unprot) -> NTuple{5}

Calculate zone economic values (Zone Values section). See _background/equations.md.