The history of jEPlus

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!

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.

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
• Improvements to the GUI
• *tools.json file contents have changed*
• Timeout TRNSYS execution in case of simulation error

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

New Features and enhancements:

• Python pre-processing works with TRNSYS projects
• Added “fromFor” in the CSV extraction options of RVX
• Tidy-up example projects
• Various bug fixes

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

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

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

Bug fix release:

• Unordered List ItemReadVarsESO fails if the RVI file path contains spaces

Bug fix release:

• Fixed the issue that previous results in the output folder are not overwritten by the new simulations in certain circumstances
• Fixed an error in passing arguments to Python scripts in post-processing

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)

• New version converter GUI supports the E+ version updaters
• New Python script executor GUI for running your own postprocessing scripts (see included examples)
• Experimental support for INSEL 8
• Fixed a bug in TRNSYS project result collection.

• 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
• Improvements to the GUI
• Bug fixes.

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

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

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

• 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
• Some tweaks of the GUI

• 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

• 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

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