Add combined-cycle gas turbine class with default values

docs/combined_cycle_gas_turbine.md

@@ -0,0 +1,189 @@
+# Combined Cycle Gas Turbine
+
+The `CombinedCycleGasTurbine` class models a combined-cycle gas turbine (CCGT). It is a subclass of {doc}`ThermalComponentBase <thermal_component_base>` and inherits all state machine behavior, ramp constraints, and operational logic from the base class. This class represents the combined gas turbine and steam turbine operation as an improvement in the fuel efficiency of the unit and does not model the individual generators.
+
+For details on the state machine, startup/shutdown behavior, and base parameters, see {doc}`thermal_component_base`.
+
+## CCGT-Specific Parameters
+
+The CCGT class provides default values for natural gas properties from [6]:
+
+| Parameter | Units | Default | Description |
+|-----------|-------|---------|-------------|
+| `hhv` | J/m³ | 39050000 | Higher heating value of natural gas (39.05 MJ/m³) [6] |
+| `fuel_density` | kg/m³ | 0.768 | Fuel density for mass calculations [6] |
+
+The `efficiency_table` parameter is **optional**. If not provided, default values based on approximate readings from the CC1A-F curve in Exhibit ES-4 of [5] are used. All efficiency values are **HHV (Higher Heating Value) net plant efficiencies**. See {doc}`thermal_component_base` for details on the efficiency table format.
+
+## Default Parameter Values
+
+The `CombinedCycleGasTurbine` class provides default values for base class parameters based on References [1-5]. Only `rated_capacity` and `initial_conditions` are required in the YAML configuration.
+
+| Parameter | Default Value | Source |
+|-----------|---------------|--------|
+| `min_stable_load_fraction` | 0.40 (40%) | [4] |
+| `ramp_rate_fraction` | 0.03 (3%/min) | [1] |
+| `run_up_rate_fraction` | Same as `ramp_rate_fraction` | — |
+| `hot_startup_time` | 4500 s (75 minutes, 1.25 hours) | [1], [5] |
+| `warm_startup_time` | 7200 s (120 minutes, 2 hours) | [1], [5] |
+| `cold_startup_time` | 10800 s (180 minutes, 3 hours) | [1], [5] |
+| `min_up_time` | 14400 s (240 minutes, 4 hours) | [4] |
+| `min_down_time` | 7200 s (120 minutes, 2 hours) | [4] |
+| `hhv` | 39050000 J/m³ (39.05 MJ/m³) | [6] |
+| `fuel_density` | 0.768 kg/m³ | [6] |
+| `efficiency_table` | SC1A HHV net efficiency (see below) | Exhibit ES-4 of [5] |
+
+### Default Efficiency Table
+
+The default HHV net plant efficiency table is based on approximate readings from the CC1A-F curve in Exhibit ES-4 of [5]:
+
+| Power Fraction | HHV Net Efficiency |
+|---------------|-------------------|
+| 1.00 | 0.53 (53%) |
+| 0.95 | 0.515 (51.5%) |
+| 0.90 | 0.52 (52%) |
+| 0.85 | 0.52 (52%) |
+| 0.80 | 0.52 (52%) |
+| 0.75 | 0.52 (52%) |
+| 0.70 | 0.52 (52%) |
+| 0.65 | 0.515 (51.5%) |
+| 0.60 | 0.505 (50.5%) |
+| 0.55 | 0.5 (50%) |
+| 0.50 | 0.49 (49%) |
+| 0.4 | 0.47 (47%) |
+
+## CCGT Outputs
+
+The CCGT model provides the following outputs (inherited from base class):
+
+| Output | Units | Description |
+|--------|-------|-------------|
+| `power` | kW | Actual power output |
+| `state` | integer | Operating state number (0-5), corresponding to the `STATES` enum |
+| `efficiency` | fraction (0-1) | Current HHV net plant efficiency |
+| `fuel_volume_rate` | m³/s | Fuel volume flow rate |
+| `fuel_mass_rate` | kg/s | Fuel mass flow rate (computed using `fuel_density` [6]) |
+
+### Efficiency and Fuel Rate
+
+HHV net plant efficiency varies with load based on the `efficiency_table`. The fuel volume rate is calculated as:
+
+$$
+\text{fuel\_volume\_rate} = \frac{\text{power}}{\text{efficiency} \times \text{hhv}}
+$$
+
+Where:
+- `power` is in W (converted from kW internally)
+- `efficiency` is the HHV net efficiency interpolated from the efficiency table
+- `hhv` is the higher heating value in J/m³ (default 39.05 MJ/m³ for natural gas [6])
+- Result is fuel volume rate in m³/s
+
+The fuel mass rate is then computed from the volume rate using the fuel density [6]:
+
+$$
+\text{fuel\_mass\_rate} = \text{fuel\_volume\_rate} \times \text{fuel\_density}
+$$
+
+Where:
+- `fuel_volume_rate` is in m³/s
+- `fuel_density` is in kg/m³ (default 0.768 kg/m³ for natural gas [6])
+- Result is fuel mass rate in kg/s
+
+## YAML Configuration
+
+### Minimal Configuration
+
+Required parameters only (uses defaults for `hhv`, `efficiency_table`, and other parameters):
+
+```yaml
+combined_cycle_gas_turbine:
+  component_type: CombinedCycleGasTurbine
+  rated_capacity: 100000  # kW (100 MW)
+  initial_conditions:
+    power: 0  # 0 kW means OFF; power > 0 means ON
+```
+
+### Full Configuration
+
+All parameters explicitly specified:
+
+```yaml
+combined_cycle_gas_turbine:
+  component_type: CombinedCycleGasTurbine
+  rated_capacity: 100000  # kW (100 MW)
+  min_stable_load_fraction: 0.4  # 40% minimum operating point
+  ramp_rate_fraction: 0.03  # 3%/min ramp rate
+  run_up_rate_fraction: 0.02 # 2%/min run up rate
+  hot_startup_time: 4500.0  # 75 minutes
+  warm_startup_time: 7200.0  # 120 minutes
+  cold_startup_time: 10800.0  # 180 minutes
+  min_up_time: 14400  # 4 hours
+  min_down_time: 7200  # 2 hours
+  # Natural gas properties from [6] Staffell, "The Energy and Fuel Data Sheet", 2011
+  # HHV: 39.05 MJ/m³, Density: 0.768 kg/m³
+  hhv: 39050000  # J/m³ for natural gas (39.05 MJ/m³) [6]
+  fuel_density: 0.768  # kg/m³ for natural gas [6]
+  efficiency_table:
+    power_fraction:
+      - 1.0
+      - 0.95
+      - 0.90
+      - 0.85
+      - 0.80
+      - 0.75
+      - 0.7
+      - 0.65
+      - 0.6
+      - 0.55
+      - 0.50
+      - 0.4
+    efficiency:  # HHV net plant efficiency, fractions (0-1), from CC1A-F curve in Exhibit ES-4 of [5]
+      - 0.53
+      - 0.515
+      - 0.52
+      - 0.52
+      - 0.52
+      - 0.52
+      - 0.52
+      - 0.515
+      - 0.505
+      - 0.5
+      - 0.49
+      - 0.47
+  log_channels:
+    - power
+    - fuel_volume_rate
+    - fuel_mass_rate
+    - state
+    - efficiency
+    - power_setpoint
+  initial_conditions:
+    power: 100000  # 0 kW means OFF; power > 0 means ON
+
+```
+
+## Logging Configuration
+
+The `log_channels` parameter controls which outputs are written to the HDF5 output file.
+
+**Available Channels:**
+- `power`: Actual power output in kW (always logged)
+- `state`: Operating state number (0-5), corresponding to the `STATES` enum
+- `fuel_volume_rate`: Fuel volume flow rate in m³/s
+- `fuel_mass_rate`: Fuel mass flow rate in kg/s (computed using `fuel_density` [6])
+- `efficiency`: Current HHV net plant efficiency (0-1)
+- `power_setpoint`: Requested power setpoint in kW
+
+## References
+
+1. Agora Energiewende (2017): "Flexibility in thermal power plants - With a focus on existing coal-fired power plants."
+
+2. "Impact of Detailed Parameter Modeling of Open-Cycle Gas Turbines on Production Cost Simulation", NREL/CP-6A40-87554, National Renewable Energy Laboratory, 2024.
+
+3. Deane, J.P., G. Drayton, and B.P. Ó Gallachóir. "The Impact of Sub-Hourly Modelling in Power Systems with Significant Levels of Renewable Generation." Applied Energy 113 (January 2014): 152–58. https://doi.org/10.1016/j.apenergy.2013.07.027.
+
+4. IRENA (2019), Innovation landscape brief: Flexibility in conventional power plants, International Renewable Energy Agency, Abu Dhabi.
+
+5. M. Oakes, M. Turner, "Cost and Performance Baseline for Fossil Energy Plants, Volume 5: Natural Gas Electricity Generating Units for Flexible Operation," National Energy Technology Laboratory, Pittsburgh, May 5, 2023.
+
+6. I. Staffell, "The Energy and Fuel Data Sheet," University of Birmingham, March 2011. https://claverton-energy.com/cms4/wp-content/uploads/2012/08/the_energy_and_fuel_data_sheet.pdf

docs/examples/07_open_cycle_gas_turbine.md

@@ -14,7 +14,9 @@ The simulation runs for 6 hours with 1-minute time steps. A controller commands
 
 | Time (min) | Event Type | Setpoint | State | Description |
 |------------|------------|----------|-------|-------------|
-| 0 | Initial | 0 | OFF (0) | Turbine starts off, `time_in_state` begins counting |
+| 0 | Initial | 100 MW | ON (4) | Turbine starts at rated power |
+| 10 | Command + State | → 0 | → STOPPING (5) | Shutdown command; `min_up_time` satisfied (initialized to be dispatchable), begins stopping sequence |
+| ~20 | State | 0 | → OFF (0) | Power reaches 0 (ramped down at 10 MW/min), turbine off |
 | 40 | Command | → 100 MW | OFF (0) | Setpoint changes to full power, but `min_down_time` (60 min) not yet satisfied—turbine remains off |
 | 60 | State | 100 MW | → HOT STARTING (1) | `min_down_time` satisfied, turbine begins hot starting sequence |
 | ~64 | State | 100 MW | HOT STARTING (1) | `hot_readying_time` (~4.2 min) complete, run-up ramp begins |

docs/examples/08_combined_cycle_gas_turbine.md

@@ -0,0 +1,68 @@
+# Example 08: Combined Cycle Gas Turbine (CCGT)
+
+## Description
+
+This example demonstrates a standalone combined-cycle gas turbine (CCGT) simulation. The example showcases the turbine's state machine behavior including startup sequences, power ramping, minimum stable load constraints, and shutdown sequences.
+
+For details on CCGT parameters and configuration, see {doc}`../combined_cycle_gas_turbine`. For details on the underlying state machine and ramp behavior, see {doc}`../thermal_component_base`.
+
+## Scenario
+
+The simulation runs for 10 hours with 1-minute time steps. A controller commands the turbine through several operating phases. The table below shows both **control commands** (setpoint changes) and **state transitions** (responses to commands based on constraints).
+
+### Timeline
+
+| Time (min) | Event Type | Setpoint | State | Description |
+|------------|------------|----------|-------|-------------|
+| 0 | Initial | 100 MW | ON (4) | Turbine starts on at rated power, `time_in_state` begins counting |
+| 10 | Command + State | → 0 | → STOPPING (5) | Shutdown command; `min_up_time` satisfied (initialized to be dispatchable), begins stopping sequence |
+| ~45 | State | 0 | → OFF (0) | Power reaches 0 (ramped down at 3 MW/min), turbine off |
+| 60 | Command | → 100 MW | OFF (0) | Setpoint changes to full power, but `min_down_time` (120 min) not yet satisfied—turbine remains off |
+| ~160 | State | 100 MW | → HOT STARTING (1) | `min_down_time` satisfied, turbine begins hot starting sequence |
+| ~225 | State | 100 MW | HOT STARTING (1) | `hot_readying_time` (~65 min) complete, run-up ramp begins |
+| ~235 | State | 100 MW | → ON (4) | Power reaches P_min (40 MW) after `hot_startup_time` (~75 min), turbine now operational |
+| ~260 | Ramp | 100 MW | ON (4) | Power reaches 100 MW (ramped at 3 MW/min from P_min) |
+| 260 | Command | → 50 MW | ON (4) | Setpoint reduced to 50% capacity |
+| ~276 | Ramp | 50 MW | ON (4) | Power reaches 50 MW (ramped down at 3 MW/min) |
+| 360 | Command | → 10 MW | ON (4) | Setpoint reduced to 10% (below P_min), power clamped to P_min (40 MW) |
+| ~365 | Ramp | 10 MW | ON (4) | Power reaches P_min (40 MW), cannot go lower |
+| 480 | Command | → 100 MW | ON (4) | Setpoint increased to full power |
+| ~500 | Ramp | 100 MW | ON (4) | Power reaches 100 MW |
+| 540 | Command + State | → 0 | → STOPPING (5) | Shutdown command; `min_up_time` satisfied (~305 min on), begins stopping sequence |
+| ~570 | State | 0 | → OFF (0) | Power reaches 0 (ramped down at 3 MW/min), turbine off |
+| 600 | End | 0 | OFF (0) | Simulation ends |
+
+### Key Behaviors Demonstrated
+
+- **Minimum down time**: The turbine cannot start until `min_down_time` (120 min) is satisfied, even though the command is issued at 60 min
+- **Hot startup sequence**: After `min_down_time`, the turbine enters HOT STARTING, waits through `hot_readying_time`, then ramps to P_min using `run_up_rate`
+- **Ramp rate constraints**: All power changes in ON state are limited by `ramp_rate` (3 MW/min)
+- **Minimum stable load**: When commanded to 10 MW (below P_min = 40 MW), power is clamped to P_min
+- **Minimum up time**: Shutdown is allowed immediately at 570 min because `min_up_time` (240 min) was satisfied long ago
+- **Stopping sequence**: The turbine ramps down to zero at `ramp_rate` before transitioning to OFF
+
+## Setup
+
+No manual setup is required. The example uses only the CCGT component which requires no external data files.
+
+## Running
+
+To run the example, execute the following command in the terminal:
+
+```bash
+python hercules_runscript.py
+```
+
+## Outputs
+
+To plot the outputs, run:
+
+```bash
+python plot_outputs.py
+```
+
+The plot shows:
+- Power output over time (demonstrating ramp constraints and minimum stable load)
+- Operating state transitions
+- Fuel consumption tracking
+- Heat rate variation with load

examples/07_open_cycle_gas_turbine/hercules_input_ccgt.yaml

@@ -0,0 +1,72 @@
+# Input YAML for hercules
+# Explicitly specify the parameters for demonstration purposes
+
+# Name
+name: example_08
+
+###
+# Describe this simulation setup
+description: Combined Cycle Gas Turbine (OCGT) Example
+
+dt: 60.0  # 1 minute time step
+starttime_utc: "2020-01-01T00:00:00Z"  # Midnight Jan 1, 2020 UTC
+endtime_utc: "2020-01-01T10:00:00Z"  # 12 hours later
+verbose: False
+log_every_n: 1
+output_file: "outputs/hercules_output_ccgt"
+
+plant:
+  interconnect_limit: 100000  # kW (100 MW)
+
+combined_cycle_gas_turbine:
+  component_type: CombinedCycleGasTurbine
+  rated_capacity: 100000  # kW (100 MW)
+  min_stable_load_fraction: 0.4  # 40% minimum operating point
+  ramp_rate_fraction: 0.03  # 3%/min ramp rate
+  hot_startup_time: 4500.0  # 75 minutes
+  warm_startup_time: 7200.0  # 120 minutes
+  cold_startup_time: 10800.0  # 180 minutes
+  min_up_time: 14400  # 4 hours
+  min_down_time: 7200  # 2 hours
+  # Natural gas properties from [6] Staffell, "The Energy and Fuel Data Sheet", 2011
+  # HHV: 39.05 MJ/m³, Density: 0.768 kg/m³
+  hhv: 39050000  # J/m³ for natural gas (39.05 MJ/m³) [6]
+  fuel_density: 0.768  # kg/m³ for natural gas [6]
+  efficiency_table:
+    power_fraction:
+      - 1.0
+      - 0.95
+      - 0.90
+      - 0.85
+      - 0.80
+      - 0.75
+      - 0.7
+      - 0.65
+      - 0.6
+      - 0.55
+      - 0.50
+      - 0.4
+    efficiency:  # HHV net plant efficiency, fractions (0-1), from CC1A-F curve in Exhibit ES-4 of [5]
+      - 0.53
+      - 0.515
+      - 0.52
+      - 0.52
+      - 0.52
+      - 0.52
+      - 0.52
+      - 0.515
+      - 0.505
+      - 0.5
+      - 0.49
+      - 0.47
+  log_channels:
+    - power
+    - fuel_volume_rate
+    - fuel_mass_rate
+    - state
+    - efficiency
+    - power_setpoint
+  initial_conditions:
+    power: 100000  # Start ON at rated capacity (100 MW)
+
+controller:

examples/07_open_cycle_gas_turbine/hercules_input.yaml → examples/07_open_cycle_gas_turbine/hercules_input_ocgt.yaml

@@ -10,9 +10,10 @@ description: Open Cycle Gas Turbine (OCGT) Example
 
 dt: 60.0  # 1 minute time step
 starttime_utc: "2020-01-01T00:00:00Z"  # Midnight Jan 1, 2020 UTC
-endtime_utc: "2020-01-01T06:00:00Z"  # 6 hours later
+endtime_utc: "2020-01-01T10:00:00Z"  # 6 hours later
 verbose: False
 log_every_n: 1
+output_file: "outputs/hercules_output_ocgt"
 
 plant:
   interconnect_limit: 100000  # kW (100 MW)
@@ -54,4 +55,3 @@ open_cycle_gas_turbine:
     power: 100000  # Start ON at rated capacity (100 MW)
 
 controller:
-