Make topology const in locate_dofs_topological (#2885)

* use const modifier for topology

* add more const

* change from assertion to runtime error

* Add precondition to docs

* Doc improvement

---------

Co-authored-by: Garth N. Wells <[email protected]>

cpp/dolfinx/fem/DirichletBC.cpp

@@ -32,17 +32,24 @@ namespace
 /// @returns A list of (cell_index, entity_index) pairs for each input
 /// entity.
 std::vector<std::pair<std::int32_t, int>>
-find_local_entity_index(mesh::Topology& topology,
+find_local_entity_index(const mesh::Topology& topology,
                         std::span<const std::int32_t> entities, int dim)
 {
   // Initialise entity-cell connectivity
   const int tdim = topology.dim();
-  topology.create_entities(tdim);
-  topology.create_connectivity(dim, tdim);
   auto e_to_c = topology.connectivity(dim, tdim);
-  assert(e_to_c);
+  if (!e_to_c)
+  {
+    throw std::runtime_error(
+        "Entity-to-cell connectivity has not been computed.");
+  }
+
   auto c_to_e = topology.connectivity(tdim, dim);
-  assert(c_to_e);
+  if (!c_to_e)
+  {
+    throw std::runtime_error(
+        "Cell-to-entity connectivity has not been computed.");
+  }
 
   std::vector<std::pair<std::int32_t, int>> entity_indices;
   entity_indices.reserve(entities.size());
@@ -176,10 +183,9 @@ get_remote_dofs(MPI_Comm comm, const common::IndexMap& map, int bs_map,
 } // namespace
 
 //-----------------------------------------------------------------------------
-std::vector<std::int32_t>
-fem::locate_dofs_topological(mesh::Topology& topology, const DofMap& dofmap,
-                             int dim, std::span<const std::int32_t> entities,
-                             bool remote)
+std::vector<std::int32_t> fem::locate_dofs_topological(
+    const mesh::Topology& topology, const DofMap& dofmap, int dim,
+    std::span<const std::int32_t> entities, bool remote)
 {
   auto cell_types = topology.cell_types();
   if (cell_types.size() > 1)
@@ -291,7 +297,7 @@ fem::locate_dofs_topological(mesh::Topology& topology, const DofMap& dofmap,
 }
 //-----------------------------------------------------------------------------
 std::array<std::vector<std::int32_t>, 2> fem::locate_dofs_topological(
-    mesh::Topology& topology,
+    const mesh::Topology& topology,
     std::array<std::reference_wrapper<const DofMap>, 2> dofmaps, const int dim,
     std::span<const std::int32_t> entities, bool remote)
 {

cpp/dolfinx/fem/DirichletBC.h

@@ -25,10 +25,12 @@
 namespace dolfinx::fem
 {
 
-/// Find degrees-of-freedom which belong to the provided mesh entities
-/// (topological). Note that degrees-of-freedom for discontinuous
-/// elements are associated with the cell even if they may appear to be
-/// associated with a facet/edge/vertex.
+/// @brief Find degrees-of-freedom which belong to the provided mesh
+/// entities (topological).
+///
+/// @note Degrees-of-freedom for discontinuous elements are associated
+/// with the cell even if they may appear to be associated with a
+/// facet/edge/vertex.
 ///
 /// @param[in] topology Mesh topology.
 /// @param[in] dofmap Dofmap that associated DOFs with cells.
@@ -46,15 +48,19 @@ namespace dolfinx::fem
 /// @return Array of DOF index blocks (local to the MPI rank) in the
 /// space V. The array uses the block size of the dofmap associated
 /// with V.
+/// @pre The topology cell->entity and entity->cell connectivity must
+/// have been computed before calling this function.
 std::vector<std::int32_t>
-locate_dofs_topological(mesh::Topology& topology, const DofMap& dofmap, int dim,
-                        std::span<const std::int32_t> entities,
+locate_dofs_topological(const mesh::Topology& topology, const DofMap& dofmap,
+                        int dim, std::span<const std::int32_t> entities,
                         bool remote = true);
 
-/// Find degrees-of-freedom which belong to the provided mesh entities
-/// (topological). Note that degrees-of-freedom for discontinuous
-/// elements are associated with the cell even if they may appear to be
-/// associated with a facet/edge/vertex.
+/// @brief Find degrees-of-freedom which belong to the provided mesh
+/// entities (topological).
+///
+/// @note Degrees-of-freedom for discontinuous elements are associated
+/// with the cell even if they may appear to be associated with a
+/// facet/edge/vertex.
 ///
 /// @param[in] topology Mesh topology.
 /// @param[in] dofmaps The dofmaps.
@@ -73,8 +79,10 @@ locate_dofs_topological(mesh::Topology& topology, const DofMap& dofmap, int dim,
 /// V[0] and V[1]. The array[0](i) entry is the DOF index in the space
 /// V[0] and array[1](i) is the corresponding DOF entry in the space
 /// V[1]. The returned dofs are 'unrolled', i.e. block size = 1.
+/// @pre The topology cell->entity and entity->cell connectivity must
+/// have been computed before calling this function.
 std::array<std::vector<std::int32_t>, 2> locate_dofs_topological(
-    mesh::Topology& topology,
+    const mesh::Topology& topology,
     std::array<std::reference_wrapper<const DofMap>, 2> dofmaps, int dim,
     std::span<const std::int32_t> entities, bool remote = true);