name: energyplus-builder description: "Generate EnergyPlus building simulations from natural language descriptions or building images. Use when user asks to 'create building simulation', 'generate IDF', 'simulate X-story building', provides building floor plans, 3D models, or describes buildings like 'a 3-story office building in Shenzhen'."

EnergyPlus Building Simulation Skill

This skill automates the complete workflow from building description to EnergyPlus simulation results.

Capabilities

1. Parse natural language building descriptions (Chinese/English)
2. Analyze building images (floor plans, 3D models) for geometry extraction
3. Generate compliant YAML configuration files
4. Execute YAML-to-IDF conversion with Pydantic validation
5. Run EnergyPlus simulations
6. Detect and auto-fix common errors
7. Output clean, validated YAML files

Input Types

Natural Language Examples

• "一栋三层的办公楼，复杂度：complex，地点位于深圳"
• "A 2-story residential building in Beijing, simple layout"
• "Create a medium complexity commercial building, 5 floors, 1000 m²"

Image Types Supported

• Floor plans (2D layout drawings)
• 3D building models/renderings
• CAD exports

Parameter Extraction Rules

When parsing user input, extract the following parameters:

Complexity Levels

Simple (每层最多3个热区)

• Zones per floor: 1-3
• Layout: Single zone or linear divisions
• Windows per exterior wall: 0-1
• Default zone area: 100 m²
• Ceiling height: 3.0 m
• No interior walls between zones

Medium (每层最多8个热区和8个门窗)

• Zones per floor: 4-8
• Layout: Grid pattern (2x2, 2x3, 2x4)
• Windows per exterior wall: 1-2
• Default zone area: 50 m²
• Ceiling height: 3.2 m
• Interior walls between zones

Complex (多热区及多门窗)

• Zones per floor: 9+
• Layout: Perimeter + core pattern
• Windows per exterior wall: 2-3
• Default zone area: 30 m²
• Ceiling height: 3.5 m
• Interior walls and doors

City Location Database

Shenzhen/深圳:
  Name: Shenzhen_GD_CHN Design_Conditions
  Latitude: 22.54
  Longitude: 114.00
  Time Zone: 8.00
  Elevation: 4.00

Beijing/北京:
  Name: Beijing_CHN Design_Conditions
  Latitude: 39.92
  Longitude: 116.46
  Time Zone: 8.00
  Elevation: 55.00

Shanghai/上海:
  Name: Shanghai_CHN Design_Conditions
  Latitude: 31.17
  Longitude: 121.43
  Time Zone: 8.00
  Elevation: 4.00

Guangzhou/广州:
  Name: Guangzhou_GD_CHN Design_Conditions
  Latitude: 23.13
  Longitude: 113.32
  Time Zone: 8.00
  Elevation: 11.00

Workflow Instructions

Step 1: Parse User Input

1. Extract building parameters from natural language or image
2. Determine complexity level (simple/medium/complex)
3. Set defaults for missing parameters

Step 2: Calculate Building Geometry

Use the geometry rules from ./docs/geometry-rules.md:

1. Calculate building footprint based on total area and number of floors
2. Subdivide into zones based on complexity level
3. Generate surface vertices for each zone (floor, ceiling/roof, walls)
4. Calculate window positions for exterior walls

Step 3: Generate YAML File

Generate YAML following the structure in ./docs/yaml-schema-reference.md:

# Required sections in order:
SimulationControl:
Building:
Timestep:
Site:Location:
RunPeriod:
Material:
Construction:
GlobalGeometryRules:
Zone:
BuildingSurface:Detailed:
FenestrationSurface:Detailed:  # if windows exist
Schedule:
HVAC:
Output:VariableDictionary:
Output:Diagnostics:
Output:Table:SummaryReports:
OutputControl:Table:Style:
Output:Variable:

Save to: schemas/generated_building_YYYYMMDD_HHMMSS.yaml

Step 4: Execute Pipeline

# Run the conversion and simulation pipeline
python main.py schemas/generated_building_XXXXXX.yaml dependencies/Shenzhen.epw

Step 5: Check for Errors

1. Pydantic Validation Errors: Check console output for validation failures
2. EnergyPlus Errors: Check .err files in output/results/energyplus_runs_*/

Common error patterns and fixes are documented in ./docs/error-handling.md.

Step 6: Auto-Fix and Retry

If errors occur:

1. Parse error message to identify issue
2. Apply appropriate fix from error handling guide
3. Regenerate YAML with corrections
4. Re-run pipeline (maximum 3 retries)

Step 7: Output Results

After successful simulation:

1. Report simulation success and output location
2. Clean the final YAML file (remove comments, format consistently)
3. Present the validated YAML to user

YAML Generation Template

Use this template structure for generating YAML files:

# ==================================================================
# Simulation Control
# ==================================================================
SimulationControl:
    Do Zone Sizing Calculation: No
    Do System Sizing Calculation: No
    Do Plant Sizing Calculation: No
    Run Simulation for Sizing Periods: No
    Run Simulation for Weather File Run Periods: Yes
    Do HVAC Sizing Simulation for Sizing Periods: Yes
    Maximum Number of HVAC Sizing Simulation Passes: 1

# ==================================================================
# Building
# ==================================================================
Building:
    Name: {building_name}
    North Axis: {north_axis}
    Terrain: {terrain}
    Loads Convergence Tolerance Value: 0.04
    Temperature Convergence Tolerance Value: 0.40
    Solar Distribution: FullInteriorAndExterior
    Maximum Number of Warmup Days: 25
    Minimum Number of Warmup Days: 6

# ==================================================================
# Timestep
# ==================================================================
Timestep:
    Number of Timesteps per Hour: 4

# ==================================================================
# Site Location
# ==================================================================
Site:Location:
    Name: {location_name}
    Latitude: {latitude}
    Longitude: {longitude}
    Time Zone: {time_zone}
    Elevation: {elevation}

# ==================================================================
# Run Period
# ==================================================================
RunPeriod:
    Name: Run Period 1
    Begin Month: 1
    Begin Day of Month: 1
    Begin Year: 2040
    End Month: 12
    End Day of Month: 31
    End Year: 2040
    Day of Week for Start Day: Tuesday
    Use Weather File Holidays and Special Days: Yes
    Use Weather File Daylight Saving Period: Yes
    Apply Weekend Holiday Rule: No
    Use Weather File Rain Indicators: Yes
    Use Weather File Snow Indicators: Yes

# ==================================================================
# Materials
# ==================================================================
Material:
  - Name: Concrete_20cm
    Type: Standard
    Roughness: MediumRough
    Thickness: 0.2
    Conductivity: 1.729
    Density: 2240
    Specific_Heat: 837

  - Name: Gypsum_1.3cm
    Type: Standard
    Roughness: Smooth
    Thickness: 0.0127
    Conductivity: 0.16
    Density: 785
    Specific_Heat: 830

  - Name: Interior_Insulation
    Type: NoMass
    Roughness: MediumRough
    Thermal_Resistance: 2.5

  - Name: SimpleGlazingSystem
    Type: Glazing
    U-Factor: 5.8
    Solar_Heat_Gain_Coefficient: 0.8
    Visible_Transmittance: 0.9

# ==================================================================
# Constructions
# ==================================================================
Construction:
  - Name: Exterior_Wall_Const
    Layers:
      - Concrete_20cm
  - Name: Interior_Wall_Const
    Layers:
      - Gypsum_1.3cm
      - Gypsum_1.3cm
  - Name: Roof_Const
    Layers:
      - Concrete_20cm
  - Name: Floor_Const
    Layers:
      - Concrete_20cm
  - Name: Ceiling_Const
    Layers:
      - Concrete_20cm
  - Name: Window_Const
    Layers:
      - SimpleGlazingSystem

# ==================================================================
# Global Geometry Rules
# ==================================================================
GlobalGeometryRules:
    Starting Vertex Position: UpperLeftCorner
    Vertex Entry Direction: Counterclockwise
    Coordinate System: World

# ==================================================================
# Zones (generate based on complexity)
# ==================================================================
Zone:
  # Generate zone entries based on complexity level

# ==================================================================
# Building Surfaces (generate for each zone)
# ==================================================================
BuildingSurface:Detailed:
  # Generate surfaces: Floor, Roof/Ceiling, 4 Walls per zone

# ==================================================================
# Fenestration Surfaces (if applicable)
# ==================================================================
FenestrationSurface:Detailed:
  # Generate windows on exterior walls

# ==================================================================
# Schedules
# ==================================================================
Schedule:
  ScheduleTypeLimits:
    - Name: On/Off
      Lower Limit Value: 0
      Upper Limit Value: 1
      Numeric Type: DISCRETE
      Unit Type: Dimensionless
    - Name: Temperature
      Numeric Type: CONTINUOUS
      Unit Type: Temperature
  Schedule:Compact:
    - Name: Always On
      Schedule Type Limits Name: On/Off
      Data:
        - Through: "12/31"
          Days:
          - For: "AllDays"
            Times:
            - Until:
                Time: "24:00"
                Value: 1
    - Name: Heating_Setpoint_Schedule
      Schedule Type Limits Name: Temperature
      Data:
        - Through: "12/31"
          Days:
          - For: "AllDays"
            Times:
            - Until:
                Time: "24:00"
                Value: 20
    - Name: Cooling_Setpoint_Schedule
      Schedule Type Limits Name: Temperature
      Data:
        - Through: "12/31"
          Days:
          - For: "AllDays"
            Times:
            - Until:
                Time: "24:00"
                Value: 26

# ==================================================================
# HVAC
# ==================================================================
HVAC:
  HVACTemplate:Thermostat:
    - Name: Ideal Loads Thermostat
      Heating Setpoint Schedule Name: Heating_Setpoint_Schedule
      Cooling Setpoint Schedule Name: Cooling_Setpoint_Schedule
  HVACTemplate:Zone:IdealLoadsAirSystem:
    # One entry per zone
    - Zone Name: {zone_name}
      Template Thermostat Name: Ideal Loads Thermostat
      System Availability Schedule Name: Always On

# ==================================================================
# Output Settings
# ==================================================================
Output:VariableDictionary:
    Key Field: regular
Output:Diagnostics:
    Key 1: DisplayExtraWarnings
Output:Table:SummaryReports:
    Report 1 Name: AllSummary
OutputControl:Table:Style:
    Column Separator: HTML
Output:Variable:
  - Key Value: "*"
    Variable Name: Zone Mean Air Temperature
    Reporting Frequency: Hourly
  - Key Value: "*"
    Variable Name: Surface Inside Face Temperature
    Reporting Frequency: Hourly

Important Validation Rules

Surface Vertices

• Each surface must have exactly 4 vertices (rectangular surfaces)
• Vertices must be specified counterclockwise when viewed from outside
• Minimum distance between vertices: 1e-10
• All surfaces in a zone must form a closed volume

Interior Walls

• Interior walls connecting two zones must have paired surfaces
• Use Outside Boundary Condition: Surface
• Specify Outside Boundary Condition Object with paired surface name

Boundary Conditions

Reference Files

For detailed specifications, refer to:

• docs/yaml-schema-reference.md - Complete field reference
• docs/complexity-presets.md - Complexity level configurations
• docs/geometry-rules.md - Vertex calculation formulas
• docs/error-handling.md - Error patterns and fixes
• examples/ - Working YAML examples for each complexity level