meta data for this page

jEPlus User's Manual

Version 2.1, © 2019, 2020 Energy Simulation Solutions Ltd

Disclaimer

jEPlus v2.x (the software) is provided by Dr Yi Zhang free of charge for commercial or non-commercial use. It is provided on the basis of “as is”. Any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall Dr Yi Zhang or his employer be liable for any direct, indirect, incidental, special, exemplary, or consequential damages, (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software.

The software is released under the free, copyleft license GPLv3. The use of the software is done at your own discretion and risk and with the agreement of the foregoing disclaimer.

New Features

The new changes in jEPlus introduced in Version 2.1 include:

  • Using JSON formation for both jEPlus project files and the jEPlus configuration file
  • Improved consistency such as detecting project changes
  • Generic script language support, where user can specify the interpreter and the command-line to use *any* scripting language with jEPlus
  • Internal script engine changed to JavaScript
  • New example project showing various parameter definitions and result collection options
  • Branching parameter tree is no longer supported. Instead, you should use combinatorial parameters and/or Python preprocessing to achieve special designs
  • Timeout TRNSYS execution in case of simulation error
  • GUI Improvements:
    • Tidying up and some of the long-standing glitches fixed
    • New Result Collection tab for editing RVX information
    • Scanning multiple EnergyPlus installations in a folder; select and store information of multiple EnergyPlus versions
    • Explicit options to write a jobs list file and perform preparation, simulation and result collection/post-processing steps

Installation

The jEPlus v2.x program is distributed as a zip archive containing the main Java JAR binary, supporting files and example projects. You can download the distribution package from here:

https://sourceforge.net/projects/jeplus/ (Source code is hosted on GitHub)

To run jEPlus v2, you need:

  1. A computer supports EnergyPlus or TRNSYS, and Java Standard Edition Version 8, with a display of at least WXGA resolution (1366×768)
  2. Download and install Java Runtime Environment 8 (JRE 8, from www.oracle.com)
  3. Get and install the desired version of EnergyPlus; take note of where it is installed on your HDD
  4. Download the latest jEPlus package from sourceforge, and extract its contents to a folder
  5. Launch jEPlus by either using the included batch/shell script file or double-clicking on jEPlus.jar.

Table of Contents

Chapter 1 Introduction – This chapter describes how jEPlus works with diagrams, and explains some of the key concepts and terminologies used in this users guide. Also covered are the things you need to know about installing the software.

Chapter 2 The GUI – Description of the graphical user interface, including the menu structure, the project tab, the result collection tab, the execution tab, the utility tab, and the output/editor pane. Controllable elements are annotated on the screenshots.

Chapter 3 The Project File – This chapter explains the contents of a jEPlus project file, its format, and the tools can be used to edit the file.

Chapter 4 Parameter Definition – This chapter is all about the jEPlus parameter definitions, including the syntax you can use to specify the parameter values, and some tips about what can be defined as a parameter in EnergyPlus.

Chapter 5 Result Collection – jEPlus v2.x introduces a new GUI tab for editing result collection options specified in the RVX object. The use of ReadVarsEso, SQLite, tabular outputs, TRNSYS printers, user-supplied table, scripts and user-defined metrics for result collection/post-processing are explained. Also described are the output files of jEPlus, such as the aggregated result table and the user metrics table.

Chapter 6 Running Simulations – The simulation execution options jEPlus provides are described in this chapter. You can test and run a jEPlus project in various ways, such as using random sampling. The control of computing resource is explained here, too.

Chapter 7 Utilities – jEPlus includes a few utilities to help you prepare your project and extract/post-process results. These utilities include an EnergyPlus version updater shell, a script tester/executor, and an E+ ReadVars executor.

Chapter 8 Using Scripts in jEPlus – You can use different script languages in various ways with jEPlus v2.1. This chapter summarizes how to use Python scripts in pre-processing and post-processing stages, and information on how to test your scripts in jEPlus.

Chapter 9 jEPlus CLI – For advanced users, the command-line interface and the programming interface of jEPlus are explained in this chapter. Also covered is the use of the job list files, and how to run jEPlus projects from other programs such as Matlab and Excel (under construction).

Chapter 10 Examples and Command Questions – A few examples are described in this chapter, including the use of EP-Macro, and the different ways to parameterize window size. Also a Q&A section including some of the most commonly asked questions. [to be updated]

Contact

I hope you enjoy using jEPlus. Should you have any questions relating to the use of jEPlus, please post them on Unmet Hours with the tag #jeplus. To report issues and request new features, please use jEPlus' Github project pages. Some previous questions and answers are available on the jeplus forum, although it is closed to new registrants due to security concerns. You are also welcome to contact me directly by email on yi@jeplus.org

References

Please use the following references to cite jEPlus in your works. If you are interested in how the jEPlus and jEPlus+EA tools have been used in research, here is a list of nearly 200 articles and dissertations that we have found online.

Zhang, Y., Korolija, I (2010) “Performing complex parametric simulations with jEPlus”, SET2010 - 9th International Conference on Sustainable Energy Technologies, 24-27 August 2010, Shanghai, China pdf

Zhang, Y. (2009) “‘Parallel’ EnergyPlus and the development of a parametric analysis tool”, IBPSA BS2009, 27–30 July 2009, Glasgow, UK pdf