Voltaire Service

Voltaire Service is a package that provides API endpoints for the Voltaire project. It is built using the Genie web framework. It is designed to be used in conjunction with the VoltaireBattery package, which provides the core functionality for optimizing battery scheduling.

The primary use case is an endpoint for submitting JSON objects for evaluation, which will then be processed and stored in the database. These JSON objects will contain the necessary information for the VoltaireBattery package to optimize the battery schedule, specified below in the "Using the core API endpoints" section.

As of July 2024, the Voltaire Service prepends a version number to the api to allow for future updates. The current version is v1, so each endpoint must be accessed by prepending /api/v1/[endpoint] to the endpoint.

Using the core API endpoints

The two primary endpoints for the VoltaireService is the /day_ahead endpoint and /real_time endpoint. Both endpoints accept a JSON object and pass it to the Voltaire package for processing.

The JSON object for the Day-Ahead endpoint should be in the following format:

{
  "constraints": {
        "max_discharge_rate": 125.0,
        "min_daily_throughput": 0.0,
        "soc": 125.0,
        "total_capacity": 125.0,
        "max_charge_rate": 125.0,
        "min_cycles_per_day": 0.0,
        "max_daily_throughput": 250.0,
        "min_soc": 12.5,
        "solar_only": false,
        "max_cycles_per_day": 1.0
    },
  // Forecast (posted at 8am that day, updated throughout day)
  // datetime is hour-ending 
  "forecast": {
    "datetime": ["2024-03-19T00:00", "2024-03-20T01:00", "2024-03-20T00:00", "..."],
    "rrs": [10, 10, 10, "..."],
    "regUp": [10, 10, 10, "..."],
    "regDown": [10, 10, 10, "..."],
    "solarCapacity": [10, 10, 10, "..."],
    "rtLmp": [10, 10, 10, "..."],
    "solarvalues": [5, 5, 5, "..."]
  }
}

You can then submit this JSON object to the /day_ahead endpoint using a POST request. The response will be a JSON object containing price and volume pairs for the following day.

Example in bash:

curl -X POST -H "Content-Type: application/json" -d @example_da_json_payload.json http://voltaire-noble-bess.centralus.cloudapp.azure.com/api/day_ahead

The Real-Time endpoint is similar to the Day-Ahead endpoint, but the JSON object should contain the energy commitments. This is because the optimizer needs to avoid the hours where the battery is already committed to other tasks.

This payload can also (optionally) contain two additional fields not shown below: bidaggressiveness, which is a scalar indicating a percentile to be added above the base price expectation from the market state, and bid_prices, which can be a scalar or vector indicating the price to bid to charge the battery. If this field is a scalar, the same price will be bid for the scheduling block. If the field is a vector, the values will indicate bids for each hour corresponding to the hour-ending. NOTE: if bid_prices is given, it will override the bid_aggressiveness field.

{
    "constraints":{
      "max_discharge_rate": 125.0,
      "min_daily_throughput": 0.0,
      "soc": 125.0,
      "total_capacity": 125.0,
      "max_charge_rate": 125.0,
      "min_cycles_per_day": 0.0,
      "max_daily_throughput": 250.0,
      "min_soc": 12.5,
      "max_cycles_per_day": 1.0,
      "solar_only" : true // Set false to allow charging when insufficient solar capacity 
      },
    // RealTime Price Forecast - should only encompass intended operational hours (i.e., no past hours)
    "realTimePriceForecast": {
      "datetime": ["2024-03-19T00:00", "2024-03-20T01:00", "2024-03-20T00:00", "..."],
      "rtLmp": [10, 10, 10, "..."],
      "solarvalues": [5, 5, 5, "..."]
    },
  // Describes accepted market offers (constaining what system can do)
  // Includes all DA ancillaries + charge / discharge committments
  "commitments" : [
    {
  "datetime": "2023-01-01T21:00:00",
  "hourEnding": 21,
  "rrs": {
      "volume": 125.0,
      "price": 1.0
    }
    "....."
  },
  {
  "datetime": "2023-01-01T22:00:00",
  "hourEnding": 22,
  "rrs": {
      "volume": 125.0,
      "price": 1.0
    }
  }
]

}

Example in bash:

curl -X POST -H "Content-Type: application/json" -d @example_rt_json_payload.json http://voltaire-noble-bess.centralus.cloudapp.azure.com/api/real_time

Creating test data

The VoltaireService package also provides functionality for acquiring example DA/RT data. The following endpoints will give you example data for the Day-Ahead and Real-Time endpoints, respectively.

Day-Ahead example data:

curl http://voltaire-noble-bess.centralus.cloudapp.azure.com/api/example_da

Real-Time example data:

curl http://voltaire-noble-bess.centralus.cloudapp.azure.com/api/example_rt

Backtesting Endpoints

The backtesting endpoints enable users to submit and retrieve backtests for battery optimization. Upon submitting a start date, end date, and set of constraints, the submit endpoint will return a job ID. This job ID can be used to retrieve the current spot in the queue using the status endpoint. Finally, the results endpoint can be used to retrieve the results of the backtest.

The JSON object for the backtesting endpoint should be in the following format:

{
  "constraints": {
        "max_discharge_rate": 125.0,
        "min_daily_throughput": 0.0,
        "soc": 125.0,
        "total_capacity": 125.0,
        "max_charge_rate": 125.0,
        "min_cycles_per_day": 0.0,
        "max_daily_throughput": 250.0,
        "min_soc": 12.5,
        "solar_only": false,
        "max_cycles_per_day": 1.0
    },
  "foresight": "imperfect",
  "basecase": "rrs",
  "start_date": "2024-03-19",
  "end_date": "2024-03-20"
}

The start date and end date should be text in the format YYYY-MM-DD. The foresight parameter can be either "perfect" or "imperfect" - corresponding to whether to use realized or predicted prices for the backtest. The basecase parameter can be only "rrs" at the moment, and refers to the base strategy (rrs is an all RRS strategy). The response will be a JSON object containing the job ID.

The Forecasting Endpoint

The forecasting endpoint is used to generate forecasts for time series prediction for five-minute intervals. The JSON object should be in the following format:

{
  "ds": ["2024-03-19T00:00", "2024-03-20T01:00", "2024-03-20T00:00", "..."],
  "y": [1.1, 2.1, 3.4, "..."],
  "horizon": 12
}

Where `ds` is the datetime, `y` is the time series, and `horizon` is the number of intervals to predict. The response will be a JSON object containing the forecasted values `yhat`, `yhat_upper`, and `yhat_lower`. The latter two are the upper and lower bounds of the forecasted values.

@autodocs Modules = [VoltaireService] Pages = ["VoltaireService.jl"] ```