Introduce inclusion_mapping operation

cpp/doc/source/api.rst

@@ -14,6 +14,7 @@ generated documentation is `here <doxygen>`_.
    io
    la
    mesh
+   multigrid
    refinement
 
 * :ref:`genindex`

cpp/doc/source/multigrid.rst

@@ -0,0 +1,5 @@
+Multigrid (``dolfinx::multigrid``)
+====================================
+
+.. doxygennamespace:: dolfinx::multigrid
+   :project: DOLFINx

cpp/dolfinx/CMakeLists.txt

@@ -17,6 +17,7 @@ set(DOLFINX_DIRS
     io
     la
     mesh
+    multigrid
     nls
     refinement
 )

cpp/dolfinx/multigrid/CMakeLists.txt

@@ -0,0 +1,9 @@
+set(HEADERS_multigrid
+    ${CMAKE_CURRENT_SOURCE_DIR}/inclusion.h
+    PARENT_SCOPE
+)
+
+target_sources(
+  dolfinx
+  PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/inclusion.cpp
+)

cpp/dolfinx/multigrid/dolfinx_multigrid.h

@@ -0,0 +1,11 @@
+#pragma once
+
+/// @brief Multigrid algorithms.
+///
+namespace dolfinx::multigrid
+{
+}
+
+// DOLFINx multigrid interface
+
+#include <dolfinx/multigrid/inclusion.h>

cpp/dolfinx/multigrid/inclusion.cpp

@@ -0,0 +1,78 @@
+// Copyright (C) 2025 Paul T. Kühner
+//
+// This file is part of DOLFINX (https://www.fenicsproject.org)
+//
+// SPDX-License-Identifier:    LGPL-3.0-or-later
+
+#include "inclusion.h"
+
+#include <algorithm>
+#include <concepts>
+#include <cstdint>
+#include <iterator>
+#include <vector>
+
+#include <mpi.h>
+
+#include "dolfinx/common/IndexMap.h"
+#include "dolfinx/la/SparsityPattern.h"
+#include "dolfinx/mesh/Mesh.h"
+
+namespace dolfinx::multigrid
+{
+
+template <std::floating_point T>
+std::vector<std::int32_t>
+inclusion_mapping(const dolfinx::mesh::Mesh<T>& mesh_from,
+                  const dolfinx::mesh::Mesh<T>& mesh_to)
+{
+  {
+    // Check comms equal
+    int result;
+    MPI_Comm_compare(mesh_from.comm(), mesh_to.comm(), &result);
+    assert(result == MPI_CONGRUENT);
+  }
+
+  const common::IndexMap& im_from = *mesh_from.topology()->index_map(0);
+  const common::IndexMap& im_to = *mesh_to.topology()->index_map(0);
+
+  std::vector<std::int32_t> map(im_from.size_local() + im_from.num_ghosts(),
+                                -1);
+
+  std::span<const T> x_from = mesh_from.geometry().x();
+  std::span<const T> x_to = mesh_to.geometry().x();
+
+  for (std::int32_t i = 0; i < im_from.size_local() + im_from.num_ghosts(); i++)
+  {
+    std::ranges::subrange vertex_from(std::next(x_from.begin(), 3 * i),
+                                      std::next(x_from.begin(), 3 * (i + 1)));
+    for (std::int32_t j = 0; j < im_to.size_local() + im_to.num_ghosts(); j++)
+    {
+      std::ranges::subrange vertex_to(std::next(x_to.begin(), 3 * j),
+                                      std::next(x_to.begin(), 3 * (j + 1)));
+
+      if (std::ranges::equal(
+              vertex_from, vertex_to, [](auto a, auto b)
+              { return std::abs(a - b) <= std::numeric_limits<T>::epsilon(); }))
+      {
+        assert(map[i] == -1);
+        map[i] = j;
+        break;
+      }
+    }
+  }
+
+  return map;
+}
+
+/// @cond
+template std::vector<std::int32_t>
+inclusion_mapping<float>(const dolfinx::mesh::Mesh<float>& mesh_from,
+                         const dolfinx::mesh::Mesh<float>& mesh_to);
+
+template std::vector<std::int32_t>
+inclusion_mapping<double>(const dolfinx::mesh::Mesh<double>& mesh_from,
+                          const dolfinx::mesh::Mesh<double>& mesh_to);
+/// @endcond
+
+} // namespace dolfinx::multigrid

cpp/dolfinx/multigrid/inclusion.h

@@ -0,0 +1,39 @@
+// Copyright (C) 2025 Paul T. Kühner
+//
+// This file is part of DOLFINX (https://www.fenicsproject.org)
+//
+// SPDX-License-Identifier:    LGPL-3.0-or-later
+
+#pragma once
+
+#include <concepts>
+#include <cstdint>
+#include <vector>
+
+#include "dolfinx/mesh/Mesh.h"
+
+namespace dolfinx::multigrid
+{
+
+/// @brief Computes an inclusion map: a map between vertex indices from one mesh
+/// to another.
+///
+/// @param mesh_from Domain of the map
+/// @param mesh_to Range of the map
+///
+/// @return Inclusion map, the `i`-th component is the vertex index of the
+/// vertex with the same coordinates in `mesh_to` and `-1` if it can not be
+/// found (locally!) in `mesh_to`. If `map[i] != -1` it holds
+/// `mesh_from.geometry.x()[i:i+3] == mesh_to.geometry.x()[map[i]:map[i]+3]`.
+///
+/// @note Invoking `inclusion_map` on a `(mesh_coarse, mesh_fine)` tuple, where
+/// `mesh_fine` is produced by refinement with
+/// `IdentityPartitionerPlaceholder()` option, the returned `map` is guaranteed
+/// to match all vertices for all locally owned vertices (not for the ghost
+/// vertices).
+template <std::floating_point T>
+std::vector<std::int32_t>
+inclusion_mapping(const dolfinx::mesh::Mesh<T>& mesh_from,
+                  const dolfinx::mesh::Mesh<T>& mesh_to);
+
+} // namespace dolfinx::multigrid

cpp/test/CMakeLists.txt

@@ -67,6 +67,7 @@ add_executable(
   mesh/refinement/interval.cpp
   mesh/refinement/option.cpp
   mesh/refinement/rectangle.cpp
+  multigrid/inclusion.cpp
   ${CMAKE_CURRENT_BINARY_DIR}/expr.c
   ${CMAKE_CURRENT_BINARY_DIR}/poisson.c
 )

cpp/test/multigrid/inclusion.cpp

@@ -0,0 +1,111 @@
+// Copyright (C) 2025 Paul T. Kühner
+//
+// This file is part of DOLFINX (https://www.fenicsproject.org)
+//
+// SPDX-License-Identifier:    LGPL-3.0-or-later
+
+#include <array>
+#include <concepts>
+#include <cstddef>
+#include <cstdint>
+#include <optional>
+#include <variant>
+#include <vector>
+
+#include <mpi.h>
+
+#include <catch2/catch_approx.hpp>
+#include <catch2/catch_template_test_macros.hpp>
+#include <catch2/catch_test_macros.hpp>
+#include <catch2/matchers/catch_matchers_range_equals.hpp>
+
+#include <basix/cell.h>
+
+#include <dolfinx/mesh/Mesh.h>
+#include <dolfinx/mesh/generation.h>
+#include <dolfinx/mesh/utils.h>
+#include <dolfinx/multigrid/inclusion.h>
+#include <dolfinx/refinement/refine.h>
+
+using namespace dolfinx;
+using namespace Catch::Matchers;
+
+template <std::floating_point T>
+void CHECK_inclusion_map(const mesh::Mesh<T>& mesh_coarse,
+                         const mesh::Mesh<T>& mesh_fine,
+                         const std::vector<std::int32_t>& map)
+{
+  const common::IndexMap& im_from = *mesh_coarse.topology()->index_map(0);
+  const common::IndexMap& im_to = *mesh_fine.topology()->index_map(0);
+  CHECK(
+      map.size()
+      == static_cast<std::size_t>(im_from.size_local() + im_from.num_ghosts()));
+  for (std::size_t i = 0; i < map.size(); i++)
+  {
+    if (map[i] == -1)
+      continue;
+
+    CHECK(0 <= map[i]);
+    CHECK(map[i] <= im_to.size_local() + im_to.num_ghosts());
+
+    auto x = std::array{mesh_coarse.geometry().x()[3 * i],
+                        mesh_coarse.geometry().x()[3 * i + 1],
+                        mesh_coarse.geometry().x()[3 * i + 2]};
+    auto global_x = std::array{mesh_fine.geometry().x()[3 * map[i]],
+                               mesh_fine.geometry().x()[3 * map[i] + 1],
+                               mesh_fine.geometry().x()[3 * map[i] + 2]};
+
+    CHECK_THAT(x, Catch::Matchers::RangeEquals(global_x));
+  }
+}
+
+template <std::floating_point T>
+void TEST_inclusion(dolfinx::mesh::Mesh<T>&& mesh_coarse)
+{
+  mesh_coarse.topology()->create_entities(1);
+
+  std::array<std::variant<refinement::IdentityPartitionerPlaceholder,
+                          mesh::CellPartitionFunction>,
+             3>
+      ghost_modes
+      = {mesh::create_cell_partitioner(mesh::GhostMode::none),
+         mesh::create_cell_partitioner(mesh::GhostMode::shared_facet),
+         refinement::IdentityPartitionerPlaceholder()};
+  for (const auto& ghost_mode : ghost_modes)
+  {
+    auto [mesh_fine, parent_cell, parent_facet]
+        = refinement::refine(mesh_coarse, std::nullopt, ghost_mode);
+    mesh_fine.topology()->create_connectivity(1, 0);
+    mesh_fine.topology()->create_connectivity(0, 1);
+    std::vector<std::int32_t> inclusion_map
+        = multigrid::inclusion_mapping(mesh_coarse, mesh_fine);
+
+    if (std::holds_alternative<refinement::IdentityPartitionerPlaceholder>(
+            ghost_mode))
+      CHECK(std::ranges::all_of(inclusion_map, [](auto e) { return e >= 0; }));
+
+    CHECK_inclusion_map(mesh_coarse, mesh_fine, inclusion_map);
+  }
+}
+
+TEMPLATE_TEST_CASE("Inclusion (interval)", "[multigrid][inclusion]", double,
+                   float)
+{
+  TEST_inclusion(
+      dolfinx::mesh::create_interval<TestType>(MPI_COMM_WORLD, 10, {0.0, 1.0}));
+}
+
+TEMPLATE_TEST_CASE("Inclusion (triangle)", "[multigrid][inclusion]", double,
+                   float)
+{
+  TEST_inclusion(dolfinx::mesh::create_rectangle<TestType>(
+      MPI_COMM_WORLD, {{{0, 0}, {1, 1}}}, {5, 5}, mesh::CellType::triangle));
+}
+
+TEMPLATE_TEST_CASE("Inclusion (tetrahedron)", "[multigrid][inclusion]", double,
+                   float)
+{
+  TEST_inclusion(dolfinx::mesh::create_box<TestType>(
+      MPI_COMM_WORLD, {{{0, 0, 0}, {1, 1, 1}}}, {5, 5, 5},
+      mesh::CellType::tetrahedron));
+}

python/CMakeLists.txt

@@ -53,6 +53,7 @@ nanobind_add_module(
   dolfinx/wrappers/la.cpp
   dolfinx/wrappers/log.cpp
   dolfinx/wrappers/mesh.cpp
+  dolfinx/wrappers/multigrid.cpp
   dolfinx/wrappers/petsc.cpp
   dolfinx/wrappers/refinement.cpp
 )

python/dolfinx/multigrid.py

@@ -0,0 +1,43 @@
+# Copyright (C) 2025 Paul T. Kühner
+#
+# This file is part of DOLFINx (https://www.fenicsproject.org)
+#
+# SPDX-License-Identifier:    LGPL-3.0-or-later
+
+import numpy as np
+from numpy.typing import NDArray
+
+from dolfinx.cpp.multigrid import inclusion_mapping_float32 as _inclusion_mapping_float32
+from dolfinx.cpp.multigrid import inclusion_mapping_float64 as _inclusion_mapping_float64
+from dolfinx.mesh import Mesh
+
+__all__ = ["inclusion_mapping"]
+
+
+def inclusion_mapping(mesh_from: Mesh, mesh_to: Mesh) -> NDArray[np.int64]:
+    """Computes an inclusion map: a map between vertex indices from one
+    mesh to another.
+
+    Args:
+        mesh_from: Domain of the map.
+        mesh_to: Range of the map.
+
+    Returns:
+        Inclusion map, the `i`-th component is the vertex index of the
+        vertex with the same coordinates in `mesh_to` and `-1` if it can
+        not be found (locally!) in `mesh_to`. If `map[i] != -1` it holds
+        `mesh_from.geometry.x[i] == mesh_to.geometry.x[map[i]]`.
+
+    Note:
+        Invoking `inclusion_map` on a `(mesh_coarse, mesh_fine)` tuple,
+        where `mesh_fine` is produced by refinement with
+        `IdentityPartitionerPlaceholder()`option, the returned `map` is
+        guaranteed to match all vertices for all locally owned vertices
+        (not for the ghost vertices).
+    """
+    if np.issubdtype(mesh_from.geometry.x.dtype, np.float32):
+        return _inclusion_mapping_float32(mesh_from._cpp_object, mesh_to._cpp_object)
+    elif np.issubdtype(mesh_from.geometry.x.dtype, np.float64):
+        return _inclusion_mapping_float64(mesh_from._cpp_object, mesh_to._cpp_object)
+    else:
+        raise RuntimeError("Unsupported mesh dtype.")

python/dolfinx/wrappers/dolfinx.cpp

@@ -25,6 +25,8 @@ void la(nb::module_& m);
 void mesh(nb::module_& m);
 void nls(nb::module_& m);
 void refinement(nb::module_& m);
+void multigrid(nb::module_& m);
+
 } // namespace dolfinx_wrappers
 
 NB_MODULE(cpp, m)
@@ -74,6 +76,10 @@ NB_MODULE(cpp, m)
   nb::module_ refinement = m.def_submodule("refinement", "Refinement module");
   dolfinx_wrappers::refinement(refinement);
 
+  // Create multigrid submodule
+  nb::module_ multigrid = m.def_submodule("multigrid", "Multigrid module");
+  dolfinx_wrappers::multigrid(multigrid);
+
 #if defined(HAS_PETSC) && defined(HAS_PETSC4PY)
   // PETSc-specific wrappers
   nb::module_ nls = m.def_submodule("nls", "Nonlinear solver module");

python/dolfinx/wrappers/multigrid.cpp

@@ -0,0 +1,42 @@
+// Copyright (C) 2025 Paul T. Kühner
+//
+// This file is part of DOLFINX (https://www.fenicsproject.org)
+//
+// SPDX-License-Identifier:    LGPL-3.0-or-later
+
+#include <concepts>
+
+#include <nanobind/nanobind.h>
+#include <nanobind/stl/vector.h>
+
+#include <dolfinx/la/MatrixCSR.h>
+#include <dolfinx/multigrid/inclusion.h>
+
+#include "dolfinx_wrappers/array.h"
+
+namespace nb = nanobind;
+
+namespace dolfinx_wrappers
+{
+
+template <std::floating_point T>
+void declare_inlcusion_mapping(nb::module_& m, const std::string& type)
+{
+  m.def(("inclusion_mapping_" + type).c_str(),
+        [](const dolfinx::mesh::Mesh<T>& mesh_from,
+           const dolfinx::mesh::Mesh<T>& mesh_to)
+        {
+          return dolfinx_wrappers::as_nbarray(
+              dolfinx::multigrid::inclusion_mapping<T>(mesh_from, mesh_to));
+        },
+        nb::arg("mesh_from"), nb::arg("mesh_to"),
+        "Computes inclusion mapping between two meshes");
+}
+
+void multigrid(nb::module_& m)
+{
+  declare_inlcusion_mapping<float>(m, "float32");
+  declare_inlcusion_mapping<double>(m, "float64");
+}
+
+} // namespace dolfinx_wrappers