Skip to content

Replace archetypal, eppy and geomeppy with idfkit - #70

Draft
samuelduchesne wants to merge 41 commits into
szvsw:mainfrom
samuelduchesne:feature/happy-rubin-nfa42s
Draft

samuelduchesne wants to merge 41 commits into
szvsw:mainfrom
samuelduchesne:feature/happy-rubin-nfa42s

Conversation

@samuelduchesne

Copy link
Copy Markdown

Summary

epinterface now builds, simulates and reads EnergyPlus models through idfkit's native API. archetypal, eppy and geomeppy are gone from the code and the lock file. Results for the same inputs match the archetypal-based 1.x within the regression tolerances, and the package is faster.

Speed

Measured on one container with EnergyPlus 25.2.0, using FlatModel's example building (40 × 40 m, 2 storeys, core/perimeter), main against this branch:

archetypal (main) idfkit (this branch) Change
Fresh process: import + first model build (3 runs) 5.7–6.0 s 1.5–1.65 s about 3.7× faster
Later model builds (median of 6) 1.43 s 0.15 s about 9× faster
Full simulation + hourly results (median of 4) 9.9 s 7.25 s 27% less time, about 2.6 s per building
Sum of energy_and_peak 1068.46643097 1068.46643122 same within 2e-10

EnergyPlus's own run time is unchanged, so the saving comes from Python overhead. These are one building type on one machine, so treat them as indicative.

Results stay the same

A new regression test (tests/test_regression.py) compares this branch against fixtures captured from the archetypal-era code on EnergyPlus 25.2.0, for three configurations: plain by-storey; core/perimeter with a conditioned basement and an attic; and neighbour shading with the overheating analysis.

  • Labels and shapes must match exactly, including zone names and their order.
  • Per-zone geometry (area, volume, wall and window area, from EnergyPlus's Zone Summary) must match within rtol 1e-9, atol 0.01.
  • Energy, peak, overheating and hourly values must match within rtol 1e-3, atol 1e-6.

The fixtures were captured with realistic thermostat setpoints (21 °C heating, 24 °C cooling). The test seed previously set every schedule, setpoints included, to a constant 0.5 (Fraction), so the models sat at 0.5 °C and their cooling sizing was meaningless.

A no-simulation geometry fixture also pins every surface (zone, type, boundary, construction, area, centroid) for 17 geometry variants against geomeppy's output.

Breaking changes

  • ModelRunResults.idf is an idfkit IDFDocument, and ModelRunResults.sql is an idfkit SQLResult.
  • Model.build() returns IDFDocument, Model.simulate() returns (IDFDocument, SQLResult), and post_geometry_callback takes and returns an IDFDocument.
  • Every add_to_idf(...)-style method, and the classes in interface.py, builder.py, climate_studio/ and geometry.py, take an IDFDocument.
  • EnergyPlusSettings.archetypal_energyplus_version is replaced by version_tuple.
  • ddy_interface_bayes.py is removed (nothing imported it).

Migration for GLOBi

GLOBi needs one line changed, plus its pin moved from epinterface>=1.4,<1.5 to >=2.0,<3:

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

hourly_timeseries returns the same frame: three column levels in the same order, the same index, and the same raw EnergyPlus units (°C, %). The difference is that it is a plain DataFrame, without archetypal's .units attribute. Everything else GLOBi calls (Model, ShoeboxGeometry, SceneContext, run(), energy_and_peak, overheating_results, total_conditioned_area, compute_shading_mask, SemanticModelFields, …) is unchanged. sbem-ui uses only component models and the database, so it needs nothing beyond the version bump.

Behaviour notes

  • Sizing-period order is now fixed. archetypal added the two weather-file sizing periods in Python set order, which can differ between processes. On the degenerate pre-fix test model, swapping the order changed October cooling by 31%. The order is now fixed winter-first, matching the baseline.
  • Geometry is correct where geomeppy mis-paired walls. For some storey heights (for example a 3-storey core/perimeter block with 4.321 m storeys), geomeppy paired walls wrongly: an outdoor wall became a partition and lost its window. This branch keeps the correct geometry, and a test pins the exact difference.
  • Weekday schedules keep a one-day shift on purpose. Schedules built from 8760 values still put January 1 in the Monday slot, while the RunPeriod starts on Sunday. This reproduces archetypal exactly so results don't move; fixing it is a follow-up that will change results.
  • The base model is built programmatically. minimal_document(version) creates it with idfkit for any EnergyPlus version, instead of reading the packaged 22.2 Minimal.idf and migrating it with EnergyPlus's version-upgrade programs, which cost about 37 s on the first build in each process.
  • The default EnergyPlus version is the newest installed one epinterface supports. Unsupported versions raise UnsupportedEnergyPlusVersionError instead of a KeyError.
  • idfkit is pinned to >=1.2,<1.3. Parity is proven only for that series.
  • networkx, tqdm and pyyaml are now direct dependencies. archetypal used to provide them.
  • The legacy builder.py now simulates. It requested plant sizing with no plant loops, which EnergyPlus treats as fatal; plant sizing is now off. climate_studio now runs on EnergyPlus 23+ too.
  • run(eplus_parent_dir=None) keeps results readable and Windows-safe. It releases the SQLite file before its temporary directory is deleted, and keeps results readable from a copy. GLOBi's path, with eplus_parent_dir set, is unchanged.

Test plan

  • Full suite on EnergyPlus 25.2.0: 418 passed, 8 skipped, 2 xfailed
  • Regression (3 configurations) and output-object comparison against the archetypal baseline: 7/7 at unchanged tolerances
  • pyright: 0 errors; pre-commit run --all-files: clean; uv lock --locked: OK
  • Every EnergyPlus version idfkit knows (8.9 to 26.2) builds and validates a base document
  • CI on EnergyPlus 22.2 / 24.2 (only 25.2 and 26.x were available locally)
  • One GLOBi pipeline run with hourly_data_config set, on its Docker image

Follow-ups (not in this PR, they change results)

  • Fix the weekday shift, possibly by moving 8760-value schedules to Schedule:Compact.
  • Validate thermostat setpoint schedules (reject Fraction / implausible setpoints).
  • Expose units on hourly_timeseries (df.attrs["units"]) and pin all four hourly variables in the regression fixture.
  • Decide on the sun and wind exposure of the upper half of a split basement wall (inherited from geomeppy).

Design and plan: docs/superpowers/specs/2026-11-12-idfkit-migration-design.md, docs/superpowers/plans/2026-11-12-idfkit-migration.md.


Generated by Claude Code

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
Writers take and return an IDFDocument and write through doc.add with
idfkit's snake_case field names (resolved against the document schema).
Single-instance types replace the object already present. The simple
residential builder selects exterior walls by surface type and boundary
condition instead of matching geomeppy's "Project Wall" construction.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
…writers

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
Model.build/simulate/run, FlatModel and DDYSizingSpec now work on an
idfkit IDFDocument and run EnergyPlus through idfkit.simulation.simulate.
The Output:* objects archetypal's prep_outputs requested are reproduced,
and sizing periods are injected in a fixed order (winter, summer): the
order archetypal produced varied with the string hash seed and the
core/perim + basement + attic baseline is sensitive to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
The climate studio library holds its schedules as LibrarySchedule models
(type limits + 8760 values, same JSON shape as before) written with
add_values_schedule. The builder builds an IDFDocument from the shared
minimal_document (moved from sbem/builder.py to epinterface.document),
requests the sbem path's outputs, injects winter-first sizing periods,
simulates through idfkit and returns (IDFDocument, SQLResult). The legacy
SimpleResidentialModel loads its DDY with load_idf and no longer requests
plant sizing, so it simulates end to end; both get tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
Remove the archetypal dependency (networkx, tqdm, pyyaml and matplotlib,
previously transitive, are now declared), delete the archetypal parity
test, port the notebooks to idfkit, document the provenance scripts and
add the 2.0.0 changelog.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
- test_lights_and_equipment_use_floor_area_field picks the floor-area field
  for the document's EnergyPlus version (watts_per_zone_floor_area < 24).
- pre-commit: never rewrite tests/data fixtures or docs/superpowers; skip
  pyright on the archetypal-based capture scripts.
- Revert formatting churn in analysis/ to the pinned ruff-format.
- Fix pyright findings in tests (Optional access, idfkit.schedules import,
  EnergyPlusNotFoundError args, isinstance on generic IDFDocument).
- add_values_schedule: accept numpy arrays in the signature and remove
  generated d_/w_ objects numbered 100 and above when rewriting.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
idfkit's SQLResult keeps its connection open, so leaving a
TemporaryDirectory with eplusout.sql open fails on Windows.

- New epinterface.simulation holds the code both builders shared:
  add_output_objects (re-exported from sbem.builder), run_energyplus,
  read_warnings and detach_sql.
- climate_studio Model.run closes the results after post-processing.
- sbem Model.run without eplus_parent_dir closes the results, copies the
  file to a mkstemp file and returns a result on that copy (deleted on
  close), so ModelRunResults.sql still works after run() returns. With
  eplus_parent_dir set nothing changes.
- Tests: a spy fixture asserting no results file is open when a temp dir
  is deleted, hourly_timeseries after a temp-dir run, detach_sql unit test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
The parity tests prove only idfkit 1.2, and downstream installs do not use
this lock. CHANGELOG now gives the tolerances, drops the Removed bullet that
repeated Changed and notes the Windows run() fix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
minimal_document now builds the minimal EnergyPlus model from the version's
schema instead of migrating the packaged Minimal.idf, so any idfkit version
works, there is no transition step, and each call returns a fresh document.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
Only the one known version-dependent field (Output:SQLite unit conversion
before 9.5) is skipped; any other field missing from the schema now raises.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
The seeded Heating_Year and Cooling_Year schedules were constant 0.5
Fraction schedules, so models built from the test seed held 0.5 degC
heating and cooling setpoints. create_schedule gains optional value,
day_type and year_type parameters (defaults unchanged); the thermostat
schedules are now constant Temperature/Setpoint schedules at 21 and 24 degC.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
Fixtures recaptured from b4f9f6a (archetypal) with the new seed and
regression config, EnergyPlus 25.2.0, PYTHONHASHSEED=4 (Winter Extreme
sizing period first in every built.idf). neighbors_overheating now uses
thresholds the conditioned zones cross (heat 23/26, cold 22.5 degC) so
every overheating frame, including consecutive_e_zone, is non-trivial.
Geometry fixtures are unchanged. Tolerances are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
The DDY injector and the exposed-basement wall split copied objects by
passing to_dict() minus the name to doc.add(). copyidfobject(obj, new_name=)
is idfkit's own copy primitive (idfkit uses it to apply design days).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
idf-demo.py still called the eppy-style idf.saveas(), which only ran through
idfkit's compatibility methods.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@claude we don't need any of this on this PR

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@claude we don't need any of this on this PR

# Sizing periods run in this order; winter first, as on the sbem path.
ddy_spec = DDYSizingSpec(
match=False, conditions_types=["Summer Extreme", "Winter Extreme"]
match=False, conditions_types=["Winter Extreme", "Summer Extreme"]

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@claude why flip the condition_types?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On main this list went through set(obj_names) before the sizing periods were copied, so their order followed string hashing and could change between runs; summer-first was never guaranteed. The port keeps the order given, so the list now decides it. I chose winter-first to match the sbem builder (sbem/builder.py:866), and test_climate_studio checks it. Happy to switch back to summer-first if you prefer; either is now deterministic.

add_or_replace keeps archetypal's reuse-or-replace semantics for shared
objects; field_name resolves fields renamed between EnergyPlus versions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
The sbem components, builder, geometry placeholder constructions and the
interface helpers now call add_or_replace / doc.add with idfkit field
names instead of the EnergyPlus mirror classes, carrying every non-schema
default over explicitly. The written IDF is byte-identical for 25.2 and
22.2.

TypeLimits entries become a frozen TypeLimitsSpec dataclass with the same
Lower_Limit_Value/Upper_Limit_Value attributes GLOBi reads.
ConstructionLayerComponent.ep_material is replaced by add_to_idf, the
thermostat writer returns the IDFObject, and AddedZoneLists holds zone
name lists.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
SimpleResidentialModel and the climate studio library and builder now
write their objects with add_or_replace and idfkit field names, with the
former classes' defaults spelled out. The written IDF is byte-identical
for 25.2 and 22.2.

OpaqueConstructionLayer.dereference_to_material becomes
add_material_to_idf, and the climate studio zone lists are the written
ZoneList objects.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
epinterface.interface keeps the literal types, the material library and
the document helpers. The pydantic classes that mirrored one EnergyPlus
object each (Material, Construction, People, Lights, ScheduleYear, ...),
BaseObj with its extract() readers and the field alias layer are gone:
objects are written with doc.add / add_or_replace and idfkit field names.

New helpers replace the class-based ones: add_site_ground_temperature
(for SiteGroundTemperature.FromValues), add_zone_list / zone_list_names
(for ZoneList) and BaseMaterial.add_layer_to_idf (for as_layer).
test_interface.py now tests these helpers and the literal types.

BREAKING CHANGE: the mirror classes are removed from epinterface.interface.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
ModelRunResults.idf becomes ModelRunResults.doc; the old name stays as a
deprecated property.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
Comment thread docs/index.md Outdated
[![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.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@claude add a link to the idfkit GitHub repo

Pin idfkit to >=1.3.0rc1,<1.4 and type every document as EPDocument, the
union of idfkit's IDFDocumentV22_2 to IDFDocumentV25_2, instead of the
26.2-typed IDFDocument. as_supported() and load_document() narrow documents
at the load boundaries; minimal_document() refuses unsupported releases up
front. watts_per_area() replaces field_name() for the Lights and
ElectricEquipment design level renamed in 24.1. 22.1 is left out: it names
the infiltration and ventilation fields epinterface writes differently. A
pre-commit hook runs idfkit check on the supported releases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
- minimal_document no longer shares list-valued fields with the module
  template, so editing one document cannot change later ones.
- add_or_replace restores the object it was replacing when the replacement
  fails validation, instead of leaving the document without it.
- add_values_schedule takes holiday, design-day and custom-day profiles from
  their weekday fields, so first_weekday="sunday" no longer sizes on weekends.
- The default EnergyPlus version skips releases before 22.2, which
  minimal_document refuses.
- run_energyplus runs the EnergyPlus of the document's own release.
- detach_sql returns an already-detached result unchanged instead of deleting
  the file it is about to copy.
- DDY sizing-period names are de-duplicated case-insensitively, as idfkit
  looks them up.
- climate_studio hot water writes the Temperature type limits archetypal
  ended up writing (-100/100, as in the sbem baseline), not -60/200.
- The ideal-loads template defaults live in one add_ideal_loads_template
  helper used by all three writers; one NON_LEAP_MONTH_LENGTHS table; the
  legacy builder uses DEFAULT_CONSTANT_SCHEDULE_PAIRS; _floor_plan_centre
  uses idfkit's bounding_box.
- The regression test and zone summary close their SQLite connections.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
Restore version 1.5.0 and list the changes under Unreleased in the
changelog instead of a 2.0.0 release.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants