Merge pull request #485 from NREL/develop

After-tax savings, update docs pages March 2025

Author: Bill-Becker

CHANGELOG.md

@@ -24,6 +24,19 @@ Classify the change according to the following categories:
     ### Fixed
     ### Deprecated
     ### Removed
+
+
+## v0.51.1
+### Added
+- Added the following output fields: `year_one_fuel_cost_after_tax` for `ExistingBoiler`, `CHP`, `Generator`, and `Boiler`; `ElectricTariff`: `year_one_bill_after_tax` and `year_one_export_benefit_after_tax`, `Financial`: `capital_costs_after_non_discounted_incentives`, `year_one_total_operating_cost_savings_before_tax`, `year_one_total_operating_cost_savings_after_tax`, `year_one_total_operating_cost_before_tax`, `year_one_total_operating_cost_after_tax`, `year_one_fuel_cost_before_tax`, `year_one_fuel_cost_after_tax`, `year_one_chp_standby_cost_after_tax`, `year_one_chp_standby_cost_after_tax`, `GHP.avoided_capex_by_ghp_present_value`
+- Add a warning so that when **SteamTurbine** is included, renewable energy fractions may not be accurate.
+- Added new attribute **fuel_renewable_energy_fraction** to the technology **Boiler**.
+### Changed
+- Updated and fixed some `docs` pages: improved setup, using HiGHS solver, fixed docstrings 
+- Changed the name of the following output fields: `Financial.capital_costs_after_incentives_without_macrs` to `Financial.capital_costs_after_non_discounted_incentives_without_macrs`
+### Fixed
+- Update the **REoptInputs** parameter **tech_renewable_energy_fraction** so that only electricity-producing and fuel-burning heating technologies are included (instead of all technologies).
+- Included the following in the `Financial.lifecycle_capital_costs` and `Financial.initial_capital_costs`: `m[Symbol("OffgridOtherCapexAfterDepr"*_n)] - m[Symbol("AvoidedCapexByGHP"*_n)] - m[Symbol("ResidualGHXCapCost"*_n)] - m[Symbol("AvoidedCapexByASHP"*_n)]`
 
 ## v0.51.0
 ### Added 
@@ -53,7 +66,7 @@ Classify the change according to the following categories:
 ### Fixed
 - Make **ElectricTariff** **export_rate_beyond_net_metering_limit** and **wholesale_rate** with sub-hour time step work
 - Update the expression `m[:AnnualEleckWh]` to include electrified thermal loads
-- Update expressions `m[AnnualREHeatkWh]` and `AnnualHeatkWh` so that only non-electrified thermal loads are included and storage losses are proportional to the contribution of fuel-burning technologies to charging storage
+- Update expressions `m[:AnnualREHeatkWh]` and `m[:AnnualHeatkWh]` so that only non-electrified thermal loads are included and storage losses are proportional to the contribution of fuel-burning technologies to charging storage
 
 ## v0.50.0
 ### Added

Project.toml

@@ -1,7 +1,7 @@
 name = "REopt"
 uuid = "d36ad4e8-d74a-4f7a-ace1-eaea049febf6"
 authors = ["Nick Laws", "Hallie Dunham <hallie.dunham@nrel.gov>", "Bill Becker <william.becker@nrel.gov>", "Bhavesh Rathod <bhavesh.rathod@nrel.gov>", "Alex Zolan <alexander.zolan@nrel.gov>", "Amanda Farthing <amanda.farthing@nrel.gov>", "Xiangkun Li <xiangkun.li@nrel.gov>", "An Pham <an.pham@nrel.gov>", "Byron Pullutasig <byron.pullatasig@nrel.gov>"]
-version = "0.51.0"
+version = "0.51.1"
 
 [deps]
 ArchGDAL = "c9ce4bd3-c3d5-55b8-8973-c0e20141b8c3"

README.md

@@ -9,18 +9,14 @@ For more information about REopt.jl please see the Julia documentation:
 
 
 ## Quick Start
-Evaluating only `PV` and `Storage` requires a linear program solver. Adding a generator and/or multiple outages makes the problem mixed-integer linear, and thus requires a MILP solver. See https://jump.dev/JuMP.jl/stable/installation/ for a list of solvers. The REopt package has been tested with `Xpress`, `Cbc`, `HiGHS` and `CPLEX`.
-
-Note that not all solvers support indicator constraints and special order sets (such as HiGHS), and so not all REopt problems can be solved with solvers lacking these capabilities.
+Evaluating simple `PV` and `ElectricStorage` scenarios requires a linear program solver. Evaluating net-metering, `Generator`, multiple outages, or other more complex scenario makes the problem mixed-integer linear, and thus requires a MILP solver. See https://jump.dev/JuMP.jl/stable/installation/ for a list of solvers. The REopt package has been tested with , `HiGHS`, `Cbc`, `SCIP`, `Xpress` (commercial), and `CPLEX` (commercial).
 
 ### Example
 ```
-using Xpress
-using JuMP
-using REopt
+using REopt, JuMP, HiGHS
 
-m = Model(Xpress.Optimizer)
-results = run_reopt(m, "path/to/scenario.json")
+m = Model(HiGHS.Optimizer)
+results = run_reopt(m, "pv_storage.json")
 ```
 See the `test/scenarios` directory for examples of `scenario.json`.
 

docs/Project.toml

@@ -6,4 +6,4 @@ REopt = "d36ad4e8-d74a-4f7a-ace1-eaea049febf6"
 
 [compat]
 Documenter = "0.26"
-julia = "1.6, 1.7, 1.8"
+julia = "1"

docs/README.md

@@ -29,8 +29,8 @@ Serving HTTP on ::1 port 8000 (http://[::1]:8000/) ...
 Alternatively, you can use `LiveServer.jl` to host the documentation locally by running `docs/src/devdeploy.jl`; e.g.: 
 ```julia
 [~/.julia/dev/REopt/docs]
-(REopt) pkg> activate .
-(REopt) pkg> dev REopt
+(docs) pkg> activate .
+(docs) pkg> dev REopt
 julia> include("devdeploy.jl")
 [ Info: Precompiling REopt [d36ad4e8-d74a-4f7a-ace1-eaea049febf6]
 ...

docs/devdeploy.jl

@@ -7,8 +7,8 @@ NOTE you have to dev REopt in the `docs` environment to get local changes.
 e.g. 
 ```julia
 [~/.julia/dev/REopt/docs]
-(REopt) pkg> activate .
-(REopt) pkg> dev REopt
+(docs) pkg> activate .
+(docs) pkg> dev REopt
 julia> include("devdeploy.jl")
 [ Info: Precompiling REopt [d36ad4e8-d74a-4f7a-ace1-eaea049febf6]
 ...

docs/src/index.md

@@ -5,14 +5,13 @@
     This package is used as the core model of the [REopt API](https://github.com/NREL/REopt_API) and the [REopt Web Tool](https://reopt.nrel.gov/tool). This package contains additional functionality and flexibility to run locally and customize.
 
 ## Installing
-REopt evaluations for all system types **except GHP** can be performed using the following installation instructions from the Julia REPL:
-```julia
-using Pkg
-Pkg.add("REopt")
+REopt evaluations for all system types except GHP (see below) can be performed using the following installation instructions from the package manager mode (`]`) of the Julia REPL:
+```sh
+(active_env) pkg> add REopt JuMP HiGHS
 ```
 
 ### Add NREL developer API key for PV and Wind
-If you don't have an NREL developer network API key, sign up here to get one (free): https://developer.nrel.gov/signup/; this is required to load PV and Wind resource profiles from PVWatts and the Wind Toolkit APIs from within REopt.jl.
+If you don't have an NREL developer network API key, [sign up here on https://developer.nrel.gov to get one (free)](https://developer.nrel.gov/signup); this is required to load PV and Wind resource profiles from PVWatts and the Wind Toolkit APIs from within REopt.jl.
 Assign your API key to the expected environment variable:
 ```julia
 ENV["NREL_DEVELOPER_API_KEY"]="your API key"
@@ -21,7 +20,13 @@ before running PV or Wind scenarios.
 
 ### Additional package loading for GHP
 GHP evaluations must load in the [`GhpGhx.jl`](https://github.com/NREL/GhpGhx.jl) package separately because it has a more [restrictive license](https://github.com/NREL/GhpGhx.jl/blob/main/LICENSE.md) and is not a registered Julia package.
+
+First add the GhpGhx.jl package to the project's dependencies from the package manager (`]`):
+```sh
+(active_env) pkg> add "https://github.com/NREL/GhpGhx.jl"
+```
+
+Then load in the package from the script where `run_reopt()` is called:
 ```julia
-Pkg.add("https://github.com/NREL/GhpGhx.jl")
 using GhpGhx
-```
+```

docs/src/reopt/examples.md

@@ -1,22 +1,24 @@
 # Examples
-To use REopt you will need to have a solver installed. REopt.jl has been tested with Xpress, Cbc, and CPLEX solvers, but it should work with other Linear Progam solvers (for PV and Storage scenarios) or Mixed Integer Linear Program solvers (for scenarios with outages and/or Generators).
+To use REopt you will need to have a solver installed. This just requires adding one of the compatible open-source solver Julia packages to your Julia environment, along with the JuMP.jl optimization modeling package. If you want to use a commercial solver which requires a licenese, installation of that solver is required external to the Julia environment.
+
+REopt.jl has been tested with HiGHS (preferred open-source), Xpress (commercial), Cbc, SCIP, and CPLEX (commercial) solvers, but it should work with other Linear Progam solvers (for PV and Storage scenarios) or Mixed Integer Linear Program solvers (for scenarios with outages and/or Generators).
 
 ## Basic
 A REopt optimization can be run with three lines: 
 ```julia
-using REopt, JuMP, Cbc
+using REopt, JuMP, HiGHS
 
-m = Model(Cbc.Optimizer)
-results = run_reopt(m, "test/scenarios/pv_storage.json")
+m = Model(HiGHS.Optimizer)
+results = run_reopt(m, "pv_storage.json")
 ```
 
-The `scenario.json` contains a `Dict` of inputs. For more on the `scenario.json` see the [REopt Inputs](@ref) section and find examples at [test/scenarios](https://github.com/NREL/REopt/blob/master/test/scenarios). For more examples of how to run REopt, see [`test_with_cplex.jl`](https://github.com/NREL/REopt/blob/master/test/test_with_cplex.jl) and [`test_with_xpress.jl`](https://github.com/NREL/REopt/blob/master/test/test_with_xpress.jl)
+The input file, in this case `pv_storage.json`, contains the set of user-defined inputs. For more on the inputs .json file, see the [REopt Inputs](@ref) section and find examples at [test/scenarios](https://github.com/NREL/REopt/blob/master/test/scenarios). For more examples of how to run REopt, see [`runtests.jl`](https://github.com/NREL/REopt.jl/blob/master/test/runtests.jl). To adjust settings such as optimality tolerance and logging, see more about relevant `Model()` arguments here: [open source solver setups](https://github.com/NREL/REopt_API/blob/master/julia_src/os_solvers.jl).
 
 To compare the optimized case to a "Business-as-usual" case (with existing techs or no techs), you can run the [BAUScenario](@ref) scenario in parallel by providing two `JuMP.Model`s like so:
 ```julia
-m1 = Model(Cbc.Optimizer)
-m2 = Model(Cbc.Optimizer)
-results = run_reopt([m1,m2], "./scenarios/pv_storage.json")
+m1 = Model(HiGHS.Optimizer)
+m2 = Model(HiGHS.Optimizer)
+results = run_reopt([m1,m2], "pv_storage.json")
 ```
 When the [BAUScenario](@ref) is included as shown above, the outputs will include comparative results such as the net present value and emissions reductions of the optimal system as compared to the BAU Scenario.
 
@@ -30,13 +32,13 @@ When the [BAUScenario](@ref) is included as shown above, the outputs will includ
 Using the `build_reopt!` method and `JuMP` methods one can modify the REopt model before optimizing.
 In the following example we add a cost for curtailed PV power.
 ```julia
-using Xpress
+using HiGHS
 using JuMP
 using REopt
 
-m = JuMP.Model(Xpress.Optimizer)
+m = JuMP.Model(HiGHS.Optimizer)
 
-p = REoptInputs("scenarios/pv_storage.json");
+p = REoptInputs("pv_storage.json");
 
 build_reopt!(m, p)
 

docs/src/reopt/inputs.md

@@ -1,5 +1,5 @@
 # REopt Inputs
-Inputs to `run_reopt` can be provided in one of four formats:
+Inputs to the `run_reopt` function can be provided in one of four formats:
 1. a file path (string) to a JSON file,
 2. a `Dict`, 
 3. using the `Scenario` struct, or
@@ -139,7 +139,12 @@ REopt.ColdThermalStorageDefaults
 
 ## HeatingLoad
 ```@docs
-REopt.HeatingLoad
+REopt.HeatingLoad()
+```
+
+## CoolingLoad
+```@docs
+REopt.CoolingLoad
 ```
 
 ## FlexibleHVAC

docs/src/reopt/outputs.md

@@ -5,6 +5,11 @@
 REopt.add_financial_results
 ```
 
+## Financial outputs adders with BAU Scenario
+```@docs
+REopt.combine_results(p::REoptInputs, bau::Dict, opt::Dict, bau_scenario::BAUScenario)
+```
+
 ## ElectricTariff outputs
 ```@docs
 REopt.add_electric_tariff_results(::JuMP.AbstractModel, ::REoptInputs, ::Dict)