energyplus-assistant

name	energyplus-assistant
description	Use this skill when analyzing EnergyPlus IDF building energy models, including QA/QC validation, HVAC topology analysis, ECM testing, or running simulations. Supports fast validation without Docker (direct parsing) and comprehensive analysis with MCP tools when needed. Handles Windows path formats, environment detection, and intelligent method selection. (project)

EnergyPlus Assistant

Specialized assistant for EnergyPlus building energy modeling workflows with intelligent method selection based on environment and task requirements.

Core Capabilities

1. Pre-Simulation QA/QC - Fast validation using direct parsing (< 5 seconds)
2. IDF Repair - Automated fixing of corrupt objects, field shifts, version mismatches
3. HVAC System Analysis - Topology discovery and visualization
4. ECM Testing - Parametric energy conservation measure evaluation
5. Environment-Aware - Adapts to Windows/macOS, Docker available/unavailable

---

Quick Start (Always Start Here)

Step 1: Environment Check

# Check Docker availability
docker ps > /dev/null 2>&1 && echo "✓ Docker available" || echo "✗ Docker unavailable"

# Check Python/eppy
python -c "import eppy; print('✓ eppy available')" 2>/dev/null || echo "⚠ Need: pip install eppy"

# Verify IDF file exists
test -f "$IDF_PATH" && echo "✓ File found" || echo "✗ File not found: $IDF_PATH"

Step 2: Choose Method Based on Task

Your Task	Best Method	Time	Details
QA/QC validation	Direct parsing	< 5 sec	./direct-parsing-methods.md
Object counts	Direct parsing	< 5 sec	./direct-parsing-methods.md
Fix corrupt objects	fix-equipment-lists.py	< 5 sec	See "IDF Repair" section below
Version mismatch	fix-equipment-lists.py	< 5 sec	Auto-updates IDF version
HVAC topology	MCP (if Docker available)	30+ sec	./mcp-server-usage.md
Simulations	EnergyPlus CLI	Minutes	Native EnergyPlus installation
ECM testing	MCP or scripts	Varies	./ecm-testing-workflows.md

Key Decision: For QA/QC (most common), use direct parsing—no Docker required, 10x faster.

---

Priority Workflows

1. Pre-Simulation QA/QC (Most Common)

Fast Method - Direct Parsing (< 5 seconds):

# Install once
pip install eppy

# Run analysis
python ~/.claude/skills/energyplus-assistant/scripts/qaqc-direct.py "$IDF_PATH"

What it checks:

• Building, zones, surfaces, fenestration
• Constructions and materials
• HVAC systems (air loops, plant loops, zone equipment)
• Internal loads (people, lights, equipment)
• Simulation settings (RunPeriod, SimulationControl)
• Output variables and meters

Output:

• Object count summary
• Validation status (PASS/FAIL)
• Critical errors and warnings
• Recommendations for next steps

When Docker/MCP needed instead:

• Detailed HVAC connectivity validation
• Automated output variable discovery
• Simulation test runs
• See ./mcp-server-usage.md for MCP workflows

Complete documentation: ./direct-parsing-methods.md

---

2. HVAC Topology Analysis

When to use:

• Understanding existing HVAC before modifications
• Troubleshooting equipment connections
• Visualizing system architecture
• Validating loop configurations

Methods available:

1. MCP Tools (if Docker available) - Most comprehensive
2. Text pattern matching - Quick checks without Docker
3. IDF Editor - Visual inspection

Full documentation: ./mcp-server-usage.md

---

3. IDF Repair and Fixing Corrupt Objects

When to use:

• Fatal errors from corrupt ZoneHVAC:EquipmentList objects
• Field shifting issues (data in wrong field positions)
• IDF version mismatches between file and EnergyPlus installation
• Duplicate object errors preventing simulation

fix-equipment-lists.py - Automated repair tool

# Fix corrupted equipment lists + update version
python ~/.claude/skills/energyplus-assistant/scripts/fix-equipment-lists.py input.idf output.idf

What it does:

1. Detects corruption patterns:

   • Blank object types with present names (field shift)
   • Equipment names in numeric sequence fields
   • Non-numeric values in cooling/heating sequence fields

2. Automatically fixes:

   • Removes ALL corrupted equipment lists (no duplicates)
   • Reconstructs with correct field structure
   • Sets proper cooling/heating sequences (1, 2, 3...)

3. Updates IDF version:

   • Detects current version (e.g., 24.2)
   • Updates to match installed EnergyPlus (e.g., 25.1)
   • No separate transition tool needed

Output:

• Analysis report of corrupted vs clean objects
• Fixed IDF file ready for simulation
• Summary of changes made

Philosophy: "Let tools handle syntax, let humans handle logic"

• eppy ensures syntactically correct IDF format
• You specify the logic (what fields should contain)
• Tool guarantees proper file structure

Example error this fixes:

** Severe ** processZoneEquipmentInput: ZoneHVAC:EquipmentList = "THERMAL ZONE: CARDIO 1 EQUIPMENT LIST".
**   ~~~   ** invalid zone_equipment_cooling_sequence=[2].
**   ~~~   ** equipment sequence must be > 0 and <= number of equipments in the list.
**   ~~~   ** only 1 in the list.
**  Fatal  ** GetZoneEquipmentData: Errors found in getting Zone Equipment input.

Related scripts:

• validate-idf-fields.py (coming soon) - Pre-flight field validation
• add-outputs.py (coming soon) - Automated output variable injection

---

4. ECM Testing

When to use:

• Testing lighting upgrades
• Evaluating plug load reductions
• Infiltration reduction strategies
• Occupancy schedule changes

Full documentation: ./ecm-testing-workflows.md

---

Environment-Specific Guidance

Windows Users

Docker path formats, console encoding, Git Bash considerations: See ./windows-setup.md

Key points:

• Use forward slashes in Docker mounts: C:/Users/...
• Git Bash: Double slashes for workdir: //workspace//...
• PowerShell: Single slashes work fine
• Set UTF-8 encoding: $env:PYTHONIOENCODING = "utf-8"

macOS/Linux Users

Generally straightforward:

• Docker paths use native format
• UTF-8 typically default
• Bash commands work as documented

---

Supporting Resources

Scripts

Located in ./scripts/:

Completed:

• qaqc-direct.py - Fast Python-based QA/QC (no Docker, < 5 sec)
• fix-equipment-lists.py - Repair corrupt ZoneHVAC:EquipmentList + version update
• validate-idf-structure.py - Comprehensive field validation (< 10 sec)

In Development (see DEVELOPMENT_PLAN.md):

• add-standard-outputs.py - Automated output variable injection (Phase 1)
• extract-results.py - Parse results for deliverables (Phase 1)
• fix-node-connections.py - Repair HVAC node connections (Phase 2)
• fix-schedules.py - Repair schedule references (Phase 2)
• add-ideal-loads.py - Replace HVAC with ideal loads (Phase 3)
• apply-ecm-lighting.py - LPD reduction ECM (Phase 4)
• apply-ecm-envelope.py - Insulation/window ECM (Phase 4)
• compare-models.py - Diff two IDF files (Phase 5)

Full Development Roadmap: DEVELOPMENT_PLAN.md - Complete specifications for 17+ scripts

Documentation

• ./DEVELOPMENT_PLAN.md - Complete toolkit development roadmap (17+ scripts)
• ./scripts/README.md - Script usage guide and documentation
• ./direct-parsing-methods.md - Python/Node.js QA/QC without Docker
• ./windows-setup.md - Windows-specific setup and troubleshooting
• ./mcp-server-usage.md - Docker/MCP tools for complex analysis
• ./ecm-testing-workflows.md - ECM parametric studies
• ./SKILL_OPTIMIZATION_ANALYSIS.md - Lessons learned and optimization rationale

---

Decision Tree

User Request: Analyze EnergyPlus model
    ↓
What's the primary need?
    ↓
├─ QA/QC Validation (most common)
│   ↓
│   Is Docker available?
│   ├─ YES → Still use direct parsing (faster)
│   └─ NO  → Use direct parsing (only option)
│   ↓
│   python ./scripts/qaqc-direct.py model.idf
│
├─ IDF Repair (corrupt objects)
│   ↓
│   What type of error?
│   ├─ ZoneHVAC:EquipmentList errors
│   │   └─ python ./scripts/fix-equipment-lists.py input.idf output.idf
│   ├─ Version mismatch
│   │   └─ python ./scripts/fix-equipment-lists.py input.idf output.idf (auto-updates version)
│   └─ Field validation
│       └─ python ./scripts/validate-idf-fields.py model.idf (coming soon)
│
├─ HVAC Topology Analysis
│   ↓
│   Is Docker available?
│   ├─ YES → Use MCP tools (detailed analysis)
│   └─ NO  → Use text pattern matching (basic)
│   ↓
│   See: ./mcp-server-usage.md
│
├─ Run Simulation
│   ↓
│   Is EnergyPlus installed locally?
│   ├─ YES → Use energyplus CLI (fastest)
│   └─ NO  → Use MCP if Docker available
│   ↓
│   energyplus -w weather.epw model.idf
│
└─ ECM Testing
    ↓
    See: ./ecm-testing-workflows.md

---

SECC Project Context

Current Project: Fort Collins SECC v3 Model Deadline: 2025-11-27 (Pre-Thanksgiving) Deliverables: EUI, GHG, Utility Cost

Model Location:

Local: C:\Users\mcoalson\Documents\WorkPath\User-Files\work-tracking\secc-fort-collins\energy-model\
Container: /workspace/models/ (when using Docker)

Key Files:

• SECC_WSHP_ProposedModel_v3_WaterLoop_RTUHP_DOAS_Pool/run/in.idf
• SECC_WSHP_ProposedModel_v3_WaterLoop_RTUHP_DOAS_Pool/run/in_cleaned.idf ✓ QA/QC passed

Recent Work:

• ✓ QA/QC completed on in_cleaned.idf (2025-11-24)
• ✓ Model validated: 24 zones, 295 surfaces, 58 HVAC equipment
• ✓ Status: Ready for simulation

---

Troubleshooting

"Docker not available"

→ Use direct parsing methods (faster anyway for QA/QC)

"MCP startup slow (30+ seconds)"

→ Use direct parsing for QA/QC, reserve MCP for complex HVAC analysis

"Unicode/encoding errors on Windows"

→ See ./windows-setup.md for console encoding setup

"Path format errors in Docker"

→ See ./windows-setup.md for Windows path guidance

"eppy not installed"

pip install eppy

---

Performance Expectations

Task	Direct Parsing	MCP Tools	Native EnergyPlus
QA/QC	< 5 sec	30+ sec startup	N/A
Object counts	< 5 sec	30+ sec startup	N/A
HVAC topology	Basic (< 5 sec)	Detailed (30+ sec)	N/A
1-day simulation	N/A	Minutes	Seconds to minutes
Annual simulation	N/A	Hours	Hours

Recommendation: Start with fast methods, escalate to slower methods only when needed.

---

Integration with Work Command Center

This skill can be invoked from work-command-center when:

• User mentions "SECC energy model"
• User requests "energy model QA/QC"
• User asks to "validate EnergyPlus model"
• User needs "HVAC topology analysis"
• User wants to "test ECM scenarios"

Communication Style:

• Concise and technical (Matt is an expert)
• Focus on actionable insights
• Flag errors/warnings immediately
• Provide numerical results with units
• Suggest next steps

---

Version History

• v1.0 (2025-11-23): Initial release - MCP-focused
• v2.0 (2025-11-24): Optimized with direct parsing, environment detection, Windows support

Last Updated: 2025-11-24 Status: Active - Replaces diagnosing-energy-models skill