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

# 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:

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

# Fix corrupted equipment lists + update version
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

./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

Example Project Context

Current Project: Example Recreation Center Model Deadline: 2025-11-27 (Pre-Thanksgiving) Deliverables: EUI, GHG, Utility Cost

Model Location:

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

Key Files:

Example_Model_v3_WaterLoop_RTUHP_DOAS_Pool/run/in.idf
Example_Model_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 "recreation center 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

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 "energyplus-assistant: QA/QC validation complete, found 3 warnings"

Signal Completion (called by WCC after skill returns):

node .claude/skills/work-command-center/tools/session-state.js skill-complete \
  --skill-name "energyplus-assistant" \
  --summary "Model validation: 3 warnings, 0 errors. HVAC topology verified." \
  --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

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

Saving Next Steps

When energyplus-assistant work is complete or paused:

node .claude/skills/work-command-center/tools/add-skill-next-steps.js \
  --skill "energyplus-assistant" \
  --content "## Priority Tasks
1. Complete QA/QC validation on IDF model
2. Run simulation and extract results
3. Analyze HVAC topology for ECM opportunities"

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