Phase 6.1 complete: added PT1/PT2 built-in process models with strict ModelSignature metadata, introduced minimal time units, expanded unit and analytical test coverage, and updated examples and documentation.

Author: CameronBrooks11

CMakeLists.txt

@@ -46,6 +46,8 @@ set(FLUXGRAPH_SOURCES
     src/model/thermal_integration.cpp
     src/model/thermal_mass.cpp
     src/model/thermal_rc2.cpp
+    src/model/first_order_process.cpp
+    src/model/second_order_process.cpp
     src/graph/compiler.cpp
     src/engine.cpp
 )

README.md

@@ -127,6 +127,8 @@ int main() {
 - [`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
+- [`06_first_order_process`](./examples/06_first_order_process/) - First-order process primitive (PT1)
+- [`07_second_order_process`](./examples/07_second_order_process/) - Second-order process primitive (PT2)
 
 ## Project Structure
 

docs/api-reference.md

@@ -249,6 +249,8 @@ spec.models.push_back(model);
 
 - `thermal_mass` - Heat transfer simulation
 - `thermal_rc2` - Two-node thermal RC network (coupled temperatures)
+- `first_order_process` - First-order process primitive (PT1)
+- `second_order_process` - Second-order process primitive (PT2)
 
 #### RuleSpec
 

docs/numerical-methods.md

@@ -14,9 +14,16 @@ 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`.
 
-## Thermal Model Integration Methods
+## ODE Model Integration Methods
 
-Both `thermal_mass` and `thermal_rc2` support:
+The following built-in models support `integration_method`:
+
+1. `thermal_mass`
+2. `thermal_rc2`
+3. `first_order_process`
+4. `second_order_process`
+
+Supported methods:
 
 1. `forward_euler` (default)
 2. `rk4` (classic fourth-order Runge-Kutta)
@@ -50,6 +57,14 @@ the negative real axis). The stability limits use:
 
 FluxGraph enforces these via `IModel::compute_stability_limit()`.
 
+For the process primitives:
+
+1. `first_order_process`: equivalent to `lambda = -1/tau_s`, so the same
+   negative-real-axis limits apply.
+2. `second_order_process`: eigenvalues may be complex; stability is evaluated
+   using the selected method's stability function `R(z)` along `z = lambda*dt`,
+   requiring `|R(lambda*dt)| <= 1` for each eigenvalue.
+
 ## 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 (built-in: `"thermal_mass"`, `"thermal_rc2"`)
+- `type` (string, required) - Model type (built-in: `"thermal_mass"`, `"thermal_rc2"`, `"first_order_process"`, `"second_order_process"`)
 - `params` (object, required) - Model-specific parameters
 
 ### ThermalMass Model
@@ -138,6 +138,72 @@ Two-node thermal RC network with ambient coupling and inter-node conductance.
 }
 ```
 
+### FirstOrderProcess Model
+
+First-order process primitive: `dy/dt = (gain * u - y) / tau`.
+
+**Parameters:**
+| Parameter | Type | Units | Description |
+|-----------|------|-------|-------------|
+| `output_signal` | string | dimensionless | Output signal path |
+| `input_signal` | string | dimensionless | Input signal path |
+| `gain` | number | dimensionless | Static gain (finite) |
+| `tau_s` | number | s | Time constant (must be > 0) |
+| `initial_output` | number | dimensionless | Initial output value |
+| `integration_method` | string | - | Optional: `"forward_euler"` (default) or `"rk4"` |
+
+**Example:**
+
+```json
+{
+  "id": "pt1",
+  "type": "first_order_process",
+  "params": {
+    "output_signal": "pt1.y",
+    "input_signal": "pt1.u",
+    "gain": 2.0,
+    "tau_s": 1.0,
+    "initial_output": 0.0
+  }
+}
+```
+
+### SecondOrderProcess Model
+
+Second-order process primitive:
+`y'' + 2*zeta*omega_n*y' + omega_n^2*y = omega_n^2 * gain * u`
+
+**Parameters:**
+| Parameter | Type | Units | Description |
+|-----------|------|-------|-------------|
+| `output_signal` | string | dimensionless | Output signal path |
+| `input_signal` | string | dimensionless | Input signal path |
+| `gain` | number | dimensionless | Static gain (finite) |
+| `zeta` | number | dimensionless | Damping ratio (must be >= 0) |
+| `omega_n_rad_s` | number | 1/s | Natural frequency (must be > 0) |
+| `initial_output` | number | dimensionless | Initial output value |
+| `initial_output_rate` | number | 1/s | Initial output rate |
+| `integration_method` | string | - | Optional: `"forward_euler"` (default) or `"rk4"` |
+
+**Example:**
+
+```json
+{
+  "id": "pt2",
+  "type": "second_order_process",
+  "params": {
+    "output_signal": "pt2.y",
+    "input_signal": "pt2.u",
+    "gain": 2.0,
+    "zeta": 0.7,
+    "omega_n_rad_s": 4.0,
+    "initial_output": 0.0,
+    "initial_output_rate": 0.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, thermal_rc2)
+  type: model_type # Model type (thermal_mass, thermal_rc2, first_order_process, second_order_process)
   params: # Model-specific parameters
     param_name: value
 ```
@@ -136,6 +136,68 @@ models:
       integration_method: rk4
 ```
 
+### FirstOrderProcess Model
+
+First-order process primitive: `dy/dt = (gain * u - y) / tau`.
+
+**Parameters:**
+| Parameter | Type | Units | Description |
+|-----------|------|-------|-------------|
+| `output_signal` | string | dimensionless | Output signal path |
+| `input_signal` | string | dimensionless | Input signal path |
+| `gain` | number | dimensionless | Static gain (finite) |
+| `tau_s` | number | s | Time constant (must be > 0) |
+| `initial_output` | number | dimensionless | Initial output value |
+| `integration_method` | string | - | Optional: `forward_euler` (default) or `rk4` |
+
+**Example:**
+
+```yaml
+models:
+  - id: pt1
+    type: first_order_process
+    params:
+      output_signal: pt1.y
+      input_signal: pt1.u
+      gain: 2.0
+      tau_s: 1.0
+      initial_output: 0.0
+```
+
+### SecondOrderProcess Model
+
+Second-order process primitive:
+`y'' + 2*zeta*omega_n*y' + omega_n^2*y = omega_n^2 * gain * u`
+
+**Parameters:**
+| Parameter | Type | Units | Description |
+|-----------|------|-------|-------------|
+| `output_signal` | string | dimensionless | Output signal path |
+| `input_signal` | string | dimensionless | Input signal path |
+| `gain` | number | dimensionless | Static gain (finite) |
+| `zeta` | number | dimensionless | Damping ratio (must be >= 0) |
+| `omega_n_rad_s` | number | 1/s | Natural frequency (must be > 0) |
+| `initial_output` | number | dimensionless | Initial output value |
+| `initial_output_rate` | number | 1/s | Initial output rate |
+| `integration_method` | string | - | Optional: `forward_euler` (default) or `rk4` |
+
+**Example:**
+
+```yaml
+models:
+  - id: pt2
+    type: second_order_process
+    params:
+      output_signal: pt2.y
+      input_signal: pt2.u
+      gain: 2.0
+      zeta: 0.7
+      omega_n_rad_s: 4.0
+      initial_output: 0.0
+      initial_output_rate: 0.0
+      integration_method: rk4
+```
+
 ## Edges
 
 Edges connect signals through transforms, defining the dataflow graph.

examples/06_first_order_process/CMakeLists.txt

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

examples/06_first_order_process/main.cpp

@@ -0,0 +1,55 @@
+#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;
+  spec.signals.push_back({"pt1.u", "dimensionless"});
+  spec.signals.push_back({"pt1.y", "dimensionless"});
+
+  fluxgraph::ModelSpec model;
+  model.id = "pt1";
+  model.type = "first_order_process";
+  model.params["output_signal"] = std::string("pt1.y");
+  model.params["input_signal"] = std::string("pt1.u");
+  model.params["gain"] = 2.0;
+  model.params["tau_s"] = 1.0;
+  model.params["initial_output"] = 0.0;
+  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 u_sig = sig_ns.resolve("pt1.u");
+  const auto y_sig = sig_ns.resolve("pt1.y");
+
+  std::cout << "First-Order Process Simulation (PT1)\n";
+  std::cout << "===================================\n";
+  std::cout << std::fixed << std::setprecision(3);
+
+  constexpr double dt = 0.05;
+  store.write(u_sig, 0.0, "dimensionless");
+
+  for (double t = 0.0; t <= 5.0; t += dt) {
+    const double u = (t >= 1.0) ? 1.0 : 0.0;
+    store.write(u_sig, u, "dimensionless");
+    engine.tick(dt, store);
+
+    const double y = store.read_value(y_sig);
+    std::cout << "t=" << std::setw(5) << t << "s  u=" << u
+              << "  y=" << std::setw(8) << y << "\n";
+  }
+
+  return 0;
+}

examples/07_second_order_process/CMakeLists.txt

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

examples/07_second_order_process/main.cpp

@@ -0,0 +1,59 @@
+#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;
+  spec.signals.push_back({"pt2.u", "dimensionless"});
+  spec.signals.push_back({"pt2.y", "dimensionless"});
+
+  fluxgraph::ModelSpec model;
+  model.id = "pt2";
+  model.type = "second_order_process";
+  model.params["output_signal"] = std::string("pt2.y");
+  model.params["input_signal"] = std::string("pt2.u");
+  model.params["gain"] = 2.0;
+  model.params["zeta"] = 0.7;
+  model.params["omega_n_rad_s"] = 4.0;
+  model.params["initial_output"] = 0.0;
+  model.params["initial_output_rate"] = 0.0;
+  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 u_sig = sig_ns.resolve("pt2.u");
+  const auto y_sig = sig_ns.resolve("pt2.y");
+
+  std::cout << "Second-Order Process Simulation (PT2)\n";
+  std::cout << "====================================\n";
+  std::cout << std::fixed << std::setprecision(3);
+
+  constexpr double dt = 0.01;
+  store.write(u_sig, 0.0, "dimensionless");
+
+  for (double t = 0.0; t <= 5.0; t += dt) {
+    const double u = (t >= 1.0) ? 1.0 : 0.0;
+    store.write(u_sig, u, "dimensionless");
+    engine.tick(dt, store);
+
+    const double y = store.read_value(y_sig);
+    if (static_cast<int>(t / dt) % 10 == 0) {
+      std::cout << "t=" << std::setw(5) << t << "s  u=" << u
+                << "  y=" << std::setw(8) << y << "\n";
+    }
+  }
+
+  return 0;
+}