archetypal: A Python package for collecting, simulating, converting and analyzing building archetypes

The field of Urban Building Energy Modeling (UBEM), which assesses the energy performance of buildings in cities relies on advanced physical models known as building energy models that are representative of the building stock. These building archetypes are often developed in specific modelling platforms such as EnergyPlus or TRNSYS, two leading simulation engines in the field of building energy modeling. EnergyPlus is an open source simulation engine developed by the US Department of Energy. TRNSYS is a well established and specialized simulation platform used to simulate the behavior of transient systems. The Urban Modeling Interface (UMI), developed by the MIT Sustainable Design Lab, leverages EnergyPlus to enable building energy modeling at the urban scale. The three tools offer many advantages in their respective fields, but all suffer from the same flaw: creating building archetypes for any platform is a time-consuming, tedious and error-prone process. archetypal is a Python package that helps handling collections of such archetypes and to enable the interoperability between these energy simulation platforms to accelerate the creation of reliable urban building energy models. This package offers three major capabilities for researchers and practitioners:


Summary
The field of Urban Building Energy Modeling (UBEM), which assesses the energy performance of buildings in cities relies on advanced physical models known as building energy models that are representative of the building stock. These building archetypes are often developed in specific modelling platforms such as EnergyPlus or TRNSYS, two leading simulation engines in the field of building energy modeling. EnergyPlus is an open source simulation engine developed by the US Department of Energy. TRNSYS is a well established and specialized simulation platform used to simulate the behavior of transient systems. The Urban Modeling Interface (UMI), developed by the MIT Sustainable Design Lab, leverages EnergyPlus to enable building energy modeling at the urban scale. The three tools offer many advantages in their respective fields, but all suffer from the same flaw: creating building archetypes for any platform is a time-consuming, tedious and error-prone process. archetypal is a Python package that helps handling collections of such archetypes and to enable the interoperability between these energy simulation platforms to accelerate the creation of reliable urban building energy models. This package offers three major capabilities for researchers and practitioners: 1. Run, modify and analyze collections of EnergyPlus models in a persistent environment; 2. Convert EnergyPlus models to UMI Template Files; 3. Edit UMI Template Files in a scripting environment. 4. Convert EnergyPlus models to TRNSYS TrnBuild Models.

EnergyPlus Simulation Environment
archetypal leverages the Python Eppy (Philip, Tran, Youngson, & Bull, 2004) and Ge-omEppy (Bull, 2016) packages to read, edit and run EnergyPlus files. It includes additional functionalities developed to improve building energy analysis workflows. For instance, archetypal exposes simulation results as time-series DataFrames and typical building energy profiles such as the space heating, space cooling and domestic hot water profiles are accessible by default. Other output names can be specified by the user.
Furthermore, for a drastic workflow speed gain, especially with multiple and/or larger IDF files (which can take several minutes to transition and simulate), archetypal features a caching API. This is particularly useful for reproducible workflows such as the Jupyter Notebook programming environment. Rerunning cells (even after a kernel restart) will use the cached IDF models and their simulation results instead of executing EnergyPlus again. Speedups of up to 8x have been measured.

EnergyPlus to UMI Template File Conversion
UMI users spend a lot of time and resources gathering all the necessary data and creating archetype templates for their urban building energy models. archetypal offers researchers and designers a way of creating UMI Template Files from existing EnergyPlus models, automatically. The algorithm approximates the non-geometric parameters of a multi-zone EnergyPlus model by dissecting and combining core zones and perimeter zones. The procedure is an attempt to streamline and accelerate the creation of urban building energy models (Reinhart & Cerezo Davila, 2016) by handling the creation of the inputs of the "Shoeboxer" method (Dogan & Reinhart, 2017) used by UMI.

UMI Template File Scripting Language
archetypal also aims at providing a scripting language for the modification of UMI Template Files. It is a Python interface for the specific data format of the UMI Template Editor developed in C#.

EnergyPlus to TRNBuild Conversion
Intermodel comparison methods are important in the field of building energy modelling because they allow model methodologies and results to be reviewed (Judkoff & Neymark, 1995). Furthermore, some model engines include features that others don't already implement. Since it can be long and error-prone to create archetype buildings by hand, converting EnergyPlus models to TrnBuild models emerged as a way of speeding both the intermodel comparisons and the supplemental model creation. That is to say, a large repository of prototype building models exists in the literature with a large majority developed in the popular EnergyPlus environment ( US DOE -Building Energy Codes Program, 2012; US DOE -Building Technology Office, 2018). With archetypal, researchers and building energy model specialists can create TrnBuild Models from existing EnergyPlus models.
The latest stable release of the software can be installed via pip and full documentation can be found at https://archetypal.readthedocs.io.