Skip to content

2. Run analyses using the API

Jump to bottom
adfarth edited this page Oct 15, 2024 · 11 revisions

Running a REopt "job" in the API

The REopt API includes many endpoints. However, the main use case is running an optimization job and getting the results of the job, which is a two-step process.

Step 1: POST a job

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"}

See all v3 job inputs in REopt_API models.py or view a mapping of v2 to v3 job inputs in the v2_v3_inputs_map.csv. Example posts to the API can be found in the single_scenario_example.ipynb

Step 2: GET results

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 status will be "Optimizing...". Once the job is complete the status will be "optimal" (assuming no problems were encountered).

The API response will contain several top level keys:

  • '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.
  • 'run_uuid': Unique ID for API run.
  • 'api_version': Version of REopt API utilized.
  • 'user_uuid': The assigned unique ID of a signed in REopt web tool user.
  • 'webtool_uuid': The unique ID of a scenario created by the REopt Webtool.
  • 'job_type': 'REopt Web Tool', 'developer.nrel.gov', 'Internal NREL', or 'Monitoring'
  • 'status'
  • 'created': datetime model is created
  • 'reopt_version': Version number of the Julia package for REopt that is used to solve the problem.

Example scripts to use the REopt API

This repository contains example scripts to run the REopt API. See the single_scenario_example.ipynb as a starting point.

Scripts with Multi-Scenario and Multi-Tariff Inputs (to be added for v3)

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.

"job" inputs

An optimization job is created by POST'ing your Scenario to the job endpoint.

For example, a Scenario POST 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
    }
}

The latest v3 inputs for the job endpoint can be retrieved from the API via: https://developer.nrel.gov/api/reopt/dev/job/inputs?api_key=DEMO_KEY. You can also see inputs in the REopt.jl documentation or API code.

Note that many of the input fields in the above example are not required. If you see a default value in 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.

"job" outputs

Output keys provided by the API can be viewed in the API code, the REopt.jl outputs documentation, or at https://developer.nrel.gov/api/reopt/dev/job/outputs?api_key=DEMO_KEY.

Clone this wiki locally