5.7. ESP-r

5.7. ESP-r
	Chapter 5. Configuring programs for use with the BCVTB

5.7.1. Introduction

ESP-r is an integrated energy modelling tool for the simulation of the thermal, visual and acoustic performance of buildings and the energy use and gaseous emissions associated with environmental control systems.

5.7.2. Configuring ESP-r

ESP-r with the BCVTB functionality is not available in the standard precompiled ESP-r versions, but it can be downloaded from the subversion repository branch 'ESP-r_BCVTB' and installed using

svn checkout https://espr.svn.cvsdude.com/esp-r/branches/ESP-r_BCVTB
cd ESP-r_BCVTB/src
sudo ./Install -d /usr/local

To run the examples, only the module bps needs to be compiled, together with the training files and databases.

You will also need to add ESP-r's binary directory to your path variable, which may be done by adding the line

export PATH=$PATH:/usr/local/esp-r/bin

to your ~/.bashrc file and restarting the bash shell.

	Note
	The ESP-r interface and examples have only been tested on Linux and Mac OS X.

5.7.3. Examples

5.7.3.1. HVAC control in MATLAB

This example is available in the directory examples/esprMatlab-hvac. It demonstrates heating control of an ESP-r building model with control logic implemented in MATLAB. Please refer to Section 5.5, “MATLAB” for how to configure MATLAB.

The control logic represents a PID controller for two zones in the building. The room temperature is sensed, and sent from ESP-r to MATLAB. The control algorithm in MATLAB computes the required heating power, and sends this back to ESP-r.

To exchange sensor and actuator values with the BCVTB, first define the sensor and actuator locations as you would normally do in ESP-r. This results in a typical ESP-r control file, see the example control file esp-r/ctl/bld_basic.ctl. The next step is to configure the BCVTB coupling in the file esp-r/ctl/bld_basic.ctl. This is done under the * BCVTB heading in the control file of which a snippet is shown in Figure 5.26. The BCVTBflag indicates the specific BCVTB application (0 = no BCVTB coupling, 1 = basic ESP-r controller, 2 = advanced optics control). The three lines below this flag are used to control which sensor and actuators are coupled to the BCVTB (based on their ESP-r zone numbers) and to set the initial sensor values. Note that it is not necessary to couple all sensors and actuators. If an actuator is not coupled, then the ESP-r control logic as defined in the .ctl file will be used.

Figure 5.26. Snippet of the ESP-r input file that shows the configuration of the BCVTB interface.

>

* BCVTB 
# The BCVTBflag indicates the specific BCVTB application: 
# 0 = no BCVTB coupling, 1 = basic esp-r controller, 2 = advanced optics control 
   1    # BCVTBflag 
   1    2  # Define which zones' sensor values to send 
  15   15  # Define initial sensor values 
   1    2  # Define which zones' actuator values to overwrite

The BCVTB starts EPS-r in text-mode by running the shell script esp-r/bcvtb/call_espr. This file can be configured as follows:

  1 #!/bin/sh
    #########################################################
    #
    # Script that is called by the BCVTB to run ESP-r.
  5 #
    #########################################################
    BCVTBpath=..
    ESPR_PATH=`which bps`
    
 10 # Check wether ESP-r is installed and on the PATH
    if [ "${ESPR_PATH}x" == "x" ]; then
        echo "Error: Did not find ESP-r executable 'bps'."
        echo "       ESP-r directory must be on the PATH variable."
        exit 1
 15 fi
    
    rm -f ${BCVTBpath}/resfile.res
    rm -f ${BCVTBpath}/output.txt.par
    rm -f ${BCVTBpath}/output.txt
 20 
    bps -file ${BCVTBpath}/cfg/bld_basic_BCVTB.cfg -mode text <<ABC
    
    c
    ${BCVTBpath}/resfile.res
 25 8 2 # start date dd/mm
    10 2 # end date dd/mm
    2 # startup days
    12 # timesteps per hour
    n
 30 s
    y
    
    
    
 35 
    
    BCVTB1_heating_example
    y
    y
 40 -
    -
    ABC
    exiVal=$?
    if [ $exiVal != 0 ]; then
 45     echo "Error: ESP-r program 'bps' failed with exit code $exiVal'."
        exit $exiVal
    fi
    
    res -file ${BCVTBpath}/resfile.res -mode text <<BCD
 50 
    d # enquire about
    >
    a
    ../output.txt
 55 results
    -
    d
    f
    d # hours below a value
 60 b # temperature
    a # zones
    21 # setpoint
    -
    c # hours above a value
 65 b # temperature
    a # zones 
    24 # setpoint
    -
    -
 70 -
    BCD
    exiVal=$?
    if [ $exiVal != 0 ]; then
        echo "Error: ESP-r program 'res' failed with exit code $exiVal'."
 75     exit $exiVal
    fi
    exit 0

Lines 25-28 of the shell script controls the simulation start and stop days, number of startup days, and number of time-steps per hour. If you change these settings, you need to change the simulation control parameters in the BCVTB system.xml and the Matlab .m file accordingly.

5.7.3.2. Solar shading control in Ptolemy II

This example is available in the directory examples/espr-shading. In this example, a shading controller is implemented in ESP-r. The solar shading is modeled by using ESP-r's advanced optics module. Three sets of bi-directional window data are included in the file espr-shading/esp-r/bidata.txt. Each set corresponds to a double glazing unit with interior Venetian blinds at slat angles of 0°, 45° and 90°. New types of complex glazing systems can be added with the help of WINDOW 6. The control logic in the present example is implemented in Ptolemy II. The controller output is an integer that refers to the selected set of window properties. In this example, the room temperature is the sensor variable.

5.7.4. Developing new applications

The previous sections describe two illustrative examples to demonstrate the basic principles of coupling ESP-r with BCVTB. With minor code changes, it is possible to adapt these examples to meet the needs of variations of these cases. Communication between ESP-r and BCVTB was set up in a generic way with the aim of limiting the required code changes in ESP-r. Nevertheless, it is important that you become familiar with ESP-r's source code structure. ESP-r's developers guide provides a good starting point.

The BCVTB settings in ESP-r are declared and initialized in a new header file, include/bcvtb.h. The actual calls to the subroutines for data exchange with BCVTB are made in esrubps/bmatsv.F. These subroutines can be found in esrubld/bcvtb.F90. The implementation logic is similar to the FORTRAN 90 example, found in the directory bcvtb/examples/f90-room. Before the first time step the connection gets established. In every subsequent time step the data exchange takes place, just after completion of ESP-r's zone loop. The ESP-r to BCVTB coupling makes use of two new data structures, one for sending (bcvtb_y) and one for receiving (bcvtb_u). Both structures are FORTRAN arrays, with the array length equal to the number of exchanged variables. The task of the developer is to identify the right location in the code where the variable of choice is calculated. To enable the exchange of that variable, you have to add lines with the following structure:

       C Receiving variable from BCVTB
         variable #n = bcvtb_u(n)

       C Sending variable to BCVTB
         bcvtb_y(m) = variable #m

In addition, common blocks may be needed to pass the newly created variables between the various subroutines.

It is good practice to enclose BCVTB-related code in conditional statements with a BCVTBflag as identifier. This avoids the risk of unintentional interference with existing code, and allows ESP-r to run in normal mode if the BCVTBflag is set to 0. Currently, BCVTBflag=1 and BCVTBflag=2 are in use for the examples given in the previous sections. New applications shall be given a unique BCVTBflag.

	Note
	Using ESP-r in the BCVTB requires advanced ESP-r knowledge and skills. A BCVTB user that is new to ESP-r should first learn to use ESP-r before attempting to use ESP-r in BCVTB. A good starting point for learning is the ESP-r Cookbook.


5.6. Simulink		5.8. TRNSYS