Merge branch 'refs/heads/develop' into dopey_fermi

# Conflicts:
#	examples/chemical_potentials_tutorial.ipynb

docs/Dev_ToDo.md

@@ -3,7 +3,7 @@
 - Check through chemical potential TO-DOs. Need to recheck validity of approximations used for extrinsic competing phases (and code for this).
 - Efficient generation of competing phases for which there are many polymorphs? See SK notes from CdTe competing phases.
 - Update chemical potential tools to work with new Materials Project API. Currently, supplying an API key for the new Materials Project API returns entries which do not have `e_above_hull` as a property, and so crashes. Ideally would be good to be compatible with both the legacy and new API, which should be fairly straightforward (try importing MPRester from mp_api client except ImportError import from pmg then will need to make a whole separate query/search because `band_gap` and `total_magnetisation` no longer accessible from `get_entries`). See https://docs.materialsproject.org/downloading-data/using-the-api
-- Publication ready chemical potential diagram plotting tool as in Adam Jackson's `plot-cplap-ternary` (3D) and Sungyhun's `cplapy` (4D) (see `doped_chempot_plotting_example.ipynb`; code there, just needs to be implemented in module functions). `ChemicalPotentialGrid` in `py-sc-fermi` interface could be quite useful for this? (Worth moving that part of code out of `interface` subpackage?)
+- Publication ready chemical potential diagram plotting tool as in Adam Jackson's `plot-cplap-ternary` (3D) and Sungyhun's `cplapy` (4D) (see `doped_chempot_plotting_example.ipynb`; code there, just needs to be implemented in module functions). `ChemicalPotentialGrid` in `py-sc-fermi` interface could be quite useful for this? (Worth moving that part of code out of `interface` subpackage?) Also can see https://github.com/materialsproject/pymatgen-analysis-defects/blob/main/pymatgen/analysis/defects/plotting/phases.py for 2D chempot plotting.
   - Also see `Cs2SnTiI6` notebooks for template code for this.
 - Note in tutorial that LaTeX table generator website can also be used with the `to_csv()` function to generate LaTeX tables for the competing phases.
 

docs/Installation.rst

@@ -108,4 +108,5 @@ the ``doped`` GitHub repository:
 Requirements
 -------------
 
-``doped`` requires ``pymatgen>=2022.10.22`` and its dependencies.
+The ``doped`` dependencies are listed in the ``pyproject.toml`` file on
+`the GitHub repository <https://github.com/SMTG-Bham/doped/blob/main/pyproject.toml>`__.

docs/Tips.rst

@@ -89,7 +89,7 @@ underlying calculation and/or extreme forces.
       `this part <https://shakenbreak.readthedocs.io/en/latest/Tips.html#bulk-phase-transformations>`_
       of the ``SnB`` docs.
 
-    - **Alternatively (if you have already performed SnB structure-searching), convergence of the forces can be aided by:**
+    - `Alternatively (if you have already performed SnB structure-searching), convergence of the forces can be aided by:`
     - Switching the ionic relaxation algorithm back and forth (i.e. change :code:`IBRION` to :code:`1` or
       :code:`3` and back).
     - Reducing the ionic step width (e.g. change :code:`POTIM` to :code:`0.02` in the :code:`INCAR`)
@@ -135,6 +135,13 @@ when parsing the intrinsic defects, the -3 charge antimony vacancy (``v_Sb-3``)
         with the supercell approach). If this error is not acceptable, you may need to use a larger supercell
         for more accurate energies.
 
+.. note::
+
+    Charge correction errors are estimated by computing the standard error of the mean of the electrostatic
+    potential difference between the bulk and defect supercells, in the sampling region (far from the
+    defect site), and multiplying by the defect charge. This gives a lower bound estimate of the true
+    error in the charge correction for a given supercell.
+
 Following the advice in the warning, we use ``defect_entry.get_kumagai_correction(plot=True)`` to plot the
 site potential differences for the defect supercell (which is used to obtain the eFNV (Kumagai-Oba)
 anisotropic charge correction):
@@ -277,6 +284,11 @@ supercells and plotting the charge density. Important terms include:
 3. ``vbm has acceptor phs``/``cbm has donor phs``: Whether a PHS has been automatically identified. Depends on how VBM-like/CBM-like the defect states are and the occupancy of the state. ``(X vs. 0.2)`` refers to the hole/electron occupancy at the band edge vs the default threshold of 0.2 for flagging as a PHS (but you should use your own judgement of course).
 4. ``Localized Orbital(s)``: Information about localised defect states, if present.
 
+Additionally, ``Index`` refers to the band/eigenvalue index in the DFT calculation, ``Energy`` is its
+eigenvalue energy at the given ``K-point coords``, ``Orbitals`` lists the projected orbital contributions
+to that state, and ``OrbDiff`` is the normalised difference in projected orbital contributions to the
+VBM/CBM states between the bulk and defect supercells.
+
 .. code-block:: python
 
     bulk = "Cu2SiSe3/bulk/vasp_std"

doped/analysis.py

@@ -403,8 +403,9 @@ def defect_entry_from_paths(
             corrections to the defect energy (not recommended in most cases).
             Default = False.
         error_tolerance (float):
-            If the estimated error in the defect charge correction is greater
-            than this value (in eV), then a warning is raised. (default: 0.05 eV)
+            If the estimated error in the defect charge correction, based on the
+            variance of the potential in the sampling region is greater than this
+            value (in eV), then a warning is raised. (default: 0.05 eV)
         bulk_band_gap_path (str):
             Path to bulk OUTCAR file for determining the band gap. If the VBM/CBM
             occur at reciprocal space points not included in the bulk supercell
@@ -511,7 +512,8 @@ def __init__(
                 corrections to the defect energies (not recommended in most cases).
                 Default = False.
             error_tolerance (float):
-                If the estimated error in any charge correction is greater than
+                If the estimated error in any charge correction, based on the
+                variance of the potential in the sampling region, is greater than
                 this value (in eV), then a warning is raised. (default: 0.05 eV)
             bulk_band_gap_path (str):
                 Path to bulk OUTCAR file for determining the band gap. If the
@@ -997,12 +999,20 @@ def _mention_bulk_path_subfolder_for_correction_warnings(warning: str) -> str:
 
         def _call_multiple_corrections_tolerance_warning(correction_errors, type="FNV"):
             long_name = "Freysoldt" if type == "FNV" else "Kumagai"
-            correction_errors_string = "\n".join(
-                f"{name}: {error:.3f} eV" for name, error in correction_errors
-            )
+            if error_tolerance >= 0.01:  # if greater than 10 meV, round energy values to meV:
+                error_tol_string = f"{error_tolerance:.3f}"
+                correction_errors_string = "\n".join(
+                    f"{name}: {error:.3f} eV" for name, error in correction_errors
+                )
+            else:  # else give in scientific notation:
+                error_tol_string = f"{error_tolerance:.2e}"
+                correction_errors_string = "\n".join(
+                    f"{name}: {error:.2e} eV" for name, error in correction_errors
+                )
+
             warnings.warn(
                 f"Estimated error in the {long_name} ({type}) charge correction for certain "
-                f"defects is greater than the `error_tolerance` (= {error_tolerance:.3f} eV):"
+                f"defects is greater than the `error_tolerance` (= {error_tol_string} eV):"
                 f"\n{correction_errors_string}\n"
                 f"You may want to check the accuracy of the corrections by plotting the site "
                 f"potential differences (using `defect_entry.get_{long_name.lower()}_correction()`"
@@ -1316,6 +1326,11 @@ def _parse_vr_and_poss_procar(
     parse_procar: bool = True,
 ):
     procar = None
+
+    failed_eig_parsing_warning_message = (
+        f"Could not parse eigenvalue data from vasprun.xml.gz files in {label} folder at {output_path}"
+    )
+
     try:
         vr = get_vasprun(
             vr_path,
@@ -1324,6 +1339,7 @@ def _parse_vr_and_poss_procar(
         )  # vr.eigenvalues not needed for defects except for vr-only eigenvalue analysis
     except Exception as vr_exc:
         vr = get_vasprun(vr_path, parse_projected_eigen=False, parse_eigen=label == "bulk")
+        failed_eig_parsing_warning_message += f", got error:\n{vr_exc}"
 
         if parse_procar:
             procar_path, multiple = _get_output_files_and_check_if_multiple("PROCAR", output_path)
@@ -1332,15 +1348,14 @@ def _parse_vr_and_poss_procar(
                     procar = get_procar(procar_path)
 
                 except Exception as procar_exc:
-                    if parse_projected_eigen is not None:  # otherwise no warning
-                        warning_message = (
-                            f"Could not parse eigenvalue data from vasprun.xml.gz files in "
-                            f"{label} folder at {output_path}, got error:\n{vr_exc}\nThen got "
-                        )
-                        warnings.warn(
-                            f"{warning_message}the following error when attempting to parse projected "
-                            f"eigenvalues from the defect PROCAR(.gz):\n{procar_exc}"
-                        )
+                    failed_eig_parsing_warning_message += (
+                        f"\nThen got the following error when attempting to parse projected eigenvalues "
+                        f"from the defect PROCAR(.gz):\n{procar_exc}"
+                    )
+
+    if vr.projected_eigenvalues is None and procar is None and parse_projected_eigen is True:
+        # only warn if parse_projected_eigen is set to True (not None)
+        warnings.warn(failed_eig_parsing_warning_message)
 
     return vr, procar if parse_procar else vr
 
@@ -1376,8 +1391,9 @@ def __init__(
                 corrections to the defect energy (not recommended in most cases).
                 Default = False.
             error_tolerance (float):
-                If the estimated error in the defect charge correction is greater
-                than this value (in eV), then a warning is raised. (default: 0.05 eV)
+                If the estimated error in the defect charge correction, based on the
+                variance of the potential in the sampling region is greater than this
+                value (in eV), then a warning is raised. (default: 0.05 eV)
             parse_projected_eigen (bool):
                 Whether to parse the projected eigenvalues & orbitals from the bulk and
                 defect calculations (so ``DefectEntry.get_eigenvalue_analysis()`` can
@@ -1464,8 +1480,9 @@ def from_paths(
                 corrections to the defect energy (not recommended in most cases).
                 Default = ``False``.
             error_tolerance (float):
-                If the estimated error in the defect charge correction is greater
-                than this value (in eV), then a warning is raised. (default: 0.05 eV)
+                If the estimated error in the defect charge correction, based on the
+                variance of the potential in the sampling region, is greater than this
+                value (in eV), then a warning is raised. (default: 0.05 eV)
             bulk_band_gap_path (str):
                 Path to bulk ``OUTCAR`` file for determining the band gap. If the
                 VBM/CBM occur at reciprocal space points not included in the bulk
@@ -1781,7 +1798,7 @@ def _read_bulk_voronoi_node_dict(bulk_path):
                     defect_procar=defect_procar,
                 )
             except Exception as exc:
-                if parse_projected_eigen is not None:  # otherwise no warning
+                if parse_projected_eigen is True:  # otherwise no warning
                     warnings.warn(f"Projected eigenvalues/orbitals parsing failed with error: {exc!r}")
 
         defect_vr.projected_eigenvalues = None  # no longer needed, delete to reduce memory demand