Energyplus Assistant

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

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

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

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