Advanced Guide for jEPlus

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.