ExplicitDamageRatio#

ExplicitDamageRatio calculates wind damage ratios for components represented directly in the final resistance dictionary: roof coverings, roof sheathings, roof-wall connections, openings, and walls.

Use it when you need component-level explicit wind damage ratios without the implicit interior, utility, or flood calculations.

Inputs#

Building: cheersafe.inventory.Building.
FailureChecks: object with get_final_resistance() -> dict[str, np.ndarray].
ComponentConfigurationIndex: zero-based component-configuration row. Required by the base class even though explicit wind ratios do not use it directly.
FloodDepthIndex: zero-based flood-depth row. Required by the base class even though explicit wind ratios do not use it directly.

FailureChecks.get_final_resistance() must return these keys:

"Roof Coverings" and "Roof Sheathings": shape (sum(Building.NumPanel),).
"Roof-Wall Connections": shape (sum(Building.NumConnection),).
"Openings": total opening count.
"Walls": shape (12,), reshaped internally as (4, 3) with Fortran order.

Outputs And Returns#

With automatic execution:

ResistanceValues: final resistance dictionary from FailureChecks.
ExplicitDamageRatioWind: dict[str, float] keyed by component name.

fn_damage_ratio_wind() returns the explicit wind dictionary. A component ratio is generally the fraction of resistance entries equal to zero. Roof coverings and roof sheathings are treated as total loss when their ratio exceeds 0.35. Walls are evaluated by wall side: one failed side gives 0.25; two or more failed sides give 1.0.

Config Behavior#

With AUTO_LOAD_DATASETS = True, base damage-ratio datasets are loaded even though this class only needs the final resistance dictionary for fn_damage_ratio_wind().

With AUTO_EXECUTE_METHODS = True, the explicit dictionary is calculated during construction. With it disabled, ResistanceValues is still set by __post_init__, but call and assign fn_damage_ratio_wind() yourself.

Automatic Example#

import numpy as np
from cheersafe.damage_ratio_calculation import ExplicitDamageRatio
from cheersafe.inventory import BuildingInventory
from cheersafe.loads import LoadingAndFailureCheck
from cheersafe.tools import Utils

building = BuildingInventory(buildings_file_name="BuildingGeometry.json").buildings[0]
mean = Utils.from_json("Inputs/MeanResistanceValue.json")
failure = LoadingAndFailureCheck(
    np.full(sum(building.NumPanel), mean[1, 0]),
    np.full(sum(building.NumPanel), mean[0, 0]),
    np.full(sum(building.NumConnection), mean[2, 0]),
    np.full(building.DoorFront + building.DoorBack + building.DoorGarage
            + building.OpeningFront + building.OpeningBack
            + 2 * (building.OpeningSideR + building.OpeningSideH), mean[3, 0]),
    np.full(12, mean[4, 0]),
    building,
    0,
    50,
)
explicit = ExplicitDamageRatio(building, failure, 0, 0)
print(explicit.ExplicitDamageRatioWind)

Manual-Control Example#

import numpy as np
from types import SimpleNamespace
from cheersafe.config import Config
from cheersafe.damage_ratio_calculation import ExplicitDamageRatio
from cheersafe.inventory import BuildingInventory

building = BuildingInventory(buildings_file_name="BuildingGeometry.json").buildings[0]
resistance = {
    "Openings": np.ones(building.DoorFront + building.DoorBack + building.DoorGarage
                       + building.OpeningFront + building.OpeningBack
                       + 2 * (building.OpeningSideR + building.OpeningSideH)),
    "Walls": np.ones(12),
    "Roof Sheathings": np.ones(sum(building.NumPanel)),
    "Roof Coverings": np.ones(sum(building.NumPanel)),
    "Roof-Wall Connections": np.ones(sum(building.NumConnection)),
}
failure = SimpleNamespace(get_final_resistance=lambda: resistance)

old_execute = Config.AUTO_EXECUTE_METHODS
Config.AUTO_EXECUTE_METHODS = False
try:
    explicit = ExplicitDamageRatio(building, failure, 0, 0)
    explicit.ExplicitDamageRatioWind = explicit.fn_damage_ratio_wind()
finally:
    Config.AUTO_EXECUTE_METHODS = old_execute