ENH: add sorting API

pyproject.toml

@@ -26,6 +26,7 @@ dependencies = [
     # keep in sync with NPY_TARGET_VERSION (setup.py)
     # https://github.com/scipy/oldest-supported-numpy/issues/76#issuecomment-1628865694
     "numpy>=1.21",
+    "typing-extensions>=4.0.0 ; python_version < '3.11'",
 ]
 
 [project.readme]

src/gpgi/types.py

@@ -32,7 +32,10 @@
 
 if sys.version_info >= (3, 11):
     from enum import StrEnum
+    from typing import Self
 else:
+    from typing_extensions import Self
+
     from ._backports import StrEnum
 
 BoundarySpec = tuple[tuple[str, str, str], ...]
@@ -481,6 +484,51 @@ def _setup_host_cell_index(self, verbose: bool = False) -> None:
                 f"Indexed {self.particles.count:.4g} particles in {(tstop-tstart)/1e9:.2f} s"
             )
 
+    @property
+    def host_cell_index(self) -> np.ndarray[Any, np.dtype[np.uint16]]:
+        r"""
+        The host cell index (HCI) represents the ndimensional index
+        of the host cell for each particle.
+        It has shape (particles.count, grid.ndim).
+        Indices are 0-based and ghost layers are included.
+        """
+        self._setup_host_cell_index()
+        return self._hci
+
+    @cached_property
+    def _sort_key(self) -> np.ndarray[Any, np.dtype[np.uint16]]:
+        hci = self.host_cell_index
+        if self.grid.ndim == 1:
+            ind = np.lexsort((hci[:, 0],))
+        elif self.grid.ndim == 2:
+            ind = np.lexsort((hci[:, 0], hci[:, 1]))
+        else:
+            ind = np.lexsort((hci[:, 0], hci[:, 1], hci[:, 2]))
+        return np.array(ind, dtype="uint16")
+
+    def is_sorted(self) -> bool:
+        r"""Return True if and only if particles are already sorted."""
+        hci = self.host_cell_index
+        return bool(np.all(hci == hci[self._sort_key]))
+
+    def sorted(self) -> Self:
+        r"""Return a copy of this dataset with particles sorted by host cell index."""
+        return type(self)(
+            geometry=self.geometry,
+            grid=self.grid,
+            particles=ParticleSet(
+                self.geometry,
+                coordinates={
+                    name: arr[self._sort_key]
+                    for name, arr in deepcopy(self.particles.coordinates).items()
+                },
+                fields={
+                    name: arr[self._sort_key]
+                    for name, arr in deepcopy(self.particles.fields).items()
+                },
+            ),
+        )
+
     def deposit(
         self,
         particle_field_key: Name,