| 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
- Pre-Simulation QA/QC - Fast validation using direct parsing (< 5 seconds)
- IDF Repair - Automated fixing of corrupt objects, field shifts, version mismatches
- HVAC System Analysis - Topology discovery and visualization
- ECM Testing - Parametric energy conservation measure evaluation
- Environment-Aware - Adapts to Windows/macOS, Docker available/unavailable
Quick Start (Always Start Here)
Step 1: Environment Check
docker ps > /dev/null 2>&1 && echo "✓ Docker available" || echo "✗ Docker unavailable"
python -c "import eppy; print('✓ eppy available')" 2>/dev/null || echo "⚠ Need: pip install eppy"
test -f "$IDF_PATH" && echo "✓ File found" || echo "✗ File not found: $IDF_PATH"
Step 2: Choose Method Based on Task
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):
pip install eppy
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:
- MCP Tools (if Docker available) - Most comprehensive
- Text pattern matching - Quick checks without Docker
- 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
python ~/.claude/skills/energyplus-assistant/scripts/fix-equipment-lists.py input.idf output.idf
What it does:
-
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
-
Automatically fixes:
- Removes ALL corrupted equipment lists (no duplicates)
- Reconstructs with correct field structure
- Sets proper cooling/heating sequences (1, 2, 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
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.idfSECC_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
