Clean up io.vasp.outputs.Outcar docstring (materialsproject#4160)

* improve docstring

* relocate private parser method and as_dict

* tweak class docstring

* NEED CONFIRM: deprecate read_pattern, rename to _parse_pattern

* update available readers

* micro_pyawk doc clean up

* schedule debug arg for removal

* remove umask that is doing nothing

* the docstring must be incorrect, tuple is not mutable

* unpack tuple for readability

* fix return type

* use is to check None

* Revert "NEED CONFIRM: deprecate read_pattern, rename to _parse_pattern"

This reverts commit 6b80819.

* relocate read_pattern

* add type, use is to check None

* enhance type

* getattr default as False instead of None when using as condition

* DEBUG: to be reverted, comment out isotope check

* Revert "DEBUG: to be reverted, comment out isotope check"

This reverts commit 4363d1b.

* add test for make_symmetric_matrix_from_upper_tri

* add shape require

* simplify implementation

* add tabledata type alias

* revert unrelated changes

* type and comment clean up

* avoid np.array as type in docstring

* clean up read_electrostatic_potential and read_freq_dielectric

* fix a lot of NMR CS parser

* more types

* more type

* fix the rest

* finish read_igpar

* fix mypy error

Author: DanielYang59

src/pymatgen/analysis/pourbaix_diagram.py

@@ -114,7 +114,7 @@ def __init__(
         self.uncorrected_energy = entry.energy
         if entry_id is not None:
             self.entry_id: str | None = entry_id
-        elif getattr(entry, "entry_id", None):
+        elif getattr(entry, "entry_id", False):
             self.entry_id = entry.entry_id
         else:
             self.entry_id = None

src/pymatgen/core/interface.py

@@ -916,7 +916,7 @@ def get_trans_mat(
             normal (bool): determine if need to require the c axis of one grain associated with
                 the first transformation matrix perpendicular to the surface or not.
                 default to false.
-            trans_cry (np.array): shape 3x3. If the structure given are primitive cell in cubic system, e.g.
+            trans_cry (NDArray): shape 3x3. If the structure given are primitive cell in cubic system, e.g.
                 bcc or fcc system, trans_cry is the transformation matrix from its
                 conventional cell to the primitive cell.
             lat_type (str): one character to specify the lattice type. Defaults to 'c' for cubic.

src/pymatgen/electronic_structure/boltztrap2.py

@@ -869,8 +869,8 @@ def compute_properties_doping(self, doping, temp_r=None) -> None:
     #     Find the chemical potential (mu).
 
     #     Args:
-    #         epsilon (np.array): Array of energy values.
-    #         dos (np.array): Array of density of states values.
+    #         epsilon (NDArray): Array of energy values.
+    #         dos (NDArray): Array of density of states values.
     #         N0 (float): Background carrier concentration.
     #         T (float): Temperature in Kelvin.
     #         dosweight (float, optional): Weighting factor for the density of states. Default is 2.0.

src/pymatgen/entries/computed_entries.py

@@ -469,7 +469,7 @@ def __eq__(self, other: object) -> bool:
         # However, if entry_id is same, they may have different corrections (e.g., due
         # to mixing scheme used) and thus should be compared on corrected energy.
 
-        if getattr(self, "entry_id", None) and getattr(other, "entry_id", None) and self.entry_id != other.entry_id:
+        if getattr(self, "entry_id", False) and getattr(other, "entry_id", False) and self.entry_id != other.entry_id:
             return False
 
         if not math.isclose(self.energy, other.energy):

src/pymatgen/io/common.py

@@ -70,11 +70,11 @@ def __init__(
 
         Args:
             structure (Structure): associated with the volumetric data
-            data (dict[str, np.array]): Actual volumetric data.
-            distance_matrix (np.array): A pre-computed distance matrix if available.
+            data (dict[str, NDArray]): Actual volumetric data.
+            distance_matrix (NDArray): A pre-computed distance matrix if available.
                 Useful so pass distance_matrices between sums,
                 short-circuiting an otherwise expensive operation.
-            data_aug (np.array): Any extra information associated with volumetric data
+            data_aug (NDArray): Any extra information associated with volumetric data
                 (typically augmentation charges)
         """
         self.structure = structure

src/pymatgen/io/pwmat/inputs.py

@@ -495,7 +495,7 @@ def __init__(
         """Initialization function.
 
         Args:
-            reciprocal_lattice (np.array): Reciprocal lattice with factor of 2*pi.
+            reciprocal_lattice (NDArray): Reciprocal lattice with factor of 2*pi.
             kpoints (dict[str, np.array]): Kpoints and their corresponding fractional coordinates.
             kpath (list[list[str]]): All kpaths, with each list representing one kpath.
             density (float): The density of kpoints mesh with factor of 2*pi.

src/pymatgen/io/pwmat/outputs.py

@@ -341,7 +341,7 @@ def _parse(self):
 
         Returns:
             labels (list[str]): The label of DOS, e.g. Total, Cr-3S, ...
-            dos (np.array): Value of density of state.
+            dos (NDArray): Value of density of state.
         """
         labels: list[str] = []
         labels = linecache.getline(str(self.filename), 1).split()[1:]

src/pymatgen/io/vasp/outputs.py

@@ -789,7 +789,7 @@ def _add_spin_magnitudes(self, structure: Structure):
             Structure: Structure with spin magnitudes added.
         """
         for idx, site in enumerate(structure):
-            if getattr(site.specie, "spin", None):
+            if getattr(site.specie, "spin", False):
                 spin = site.specie.spin
                 spin = getattr(site.specie, "spin", None)
                 sign = int(spin) if spin else 0

src/pymatgen/transformations/advanced_transformations.py

@@ -357,7 +357,7 @@ def add_partial_sphere(self, coords, radius, color, start=0, end=360, opacity=1.
         Adding a partial sphere (to display partial occupancies.
 
         Args:
-            coords (np.array): Coordinates
+            coords (NDArray): Coordinates
             radius (float): Radius of sphere
             color (tuple): RGB color of sphere
             start (float): Starting angle.