Documentation for REopt cost analysis workflow

getting_started/getting_started.md

@@ -181,7 +181,7 @@ nav_order: 1
         <li>Obtain an API key from the <a href="https://developer.nrel.gov/" class="bold">NREL Developer Network</a> to use the <strong>REopt API</strong>. Copy and paste your key as an environment variable named <code>GEM_DEVELOPER_KEY</code> on your computer. Step-by-step instructions for creating env variables are found in the <a href="../installation/installation" class="bold">installation docs</a> for your operating system.
           <div class="language-terminal highlighter-rouge"><pre class="highlight"><code><span class="code-text"> GEM_DEVELOPER_KEY = '&lt;insert your NREL developer key here'&gt;</span></code></pre></div>
         </li>
-        <li><p>Extend the Scenario CSV File with REopt information. After following the instructions above to create a basic Scenario CSV File for each mapper, use the command below to create a new Scenario CSV File (named REopt_scenario.csv by default) that has an extra column to map assumptions files to features. Use this Scenario CSV File going forward in future steps. The assumptions file listed in the Scenario CSV will be used when performing a REopt feature optimization.  By default, this is set to <code>multiPV_assumptions.json</code>. If you'd like to use a different file, open the Scenario CSV file, edit the assumptions file name and save. Your new assumptions file should be saved in the <code>reopt</code> directory within your project directory.</p>
+        <li><p>Extend the Scenario CSV File with REopt information. After following the instructions above to create a basic Scenario CSV File for each mapper, use the command below to create a new Scenario CSV File (named REopt_[base-scenario-name]_scenario.csv by default) that has an extra column to map assumptions files to features. Use this Scenario CSV File going forward in future steps. The assumptions file listed in the Scenario CSV will be used when performing a REopt feature optimization.  By default, this is set to <code>multiPV_assumptions.json</code>. If you'd like to use a different file, open the Scenario CSV file, edit the assumptions file name and save. Your new assumptions file should be saved in the <code>reopt</code> directory within your project directory.</p>
           <div class="language-terminal highlighter-rouge"><pre class="highlight"><code><span class="code-text">uo create --reopt-scenario-file &lt;path/to/EXISTING_SCENARIO_FILE.csv&gt;</span></code></pre></div>
         </li>
         <li><p>Configure your REopt assumptions. Two example <strong>REopt</strong> assumptions files are located in the <code>reopt</code> folder within your project directory:  <code>base_assumptions.json</code> and <code>multiPV_assumptions.json</code>. These files follow the format outlined in the <a href="https://github.com/NREL/REopt-API-Analysis/wiki/Job-Inputs" target="_blank" class="bold">REopt API documentation</a> and can be customized to your specific project needs. Through CLI commands, they will be updated with basic information from your Feature and Scenario Reports (i.e. latitude, longitude, electric load profile) and submitted to the <strong>REopt API</strong>.</p>
@@ -195,6 +195,20 @@ nav_order: 1
       <p>Visit the <a href="../workflows/reopt/reopt" class="bold">REopt page</a> for more details on using REopt with URBANopt, or watch the <a href="https://urbanopt-tutorial.s3.amazonaws.com/videos/08_REopt-URBANopt.mp4" target="_blank" class="bold">REopt Workflow Tutorial Video</a>.</p>
     </div>
   </li>
+    <li class="acc"><input id="reopt-cost" type="checkbox" /><label for="reopt-cost">Enable REopt&trade; Cost Analysis Functionality</label>
+    <div class="show">
+      <ol>
+        <li>As with the REopt scenario above, you will need an internet connection so the REopt™ Gem can access the REopt API.</li>
+        <li>Obtain an API key from the <a href="https://developer.nrel.gov/" class="bold">NREL Developer Network</a> to use the <strong>REopt API</strong>. Copy and paste your key as an environment variable named <code>GEM_DEVELOPER_KEY</code> on your computer. Step-by-step instructions for creating env variables are found in the <a href="../installation/installation" class="bold">installation docs</a> for your operating system.
+          <div class="language-terminal highlighter-rouge"><pre class="highlight"><code><span class="code-text"> GEM_DEVELOPER_KEY = '&lt;insert your NREL developer key here'&gt;</span></code></pre></div>
+        </li>
+        <li><p>Extend the Scenario CSV File with REopt information and cost information. After following the instructions above to create a basic Scenario CSV File for each mapper, use the command below to create a new Scenario CSV File (named REopt_cost_[base-scenario-name]_scenario.csv by default) that has an extra column to map assumptions files to features, and 2 extra columns to enter costs per feature. The scenario CSV File will be prepopulated with placeholder cost information. <strong>Ensure that you update these values with your project's real costs before running the analysis.</strong> You only need values in either the "Total Capital Costs ($)" column or the "Capital Cost Per Floor Area ($/sq.ft.)" column. If both columns are provided, the Total Capital Costs ($) values will be used. Use this Scenario CSV File going forward in future steps. The assumptions file listed in the Scenario CSV will be used when performing a REopt feature optimization. See the section above for more information on REopt assumptions files.</p> 
+          <div class="language-terminal highlighter-rouge"><pre class="highlight"><code><span class="code-text">uo create --reopt-scenario-cost-file &lt;path/to/EXISTING_SCENARIO_FILE.csv&gt;</span></code></pre></div>
+        </li>
+      </ol>
+      <p>Visit the <a href="../workflows/reopt/reopt_cost_analysis" class="bold">REopt Cost Analysis page</a> for more details on this analysis.</p>
+    </div>
+  </li>
 </ul>
 <p>Other Options</p>
 <ul class="jk_accordion">

workflows/reopt/reopt_cost_analysis.md

@@ -0,0 +1,82 @@
+---
+layout: default
+title: URBANopt Cost Analysis Capabilities
+parent: REopt
+grand_parent: Workflows
+nav_order: 3
+---
+## Intro
+
+This document outlines capabilities for calculating capital and operational costs associated with buildings in a district, campus, or neighborhood using **URBANopt**. These cost calculations will support comparison of various **URBANopt** scenarios, providing insights into the financial implications of different design decisions and enhancing visibility into project feasibility and affordability. For example, users can define costs for a baseline new construction project and compare them with scenarios featuring increasing levels of efficiency. This functionality also supports evaluating tradeoffs between capital investments in building energy efficiency and demand flexibility technologies and their resulting impacts on operational energy savings. The workflow utilizes user-defined costs for each **URBANopt** scenario and leverages the **REopt** techno-economic engine to calculate financial parameters such as Net Present Value and Lifecycle Capital Cost for the analysis period.
+
+These following sections detail the inputs required, expected outputs, software architecture and workflow for running the analysis.
+
+
+## User Cost Inputs
+
+### Capital Costs for Buildings
+
+This is a user input for the total capital cost associated with a single building in each scenario. It can be added as a total cost \(\$\) or cost per floor area \(\$/sq.ft.\). The capital costs for each building will be aggregated for all the buildings on the site and will be reported at the scenario level, allowing direct comparison across scenarios. This input field provides flexibility for different use case, such as:
+
+- Users may specify known total costs per building for both baseline and high-efficiency scenarios.
+- Alternatively, users may enter incremental costs for high-efficiency scenarios, defined relative to the baseline cost. 
+
+Note that dummy values of \$100 and \$100/sq.ft. will be propagated for each building in the **REopt Scenario File** initially. Users should modify the values to reflect the actual capital costs of their project.
+
+### Electricity Utility Rate
+
+This will be specified through the [Utility Rate Database (URDB)](https://apps.openei.org/USURDB/) label at the project level. This is used to calculate the operating costs for electricity consumption across scenarios. 
+
+### Fuel Utility Rate
+
+This is the user specified fuel cost \(\$/MMBtu\) at the project level. The rate is applied when calculating operating costs for fuel consumption across scenarios. The initial capability supports `Natural Gas` fuel type. Note that dummy values of \$100/MMBtu will be used in the **REopt Assumption File** initially. Users should modify the value to reflect the actual fuel cost of their project.
+
+|             Input           |      Unit      | URBANopt SDK Location  |                     Notes                     |
+| ----------------------------| -------------- | ---------------------- | --------------------------------------------- |
+| Capital costs for buildings | \$ or \$/sq.ft.| REopt Scenario File          | New fields will be added for \$ and \$/sq.ft. |
+| Electricity utility rate    | URDB Label     | REopt Assumption File | Existing field will be used                   |
+| Fuel utility rate           | \$/MMBtu       | REopt Assumption File | New field will be added                       |
+
+## REopt Calculations
+
+### Building Capital Cost Calculation
+
+Currently, building energy upgrades are not supported as a distinct technology type within the **REopt** engine. To enable cost calculations associated with building technology upgrades, the `Wind` technology type is being used as a placeholder.
+
+Although `Wind` is not modeled within the **URBANopt–REopt** integration, it provides the necessary input fields and analytical capabilities required to represent building energy upgrade costs. By repurposing the `Wind` technology type in this manner, we can support upgrade cost analysis without modifications to the core **REopt** schema.
+
+In the future, if **REopt** introduces explicit support for input of building capital costs, the integration will be updated to leverage the new inputs directly, replacing the temporary Wind-based representation.
+
+The **REopt** input assumption file will be updated to include building energy upgrade costs under `Wind`.
+
+### Fuel Cost Calculation
+
+To calculate the fuel cost for building fuel energy consumption, the `SpaceHeatingLoad > fuel_loads_mmbtu_per_hour` **REopt** property will be used. The `fuel_loads_mmbtu_per_hour` field takes an array of hourly fuel consumption values for the building. Using the **URBANopt** default feature reports, the hourly fuel load values are populated into this field. The `fuel cost per MMBtu` is then copied from the user-specified value in the **REopt Assumption File** into the `ExistingBoiler > fuel_cost_per_mmbtu` property in the **REopt** input schema. These inputs are passed on to **REopt**, which then calculates the total fuel cost associated with the building. The `Boiler` object is used in order to calculate fuel costs while the boiler is not actually modelled on the site.
+
+More details on the **REopt** input schema can be found at: https://developer.nrel.gov/api/reopt/stable/help/?API_KEY=DEMO_KEY.
+
+### REopt Input Cost Parameters
+
+**REopt** input cost parameters are specified at the project level, and include the `electricity cost escalation rate`, `analysis years`, `discount rate fraction` and `tax rate fraction`. More details for these inputs, including the default values, are provided in the [REopt user manual](https://reopt.nrel.gov/tool/reopt-user-manual.pdf).
+
+## Overall Workflow
+
+![workflow_diagram](../../doc_files/reopt_cost_analysis_workflow.jpg)
+
+This figure describes the overall workflow for running the **REopt** cost analysis. The user creates an **URBANopt-REopt** project and adds the necessary user cost inputs. The **URBANopt** project is then run, followed by default post processing. Next, the **REopt** post processing command is run. During this step, the user inputs are copied into the **REopt Assumption Files**. To get the total capital costs for a scenario, individual building capital costs would be multiplied with the floor area (if costs were input as \$/sq.ft.), then individual building capital costs would be added to calculate total building capital costs across all buildings. Then, the **REopt API** call is made sending the **REopt** input assumptions file and analysis is run. The **REopt** outputs are then reported back to the **URBANopt SDK**.
+
+## Outputs
+
+The existing **REopt** output reports will be used to report the financial outputs from the analysis. The outputs reported from the **REopt** techno economic analysis are:
+
+- `initial_capital_costs`: Up-front capital costs for all technologies, in present value, excluding replacement costs and incentives. If third party ownership, represents cost to third party.
+
+- `initial_capital_costs_after_incentives`: Up-front capital costs for all technologies, in present value excluding replacement costs, and accounting for incentives.
+
+- `lifecycle_capital_costs`: Net capital costs for all technologies, in present value, including replacement costs and incentives.
+
+- `lifecycle_fuel_costs_after_tax`: LCC component. Present value of all fuel costs over the analysis period, after tax
+
+- `lifecycle_elecbill_after_tax`: LCC component. Present value of all electric utility charges, including compensation for exports, after tax.
+
+- `NPV`: Net present value of savings realized by the project.

workflows/reopt/reopt_customization.md

@@ -3,7 +3,7 @@ layout: default
 title: REopt Customization
 parent: REopt
 grand_parent: Workflows
-nav_order: 3
+nav_order: 4
 ---
 ## Customization