Chapter 8 Interface with jEPlus

Version 1.5, © 2014 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
 -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.
 -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 and -lhs
 -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		

Start jEPlus GUI:

java -Xmx1000m -jar jEPlus.jar			

Start jEPlus GUI and load the specified project:

java -Xmx1000m -jar jEPlus.jar -job example_E+v8.0/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 -Xmx1000m -jar jEPlus.jar -job example_E+v8.0/HVACTemplate-5ZoneFanCoil.jep -all -cfg jeplus_v80.cfg -local 2 -output ../CmdLineTests/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 -Xmx1000m -jar jEPlus.jar -job example_E+v8.0/HVACTemplate-5ZoneFanCoil.jep -sample 15 -cfg jeplus_v80.cfg

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

java -jar jEPlus.jar -job example_E+v8.0/HVACTemplate-5ZoneFanCoil.jep -lhs 20 -seed 1234567 -cfg jeplus_v80.cfg

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

java -jar jEPlus.jar -job example_E+v8.0/HVACTemplate-5ZoneFanCoil.jep -index job0,0,0,0,1;job1,0,0,1,0 -cfg jeplus_v80.cfg

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_E+v8.0/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_E+v8.0/HVACTemplate-5ZoneFanCoil.jep -file joblist.txt -cfg jeplus_v80.cfg

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

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

  // load project file
  JEPlusProject Project = new JEPlusProject (/* "project.jep" */);
  
  // 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 = /* array of job strings */;
   
    // execute jobs – job string contains values
    SimManager.runJobSet(jobs);
  
    // or if job string contains indexes
    // SimManager.runJobSet2(jobs);
  
    // 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<double []>> Results = SimManager.getSimulationResults();
       
    // ... ...

  }else {
    System.out.println(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 takes the following form:

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

Or, in the 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

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.