Skip to content

Simulation Overview

The simulation module provides subprocess-based EnergyPlus execution with structured result parsing, batch processing, and content-addressed caching.

Python only, permanently

Running a locally installed EnergyPlus and reading its results belongs to Python alone. JavaScript is not waiting on a port and will not gain a counterpart: this is a permanent boundary, so no issue tracks it, and moving the capability out of that state takes a constitutional amendment rather than a ledger edit.

Requires an EnergyPlus installation on the machine and a subprocess to drive it, then reads the eplusout files that run leaves on disk. Neither the installation nor the subprocess is available in a browser, which is the runtime the JavaScript library targets. JavaScript reaches EnergyPlus by the other mechanism instead: see browser-simulation, which is not a workaround for this entry but a different capability.

The full entry, including the vocabulary this capability owns, is on the capability parity page.

Quick Start

from idfkit import load_idf
from idfkit.simulation import simulate

# Load a model and run a simulation
model = load_idf("building.idf")
result = simulate(model, "weather.epw", design_day=True)

# Check results
print(f"Success: {result.success}")
print(f"Runtime: {result.runtime_seconds:.1f}s")

# Query time-series data
ts = result.sql.get_timeseries(
    variable_name="Zone Mean Air Temperature",
    key_value="THERMAL ZONE 1",
)
print(f"Max temp: {max(ts.values):.1f}°C")

Requirements

  • EnergyPlus 8.9+ installed on your system
  • idfkit auto-discovers EnergyPlus installations

Check your installation:

from idfkit.simulation import find_energyplus

config = find_energyplus()
print(f"Found EnergyPlus {config.version[0]}.{config.version[1]}")

Module Components

Component Description
simulate() Run a single simulation
SimulationResult Access output files and parsed data
SQLResult Query time-series and tabular data
simulate_batch() Run multiple simulations in parallel
async_simulate() Non-blocking single simulation
async_simulate_batch() Non-blocking parallel simulations
async_simulate_batch_stream() Streaming progress via async generator
SimulationProgress Real-time progress tracking via callbacks
SimulationCache Content-addressed result caching
OutputVariableIndex Discover available output variables
ErrorReport Parse error and warning messages
How to plot simulation results Visualize results with matplotlib/plotly

Key Features

Automatic SQLite Output

The module automatically injects Output:SQLite into your model, ensuring reliable access to all simulation data through a single queryable file.

Lazy Loading

Output files are only parsed when accessed, keeping memory usage low:

result = simulate(model, weather)  # Just runs EnergyPlus
result.errors  # Parses ERR file on first access
result.sql  # Opens SQLite database on first access

Model Safety

Your original model is never mutated — simulations work on a copy:

result = simulate(model, weather)
assert "Output:SQLite" not in model  # Original unchanged

Parallel Execution

Run parametric studies efficiently with batch processing:

from idfkit.simulation import simulate_batch, SimulationJob

jobs = [SimulationJob(model=variant, weather="weather.epw", label=f"case-{i}") for i, variant in enumerate(variants)]
batch = simulate_batch(jobs, max_workers=4)

Async Execution

For async applications, non-blocking variants are available:

from idfkit.simulation import async_simulate, async_simulate_batch_stream

# Single simulation
result = await async_simulate(model, "weather.epw")

# Streaming progress
async for event in async_simulate_batch_stream(jobs, max_concurrent=4):
    print(f"[{event.completed}/{event.total}] {event.label}")

Installation

The simulation module requires no extra dependencies for basic operation.

For optional features:

# DataFrame conversion
pip install idfkit[dataframes]

# Plotting
pip install idfkit[plot]      # matplotlib
pip install idfkit[plotly]    # plotly

# Cloud storage
pip install idfkit[s3]

Next Steps