The history of jEPlus
How it started
Our work on this GUI for parametric simulations was actually started in early 2007, with jCFX5, a shell for ANSYS CFX (a commercial CFD package). By that time we were trying to automate 'virtual experiment', such as rotating the geometry of a human body in a wind tunnel or testing control strategy of natural ventilation etc. Admittedly, CFX is a lot harder to wrap-up than E+, because it is not naturally based on input text files. There has not been any further development on jCFX5 since 2009. However, the last release is still functional if anyone cares to try.
During that period (2007-2010), there were quite a few active E+ users in the Institute, such as Sherif, Ivan, Stefan, and Stephen. They all learned E+ the hard way, i.e. spending weeks and weeks reading IDF files with only the manual to consult. They used to have meetings together, just to share learning experience and methods to make the IDFs a bit more manageable - for example, a Post-it-based HVAC system builder was rather popular at a time.
The studies they were doing had some striking similarities: Sherif was on mixed ventilation and passive cooling strategies, Ivan on HVAC systems in office buildings, Stephen on heatwave adaptation strategies for dwellings, and Stefan on future climatic scenarios, i.e. a parametric study is the method in common. This prompted the development of jEPlus. Ivan and Stephen managed to actually use jEPlus in their studies, which can be found in their respective theses: Korolija I. (2011) HVAC system energy demand coupling with building loads for office buildings and Porritt S. (2012) Adapting UK Dwellings for Heat Waves.
The original plan was to build and expand jEPlus' functions to sensitivity analysis and optimisation. Well, like many other plans, the form and schedule of the final deliverable are all changed beyond recognition during the process. But, at least, all the original goals are achieved, albeit 7 years later than planned. There is even a new company came out it!
People
jEPlus, jEPlus+EA and the latest ENSIMS Web Service platform have been developed primarily by Dr Yi Zhang. Many people contributed to the projects over the years, notably Dr Ivan Korolija with testing, example projects and tutorials from the beginning, and Mr Jose Santiago Villar with the development of TRNSYS support.
The users of jEPlus really helped the tool to grow. The original discussion boards are disused but still accessible here: Q&A section on jeplus.org and the jeplus forum site. Many research papers and reports can be found using or mentioning jEPlus and jEPlus+EA tools. Some of them are collected on the publictions page.
Version history
v2.1.0, September 2020
New features, enhancements and changes:
Scanning multiple EnergyPlus installations in a folder
Generic script language support, where user can specify the interpreter and the command-line to use *any* scripting language with jEPlus
Explicit options to write a jobs list file and perform preparation, simulation and result collection/post-processing steps
-
*tools.json file contents have changed*
Timeout TRNSYS execution in case of simulation error
v2.0.0 Beta, November 2019
New Features and enhancements:
jEPlus project file format changed to JSON
Select and store information of multiple EnergyPlus versions
New Result Collection tab for editing RVX information
Improved consistency such as detecting project changes
Internal script engine changed to JavaScript
New example project showing various parameter definitions and result collection options
Jython library is removed
Branching parameter tree is no longer supported
v1.7.2, May 2018
New Features and enhancements:
v1.7.0 Beta, September 2016
New Features and enhancements:
Python for pre-processing with @python? syntax
Sobol sampling
Added exponential and log-normal distributions
New dialog for configuring external programs
v1.6.3, March 2016
New Features and enhancements:
Editor panel checks JSON validity
Defining RVX for TRNSYS project (for supporting jEPlus+EA)
Redesign of the User Supplied Spreadsheet object in RVX, to include a default value and the first match rule
Bug fixes:
Corrects various issues with TRNSYS support
Corrects the RVX CSV function locating “Report name” before “Table”
Corrects the issue that “Used in Calc” switch in some RVX objects was not working
Corrects a bug in RVX Constraint scaling implementation
Corrects the handling of quotes (“”) in the job list file
v1.6.0, August 2015
New Features and enhancements:
Project files now use relative paths by default
Import/export project in JSON format
jEPlus command-line executes JSON project directly
Jython is used as the script engine to handle in-line calculations (e.g. in the @calc syntax and RVX)
RVX enhancements - specify report frequency in RVI objects and option to include extracted CSV table in the combined table or not
RVX enhancements - read E+ tabular reports in CSV format, partially replaces the need for SQLite output
RVX enhancements - changes in Python script arguments
Improved Run Python utility for testing scripts and post-processing
Jython supports updated to 2.7
Menu commands for launching JESS Client and jEPlus+EA with the current project
Importing parameter definitions from CSV now handles “” correctly
Various bug fixes
v1.5.2, June 2015
v1.5.1, December 2014
v1.5 Beta, September 2014
New Features:
@calc() syntax in parameter definition allows values to be calculated from a formula
New Python script executor
GUI for running your own postprocessing scripts (see included examples)
Extended RVI (.rvx) file for customizing result collection
Calls Python scripts for post-processing during result collection
Calculate user-defined variables after result collection
Combined results table generated by default
New text editor with syntax highlighting that works well with large model files
Additional tools organized on the Utilities tabs
Run Python script for further analysis
Added support for INSEL 8
IDF version converter shell for easily updating projects to later E+ versions (Windows only)
v1.5 preview, October 2013
v1.4, June 2013
Support combinatorial parameters, i.e. parameters containing two or more search strings and the corresponding value sets
Parameter definitions can be imported from and export to a CSV-styled text file, making the task of editing large number of parameters easier
Extracts simulation results from both ESO (using ReadVarsESO) and tabular (using SQLite) outputs
Result files can be merged into a single table, and openned directly in the associated program for CSV (e.g. Microsoft Excel) from the
GUI
Complete overhaul of command-line options
-
Bug fixes.
v1.3, August 2012
jEPlus now supports TRNSYS parametrics!
Latin Hypercube Sampling (LHS) is implemented, supporting Gaussian, Uniform, Triangular and Discrete distributions.
Resource and progress monitor is shown when running simulation jobs. It helps users keep an eye on memory and disk space during large parametrics. The monitor also allows you to pause and resume a batch, as well as throttling number of threads on-the-fly.
Project validation function has been revised. It can now handle practically infinite sized projects.
Post-process function provides a link between E+ and TRNSYS parametrics. This feature is experimental.
Various improvements to
GUI.
Bug fixes.
v1.2, December 2011
Improved memory usage. You can now create a job batch in excess of 1 million jobs.
Better handling of directories. You can now (manually) specify relative directories for weather, IDF, RVI and output files. In this way, you can put all files in one folder and move it to another location; and everything should still work.
New feature for importing parameter definitions in a CSV-styled table. When you have many parameters, it is offen a pain to edit the parameter tree in the
GUI. You can now import them from CSV-like text file, and a single-branch parameter tree will be generated from these parameters. See “examples/parameters.csv” for an example.
Exporting a project to an .obj file, which can then be loaded using a different mechanism. This is required if you want to use jEPlus with Matlab at programming level.
Batch job result now contains an index file, in which parameter values of each job are listed against the job ids.
Various
GUI improvements, including adjustable left-right pane layout.
v1.1, July 2011
Improved IDF editor tab. The editor now reads search strings in the current jeplus project and locate them in the IDF file on opening. It also highlights E+ macro commands and the version line.
On the post-process tab, you can now obtain simple stats (mean, variance, min and max) from the simulation results of the project.
Other tweaks to the
GUI, including improved checking of unsaved changes.
v1.0a, May 2011
Command-line interface to run selected jobs. There are four ways to specify jobs to execute. Try “java -jar jEPlus.jar -help” for more details.
Improvement on jEPlus' memory usage when processing large projects
-
v1.0beta, February 2011
Many improvements made to
GUI
jEPlus project file (.jep) in XML format
Select and run a subset of the project by freezing parameters on selected values
Support for parameter value sampling with uniform or normal distributions
Support for loading parameter values from an external text file
Three 'test run' methods – the first job of each parameter chain; the first m jobs of the whole project; and the random samples (n jobs) of the whole project
Post-process tab allows extracting a different set of results from E+ outputs without re-running the simulations
Miscellaneous issues resolved
v0.5, October 2009
UI layout change to support smaller screens (1024×768)
Stores information of local E+ installation
Support for EP-Macro (macro preprocessing) and HVACTemplates
Support for .IMF and .MVI file extensions
SQL script for collecting indices and E+ execution information
Improved validation failure feedback
Default settings and examples are now for E+ 3.1.0
Options to remove E+ temporary files
Improved user manual
Miscellaneous
GUI issues resolved
v0.1, July 2009
Complete
GUI provide setting up parametric runs with E+
Unique parameter tree for defining dependency between parameters
Flexible syntax for specifying alternative values
Supports multi-processor/multi-core systems by threading
Supports Windows/Mac/Linux versions of E+
In-built IDF editor supports basic syntax highlighting and incremental search
Simulation results are collected in CSV format (using ReadVarsESO) with index files
jCFX5 is still available to download.