IBPSA Project 1 - BOPTEST

Building Optimization Performance Tests

This repository contains prototype code for the Building Optimization Performance Test framework (BOPTEST) that is being developed as part of the IBPSA Project 1 (https://ibpsa.github.io/project1/).

Structure

• /testcases contains test cases, including docs, models, and configuration settings.
• /examples contains prototype code for interacting with a test case and running example tests with simple controllers. Those controllers are implemented in both Python (Version 2.7) and Julia (Version 1.0.3).
• /parsing contains prototype code for a script that parses a Modelica model using signal exchange blocks and outputs a wrapper FMU and KPI json.
• /template contains template Modelica code for a test case emulator model.
• /testing contains code for unit and functional testing of this software. See the README there for more information about running these tests.
• /data contains prototype code for generating and managing data associated with test cases. This includes boundary conditions, such as weather, schedules, and energy prices, as well as a map of test case FMU outputs needed to calculate KPIs.
• /forecast contains prototype code for returning boundary condition forecast, such as weather, schedules, and energy prices.
• /kpis contains prototype code for calculating key performance indicators.
• /docs contains design requirements and guide documentation.

Quick-Start to Run Test Cases

1. Install Docker
2. Build the test case by $ make build TESTCASE=<testcase_dir_name> where <testcase_dir_name> is the name of the test case subdirectory located in /testcases.
3. Deploy the test case by $ make run TESTCASE=<testcase_dir_name> where <testcase_dir_name> is the name of the test case subdirectory located in /testcases.
4. In a separate process, use the test case API defined below to interact with the test case using your test controller. Alternatively, view and run an example test controller as described in the next step.
5. Run an example test controller:

• For Python-based example controllers:

  • Build and deploy testcase1. Then, in a separate terminal, use $ cd examples/python/ && python testcase1.py to test a simple proportional feedback controller on this test case over a two-day period.
  • Build and deploy testcase2. Then, in a separate terminal, use $ cd examples/python/ && python testcase2.py to test a simple supervisory controller on this test case over a two-day period.

• For Julia-based example controllers:

  • Build and deploy testcase1. Then, in a separate terminal, use $ cd examples/julia && make build Script=testcase1 && make run Script=testcase1 to test a simple proportional feedback controller on this test case over a two-day period. Note that the Julia-based controller is run in a separate Docker container.
  • Build and deploy testcase2. Then, in a separate terminal, use $ cd examples/julia && make build Script=testcase2 && make run Script=testcase2 to test a simple supervisory controller on this test case over a two-day period. Note that the Julia-based controller is run in a separate Docker container.
  • Once either test is done, use $ make remove-image Script=testcase1 or $ make remove-image Script=testcase2 to removes containers, networks, volumes, and images associated with these Julia-based examples.

6. Shutdown a test case container by selecting the container terminal window, Ctrl+C to close port, and Ctrl+D to exit the Docker container.
7. Remove the test case Docker image by $ make remove-image TESTCASE=<testcase_dir_name>.

Test Case RESTful API

• To interact with a deployed test case, use the API defined in the table below by sending RESTful requests to: http://127.0.0.1:5000/<request>

Example RESTful interaction:

• Receive a list of available measurement names and their metadata: $ curl http://127.0.0.1:5000/measurements
• Receive a forecast of boundary condition data: $ curl http://127.0.0.1:5000/forecast
• Advance simulation of test case 2 with new heating and cooling temperature setpoints: $ curl http://127.0.0.1:5000/advance -d '{"oveTSetRooHea_u":293.15,"oveTSetRooHea_activate":1, "oveTSetRooCoo_activate":1,"oveTSetRooCoo_u":298.15}' -H "Content-Type: application/json". Leave an empty json to advance the simulation using the setpoints embedded in the model.

Interaction	Request
Advance simulation with control input and receive measurements	POST advance with json data "{<input_name>:}"
Initialize simulation to a start time using a warmup period in seconds	PUT initialize with arguments start_time=<value>, warmup_time=<value>
Receive communication step in seconds	GET step
Set communication step in seconds	PUT step with argument step=<value>
Receive sensor signal names (y) and metadata	GET measurements
Receive control signals names (u) and metadata	GET inputs
Receive test result data	GET results
Receive test KPIs	GET kpi
Receive test case name	GET name
Receive boundary condition forecast from current communication step	GET forecast
Receive boundary condition forecast parameters in seconds	GET forecast_parameters
Set boundary condition forecast parameters in seconds	PUT forecast_parameters with arguments horizon=<value>, interval=<value>

More Information

See the wiki for use cases and development requirements.

Proposed Interface Design

A proposed BOPTEST home page and interface for creating accounts and sharing results is published here https://xd.adobe.com/view/0e0c63d4-3916-40a9-5e5c-cc03f853f40a-783d/.

Publications

D. Blum, F. Jorissen, S. Huang, Y. Chen, J. Arroyo, K. Benne, Y. Li, V. Gavan, L. Rivalin, L. Helsen, D. Vrabie, M. Wetter, and M. Sofos. (2019). “Prototyping the BOPTEST framework for simulation-based testing of advanced control strategies in buildings.” In Proc. of the 16th International Conference of IBPSA, Sep 2 – 4. Rome, Italy.