Proposed Resilience Requirements.

[phylroy]

Resilience CLI Tool

Objective

Create a command-line interface (CLI) tool that analyzes building resiliency scenarios by examining clothing factors and HVAC performance during power outages and extreme weather conditions.

Requirements

• The code/cli should be contained in bin/resilence.py and leverage bin/h2k2hpxml.py and h2ktohpxml/h2ktohpxml.py
• Code should be written in python.
• Code should use the openstudio sdk to articulate the model scearios as required.
• OpenStudio Python Bindings are installed in the environment.
• Always check for python bindings before running.

The CLI should accept the following parameters:

• h2k_path (required): Path to H2K XML file
• outage_days (optional): Number of days for power outage analysis (default: 7, range: 0-365)
• output_path (optional): Output folder path (default: same directory as H2K input file)
• clothing_factor_summer (optional): Summer clothing insulation factor (default: 0.5, range: 0.0-2.0)
• clothing_factor_winter (optional): Winter clothing insulation factor (default: 1.0, range: 0.0-2.0)
• run_simulation(optional): Runs a full annual simulation. (default: False)

Processing Workflow

1. File Setup and Conversion

• Create a original folder within the output directory
• Convert H2K file to OSM format using h2khpxml converter
• Save as original.osm in the baseline folder
• Run original simulation using OpenStudio with robust error handling.

2. Weather File Processing

• Locate matching EWY weather files using h2ktohpxml/resources/weather/h2k_weather_names.csv from the osm.
• The EWY do not exist as yet.. however for the time being you can create a new EWY column and simply copy the CWEC2020.zip values to the new column. We will update the filenames with the actual EYW at a later date.
• Download weather files if not present in resources/weather/ folder
• For both weather files:
  • Scan hourly dry-bulb temperatures
  • Identify the hottest consecutive period matching outage_days length
  • Store start dates in extreme_periods.yml:

    cwec_outage_start_date: "YYYY-MM-DD"
    ewy_outage_start_date: "YYYY-MM-DD"

3. Season Determination

• Analyze both weather files to determine summer/winter periods
• Summer: periods where average daily temperature > 15°C
• Winter: periods where average daily temperature ≤ 15°C
• Store results in summer_period.yml:

  cwec_summer_start: "MM-DD"
  cwec_summer_end: "MM-DD"
  ewy_summer_start: "MM-DD"
  ewy_summer_end: "MM-DD"

4. Scenario Generation

Using OpenStudio Python SDK, create four scenarios based on this matrix:

run_name	weather_file	clothing_schedule	mechanical_cooling_available	power_failure_schedule
outage_typical_year	CWEC	TRUE	TRUE	TRUE
outage_extreme_year	EWY	TRUE	TRUE	TRUE
thermal_autonomy_typical_year	CWEC	TRUE	FALSE	FALSE
thermal_autonomy_extreme_year	EWY	TRUE	FALSE	FALSE

For each scenario:

1. Weather File: Apply the specified weather file (CWEC or EWY)
2. Clothing Schedule:
   • Interate through all OS PeopleDefinition objects in the model and remove any ClothingInsulationSchedule
   • Delete any orphan Schedule objects.
   • Create new 'Seasonal Clothing Schedule' schedule.
   • Set the default value: clothing_factor_winter
   • Add a Summer rule: clothing_factor_summer (applied during summer period from summer_period.yml)
3. Mechanical Cooling:
   • When TRUE: Ensure cooling system is present with appropriate capacity
   • When FALSE: Disable all cooling equipment and remove thermostat cooling setpoints if present.
4. Power Failure Schedule:
   • When TRUE: Create schedule that disables all heating, cooling, and fans during the outage period (from extreme_periods.yml). This should effect all electrical loads as well.
   • When FALSE: Normal operation (no power interruption)
5. Output Variables:
   Add the following OutputVariables to the model. Ensure the reporting frequency is hourly.
   • 'Site Outdoor Air Relative Humidity'
   • 'Zone Air Temperature'
   • 'Zone Air Relative Humidity'
   • 'Zone Mean Radiant Temperature'
   • 'Zone Operative Temperature'
   • 'Zone People Occupant Count'
6. Output: Save each OSM model in a subfolder named after the run_name

5. Optionally Run the Simulations

If run_simulation is True, simulate the models in their folders.

• Run a full annual simulation
• Use the correct weather file associated for each simulation run (CWEC for typical, EWY for extreme)
• Use proper error handling. Log all std output and std error output to log.txt in the run_name folder
• Ensure that the eplusout.sql file was created. Otherwise log a failure to the log.txt file
• Ensure that the eplusout.err does not contain fatal or severe errors, otherwise log the error in the log.txt
• Ensure that the hourly output variables requested are present in the eplusout.sql file
  • Queries ReportVariableDataDictionary table in eplusout.sql
  • Verifies all required variables: 'Zone Air Temperature', 'Zone Mean Radiant Temperature', etc.
  • Confirms hourly reporting frequency for each variable
  • Logs success/failure of validation to log.txt

Error Handling Requirements

• Validate all input parameters and file paths
• Provide clear error messages for missing weather files
• Handle OpenStudio simulation failures gracefully
• Verify weather file data integrity before processing

Output Structure

output_path/
├── baseline/
│   ├── baseline.osm              # Full HPXML-derived OpenStudio model
│   ├── baseline.xml              # Generated HPXML file  
│   ├── hpxml_run/               # OpenStudio-HPXML workflow outputs
│   ├── eplusout.sql             # Simulation results database (if --run-simulation)
│   ├── eplusout.err             # Error log (if --run-simulation)
│   ├── in.idf                   # EnergyPlus input file (if --run-simulation)
│   └── log.txt                  # Simulation log with validation (if --run-simulation)
├── extreme_periods.yml           # Outage start dates for CWEC/EWY
├── summer_period.yml             # Summer season dates (MM-DD format)
├── outage_typical_year/
│   ├── outage_typical_year.osm   # Power outage + CWEC weather scenario
│   ├── eplusout.sql, log.txt     # Simulation results (if --run-simulation)
│   └── [additional EnergyPlus output files]
├── outage_extreme_year/
│   ├── outage_extreme_year.osm   # Power outage + EWY weather scenario  
│   ├── eplusout.sql, log.txt     # Simulation results (if --run-simulation)
│   └── [additional EnergyPlus output files]
├── thermal_autonomy_typical_year/
│   ├── thermal_autonomy_typical_year.osm  # No cooling + CWEC weather
│   ├── eplusout.sql, log.txt     # Simulation results (if --run-simulation)
│   └── [additional EnergyPlus output files]
└── thermal_autonomy_extreme_year/
    ├── thermal_autonomy_extreme_year.osm  # No cooling + EWY weather
    ├── eplusout.sql, log.txt     # Simulation results (if --run-simulation)
    └── [additional EnergyPlus output files]