From 6b43a298f4dd6d252e61db81a95dca33f5a83428 Mon Sep 17 00:00:00 2001
From: GuySten <62616591+GuySten@users.noreply.github.com>
Date: Thu, 22 Jan 2026 17:04:30 +0200
Subject: [PATCH] Add n_elements to the MeshBase protocol and deprecate
 num_mesh_cells (#3745)

---
 openmc/mesh.py                                | 36 +++++++++++++++++--
 openmc/source.py                              |  4 +--
 tests/unit_tests/mesh_to_vtk/test_vtk_dims.py |  4 +--
 3 files changed, 37 insertions(+), 7 deletions(-)

diff --git a/openmc/mesh.py b/openmc/mesh.py
index ce5218b5e9..12e8798109 100644
--- a/openmc/mesh.py
+++ b/openmc/mesh.py
@@ -153,11 +153,17 @@ class MeshBase(IDManagerMixin, ABC):
         Unique identifier for the mesh
     name : str
         Name of the mesh
+    lower_left : Iterable of float
+        The lower-left coordinates
+    upper_right : Iterable of float
+        The upper-right coordinates
     bounding_box : openmc.BoundingBox
         Axis-aligned bounding box of the mesh as defined by the upper-right and
         lower-left coordinates.
     indices : Iterable of tuple
         An iterable of mesh indices for each mesh element, e.g. [(1, 1, 1), (2, 1, 1), ...]
+    n_elements : int
+        Number of elements in the mesh
     """
 
     next_id = 1
@@ -179,6 +185,16 @@ class MeshBase(IDManagerMixin, ABC):
             self._name = name
         else:
             self._name = ''
+            
+    @property
+    @abstractmethod
+    def lower_left(self):
+        pass
+        
+    @property
+    @abstractmethod
+    def upper_right(self):
+        pass
 
     @property
     def bounding_box(self) -> openmc.BoundingBox:
@@ -188,6 +204,11 @@ class MeshBase(IDManagerMixin, ABC):
     @abstractmethod
     def indices(self):
         pass
+        
+    @property
+    @abstractmethod
+    def n_elements(self):
+        pass
 
     def __repr__(self):
         string = type(self).__name__ + '\n'
@@ -557,10 +578,19 @@ class StructuredMesh(MeshBase):
         s0 = (slice(0, -1),)*ndim + (slice(None),)
         s1 = (slice(1, None),)*ndim + (slice(None),)
         return (vertices[s0] + vertices[s1]) / 2
+    
+    @property
+    def n_elements(self):
+        return np.prod(self.dimension)
 
     @property
     def num_mesh_cells(self):
-        return np.prod(self.dimension)
+        warnings.warn(
+            "The 'num_mesh_cells' attribute is deprecated and will be removed in a future version. "
+            "Use 'n_elements' instead.",
+            FutureWarning, stacklevel=2
+        )
+        return self.n_elements
 
     def write_data_to_vtk(self,
                           filename: PathLike,
@@ -822,10 +852,10 @@ class StructuredMesh(MeshBase):
         """
         cv.check_type('data label', label, str)
 
-        if dataset.size != self.num_mesh_cells:
+        if dataset.size != self.n_elements:
             raise ValueError(
                 f"The size of the dataset '{label}' ({dataset.size}) should be"
-                f" equal to the number of mesh cells ({self.num_mesh_cells})"
+                f" equal to the number of mesh cells ({self.n_elements})"
             )
 
         # accept a flat array as-is, assuming it is in the correct order
diff --git a/openmc/source.py b/openmc/source.py
index 84d8a9619d..5acf55c219 100644
--- a/openmc/source.py
+++ b/openmc/source.py
@@ -572,10 +572,10 @@ class MeshSource(SourceBase):
         s = np.asarray(s)
 
         if isinstance(self.mesh, StructuredMesh):
-            if s.size != self.mesh.num_mesh_cells:
+            if s.size != self.mesh.n_elements:
                 raise ValueError(
                     f'The length of the source array ({s.size}) does not match '
-                    f'the number of mesh elements ({self.mesh.num_mesh_cells}).')
+                    f'the number of mesh elements ({self.mesh.n_elements}).')
 
             # If user gave a multidimensional array, flatten in the order
             # of the mesh indices
diff --git a/tests/unit_tests/mesh_to_vtk/test_vtk_dims.py b/tests/unit_tests/mesh_to_vtk/test_vtk_dims.py
index 8166ba68c8..366ce18efb 100644
--- a/tests/unit_tests/mesh_to_vtk/test_vtk_dims.py
+++ b/tests/unit_tests/mesh_to_vtk/test_vtk_dims.py
@@ -131,7 +131,7 @@ def test_write_data_to_vtk_size_mismatch(mesh):
     mesh : openmc.StructuredMesh
         The mesh to test
     """
-    right_size = mesh.num_mesh_cells
+    right_size = mesh.n_elements
     data = np.random.random(right_size + 1)
 
     # Error message has \ in to escape characters that are otherwise recognized
@@ -139,7 +139,7 @@ def test_write_data_to_vtk_size_mismatch(mesh):
     # string when using the match argument as that uses regular expression
     expected_error_msg = (
         fr"The size of the dataset 'label' \({len(data)}\) should be equal to "
-        fr"the number of mesh cells \({mesh.num_mesh_cells}\)"
+        fr"the number of mesh cells \({mesh.n_elements}\)"
     )
     with pytest.raises(ValueError, match=expected_error_msg):
         mesh.write_data_to_vtk(filename="out.vtk", datasets={"label": data})