Merge branch 'refs/heads/develop' into dopey_fermi

.github/workflows/JOSS_draft-PDF.yaml

@@ -1,20 +1,21 @@
-on: [push]
+on:
+  workflow_dispatch:  # only if manually run, now JOSS published
 
 jobs:
   paper:
     runs-on: ubuntu-latest
     name: Paper Draft
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Build draft PDF
         uses: openjournals/openjournals-draft-action@master
         with:
           journal: joss
           # This should be the path to the paper within your repo.
           paper-path: docs/JOSS/paper.md
       - name: Upload
-        uses: actions/upload-artifact@v1
+        uses: actions/upload-artifact@v4
         with:
           name: paper
           # This is the output path where Pandoc will write the compiled

.github/workflows/pip_install_test.yml

@@ -18,15 +18,20 @@ jobs:
       fail-fast: false
 
       matrix:
+        os: [ ubuntu-latest, macos-14 ]
         python-version: [ '3.9', '3.10', '3.11' ]
-        os: [ ubuntu-latest ]
+        exclude:
+          - os: macos-14
+            python-version: '3.9'  # Exclude Python 3.9 on macOS, not supported for macOS-14 tests
+        # macos-latest should be 14 according to link below, but currently doesn't?
+        # https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories
 
     runs-on: ${{ matrix.os }}
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
 
-      - uses: actions/setup-python@v2
+      - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -55,7 +60,7 @@ jobs:
       # Upload test plots
       - name: Archive test plots
         if: always()
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: output-plots
           path: tests/remote_baseline

.github/workflows/release.yml

@@ -16,11 +16,11 @@ jobs:
     # only run when tests have passed (or manually triggered)
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
 
-      - uses: actions/setup-python@v3
+      - uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.11"
 
       - name: Install dependencies
         run: |

.github/workflows/test.yml

@@ -3,9 +3,6 @@ name: Tests
 on:
   workflow_dispatch:
 
-  pull_request:
-    branches:
-       - '*'  # all branches
   push:
     branches:
       - '*'  # all branches
@@ -16,15 +13,20 @@ jobs:
       fail-fast: false
 
       matrix:
+        os: [ ubuntu-latest, macos-14 ]
         python-version: [ '3.9', '3.10', '3.11' ]
-        os: [ ubuntu-latest ]
+        exclude:
+          - os: macos-14
+            python-version: '3.9'  # Exclude Python 3.9 on macOS, not supported for macOS-14 tests
+        # macos-latest should be 14 according to link below, but currently doesn't?
+        # https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories
 
     runs-on: ${{ matrix.os }}
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
 
-      - uses: actions/setup-python@v2
+      - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -52,7 +54,7 @@ jobs:
       # Upload test plots
       - name: Archive test plots
         if: always()
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: output-plots
           path: tests/remote_baseline

.readthedocs.yaml

@@ -6,9 +6,9 @@
 version: 2
 
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
-    python: "3.9"
+    python: "3.11"
 
 # Build from the docs/ directory with Sphinx
 sphinx:

CHANGELOG.rst

@@ -1,6 +1,13 @@
 Change Log
 ==========
 
+v.2.4.2
+----------
+- Allow cases where the calculated host material is unstable wrt competing phases (above the hull), by downshifting to the hull and warning the user about this.
+- General updates to chemical potentials code; more robust (better error catches and messages, API key handling), more informative, cleaner outputs.
+- Updates to match recent changes in ``pymatgen`` object types (e.g. https://github.com/SMTG-Bham/doped/issues/68)
+- Minor efficiency & robustness updates
+
 v.2.4.1
 ----------
 - Speed up eigenvalue parsing by using the faster ``doped`` site-matching functions rather than ``MakeDefectStructureInfo`` from ``pydefect``

CITATION.cff

@@ -0,0 +1,80 @@
+cff-version: "1.2.0"
+authors:
+- family-names: Kavanagh
+  given-names: Seán R.
+  orcid: "https://orcid.org/0000-0003-4577-9647"
+- family-names: Squires
+  given-names: Alexander G.
+  orcid: "https://orcid.org/0000-0001-6967-3690"
+- family-names: Nicolson
+  given-names: Adair
+  orcid: "https://orcid.org/0000-0002-8889-9369"
+- family-names: Mosquera-Lois
+  given-names: Irea
+  orcid: "https://orcid.org/0000-0001-7651-0814"
+- family-names: Ganose
+  given-names: Alex M.
+  orcid: "https://orcid.org/0000-0002-4486-3321"
+- family-names: Zhu
+  given-names: Bonan
+  orcid: "https://orcid.org/0000-0001-5601-6130"
+- family-names: Brlec
+  given-names: Katarina
+  orcid: "https://orcid.org/0000-0003-1485-1888"
+- family-names: Walsh
+  given-names: Aron
+  orcid: "https://orcid.org/0000-0001-5460-7033"
+- family-names: Scanlon
+  given-names: David O.
+  orcid: "https://orcid.org/0000-0001-9174-8601"
+contact:
+- family-names: Kavanagh
+  given-names: Seán R.
+  orcid: "https://orcid.org/0000-0003-4577-9647"
+doi: 10.5281/zenodo.10957359
+message: If you use this software, please cite our article in the
+  Journal of Open Source Software.
+preferred-citation:
+  authors:
+  - family-names: Kavanagh
+    given-names: Seán R.
+    orcid: "https://orcid.org/0000-0003-4577-9647"
+  - family-names: Squires
+    given-names: Alexander G.
+    orcid: "https://orcid.org/0000-0001-6967-3690"
+  - family-names: Nicolson
+    given-names: Adair
+    orcid: "https://orcid.org/0000-0002-8889-9369"
+  - family-names: Mosquera-Lois
+    given-names: Irea
+    orcid: "https://orcid.org/0000-0001-7651-0814"
+  - family-names: Ganose
+    given-names: Alex M.
+    orcid: "https://orcid.org/0000-0002-4486-3321"
+  - family-names: Zhu
+    given-names: Bonan
+    orcid: "https://orcid.org/0000-0001-5601-6130"
+  - family-names: Brlec
+    given-names: Katarina
+    orcid: "https://orcid.org/0000-0003-1485-1888"
+  - family-names: Walsh
+    given-names: Aron
+    orcid: "https://orcid.org/0000-0001-5460-7033"
+  - family-names: Scanlon
+    given-names: David O.
+    orcid: "https://orcid.org/0000-0001-9174-8601"
+  date-published: 2024-04-15
+  doi: 10.21105/joss.06433
+  issn: 2475-9066
+  issue: 96
+  journal: Journal of Open Source Software
+  publisher:
+    name: Open Journals
+  start: 6433
+  title: "doped: Python toolkit for robust and repeatable charged defect
+    supercell calculations"
+  type: article
+  url: "https://joss.theoj.org/papers/10.21105/joss.06433"
+  volume: 9
+title: "doped: Python toolkit for robust and repeatable charged defect
+  supercell calculations"

README.md

@@ -3,11 +3,11 @@
 [![PyPI](https://img.shields.io/pypi/v/doped)](https://pypi.org/project/doped)
 [![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)
+[![DOI](https://joss.theoj.org/papers/10.21105/joss.06433/status.svg)](https://doi.org/10.21105/joss.06433)
 
 <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://arxiv.org/abs/2403.08012).
-<!-- Update this link!! -->
+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://doi.org/10.21105/joss.06433).
 
 <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>
 
@@ -26,8 +26,7 @@ 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`. 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!! -->
+displacements from DFT supercell calculations. See the [JOSS paper](https://doi.org/10.21105/joss.06433) for more details.
 
 ## Installation
 ```bash
@@ -44,6 +43,9 @@ Alternatively if desired, `doped` can also be installed from `conda` with:
 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.
 See the docs [Installation](https://doped.readthedocs.io/en/latest/Installation.html) page for details on this.
 
+## Citation
+If you use `doped` in your research, please cite:
+- S. R. Kavanagh et al. [doped: Python toolkit for robust and repeatable charged defect supercell calculations](https://doi.org/10.21105/joss.06433). _Journal of Open Source Software_ 9 (96), 6433, **2024**
 
 ## `ShakeNBreak`
 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.
@@ -52,23 +54,25 @@ As shown in the `doped` tutorials, it is highly recommended to use the [`ShakeNB
 
 ## Studies using `doped`, so far
 
+- B. E. Murdock et al. **_Li-Site Defects Induce Formation of Li-Rich Impurity Phases: Implications for Charge Distribution and Performance of LiNi<sub>0.5-x</sub>M<sub>x</sub>Mn<sub>1.5</sub>O<sub>4</sub> Cathodes (M = Fe and Mg; x = 0.05–0.2)_** [_Advanced Materials_](https://doi.org/10.1002/adma.202400343) 2024
+- A. G. Squires et al. **_Oxygen dimerization as a defect-driven process in bulk LiNiO2<sub>2</sub>_** [_ChemRxiv_](https://doi.org/10.26434/chemrxiv-2024-lcmkj) 2024
 - 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>_** [_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
+- 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
 - A. T. J. Nicolson et al. **_Cu<sub>2</sub>SiSe<sub>3</sub> as a promising solar absorber: harnessing cation dissimilarity to avoid killer antisites_** [_Journal of Materials Chemistry A_](https://doi.org/10.1039/D3TA02429F) 2023
 - Y. W. Woo, Z. Li, Y-K. Jung, J-S. Park, A. Walsh **_Inhomogeneous Defect Distribution in Mixed-Polytype Metal Halide Perovskites_** [_ACS Energy Letters_](https://doi.org/10.1021/acsenergylett.2c02306) 2023
 - P. A. Hyde et al. **_Lithium Intercalation into the Excitonic Insulator Candidate Ta<sub>2</sub>NiSe<sub>5</sub>_** [_Inorganic Chemistry_](https://doi.org/10.1021/acs.inorgchem.3c01510) 2023
 - J. Willis, K. B. Spooner, D. O. Scanlon **_On the possibility of p-type doping in barium stannate_** [_Applied Physics Letters_](https://doi.org/10.1063/5.0170552) 2023
 - J. Cen et al. **_Cation disorder dominates the defect chemistry of high-voltage LiMn<sub>1.5</sub>Ni<sub>0.5</sub>O<sub>4</sub> (LMNO) spinel cathodes_** [_Journal of Materials Chemistry A_](https://doi.org/10.1039/D3TA00532A) 2023
-- J. Willis & R. Claes et al. **_Limits to Hole Mobility and Doping in Copper Iodide_** [_Chem Mater_](https://doi.org/10.1021/acs.chemmater.3c01628) 2023
+- J. Willis & R. Claes et al. **_Limits to Hole Mobility and Doping in Copper Iodide_** [_Chemistry of Materials_](https://doi.org/10.1021/acs.chemmater.3c01628) 2023
 - I. Mosquera-Lois & S. R. Kavanagh, A. Walsh, D. O. Scanlon **_Identifying the ground state structures of point defects in solids_** [_npj Computational Materials_](https://www.nature.com/articles/s41524-023-00973-1) 2023
 - Y. T. Huang & S. R. Kavanagh et al. **_Strong absorption and ultrafast localisation in NaBiS<sub>2</sub> nanocrystals with slow charge-carrier recombination_** [_Nature Communications_](https://www.nature.com/articles/s41467-022-32669-3) 2022
 - S. R. Kavanagh, D. O. Scanlon, A. Walsh, C. Freysoldt **_Impact of metastable defect structures on carrier recombination in solar cells_** [_Faraday Discussions_](https://doi.org/10.1039/D2FD00043A) 2022
-- 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
+- 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 Applied Energy Materials_](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