Skip to content

DamageProbabilityCalculation#

DamageProbabilityCalculation is the full Monte Carlo engine for generating damage-state probability arrays by building type and component configuration. Use it after inventory, loading, damage-ratio, and resistance inputs are ready.

Inputs#

Constructor inputs:

Input Type Notes
BuildingInventory BuildingInventory Supplies buildings; each building must already have inventory outputs such as panels and connections available.
Sampling Sampling Generates Latin-hypercube resistance samples and derived random seeds.
Covariance Covariance Builds covariance matrices from component means and CVs.
building_types_to_process list[int] or None Optional filter. Values are building-type ids such as 1.
cindex_to_process list[int] or None Optional filter. Public cIndex values are 1-based.

Loaded file inputs are listed in the module overview. The workflow also creates LoadingAndFailureCheck and DamageRatioCalculation objects for each sampled condition, so their required inventory, pressure coefficient, replacement ratio, and damage-ratio inputs must be available too.

Key indexing and shapes:

Value Shape Notes
wind grid len(WindSpeeds) Bundled input has 25 wind-speed rows.
flood grid ProbDS_Flood.shape[2] Bundled input has 136 flood-depth rows.
damage states len(DamageStates) Bundled input has 50 states.
per-run output [wind, flood, damage_state] Saved for each (building_type, cIndex).
aggregate output dict[(m, c), array] Keys are integer building type and 1-based cIndex.

Outputs And Returns#

Method Returns Files or state
set_building_types_to_process(building_types) None Stores the building-type filter.
set_cindex_to_process(cindices) None Stores the 1-based component-index filter. Rejects values below 1.
process_single_iteration(...) (iter_results, detailed_results) No persistent state.
process_component_combination(building, ComponentCombination, cIndex) (m, cIndex, ProbDS_wfd) or None Writes ProbDS_wfd_m{m}_c{cIndex}_iter{NUM_OF_ITERATIONS}.pkl; may write detailed CSV.
get_available_building_types() list[int] None.
get_available_cindices() list[int] None.
get_average_damage_probability() True Writes one pickle per processed (m, cIndex).
aggregate_results(output_dir=None) dict[(int, int), np.ndarray] Sets ProbDS_wfd_dict and writes ProbDS_wfd_dictMaxIter{NUM_OF_ITERATIONS}_aggregated.pkl.

Detailed CSV export is controlled by Config.EXPORT_DETAILED_DAMAGE_RATIOS. When enabled, files are named DetailedDR_m{m}_c{cIndex}_iter{NUM_OF_ITERATIONS}.csv.

Configuration Behavior#

Config.AUTO_LOAD_DATASETS=True loads shared probability-calculation datasets during initialization. With False, call all required load_* methods before running workflow methods. Current limitation: this class also creates IterationResult in __post_init__ from WindSpeeds and ProbDS_Flood, so a plain construction with AUTO_LOAD_DATASETS=False raises before manual loaders can be called. Keep auto-loading enabled for this class unless you are subclassing or otherwise pre-populating those attributes before __post_init__.

DamageProbabilityCalculation.__post_init__ initializes compatibility storage but does not call get_average_damage_probability(). Config.AUTO_EXECUTE_METHODS affects downstream CHEERSafe objects constructed during the run.

Minimal Examples#

Automatic workflow for a small filtered run:

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
Config.NUM_OF_WORKERS = 1

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

Manual-control setup without running the Monte Carlo loop:

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.AUTO_EXECUTE_METHODS = False

calc = DamageProbabilityCalculation(BuildingInventory(), Sampling(), Covariance())
building_types = calc.get_available_building_types()
cindices = calc.get_available_cindices()