jEPlus+EA: jEPlus optimisation tool

(This page is currently under revision)


For anyone who wants to find the best solution of a problem, the very first approach comes to mind is testing all possible options, i.e. using brute-force search (or exhaustive search). Parametric study and full factorial design are also used to refer to this approach. Although “the best” solution is guaranteed, there is a catch with brute-force search, cost.

The above example has 20 design variables, each has a handful of options. As a result, the total design space is over one trillion! Assuming each simulation takes only 1 minute, to complete a brute-force search on the IESD's 256-core cluster will take 7,600 years. It will be too late for the project meeting with the client, that's for sure. Using a proper optimization algorithm is the only feasible option. This is why jEPlus needs EA for solving real world problems.

What's special about jEPlus+EA?

There are a number of optimization tools/packages available for EnergyPlus users. Most notable is GenOpt, which has been around since 1998. GenOpt employs a very flexible mechanism to couple with simulation programs and user-written search algorithms. Here is a schematic of GenOpt (from the GenOpt website):

Since all interactions between the GenOpt core and the simulation program are definable using text files, it can be coupled, by user, with practically any simulation tools that have command-line interface and use text files for input and output. GenOpt is shipped with examples for running simulation with EnergyPlus, TRNSYS, IDA, Dymola, Java classes, and shell scripts. On the other hand, there is a bit of initial learning curve. A user has to familiar himself with GenOpt configuration files before he can use it for the job. This presents a problem for casual users, because spending an hour each time to figure out what controls what can be a pain.

It is of course possible to use generic tools for EnergyPlus optimization, for example, MATLAB's Global Optimization Toolbox; or indeed, write your own optimization algorithms. The problem, again, is the initial effort you have to put in to make the coupling work, in addition to that you need to be fluent with MATLAB or your chosen programming language in the first place.

jEPlus+EA is designed with an aim to remove the barrier to entry into the field of optimization, for existing jEPlus users at least. If you have already got a jEPlus project, you can use jEPlus+EA (almost) out of the box, and see optimization results extremely quickly. There is very little configuration you will have to do. The necessary controls are (or will be) provided on the GUI. For example, you can control the population size, crossover rate and mutation rate on-the-fly, as well as manage your computing resources for the job.

What are the limitations?

For tools, there is often a trade-off between ease-of-use and versatility. jEPlus+EA sacrifices much in functionality, in order to hide the complex configurations from end users. However, we will keep improving the tool, so please do let us have your requests and comments.

Objectives, constraints and variables

jEPlus+EA can only use parameters defined in a valid jEPlus project as variables. This means all variables are considered as discrete during optimization. If a jEPlus project parameter tree has multiple branches, only the first branch will be used for optimization.

jEPlus+EA takes raw output (SimResults.csv) from jEPlus as objectives. These are the values you extract from EnergyPlus simulation using the .RVI file, i.e. you can only have what EnergyPlus can report as objectives. If there are multiple lines of results for each job in SimResults.csv, only the last row will be taken into account. jEPlus+EA has multi-objective and single-objective modes. In the multi-objective mode, all EnergyPlus output variables collected in SimResults.csv are considered as separate objectives. In the single-objective model on the other hand, the objective value is calculated as the arithmetic sum of all reported EnergyPlus variables in SimResults.csv. It is not yet possible to define your own objective function(s).

jEPlus+EA does not yet consider constraints. The next version of jEPlus+EA may allow you to define objectives and constraints. In the meantime, however, it would be possible to use EnergyPlus' EMS functions to calculate and report required objective values.

Optimization algorithms

For multi-objective optimization, NSGA2 with elitism that keeps all non-dominated solutions in the population. In each generation (or Epoch), a number of new solutions will be evaluated. The number is defined by the population size parameter. The algorithm uses integer-encoding, which is pertinent to the parametric space defined by jEPlus projects. Hybrid crossover and mutation operators are used. However, only the overall crossover and mutation rates can be controlled by the user. The algorithm seems to work well on the problems we have tested so far.

How to run jEPlus+EA?

Firstly, unpack the downloaded zip package into a folder, and then copy an existing jeplus.cfg (which contains the location of EnergyPlus executables) to the folder. Alternatively, run run-jEPlus.bat once and located the EnergyPlus executables. A jeplus.cfg will be generated when you close the program.

There are a few things you need to do to make a jEPlus project work with jEPlus+EA:

  1. Put all required files of a jEPlus project, with the project file (.JEP) itself, in one folder, and rename the project file to project.jep
  2. Open the project in jEPlus, and charge all paths in the project to relative form, relative to the location of project.jep.
  3. Validate the project and test run a few jobs to make sure everything works. Save the project.
  4. Edit the run-JESS_MO.bat or the run-JESS_SO.bat, so it points to your project folder that contains the project.jep.
  5. Alternatively, run
    java -Xmx1000m -jar jEPlus+EA.jar "your_project_folder"

    from the command-line.

  6. Use
    java -Xmx1000m -jar jEPlus+EA.jar -help

    for more options.

Input, output and GUI features

The GUI of jEPlus+EA is fairly straightforward (see screenshots below). One thing to note is that all options to the side of the chart are for customizing the chart only. It does not affect the optimization process in any way. For example, you can put in a conversion factor (a multiplier) for values shown on the Y axis, to convert the unit show on the chart.

There are in fact a few configuration files you may want to check out. The EA_jEPlus.set file controls the optimization algorithm, including its output. The chart.cfg file records any customized settings for the charts. And the log4j.cfg specifies the log file.