Chapter 1 Introduction

Version 2.1, © 2019, 2020 Energy Simulation Solutions Ltd

Parametric analysis is often needed for exploring design options, especially when a global optimization method is not available, or the optimization result is in doubt. Parametric analysis can also be applied to all design variables simultaneously, which forms an exhaustive search that, on a fine mesh, guarantees the discovery of the global optimum solution. To perform complex parametric analysis on multiple design parameters, a tool is needed to create and manage simulation jobs and to collect results afterwards. jEPlus has been developed for this purpose.

Figure 1.1: The concept

So, how does it work? In a nutshell, you select one or more building models, i.e. IDF/IMF files for EnergyPlus and DCK/BLD files for TRNSYS, with a number of search strings placed inside the models to mark the locations of where the parameter values should go; specify all the alternative values for the parameters in jEPlus; jEPlus will then pick a set of values and put them in the right places in the building model and call EnergyPlus or TRNSYS. In this way, you can quickly set up a large amount of simulation runs to explore the parametric space.

The following diagrams show the process in more details.

Creating simulation jobs list from jEPlus parameters

Once you have defined parameters (their search tags and alternative values used for creating simulation cases), jEPlus parses the parameter definitions and create a (long) list of cases. The process used is recursion through the tree-like structure and listing all possible paths from the root to leaves. Each case contains a unique set of parameter values that will be placed in the model template.

Figure 1.3: From the list of jobs to the simulation case folders: the pre-processing steps

With the list of cases, jEPlus starts to create folders for individual simulation jobs and copies necessary files into the folders. It then uses the parameter values to replace the search tags in the model template in order to create working models for simulation. This actually involves several steps as depicted in the diagram.

Note that the execution of Python scripts defined in special parameters in the jEPlus project is carried out after all search tags have been processed. At this stage, a working in.idf is ready in the case's folder. User's script can apply further operations on the in.idf file, using the arguments defined in the parameter and paths names passed in by jEPlus.

Figure 1.4: Running simulations and collecting results

After the pre-processes, jEPlus will run simulations on each case and wait for the process to complete. Once the simulations are done, it will use the information defined in the RVX object in the project to collect results. The diagram above shows the sequence of result collection and post-processing steps.

jEPlus Project - a jEPlus project contains all the necessary information for a parametric study. This information includes a list of model templates, a list of weather files (for E+), the parameter definitions, the definitions for result collection, and simulation settings such as the working directory, number of processors to deploy, and options to keep or remove temporary files and EnergyPlus outputs. Since v2.0, a jEPlus project is saved in JSON format for improved readability and easy manipulation.

Model template – one or more simulation model files with search strings (see next) inserted at the places for the parameters. For EnergyPlus, the models are IDF (.idf) or IMF (.imf) files. For TRNSYS, they can be DCK (.dck) or TRN (.trn) files. A template must be based on a working simulation model.

Search string – a specially formulated text string (e.g. @@orientation@@) that is not normally occurring in simulation model files. Search strings are used by jEPlus for marking the locations in the model templates in order to insert the values of the parameters at the correct places.

Parameter – a value, a reference or any aspect of the model that can have more than one options. A parameter can be a single design variable (e.g. a temperature setpoint), a component (e.g. the construction of an external wall), a sub-system (e.g. an HVAC system), and even a complete model (the model templates can be regarded as a parameter). If more than one weather files are used, they can be regarded as a parameter, too.

Simulation case (job) – jEPlus picks a model file and the associated files and replaces the search strings with a selection of parameter values, to create each simulation case. The term 'a job' can refer to a model to be simulated, or the execution of a simulation process.

Job ID - Each simulation case generated by jEPlus is named using a simple convention, such as G_[group/project id]-T_[template id]-W_[weather id]-[parameter 1's id]_[alt value id]-[parameter 2's id]_[alt value id]-…, or LHS-[serial number] in the case of random sampling. A job id is a unique identification of the job within a project. It is also used for naming the output directories of simulation cases.

Simulation batch – a collection of jobs of a parametric study. jEPlus creates batch jobs according to the batch configuration defined by the user and systematically names each job before carrying out simulations with EnergyPlus/TRNSYS. Several methods are provided for creating a batch that is a subset of all jobs defined by the project.

Execution options - these include the choice of the simulation controller to use (only the local batch controller is provided in this version), the number of processor cores to deploy, the working directory of the project, and options to keep/remove temporary files after the simulation.

Working directory - this is the directory in which jobs are prepared and results/output files are stored. In fact, the Working directory is the parent directory of the individual working directory of each job, named with the job id. After the simulation, results will be collected from individual job directories and saved to a few result files in the Working Directory.

Result collection – after a simulation case is executed, the simulation program (EnergyPlus or TRNSYS) produces a number of output files containing the useful results. jEPlus provide various ways to extract data from these output files. The result collection process is defined by the RVX object in the jEPlus project. More details of RVX and the results tables jEPlus produces can be found in Chapter 5.

jEPlus input files – jEPlus allows you to use a text file as input at various places, such as specifying a list of weather files, a list of model templates, a list of parameter values, a set of parameter definitions, and the selected jobs of a project to execute. These input files are normally comma-delimited text files, although each can have different format requirements. Please refer to the corresponding sections on how to use these files.

Following the steps below to install (well, download and unpack, really) jEPlus:

1. You will need a computer that supports Java (Java Platform Standard Edition 8 only, available from Java Runtime Environment Download) and EnergyPlus (any versions since 2.2.0, available from energyplus.net). In order to use jEPlus, the screen resolution of your computer should be WXGA (1366×768) or higher
2. The jEPlus distribution package, available from SourceForge
3. Unpack the jEPlus package into a folder. (Since jEPlus does not require installation, you can put it on a memory stick and run it on any computer that has Java.)
4. Start jEPlus by either double-clicking on the jEPlus.jar file, using the supplied run.bat and run.sh files, or using the following command in a terminal window:

   java -jar jEPlus.jar

   or if you are on a 32-bit operating system and/or a 32-bit Java Runtime (installed an x86 instead of the x64 variant), and have a large project (e.g. containing more than a few thousand jobs), use

   java -Xmx1000m -jar jEPlus.jar

5. Your EnergyPlus models or test it with the example projects provided.