REopt API Scripts/single_scenario_example.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Run a REopt API evaluation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Initialization"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "import numpy as np\n",
    "import json\n",
    "import requests\n",
    "import copy\n",
    "import os\n",
    "from src.post_and_poll import get_api_results\n",
    "API_KEY = 'DEMO_KEY'  # REPLACE WITH YOUR API KEY"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# following is not necessary but silences warnings:\n",
    "# InsecureRequestWarning: Unverified HTTPS request is being made to host 'developer.nrel.gov'. Adding certificate verification is strongly advised.\n",
    "import urllib3\n",
    "urllib3.disable_warnings()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "\"\"\"\n",
    "Here are some convenience definitions for using the Multi-scenario capabilities\n",
    "\"\"\"\n",
    "##############################################################################################################\n",
    "inputs_path = os.path.join(\".\", 'inputs')\n",
    "outputs_path = os.path.join(\".\", 'outputs')\n",
    "loads_path = os.path.join(\".\", 'load_profiles')\n",
    "rates_path = os.path.join(\".\", 'electric_rates')\n",
    "##############################################################################################################"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Load a previously saved API response .json file instead of running REopt"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "response_json = 'results'\n",
    "with open(os.path.join(outputs_path, response_json + '.json'), 'rb') as handle:\n",
    "    api_response = json.load(handle)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Scenario Inputs (POST), if wanting to do a new API call"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "post_1 = {\n",
    "    \"Site\": {\n",
    "        \"longitude\": -118.1164613,\n",
    "        \"latitude\": 34.5794343\n",
    "    },\n",
    "    \"PV\": {\n",
    "        \"array_type\": 0\n",
    "    },\n",
    "    \"ElectricLoad\": {\n",
    "        \"doe_reference_name\": \"RetailStore\",\n",
    "        \"annual_kwh\": 100000.0,\n",
    "        \"year\": 2017\n",
    "    },\n",
    "    \"ElectricTariff\": {\n",
    "        \"urdb_label\": \"5ed6c1a15457a3367add15ae\"\n",
    "    },\n",
    "    \"Financial\": {\n",
    "        \"elec_cost_escalation_rate_fraction\": 0.026,\n",
    "        \"owner_discount_rate_fraction\": 0.081,\n",
    "        \"analysis_years\": 20,\n",
    "        \"offtaker_tax_rate_fraction\": 0.4,\n",
    "        \"owner_tax_rate_fraction\": 0.4,\n",
    "        \"om_cost_escalation_rate_fraction\": 0.025\n",
    "    }\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Load in a custom electric rate generated from https://reopt.nrel.gov/tool/custom_tariffs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "load_electric_rate = \"PGE_E20\"\n",
    "with open(os.path.join(rates_path, load_electric_rate + \".json\"), 'r') as fp:\n",
    "    rate_1 = json.load(fp)\n",
    "post_1[\"ElectricTariff\"][\"urdb_response\"] = rate_1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Save the POST to a .json file for sharing or future loading in"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Convert python dictionary post into json and save to a .json file\n",
    "post_save = post_1\n",
    "post_name = \"post_1\"\n",
    "with open(os.path.join(inputs_path, post_name + \".json\"), 'w') as fp:\n",
    "    json.dump(post_save, fp)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Or load in a saved .json file for the inputs/POST"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# Load a json into a python dictionary\n",
    "load_post = \"post_1\"\n",
    "with open(os.path.join(inputs_path, load_post + \".json\"), 'r') as fp:\n",
    "    post_1 = json.load(fp)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## POST and poll (periodic GET request) the API to GET a new result, if not loading in a previous response. This may take a while!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Note, the `api_url` in the `get_api_results` function below calls the **production server** hosted API (master/main branch/version, publicly accessible)\n",
    "\n",
    "#### For calling a locally-hosted (localhost) API, see:\n",
    "- https://github.com/NREL/REopt_API/wiki/3.-Calling-Locally-Hosted-API\n",
    "\n",
    "#### For calling an API hosted on an NREL-internal server (only NREL users can access this), see:\n",
    "- https://github.nrel.gov/REopt/API_scripts/wiki/API-URLs-for-NREL-internal-servers"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`get_api_results` POST's your inputs to the API `job` endpoint, which provides a `run_uuid` if the input is valid, and then polls the `results` endpoint using the `run_uuid` until the results come back with a status other than `Optimizing...`.\n",
    "\n",
    "`get_api_results` also saves the results (full API response, including inputs) to the `results_file`.\n",
    "\n",
    "A log file is also created in the current working directory."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "main         INFO     Response OK from https://developer.nrel.gov/api/reopt/stable/job/?api_key=DEMO_KEY.\n",
      "main         INFO     Polling https://developer.nrel.gov/api/reopt/stable/job/9dfea231-3209-43eb-9270-30566fcab24c/results/?api_key=DEMO_KEY for results with interval of 5s...\n",
      "main         INFO     Saved results to ./outputs/results_file.json\n"
     ]
    }
   ],
   "source": [
    "outputs_file_name = \"results_file\"\n",
    "root_url = \"https://developer.nrel.gov/api/reopt/stable\" # /stable == /v3 \n",
    "api_response = get_api_results(post=post_1, \n",
    "                               API_KEY=API_KEY, \n",
    "                               api_url=root_url, \n",
    "                               results_file=os.path.join(outputs_path, outputs_file_name + \".json\"), \n",
    "                               run_id=None)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### If you get disconnected from the polling function but you think it ran, copy the run_uuid from the log above to manually GET the results:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict_keys(['run_uuid', 'api_version', 'user_uuid', 'webtool_uuid', 'job_type', 'status', 'created', 'reopt_version', 'inputs', 'outputs', 'messages'])"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "api_response.keys()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "run_uuid = api_response[\"run_uuid\"]\n",
    "results_url = root_url + '/job/' + run_uuid + '/results/?api_key=' + API_KEY\n",
    "resp = requests.get(url=results_url, verify=False)\n",
    "api_response = json.loads(resp.text)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get summary of results"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "NPV ($) =  47696.79\n",
      "Capital Cost, Net ($) =  23587.6414\n",
      "PV size_kw  =  37.0515\n"
     ]
    }
   ],
   "source": [
    "print(\"NPV ($) = \", api_response[\"outputs\"][\"Financial\"][\"npv\"])\n",
    "print(\"Capital Cost, Net ($) = \", api_response[\"outputs\"][\"Financial\"][\"lifecycle_capital_costs\"])\n",
    "tech_list = [\"PV\", \"Wind\", \"ElectricStorage\", \"CHP\", \"Generator\", \"HotThermalStorage\", \"ColdThermalStorage\", \"AbsorptionChiller\", \"GHP\", \"Boiler\", \"SteamTurbine\"]\n",
    "for tech in tech_list:\n",
    "    if tech in post_1.keys():\n",
    "        if tech == \"GHP\":\n",
    "            print(\"GHX Number of Boreholes = \", api_response[\"outputs\"][tech][\"ghpghx_chosen_outputs\"].get(\"number_of_boreholes\"))\n",
    "            print(\"GHP Heat Pump Capacity (ton) = \", api_response[\"outputs\"][tech][\"ghpghx_chosen_outputs\"].get(\"peak_combined_heatpump_thermal_ton\"))\n",
    "        for size_name_value in [(key, val) for key, val in api_response[\"outputs\"][tech].items() if \"size\" in key]:\n",
    "                print(tech + \" \" + size_name_value[0], \" = \", size_name_value[1])               "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Here are some results keys examples:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict_keys(['run_uuid', 'api_version', 'user_uuid', 'webtool_uuid', 'job_type', 'status', 'created', 'reopt_version', 'inputs', 'outputs', 'messages'])"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "api_response.keys()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'optimal'"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "api_response[\"status\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'info': 'When using doe_reference_name or blended_doe_reference_names for ElectricLoad the year is set to 2017 because the DoE load profiles start on a Sunday.',\n",
       " 'errors': {},\n",
       " 'warnings': {},\n",
       " 'has_stacktrace': False}"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "api_response[\"messages\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Financial\n",
      "ElectricTariff\n",
      "ElectricUtility\n",
      "ElectricLoad\n",
      "Site\n",
      "PV\n"
     ]
    }
   ],
   "source": [
    "for k in api_response[\"outputs\"].keys():\n",
    "    print(k)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Save API response into a JSON file for later use"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [],
   "source": [
    "response_save = api_response\n",
    "file_name_to_save = \"response_1\"\n",
    "with open(os.path.join(outputs_path, file_name_to_save + \".json\"), 'w') as fp:\n",
    "    json.dump(response_save, fp)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "@webio": {
   "lastCommId": null,
   "lastKernelId": null
  },
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.8"
  },
  "latex_envs": {
   "LaTeX_envs_menu_present": true,
   "autoclose": false,
   "autocomplete": true,
   "bibliofile": "biblio.bib",
   "cite_by": "apalike",
   "current_citInitial": 1,
   "eqLabelWithNumbers": true,
   "eqNumInitial": 1,
   "hotkeys": {
    "equation": "Ctrl-E",
    "itemize": "Ctrl-I"
   },
   "labels_anchors": false,
   "latex_user_defs": false,
   "report_style_numbering": false,
   "user_envs_cfg": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}