Skip to content

Simulation

See Running simulations for examples.

EnergyPlus simulation runner.

Public API

simulate — run a single simulation (sync) simulate_batch — run multiple simulations concurrently (sync) async_simulate — single simulation (async) async_simulate_batch — batch simulation (async)

SimJob

Bases: BaseModel

Single simulation job definition.

SimResult

Bases: BaseModel

EnergyPlus simulation result.

end_message property 

end_message: str | None

Read end file content.

err property 

err: ErrSummary | None

Parse err file summary.

ErrSummary

Bases: BaseModel

Parsed summary of an eplusout.err file.

from_file classmethod 

from_file(path: Path) -> ErrSummary

Parse an eplusout.err file into structured summary.

simulate 

simulate(
    idf: object,
    weather: Path,
    *,
    output_dir: Path | None = None,
    energyplus_bin: str = 'energyplus',
    design_day: bool = False,
    annual: bool = False,
    expand_objects: bool = True,
    readvars: bool = False,
    output_prefix: str | None = None,
    echo: bool = True,
) -> SimResult

Run a single EnergyPlus simulation (sync).

Parameters:

Name Type Description Default
idf object

IDF object or Path to IDF file.

 required
weather Path

Path to EPW weather file.

 required
output_dir Path | None

Output directory. Defaults to the IDF file's parent when idf is a Path. Required when idf is an in-memory IDF object (raises ValueError if omitted).

 None
energyplus_bin str

Path to EnergyPlus executable.

 'energyplus'
design_day bool

Run design-day-only simulation (-D).

 False
annual bool

Run annual simulation (-a).

 False
expand_objects bool

Expand HVACTemplate objects (-x).

 True
readvars bool

Run ReadVarsESO to convert ESO to CSV (-r).

 False
output_prefix str | None

Output file prefix (-p).

 None
echo bool

Print EnergyPlus output to terminal in real time.

 True

simulate_batch 

simulate_batch(
    jobs: list[SimJob],
    *,
    max_concurrent: int | None = None,
    energyplus_bin: str = 'energyplus',
    expand_objects: bool = True,
    readvars: bool = False,
    output_prefix: str | None = None,
    echo: bool = False,
) -> list[SimResult]

Run multiple EnergyPlus simulations concurrently (sync).

Parameters:

Name Type Description Default
jobs list[SimJob]

List of simulation jobs.

 required
max_concurrent int | None

Maximum concurrent EnergyPlus processes. Defaults to os.cpu_count() - 1 (minimum 1).

 None
energyplus_bin str

Path to EnergyPlus executable.

 'energyplus'
expand_objects bool

Expand HVACTemplate objects (-x).

 True
readvars bool

Run ReadVarsESO to convert ESO to CSV (-r).

 False
output_prefix str | None

Default output file prefix (-p), overridden by per-job prefix.

 None
echo bool

Print EnergyPlus output to terminal.

 False

async_simulate async 

async_simulate(
    idf: object,
    weather: Path,
    *,
    output_dir: Path | None = None,
    energyplus_bin: str = 'energyplus',
    design_day: bool = False,
    annual: bool = False,
    expand_objects: bool = True,
    readvars: bool = False,
    output_prefix: str | None = None,
    echo: bool = True,
) -> SimResult

Run a single EnergyPlus simulation (async).

Same interface as simulate() but meant to be awaited inside an existing event loop. output_dir is required when idf is an in-memory IDF object; it defaults to the file's parent only when idf is a Path.

async_simulate_batch async 

async_simulate_batch(
    jobs: list[SimJob],
    *,
    max_concurrent: int | None = None,
    energyplus_bin: str = 'energyplus',
    expand_objects: bool = True,
    readvars: bool = False,
    output_prefix: str | None = None,
    echo: bool = False,
) -> list[SimResult]

Run multiple EnergyPlus simulations concurrently (async).

Same interface as simulate_batch() but meant to be awaited inside an existing event loop.