feat(filter): implement MTRSim algorithm execute + statistical wiring test

Wire MTRSimFilter to the LibMTRSim simulateMTR entry point: reconstruct
ODFComponents from the selected Float64 cell arrays, build SimulationParams
from filter inputs, run the simulation, and write MTRIds + Eulers into the
output geometry cell AttributeMatrix. Polar coloring (Task 8) is deferred.

Add preflight non-negativity/range hardening (error -13007) requiring each
Volume Fraction value to lie in [0, 1].

Add an end-to-end execute test (100x100 = 10000 voxels, seed 42, 3 components)
that verifies array contract (types/components/tuples), id set {1,2,3},
finite Bunge-bounded Eulers, recorded seed, and loose volume fractions.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: imikejackson

src/MTRSim/Filters/Algorithms/MTRSim.cpp

@@ -1,5 +1,17 @@
 #include "MTRSim.hpp"
 
+#include "simplnx/DataStructure/DataArray.hpp"
+#include "simplnx/DataStructure/Geometry/ImageGeom.hpp"
+
+#include "LibMTRSim/MTRSimDriver.hpp"
+
+#include <fmt/format.h>
+
+#include <cmath>
+#include <exception>
+#include <random>
+#include <vector>
+
 using namespace nx::core;
 
 // -----------------------------------------------------------------------------
@@ -17,8 +29,81 @@ MTRSim::~MTRSim() noexcept = default;
 // -----------------------------------------------------------------------------
 Result<> MTRSim::operator()()
 {
-  // NOTE: The algorithm body is implemented in a later task. For now this is a
-  // no-op stub so the filter scaffolding (preflight + parameter validation) can
-  // be built and tested independently.
+  m_MessageHandler(IFilter::Message::Type::Info, "Reading ODF geometry...");
+
+  // 1. ODF grid geometry (degrees) from the input ODF ImageGeom.
+  const auto& odfGeom = m_DataStructure.getDataRefAs<ImageGeom>(m_InputValues->inputOdfGeometryPath);
+  const SizeVec3 odfDims = odfGeom.getDimensions();  // X=phi2, Y=PHI, Z=phi1
+  const FloatVec3 odfSpacing = odfGeom.getSpacing(); // degrees
+  const int n2 = static_cast<int>(odfDims[0]);
+  const int nPHI = static_cast<int>(odfDims[1]);
+  const int n1 = static_cast<int>(odfDims[2]);
+
+  // 2. Reconstruct ODFComponents from the selected Float64 cell arrays. The
+  // store is row-major ZYX (phi1 slowest, phi2 fastest), exactly the flat
+  // layout gridToODFComponent expects, so we copy values in their natural order.
+  std::vector<mtrsim::ODFComponent> components;
+  components.reserve(m_InputValues->odfComponentPaths.size());
+  for(const auto& path : m_InputValues->odfComponentPaths)
+  {
+    const auto& arr = m_DataStructure.getDataRefAs<Float64Array>(path);
+    const auto& store = arr.getDataStoreRef();
+    std::vector<double> values(store.begin(), store.end());
+    components.push_back(mtrsim::gridToODFComponent(values, n1, nPHI, n2, static_cast<double>(odfSpacing[2]), static_cast<double>(odfSpacing[1]), static_cast<double>(odfSpacing[0])));
+  }
+
+  // 3. SimulationParams from filter inputs.
+  mtrsim::SimulationParams params;
+  params.xLen = m_InputValues->physicalSize[0];
+  params.yLen = m_InputValues->physicalSize[1];
+  params.zLen = m_InputValues->physicalSize[2];
+  params.dx = m_InputValues->physicalSpacing[0];
+  params.dy = m_InputValues->physicalSpacing[1];
+  params.dz = m_InputValues->physicalSpacing[2];
+  params.volumeFractions = m_InputValues->volumeFractions[0]; // 1 row
+  params.thetaList = m_InputValues->thetaList;
+  params.seed = m_InputValues->seed;
+
+  if(m_ShouldCancel)
+  {
+    return {};
+  }
+
+  // 4. Run simulation (SIMPLNX z,y,x order out).
+  m_MessageHandler(IFilter::Message::Type::Info, "Running MTR simulation (this may take a while for large volumes)...");
+  std::mt19937_64 rng(m_InputValues->seed);
+  mtrsim::MTRSimResult sim;
+  try
+  {
+    sim = mtrsim::simulateMTR(params, components, rng, n1, nPHI, n2);
+  } catch(const std::exception& e)
+  {
+    return MakeErrorResult(-13050, fmt::format("MTR simulation failed: {}", e.what()));
+  }
+
+  if(m_ShouldCancel)
+  {
+    return {};
+  }
+
+  // 5. Write MTR ids + Euler arrays (output geometry cell AM).
+  const DataPath cellAm = m_InputValues->outputGeometryPath.createChildPath(m_InputValues->cellAttrMatName);
+  auto& mtrIds = m_DataStructure.getDataRefAs<Int32Array>(cellAm.createChildPath(m_InputValues->mtrIdsArrayName));
+  auto& eulers = m_DataStructure.getDataRefAs<Float32Array>(cellAm.createChildPath(m_InputValues->eulersArrayName));
+  auto& mtrStore = mtrIds.getDataStoreRef();
+  auto& eulerStore = eulers.getDataStoreRef();
+
+  const std::size_t N = sim.mtrIndex.size();
+  for(std::size_t i = 0; i < N; ++i)
+  {
+    mtrStore[i] = sim.mtrIndex[i];
+    eulerStore[i * 3 + 0] = static_cast<float>(sim.phi1[i]);
+    eulerStore[i * 3 + 1] = static_cast<float>(sim.phi[i]);
+    eulerStore[i * 3 + 2] = static_cast<float>(sim.phi2[i]);
+  }
+
+  m_MessageHandler(IFilter::Message::Type::Info, "MTR simulation complete.");
+  // Polar coloring (Task 8) is handled in a later task; the optional array (if
+  // requested) is left created-but-unfilled here and populated next task.
   return {};
 }

src/MTRSim/Filters/MTRSimFilter.cpp

@@ -161,6 +161,13 @@ IFilter::PreflightResult MTRSimFilter::preflightImpl(const DataStructure& dataSt
   {
     return {MakeErrorResult<OutputActions>(-13003, fmt::format("Volume Fraction values must sum to 1.0 (got {:.4f}).", vfSum))};
   }
+  for(double v : pVolumeFractions[0])
+  {
+    if(v < 0.0 || v > 1.0)
+    {
+      return {MakeErrorResult<OutputActions>(-13007, fmt::format("Each Volume Fraction value must be in the range [0, 1] (got {:.4f}).", v))};
+    }
+  }
   if(pThetaList.size() < numComponents - 1)
   {
     return {MakeErrorResult<OutputActions>(-13004, fmt::format("Theta List needs at least {} rows (components - 1).", numComponents - 1))};

test/MTRSimTest.cpp

@@ -23,6 +23,8 @@
 
 #include <fmt/format.h>
 
+#include <array>
+#include <cmath>
 #include <vector>
 
 using namespace nx::core;
@@ -116,6 +118,107 @@ TEST_CASE("MTRSim::MTRSimFilter: Rejects mismatched Volume Fraction column count
   SIMPLNX_RESULT_REQUIRE_INVALID(preflightResult.outputActions);
 }
 
+TEST_CASE("MTRSim::MTRSimFilter: Execute wires simulation to output arrays", "[MTRSim][MTRSimFilter]")
+{
+  UnitTest::LoadPlugins();
+
+  DataStructure dataStructure;
+  const std::vector<DataPath> compPaths = BuildOdfDataStructure(dataStructure, 3);
+  // Fill every component array with a uniform value so ODF sampling is well-defined.
+  for(const auto& path : compPaths)
+  {
+    auto& arr = dataStructure.getDataRefAs<Float64Array>(path);
+    arr.fill(1.0);
+  }
+
+  MTRSimFilter filter;
+  Arguments args = MakeValidArgs(compPaths);
+  // Modest domain: 100x100 = 10000 voxels (Z=0 -> single layer).
+  args.insertOrAssign(MTRSimFilter::k_PhysicalSize_Key, std::vector<float32>{2.0f, 2.0f, 0.0f});
+  args.insertOrAssign(MTRSimFilter::k_PhysicalSpacing_Key, std::vector<float32>{0.02f, 0.02f, 0.02f});
+  args.insertOrAssign(MTRSimFilter::k_VolumeFractions_Key, DynamicTableParameter::ValueType{{0.30, 0.35, 0.35}});
+  args.insertOrAssign(MTRSimFilter::k_UseSeed_Key, true);
+  args.insertOrAssign(MTRSimFilter::k_SeedValue_Key, static_cast<uint64>(42));
+
+  auto preflightResult = filter.preflight(dataStructure, args);
+  SIMPLNX_RESULT_REQUIRE_VALID(preflightResult.outputActions);
+
+  auto executeResult = filter.execute(dataStructure, args);
+  SIMPLNX_RESULT_REQUIRE_VALID(executeResult.result);
+
+  // Output ImageGeom exists.
+  const DataPath outGeomPath({"MTR Microstructure"});
+  REQUIRE_NOTHROW(dataStructure.getDataRefAs<ImageGeom>(outGeomPath));
+
+  const DataPath cellAm = outGeomPath.createChildPath("Cell Data");
+  const usize expectedTuples = 100 * 100;
+
+  // MTRIds: Int32, 1 component, 10000 tuples.
+  auto& mtrIds = dataStructure.getDataRefAs<Int32Array>(cellAm.createChildPath("MTRIds"));
+  REQUIRE(mtrIds.getNumberOfComponents() == 1);
+  REQUIRE(mtrIds.getNumberOfTuples() == expectedTuples);
+
+  // Eulers: Float32, 3 components, 10000 tuples.
+  auto& eulers = dataStructure.getDataRefAs<Float32Array>(cellAm.createChildPath("Eulers"));
+  REQUIRE(eulers.getNumberOfComponents() == 3);
+  REQUIRE(eulers.getNumberOfTuples() == expectedTuples);
+
+  // MTR ids in {1,2,3}; at least 2 distinct ids appear. Also accumulate empirical
+  // volume fractions for a loose wiring check.
+  const auto& mtrStore = mtrIds.getDataStoreRef();
+  std::array<usize, 4> counts = {0, 0, 0, 0};
+  for(usize i = 0; i < mtrStore.getSize(); ++i)
+  {
+    const int32 id = mtrStore[i];
+    REQUIRE(id >= 1);
+    REQUIRE(id <= 3);
+    counts[static_cast<usize>(id)]++;
+  }
+  usize distinct = 0;
+  for(usize id = 1; id <= 3; ++id)
+  {
+    if(counts[id] > 0)
+    {
+      distinct++;
+    }
+  }
+  REQUIRE(distinct >= 2);
+
+  // Euler values finite and within Bunge bounds (interleaved 3/voxel).
+  constexpr float twoPi = 2.0f * static_cast<float>(M_PI);
+  constexpr float pi = static_cast<float>(M_PI);
+  const auto& eulerStore = eulers.getDataStoreRef();
+  for(usize t = 0; t < expectedTuples; ++t)
+  {
+    const float phi1 = eulerStore[t * 3 + 0];
+    const float Phi = eulerStore[t * 3 + 1];
+    const float phi2 = eulerStore[t * 3 + 2];
+    REQUIRE(std::isfinite(phi1));
+    REQUIRE(std::isfinite(Phi));
+    REQUIRE(std::isfinite(phi2));
+    REQUIRE(phi1 >= 0.0f);
+    REQUIRE(phi1 <= twoPi);
+    REQUIRE(Phi >= 0.0f);
+    REQUIRE(Phi <= pi);
+    REQUIRE(phi2 >= 0.0f);
+    REQUIRE(phi2 <= twoPi);
+  }
+
+  // Seed array records 42.
+  auto& seedArray = dataStructure.getDataRefAs<UInt64Array>(DataPath({"MTRSim SeedValue"}));
+  REQUIRE(seedArray[0] == 42);
+
+  // Loose volume-fraction wiring check (NOT a statistics check; rigorous VF
+  // validation lives in the LibMTRSim statistical test). A 100x100 correlated
+  // field has real variance, so use a generous margin of 0.12.
+  const std::array<double, 4> targets = {0.0, 0.30, 0.35, 0.35};
+  for(usize id = 1; id <= 3; ++id)
+  {
+    const double empirical = static_cast<double>(counts[id]) / static_cast<double>(expectedTuples);
+    REQUIRE(empirical == Approx(targets[id]).margin(0.12));
+  }
+}
+
 TEST_CASE("MTRSim::MTRSimFilter: Rejects too few Theta List rows", "[MTRSim][MTRSimFilter][ErrorPath]")
 {
   UnitTest::LoadPlugins();