jEPlus+EA v2 Quick Start Guide

Version 2.1, © 2019, 2020 Energy Simulation Solutions Ltd

In this quick start guide, we shall look at how you should prepare the jEPlus project and load it into jEPlus+EA for a sensitivity analysis run and exploring the results.

Let's start with getting and installing jEPlus+EA v2. The program is written in Java and distributed as a zip archive containing the main JAR file, the supporting files and an example project. You can download the distribution package from here:

Get jEPlus+EA v2

Before launching jEPlus+EA v2, you may also need to:

• Download and install Java Runtime Environment 8 (JRE 8) from www.oracle.com. Most PCs and laptops have 64bit operating systems, so make sure you have selected the x64 version of JRE for your OS.

• Get and install the desired version of EnergyPlus or TRNSYS; take note of where it is installed on your HDD.

• If you plan to use scripts, such as Python and R, in your jEPlus projects, install the language platforms and take note of where they are installed.

• If you want to ENSIMS' JESS online simulation service to run EnergyPlus simulations, you need to fill in this form to request a user name and a password. These are different from the ENSIMS web platform account you need to register in the next section.

• Download the latest jEPlus+EA v2 package using the link above, and extract its contents to a folder. The contents of the extract folder should look like those in the screenshot.

• Launch jEPlus+EA v2 by either using the included batch/shell script files. The GUI program can be launched in either jEPlus or jEPlus+EA mode, using the respective batch files run-jEPlus.bat and run-jEPlus+EA.bat. Please note that double-clicking on jEPlus+EA.jar to start the program is NOT recommended.

• Launching the program for the first time, you will see a couple of error messages in the terminal window. This is normal, and the reported missing files will be created automatically.

• Once the GUI is shown, a log-on dialogue will appear, prompting you to put in the email address and the password you have registered on the ENSIMS Web platform. If you haven't done so, please click on Register an account link on the log-on dialogue, which will open a web browser and take you to JEA web portal where you can find a link to create an account.

• The registration process is quick and easy. You only need to provide a valid email address and your name, an activation email will then be sent to your email address. There you can find a link to set the password, after which you will be able to log on to the system. Use this email address and password to connect to JEA service from jEPlus+EA v2.

• If successful, you may see a few projects are already there on the Project List tab. These are the example or other projects shared with you. You can open the existing projects, or start creating new ones.

• Before you can run simulations and scripts used in pre- and post-processing, the external tools including EnergyPlus, TRNSYS and script language interpreters must be configured. Go to the Settings & Logs tab to configure the local programs.

• If you plan to use JESS to run EnergyPlus projects, use the JESS Client option to log on to the service with your JESS account. Note that the JESS account is different from the ENSIMS web platform account. You only need to do this once and the access key will be stored in jEPlus+EA.

jEPlus+EA v2 is built for jEPlus projects. However, in order to make setting up parametric and optimisation analyses easier, you check the following things when preparing the project.

• The jEPlus project is used for running local EnergyPlus or TRNSYS simulations as well as running EnergyPlus simulations remotely on JESS, hence it is important to set it up correctly and tested before going to the next step.

• The parameter definitions and the optional fields of the results extraction options, including Report Variables, Constraints and Objectives, will be imported into jEPlus+EA v2 for creating new JEA projects. These definitions can be edited in jEPlus+EA v2.

• You test the jEPlus project by running simulations on a random sample and checking especially the AllCombinedResutls and the AllDerivedResults tables to make sure that the project is working correctly and collects the results as expected. The LHS sampling method is recommended for testing the project.

Once the jEPlus project is prepared and tested, starting a JEA project is straightforward.

• First, you can open the jEPlus project using the command under the File menu.

• jEPlus+EA will import all the parameters, including the weather file options and the model file options, as the “variables” of the problem definition. The numbers in the square brackets are the effective options and the total options. Check the “Simulation Outputs”, “Constraints” and “Objectives” are consistent with what have been defined in the jEPlus project. Please be aware that the formulae of the constraints and the objectives can only use the variables defined as simulation outputs.

• You can add, edit, disable or remove constraints, objectives and user-defined metrics in jEPlus+EA. These operations will not affect the original jEPlus project.

• Choose what kind of analysis you want to run. The available options are optimisation (using an NSGA2-based algorithm), full-factorial, Monte Carlo simulation (using random sampling), and global sensitivity analysis (using Morris and Sobol methods).

• Fill in some information about this project and the current run. jEPlus+EA and the JEA platform support multiple analyses in the same project.

• When you are ready, use the Create button to upload the project definition and the jEPlus project files to the server. Beware that jEPlus+EA will upload the full contents of the folder containing the jEPlus project file, hence you should clean the folder and keep only the required files before submission.

• If the submission is successful, a new project with your given ID will be created on the JEA platform, and the status will show that the project is “online”, with the Start button enabled.

• If the project is “online” and the Start button is enabled, we are ready to run it. Clicking on the Start button, you will see the status of the project changes into “Initialising”, and the button changes to Pause, which means the JEA platform has started the process of the first run of the project.

• However, jEPlus+EA is not yet running simulations. To do that, you need to check the Simulation Manager area. Choose running simulations locally or using the JESS simulation service. For small models such as the one in the example project, running them locally may be faster. Then, you need to tick the Run checkbox to allow jEPlus+EA to run simulations. This is necessary because the JEA platform allows multiple jEPlus+EA instances connecting to the same project, e.g. one in the office and one at home. It does not know which one would be running simulations, hence the decision is left to the user.

• Once the simulations are going, you can click on the Scatter Plot tab to see the results coming back.

• The project info area shows the status of the project, along with the number of batches (a.k.a. epochs, generations or iterations) and solutions have been explored.

• You can Pause or Resume the project, Stop to terminate the current run, or Reset to clear all the solutions in this run.

One of the advantages of jEPlus+EA and the JEA platform is that you can make on-going changes to many aspects of the project. You can change:

• The effective search space you are exploring, by applying “filters” to the available values of the parameters

• Enable/disable/modify the evaluation metrics such as constraints and objectives on-the-fly

• Change certain algorithms settings, e.g. the population size and the optimisation parameters

• Schedule future runs to perform different analyses automatically

Once you have made the desired changes to the Optimisation Problem and Algorithm Settings, click on the Update button to submit them. You will be given an option to state that the proposed changes should apply to the current run or for setting a future run.

jEPlus+EA v2 provides a number of new ways to highlight and select various groups of solutions using the Scatter Plot tab.

• Hover your mouse pointer over a solution to see a summary of the input parameter values and the output metrics

• The customisable highlighters can be used to select a group of solutions based on their meta data and parameter values

• If you left-click on a solution, you can directly access its model files including the raw simulation outputs

• Other tabs provide means to see the progression of optimisation, show parameter value composition amongst the solutions, and tabulate/export solution data.

Logging onto the https://app.ensims.com/jea_portal.html|JEA web portal, you will be able to use an additional set of visual analytic tools to process the solutions.

• You can control every aspect of the project from the web portal, except running EnergyPlus or TRNSYS simulations

• You can check the raw dataset and see how the JEA platform works

• You can use the “cross-filter” tool to explore the interaction between inputs and outputs and make useful charts such as histograms, boxplots and bubble charts

• You can get the parallel coordinate chart straightaway

• Once a run is finished, you can use the Sensitivity tab to see how the output metrics are impacted by the input parameters, using the matrix plot, multi-linear regression, and global SA reports.

Since all your project data are online, you can access them from anywhere, using a web browser or the jEPlus+EA v2 program. Using the Project List tab in jEPlus+EA, you can:

• Sort and filter the projects to be shown

• Check status and manage meta info of the projects

• Open, Delete or make a copy (Clone) of a project

• Share your project and/or its results with colleagues, or make it publicly available