---

name: running-openstudio-models description: Use this skill when working with OpenStudio 3.10 .osm models to adjust HVAC systems, equipment, thermal zones, schedules, or constructions, then run simulations to validate changes. Handles applying existing measures, running CLI simulations, and saving versioned model files. Delegates to diagnosing-energy-models for simulation failures and writing-openstudio-model-measures for custom measure creation. Includes BCL measure search and download.

Running OpenStudio Models

This skill helps you work with OpenStudio 3.10 .osm models to modify building systems, apply measures, and run simulations. It focuses on practical model adjustments and validation runs using the OpenStudio CLI.

Core Approach

1. Model Versioning: Always save new versions before making changes (format: projectname_YYYY-MM-DD_vX.osm)
2. Incremental Changes: Modify HVAC, zones, schedules, or constructions systematically
3. Apply Measures: Use existing measures from BCL or local libraries
4. Run & Validate: Execute simulations and verify successful completion
5. Delegate Issues: Hand off failures to diagnosing-energy-models skill
6. Delegate Custom Measures: Hand off measure creation to writing-openstudio-model-measures skill

OpenStudio CLI Basics

Installation Path: C:\openstudio-3.10.0\bin\openstudio.exe

Core Commands:

• openstudio.exe run --workflow workflow.osw - Run complete simulation
• openstudio.exe run --measures_only --workflow workflow.osw - Apply measures without simulation
• openstudio.exe measure --update /path/to/measure/ - Update measure metadata

File Conventions:

• No whitespace in paths: use underscored_path/my_model.osm not whitespace path/my model.osm
• Use forward slashes in OSW files even on Windows

Step-by-Step Workflow

1. Version the Current Model

Before any changes, create a versioned copy:

# Get current date for filename
node -e "console.log(new Date().toISOString().split('T')[0])"

# Copy model with versioning (example for project SECC)
cp existing_model.osm SECC_2025-12-03_v1.osm

Naming Convention: {projectname}_{YYYY-MM-DD}_v{X}.osm

• projectname: Project identifier (e.g., SECC, MVCC, Wintrust)
• YYYY-MM-DD: Today's date
• vX: Version number for that day (v1, v2, v3, etc.)

2. Check for Weather File

Before running simulations, verify weather file exists:

# Check if .epw file exists in current directory
cmd /c "dir *.epw /b"

If no weather file found:

• Prompt user: "No weather file found. Please provide the .epw file for this project."
• Ask for location: User should place .epw in the project folder or provide path

3. Create or Modify OpenStudio Workflow (OSW)

Create a JSON workflow file to define the simulation:

Basic OSW Template (workflow.osw):

{
  "seed_file": "SECC_2025-12-03_v1.osm",
  "weather_file": "USA_CO_Fort_Collins.epw",
  "steps": []
}

OSW with Measures:

{
  "seed_file": "SECC_2025-12-03_v1.osm",
  "weather_file": "USA_CO_Fort_Collins.epw",
  "steps": [
    {
      "measure_dir_name": "AddMeter",
      "arguments": {
        "meter_name": "Electricity:Facility"
      }
    }
  ]
}

Use Node.js to generate OSW files programmatically:

#!/usr/bin/env node
import { writeFile } from 'fs/promises';

const workflow = {
  seed_file: "SECC_2025-12-03_v1.osm",
  weather_file: "USA_CO_Fort_Collins.epw",
  steps: []
};

await writeFile('workflow.osw', JSON.stringify(workflow, null, 2));
console.log("Created workflow.osw");

4. Search and Download Measures from BCL

The Building Component Library (BCL) hosts community measures.

Search for measures:

• Visit: https://bcl.nrel.gov/
• Search by keyword (e.g., "HVAC", "schedule", "envelope")
• Note the measure name and download URL

Download measures manually:

1. Download .tar.gz or .zip from BCL
2. Extract to measures/ directory in project folder
3. Update measure metadata:

C:\openstudio-3.10.0\bin\openstudio.exe measure --update measures/measure_name/

Organize measures:

# Create measures directory
mkdir measures

# After downloading and extracting BCL measure
C:\openstudio-3.10.0\bin\openstudio.exe measure --update_all measures/

5. Apply Measures to Model

Option A: Using OSW Workflow (Recommended)

Add measures to the steps array in your OSW file:

{
  "seed_file": "SECC_2025-12-03_v1.osm",
  "weather_file": "USA_CO_Fort_Collins.epw",
  "steps": [
    {
      "measure_dir_name": "SetThermostatSchedules",
      "arguments": {
        "heating_setpoint": 20,
        "cooling_setpoint": 24
      }
    }
  ]
}

Run with measures only (no simulation):

C:\openstudio-3.10.0\bin\openstudio.exe run --measures_only --workflow workflow.osw

Option B: Compute Measure Arguments

If you need to see what arguments a measure accepts:

C:\openstudio-3.10.0\bin\openstudio.exe measure --compute_arguments SECC_2025-12-03_v1.osm measures/SetThermostatSchedules/

6. Run Simulation

Execute the full simulation workflow:

C:\openstudio-3.10.0\bin\openstudio.exe run --workflow workflow.osw

With debugging (if issues expected):

C:\openstudio-3.10.0\bin\openstudio.exe --verbose run --debug --workflow workflow.osw

Output Files:

• run/ directory created with simulation results
• run/eplusout.err - EnergyPlus error file
• run/eplusout.sql - Simulation results database
• out.osw - Workflow output with execution log

7. Check Simulation Success

Quick Check:

# Check if error file exists and is small (successful runs have minimal errors)
cmd /c "dir run\eplusout.err"

# View last 20 lines of error file
cmd /c "type run\eplusout.err | more +20"

Success Indicators:

• out.osw contains "completed_status": "Success"
• eplusout.err has no severe errors
• eplusout.sql file exists and has data

Failure Indicators:

• out.osw shows "completed_status": "Fail"
• eplusout.err contains ** Severe ** errors
• Missing output files

8. Handle Simulation Failures

If simulation fails, delegate to diagnosing-energy-models skill:

Gather context:

# Read error file
type run\eplusout.err

# Check out.osw for step_errors
type out.osw | findstr "step_errors"

# Get model summary
C:\openstudio-3.10.0\bin\openstudio.exe --verbose run --measures_only --workflow workflow.osw

Hand off to diagnostic skill:

• Provide path to .err file
• Include out.osw step_errors
• Describe what changes were made
• Share OSW file contents

Example delegation:

"Simulation failed with severe errors. Delegating to diagnosing-energy-models skill to analyze run/eplusout.err and diagnose the issue. Changes made: [describe HVAC/zone/schedule modifications]."

Model Modification Patterns

Modifying HVAC Systems

OpenStudio models use object-oriented HVAC components. Common modifications:

Access HVAC loops programmatically (requires Ruby or Python bindings):

• Air loops: model.getAirLoopHVACs
• Plant loops: model.getPlantLoops
• Thermal zones: model.getThermalZones

Recommended approach: Use existing measures from BCL

• "Add HVAC System" measure family
• "Replace HVAC" measures
• "Modify HVAC" measures

If custom HVAC logic needed, delegate to writing-openstudio-model-measures skill.

Modifying Thermal Zones

Via Measures:

• "Set Thermal Zone Properties"
• "Assign Spaces to Thermal Zones"
• "Merge Thermal Zones"

Manual edits: Not recommended via CLI (use OpenStudio Application GUI or custom measure)

Modifying Schedules

Via Measures:

• "Set Thermostat Schedules"
• "Modify Occupancy Schedules"
• "Add Typical Schedules"

Arguments example:

{
  "measure_dir_name": "SetThermostatSchedules",
  "arguments": {
    "heating_setpoint_schedule": "HtgSetp 20C",
    "cooling_setpoint_schedule": "ClgSetp 24C"
  }
}

Modifying Constructions

Via Measures:

• "Set Construction Properties"
• "Increase Insulation R-Value"
• "Replace Constructions"

Arguments example:

{
  "measure_dir_name": "IncreaseInsulationRValueForExteriorWalls",
  "arguments": {
    "r_value": 3.5
  }
}

Validation Checklist

After running simulation, verify:

• New versioned .osm file created
• Simulation completed without severe errors
• eplusout.sql file generated
• out.osw shows "completed_status": "Success"
• Results make sense for changes made

If failures occur:

• Delegate to diagnosing-energy-models with error context
• Include .err file path and recent changes

Common Issues & Quick Fixes

Issue: Missing Weather File

Symptoms: Workflow fails immediately with "weather file not found"

Solution:

# Check for weather files
cmd /c "dir *.epw /b"

# If missing, prompt user for .epw file path

Prompt: "No weather file found. Please provide the .epw file path for this project."

Issue: Measure Not Found

Symptoms: out.osw shows measure directory not found

Investigation:

# Check measures directory
cmd /c "dir measures /b"

# Update measure if it exists
C:\openstudio-3.10.0\bin\openstudio.exe measure --update measures/MeasureName/

Solution:

• Download measure from BCL
• Verify measure directory name matches OSW measure_dir_name
• Run --update to regenerate metadata

Issue: Model Translation Failure

Symptoms: Fails when translating OSM to IDF

Delegate to: diagnosing-energy-models skill

• Likely geometry issues (intersecting surfaces, non-planar surfaces)
• Could be orphaned objects

Issue: EnergyPlus Simulation Severe Errors

Symptoms: Simulation runs but produces severe errors in eplusout.err

Delegate to: diagnosing-energy-models skill with:

• Path to run/eplusout.err
• Description of model changes
• OSW file contents

Skill Orchestration

When to Stay in This Skill

• Running existing models
• Applying downloaded/existing measures
• Making straightforward HVAC, zone, schedule, or construction changes
• Versioning and managing model files

When to Delegate to diagnosing-energy-models

• Simulation fails with severe errors
• Model translation fails (OSM → IDF)
• Geometry errors appear
• Complex diagnostic analysis needed
• Provide: .err file path, out.osw errors, recent changes

When to Delegate to writing-openstudio-model-measures

• Custom measure logic required
• Existing BCL measures don't fit use case
• Need to create reusable measure for repeated operations
• Provide: Desired functionality, model context, argument requirements

Reference Resources

Official Documentation

• OpenStudio CLI Reference: https://nrel.github.io/OpenStudio-user-documentation/reference/command_line_interface/
• OpenStudio SDK Docs: https://nrel.github.io/OpenStudio-user-documentation/
• Measure Writer's Guide: https://nrel.github.io/OpenStudio-user-documentation/reference/measure_writing_guide/

Troubleshooting Resources

• OpenStudio Coalition Troubleshooting: https://openstudiocoalition.org/getting_started/troubleshooting/
• Unmet Hours Forum: https://unmethours.com/ (community Q&A)

Measure Resources

• Building Component Library (BCL): https://bcl.nrel.gov/
• NREL GitHub: https://github.com/NREL/ (official measures and tools)

See ./openstudio-cli-reference.md for detailed CLI command syntax and examples.