Merge pull request #53 from SMTG-Bham/develop

Develop

.github/workflows/test_mac.yml

@@ -5,6 +5,8 @@ on:
 
   workflow_run:
     workflows: [ "Tests" ]
+    branches:
+      - '*'  # all branches
     types:
       - completed  # only test when new release has been deployed to PyPI
 

.pre-commit-config.yaml

@@ -2,14 +2,14 @@ exclude: ^(docs|examples|.github|tests/data)
 repos:
   # Lint and format, isort, docstrings...
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: v0.0.270
+    rev: v0.3.0
     hooks:
       - id: ruff
         args: [--fix]
 
   # Remove trailing whitespace, leave empty line at end of file
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.5.0
     hooks:
       - id: check-yaml
       - id: end-of-file-fixer
@@ -18,12 +18,12 @@ repos:
 
   # Code formatting
   - repo: https://github.com/psf/black
-    rev: 23.3.0
+    rev: 24.2.0
     hooks:
       - id: black  # max line length 107 specified in pyproject.toml
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.3.0
+    rev: v1.8.0
     hooks:
       - id: mypy
 
@@ -38,7 +38,7 @@ repos:
 
   # format docstring length:
   - repo: https://github.com/PyCQA/docformatter
-    rev: v1.7.1
+    rev: v1.7.5
     hooks:
       - id: docformatter
         additional_dependencies: [tomli]

CHANGELOG.rst

@@ -1,6 +1,17 @@
 Change Log
 ==========
 
+v.2.3.3
+----------
+- General robustness updates:
+    - Updated file parsing to avoid hidden files.
+    - Sanity check in `DefectsGenerator` if input symmetry is `P1`.
+    - Add `NKRED` to `INCAR` mismatch tests.
+    - Re-parse config & spin degeneracies in concentration/symmetry functions if data not already present
+      (if user is porting `DefectEntry`s from older `doped` versions or manually).
+    - Avoid unnecessary `DeprecationWarning`s
+- Updated docs and linting
+
 v.2.3.2
 ----------
 - Update to match breaking change in ``pymatgen==2024.3.1`` (released today), handling ``incar_params``.

README.md

@@ -4,21 +4,29 @@
 [![Conda Version](https://img.shields.io/conda/vn/conda-forge/doped.svg)](https://anaconda.org/conda-forge/doped)
 [![Downloads](https://img.shields.io/pypi/dm/doped)](https://pypi.org/project/doped)
 
-<a href="https://doped.readthedocs.io/en/latest/"><img align="right" width="275" 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 package for
-managing solid-state defect calculations, with functionality to
-generate defect structures and relevant competing phases (for chemical potentials), interface with
-[`ShakeNBreak`](https://shakenbreak.readthedocs.io) for
-[defect structure-searching](https://www.nature.com/articles/s41524-023-00973-1), write VASP input files for defect
-supercell calculations, and automatically parse and analyse the results.
-
-Tutorials showing the code functionality and usage are provided on the [docs](https://doped.readthedocs.io/en/latest/) site.
-
-### Example Outputs:
-Chemical potential/stability region plots and defect formation energy (a.k.a. transition level) diagrams:
-
-<a href="https://doped.readthedocs.io/en/latest/chemical_potentials_tutorial.html#analysing-and-visualising-the-chemical-potential-limits"><img align="left" width="365" src="https://raw.githubusercontent.com/SMTG-Bham/doped/main/docs/doped_chempot_plotting.png"></a> <a href="https://doped.readthedocs.io/en/latest/dope_parsing_example.html#defect-formation-energy-transition-level-diagrams"><img align="right" width="385" src="https://raw.githubusercontent.com/SMTG-Bham/doped/main/docs/doped_TLD_plot.png"></a>
-<br><br><br><br><br><br><br><br><br><br><br>
-
+<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).
+<!-- 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>
+
+## Key Features
+All features and functionality are fully-customisable:
+- **Supercell Generation**: Generate an optimal supercell, maximising periodic image separation for the minimum number of atoms (computational cost).
+- **Defect Generation**: Generate defect supercells and guess likely charge states based on chemical intuition.
+- **Calculation I/O**: Automatically write inputs and parse calculations (`VASP` & other DFT/force-field codes).
+- **Chemical Potentials**: Determine relevant competing phases for chemical potential limits, with automated calculation setup, parsing and analysis.
+- **Defect Analysis**: Automatically parse calculation outputs to compute defect formation energies, finite-size corrections (FNV & eFNV), symmetries, degeneracies, transition levels, etc.
+- **Thermodynamic Analysis**: Compute (non-)equilibrium Fermi levels, defect/carrier concentrations etc. as functions of annealing/cooling temperature, chemical potentials etc.
+- **Plotting**: Generate publication-quality plots of defect formation energies, chemical potential limits, defect/carrier concentrations, Fermi levels, charge corrections, etc.
+- **`Python` Interface**: Fully-customisable, modular `Python` API. Plug-and-play w/[`ShakeNBreak`](https://shakenbreak.readthedocs.io) – [defect structure-searching](https://www.nature.com/articles/s41524-023-00973-1), [`easyunfold`](https://smtg-bham.github.io/easyunfold/) – band unfolding, [`CarrierCapture.jl`](https://github.com/WMD-group/CarrierCapture.jl)/[`nonrad`](https://nonrad.readthedocs.io/en/latest/) – non-radiative recombination etc.
+- Reproducibility, tabulation, automated compatibility/sanity checking, strain/displacement analysis, shallow defect analysis, high-throughput compatibility, Wyckoff analysis...
+
+### 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.
+<!-- Update this link!! -->
 
 ## Installation
 ```bash
@@ -35,34 +43,11 @@ If you haven't done so already, you will need to set up your VASP `POTCAR` files
 See the docs [Installation](https://doped.readthedocs.io/en/latest/Installation.html) page for details on this.
 
 
-
 ## `ShakeNBreak`
-As shown in the example notebook, it is highly recommended to use the [`ShakeNBreak`](https://shakenbreak.readthedocs.io/en/latest/) approach when calculating point defects in solids, to ensure you have identified the groundstate structures of your defects. As detailed in the [theory paper](https://doi.org/10.1038/s41524-023-00973-1), skipping this step can result in drastically incorrect formation energies, transition levels, carrier capture (basically any property associated with defects). This approach is followed in the [doped example notebook](https://github.com/SMTG-Bham/doped/blob/main/dope_workflow_example.ipynb), with a more in-depth explanation and tutorial given on the [ShakeNBreak](https://shakenbreak.readthedocs.io/en/latest/) website.
+As shown in the `doped` tutorials, it is highly recommended to use the [`ShakeNBreak`](https://shakenbreak.readthedocs.io/en/latest/) approach when calculating point defects in solids, to ensure you have identified the groundstate structures of your defects. As detailed in the [theory paper](https://doi.org/10.1038/s41524-023-00973-1), skipping this step can result in drastically incorrect formation energies, transition levels, carrier capture (basically any property associated with defects). This approach is followed in the [doped example notebook](https://github.com/SMTG-Bham/doped/blob/main/dope_workflow_example.ipynb), with a more in-depth explanation and tutorial given on the [ShakeNBreak](https://shakenbreak.readthedocs.io/en/latest/) website.
 
-Summary GIF:
 ![ShakeNBreak Summary](https://raw.githubusercontent.com/SMTG-Bham/ShakeNBreak/main/docs/SnB_Supercell_Schematic_PES_2sec_Compressed.gif)
 
-`SnB` CLI Usage:
-![ShakeNBreak CLI](https://raw.githubusercontent.com/SMTG-Bham/ShakeNBreak/main/docs/SnB_CLI.gif)
-
-
-## Acknowledgments
-`doped` (née `DefectsWithTheBoys` #iykyk) has benefitted from feedback from many users, in particular
-members of the [Scanlon](http://davidscanlon.com/) and [Walsh](https://wmd-group.github.io/) research groups who have used / are using it in their work. Direct contributors are listed in the `Contributors` sidebar above; including Seán Kavanagh, Bonan Zhu, Katarina Brlec, Adair Nicolson,
-Sabrine Hachmioune and Savya Aggarwal.
-
-Code to efficiently identify defect species from input supercell structures was contributed by Dr
-[Alex Ganose](https://github.com/utf), and the colour scheme for defect formation energy plots was originally templated from
-the `aide` package, developed by the dynamic duo [Adam Jackson](https://github.com/ajjackson) and [Alex Ganose](https://github.com/utf).
-
-The [docs](https://readthedocs.io) website setup was templated from the `ShakeNBreak` docs set up by [Irea Mosquera-Lois](https://scholar.google.com/citations?user=oIMzt0cAAAAJ&hl=en) 🙌
-
-`doped` was originally based on the excellent
-[PyCDT](https://www.sciencedirect.com/science/article/pii/S0010465518300079) (no longer maintained), but transformed
-and morphed over time as more and more functionality was added. After breaking changes in `pymatgen`, the package was
-entirely refactored and rewritten, to work with the new
-`pymatgen-analysis-defects` package.
-
 ## Studies using `doped`, so far
 
 - 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
@@ -84,3 +69,10 @@ entirely refactored and rewritten, to work with the new
 - Y-S. Choi et al. **_Intrinsic Defects and Their Role in the Phase Transition of Na-Ion Anode Na<sub>2</sub>Ti<sub>3</sub>O<sub>7</sub>_** [_ACS Appl. Energy Mater._](https://doi.org/10.1021/acsaem.2c03466) 2022
 - S. R. Kavanagh, D. O. Scanlon, A. Walsh **_Rapid Recombination by Cadmium Vacancies in CdTe_** [_ACS Energy Letters_](https://pubs.acs.org/doi/full/10.1021/acsenergylett.1c00380) 2021
 - C. J. Krajewska et al. **_Enhanced visible light absorption in layered Cs<sub>3</sub>Bi<sub>2</sub>Br<sub>9</sub> through mixed-valence Sn(II)/Sn(IV) doping_** [_Chemical Science_](https://doi.org/10.1039/D1SC03775G) 2021
+
+## Acknowledgments
+`doped` (née `DefectsWithTheBoys` #iykyk) has benefitted from feedback from many users, in particular
+members of the [Scanlon](http://davidscanlon.com/) and [Walsh](https://wmd-group.github.io/) research groups who have used / are using it in their work. Direct contributors are listed in the `Contributors` sidebar above; including Seán Kavanagh, Alex Squires, Adair Nicolson, Irea Mosquera-Lois, Alex Ganose, Bonan Zhu, Katarina Brlec, Sabrine Hachmioune and Savya Aggarwal.
+
+`doped` was originally based on the excellent `PyCDT` (no longer maintained), but transformed and morphed over time as more and more functionality was added. After breaking changes in `pymatgen`, the package was entirely refactored and rewritten, to work with the new
+`pymatgen-analysis-defects` package.

docs/Dev_ToDo.md

@@ -22,24 +22,14 @@
 ## Housekeeping
 - Tutorials general structure clean-up
 - Clean up repo, removing old unnecessary git blobs
-- Clean `README` with bullet-point summary of key features, and sidebar like `SnB`. Add correction plots and other example outputs (see MRS poster for this).
-- Code tidy up:
-  - Test coverage?
-  - Generate docs locally and check warnings
-  - Add type hints for all functions.
-- Need JOSS requirements; how to run tests and community guidelines
 
 - Docs:
   - Update note at end of thermo tutorial to link to py-sc-fermi/doped interface.
-  - Barebones tutorial workflow, as suggested by Alex G. 
-  - Create GGA practice workflow, for people to learn how to work with doped and defect calculations
-  - Note in Tips page about eFNV correction with layered materials; may want to adjust sampling region (see `doped` Slack discussion). Add link to docstrings when added.
+  - Barebones tutorial workflow, as suggested by Alex G.
   - Add note about `NUPDOWN` for triplet states (bipolarons or dimers (e.g. C-C in Si apparently has ~0.5 eV energy splitting (10.1038/s41467-023-36090-2), and 0.4 eV for O-O in STO from Kanta, but smaller for VCd bipolaron in CdTe))).
   - Add our recommended  workflow (gam, NKRED, std, ncl). See https://sites.tufts.edu/andrewrosen/density-functional-theory/vasp/ for some possibly useful general tips.
   - Show on chemical potentials docs how chempots can be later set as attribute for DefectThermodynamics (loaded from `json`) (e.g. if user had finished and parsed defect calculations first, and then finished chemical potential calculations after).
-  - Show example in docs/advanced tutorial of changing `dist_tol` after parsing
   - Example on docs (miscellaneous/advanced analysis tutorial page?) for adding entries / combining multiple DefectThermodynamics objects
-  - Example in docs of printing number of in-gap thermodynamic TLs, TLs with one meta charge state, and TLs with two meta charge states, using df output from `get_transition_levels` (i.e. to get the numbers we reported in the Te_i Faraday Discussions paper (10.1039/D2FD00043A)
   - Note that bandfilling corrections are no longer supported, as in most cases they shouldn't be used anyway, and if you have band occupation in your supercell then the energies aren't accurate anyway as it's a resonant/shallow defect, and this is just lowering the energy so it sits near the band edge (leads to false charge state behaviour being a bit more common etc). If the user wants to add bandfilling corrections, they can still doing this by calculating it themselves and adding to the `corrections` attribute. (Link our code in old `pymatgen` for doing this)
   - Regarding competing phases with many low-energy polymorphs from the Materials Project; will build
     in a warning when many entries for the same composition, say which have database IDs, warn the user
@@ -66,7 +56,7 @@
     Primitive structure can change, as can supercell / supercell matrix (depending on input structure,
     `generate_supercell` etc), but conventional cell should always be the same (`spglib` convention).
   - Add examples of extending analysis with `easyunfold` and `py-sc-fermi`, and get the lads to add
-    this to their docs as example use cases as well. Add our thesis sc-fermi analysis notebooks to tutorials, and example of doing the Kumagai PRX Energy carrier concentration with TLD plots (can use: https://py-sc-fermi.readthedocs.io/en/latest/tutorial.html#plot-defect-concentrations-as-a-function-of-Fermi-energy). Also include examples of extending to
+    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)
@@ -104,10 +94,6 @@
 ## SK To-Do for next update:
 - `doped` repo/docs cleanup `TODO`s above
 - Add chempot grid plotting tool, shown in `JOSS_plots` using Alex's chemical potential grid, and test (and remove TODO from JOSS plots notebook).
-- Update Sb2O5 test in `test_analysis.py`
-  - Add Sb2O5 as example case in plotting customisation tutorial, nice case for `dist_tol` usage.
-- Plotting lines colour updates.
-- Add sanity check warning with `DefectsGenerator`, if input structure symmetry is `P1` – you sure about this??
-- Add spin degeneracy auto determination to get symmetries/degeneracies later (if hasn't been parsed with current code for some reason e.g. Kanta...). Should implement this for all degeneracy factors whenever concentration methods used?
 - Deal with cases where "X-rich"/"X-poor" corresponds to more than one limit (pick one and warn user?)
-- Note in chempot tutorial you may need to increase the kpoints range for certain metals to reach convergence. Also show writing `KPOINTS` files from convergence dict (as in Alkali_Doping notebook) to folders.
+- `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)
+- Plotting lines colour updates.

docs/Future_ToDo.md

@@ -84,6 +84,8 @@
     Separate lines to the stoichiometrically-equivalent (unperturbed) point defect, but with the same
     colour just different linestyles? (or something similar)
 - `doped` functions should be equally applicable to the base `pymatgen` `Defect`/`DefectEntry` objects (as well as the corresponding `doped` subclasses) as much as possible. Can we add some quick tests for this? 
+- Implement shallow donor/acceptor binding estimation functions (via effective mass theory)
+- Kasamatsu formula for defect concentrations at high concentrations (accounts for lattice site competition), as shown in DefAP paper
 
 ## Docs
 - Add LDOS plotting, big selling point for defects and disorder!

docs/Installation.rst

@@ -39,10 +39,10 @@ for charged defects, your ``POTCAR`` directory needs to be setup to work with ``
    .. code-block:: bash
 
       mkdir temp_potcars  # make a top folder to store the unzipped POTCARs
-      mkdir temp_potcars/POT_PAW_GGA_PBE  # make a subfolder to store the unzipped POTCARs
-      mv potpaw_PBE.54.tar.gz temp_potcars/POT_PAW_GGA_PBE  # copy in your zipped VASP POTCAR source
-      cd temp_potcars/POT_PAW_GGA_PBE
-      tar -xzf potpaw_PBE.54.tar.gz  # unzip your VASP POTCAR source
+      mkdir temp_potcars/POT_GGA_PAW_PBE  # make a subfolder to store the unzipped POTCARs
+      mv potpaw_PBE.54.tar.gz temp_potcars/POT_GGA_PAW_PBE  # copy in your zipped VASP POTCAR source
+      cd temp_potcars/POT_GGA_PAW_PBE
+      tar -xf potpaw_PBE.54.tar.gz  # unzip your VASP POTCAR source
       cd ../..  # return to the top folder
       pmg config -p temp_potcars psp_resources  # configure the psp_resources pymatgen POTCAR directory
       pmg config --add PMG_VASP_PSP_DIR "${PWD}/psp_resources"  # add the POTCAR directory to pymatgen's config file ($HOME/.pmgrc.yaml)