Refactor Mesh Handling: Introduce an Object-Oriented Mesh Abstraction

[zasexton]

Use Case

Summary

• adding an object-oriented Mesh abstraction to decouple
  mesh representation, I/O, and solver concerns.
• Provide a stable, testable interface that can wrap existing legacy meshes
  and enable incremental migration without breaking current workflows.

Problem

Current Limitations Of mshType

• Monolithic “data bag” with wide surface area:
  • Public mutable members, little encapsulation and few invariants,
    making it easy to enter inconsistent states. See Code/Source/solver/
    ComMod.h:889.
• Unclear object semantics and ownership:
  • Copy/assignment commented out with side-effect prints, contributing to
    uncertainty about safe copying and lifetimes. See Code/Source/solver/
    ComMod.h:895 and Code/Source/solver/ComMod.h:901.
• Mixed responsibilities spread across the codebase:
  • I/O mixes parsing, face-node/element mapping, and basis/face setup
    within one path (hard to test or swap out):
    • VTP read: Code/Source/solver/load_msh.cpp:266
    • Face-node/element mapping by coordinate hashing: Code/Source/solver/
      load_msh.cpp:284
    • Face basis setup: Code/Source/solver/load_msh.cpp:324
  • VTU read directly populates legacy structures, tying representation to
    reader details: Code/Source/solver/vtk_xml.cpp:560.
  • Basis/quadrature selection is driven externally and tied to ComMod +
    mshType, rather than a small dedicated interface: Code/Source/solver/
    nn.h:76.
• Tight solver coupling:
  • Many solver routines expect mshType and global arrays in ComMod,
    complicating isolated testing and making refactors risky.
• Harder evolution for new capabilities:
  • Adding higher-order elements, alternative readers, or extra per-node/
    per-element fields touches many call sites.
  • Partitioning/adjacency and face handling live inside or adjacent to
    mshType, increasing cognitive load and coupling.

Solution

Goals

• Define a Mesh interface that:

  • Encapsulates geometry/topology (coordinates, connectivity, element meta)
    with const-correct accessors.
  • Is reader-agnostic (VTU/VTP/Gmsh or other sources), with pluggable
    readers.
  • Can wrap the legacy mshType (non-owning view) to support incremental
    adoption.
  • Separates core representation from basis/quadrature and solver state.
  • Supports attaching read-only or mutable fields via clear APIs.

• Improve testability and maintainability with narrower and clearer contracts.

Non-Goals

• Do not change solver algorithms or numerical methods in this refactor.
• Do not remove mshType immediately; instead, provide an adapter path and
  migrate progressively.

Alternatives considered

• Incrementally improving mshType in place.
  • Rejected for this scope: preserves coupling and broad surface area;
    harder to converge on strict invariants and clear API.
• Widespread usage of mshType increases migration complexity.
  • Mitigation: Provide adapters/wrappers so adoption can be piecemeal.
• Potential performance concerns during transition.
  • Mitigation: Keep data layout compatible and avoid unnecessary copies;
    measure and adjust.

Additional context

Milestones

• Define Mesh interface and adapters (non-owning wrapper over mshType).
• Add pluggable readers that populate Mesh without altering solvers.
• Provide utilities for face mapping and basis setup decoupled from I/O.
• Incremental solver touchpoints: switch read-only consumers to the Mesh
  interface.
• Document interface and migration guidelines.

Success criteria

• A Mesh abstraction exists with:
  • Clear, minimal API for geometry/topology and metadata.
  • Capability to wrap mshType safely for incremental migration.
  • At least one reader (VTK) that produces a Mesh without touching solver
    code.
• No regression in existing workflows; tests (unit or integration) confirm
  backward compatibility.
• Documentation describing responsibilities, invariants, and migration
  patterns.

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines

[aabrown100-git]

Thanks @zasexton! I think you touched on it, but the parallelization/partitioning on the mesh is currently extremely confusing with terrible names for different sets of indices. It would be great to clarify this aspect in this refactor.

[zasexton]

Yes, I think my goal here will be to isolate the parallelization and mesh partitioning from this class implementation which should instead focus on a clear but extensible way to house and verify valid meshes.

[zasexton]

So in general we have these design goals for our new Mesh class:

• Extensible: physics-agnostic, arbitrary element shapes, various IO formats (although right now we will primarily ensure VTK compatibility)
• Separation of concerns: topology vs geometry; serial vs parallel; mesh vs FE spaces
• HPC ready: cache‑friendly storage, partitioned topology
• Geometry flexibility: linear and high‑order (isoparametric/curvilinear), reference vs current config for ALE/FSI
• Labeling & Markers: parent/child lineage, markers, subdomains, boundaries, interfaces

[zasexton]

Attaching a terminology document for this refactoring. This will point out key works and their relevant contexts when referring to Mesh APIs.

TERMINOLOGY.md

[ktbolt]

@zasexton I thought the initial refactoring effort was supposed to be related to creating a solver class ? Are you not thinking about that ?