Feature/add ct by paulf81 · Pull Request #189 · NatLabRockies/hercules

paulf81 · 2025-12-18T17:16:04Z

This PR adds a base class for thermal components, including both gas and coal plants. The modeling is based largely on 3 papers:

[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.

In this PR, in addition to the base class: ThermalComponentBase a first subclass is added: OpenCycleGasTurbine, implementing an open-cycle (CT, peaker) NG component. The PR includes an example demonstrating OpenCycleGasTurbine, docs for the new code and tests for both.

Still todo:

@genevievestarke could you review this model and compare with what is in HOPP/H2I?
also @genevievestarke or @misi9170 , I'd like second pair of eyes on the heat-rate and fuel consumption code. Could you review those parts and also maybe add a small first principles test to tests/open_cycle_gas_turbine_test.py (note there is TODO comment at the relavent location in the file)

Copilot

Pull request overview

This PR introduces a new natural gas combustion turbine model (CombustionTurbineSimple) to Hercules with basic state management, ramp rate constraints, minimum stable load enforcement, and fuel consumption tracking. The implementation includes integration with the plant component system, a basic test, and a comprehensive example demonstrating turbine operation through various power setpoints and state transitions.

Key Changes:

Adds CombustionTurbineSimple component with 4-state machine (off, starting, on, stopping) and configurable operational constraints
Integrates combustion turbine as a generator component in the utilities and hybrid plant infrastructure
Provides Example 07 demonstrating a 6-hour simulation with complex control schedule

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
`hercules/plant_components/combustion_turbine_simple.py`	New combustion turbine model with state machine, ramp constraints, fuel consumption, and part-load efficiency calculations
`hercules/hybrid_plant.py`	Adds component instantiation logic for CombustionTurbineSimple
`hercules/utilities.py`	Registers combustion_turbine as available component and generator type
`tests/combustion_turbine_simple_test.py`	Basic initialization test (requires missing test fixture to run)
`examples/07_ngct/hercules_input.yaml`	Configuration for 100 MW turbine with 20% minimum load
`examples/07_ngct/hercules_runscript.py`	Controller implementing multi-stage power schedule
`examples/07_ngct/plot_outputs.py`	Visualization script for power, state, and fuel consumption
`examples/07_ngct/README.md`	Documentation of example configuration and control schedule

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

hercules/plant_components/combustion_turbine_simple.py

Copilot · 2025-12-18T17:22:37Z

hercules/plant_components/combustion_turbine_simple.py

+            dict: Updated h_dict with combustion turbine outputs:
+                - power: Actual power output [kW]
+                - state_num: Operating state number (0=off, 1=starting, 2=on, 3=stopping)
+                - state_name: Operating state string ("off", "starting", "on", "stopping")


The step method documentation lists 'state_name' as an output (line 189), but the actual code has this output commented out (line 208). This creates a discrepancy between documentation and implementation. Either uncomment the output if it should be included, or remove it from the documentation if it's intentionally excluded.

Suggested change

- state_name: Operating state string ("off", "starting", "on", "stopping")

This output was removed because it created problems to have a string in the h_dict output, (and anyway the info is in statenum). Removing from docstring

tests/combustion_turbine_simple_test.py

Copilot · 2025-12-18T17:22:37Z

hercules/plant_components/combustion_turbine_simple.py

+
+        # Check that initial conditions are valid
+        if self.power_output < 0 or self.power_output > self.rated_capacity:
+            raise ValueError("power_output must be between 0 and rated_capacity (inclusive)")


The error message references 'power_output' but this is not a user-provided parameter - it comes from initial_conditions["power"]. The error message should reference 'initial power' or 'initial_conditions.power' to help users identify which configuration value is invalid.

Suggested change

raise ValueError("power_output must be between 0 and rated_capacity (inclusive)")

raise ValueError(

"initial_conditions['power'] (initial power) must be between 0 and rated_capacity (inclusive)"

)

hercules/plant_components/combustion_turbine_simple.py

Copilot · 2025-12-18T17:22:38Z

examples/07_ngct/hercules_runscript.py

+    """Simple controller for combustion turbine on/off scheduling.
+
+    This controller turns the combustion turbine on at 60 minutes,
+    runs at full power for 3 hours, then shuts down at 240 minutes.


The class docstring description is inconsistent with the actual controller behavior. The docstring says "runs at full power for 3 hours" but the implementation has a more complex schedule with multiple power level changes (100% → 50% → 10% → 100% → off) as documented in lines 5-9 of the module docstring. Consider updating the class docstring to accurately reflect the control logic or simply reference the module docstring.

Suggested change

"""Simple controller for combustion turbine on/off scheduling.

This controller turns the combustion turbine on at 60 minutes,

runs at full power for 3 hours, then shuts down at 240 minutes.

"""Controller implementing the NGCT schedule described in the module docstring.

The turbine starts off, then:

- At 60 minutes, it is commanded to 100% of rated capacity.

- At 120 minutes, it is reduced to 50% of rated capacity.

- At 180 minutes, it is reduced to 10% of rated capacity.

- At 210 minutes, it is increased back to 100% of rated capacity.

- At 240 minutes, it is commanded off.

tests/combustion_turbine_simple_test.py

Copilot · 2025-12-18T17:22:39Z

hercules/plant_components/combustion_turbine_simple.py

+        if self.state_num not in self.STATE_NAMES:
+            raise ValueError(
+                "state_num must be one of the following: " + str(self.STATE_NAMES.values())
+            )


The state_num validation is redundant. Lines 116-117 already check if state_num is between 0 and 3 (inclusive), which is identical to checking if it's in STATE_NAMES (which contains keys 0, 1, 2, 3). The check on line 118 will always pass if line 116 passes. Consider removing lines 118-121 to eliminate redundancy.

Suggested change

if self.state_num not in self.STATE_NAMES:

raise ValueError(

"state_num must be one of the following: " + str(self.STATE_NAMES.values())

)

paulf81 · 2025-12-22T19:31:35Z

@misi9170 and @genevievestarke , update today is I merged back in develop to this PR and then went through the review comments from co-pilot (most of which were helpful!)

paulf81 · 2026-01-30T21:26:33Z

hercules/plant_components/combustion_turbine_simple.py

+            float: Fuel consumed this timestep in kJ.
+        """
+
+        # TODO: Is this correct?  Should we be getting to m^3 of natural gas?


@genevievestarke check this one?

paulf81 · 2026-02-02T16:51:50Z

ok @genevievestarke and @misi9170 , I now wrote a set of tests and updated the docs so this one should be ready for review.

paulf81 · 2026-02-04T18:11:18Z

ok @genevievestarke and @misi9170 , this PR is now fully reworked following our discussion. It most closely follows the model descriptions in:

[1] Agora Energiewende (2017): Flexibility in thermal power plants
With a focus on existing coal-fired power plants.

I redid the top comment box on this PR and added 2 todo items if you don't mind to have a look, or can just talk with me about it.

@brookeslawski I added you as a reviewer in case you have a few minutes would value your feedback, but understand if you don't!

Copilot

Pull request overview

Copilot reviewed 14 out of 15 changed files in this pull request and generated 12 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

hercules/hybrid_plant.py

Copilot · 2026-02-04T18:21:34Z

hercules/plant_components/thermal_component_base.py

+            # Ramp up using run_up_rate
+            startup_power = (self.time_in_state - self.hot_readying_time) * self.run_up_rate
+
+            # Check if ramping is complete
+            if startup_power >= self.P_min:
+                self.state_num = self.STATE_ON
+                self.time_in_state = 0.0
+                return startup_power
+
+            return startup_power


When startup ramping reaches/exceeds P_min, _control transitions to STATE_ON but returns startup_power without any cap. With larger dt or high run_up_rate, this can exceed rated_capacity and propagate unrealistic power (and downstream fuel burn). Clamp the returned power at least to [0, P_max] (and typically return exactly P_min on the transition).

Copilot · 2026-02-04T18:21:35Z

hercules/plant_components/open_cycle_gas_turbine.py

+        # Store the type of this component
+        self.component_type = "OpenCycleGasTurbine"
+
+        # Apply fixeddefault parameters based on [1], [2] and [3]


Typo in comment: “fixeddefault” should be “fixed default”.

Suggested change

# Apply fixeddefault parameters based on [1], [2] and [3]

# Apply fixed default parameters based on [1], [2] and [3]

Copilot · 2026-02-04T18:21:35Z

tests/thermal_component_base_test.py

+    # Test cold_startup_time must be a number greater than the ramp_time
+    # determined by the ramp_rate_fraction


This comment says the cold startup constraint is “determined by the ramp_rate_fraction”, but the implementation enforces cold_startup_time >= hot_startup_time (and ramp time is based on run_up_rate_fraction). Consider updating the comment to reflect the actual validation being exercised.

Suggested change

# Test cold_startup_time must be a number greater than the ramp_time

# determined by the ramp_rate_fraction

# Test cold_startup_time must be a number greater than or equal to the

# hot_startup_time (which in this setup equals the ramp_time determined

# by the run_up_rate_fraction)

examples/07_ocgt/hercules_runscript.py

Copilot · 2026-02-04T18:21:36Z

hercules/plant_components/thermal_component_base.py

+                # Transition to shutdown sequence
+                self.state_num = self.STATE_STOPPING
+                self.time_in_state = 0.0
+


In the STATE_ON branch, you set state_num = STATE_STOPPING but still return _apply_on_constraints(...) (ON-state logic). This means the first timestep of STOPPING still enforces P_min/ON constraints, which can delay or distort shutdown behavior (especially for large dt). After transitioning to STATE_STOPPING, return stopping-state ramp-down power instead (or early-return and let the STOPPING branch handle output).

Suggested change

# Immediately apply stopping-state ramp-down behavior

shutdown_power = self.power_output - self.ramp_rate * self.dt

# Check if shutdown is complete in this timestep

if shutdown_power <= 0:

self.state_num = self.STATE_OFF

self.time_in_state = 0.0

return 0.0

return shutdown_power

Copilot · 2026-02-04T18:21:37Z

tests/open_cycle_gas_turbine_test.py

+
+
+def test_init_from_dict():
+    """Test that ThermalComponentBase can be initialized from a dictionary."""


Test docstring references ThermalComponentBase, but this test initializes OpenCycleGasTurbine. Update the docstring to match what’s being tested.

Suggested change

"""Test that ThermalComponentBase can be initialized from a dictionary."""

"""Test that OpenCycleGasTurbine can be initialized from a dictionary."""

Copilot · 2026-02-04T18:21:37Z

tests/open_cycle_gas_turbine_test.py

+# TODO: Someone familiar with heat rate and fuel consumption please add tests based
+# on first principles for the heat rate and fuel consumption.
+def test_post_process():
+    """Test that OpenCycleGasTurbine post-processes correctly."""
+    h_dict = copy.deepcopy(h_dict_open_cycle_gas_turbine)
+    ocgt = OpenCycleGasTurbine(h_dict)
+    h_dict = ocgt._post_process(h_dict)


test_post_process doesn’t assert anything about the post-processed outputs, so it will pass even if _post_process is broken. Add assertions that fuel_consumption and heat_rate keys are written to h_dict and that values match expected first-principles calculations for a known power_output/dt (including an off/zero-power case).

Copilot · 2026-02-04T18:21:37Z

examples/07_ocgt/plot_outputs.py

@@ -0,0 +1,84 @@
+# Plot the outputs of the simulation for the NGCT example


Header comment references an “NGCT example”, but this example is for an open-cycle gas turbine (OCGT). Consider renaming references (and possibly ControllerNGCT) to avoid confusion.

Suggested change

# Plot the outputs of the simulation for the NGCT example

# Plot the outputs of the simulation for the open-cycle gas turbine (OCGT) example

Copilot · 2026-02-04T18:21:38Z

tests/thermal_component_base_test.py

+    h_dict = copy.deepcopy(h_dict_thermal_component)
+


This assignment to 'h_dict' is unnecessary as it is redefined before this value is used.

Suggested change

h_dict = copy.deepcopy(h_dict_thermal_component)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

paulf81 added 5 commits December 17, 2025 16:08

Add combustion turbine model

3ccb8e3

add to hybrid plant

b7b4696

add to utilities

0f65a52

add first test

b9e8200

add new example

9eb9535

paulf81 requested review from Copilot, genevievestarke and misi9170 December 18, 2025 17:16

paulf81 self-assigned this Dec 18, 2025

Copilot started reviewing on behalf of paulf81 December 18, 2025 17:16 View session

Copilot AI reviewed Dec 18, 2025

View reviewed changes

paulf81 added 9 commits December 19, 2025 12:39

add test dicts

36d5493

Merge branch 'develop' into feature/add_ct

7cf9dca

address comment

24896c6

standardize to min_stable_load_fraction

1e386a1

address comment

cc58bd0

clean up state_num error checks

dca6e13

clean up step function

ce8d2c7

add else case

494538d

linting

1bc2961

paulf81 added 4 commits December 22, 2025 12:40

fix long line

d75f6e0

fix long line

eccc7a7

fix comment

48594a7

adjust timing

8befd4d

paulf81 commented Jan 30, 2026

View reviewed changes

paulf81 added 3 commits January 30, 2026 15:05

Add tests for Ct

feaad7b

add combustion turbine docs

6537bb5

Add 07 example

5234a6d

paulf81 marked this pull request as ready for review February 2, 2026 16:49

Merge branch 'develop' into feature/add_ct

eb56021

paulf81 added 16 commits February 4, 2026 09:30

remove combustion turbine model

747a05d

add thermal component base

20e7b77

add tests

0f3870e

update h_dict

c08227f

linting

bee19b2

add ocgt

6367251

route ocgt

c3e2495

rename example

c7d139c

linting

cf13402

update example 7

e8b778b

update utilities

bd367c6

bugfix

5d20da4

add shell post-process test

0507d5d

update docs

313a95f

Merge branch 'develop' into pr/paulf81/189

05cbc68

Add 07 doc

69b426a

paulf81 requested review from brookeslawski and Copilot February 4, 2026 18:09

Copilot started reviewing on behalf of paulf81 February 4, 2026 18:09 View session

Copilot AI reviewed Feb 4, 2026

View reviewed changes

paulf81 and others added 6 commits February 4, 2026 11:52

Update hercules/hybrid_plant.py

d5b2880

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Merge branch 'develop' into pr/paulf81/189

f5551fe

harmonize comments

8ab6150

clarify comment

5cca1bf

Fix comment

84e1251

add warm start state and hard code start state time definitions

055da8d

-    """Simple controller for combustion turbine on/off scheduling.
-    This controller turns the combustion turbine on at 60 minutes,
-    runs at full power for 3 hours, then shuts down at 240 minutes.
+    """Controller implementing the NGCT schedule described in the module docstring.
+    The turbine starts off, then:
+    - At 60 minutes, it is commanded to 100% of rated capacity.
+    - At 120 minutes, it is reduced to 50% of rated capacity.
+    - At 180 minutes, it is reduced to 10% of rated capacity.
+    - At 210 minutes, it is increased back to 100% of rated capacity.
+    - At 240 minutes, it is commanded off.

	# Apply fixeddefault parameters based on [1], [2] and [3]
	# Apply fixed default parameters based on [1], [2] and [3]

		# Test cold_startup_time must be a number greater than the ramp_time
		# determined by the ramp_rate_fraction

-    # Test cold_startup_time must be a number greater than the ramp_time
-    # determined by the ramp_rate_fraction
+    # Test cold_startup_time must be a number greater than or equal to the
+    # hot_startup_time (which in this setup equals the ramp_time determined
+    # by the run_up_rate_fraction)

+                # Immediately apply stopping-state ramp-down behavior
+                shutdown_power = self.power_output - self.ramp_rate * self.dt
+                # Check if shutdown is complete in this timestep
+                if shutdown_power <= 0:
+                    self.state_num = self.STATE_OFF
+                    self.time_in_state = 0.0
+                    return 0.0
+                return shutdown_power



		def test_init_from_dict():
		"""Test that ThermalComponentBase can be initialized from a dictionary."""

	"""Test that ThermalComponentBase can be initialized from a dictionary."""
	"""Test that OpenCycleGasTurbine can be initialized from a dictionary."""

		@@ -0,0 +1,84 @@
		# Plot the outputs of the simulation for the NGCT example

Conversation

paulf81 commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

paulf81 Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

paulf81 Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

paulf81 Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

paulf81 Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

paulf81 commented Dec 22, 2025

Uh oh!

paulf81 Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

paulf81 commented Feb 2, 2026

Uh oh!

paulf81 commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

paulf81 Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 4, 2026

paulf81 commented Dec 18, 2025 •

edited

Loading

paulf81 commented Feb 4, 2026 •

edited

Loading