Important Update: REopt API V3 Release

[Bill-Becker]

MEMO

Important Update: REopt API V3 Release

UPDATED October 2nd 2023, after V3 release

A new version (V3) of the REopt API was released on Sept. 25, 2023. This update designates V3 as the “stable” version of the API and introduces changes to https://developer.nrel.gov/api/reopt/stable/job. These changes requires a modified POST request and will return different outputs.

Key Changes in REopt API V3

• Streamlined Structure: We have simplified the structure of API inputs and outputs for enhance usability.
• Field Name Changes: Many data field names have been updated to improve clarity and consistency.
• Enhanced Features: V3 introduces new capabilities, such as modeling multiple grid outages, accounting for technology reliability with the Energy Resilience Performance Tool, and central geothermal heat pumps. Additionally, web users will now be able to conduct portfolio analysis via the web tool.
• REopt.jl Integration: The V3 API integrates seamlessly with the registered REopt.jl Julia package, offering all the same capabilities of V2, plus more. This allows users to supply the same inputs to either REopt.jl directly or the REopt API V3 and obtain identical results. REopt.jl also provides a user-friendly setup for local runs and greater customization for developers.
• Annual Updates: Default values for technology costs, financial parameters, and more will receive annual updates to reflect changing industry standards.

Please see below for more details on the upcoming REopt API version update, with a focus on accessing the tool. Subsequent announcements will provide further insights into the new capabilities mentioned above.

Frequently Asked Questions

I’m a REopt web tool user. Does this change affect me?

The REopt web tool will start using the REopt V3 API at the end of September. The user interface of the web tool will look the same, but will include some new enhanced features, mentioned above.

For previously run evaluations (using V2), including previous results as well as those stored in a registered user’s “Saved Evaluations”, we will provide a PDF download of those evaluations instead of the results page. We are working on making these V2 results PDF available and we should have them available by mid-October. This will allow a record of that analysis as well as the ability to recreate that run in the new version of the web tool.

In the coming months, additional abilities may be offered.

What is the new expected format of REopt API POSTs?

The V3 posts will no longer have key input fields nested under “Scenario” and “Site.” This should make it less cumbersome to create and view inputs. Below is an example comparison of a V2 and V3 POST to the REopt API (learn more about this change on GitHub)). Before Sept. 25, users can try this out by replacing “v2” or “stable” from the URL with “dev”.

How will input and output names change?

In the REopt-Analysis-Scripts repository, we have added a V2 to V3 inputs and a V2 to V3 outputs, also available as downloadable .csv files in the repository. Read a summary of the changes. We hope these name changes improve usability by being more consistent, accurate, and explanatory.

Is the V2 API going away?

The V2 API (at /v2 URL) will be available for the next six months (end of March 2024), but we will not be making updates or bug fixes to it. We encourage users to make the switch to /stable (same as /v3) soon.

I’m a REopt API user. Should I use the new REopt Julia Package instead?

In some instances, using the REopt Julia package directly may have advantages over using the REopt API V3. We believe REopt.jl is a really great way to run REopt; it is easier to setup, use, and develop than the API for programmatic access. It is more customizable in the way it runs, and it runs much faster in many cases.

However, this requires users to run in a Julia environment. There is also a way to run REopt.jl in a python environment using PyJulia and PyCall that several users have adopted. We will post guidance on that in the coming months.

Regardless of environment selected, REopt.jl does not use NREL’s servers or a commercial license; the optimization will run locally on the user’s computational resources, and the user will need to set up an optimization solver, either licensed or open source. We have found that it is very easy to use an open-source solver (such as Cbc and HiGHS) with REopt.jl.

The API hosted on NREL servers still has obvious use cases for users who:

• Only need to call the main version of REopt a moderate number of times (there is a current rate limit of 60 runs per hour)
• Do not have sufficient computational resources to run REopt.jl locally, and/or have a complex problem that a licensed optimization solver is required to solve in a reasonable time (and are not able to obtain a licensed solver themselves)
• Run REopt within their custom workflow that is in a different programming language than Julia.
  Please see the REopt API README for more information on when and how to use the API and Julia package.

How can I find support?

We understand there may be some challenges during this transition, and we are available to assist users. Please check the documentation on this change in the REopt API wiki and REopt-Analysis-Scripts wiki.

If your question is not answered there, use the REopt User Forum to see if it has already been answered.

If you are still experiencing challenges and are not getting a response quickly in the user forum, reach out to reopt@nrel.gov for additional support.

[adfarth]

Please see the following announcement for details on the annual updates to default values in REopt: #120.