Chapter 10 Examples

Version 2.1, © 2019, 2020 Energy Simulation Solutions Ltd

[This page is under construction]

Four example project folders are included in the jEPlus' distribution package.

This example demonstrates the user of different parameter definition syntax, including the @sample, @file, and @calc.

Ex.1 - Parameter definitions

This is the same project as in the Example 1. A few additional files are included for a demonstration of how to do Sensitivity Analysis with SimLab.

The steps are as below:

1. Define the model parameters as the UA/SA factors in SimLab 2.2
2. Generate a sample of the factors using SimLab, for example as in simlab_sobol.sam
3. Open simlab_sobol.sam in Excel, keep only the sample body, insert three columns for Job_IDs, weather file index (0), and model file index (0), and then save the table in CSV format. The result is joblist.csv.
4. Run jEPlus with the job list file joblist.csv
5. After simulation, open AllCombinedResults.csv, sort the table according to the Job_IDs, remove the unnecessary columns and the header row, insert the header rows as required by SimLab, and then save the file as tab-separated text.
6. This result table can be used in SimLab for UA and SA analysis.

Demonstrates the latest RVX syntax and various ways of collecting results. The my.rvx file is explained in Chapter 5 Result Extraction in full details.

Ex.3 - RVX

Demonstrates the JSON version of the project in Example 3, and the command-line to execute the JSON project. You may note in the folder, project.json has replaced project.jep, and my.rvx is no longer required. To run the project, use the command-line as given in commandline.bat:

java -jar ../jEPlus.jar -job project.json -sample 5 -cfg ../jeplus.cfg -log ../log4j.cfg -local 2 -output results

EP-Macro is a powerful tool provided in the EnergyPlus package. It allows more flexibility in designing parameters with jEPlus:

Table 1: features of EP-Macro and potential applications

To use EP-Macro with jEPlus, however, the specific instructions bellow needs your attention:

• EP-Macro will be triggered if the model template file has an .imf extension
• If the model has inclusion files (i.e. ##include is used), rules regarding the location where you can insert search strings differ for the main IMF file and for the inclusion files
• In the main IMF file, search strings are allowed anywhere, either in the model code, or in macro instructions
• In the inclusion files, search strings are only allowed in model code. Search strings in macro instructions in an inclusion file cannot be processed by jEPlus; therefore errors will be reported by EP-Macro
• If ##include and/or ##fileprefix are used, absolute path to the folder location is recommended, for example: ##fileprefix C:\EnergyPlusV6-0-0\ExampleFiles\ If relative path is used, please bear in mind that it is relative to the location of the main IDF/IMF model.

A tutorial is available here:

How to use jEPlus to change window size is a question came up rather frequently. Manipulating geometry is not what jEPlus is best at, especially compared to the tools with 3D modelling capability, such as DesignBuilder. However, for a simple problem e.g. to test a small number of window geometries, or the sizes of one window, there are at least four ways to achieve the effect:

1. Incorporate pre-defined FenestrationSurface objects into the main model using EP-Macro's #include function
2. Use the combinatorial parameter syntax to specify pre-defined sets of coordinates
3. Use the @calc syntax to calculate coordinates from height and width parameters
4. And use EP-Macro's macro functions to perform coordinates calculations within the IDF model

In this example we focus on the third and the fourth methods.

The location and the dimensions of a rectangular window in a wall can be defined by four parameters. These can be the coordinates of the opposite corners of the windows, or its width and height plus the offsets to a reference point. In the examples below, both methods of using the @calc syntax in parameter definition, and using EP-Macro, are demonstrated.

The @calc syntax allows you to define dependent parameters whose values are to be calculated from other parameters. This example shows defining the window geometry using the offset of its lower left corner and its width/height. The actual coordinates of the corners are calculated in a different set of parameters, whose search tags are placed in the IDF model template.

First, let's see the parameter definitions. The text file (in CSV format) below can be imported into a jEPlus project to create the parameter tree (Requires jEPlus v1.6.0 or later).

#
# 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, .... depending on number of values}
# Please note , " or ' must not be used in data fields, e.g. "{1, 2, 3}" will cause errors; use { 1 2 3 } instead.

# Independent parameters
DX, OffsetX, 0, Window offset X to the lower left corner of the wall, @@dx@@, 1, [0.1:0.1:9.0], 0
DZ, OffsetZ, 0, Window offset Z to the lower left corner of the wall, @@dz@@, 1, [0.6:0.1:2.8], 0
W,  Width,   0, Width of window,                                      @@w@@,  1, [0.5:0.1:9.8], 0
H,  Height,  0, Height of window,                                     @@h@@,  1, [0.5:0.1:2.4], 0

# Dependent parameters. Note that the wall's coordinates are (0, 0) - (10, 3.5)
X0, CoordX0, 0, Coordinate X of the lower left corner of the window,  @@x0@@, 1, @calc(0.0+DX), 0
Z0, CoordZ0, 0, Coordinate Z of the lower left corner of the window,  @@z0@@, 1, @calc(0.0+DZ), 0
X2, CoordX2, 0, Coordinate X of the upper right corner of the window, @@x2@@, 1, @calc(min(X0+W,10-0.1)), 0
Z2, CoordZ2, 0, Coordinate Z of the upper right corner of the window, @@z2@@, 1, @calc(min(Z0+H,3.5-0.1)), 0

#

And then, in the IDF model, the search tags are applied as below:

...
!-   ===========  ALL OBJECTS IN CLASS: FENESTRATIONSURFACE:DETAILED ===========

!- Intermediate parameter values: dx = @@dx@@, dz = @@dz@@, w = @@w@@, h = @@h@@

! Window, 16.354m2
FenestrationSurface:Detailed,
    Block1:Zone1_Wall_5_0_0_0_0_0_Win,  !- Name
    Window,                  !- Surface Type
    1001,                    !- Construction Name
    Block1:Zone1_Wall_5_0_0, !- Building Surface Name
    ,                        !- Outside Boundary Condition Object
    0.5,                     !- View Factor to Ground
    ,                        !- Shading Control Name
    ,                        !- Frame and Divider Name
    1,                       !- Multiplier
    4,                       !- Number of Vertices
    @@x0@@, -10, @@z0@@,     !- X,Y,Z  1 {m}
    @@x2@@, -10, @@z0@@,     !- X,Y,Z  2 {m}
    @@x2@@, -10, @@z2@@,     !- X,Y,Z  3 {m}
    @@x0@@, -10, @@z2@@;     !- X,Y,Z  4 {m}


!-   ===========  ALL OBJECTS IN CLASS: PEOPLE ===========
...

The working jEPlus project can be downloaded here: WindowSizeExample1-atCalc.zip

The same effect can be achieved by using the EP-Macro functions in the IMF model. The example below let user define four parameters: left, bottom, top, and right, corresponding to x0, z0, z2 and x2 respectively, as in the above diagram. Further macro functions are used for checking coordinates collisions, so that a window of size 0.1m x 0.1m minimum is produced. User must take care of the value ranges for the left, bottom, top and right parameters.

...

!-   ===========  ALL OBJECTS IN CLASS: FENESTRATIONSURFACE:DETAILED ===========
##set1 Left @@L@@
##set1 Bottom @@B@@
##set1 Top @@T@@
##set1 Right @@R@@

##if #[Top[] LE Bottom[]]
##set1 NewTop #eval[Bottom[] + 0.10]
##else 
##set1 NewTop Top[]
##endif

##if #[Right[] LE Left[]]
##set1 NewRight #eval[Left[] + 0.10]
##else 
##set1 NewRight Right[]
##endif


! Window, 16.354m2
FenestrationSurface:Detailed,
    Block1:Zone1_Wall_5_0_0_0_0_0_Win,  !- Name
    Window,                  !- Surface Type
    1001,                    !- Construction Name
    Block1:Zone1_Wall_5_0_0, !- Building Surface Name
    ,                        !- Outside Boundary Condition Object
    0.5,                     !- View Factor to Ground
    ,                        !- Shading Control Name
    ,                       !- Frame and Divider Name
    1,                       !- Multiplier
    4,                       !- Number of Vertices
    Left[], -10, Bottom[],    !- X,Y,Z  1 {m}
    NewRight[], -10, Bottom[],     !- X,Y,Z  2 {m}
    NewRight[], -10, NewTop[],     !- X,Y,Z  3 {m}
    Left[], -10, NewTop[];    !- X,Y,Z  4 {m}


!-   ===========  ALL OBJECTS IN CLASS: PEOPLE ===========
...

The working jEPlus project of this example can be downloaded here: WindowSizeExample2-EPMacro.zip

Changing the window-to-wall ratio (WWR) is a special case for manipulating window geometries. Here we show two ways to do that.

This example presents the simplest case, in which the window is located in the centre of the wall, and its width and height are proportional to the overall size of the wall according to the WWR. The diagram below illustrates the calculations. The example project requires jEPlus v1.5.2 or later.

#
# 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, .... depending on number of values}
# Please note , " or ' must not be used in data fields, e.g. "{1, 2, 3}" will cause errors; use { 1 2 3 } instead.

# Independent parameters
WWR, WWR, 0, Window-to-wall ratio, @@wwr@@, 1, [0.1:0.1:0.9], 0

# Dependent parameters. Note that the wall's coordinates are (0, 0) - (10, 3.5)
X0, CoordX0, 0, Coordinate X of the lower left corner of the window,  @@x0@@, 1, @calc(5.0-math.sqrt(WWR)*5.0), 0
Z0, CoordZ0, 0, Coordinate Z of the lower left corner of the window,  @@z0@@, 1, @calc(1.75-math.sqrt(WWR)*1.75), 0
X2, CoordX2, 0, Coordinate X of the upper right corner of the window, @@x2@@, 1, @calc(5.0+math.sqrt(WWR)*5.0), 0
Z2, CoordZ2, 0, Coordinate Z of the upper right corner of the window, @@z2@@, 1, @calc(1.75+math.sqrt(WWR)*1.75), 0

#

And then, in the IDF model, the search tags are applied as below:

...
!-   ===========  ALL OBJECTS IN CLASS: FENESTRATIONSURFACE:DETAILED ===========

!- Intermediate parameter values: wwr = @@wwr@@

! Window, 16.354m2
FenestrationSurface:Detailed,
    Block1:Zone1_Wall_5_0_0_0_0_0_Win,  !- Name
    Window,                  !- Surface Type
    1001,                    !- Construction Name
    Block1:Zone1_Wall_5_0_0, !- Building Surface Name
    ,                        !- Outside Boundary Condition Object
    0.5,                     !- View Factor to Ground
    ,                        !- Shading Control Name
    ,                        !- Frame and Divider Name
    1,                       !- Multiplier
    4,                       !- Number of Vertices
    @@x0@@, -10, @@z0@@,     !- X,Y,Z  1 {m}
    @@x2@@, -10, @@z0@@,     !- X,Y,Z  2 {m}
    @@x2@@, -10, @@z2@@,     !- X,Y,Z  3 {m}
    @@x0@@, -10, @@z2@@;     !- X,Y,Z  4 {m}


!-   ===========  ALL OBJECTS IN CLASS: PEOPLE ===========
...

The working jEPlus project can be downloaded here: WWR_Example-atCalc.zip

example_8-PyPreProcess_E+v8.5 contains the window-to-wall ratio example. In the project, a jEPlus parameter defines the alt WWR values of all external walls. The Python script (written in Python3 and Eppy) takes the WWR value and applies it to all window objects in the IDF.

Example 8. Changing WWR with Python

Please note, to run this example, you need to have Python3 and the Eppy dependencies installed, and the python3 script language configured in jEPlus. Below is the contents of the script.

# python script for pre-processing: This script takes WWR value from the argument list and modifies all the windows in the IDF model
# This script is designed to work with jEPlus v1.6.4 and later, with the @python? syntax
# @author: Dr Ivan Korolija [ivan.korolija@gmail.com]
# Arguments:
#   sys.argv[1]  -  project's base folder where the project files are located
#   sys.argv[2]  -  folder of the current case where in.idf is located
#   sys.argv[3]  -  Other arguments specified in the parameter definition. They are passed in as a ',' delimited string
#   sys.argv[4]  -  folder of the binary files of the simulation program, e.g. the location of Energy+.idd

import os
from eppy.modeleditor import IDF
import sys
import math

# function for calculating wall width and height
def wall_width_height(coordinates):
    ulc = coordinates[0]  # upper left corner coordinates
    blc = coordinates[1]  # bottom left corner coordinates
    brc = coordinates[2]  # bottom right corner coordinates

    # calculate wall width and height by using the Euclidean distance
    w = math.sqrt(math.pow(
        (brc[0] - blc[0]), 2) + math.pow((brc[1] - blc[1]), 2) +
        math.pow((brc[2] - blc[2]), 2))
    h = math.sqrt(math.pow(
        (ulc[0] - blc[0]), 2) + math.pow((ulc[1] - blc[1]), 2) +
        math.pow((ulc[2] - blc[2]), 2))
    return w, h  # return wall width and height
# End 


# path to E+ idd file (required by eppy)
iddfile = os.path.join(sys.argv[4], 'Energy+.idd')
IDF.setiddname(iddfile)

# path to energyplus input file within each simulated folder
idf = os.path.join(sys.argv[2], 'in.idf')

# glazing ratio convert to integer
gr = int(sys.argv[3])

idf = IDF(idf)  # read idf file to eppy
# extract window and wall objects
window_objects = idf.idfobjects['Window'.upper()]
wall_object = idf.idfobjects['BuildingSurface:Detailed'.upper()]

# loop through window objects
for window in window_objects:
    # find the base surface for the window
    win_base_surface = window.Building_Surface_Name

    # loop through the wall objects
    for wall in wall_object:
        # when wall name equals to the window base surface name extract coords
        if wall.Name == win_base_surface:
            coord = wall.coords
            # calculate wall width and height
            w, h = wall_width_height(coord)
            # calculate wall length and height as a function of glazing ratio
            wl = w * math.sqrt(gr / 100)  # window length
            wh = h * math.sqrt(gr / 100)  # window height
            # starting X/Z coordinates relative to the wall bottom left corner
            x = (w - wl) / 2
            z = (h - wh) / 2

    # coords and window H/L converted into strings and applied to window object
    window.Starting_X_Coordinate = '%.2f' % x
    window.Starting_Z_Coordinate = '%.2f' % z
    window.Length = '%.2f' % wl
    window.Height = '%.2f' % wh

# save the updated idf file
idf.saveas('in.idf')

# Done