NatLabRockies · dzalkind · Mar 4, 2026 · Mar 4, 2026 · Mar 4, 2026 · Mar 4, 2026
diff --git a/docs/_toc.yml b/docs/_toc.yml
@@ -33,6 +33,7 @@ parts:
     - file: open_cycle_gas_turbine
     - file: hard_coal_steam_turbine
     - file: thermal_plant
+    - file: linear_generator
   - caption: Inputs
     chapters:
     - file: hercules_input
@@ -53,3 +54,4 @@ parts:
     - file: examples/06_wind_and_hydrogen
     - file: examples/07_open_cycle_gas_turbine
     - file: examples/09_multiunit_thermal_plant
+    - file: examples/10_linear_generator
diff --git a/docs/component_types.md b/docs/component_types.md
@@ -55,6 +55,7 @@ Every `ComponentBase` subclass **must** define `component_category`; a `TypeErro
 | `BatteryLithiumIon` | `storage` | [Battery](battery.md) |
 | `ElectrolyzerPlant` | `load` | [Electrolyzer](electrolyzer.md) |
 | `OpenCycleGasTurbine` | `generator` | [Open Cycle Gas Turbine](open_cycle_gas_turbine.md) |
+| `LinearGenerator` | `generator` | [Linear Generator](linear_generator.md) |
 | `HardCoalSteamTurbine` | `generator` | [Hard Coal Steam Turbine](hard_coal_steam_turbine.md) |
 | `ThermalPlant` | `generator` | [Thermal Plant](thermal_plant.md) |
 

diff --git a/docs/examples/10_linear_generator.md b/docs/examples/10_linear_generator.md
@@ -0,0 +1,66 @@
+# Example 10: Linear Generator
+
+## Description
+
+This example demonstrates a standalone Mainspring linear generator simulation. It highlights three key characteristics that distinguish the linear generator from other thermal components:
+
+1. **Fast ramp rate** (120%/min) — power changes are effectively instantaneous at 1-minute time steps
+2. **No minimum stable load** — the generator can operate at any fraction of rated capacity, including very low loads, without shutting down
+3. **Flat efficiency** — HHV net efficiency is constant at 41.44% regardless of load level
+
+For details on linear generator parameters and configuration, see {doc}`../linear_generator`. For details on the underlying state machine and ramp behavior, see {doc}`../thermal_component_base`.
+
+## Scenario
+
+The simulation runs for 4 hours with 1-minute time steps on a 250 kW unit.
+
+### Timeline
+
+| Time (min) | Event Type | Setpoint | State | Description |
+|------------|------------|----------|-------|-------------|
+| 0 | Initial | 250 kW | ON (4) | Generator starts on at rated capacity; `time_in_state` pre-set to `min_up_time` |
+| 10 | Command | → 0 | → STOPPING (5) | Shutdown command; `min_up_time` pre-satisfied, stopping begins immediately |
+| ~10 | State | 0 | → OFF_HOT (0) | Power reaches 0 within one time step (ramp rate of 120%/min exceeds rated capacity), `min_down_time` begins counting |
+| ~15 | State | 0 | OFF_HOT (0) | `min_down_time` (5 min) satisfied |
+| 20 | Command | → 250 kW | → HOT STARTING (1) | ON command issued; `min_down_time` already satisfied, hot start begins immediately |
+| ~21–22 | State | — | HOT STARTING (1) | Hot start in progress; `hot_startup_time` is 90 s, which spans 2 time steps at dt=60 s |
+| ~22 | State | 250 kW | → ON (4) | `hot_startup_time` complete; power ramps to 250 kW (ramp rate of 120%/min exceeds rated capacity, so full power is reached within one time step) |
+| 90 | Command | → 125 kW | ON (4) | Setpoint reduced to 50%; power reaches 125 kW within one time step |
+| 120 | Command | → 50 kW | ON (4) | Setpoint reduced to 20%; power reaches 50 kW — note no minimum stable load constraint |
+| 180 | Command | → 0 | → STOPPING (5) | Shutdown command; `min_up_time` satisfied (~153 min on), stopping begins |
+| ~180 | State | 0 | → OFF_HOT (0) | Power reaches 0 within one time step |
+| 240 | End | 0 | OFF_HOT (0) | Simulation ends |
+
+### Key Behaviors Demonstrated
+
+- **Fast ramp**: Load changes while ON complete within a single 1-minute time step — the ramp rate (120%/min) exceeds rated capacity, so any setpoint change is met immediately
+- **Hot startup duration**: `hot_startup_time` is 90 s, which spans 2 timesteps at dt=60 s; power is not available until the startup sequence completes
+- **No minimum stable load**: The generator operates at 20% (50 kW) without clamping or shutdown, unlike a gas turbine which typically has a 30–40% minimum
+- **Flat efficiency**: Efficiency remains 41.44% at 100%, 50%, and 20% load — fuel consumption scales linearly with power output
+- **Minimum down time**: After shutdown at t=10 min, `min_down_time` (5 min) is satisfied by t=15 min, so the ON command at t=20 min starts the hot start sequence immediately
+
+## Setup
+
+No manual setup is required. The example uses only the `LinearGenerator` 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 and setpoint over time (demonstrating fast ramp and no minimum stable load)
+- Operating state transitions
+- Thermal efficiency over time (flat at 41.44% across all load levels)
+- Fuel volume rate over time
diff --git a/docs/hard_coal_steam_turbine.md b/docs/hard_coal_steam_turbine.md
@@ -31,6 +31,8 @@ The `HardCoalSteamTurbine` class provides default values for base class paramete
 | `cold_startup_time` | 7.5 hours | [1] |
 | `min_up_time` | 48 hours | [2] |
 | `min_down_time` | 48 hours | [2] |
+| `hot_to_warm_time` | 28800 s (8 hours) | [5] |
+| `hot_to_cold_time` | 172800 s (48 hours) | [5] |
 | `efficiency_table` | Average plant efficiency | [2,3] |
 
 ### Default Efficiency Table
@@ -50,7 +52,7 @@ The HCST 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 |
+| `state` | integer | Operating state number (0-7), 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` |
@@ -110,6 +112,8 @@ hard_coal_steam_turbine:
   cold_startup_time: 27000.0  # 7.5 hours
   min_up_time: 172800  # 48 hours
   min_down_time: 172800  # 48 hour
+  hot_to_warm_time: 28800.0  # 8 hours
+  hot_to_cold_time: 172800.0  # 48 hours
   hhv: 29310000000  # J/m³ for bituminous coal (29.31 MJ/m³) [4]
   fuel_density: 1000  # kg/m³ for bituminous coal
   efficiency_table:
@@ -138,7 +142,7 @@ The `log_channels` parameter controls which outputs are written to the HDF5 outp
 
 **Available Channels:**
 - `power`: Actual power output in kW (always logged)
-- `state`: Operating state number (0-5), corresponding to the `STATES` enum
+- `state`: Operating state number (0-7), 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
 - `efficiency`: Current HHV net plant efficiency (0-1)

diff --git a/docs/hybrid_plant.md b/docs/hybrid_plant.md
@@ -19,6 +19,7 @@ See [Component Names, Types, and Categories](component_types.md) for a full expl
 | `BatteryLithiumIon` | `storage` | No | [Battery](battery.md) |
 | `ElectrolyzerPlant` | `load` | No | [Electrolyzer](electrolyzer.md) |
 | `OpenCycleGasTurbine` | `generator` | Yes | [Open Cycle Gas Turbine](open_cycle_gas_turbine.md) |
+| `LinearGenerator` | `generator` | Yes | [Linear Generator](linear_generator.md) |
 | `HardCoalSteamTurbine` | `generator` | [Hard Coal Steam Turbine](hard_coal_steam_turbine.md) |
 | `ThermalPlant` | `generator` | [Thermal Plant](thermal_plant.md) |
 

diff --git a/docs/linear_generator.md b/docs/linear_generator.md
@@ -0,0 +1,212 @@
+# Linear Generator
+
+The `LinearGenerator` class models a Mainspring linear generator — a free-piston linear engine that burns fuel to produce electricity directly, without a rotating shaft. 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.
+
+Set `component_type: LinearGenerator` in the component's YAML section. The section key is a user-chosen `component_name` (e.g. `linear_generator`); see [Component Names, Types, and Categories](component_types.md) for details.
+
+For details on the state machine, startup/shutdown behavior, and base parameters, see {doc}`thermal_component_base`.
+
+
+## Default Linear Generator-Specific Parameter Values
+
+The `LinearGenerator` class provides default values for all base class parameters. Only `rated_capacity` and `initial_conditions` are required in the YAML configuration. All defaults are defined in the class-level `DEFAULTS` dict.
+
+| Parameter | Default Value | Source | Notes |
+|-----------|---------------|--------|------|
+| `min_stable_load_fraction` | 0.0 (0%) | — | Minimum stable load fraction of the generator |
+| `ramp_rate_fraction` | 1.2 (120%/min) | [2] | Ramp rate fraction of the generator |
+| `run_up_rate_fraction` | Same as `ramp_rate_fraction` | — | Run-up rate fraction of the generator |
+| `hot_startup_time` | 90 s (1.5 minutes) | — | Time required for a hot start |
+| `warm_startup_time` | 450 s (7.5 minutes) | — | Time required for a warm start |
+| `cold_startup_time` | 900 s (15 minutes) | — | Time required for a cold start |
+| `min_up_time` | 300 s (5 minutes) | — | Note below |
+| `min_down_time` | 300 s (5 minutes) | — | Minimum down time of the generator |
+| `hot_to_warm_time` | 2700 s (45 minutes) | — | Assumptions documented below |
+| `hot_to_cold_time` | 10800 s (3 hours) | — | Assumptions documented below |
+| `hhv` | 39050000 J/m³ (39.05 MJ/m³) | [3] | Higher heating value of the fuel |
+| `fuel_density` | 0.768 kg/m³ | [3] | Density of the fuel |
+| `efficiency_table` | 41.44% HHV peak, with roll-off at extremes (see below) | [1] | Efficiency of the generator, converted from LHV |
+
+Notes:
+- `min_up_time` is often determined by thermal and mechanical stress management considerations, as the generator may need to remain on for a minimum duration to avoid excessive wear from frequent cycling.
+- `hot_to_warm_time` and `hot_to_cold_time` are estimated based on catalyst cooling characteristics; see the section below for details on how these values were derived.
+
+
+### Estimating `hot_to_warm_time` and `hot_to_cold_time`
+
+These two parameters can be interpreted as catalyst cooling thresholds, similar to the `\tau_{hot}` and `\tau_{warm}` transition times used in conventional unit commitment startup models:
+
+- `hot_to_warm_time`: time offline after which a hot start can no longer be assumed
+- `hot_to_cold_time`: time offline after which a cold start must be assumed
+
+For the linear generator, a reasonable first estimate is based on how long the catalyst takes to cool below its light-off temperature, typically about 200-300 °C. A simple lumped thermal model treats the catalyst assembly as cooling approximately exponentially after shutdown:
+
+$$
+T(t) = T_{amb} + (T_{op} - T_{amb}) e^{-t/\tau}
+$$
+
+where `T_amb` is ambient temperature, `T_op` is the catalyst operating temperature, and `\tau` is the thermal time constant of the catalyst assembly, approximately equal to thermal mass divided by heat loss conductance.
+
+Using rough screening values:
+
+- catalyst operating temperature: 400-600 °C
+- ambient temperature: about 20 °C
+- catalyst light-off temperature: about 250 °C
+- catalyst thermal time constant: about 30-60 minutes for a relatively small, modestly insulated substrate
+
+For example, if the catalyst is at 500 °C when the unit shuts down and the hot-to-warm threshold is taken as 250 °C, then:
+
+$$
+250 = 20 + (500 - 20)e^{-t/\tau}
+$$
+
+which gives:
+
+$$
+\frac{230}{480} = e^{-t/\tau}, \qquad
+t = \tau \ln\left(\frac{480}{230}\right) \approx 0.74\tau
+$$
+
+If `\tau = 45` minutes, this yields a hot-to-warm transition time of about 33 minutes after shutdown. The warm-to-cold transition, defined more conservatively as the catalyst approaching near-ambient conditions such as within 50 °C of ambient, would usually occur after several time constants, on the order of 2-4 hours.
+
+This supports a reasonable first-guess range of:
+
+| Transition | Estimated threshold |
+|-----------|---------------------|
+| Hot -> Warm | 30-60 minutes offline |
+| Warm -> Cold | 2-4 hours offline |
+
+These thresholds are much shorter than those of many conventional thermal generators because the catalyst assembly has much lower thermal mass. More accurate values would require vendor-specific information about catalyst substrate mass, heat capacity, insulation, and enclosure heat loss.
+
+## Linear Generator Fuel Parameters
+
+The `LinearGenerator` class currently uses default values for natural gas properties from [3]:
+
+| Parameter | Units | Default | Description |
+|-----------|-------|---------|-------------|
+| `hhv` | J/m³ | 39050000 | Higher heating value of natural gas (39.05 MJ/m³) [3] |
+| `fuel_density` | kg/m³ | 0.768 | Fuel density for mass calculations [3] |
+
+Linear generators are also capable of mixed-fuel operation. To model a different fuel, simply override the `hhv` and `fuel_density` parameters in the YAML configuration; in this case the `efficiency_table` should also be updated to reflect the new fuel's combustion characteristics.
+The `efficiency_table` parameter is **optional**. If not provided, the default HHV net plant efficiency from the Mainspring Energy Linear Generator datasheet [1] is 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 Efficiency Table
+
+The default HHV net plant efficiency table is sourced from the Mainspring Energy Linear Generator datasheet [1]:
+
+| Power Fraction | HHV Net Efficiency |
+|---------------|-------------------|
+| 1.00 | 0.40 (40%) |
+| 0.90 | 0.4144 (41.44%) |
+| 0.30 | 0.4144 (41.44%) |
+| 0.20 | 0.35 (35%) |
+
+Mainspring reports a single peak efficiency value of 41.44% HHV, which is representative of most of the operating range. The table adds a modest drop-off at the extremes: a small reduction at high load (above ~90% of rated) reflecting thermal losses, and a larger reduction at low load (below ~30% of rated) reflecting fixed auxiliary and parasitic losses. The boundary values at 0.90 and 0.30 are chosen conservatively to preserve the reported peak efficiency across the broad mid-load range; the actual roll-off shape is uncertain without part-load test data, so users with site-specific measurements should override the `efficiency_table` accordingly.
+
+## Linear Generator Outputs
+
+The linear generator model provides the following outputs (inherited from base class):
+
+| Output | Units | Description |
+|--------|-------|-------------|
+| `power` | kW | Actual power output |
+| `state` | integer | Operating state number (0-7), 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` [3]) |
+
+
+## YAML Configuration
+
+### Minimal Configuration
+
+Required parameters only (uses all defaults):
+
+```yaml
+linear_generator:
+  component_type: LinearGenerator
+  rated_capacity: 250  # kW
+  initial_conditions:
+    power: 0  # 0 kW means OFF; power > 0 means ON
+```
+
+### Full Configuration
+
+All parameters explicitly specified:
+
+```yaml
+linear_generator:
+  component_type: LinearGenerator
+  rated_capacity: 250  # kW
+  min_stable_load_fraction: 0.0
+  ramp_rate_fraction: 1.2  # 120%/min
+  run_up_rate_fraction: 1.2  # 120%/min
+  hot_startup_time: 90.0  # 1.5 minutes
+  warm_startup_time: 450.0  # 7.5 minutes
+  cold_startup_time: 900.0  # 15 minutes
+  min_up_time: 300  # 5 minutes
+  min_down_time: 300  # 5 minutes
+  hot_to_warm_time: 2700.0  # 45 minutes
+  hot_to_cold_time: 10800.0  # 3 hours
+  hhv: 39050000  # J/m³ for natural gas (39.05 MJ/m³) [3]
+  fuel_density: 0.768  # kg/m³ for natural gas [3]
+  efficiency_table:
+    power_fraction:
+      - 1.00
+      - 0.90
+      - 0.30
+      - 0.20
+    efficiency:  # HHV net plant efficiency from [1]; peak ±roll-off at extremes
+      - 0.40
+      - 0.4144
+      - 0.4144
+      - 0.35
+  log_channels:
+    - power
+    - fuel_volume_rate
+    - fuel_mass_rate
+    - state
+    - efficiency
+    - power_setpoint
+  initial_conditions:
+    power: 250  # kW; power > 0 means ON
+```
+
+### Multi-Unit Configuration (via ThermalPlant)
+
+Multiple linear generators can be combined using the `ThermalPlant` component:
+
+```yaml
+thermal_power_plant:
+  component_type: ThermalPlant
+  units: ["linear_generator_ms", "linear_generator_ms", "linear_generator_ms", "linear_generator_ms"]
+  unit_names: ["lg_1", "lg_2", "lg_3", "lg_4"]
+
+  linear_generator_ms:
+    component_type: LinearGenerator
+    rated_capacity: 250  # kW
+    initial_conditions:
+      power: 250  # Start ON at rated capacity
+```
+
+## 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-7), 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` [3])
+- `efficiency`: Current HHV net plant efficiency (0-1)
+- `power_setpoint`: Requested power setpoint in kW
+
+## References
+
+1. Mainspring Energy, "Linear Generator Datasheet," Rev. R30313.3, March 16, 2026.
+   https://linear-power.files.svdcdn.com/production/Mainspring-Linear-Generator-Datasheet-R30313.3_2026-03-16-205457_psod.pdf
+
+2. https://www.energy.ca.gov/sites/default/files/2024-05/CEC-500-2024-037.pdf
+
+3. 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
diff --git a/docs/open_cycle_gas_turbine.md b/docs/open_cycle_gas_turbine.md
@@ -31,6 +31,8 @@ The `OpenCycleGasTurbine` class provides default values for base class parameter
 | `cold_startup_time` | 480 s (8 minutes) | [1], [5] |
 | `min_up_time` | 1800 s (30 minutes) | [4] |
 | `min_down_time` | 3600 s (1 hour) | [4] |
+| `hot_to_warm_time` | 28800 s (8 hours) | [5] |
+| `hot_to_cold_time` | 172800 s (48 hours) | [5] |
 | `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] |
@@ -53,7 +55,7 @@ The OCGT 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 |
+| `state` | integer | Operating state number (0-7), 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]) |
@@ -113,6 +115,8 @@ open_cycle_gas_turbine:
   cold_startup_time: 480.0  # 8 minutes
   min_up_time: 1800  # 30 minutes
   min_down_time: 3600  # 1 hour
+  hot_to_warm_time: 28800.0  # 8 hours
+  hot_to_cold_time: 172800.0  # 48 hours
   hhv: 39050000  # J/m³ for natural gas (39.05 MJ/m³) [6]
   fuel_density: 0.768  # kg/m³ for natural gas [6]
   efficiency_table:
@@ -144,7 +148,7 @@ The `log_channels` parameter controls which outputs are written to the HDF5 outp
 
 **Available Channels:**
 - `power`: Actual power output in kW (always logged)
-- `state`: Operating state number (0-5), corresponding to the `STATES` enum
+- `state`: Operating state number (0-7), 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)