test: mixed-dimensional consistency

[OmarDuran]

This PR introduces a new suite of integration tests designed to verify the consistency and correctness of several core capabilities: the Finite Element Method (FEM) mechanical solver SolidMechanicsAugmentedLagrangianContact, single-phase flow, compositional hydrostatic equilibrium, and the workflow for defining fractures using the SurfaceGenerator class.

These tests specifically target the solution of mixed-dimensional problems generated with the internal Surface Generator, where fractures (2D entities) are conformal within a 3D matrix mesh. The test suite also includes verification of the topological modifications induced in the mesh by fracture generation.

Among its key benefits, this PR enables a more robust initialization procedure for mechanical problems with fractures. It allows for the following workflow: initialize the intact rock problem, perform a fracturing step (generation of fractures), initialize fracture tractions based on the already computed surrounding stress, and finally equilibrate the entire system with fractures before the actual dynamic simulation.

<Events minTime="0.0" maxTime="1.0">
    <SoloEvent name="IntactRockInitialization" targetTime="0.0" beginTime="0.0" target="/Tasks/PRE.SPLIT.STEP"/>
    <SoloEvent name="FracturingStep" target="/Solvers/SurfaceGen" targetTime="0.0" beginTime="0.0"/> 
    <SoloEvent name="FracturedRockInitialization" targetTime="0.0" beginTime="0.0" target="/Tasks/POST.SPLIT.STEP"/>
    <PeriodicEvent name="solverApplications" target="/Solvers/mechSolver" forceDt="1.0"/>
</Events>

The following four C++ integration test files are introduced; all other code modifications are strictly test-driven and were required to support these new integration tests.

All simulations shown in the image sequence were executed using 12 MPI ranks.
C1: Mesh configuration containing five fractures with no topological connection to the domain boundary.
(Expected Euler characteristic of the resulting 3D mesh: 2)

C2: Mesh configuration containing three intersecting fractures that are topologically connected to the domain boundary.
(Expected Euler characteristic of the resulting 3D mesh: 8)

C3: Mesh configuration containing three perfectly aligned fractures.
(Expected Euler characteristic of the resulting 3D mesh: 2)

Test description

testFEMConsistency.cpp (Serial and MPI test)

The test ensures that the mechanical solvers preserve stress equilibrium and correctly handle contact/interface conditions across different mesh types and fracture configurations.

The physical setup corresponds to a pure compression case (-10 [MPa]), with no shear induced by the boundary conditions. As a result, the stress field is constant, which allows for direct verification. For volume elements, the averaged computed stress tensor is checked against the applied boundary tractions. For fracture surfaces, the traction vector
𝑡=𝜎⋅𝑛 is applied neighboring volume cells onto the fracture faces, computed, and verified on both sides of the fracture against the expected traction. The value of the normal traction (-10 [MPa]) can be easily verified because the loading condition is hydrostatic and the displacement solution is trilinear and exact.
The test ensures that the mechanical solvers preserve stress equilibrium and correctly handle contact/interface conditions across different mesh types and fracture configurations.

Regardless of the DFN geometry, the normal traction is -10[MPa] and the displacement jump is zero; that is, continuity of stresses and displacements is obtained:
C1

C2

testMixedDimHydrostaticEquilibrium.cpp (Serial and MPI test)

This test verifies that a hydrostatic equilibrium state defined in both the matrix (3D elements) and fractures (2D elements) with compatible boundary conditions, it is indeed a valid solution of the underlying mixed-dimensional equilibrium problem.

Because the system is initialized exactly at equilibrium, executing a single simulation step should not modify the solution regardless of the time step size. The test therefore checks that the numerical solver preserves the hydrostatic state without introducing spurious pressure or saturation changes.

Regardless of the DFN geometry, saturation and pressure on fractures and matrix should be aligned:
C1

C2

testMixedDimSinglePhaseFlow.cpp (Serial and MPI test)

This test verifies that the single-phase flow solver reproduces exact linear pressure solutions in mixed-dimensional settings. It ensures that the solver correctly handles contact and interface conditions between matrix and fracture elements across different mesh configurations, while preserving the exactness of the analytical pressure solution.

C3 satisfies K-orthogonality; therefore, exactness in linear pressure solutions is expected:

testSurfaceGenerator.cpp (Serial and MPI test)

This test validates the correctness of the Surface Generator by ensuring that the mesh undergoes the expected topological modifications during fracture generation.

The tests cover a variety of fracture configurations and fracture networks (62 configurations), which are compiled in the following directory:src/coreComponents/integrationTests/meshTests/dfn_market. It verifies:

• The expected number of fractures created in the mesh
• The correct duplication of nodes required for fracture separation
• The Euler characteristic of the mesh before and after the split, ensuring that the topological transformation is consistent

Special acknowledgments to @rrsettgast for his guidance and suggestions during the implementation of these changes, and to @castelletto1 for providing the five-fracture mesh configurations.

GEOS-DEV/LvArray#354

[codecov]

Codecov Report

❌ Patch coverage is 79.65368% with 188 lines in your changes missing coverage. Please review.
✅ Project coverage is 64.07%. Comparing base (2b691d5) to head (68d1450).

Files with missing lines	Patch %	Lines
.../coreComponents/physicsSolvers/FieldApplicator.cpp	31.89%	126 Missing ⚠️
...tegrationTests/mechanicTest/testFEMConsistency.cpp	93.83%	13 Missing ⚠️
...idFlowTests/testMixedDimHydrostaticEquilibrium.cpp	85.71%	12 Missing ⚠️
...sicsSolvers/surfaceGeneration/SurfaceGenerator.cpp	85.33%	11 Missing ⚠️
...lvers/multiphysics/PoromechanicsInitialization.cpp	0.00%	8 Missing ⚠️
...ntact/SolidMechanicsAugmentedLagrangianContact.cpp	94.73%	8 Missing ⚠️
...rs/solidMechanics/SolidMechanicsInitialization.cpp	91.30%	4 Missing ⚠️
...sts/fluidFlowTests/testMixedDimSinglePhaseFlow.cpp	96.82%	2 Missing ⚠️
src/coreComponents/dataRepository/Group.cpp	66.66%	1 Missing ⚠️
...ents/mesh/mpiCommunications/CommunicationTools.cpp	50.00%	1 Missing ⚠️
... and 2 more

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #3957      +/-   ##
===========================================
+ Coverage    58.87%   64.07%   +5.19%     
===========================================
  Files         1356     1363       +7     
  Lines       113234   114086     +852     
===========================================
+ Hits         66668    73097    +6429     
+ Misses       46566    40989    -5577     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Adds a new mixed-dimensional integration test suite (serial + MPI) for fractured meshes generated via SurfaceGenerator, and introduces supporting runtime/test infrastructure changes needed to make those tests reliable and deterministic in parallel.

Changes:

• Adds new integration tests for FEM contact consistency, mixed-dim hydrostatic equilibrium, mixed-dim single-phase flow, and SurfaceGenerator topology validation (plus MPI variants).
• Improves robustness/determinism for parallel mesh/topology workflows (graph coloring validity, neighbor-rank detection, ParMETIS empty-rank handling, additional profiling markers).
• Adds new tasks/utilities to support initialization workflows with fractures (e.g., SolidMechanicsInitialization, FieldApplicator) and optional Euler characteristic validation after mesh load.

Reviewed changes

Copilot reviewed 141 out of 145 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
src/uncrustify.cfg	Updates execution-context tokens for formatting.
src/docs/sphinx/basicExamples/hydraulicFracturing/Example.rst	Documents SurfaceGenerator logging behavior.
src/coreComponents/physicsSolvers/surfaceGeneration/SurfaceGenerator.hpp	Refactors/extends fracture grouping + BFS location assignment APIs; adds helpers/state.
src/coreComponents/physicsSolvers/surfaceGeneration/ParallelTopologyChangeNoFixup.cpp	Adds profiling marker.
src/coreComponents/physicsSolvers/surfaceGeneration/ParallelTopologyChange.cpp	Adds CUDA error/status checks + profiling markers around pack/unpack/sync.
src/coreComponents/physicsSolvers/solidMechanics/contact/kernels/SolidMechanicsALMSimultaneousKernels.hpp	Guards divide-by-zero on face area in contact kernel.
src/coreComponents/physicsSolvers/solidMechanics/contact/SolidMechanicsLagrangeContactBubbleStab.cpp	Fixes/extends contact setup for fracture meshes; adds GPU/host movement fixes.
src/coreComponents/physicsSolvers/solidMechanics/contact/SolidMechanicsLagrangeContact.cpp	Registers default pressure fields for coupling; removes dead code/comments.
src/coreComponents/physicsSolvers/solidMechanics/contact/SolidMechanicsAugmentedLagrangianContact.hpp	Declares traction initialization from adjacent-cell stress.
src/coreComponents/physicsSolvers/solidMechanics/SolidMechanicsStateReset.hpp	Grants SolidMechanicsInitialization friend access.
src/coreComponents/physicsSolvers/solidMechanics/SolidMechanicsInitialization.hpp	New task for solid-mechanics-only stress initialization workflow.
src/coreComponents/physicsSolvers/solidMechanics/SolidMechanicsInitialization.cpp	Implements new initialization task + catalog registration.
src/coreComponents/physicsSolvers/solidMechanics/CMakeLists.txt	Wires new initialization task into build.
src/coreComponents/physicsSolvers/multiphysics/PoromechanicsInitialization.hpp	Adds reset_displacements option.
src/coreComponents/physicsSolvers/multiphysics/PoromechanicsInitialization.cpp	Makes displacement reset optional via new flag.
src/coreComponents/physicsSolvers/fluidFlow/SinglePhaseBase.hpp	Moves applyDeltaVolume out of SinglePhaseBase.
src/coreComponents/physicsSolvers/fluidFlow/SinglePhaseBase.cpp	Removes old applyDeltaVolume implementation.
src/coreComponents/physicsSolvers/fluidFlow/FlowSolverBase.hpp	Adds FlowSolverBase::applyDeltaVolume.
src/coreComponents/physicsSolvers/fluidFlow/FlowSolverBase.cpp	Implements FlowSolverBase::applyDeltaVolume.
src/coreComponents/physicsSolvers/FieldApplicator.hpp	New task to apply field specs to dynamically created elements.
src/coreComponents/physicsSolvers/FieldApplicator.cpp	Implements/catalogns FieldApplicator including equilibrium re-init delegation.
src/coreComponents/physicsSolvers/CMakeLists.txt	Adds FieldApplicator to build.
src/coreComponents/mesh/mpiCommunications/CommunicationTools.cpp	Adds profiling markers for global-index assignment.
src/coreComponents/mesh/graphs/RLFGraphColoringMPI.cpp	Symmetrizes gathered MPI graph before coloring.
src/coreComponents/mesh/graphs/GraphColoringBase.cpp	Replaces fragile p2p validation with allgather-based validation.
src/coreComponents/mesh/generators/VTKUtilities.cpp	Improves bounding-box inflation robustness for neighbor detection.
src/coreComponents/mesh/generators/ParMETISInterface.cpp	Adds dummy pointers to survive empty-rank ParMETIS collectives.
src/coreComponents/mesh/generators/MeshGeneratorBase.hpp	Declares Euler characteristic utility + adds optional check flag.
src/coreComponents/mesh/generators/MeshGeneratorBase.cpp	Implements Euler characteristic computation and XML flag registration.
src/coreComponents/mesh/SurfaceElementRegion.hpp	Adds SurfaceElementRegion::updateSets.
src/coreComponents/mesh/SurfaceElementRegion.cpp	Implements updateSets; adds profiling markers.
src/coreComponents/mesh/ParticleSubRegionBase.cpp	Fixes lambda bracing/formatting.
src/coreComponents/mesh/ParticleRegion.cpp	Fixes lambda bracing/formatting.
src/coreComponents/mesh/ObjectManagerBase.cpp	Adds profiling marker in splitObject.
src/coreComponents/mesh/NodeManager.hpp	Declares NodeManager::reserve override.
src/coreComponents/mesh/NodeManager.cpp	Implements reserve; adds profiling marker in resize.
src/coreComponents/mesh/FaceManager.hpp	Declares FaceManager::reserve override.
src/coreComponents/mesh/FaceManager.cpp	Implements reserve; refactors geometry compute to use views; adds profiling markers.
src/coreComponents/mesh/FaceElementSubRegion.hpp	Adds kf1 node ordering helper.
src/coreComponents/mesh/FaceElementSubRegion.cpp	Improves normal/orientation robustness; implements kf1 node reordering.
src/coreComponents/mesh/EdgeManager.hpp	Declares EdgeManager::reserve override.
src/coreComponents/mesh/EdgeManager.cpp	Implements reserve; adds profiling markers; fixes unused param handling.
src/coreComponents/mainInterface/ProblemManager.cpp	Adds optional Euler characteristic validation + enforces kf1 ordering after split.
src/coreComponents/linearAlgebra/interfaces/trilinos/EpetraMatrix.cpp	Guards scaling computation for near-zero weights.
src/coreComponents/linearAlgebra/interfaces/petsc/PetscMatrix.cpp	Guards scaling computation for near-zero weights.
src/coreComponents/linearAlgebra/DofManagerHelpers.hpp	Skips invalid indices in ghost/visited logic.
src/coreComponents/integrationTests/meshTests/CMakeLists.txt	Adds testSurfaceGenerator + copies DFN meshes at configure time; adds MPI variant.
src/coreComponents/integrationTests/mechanicTest/testFEMConsistency.cpp	New serial FEM consistency test runner/instantiation.
src/coreComponents/integrationTests/mechanicTest/testFEMConsistency_mpi.cpp	New MPI FEM consistency test runner/instantiation.
src/coreComponents/integrationTests/mechanicTest/CMakeLists.txt	New mechanicTest test target wiring + mesh asset copying.
src/coreComponents/integrationTests/fluidFlowTests/testMixedDimSinglePhaseFlow.cpp	New serial mixed-dim single-phase flow test runner/instantiation.
src/coreComponents/integrationTests/fluidFlowTests/testMixedDimSinglePhaseFlow_mpi.cpp	New MPI mixed-dim single-phase flow test runner/instantiation.
src/coreComponents/integrationTests/fluidFlowTests/testMixedDimHydrostaticEquilibrium.cpp	New serial mixed-dim hydrostatic equilibrium test runner/instantiation.
src/coreComponents/integrationTests/fluidFlowTests/testMixedDimHydrostaticEquilibrium_mpi.cpp	New MPI mixed-dim hydrostatic equilibrium test runner/instantiation.
src/coreComponents/integrationTests/fluidFlowTests/testFixedDimensionalHydrostaticEquilibrium.cpp	Adds/updates fixed-dimensional hydrostatic equilibrium test runner.
src/coreComponents/integrationTests/fluidFlowTests/CMakeLists.txt	Wires new mixed-dim flow tests + mesh copying.
src/coreComponents/integrationTests/CMakeLists.txt	Adds mechanicTest subdirectory.
src/coreComponents/finiteVolume/TwoPointFluxApproximation.cpp	Makes transmissibility multiplier optional (wrapper may not exist).
src/coreComponents/fileIO/silo/SiloFile.cpp	Adjusts Silo node ordering for FaceElementSubRegion; formatting fixes.
src/coreComponents/dataRepository/wrapperHelpers.hpp	Extends reserve() helper to also reserve value storage when available.
src/coreComponents/dataRepository/unitTests/testErrorHandling.cpp	Adds missing include.
src/coreComponents/dataRepository/Group.cpp	Adds profiling marker; fixes reserve behavior for sized subgroups.
src/coreComponents/common/GeosxMacros.hpp	Adds NVCC diagnostic suppression helper macros.
src/coreComponents/codingUtilities/traits.hpp	Adds reserveValues trait detection.
src/coreComponents/codingUtilities/Utilities.hpp	Formatting fixes in small RAJA utilities.
src/cmake/GeosxVersion.cmake	Makes git version metadata optional.
src/cmake/GeosxOptions.cmake	Adds option to toggle git version metadata querying.
BASELINE_NOTES.md	Updates baseline notes.
.integrated_tests.yaml	Updates integrated test baseline pointer.
src/coreComponents/integrationTests/meshTests/dfn_market/*.vtu	Adds DFN-market VTK mesh assets used by the new test suite.

[OmarDuran]

At the current time, Copilot’s reviews and suggestions are far from correct. It seems the quality of such AI reviews degenerates with the amount of modifications and the complexity of the codebase.