Shallow defect analysis

.github/workflows/pip_install_test.yml

@@ -38,12 +38,12 @@ jobs:
 
       - name: Test
         run: |
-          pytest -vv tests  # test everything
+          pytest -vv -m "not mpl_image_compare" tests  # all non-plotting tests
 
       - name: Plotting Tests
         id: plotting_tests  # Add an ID to this step for reference
         run: |
-          pytest --mpl -m "mpl_image_compare" tests  # test everything
+          pytest --mpl -m "mpl_image_compare" tests  # all plotting tests
 
       - name: Generate GH Actions test plots
         if: failure() && steps.plotting_tests.outcome == 'failure'  # Run only if plotting tests fail

.github/workflows/test.yml

@@ -35,12 +35,12 @@ jobs:
 
       - name: Test
         run:  |
-          pytest -vv tests  # test everything
+          pytest -vv -m "not mpl_image_compare" tests  # all non-plotting tests
 
       - name: Plotting Tests
         id: plotting_tests  # Add an ID to this step for reference
         run: |
-          pytest --mpl -m "mpl_image_compare" tests  # test everything
+          pytest --mpl -m "mpl_image_compare" tests  # all plotting tests
 
       - name: Generate GH Actions test plots
         if: failure() && steps.plotting_tests.outcome == 'failure'  # Run only if plotting tests fail

.github/workflows/test_mac.yml

@@ -35,12 +35,12 @@ jobs:
 
       - name: Test
         run: |
-          pytest -vv tests  # test everything
+          pytest -vv -m "not mpl_image_compare" tests  # all non-plotting tests
 
       - name: Plotting Tests
         id: plotting_tests  # Add an ID to this step for reference
         run: |
-          pytest --mpl -m "mpl_image_compare" tests  # test everything
+          pytest --mpl -m "mpl_image_compare" tests  # all plotting tests
 
       - name: Generate GH Actions test plots
         if: failure() && steps.plotting_tests.outcome == 'failure'  # Run only if plotting tests fail

CHANGELOG.rst

@@ -1,6 +1,23 @@
 Change Log
 ==========
 
+v.2.4.0
+----------
+- Electronic structure analysis by @adair-nicolson & @kavanase:
+    - Adds ``DefectEntry.get_eigenvalue_analysis()`` method to plot single-particle eigenvalues and
+      analyse orbital character and localisation; usage and examples shown on the
+      `docs Tips <https://doped.readthedocs.io/en/latest/Tips.html#eigenvalue-electronic-structure-analysis>`__
+      page and the `advanced analysis tutorial <https://doped.readthedocs.io/en/latest/advanced_analysis_tutorial.html#eigenvalue-electronic-structure-analysis>`__.
+    - Projected eigenvalues can be parsed from ``vasprun.xml(.gz)`` files (preferred, as more accurate
+      with 4 decimal places; c.f. 3 in ``PROCAR(.gz)``; more convenient and only ~5% slower) or ``PROCAR(.gz)``
+      files in calculation directories (both with significantly expedited parsing compared to ``pymatgen`` methods).
+      Compatible with spin-polarised, unpolarised and SOC calculations. Comes with update by @kavanase to ``easyunfold``
+      ``PROCAR.gz`` parsing.
+- More efficient defect calculation parsing
+- Add ``get_magnetization_from_vasprun`` and ``get_nelect_from_vasprun`` functions to ``doped.utils.parsing``,
+  as these attributes are not available from ``pymatgen.io.vasp.outputs.Vasprun``.
+- Improve testing efficiency
+
 v.2.3.3
 ----------
 - General robustness updates:

README.md

@@ -6,7 +6,7 @@
 
 <a href="https://doped.readthedocs.io/en/latest/"><img align="right" width="150" src="https://raw.githubusercontent.com/SMTG-Bham/doped/main/docs/doped_v2_logo.png" alt="Schematic of a doped (defect-containing) crystal, inspired by the biological analogy to (semiconductor) doping." title="Schematic of a doped (defect-containing) crystal, inspired by the biological analogy to (semiconductor) doping."></a>`doped` is a Python software for the generation, pre-/post-processing and analysis of defect supercell calculations, implementing the defect simulation workflow in an efficient, reproducible, user-friendly yet powerful and fully-customisable manner.
 
-Tutorials showing the code functionality and usage are provided on the [docs](https://doped.readthedocs.io/en/latest/) site, and an overview of the key advances of the package is given in the [JOSS paper](https://github.com/openjournals/joss-reviews/issues/6433).
+Tutorials showing the code functionality and usage are provided on the [docs](https://doped.readthedocs.io/en/latest/) site, and an overview of the key advances of the package is given in the [JOSS paper](https://arxiv.org/abs/2403.08012).
 <!-- Update this link!! -->
 
 <a href="https://doi.org/10.21105/joss.06433"><img class="center" width="800" src="https://raw.githubusercontent.com/SMTG-Bham/doped/main/docs/JOSS/doped_JOSS_workflow_figure.png"></a>

docs/Dev_ToDo.md

@@ -1,7 +1,7 @@
 # `doped` Development To-Do List
 ## Chemical potential
 - 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?
+- 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?)
   - Also see `Cs2SnTiI6` notebooks for template code for this.

docs/JOSS/JOSS_plots.ipynb

@@ -10510,12 +10510,21 @@
    "cell_type": "markdown",
    "source": [
     "# Other Sub-Figures\n",
-    "The functions used to generate all other sub figures in the `doped` JOSS figure are shown in the parsing & thermodynamics tutorials on the docs, with the necessary data provided in the `examples` folder of the GitHub repository. "
+    "The functions used to generate all other sub figures in the `doped` JOSS figure are shown in the parsing, thermodynamics & advanced analysis tutorials on the docs, with the necessary data provided in the `examples` folder of the GitHub repository. "
    ],
    "metadata": {
     "collapsed": false
    },
    "id": "b3c59bcc0fe24b9"
+  },
+  {
+   "cell_type": "code",
+   "outputs": [],
+   "source": [],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "e0ac1958e7d3133d"
   }
  ],
  "metadata": {

docs/JOSS/paper.md

@@ -100,7 +100,7 @@ While each of these codes have their strengths, they do not include the full sui
 The design philosophy of `doped` has been to implement the defect simulation workflow in an efficient, reproducible, user-friendly yet powerful and fully-customisable manner, combining reasonable defaults with full user control for each parameter in the workflow.
 As depicted in \autoref{fig_workflow}, the core functionality of `doped` is the generation of defect supercells and competing phases, writing calculation input files, parsing calculation outputs and analysing/plotting defect-related properties. This functionality and recommended usage of `doped` is demonstrated in the [tutorials](https://doped.readthedocs.io/en/latest/Tutorials.html) on the [documentation website](https://doped.readthedocs.io/en/latest/).
 
-![**a.** Average minimum periodic image distance, normalised by the ideal image distance at that volume (i.e. for a perfect close-packed face-centred cubic (FCC) cell), versus the number of primitive unit cells, for the supercell generation algorithms of `doped`, `ASE` and `pymatgen`. "SC" = simple cubic and "HCP" = hexagonal close-packed. **b.** Average performance of charge state estimation routines from `doped` compared to alternative approaches, in terms of false positives and false negatives. "ICSD probabilities" refers to a model using the probabilities of oxidation states, as given by their occurrence in the ICSD database, as the input on which to estimate likely charge states. Asterisk indicates that the `pyCDT` false _negatives_ are underestimated as the majority of this test set used the estimated charge state ranges from `pyCDT`. "Ox. state" = oxidation state. Example **(c)** Kumagai-Oba (extended Freysoldt-Neugebauer-Van-de-Walle; "eFNV") finite-size correction plot, **(d)** defect formation energy diagram, **(e)** chemical potential / stability region, **(f)** Fermi level vs. annealing temperature, **(g)** defect/carrier concentrations vs. annealing temperature and **(h)** Fermi level / carrier concentration heatmap plots from `doped`. Data and code to reproduce these plots is provided in the [`docs/JOSS`](https://github.com/SMTG-Bham/doped/blob/main/docs/JOSS) subfolder of the `doped` GitHub repository. \label{fig1}](doped_JOSS_figure.png)
+![**a.** Average minimum periodic image distance, normalised by the ideal image distance at that volume (i.e. for a perfect close-packed face-centred cubic (FCC) cell), versus the number of primitive unit cells, for the supercell generation algorithms of `doped`, `ASE` and `pymatgen`. "SC" = simple cubic and "HCP" = hexagonal close-packed. **b.** Average performance of various charge state estimation routines, in terms of false positives/negatives. "ICSD probabilities" refers to a model based on the probabilities of oxidation states, as given by their occurrence in the ICSD database. Asterisk indicates that `pyCDT` "false _negatives_" are underestimated as the majority of this test set used the estimated charge state ranges from `pyCDT`. "Ox. state" = oxidation state. Example **(c)** Kumagai-Oba (extended Freysoldt-Neugebauer-Van-de-Walle; "eFNV") finite-size correction plot, **(d)** defect formation energy diagram, **(e)** chemical potential / stability region, **(f)** Fermi level vs. annealing temperature, **(g)** defect/carrier concentrations vs. annealing temperature and **(h)** Fermi level / carrier concentration heatmap plots from `doped`. Automated plots of single-particle eigenvalues from DFT supercell calculations for **(i)** $V_{Cu}^{0}$ in $Cu_2SiSe_3$ and **(j)** $V_{Cd}^{-1}$ in CdTe. **(k)** Automated site displacement analysis, plotting atomic displacements with respect to the defect site against distance to the defect site, for $V_{Cd}^{-1}$ in CdTe. Data and code to reproduce these plots is provided in the [`docs/JOSS`](https://github.com/SMTG-Bham/doped/blob/main/docs/JOSS) subfolder of the `doped` GitHub repository. \label{fig1}](doped_JOSS_figure.png)
 
 Some key advances of `doped` include:
 
@@ -131,7 +131,7 @@ Some key advances of `doped` include:
 
 - **Automated Compatibility Checking:** When parsing defect calculations, `doped` automatically checks that calculation parameters which could affect the defect formation energy (e.g. _k_-point grid, energy cutoff, pseudopotential choice, exchange fraction, Hubbard U etc.) are consistent between the defect and reference calculations. This is a common source of accidental error in defect calculations, and `doped` provides informative warnings if any inconsistencies are detected. 
 
-- **Thermodynamic Analysis:** `doped` provides a suite of flexible tools for the analysis of defect thermodynamics, including formation energy diagrams (\autoref{fig1}d), equilibrium & non-equilibrium Fermi level solving (\autoref{fig1}f), doping analysis (\autoref{fig1}g,h), Brouwer-type diagrams etc. These include physically-motivated (but tunable) grouping of defect sites, full inclusion of metastable states, support for complex system constraints, optimisation over high-dimensional chemical & temperature space and highly-customisable plotting.
+- **Thermodynamic Analysis:** `doped` provides a suite of flexible tools for the analysis of defect thermodynamics, including formation energy diagrams (\autoref{fig1}d), equilibrium & non-equilibrium Fermi level solving (\autoref{fig1}f), doping analysis (\autoref{fig1}g,h), Brouwer-type diagrams etc. These include physically-motivated (but tunable) grouping of defect sites, full inclusion of metastable states, support for complex system constraints, optimisation over high-dimensional chemical & temperature space and highly-customisable plotting. In-depth examples are provided in the [tutorials](https://doped.readthedocs.io/en/latest/Tutorials.html).
 
 - **Finite-Size Corrections:** Both the isotropic Freysoldt (FNV) [@Freysoldt2009] and anisotropic Kumagai (eFNV) [@kumagai_electrostatics-based_2014] image charge corrections are implemented automatically in `doped`, with tunable sampling radii / sites (which may be desirable for e.g. layered materials), automated correction plotting (to visualise/analyse convergence; \autoref{fig1}c) and automatic sampling error estimation.