Hourlymatching

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Added
+- A generalized hourly matching policy module (#855).
+
+### Fixed
+- Fix writing of net revenue to include all sources of revenue, not just energy revenue (#855).
+
 ### Changed
 - Changed default value of parameter scaling to 1 (#866)
 
@@ -25,7 +31,6 @@ Models running with, non-default, solvers Cbc and Clp will fail unless
 - Modify `storage_all.jl` to prevent micro-charging/discharging close to capacity (#836).
 - Got rid of brodcast operator src/write_outputs/capacity_reserve_margin/write_virtual_discharge.jl for preventing error with Julia 1.6 (#885)
 
-
 ### Changed
 - Replace `+=` and `-=` with `add_to_expression!` and `add_similar_to_expression!`
 in several modules to improve performance (#826).

docs/src/Model_Concept_Overview/model_notation.md

@@ -17,6 +17,7 @@ $z \in \mathcal{Z}$ | where $z$ denotes a zone and $\mathcal{Z}$ is the set of z
 |$\mathcal{VRE} \subseteq \mathcal{G}$ | where $\mathcal{VRE}$ is the subset of curtailable Variable Renewable Energy (VRE) resources|
 |$\overline{\mathcal{VRE}}^{y,z}$ | set of VRE resource bins for VRE technology type $y \in \mathcal{VRE}$ in zone $z$ |
 |$\mathcal{CE} \subseteq \mathcal{G}$ | where $\mathcal{CE}$ is the subset of resources qualifying for the clean energy standard policy constraint|
+|$\mathcal{HM} \subseteq \mathcal{G}$ | where $\mathcal{HM}$ is the subset of resources qualifying for the hourly matching policy constraint|
 |$\mathcal{UC} \subseteq \mathcal{H}$ | where $\mathcal{UC}$ is the subset of thermal resources subject to unit commitment constraints|
 |$s \in \mathcal{S}$ | where $s$ denotes a segment and $\mathcal{S}$ is the set of consumers segments for price-responsive demand curtailment|
 |$\mathcal{O} \subseteq \mathcal{G}$ | where $\mathcal{O}$ is the subset of storage resources excluding heat storage and hydro storage |
@@ -152,7 +153,6 @@ $\mathcal{W} \subseteq \mathcal{G}$ | where $\mathcal{W}$ set of hydroelectric g
 |$\Gamma^{CRM}_{y,z,t} \in \mathbb{R}_+$ | Total "virtual" state of charge being held in reserves for technology $y$ at time step $t$ in zone $z$ - only applicable for standalone storage and co-located VRE and storage resources with activated capacity reserve margin policies, $y \in \mathcal{O} \cup y \in \mathcal{VS}^{stor}$ \[MWh]|
 ---
 
-
 ## Parameters
 ---
 |**Notation** | **Description**|

docs/src/Model_Reference/policies.md

@@ -32,7 +32,7 @@ GenX.hydrogen_demand!
 ```
 
 ## Hourly clean supply matching constraint
-```@autodocs
-Modules = [GenX]
-Pages = ["hourly_matching.jl"]
+```@docs
+GenX.load_hourly_matching_requirement!
+GenX.hourly_matching!
 ```

docs/src/Model_Reference/write_outputs.md

@@ -121,6 +121,13 @@ Modules = [GenX]
 Pages = ["write_reserve_margin_revenue.jl"]
 ```
 
+## Write Hourly Matching Revenue
+```@docs
+GenX.write_hourly_matching_prices
+GenX.write_hourly_matching_revenue
+GenX.write_hourly_matching_slack
+```
+
 ## Write Energy Share Requirement Revenue
 ```@autodocs
 Modules = [GenX]

docs/src/User_Guide/model_input.md

@@ -30,7 +30,8 @@ Additionally, the user may need to specify eight more **settings-specific** inpu
 7. Vre\_and\_stor\_solar\_variability.csv: specify time-series of capacity factor/availability for each solar PV resource that exists for every co-located VRE and storage resource (in DC terms).
 8. Vre\_and\_stor\_wind\_variability.csv: specify time-series of capacity factor/availability for each wind resource that exists for every co-located VRE and storage resource (in AC terms).
 9. Hydrogen\_demand.csv: specify regional hydrogen production requirements.
-
+10. Hourly\_matching\_requirement.csv: specify hourly matching policies requiring minimum generation from qualifying resources in each model timestep. The second row specifies the hourly matching target percentage for each hourly matching constraint, and the remaining rows specify the participating demand to be matched in each timestep.
+11. Hourly\_matching\_requirement\_zonal.csv: Optional. Specify demand participating in hourly matching requirements as a fraction of total demand in each model region.
 
 !!! note "Note"
     Names of the input files are case sensitive.
@@ -353,9 +354,7 @@ Each file contains cost and performance parameters for various generators and ot
 |Hydrogen\_Price\_Per\_Tonne| Price (or value) of hydrogen per metric tonne (USD/t)|
 |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.|
-!!! note
-    Check `Qualified_Hydrogen_Supply` column in table 5a if electrolyzers are included in the model. This column is used to indicate which resources are eligible to supply electrolyzers in the same zone (used for hourly clean supply constraint).
+|Ramp\_Dn\_Percentage |[0,1], Maximum decrease in power output from between two periods (typically hours), reported as a fraction of nameplate capacity.
 
 Each co-located VRE, electrolyzer, and storage resource can be easily configured to contain either a co-located VRE-ELEC-storage resource, standalone VRE resource (either wind, solar PV, or both), standalone eletrolyzers, or standalone storage resource.
 ##### Table 12a: Additional columns in the Vre_stor.csv file
@@ -536,7 +535,7 @@ In addition to the files described above, the `resources` folder contains a fold
 3) `Resource_maximum_capacity_requirement.csv`
 4) `Resource_capacity_reserve_margin.csv`
 5) `Resource_hydrogen_demand.csv`
-6) `Resource_hourly_matching.csv`
+6) `Resource_hourly_matching_requirement.csv`
 
 !!! note
     These files are optional and can be omitted if no policy-related settings are specified in the `genx_settings.yml` file. Also, not all the resources need to be included in these files, only those for which the policy applies.
@@ -605,14 +604,13 @@ This policy is applied when if `HydrogenMinimumProduction = 1` in the settings f
 |Resource| Resource name corresponding to a resource in one of the resource data files described above.|
 |H2\_Demand\_*| Flag to indicate which resources are considered for the Hydrogen Demand constraint.|
 
-This policy is applied when if `HourlyMatching = 1` in the settings file.
 
-##### Table 19: Hourly matching policy parameters in Resource\_hourly\_matching.csv
+##### Table 19: Hourly matching policy parameters in Resource\_hourly\_matching\_requirement.csv
 ---
 |**Column Name** | **Description**|
 | :------------ | :-----------|
 |Resource| Resource name corresponding to a resource in one of the resource data files described above.|
-|Qualified\_Supply| Flag to indicate which resources are eligible to supply the generation in the same zone.|
+|HM\_*| Flag to indicate which resources are eligible to contribute toward a given hourly matching constraint.|
 
 ##### Additional module-related columns for all resources
 In addition to the files described above, the `resources` folder can contain additional files that are used to specify attributes for specific resources and modules. Currently, the following files are supported:

docs/src/User_Guide/slack_variables_overview.md

@@ -35,6 +35,12 @@ Slack variables for Energy Share Requirement constraints are created when GenX d
 This file should contain two columns: one titled 'ESR_Constraint' naming the individual Energy Share Requirement constraints in the same order in which they are listed in the first row of `Energy_share_requirement.csv`, and a second titled 'PriceCap' containing the price thresholds for each constraint. 
 The units for these thresholds are USD/MWh.
 
+## Hourly Matching Requirement
+
+Slack variables for Hourly Matching Requirement constraints are created when GenX detects the presence of the file `Hourly_matching_requirement_slack.csv` in the Inputs folder. 
+This file should contain two columns: one titled 'HM_Constraint' naming the individual Hourly Matching Requirement constraints in the same order in which they are listed in the first row of `Hourly_matching_requirement.csv`, and a second titled 'PriceCap' containing the price thresholds for each constraint. 
+The units for these thresholds are USD/MWh.
+
 ## Minimum Capacity Requirement
 
 Slack variables for Minimum Capacity Requirement constraints are created when GenX detects the presence of a column titled 'PriceCap' in the file `Minimum_capacity_requirement.csv`. 
@@ -48,9 +54,11 @@ This column contains the price thresholds for each Maximum Capacity Requirement
 ## Slack Variables Results Files
 
 By default, a policy type's result files include the shadow prices for each policy constraint. 
-When slack variables are activated, outputs also include the final values of the slack variables (i.e. the amount by which the policy constraint was violated), and the total costs associated with those slack variables. 
+When slack variables are activated for policies that do not create constraints in each timestep (all except Capacity Reserve Margin and Hourly Matching), these outputs also include the final values of the slack variables (i.e. the amount by which the policy constraint was violated), and the total costs associated with those slack variables. 
 These files are named using the convention `X_prices_and_penalties.csv`, where `X` is the name of the relevant policy type.
 
+For Capacity Reserve Margin and Hourly Matching constraints, which have slack variables for each timestep, GenX will create a separate output file using the naming convention `X_slack_and_penalties.csv`, where `X` is the name of the relevant policy type.
+
 GenX will also print the total cost associated with each activated slack variable type in the file `costs.csv`.
 
 ## Slack Variables Example