Building Optimization Performance Tests
This repository contains 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/).
/testcasescontains test cases, including docs, models, and configuration settings./examplescontains code for interacting with a test case and running example tests with simple controllers. Those controllers are implemented in Python (Version 2.7 and 3.9), Julia (Version 1.0.3), and JavaScript (Version ECMAScript 2018)./parsingcontains code for a script that parses a Modelica model using signal exchange blocks and outputs a wrapper FMU and KPI json./testingcontains code for unit and functional testing of this software. See the README there for more information about running these tests./datacontains 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./forecastcontains code for returning boundary condition forecast, such as weather, schedules, and energy prices./kpiscontains code for calculating key performance indicators./docscontains design documentation and delivered workshop content.
- Install Docker.
- 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. - 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. - 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.
- 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.pyto test a simple proportional feedback controller on this test case over a two-day period. - Build and deploy
testcase1. Then, in a separate terminal, use$ cd examples/python/ && python testcase1_scenario.pyto test a simple proportional feedback controller on this test case over a test period defined using the/scenarioAPI. - Build and deploy
testcase2. Then, in a separate terminal, use$ cd examples/python/ && python testcase2.pyto test a simple supervisory controller on this test case over a two-day period.
- Build and deploy
-
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=testcase1to 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=testcase2to 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=testcase1or$ make remove-image Script=testcase2to removes containers, networks, volumes, and images associated with these Julia-based examples.
- Build and deploy
-
For JavaScript based controllers:
- In a separate terminal, use
$ cd examples/javascript && make build Script=testcase1 && make run Script=testcase1to test a simple proportional feedback controller on the testcase1 over a two-day period. - In a separate terminal, use
$ cd examples/javascript && make build Script=testcase2 && make run Script=testcase2to test a simple supervisory controller on the testcase2 over a two-day period. - Ince the test is done, use
$ make remove-image Script=testcase1or$ make remove-image Script=testcase2to removes containers, networks, volumes, and images, and use$ cd examples/javascript && rm geckodriverto remove the geckodriver file. - Note that those two controllers can also be executed by web browers, such as chrome or firefox.
- In a separate terminal, use
- Shutdown a test case container by selecting the container terminal window,
Ctrl+Cto close port, andCtrl+Dto exit the Docker container. - Remove the test case Docker image by
$ make remove-image TESTCASE=<testcase_dir_name>.
- To interact with a deployed test case, use the API defined in the table below by sending RESTful requests to:
https://127.0.0.1:5000/<request>
Example RESTful interaction:
- Receive a list of available measurement names and their metadata:
$ curl https://127.0.0.1:5000/measurements - Receive a forecast of boundary condition data:
$ curl https://127.0.0.1:5000/forecast - Advance simulation of test case 2 with new heating and cooling temperature setpoints:
$ curl https://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 point names (y) and metadata. | GET measurements |
| Receive control signal point names (u) and metadata. | GET inputs |
| Receive test result data for the given point name between the start and final time in seconds. | PUT results with arguments point_name=<string>, start_time=<value>, final_time=<value> |
| 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> |
| Receive current test scenario. | GET scenario |
Set test scenario. Setting the argument time_period performs an initialization with predefined start time and warmup period and will only simulate for predefined duration. |
PUT scenario with optional arguments electricity_price=<string>, time_period=<string>. See README in /testcases for options and test case documentation for details. |
| Receive BOPTEST version. | GET version |
This repository uses pre-commit to ensure that the files meet standard formatting conventions (such as line spacing, layout, etc).
Presently only a handful of checks are enabled and will expanded in the near future. To run pre-commit first install
pre-commit into your Python version using pip pip install pre-commit. Pre-commit can either be manually by calling
pre-commit run --all-files from within the BOPTEST checkout directory, or you can install pre-commit to be run automatically
as a hook on all commits by calling pre-commit install in the root directory of the BOPTEST GitHub checkout.
See the wiki for use cases and development requirements.
BOPTEST is implemented as a web-service in the boptest-service branch of this repository.
An OpenAI-Gym environment for BOPTEST is implemented in ibpsa/project1-boptest-gym.
A proposed BOPTEST home page and dashboard for creating accounts and sharing results is published here https://xd.adobe.com/view/0e0c63d4-3916-40a9-5e5c-cc03f853f40a-783d/.
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.