updates from bess-export branch

Author: adfarth

CHANGELOG.md

@@ -27,7 +27,7 @@ Classify the change according to the following categories:
 
 ## fixed-bess-soc
 ### Added
-- Add **ElectricStorage** input field `fixed_soc_series_fraction` to allow users to fix the SOC timeseries
+- Add **ElectricStorage** inputs field **fixed_soc_series_fraction** and  **fixed_soc_series_fraction_tolerance** to allow users to fix the SOC timeseries within a chosen absolute tolerance
 
 ## v0.58.1 
 ### Fixed

src/constraints/storage_constraints.jl

@@ -44,7 +44,7 @@ function add_general_storage_dispatch_constraints(m, p, b; _n="")
         @constraint(m,
             m[Symbol("dvStoredEnergy"*_n)][b, 0] == m[:dvStoredEnergy][b, maximum(p.time_steps)]
         )
-    elseif !hasproperty(p.s.storage.attr[b], :fixed_soc_series_fraction) || isnothing(p.s.storage.attr[b].fixed_soc_series_fraction)
+    else
         @constraint(m,
             m[Symbol("dvStoredEnergy"*_n)][b, 0] == p.s.storage.attr[b].soc_init_fraction * m[Symbol("dvStorageEnergy"*_n)][b]
         )
@@ -105,32 +105,21 @@ function add_elec_storage_dispatch_constraints(m, p, b; _n="")
         )
     )
 
-	# Constraint (4i)-1: Dispatch to electrical storage is no greater than power capacity
-	@constraint(m, [ts in p.time_steps],
-        m[Symbol("dvStoragePower"*_n)][b] >= 
-            sum(m[Symbol("dvProductionToStorage"*_n)][b, t, ts] for t in p.techs.elec) + m[Symbol("dvGridToStorage"*_n)][b, ts]
-    )
-	
-	#Constraint (4k)-alt: Dispatch to and from electrical storage is no greater than power capacity
-	@constraint(m, [ts in p.time_steps_with_grid],
-        m[Symbol("dvStoragePower"*_n)][b] >= m[Symbol("dvDischargeFromStorage"*_n)][b, ts] + 
-            sum(m[Symbol("dvProductionToStorage"*_n)][b, t, ts] for t in p.techs.elec) + m[Symbol("dvGridToStorage"*_n)][b, ts]
-    )
-
-	#Constraint (4l)-alt: Dispatch from electrical storage is no greater than power capacity (no grid connection)
-	@constraint(m, [ts in p.time_steps_without_grid],
-        m[Symbol("dvStoragePower"*_n)][b] >= m[Symbol("dvDischargeFromStorage"*_n)][b,ts] + 
-            sum(m[Symbol("dvProductionToStorage"*_n)][b, t, ts] for t in p.techs.elec)
+    # Constraint (4i): Dispatch to and from electrical storage is no greater than power capacity
+    @constraint(m, [ts in p.time_steps],
+        m[Symbol("dvStoragePower"*_n)][b] >= m[Symbol("dvDischargeFromStorage"*_n)][b, ts] 
+            + sum(m[Symbol("dvProductionToStorage"*_n)][b, t, ts] for t in p.techs.elec)
+            + m[Symbol("dvGridToStorage"*_n)][b, ts]
     )
 
-    # Remove grid-to-storage as an option if option to grid charge is turned off
+    # Constraint (4j): Remove grid-to-storage as an option if option to grid charge is turned off
     if !(p.s.storage.attr[b].can_grid_charge)
         for ts in p.time_steps_with_grid
             fix(m[Symbol("dvGridToStorage"*_n)][b, ts], 0.0, force=true)
         end
 	end
 
-    # Constrain average state of charge
+    # Constraint (4k): Constrain average state of charge
     if p.s.storage.attr[b].minimum_avg_soc_fraction > 0
         avg_soc = sum(m[Symbol("dvStoredEnergy"*_n)][b, ts] for ts in p.time_steps) /
                    (8760. / p.hours_per_time_step)
@@ -139,14 +128,14 @@ function add_elec_storage_dispatch_constraints(m, p, b; _n="")
         )
     end
 
-    # Constrain to fixed_soc_series_fraction
-    if hasproperty(p.s.storage.attr[b], :fixed_soc_series_fraction) && !isnothing(p.s.storage.attr[b].fixed_soc_series_fraction)      
+    # Constraint (4l): Constrain to fixed_soc_series_fraction
+    if hasproperty(p.s.storage.attr[b], :fixed_soc_series_fraction) && !isnothing(p.s.storage.attr[b].fixed_soc_series_fraction)
+        # Allow for a percentage point (fractional) buffer on user-provided fixed_soc_series_fraction 
         @constraint(m, [ts in p.time_steps],
-        # Allow for a 1 pct point buffer on user-provided fixed_soc_series_fraction
-            m[Symbol("dvStoredEnergy"*_n)][b, ts] <= (0.02 + p.s.storage.attr[b].fixed_soc_series_fraction[ts]) * m[Symbol("dvStorageEnergy"*_n)][b]
+            m[Symbol("dvStoredEnergy"*_n)][b, ts] <= (p.s.storage.attr[b].fixed_soc_series_fraction_tolerance + p.s.storage.attr[b].fixed_soc_series_fraction[ts]) * m[Symbol("dvStorageEnergy"*_n)][b]
         )
         @constraint(m, [ts in p.time_steps],
-            m[Symbol("dvStoredEnergy"*_n)][b, ts] >= (-0.02 + p.s.storage.attr[b].fixed_soc_series_fraction[ts]) * m[Symbol("dvStorageEnergy"*_n)][b]
+            m[Symbol("dvStoredEnergy"*_n)][b, ts] >= (-p.s.storage.attr[b].fixed_soc_series_fraction_tolerance + p.s.storage.attr[b].fixed_soc_series_fraction[ts]) * m[Symbol("dvStorageEnergy"*_n)][b]
         )
     end
 end

src/core/electric_tariff.jl

@@ -49,7 +49,7 @@ end
     urdb_utility_name::String="",
     urdb_rate_name::String="",
     urdb_metadata::Dict=Dict(), # Meta data about the URDB rate, from the URDB API response
-    wholesale_rate::T1=nothing, # Price of electricity sold back to the grid in absence of net metering. Can be a scalar value, which applies for all-time, or an array with time-sensitive values. If an array is input then it must have a length of 8760, 17520, or 35040. The inputed array values are up/down-sampled using mean values to match the Settings.time_steps_per_hour.
+    wholesale_rate::T1=nothing, # Price of electricity [\$ per kWh] sold back to the grid in absence of net metering. Can be a scalar value, which applies for all-time, or an array with time-sensitive values. If an array is input then it must have a length of 8760, 17520, or 35040. The inputed array values are up/down-sampled using mean values to match the Settings.time_steps_per_hour.
     export_rate_beyond_net_metering_limit::T2=nothing, # Price of electricity sold back to the grid beyond total annual grid purchases, regardless of net metering. Can be a scalar value, which applies for all-time, or an array with time-sensitive values. If an array is input then it must have a length of 8760, 17520, or 35040. The inputed array values are up/down-sampled using mean values to match the Settings.time_steps_per_hour
     monthly_energy_rates::Array=[], # Array (length of 12) of blended energy rates in dollars per kWh
     monthly_demand_rates::Array=[], # Array (length of 12) of blended demand charges in dollars per kW

src/core/energy_storage/electric_storage.jl

@@ -162,7 +162,7 @@ end
 
 
 """
-`ElectricStorage` is an optional optional REopt input with the following keys and default values:
+`ElectricStorage` is an optional REopt input with the following keys and default values:
 
 ```julia
     min_kw::Real = 0.0
@@ -199,7 +199,8 @@ end
     degradation::Dict = Dict()
     minimum_avg_soc_fraction::Float64 = 0.0
     optimize_soc_init_fraction::Bool = false # If true, soc_init_fraction will not apply. Model will optimize initial SOC and constrain initial SOC = final SOC. 
-    fixed_soc_series_fraction::Union{Nothing, Array{<:Real,1}} = nothing # If provided, SOC (as fraction of total energy capacity) will not be optimized and will instead be fixed to the values provided here +- 0.02 (this buffer is to avoid infeasible solutions) 
+    fixed_soc_series_fraction::Union{Nothing, Array{<:Real,1}} = nothing # If provided, SOC (as fraction of total energy capacity) will not be optimized and will instead be fixed to the values provided here +- the absolute fixed_soc_series_fraction_tolerance (this buffer is to avoid infeasible solutions)
+    fixed_soc_series_fraction_tolerance::Real = !isnothing(fixed_soc_series_fraction) ? 0.02 : nothing # Absolute tolerance on fixed_soc_series_fraction to avoid infeasible solutions when fixed_soc_series_fraction is provided.
     min_duration_hours::Real = 0.0 # Minimum amount of time storage can discharge at its rated power capacity
     max_duration_hours::Real = 100000.0 # Maximum amount of time storage can discharge at its rated power capacity (ratio of ElectricStorage size_kwh to size_kw)
 
@@ -244,6 +245,7 @@ Base.@kwdef struct ElectricStorageDefaults
     min_duration_hours::Real = 0.0
     max_duration_hours::Real = 100000.0
     fixed_soc_series_fraction::Union{Nothing, Array{<:Real,1}} = nothing
+    fixed_soc_series_fraction_tolerance::Real = !isnothing(fixed_soc_series_fraction) ? 0.02 : nothing
 end
 
 
@@ -293,7 +295,8 @@ struct ElectricStorage <: AbstractElectricStorage
     optimize_soc_init_fraction::Bool
     min_duration_hours::Real
     max_duration_hours::Real
-    fixed_soc_series_fraction::Union{Nothing, Array{<:Real,1}} 
+    fixed_soc_series_fraction::Union{Nothing, Array{<:Real,1}}
+    fixed_soc_series_fraction_tolerance::Real
 
     function ElectricStorage(d::Dict, f::Financial, s::Site)  
         set_sector_defaults!(d; struct_name="Storage", sector=s.sector, federal_procurement_type=s.federal_procurement_type)
@@ -312,12 +315,16 @@ struct ElectricStorage <: AbstractElectricStorage
         end
 
         # Copy SOC input in case we need to change them
+        soc_init_fraction = s.soc_init_fraction
         soc_min_fraction = s.soc_min_fraction
         optimize_soc_init_fraction = s.optimize_soc_init_fraction
+        minimum_avg_soc_fraction = s.minimum_avg_soc_fraction
         if !isnothing(s.fixed_soc_series_fraction) 
             @warn "Fixing ElectricStorage soc_series_fraction to the provided fixed_soc_series_fraction. Other SOC inputs will be ignored."
+            soc_init_fraction = s.fixed_soc_series_fraction[1]
             soc_min_fraction = 0.0
             optimize_soc_init_fraction = false
+            minimum_avg_soc_fraction = 0.0
             error_if_series_vals_not_0_to_1(s.fixed_soc_series_fraction, "ElectricStorage", "fixed_soc_series_fraction")
         end
 
@@ -409,7 +416,7 @@ struct ElectricStorage <: AbstractElectricStorage
             s.rectifier_efficiency_fraction,
             soc_min_fraction,
             s.soc_min_applies_during_outages,
-            s.soc_init_fraction,
+            soc_init_fraction,
             s.can_grid_charge,
             s.installed_cost_per_kw,
             s.installed_cost_per_kwh,
@@ -435,11 +442,12 @@ struct ElectricStorage <: AbstractElectricStorage
             net_present_cost_cost_constant,
             s.model_degradation,
             degr,
-            s.minimum_avg_soc_fraction,
+            minimum_avg_soc_fraction,
             optimize_soc_init_fraction,
             s.min_duration_hours,
             s.max_duration_hours,
-            s.fixed_soc_series_fraction
+            s.fixed_soc_series_fraction,
+            s.fixed_soc_series_fraction_tolerance
         )
     end
 end

src/core/reopt.jl

@@ -192,8 +192,8 @@ function build_reopt!(m::JuMP.AbstractModel, p::REoptInputs)
 			fix(m[:dvGridPurchase][ts, tier] , 0.0, force=true)
 		end
 
-		for t in p.s.storage.types.elec
-			fix(m[:dvGridToStorage][t, ts], 0.0, force=true)
+		for b in p.s.storage.types.elec
+			fix(m[:dvGridToStorage][b, ts], 0.0, force=true)
 		end
 
         if !isempty(p.s.electric_tariff.export_bins)
@@ -421,7 +421,7 @@ function build_reopt!(m::JuMP.AbstractModel, p::REoptInputs)
 
 		degr_bool = p.s.storage.attr[b].model_degradation
 		if degr_bool
-			@info "Battery energy capacity degradation costs for $b are being modeled using REopt's Degradation model. ElectricStorageOMCost will include costs to be incurred for power electronics and the cost constant."
+			@info "Battery energy capacity degradation costs for $b are being modeled using REopt's Degradation model. ElectricStorageOMCost will include costs incurred for power electronics [per kW] and the cost constant, but not for the per kWh components."
             add_to_expression!(
 				m[:ElectricStorageOMCost], -1.0 * p.third_party_factor * p.pwf_om * p.s.storage.attr[b].om_cost_fraction_of_installed_cost * p.s.storage.attr[b].installed_cost_per_kwh * m[:dvStorageEnergy][b]
 			)

src/core/scenario.jl

@@ -44,7 +44,6 @@ A Scenario struct can contain the following keys:
 - [HotThermalStorage](@ref) (optional)
 - [HighTempThermalStorage](@ref) (optional)
 - [ColdThermalStorage](@ref) (optional)
-- [ElectricStorage](@ref) (optional)
 - [ElectricUtility](@ref) (optional)
 - [Generator](@ref) (optional)
 - [HeatingLoad](@ref) (optional)

src/core/utils.jl

@@ -169,6 +169,8 @@ function dictkeys_tosymbols(d::Dict)
             "cooling_cop_reference",
             "cooling_cf_reference",
             "cooling_reference_temps_degF",
+            "cycle_fade_coefficient",
+            "cycle_fade_fraction",
             #for ERP
             "pv_production_factor_series", "wind_production_factor_series",
             "battery_starting_soc_series_fraction",

src/mpc/model.jl

@@ -82,8 +82,8 @@ function build_mpc!(m::JuMP.AbstractModel, p::MPCInputs)
 
 		fix(m[:dvGridPurchase][ts], 0.0, force=true)
 
-		for t in p.s.storage.types.elec
-			fix(m[:dvGridToStorage][t, ts], 0.0, force=true)
+		for b in p.s.storage.types.elec
+			fix(m[:dvGridToStorage][b, ts], 0.0, force=true)
 		end
 
 		for t in p.techs.elec, u in p.export_bins_by_tech[t]

src/mpc/structs.jl

@@ -228,6 +228,7 @@ Base.@kwdef struct MPCElectricStorage < AbstractElectricStorage
     can_grid_charge::Bool = true
     grid_charge_efficiency::Float64 = 0.96 * 0.975^2
     fixed_soc_series_fraction::Union{Nothing, Array{<:Real,1}} = nothing
+    fixed_soc_series_fraction_tolerance::Real = !isnothing(fixed_soc_series_fraction) ? 0.05 : nothing
 end
 ```
 """
@@ -244,6 +245,7 @@ Base.@kwdef struct MPCElectricStorage <: AbstractElectricStorage
     max_kwh::Float64 = size_kwh
     minimum_avg_soc_fraction::Float64 = 0.0
     fixed_soc_series_fraction::Union{Nothing, Array{<:Real,1}} = nothing
+    fixed_soc_series_fraction_tolerance::Real = !isnothing(fixed_soc_series_fraction) ? 0.05 : nothing
 end
 
 

src/results/electric_storage.jl

@@ -3,11 +3,11 @@
 `ElectricStorage` results keys:
 - `size_kw` Optimal inverter capacity
 - `size_kwh` Optimal storage capacity
-- `soc_series_fraction` Vector of normalized (0-1) state of charge values over the first year
-- `storage_to_load_series_kw` Vector of power used to meet load over the first year
+- `soc_series_fraction` Vector of normalized (0-1) state of charge values over an average year
+- `storage_to_load_series_kw` Vector of power used to meet load over an average year
 - `initial_capital_cost` Upfront capital cost for storage and inverter
 # The following results are reported if storage degradation is modeled:
-- `state_of_health`
+- `state_of_health_series_fraction`
 - `maintenance_cost`
 - `replacement_month` # only applies is maintenance_strategy = "replacement"
 - `residual_value`
@@ -38,7 +38,7 @@ function add_electric_storage_results(m::JuMP.AbstractModel, p::REoptInputs, d::
             p.s.storage.attr[b].installed_cost_constant
 
         if p.s.storage.attr[b].model_degradation
-            r["state_of_health"] = round.(value.(m[:SOH]).data / value.(m[:dvStorageEnergy])["ElectricStorage"], digits=3)
+            r["state_of_health_series_fraction"] = round.(value.(m[:SOH]).data / value.(m[:dvStorageEnergy])["ElectricStorage"], digits=3)
             r["maintenance_cost"] = value(m[:degr_cost])
             if p.s.storage.attr[b].degradation.maintenance_strategy == "replacement"
                 r["replacement_month"] = round(Int, value(
@@ -48,9 +48,9 @@ function add_electric_storage_results(m::JuMP.AbstractModel, p::REoptInputs, d::
                 # Determine fraction of useful life left assuming same replacement frequency.
                 # Multiply by 0.2 to scale residual useful life since entire BESS is replaced when SOH drops below 80%.
                 # Total BESS capacity residual is (0.8 + residual useful fraction) * BESS capacity
-                # If not replacements happen then useful capacity is SOH[end]*BESS capacity.
+                # If no replacements happen then useful capacity is SOH[end]*BESS capacity.
                 if iszero(r["replacement_month"])
-                    r["total_residual_kwh"] = r["state_of_health"][end]*r["size_kwh"]
+                    r["total_residual_kwh"] = r["state_of_health_series_fraction"][end]*r["size_kwh"]
                 else
                     # SOH[end] can be negative, so alternate method to calculate residual healthy SOH.
                     total_replacements = (p.s.financial.analysis_years*12)/r["replacement_month"]