Add Structure.get_symmetry_dataset convenience method (#4268)

* add Structure.get_moyo_dataset -> moyopy.MoyoDataset convenience method

* Add Structure.get_symmetry_dataset() method with multiple backend support, currently moyopy and spglib

- remove get_moyo_dataset method
- implement method overloading for type hints
- update tests to cover both backends and error cases

* add @due.dcite decorator for citation tracking with DOI for Spglib

- also include citation details in method doc string

* fix duecredit import from pymatgen.util.due module

- update pyproject.toml to install symmetry optional deps in CI

* fix ImportError on ase: Try installing dependencies with `pip install moyopy[interface]`

Author: janosh

pyproject.toml

@@ -68,7 +68,7 @@ dependencies = [
     # scipy<1.14.1 is incompatible with NumPy 2.0 on Windows
     # https://github.com/scipy/scipy/issues/21052
     "scipy>=1.14.1; platform_system == 'Windows'",
-    "spglib>=2.5.0",
+    "spglib>=2.5",
     "sympy>=1.3",  # PR #4116
     "tabulate>=0.9",
     "tqdm>=4.60",
@@ -89,7 +89,7 @@ Pypi = "https://pypi.org/project/pymatgen"
 [project.optional-dependencies]
 abinit = ["netcdf4>=1.7.2"]
 ase = ["ase>=3.23.0"]
-ci = ["pytest-cov>=4", "pytest-split>=0.8", "pytest>=8"]
+ci = ["pytest-cov>=4", "pytest-split>=0.8", "pytest>=8", "pymatgen[symmetry]"]
 docs = ["invoke", "sphinx", "sphinx_markdown_builder", "sphinx_rtd_theme"]
 electronic_structure = ["fdint>=2.0.2"]
 mlp = ["chgnet>=0.3.8", "matgl>=1.1.3"]
@@ -110,6 +110,8 @@ optional = [
     "phonopy>=2.33.3",
     "seekpath>=2.0.1",
 ]
+# moyopy[interface] includes ase
+symmetry = ["moyopy[interface]>=0.3", "spglib>=2.5"]
 # tblite only support Python 3.12+ through conda-forge
 # https://github.com/tblite/tblite/issues/175
 tblite = [ "tblite[ase]>=0.3.0; platform_system=='Linux' and python_version<'3.12'"]

src/pymatgen/core/structure.py

@@ -20,7 +20,7 @@
 from abc import ABC, abstractmethod
 from collections import defaultdict
 from fnmatch import fnmatch
-from typing import TYPE_CHECKING, Literal, cast, get_args
+from typing import TYPE_CHECKING, Literal, cast, get_args, overload
 
 import numpy as np
 from monty.dev import deprecated
@@ -43,12 +43,15 @@
 from pymatgen.electronic_structure.core import Magmom
 from pymatgen.symmetry.maggroups import MagneticSpaceGroup
 from pymatgen.util.coord import all_distances, get_angle, lattice_points_in_supercell
+from pymatgen.util.due import Doi, due
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator, Sequence
     from typing import Any, ClassVar, SupportsIndex, TypeAlias
 
+    import moyopy
     import pandas as pd
+    import spglib
     from ase import Atoms
     from ase.calculators.calculator import Calculator
     from ase.io.trajectory import Trajectory
@@ -3338,6 +3341,61 @@ def to_conventional(self, **kwargs) -> Structure:
         """
         return self.to_cell("conventional", **kwargs)
 
+    @overload
+    def get_symmetry_dataset(self, backend: Literal["moyopy"], **kwargs) -> moyopy.MoyoDataset: ...
+
+    @due.dcite(
+        Doi("10.1080/27660400.2024.2384822"),
+        description="Spglib: a software library for crystal symmetry search",
+    )
+    @overload
+    def get_symmetry_dataset(self, backend: Literal["spglib"], **kwargs) -> spglib.SpglibDataset: ...
+
+    def get_symmetry_dataset(
+        self, backend: Literal["moyopy", "spglib"] = "spglib", **kwargs
+    ) -> moyopy.MoyoDataset | spglib.SpglibDataset:
+        """Get a symmetry dataset from the structure using either moyopy or spglib backend.
+
+        If using the spglib backend (default), please cite:
+
+        Togo, A., Shinohara, K., & Tanaka, I. (2024). Spglib: a software library for crystal
+        symmetry search. Science and Technology of Advanced Materials: Methods, 4(1), 2384822-2384836.
+        https://doi.org/10.1080/27660400.2024.2384822
+
+        Args:
+            backend ("moyopy" | "spglib"): Which symmetry analysis backend to use.
+                Defaults to "spglib".
+            **kwargs: Additional arguments passed to the respective backend's constructor.
+                For spglib, these are passed to SpacegroupAnalyzer (e.g. symprec, angle_tolerance).
+                For moyopy, these are passed to MoyoDataset constructor.
+
+        Returns:
+            MoyoDataset | SpglibDataset: Symmetry dataset from the chosen backend.
+
+        Raises:
+            ImportError: If the requested backend is not installed.
+            ValueError: If an invalid backend is specified.
+        """
+        if backend == "moyopy":
+            try:
+                import moyopy
+                import moyopy.interface
+            except ImportError:
+                raise ImportError("moyopy is not installed. Run pip install moyopy.")
+
+            # Convert structure to MoyoDataset format
+            moyo_cell = moyopy.interface.MoyoAdapter.from_structure(self)
+            return moyopy.MoyoDataset(cell=moyo_cell, **kwargs)
+
+        if backend == "spglib":
+            from pymatgen.symmetry.analyzer import SpacegroupAnalyzer
+
+            sga = SpacegroupAnalyzer(self, **kwargs)
+            return sga.get_symmetry_dataset()
+
+        valid_backends = ("moyopy", "spglib")
+        raise ValueError(f"Invalid {backend=}, must be one of {valid_backends}")
+
 
 class IMolecule(SiteCollection, MSONable):
     """Basic immutable Molecule object without periodicity. Essentially a

tests/core/test_structure.py

@@ -6,6 +6,7 @@
 from fractions import Fraction
 from pathlib import Path
 from shutil import which
+from unittest import mock
 
 import numpy as np
 import pytest
@@ -965,6 +966,32 @@ def test_sites_setter(self):
         struct.sites = new_sites
         assert struct.sites == new_sites
 
+    def test_get_symmetry_dataset(self):
+        """Test getting symmetry dataset from structure using different backends."""
+        # Test spglib backend
+        dataset = self.struct.get_symmetry_dataset(backend="spglib")
+        assert dataset.number == 227  # Fd-3m space group
+        assert dataset.international == "Fd-3m"
+        assert len(dataset.rotations) > 0
+        assert len(dataset.translations) > 0
+
+        # Test moyopy backend if available
+        moyopy = pytest.importorskip("moyopy")
+        dataset = self.struct.get_symmetry_dataset(backend="moyopy")
+        assert isinstance(dataset, moyopy.MoyoDataset)
+        assert dataset.prim_std_cell.numbers == [14, 14]  # Si atomic number is 14
+
+        # Test import error
+        with (
+            mock.patch.dict("sys.modules", {"moyopy": None}),
+            pytest.raises(ImportError, match="moyopy is not installed. Run pip install moyopy."),
+        ):
+            self.struct.get_symmetry_dataset(backend="moyopy")
+
+        # Test invalid backend
+        with pytest.raises(ValueError, match="Invalid backend='42'"):
+            self.struct.get_symmetry_dataset(backend="42")
+
 
 class TestStructure(PymatgenTest):
     def setUp(self):