Skip to content

Config#

cheersafe.config.Config is a dataclass used as global class-level runtime configuration. Import it when you need to select input/output directories, switch between automatic and manual workflows, set simulation sizes, or reset a session after changing global flags.

Purpose And When To Use#

Use Config before constructing CHEERSafe objects. Most classes read the class attributes during initialization, so changing a flag after an object is created does not retroactively load datasets or calculate missing attributes unless the object exposes an explicit method such as update_outputs().

Config.reset_flags() restores the package defaults and is useful in notebooks, tests, and examples where previous cells may have changed global state.

Inputs#

Config has no instance inputs. Set class attributes directly.

Attribute Default Unit or meaning Used by
AUTO_EXECUTE_METHODS True Run calculation methods during object initialization. Building, loads, damage ratio, and analysis calculators.
AUTO_LOAD_DATASETS True Load file-backed datasets during object initialization. BuildingInventory, loads, damage probability, analysis, and loss workflows.
INPUTS_PATH "Inputs" Directory containing runtime JSON/CSV input files. Dataset loaders and inventory loaders.
OUTPUTS_PATH "Outputs" Directory for generated pickle/CSV outputs. Damage probability and loss output workflows.
NUM_OF_ITERATIONS 3000 Monte Carlo iterations. Damage probability calculation.
NUM_OF_WORKERS 4 Parallel jobs. Joblib-backed damage probability calculation.
NUM_OF_WORKERS_SAMPLING 1 Workers passed to SciPy Latin hypercube sampling. Sampling.generate_lhs_samples_*.
RANDOM_SEED 42 Default deterministic seed. Sampling helpers.
EXPORT_DETAILED_DAMAGE_RATIOS False Export component-level detailed damage-ratio CSV files. Damage probability calculation.

Outputs And Returns#

Config.reset_flags() mutates the class attributes above and returns None. The class itself does not produce arrays or files. Other modules read its values when they load data, run calculations, or write outputs.

AUTO_LOAD_DATASETS Behavior#

With AUTO_LOAD_DATASETS = True, file-backed classes load their datasets during initialization. For example, BuildingInventory() reads Config.INPUTS_PATH / buildings_file_name.

With AUTO_LOAD_DATASETS = False, those classes are created without loading their datasets. Call the relevant loader manually, such as inventory.instantiate_buildings_from_json().

Config itself is never file-backed, so this flag does not change how Config is created.

AUTO_EXECUTE_METHODS Behavior#

With AUTO_EXECUTE_METHODS = True, calculation classes that support automatic execution compute their derived outputs during initialization. For inventory, each Building computes PanelCoordinate, NumPanel, ConnectionCoordinate, and NumConnection when it is instantiated.

With AUTO_EXECUTE_METHODS = False, calculation outputs are left unset until you call the corresponding method and assign or pass along the returned values.

Config itself has no calculation methods controlled by this flag.

Minimal Automatic Example#

Run from the repository root before package installation:

PYTHONPATH=src python3 - <<'PY'
from cheersafe.config import Config
from cheersafe.inventory import BuildingInventory

Config.reset_flags()
Config.INPUTS_PATH = "Inputs"

inventory = BuildingInventory()
print(len(inventory.buildings))
print(inventory.buildings[0].PanelCoordinate.shape)

Config.reset_flags()
PY

Minimal Manual-Control Example#

PYTHONPATH=src python3 - <<'PY'
from cheersafe.config import Config
from cheersafe.inventory import BuildingInventory

Config.reset_flags()
Config.AUTO_LOAD_DATASETS = False
Config.AUTO_EXECUTE_METHODS = False

inventory = BuildingInventory()
print(hasattr(inventory, "buildings"))

inventory.instantiate_buildings_from_json()
building = inventory.buildings[0]

panel_coordinate, num_panel = building.fn_panel_coordinate()
connection_coordinate, num_connection = building.fn_connection_coordinate()

print(panel_coordinate.shape, num_panel.tolist())
print(connection_coordinate.shape, num_connection)

Config.reset_flags()
PY