Add thermal_rc2 two-node thermal model with shared thermal integration utilities, docs, tests, and example.

Author: CameronBrooks11

CMakeLists.txt

@@ -43,7 +43,9 @@ set(FLUXGRAPH_SOURCES
     src/core/signal_store.cpp
     src/core/namespace.cpp
     src/core/units.cpp
+    src/model/thermal_integration.cpp
     src/model/thermal_mass.cpp
+    src/model/thermal_rc2.cpp
     src/graph/compiler.cpp
     src/engine.cpp
 )

README.md

@@ -126,6 +126,7 @@ int main() {
 - [`02_thermal_mass`](./examples/02_thermal_mass/) - Physics simulation with models
 - [`03_json_graph`](./examples/03_json_graph/) - Load graph from JSON file
 - [`04_yaml_graph`](./examples/04_yaml_graph/) - Load graph from YAML file
+- [`05_thermal_rc2`](./examples/05_thermal_rc2/) - Two-node thermal RC model example
 
 ## Project Structure
 

docs/api-reference.md

@@ -238,8 +238,8 @@ model.type = "thermal_mass";
 model.params["temp_signal"] = std::string("chamber.temp");
 model.params["power_signal"] = std::string("chamber.power");
 model.params["ambient_signal"] = std::string("ambient.temp");
-model.params["thermal_mass"] = 1000.0;  // J/degC
-model.params["heat_transfer_coeff"] = 10.0;  // W/degC
+model.params["thermal_mass"] = 1000.0;  // J/K
+model.params["heat_transfer_coeff"] = 10.0;  // W/K
 model.params["initial_temp"] = 25.0;  // degC
 model.params["integration_method"] = std::string("forward_euler"); // optional: "forward_euler" (default) or "rk4"
 spec.models.push_back(model);
@@ -248,6 +248,7 @@ spec.models.push_back(model);
 **Available model types:**
 
 - `thermal_mass` - Heat transfer simulation
+- `thermal_rc2` - Two-node thermal RC network (coupled temperatures)
 
 #### RuleSpec
 

docs/numerical-methods.md

@@ -14,9 +14,9 @@ Validation protocol details are documented in `docs/validation-methodology.md`.
 3. Methods are selected at compile time and remain fixed at runtime.
 4. Runtime behavior must be deterministic for identical inputs and `dt`.
 
-## ThermalMassModel Integration Methods
+## Thermal Model Integration Methods
 
-`thermal_mass` supports:
+Both `thermal_mass` and `thermal_rc2` support:
 
 1. `forward_euler` (default)
 2. `rk4` (classic fourth-order Runge-Kutta)
@@ -33,14 +33,23 @@ Unknown method names are compile-time errors.
 
 ## Stability Limits
 
-For the linear thermal model `dT/dt = (P - h*(T - T_amb)) / C`, with
-`k = h/C`:
+For the linear thermal mass model `dT/dt = (P - h*(T - T_amb)) / C`, with
+`k = h/C`, the stability limits are:
 
 1. `forward_euler`: `dt < 2/k = 2*C/h`
 2. `rk4`: `dt < 2.785293563/k = 2.785293563*C/h`
 
 If `h <= 0`, the model is treated as unconditionally stable for this criterion.
 
+For the two-node thermal RC model, the system is linear: `dT/dt = A*T + c`.
+Let `lambda_min` be the most negative eigenvalue of `A` (largest magnitude on
+the negative real axis). The stability limits use:
+
+1. `forward_euler`: `dt < 2/|lambda_min|`
+2. `rk4`: `dt < 2.785293563/|lambda_min|`
+
+FluxGraph enforces these via `IModel::compute_stability_limit()`.
+
 ## Validation Expectations
 
 Validation runs must report:

docs/schema-json.md

@@ -58,7 +58,7 @@ Models represent physical systems with internal state and differential equations
 **Fields:**
 
 - `id` (string, required) - Unique model identifier
-- `type` (string, required) - Model type (`"thermal_mass"` only in v1.0)
+- `type` (string, required) - Model type (built-in: `"thermal_mass"`, `"thermal_rc2"`)
 - `params` (object, required) - Model-specific parameters
 
 ### ThermalMass Model
@@ -74,6 +74,7 @@ Lumped thermal capacitance with heat transfer: `C * dT/dt = P - h * (T - T_ambie
 | `thermal_mass` | number | J/K | Heat capacity (must be > 0) |
 | `heat_transfer_coeff` | number | W/K | Heat transfer coefficient (must be > 0) |
 | `initial_temp` | number | degC | Initial temperature |
+| `integration_method` | string | - | Optional: `"forward_euler"` (default) or `"rk4"` |
 
 **Example:**
 
@@ -94,6 +95,49 @@ Lumped thermal capacitance with heat transfer: `C * dT/dt = P - h * (T - T_ambie
 
 **Stability:** Forward Euler integration requires `dt < 2 * thermal_mass / heat_transfer_coeff`
 
+### ThermalRc2 Model
+
+Two-node thermal RC network with ambient coupling and inter-node conductance.
+
+**Parameters:**
+| Parameter | Type | Units | Description |
+|-----------|------|-------|-------------|
+| `temp_signal_a` | string | - | Output signal path for node A temperature |
+| `temp_signal_b` | string | - | Output signal path for node B temperature |
+| `power_signal` | string | W | Input signal path for heating power (applied to node A) |
+| `ambient_signal` | string | degC | Input signal path for ambient temperature |
+| `thermal_mass_a` | number | J/K | Heat capacity of node A (must be > 0) |
+| `thermal_mass_b` | number | J/K | Heat capacity of node B (must be > 0) |
+| `heat_transfer_coeff_a` | number | W/K | Ambient coupling of node A (must be > 0) |
+| `heat_transfer_coeff_b` | number | W/K | Ambient coupling of node B (must be > 0) |
+| `coupling_coeff` | number | W/K | Conductance between nodes (must be >= 0) |
+| `initial_temp_a` | number | degC | Initial temperature of node A |
+| `initial_temp_b` | number | degC | Initial temperature of node B |
+| `integration_method` | string | - | Optional: `"forward_euler"` (default) or `"rk4"` |
+
+**Example:**
+
+```json
+{
+  "id": "chamber_rc",
+  "type": "thermal_rc2",
+  "params": {
+    "temp_signal_a": "chamber.shell_temp",
+    "temp_signal_b": "chamber.core_temp",
+    "power_signal": "chamber.heater_power",
+    "ambient_signal": "ambient.temp",
+    "thermal_mass_a": 1000.0,
+    "thermal_mass_b": 2000.0,
+    "heat_transfer_coeff_a": 10.0,
+    "heat_transfer_coeff_b": 8.0,
+    "coupling_coeff": 6.0,
+    "initial_temp_a": 25.0,
+    "initial_temp_b": 25.0,
+    "integration_method": "rk4"
+  }
+}
+```
+
 ## Edges
 
 Edges connect signals through transforms, defining the dataflow graph.

docs/schema-yaml.md

@@ -58,7 +58,7 @@ Models represent physical systems with internal state and differential equations
 
 ```yaml
 - id: unique_identifier # Unique model identifier
-  type: model_type # Model type (thermal_mass in v1.0)
+  type: model_type # Model type (thermal_mass, thermal_rc2)
   params: # Model-specific parameters
     param_name: value
 ```
@@ -76,6 +76,7 @@ Lumped thermal capacitance with heat transfer: `C * dT/dt = P - h * (T - T_ambie
 | `thermal_mass` | number | J/K | Heat capacity (must be > 0) |
 | `heat_transfer_coeff` | number | W/K | Heat transfer coefficient (must be > 0) |
 | `initial_temp` | number | degC | Initial temperature |
+| `integration_method` | string | - | Optional: `forward_euler` (default) or `rk4` |
 
 **Example:**
 
@@ -94,6 +95,47 @@ models:
 
 **Stability:** Forward Euler integration requires `dt < 2 * thermal_mass / heat_transfer_coeff`
 
+### ThermalRc2 Model
+
+Two-node thermal RC network with ambient coupling and inter-node conductance.
+
+**Parameters:**
+| Parameter | Type | Units | Description |
+|-----------|------|-------|-------------|
+| `temp_signal_a` | string | - | Output signal path for node A temperature |
+| `temp_signal_b` | string | - | Output signal path for node B temperature |
+| `power_signal` | string | W | Input signal path for heating power (applied to node A) |
+| `ambient_signal` | string | degC | Input signal path for ambient temperature |
+| `thermal_mass_a` | number | J/K | Heat capacity of node A (must be > 0) |
+| `thermal_mass_b` | number | J/K | Heat capacity of node B (must be > 0) |
+| `heat_transfer_coeff_a` | number | W/K | Ambient coupling of node A (must be > 0) |
+| `heat_transfer_coeff_b` | number | W/K | Ambient coupling of node B (must be > 0) |
+| `coupling_coeff` | number | W/K | Conductance between nodes (must be >= 0) |
+| `initial_temp_a` | number | degC | Initial temperature of node A |
+| `initial_temp_b` | number | degC | Initial temperature of node B |
+| `integration_method` | string | - | Optional: `forward_euler` (default) or `rk4` |
+
+**Example:**
+
+```yaml
+models:
+  - id: chamber_rc
+    type: thermal_rc2
+    params:
+      temp_signal_a: chamber.shell_temp
+      temp_signal_b: chamber.core_temp
+      power_signal: chamber.heater_power
+      ambient_signal: ambient.temp
+      thermal_mass_a: 1000.0
+      thermal_mass_b: 2000.0
+      heat_transfer_coeff_a: 10.0
+      heat_transfer_coeff_b: 8.0
+      coupling_coeff: 6.0
+      initial_temp_a: 25.0
+      initial_temp_b: 25.0
+      integration_method: rk4
+```
+
 ## Edges
 
 Edges connect signals through transforms, defining the dataflow graph.

examples/05_thermal_rc2/CMakeLists.txt

@@ -0,0 +1,2 @@
+add_executable(example_thermal_rc2 main.cpp)
+target_link_libraries(example_thermal_rc2 PRIVATE fluxgraph)

examples/05_thermal_rc2/main.cpp

@@ -0,0 +1,65 @@
+#include <fluxgraph/core/namespace.hpp>
+#include <fluxgraph/core/signal_store.hpp>
+#include <fluxgraph/engine.hpp>
+#include <fluxgraph/graph/compiler.hpp>
+#include <iomanip>
+#include <iostream>
+
+int main() {
+  fluxgraph::SignalNamespace sig_ns;
+  fluxgraph::FunctionNamespace func_ns;
+  fluxgraph::SignalStore store;
+
+  fluxgraph::GraphSpec spec;
+
+  fluxgraph::ModelSpec model;
+  model.id = "chamber_rc";
+  model.type = "thermal_rc2";
+  model.params["temp_signal_a"] = std::string("chamber.shell_temp");
+  model.params["temp_signal_b"] = std::string("chamber.core_temp");
+  model.params["power_signal"] = std::string("chamber.heater_power");
+  model.params["ambient_signal"] = std::string("ambient.temp");
+  model.params["thermal_mass_a"] = 1000.0;          // J/K
+  model.params["thermal_mass_b"] = 2000.0;          // J/K
+  model.params["heat_transfer_coeff_a"] = 10.0;     // W/K
+  model.params["heat_transfer_coeff_b"] = 8.0;      // W/K
+  model.params["coupling_coeff"] = 6.0;             // W/K
+  model.params["initial_temp_a"] = 25.0;            // degC
+  model.params["initial_temp_b"] = 25.0;            // degC
+  model.params["integration_method"] = std::string("rk4"); // optional
+  spec.models.push_back(model);
+
+  fluxgraph::GraphCompiler compiler;
+  auto program = compiler.compile(spec, sig_ns, func_ns);
+
+  fluxgraph::Engine engine;
+  engine.load(std::move(program));
+
+  const auto heater_sig = sig_ns.resolve("chamber.heater_power");
+  const auto ambient_sig = sig_ns.resolve("ambient.temp");
+  const auto shell_temp_sig = sig_ns.resolve("chamber.shell_temp");
+  const auto core_temp_sig = sig_ns.resolve("chamber.core_temp");
+
+  store.write(ambient_sig, 20.0, "degC");
+
+  std::cout << "Thermal RC2 Simulation\n";
+  std::cout << "======================\n";
+  std::cout << std::fixed << std::setprecision(2);
+
+  for (double t = 0.0; t <= 10.0; t += 0.5) {
+    const double heater_power = (t < 5.0) ? 500.0 : 0.0;
+    store.write(heater_sig, heater_power, "W");
+
+    engine.tick(0.5, store);
+
+    const double shell_temp = store.read_value(shell_temp_sig);
+    const double core_temp = store.read_value(core_temp_sig);
+
+    std::cout << "t=" << std::setw(5) << t << "s  "
+              << "Heater=" << std::setw(6) << heater_power << "W  "
+              << "Shell=" << std::setw(6) << shell_temp << " degC  "
+              << "Core=" << std::setw(6) << core_temp << " degC\n";
+  }
+
+  return 0;
+}

examples/CMakeLists.txt

@@ -4,8 +4,10 @@
 # Example 2: Thermal mass - Realistic physics simulation with models
 # Example 3: JSON loader - Load graph from JSON file (requires -DFLUXGRAPH_JSON_ENABLED=ON)
 # Example 4: YAML loader - Load graph from YAML file (requires -DFLUXGRAPH_YAML_ENABLED=ON)
+# Example 5: Thermal RC2 - Coupled two-node thermal model
 
 add_subdirectory(01_basic_transform)
 add_subdirectory(02_thermal_mass)
 add_subdirectory(03_json_graph)
 add_subdirectory(04_yaml_graph)
+add_subdirectory(05_thermal_rc2)

examples/README.md

@@ -165,6 +165,22 @@ cmake --build build-yaml --config Debug
 - Optional dependency (core library still zero-dep)
 - Can enable both JSON and YAML simultaneously
 
+## Example 5: Two-Node Thermal RC Simulation
+
+**Location:** `05_thermal_rc2/`
+
+Demonstrates a coupled two-temperature physics model:
+
+- `thermal_rc2` - Two-node thermal RC network (shell/core style)
+- Multiple model outputs (`temp_signal_a`, `temp_signal_b`)
+- Ambient coupling + inter-node conductance
+
+**Run:**
+
+```bash
+./build/examples/05_thermal_rc2/Debug/example_thermal_rc2.exe
+```
+
 ## When to Use Each Approach
 
 ### Manual GraphSpec (Examples 1 & 2)
@@ -255,7 +271,7 @@ double result = store.read_value(output_sig);
 
 **"Unknown model type" error:**
 
-- Check ModelSpec `type` field matches implemented model ("thermal_mass")
+- Check ModelSpec `type` field matches implemented model ("thermal_mass" or "thermal_rc2")
 - Ensure all required params are present
 
 **Signals read as 0.0:**
@@ -267,7 +283,7 @@ double result = store.read_value(output_sig);
 **Unexpected NaN/Inf values:**
 
 - Check model stability limits (dt too large)
-- Verify thermal_mass and heat_transfer_coeff > 0
+- Verify model parameters satisfy constraints (for example: thermal_mass > 0, heat_transfer_coeff > 0)
 - Ensure ambient temperature is initialized
 
 **Compile errors:**