Chapter 9 jEPlus CLI & Project Composition

Version 2.2, © 2024 Energy Simulation Solutions Ltd

In addition to using jEPlus as a standalone GUI application for running parametric studies, you can couple your own scripts or programs using its command-line interface (CLI) and use it as a simulation manager to perform certain tasks with or without the GUI. In this chapter, we detail the jEPlus CLI and discuss how to compose and modify jEPlus projects without the jEPlus GUI.

In a terminal or command prompt window, type the following command:

java -jar jEPlus.jar -help

It will show the information about the available command-line options for jEPlus as below.

usage: java -jar jEPlus.jar [OPTIONS] {project file (.jep or .json)}
 -all                                Execute all jobs in project
 -file <job list file>               Execute selected jobs in project using a
                                     job list file. Effective only if a project
                                     is specified
 -help                               Show this message
 -id <job ids>                       Execute selected jobs in project using
                                     specified job id strings. Effective only if
                                     a project is specified
 -index <job indexes>                Execute selected jobs in project using
                                     specified parameter value indexes.
                                     Effective only if a project is specified
 -job <project file>                 Open project file in either XML (.jep) or
                                     JSON (.json) format
 -lhs <sample size>                  Execute a Latin Hypercube sample in
                                     project. Effective only if a project is
                                     specified
 -out <output folder>                Use the specified folder for outputs. If
                                     relative form is used, it is relative to
                                     the location of the project file
 -parallel <number of threads>       Use specified number of local threads for
                                     parallel simulations. If a non-possitive
                                     number is supplied, all available processor
                                     threads will be used.
 -seed <random seed>                 Use the given random seed for sampling. If
                                     seed is not specified, jEPlus uses the seed
                                     saved in the project. This option is
                                     effective only with -shuffle, -lhs and
                                     -sobol
 -shuffle <sample size>              Execute a random sample in project. Project
                                     size limit applies. Effective only if a
                                     project is specified
 -sobol <sample size>                Execute a Sobol sample in project.
                                     Effective only if a project is specified
 -timeout <TRNSYS timeout seconds>   Timeout setting for TRNSYS only. In case of
                                     simulation error, the the job will be
                                     terminated after the set amount of time.
 -value <job values>                 Execute selected jobs in project using
                                     specified parameter values. Effective only
                                     if a project is specified

This might not be easy to understand if you are not familiar with CLIs. The purpose of the command-line interface, or CLI in short, is to instruct the program to perform certain tasks at launch without using the controls on its GUI. For example, instead of using the command java -jar jEPlus.jar to launch the program and then open a project file by clicking through the menu, you can start the program with the project already loaded using the following command:

java -jar jEPlus example_1-params_E+v9.2/project.json

Of course, the main point of a CLI is to let you execute a project without showing the GUI at all. We will see some examples next.

To execute all jobs of a specified jEPlus project without the GUI, you should use the -all option. The -parallel option specifies how many parallel simulations to run, two in this case. If omitted, jEPlus will use all the processor cores/threads your computer has. The -out option specifies where the output folder should be. If a relative path is used, as in the example, it is relative to the location of the project file. If the output folder does not exist, jEPlus will create it.

java -jar jEPlus.jar -all -parallel 2 -out ../output/ example_1-params_E+v9.2/project.json

There are three options to execute a random sample of the specified jEPlus project: -shuffle, -lhs, and -sobol, which correspond to the three sampling methods supported by jEPlus. The argument follows the option is the desired sample size. The -seed option specifies a seed for the random number generator. If two sampling runs have the same positive number as the random seed, the sampled cases will stay the same. In this example, jEPlus will use all available processer cores and write to the output folder defined in the project, as the -parallel and -out options are omitted.

java -jar jEPlus.jar -lhs 30 -seed 1234 example_1-params_E+v9.2/project.json

The jEPlus CLI lets you run a specific set of jobs (as opposed to random sampling) as defined in the project or “arbitrarily”, using four different options: -id, -index, -value and -file.

The -id option instructs jEPlus to execute the jobs of the given job_id, e.g. EP_0-T_0-W_1-P1_5-P2_3-P3_3-P4_0-P5_7. This option only works with smaller projects where the number of parameters is fewer than 7. Its use case is probably rerunning the selected cases in a project, or doing one-at-a-time sensitivity analysis.

java -jar jEPlus.jar -id EP_0-T_0-W_1-P1_5-P2_3-P3_3-P4_0-P5_6;EP_0-T_0-W_1-P1_5-P2_3-P3_3-P4_0-P5_7 example_1-params_E+v9.2/project.json

The -index option means that jEPlus should take parameter values at the specified indexes for the parameters. The effect is very similar to that of the -id option, though much less restrictive. It also allows you to specify your own job names. Please note the first two indices are for selecting the weather file and the model template, respective, which is NOT the same order as in -id. The following command-line runs the same two cases as the previous example, but with different job names.

java -jar jEPlus.jar -index “job0,1,0,5,3,3,0,6;job1,1,0,5,3,3,0,7” example_1-params_E+v9.2/project.json

The -value option offers a lot more flexibly than the two above, as the simulation cases you can run are no longer bound by those defined in the project. The argument passed to the -value option is a list of parameter values headed by a job name. Multiple jobs are separated by semi-colons (;). More details of the composition and the limitations of the job string in this form are discussed in the next section.

Again, the command-line below runs the same two cases as above and with custom job names.

java -jar jEPlus.jar -value “job0,weather/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw,HVACTemplate-5ZoneBase.imf,315,0.010,0.025,7.3,PackagedVAV;job1,weather/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw,HVACTemplate-5ZoneBase.imf,315,0.010,0.025,7.3,PTAC” example_1-params_E+v9.2/project.json

The flexibility of the -value option also brings about the issue of long command-lines. The solution is to put the job strings in a text file and then run them using the -file option as below.

java -jar jEPlus.jar -file joblist.txt example_1-params_E+v9.2/project.json

More details of the composition and the limitations of the job strings and the job list file are discussed next.

A jEPlus job string may take the following form:

{job ID},{name of weather file},{name of building model}, {value of parameter 1}, {value of parameter 2}, …;

Or use indexes for the weather file and the building model, and values for the parameters:

{job ID},{index of weather file},{index of building model}, {value of parameter 1}, {value of parameter 2}, …;

in which, the job ID is a unique string assigned to the job; the index of weather file or building model is a zero-based sequential number of the selected file in the corresponding list in the jEPlus project. The parameter value must be the actual value you want to the parameter to take but is not limited to the alternative values specified in the jEPlus project.

A job list file is a text file containing lines of job strings. It is a very useful instrument for making jEPlus to run specific jobs defined by another program, e.g. Matlab. Below is the content of an example job list file:

G-1_10_1_20, 0, 1, 150, 0.1,  Triple_6-13_LoE66_Clr_Air
G-2_6_4_17,  0, 2, 90,  0.25, Triple_4-12_LoE_Ar
G-4_23_1_21, 0, 4, 345, 0.1,  Triple_6-13_LoE66_Bronze_Air
G-1_6_3_18,  0, 1, 90,  0.2,  Triple_6-13_LoE55_Clr_Air

Each row starts with a unique job id (of your choice), followed by the index of weather file, the index of IDF file, and then, parameter values. Fields are separated by ',' (comma). In the above example, there are 3 different parameters in the project.

Once you have prepared the job list file, you can execute the jobs it contains using either jEPlus GUI or through its CLI.

If some of the parameters use the @calc and @script syntax, you must use their parsed forms, as shown in the preview box in the jEPlus GUI, in the job list file. For example, if parameter P2 is defined as @calc(P0+P1), its parsed form would thus be ?=@@tag0@@+@@tag1@@. And, if parameter P3 is defined as @script(python3, myscript.py, P2, 78.9), its parsed form should be call(python3, myscript.py, @@tag2@@, 78.9). To specify them in a job list file, it would look like the following:

job00, 0, 1, 150, 0.1, ?=@@tag0@@+@@tag1@@, call(python3, myscript.py, @@tag2@@, 78.9)

[Under construction]

The JSON format that jEPlus projects use is super easy to handle and is very well supported by many languages. It is fairly trivial to create and modify a jEPlus project without the GUI. What's more, there are a few ways to externalise certain parts of the project, such as:

• the parameter values, through a job list file
• the parameter definitions, through a parameter definition list file
• the result collection object, through a separate RVX file

[Under construction]

(We will show a few examples of how you can run jEPlus projects from Matlab and Excel…)