Restructure as Python Package, Internalize Input Builder, and Improve Robustness

.gitignore

@@ -12,15 +12,22 @@
 .coverage
 
 # Python egg metadata, regenerated from source files by setuptools
-/*.egg-info
-/*.egg
+*.egg-info/
+.eggs/
+*.egg
 
 # Temporary jupyter files
 /.ipynb_checkpoints/
 *.ipynb_checkpoints
 
 # Output folder
-/outputs/
+outputs/
+
+# Folder with original Matlab code
+/Matlab_code/
+
+.ai/
+Comparison_scripts/
 
 # All new files coming out of buildInputs
 inputs/example_inputs/*/optional_inputs.json

README.md

@@ -2,43 +2,39 @@
 This is translation of Matlab codebase into Python for quantifying building-specific functional recovery and reoccupancy based on a probabilistic performance-based earthquake engineering framework.
 
 ## Requirements
-- The `requirements.txt` file defines the Python package dependencies required to run this codebase. Follow the instructions below to install all required depenedancies listed in the 'requirements.txt' file.
-- Recommended Python version: `3.9` (the codebase was developed and tested with Python 3.9).
 
-Installation (using a virtual environment is recommended):
+- **Python Version**: 3.9 or later (recommend 3.9)
+- **Package Manager**: pip (comes with Python)
 
-```powershell
-# create a virtual environment
-python -m venv .venv
+### Installation
 
-# activate the virtual environment (PowerShell)
-.\.venv\Scripts\Activate.ps1
+The ATC-138 Functional Recovery Assessment tool is distributed as a Python package. Install it using pip:
 
-# upgrade pip (optional but recommended)
-python -m pip install --upgrade pip
 
-# install dependencies from requirements.txt
-pip install -r requirements.txt
-```
+```bash
+# Create and activate a virtual environment (recommended)
+python -m venv .venv
 
-If you prefer conda:
+# Activate virtual environment
+# On Windows (PowerShell):
+.\.venv\Scripts\Activate.ps1
+# On macOS/Linux:
+source .venv/bin/activate
 
-```bash
-conda create -n frec python=3.9
-conda activate frec
-pip install -r requirements.txt
+# Install the package in editable mode
+pip install -e .
 ```
 
-If you run into platform-specific dependency issues, please refer to the package error messages and install any missing system libraries before re-running `pip install -r requirements.txt`.
-Original Matlab code is from Dr. Dustin Cook's Github directory https://github.com/OpenPBEE/PBEE-Recovery.
 
-### Method Description
-The method for quantifying building-specific functional recovery is based on the performance-based earthquake engineering framework. To quantify building function, the method maps component-level damage to system-level performance, and system-level performance to building function using a series of fault trees that describe the interdependencies between the functions of various building components. The method defines the recovery of function and occupancy at the tenant unit level, where a building can be made up of one-to-many tenant units, each with a possible unique set of requirements to regain building function; the recovery state of the building is defined as an aggregation of all the tenant units within the building. The method propagates uncertainty through the assessment using a Monte Carlo simulation. Details of the method are fully described in Cook, Liel, Haselton, and Koliou, 2022. "A Framework for Operationalizing the Assessment of Post Earthquake Functional Recovery of Buildings", Earthquake Spectra.
+### Verify Installation
+
+After installation, verify that the CLI is available:
 
-### Implementation Details
-The method is developed as part of the consequence module of the Performance-Based Earthquake Engineering framework and uses simulations of component damage from the FEMA P-58 method as an fundamental input. Therefore, this implementation will not perform a FEMA P-58 assessment, and instead, expects the simulations of component damage, from a FEMA P-58 assessment to be provided as inputs. Along with other information about the building, the buildings tenant units, and some analysis options, this implementation will perform the functional recovery assessment method, and provide simulated recovery times for each realization provided. The implementation runs an assessment for a single building at a single intensity level. The implementation of the method does not handle demo and replace conditions and predicts building function based on component damage simulation and recovery times assuming damage will be repaired in-kind. Building failure, demo, and replacement conditions can be handled as a post-process by either overwriting realizations where global failure occurs or only inputting realizations that are scheduled for repair.
+```bash
+atc138 --help
+```
 
-The method is employs Python v 3.9; running this implementation using other versions of Python may not perform as expected.
+You should see the command help output with available options.
 
 ## Running an Assessment
  - **Step 1**: Build the inputs json file of simulated inputs. Title the file "simulated_inputs.json" and place it in a directory of the model name within the "inputs" drirectory. This json data file can either be constructed manually following the inputs schema or using the build script as discussed in the _Building the Inputs File section_ below.

pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "atc138"
+version = "0.1.0"
+description = "Functional Recovery Assessment (ATC-138)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {file = "LICENSE"}
+authors = [
+  {name = "Dustin Cook", email = "dustin.cook@nist.gov"},
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: BSD License",
+  "Operating System :: OS Independent",
+]
+dependencies = [
+  "numpy",
+  "pandas",
+  "scipy",
+  "matplotlib",
+  "seaborn",
+]
+
+[project.scripts]
+atc138 = "atc138.cli:main"
+
+[project.urls]
+"Homepage" = "https://github.com/NHERI-SimCenter/Functional-Recovery-Python"
+"Bug Tracker" = "https://github.com/NHERI-SimCenter/Functional-Recovery-Python/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

src/atc138/cli.py

@@ -0,0 +1,26 @@
+import argparse
+import sys
+import os
+from .driver import run_analysis
+
+def main():
+    parser = argparse.ArgumentParser(description="Run ATC-138 Functional Recovery Assessment")
+    parser.add_argument("input_dir", help="Path to the directory containing input files (e.g., simulated_inputs.json)")
+    parser.add_argument("output_dir", help="Path to the directory where outputs will be saved")
+    parser.add_argument("--seed", type=int, help="Random seed for reproducibility", default=None)
+
+    args = parser.parse_args()
+
+    # Validate inputs
+    if not os.path.isdir(args.input_dir):
+        print(f"Error: Input directory '{args.input_dir}' does not exist.", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        run_analysis(args.input_dir, args.output_dir, seed=args.seed)
+    except Exception as e:
+        print(f"Error running analysis: {e}", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

src/atc138/data/default_inputs.json

@@ -0,0 +1,81 @@
+{
+  "impedance_options": {
+    "include_impedance": {
+      "inspection": true,
+      "financing": true,
+      "permitting": true,
+      "engineering": true,
+      "contractor": true,
+      "long_lead": false
+    },
+    "system_design_time": {
+      "f": 0.04,
+      "r": 200,
+      "t": 1.3,
+      "w": 8
+    },
+    "eng_design_min_days": 14,
+    "eng_design_max_days": 365,
+    "mitigation": {
+      "is_essential_facility": false,
+      "is_borp_equivalent": false,
+      "is_engineer_on_retainer": false,
+      "contractor_relationship": "good",
+      "contractor_retainer_time": 3,
+      "funding_source": "private",
+      "capital_available_ratio": 0.02
+    },
+    "impedance_beta": 0.6,
+    "impedance_truncation": 2,
+    "default_lead_time": 182,
+    "demand_surge": {
+      "include_surge": 1,
+      "is_dense_urban_area": 1,
+      "site_pga": 1,
+      "pga_de": 1
+    },
+    "scaffolding_lead_time": 5,
+    "scaffolding_erect_time": 2,
+    "door_racking_repair_day": 3,
+    "flooding_cleanup_day": 5,
+    "flooding_repair_day": 90
+  },
+  "repair_time_options": {
+    "max_workers_per_sqft_story": 0.001,
+    "max_workers_per_sqft_story_temp_repair": 0.005,
+    "max_workers_per_sqft_building": 0.00025,
+    "max_workers_building_min": 20,
+    "max_workers_building_max": 260,
+    "allow_tmp_repairs": 1,
+    "allow_shoring": 1
+  },
+  "functionality_options": {
+    "calculate_red_tag": 1,
+    "red_tag_clear_time": 7,
+    "red_tag_clear_beta": 0.6,
+    "red_tag_options": {
+      "tag_coupling_beams_over_height": true,
+      "ignore_coupling_beam_for_red_tag": false
+    },
+    "include_local_stability_impact": 1,
+    "include_flooding_impact": 1,
+    "egress_threshold": 0.5,
+    "fire_watch": true,
+    "local_fire_damamge_threshold": 0.25,
+    "min_egress_paths": 2,
+    "exterior_safety_threshold": 0.1,
+    "interior_safety_threshold": 0.25,
+    "door_access_width_ft": 9,
+    "habitability_requirements": {
+      "electrical": 0,
+      "water_potable": 0,
+      "water_sanitary": 0,
+      "hvac_ventilation": 0,
+      "hvac_heating": 0,
+      "hvac_cooling": 0,
+      "hvac_exhaust": 0
+    },
+    "water_pressure_max_story": 4,
+    "heat_utility": "gas"
+  }
+}