DamageRatioCalculation

DamageRatioCalculation is the main damage-ratio workflow class. It calculates explicit component damage ratios, implicit wind and flood damage ratios, and replacement-ratio-weighted building damage ratios.

Use it after LoadingAndFailureCheck when you need the final building damage ratio for one scenario.

Related API: Damage Ratio Calculation API Related notebook: Fragility Curve Calculation with Detailed Damage Ratio Analysis

Inputs

• Building: cheersafe.inventory.Building.
• FailureChecks: cheersafe.loads.LoadingAndFailureCheck.
• ComponentConfigurationIndex: zero-based row index into ComponentCombination_All.
• FloodDepthIndex: zero-based row index in the flood-depth dimension.
• Optional rng: seed or generator for stochastic implicit damage.

File dependencies with automatic dataset loading:

• Inputs/ComponentCombination_All.json, shape (192, 6).
• Inputs/ProbDS_Flood.json, shape (8, 4, 136, 6).
• Inputs/DamageState_Flood.json, shape (6, 2).
• Inputs/ReplacementRatio.json, shape (8, 9).

ReplacementRatio is converted to a dictionary keyed by one-based building type. Component keys are "Roof Coverings", "Roof Sheathings", "Roof-Wall Connections", "Openings", "Walls", "Interior", "Electrical", "Mechanical", and "Plumbing".

Outputs And Returns

Automatic attributes are inherited:

• ExplicitDamageRatioWind: explicit wind component ratios.
• ImplicitDamageRatioWind: implicit wind component ratios.
• ImplicitDamageRatioFlood: implicit flood scalar ratio.
• tempProbDS_Flood: cumulative flood probabilities for the selected component configuration.

Getter returns:

• get_damage_ratio_wind_explicit() -> float: replacement-ratio-weighted explicit wind damage.
• get_damage_ratio_wind_implicit() -> float: replacement-ratio-weighted implicit wind damage.
• get_damage_ratio_flood_implicit() -> float: flood damage scalar.
• get_damage_ratio_explicit() -> float: currently the same as explicit wind damage.
• get_damage_ratio_implicit() -> float: combined wind/flood implicit damage using min(max(wind, flood) + 0.5 * min(wind, flood), 1).
• get_building_damage_ratio() -> float: explicit plus implicit damage.

Config Behavior

With AUTO_LOAD_DATASETS = True, all needed damage-ratio datasets are loaded during construction. With it disabled, call load_ProbDS_Flood(), load_component_combination_all(), load_DS_Flood(), and load_replacement_ratio() or assign equivalent attributes before methods use them.

With AUTO_EXECUTE_METHODS = True, all explicit and implicit component ratios are populated during construction. With it disabled, execute the methods manually before calling the building-level getters.

Automatic Example

import numpy as np
from cheersafe.damage_ratio_calculation import DamageRatioCalculation
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,
)
ratio = DamageRatioCalculation(building, failure, 0, 0, rng=1234)
print(ratio.get_building_damage_ratio())

Manual-Control Example

import numpy as np
from types import SimpleNamespace
from cheersafe.config import Config
from cheersafe.damage_ratio_calculation import DamageRatioCalculation
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:
    ratio = DamageRatioCalculation(building, failure, 0, 0, rng=1234)
    ratio.ExplicitDamageRatioWind = ratio.fn_damage_ratio_wind()
    ratio.ImplicitDamageRatioWind["Interior"] = ratio.fn_damage_ratio_interior_wind()
    ratio.ImplicitDamageRatioWind = ratio.fn_damage_ratio_utility_wind()
    ratio.tempProbDS_Flood = ratio.fn_helper_damage_ratio_flood()
    ratio.ImplicitDamageRatioFlood = ratio.fn_damage_ratio_flood()
    building_damage_ratio = ratio.get_building_damage_ratio()
finally:
    Config.AUTO_EXECUTE_METHODS = old_execute