Move occ_tol to init in OrderDisorderedStructureTransformation (#4274)

* move occ_tol to initialization parameters

* add tests

* fix: ruff formatting issues

* pre-commit auto-fixes

---------

Co-authored-by: Hui Zheng <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

src/pymatgen/transformations/standard_transformations.py

@@ -454,7 +454,7 @@ class OrderDisorderedStructureTransformation(AbstractTransformation):
     ALGO_BEST_FIRST = 2
     ALGO_RANDOM = -1
 
-    def __init__(self, algo=ALGO_FAST, symmetrized_structures=False, no_oxi_states=False):
+    def __init__(self, algo=ALGO_FAST, symmetrized_structures=False, no_oxi_states=False, occ_tol=0.25):
         """
         Args:
             algo (int): Algorithm to use.
@@ -463,15 +463,17 @@ def __init__(self, algo=ALGO_FAST, symmetrized_structures=False, no_oxi_states=F
                 should be used for the grouping of sites.
             no_oxi_states (bool): Whether to remove oxidation states prior to
                 ordering.
+            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.
         """
         self.algo = algo
         self._all_structures: list = []
         self.no_oxi_states = no_oxi_states
         self.symmetrized_structures = symmetrized_structures
+        self.occ_tol = occ_tol
 
-    def apply_transformation(
-        self, structure: Structure, return_ranked_list: bool | int = False, occ_tol=0.25
-    ) -> Structure:
+    def apply_transformation(self, structure: Structure, return_ranked_list: bool | int = False) -> Structure:
         """For this transformation, the apply_transformation method will return
         only the ordered structure with the lowest Ewald energy, to be
         consistent with the method signature of the other transformations.
@@ -482,9 +484,6 @@ def apply_transformation(
             structure: Oxidation state decorated disordered structure to order
             return_ranked_list (bool | int, optional): If return_ranked_list is int, that number of structures
                 is returned. If False, only the single lowest energy structure is returned. Defaults to False.
-            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.
 
         Returns:
             Depending on returned_ranked list, either a transformed structure
@@ -554,7 +553,7 @@ def apply_transformation(
             )
             # round total occupancy to possible values
             for key, val in total_occupancy.items():
-                if abs(val - round(val)) > occ_tol:
+                if abs(val - round(val)) > self.occ_tol:
                     raise ValueError("Occupancy fractions not consistent with size of unit cell")
                 total_occupancy[key] = round(val)
             # start with an ordered structure

tests/transformations/test_standard_transformations.py

@@ -12,6 +12,7 @@
 from numpy.testing import assert_allclose
 from pytest import approx
 
+from pymatgen.alchemy.transmuters import StandardTransmuter
 from pymatgen.core import Element, PeriodicSite
 from pymatgen.core.lattice import Lattice
 from pymatgen.symmetry.structure import SymmetrizedStructure
@@ -427,6 +428,38 @@ def test_random_sample(self):
         output = trafo.apply_transformation(struct * [2, 2, 2], return_ranked_list=False)
         assert output.composition.reduced_formula == struct.composition.reduced_formula
 
+    def test_occ_tol_with_supercell(self):
+        """Test occ_tol parameter behavior with supercell structures."""
+        # Create a disordered structure
+        coords = [[0.0, 0.0, 0.0], [0.5, 0.5, 0.5]]
+        lattice = Lattice(
+            [
+                [2.9823991724941643, 0.0, 1.8261928001873466e-16],
+                [4.796063659664723e-16, 2.9823991724941643, 1.8261928001873466e-16],
+                [0.0, 0.0, 2.9823991724941643],
+            ]
+        )
+        struct = Structure(lattice, [{"V": 0.75, "Ti": 0.25}, {"V": 0.75, "Ti": 0.25}], coords)
+
+        # Create a 5x5x5 supercell structure
+        supercell = struct * [5, 5, 5]
+
+        # Test 1: Default occ_tol (0.25) should raise error
+        ts_strict = OrderDisorderedStructureTransformation(algo=-1, no_oxi_states=True, occ_tol=0.25)
+        with pytest.raises(ValueError, match="Occupancy fractions not consistent with size of unit cell"):
+            StandardTransmuter.from_structures([supercell], transformations=[ts_strict], extend_collection=3)
+
+        # Test 2: Relaxed occ_tol (0.5) should work
+        ts_relaxed = OrderDisorderedStructureTransformation(algo=-1, no_oxi_states=True, occ_tol=0.5)
+        transmuter = StandardTransmuter.from_structures([supercell], transformations=[ts_relaxed], extend_collection=3)
+
+        # Verify the transformation worked and produced expected composition
+        transformed_structs = transmuter.transformed_structures
+        assert len(transformed_structs) == 3
+        # Check composition matches expected Ti31V94
+        composition = transformed_structs[0].final_structure.composition
+        assert composition.reduced_formula == "Ti31V94"
+
 
 class TestPrimitiveCellTransformation:
     def test_apply_transformation(self):