Add citations for Lobster modules and tiny addition to DOSCAR processing (#3114)

* Update citations

* Add lobster automation citations

* add more flexibility for dos

* prefer np.allclose over for loops for frac_coords assertion

---------

Co-authored-by: Janosh Riebesell <[email protected]>

Author: JaGeo

pymatgen/analysis/chemenv/coordination_environments/coordination_geometry_finder.py

@@ -1,6 +1,6 @@
 """
 This module contains the main object used to identify the coordination environments in a given structure.
-If you use this module, please cite the following:
+If you use this module, please cite:
 David Waroquiers, Xavier Gonze, Gian-Marco Rignanese, Cathrin Welker-Nieuwoudt, Frank Rosowski,
 Michael Goebel, Stephan Schenk, Peter Degelmann, Rute Andre, Robert Glaum, and Geoffroy Hautier,
 "Statistical analysis of coordination environments in oxides",

pymatgen/command_line/bader_caller.py

@@ -6,7 +6,7 @@
 Please download the library at http://theory.cm.utexas.edu/henkelman/code/bader/
 and follow the instructions to compile the executable.
 
-If you use this module, please cite the following:
+If you use this module, please cite:
 
 G. Henkelman, A. Arnaldsson, and H. Jonsson, "A fast and robust algorithm for
 Bader decomposition of charge density", Comput. Mater. Sci. 36, 254-360 (2006).

pymatgen/command_line/critic2_caller.py

@@ -26,7 +26,7 @@
  a bond critical point)
 * critic2 can do many other things besides
 
-If you use this module, please cite the following:
+If you use this module, please cite:
 
 A. Otero-de-la-Roza, E. R. Johnson and V. Luaña,
 Comput. Phys. Communications 185, 1007-1018 (2014)

pymatgen/command_line/enumlib_caller.py

@@ -7,7 +7,7 @@
 https://github.com/msg-byu/enumlib and follow the instructions in the README to
 compile these two executables accordingly.
 
-If you use this module, please cite the following:
+If you use this module, please cite:
 
 Gus L. W. Hart and Rodney W. Forcade, "Algorithm for generating derivative
 structures," Phys. Rev. B 77 224115 (26 June 2008)

pymatgen/command_line/vampire_caller.py

@@ -6,7 +6,7 @@
 Please download at https://vampire.york.ac.uk/download/ and
 follow the instructions to compile the executable.
 
-If you use this module, please cite the following:
+If you use this module, please cite:
 
 "Atomistic spin model simulations of magnetic nanomaterials."
 R. F. L. Evans, W. J. Fan, P. Chureemart, T. A. Ostler, M. O. A. Ellis

pymatgen/electronic_structure/cohp.py

@@ -1,7 +1,12 @@
 """
 This module defines classes to represent crystal orbital Hamilton
 populations (COHP) and integrated COHP (ICOHP), but can also be used
-for crystal orbital overlap populations (COOP).
+for crystal orbital overlap populations (COOP) or crystal orbital bond indices (COBIs).
+If you use this module, please cite:
+J. George, G. Petretto, A. Naik, M. Esters, A. J. Jackson, R. Nelson, R. Dronskowski, G.-M. Rignanese, G. Hautier,
+"Automated Bonding Analysis with Crystal Orbital Hamilton Populations",
+ChemPlusChem 2022, e202200123,
+DOI: 10.1002/cplu.202200123.
 """
 
 from __future__ import annotations
@@ -20,15 +25,21 @@
 from pymatgen.io.lmto import LMTOCopl
 from pymatgen.io.lobster import Cohpcar
 from pymatgen.util.coord import get_linear_interpolated_value
+from pymatgen.util.due import Doi, due
 from pymatgen.util.num import round_to_sigfigs
 
 __author__ = "Marco Esters, Janine George"
 __copyright__ = "Copyright 2017, The Materials Project"
 __version__ = "0.2"
-__maintainer__ = "Marco Esters, Janine George"
-__email__ = "[email protected], [email protected]"
+__maintainer__ = "Janine George"
+__email__ = "[email protected]"
 __date__ = "Dec 13, 2017"
 
+due.cite(
+    Doi("10.1002/cplu.202200123"),
+    description="Automated Bonding Analysis with Crystal Orbital Hamilton Populations",
+)
+
 
 class Cohp(MSONable):
     """Basic COHP object."""

pymatgen/io/lmto.py

@@ -1,5 +1,3 @@
-# Distributed under the terms of the MIT License
-
 """
 Module for implementing a CTRL file object class for the Stuttgart
 LMTO-ASA code. It will primarily be used to generate a pymatgen

pymatgen/io/lobster/inputs.py

@@ -1,8 +1,11 @@
-# Distributed under the terms of the MIT License
-
 """
 Module for reading Lobster input files. For more information
 on LOBSTER see www.cohp.de.
+If you use this module, please cite:
+J. George, G. Petretto, A. Naik, M. Esters, A. J. Jackson, R. Nelson, R. Dronskowski, G.-M. Rignanese, G. Hautier,
+"Automated Bonding Analysis with Crystal Orbital Hamilton Populations",
+ChemPlusChem 2022, e202200123,
+DOI: 10.1002/cplu.202200123.
 """
 
 from __future__ import annotations
@@ -22,6 +25,7 @@
 from pymatgen.io.vasp import Vasprun
 from pymatgen.io.vasp.inputs import Incar, Kpoints, Potcar
 from pymatgen.symmetry.bandstructure import HighSymmKpath
+from pymatgen.util.due import Doi, due
 
 if TYPE_CHECKING:
     from pymatgen.core.composition import Composition
@@ -30,13 +34,19 @@
 __author__ = "Janine George, Marco Esters"
 __copyright__ = "Copyright 2017, The Materials Project"
 __version__ = "0.2"
-__maintainer__ = "Janine George, Marco Esters"
-__email__ = "[email protected], [email protected]"
+__maintainer__ = "Janine George"
+__email__ = "[email protected]"
 __date__ = "Dec 13, 2017"
 
 MODULE_DIR = os.path.dirname(os.path.abspath(__file__))
 
 
+due.cite(
+    Doi("10.1002/cplu.202200123"),
+    description="Automated Bonding Analysis with Crystal Orbital Hamilton Populations",
+)
+
+
 class Lobsterin(dict, MSONable):
     """
     This class can handle and generate lobsterin files

pymatgen/io/lobster/lobsterenv.py

@@ -3,6 +3,11 @@
 the local environments (e.g., finding near neighbors)
 of single sites in molecules and structures based on
 bonding analysis with Lobster.
+If you use this module, please cite:
+J. George, G. Petretto, A. Naik, M. Esters, A. J. Jackson, R. Nelson, R. Dronskowski, G.-M. Rignanese, G. Hautier,
+"Automated Bonding Analysis with Crystal Orbital Hamilton Populations",
+ChemPlusChem 2022, e202200123,
+DOI: 10.1002/cplu.202200123.
 """
 from __future__ import annotations
 
@@ -23,6 +28,7 @@
 from pymatgen.electronic_structure.core import Spin
 from pymatgen.electronic_structure.plotter import CohpPlotter
 from pymatgen.io.lobster import Charge, Icohplist
+from pymatgen.util.due import Doi, due
 
 if TYPE_CHECKING:
     from pymatgen.core import Structure
@@ -35,6 +41,11 @@
 __status__ = "Production"
 __date__ = "February 2, 2021"
 
+due.cite(
+    Doi("10.1002/cplu.202200123"),
+    description="Automated Bonding Analysis with Crystal Orbital Hamilton Populations",
+)
+
 
 class LobsterNeighbors(NearNeighbors):
     """

pymatgen/io/lobster/outputs.py

@@ -1,8 +1,11 @@
-# Distributed under the terms of the MIT License
-
 """
 Module for reading Lobster output files. For more information
 on LOBSTER see www.cohp.de.
+If you use this module, please cite:
+J. George, G. Petretto, A. Naik, M. Esters, A. J. Jackson, R. Nelson, R. Dronskowski, G.-M. Rignanese, G. Hautier,
+"Automated Bonding Analysis with Crystal Orbital Hamilton Populations",
+ChemPlusChem 2022, e202200123,
+DOI: 10.1002/cplu.202200123.
 """
 
 from __future__ import annotations
@@ -13,7 +16,7 @@
 import re
 import warnings
 from collections import defaultdict
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 import numpy as np
 from monty.io import zopen
@@ -24,16 +27,25 @@
 from pymatgen.electronic_structure.dos import Dos, LobsterCompleteDos
 from pymatgen.io.vasp.inputs import Kpoints
 from pymatgen.io.vasp.outputs import Vasprun, VolumetricData
+from pymatgen.util.due import Doi, due
+
+if TYPE_CHECKING:
+    from pymatgen.core.structure import IStructure
 
 __author__ = "Janine George, Marco Esters"
 __copyright__ = "Copyright 2017, The Materials Project"
 __version__ = "0.2"
-__maintainer__ = "Janine George, Marco Esters "
-__email__ = "[email protected], [email protected]"
+__maintainer__ = "Janine George "
+__email__ = "[email protected]"
 __date__ = "Dec 13, 2017"
 
 MODULE_DIR = os.path.dirname(os.path.abspath(__file__))
 
+due.cite(
+    Doi("10.1002/cplu.202200123"),
+    description="Automated Bonding Analysis with Crystal Orbital Hamilton Populations",
+)
+
 
 class Cohpcar:
     """
@@ -469,18 +481,19 @@ class Doscar:
     def __init__(
         self,
         doscar: str = "DOSCAR.lobster",
-        structure_file: str = "POSCAR",
-        dftprogram: str = "Vasp",
+        structure_file: str | None = "POSCAR",
+        structure: IStructure | Structure | None = None,
     ):
         """
         Args:
             doscar: DOSCAR filename, typically "DOSCAR.lobster"
             structure_file: for vasp, this is typically "POSCAR"
-            dftprogram: so far only "vasp" is implemented.
+            structure: instead of a structure file, the structure can be given
+                directly. structure_file will be preferred.
         """
         self._doscar = doscar
-        if dftprogram == "Vasp":
-            self._final_structure = Structure.from_file(structure_file)
+
+        self._final_structure = Structure.from_file(structure_file) if structure_file is not None else structure
 
         self._parse_doscar()
 

pymatgen/io/lobster/tests/test_lobster.py

@@ -692,7 +692,10 @@ def setUp(self):
 
         self.structure = Structure.from_dict(data)
 
-    def test_completedos(self):
+        # test structure argument
+        self.DOSCAR_spin_pol2 = Doscar(doscar=doscar, structure_file=None, structure=Structure.from_file(poscar))
+
+    def test_complete_dos(self):
         # first for spin polarized version
         energies_spin = [-11.25000, -7.50000, -3.75000, 0.00000, 3.75000, 7.50000]
         tdos_up = [0.00000, 0.79999, 0.00000, 0.79999, 0.00000, 0.02577]
@@ -712,12 +715,15 @@ def test_completedos(self):
         assert tdos_up == self.DOSCAR_spin_pol.completedos.densities[Spin.up].tolist()
         assert tdos_down == self.DOSCAR_spin_pol.completedos.densities[Spin.down].tolist()
         assert fermi == approx(self.DOSCAR_spin_pol.completedos.efermi)
-        for coords, coords2 in zip(
+
+        assert np.allclose(
             self.DOSCAR_spin_pol.completedos.structure.frac_coords,
             self.structure.frac_coords,
-        ):
-            for xyz, xyz2 in zip(coords, coords2):
-                assert xyz == approx(xyz2)
+        )
+        assert np.allclose(
+            self.DOSCAR_spin_pol2.completedos.structure.frac_coords,
+            self.structure.frac_coords,
+        )
         assert self.DOSCAR_spin_pol.completedos.pdos[self.structure[0]]["2s"][Spin.up].tolist() == PDOS_F_2s_up
         assert self.DOSCAR_spin_pol.completedos.pdos[self.structure[0]]["2s"][Spin.down].tolist() == PDOS_F_2s_down
         assert self.DOSCAR_spin_pol.completedos.pdos[self.structure[0]]["2p_y"][Spin.up].tolist() == PDOS_F_2py_up
@@ -2308,12 +2314,10 @@ def test_structure_with_grosspop(self):
             ],
         }
 
-        newstructure = self.grosspop1.get_structure_with_total_grosspop(
+        new_structure = self.grosspop1.get_structure_with_total_grosspop(
             os.path.join(PymatgenTest.TEST_FILES_DIR, "cohp", "POSCAR.SiO2")
         )
-        for coords, coords2 in zip(newstructure.frac_coords, Structure.from_dict(struct_dict).frac_coords):
-            for xyz, xyz2 in zip(coords, coords2):
-                assert xyz == approx(xyz2)
+        assert np.allclose(new_structure.frac_coords, Structure.from_dict(struct_dict).frac_coords)
 
 
 class TestUtils(PymatgenTest):

pymatgen/io/shengbte.py

@@ -1,5 +1,3 @@
-# Distributed under the terms of the MIT License
-
 """This module implements reading and writing of ShengBTE CONTROL files."""
 
 from __future__ import annotations

pymatgen/util/convergence.py

@@ -1,5 +1,3 @@
-# Distributed under the terms of the MIT License.import string
-
 """
 function for calculating the convergence of an x, y data set
 main api:

test_files/.pytest-split-durations

@@ -1657,7 +1657,7 @@
     "pymatgen/io/lobster/tests/test_lobster.py::CohpcarTest::test_cohp_data": 0.07920433301478624,
     "pymatgen/io/lobster/tests/test_lobster.py::CohpcarTest::test_energies": 0.07907520799199119,
     "pymatgen/io/lobster/tests/test_lobster.py::CohpcarTest::test_orbital_resolved_cohp": 0.08125483398907818,
-    "pymatgen/io/lobster/tests/test_lobster.py::DoscarTest::test_completedos": 0.002467168014845811,
+    "pymatgen/io/lobster/tests/test_lobster.py::DoscarTest::test_complete_dos": 0.002467168014845811,
     "pymatgen/io/lobster/tests/test_lobster.py::DoscarTest::test_energies": 0.0008928750030463561,
     "pymatgen/io/lobster/tests/test_lobster.py::DoscarTest::test_is_spin_polarized": 0.0008428330183960497,
     "pymatgen/io/lobster/tests/test_lobster.py::DoscarTest::test_itdensities": 0.0008630430093035102,