Skip to content

Damage Probability Calculation#

Use this module to generate CHEERSafe damage-state probability surfaces from building inventories, component resistance samples, wind speeds, flood depths, and wind orientations. It is the upstream producer for vulnerability, fragility, and loss-estimation workflows.

Classes#

Page Use when
DamageCalculator You need helper methods for selecting component combinations, mapping resistance parameters, or converting iteration damage ratios to damage-state probabilities.
DamageProbabilityCalculation You need the full Monte Carlo workflow that writes ProbDS_wfd_m{m}_c{c}_iter{n}.pkl files and optionally aggregates them.
DamageRatioExporter You enable detailed damage-ratio CSV export during probability calculations.

Shared Inputs#

Most classes inherit the dataset loaders from the base calculation class and expect these runtime inputs under Config.INPUTS_PATH, normally Inputs/:

File Shape Units or indexing Purpose
ProbDS_Flood.json [8, 4, 136, 6] building type, flood configuration, flood-depth index, flood damage state Flood damage-state probabilities.
DamageState.json [50, 2] 1-based damage-state id, damage ratio Wind damage-state bins used to classify simulated damage ratios.
WindSpeed.json [25, 3] id, mph, m/s Wind grid. Calculation uses column 2 as mph.
WindOrientation.json [8, 2] id, degrees Orientation grid.
MeanResistanceCV.json [10, 3] component row, resistance config Resistance coefficients of variation.
MeanResistanceValue.json [10, 3] component row, resistance config Mean resistance values. Units depend on component family.
ComponentCombination_Hip.json [24, 10] 1-based config values Hip-roof combinations.
ComponentCombination_Gable.json [48, 10] 1-based config values Gable-roof combinations.
ComponentCombination_All.json [192, 6] RC, RS, RWC, O, W, F Full compact configuration table.

The main workflow also needs initialized BuildingInventory, Sampling, and Covariance objects.

Configuration Behavior#

Config.AUTO_LOAD_DATASETS=True loads the shared datasets during initialization. With False, instantiate the class and call the load_* methods before using helper or workflow methods that rely on those arrays.

DamageProbabilityCalculation does not run the Monte Carlo workflow in __post_init__; call get_average_damage_probability() explicitly. Config.AUTO_EXECUTE_METHODS still affects downstream objects created inside the workflow, such as loading and damage-ratio classes.

Current nuance: DamageProbabilityCalculation.__post_init__ sizes a compatibility IterationResult array from WindSpeeds and ProbDS_Flood. Because of that, constructing this specific class with AUTO_LOAD_DATASETS=False is not a working manual-load pattern unless those attributes are supplied before __post_init__ runs. Use DamageCalculator for manual helper work, or keep auto-loading enabled and control execution by calling workflow methods explicitly.

Minimal Examples#

Automatic dataset loading:

from cheersafe.config import Config
from cheersafe.inventory import BuildingInventory
from cheersafe.tools import Sampling, Covariance
from cheersafe.damage_probability_calculation import DamageProbabilityCalculation

Config.AUTO_LOAD_DATASETS = True
Config.NUM_OF_ITERATIONS = 50

calc = DamageProbabilityCalculation(
    BuildingInventory=BuildingInventory(),
    Sampling=Sampling(),
    Covariance=Covariance(),
)
calc.set_building_types_to_process([1])
calc.set_cindex_to_process([1])
completed = calc.get_average_damage_probability()
probabilities = calc.aggregate_results()

Manual helper loading:

from cheersafe.config import Config
from cheersafe.inventory import BuildingInventory
from cheersafe.tools import Sampling, Covariance
from cheersafe.damage_probability_calculation import DamageCalculator

Config.AUTO_LOAD_DATASETS = False

calc = DamageCalculator(
    BuildingInventory=BuildingInventory(),
    Sampling=Sampling(),
    Covariance=Covariance(),
)
calc.load_damage_states()
calc.load_component_combinations()
gable = calc.get_component_combination_gable()