### Instantiate BOPTEST-Gym Environment

Source: https://github.com/ibpsa/project1-boptest/blob/master/docs/workshops/RlemWorkshop_20231112/Introduction_to_the_BOPTEST_framework.ipynb

Imports the BoptestGymEnv class and instantiates a BOPTEST-Gym environment. This example connects to a BOPTEST service, specifies a test case, defines the action and observation spaces, and sets episode parameters like start time, duration, warmup period, and step period.

```python
import sys
sys.path.insert(0,'boptestGymService')
from boptestGymService.boptestGymEnv import BoptestGymEnv

# url for the BOPTEST service
url = 'https://api.boptest.net'

# Instantiate environment
env = BoptestGymEnv(url                   = url,
                    testcase              = 'bestest_hydronic_heat_pump',
                    actions               = ['oveHeaPumY_u'],
                    observations          = {'reaTZon_y':(280.,310.)},
                    random_start_time     = False,
                    start_time            = 31*24*3600,
                    max_episode_length    = 24*3600,
                    warmup_period         = 24*3600,
                    step_period           = 3600)
```

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

### Start all services with Podman

Source: https://github.com/ibpsa/project1-boptest/blob/master/PODMAN-MIGRATION.md

Starts all services in detached mode using Podman Compose.

```bash
podman-compose up -d
```

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

### Create a Basic Client

Source: https://github.com/ibpsa/project1-boptest/blob/master/examples/python/autogenerated_client/output/README.md

Instantiate the client with the base URL of the API. This is the starting point for all API interactions.

```python
from boptest_service_api_client import Client

client = Client(base_url="https://api.example.com")
```

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

### Install Wheel in Non-Poetry Project

Source: https://github.com/ibpsa/project1-boptest/blob/master/examples/python/autogenerated_client/output/README.md

Install the built wheel distribution of the Python client package into a project that does not use Poetry. Use pip for installation.

```bash
pip install <path-to-wheel>
```

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

### Run Python Example Controller: testcase2

Source: https://github.com/ibpsa/project1-boptest/blob/master/README.md

Execute a simple supervisory controller on testcase2 over a two-day period. Ensure testcase2 is built and deployed first.

```bash
cd examples/python/ && python testcase2.py
```

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

### Select and Start a BOPTEST Test Case

Source: https://github.com/ibpsa/project1-boptest/blob/master/docs/workshops/RlemWorkshop_20231112/Introduction_to_the_BOPTEST_framework.ipynb

Selects a test case and starts a new session, returning a unique test ID. It includes error handling for stopping a previously running test case.

```python
import requests

# url for the BOPTEST service
url = 'http://api.boptest.net'

# Select test case and get identifier
testcase = 'bestest_hydronic_heat_pump'
# Check if already started a test case and stop it if so before starting another
try:
  requests.put('{0}/stop/{1}'.format(url, testid))
except:
  pass
# Select and start a new test case
testid =
requests.post('{0}/testcases/{1}/select'.format(url,testcase)).json()['testid']
```

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

### Install Gymnasium and Stable Baselines 3

Source: https://github.com/ibpsa/project1-boptest/blob/master/docs/workshops/BS23Workshop_20230904/Introduction_to_the_BOPTEST_framework_BS2023.ipynb

Installs the Gymnasium library (version 0.28.1) and Stable Baselines 3 (version 2.0.0). These libraries are required for using BOPTEST-Gym and its associated RL algorithms.

```python
!pip install gymnasium==0.28.1 stable-baselines3==2.0.0
```

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

### Compile Documentation to PDF

Source: https://github.com/ibpsa/project1-boptest/blob/master/docs/design/README.md

Use this command to compile the project documentation into PDF format. LaTeX must be installed on your system.

```bash
$ make latex
```

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

### Initialize Test Case with Specific Time and Warm-up Period

Source: https://github.com/ibpsa/project1-boptest/blob/master/docs/workshops/BS25Workshop_20250828/Introduction_to_the_BOPTEST_framework.ipynb

Initializes the test case to a specific start time with a defined warm-up period. This allows for testing controllers over arbitrary periods within the year. The warm-up period simulates the model before the start time to establish initial conditions.

```APIDOC
## PUT /initialize

### Description
Initializes the test case to a specific start time with a defined warm-up period. This allows for testing controllers over arbitrary periods within the year. The warm-up period simulates the model before the start time to establish initial conditions.

### Method
PUT

### Endpoint
/initialize/{test_id}

### Parameters
#### Path Parameters
- **test_id** (string) - Required - The identifier for the test case.

#### Request Body
- **start_time** (integer) - Required - The start time in seconds from the beginning of the year.
- **warmup_period** (integer) - Required - The duration of the warm-up period in seconds before the `start_time`.

### Request Example
```python
{
  "start_time": 31*24*3600, 
  "warmup_period": 7*24*3600
}
```

### Response
#### Success Response (200)
- **payload** (object) - Contains the current values of measurement points, including 'time'.
  - **time** (float) - The current simulation time in days.
  - **reaTZon_y** (float) - The zone temperature measurement.

#### Response Example
```json
{
  "payload": {
    "reaTZon_y": 294.514471442540776,
    "time": 31.0
  }
}
```
```

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

### Initialize Simulation

Source: https://github.com/ibpsa/project1-boptest/blob/master/README.md

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

```APIDOC
## PUT initialize/{testid}

### Description
Initializes the simulation to a specified start time and warmup period. This also resets historical data for points and KPI calculations.

### Method
PUT

### Endpoint
`/initialize/{testid}`

### Parameters
#### Path Parameters
- **testid** (string) - Required - The unique identifier of the test case.

#### Query Parameters
- **start_time** (string) - Required - The desired start time for the simulation.
- **warmup_period** (integer) - Required - The duration of the warmup period in seconds.

### Request Example
`PUT /initialize/unique_test_id_123?start_time=2024-01-01T00:00:00&warmup_period=3600`

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of initialization.

#### Response Example
{
  "status": 200,
  "message": "Simulation initialized successfully.",
  "payload": null
}
```

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

### Run Python 2.7 Controller Tests

Source: https://github.com/ibpsa/project1-boptest/blob/master/testing/README.md

Execute example controllers implemented in Python within a Python 2.7 environment. This is defined by the '.travis.yml' configuration.

```bash
$ make test_python2
```

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

### Get BOPTEST Version

Source: https://github.com/ibpsa/project1-boptest/blob/master/README.md

Use this endpoint to retrieve the current version of BOPTEST. No setup or special imports are required.

```http
GET version
```

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

### Run Python Example Controller: testcase1

Source: https://github.com/ibpsa/project1-boptest/blob/master/README.md

Execute a simple proportional feedback controller on testcase1 over a two-day period. Ensure testcase1 is built and deployed first.

```bash
cd examples/python/ && python testcase1.py
```

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

### Reset BOPTEST-Gym Environment and Get Initial Observation

Source: https://github.com/ibpsa/project1-boptest/blob/master/docs/workshops/BS23Workshop_20230904/Introduction_to_the_BOPTEST_framework_BS2023.ipynb

Resets the BOPTEST-Gym environment to its initial state before the episode starts and retrieves the first observation. The observation is typically in Kelvin and may require conversion to Celsius.

```python
obs, _ = env.reset()
print('Zone temperature: {:.2f} degC'.format(obs[0]-273.15))
print('Episode starting day: {:.1f} (from beginning of the year)'.format(env.start_time/24/3600))
```

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

### Run Python Example Controller: testcase1 with Scenario API

Source: https://github.com/ibpsa/project1-boptest/blob/master/README.md

Test a simple proportional feedback controller on testcase1 using a test period defined via the /scenario API. Ensure testcase1 is built and deployed first.

```bash
cd examples/python/ && python testcase1_scenario.py
```

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

### Run Julia Example Controller: testcase1

Source: https://github.com/ibpsa/project1-boptest/blob/master/README.md

Test a simple proportional feedback controller on testcase1 over a two-day period. This controller runs in a separate Docker container. Ensure testcase1 is built and deployed first.

```bash
cd examples/julia && make build Script=testcase1 && make run Script=testcase1
```

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

### KPI Calculation Class Example

Source: https://github.com/ibpsa/project1-boptest/blob/master/docs/design/source/appendix_KPI.md

This class, 'MovingAve', is an example of a KPI calculation module. It should 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''])
```

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

### Remove Julia Example Docker Image

Source: https://github.com/ibpsa/project1-boptest/blob/master/README.md

Remove Docker containers, networks, volumes, and images associated with a Julia-based example. Use either 'testcase1' or 'testcase2' as the Script argument.

```bash
make remove-image Script=testcase1
```

```bash
make remove-image Script=testcase2
```

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

### Compile Documentation to HTML

Source: https://github.com/ibpsa/project1-boptest/blob/master/docs/design/README.md

Use this command to compile the project documentation into HTML format. The output will be available in the \"/build\" subdirectory.

```bash
$ make html
```

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

### Get Current Test Case Scenario

Source: https://github.com/ibpsa/project1-boptest/blob/master/docs/workshops/BS21Workshop_20210831/Introduction_to_the_BOPTEST_framework.ipynb

Retrieves the current test case scenario configuration using the GET /scenario API. Useful for checking the active scenario settings.

```python
requests.get('{0}/scenario/{1}'.format(url, testid)).json()['payload']
```

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

### Deploy BACnet Device for a Test Case

Source: https://github.com/ibpsa/project1-boptest/blob/master/bacnet/README.md

Run this command to deploy the BACnet device and objects for a specific test case. Initialize it with start time and warmup period.

```bash
$ python BopTestProxy.py bestest_air 0 0
```

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

### Initialize BOPTEST Scenario and Controller

Source: https://github.com/ibpsa/project1-boptest/blob/master/docs/workshops/BS25Workshop_20250828/Introduction_to_the_BOPTEST_framework.ipynb

Initializes a BOPTEST scenario with a specific time period and electricity price, sets the control step to one hour, and instantiates a custom proportional controller. This setup is used for simulating and testing control algorithms.

```python
# Initialize scenario
y = requests.put('{0}/scenario/{1}'.format(url, testid),
                 json={'time_period':'peak_heat_day',
                       'electricity_price':'dynamic'}).json()['payload']['time_period']
# Set control step
requests.put('{0}/step/{1}'.format(url, testid), json={'step':3600})
# Instantiate controller
con = Controller_Proportional(TSet=273.15+21, k_p=5.)
```

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

### Run Julia Example Controller: testcase2

Source: https://github.com/ibpsa/project1-boptest/blob/master/README.md

Test a simple supervisory controller on testcase2 over a two-day period. This controller runs in a separate Docker container. Ensure testcase2 is built and deployed first.

```bash
cd examples/julia && make build Script=testcase2 && make run Script=testcase2
```

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

### Select and Start a Test Case

Source: https://github.com/ibpsa/project1-boptest/blob/master/docs/workshops/BS21Workshop_20210831/Introduction_to_the_BOPTEST_framework.ipynb

Selects a test case and starts a new one, retrieving a unique test ID for future interactions. Handles potential errors if a test case is already running.

```python
testcase = 'bestest_hydronic_heat_pump'
try:
  requests.put('{0}/stop/{1}'.format(url, testid))
except:
  pass
testid =
requests.post('{0}/testcases/{1}/select'.format(url,testcase)).json()['testid']
```

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

### Instantiate BOPTEST-Gym Environment

Source: https://github.com/ibpsa/project1-boptest/blob/master/docs/workshops/BS23Workshop_20230904/Introduction_to_the_BOPTEST_framework_BS2023.ipynb

Initializes a BOPTEST-Gym environment with specified test case, actions, observations, and simulation parameters. Ensure the BOPTEST-service URL is correctly set.

```python
env = BoptestGymEnv(
    url                   = url,
    testcase              = 'bestest_hydronic_heat_pump',
    actions               = ['oveHeaPumY_u'],
    observations          = {'reaTZon_y':(280.,310.)},
    random_start_time     = False,
    start_time            = 31*24*3600,
    max_episode_length    = 24*3600,
    warmup_period         = 24*3600,
    step_period           = 3600)

```

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

### Run provision service with Podman

Source: https://github.com/ibpsa/project1-boptest/blob/master/PODMAN-MIGRATION.md

Executes the provision service in a temporary container to upload test cases.

```bash
podman-compose run --rm provision
```

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

### Retrieve Control Inputs and Measurements

Source: https://github.com/ibpsa/project1-boptest/blob/master/docs/workshops/RlemWorkshop_20231112/Introduction_to_the_BOPTEST_framework.ipynb

Use the GET /inputs and GET /measurements BOPTEST API endpoints to retrieve available control inputs and measurement points for a given test ID. The results are returned as JSON payloads.

```python
# Get inputs available
inputs = requests.get('{0}/inputs/{1}'.format(url, testid)).json()['payload']
print('TEST CASE INPUTS ---------------------------------------------')
print(inputs.keys())
# Get measurements available
print('TEST CASE MEASUREMENTS ---------------------------------------')
measurements = requests.get('{0}/measurements/{1}'.format(url, testid)).json()['payload']
print(measurements.keys())
```

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

### Build all services with Podman

Source: https://github.com/ibpsa/project1-boptest/blob/master/PODMAN-MIGRATION.md

Use this command to build all services defined in the docker-compose.yml file using Podman.

```bash
podman-compose build
```

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

### Get Test Case Name using Test ID

Source: https://github.com/ibpsa/project1-boptest/blob/master/docs/workshops/BS25Workshop_20250828/Introduction_to_the_BOPTEST_framework.ipynb

Retrieves the name of the selected BOPTEST test case using the GET /name/<testid> API endpoint. This confirms that the correct test case has been launched and is ready for interaction.

```python
# Get test case name
name = requests.get('{0}/name/{1}'.format(url, testid)).json()['payload']
print(name)

```

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

### GET /version

Source: https://github.com/ibpsa/project1-boptest/blob/master/README.md

Receive the BOPTEST version information.

```APIDOC
## GET /version

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

### Method
GET

### Endpoint
/version

### Parameters
None

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

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

### Navigate and Activate Client Environment

Source: https://github.com/ibpsa/project1-boptest/blob/master/examples/python/autogenerated_client/README.md

Changes the directory to the generated client project and activates its virtual environment. This prepares the environment for running controller scripts.

```console
(my-env)$ cd ../boptest-controller-project
(my-env)$ source .venv/bin/activate
(boptest-service-api-client)$
```

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

### Get Scenario

Source: https://github.com/ibpsa/project1-boptest/blob/master/README.md

Retrieves the current test scenario configuration.

```APIDOC
## GET scenario/{testid}

### Description
Retrieves the current scenario configuration for the test case.

### Method
GET

### Endpoint
`/scenario/{testid}`

### Parameters
#### Path Parameters
- **testid** (string) - Required - The unique identifier of the test case.

### Request Example
None

### Response
#### Success Response (200)
- **scenario** (object) - An object detailing the current scenario parameters.

#### Response Example
{
  "status": 200,
  "message": "Success",
  "payload": {
    "electricity_price": "dynamic",
    "time_period": "default",
    "temperature_uncertainty": "low",
    "solar_uncertainty": "medium",
    "seed": 42
  }
}
```

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

### Import and Instantiate BOPTEST-Gym Environment

Source: https://github.com/ibpsa/project1-boptest/blob/master/docs/workshops/BS23Workshop_20230904/Introduction_to_the_BOPTEST_framework_BS2023.ipynb

Imports the BoptestGymEnv class and instantiates a BOPTEST-Gym environment. Ensure the BOPTEST-Gym service is cloned and accessible in the system path.

```python
import sys
sys.path.insert(0,'boptestGymService')
from boptestGymEnv import BoptestGymEnv
```

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

### Get KPIs

Source: https://github.com/ibpsa/project1-boptest/blob/master/README.md

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

```APIDOC
## GET kpi/{testid}

### Description
Retrieves the Key Performance Indicators (KPIs) calculated for the test case.

### Method
GET

### Endpoint
`/kpi/{testid}`

### Parameters
#### Path Parameters
- **testid** (string) - Required - The unique identifier of the test case.

### Request Example
None

### Response
#### Success Response (200)
- **kpis** (object) - An object containing KPI names as keys and their calculated values.

#### Response Example
{
  "status": 200,
  "message": "Success",
  "payload": {
    "peak_power": 200.5,
    "energy_consumption": 15.2
  }
}
```

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

### Get Inputs

Source: https://github.com/ibpsa/project1-boptest/blob/master/README.md

Retrieves control signal point names and their metadata.

```APIDOC
## GET inputs/{testid}

### Description
Retrieves the names of control signal points (u) and their associated metadata.

### Method
GET

### Endpoint
`/inputs/{testid}`

### Parameters
#### Path Parameters
- **testid** (string) - Required - The unique identifier of the test case.

### Request Example
None

### Response
#### Success Response (200)
- **inputs** (object) - An object containing control point names as keys and their metadata as values.

#### Response Example
{
  "status": 200,
  "message": "Success",
  "payload": {
    "Temperature_sensor_u": {
      "unit": "degC",
      "description": "Setpoint for temperature control"
    },
    "Ventilation_u": {
      "unit": "m3/s",
      "description": "Ventilation rate control"
    }
  }
}
```

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

### Retrieve Scenario Initialization Results

Source: https://github.com/ibpsa/project1-boptest/blob/master/docs/workshops/BS21Workshop_20210831/Introduction_to_the_BOPTEST_framework.ipynb

Retrieves and prints the results after setting a scenario, including temperature, time in days, and electricity price status. Useful for verifying scenario setup.

```python
y = scenario_return['time_period']
start_time_days = y['time']/24/3600
print(y['reaTZon_y']-273.15)
print(y['time']/24/3600)
print(scenario_return['electricity_price'])
```

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

### Get Measurements

Source: https://github.com/ibpsa/project1-boptest/blob/master/README.md

Retrieves sensor signal point names and their metadata.

```APIDOC
## GET measurements/{testid}

### Description
Retrieves the names of sensor signal points (y) and their associated metadata.

### Method
GET

### Endpoint
`/measurements/{testid}`

### Parameters
#### Path Parameters
- **testid** (string) - Required - The unique identifier of the test case.

### Request Example
None

### Response
#### Success Response (200)
- **measurements** (object) - An object containing measurement point names as keys and their metadata as values.

#### Response Example
{
  "status": 200,
  "message": "Success",
  "payload": {
    "Temperature_sensor_y": {
      "unit": "degC",
      "description": "Indoor temperature sensor"
    },
    "Power_sensor_y": {
      "unit": "W",
      "description": "Total power consumption"
    }
  }
}
```

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

### Generate HTML Documentation for Test Case I/O Points

Source: https://github.com/ibpsa/project1-boptest/blob/master/data/README.md

Use this script to generate HTML documentation for test case inputs and measurements. Ensure the BOPTEST test case is deployed and run from the /data folder.

```python
python get_html_IO.py
```

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

### Get test status

Source: https://github.com/ibpsa/project1-boptest/blob/master/README.md

Retrieves the current status of a test, which can be `Running` or `Queued`.

```APIDOC
## GET status/{testid}

### Description
Get test status as `Running` or `Queued`

### Method
GET

### Endpoint
`/status/{testid}`
```

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

### Initialize BOPTEST Simulation with Start Time and Warm-up

Source: https://github.com/ibpsa/project1-boptest/blob/master/docs/workshops/BS25Workshop_20250828/Introduction_to_the_BOPTEST_framework.ipynb

Use this snippet to initialize a BOPTEST simulation to a specific time with a defined warm-up period. The returned JSON includes current measurement point values, such as time.

```python
y = requests.put('{0}/initialize/{1}'.format(url, testid),
                 json={'start_time':   31*24*3600,
                       'warmup_period': 7*24*3600}).json()['payload']
print('Starting TZon: '+ str(y['reaTZon_y']-273.15))
print('Starting time: '+ str(y['time']/24/3600))
```