Repository navigation
2. Run analyses using the API
The REopt API includes many endpoints (TODO: update). However, the main use case is running an optimization job and getting the results of the job, which is a two-step process.
First, you POST your REopt Scenario to the job endpoint, i.e. https://developer.nrel.gov/api/reopt/stable/job. POST'ing can be done with many tools. This repository includes python functions to make it easy to POST your jobs to the API.
The job endpoint will return a run_uuid in JSON format, like
{"run_uuid": "288523d9-b3ca-491b-a490-27b10c384ce1"}
Go here for information on all the inputs for a job. (TODO: update)
The second step is to GET your results at the results endpoint using your run_uuid. The URL will look like:
https://developer.nrel.gov/api/reopt/stable/job/288523d9-b3ca-491b-a490-27b10c384ce1/results
Note that it can take some time to optimize your Scenario. While the job is running the Scenario.status will be "Optimizing...". Once the job is complete the status will be "optimal" (assuming no problems were encountered).
The API response will contain three top level keys: (TODO: still true?)
- "inputs": all of the inputs that you provided in addition to all the other default values that were used;
- "outputs": the optimization results; and
- "messages": information on input validation as well as errors if they occurred.
This repository contains example scripts to run the REopt API. See the single_scenario_example.ipynb and multi_scenario_example.ipynb as starting points.
We now have now have the ability to use multiple custom electric tariffs in the multi_scenario_example. In particular, it allows the addition of a column in the multi-scenario input file titled urdb_json_file that allows a specific electric tariff to be specified for each scenario. Below is an example of some inputs:
| description | load_file | urdb_json_file | urdb_label |
|---|---|---|---|
| 87104 | 87104_load_kw.csv | 87104_electric_tariff.json | |
| 87106 | 87106_load_kw.csv | 87106_electric_tariff.json | |
| 87106 | 87106_load_kw.csv | 5cc090b85457a3a43667107e |
The user can specify the location of a json file that is placed within ./electric_rates/ or a urdb_label as usual. This is useful for when users have scenarios looking at multiple different customer classes that may face different rate structures.
An optimization job is created by POST'ing your Scenario to the job endpoint.
For example, a Scenario POST for V3 and higher looks like:
{
"Site": {
"longitude": -118.1164613,
"latitude": 34.5794343
},
"ElectricLoad": {
"doe_reference_name": "MidriseApartment",
"annual_kwh": 1000000.0
},
"ElectricTariff": {
"urdb_label": "5ed6c1a15457a3367add15ae"
},
"PV": {},
"Financial": {
"elec_cost_escalation_rate_fraction": 0.03,
"analysis_years": 20,
}
All possible input keys can be viewed in the API code (which also contains descriptions, defaults, and minimum/maximum values of the inputs) or the REopt.jl documentation.
Note that many of the input fields in the above example are not required. If you see a default value in the models.py for any field, then it is not required. Also, some fields are conditionally required. For example there are many ways to define your electric load profile, including providing your own loads_kw, scaling one (or multiple) DoE Commercial Reference Building (CRB) profiles, or using a DoE CRB default load. See the REopt.jl documentation for more details.
Output keys provided by the API can be viewed in the API code or the REopt.jl outputs documentation.