Chapter 9 Interface with jEPlus

Version 1.7, © 2015 jeplus.org

Once the jEPlus project has been created and tested successfully, it can be saved as a text file in XML format, which is editable with a text editor. jEPlus can then be launched by a shell command, or via its programming interface.

The shell command:

java -jar jEPlus.jar -help

gives you the following instructions:

usage: java -Xmx1000m -jar jEPlus.jar [OPTIONS]
 -all                          Execute all jobs in project
 -cfg <config file>            Load jEPlus configuration file.
                               Default=./jeplus.cfg
 -file <job list file>         Execute selected jobs in project using a job list
                               file. Effective with -job
 -help                         Show this message
 -id <job ids>                 Execute selected jobs in project using specified
                               job id strings. Effective with -job
 -index <job indexes>          Execute selected jobs in project using specified
                               parameter value indexes. Effective with -job
 -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 with -job
 -local <number of threads>    Use specified number of local threads for
                               parallel execution.
 -log <log config file>        Specify the configuration file for logs.
                               Default=./log4j.cfg
 -output <output folder>       Use the specified folder for outputs.
 -sample <sample size>         Execute a random sample in project. Project size
                               limit applies. Effective with -job
 -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
                               -sample, -lhs and -sobol
 -sobol <sample size>          Execute a Sobol sample in project. Effective with
                               -job
 -value <job values>           Execute selected jobs in project using specified
                               parameter values. Effective with -job

Here are some usage examples. To show help on commandline options:

java -jar jEPlus.jar -help		

java -jar jEPlus.jar			

You can start the GUI and load a specified project to begin with, using the following command

java -jar jEPlus.jar -job example_1-params_E+v8.3/HVACTemplate-5ZoneFanCoil.jep

Execute all jobs in the specified jEPlus project without the GUI, using the selected E+ configuration, 2 processor threads, and put output in the designated folder (relative to the project file):

java -jar jEPlus.jar -job example_1-params_E+v8.3/HVACTemplate-5ZoneFanCoil.jep -all -cfg jeplus.cfg -local 2 -output ../output/

Execute a random sample of jobs in the specified jEPlus project, using the selected E+ configuration. All processor threads and the output folder specified in the project will be used:

java -jar jEPlus.jar -job example_1-params_E+v8.3/HVACTemplate-5ZoneFanCoil.jep -sample 15

Execute a LHS sample of jobs in the specified jEPlus project, using the given random seed. The default E+ configuration (jeplus.cfg), all processor threads and the output folder specified in the project will be used:

java -jar jEPlus.jar -job example_1-params_E+v8.3/HVACTemplate-5ZoneFanCoil.jep -lhs 20 -seed 1234567

Execute the selected jobs by parameter index, of the specified jEPlus project:

java -jar jEPlus.jar -job example_1-params_E+v8.3/HVACTemplate-5ZoneFanCoil.jep -index job0,0,0,0,1;job1,0,0,1,0

Execute the selected jobs by job_id, of the specified jEPlus project. Job_ids are those would be generated when executing the whole project. Please note the format is changeable between projects. Jobs will be executed with the default E+ configuration (as defined by jeplus.cfg if present, or E+ v7.2 at the default location if not):

java -jar jEPlus.jar -job example_1-params_E+v8.3/HVACTemplate-5ZoneFanCoil.jep -id EP_0-T_0-W_0-P1_0-P2_2;EP_0-T_0-W_0-P1_5-P2_1;EP_0-T_0-W_1-P1_1-P2_4

Execute the selected jobs by parameter values. Note that jobs are separated by ';', and in each job string, the first field is a unique job id string, followed by the index of the weather file, the index of the IDF file, and then the parameter values:

java -jar jEPlus.jar -job example_E+v8.0/HVACTemplate-5ZoneFanCoil.jep -value job_north,0,0,0,0.008;job_east,0,0,90,0.008;job_south,0,0,180,0.008;job_west,0,0,270,0.008 -cfg jeplus_v80.cfg

Execute the selected jobs of the specified jEPlus project in the job list file, using the selected E+ configuration:

java -Xmx1000m -jar jEPlus.jar -job example_1-params_E+v8.3/HVACTemplate-5ZoneFanCoil.jep -file joblist.txt

The following example shows how to use the jEPlus programming interface in Java language:

  // ... ...
 
        // configure logger
        PropertyConfigurator.configure("log4j.cfg");

        // load jEPlus configuration file
        JEPlusConfig.setDefaultInstance(new JEPlusConfig("jeplus.cfg"));

        // load project file
        JEPlusProject Project = JEPlusProject.loadAsXML(new File("example_3-RVX_v1.6_E+v8.3/project.jep")); // Or your own project file

        // create simulation manager
        EPlusBatch SimManager = new EPlusBatch (null, Project);

        // Set simulation agent
        SimManager.setAgent(new EPlusAgentLocal ( Project.getExecSettings()));

        // Validate project
        SimManager.validateProject();

        // If project is valid
        if (SimManager.getBatchInfo().isValidationSuccessful()) {

            // specify jobs
            String [][] jobs = new String [][] {{"case-1", "0", "0", "0", "7500", "350", "1.05", "-1"}, 
                                                {"case-2", "0", "0", "90", "3000", "800", "1.05", "-1"},
                                                {"case-3", "0", "0", "180", "3500", "200", "1.45", "-1"},
                                                {"case-4", "0", "0", "270", "175", "650", "1.05", "-1"}};
                                                // Or specify your own value set
            // execute jobs
            SimManager.runJobSet(jobs);
            
            // Alternatively, run jobs in the job list file 
            // SimManager.runJobSet(EPlusBatch.JobStringType.FILE, "example_3-RVX_v1.6_E+v8.3/jobs2.txt");

            // wait for jobs to finish
            try {
            do {
                Thread.sleep(2000);
            }while (SimManager.isSimulationRunning());
            }catch (InterruptedException iex) {
                SimManager.getAgent().setStopAgent(true);
            }

            // collect simulation results
            HashMap<String, ArrayList<ArrayList<double []>>> Results = SimManager.getSimulationResults(
              SimManager.getAgent().getResultCollectors(),
              SimManager.getResolvedEnv().getParentDir(),
              Project.getRvx(),
              null
            );

            int n = Results.size();
            // ... ...

        }else {
          logger.info(SimManager.getBatchInfo().getValidationErrorsText());
        }

  // ... ...

Here, simulation results can be retrieved directly from the simulation manager instance as a map indexed by the job IDs. A job ID is a unique string that a user must assign to each job as the first part of the job string.

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}, …;

Or, in the all-index form:

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

in which, job ID is a unique string assigned to the job; the index of weather file or building model is zero-based sequential number of the selected file in the corresponding list in the jEPlus project.

Specification of a parameter value can take two forms: as the actual value or as the index (zero-based) of the value in the alternative values list of the parameter in question. The first form is suitable for real value encoded optimisation algorithms, and indeed, for any job creator that a user wants to employ, for instance, for implementing user defined sampling methods, uncertainty analysis, or sensitivity analysis purposes.

The second form relies on the predetermined alternative value lists of the parameters. It is suitable for use with integer-encoded algorithms, which will be demonstrated in the next section. It worth noting that the job strings, in either value or index forms, are NOT validated by jEPlus before execution.

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 prepare the job list file, for example, jobs.lst, the following command will run the jobs:

java -jar jEPlus.jar -job my_project.jep -file jobs.lst

[Under review]

To use the 'special syntax @calc and @python in a job list file, you must use their parsed forms as shown in the preview box in the jEPlus GUI. For example, parameter P2 is defined as @calc(P0+P1). Its parsed form would thus be ?=@@tag0@@+@@tag1@@. And, if parameter P3 is defined as @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)
job01,  0, 2, 90,  0.25, ?=@@tag0@@+@@tag1@@, @call(python3, myscript.py, @@tag2@@, 78.9)
...

jEPlus can be used as a bare simulation manager instead of as a GUI for creating parametric jobs. You can prepare or generate a jEPlus project containing multiple simulations and jEPlus will execute those for you and collect results. Sometimes editing the jEPlus project file in a text editor is quicker to make changes than using the GUI, too. This page describes the jEPlus project file, and various ways to use jEPlus in other programs or programming languages.

A jEPlus project (.jep) file is a saved JEPlusProject instance using Java XMLEncoder. It is a text file in XML format. With some patience, you can probably read and edit the file with a text editor. However, if you have more parameters in the project, the .jep file will get quite long and difficult to locate each parameter. Here is an example of the definition of the first parameter in parameter tree in a .jep file.

  <void property="paramTree">
   <void id="ParameterItem0" property="userObject">
    <void class="jeplus.data.ParameterItem" method="getField">
     <string>Name</string>
     <void method="set">
      <object idref="ParameterItem0"/>
      <string>Orientation</string>
     </void>
    </void>
    <void class="jeplus.data.ParameterItem" method="getField">
     <string>Description</string>
     <void method="set">
      <object idref="ParameterItem0"/>
      <string>Orientation of the building</string>
     </void>
    </void>
    <void class="jeplus.data.ParameterItem" method="getField">
     <string>SearchString</string>
     <void method="set">
      <object idref="ParameterItem0"/>
      <string>@@orientation@@</string>
     </void>
    </void>
    <void property="valuesString">
     <string>[0 :45 :359 ] &amp; {101} ^ {45, 135}</string>
    </void>
   </void>

Unless you are using Java, the project file is really not suitable for editing or manipulation. For this reason the import feature of tabular parameter definitions is introduced.

The parameter definitions can be stored as a table in a CSV-styled text file, which can be subsequently referenced in a jEPlus project file. In this way, both the parameter definitions and the .jep file are much simpler to compile.

An example parameter definition list file is shown below. Once imported into the jEPlus project, the parameters will be arranged in a single-branch tree.

# Parameter definitions in a csv file. Column headings are as below
# ID, Name, Parameter Type, Description, Search String, Value Type, Value String, Selected Value Index
#           {0}                                         {0, 1, 2}                 {0, ... number of values}
# Please note ',' (comma) '"' (quotation mark) or ''' (apostrophe) must not be used in any data fields
# For example, "{1, 2, 3}" will cause errors. Use { 1 2 3 } instead.

  P01, Orientation, 0, Orientation of the building, @@orientation@@, 0, [0:15:359],         0

  P02, OA,          0, Minimum fresh air,           @@Outside_Air@@, 1, [0.008:.001:0.025], 0

# ...

Once the parameters are externalized, the remainder of the project file is much simpler. Here is an example that points to the parameter file (parameters.csv) above.

<?xml version="1.0" encoding="UTF-8"?>
<java version="1.7.0_17" class="java.beans.XMLDecoder">
	<object class="jeplus.JEPlusProject">
		<void property="ParamFile">
			<string>parameters.csv</string>
		</void>
		
		<void property="IDFTemplate">
			<string>my_model.imf</string>
		</void>
		
		<void property="RVIFile">
			<string>my.rvi</string>
		</void>
		
		<void property="baseDir">
			<string> </string>
		</void>
		
		<void property="projectID">
			<string>A</string>
		</void>
		
		<void property="projectNotes">
			<string>My project</string>
		</void>
		
		<void property="weatherFile">
			<string>my_weather.epw</string>
		</void>
	</object>
</java>

You can now write procedures in your program to generate this project file, or to swap in different idf models, rvi files or weather files.

Here you can download an example project bundle containing the files above, and the other necessary model files. To do a test run, unpack the contents into the jEPlus folder, and then issue the following command:

java -jar jEPlus.jar -job example_jep/project.jep -sample 5

Results of the 5 simulation jobs will be stored in “example_jep/output/” folder.