db-eplusout-reader

A tool to fetch results from EnergyPlus output files (.sql and .eso formats).

Features

• Read results from both .sql (SQLite) and .eso (text) EnergyPlus output files
• Filter variables by key, type, and units
• Support for exact and substring (alike) matching
• Filter results by date range
• Export results to CSV (and optionally Parquet via the parquet extra)
• Zero runtime dependencies (the parquet extra adds pyarrow)

DesignBuilder Compatibility

Installation

From PyPI:

pip install db-eplusout-reader   # or: uv add db-eplusout-reader

DesignBuilder: to update the bundled copy, install into its Python directory:

pip install db-eplusout-reader --target "C:\Program Files\DesignBuilder\Python\Lib"

Usage

Basic Concepts

Variable: A named tuple (key, type, units) that defines which outputs to extract.

from db_eplusout_reader import Variable

# Specific variable
v = Variable(
    key="PEOPLE BLOCK1:ZONE2",
    type="Zone Thermal Comfort Fanger Model PPD",
    units="%"
)

# Use None to match any value for that field
Variable(None, None, None)  # returns all outputs
Variable(None, None, "J")   # returns all outputs with units "J"
Variable(None, "Temperature", None)  # returns all temperature outputs

Frequency: Output interval - one of TS (timestep), H (hourly), D (daily), M (monthly), A (annual), or RP (runperiod).

from db_eplusout_reader.constants import TS, H, D, M, A, RP

Reading SQL Files

For .sql files, use get_results() directly - SQLite handles caching efficiently:

from db_eplusout_reader import Variable, get_results
from db_eplusout_reader.constants import H

results = get_results(
    r"C:\path\to\eplusout.sql",
    variables=[Variable(None, None, "C")],
    frequency=H
)

Reading ESO Files

For .eso files, parse once and query multiple times to avoid re-reading:

from db_eplusout_reader import DBEsoFile, Variable
from db_eplusout_reader.constants import H, D

# Parse the file once
eso = DBEsoFile.from_path(r"C:\path\to\eplusout.eso")

# Query multiple times without re-reading
results_temp = eso.get_results([Variable(None, None, "C")], H)
results_pressure = eso.get_results([Variable(None, None, "Pa")], H)
results_daily = eso.get_results([Variable(None, None, None)], D)

You can also pass the DBEsoFile object to get_results():

results = get_results(eso, variables=[Variable(None, None, "C")], frequency=H)

Filtering Options

Exact vs Substring Matching

# Exact match (default) - key must match exactly
results = get_results(path, variables, frequency=D, alike=False)

# Substring match - partial matches allowed
results = get_results(path, variables, frequency=D, alike=True)
# Variable("BLOCK", None, None) will match "PEOPLE BLOCK1:ZONE2"

Strict Mode

# By default, requested variables that aren't present are silently skipped.
# Pass strict=True to raise VariableNotFound instead.
results = get_results(path, variables, frequency=D, strict=True)

Date Range Filtering

from datetime import datetime

results = get_results(
    path,
    variables=variables,
    frequency=D,
    start_date=datetime(2002, 5, 1, 0),
    end_date=datetime(2002, 5, 31, 23, 59)
)

Working with Results

get_results() returns a ResultsDictionary with useful properties:

results = get_results(path, variables, frequency=M)

# Metadata
results.frequency      # 'monthly'
results.time_series    # [datetime(2013, 1, 1), datetime(2013, 2, 1), ...]

# Access data
results.variables      # List of matched Variable tuples
results.arrays         # List of value arrays (one per variable)
results.first_variable # First matched Variable
results.first_array    # Values for first variable
results.scalar         # First value of first array

# Iterate
for variable, values in results.items():
    print(f"{variable}: {len(values)} values")

Export to CSV

# Basic export
results.to_csv(r"C:\output.csv")

# With options
results.to_csv(
    r"C:\output.csv",
    explode_header=True,  # Split Variable into separate columns
    delimiter=",",        # CSV delimiter
    title="My Results",   # Add title row
    append=True           # Append to existing file
)

Parquet (optional)

Parquet is handy for object-storage workflows. It's an optional extension — install the extra to enable it:

pip install db-eplusout-reader[parquet]

from db_eplusout_reader import get_results, to_parquet, read_parquet

results = get_results(path, variables, frequency=M)

# Write to Parquet (extra kwargs forwarded to pyarrow, e.g. compression)
to_parquet(results, r"C:\output.parquet", compression="snappy")

# Read back into a ResultsDictionary (frequency, variables and time series preserved)
results = read_parquet(r"C:\output.parquet")

Complete Example

from datetime import datetime
from db_eplusout_reader import DBEsoFile, Variable, get_results
from db_eplusout_reader.constants import H, D, M

# Define variables to extract
variables = [
    Variable(None, "Electricity:Facility", "J"),
    Variable("PEOPLE BLOCK1:ZONE1", "Zone Thermal Comfort Fanger Model PMV", ""),
]

# === SQL File ===
sql_results = get_results(
    r"C:\path\to\eplusout.sql",
    variables=variables,
    frequency=M,
    alike=False
)

# === ESO File (parse once, query many) ===
eso = DBEsoFile.from_path(r"C:\path\to\eplusout.eso")

eso_results_monthly = eso.get_results(variables, M)
eso_results_hourly = eso.get_results(variables, H)
eso_results_filtered = eso.get_results(
    variables,
    H,
    start_date=datetime(2019, 1, 1),
    end_date=datetime(2019, 1, 31)
)

# === Work with results ===
print(f"Found {len(sql_results)} variables")
print(f"Time steps: {len(sql_results.time_series)}")
print(f"First variable: {sql_results.first_variable}")
print(f"First 5 values: {sql_results.first_array[:5]}")

# Export
sql_results.to_csv(r"C:\output.csv", explode_header=True)

Development

Setup

This project uses uv for dependency management and ruff for linting/formatting.

# Install dependencies
uv sync --group dev

# Run tests
uv run pytest tests -v

# Run linting
uv run ruff check .
uv run ruff format .

# Run pre-commit hooks
uv run pre-commit run --all-files

Pre-commit Hooks

Install pre-commit hooks for automatic code quality checks:

uv run pre-commit install

License

MIT License - see LICENSE for details.