canmet-energyplus

EnergyPlus as a Python wheel. pip install canmet-energyplus gives you a runnable simulation engine — no separate download, no installer, no PATH setup, no thinking about it.

import subprocess, canmet_energyplus as ce

subprocess.run([ce.binary_path(), "-w", "weather.epw", "-d", "out/", "model.idf"])
print(ce.ENERGYPLUS_VERSION)   # 25.2.0

What you get

The official NREL EnergyPlus release, sha256-verified before anything touches it, pruned to what a simulation run actually needs, and repackaged as a platform wheel. The binaries, Energy+.idd, the epJSON schema, ExpandObjects, the datasets, the TMY3 weather files and the licence notices all ship. What does not: the PythonPlugin host (python_lib, pyenergyplus), Documentation, ExampleFiles and PreProcess — about 100 MB that no run reaches, and the difference between a 164 MB wheel PyPI refuses and a ~60 MB one it accepts.

Every wheel carries PROVENANCE.json: the upstream asset and its verified digest, every file removed and kept with hashes, and the builder commit.

Platform	Wheel	Size
Linux x86-64 (glibc ≥ 2.35)	py3-none-manylinux_2_35_x86_64	~60 MB
Windows x86-64	py3-none-win_amd64	~28 MB

The manylinux tag is earned, not asserted: the bundled libpython is renamed and the binaries' NEEDED entries patched so no payload ELF links a plain libpython, then auditwheel show must grade the finished wheel at exactly the tag baked into its filename or the build fails.

macOS is not published: use EnergyPlus's own installer there.

Versioning

<EnergyPlus version>.<packaging iteration> — 25.2.0.2 is the second packaging of EnergyPlus 25.2.0. Repackaging the same engine (a different prune, a fixed exec bit) bumps the last segment only. ENERGYPLUS_VERSION is always the three-part engine version; the distribution version comes from importlib.metadata.version("canmet-energyplus").

Pin it exactly if you depend on a specific engine build:

canmet-energyplus==25.2.0.2 ; sys_platform == 'win32' or (sys_platform == 'linux' and platform_machine == 'x86_64')

Which upstream build?

This repository is the authority for which EnergyPlus asset is repackaged and its digest — they are pinned in build_wheel.py. A consumer that also carries its own EnergyPlus version data (because it supports platforms this wheel does not) should cross-check PROVENANCE["source_asset"]["sha256"], ENERGYPLUS_VERSION and BUILD_SHA against its own copy, so divergence fails loudly instead of resolving quietly.

Building

python3 build_wheel.py --platform all --iteration 2 --outdir dist/

Validation installs the built wheel into a scratch venv, resolves the binary through binary_path(), and runs a real EnergyPlus simulation using a weather file the payload itself ships — self-contained, with no consumer package required to prove the engine works. Only the artifact the build host can execute is validated; the other is validated by exact digest on its own runner in publish.yml.

Licence

The code here is LGPL-3.0-or-later. The wheels additionally contain EnergyPlus under its own BSD-style NREL/UC Regents licence and a bundled CPython runtime under PSF-2.0. See NOTICE.

Provenance

Extracted from canmet-energy/btap at commit 72b97516cd340a7d0197a21dc84645af8ddcbc0e with git filter-repo, preserving this code's history. It was previously published as the btap-energyplus companion; the org-scoped name reflects that the engine is useful beyond that one consumer.