Ensure structure symmetrization in OrderDisorderedStructureTransformation (#4403)

* add optional symmetrization of disordered structure on the fly

* ensure symm struct when oxi states are removed

Author: esoteric-ephemera

src/pymatgen/transformations/standard_transformations.py

@@ -19,6 +19,7 @@
 from pymatgen.core.operations import SymmOp
 from pymatgen.core.structure import Lattice, Structure
 from pymatgen.symmetry.analyzer import SpacegroupAnalyzer
+from pymatgen.symmetry.structure import SymmetrizedStructure
 from pymatgen.transformations.site_transformations import PartialRemoveSitesTransformation
 from pymatgen.transformations.transformation_abc import AbstractTransformation
 
@@ -454,7 +455,15 @@ class OrderDisorderedStructureTransformation(AbstractTransformation):
     ALGO_BEST_FIRST = 2
     ALGO_RANDOM = -1
 
-    def __init__(self, algo=ALGO_FAST, symmetrized_structures=False, no_oxi_states=False, occ_tol=0.25):
+    def __init__(
+        self,
+        algo: int = ALGO_FAST,
+        symmetrized_structures: bool = False,
+        no_oxi_states: bool = False,
+        occ_tol: float = 0.25,
+        symprec: float | None = None,
+        angle_tolerance: float | None = None,
+    ):
         """
         Args:
             algo (int): Algorithm to use.
@@ -466,15 +475,23 @@ def __init__(self, algo=ALGO_FAST, symmetrized_structures=False, no_oxi_states=F
             occ_tol (float): Occupancy tolerance. If the total occupancy of a group is within this value
                 of an integer, it will be rounded to that integer otherwise raise a ValueError.
                 Defaults to 0.25.
+            symprec : float or None (default)
+                If a float, and symmetrized_structures is True, the linear tolerance
+                used to symmetrize structures with SpacegroupAnalyzer.
+            angle_tolerance : float or None (default)
+                If a float, and symmetrized_structures is True, the angle tolerance
+                used to symmetrize structures with SpacegroupAnalyzer.
         """
         self.algo = algo
         self._all_structures: list = []
         self.no_oxi_states = no_oxi_states
         self.symmetrized_structures = symmetrized_structures
+        self.symprec = symprec
+        self.angle_tolerance = angle_tolerance
         self.occ_tol = occ_tol
 
     def apply_transformation(
-        self, structure: Structure, return_ranked_list: bool | int = False
+        self, structure: Structure | SymmetrizedStructure, return_ranked_list: bool | int = False
     ) -> Structure | list[Structure] | list[dict[str, Any]]:
         """For this transformation, the apply_transformation method will return
         only the ordered structure with the lowest Ewald energy, to be
@@ -510,6 +527,11 @@ def apply_transformation(
             for idx, site in enumerate(structure):
                 structure[idx] = {f"{k.symbol}0+": v for k, v in site.species.items()}  # type: ignore[assignment]
 
+        if self.symmetrized_structures and not isinstance(structure, SymmetrizedStructure):
+            structure = SpacegroupAnalyzer(
+                structure, **{k: getattr(self, k) for k in ("symprec", "angle_tolerance") if getattr(self, k, None)}
+            ).get_symmetrized_structure()
+
         equivalent_sites: list[list[int]] = []
         exemplars: list[PeriodicSite] = []
         # generate list of equivalent sites to order

tests/transformations/test_standard_transformations.py

@@ -14,6 +14,7 @@
 from pymatgen.alchemy.transmuters import StandardTransmuter
 from pymatgen.core import Element, PeriodicSite
 from pymatgen.core.lattice import Lattice
+from pymatgen.symmetry.analyzer import SpacegroupAnalyzer
 from pymatgen.symmetry.structure import SymmetrizedStructure
 from pymatgen.transformations.standard_transformations import (
     AutoOxiStateDecorationTransformation,
@@ -358,10 +359,33 @@ def test_symmetrized_structure(self):
         ]
         struct = Structure(lattice, [{"Si4+": 1}, *[{"Si4+": 0.5}] * 4], coords)
         test_site = PeriodicSite("Si4+", coords[2], lattice)
-        struct = SymmetrizedStructure(struct, "not_real", [0, 1, 1, 2, 2], ["a", "b", "b", "c", "c"])
-        output = trafo.apply_transformation(struct)
+        symm_struct = SymmetrizedStructure(struct, "not_real", [0, 1, 1, 2, 2], ["a", "b", "b", "c", "c"])
+        output = trafo.apply_transformation(symm_struct)
         assert test_site in output
 
+        ds_coords = [
+            [0.0, 0.0, 0.0],
+            [0.0, 0.5, 0.5],
+            [0.5, 0.0, 0.5],
+            [0.5, 0.5, 0.0],
+            [0.25, 0.25, 0.75],
+            [0.25, 0.75, 0.25],
+            [0.75, 0.25, 0.25],
+            [0.75, 0.75, 0.75],
+        ]
+        structure = Structure(
+            Lattice.cubic(5),
+            [*[{"Si4-": 1}] * 4, *[{"Si4+": 0.5, "Ge4+": 0.5}] * 4],
+            ds_coords,
+        )
+        symm_struct = SpacegroupAnalyzer(structure).get_symmetrized_structure()
+
+        for no_oxi_states in (True, False):
+            _kwargs = {"symmetrized_structures": True, "no_oxi_states": no_oxi_states}
+            assert OrderDisorderedStructureTransformation(**_kwargs).apply_transformation(
+                symm_struct
+            ) == OrderDisorderedStructureTransformation(**_kwargs).apply_transformation(structure)
+
     def test_too_small_cell(self):
         trafo = OrderDisorderedStructureTransformation()
         coords = [[0.5, 0.5, 0.5]]