meta data for this page
Chapter 9 Examples
9.1 Work with EP-Macro
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
| EP-Macro features | Application of jEPlus with EP-Macro | |
|---|---|---|
| 1 | Incorporating external files containing pieces of IDF into the main EnergyPlus input stream | Defining a block of code in the building model as one parameter |
| 2 | Selectively accepting or skipping portions of the input | Another way for defining a block of code as a parameter |
| 3 | Defining a block of input with parameters and later referencing this block | Using one search string to change multiple values at different locations |
| 4 | Performing arithmetic and logical operations on the input | Calculating a variable value from an input value, therefore one parameter can be used in stead of two |
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
.imfextension - If the model has inclusion files (i.e.
##includeis 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
##includeand/or##fileprefixare 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:
9.2 Change Window Size
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:
- Incorporate pre-defined FenestrationSurface objects into the main model using EP-Macro's #include function
- Use the combinatorial parameter syntax to specify pre-defined sets of coordinates
- Use the @calc syntax to calculate coordinates from height and width parameters
- 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.
Problem definition
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.
Use @calc syntax
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
Use macro functions
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
9.3 Change Window-to-wall Ratio
Changing window-to-wall ratio (WWR) can be considered as a special case for manipulating window geometries. 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 the WWR. The diagram below illustrate 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