Diagnosing Energy Models

Energy Model Diagnostics Skill

Systematic troubleshooting, validation, and repair workflows for OpenStudio and EnergyPlus energy models. Particularly useful for LEED projects, complex HVAC systems, and models with geometry errors.

Key Principle: All recommendations must be validated against authoritative sources before implementation.

VALIDATION PROTOCOL (CRITICAL)

Before providing ANY fix recommendations, validate your approach using these authoritative sources in priority order:

Required Validation Steps

1. Check OpenStudio Documentation FIRST (Primary Source - MANDATORY for geometry and HVAC)

   • Use WebFetch: https://nrel.github.io/OpenStudio-user-documentation/
   • Version: OpenStudio 3.9 (default unless specified otherwise)
   • For: Geometry issues, HVAC system setup and connections, OpenStudio workflows
   • Priority Rule: ALWAYS check OpenStudio docs BEFORE any other source for geometry fixes and HVAC solutions

2. Search Unmet Hours Community (Secondary Source - Use with Caution)

   • Use WebSearch: site:unmethours.com [topic] openstudio
   • For: Real-world troubleshooting, edge cases not in official docs
   • Caution: Prioritize answers from well-regarded contributors (NREL staff, Big Ladder Software, high-karma users)
   • When NOT to use: As primary source when OpenStudio docs provide clear guidance
   • If Unmet Hours contradicts OpenStudio docs → Trust OpenStudio docs

3. Reference EnergyPlus Documentation (Object-Level Details)

   • Use WebFetch: https://bigladdersoftware.com/epx/docs/24-2/input-output-reference/
   • Version: EnergyPlus 24.2 (aligns with OpenStudio 3.9)
   • For: EnergyPlus object requirements, field definitions, simulation errors

Validation Checklist

Before recommending any fix:

• Checked OpenStudio 3.9 documentation FIRST (mandatory for geometry/HVAC)
• If using Unmet Hours: Verified contributor reputation and answer quality
• Verified approach compatible with OpenStudio 3.9 / EnergyPlus 24.2
• Cross-validated if sources conflict (OpenStudio docs take precedence)
• Included brief source citation in recommendation

See validation-sources.md for detailed instructions on version-specific docs and contributor evaluation.

Core Capabilities

Geometry Diagnostics

• Intersecting Surfaces: Identify overlapping geometry causing simulation failures
• Story Organization: Validate proper vertical building structure (common critical error)
• Surface Matching: Verify adjacent surfaces properly matched
• Non-Planar Surfaces: Find and fix vertex alignment issues from SketchUp imports

HVAC System Validation

• EOR Compliance: Match modeled systems to Engineer of Record specifications
• Thermal Zone Assignment: Verify space-to-zone-to-equipment mappings
• Plant Loop Integrity: Check connections between plant equipment and air/water loops
• Equipment Validation: Verify equipment types, capacities, and connections

LEED Compliance

• Appendix G Baseline: Generate baseline models per ASHRAE 90.1
• Building Rotation: Create and analyze 4 rotated baseline models
• Percent Savings: Calculate energy cost budget and verify savings targets
• Documentation: Prepare LEED submittal deliverables

Model Quality Assurance

• Pre-Simulation Checks: Validate model completeness before running
• Error Parsing: Translate EnergyPlus errors into actionable fixes
• Results Validation: Verify simulation outputs are reasonable

Common Error Patterns

Six major patterns account for most model failures.

For detailed symptoms, root causes, and step-by-step fixes, see common-error-patterns.md

Quick Reference

Pattern 1: Overlapping Building Stories

• Multiple stories with same Z-coordinate (typically Z=0)
• Causes severe geometry errors, simulation failure
• Fix: Consolidate spaces onto correct physical floor levels
• Validate before fixing: Check OpenStudio geometry documentation

Pattern 2: Non-Planar Surfaces

• Vertices not coplanar, typically from SketchUp geometry
• Causes simulation warnings or failures
• Fix: Delete and recreate using OpenStudio SketchUp plugin tools
• Validate before fixing: Search Unmet Hours for non-planar surface solutions

Pattern 3: Unassigned Thermal Zones

• Spaces without zones or orphaned zones without spaces
• Causes HVAC errors, simulation failure
• Fix: Create zone assignment matrix, assign systematically
• Validate before fixing: Check OpenStudio thermal zone documentation

Pattern 4: Missing HVAC Connections

• Components not connected to plant loops
• Node connection mismatches
• Fix: Delete and re-add using proper OpenStudio workflow
• Validate before fixing: Check OpenStudio HVAC docs + Unmet Hours

Pattern 5: Surface Matching Failures

• Adjacent surfaces not matched (red in 3D view)
• Fix: Run surface matching algorithm, check story organization
• Validate before fixing: Check OpenStudio surface matching documentation

Pattern 6: Schedule Type Mismatches

• Wrong schedule type limits for object field
• Fix: Verify required schedule type in EnergyPlus I/O Reference
• Validate before fixing: Check EnergyPlus documentation

Diagnostic Workflows

Five systematic workflows for common scenarios.

For detailed step-by-step procedures, see diagnostic-workflows.md

Workflow 1: Model Triage (5-10 minutes)

When: Model fails to simulate or has unexpected behavior

Quick Steps:

1. Check story organization (flag duplicate Z-coordinates)
2. Validate surfaces (count, check for anomalies, intersections)
3. Verify zone assignments (spaces have zones, zones have spaces)
4. Check HVAC topology (plant loops, air loops, terminals connected)
5. Attempt simulation, parse top errors

Output: Prioritized list of blocking issues

Before providing fixes: Validate approach for each issue type using validation-sources.md

Workflow 2: Geometry Rebuild Decision (15-20 minutes)

When: Considering whether to fix or rebuild geometry

Decision Criteria:

• Fix: <10 intersecting surfaces, correct story organization, high preservation value
• Rebuild: >10 intersecting surfaces, multiple stories at Z=0, systemic issues
• Hybrid: Extract valuable components, rebuild geometry, reapply

Time Estimates:

• Small fix (<5 surfaces): 1-2 hours
• Medium fix (5-10 surfaces): 3-5 hours
• Small building rebuild (<20k sf): 4-8 hours
• Large building rebuild (50-100k sf): 16-24 hours

Before recommending: Validate geometry best practices with OpenStudio documentation

Workflow 3: EOR Specification Mapping (30-45 minutes)

When: Starting new model or validating zone assignments

Key Steps:

1. Gather EOR documents (mechanical drawings, equipment schedules, BOD)
2. Create equipment matrix (equipment ID, type, spaces served, capacities)
3. Create space assignment matrix (space → zone → equipment → terminal)
4. Validate model against matrices
5. Generate validation report with discrepancies

Output: Validated mapping between spaces and EOR equipment

Before providing recommendations: Cross-reference EOR specs carefully, validate HVAC approach with OpenStudio docs

Workflow 4: LEED Baseline Generation

When: Ready to create ASHRAE 90.1 Appendix G baseline model

See leed-compliance-procedures.md for comprehensive procedures.

High-Level Steps:

1. Verify proposed model completeness (simulation runs, matches EOR)
2. Apply Appendix G transformations (envelope, lighting, HVAC)
3. Create 4 rotations (0°, 90°, 180°, 270°)
4. Run all models, calculate averaged baseline
5. Calculate percent savings
6. Verify unmet hours <300 for all models
7. Generate LEED documentation

Before baseline generation: Validate Appendix G requirements for project's ASHRAE 90.1 version and climate zone

Workflow 5: Systematic Error Resolution

When: Multiple simulation errors need methodical resolution

Key Steps:

1. Parse error file, categorize by severity and type
2. Prioritize: Severe/fatal → Warnings → Info
3. Validate fix approaches using authoritative sources (critical step)
4. Apply fixes iteratively (fix 1-3 errors, re-run, repeat)
5. Document fixes and results

Before providing fixes: For EACH error, validate solution approach using validation-sources.md

LEED Compliance

For comprehensive LEED procedures, see leed-compliance-procedures.md

Quick Reference: Prerequisites

Proposed Model Ready:

• Simulation runs successfully
• Unmet hours <300
• HVAC systems match EOR specifications
• All spaces have thermal zones
• Schedules and constructions complete

Baseline Transformation Rules (ASHRAE 90.1 Appendix G):

• Envelope: Table G3.1.5 baseline assemblies by climate zone
• Lighting: Table G3.1.6 baseline LPDs by space type
• HVAC: Table G3.1.1-1 system selection by building type, size, heating source
• Equipment efficiencies: Tables 6.8.1-X

Rotation Analysis:

• Create 4 baseline orientations (0°, 90°, 180°, 270°)
• Average baseline results
• Proposed stays as-designed (1 simulation)

Percent Savings:

• ECB = Average of 4 baseline energy costs
• Savings = (ECB - Proposed) / ECB × 100%

Before LEED work: Validate Appendix G requirements for project's specific ASHRAE 90.1 version

Quality Control Checklists

Pre-Simulation Checklist

□ All spaces assigned to building stories with correct Z-coordinates
□ All spaces have thermal zones
□ All thermal zones have HVAC equipment or ideal loads
□ All surfaces properly matched (no red in 3D view)
□ No duplicate or overlapping geometry
□ Space types assigned
□ Construction sets assigned
□ Schedules defined and applied
□ Weather file matches project location

Post-Simulation Checklist

□ Simulation completed without severe errors
□ Unmet hours <300 (for LEED)
□ Energy consumption reasonable (compare EUI to benchmarks)
□ Equipment sizing reasonable
□ Monthly energy patterns make sense
□ End use breakdown logical

EOR Compliance Checklist

□ All equipment from EOR specs in model
□ Equipment types match exactly
□ Thermal zones match EOR space assignments
□ Plant loops correct for water-based systems
□ Terminal types match (VAV vs CV, reheat vs no reheat)

Project-Specific Context

Example Recreation Center

For detailed project context, see project-example-recreation-center.md

Key Project Details:

• 92,000 sf rec center + pool + library
• LEED V4 + Colorado IDAP (10% below ASHRAE 90.1-2022)
• Engineer of Record: Clarkenersen (see 11_10_2025_ZoneEquipList.pdf)
• Pre-Thanksgiving 2025 coordination deadline

Special Considerations:

• Historical issue: Original model had 5 stories at Z=0 (required complete rebuild)
• Pool: 30' ceiling height, dehumidification system, special modeling
• WAHP systems: Water-to-air heat pumps with fluid cooler (NOT cooling tower)
• 6 different RTU/DOAS systems + central plant

Before working on this project:

• Reference EOR equipment list: 11_10_2025_ZoneEquipList.pdf
• Check HVAC rebuild plan: Example_HVAC_Rebuild_Plan.md
• Validate pool modeling approach with multiple sources
• Verify fluid cooler (not cooling tower) for WAHP systems

Usage Examples

Example 1: Model Won't Simulate

User: "My energy model won't simulate. Can you diagnose what's wrong?"

Response Pattern:

1. "I'll run a systematic diagnostic using Workflow 1 (Model Triage)"
2. [Check story organization, surfaces, zones, HVAC]
3. [Identify issues - e.g., "5 stories at Z=0, 8 intersecting surfaces"]
4. **VALIDATE**: Use WebFetch on OpenStudio 3.9 geometry documentation (PRIMARY)
5. [If needed] Search Unmet Hours for similar issues (SECONDARY - check contributor reputation)
6. Provide recommendations citing sources with version:
   "According to OpenStudio 3.9 geometry documentation, Building Story objects must represent physical floor levels, not programmatic areas..."
7. Recommend fix or rebuild based on validated decision criteria

Key: ALWAYS check OpenStudio docs FIRST, especially for geometry issues

Example 2: Verify Against EOR Specs

User: "Can you check if my model matches the mechanical engineer's specifications?"

Response Pattern:

1. "I'll use Workflow 3 (EOR Specification Mapping)"
2. Request documents: OSM file, EOR mechanical drawings/equipment schedule
3. Create equipment matrix from EOR specs
4. Export model zone assignments
5. Compare and flag discrepancies
6. **VALIDATE**: Check OpenStudio 3.9 HVAC documentation for proper modeling (PRIMARY)
7. [If needed] Search Unmet Hours for equipment-specific guidance (SECONDARY - prioritize NREL/Big Ladder answers)
8. Provide specific fix instructions for each discrepancy, citing sources:
   "Per OpenStudio 3.9 HVAC systems documentation..."

Key: Check OpenStudio HVAC docs FIRST before recommending any HVAC changes

Example 3: LEED Baseline Generation

User: "I need to create my LEED baseline model."

Response Pattern:

1. "I'll guide you through LEED baseline generation (see leed-compliance-procedures.md)"
2. Run pre-simulation checklist on proposed model
3. **VALIDATE**: Check ASHRAE 90.1 version requirements for project
4. **VALIDATE**: WebFetch current Appendix G transformation rules
5. Guide through transformations (envelope, lighting, HVAC)
6. Create 4 rotations
7. Calculate percent savings
8. Verify unmet hours
9. Generate documentation

Key: Validate Appendix G requirements for specific project version and climate zone

Example 4: Simulation Error Resolution

User: "I'm getting errors about non-planar surfaces. How do I fix this?"

Response Pattern:

1. "I'll help resolve non-planar surface errors (Pattern 2)"
2. Identify specific surfaces from error file
3. **VALIDATE**: WebFetch OpenStudio 3.9 geometry editor documentation (PRIMARY - mandatory check)
4. [If additional context needed] Search Unmet Hours: "site:unmethours.com non-planar surface openstudio"
   - Check contributor reputation (prefer NREL staff, Big Ladder Software)
   - Verify answer is recent and compatible with OpenStudio 3.x
5. Provide fix strategy citing OpenStudio docs:
   "Per OpenStudio 3.9 geometry documentation, non-planar surfaces should be deleted and recreated..."
   [If using Unmet Hours] "This approach is validated by [contributor name] on Unmet Hours..."
6. Provide step-by-step fix instructions
7. Explain prevention strategies

Key: OpenStudio docs are PRIMARY source; use Unmet Hours only for additional context and only from trusted contributors

Integration with Other Skills

This skill works in combination with:

• energy-efficiency: Post-diagnostic energy calculations and performance analysis
• writing-openstudio-model-measures: Create Ruby measures for automated fixes or transformations
• work-command-center: Project timeline management and deadline tracking
• commissioning-reports: Document model validation in MBCx reports
• n8n-automation: Automated model checking in CI/CD pipelines

Best Practices

Always Validate First (MANDATORY)

• Never provide fix recommendations without checking authoritative sources
• For geometry and HVAC: ALWAYS check OpenStudio 3.9 documentation FIRST
• Use WebFetch for OpenStudio documentation (version-specific)
• Use WebFetch for EnergyPlus 24.2 documentation (object-level details)
• Use WebSearch for Unmet Hours (secondary, with caution)
• Always cite sources with version: "According to OpenStudio 3.9 [section]..."

Unmet Hours Usage Rules

• Primary check: OpenStudio documentation
• Secondary check: Unmet Hours (only if needed for additional context)
• Evaluate contributors: Prioritize NREL staff, Big Ladder Software, high-karma users
• Check dates: Prefer recent answers compatible with OpenStudio 3.x
• Cross-validate: If Unmet Hours contradicts OpenStudio docs → Trust OpenStudio docs
• Cite carefully: "Per OpenStudio 3.9 docs... [validated by contributor name on Unmet Hours]"

Work Systematically

• Follow workflows step-by-step (don't skip steps)
• Fix errors iteratively (not all at once)
• Validate each fix before proceeding to next
• Document assumptions and decisions

Verify Version Compatibility

• Default: OpenStudio 3.9 → EnergyPlus 24.2
• Check OpenStudio version if different (Help → About in OpenStudio Application)
• Verify solutions are compatible with version in use
• Older Unmet Hours answers (OpenStudio 2.x, 1.x) may not apply
• Note version compatibility in recommendations

Use Progressive Disclosure

• Start with high-level diagnosis
• Provide detailed steps only after validation
• Reference supporting files for comprehensive details
• Keep recommendations focused and actionable

Analysis Tools

EnergyPlus Results Analyzer

Location: scripts/analyze_energyplus_results.py

Automated tool to extract, calculate, and structure key metrics from EnergyPlus simulation outputs. Designed to distill E+ results for LLM interpretation and graphing tools, separating calculation work from interpretation.

Purpose:

• Extract all metrics from EnergyPlus outputs
• Convert between Imperial and Metric units
• Generate JSON for programmatic use or Markdown for human readability
• Designed for use with future GHG and utility cost calculators

Usage:

# Imperial units, JSON output
python scripts/analyze_energyplus_results.py \
  --input-dir "path/to/run/" \
  --units imperial \
  --format json

# Metric units, Markdown summary
python scripts/analyze_energyplus_results.py \
  --input-dir "path/to/run/" \
  --units metric \
  --format markdown \
  --output summary.md

Input Sources (priority order):

1. Priority 1: eplusout.sql - SQLite database (most complete)
2. Priority 2: results.json - OpenStudio Results measure (supplemental, optional)
3. Priority 3: eplustbl.htm - HTML tables (fallback)

Metrics Extracted:

• Site & Source Energy (GJ, kWh, MBtu, kBtu)
• EUI calculations (MJ/m², kWh/m², kBtu/sf/yr)
• Building areas (m², sf)
• End uses by category (Heating, Cooling, Lighting, Equipment, etc.)
• End uses by fuel type (Electricity, Natural Gas, District, etc.)
• Percentages for all end uses
• Unmet hours (heating, cooling, occupied)
• Peak electric demand
• Utility costs (if available)

Output Formats:

• JSON: Structured data for LLMs, graphing tools, or downstream analysis
• Markdown: Human-readable summary with tables

When to Use:

• After model simulation to extract results
• When comparing model iterations
• When preparing data for LLM interpretation
• Before generating reports or visualizations
• As input to future GHG/utility cost calculators

Supporting Files

All supporting files use progressive disclosure to keep this skill concise:

• validation-sources.md: Detailed instructions for using each authoritative source
• common-error-patterns.md: Six major error patterns with symptoms, causes, and fixes
• diagnostic-workflows.md: Five detailed step-by-step diagnostic workflows
• leed-compliance-procedures.md: Comprehensive LEED Appendix G procedures
• project-example-recreation-center.md: Example project-specific context

Cost Analysis for HVAC Alternatives

NPV Analysis Email Generator

Purpose: Generate lifecycle cost analysis summaries when comparing HVAC system alternatives (baseline vs. proposed systems)

Location: scripts/npv_analysis_email_generator.py

Documentation: docs/TOOL_NPV_Email_Generator.md

When to Use:

1. After running proposed and baseline models - Compare lifecycle costs of different HVAC approaches
2. LEED Appendix G cost analysis - Show first cost premium vs. lifecycle savings
3. Value engineering decisions - Demonstrate cost impact of HVAC system changes
4. EOR specification validation - Compare specified system costs vs. alternatives

Typical Workflow:

1. Model multiple HVAC alternatives:

   • Baseline (code-minimum or existing)
   • Proposed (EOR specification)
   • Alternatives (if evaluating options)

2. Extract annual energy costs from simulation results

3. Input costs into NPV spreadsheet:

   • First costs (equipment, installation)
   • Annual energy costs (from energy model results)
   • Maintenance costs (if applicable)

4. Generate formatted summary:

   python scripts/npv_analysis_email_generator.py "path/to/NPV_Analysis.xlsx" \
     -o "path/to/Summary.xlsx" \
     -p "Project Name - HVAC Alternatives"
   

Output:

• Excel summary with color-coded comparisons
• First cost vs. lifecycle NPV for each alternative
• Highlights lowest lifecycle cost option
• Ready for stakeholder presentations

Integration with Other Skills:

• energy-efficiency skill - Use for energy savings calculations
• xlsx skill - Edit NPV spreadsheet and recalculate formulas before generating summary
• work-command-center - Track NPV summary generation as project deliverable

Example Use Cases:

• "Compare lifecycle costs: Water-source heat pump vs. GSHP vs. conventional DX"
• "Generate cost comparison for LEED review submittal"
• "Show client the 25-year NPV of HVAC system alternatives"

Quick Start

For any diagnostic task:

1. Identify task type (triage, rebuild decision, EOR validation, LEED baseline, error resolution)
2. Select appropriate workflow from diagnostic-workflows.md
3. VALIDATE all recommendations using validation-sources.md
4. Check for known patterns in common-error-patterns.md
5. Provide recommendations with source citations
6. Use quality control checklists to verify completeness

Remember: The validation protocol is not optional. Always validate before recommending fixes.

Context Awareness

This skill integrates with work-command-center session tracking:

Check Active Context:

node .claude/skills/work-command-center/tools/session-state.js status

Returns: Project name, project number, duration, and deliverables context

Log Activity Checkpoints:

node .claude/skills/work-command-center/tools/session-state.js checkpoint \
  --activity "diagnosing-energy-models: Fixed 8 geometry errors, model ready for simulation"

Signal Completion (called by WCC after skill returns):

node .claude/skills/work-command-center/tools/session-state.js skill-complete \
  --skill-name "diagnosing-energy-models" \
  --summary "Diagnosed and repaired geometry errors. Model validates successfully." \
  --outcome "success"

Benefits:

• WCC tracks time spent in this skill
• Session logs include skill work breakdown
• Context visible across skill transitions
• Deliverables auto-update from skill outcomes

Last Updated: 2025-11-20 Version: 2.1 (Added EnergyPlus Results Analyzer tool) Aligned with: OpenStudio 3.9, EnergyPlus 24.2 Primary Use Cases: Recreation center projects, LEED v4 projects, complex HVAC troubleshooting

Saving Next Steps

When diagnosing-energy-models work is complete or paused:

node .claude/skills/work-command-center/tools/add-skill-next-steps.js \
  --skill "diagnosing-energy-models" \
  --content "## Priority Tasks
1. Fix geometry errors in energy model
2. Validate HVAC system against EOR specs
3. Generate LEED Appendix G baseline model"

See: .claude/skills/work-command-center/skill-next-steps-convention.md