Documentation for REopt cost analysis workflow

getting_started/getting_started.md

@@ -174,14 +174,14 @@ nav_order: 1
     <div class="language-terminal highlighter-rouge"><pre class="highlight"><code><span class="code-text">uo create --scenario-file &lt;path/to/FEATUREFILE.json&gt;</span></code></pre></div>
     </div>
   </li>
-  <li class="acc"><input id="enable-reopt" type="checkbox" /><label for="enable-reopt">Enable REopt&trade; Functionality</label>
+  <li class="acc"><input id="enable-reopt" type="checkbox" /><label for="enable-reopt">Enable URBANopt-REopt&reg; Functionality</label>
     <div class="show">
       <ol>
-        <li>To run a REopt scenario you will need an internet connection so the REopt™ Gem can access the REopt API.</li>
+        <li>To run a REopt scenario 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. 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 URBANopt-REopt Cost Analysis (Alpha) Capabilities</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 scenario optimization (this functionality is enabled in the reopt-scenario post processor, and not the reopt-feature post processor). 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">URBANopt-REopt Cost Analysis page</a> for more details on this analysis.</p>
+    </div>
+  </li>
 </ul>
 <p>Other Options</p>
 <ul class="jk_accordion">
@@ -269,11 +283,12 @@ nav_order: 1
         <li><strong>scenario-level</strong>, which optimizes for the aggregate load of the entire district being simulated assuming there is one primary utility meter, and</li>
         <li><strong>feature-level</strong>, which optimizes each building’s load individually assuming each building is individually metered.</li>
       </ol>
-      <p>You may chose to optimize by one or both of these approaches according to your project objectives. </p>
+      <p>You may chose to optimize by one or both of these approaches according to your project objectives. The cost analysis is enabled in the scenario-level optimization only.</p>
       <div class="important-note"><p>Note&mdash;You will need an internet connection so the REopt™ Gem can access the REopt API.</p></div>
       <p><strong>To optimize at the scenario-level, use the <code>--reopt-scenario</code> flag:</strong></p>
       <div class="language-terminal highlighter-rouge"><pre class="highlight"><code><span class="code-text">  uo process --reopt-scenario --feature &lt;path/to/FEATUREFILE.json&gt; --scenario &lt;path/to/SCENARIOFILE.csv&gt;</span></code></pre></div>
       <p>The <code>--reopt-scenario-assumptions-file</code> (or <code>-a</code>) option can be used to specify the path to the assumptions file to use for this optimization. If none is specified, the <code>base_assumptions.json</code> file in the <code>reopt</code> folder of the project directory will be used.</p>
+      <p>If cost optimization is enabled (via the extra costs column(s) in the scenario CSV), cost results will also be reported. Look through the command line output for additional details and troubleshooting.</p>
       <p><strong>To optimize at the feature-level, use the <code>--reopt-feature</code> flag:</strong></p>
       <div class="language-terminal highlighter-rouge"><pre class="highlight"><code><span class="code-text">  uo process --reopt-feature --feature &lt;path/to/FEATUREFILE.json&gt; --scenario &lt;path/to/REoptEnabledSCENARIOFILE.csv&gt;</span></code></pre></div>
       <p>For this optimization, the assumptions file is specified per feature in the Scenario CSV file, and is defaulted to the <code>multiPV_assumptions.json</code> file in the <code>reopt</code> folder of the project directory.</p>

workflows/reopt/reopt.md

@@ -8,7 +8,7 @@ nav_order: 9
 
 <div style="text-align:center"><img src="../../doc_files/reopt-logo.png" /></div>
 
-**REopt<sup>TM</sup>** is a technoeconomic decision making model for distributed energy resource (DER) design accessible via [web tool](https://reopt.nrel.gov/tool) and [API](https://developer.nrel.gov/docs/energy-optimization/reopt/). Given a set of inputs it leverages mixed-integer linear programming to select the optimal design and hourly annual dispatch of solar PV, storage, wind and diesel generator technologies - it also provides key economic metrics for the system. Integration of this model with URBANopt allows individual buildings (i.e _Feature Reports_) and collections of buildings (i.e. _Scenario Reports_) to be assessed for cost-optimal DER solutions.
+**REopt&reg;** is a technoeconomic decision making model for distributed energy resource (DER) design accessible via [web tool](https://reopt.nrel.gov/tool) and [API](https://developer.nrel.gov/docs/energy-optimization/reopt/). Given a set of inputs it leverages mixed-integer linear programming to select the optimal design and hourly annual dispatch of solar PV, storage, wind and diesel generator technologies - it also provides key economic metrics for the system. Integration of this model with URBANopt allows individual buildings (i.e _Feature Reports_) and collections of buildings (i.e. _Scenario Reports_) to be assessed for cost-optimal DER solutions.
 
 The [URBANopt REopt Gem](https://github.com/urbanopt/urbanopt-reopt-gem) extends the [URBANopt Scenario Gem](https://github.com/urbanopt/urbanopt-scenario-gem) and is intended to be used as a post-processor on _Feature_ and _Scenario_ Reports. The **URBANopt REopt Gem** can be used directly as shown in the [example REopt project](https://github.com/urbanopt/urbanopt-example-reopt-project) or through the [URBANopt CLI](https://github.com/urbanopt/urbanopt-cli). The **URBANopt REopt Gem**  comes with the following functionality:
 

workflows/reopt/reopt_cost_analysis.md

@@ -0,0 +1,85 @@
+---
+layout: default
+title: URBANopt-REopt Cost Analysis Capabilities
+parent: REopt
+grand_parent: Workflows
+nav_order: 3
+---
+## URBANopt™-REopt® Cost Analysis (Alpha) Capabilities
+
+The URBANopt-REopt Cost Analysis capabilities can be used to calculate capital and operational costs associated with buildings in a district, campus, or neighborhood using URBANopt-REopt workflows. 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 cost-effectiveness. For example, users can define costs for a baseline new construction project and compare them with scenarios featuring increasing levels of energy 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 are Alpha capabilities initially released in URBANopt version 1.2.0 for initial user testing and feedback and may be refined and updated in future releases.
+
+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 capital costs per building for both baseline and high-efficiency scenarios.
+
+Note that dummy values of \$1 and \$1/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.
+
+### Analysis Period
+
+The analysis period for financial calculations can be modified in the **REopt Assumptions File**, under the `Financial.analysis_years` field. This is set at 20 years in the example URBANopt-REopt assumptions files.
+
+### Electricity Utility Rate
+
+The electricity utility rate 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
+
+The fuel utility rate is user specified \(\$/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 placeholder values of \$1/MMBtu will be used in the **REopt Assumptions 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 added for \$ and \$/sq.ft. |
+| Electricity utility rate    | URDB Label     | REopt Assumption File | Existing field used                   |
+| Fuel utility rate           | \$/MMBtu       | REopt Assumption File | New field 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/when **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 is used 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 is 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 Natural Gas fuel costs while the boiler is not actually modeled 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** scenario 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.) or taken as is if costs were input as total per building, then individual building capital costs would be added to calculate total building capital costs across all buildings. Then, the **REopt API** call is made with the **REopt** input assumptions file and the 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. Note: The replacement costs and incentives are currently not considered in the analysis.
+
+- `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.