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.
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.
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
Gains
Internal thermal gains such as “people”, “lights” and “equipment” are translated from the IDF file to the BUI file.
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\)
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
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.17archetypal 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 namesarchetypal 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” messagearchetypal 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¶
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.
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
Create a BuildingTemplate Object
>>> from archetypal import BuildingTemplate
>>> template_obj = BuildingTemplate.from_idf(
>>> idf, DataSource=idf.name
>>> )
Create an UmiTemplateLibrary Object and Save
>>> from archetypal import UmiTemplateLibrary
>>> template_json = UmiTemplateLibrary(
>>> name="my_umi_template",
>>> BuildingTemplates=[template_obj]
>>> ).to_json()