Fix comment pass in Kpoints constructors (#4131)

* pass comment

* add test for gamma centered and other comment

* take comment as arg

* tweak comment and type

Author: DanielYang59

src/pymatgen/io/vasp/inputs.py

@@ -1296,7 +1296,11 @@ def style(self, style: str | KpointsSupportedModes) -> None:
         self._style = style
 
     @classmethod
-    def automatic(cls, subdivisions: int) -> Self:
+    def automatic(
+        cls,
+        subdivisions: int,
+        comment: str = "Fully automatic kpoint scheme",
+    ) -> Self:
         """
         Constructor for a fully automatic Kpoint grid, with
         Gamma-centered grids and the number of subdivisions
@@ -1306,14 +1310,15 @@ def automatic(cls, subdivisions: int) -> Self:
         Args:
             subdivisions (int): Number of subdivisions along
                 each reciprocal lattice vector.
+            comment (str): Comment in Kpoints.
 
         Returns:
             Kpoints
         """
         warnings.warn("Please use INCAR KSPACING tag.", DeprecationWarning, stacklevel=2)
 
         return cls(
-            "Fully automatic kpoint scheme",
+            comment,
             0,
             style=cls.supported_modes.Automatic,
             kpts=[
@@ -1322,49 +1327,67 @@ def automatic(cls, subdivisions: int) -> Self:
         )
 
     @classmethod
-    def gamma_automatic(cls, kpts: Tuple3Ints = (1, 1, 1), shift: Vector3D = (0, 0, 0)) -> Self:
+    def gamma_automatic(
+        cls,
+        kpts: Tuple3Ints = (1, 1, 1),
+        shift: Vector3D = (0, 0, 0),
+        comment: str = "Automatic kpoint scheme",
+    ) -> Self:
         """
         Construct an automatic Gamma-centered Kpoint grid.
 
         Args:
             kpts: Subdivisions N_1, N_2 and N_3 along reciprocal lattice
                 vectors. Defaults to (1, 1, 1)
             shift: Shift to be applied to the kpoints. Defaults to (0, 0, 0).
+            comment (str): Comment in Kpoints.
 
         Returns:
             Kpoints
         """
         return cls(
-            "Automatic kpoint scheme",
+            comment,
             0,
             cls.supported_modes.Gamma,
             kpts=[kpts],
             kpts_shift=shift,
         )
 
     @classmethod
-    def monkhorst_automatic(cls, kpts: Tuple3Ints = (2, 2, 2), shift: Vector3D = (0, 0, 0)) -> Self:
+    def monkhorst_automatic(
+        cls,
+        kpts: Tuple3Ints = (2, 2, 2),
+        shift: Vector3D = (0, 0, 0),
+        comment: str = "Automatic kpoint scheme",
+    ) -> Self:
         """
         Construct an automatic Monkhorst-Pack Kpoint grid.
 
         Args:
             kpts: Subdivisions N_1, N_2, N_3 along reciprocal lattice
                 vectors. Defaults to (2, 2, 2)
             shift: Shift to be applied to the kpoints. Defaults to (0, 0, 0).
+            comment (str): Comment in Kpoints.
 
         Returns:
             Kpoints
         """
         return cls(
-            "Automatic kpoint scheme",
+            comment,
             0,
             cls.supported_modes.Monkhorst,
             kpts=[kpts],
             kpts_shift=shift,
         )
 
     @classmethod
-    def automatic_density(cls, structure: Structure, kppa: float, force_gamma: bool = False) -> Self:
+    def automatic_density(
+        cls,
+        structure: Structure,
+        kppa: float,
+        force_gamma: bool = False,
+        comment: str | None = None,
+    ) -> Self:
         """Get an automatic Kpoints object based on a structure and a kpoint
         density. Uses Gamma centered meshes for hexagonal cells and face-centered cells,
         Monkhorst-Pack grids otherwise.
@@ -1374,15 +1397,18 @@ def automatic_density(cls, structure: Structure, kppa: float, force_gamma: bool
             reciprocal lattice vector proportional to its length.
 
         Args:
-            structure (Structure): Input structure
-            kppa (float): Grid density
+            structure (Structure): Input structure.
+            kppa (float): Grid density.
             force_gamma (bool): Force a gamma centered mesh (default is to
-                use gamma only for hexagonal cells or odd meshes)
+                use gamma only for hexagonal cells or odd meshes).
+            comment (str): Comment in Kpoints.
 
         Returns:
             Kpoints
         """
-        comment = f"pymatgen with grid density = {kppa:.0f} / number of atoms"
+        if comment is None:
+            comment = f"pymatgen with grid density = {kppa:.0f} / number of atoms"
+
         if math.fabs((math.floor(kppa ** (1 / 3) + 0.5)) ** 3 - kppa) < 1:
             kppa += kppa * 0.01
         lattice = structure.lattice
@@ -1409,7 +1435,12 @@ def automatic_density(cls, structure: Structure, kppa: float, force_gamma: bool
         )
 
     @classmethod
-    def automatic_gamma_density(cls, structure: Structure, kppa: float) -> Self:
+    def automatic_gamma_density(
+        cls,
+        structure: Structure,
+        kppa: float,
+        comment: str | None = None,
+    ) -> Self:
         """Get an automatic Kpoints object based on a structure and a kpoint
         density. Uses Gamma centered meshes always. For GW.
 
@@ -1418,9 +1449,13 @@ def automatic_gamma_density(cls, structure: Structure, kppa: float) -> Self:
             reciprocal lattice vector proportional to its length.
 
         Args:
-            structure: Input structure
-            kppa: Grid density
+            structure (Structure): Input structure
+            kppa (float): Grid density
+            comment (str): Comment in Kpoints.
         """
+        if comment is None:
+            comment = f"pymatgen with grid density = {kppa:.0f} / number of atoms"
+
         lattice = structure.lattice
         a, b, c = lattice.abc
         n_grid = kppa / len(structure)
@@ -1436,8 +1471,6 @@ def automatic_gamma_density(cls, structure: Structure, kppa: float) -> Self:
 
         style = cls.supported_modes.Gamma
 
-        comment = f"pymatgen with grid density = {kppa:.0f} / number of atoms"
-
         n_kpts = 0
         return cls(
             comment,
@@ -1448,31 +1481,39 @@ def automatic_gamma_density(cls, structure: Structure, kppa: float) -> Self:
         )
 
     @classmethod
-    def automatic_density_by_vol(cls, structure: Structure, kppvol: int, force_gamma: bool = False) -> Self:
+    def automatic_density_by_vol(
+        cls,
+        structure: Structure,
+        kppvol: int,
+        force_gamma: bool = False,
+        comment: str | None = None,
+    ) -> Self:
         """Get an automatic Kpoints object based on a structure and a kpoint
         density per inverse Angstrom^3 of reciprocal cell.
 
         Algorithm:
             Same as automatic_density()
 
         Args:
-            structure (Structure): Input structure
-            kppvol (int): Grid density per Angstrom^(-3) of reciprocal cell
-            force_gamma (bool): Force a gamma centered mesh
+            structure (Structure): Input structure.
+            kppvol (int): Grid density per Angstrom^(-3) of reciprocal cell.
+            force_gamma (bool): Force a gamma centered mesh.
+            comment (str): Comment in Kpoints.
 
         Returns:
             Kpoints
         """
         vol = structure.lattice.reciprocal_lattice.volume
         kppa = kppvol * vol * len(structure)
-        return cls.automatic_density(structure, kppa, force_gamma=force_gamma)
+        return cls.automatic_density(structure, kppa, force_gamma=force_gamma, comment=comment)
 
     @classmethod
     def automatic_density_by_lengths(
         cls,
         structure: Structure,
         length_densities: Sequence[float],
         force_gamma: bool = False,
+        comment: str | None = None,
     ) -> Self:
         """Get an automatic Kpoints object based on a structure and a k-point
         density normalized by lattice constants.
@@ -1483,18 +1524,20 @@ def automatic_density_by_lengths(
             have k-points of 50/a x 50/b x 1/c.
 
         Args:
-            structure (Structure): Input structure
-            length_densities (list[float]): Defines the density of k-points in each
+            structure (Structure): Input structure.
+            length_densities (list[float]): Defines the density of k-points in each.
             dimension, e.g. [50.0, 50.0, 1.0].
-            force_gamma (bool): Force a gamma centered mesh
+            force_gamma (bool): Force a gamma centered mesh.
+            comment (str): Comment in Kpoints.
 
         Returns:
             Kpoints
         """
         if len(length_densities) != 3:
             raise ValueError(f"The dimensions of length_densities must be 3, not {len(length_densities)}")
 
-        comment: str = f"k-point density of {length_densities}/[a, b, c]"
+        if comment is None:
+            comment = f"k-point density of {length_densities}/[a, b, c]"
 
         lattice = structure.lattice
 
@@ -1520,16 +1563,22 @@ def automatic_density_by_lengths(
         )
 
     @classmethod
-    def automatic_linemode(cls, divisions: int, ibz: HighSymmKpath) -> Self:
+    def automatic_linemode(
+        cls,
+        divisions: int,
+        ibz: HighSymmKpath,
+        comment: str = "Line_mode KPOINTS file",
+    ) -> Self:
         """
         Convenient static constructor for a KPOINTS in mode line_mode.
         gamma centered Monkhorst-Pack grids and the number of subdivisions
         along each reciprocal lattice vector determined by the scheme in the
         VASP manual.
 
         Args:
-            divisions: Parameter determining the number of k-points along each high symmetry line.
-            ibz: HighSymmKpath object (pymatgen.symmetry.bandstructure)
+            divisions (int): Parameter determining the number of k-points along each high symmetry line.
+            ibz (HighSymmKpath): HighSymmKpath object (pymatgen.symmetry.bandstructure).
+            comment (str): Comment in Kpoints.
 
         Returns:
             Kpoints object
@@ -1547,7 +1596,7 @@ def automatic_linemode(cls, divisions: int, ibz: HighSymmKpath) -> Self:
             labels.append(path[-1])
 
         return cls(
-            "Line_mode KPOINTS file",
+            comment,
             style=cls.supported_modes.Line_mode,
             coord_type="Reciprocal",
             kpts=kpoints,
@@ -1591,7 +1640,7 @@ def from_str(cls, string: str) -> Self:
 
         # Fully automatic KPOINTS
         if style == "a":
-            return cls.automatic(int(lines[3].split()[0].strip()))
+            return cls.automatic(int(lines[3].split()[0].strip()), comment=comment)
 
         coord_pattern = re.compile(r"^\s*([\d+.\-Ee]+)\s+([\d+.\-Ee]+)\s+([\d+.\-Ee]+)")
 
@@ -1614,7 +1663,11 @@ def from_str(cls, string: str) -> Self:
 
                 kpts_shift = cast(Vector3D, tuple(_kpts_shift))
 
-            return cls.gamma_automatic(kpt, kpts_shift) if style == "g" else cls.monkhorst_automatic(kpt, kpts_shift)
+            return (
+                cls.gamma_automatic(kpt, kpts_shift, comment=comment)
+                if style == "g"
+                else cls.monkhorst_automatic(kpt, kpts_shift, comment=comment)
+            )
 
         # Automatic kpoints with basis
         if num_kpts <= 0:
@@ -1709,7 +1762,7 @@ def write_file(self, filename: PathLike) -> None:
         with zopen(filename, mode="wt") as file:
             file.write(str(self))
 
-    def as_dict(self) -> dict:
+    def as_dict(self) -> dict[str, Any]:
         """MSONable dict."""
         dct = {
             "@module": type(self).__module__,
@@ -1734,7 +1787,7 @@ def as_dict(self) -> dict:
         return dct
 
     @classmethod
-    def from_dict(cls, dct: dict) -> Self:
+    def from_dict(cls, dct: dict[str, Any]) -> Self:
         """
         Args:
             dct (dict): Dict representation.
@@ -1803,9 +1856,9 @@ class OrbitalDescription(NamedTuple):
 
 
 # Hashes computed from the full POTCAR file contents by pymatgen (not 1st-party VASP hashes)
-PYMATGEN_POTCAR_HASHES = loadfn(f"{MODULE_DIR}/vasp_potcar_pymatgen_hashes.json")
+PYMATGEN_POTCAR_HASHES: dict = loadfn(f"{MODULE_DIR}/vasp_potcar_pymatgen_hashes.json")
 # Written to some newer POTCARs by VASP
-VASP_POTCAR_HASHES = loadfn(f"{MODULE_DIR}/vasp_potcar_file_hashes.json")
+VASP_POTCAR_HASHES: dict = loadfn(f"{MODULE_DIR}/vasp_potcar_file_hashes.json")
 POTCAR_STATS_PATH: str = os.path.join(MODULE_DIR, "potcar-summary-stats.json.bz2")
 
 

tests/files/io/vasp/inputs/KPOINTS_gamma

@@ -0,0 +1,4 @@
+Gamma centered mesh
+0
+Gamma
+4 4 4

tests/io/vasp/test_inputs.py

@@ -899,23 +899,25 @@ def test_check_params(self):
 
 
 class TestKpointsSupportedModes:
-    def test_from_str(self):
-        test_cases = "Automatic Gamma Monkhorst Line_mode Cartesian Reciprocal".split()
-        for input_str in test_cases:
-            expected = getattr(KpointsSupportedModes, input_str)
-            assert KpointsSupportedModes.from_str(input_str) == expected
-            assert KpointsSupportedModes.from_str(input_str.lower()) == expected  # case insensitive
-            assert KpointsSupportedModes.from_str(input_str[0]) == expected  # only first letter matters
-
+    @pytest.mark.parametrize("mode", ["Automatic", "Gamma", "Monkhorst", "Line_mode", "Cartesian", "Reciprocal"])
+    def test_from_str(self, mode):
+        expected = getattr(KpointsSupportedModes, mode)
+        assert KpointsSupportedModes.from_str(mode) == expected
+        assert KpointsSupportedModes.from_str(mode.lower()) == expected  # case insensitive
+        assert KpointsSupportedModes.from_str(mode[0]) == expected  # only first letter matters
+
+    def test_invalid_mode(self):
         mode = "InvalidMode"
         with pytest.raises(ValueError, match=f"Invalid Kpoint {mode=}"):
             KpointsSupportedModes.from_str(mode)
 
 
 class TestKpoints:
     def test_init(self):
+        # Automatic KPOINT grid
         filepath = f"{VASP_IN_DIR}/KPOINTS_auto"
         kpoints = Kpoints.from_file(filepath)
+        assert kpoints.comment == "Automatic mesh"
         assert kpoints.kpts == [(10,)], "Wrong kpoint lattice read"
         filepath = f"{VASP_IN_DIR}/KPOINTS_cartesian"
         kpoints = Kpoints.from_file(filepath)
@@ -926,17 +928,27 @@ def test_init(self):
         ], "Wrong kpoint lattice read"
         assert kpoints.kpts_shift == (0.5, 0.5, 0.5)
 
+        # Gamma-centered Kpoint grid
+        filepath = f"{VASP_IN_DIR}/KPOINTS_gamma"
+        kpoints = Kpoints.from_file(filepath)
+        assert kpoints.comment == "Gamma centered mesh"
+        assert kpoints.kpts == [(4, 4, 4)]
+
+        # Monkhorst-Pack Kpoint grid
         filepath = f"{VASP_IN_DIR}/KPOINTS"
         kpoints = Kpoints.from_file(filepath)
+        assert kpoints.comment == "Auto-generated kpoints file: VaspIO.writeKPOINTS(XX,XX,500)"
         self.kpoints = kpoints
         assert kpoints.kpts == [(2, 4, 6)]
 
+        # Line mode
         filepath = f"{VASP_IN_DIR}/KPOINTS_band"
         kpoints = Kpoints.from_file(filepath)
         assert kpoints.labels is not None
         assert kpoints.style == Kpoints.supported_modes.Line_mode
         assert str(kpoints).split("\n")[3] == "Reciprocal"
 
+        # Explicit K-point mode
         filepath = f"{VASP_IN_DIR}/KPOINTS_explicit"
         kpoints = Kpoints.from_file(filepath)
         assert kpoints.kpts_weights is not None
@@ -949,8 +961,10 @@ def test_init(self):
 0.5 0.5 0.5 4 None"""
         assert str(kpoints).strip() == expected_kpt_str
 
+        # Explicit tetrahedra method
         filepath = f"{VASP_IN_DIR}/KPOINTS_explicit_tet"
         kpoints = Kpoints.from_file(filepath)
+        assert kpoints.comment == "Example file"
         assert kpoints.tet_connections == [(6, [1, 2, 3, 4])]
 
     def test_property_kpts(self):