Merge pull request #822 from GenXProject/release/0.4.3

Patch Release v0.4.3
GenXProject · Jan 30, 2025 · dcf3df0 · dcf3df0 · lbonaldo · Jan 30, 2025
2 parents 0efaff1 + 8e5af17
commit dcf3df0
Show file tree

Hide file tree

Showing 12 changed files with 41 additions and 23 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## [0.4.3] - 2025-01-29
+
+### Changed
+- Changed the output filename for RSV from `reg_dn.csv` to `reserves.csv` (#814).
+- Created link in the thermal doc page to fuels page for piecewise linear cost curve documentation (#820).
+- Doc rendering fix in fuel.jl (#821).
+
+### Fixed
+- Fixed capacity reserve margin formulation for asymmetric storage
+when OperationalReserves is on. (#818)
+
 ## [0.4.2] - 2024-12-23
 
 ### Added

diff --git a/CITATION.cff b/CITATION.cff
@@ -54,7 +54,7 @@ authors:
   given-names: "Qingyu"
   orcid: "https://orcid.org/0000-0003-2692-5135"
 title: "GenX"
-version: 0.4.2
+version: 0.4.3
 doi: 10.5281/zenodo.10846070
-date-released: 2024-04-26
+date-released: 2025-01-29
 url: "https://github.com/GenXProject/GenX.jl"
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "GenX"
 uuid = "5d317b1e-30ec-4ed6-a8ce-8d2d88d7cfac"
 authors = ["Bonaldo, Luca", "Chakrabarti, Sambuddha", "Cheng, Fangwei", "Ding, Yifu", "Jenkins, Jesse D.", "Luo, Qian", "Macdonald, Ruaridh", "Mallapragada, Dharik", "Manocha, Aneesha", "Mantegna, Gabe ", "Morris, Jack", "Patankar, Neha", "Pecci, Filippo", "Schwartz, Aaron", "Schwartz, Jacob", "Schivley, Greg", "Sepulveda, Nestor", "Xu, Qingyu", "Zhou, Justin"]
-version = "0.4.2"
+version = "0.4.3"
 
 [deps]
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"

diff --git a/README.md b/README.md
@@ -40,7 +40,7 @@ The 'main' branch is the current master branch of GenX. The various subdirectori
 
 ## Requirements
 
-GenX (v0.4.2) runs on Julia v1.6 through v1.9, with a minimum version of the package JuMP v1.1.1. Julia v1.10 and v1.11 are also supported. However, we recently noticed a decline in performance with Julia v1.10, which is currently under investigation. Therefore, **we recommend using Julia v1.9**, particularly for very large cases.
+GenX (v0.4.3) runs on Julia v1.6 through v1.9, with a minimum version of the package JuMP v1.1.1. Julia v1.10 and v1.11 are also supported. However, we recently noticed a decline in performance with Julia v1.10, which is currently under investigation. Therefore, **we recommend using Julia v1.9**, particularly for very large cases.
 We recommend the users to either stick to a particular version of Julia to run GenX. If however, the users decide to switch between versions, it's very important to delete the old `Manifest.toml` file and do a fresh build of GenX when switching between Julia versions.
 
 There is also an older version of GenX, which is also currently maintained and runs on Julia 1.3.x and 1.4.x series.

diff --git a/docs/src/User_Guide/generate_alternatives.md b/docs/src/User_Guide/generate_alternatives.md
@@ -10,4 +10,4 @@ GenX includes a modeling to generate alternatives (MGA) package that can be used
 6. Set the `MGAAnnualGeneration` flag in the `genx_settings.yml` file to the desired MGA formulation.
 7. Solve the model using `Run.jl` file.
 
-Results from the MGA algorithm would be saved in MGA_max and MGA_min folders in the case folder.
+Results from the MGA algorithm would be saved in MGA\_max and MGA\_min folders in the case folder.
diff --git a/docs/src/User_Guide/model_configuration.md b/docs/src/User_Guide/model_configuration.md
@@ -52,7 +52,7 @@ The following tables summarize the model settings parameters and their default/p
 |MultiStage | Model multiple planning stages |
 ||1 = Model multiple planning stages as specified in `multi_stage_settings.yml` |
 ||0 = Model single planning stage |
-|ModelingToGenerateAlternatives | Modeling to Generate Alternative Algorithm. For details, see [here](https://genxproject.github.io/GenX/dev/additional_features/#Modeling-to-Generate-Alternatives)|
+|ModelingToGenerateAlternatives | Modeling to Generate Alternatives Algorithm. For more details, see the [Modeling to Generate Alternatives](@ref) section in the **Model Reference**.|
 ||1 = Use the algorithm. |
 ||0 = Do not use the algorithm. |
 |ModelingtoGenerateAlternativeSlack | value used to define the maximum deviation from the least-cost solution as a part of Modeling to Generate Alternative Algorithm. Can take any real value between 0 and 1. |

diff --git a/docs/src/User_Guide/model_input.md b/docs/src/User_Guide/model_input.md
@@ -142,7 +142,7 @@ The `resources` folder contains the input files for each resource type. At the c
 
 Each file contains cost and performance parameters for various generators and other resources included in the model formulation. The following table describes the mandatory columns in each of these files. Note that the column names are case insensitive.
 
-##### Table 5a: Mandatory columns in all resource .csv file
+##### Table 5a: Columns in resource .csv files that are common to all resources
 ---
 |**Column Name** | **Description**|
 | :------------ | :-----------|
@@ -196,7 +196,7 @@ Each file contains cost and performance parameters for various generators and ot
 |Maintenance\_Duration| (Positive integer, less than total length of simulation.) Duration of the maintenance period, in number of timesteps. Only used if `MAINT=1`.|
 |Maintenance\_Cycle\_Length\_Years| Length of scheduled maintenance cycle, in years. `1` is maintenance every year, `3` is every three years, etc. (Positive integer. Only used if `MAINT=1`.)|
 |Maintenance\_Begin\_Cadence| Cadence of timesteps in which scheduled maintenance can begin. `1` means that a maintenance period can start in any timestep, `24` means it can start only in timesteps 1, 25, 49, etc. A larger number can decrease the simulation computational cost as it limits the optimizer's choices. (Positive integer, less than total length of simulation. Only used if `MAINT=1`.)|
-|**CO2-related parameters required if any resources have nonzero CO2_Capture_Fraction**|
+|**CO2-related parameters required if any resources have nonzero CO2\_Capture\_Fraction**|
 |CO2\_Capture\_Fraction  |[0,1], The CO2 capture fraction of CCS-equipped power plants during steady state operation. This value should be 0 for generators without CCS. |
 |CO2\_Capture\_Fraction\_Startup  |[0,1], The CO2 capture fraction of CCS-equipped power plants during the startup events. This value should be 0 for generators without CCS |
 |Biomass | {0, 1}, Flag to indicate if generator uses biomass as feedstock (optional input column).|
@@ -210,6 +210,7 @@ Each file contains cost and performance parameters for various generators and ot
 |Model | {1, 2}, Flag to indicate membership in set of thermal resources (e.g. nuclear, combined heat and power, natural gas combined cycle, coal power plant)|
 ||Model = 1: If the power plant relies on thermal energy input and subject unit commitment constraints/decisions if `UCommit >= 1` (e.g. cycling decisions/costs/constraints). |
 ||Model = 2: If the power plant relies on thermal energy input and is subject to simplified economic dispatch constraints (ramping limits and minimum output level but no cycling decisions/costs/constraints). |
+|Cap\_size | Size (MW) of a single generating unit. This is used for resources with integer unit commitment (`Model = 1`). |
 |Min\_Power |[0,1], The minimum generation level for a unit as a fraction of total capacity. This value cannot be higher than the smallest time-dependent CF value for a resource in `Generators_variability.csv`.|
 |Ramp\_Up\_Percentage |[0,1], Maximum increase in power output from between two periods (typically hours), reported as a fraction of nameplate capacity.|
 |Ramp\_Dn\_Percentage |[0,1], Maximum decrease in power output from between two periods (typically hours), reported as a fraction of nameplate capacity.|

diff --git a/docs/src/installation.md b/docs/src/installation.md
@@ -2,7 +2,7 @@
 This guide will walk you through the steps to install Julia, the GenX package, and the required dependencies to run GenX.
 
 ## Installing Julia
-GenX (v0.4.2) runs on Julia v1.6 through v1.9, with a minimum version of the package [JuMP](https://jump.dev/JuMP.jl/stable/) v1.1.1. Julia v1.10 and v1.11 are also supported. However, we recently noticed a decline in performance with Julia v1.10, which is currently under investigation. Therefore, we recommend using Julia v1.9, particularly for very large cases. To install Julia, please follow the instructions on the [Julia website](https://julialang.org/downloads/).
+GenX (v0.4.3) runs on Julia v1.6 through v1.9, with a minimum version of the package [JuMP](https://jump.dev/JuMP.jl/stable/) v1.1.1. Julia v1.10 and v1.11 are also supported. However, we recently noticed a decline in performance with Julia v1.10, which is currently under investigation. Therefore, we recommend using Julia v1.9, particularly for very large cases. To install Julia, please follow the instructions on the [Julia website](https://julialang.org/downloads/).
 
 !!! note "Note" 
     We recommend the users to stick to a particular version of Julia to run GenX. If however, the users decide to switch between versions, it's very important to delete the old `Manifest.toml` file and do a fresh build of GenX.

diff --git a/src/model/core/fuel.jl b/src/model/core/fuel.jl
@@ -4,22 +4,25 @@
 
 This function creates expressions to account for total fuel consumption (e.g., coal, 
 natural gas, hydrogen, etc). It also has the capability to model heat rates that are
-a function of load via a piecewise-linear approximation.
+a function of load via a piecewise-linear approximation. See also the [`thermal!`](@ref) page.
+
+**Expressions**
 
-***** Expressions ******
 Users have two options to model the fuel consumption as a function of power generation: 
 (1). Use a constant heat rate, regardless of the minimum load or maximum load; and 
+
 (2). Use the PiecewiseFuelUsage-related parameters to model the fuel consumption via a 
 piecewise-linear approximation of the heat rate curves. By using this option, users can represent 
 the fact that most generators have a decreasing heat rate as a function of load.
 
-(1). Constant heat rate. 
+(1). Constant heat rate: 
 The fuel consumption for power generation $vFuel_{y,t}$ is determined by power generation 
 ($vP_{y,t}$) mutiplied by the corresponding heat rate ($Heat\_Rate_y$). 
 The fuel costs for power generation and start fuel for a plant $y$ at time $t$, 
 denoted by $eCFuelOut_{y,t}$ and $eFuelStart$, are determined by fuel consumption ($vFuel_{y,t}$ 
 and $eStartFuel$) multiplied by the fuel costs (\$/MMBTU)
-(2). Piecewise-linear approximation
+
+(2). Piecewise-linear approximation: 
 With this formulation, the heat rate of generators becomes a function of load.
 In reality this relationship takes a nonlinear form, but we model it
 through a piecewise-linear approximation:
@@ -35,11 +38,11 @@ Where $h_{y,x}$ represents the heat rate slope for generator $y$ in segment $x$
 and $U_{y,t}$ represents the commitment status of a generator $y$ at time $t$. These parameters
 are optional inputs to the resource .csv files. 
 When Unit commitment is on, if a user provides slope and intercept, the standard heat rate 
-(i.e., Heat_Rate_MMBTU_per_MWh) will not be used. When unit commitment is off, the model will 
+(i.e., Heat\_Rate\_MMBTU\_per\_MWh) will not be used. When unit commitment is off, the model will 
 always use the standard heat rate.
-The user should determine the slope and intercept parameters based on the Cap_Size of the plant. 
-For example, when a plant is operating at the full load (i.e., power output equal to the Cap_Size),
-the fuel usage determined by the effective segment divided by Cap_Size should be equal to the 
+The user should determine the slope and intercept parameters based on the Cap\_Size of the plant. 
+For example, when a plant is operating at the full load (i.e., power output equal to the Cap\_Size),
+the fuel usage determined by the effective segment divided by Cap\_Size should be equal to the 
 heat rate at full-load.
 
 Since fuel consumption and fuel costs are postive, the optimization will force the fuel usage
@@ -48,11 +51,13 @@ When the power output is zero, the commitment variable $U_{g,t}$ will bring the
 to be zero such that the fuel consumption is zero when thermal units are offline.
 
 In order to run piecewise fuel consumption module,
-the unit commitment must be turned on (UC = 1 or 2), and users should provide PWFU_Slope_* and 
-PWFU_Intercept_* for at least one segment. 
+the unit commitment must be turned on (UC = 1 or 2), and users should provide $PWFU_{y_0}$, $PWFU_{Slope_i}$ and 
+$PWFU_{Intercept_i}$ for at least one segment ($PWFU$ refers to Piece Wise Fuel Usage) (Refer to 
+the PWFU parameters in [Table 6a: Additional columns in the Thermal.csv file](@ref) for the corresponding entries against the above-mentioned ones). 
 
 To enable resources to use multiple fuels during both startup and normal operational processes, three additional variables were added: 
-fuel $i$ consumption by plant $y$ at time $t$ ($vMulFuel_{y,i,t}$); startup fuel consumption for single-fuel plants ($vStartFuel_{y,t}$); and startup fuel consumption for multi-fuel plants ($vMulStartFuel_{y,i,t}$). By making startup fuel consumption variables, the model can choose the startup fuel to meet the constraints.    
+fuel $i$ consumption by plant $y$ at time $t$ ($vMulFuel_{y,i,t}$); startup fuel consumption for single-fuel plants ($vStartFuel_{y,t}$); 
+and startup fuel consumption for multi-fuel plants ($vMulStartFuel_{y,i,t}$). By making startup fuel consumption variables, the model can choose the startup fuel to meet the constraints.    
     
 For plants using multiple fuels:
     

diff --git a/src/model/resources/storage/storage_all.jl b/src/model/resources/storage/storage_all.jl
@@ -213,7 +213,7 @@ function storage_all_operational_reserves!(EP::Model, inputs::Dict, setup::Dict)
     gen = inputs["RESOURCES"]
     T = inputs["T"]
     p = inputs["hours_per_subperiod"]
-    CapacityReserveMargin = setup["CapacityReserveMargin"] > 1
+    CapacityReserveMargin = setup["CapacityReserveMargin"] > 0
 
     STOR_ALL = inputs["STOR_ALL"]
 

diff --git a/src/model/resources/thermal/thermal.jl b/src/model/resources/thermal/thermal.jl
@@ -2,6 +2,7 @@
     thermal!(EP::Model, inputs::Dict, setup::Dict)
 The thermal module creates decision variables, expressions, and constraints related to thermal power plants e.g. coal, oil or natural gas steam plants, natural gas combined cycle and combustion turbine plants, nuclear, hydrogen combustion etc.
 This module uses the following 'helper' functions in separate files: ```thermal_commit()``` for thermal resources subject to unit commitment decisions and constraints (if any) and ```thermal_no_commit()``` for thermal resources not subject to unit commitment (if any).
+For the piecewise linear cost function for thermal generators, please refer to the documentation in the [`fuel!`](@ref) page
 """
 function thermal!(EP::Model, inputs::Dict, setup::Dict)
     gen = inputs["RESOURCES"]

diff --git a/src/write_outputs/reserves/write_rsv.jl b/src/write_outputs/reserves/write_rsv.jl
@@ -12,7 +12,7 @@ function write_rsv(path::AbstractString, inputs::Dict, setup::Dict, EP::Model)
     dfRsv.AnnualSum = rsv * inputs["omega"]
 
     if setup["WriteOutputs"] == "annual"
-        write_annual(joinpath(path, "reg_dn.csv"), dfRsv)
+        write_annual(joinpath(path, "reserves.csv"), dfRsv)
     else # setup["WriteOutputs"] == "full"
         unmet_vec = value.(EP[:vUNMET_RSV]) * scale_factor
         total_unmet = sum(unmet_vec)
@@ -30,7 +30,7 @@ function write_rsv(path::AbstractString, inputs::Dict, setup::Dict, EP::Model)
         rename!(total, auxNew_Names)
         rename!(unmet, auxNew_Names)
         dfRsv = vcat(dfRsv, unmet, total)
-        CSV.write(joinpath(path, "reg_dn.csv"),
+        CSV.write(joinpath(path, "reserves.csv"),
             dftranspose(dfRsv, false),
             writeheader = false)
     end