Repository navigation
Replace archetypal, eppy and geomeppy with idfkit - #70
Draft
samuelduchesne wants to merge 41 commits into
Draft
samuelduchesne wants to merge 41 commits into
samuelduchesne wants to merge 41 commits into
Conversation
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
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
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
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
Co-Authored-By: Claude Opus 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
samuelduchesne
commented
Nov 13, 2026
| # 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"] |
Author
There was a problem hiding this comment.
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
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
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
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
samuelduchesne
commented
Nov 13, 2026
| [](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. |
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LQbHyrrQQ7yR4tU6142dXd
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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),mainagainst this branch:main)energy_and_peakEnergyPlus'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.rtol 1e-9,atol 0.01.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.idfis an idfkitIDFDocument, andModelRunResults.sqlis an idfkitSQLResult.Model.build()returnsIDFDocument,Model.simulate()returns(IDFDocument, SQLResult), andpost_geometry_callbacktakes and returns anIDFDocument.add_to_idf(...)-style method, and the classes ininterface.py,builder.py,climate_studio/andgeometry.py, take anIDFDocument.EnergyPlusSettings.archetypal_energyplus_versionis replaced byversion_tuple.ddy_interface_bayes.pyis removed (nothing imported it).Migration for GLOBi
GLOBi needs one line changed, plus its pin moved from
epinterface>=1.4,<1.5to>=2.0,<3:hourly_timeseriesreturns 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 plainDataFrame, without archetypal's.unitsattribute. 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
setorder, 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.minimal_document(version)creates it with idfkit for any EnergyPlus version, instead of reading the packaged 22.2Minimal.idfand migrating it with EnergyPlus's version-upgrade programs, which cost about 37 s on the first build in each process.UnsupportedEnergyPlusVersionErrorinstead of aKeyError.>=1.2,<1.3. Parity is proven only for that series.networkx,tqdmandpyyamlare now direct dependencies. archetypal used to provide them.builder.pynow simulates. It requested plant sizing with no plant loops, which EnergyPlus treats as fatal; plant sizing is now off.climate_studionow 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, witheplus_parent_dirset, is unchanged.Test plan
pyright: 0 errors;pre-commit run --all-files: clean;uv lock --locked: OKhourly_data_configset, on its Docker imageFollow-ups (not in this PR, they change results)
Schedule:Compact.Fraction/ implausible setpoints).hourly_timeseries(df.attrs["units"]) and pin all four hourly variables in the regression fixture.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