EP-Launch is an optional component of the EnergyPlus Windows installation (it is not available for Linux and Mac platforms). For users that want a simple way of selecting files and running EnergyPlus, EP-Launch provides this and more. In addition, EP-Launch can help open a text editor for the input and output files, open a spreadsheet for the postprocessor results files, a web browser for the tabular results file, and start up a viewer for the selected drawing file.
EP-Launch is located in the main directory/folder for EnergyPlus. In addition, it is available on the shortcut menu for EnergyPlus. By double clicking on the EP-Launch icon you get the screen shown above (Figure) for running a single input file. The EP-Launch program simply starts other programs and allows you to avoid having to use the DOS command line prompt to run EnergyPlus. More help is provided for the program under the “Help” menu.
Selecting Input and Weather Files[LINK]
The input file and weather files can be selected on the Single Input File tab from the two pull down lists which show recently used files or you can press the “Browse…” buttons to locate an input or weather file that you have created yourself. If this is your first time using EP-Launch, the pull down lists will show some files from the ExampleFiles subdirectory. These are not the only examples, use browse to open other example files from the ExampleFiles subdirectory or other EnergyPlus input files.
Running a Single Input File[LINK]
On the Single Input File tab, after you select the weather and input files simply push the “Simulate…” button to start the EnergyPlus building energy simulation engine. At this point a black DOS window should pop up on your screen and show the progress of your simulation. The simulation is complete when the black DOS box closes. The EnergyPlus program black DOS window will show scrolling text as the simulation procedure progresses. If you would like to see these messages more slowly you have two options:
Press the “Control-S” key combination to try to stop the progress and any key to continue.
Under the “View” menu on the EP-Launch program, select “Options” then “Command Window” then check “Pause During Simulation” and this will pause the process immediately after EnergyPlus executes. To continue after the pause, press any key.
If the file contains Parametric objects, the single input file may cause multiple simulations to be performed. If multiple simulations are performed, the output files will be listed on the History tab and will be named with either the file suffixes defined in the input file or with a serial number.
Multiple single input file and group simulations can be started at the same time. On a computer with multiple-processors or multiple-cores, this will enable the simulations to complete more quickly than starting one after another.
Looking at the Results[LINK]
After you have run a simulation and the black DOS window closes, EnergyPlus has completed, and a status message is displayed (see figure below):
This status gives you a quick overview of whether there were warning (should look at), severe (should probably fix) or fatal (must fix) errors in the run as well as the time it took for the simulation to complete. After pressing “OK” from this box, selecting “ERR/EIO/BND Output Files Only” from the “View” menu will display the ERR, EIO, and BND files - useful when errors may have occurred. Alternatively, pressing the F2 function key will display the same three files.
Another way to open files easily is by using the View Results buttons as shown in 29. Two different panels of buttons can be used under View Results, one shown by using the “All” tab on the left edge and by using the “Sets” tab on the left edge. The “All” tab shows all the various files by file extension that can be viewed individually. Files available for view based on the current input file name, are “enabled” (extension names clearly readable).
The figure above shows the same main screen of EP-Launch but with the “Sets” tab selected on the left edge of the View Results section. The buttons on this tab can open many files at the same time and are a shortcut to opening the files that may be commonly used. The Text Output Files, Drawing Files, and Spreadsheets buttons cause several different results files to open at once based on the currently selected Input File. The HTML file opens just the tabular results file if that file was produced (see OutputControl:Table:Style). The buttons labeled as Set 1 to Set 8 allow you to select which sets of files you want to open. Press the “Define” button in order to define the files to view.
When the “Define” button is pressed on the Sets tab of the View Results section of the main screen, the dialog box in the figure above is shown. This allows the files extensions to be selected that would be opened for each of the Set 1 to Set 8 buttons. One or many files can be selected for each of the Set buttons. This allows you to define exactly which files you want opened.
The content of each file extension is listed below. The contents (along with examples) are discussed in the Output Details document.
By pressing the “Text Output Files” button, a text editor will open each of the text output files. Up to 29 files will open, if they exist. Selecting “Single File” from the ‘View’ menu displays a menu of all available output files from which any file can be opened individually. Each file may also be opened with an associated function key. The output files and function key shortcuts are listed below:
Variable - tabulated results in comma, tab or space delimited format (generated by the ReadVarsESO postprocessor) (F4)
ESO - raw report variable output (F5),
RDD - list of output variables available from the run (F6).
MDD - list of output meters available from the run (Shift-Ctrl-F3)
EIO - additional EnergyPlus results (F7),
ERR - list of errors and warnings (F8),
BND - HVAC system node and component connection details (F9),
MTR - raw report meter output (F11),
MTD - list of meter component variables (F12)
METER File - tabulated meter report in comma, tab or space delimited format (generated by the ReadVarsESO postprocessor) (Ctrl-F4)
ZSZ - zone sizing details in comma, tab or space delimited format (Ctrl+F5)
SSZ - system sizing details in comma, tab or space delimited format (Ctrl+F6)
AUDIT - input file echo with input processor errors and warnings (Ctrl+F8)
SLN - output from “report, surfaces, lines” (Ctrl+F9)
DBG - output from the debug command (Ctrl+F11)
SHD - output related to shading (Ctrl+F12)
SVG - HVAC Diagram (Shift+ F4)
EPMIDF - clean idf file after EP-Macro processing (Shift+F5)
EPMDET - EP-Macro detailed output with errors and warnings (Shift+F6)
MAP - daylighting illuminance map (Shift+F7)
TABLE - tabulated report of bin and monthly data in comma, tab or space delimited or HTML format (Shift+F8)
VMRL - drawing file in VRML (Virtual Reality Markup Language) format (Shift F+F11)
DXF - drawing file in AutoCAD DXF format (Shift+F12)
Delight IN - DElight input generated from EnergyPlus processed input (Shift+Ctrl+F4)
Delight OUT - Detailed DElight output (Shift+Ctrl+F5)
Delight ELDMP - DElight reference point illuminance per time step (Shift+Ctrl+F6)
Delight DFDMP - DElight warning and error messages (Shift+Ctrl+F7)
EXPIDF - Expanded IDF when using HVACTemplate objects (Shift+Ctrl+F8)
Group Error - combined error files for a group run. (Shift+Ctrl+F9)
VCpErr - Transition program error file (Shift+Ctrl+F11)
Proc CSV - Simple statistiscs generated from CSVProc (also see Create Statistics File option under View-Options).
EDD - Energy Management System details.
Clicking on the “Drawing File” button will open the generated DXF file if an appropriate viewer has been configured (see Selecting Viewers and Editors below). The DXF file is a CAD format that displays the physical shape of the building being modeled in three dimensions. The “Drawing File” button also opens the HVAC diagram generated with the HVAC-Diagram utility (see Auxiliary Programs).
Clicking on the “Spreadsheets” buttons will open any generated CSV files if an appropriate viewer has been configured (see Selecting Viewers and Editors below).
Viewing the Drawing File without Running a Simulation[LINK]
The “Drawing” button (or the View menu Drawing File option) will automatically run EPDrawGUI if the DXF file does not exist or it is older than the input file. This allows the building geometry to be viewed without running a full simulation. For more information about EPDrawGUI, see the EPDrawGUI section in this document.
Editing the Input Files[LINK]
The input file, called IDF file that is selected from the top pull-down list, can be edited by pressing one of two buttons in the “Input File” area. The “Edit - Text Editor” button will start a text editor and the “Edit - IDF Editor” will start the separate program called the IDF Editor. Remember to save any changes you make in either editor before returning to EP-Launch to run the simulations again.
Command Window Options[LINK]
Pause During Simulation (Unless Minimized) - Stops the progress of the EnergyPlus run at different points. This does not stop the simulation itself but pauses before or after important events as files are copied or utility programs are run. It is usually used only for diagnosing problems with the EPL-RUN batch file. The feature is also described in the Running a Single Input File section above.
Minimize Single Simulation Command Window - For a single input file, minimizes the Command Window that EP-Launch uses to run EnergyPlus. The command window will appear only in the Windows taskbar and the command window will not be visible. You can restore the command window be clicking on the taskbar item labeled “EnergyPlus Process”. This option should be used with caution since you will not see any indication of the simulation being complete other than the “EnergyPlus Process” taskbar item will disappear.
Minimize Group Simulation Command Window - For a group of input files, minimizes the Command Window that EP-Launch uses to run EnergyPlus. This is a good option when working on something else on your computer at the same time as the group of simulations is running since the command window normally becomes the front window each time a new simulation starts. This option prevents the command window coming to the front for each simulation. The command window will appear only in the Windows taskbar and the command window will not be visible. You can restore the command window be clicking on the taskbar item labeled “EnergyPlus Process”. This option should be used with caution since you will not see any indication of the simulation being complete other than the “EnergyPlus Process” taskbar item will not be present.
Number of Simultaneous Processes - Select the maximum number of simulations that should be able to be run at the same time. For a computer with multiple processors or multiple cores, this will allow better utilization of the computers power. The value selected should correspond to the number of processors/cores but higher or lower number can be used as well.
Extra Wide Window - Select this option to make the main EP-Launch window wider. This is useful when files are used with very long file path names.
Alternative layout - Changes the layout of the EP-Launch window to an alternative arrangement of buttons.
Tab Delimited Open with Spreadsheet - Selecting “Single File” and then “Main Results File” from the “View” menu or pressing the F4 function key will open TAB files with the default spreadsheet application rather than the text editor. Comma-separated variable (CSV) is the default setting for viewing tabulated results set in the RVI file. If the user changes the setting for viewing tabulated results to TAB or TXT format, selecting “Single File” and then “Main Results File” from the “View” menu or pressing the F4 function key will open the files in the default text editor. TAB files, when selected, will also be opened by the text editor when the “Text Output Files” button is pressed after a successful run.
Allow More Than 250 Columns - Tabulated data that exceeds 250 columns, the MS Excel maximum, will be truncated to that limit unless “Allow >250 Columns” is selected. Excel versions prior to 2007 were limited to 255 columns in a sheet; later versions allow unlimited number of columns. This limitation may not be true for other spreadsheet programs.
Check VERSION Prior to Simulation - Automatically check the VERSION object in the selected EnergyPlus input file prior to simulation and if it is an older version than the current version will run the Transition program to update the file.
Convert ESO/MTR to IP Units - Runs the convertESOMTR utility program (see AuxiliaryPrograms documentation for more information). This utility will convert the ESO and MTR files into Inch-Pound units. The CSV file created from these files will also be in Inch-Pound units.
Create Statistics File - Runs the CSVProc utility program (see the AuxiliaryPrograms documentation for more information) and creates the -Proc.csv file. This file contains some simple statistics on each variable in the normal CSV file.
Create Batch File to Run EnergyPlus - Traditionally EP-Launch has created a batch file in order to execute EnergyPlus with the various options chosen. This can cause problems with some operating systems, such as Windows Vista, when set to a higher security setting. This option can be unchecked and a batch file is not created when running EnergyPlus instead parameters are passed to an existing batch file.
Run ParametricPreprocessor - When this option is checked, if Parametric objects are present in the file, the ParametricPreprocessor will be run prior to the first simulation and if multiple simulations are needed they will all be executed. See the Auxiliary Programs documentation for details.
Check for Updates to EnergyPlus - When this option is checked, EP-Launch will check every seven days if an update to EnergyPlus or any of the files distributed with EnergyPlus are available to download. If they are available a message will be shown upon start up. You can also manually check by going to HELP .. CHECK FOR UPDATES.
Text Editor Options[LINK]
EP-Launch will start a text editor when editing a IDF file or when viewing many of the results files. The text editor that will be used is shown but can be changed by either pressing the Select button or by pressing the Auto Find button. The Select button allows you to find the text editor of your choice. The Auto Find button will automatically find the program that is associated with the TXT file extension and use that program. Auto Find is invoked the first time EP-Launch is started so that a text editor is available immediately. The most common text editor is NOTEPAD.EXE and is built into Windows but many other text editors are also available.
Drawing Viewer Options[LINK]
The default drawing viewer is the application associated with DXF files. This can be changed to your favorite drawing program by using the Select button then locating the executable file for your favorite drawing software capable of reading a DXF file. The Auto Find button will automatically find the program that is associated with the DXF file extension and use that program. A variety of programs (free of charge) can render DXF files for viewing. The Output Details document lists some of these programs as well as displaying what a DXF rendered file looks like on the screen.
VRML Viewer Options[LINK]
EP-Launch will start a VRML Viewer when a building drawing is created using the Report, Surfaces, VRML option in your IDF file. The VRML Viewer that will be used is shown but can be changed by either pressing the Select button or by pressing the Auto Find button. The Select button allows you to find the VRML Viewer of your choice. The Auto Find button will automatically find the program that is associated with the WRL file extension and use that program. Auto Find is invoked the first time EP-Launch is started so that a VRML Viewer is available immediately. Many other VRML Viewers are available.
EP-Launch will start a spreadsheet program when viewing many of the results files. The spreadsheet that will be used is shown but can be changed by either pressing the Select button or by pressing the Auto Find button. The Select button allows you to find the spreadsheet program of your choice. The Auto Find button will automatically find the program that is associated with the CSV file extension and use that program. Auto Find is invoked the first time EP-Launch is started so that a spreadsheet program is available immediately.
EP-Launch will start a diagramming program to view SVG files from HVAC Diagram. The diagramming program that will be used is shown but can be changed by either pressing the Select button, the Auto Find button, the Use Firefox button or the Use Opera button. The Select button allows you to find the diagramming program of your choice but make sure it is capable of opening SVG files. The Auto Find button will automatically find the program that is associated with the SVG file extension and use that program. Auto Find is invoked the first time EP-Launch is started so that a spreadsheet program is available immediately. Since both Firefox and Opera web browsers can view SVG files, those buttons will select those respective browsers if available.
HTML Browser Options[LINK]
EP-Launch will start a HTML browser program when viewing the tabular results file when HTML is chosen in OutputControl:Table:Style. The HTML browser that will be used is shown but can be changed by either pressing the Select button or by pressing the Auto Find button. The Select button allows you to find the HTML browser of your choice. The Auto Find button will automatically find the program that is associated with the HTML file extension and use that program. Auto Find is invoked the first time EP-Launch is started so that a HTML browser is available immediately.
ESO Viewer Options[LINK]
By default, ESO files are opened with a text editor. ESO files are the raw output file containing results from EnergyPlus for Report Variable objects. They are often processed into CSV files to make it easier to view them. At least one utility program has been developed to view ESO files directly (see the EnergyPlus.gov web site under “Interfaces & Other Tools”, “Third-party EnergyPlus Tools). The Auto Find and Select buttons work the same way as other viewer selectors. If no special ESO viewer is selected the box will be shown as empty. It can also be emptied by using the Clear button.
PDF Viewer Options[LINK]
EP-Launch will start a PDF viewer program when opening the EnergyPlus documentation under the Help menu. The PDF Viewer that will be used is shown but can be changed by either pressing the Select button or by pressing the Auto Find button. The Select button allows you to find the PDF Viewer of your choice. The Auto Find button will automatically find the program that is associated with the PDF file extension and use that program. Auto Find is invoked the first time EP-Launch is started so that a PDF Viewer is available immediately.
File Association Options[LINK]
When installing EnergyPlus, you are given an option if you want IDF, IMF, and EPG files associated with EP-Launch. This allows double clicking on files with those extensions and having EP-Launch start automatically with those files. If during the install that option is not selected or if you have changed the program that opens IDF, IMF and EPG files and want to change it back to EP-Launch, the button for this option will do that.
Two reset options are available here.
The Auto Find All File Viewers button will autofind all the file viewers in one step. This is equivalent to pressing the Auto Find button for each viewer program.
The Reset All Options and Exit button will clear all options and restore the default values used when first invoking EP-Launch for the first time. This also clears the list of recently used IDF and weather files. This option will exit EP-Launch and you will have to start EP-Launch again.
Recently Used Files[LINK]
The recently used input, weather and group file pull down lists can hold a maximum of twenty items. These lists, like the viewers selected, are saved between times you use the EP-Launch program.
Running Groups of Input Files[LINK]
If you are running EnergyPlus on one file or even just a few different files, the easiest way to do this is on the Single Simulation tab. If you are performing an analysis of a building which requires running EnergyPlus for a larger number of times, you may want to consider the Group of Input Files tab, shown below. You may also want to set the Number of Simultaneous Processes option under View Options Command Window so that the simulations are completed as fast as your computer will allow.
This tab lets you manage EPG, EnergyPlus Group files which contain a list of simulations that need to be performed. The EPG file is simply a text file that contains on each line the input file and weather file names to be used for a simulation along with how the output files should be named and a counter.
You do not need to manually create EPG files, instead press the New Group button on the Group of Input Files Tab and a step-by-step “wizard” will help to create a new EPG, EnergyPlus Group file. The first step of the wizard is to selected the EnergyPlus input files that should be simulated as part of the group:
Use the boxes next to each file to select the files to be simulated. The path to files shown may be changed using the “path” button. Once the files in a certain directory are selected the “next” button should be pressed. If additional files are desired in different directories, you will get a chance to add them to the EnergyPlus group file in a later step.
Select one or several weather files using the second step of the wizard, shown below:
The next step is to review the simulations selected. Each combination of weather file and input file is initially shown. Each simulation is displayed as a single row. You may select a row and delete the simulation at this point. In addition, if additional simulations are desired, the “Add more simulations button” brings you back to the first step of the wizard to add more file.
The next step of the wizard allows you to decide exactly where you want the output files located and what they should be named. For most people just trying to group their simulations and wanting the output files in the same directory as the input files, just select “Original Input File Locations”.
More advanced users may choose to define their locations for the output files using symbols that define the name of the directory and file name using:
%I = input file name
%G = group file name
%W = weather file name
%N = repeat number for IMF files
%J = input file path
%H = group file path
%X = weather file path
Each of these symbols may be used in the location field and substitutions will be made for each when defining the output file location.
For macro files (they have an extension IMF instead of IDF) used in a parametric analysis, the macro file may be run repeatedly up to 999 times. Each time they are simulated a new COUNTER.INC file is created which sets a macro parameter. The COUNTER.INC file should be included using the ##include statement in the macro file.
Finally, you can save the EPG, EnergyPlus Group, file wherever you would like.
To run the simulations press the “Simulate Group” button on the Group of Input Files tab. To prevent a specific simulation from being performed, edit the file and use a comment character (an exclamation point) to comment out the line.
When the group of input file simulations is running, the title bar of EP-Launch will show the progress.
History of Simulations Performed[LINK]
The History tab allows you to see what files were associated with a particular simulation that was performed. The list shows the date and time of the simulation along with the input and weather file names.
You can expand the level of detail by clicking on the plus signs or double clicking on the entry. The detail shown includes the names of all the input and output files associated with that simulation along with the message summary of the warnings and errors generated. It is possible that a file may be shown that no longer exists.
The View Files button will display the selected file using a spreadsheet, text editor, DXF file viewer, SVG file viewer, or HTML web browser. When groups of simulations are performed using the Group of Input File tab and User Defined Locations are used for the output files, the history view is the only way to access those files using EP-Launch.
The history tab displays the HISTORY.CSV file that is located in the same directory as EP-Launch. If EP-Launch seems to be starting slowly, it is possible that the history file has grown very large. It may be deleted or renamed and a new history file will be automatically created during the next simulation. The HISTORY.CSV file may also be opened in a spreadsheet program.
The utilities tab shown in the following figure allows several utility programs that come with EnergyPlus to be used directly. More information on each utility is also available in the AuxiliaryPrograms documentation.
For each utility, input files can be selected by using the Browse Button. The input file can be opened using a text editor and, for certain utilities, the IDF Editor. If a weather file is needed for a utility it can also be selected. For other utilities, no weather file is needed and that portion of the screen is not shown. The appropriate output files can be opened by the “Open” button near the bottom of the screen. To run the utility, use the “Run” button in the lower left corner of the screen above the “Exit” button.
In addition, for each utility, a brief description of the function of the utility is shown in the about box but much more information is available in the AuxiliaryPrograms documentation.
Remember to save changes made in the editor before you run another simulation.
The simulation cannot write new results to open files which are locked by another application.
You will need to close the spreadsheet program that views the resulting CSV files prior to another simulation and you may need to close the text editor windows also (depending on your editor).
The EPL-RUN.BAT batch file is used to run EnergyPlus from the EP-Launch program. It can be edited with care if other postprocessors or preprocessors are to be used.
When things go wrong[LINK]
Though EnergyPlus has had several releases (including beta releases prior to initial release), there still may be problems when input files meet with EnergyPlus. If you are using EP-Launch when this happens, you will see a window appear as in the figure below (Figure). Follow the instructions listed on the screen.
The EP-Launch program has been through several “releases” but there is still a chance you will find bugs. Please report them to the email@example.com address so that we can fix them prior to the release.
If the pull-down lists ever are shown as blank the “reset” button may be used. This unlabeled button is very small in the lower left-hand corner of the main screen. It removes the items shown in the recently used file list and causes the program to forget the selected viewers and text editors; and exits the program. When you start EP-Launch again, you will need to make these selections (viewers and text editors) again.