Skip to content

Quickstart Guide#

This guide shows the shortest path from installation to a small CHEERSafe damage-probability run. For deeper control of each class, use the User Manual and the example notebooks.

Installation#

Clone the repository and install CHEERSafe:

git clone https://github.com/CHEER-Hub/CHEERSafe.git
cd CHEERSafe
pip install .

For notebooks and local documentation builds, install the optional extras:

pip install -e ".[dev,docs,jupyter]"

Interactive Examples#

Start with these notebooks:

Additional module notebooks are available from the Examples navigation section.

Minimal Workflow#

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

Config.NUM_OF_ITERATIONS = 5
Config.NUM_OF_WORKERS = 1
Config.INPUTS_PATH = "Inputs"
Config.OUTPUTS_PATH = "Outputs"

inventory = BuildingInventory(buildings_file_name="BuildingGeometry_Old.json")
calculation = DamageProbabilityCalculation(
    BuildingInventory=inventory,
    Sampling=Sampling(),
    Covariance=Covariance(),
)

calculation.set_building_types_to_process([1])
calculation.set_cindex_to_process([1])
calculation.get_average_damage_probability()
probabilities = calculation.aggregate_results()

Config.reset_flags()

Exposure And Loss Workflow#

The exposure and loss-estimation modules take a building inventory and hazard layers to expected annual loss. This snippet builds a small synthetic case (inventory, hazard events, zones, event probabilities and a damage library), runs the exposure chain and hands the result to LossEstimation in memory:

import pickle

from cheersafe.config import Config
from cheersafe.exposure import Exposure, SyntheticExposureData
from cheersafe.loss_estimation import LossEstimation
from cheersafe.tools import Utils

Config.reset_flags()
case = "Outputs/quickstart"
probabilities = SyntheticExposureData.make_hurricane_probabilities(3, seed=1)
paths = SyntheticExposureData.save_inputs(
    case,
    inventory=SyntheticExposureData.make_inventory(200, seed=1, include_edge_cases=False),
    hazard_events=SyntheticExposureData.make_hazard_events(("h1", "h2", "h3"), seed=1),
    zones=SyntheticExposureData.make_zones(),
    hurricane_probabilities=probabilities,
    wind_speeds=Utils.from_json("Inputs/WindSpeed.json"),
    flood_depths=Utils.from_json("Inputs/FloodDepth.json"),
    damage_states=Utils.from_json("Inputs/DamageState.json"),
    component_combinations=Utils.from_json("Inputs/ComponentCombination_All.json"),
)

# Exposure: archetypes M and C, hazard IDs per event, zone ids, STARR table
exposure = Exposure(
    inventory_path=paths["inventory"], hazard_dir=paths["hazard_dir"], zones_path=paths["zones"], seed=1
)

# A damage library for the (M, C) pairs that occur, then loss estimation in memory
pairs = sorted(set(zip(exposure.starr_inventory["M"], exposure.starr_inventory["C"])))
library_path = f"{case}/Inputs/damage_library.pkl"
with open(library_path, "wb") as handle:
    pickle.dump(SyntheticExposureData.make_damage_library(pairs, seed=1, unnormalized_rows=0), handle)

estimator = LossEstimation(
    prob_ds_file_path=library_path,
    hurricane_probabilities=probabilities,
    zones_path=paths["zones"],
    aggregation_col="i_lh503",
)
estimator.load_from_exposure(exposure)
results = estimator.estimate_all_losses()
print(results["zone_eal"])

Wind_Tr and Flood_Tr are continuous, 1-based hazard IDs; index_mode (floor by default) decides how they select lookup-table bins, and combine_mode / value_basis decide how wind and flood are combined and which value the loss ratio multiplies. See the exposure and loss-estimation manuals.

Key Concepts#

  • Config.AUTO_LOAD_DATASETS=True lets supported classes load their standard input files during initialization.
  • Config.AUTO_EXECUTE_METHODS=True lets supported classes calculate derived outputs during initialization.
  • Turn either flag off when you want to load data or assign returned method outputs manually.
  • Most public building and calculation indices in examples are 1-based, while several lower-level arrays use Python's 0-based indexing internally.
  • Hazard IDs produced by the exposure module are continuous (for example 2.5 between the 50 mph and 55 mph knots); the loss module's index_mode chooses the bin, and floor reproduces the published Eastern North Carolina maps.

Next Steps#

  • Review the input manual for runtime file shapes, units, and indexing conventions.
  • Open the class-level user manual pages for the module you are using.
  • Use the API Reference when you need signatures and docstring-level details.