BOPTEST

https://ibpsa.github.io/project1-boptest/docs/
Admin
A framework for building control performance benchmarking with a RESTful API, test case repository,...
Tokens:31,979
Snippets:393
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### POST /advance Response Example

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

Example response from the POST /advance endpoint, providing the values of points at the end of the control step.

```json
{
    <point_name>:   // str, name of point
        <value>,    // float, point value at time at end of control step
    ...
}
```

--------------------------------

### PUT /scenario Response Example

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

Example of a successful response when setting test scenario parameters. It returns the updated values for the parameters that were successfully changed.

```json
{
    "electricity_price":<value>,        // str, if succeeded in changing then value, else None
    "time_period":                      // dict, if succeeded then initial measurements, else None
        {<point_name>:                  // str, name of point
         <value>,                       // float, point value at start time
         ...
        },
    "temperature_uncertainty": <value>, // str, if succeeded in changing then value, else None
    "solar_uncertainty": <value>,       // str, if succeeded in changing then value, else None
    "seed":<value>                      // int, if succeeded then value, else None
}
```

--------------------------------

### KPI Calculation Class Example

Source: https://ibpsa.github.io/project1-boptest/docs-design/appendix_KPI.html

Example of a KPI calculation class that should be present in the specified kpi_file. It must contain a 'calculation' function.

```python
class MovingAve(object):
def __init__(self, config, **kwargs):
    self.name=config.get(``name'')

def calculation(self,data):
    return sum(data[``x''])/len(data[``x''])

```

--------------------------------

### PUT /forecast Response Example

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

Example response structure for the PUT /forecast endpoint, containing time values and forecast values for specified points.

```json
{
    "time":
        <values>,   // array of floats, time values at interval for horizon
    <point_name>:   // str, name of point
        <values>,   // array of floats, forecast values at interval for horizon
    ...
}
```

--------------------------------

### PUT /results Response Example

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

Example response structure for the PUT /results endpoint, containing time values and point values over the specified period.

```json
{
    "time":
        <values>,   // array of floats, values of time in seconds over time period
    <point_name>:   // str, name of point
        <values>,   // array of floats, point values over time period
}
```

--------------------------------

### GET /kpi

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

Retrieves Key Performance Indicator (KPI) values calculated from the start time, excluding warmup periods. These metrics provide insights into the building's energy consumption, cost, emissions, and comfort levels.

```APIDOC
## GET /kpi

### Description
Receive KPI values. Calculated from start time and do not include warmup periods.

### Method
GET

### Endpoint
/kpi

### Parameters
#### Query Parameters
None

### Response
#### Success Response (200)
- **cost_tot** (float) - HVAC energy cost in $/m2 or Euro/m2
- **emis_tot** (float) - HVAC energy emissions in kgCO2e/m2
- **ener_tot** (float) - HVAC energy total in kWh/m2
- **pele_tot** (float) - HVAC peak electrical demand in kW/m2
- **pgas_tot** (float) - HVAC peak gas demand in kW/m2
- **pdih_tot** (float) - HVAC peak district heating demand in kW/m2
- **idis_tot** (float) - Indoor air quality discomfort in ppmh/zone
- **tdis_tot** (float) - Thermal discomfort in Kh/zone
- **time_rat** (float) - Computational time ratio in s/ss

#### Response Example
```json
{
    "cost_tot":<value>,
    "emis_tot":<value>,
    "ener_tot":<value>,
    "pele_tot":<value>,
    "pgas_tot":<value>,
    "pdih_tot":<value>,
    "idis_tot":<value>,
    "tdis_tot":<value>,
    "time_rat":<value>
}
```
```

--------------------------------

### GET /step

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/index.html

Retrieves the current simulation step.

```APIDOC
## GET /step

### Description
Retrieves the current simulation step.

### Method
GET

### Endpoint
/step

### Response
#### Success Response (200)
- **step** (integer) - The current simulation step.
```

--------------------------------

### GET /name

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/index.html

Retrieves the name of the BOPTEST system.

```APIDOC
## GET /name

### Description
Retrieves the name of the BOPTEST system.

### Method
GET

### Endpoint
/name

### Response
#### Success Response (200)
- **name** (string) - The name of the BOPTEST system.
```

--------------------------------

### Two-Day Simulation Example

Source: https://ibpsa.github.io/project1-boptest/docs-design/sources/architecture.rst.txt

This Python script demonstrates how to run a two-day simulation using the BOPTEST framework. It sets up the simulation environment and executes the simulation steps.

```python
import os
import sys
import logging

# Add BOPTEST root to Python path
project_root = os.path.dirname(os.path.abspath(__file__))
sys.path.insert(0, project_root)

# Import BOPTEST modules
from boptest.bop import BOPTest

# Setup logging
logging.basicConfig(level=logging.INFO)

# Initialize BOPTest instance
bopt = BOPTest()

# Simulation parameters
# Number of days to simulate
num_days = 2
# Simulation step size (e.g., 15 minutes)
step_size = 15 * 60  # seconds
# Total simulation steps
num_steps = int(num_days * 24 * 60 * 60 / step_size)

# Run simulation
print(f"Running simulation for {num_days} days...")
bopt.simulate(step=num_steps, step_size=step_size)
print("Simulation complete.")

# Get simulation results
results = bopt.get_simulation_results()

# Print some results (e.g., temperature)
print("Simulation Results (Sample):")
for i in range(0, len(results['time'])-1, 100):
    print(f"Time: {results['time'][i]}, Temperature: {results['Temperature_sensor']['value'][i]}")

```

--------------------------------

### GET /scenario

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/index.html

Retrieves the current scenario configuration.

```APIDOC
## GET /scenario

### Description
Retrieves the current scenario configuration.

### Method
GET

### Endpoint
/scenario

### Response
#### Success Response (200)
- **scenario** (object) - The current scenario configuration.
```

--------------------------------

### GET /version

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/index.html

Retrieves the current version of the BOPTEST system.

```APIDOC
## GET /version

### Description
Retrieves the current version of the BOPTEST system.

### Method
GET

### Endpoint
/version

### Response
#### Success Response (200)
- **version** (string) - The version string of BOPTEST.
```

--------------------------------

### GET /scenario

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/sources/api.rst.txt

Retrieves the current test scenario settings, including electricity price and time period.

```APIDOC
## GET /scenario

### Description
Receive current test scenario.

### Method
GET

### Endpoint
/scenario

### Parameters
#### Path Parameters
None.

#### Query Parameters
None.

### Response
#### Success Response (200)
- **electricity_price** (str) - The current electricity price scenario.
- **time_period** (str) - The current time period scenario.

#### Response Example
```json
{
  "electricity_price": "dynamic",
  "time_period": "winter"
}
```
```

--------------------------------

### KPI Calculation Class Example

Source: https://ibpsa.github.io/project1-boptest/docs-design/sources/appendix_KPI.rst.txt

An example of a Python class for calculating a KPI, specifically 'MovingAve', which calculates the average of input data 'x'.

```python
class MovingAve(object):
  def __init__(self, config, **kwargs):
      self.name=config.get("name")

  def calculation(self,data):
      return sum(data["x"])/len(data["x"])
```

--------------------------------

### PUT /initialize

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/sources/api.rst.txt

Initializes the simulation to a specified start time and warmup period, resetting history and KPI calculations.

```APIDOC
## PUT /initialize

### Description
Initialize simulation to a start time using a specified warmup period. Also resets point data history and KPI calculations.

### Method
PUT

### Endpoint
/initialize

### Parameters
#### Path Parameters
None.

#### Query Parameters
None.

#### Request Body
- **start_time** (float) - Required - The simulation start time in seconds.
- **warmup_period** (float) - Required - The length of the warmup period in seconds.

### Response
#### Success Response (200)
- **point_name** (str) - The name of a point in the test case.
  - **value** (float) - The value of the point at the simulation start time.

#### Response Example
```json
{
  "temperature": 20.5,
  "electricity_price": 0.15
}
```
```

--------------------------------

### Initialize Simulation

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

Initialize the simulation to a specified start time and warmup period. This action also resets point data history and KPI calculations. Requires 'start_time' and 'warmup_period' arguments.

```json
start_time      // required, float, start time in seconds
warmup_period   // required, float, warmup period length in seconds
```

```json
{
    "<point_name>":   // str, name of point
        <value>,    // float, point values at start time
    ...
}
```

--------------------------------

### GET /inputs

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/index.html

Retrieves a list of available inputs for the BOPTEST system.

```APIDOC
## GET /inputs

### Description
Retrieves a list of available inputs for the BOPTEST system.

### Method
GET

### Endpoint
/inputs

### Response
#### Success Response (200)
- **inputs** (array) - A list of input names.
```

--------------------------------

### Get KPI Values

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

Retrieve Key Performance Indicator (KPI) values calculated from the start time, excluding warmup periods. This endpoint returns a JSON object containing various performance metrics.

```json
{
    "cost_tot":<value>,
    "emis_tot":<value>,
    "ener_tot":<value>,
    "pele_tot":<value>,
    "pgas_tot":<value>,
    "pdih_tot":<value>,
    "idis_tot":<value>,
    "tdis_tot":<value>,
    "time_rat":<value>
}
```

--------------------------------

### GET /submit

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/index.html

Submits the simulation results.

```APIDOC
## GET /submit

### Description
Submits the simulation results.

### Method
GET

### Endpoint
/submit

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the results have been submitted.
```

--------------------------------

### GET /step

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/sources/api.rst.txt

Retrieves the current control step, which is the amount of simulation time that will pass in the next control step.

```APIDOC
## GET /step

### Description
Receive the current control step. This is the amount of simulation time that will pass when the next control step is taken.

### Method
GET

### Endpoint
/step

### Parameters
#### Path Parameters
None.

#### Query Parameters
None.

### Response
#### Success Response (200)
- **step** (float) - The control step duration in seconds.

#### Response Example
```json
{
  "step": 300.0
}
```
```

--------------------------------

### Get Current Scenario

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

Retrieve the current test scenario, including electricity price and time period configurations. No arguments are required.

```json
{
    "electricity_price":<value>     // str, current electricity price scenario
    "time_period":<value>           // str, current time period scenario
}
```

--------------------------------

### GET /kpi

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/index.html

Retrieves the Key Performance Indicators (KPIs) for the simulation.

```APIDOC
## GET /kpi

### Description
Retrieves the Key Performance Indicators (KPIs) for the simulation.

### Method
GET

### Endpoint
/kpi

### Response
#### Success Response (200)
- **kpi** (object) - The simulation KPIs.
```

--------------------------------

### Get BOPTEST Version

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

Retrieve the current BOPTEST version string. No arguments are required.

```json
{
    "version":"X.Y.Z"    // str, X.Y.Z
}
```

--------------------------------

### GET /measurements

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/index.html

Retrieves a list of available measurements from the BOPTEST system.

```APIDOC
## GET /measurements

### Description
Retrieves a list of available measurements from the BOPTEST system.

### Method
GET

### Endpoint
/measurements

### Response
#### Success Response (200)
- **measurements** (array) - A list of measurement names.
```

--------------------------------

### GET /name

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/sources/api.rst.txt

Retrieves the name of the currently deployed test case.

```APIDOC
## GET /name

### Description
Receive test case name.

### Method
GET

### Endpoint
/name

### Parameters
#### Path Parameters
None.

#### Query Parameters
None.

### Response
#### Success Response (200)
- **name** (str) - The name of the test case.

#### Response Example
```json
{
  "name": "test_case_1"
}
```
```

--------------------------------

### GET /inputs

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/sources/api.rst.txt

Retrieves a list of available control signal input point names and their associated metadata.

```APIDOC
## GET /inputs

### Description
Receive available control signal input point names (u) and metadata.

### Method
GET

### Endpoint
/inputs

### Parameters
#### Path Parameters
None.

#### Query Parameters
None.

### Response
#### Success Response (200)
- **point_name** (str) - The name of the input point.
  - **Description** (str) - A description of the input point.
  - **Unit** (str) - The unit of measurement for the input point.
  - **Minimum** (float or null) - The minimum value for the input point.
  - **Maximum** (float or null) - The maximum value for the input point.

#### Response Example
```json
{
  "solar_power": {
    "Description": "Solar power generation",
    "Unit": "W",
    "Minimum": 0.0,
    "Maximum": 10000.0
  }
}
```
```

--------------------------------

### GET /inputs

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

Retrieves a list of available control signal input point names and their associated metadata, including description, unit, minimum, and maximum values.

```APIDOC
## GET /inputs

### Description
Receive available control signal input point names (u) and metadata.

### Method
GET

### Endpoint
/inputs

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Response
#### Success Response (200)
- **point_name** (string) - The name of the input point.
  - **Description** (string) - Description of the point.
  - **Unit** (string) - Unit of the point.
  - **Minimum** (float or null) - Minimum value of the point.
  - **Maximum** (float or null) - Maximum value of the point.

### Response Example
```json
{
    "point_name": {
        "Description": "description of point",
        "Unit": "unit of point",
        "Minimum": null,
        "Maximum": null
    }
}
```
```

--------------------------------

### BACnet TTL Configuration Template

Source: https://ibpsa.github.io/project1-boptest/docs-design/testcasedev.html

This template defines the structure for the bacnet.ttl file, mapping BOPTEST points to BACnet objects. It includes prefixes for namespaces and examples for configuring BACnetDevice, analog-input, and analog-output points.

```turtle
@prefix bldg: <urn:example#> .
@prefix brick: <https://brickschema.org/schema/Brick#> .
@prefix bacnet: <http://data.ashrae.org/bacnet/2020#> .
@prefix unit: <http://qudt.org/vocab/unit/> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix ref: <https://brickschema.org/schema/Brick/ref#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<urn:example#> a owl:Ontology ;
    owl:imports <https://brickschema.org/schema/1.2/Brick#> .

bldg:boptest-proxy-device a bacnet:BACnetDevice ;
    bacnet:device-instance 599 .

bldg:<boptest_point_name> a brick:Point ;
    ref:hasExternalReference [
            bacnet:object-identifier "analog-input,n" ;
            bacnet:object-type "analog-input" ;
            bacnet:object-name "<boptest_point_name>" ;
            bacnet:objectOf bldg:boptest-proxy-device
    ] .

# ... Repeat for each BOPTEST measurement point 1:n and replace <boptest_point_name> with the BOPTEST point name.

bldg:<boptest_point_name> a brick:Point ;
    ref:hasExternalReference [
            bacnet:object-identifier "analog-output,m" ;
            bacnet:object-type "analog-output" ;
            bacnet:object-name "<boptest_point_name>" ;
            bacnet:objectOf bldg:boptest-proxy-device
    ] .

# ... Repeat for each BOPTEST input point 1:m and replace <boptest_point_name> with the BOPTEST point name. Only needed for inputs ending with _u and not _activate.

```

--------------------------------

### Get Available Inputs

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

Retrieve a list of available control signal input point names (u) along with their metadata such as description, unit, minimum, and maximum values. No arguments are required.

```json
{
    "<point_name>":                   // str, name of point
        {"Description": <value>,    // str, description of point
         "Unit": <value>,           // str, unit of point
         "Minimum": <value>,        // float or null, minimum point value
         "Maximum": <value>,        // float or null, maximum point value
         },
    ...
}
```

--------------------------------

### Define Room Air Temperature Input

Source: https://ibpsa.github.io/project1-boptest/docs-design/sources/appendix_KPI.rst.txt

Example of defining the room air temperature variable for KPI calculation using IBPSA.Utilities.IO.SignalExchange.Read.

```modelica
IBPSA.Utilities.IO.SignalExchange.Read TRooAir(KPIs="comfort",
  y(unit="K"),
  Description="Room air temperature"));
```

--------------------------------

### Config JSON Structure for Test Case Configuration

Source: https://ibpsa.github.io/project1-boptest/docs-design/sources/testcasedev.rst.txt

Defines the structure for 'config.json' to assign configuration and default values for a test case upon loading in BOPTEST. Includes settings for name, area, start time, warmup period, step, and optional resource file exclusion.

```json
{
    "name"          : <str>,                         // Name of test case
    "area"          : <float>,                       // Floor area in m^2 to be used for KPI calculation
    "start_time"    : <float>,                       // Default start time
    "warmup_period" : <float>,                       // Default warmup_period
    "step"          : <float>,                       // Default control step in seconds
    "resource_file_exclusion" : [<str>]              // Optional: List of data files within fmu /resources directory to exclude from loading into test case (e.g. "filename.csv")
}
```

--------------------------------

### Define Total HVAC Energy Input

Source: https://ibpsa.github.io/project1-boptest/docs-design/sources/appendix_KPI.rst.txt

Example of defining the total HVAC energy variable for KPI calculation using IBPSA.Utilities.IO.SignalExchange.Read.

```modelica
IBPSA.Utilities.IO.SignalExchange.Read ETotHVAC(KPIs="energy",
  y(unit="J"),
  Description="Total HVAC energy"));
```

--------------------------------

### Get Current Control Step

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

Retrieve the current control step, which represents the amount of simulation time that will advance with the next control action. No arguments are required.

```json
<step>  // float, control step in seconds
```

--------------------------------

### GET /measurements

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

Retrieves a list of available sensor signal output point names and their associated metadata, including description, unit, minimum, and maximum values.

```APIDOC
## GET /measurements

### Description
Receive available sensor signal output point names (y) and metadata.

### Method
GET

### Endpoint
/measurements

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Response
#### Success Response (200)
- **point_name** (string) - The name of the sensor point.
  - **Description** (string) - Description of the point.
  - **Unit** (string) - Unit of the point.
  - **Minimum** (float or null) - Minimum value of the point.
  - **Maximum** (float or null) - Maximum value of the point.

### Response Example
```json
{
    "point_name": {
        "Description": "description of point",
        "Unit": "unit of point",
        "Minimum": null,
        "Maximum": null
    }
}
```
```

--------------------------------

### KPI Class Initialization and Data Buffering

Source: https://ibpsa.github.io/project1-boptest/docs-design/sources/appendix_KPI.rst.txt

Initializes the KPI calculation class, imports data point mappings and buffer size, and sets up the data buffer.

```python
           self.model = model_class(config)
           # import data point mapping info
           self.data_points=config.get(``data_points'')
           # import the length of data array
           self.data_point_num=config.get(``data_point_num'')
           # initialize the data buffer
           self.data_buff=None
```

--------------------------------

### Deploy BOPTEST Locally with Docker Compose

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/getting_started.html

Build and deploy BOPTEST containers on your local machine. Use the --scale argument to run multiple test cases concurrently and --build to re-build containers.

```bash
docker compose up web worker provision
```

```bash
docker compose up web worker provision --scale worker=n
```

```bash
docker compose up web worker provision --build
```

--------------------------------

### PUT /initialize

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/index.html

Initializes the BOPTEST simulation.

```APIDOC
## PUT /initialize

### Description
Initializes the BOPTEST simulation.

### Method
PUT

### Endpoint
/initialize

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating initialization is complete.
```

--------------------------------

### GET /forecast_points

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/index.html

Retrieves the available forecast points.

```APIDOC
## GET /forecast_points

### Description
Retrieves the available forecast points.

### Method
GET

### Endpoint
/forecast_points

### Response
#### Success Response (200)
- **forecast_points** (array) - A list of available forecast point names.
```

--------------------------------

### Set Test Scenario Settings

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

Use this endpoint to configure various settings for a test scenario, such as electricity price, time period, and uncertainty levels for temperature and solar forecasts. It also allows setting a seed for repeatable random sampling.

```text
electricity_price       // optional, str, electricity price scenario, <"constant" or "dynamic" or "highly_dynamic">
time_period             // optional, str, time period scenario, see Test Case documention for options
temperature_uncertainty // optional, str, uncertainty level for outside dry bulb temperature forecast, <None or "low" or "medium" or "high">
solar_uncertainty       // optional, str, uncertainty level for outside global horizontal irradiation forecast, <None or "low" or "medium" or "high">
seed                    // optional, int, set for repeatable uncertainty sampling with uncertain forecasts
```

--------------------------------

### HTML Template for Test Case Documentation

Source: https://ibpsa.github.io/project1-boptest/docs-design/sources/testcasedev.rst.txt

This HTML template provides a basic structure for documenting test cases, including sections for building design, HVAC systems, and scenario information.

```html
<html>
<h3>Section 1</h3>
<h4>Subsection 1.1</h4>
<p>
xxx
</p>
<h4>Subsection 1.2</h4>
<p>
xxx
</p>
<h3>Section 2</h3>
<h4>Subsection 2.1</h4>
<p>
xxx
</p>
<h4>Subsection 2.2</h4>
<p>
xxx
</p>
</html>
```

--------------------------------

### GET /forecast_points

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

Retrieves a list of available forecast point names along with their descriptions and units.

```APIDOC
## GET /forecast_points

### Description
Receive available forecast point names and metadata.

### Method
GET

### Endpoint
/forecast_points

### Parameters
None.

### Response
#### Success Response (200)
- **point_name** (str) - name of point
  - **Description** (str) - description of point
  - **Unit** (str) - unit of point

### Response Example
```json
{
  "T_amb": {
    "Description": "Outside dry bulb temperature",
    "Unit": "K"
  },
  "Q_h": {
    "Description": "Outside global horizontal irradiation",
    "Unit": "W/m^2"
  }
}
```
```

--------------------------------

### Docker Compose for BOPTEST Components

Source: https://ibpsa.github.io/project1-boptest/docs-design/sources/architecture.rst.txt

This Docker Compose file defines and links the services required for BOPTEST, including the web server, simulation manager, database, and file storage.

```yaml
version: "3.7"
services:
  webserver:
    build: ./web/server
    ports:
      - "5000:5000"
    volumes:
      - ./web/server:/app
    environment:
      - BOPTEST_HOME=/app
    depends_on:
      - database
      - queue
      - filestorage

  simulationmanager:
    build: ./worker/runsimulation
    volumes:
      - ./worker/runsimulation:/app
    environment:
      - BOPTEST_HOME=/app
    depends_on:
      - database
      - queue
      - filestorage

  database:
    image: mongo:latest
    ports:
      - "27017:27017"
    volumes:
      - boptest-db:/data/db

  queue:
    image: rabbitmq:latest
    ports:
      - "5672:5672"

  filestorage:
    image: minio/minio
    ports:
      - "9000:9000"
    volumes:
      - boptest-fs:/data
    environment:
      - MINIO_ROOT_USER=minioadmin
      - MINIO_ROOT_PASSWORD=minioadmin
    command: server /data --console-address ":9001"

volumes:
  boptest-db:
  boptest-fs:

```

--------------------------------

### POST /advance

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

Advances the simulation by one control step, optionally accepting control inputs and returning measurements at the end of the step.

```APIDOC
## POST /advance

### Description
Advance simulation one control step with optional control input(s) and receive measurements. If specified, control input value(s) will be constant over the control step. Use <input_name_u> to specify value and corresponding <input_name_activate> to enable value overwrite for the input.

### Method
POST

### Endpoint
/advance

### Parameters
#### Request Body
- **input_name_u** (float) - Optional - value of input point to overwrite
- **input_name_activate** (float) - Optional - enable corresponding input overwrite if greater than 0 (default is 0)

### Request Example
```json
{
  "u_heater_u": 1000.0,
  "activate_heater_u": 1.0
}
```

### Response
#### Success Response (200)
- **point_name** (str) - name of point
  - **value** (float) - point value at time at end of control step

### Response Example
```json
{
  "T_amb": 283.2,
  "T_in": 293.5,
  "Q_h": 10.5
}
```
```

--------------------------------

### Get Test Case Name

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

Retrieve the name of the currently deployed test case. No arguments are required.

```json
{
    "name":"<testcase_name>"    // str, name of test case
}
```

--------------------------------

### POST /advance

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/sources/api.rst.txt

Advances the simulation by one control step, optionally accepting control inputs and returning measurements. Control inputs can be set to a constant value for the duration of the step.

```APIDOC
## POST /advance

### Description
Advance simulation one control step with optional control input(s) and receive measurements. If specified, control input value(s) will be constant over the control step. Use <input_name_u> to specify value and corresponding <input_name_activate> to enable value overwrite for the input.

### Method
POST

### Endpoint
/advance

### Parameters
#### Request Body
- **<input_name_u>** (float) - Optional - Value of input point to overwrite
- **<input_name_activate>** (float) - Optional - Enable corresponding input overwrite if greater than 0 (default is 0)

### Response
#### Success Response (200)
- **<point_name>** (float) - Point value at time at end of control step
```

--------------------------------

### Deploy a Test Case via API

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/sources/getting_started.rst.txt

Select a test case to deploy by sending a POST request to the BOPTEST API. The response includes a unique test ID required for subsequent API calls.

```http
POST <url>/testcases/<testcase_name>/select
```

--------------------------------

### GET /measurements

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/sources/api.rst.txt

Retrieves a list of available sensor signal output point names and their associated metadata.

```APIDOC
## GET /measurements

### Description
Receive available sensor signal output point names (y) and metadata.

### Method
GET

### Endpoint
/measurements

### Parameters
#### Path Parameters
None.

#### Query Parameters
None.

### Response
#### Success Response (200)
- **point_name** (str) - The name of the sensor point.
  - **Description** (str) - A description of the sensor point.
  - **Unit** (str) - The unit of measurement for the sensor point.
  - **Minimum** (float or null) - The minimum value for the sensor point.
  - **Maximum** (float or null) - The maximum value for the sensor point.

#### Response Example
```json
{
  "temperature": {
    "Description": "Outside dry bulb temperature",
    "Unit": "C",
    "Minimum": -20.0,
    "Maximum": 40.0
  }
}
```
```

--------------------------------

### PUT /step

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/index.html

Advances the simulation by one step.

```APIDOC
## PUT /step

### Description
Advances the simulation by one step.

### Method
PUT

### Endpoint
/step

### Response
#### Success Response (200)
- **step** (integer) - The new current simulation step.
```

--------------------------------

### GET /submit

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/sources/api.rst.txt

Submits simulation test results to an online dashboard. This action can only be performed after a complete test scenario has finished.

```APIDOC
## GET /submit

### Description
Post test results to online dashboard located at (url coming soon). A complete test scenario (including full time period) must be finished before results can be submitted to the dashboard.

### Method
GET

### Endpoint
/submit

### Parameters
#### Query Parameters
- **api_key** (str) - Required - API key generated for user account on dashboard.
```

--------------------------------

### Test Case Repository Structure

Source: https://ibpsa.github.io/project1-boptest/docs-design/testcasedev.html

Illustrates the directory and file structure for a test case repository, including model files, resources, documentation, and BACnet definitions.

```tree
TestCaseName                    // Test case directory name
|--model                        // Model directory
|  |--Resources                 // Resources directory with test case data
|  |--model.mo                  // Modelica model file
|  |--model.fmu                 // BOPTEST ready FMU
|  |  |--resources              // Resources directory
|  |  |  |--kpis.json           // JSON mapping outputs to KPI calculations
|  |  |  |--days.json           // JSON mapping time period names to day number for simulation
|  |  |  |--config.json         // BOPTEST configuration file and sets defaults
|  |  |  |--weather.mos         // Weather data for model simulation in Modelica
|  |  |  |--weather.csv         // Weather data for forecasting
|  |  |  |--occupancy.csv       // Occupancy schedules
|  |  |  |--internalGains.csv   // Internal gain schedules
|  |  |  |--prices.csv          // Energy pricing schedules
|  |  |  |--emissions.csv       // Energy emission factor schedules
|  |  |  |--setpoints.csv       // Thermal  and IAQ comfort region schedules
|  |--bacnet.ttl                // BACnet object definition file
|--doc                          // Documentation directory
|  |--doc.html                  // Copy of .mo file documentation
|  |--images                    // Image directory
|  |  |--image1.png             // Image for model documentation

```

--------------------------------

### Calculate KPIs from Simulation Data

Source: https://ibpsa.github.io/project1-boptest/docs-design/appendix_KPI.html

Python function to calculate 'energy' and 'comfort' KPIs using stored simulation signals. Requires signals to be measured in Joules and Kelvin respectively. Converts energy to kWh and discomfort to K-h.

```python
def get_kpis(self):
        """Returns KPI data.

        Requires standard sensor signals.

        Parameters
        ----------
        None

        Returns
        kpis : dict
            Dictionary containing KPI names and values.
            {<kpi_name>:<kpi_value>}

        """
        kpis = dict()
        # Calculate each KPI using json for signalsand save
        in dictionary
        for kpi in self.kpi_json.keys():
            print(kpi, type(kpi))
            if kpi == 'energy':
                # Calculate total energy [KWh - assumes measured
                in J]
                E = 0
                for signal in self.kpi_json[kpi]:
                    E = E + self.y_store[signal][-1]
                # Store result in dictionary
                kpis[kpi] = E*2.77778e-7 # Convert to kWh
            elif kpi == 'comfort':
                # Calculate total discomfort [K-h = assumes
                measured in K]
                tot_dis = 0
                heat_setpoint = 273.15+20
                for signal in self.kpi_json[kpi]:
                    data = np.array(self.y_store[signal])
                    dT_heating = heat_setpoint - data
                    dT_heating[dT_heating<0]=0
                    tot_dis = tot_dis + trapz(dT_heating,
                    self.y_store['time'])
                    /3600
                # Store result in dictionary
                kpis[kpi] = tot_dis

        return kpis

```

--------------------------------

### Get Available Forecast Point Names and Metadata

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

This endpoint retrieves a list of all available forecast point names along with their descriptions and units.

```json
{
    <point_name>:                   // str, name of point
        {"Description": <value>,    // str, description of point
         "Unit": <value>,           // str, unit of point
         },
    ...
}
```

--------------------------------

### POST /advance

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/index.html

Advances the simulation by a specified number of steps.

```APIDOC
## POST /advance

### Description
Advances the simulation by a specified number of steps.

### Method
POST

### Endpoint
/advance

### Parameters
#### Request Body
- **steps** (integer) - Required - The number of steps to advance.

### Response
#### Success Response (200)
- **step** (integer) - The new current simulation step.
```

--------------------------------

### Advance Simulation Step with Control Inputs

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

Advance the simulation by one control step. Optionally provide control input values and activate their overwrite for the duration of the step.

```text
<input_name_u>          // optional, float, value of input point to overwrite
<input_name_activate>   // optional, float, enable corresponding input overwrite if greater than 0 (default is 0)
```

--------------------------------

### PUT /scenario

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/sources/api.rst.txt

Sets the test scenario, allowing configuration of electricity price, time period, and forecast uncertainties.

```APIDOC
## PUT /scenario

### Description
Set test scenario settings. Setting ``time_period`` results in similar behavior to ``PUT /initialize``, except uses a pre-determined start time and warmup period as defined within BOPTEST according to the selected scenario. Uncertain forecasts set with ``temperature_uncertainty`` or ``solar_uncertainty`` are updated with new error at hourly intervals at the start of each hour. Error for sub-hour intervals is interpolated linearly. Underlying error models are based on [Zhe25]_.

### Method
PUT

### Endpoint
/scenario

### Parameters
#### Path Parameters
None.

#### Query Parameters
None.

#### Request Body
- **electricity_price** (str) - Optional - The electricity price scenario. Accepted values: "constant", "dynamic", or "highly_dynamic".
- **time_period** (str) - Optional - The time period scenario. Refer to Test Case documentation for available options.
- **temperature_uncertainty** (str) - Optional - The uncertainty level for the outside dry bulb temperature forecast. Accepted values: "low", "medium", or "high".
- **solar_uncertainty** (str) - Optional - The uncertainty level for the solar forecast. Accepted values: "low", "medium", or "high".

### Response
#### Success Response (200)
No specific response body is defined for success, typically an empty body or a confirmation message.

#### Response Example
(No example provided in source)
```

--------------------------------

### Get Available Measurements

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

Retrieve a list of available sensor signal output point names (y) along with their metadata such as description, unit, minimum, and maximum values. No arguments are required.

```json
{
    "<point_name>":           // str, name of point
        {"Description": ,   // str, description of point
         "Unit": ,          // str, unit of point
         "Minimum": ,       // float or null, minimum point value
         "Maximum": ,       // float or null, maximum point value
         },
    ...
}
```

--------------------------------

### Configure Temperature and Solar Uncertainty

Source: https://ibpsa.github.io/project1-boptest/docs-design/forecasts.html

Set forecast uncertainty levels for temperature and solar irradiation using the BOPTEST API. Options include 'None' for deterministic forecasts, or 'low', 'medium', 'high' for stochastic scenarios. A 'seed' can be provided for reproducible results.

```python
scenario = {
    "temperature_uncertainty": "medium",
    "solar_uncertainty": "low",
    "seed": 123
}

client.scenario.set(scenario)
```

--------------------------------

### GET /submit

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

Posts test results to an online dashboard. This endpoint is used after a complete test scenario has finished. An API key is required for authentication, and optional tags can be provided to categorize the results.

```APIDOC
## GET /submit

### Description
Post test results to online dashboard located at (url coming soon). A complete test scenario (including full time period) must be finished before results can be submitted to the dashboard.

### Method
GET

### Endpoint
/submit

### Parameters
#### Query Parameters
- **api_key** (str) - Required - API key generated for user account on dashboard.
- **tag<n>** (str) - Optional - Tag to characterize result and which can be filtered upon in the online dashboard. Up to 10 tags are allowed, specifed by <n>=1-10.

### Response
#### Success Response (200)
- **identifier** (str) - Unique identifier for result posted to dashboard

#### Response Example
```json
{
    "identifier":<uid>
}
```
```

--------------------------------

### PUT /forecast

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/sources/api.rst.txt

Sets boundary condition forecasts from the current time onwards. Requires a list of point names, forecast horizon, and interval.

```APIDOC
## PUT /forecast

### Description
Receive boundary condition forecasts from current time.

### Method
PUT

### Endpoint
/forecast

### Parameters
#### Request Body
- **point_names** (list of str) - Required - Name of points
- **horizon** (float) - Required - Horizon of forecast in seconds
- **interval** (float) - Required - Interval of forecast in seconds

### Response
#### Success Response (200)
- **time** (array of floats) - Time values at interval for horizon
- **<point_name>** (array of floats) - Forecast values at interval for horizon
```

--------------------------------

### Receive Boundary Condition Forecasts

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/api.html

Use this endpoint to request boundary condition forecasts for specified point names, horizon, and interval. The response includes time values and forecast values for each requested point.

```text
point_names     // required, list of str, name of points
horizon         // required, float, horizon of forecast in seconds
interval        // required, float, interval of forecast in seconds
```

--------------------------------

### Deploy a Test Case via Public Web Service API

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/getting_started.html

Send a POST request to the public BOPTEST API endpoint to select a test case and receive a unique test ID. This ID is required for all subsequent API calls.

```http
POST https://api.boptest.net/testcases/<testcase_name>/select
```

--------------------------------

### Shutdown Local BOPTEST Instance

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/getting_started.html

Execute this command in the root directory to completely shut down the BOPTEST Docker environment. This is the recommended method to prevent potential issues during redeployment.

```bash
docker compose down
```

--------------------------------

### PUT /scenario

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/index.html

Updates the scenario configuration.

```APIDOC
## PUT /scenario

### Description
Updates the scenario configuration.

### Method
PUT

### Endpoint
/scenario

### Parameters
#### Request Body
- **scenario** (object) - Required - The new scenario configuration.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the scenario has been updated.
```

--------------------------------

### PUT /step

Source: https://ibpsa.github.io/project1-boptest/docs-userguide/sources/api.rst.txt

Sets the current control step, determining the simulation time duration for the next control action.

```APIDOC
## PUT /step

### Description
Set the current control step. This is the amount of simulation time that will pass when the next control step is taken.

### Method
PUT

### Endpoint
/step

### Parameters
#### Path Parameters
None.

#### Query Parameters
None.

#### Request Body
- **step** (float) - Required - The control step duration in seconds.

### Response
#### Success Response (200)
- **step** (str) - The set control step in seconds.

#### Response Example
```json
{
  "step": "300.0"
}
```
```
Tokens:
Raw