Phase 6.2 complete: added mass_spring_damper model with curated mechanical units, compiler signatures, tests, example, docs updates, and fixed a unit-contract bug in Example 2

Author: CameronBrooks11

CMakeLists.txt

@@ -48,6 +48,7 @@ set(FLUXGRAPH_SOURCES
     src/model/thermal_rc2.cpp
     src/model/first_order_process.cpp
     src/model/second_order_process.cpp
+    src/model/mass_spring_damper.cpp
     src/graph/compiler.cpp
     src/engine.cpp
 )

README.md

@@ -129,6 +129,7 @@ int main() {
 - [`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)
+- [`08_mass_spring_damper`](./examples/08_mass_spring_damper/) - Translational mass-spring-damper model example
 
 ## Project Structure
 

docs/api-reference.md

@@ -251,6 +251,7 @@ spec.models.push_back(model);
 - `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)
+- `mass_spring_damper` - Translational mass-spring-damper (mechanical)
 
 #### RuleSpec
 

docs/schema-json.md

@@ -204,6 +204,44 @@ Second-order process primitive:
 }
 ```
 
+### MassSpringDamper Model
+
+Translational single-degree-of-freedom mass-spring-damper:
+`m*x'' + c*x' + k*x = F`
+
+**Parameters:**
+| Parameter | Type | Units | Description |
+|-----------|------|-------|-------------|
+| `position_signal` | string | m | Output position signal path |
+| `velocity_signal` | string | m/s | Output velocity signal path |
+| `force_signal` | string | N | Input force signal path |
+| `mass` | number | kg | Mass (must be > 0) |
+| `damping_coeff` | number | N*s/m | Damping coefficient (must be >= 0) |
+| `spring_constant` | number | N/m | Spring constant (must be >= 0) |
+| `initial_position` | number | m | Initial position |
+| `initial_velocity` | number | m/s | Initial velocity |
+| `integration_method` | string | - | Optional: `"forward_euler"` (default) or `"rk4"` |
+
+**Example:**
+
+```json
+{
+  "id": "msd",
+  "type": "mass_spring_damper",
+  "params": {
+    "position_signal": "msd.x",
+    "velocity_signal": "msd.v",
+    "force_signal": "msd.F",
+    "mass": 1.0,
+    "damping_coeff": 2.0,
+    "spring_constant": 20.0,
+    "initial_position": 0.0,
+    "initial_velocity": 0.0,
+    "integration_method": "rk4"
+  }
+}
+```
+
 ## Edges
 
 Edges connect signals through transforms, defining the dataflow graph.

docs/schema-yaml.md

@@ -198,6 +198,42 @@ models:
       integration_method: rk4
 ```
 
+### MassSpringDamper Model
+
+Translational single-degree-of-freedom mass-spring-damper:
+`m*x'' + c*x' + k*x = F`
+
+**Parameters:**
+| Parameter | Type | Units | Description |
+|-----------|------|-------|-------------|
+| `position_signal` | string | m | Output position signal path |
+| `velocity_signal` | string | m/s | Output velocity signal path |
+| `force_signal` | string | N | Input force signal path |
+| `mass` | number | kg | Mass (must be > 0) |
+| `damping_coeff` | number | N*s/m | Damping coefficient (must be >= 0) |
+| `spring_constant` | number | N/m | Spring constant (must be >= 0) |
+| `initial_position` | number | m | Initial position |
+| `initial_velocity` | number | m/s | Initial velocity |
+| `integration_method` | string | - | Optional: `forward_euler` (default) or `rk4` |
+
+**Example:**
+
+```yaml
+models:
+  - id: msd
+    type: mass_spring_damper
+    params:
+      position_signal: msd.x
+      velocity_signal: msd.v
+      force_signal: msd.F
+      mass: 1.0
+      damping_coeff: 2.0
+      spring_constant: 20.0
+      initial_position: 0.0
+      initial_velocity: 0.0
+      integration_method: rk4
+```
+
 ## Edges
 
 Edges connect signals through transforms, defining the dataflow graph.

examples/02_thermal_mass/main.cpp

@@ -49,7 +49,7 @@ int main() {
   auto temp_noisy_sig = sig_ns.resolve("chamber.temperature_noisy");
 
   // 5. Initialize ambient temperature
-  store.write(ambient_sig, 20.0, "celsius");
+  store.write(ambient_sig, 20.0, "degC");
 
   // 6. Simulation: heat chamber for 5 seconds, then turn off
   std::cout << "Thermal Mass Simulation\n";

examples/08_mass_spring_damper/CMakeLists.txt

@@ -0,0 +1,3 @@
+add_executable(example_mass_spring_damper main.cpp)
+target_link_libraries(example_mass_spring_damper PRIVATE fluxgraph)
+

examples/08_mass_spring_damper/main.cpp

@@ -0,0 +1,62 @@
+#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 = "msd";
+  model.type = "mass_spring_damper";
+  model.params["position_signal"] = std::string("msd.position_m");
+  model.params["velocity_signal"] = std::string("msd.velocity_m_s");
+  model.params["force_signal"] = std::string("msd.force_N");
+  model.params["mass"] = 1.0;             // kg
+  model.params["damping_coeff"] = 2.0;    // N*s/m
+  model.params["spring_constant"] = 20.0; // N/m
+  model.params["initial_position"] = 0.0; // m
+  model.params["initial_velocity"] = 0.0; // m/s
+  model.params["integration_method"] = std::string("rk4");
+  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 force_id = sig_ns.resolve("msd.force_N");
+  const auto position_id = sig_ns.resolve("msd.position_m");
+  const auto velocity_id = sig_ns.resolve("msd.velocity_m_s");
+
+  std::cout << "Mass-Spring-Damper Step Response\n";
+  std::cout << "================================\n";
+  std::cout << std::fixed << std::setprecision(4);
+
+  constexpr double dt = 0.01;
+  for (double t = 0.0; t <= 5.0; t += dt) {
+    const double force = (t < 2.5) ? 1.0 : 0.0;
+    store.write(force_id, force, "N");
+
+    engine.tick(dt, store);
+
+    if (static_cast<int>(t / dt) % 50 == 0) {
+      const double x = store.read_value(position_id);
+      const double v = store.read_value(velocity_id);
+      std::cout << "t=" << std::setw(5) << t << " s  "
+                << "F=" << std::setw(6) << force << " N  "
+                << "x=" << std::setw(8) << x << " m  "
+                << "v=" << std::setw(8) << v << " m/s\n";
+    }
+  }
+
+  return 0;
+}
+

examples/CMakeLists.txt

@@ -7,6 +7,7 @@
 # Example 5: Thermal RC2 - Coupled two-node thermal model
 # Example 6: First-order process (dimensionless PT1)
 # Example 7: Second-order process (dimensionless PT2)
+# Example 8: Mass-spring-damper (translational mechanical model)
 
 add_subdirectory(01_basic_transform)
 add_subdirectory(02_thermal_mass)
@@ -15,3 +16,4 @@ add_subdirectory(04_yaml_graph)
 add_subdirectory(05_thermal_rc2)
 add_subdirectory(06_first_order_process)
 add_subdirectory(07_second_order_process)
+add_subdirectory(08_mass_spring_damper)

examples/README.md

@@ -213,6 +213,22 @@ Demonstrates a canonical second-order process primitive:
 ./build/examples/07_second_order_process/Debug/example_second_order_process.exe
 ```
 
+## Example 8: Mass-Spring-Damper (Mechanical)
+
+**Location:** `08_mass_spring_damper/`
+
+Demonstrates a simple translational mechanical model:
+
+- `mass_spring_damper` model with physical parameters (`mass`, `damping_coeff`, `spring_constant`)
+- Force input contract (`N`) and position/velocity outputs (`m`, `m/s`)
+- Step force response
+
+**Run:**
+
+```bash
+./build/examples/08_mass_spring_damper/Debug/example_mass_spring_damper.exe
+```
+
 ## When to Use Each Approach
 
 ### Manual GraphSpec (Examples 1 & 2)