feat(cpp-object-oriented-modular-refactoring): step 15 - generic-dof-manager

src/fesa/assembly/load_assembler.cpp

@@ -25,79 +25,6 @@ Status LoadFailure(const std::string& code, const SourceLocation& location,
       {{Severity::kError, code, location, keyword, identity, message}});
 }
 
-/// @brief Checks that equation-space indices preserve stable full-DOF order.
-bool IsStrictlyIncreasing(const std::vector<std::size_t>& values) {
-  return std::adjacent_find(
-             values.begin(), values.end(),
-             [](const std::size_t left, const std::size_t right) {
-               return left >= right;
-             }) == values.end();
-}
-
-/// @brief Validates the full/free/constrained partition used by load assembly.
-Status ValidateDofOrder(const DofManager& dofs,
-                        const std::size_t expected_full_count,
-                        const SourceLocation& location) {
-  const std::size_t full_count = dofs.FullDofCount();
-  const auto& free_dofs = dofs.FreeDofs();
-  const auto& constrained_dofs = dofs.ConstrainedDofs();
-  if (full_count != expected_full_count ||
-      free_dofs.size() != dofs.FreeDofCount() ||
-      constrained_dofs.size() != dofs.ConstrainedDofCount() ||
-      dofs.PrescribedValues().Size() != constrained_dofs.size() ||
-      constrained_dofs.size() > full_count ||
-      free_dofs.size() != full_count - constrained_dofs.size()) {
-    return LoadFailure("invalid-load-dimensions", location, "LOAD_ASSEMBLER",
-                       std::to_string(full_count),
-                       "Full, free, constrained, prescribed, and model "
-                       "dimensions must agree.");
-  }
-  if (!IsStrictlyIncreasing(free_dofs) ||
-      !IsStrictlyIncreasing(constrained_dofs)) {
-    return LoadFailure(
-        "invalid-load-order", location, "LOAD_ASSEMBLER",
-        std::to_string(full_count),
-        "Free and constrained DOFs must use stable increasing full-DOF order.");
-  }
-
-  std::vector<unsigned char> ownership(full_count, 0U);
-  try {
-    for (std::size_t equation = 0U; equation < free_dofs.size(); ++equation) {
-      const std::size_t full_dof = free_dofs[equation];
-      if (full_dof >= full_count || ownership[full_dof] != 0U ||
-          dofs.FreeEquation(full_dof) != equation) {
-        return LoadFailure(
-            "invalid-load-order", location, "LOAD_ASSEMBLER",
-            std::to_string(full_dof),
-            "Free equation numbering must match stable full-DOF order.");
-      }
-      ownership[full_dof] = 1U;
-    }
-    for (const std::size_t full_dof : constrained_dofs) {
-      if (full_dof >= full_count || ownership[full_dof] != 0U ||
-          dofs.FreeEquation(full_dof).has_value()) {
-        return LoadFailure(
-            "invalid-load-order", location, "LOAD_ASSEMBLER",
-            std::to_string(full_dof),
-            "Constrained DOFs must be unique and absent from free equations.");
-      }
-      ownership[full_dof] = 2U;
-    }
-  } catch (const std::out_of_range&) {
-    return LoadFailure(
-        "invalid-load-dimensions", location, "LOAD_ASSEMBLER",
-        std::to_string(full_count),
-        "DofManager equation storage must cover every full DOF.");
-  }
-  if (std::find(ownership.begin(), ownership.end(), 0U) != ownership.end()) {
-    return LoadFailure(
-        "invalid-load-order", location, "LOAD_ASSEMBLER",
-        std::to_string(full_count),
-        "Free and constrained DOFs must partition the full range.");
-  }
-  return Status::Ok();
-}
-
 Result<std::vector<EntityIndex>> ResolveTarget(
     const SourceTargetResolver& resolver, const Domain& domain,
     const NodalLoad& load) {
@@ -207,8 +134,13 @@ Result<Vector> LoadAssembler::AssembleFullNodalLoad(const AnalysisModel& model,
         "The semantic node count cannot be represented in full-DOF order."));
   }
   const std::size_t expected_full_count = domain.Nodes().size() * kDofsPerNode;
-  const Status dof_status =
-      ValidateDofOrder(dofs, expected_full_count, {domain.SourcePath(), 0U});
+  if (dofs.FullDofCount() != expected_full_count) {
+    return Result<Vector>::Failure(LoadFailure(
+        "invalid-load-dimensions", {domain.SourcePath(), 0U}, "LOAD_ASSEMBLER",
+        std::to_string(dofs.FullDofCount()),
+        "The DofManager full dimension must match the active model."));
+  }
+  const Status dof_status = dofs.ValidateInvariants();
   if (!dof_status.IsOk()) {
     return Result<Vector>::Failure(dof_status);
   }
@@ -296,7 +228,13 @@ Result<Vector> LoadAssembler::EffectiveFreeRhs(const Vector& full_load,
                                                const Vector& prescribed_values,
                                                const DofManager& dofs) {
   const SourceLocation location{{}, 0U};
-  const Status dof_status = ValidateDofOrder(dofs, full_load.Size(), location);
+  if (dofs.FullDofCount() != full_load.Size()) {
+    return Result<Vector>::Failure(
+        LoadFailure("invalid-load-dimensions", location, "LOAD_ASSEMBLER",
+                    std::to_string(dofs.FullDofCount()),
+                    "The DofManager full dimension must match the full load."));
+  }
+  const Status dof_status = dofs.ValidateInvariants();
   if (!dof_status.IsOk()) {
     return Result<Vector>::Failure(dof_status);
   }

src/fesa/constraints/essential_constraints.cpp

@@ -22,71 +22,6 @@ Status ConstraintFailure(const std::string& code, const std::string& identity,
                                                     message}});
 }
 
-bool IsStrictlyIncreasing(const std::vector<std::size_t>& values) {
-  return std::adjacent_find(
-             values.begin(), values.end(),
-             [](const std::size_t left, const std::size_t right) {
-               return left >= right;
-             }) == values.end();
-}
-
-/// @brief Validates the stable full/free/constrained numbering invariant.
-Status ValidateDofOrder(const DofManager& dofs) {
-  const std::size_t full_count = dofs.FullDofCount();
-  const auto& free_dofs = dofs.FreeDofs();
-  const auto& constrained_dofs = dofs.ConstrainedDofs();
-  if (free_dofs.size() != dofs.FreeDofCount() ||
-      constrained_dofs.size() != dofs.ConstrainedDofCount() ||
-      dofs.PrescribedValues().Size() != constrained_dofs.size() ||
-      constrained_dofs.size() > full_count ||
-      free_dofs.size() != full_count - constrained_dofs.size()) {
-    return ConstraintFailure("invalid-constraint-dimensions",
-                             std::to_string(full_count),
-                             "DofManager full, free, constrained, and "
-                             "prescribed dimensions must agree.");
-  }
-  if (!IsStrictlyIncreasing(free_dofs) ||
-      !IsStrictlyIncreasing(constrained_dofs)) {
-    return ConstraintFailure(
-        "invalid-constraint-order", std::to_string(full_count),
-        "Free and constrained DOFs must use stable increasing full-DOF order.");
-  }
-
-  std::vector<unsigned char> ownership(full_count, 0U);
-  try {
-    for (std::size_t equation = 0U; equation < free_dofs.size(); ++equation) {
-      const std::size_t full_dof = free_dofs[equation];
-      if (full_dof >= full_count || ownership[full_dof] != 0U ||
-          dofs.FreeEquation(full_dof) != equation) {
-        return ConstraintFailure(
-            "invalid-constraint-order", std::to_string(full_dof),
-            "Free equation numbering must match the stable free-DOF order.");
-      }
-      ownership[full_dof] = 1U;
-    }
-    for (const std::size_t full_dof : constrained_dofs) {
-      if (full_dof >= full_count || ownership[full_dof] != 0U ||
-          dofs.FreeEquation(full_dof).has_value()) {
-        return ConstraintFailure(
-            "invalid-constraint-order", std::to_string(full_dof),
-            "Constrained DOFs must be unique and absent from free equations.");
-      }
-      ownership[full_dof] = 2U;
-    }
-  } catch (const std::out_of_range&) {
-    return ConstraintFailure(
-        "invalid-constraint-dimensions", std::to_string(full_count),
-        "DofManager equation storage does not cover every full DOF.");
-  }
-  if (std::find(ownership.begin(), ownership.end(), 0U) != ownership.end()) {
-    return ConstraintFailure("invalid-constraint-order",
-                             std::to_string(full_count),
-                             "Free and constrained DOFs must partition the "
-                             "complete full-DOF range.");
-  }
-  return Status::Ok();
-}
-
 /// @brief Extracts one partition without changing the supplied DOF order.
 Result<SparseMatrix> ExtractBlock(const SparseMatrix& full,
                                   const std::vector<std::size_t>& row_dofs,
@@ -123,7 +58,7 @@ Result<SparseMatrix> ExtractBlock(const SparseMatrix& full,
 }
 
 void RequireDofOrder(const DofManager& dofs) {
-  if (!ValidateDofOrder(dofs).IsOk()) {
+  if (!dofs.ValidateInvariants().IsOk()) {
     throw std::invalid_argument{
         "DofManager constraint dimensions or order are invalid."};
   }
@@ -144,7 +79,7 @@ Result<PartitionedStiffness> EssentialConstraints::Partition(
         "Full stiffness must be square and match the DofManager full "
         "dimension."));
   }
-  const Status dof_status = ValidateDofOrder(dofs);
+  const Status dof_status = dofs.ValidateInvariants();
   if (!dof_status.IsOk()) {
     return Result<PartitionedStiffness>::Failure(dof_status);
   }

src/fesa/fem/dof_manager.cpp

@@ -1,8 +1,13 @@
 #include "fesa/fem/dof_manager.h"
 
 #include <algorithm>
+#include <array>
+#include <cstddef>
+#include <limits>
 #include <stdexcept>
+#include <string>
 #include <utility>
+#include <vector>
 
 #include "fesa/model/source_target_resolver.h"
 
@@ -11,6 +16,37 @@ namespace {
 
 constexpr std::size_t kDofsPerNode = 6U;
 
+Status DofFailure(const std::string& code, const SourceLocation& location,
+                  const std::string& identity, const std::string& message) {
+  return Status::Failure(
+      FailureCategory::kModel,
+      {{Severity::kError, code, location, "DOF_MANAGER", identity, message}});
+}
+
+bool SameSourceIdentity(const SourceEntityId& left,
+                        const SourceEntityId& right) {
+  return left.instance_name == right.instance_name &&
+         left.source_label == right.source_label &&
+         left.source_label_text == right.source_label_text;
+}
+
+bool IsStrictlyIncreasing(const std::vector<std::size_t>& values) {
+  return std::adjacent_find(
+             values.begin(), values.end(),
+             [](const std::size_t left, const std::size_t right) {
+               return left >= right;
+             }) == values.end();
+}
+
+bool HasAdjacentDuplicate(const std::vector<std::size_t>& values) {
+  return std::adjacent_find(values.begin(), values.end()) != values.end();
+}
+
+std::vector<DofComponent> FullNodeComponents() {
+  return {DofComponent::kUx,  DofComponent::kUy,  DofComponent::kUz,
+          DofComponent::kUrx, DofComponent::kUry, DofComponent::kUrz};
+}
+
 std::vector<EntityIndex> ExpandBoundaryTarget(
     const SourceTargetResolver& resolver, const BoundaryCondition& boundary) {
   auto resolved =
@@ -26,9 +62,8 @@ std::vector<EntityIndex> ExpandBoundaryTarget(
   return indices;
 }
 
-template <std::size_t scatter_size>
 void AppendScatter(std::vector<std::vector<std::size_t>>& columns_by_row,
-                   const std::array<std::size_t, scatter_size>& scatter) {
+                   const std::vector<std::size_t>& scatter) {
   for (const std::size_t row : scatter) {
     auto& columns = columns_by_row[row];
     columns.insert(columns.end(), scatter.begin(), scatter.end());
@@ -37,15 +72,10 @@ void AppendScatter(std::vector<std::vector<std::size_t>>& columns_by_row,
 
 /// @brief Builds sorted unique CSR columns by deterministic scatter traversal.
 SparsePattern BuildSparsePattern(
-    std::size_t full_dof_count, const std::vector<EntityIndex>& active_elements,
-    const std::vector<std::array<std::size_t, 12>>& element_scatters,
-    const std::vector<std::array<std::size_t, 24>>& shell_element_scatters) {
+    const std::size_t full_dof_count,
+    const std::vector<std::vector<std::size_t>>& element_scatters) {
   std::vector<std::vector<std::size_t>> columns_by_row(full_dof_count);
-  for (const EntityIndex element : active_elements) {
-    AppendScatter(columns_by_row, element_scatters.at(element));
-  }
-  // Every shell in the approved single-step shell subset is active.
-  for (const auto& scatter : shell_element_scatters) {
+  for (const auto& scatter : element_scatters) {
     AppendScatter(columns_by_row, scatter);
   }
 
@@ -63,17 +93,94 @@ SparsePattern BuildSparsePattern(
   return pattern;
 }
 
+template <std::size_t kSize>
+std::array<std::size_t, kSize> FixedScatter(
+    const std::vector<std::size_t>& scatter) {
+  if (scatter.size() != kSize) {
+    throw std::out_of_range{
+        "Stored element scatter does not match the compatibility shape."};
+  }
+  std::array<std::size_t, kSize> fixed{};
+  std::copy(scatter.begin(), scatter.end(), fixed.begin());
+  return fixed;
+}
+
 }  // namespace
 
 Result<DofManager> DofManager::Create(const AnalysisModel& model) {
   const Domain& domain = model.GetDomain();
+  std::vector<ElementDofLayout> layouts;
+  layouts.reserve(model.ActiveElements().size());
+  for (const EntityIndex element_index : model.ActiveElements()) {
+    if (element_index >= domain.Elements().Size()) {
+      return Result<DofManager>::Failure(
+          DofFailure("invalid-element-layout-order", {domain.SourcePath(), 0U},
+                     std::to_string(element_index),
+                     "An active element index is outside the Domain."));
+    }
+    const auto& definition = domain.Elements()[element_index];
+    layouts.push_back({definition.SourceId(), definition.NodeIndices(),
+                       FullNodeComponents()});
+  }
+
+  DofManager dofs;
+  const Status status = dofs.BuildLayouts(model, layouts);
+  if (!status.IsOk()) {
+    return Result<DofManager>::Failure(status);
+  }
+  return Result<DofManager>::Success(std::move(dofs));
+}
+
+Status DofManager::Build(const AnalysisModel& analysis_model,
+                         const ElementView& elements) {
+  std::vector<ElementDofLayout> layouts;
+  layouts.reserve(elements.size());
+  for (const auto& element : elements) {
+    layouts.push_back(element.get().DofLayout());
+  }
+  return BuildLayouts(analysis_model, layouts);
+}
+
+Status DofManager::BuildLayouts(const AnalysisModel& analysis_model,
+                                const std::vector<ElementDofLayout>& layouts) {
+  const Domain& domain = analysis_model.GetDomain();
+  if (domain.Nodes().size() >
+      (std::numeric_limits<std::size_t>::max)() / kDofsPerNode) {
+    return DofFailure(
+        "invalid-dof-dimensions", {domain.SourcePath(), 0U},
+        std::to_string(domain.Nodes().size()),
+        "The node count cannot be represented in full-DOF storage.");
+  }
+  if (layouts.size() != analysis_model.ActiveElements().size()) {
+    return DofFailure(
+        "invalid-element-layout-order", {domain.SourcePath(), 0U},
+        std::to_string(layouts.size()),
+        "Runtime elements must match the active element inventory.");
+  }
+
+  for (std::size_t source_order = 0U; source_order < layouts.size();
+       ++source_order) {
+    const EntityIndex definition_index =
+        analysis_model.ActiveElements()[source_order];
+    if (definition_index >= domain.Elements().Size() ||
+        !SameSourceIdentity(layouts[source_order].source_id,
+                            domain.Elements()[definition_index].SourceId())) {
+      return DofFailure(
+          "invalid-element-layout-order", {domain.SourcePath(), 0U},
+          std::to_string(source_order),
+          "Runtime element layouts must preserve active source order and "
+          "identity.");
+    }
+  }
+
   const SourceTargetIndex target_index = SourceTargetIndex::FromDomain(domain);
   const SourceTargetResolver target_resolver{target_index};
   const std::size_t full_count = domain.Nodes().size() * kDofsPerNode;
 
   std::vector<std::optional<double>> prescribed_by_full_dof(full_count);
-  for (const EntityIndex boundary_index : model.ActiveBoundaryConditions()) {
-    const auto& boundary = model.Step().boundaries.at(boundary_index);
+  for (const EntityIndex boundary_index :
+       analysis_model.ActiveBoundaryConditions()) {
+    const auto& boundary = analysis_model.Step().boundaries.at(boundary_index);
     const auto target = ExpandBoundaryTarget(target_resolver, boundary);
     for (const EntityIndex node : target) {
       for (int component = boundary.first_dof; component <= boundary.last_dof;
@@ -83,12 +190,12 @@ Result<DofManager> DofManager::Create(const AnalysisModel& model) {
             static_cast<std::size_t>(component - 1);
         auto& prescribed = prescribed_by_full_dof[full_dof];
         if (prescribed && *prescribed != boundary.value) {
-          return Result<DofManager>::Failure(Status::Failure(
+          return Status::Failure(
               FailureCategory::kInput,
               {{Severity::kError, "conflicting-boundary-condition",
                 boundary.location, "BOUNDARY", boundary.target,
                 "Expanded boundary rows prescribe different values to one "
-                "node/DOF."}}));
+                "node/DOF."}});
         }
         prescribed = boundary.value;
       }
@@ -119,44 +226,30 @@ Result<DofManager> DofManager::Create(const AnalysisModel& model) {
     prescribed_values[index] = constrained_values[index];
   }
 
-  std::vector<std::array<std::size_t, 12>> element_scatters(
-      domain.BeamElements().Size());
-  for (const EntityIndex element_index : model.ActiveBeamElements()) {
-    const auto& element = domain.BeamElements().At(element_index);
-    auto& scatter = element_scatters.at(element_index);
-    for (std::size_t endpoint = 0U; endpoint < element.node_indices.size();
-         ++endpoint) {
-      const std::size_t node = element.node_indices[endpoint];
-      for (std::size_t component = 0U; component < kDofsPerNode; ++component) {
-        scatter[endpoint * kDofsPerNode + component] =
-            node * kDofsPerNode + component;
-      }
+  DofManager candidate{full_count,
+                       std::move(free_equations),
+                       {},
+                       std::move(free_dofs),
+                       std::move(constrained_dofs),
+                       std::move(prescribed_values),
+                       {}};
+  candidate.element_scatters_.reserve(layouts.size());
+  for (const auto& layout : layouts) {
+    auto scatter = candidate.ElementScatter(layout);
+    if (!scatter.HasValue()) {
+      return scatter.GetStatus();
     }
+    candidate.element_scatters_.push_back(std::move(scatter.Value()));
   }
+  candidate.sparse_pattern_ =
+      BuildSparsePattern(full_count, candidate.element_scatters_);
 
-  std::vector<std::array<std::size_t, 24>> shell_element_scatters(
-      domain.ShellElements().Size());
-  for (std::size_t element_index = 0U;
-       element_index < domain.ShellElements().Size(); ++element_index) {
-    const auto& element = domain.ShellElements()[element_index];
-    auto& scatter = shell_element_scatters[element_index];
-    for (std::size_t node_position = 0U;
-         node_position < element.node_indices.size(); ++node_position) {
-      const std::size_t node = element.node_indices[node_position];
-      for (std::size_t component = 0U; component < kDofsPerNode; ++component) {
-        scatter[node_position * kDofsPerNode + component] =
-            node * kDofsPerNode + component;
-      }
-    }
+  const Status invariant_status = candidate.ValidateInvariants();
+  if (!invariant_status.IsOk()) {
+    return invariant_status;
   }
-
-  auto pattern = BuildSparsePattern(full_count, model.ActiveBeamElements(),
-                                    element_scatters, shell_element_scatters);
-  return Result<DofManager>::Success(
-      DofManager{full_count, std::move(free_equations),
-                 std::move(element_scatters), std::move(shell_element_scatters),
-                 std::move(free_dofs), std::move(constrained_dofs),
-                 std::move(prescribed_values), std::move(pattern)});
+  *this = std::move(candidate);
+  return Status::Ok();
 }
 
 std::size_t DofManager::FullDofCount() const noexcept {
@@ -171,8 +264,8 @@ std::size_t DofManager::ConstrainedDofCount() const noexcept {
   return constrained_dofs_.size();
 }
 
-std::size_t DofManager::FullDof(EntityIndex node,
-                                DofComponent component) const {
+std::size_t DofManager::FullDof(const EntityIndex node,
+                                const DofComponent component) const {
   const std::size_t component_index = static_cast<std::size_t>(component);
   if (node >= full_dof_count_ / kDofsPerNode ||
       component_index >= kDofsPerNode) {
@@ -182,18 +275,57 @@ std::size_t DofManager::FullDof(EntityIndex node,
 }
 
 std::optional<std::size_t> DofManager::FreeEquation(
-    std::size_t full_dof) const {
+    const std::size_t full_dof) const {
   return free_equations_.at(full_dof);
 }
 
-const std::array<std::size_t, 12>& DofManager::ElementScatter(
-    EntityIndex element) const {
-  return element_scatters_.at(element);
+Result<std::vector<std::size_t>> DofManager::ElementScatter(
+    const ElementDofLayout& layout) const {
+  if (layout.node_indices.empty() || layout.components_per_node.empty() ||
+      layout.node_indices.size() > (std::numeric_limits<std::size_t>::max)() /
+                                       layout.components_per_node.size()) {
+    return Result<std::vector<std::size_t>>::Failure(DofFailure(
+        "invalid-element-dof-layout", {}, layout.source_id.source_label_text,
+        "An element DOF layout requires a representable nonempty topology "
+        "and component inventory."));
+  }
+
+  std::vector<std::size_t> scatter;
+  scatter.reserve(layout.node_indices.size() *
+                  layout.components_per_node.size());
+  for (const EntityIndex node : layout.node_indices) {
+    for (const DofComponent component : layout.components_per_node) {
+      const std::size_t component_index = static_cast<std::size_t>(component);
+      if (node >= full_dof_count_ / kDofsPerNode ||
+          component_index >= kDofsPerNode) {
+        return Result<std::vector<std::size_t>>::Failure(DofFailure(
+            "invalid-element-dof-layout", {},
+            layout.source_id.source_label_text,
+            "Element node and component identities must resolve in the full "
+            "DOF range."));
+      }
+      const std::size_t full_dof =
+          static_cast<std::size_t>(node) * kDofsPerNode + component_index;
+      if (std::find(scatter.begin(), scatter.end(), full_dof) !=
+          scatter.end()) {
+        return Result<std::vector<std::size_t>>::Failure(DofFailure(
+            "duplicate-element-dof", {}, layout.source_id.source_label_text,
+            "An element layout must not repeat a full DOF."));
+      }
+      scatter.push_back(full_dof);
+    }
+  }
+  return Result<std::vector<std::size_t>>::Success(std::move(scatter));
 }
 
-const std::array<std::size_t, 24>& DofManager::ShellElementScatter(
-    EntityIndex element) const {
-  return shell_element_scatters_.at(element);
+std::array<std::size_t, 12> DofManager::ElementScatter(
+    const EntityIndex element) const {
+  return FixedScatter<12U>(element_scatters_.at(element));
+}
+
+std::array<std::size_t, 24> DofManager::ShellElementScatter(
+    const EntityIndex element) const {
+  return FixedScatter<24U>(element_scatters_.at(element));
 }
 
 const std::vector<std::size_t>& DofManager::FreeDofs() const noexcept {
@@ -212,18 +344,122 @@ const SparsePattern& DofManager::GetSparsePattern() const noexcept {
   return sparse_pattern_;
 }
 
-DofManager::DofManager(
-    std::size_t full_dof_count,
-    std::vector<std::optional<std::size_t>> free_equations,
-    std::vector<std::array<std::size_t, 12>> element_scatters,
-    std::vector<std::array<std::size_t, 24>> shell_element_scatters,
-    std::vector<std::size_t> free_dofs,
-    std::vector<std::size_t> constrained_dofs, Vector prescribed_values,
-    SparsePattern sparse_pattern)
+Status DofManager::ValidateInvariants() const {
+  if (free_equations_.size() != full_dof_count_ ||
+      free_dofs_.size() > full_dof_count_ ||
+      constrained_dofs_.size() > full_dof_count_ ||
+      free_dofs_.size() + constrained_dofs_.size() != full_dof_count_ ||
+      prescribed_values_.Size() != constrained_dofs_.size()) {
+    return DofFailure(
+        "invalid-dof-dimensions", {}, std::to_string(full_dof_count_),
+        "Full, free, constrained, prescribed, and equation dimensions must "
+        "agree.");
+  }
+  if (HasAdjacentDuplicate(free_dofs_)) {
+    return DofFailure("duplicate-dof-mapping", {},
+                      std::to_string(full_dof_count_),
+                      "Free DOF ownership must be unique.");
+  }
+  if (!IsStrictlyIncreasing(free_dofs_)) {
+    return DofFailure("invalid-free-dof-mapping", {},
+                      std::to_string(full_dof_count_),
+                      "Free DOFs must use stable increasing full-DOF order.");
+  }
+  if (HasAdjacentDuplicate(constrained_dofs_)) {
+    return DofFailure("duplicate-dof-mapping", {},
+                      std::to_string(full_dof_count_),
+                      "Constrained DOF ownership must be unique.");
+  }
+  if (!IsStrictlyIncreasing(constrained_dofs_)) {
+    return DofFailure(
+        "invalid-constrained-dof-mapping", {}, std::to_string(full_dof_count_),
+        "Constrained DOFs must use stable increasing full-DOF order.");
+  }
+
+  std::vector<unsigned char> ownership(full_dof_count_, 0U);
+  for (std::size_t equation = 0U; equation < free_dofs_.size(); ++equation) {
+    const std::size_t full_dof = free_dofs_[equation];
+    if (full_dof >= full_dof_count_) {
+      return DofFailure("invalid-free-dof-mapping", {},
+                        std::to_string(full_dof),
+                        "A free DOF is outside the full range.");
+    }
+    if (ownership[full_dof] != 0U) {
+      return DofFailure("duplicate-dof-mapping", {}, std::to_string(full_dof),
+                        "Each full DOF must have one owner.");
+    }
+    if (free_equations_[full_dof] != equation) {
+      return DofFailure(
+          "invalid-equation-mapping", {}, std::to_string(full_dof),
+          "Free equation numbering must match stable free-DOF order.");
+    }
+    ownership[full_dof] = 1U;
+  }
+  for (const std::size_t full_dof : constrained_dofs_) {
+    if (full_dof >= full_dof_count_) {
+      return DofFailure("invalid-constrained-dof-mapping", {},
+                        std::to_string(full_dof),
+                        "A constrained DOF is outside the full range.");
+    }
+    if (ownership[full_dof] != 0U) {
+      return DofFailure("duplicate-dof-mapping", {}, std::to_string(full_dof),
+                        "Each full DOF must have one owner.");
+    }
+    if (free_equations_[full_dof].has_value()) {
+      return DofFailure("invalid-equation-mapping", {},
+                        std::to_string(full_dof),
+                        "Constrained DOFs must be absent from free equations.");
+    }
+    ownership[full_dof] = 2U;
+  }
+  if (std::find(ownership.begin(), ownership.end(), 0U) != ownership.end()) {
+    return DofFailure(
+        "invalid-dof-partition", {}, std::to_string(full_dof_count_),
+        "Free and constrained DOFs must partition the complete full range.");
+  }
+
+  for (const auto& scatter : element_scatters_) {
+    if (scatter.empty()) {
+      return DofFailure("invalid-element-dof-layout", {}, {},
+                        "Stored element scatters must be nonempty.");
+    }
+    for (std::size_t position = 0U; position < scatter.size(); ++position) {
+      const std::size_t full_dof = scatter[position];
+      if (full_dof >= full_dof_count_) {
+        return DofFailure("invalid-element-dof-layout", {},
+                          std::to_string(full_dof),
+                          "Stored element scatters must stay in range.");
+      }
+      if (std::find(scatter.begin(),
+                    scatter.begin() + static_cast<std::ptrdiff_t>(position),
+                    full_dof) !=
+          scatter.begin() + static_cast<std::ptrdiff_t>(position)) {
+        return DofFailure("duplicate-element-dof", {}, std::to_string(full_dof),
+                          "Stored element scatters must remain unique.");
+      }
+    }
+  }
+
+  const SparsePattern expected_pattern =
+      BuildSparsePattern(full_dof_count_, element_scatters_);
+  if (sparse_pattern_.row_offsets != expected_pattern.row_offsets ||
+      sparse_pattern_.column_indices != expected_pattern.column_indices) {
+    return DofFailure(
+        "invalid-dof-sparse-pattern", {}, std::to_string(full_dof_count_),
+        "The CSR pattern must exactly match the stored element scatters.");
+  }
+  return Status::Ok();
+}
+
+DofManager::DofManager(const std::size_t full_dof_count,
+                       std::vector<std::optional<std::size_t>> free_equations,
+                       std::vector<std::vector<std::size_t>> element_scatters,
+                       std::vector<std::size_t> free_dofs,
+                       std::vector<std::size_t> constrained_dofs,
+                       Vector prescribed_values, SparsePattern sparse_pattern)
     : full_dof_count_{full_dof_count},
       free_equations_{std::move(free_equations)},
       element_scatters_{std::move(element_scatters)},
-      shell_element_scatters_{std::move(shell_element_scatters)},
       free_dofs_{std::move(free_dofs)},
       constrained_dofs_{std::move(constrained_dofs)},
       prescribed_values_{std::move(prescribed_values)},