Wrap entities_to_geometry in Python (#3038)

* starting

* wrap function

* fix

* isort

* npt not np

* update test

* Small doc edit.

* improve doc

* format

* ruff

* Update python/dolfinx/mesh.py

* mark option as likely to be removed

---------

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

cpp/dolfinx/mesh/utils.h

@@ -618,12 +618,12 @@ std::vector<std::int32_t> locate_entities_boundary(const Mesh<T>& mesh, int dim,
 /// @warning This function should not be used unless there is no
 /// alternative. It may be removed in the future.
 ///
-/// @param[in] mesh The mesh
-/// @param[in] dim Topological dimension of the entities of interest
+/// @param[in] mesh The mesh.
+/// @param[in] dim Topological dimension of the entities of interest.
 /// @param[in] entities Entity indices (local) to compute the vertex
-/// geometry indices for
+/// geometry indices for.
 /// @param[in] orient If true, in 3D, reorients facets to have
-/// consistent normal direction
+/// consistent normal direction.
 /// @return Indices in the geometry array for the entity vertices. The
 /// shape is `(num_entities, num_vertices_per_entity)` and the storage
 /// is row-major. The index `indices[i, j]` is the position in the

python/dolfinx/mesh.py

@@ -61,6 +61,7 @@
     "to_string",
     "refine_plaza",
     "transfer_meshtag",
+    "entities_to_geometry",
 ]
 
 
@@ -753,3 +754,27 @@ def create_unit_cube(
         ghost_mode,
         partitioner,
     )
+
+
+def entities_to_geometry(
+    mesh: Mesh, dim: int, entities: npt.NDArray[np.int32], orient: bool = False
+) -> npt.NDArray[np.int32]:
+    """Indices in the geometry data for each vertex of the given mesh entities.
+
+    Warning:
+        This function should not be used unless there is no alternative.
+        It may be removed in the future.
+
+    Args:
+        mesh: The mesh.
+        dim: Topological dimension of the entities of interest.
+        entities: Entity indices (local to the process) to determine the
+            vertex geometry indices for.
+        orient: If True, the triangular facets of a 3D mesh will be reordered
+            so that they have a consistent normal direction. This option is likely
+            to be removed in the future.
+
+    Returns:
+        Indices in the geometry array for the entity vertices.
+    """
+    return _cpp.mesh.entities_to_geometry(mesh._cpp_object, dim, entities, orient)

python/test/unit/mesh/test_mesh.py

@@ -18,7 +18,7 @@
 from dolfinx import cpp as _cpp
 from dolfinx import graph
 from dolfinx import mesh as _mesh
-from dolfinx.cpp.mesh import create_cell_partitioner, entities_to_geometry, is_simplex
+from dolfinx.cpp.mesh import create_cell_partitioner, is_simplex
 from dolfinx.fem import assemble_scalar, coordinate_element, form
 from dolfinx.mesh import (
     CellType,
@@ -31,6 +31,7 @@
     create_unit_cube,
     create_unit_interval,
     create_unit_square,
+    entities_to_geometry,
     exterior_facet_indices,
     locate_entities,
     locate_entities_boundary,
@@ -76,7 +77,7 @@ def submesh_geometry_test(mesh, submesh, entity_map, geom_map, entity_dim):
     if len(entity_map) > 0:
         assert mesh.geometry.dim == submesh.geometry.dim
 
-        e_to_g = entities_to_geometry(mesh._cpp_object, entity_dim, np.array(entity_map), False)
+        e_to_g = entities_to_geometry(mesh, entity_dim, np.array(entity_map), False)
         for submesh_entity in range(len(entity_map)):
             submesh_x_dofs = submesh.geometry.dofmap[submesh_entity]
             # e_to_g[i] gets the mesh x_dofs of entities[i], which should