Merge branch 'develop' into dopey_fermi

# Conflicts:
#	docs/Tutorials.rst
#	doped/core.py
#	doped/thermodynamics.py

.github/workflows/pip_install_test.yml

@@ -38,14 +38,16 @@ jobs:
 
  - name: Test
  run: |
- pytest -vv tests # test everything
+ pytest -vv -m "not mpl_image_compare" tests # all non-plotting tests
 
  - name: Plotting Tests
+ if: always() # run even if non-plotting tests fail
+ 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: always()  # always generate the plots, even if the tests fail
+ if: failure() && steps.plotting_tests.outcome == 'failure' # Run only if plotting tests fail
  run: |
  # Generate the test plots in case there were any failures:
  pytest --mpl-generate-path=tests/remote_baseline -m "mpl_image_compare" tests

.github/workflows/release.yml

@@ -1,16 +1,14 @@
 name: Release and publish
 
 on:
- workflow_dispatch:
-
  workflow_run:
  workflows: [ "Tests" ]
  branches: [ main ]
  types:
  - completed # only release when tests have passed
- paths:
- - 'setup.py' # only release when setup.py has been updated
 
+ workflow_dispatch: # or if manually run
+
 jobs:
  release:
  runs-on: ubuntu-latest
@@ -20,36 +18,52 @@ jobs:
  steps:
  - uses: actions/checkout@v2
 
- - uses: actions/setup-python@v1
+ - uses: actions/setup-python@v3
  with:
- python-version: 3.9
+ python-version: "3.10"
 
  - name: Install dependencies
  run: |
  python -m pip install --upgrade pip
  pip install setuptools setuptools_scm wheel
  pip install -e .
 
+ - name: Check if version has changed
+ id: check_version
+ run: |
+ current_pip_version=$(pip index versions doped | grep LATEST | awk '{print $NF}')
+ current_repo_version=$(grep version pyproject.toml | awk '{print $NF}' | tr -d '"' | head -1)
+ if [ "$current_pip_version" != "$current_repo_version" ]; then
+ echo "version_changed=true" >> $GITHUB_ENV
+ else
+ echo "version_changed=false" >> $GITHUB_ENV
+ fi
+
  - name: Build packages
+ if: env.version_changed == 'true'
  run: |
  python3 -m pip install --upgrade build
  python3 -m build
 
  - name: Publish
+ if: env.version_changed == 'true'
  uses: pypa/gh-action-pypi-publish@master
  with:
  password: ${{ secrets.PYPI_API_TOKEN }}
 
  - name: Write release info
+ if: env.version_changed == 'true'
  run: |
  awk 'BEGIN {p = 0} {a = 0 }; /^v\d*.\d*.\d*./ { p += 1; a = 1}; p + a == 1 { print } ' CHANGELOG.rst | sed -e '1,1d' | sed -e '/./,$!d' -e :a -e '/^\n*$/{$d;N;ba' -e '}' > release_info.txt
 
  - name: Get Release Tag
+ if: env.version_changed == 'true'
  run: |
  VERSION=$(grep version pyproject.toml | awk '{print $NF}' | tr -d '"' | head -1)
  echo "version=${VERSION}" >> $GITHUB_ENV
 
  - name: Release
+ if: env.version_changed == 'true'
  uses: actions/create-release@v1
  id: create_release
 

.github/workflows/test.yml

@@ -35,15 +35,17 @@ jobs:
 
  - name: Test
  run: |
- pytest -vv tests # test everything
+ pytest -vv -m "not mpl_image_compare" tests # all non-plotting tests
 
  - name: Plotting Tests
+ if: always() # run even if non-plotting tests fail
+ 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: always()  # always generate the plots, even if the tests fail
- run:  |
+ if: failure() && steps.plotting_tests.outcome == 'failure' # Run only if plotting tests fail
+ run: |
  # Generate the test plots in case there were any failures:
  pytest --mpl-generate-path=tests/remote_baseline -m "mpl_image_compare" tests
 

.github/workflows/test_mac.yml

@@ -35,14 +35,16 @@ jobs:
 
  - name: Test
  run: |
- pytest -vv tests # test everything
+ pytest -vv -m "not mpl_image_compare" tests # all non-plotting tests
 
  - name: Plotting Tests
+ if: always() # run even if non-plotting tests fail
+ 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: always()  # always generate the plots, even if the tests fail
+ if: failure() && steps.plotting_tests.outcome == 'failure' # Run only if plotting tests fail
  run: |
  # Generate the test plots in case there were any failures:
  pytest --mpl-generate-path=tests/remote_baseline -m "mpl_image_compare" tests

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>
@@ -25,7 +25,8 @@ All features and functionality are fully-customisable:
 
 ### Performance and Example Outputs
 ![https://github.com/openjournals/joss-reviews/issues/6433](docs/JOSS/doped_JOSS_figure.png)
-**a.** Optimal supercell generation comparison. **b.** Charge state estimation comparison. Example **(c)** Kumagai-Oba (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`. See the [JOSS paper](https://github.com/openjournals/joss-reviews/issues/6433) for more details.
+**(a)** Optimal supercell generation comparison. **(b)** Charge state estimation comparison. Example **(c)** Kumagai-Oba (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 **(i,j)** single-particle eigenvalues and **(k)** site
+displacements from DFT supercell calculations. See the [JOSS paper](https://github.com/openjournals/joss-reviews/issues/6433) for more details.
 <!-- Update this link!! -->
 
 ## Installation
@@ -37,6 +38,7 @@ Alternatively if desired, `doped` can also be installed from `conda` with:
 
 ```bash
  conda install -c conda-forge doped
+ pip install pydefect # pydefect not available on conda, so needs to be installed with pip or otherwise, if using the eFNV correction
 ```
 
 If you haven't done so already, you will need to set up your VASP `POTCAR` files and `Materials Project` API with `pymatgen` using the `.pmgrc.yaml` file, in order for `doped` to automatically generate VASP input files for defect calculations and determine competing phases for chemical potentials.
@@ -53,7 +55,7 @@ As shown in the `doped` tutorials, it is highly recommended to use the [`ShakeNB
 - X. Wang et al. **_Upper efficiency limit of Sb<sub>2</sub>Se<sub>3</sub> solar cells_** [_arXiv_](https://arxiv.org/abs/2402.04434) 2024
 - I. Mosquera-Lois et al. **_Machine-learning structural reconstructions for accelerated point defect calculations_** [_arXiv_](https://doi.org/10.48550/arXiv.2401.12127) 2024
 - W. Dou et al. **_Giant Band Degeneracy via Orbital Engineering Enhances Thermoelectric Performance from Sb<sub>2</sub>Si<sub>2</sub>Te<sub>6</sub> to Sc<sub>2</sub>Si<sub>2</sub>Te<sub>6</sub>_** [_ChemRxiv_](https://doi.org/10.26434/chemrxiv-2024-hm6vh) 2024
-- K. Li et al. **_Computational Prediction of an Antimony-based n-type Transparent Conducting Oxide: F-doped Sb<sub>2</sub>O<sub>5</sub>_** [_ChemRxiv_](https://chemrxiv.org/engage/chemrxiv/article-details/65846b8366c1381729bc5f23) 2023
+- K. Li et al. **_Computational Prediction of an Antimony-based n-type Transparent Conducting Oxide: F-doped Sb<sub>2</sub>O<sub>5</sub>_** [_Chemistry of Materials_](https://doi.org/10.1021/acs.chemmater.3c03257) 2023
 - X. Wang et al. **_Four-electron negative-U vacancy defects in antimony selenide_** [_Physical Review B_](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.108.134102) 2023
 - Y. Kumagai et al. **_Alkali Mono-Pnictides: A New Class of Photovoltaic Materials by Element Mutation_** [_PRX Energy_](http://dx.doi.org/10.1103/PRXEnergy.2.043002) 2023
 - S. M. Liga & S. R. Kavanagh, A. Walsh, D. O. Scanlon, G. Konstantatos **_Mixed-Cation Vacancy-Ordered Perovskites (Cs<sub>2</sub>Ti<sub>1–x</sub>Sn<sub>x</sub>X<sub>6</sub>; X = I or Br): Low-Temperature Miscibility, Additivity, and Tunable Stability_*** [_Journal of Physical Chemistry C_](https://doi.org/10.1021/acs.jpcc.3c05204) 2023

docs/Contributing.rst

@@ -23,6 +23,6 @@ run tests and add new tests for any new features whenever submitting pull reques
 
 .. NOTE::
  If you run into any issues using ``doped`` that aren't addressed on the
- [Troubleshooting](https://doped.readthedocs.io/en/latest/Troubleshooting.html) page, please contact
+ `Troubleshooting <https://doped.readthedocs.io/en/latest/Troubleshooting.html>`_ page, please contact
  the developers through the ``GitHub`` `Issues <https://github.com/SMTG-Bham/doped/issues>`_ page, or
  by email.

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.
@@ -36,7 +36,6 @@
  and direct to relevant section on the docs -> Give some general foolproof advice for how best to deal
  with these cases (i.e. check the ICSD and online for which is actually the groundstate structure,
  and/or if it's known from other work for your chosen functional etc.)
- - Add notes about polaron finding (use SnB and/or MAGMOMs. Any other advice to add? See Abdullah/Dan chat and YouTube tutorial, should have note about setting `MAGMOM`s for defects somewhere). `doped` can't do automatically because far too much defect/material-specific dependence.
  - Show our workflow for calculating interstitials (see docs Tips page, i.e. `vasp_gam` relaxations first (can point to defects tutorial for this)) -> Need to mention this in the defects tutorial, and point to discussion in Tips docs page.
  - Add mini-example of calculating the dielectric constant (plus convergence testing with `vaspup2.0`) to docs/examples, and link this when `dielectric` used in parsing examples. Should also note that the dielectric should be in the same xyz Cartesian basis as the supercell calculations (likely but not necessarily the same as the raw output of a VASP dielectric calculation if an oddly-defined primitive cell is used)
  - Note about cost of `vasp_ncl` chemical potential calculations for metals, use `ISMEAR = -5`,
@@ -45,11 +44,6 @@
  - Readily-usable in conjunction with `atomate`, `AiiDA`(-defects), `vise`, `CarrierCapture`, and give some
  quick examples? Add as optional dependencies.
  - Workflow diagram with: https://twitter.com/Andrew_S_Rosen/status/1678115044348039168?s=20
- - Note about `ISPIN = 1` for even no. of electrons defect species, **if you're sure there's no
- magnetic ordering!** – which you can check in the `OUTCAR` by looking at `magnetization (x)` `y`
- and `z`, and checking that everything is zero (not net magnetisation, as could have opposing spin
- bipolaron). This is automatically handled in `SnB_replace_mag.py` (to be added to ShakeNBreak) and
- will be added to `doped` VASP calc scripts.
  - Setting `LREAL = Auto` can sometimes be worth doing if you have a very large supercell for speed up, _but_ it's important to do a final calculation with `LREAL = False` for accurate energies/forces, so only do if you're a power user and have a very large supercell.
  - Show usage of `get_conv_cell_site` in notebooks/docs (in an advanced analysis tutorial with other possibly useful functions being showcased?)
  - Note in docs that `spglib` convention used for Wyckoff labels and conventional structure definition.
@@ -59,11 +53,12 @@
  this to their docs as example use cases as well. Also include examples of extending to
  non-radiative carrier capture calcs with `CarrierCapture.jl` and `nonrad`. Show example of using
  `sumo` to get the DOS plot of a defect calc, and why this is useful.
- - Worth adding a very short example showing how to set `MAGMOM`s for AFM/FM systems (see Dan & Abdullah chat)
  - Note about SOC for chemical potential calculations ([FERE paper](https://doi.org/10.1103/PhysRevB.
  85.115104) suggests that the SOC effects on total energy cancel out for chemical potential
  calculations, but only the case when the occupation of the SOC-affected orbitals is constant
  (typically not the case)) Better to do consistently (link Emily SOC work and/or thesis).
+ - But, can generally use non-SOC energies to reliably determine relative energies of polymorphs of the same composition (oxidation states), to good accuracy.
+ - Also, can use symmetry with SOC total energy calculations, have tested this. Also `NKRED` possibly useful for expensive (particularly metal) calculations!
  - Link to Irea review, saying that while spin and configurational degeneracies are accounted for
  automatically in `doped`, excited-state degeneracy (e.g. with bipolarons/dimers with single and triplet
  states) are not, so the user should manually account for this if present. Also note that
@@ -93,7 +88,9 @@
 
 ## SK To-Do for next update:
 - `doped` repo/docs cleanup `TODO`s above
+- Quick-start tutorial suggested by Alex G
 - Add chempot grid plotting tool, shown in `JOSS_plots` using Alex's chemical potential grid, and test (and remove TODO from JOSS plots notebook).
 - Deal with cases where "X-rich"/"X-poor" corresponds to more than one limit (pick one and warn user?)
 - `dist_tol` should also group defects for the concentration etc functions, currently doesn't (e.g. `CdTe_thermo.get_equilibrium_concentrations(limit="Te-rich", per_charge=False, fermi_level=0.5)` and `CdTe_thermo.dist_tol=10; CdTe_thermo.get_equilibrium_concentrations(limit="Te-rich", per_charge=False, fermi_level=0.5)`, same output)
+- Add example to chemical potentials / thermodynamics analysis tutorials of varying chemical potentials as a function of temperature/pressure (i.e. gas phases), using the `Spinney` functions detailed here (https://spinney.readthedocs.io/en/latest/tutorial/chemipots.html#including-temperature-and-pressure-effects-through-the-gas-phase-chemical-potentials) or possibly `DefAP` functions otherwise.
 - Plotting lines colour updates.

docs/Future_ToDo.md

@@ -31,6 +31,7 @@
  workflow which ppl often mess up. Can use modified code from `config-coord-plots` (but actually to
  scale and automatically/sensibly parsed etc.)(also see `CarrierCapture` functionalities)
 - Dielectric/kpoint-sampling weighted supercell generation? (essentially just a vectorised cost function implemented in the generation loop). Would natively optimise e.g. layered materials quite well.
+- `doped`/`SnB`/`easyunfold` (virtual) workshop? Just noting as a possibility, could be MCC-supported.
 
 ## Chemical Potentials
 - Overhaul chemical potentials code, dealing with all `TODO`s in that module.