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

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.

2. 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

3. Gains

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

4. 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

2. 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

2. Create a BuildingTemplate Object

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

3. Create an UmiTemplateLibrary Object and Save

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