Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
41 commits
Select commit Hold shift + click to select a range
249936d
docs: draft design for replacing archetypal/eppy with idfkit
claude Nov 12, 2026
9644959
docs: note sbem-ui is unaffected by the idfkit migration
claude Nov 12, 2026
760df2f
docs: record zone-name and tolerance decisions in idfkit design
claude Nov 12, 2026
1581763
docs: implementation plan for idfkit migration
claude Nov 12, 2026
b4f9f6a
test: capture archetypal regression baseline for idfkit migration
claude Nov 12, 2026
fde461a
feat: resolve EnergyPlus version through idfkit
claude Nov 12, 2026
36d860a
fix: bound default EnergyPlus version to supported majors
claude Nov 12, 2026
7e9968d
feat: read simulation results through idfkit SQLResult
claude Nov 12, 2026
1c5017a
feat: idfkit document loading and value schedules
claude Nov 12, 2026
c47fca1
fix: match archetypal week/year schedule structure exactly
claude Nov 12, 2026
ba7bff3
refactor: port legacy object writers to idfkit
claude Nov 12, 2026
44c204c
fix: dedupe shared objects and create Fraction type limits in legacy …
claude Nov 12, 2026
fc68685
refactor: port sbem components to idfkit
claude Nov 13, 2026
0b2fafd
refactor: single repeat-safe schedule writer for constant schedules
claude Nov 13, 2026
0e42257
refactor: build shoebox geometry with idfkit, keep zone names
claude Nov 13, 2026
b3513fa
fix: geomeppy default constructions and committed surface parity fixture
claude Nov 13, 2026
9911868
refactor: build, simulate and post-process sbem models with idfkit
claude Nov 13, 2026
85f5d6f
refactor: port climate_studio to idfkit, drop unused ddy_interface_bayes
claude Nov 13, 2026
7f91273
chore!: drop archetypal, release 2.0.0
claude Nov 13, 2026
eabdb27
fix: green pre-commit and version-aware tests; schedules past 99 days
claude Nov 13, 2026
04c1429
fix: release SQLite results before temp run dirs are deleted
claude Nov 13, 2026
46aea6b
chore: pin idfkit to 1.2.x; state regression tolerances in CHANGELOG
claude Nov 13, 2026
6e062db
Build the base document programmatically with idfkit
claude Nov 13, 2026
1d3a24c
Fail loudly on unknown fields when building the base document
claude Nov 13, 2026
24c99e6
docs: clarify minimal_document comment
claude Nov 13, 2026
c684ee1
test: seed realistic 21/24 degC thermostat setpoint schedules
claude Nov 13, 2026
52cefcb
test: recapture archetypal regression baseline on the 21/24 degC seed
claude Nov 13, 2026
b7042fd
refactor: copy objects with idfkit's copyidfobject
claude Nov 13, 2026
dc7f9db
fix: save the demo notebook's model with idfkit.save_idf
claude Nov 13, 2026
e9ab005
feat: add add_or_replace and field_name document writers
claude Nov 13, 2026
3805b15
refactor: write sbem, geometry and helper objects with idfkit directly
claude Nov 13, 2026
eb5c5f4
refactor: write legacy and climate studio models with idfkit directly
claude Nov 13, 2026
5241569
refactor!: remove the EnergyPlus object mirror classes
claude Nov 13, 2026
265eff2
docs: note the removed EnergyPlus mirror classes in the changelog
claude Nov 13, 2026
616f92f
docs: give field_name an example of a field EnergyPlus renamed
claude Nov 13, 2026
7e370e6
refactor: name IDFDocument variables doc instead of idf
claude Nov 13, 2026
4a881fc
chore: remove the migration plan and design docs from the PR
claude Nov 13, 2026
f006988
docs: link idfkit's GitHub repo from the README and docs index
claude Nov 13, 2026
667440e
feat: type documents per EnergyPlus release with idfkit 1.3.0rc1
claude Nov 14, 2026
e151b87
fix: address code review findings on the idfkit migration
claude Nov 14, 2026
0c758a4
chore: leave the version and release number to the maintainers
claude Nov 14, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,18 @@ repos:
# exclude: ^.devcontainer/devcontainer.json
# args: [--autofix, --no-sort-keys]
- id: end-of-file-fixer
# Regression fixtures and design docs are kept byte-for-byte as written.
exclude: ^(tests/data/|docs/superpowers/)
- id: trailing-whitespace
# Regression fixtures and design docs are kept byte-for-byte as written.
exclude: ^(tests/data/|docs/superpowers/)

- repo: https://github.com/RobertCraigie/pyright-python
rev: v1.1.382
hooks:
- id: pyright
# The capture scripts import archetypal, which is not a dependency.
exclude: ^scripts/capture_.*\.py$

- repo: https://github.com/astral-sh/ruff-pre-commit
rev: "v0.11.5"
Expand All @@ -26,7 +32,21 @@ repos:
args: [--exit-non-zero-on-fix, --show-fixes]
- id: ruff-format

- repo: local
hooks:
- id: idfkit-check
name: idfkit check (EnergyPlus 22.2 to 25.2)
# Lints object types and choice values in string-keyed idfkit calls,
# such as doc.add("Lights", ...), against every supported release.
# Keep the targets in step with epinterface.document.SUPPORTED_DOCUMENT_TYPES.
entry: uv run idfkit check --targets 22.2,23.1,23.2,24.1,24.2,25.1,25.2
language: system
types: [python]
files: ^epinterface/

- repo: https://github.com/pre-commit/mirrors-prettier
rev: "v3.0.3"
hooks:
- id: prettier
# Regression fixtures and design docs are kept byte-for-byte as written.
exclude: ^(tests/data/|docs/superpowers/)
142 changes: 142 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
# Changelog

All notable changes to this project are documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Changed

- **Breaking:** [idfkit](https://pypi.org/project/idfkit/) replaces archetypal, eppy and geomeppy. Models are built,
edited, simulated and read through idfkit's own API. archetypal, eppy and
geomeppy are no longer dependencies.
- **Breaking:** the model is now `ModelRunResults.doc`, an idfkit
`IDFDocument`, and `ModelRunResults.sql` is now idfkit's `SQLResult` (it was
archetypal's `Sql`). `ModelRunResults.idf` still returns the document but
warns that it is deprecated. Every parameter that takes an `IDFDocument` is
named `doc`.
- **Breaking:** `Model.build()` returns an `IDFDocument`; `Model.simulate()`
returns `(IDFDocument, SQLResult)`.
- **Breaking:** `post_geometry_callback` is now
`Callable[[IDFDocument], IDFDocument]`.
- **Breaking:** every `add_to_idf` and similar method on the sbem
components, the `epinterface/interface.py` classes, `epinterface/builder.py`,
`epinterface/climate_studio/` and `epinterface/geometry.py` now takes an
`IDFDocument` instead of an archetypal `IDF`.
- **Breaking:** `EnergyPlusSettings.archetypal_energyplus_version` is replaced by
`EnergyPlusSettings.version_tuple`.
- The default EnergyPlus version is the newest installed supported major
version. Set `EPINTERFACE_ENERGYPLUS_VERSION` to pin one.
- The base model is now built programmatically with idfkit for any supported
EnergyPlus version (`minimal_document`). The packaged `Minimal.idf`, its
`DefaultMinimalIDFPath`, and the IDFVersionUpdater transition step are gone,
so the first build in a process no longer spends about 37 s migrating the
file, and the EnergyPlus transition binaries are no longer needed.
- Simulation outputs match the archetypal-based results on EnergyPlus
25.2.0 within a relative tolerance of 1e-3 and an absolute tolerance of 1e-6;
per-zone geometry matches within a relative tolerance of 1e-9 and an absolute
tolerance of 0.01. The committed fixtures in `tests/data/regression` are the
evidence.
- idfkit is pinned to `>=1.3.0rc1,<1.4`.
- Documents are typed for the EnergyPlus releases epinterface supports, 22.2
to 25.2, instead of idfkit's latest release (26.2), which epinterface never
builds. `epinterface.document.EPDocument`, the union of idfkit's
`IDFDocumentV22_2` to `IDFDocumentV25_2`, annotates every parameter and return
value that takes a document, so pyright offers only the object types and
fields that all of those releases have. `as_supported(doc)` types a document
as one, checking its version at run time, and `load_document(path, version)`
loads a file as one. A pre-commit hook also runs `idfkit check` on those
releases, which lints the object types and choice values in string-keyed
calls such as `doc.add("Lights", ...)`.
- **Breaking:** `minimal_document` raises `TypeError` for an EnergyPlus version
outside 22.2 to 25.2, before building anything. Such a version used to fail
later: 22.1 when an infiltration or ventilation object was written (22.1
names their zone and flow fields differently), other majors when the results
were read.

### Added

- `ModelRunResults.hourly_timeseries(names)` returns the hourly variables as a
DataFrame, with the same index and column levels as archetypal's
`Sql.timeseries_by_name(names, reporting_frequency="Hourly")`.
- Regression tests that compare built models, geometry and simulation results
with fixtures captured under archetypal.
- The test seed's thermostat setpoints are now 21 degC heating and 24 degC
cooling `Temperature` schedules (they were constant 0.5 fraction schedules,
so the regression models never really heated or cooled). The regression
baseline was recaptured from the archetypal-era code on that seed, and the
`neighbors_overheating` regression case now uses overheating thresholds the
conditioned zones cross (heat 23 and 26 degC, cold 22.5 degC).

### Removed

- **Breaking:** `ddy_interface_bayes` (unused).
- **Breaking:** the `epinterface.interface` classes that mirrored one
EnergyPlus object each: `ScheduleTypeLimits`, `SimulationControl`,
`RunPeriod`, `Timestep`, `SizingParameters`, `SiteGroundTemperature`,
`InternalMass`, `Material`, `SimpleGlazingMaterial`, `AirGapMaterial`,
`NoMassMaterial`, `Construction`, `HVACTemplateThermostat`,
`HVACTemplateZoneIdealLoadsAirSystem`, `WaterUseEquipment`,
`ElectricEquipment`, `Lights`, `ZoneVentilationWindAndStackOpenArea`,
`ZoneInfiltrationDesignFlowRate`, `People`, `ScheduleDayHourly`,
`ScheduleWeekDaily`, `ScheduleYear`, `ZoneList` and their base `BaseObj`
(with its `extract()` readers). Write objects with idfkit's `doc.add` and
idfkit's snake_case field names instead, or with
`epinterface.document.add_or_replace`, which reuses an identical object of
the same name and replaces a different one. `watts_per_area` keys a
`Lights` or `ElectricEquipment` design level by the field name of the
document's EnergyPlus version, `add_construction` writes a
layered construction, and `add_site_ground_temperature`, `add_zone_list`
and `BaseMaterial.add_layer_to_idf` replace
`SiteGroundTemperature.FromValues`, `ZoneList` and `BaseMaterial.as_layer`.
The literal types, the default material library and the schedule helpers
stay in `epinterface.interface`. The written models are unchanged.
- **Breaking:** methods that returned those classes now write and return the
idfkit object: `ConstructionLayerComponent.ep_material` is replaced by
`add_to_idf(doc)`, climate_studio's
`OpaqueConstructionLayer.dereference_to_material` by
`add_material_to_idf(idf, material_defs)`, and
`ZoneOperationsComponent.add_thermostat_to_idf_zone` returns the
`HVACTemplate:Thermostat` object. `AddedZoneLists` holds lists of zone names,
climate_studio's zone lists are the written `ZoneList` objects, and
`TypeLimits` entries are `TypeLimitsSpec` dataclasses with the same
`Lower_Limit_Value` and `Upper_Limit_Value` attributes.

### Fixed

- Shoebox geometry for some storey heights (for example 4.321 m with a
three-storey core/perimeter layout) is now matched correctly. geomeppy paired
some walls wrongly at those heights.
- The legacy `epinterface/builder.py` (`SimpleResidentialModel`) now simulates
end to end. It no longer requests plant sizing.
- climate_studio results use the "District Heating" label on all EnergyPlus
versions. Before, they failed on EnergyPlus 23 and later.
- `Model.run()` (sbem and climate_studio) no longer leaves the results file
open in its temporary run directory, which made the directory's deletion
fail on Windows. Without `eplus_parent_dir`, sbem's `ModelRunResults.sql`
now reads a copy of the results file in the system temporary directory,
deleted when the result is closed.

### Notes

- `SizingPeriod:WeatherFileConditionType` objects are now written in a fixed
order, winter first. archetypal's order came from set iteration and could
change between processes, which could change results (notably core/perimeter
models with a basement and attic).

### Migrating from the archetypal-based releases (GLOBi)

One line changes:

```python
# before
run_result.sql.timeseries_by_name(names, reporting_frequency="Hourly")
# after
run_result.hourly_timeseries(names)
```

Code that passes archetypal or eppy objects to epinterface, or reads them from
`Model` results, must switch to idfkit documents (`epinterface.document.EPDocument`)
and `SQLResult`.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
[![Commit activity](https://img.shields.io/github/commit-activity/m/szvsw/epinterface)](https://img.shields.io/github/commit-activity/m/szvsw/epinterface)
[![License](https://img.shields.io/github/license/szvsw/epinterface)](https://img.shields.io/github/license/szvsw/epinterface)

This is a repository for dynamically generating energy models within Python, relying on Archetypal and Eppy for most of its functionality.
Dynamically generate EnergyPlus models in Python with [idfkit](https://github.com/idfkit/idfkit).

- **Github repository**: <https://github.com/szvsw/epinterface/>

Expand Down
2 changes: 1 addition & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,4 @@
[![Commit activity](https://img.shields.io/github/commit-activity/m/szvsw/epinterface)](https://img.shields.io/github/commit-activity/m/szvsw/epinterface)
[![License](https://img.shields.io/github/license/szvsw/epinterface)](https://img.shields.io/github/license/szvsw/epinterface)

This is a repository for dynamically generating energy models within Python, relying on Archetypal and Eppy for most of its functionality.
Dynamically generate EnergyPlus models in Python with [idfkit](https://github.com/idfkit/idfkit).
2 changes: 1 addition & 1 deletion docs/modules/interface.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# EnergyPlus Interface

This is a thin wrapper around Eppy for some opinionated control.
This is a thin wrapper around idfkit for some opinionated control.

::: epinterface.interface
14 changes: 9 additions & 5 deletions epinterface/analysis/energy_and_peak.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,10 @@

import numpy as np
import pandas as pd
from archetypal.idfclass.sql import Sql
from idfkit.simulation.parsers.sql import SQLResult

from epinterface.results import tabular_frame, timeseries_frame
from epinterface.settings import require_supported_major

kWh_per_GJ = 277.778
GJ_per_J = 1e-9
Expand Down Expand Up @@ -65,7 +68,7 @@


def standard_results_postprocess(
sql: Sql,
sql: SQLResult,
*,
normalizing_floor_area: float,
heat_cop: float,
Expand Down Expand Up @@ -98,10 +101,11 @@ def standard_results_postprocess(
Returns:
series: The postprocessed results (Energy and Peak, with Aggregation and Meter index levels).
"""
require_supported_major(ep_version_major)
desired_meters = DESIRED_METERS_FOR_VERSION[ep_version_major]
raw_hourly = sql.timeseries_by_name(desired_meters, "Hourly")
raw_monthly = sql.timeseries_by_name(desired_meters, "Monthly")
raw_df = sql.tabular_data_by_name(ANNUAL_SUMMARY_REPORT, END_USES_TABLE)
raw_hourly = timeseries_frame(sql, desired_meters, "Hourly")
raw_monthly = timeseries_frame(sql, desired_meters, "Monthly")
raw_df = tabular_frame(sql, ANNUAL_SUMMARY_REPORT, END_USES_TABLE)

raw_df_relevant = (
raw_df[[*TABULAR_DATA_COLUMNS_FOR_VERSION[ep_version_major]]].droplevel(
Expand Down
9 changes: 6 additions & 3 deletions epinterface/analysis/overheating.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,12 @@

import numpy as np
import pandas as pd
from archetypal.idfclass.sql import Sql
from idfkit.simulation.parsers.sql import SQLResult
from numpy.typing import NDArray
from pydantic import BaseModel, Field

from epinterface.results import timeseries_frame

# ---------------------------------------------------------------------------
# Configuration models
# ---------------------------------------------------------------------------
Expand Down Expand Up @@ -1104,7 +1106,7 @@ def compute_zone_at_risk(


def overheating_results_postprocess(
sql: Sql,
sql: SQLResult,
zone_weights: NDArray[np.float64],
zone_names: list[str],
config: OverheatingAnalysisConfig | None = None,
Expand All @@ -1122,7 +1124,8 @@ def overheating_results_postprocess(
"""
_config = config if config is not None else OverheatingAnalysisConfig()
# TODO: compare the single request flamegraph to splitting it out as multiple requests
hourly = sql.timeseries_by_name(
hourly = timeseries_frame(
sql,
[
"Zone Mean Air Temperature",
"Zone Air Relative Humidity",
Expand Down
Loading