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

DesignBuilder Version	Package Version
< v7.2.0.028	0.2.0
>= v7.2.0.028	0.3.x
future release	0.4.0

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.

fromdb_eplusout_readerimportVariable# Specific variablev=Variable(
key="PEOPLE BLOCK1:ZONE2",
type="Zone Thermal Comfort Fanger Model PPD",
units="%"
)
# Use None to match any value for that fieldVariable(None, None, None) # returns all outputsVariable(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).

fromdb_eplusout_reader.constantsimportTS, H, D, M, A, RP

Reading SQL Files

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

fromdb_eplusout_readerimportVariable, get_resultsfromdb_eplusout_reader.constantsimportHresults=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:

fromdb_eplusout_readerimportDBEsoFile, Variablefromdb_eplusout_reader.constantsimportH, D# Parse the file onceeso=DBEsoFile.from_path(r"C:\path\to\eplusout.eso")
# Query multiple times without re-readingresults_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 exactlyresults=get_results(path, variables, frequency=D, alike=False)
# Substring match - partial matches allowedresults=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

fromdatetimeimportdatetimeresults=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)
# Metadataresults.frequency# 'monthly'results.time_series# [datetime(2013, 1, 1), datetime(2013, 2, 1), ...]# Access dataresults.variables# List of matched Variable tuplesresults.arrays# List of value arrays (one per variable)results.first_variable# First matched Variableresults.first_array# Values for first variableresults.scalar# First value of first array# Iterateforvariable, valuesinresults.items():
print(f"{variable}: {len(values)} values")

Export to CSV

# Basic exportresults.to_csv(r"C:\output.csv")
# With optionsresults.to_csv(
r"C:\output.csv",
explode_header=True, # Split Variable into separate columnsdelimiter=",", # CSV delimitertitle="My Results", # Add title rowappend=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]

fromdb_eplusout_readerimportget_results, to_parquet, read_parquetresults=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

fromdatetimeimportdatetimefromdb_eplusout_readerimportDBEsoFile, Variable, get_resultsfromdb_eplusout_reader.constantsimportH, D, M# Define variables to extractvariables= [
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]}")
# Exportsql_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.