1. Converting IDF models

EnergyPlus models can be converted to umi template library files using archetypal.

1.1. Converting IDF to UMI

The IDF to UMI converter generates an Umi Template from one or more EnergyPlus models (IDF files). The conversion is performed by simplifying a multi-zone and geometric model to a 2-zone and non-geometric template. In other words, a complex EnergyPlus model is be converted to a generalized core- and perimeter-zone with aggregated performances.

Conversion can be achieved either with the command line or within a python console (interactive shell). The command line is useful for getting started quickly but does not offer any intermediate like the interactive shell does. If you would rather use archetypal inside a python script, then the archetypal module is fully accessible and documented.

1.1.1. Using the Command Line

Hint

In this tutorial, we will be using an IDF model from the ExampleFiles folder located inside the EnergyPlus folder.

Terminal and Command Prompt may not be the most convenient tool to use, which is quite understandable, since users may be more familiar with graphical interfaces. archetypal does not feature a graphical interface as it is meant to be used in a scripting environment.

The first step would be to change the current directory to the one where the idf file is located. When archetypal is executed, temporary folders may be created to enable the conversion process. It is recommended to change the current directory of the terminal window to any working directory of your choice.

cd "/path/to/directory"

An idf file can be converted to an umi template using the reduce command. For example, the following code will convert the model AdultEducationCenter.idf to a json file named myumitemplate.json. Both absolute and relative paths can be used.

archetypal reduce "/Applications/EnergyPlus-9-2-0/ExampleFiles/BasicsFiles/AdultEducationCenter.idf" "./converted/myumitemplate.json"

1.1.2. Using the Python Console

archetypal methods are accessible by importing the package.

  1. Load the file

First, load the EnergyPlus idf file using the archetypal.idfclass.idf.IDF class. In the following example, the AdultEducationCenter.idf model is used.

>>> from archetypal import IDF
>>> idf = IDF.from_example_files("AdultEducationCenter.idf", epw="USA_IL_Chicago-OHare.Intl.AP.725300_TMY3.epw")  # IDF load

  1. Simulate the file

The model must be simulated because the BuildingTemplate.from_idf method uses the sqlite database generated by EnergyPlus.

>>> idf.simulate()
<IDF object AdultEducationCenter.idf
at /Applications/EnergyPlus-9-2-0/ExampleFiles/BasicsFiles/AdultEducationCenter.idf
    Version 9.2.0
Simulation Info:
| SimulationIndex       | 1                                                          |
| EnergyPlusVersion     | EnergyPlus, Version 9.2.0-921312fa1d, YMD=2023.01.28 18:44 |
| TimeStamp             | YMD=2023.01.28 18:44                                       |
| NumTimestepsPerHour   | 4                                                          |
| Completed             | 1                                                          |
| CompletedSuccessfully | 1                                                          |
    Files at 'cache/941af560028252d7311d572b9c84cee6/f79de785e8989c884dca20f1dca08c1f'>

  1. Create a BuildingTemplate Object

>>> from archetypal import BuildingTemplate
>>> template_obj = BuildingTemplate.from_idf(
>>>     idf, DataSource=idf.name
>>> )

  1. Create an UmiTemplateLibrary Object and Save

>>> from archetypal import UmiTemplateLibrary
>>> template_json = UmiTemplateLibrary(
>>>     name="my_umi_template",
>>>     BuildingTemplates=[template_obj]
>>> ).to_dict()