Version 2.0, © 2019 jeplus.org
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.
So, how does it work? In a nutshell, you select a building model (an IDF or a set of IMF files) and put search strings in the places of the parameters; specify all 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. In this way, you can quickly set up a large amount of simulation runs to explore the design options.
The following diagrams show a more detailed workflow.
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.
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.
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:
java -jar jeplus.jar
or if you are on a 32-bit operating system, and have a large project (e.g. containing more than a few thousand jobs), use
java -Xmx1000m -jar jeplus.jar