1. Converting IDF models

EnergyPlus models can be converted to two different other formats using archetypal. TRNSYS users can convert IDF files to TRNBuild/Type56 files while UMI users can convert IDF files to UMI Template Files.

1.1. Converting IDF to BUI

converter logo

The necessity of translating IDF files (EnergyPlus input files) to BUI files (TRNBuild input files) emerged from the need of modeling building archetypes 1. Knowing that a lot of different models from different sources (NECB and US-DOE) have already been developed under EnergyPlus, and it can be a tedious task to create a multizone building in a model editor (e.g. TRNBuild), we assume the development of a file translator could be useful for simulationists.

1.1.1. Objectives

The principal objectives of this module was to translate (from IDF to BUI) the geometry of the building, the different schedules used in the model, and the thermal gains.

  1. Geometry

The building geometry is kept with all the zoning, the different surfaces (construction and windows) and the thermal properties of the walls. The thermal properties of windows are not from the IDF, but chosen by the user. The user gives a U-value, a SHGC value and Tvis value. Then a window is chosen in the Berkeley Lab library (library used in TRNBuild). For more information, see the methodology section please.

  1. Schedules

All schedules from the IDF file are translated. The translator is able to process all schedule types defined by EnergyPlus (see the different schedule types for more information). Only day and week schedules are written in the output BUI file

  1. Gains

Internal thermal gains such as “people”, “lights” and “equipment” are translated from the IDF file to the BUI file.

  1. Conditioning

Heating and cooling demands are translated from the IDF file to the BUI file such as power per floor area (W/m²) and a temperature setpoint. The temperature set-point is the set-point at the peak time for heating (or cooling).

1.1.2. Methodology

The module is divided in 2 major operations. The first one consist in translating the IDF file from EnergyPlus, to an IDF file proper to an input file for TRNBuild (T3D file), usually created by the TRNSYS plugin “Trnsys3D” in SketchUp. The second operation is the conversion of the IDF file for TRNBuild to a BUI file done with the executable trnsidf.exe (installed by default in the TRNSYS installation folder: C:TRNSYS18\Building\trnsIDF\)

  1. IDF to T3D

The conversion from the IDF EnergyPlus file to the IDF TRNBuild file (called here T3D file) is the important part of the module, which uses the Eppy python package, allowing, with object classes, to find the IDF objects, modify them if necessary and re-transcribe them in the T3D file

  1. T3D to BUI

The operation to convert the T3D file to the BUI file is done by running the trnsidf.exe executable with a command line. After this operation, the infiltration rate, internal gains and conditioning systems are written in the “REGIME” section of each zone in the BUI file.

1.1.3. How to convert an IDF file

Converting an IDF file to a BUI file is done using the terminal with a command line. First, open the Command Prompt on Windows or the Terminal on Mac. Note that if you used Anaconda to install python on your machine, you will most likely avoid some issues by using the Anaconda Prompt instead.

Then simply run the following command:

archetypal convert [OPTIONS] IDF_FILE WEATHER_FILE OUTPUT_FOLDER

1. IDF_FILE is the file path of the IDF file to convert. If there are space characters in the path, it should be enclosed in quotation marks.

2. WEATHER_FILE is the file path of the weather file to use to run the EnergyPlus simulation. If there are space characters in the path, it should be enclosed in quotation marks.

3. OUTPUT_FOLDER is the folder where we want the output folders to be written. If there are space characters in the path, it should enclosed in quotation marks. If output folder path is passed, it must exist. If nothing is passed, the output folder will be the current working directory.

Here is an example. Make sure to replace the last two arguments with the idf file path and the output folder path respectively.

archetypal convert "/Users/Documents/NECB 2011 - Warehouse.idf" "/Users/Documents/CAN_PQ_Montreal.Intl.AP.716270_CWEC.epw" "/Users/Documents/WIP"

4. OPTIONS: There are different options to the convert command. The first 3 manage the requested output files. Users can chose to return a combination of flags

  • if -i is added, the path to the modified IDF file is returned in the console, and the modified IDF file is returned in the output folder. If -t is added, the path to the T3D file (converted from the IDF file) is returned. If -d is added, the DCK file (TRNSYS input file) is returned in the output folder, and the path to this DCK file is returned in the console.

archetypal convert -i -t -d "/Users/Documents/NECB 2011 - Warehouse.idf" "/Users/Documents/CAN_PQ_Montreal.Intl.AP.716270_CWEC.epw" "/Users/Documents/WIP"
  • --window_lib is the path of the window library (W74-lib.dat). This library must be in the same format as the Berkeley Lab library used by default in TRNBuild. If nothing is passed, the “W74-lib.dat” file available in the package “ressources” folder will be used.

archetypal convert --window_lib "/Users/Documents/W74-lib.dat" "/Users/Documents/NECB 2011 - Warehouse.idf" "/Users/Documents/CAN_PQ_Montreal.Intl.AP.716270_CWEC.epw" "/Users/Documents/WIP"
  • --trnsidf_exe is the path of the trnsidf.exe executable. Usually located in the TRNSYS18 folder under “Building/trnsIDF/trnsidf.exe”. If nothing is passed, the following path will be used : “C:TRNSYS18\Building\trnsIDF\trnsidf.exe”.

archetypal convert --trnsidf_exe "C:TRNSYS18\\Building\\trnsIDF\\trnsidf.exe" "/Users/Documents/NECB 2011 - Warehouse.idf" "/Users/Documents/CAN_PQ_Montreal.Intl.AP.716270_CWEC.epw" "/Users/Documents/WIP"
  • --template is the path of the .d18 template file (usually in the same directory as the trnsidf.exe executable). If nothing is passed, the following path will be used : “C:TRNSYS18\Building\trnsIDF\NewFileTemplate.d18”.

archetypal convert --template "C:TRNSYS18\\Building\\trnsIDF\\NewFileTemplate.d18" "/Users/Documents/NECB 2011 - Warehouse.idf" "/Users/Documents/CAN_PQ_Montreal.Intl.AP.716270_CWEC.epw" "/Users/Documents/WIP"
  • --log_clear_names if added, do not print log of “clear_names” (equivalence between old and new names) in the console.

archetypal convert --log_clear_names "/Users/Documents/NECB 2011 - Warehouse.idf" "/Users/Documents/CAN_PQ_Montreal.Intl.AP.716270_CWEC.epw" "/Users/Documents/WIP"
  • --window specifies the window properties <u_value (W/m²-K)> <shgc (-)> <t_vis (-)> <tolerance (-)> <fframe (-)> <uframe (kJ/m²-K-h)>. If nothing is passed, the following values will be used : 2.2 0.65 0.8 0.05 0.15 8.17

archetypal convert --window 2.2 0.65 0.8 0.05 0.15 8.17 "/Users/Documents/NECB 2011 - Warehouse.idf" "/Users/Documents/CAN_PQ_Montreal.Intl.AP.716270_CWEC.epw" "/Users/Documents/WIP"
  • --ordered sorts the idf object names

archetypal convert --ordered "/Users/Documents/NECB 2011 - Warehouse.idf" "/Users/Documents/CAN_PQ_Montreal.Intl.AP.716270_CWEC.epw" "/Users/Documents/WIP"
  • If --nonum is added, do not renumber surfaces in BUI. If --batchjob or -N is added, does BatchJob Modus when running trnsidf.exe. --geofloor must be followed by a float between 0 and 1, and generates GEOSURF values for distributing direct solar radiation where geo_floor % is directed to the floor, the rest to walls/windows. If --refarea is added, updates floor reference area of airnodes. If --volume is added, updates volume of airnodes. If --capacitance is added, updates capacitance of airnodes. All those options are used when running trnsidf.exe (converting T3D file to BUI file).

archetypal convert --nonum -N --geofloor 0.6 --refarea --volume --capacitance "/Users/Documents/NECB 2011 - Warehouse.idf" "/Users/Documents/CAN_PQ_Montreal.Intl.AP.716270_CWEC.epw" "/Users/Documents/WIP"
  • -h Shows the “help” message

archetypal convert -h
1

Archetype: building model representing a type of building based on its geometry, thermal properties and its usage. Usually used to create urban building model by assigning different archetypes to represent at best the building stock we want to model.

1.1.4. Equivalence between idf object names when converting a file

Table 1.1 Equivalences

Old names

New names

Building

b

Site:Location

sl

SizingPeriod:DesignDay

spdd

RunPeriod

rp

RunPeriodControl:SpecialDays

rpcs

ScheduleTypeLimits

stl

Schedule:Constant

sc

Schedule:Day:Hourly

sdh

Schedule:Week:Daily

swd

Schedule:Year

sy

Schedule:Compact

sc

Material

m

Material:NoMass

mnm

Material:AirGap

mag

Construction

c

ZoneList

zl

ZoneGroup

zg

Zone

z

BuildingSurface:Detailed

bsd

Shading:Zone:Detailed

szd

InternalMass

im

People

p

Lights

l

ElectricEquipment

ee

GasEquipment

ge

HotWaterEquipment

hwe

SteamEquipment

se

ZoneBaseboard:OutdoorTemperatureControlled

zbot

ZoneInfiltration:DesignFlowRate

zidf

ZoneVentilation:DesignFlowRate

zvdf

ZoneVentilation:WindandStackOpenArea

zvws

Exterior:Lights

el

Exterior:FuelEquipment

efe

DesignSpecification:OutdoorAir

dsoa

ZoneHVAC:Baseboard:Convective:Electric

zhva

ZoneControl:Thermostat

zct

ThermostatSetpoint:SingleHeating

tssh

ThermostatSetpoint:SingleCooling

tssc

ThermostatSetpoint:DualSetpoint

tsds

AirTerminal:SingleDuct:Uncontrolled

atsd

AirTerminal:SingleDuct:VAV:Reheat

atsd

ZoneHVAC:AirDistributionUnit

zhva

ZoneHVAC:UnitHeater

zhva

ZoneHVAC:HighTemperatureRadiant

zhva

ZoneHVAC:EquipmentList

zhva

Fan:VariableVolume

fvv

Fan:OnOff

foo

Fan:ConstantVolume

fcv

Fan:ZoneExhaust

fze

Coil:Cooling:DX:SingleSpeed

ccdx

Coil:Heating:Electric

che

Coil:Cooling:DX:TwoSpeed

ccdx

Coil:Heating:Fuel

chf

CoilSystem:Cooling:DX

cscd

Controller:MechanicalVentilation

cmv

Controller:OutdoorAir

coa

AirLoopHVAC:Unitary:Furnace:HeatCool

alhv

AirLoopHVAC:ControllerList

alhv

AirLoopHVAC:UnitaryHeatCool

alhv

AirLoopHVAC

alhv

AirLoopHVAC:OutdoorAirSystem:EquipmentList

alhv

AirLoopHVAC:OutdoorAirSystem

alhv

OutdoorAir:Mixer

oam

AirLoopHVAC:ZoneSplitter

alhv

AirLoopHVAC:SupplyPath

alhv

AirLoopHVAC:ReturnPlenum

alhv

AirLoopHVAC:ZoneMixer

alhv

AirLoopHVAC:ReturnPath

alhv

Branch

b

BranchList

bl

NodeList

nl

OutdoorAir:Node

oan

AvailabilityManager:Scheduled

ams

AvailabilityManager:NightCycle

amnc

AvailabilityManagerAssignmentList

amal

SetpointManager:Scheduled

sms

SetpointManager:SingleZone:Reheat

smsz

SetpointManager:MixedAir

smma

WaterHeater:Mixed

whm

WaterUse:Connections

wuc

WaterUse:Equipment

wue

Curve:Quadratic

cq

Curve:Cubic

cc

Curve:Biquadratic

cb

Controller:OutdoorAir

coa

AirLoopHVAC:ZoneMixer

alhv

OutdoorAir:Node

oan

WaterHeater:Mixed

whm

EnergyManagementSystem:Sensor

emss

EnergyManagementSystem:Actuator

emsa

EnergyManagementSystem:ProgramCallingManager

emsp

EnergyManagementSystem:Program

emsp

EnergyManagementSystem:InternalVariable

emsi

PlantEquipmentList

pel

PlantEquipmentOperation:HeatingLoad

peoh

PlantEquipmentOperationSchemes

peos

PlantLoop

pl

Output:Table:Monthly

otm

Connector:Splitter

cs

Connector:Mixer

cm

ConnectorList

cl

Pipe:Adiabatic

pa

Pump:ConstantSpeed

pcs

LifeCycleCost:Parameters

lccp

LifeCycleCost:NonrecurringCost

lccn

UtilityCost:Tariff

uct

UtilityCost:Variable

ucv

1.2. 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.2.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.2.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 get_eplus_dirs, IDF
>>> eplus_dir = get_eplus_dirs("9-2-0")  # Getting EnergyPlus install path
>>> eplus_file = eplus_dir / "ExampleFiles" / "BasicsFiles" / "AdultEducationCenter.idf"  # Model path
>>> weather = eplus_dir / "WeatherData" / "USA_IL_Chicago-OHare.Intl.AP.725300_TMY3.epw"  # Weather file path
>>> idf = IDF(idfname=eplus_file, epw=weather)  # IDF load
  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_json()