Chapter 4 The Parameters

Version 2.2, © 2024 Energy Simulation Solutions Ltd

A parameter definition object contains three essential elements - a unique ID, a search string (also called a search tag) serving as a placeholder in the model template, and a list of alternative values that can be assigned to this parameter - along with other fields.

{
  ...
  "parameters" : [ {
    "paramType" : "PARAMETRICS",
    "id" : "P0",
    "name" : "Parameter 0",
    "description" : "new parameter item",
    "searchString" : "@@tag0@@",
    "type" : "INTEGER",
    "valuesString" : "{0}",
    "selectedAltValue" : 0
   },
   ...
  ],
  ...

The snippet above shows the definition of a parameter in the jEPlus project. Here are what each of the fields means.

• Parameter Type: the paramType field is reserved for future use. Keep the value to “PARAMETRICS” for now. It has no impact on how the project behave.
• Parameter ID: the id field must contain a short and unique identification string of the parameter, e.g. “P0”. The IDs are used for referencing other parameters and forming the job IDs.
• Parameter Name and Description: these are descriptions of the parameter, serving as notes to the user.
• Search String: the search tags is a special text string used as a placeholder to mark the location where the actual value of the parameter to be inserted in the model template. Although they can be any string of characters, you need to be careful that the string does not collide with any syntax of the model. For example, you must not use ,, ; or [ ] in a search tag in EnergyPlus models. The default form of “@@tag_name@@” works well for both EnergyPlus and TRNSYS.
• Value Type: the type field of the parameter instructs jEPlus how to interpret the valuesString field when the [ ] or @sample syntax are used.
• Alternative Values: the valuesString field is where the alternative values for the parameter are specified. The syntax available to this field is lightly complex but offers great flexibility in defining values and pre-processing operations.
• Selected Value: if the selectedAltValue field has a value that matches an index of the alternative values list, i.e. 1 < = selectedAltValue < = total number of alt values, jEPlus will use this value only when creating the parametric jobs.

Let's first look at the different ways to formulate the alternative values for a parameter, then see how parameters can be used to represent different parts of the model.

There are a number of ways to define what values or pre-processing operations jEPlus should take for a parameter. These include:

• Explicit list (for all types)
• Sequence of numerics (for Integer and Double types)
• Explicit list from an external file (for all types)
• Randon sample of a probabilistic distribution (for Integer and Double types)
• Calculation from prior parameters (for Integer and Double types)
• Pre-processing script (for all types)

The most straightforward way to define a list of values is to use an explicit list enclosed in a pair of curly brackets ({}), e.g. {Detailed, Simple, CeilingDiffuser}. This syntax applies to both text and numeric values. The list can be delimited by commas (,), semi-colons (;) or spaces ( ). If the value text contains spaces or commas itself, the string needs to be enclosed in a pair of quotes (“ ”).

For example, {“Sgl Clr 6mm”, “Dbl Clr 3mm/6mm Air”; “ Dbl Clr 3mm/13mm Arg” “Dbl LoE (e2=.4) Clr 3mm/13mm Arg”} denotes a list of four different window constructions in an EnergyPlus model.

For the numeric parameter value types, square brackets ([]) can be used to define a number series with a uniform interval using a syntax similar to that in Matlab. For example, the list {1,3,5,7,9} can be specified using [1:2:9], where colons (:) are used to separate the Start Value, the Interval, and the End Value. Please note the last value in the resultant list is unnecessarily the End Value.

Two boolean operators can be used to add or remove specific values from the regular sequence. The union operator (&) combines the elements in two lists. For example, [1:2:5]&{2,4,6} is equivalent to {1,3,5,2,4,6} (Note that the list is not sorted).

The exclusion operator (^) removes elements in the right-hand list from the left-hand list, e.g. [-2:1:6]^{2,4,6} gives {-2,-1,0,1,3,5}. The operators are processed in the left-to-right order. The following example shows the use of all supported operations: {1}&[0:5:30]^{0}, which gives {1,5,10,15,20,25,30} as the result.

If you have a long list of alternative values, or the text string of each value is long, it may be easier to edit it externally using a text editor and then save it to a text file. You can then use the @file syntax to load the contents of the text file as the values of the parameter.

the example_1-params_E+v9.2/ folder in the jEPlus package contains a parameter values file named P3_sample_EXP.txt. In the jEPlus project, the parameter references it with the syntax @file(P3_sample_EXP.txt). Please note that, if a relative path is used (as in this case), it is relative to the location of the jEPlus project file (project.json). If the content of the file is not shown in the preview box, it means that jEPlus cannot access the file, in which case you should check the paths again to make sure it is valid.

Note: the sampling method has been superseded by the PDF functions in the JEA platform, which is available to use with jEPlus+EA v2

The @sample syntax is used to create alternative values as a random sample of a probabilistic distribution. Sampling can be performed on Integer or Double parameters with different distribution profiles, including uniform, Gaussian (normal), log-normal, exponential, and triangular distributions. For Discrete parameters, a discrete distribution can be defined. This is also applicable to integer and double parameters if their values are defined using a list. The syntax of the sampling options for each of the supported distributions is shown below.

• Gaussian (normal) distribution - @sample(gaussian,0,2,20) or @sample(n,0,2,20) gives 20 samples with Gaussian distribution (mean = 0, standard deviation = 2)
• Uniform distribution - @sample(uniform,0,2,20) or @sample(u,0,2,20) gives 20 samples with uniform distribution (lower bound = 0, upper bound = 2)
• Triangular distribution - @sample(triangular,-1.0,0.2,1.0,20) or @sample(tr,-1.0,0.2,1.0,20) gives 20 samples with triangular distribution (lower bound = -1.0, mode = 0.2, upper bound = 1.0)
• Log-normal distribution - @sample(lognormal,3,2,20) or @sample(ln,3,2,20) gives 20 sample values with log-normal distribution (mean = 3, sd = 2)
• Exponential distribution - @sample(exponential,5,20) or @sample(e,5,20) gives 20 sample values with exponential distribution (mean = 5)
• Discrete distribution - @sample(discrete, single-glazed, 0.3, double-glazed, 0.5, triple-glazed, 0.2, 20) or @sample(d, single-glazed, 0.3, double-glazed, 0.5, triple-glazed, 0.2, 20) gives 20 sample points with single-, double- and triple-glazed options account for 30%, 50% and 20% of the cases, respectively.

Please note that sampling is performed right before the start of the simulation. As a result, the values you see in the Preview box may NOT be what you get in the actual simulations.

The @calc syntax instructs jEPlus to obtain the value of the current parameter by making calculations using the values of other parameters that come before it. It provides a convenient alternative to some of EnergyPlus' macro functions. Here is an example of the syntax:

@calc(15+P2/4) - the value string of parameter P3 is calculated from P2, as P3 = 15 + P2/4. Giving P2's values are {4, 8, 12}, P3 will effectively have {16, 17, 18} as a result. Please note that P2 must have been defined in the parameters list before P3.

jEPlus v2.x uses a JavaScript engine for internal calculations. All of the JavaScript arithmetic operators and functions of the Math Object are available to use. However, the boolean and bitwise operators (^ | and &) must not be used as they conflict with the jEPlus syntax.

Here a few more examples of the @calc syntax:

@calc(Math.hypot(P2, P3)) - returns the Euclidean norm of P2 and P3

Using scripting languages such as Python and R in jEPlus parameters for pre-processing is an important new feature introduced in version v2.x. The full details of the calling convention of the scripts are discussed in Chapter 8. Here we only describe the parameter definition syntax.

Below is an example of the parameter definition:

@script(python3, pre_test_args_py3.py, P1, 222, abc)

It is led by the keyword @script. The first field in the brackets is the script language, which must have been configured as described in section 9.1. The second field is the paths of the script file. Both relative and absolution paths names can be used here. If a relative path is used, it is relative to where the project file is located.

The following fields in the brackets are arguments to be passed to the script. Please note if jEPlus parameter names present in the project are referenced, the values of the parameters for each case will be used. This allows the scripts to work with existing parameters.

In the given example, arguments 222 and abc will be passed to the script as they are, whereas P2 will be replaced by e.g. 180 before being passed to the script.

If the syntax is valid, you shall see it being displayed in the Preview box, as:

{call(python3, pre_test_args_py3.py, @@orientation@@, 222, abc)}

In situations where two or more parameters' values need to be changed together, the combinatorial parameter can be used. A combinatorial parameter contains two or more search tags that can be placed in different locations in the IDF template. The alternative values to be used in place of the search tags during simulation are defined in groups, and each group is considered together as one design option. The purpose of using combinatorial parameters is to make synchronous multiple changes in the model, which is quite often needed in practice.

For example, if you want to change the size and location of a window, there are 4 values (x0, z0, w, h) have to be modified together. One combinatorial parameter is able to modify the 4 values simultaneously. The syntax for the search tag is now @@x0@@|@@y0@@|@@w@@|@@h@@. And the alternative values are {1|1|2|2, 1.1|1|1.9|2, 1|0.8|2|1.8 …}. In the IDF model, you can insert @@x0@@, @@y0@@, @@w@@ and @@h@@ at the right locations. jE+ will then parse the definition and assign correct values to the corresponding fields.

Here are some tips on the use-cases of parameters for EnergyPlus projects. The list and the solutions are by no means exhaustive.

Values - a single field to be changed by a jEPlus parameter, e.g. orientation

If the same parameter value needs to be inserted in many places in the model, e.g. in the case of design infiltration level of a multi-zone building, defining that value as an EnergyPlus macro using EP-Macro's ##def syntax would make it more readable and easier to debug.

Reference to other objects - use a jEPlus parameter to control which object is referenced, e.g. in the cases of construction and material objects.

Use the combinatorial parameter syntax for fields whose values must be changed synchronously. However, if there are many fields that are linked in this way, the parameter's search tag and alt values fields will become difficult to edit. In such cases, you should consider using other methods such as EP-Macro's ##def and ##include.

You can actually include a whole EnergyPlus object as a parameter value if you write it in one line. For example, to have the complete Site:GroundTemperature:BuildingSurface objects as parameter values, write them as {“Site:GroundTemperature:BuildingSurface,21.5,21.4,21.5,21.5,22.0,22.9,23.0,23.1,23.1,22.2,21.7,21.6;”, “Site:GroundTemperature:BuildingSurface,20.5,20.4,20.5,20.5,21.0,21.9,22.0,22.1,22.1,21.2,20.7,20.6;”, …}. As you can see, these will be best to be put in an external text file and then assign it to the parameter using the @file() syntax. In any case, this approach lacks readability and is error-prone.

The better option is to use EP-Macro's ##def, here, to define each alternative block of code as a macro, and then use a jEPlus parameter to select which one to apply.

You may also use EP-Macro's ##if syntax directly, see manual here, if you only need to define a few alternative blocks. It is less readable compared to ##def, though.

And, of course, you can use ##include (manual here) as recommended for larger chunks.

Use EP-Macro's ##include

Select multiple model templates in jEPlus.

Although the JSON format of the jEPlus project makes it fairly straightforward to create and modify its elements including the parameter definitions without the jEPlus GUI, there may still be situations where you want to prepare the parameters separately, and then import them into the jEPlus project. Here is an example parameter definition list file that is provided in the example_1-params_E+v9.2/ folder.

# Parameter list for project: 0 (exported at 02/12/19 20:09)
# Note: this list contains only the first branch of the parameter 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
#   ,     , {PARAMETRICS},             ,              , {INTEGER, DOUBLE, DISCRETE},,{0, .... depending on number of values}
# 
P1,Orientation,PARAMETRICS,"Orientation of the building",@@orientation@@,INTEGER,[0 :45 :359 ] & {101} ^ {45, 135},0
P2,Outside Air Rate,PARAMETRICS,"Outside Air Rate [m3/s/person]",@@Outside_Air@@,DOUBLE,@sample(n, 0.01, 0.0025, 10),0
P3,Occupancy density,PARAMETRICS,"occupancy density [people / m^2]",@@Occ@@,DOUBLE,@file(P3_sample_EXP.txt),0
P4,Equipment power,PARAMETRICS,"Equipment power as an arbitary function of occupancy density",@@Eq@@,DOUBLE,@calc(-400*Math.pow(P3, 2)+220*P3+2),0
P5,HVAC,PARAMETRICS,"HVAC template",@@hvac@@,DISCRETE,{"PurchAir","BaseboardHeat-NatVent","ConstantVolumeChillerBoiler","DualDuct","FanCoil","FanCoil-DOAS","FurnaceDX","PackagedVAV","PTAC","PTAC-DOAS","PTHP","UnitaryHeatPump","UnitarySystem","VAVFanPowered","VAVWaterCooled","VAVWaterCooled-ObjectReference","VRF","WaterToAirHeatPump"},0