Chapter 3 The jEPlus Project

Version 2.2, © 2024 Energy Simulation Solutions Ltd

A jEPlus project is a file describing the parametric project. In the simplest terms, jEPlus injects user-defined parameter values into the EnergyPlus or TRNSYS model templates to create a set of simulation cases, run these simulation cases, and then collect and aggregate results into result tables. A number of inputs must be specified in the jEPlus project in order to perform the process. These inputs, or segments of a project file, are:

1. The model templates and essential files (e.g. a weather file for EnergyPlus)
2. The parameters definitions, see Chapter 4
3. The result collection and postprocessing methods, see Chapter 5
4. And the execution options, see Chapter 6

This chapter provides a detailed overview of the format of the project file and the input files it relies on.

Strictly speaking, a minimum working jEPlus project for EnergyPlus requires only the two highlighted lines in the code below, wrapped in curly brackets ({}). However, that is not quite the point here. The example shows 1) how easy it is to read and edit a jEPlus project in its JSON format, and 2) what the necessary parts are there.

{
  "projectType" : "EPLUS",
  "weatherDir" : "./",
  "weatherFile" : "my.epw",
  "idfdir" : "./",
  "idftemplate" : "my.idf",
  "parameters" : [ {
    "paramType" : "PARAMETRICS",
    "id" : "P0",
    "name" : "Parameter 0",
    "description" : "new parameter item",
    "searchString" : "@@tag0@@",
    "type" : "INTEGER",
    "valuesString" : "{0}",
    "selectedAltValue" : 0
  } ],
  "rvx" : {
    "rvis" : [ ],
    "csvs" : [ ],
    "sqls" : [ ],
    "scripts" : [ ],
    "userSupplied" : [ ],
    "userVars" : [ ],
    "objectives" : [ ],
    "constraints" : [ ]
  }
}

Similarly, below is a minimalistic jEPlus project for TRNSYS. You would notice a few differences, such as the projectType's value and the fields used.

{
  "projectType" : "TRNSYS",
  "dckdir" : "./",
  "dcktemplate" : "my.dck",
  "outputFileNames" : "trnsysout.csv",
  "parameters" : [ {
    "paramType" : "PARAMETRICS",
    "id" : "P0",
    "name" : "Parameter 0",
    "description" : "new parameter item",
    "searchString" : "@@tag0@@",
    "type" : "INTEGER",
    "valuesString" : "{0}",
    "selectedAltValue" : 0
  } ],
  "rvx" : {
    "scripts" : [ ],
    "userSupplied" : [ ],
    "trns" : [ ],
    "userVars" : [ ],
    "objectives" : [ ],
    "constraints" : [ ]
  }
}

So, a jEPlus project must contain at least three parts of information:

1. The input files, e.g. the model template(s) and the weather file(s) for EnergyPlus, and the model template(s) for TRNSYS;
2. the definition of the parameters, including their IDs, search tags, and alternative values to be used in simulation
3. and the definition of results extraction, i.e. how the simulation results are to be extracted and processed.

This chapter will describe the structure and contents of the jEPlus project file. The details of the different ways of defining parameter values and extracting simulation results will be covered in later chapters.

EnergyPlus and TRNSYS projects require different input files. For EnergyPlus, the weather file(s) and the IDF/IMF file(s) are essential, while other files may be defined in the project for pre-processing and results collection, or included in the project folder to provide additional data to the main IDF/IMF files.

{
  "projectType" : "EPLUS",
  "weatherDir" : "./",
  "weatherFile" : "my.epw",
  "idfdir" : "./",
  "idftemplate" : "my.idf",
  "parameters" : [ {
  ...
}

Weather file(s) – EnergyPlus uses EPW (.epw) files to provide weather information for the simulation runs. You can easily find design or typical weather year datasets nowadays, thanks to the brilliant effort by Dru Crawley and Linda Lawrie at climate.onebuilding.org. You can also use ENSIMS' epwmap app to search for EPW files near the location you need.

In a jEPlus project, you can use one or multiple weather files for the parametric study. To have multiple weather files, you can select them in the GUI by holding down the 'Ctrl' or the 'Shift' key while clicking on the files, or write the comma ( , ) delimited list of filenames in the weatherFile field directly using a text editor. If you want to have many weather files, or they are stored in different folders, you can put the paths to the EPW files, one per row, into a text file with the extension .lst and select the list file instead.

IDF/IMF template(s) – These are EnergyPlus models on which the parametric study will be carried out. The new epjson format is not currently supported. Similar to the EPW files, you can use one or more models in a jEPlus project. You can either select them in the GUI by holding down the 'Ctrl' or the 'Shift' key while clicking on the files, or write the comma ( , ) delimited list of filenames in the idftemplate field directly using a text editor. If you want to have many model files, or they are stored in different folders, you can put the paths to the IDF/IMF files, one per row, into a text file with the extension .lst and select the list file instead.

The EnergyPlus models used in a jEPlus project are called model templates. jEPlus carries out parametric runs by inserting parameter values at the right places marked with search strings in the model templates. You should always test the original models thoroughly before putting in the search strings. To edit the template, either a text editor or the in-built IDF text editor can be used. A new tool called IDF+ Editor by Matt Doiron can be used for this purpose, too. IDF+ offers some very useful features but can have some stability issues at the time when this manual is written. Unfortunately, the IDFEditor of EnergyPlus cannot be used for inserting search strings.

Other files – other files that may be referenced in a jEPlus project or included in the project folder include:

1. Script files such as Python, R and Ruby scripts for pre-processing and results collection/postprocessing
2. EnergyPlus RVI/MVI files for results collection
3. CSV files to contain user-supplied values indexed by job_ids for results collection
4. IDF files (with any extension) containing snippets of a model, to be included in the main model using EP-Macro
5. CSV files to provide additional data to the main model, such as schedules
6. a text file (any extension) containing a list of parameter values to be used as a part of the parameter definition
7. a CSV file containing parameter definitions for jEPlus
8. a RVX file (in JSON format) containing the details of the results collection objects for jEPlus (deprecated in jEPlus v2)

{
  "projectType" : "TRNSYS",
  "dckdir" : "./",
  "dcktemplate" : "my.dck",
  "outputFileNames" : "trnsysout.csv",
  "parameters" : [ {
  ...
}

DCK/BLD template(s) – TRNSYS models in both DCK or BLD formats can be selected as the main model(s) in a jEPlus project. To use more than one TRNSYS models, You can either select them in the GUI by holding down the 'Ctrl' or the 'Shift' key while clicking on the files, or write the comma (,) delimited list of filenames in the dcktemplate field directly using a text editor. If you want to have many model files, or they are stored in different folders, you can put the paths to the IDF/IMF files, one per row, into a text file with the extension .lst and select the list file instead.

The TRNSYS models used in a jEPlus project are called model templates. jEPlus carries out parametric runs by inserting parameter values at the right places marked with search strings in the model templates. You should always test the original models thoroughly before putting in the search strings. To edit the template, either a text editor or the in-built text editor can be used.

Other files – other files that may be referenced in a jEPlus project or included in the project folder include:

1. Script files such as Python, R and Ruby scripts for pre-processing and results collection/postprocessing
2. any files referenced by the TRNSYS models, e.g. the weather file
3. CSV files to contain user-supplied values indexed by job_ids for results collection
4. a text file (any extension) containing a list of parameter values to be used as a part of the parameter definition
5. a CSV file containing parameter definitions for jEPlus
6. a RVX file (in JSON format) containing the details of the results collection objects for jEPlus (deprecated in jEPlus v2)