Develop

.github/workflows/lint.yml

@@ -16,34 +16,35 @@ jobs:
       max-parallel: 1
 
       matrix:
-        python-version: ['3.10']
+        python-version: ['3.11']
 
     name: Python ${{ matrix.python-version }} Test Pop
 
     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 }}
 
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install setuptools setuptools_scm wheel
-          pip install pydocstyle black flake8 isort
+          pip install pydocstyle black flake8 ruff
           pip install -e .[tests]
 
-      - name: sort imports
+      - name: ruff
         run:  |
-          isort . --atomic --profile black
+          ruff --version
+          ruff --fix shakenbreak
 
       - name: check docstrings
         run:  |
           pydocstyle --version
           pydocstyle -e --count --convention=google --add-ignore=D400,D415,D212,D205,D417,D107 shakenbreak
 
-      - name: black
+      - name: black  # max line length 107 specified in pyproject.toml
         run:  |
           black --version
           black --color shakenbreak

.github/workflows/pip_install_test.yml

@@ -17,15 +17,20 @@ jobs:
       fail-fast: false
 
       matrix:
+        os: [ ubuntu-latest, macos-14 ]
         python-version: [ '3.9', '3.10', '3.11' ]
-        os: [ ubuntu-latest,macos-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 }}
 
@@ -36,20 +41,27 @@ jobs:
           pip install shakenbreak[tests]  # install only from PyPI
 
       - name: Test
-        run:  |
-          pytest --mpl -vv tests  # test everything
-          
+        run: |
+          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_plotting.py  # plotting tests
+          pytest --mpl -m "mpl_image_compare" tests/test_shakenbreak.py  # 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 tests/test_plotting.py
-          pytest --mpl-generate-path=tests/remote_baseline tests/test_shakenbreak.py
+          pytest --mpl-generate-path=tests/remote_baseline -m "mpl_image_compare" tests/test_plotting.py
+          pytest --mpl-generate-path=tests/remote_baseline -m "mpl_image_compare" tests/test_shakenbreak.py
 
       # Upload test plots
       - name: Archive test plots
         if: always()  # always upload the plots, even if the tests fail
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: output-plots
           path: tests/remote_baseline

.github/workflows/release.yml

@@ -18,9 +18,9 @@ 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"
 

.github/workflows/test.yml

@@ -1,14 +1,9 @@
 name: Tests
 
 on:
-  pull_request:
-    branches:
-       - main
-       - develop
   push:
     branches:
-      - main
-      - develop
+      - '*'  # all branches
 
   workflow_dispatch:
 
@@ -18,14 +13,19 @@ jobs:
       fail-fast: false
 
       matrix:
-        python-version: ['3.9', '3.10', '3.11']
-        os: [ubuntu-latest,macos-latest]
+        os: [ ubuntu-latest, macos-14 ]
+        python-version: [ '3.9', '3.10', '3.11' ]
+        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 }}
 
@@ -39,27 +39,30 @@ jobs:
           pip show -V pymatgen-analysis-defects
           pip show -V pymatgen
           pip show -V pytest
+          pip show -V doped
 
       - name: Test
         run:  |
-          pytest --mpl -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_plotting.py  # plotting tests
+          pytest --mpl -m "mpl_image_compare" tests/test_shakenbreak.py  # 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 tests/test_plotting.py
-          pytest --mpl-generate-path=tests/remote_baseline tests/test_shakenbreak.py
+          pytest --mpl-generate-path=tests/remote_baseline -m "mpl_image_compare" tests/test_plotting.py
+          pytest --mpl-generate-path=tests/remote_baseline -m "mpl_image_compare" tests/test_shakenbreak.py
 
       # Upload test plots
       - name: Archive test plots
         if: always()  # always upload the plots, even if the tests fail
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: output-plots
           path: tests/remote_baseline
-
-      # - name: Download a single artifact
-      #   uses: actions/download-artifact@v3
-      #   with:
-      #     name: output-plots

.pre-commit-config.yaml

@@ -2,7 +2,12 @@
 # See https://pre-commit.com/hooks.html for more hooks
 exclude: ^(docs|tests|SnB_input_files|.github|shakenbreak/scripts|CITATION*|MANIFEST*)
 repos:
-
+  # Lint and format, isort, docstrings...
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: v0.3.7
+    hooks:
+      - id: ruff
+        args: [--fix]
 
  # Remove trailing whitespace, leave empty line at end of file
   - repo: https://github.com/pre-commit/pre-commit-hooks
@@ -12,18 +17,6 @@ repos:
     -   id: end-of-file-fixer
     -   id: check-yaml
 
-#  - repo: https://github.com/pre-commit/mirrors-mypy
-#    rev: v0.971
-#    hooks:
-#      - id: mypy
-
-# Sort/format imports
-  - repo: https://github.com/PyCQA/isort
-    rev: 5.12.0
-    hooks:
-      - id: isort
-        args: [--profile, black]
-
 # Check docstrings
   - repo: https://github.com/pycqa/pydocstyle
     rev: 4.0.0  # pick a git hash / tag to point to
@@ -32,8 +25,8 @@ repos:
         args: [-e, --count, "--convention=google", "--add-ignore=D107,D202,D400,D415,D212,D205,D417,D413"]
 
 # Code formatting
-  - repo: https://github.com/psf/black
-    rev: 22.6.0
+  - repo: https://github.com/psf/black  # max line length 107 specified in pyproject.toml
+    rev: 24.2.0
     hooks:
       - id: black
         args: [--color]

.readthedocs.yaml

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

CHANGELOG.rst

@@ -1,6 +1,21 @@
 Change Log
 ==========
 
+v3.3.3
+----------
+- Add ``verbose`` option to more parsing/plotting functions for better control of output detail.
+- Improve effiency & robustness of oxidation state handling.
+- Miscellaneous efficiency (e.g. memory reduction) and robustness updates.
+- Improved GitHub Actions test efficiency.
+
+v3.3.2
+----------
+- Add ``verbose`` options to ``io.parse_energies()`` and ``snb-parse``, also used in ``snb-plot`` and
+  ``snb-analyse``, and set to ``False`` by default to reduce verbosity of certain SnB CLI commands.
+- Use ``doped`` functions to make oxi-state guessing (and thus defect initialisation) more efficient.
+- Miscellaneous efficiency and robustness updates.
+- Testing updates.
+
 v3.3.1
 ----------
 - ``distortion_metadata.json`` for each defect now saved to the individual defect folders (as well as the

README.md

@@ -128,20 +128,22 @@ Automatic testing is run on the master and develop branches using Github Actions
 
 ## Studies using `ShakeNBreak`
 
+- 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
-- 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) 2024
 - 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
 - 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
 - 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
+- B. Peng et al. **_Advancing understanding of structural, electronic, and magnetic properties in 3d-transition-metal TM-doped α-Ga₂O₃ (TM = V, Cr, Mn, and Fe)_** [_Journal of Applied Physics_](https://doi.org/10.1063/5.0173544) 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 (Early version)
+- 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 (Early version)
 - 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 (Early version)
 - (News & Views): A. Mannodi-Kanakkithodi **_The devil is in the defects_** [_Nature Physics_](https://doi.org/10.1038/s41567-023-02049-9) 2023 ([Free-to-read link](https://t.co/EetpnRgjzh))

docs/Contributing.rst

@@ -27,12 +27,12 @@ workflow to do so and follow the `PEP8 <https://peps.python.org/pep-0008/>`_ sty
 
     .. NOTE::
         Alternatively, if you prefer not to use ``pre-commit hooks``, you can manually run the following in the **correct sequence**
-        on your local machine. From the ``shakenbreak`` top directory, run `isort <https://pycqa.github.io/isort/>`_ to sort and format your imports, followed by
+        on your local machine. From the ``shakenbreak`` top directory, run `ruff --fix <https://docs.astral.sh/ruff/>`_ to lint and format, followed by
         `black <https://black.readthedocs.io/en/stable/index.html>`_, which will automatically reformat the code to ``PEP8`` conventions:
 
         .. code:: bash
 
-            $ isort . --profile black
+            $ ruff --fix
             $ black  --diff --color shakenbreak
 
         Then run `pycodestyle <https://pycodestyle.pycqa.org/en/latest/>`_ to check the docstrings,

docs/conf.py

@@ -25,7 +25,7 @@
 author = 'Irea Mosquera-Lois, Seán R. Kavanagh'
 
 # The full version, including alpha/beta/rc tags
-release = '3.3.1'
+release = '3.3.3'
 
 
 # -- General configuration ---------------------------------------------------

docs/index.rst

@@ -211,19 +211,22 @@ run tests and add new tests for any new features whenever submitting pull reques
 Studies using ``ShakeNBreak``
 =============================
 
+- 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` **M** :sub:`x` **Mn** :sub:`1.5` **O** :sub:`4`  **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 LiNiO₂** `ChemRxiv <https://doi.org/10.26434/chemrxiv-2024-lcmkj>`_ 2024
 - X\. Wang et al. **Upper efficiency limit of Sb₂Se₃ 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
-- K\. Li et al. **Computational Prediction of an Antimony-based n-type Transparent Conducting Oxide: F-doped Sb₂O₅** `ChemRxiv <https://chemrxiv.org/engage/chemrxiv/article-details/65846b8366c1381729bc5f23>`_ 2024
+- K\. Li et al. **Computational Prediction of an Antimony-based n-type Transparent Conducting Oxide: F-doped Sb₂O₅** `Chemistry of Materials <https://doi.org/10.1021/acs.chemmater.3c03257>`_ 2024
 - 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
 - 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
 - A\. T. J. Nicolson et al. **Cu₂SiSe₃ as a promising solar absorber: harnessing cation dissimilarity to avoid killer antisites** `Journal of Materials Chemistry A <https://doi.org/10.1039/D3TA02429F>`__ 2023
-- J\. Cen et al. **Cation disorder dominates the defect chemistry of high-voltage LiMn** :sub:`1.5`**Ni** :sub:`0.5`**O₄ (LMNO) spinel cathodes** `Journal of Materials Chemistry A`_ 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\. Cen et al. **Cation disorder dominates the defect chemistry of high-voltage LiMn** :sub:`1.5` **Ni** :sub:`0.5` **O₄ (LMNO) spinel cathodes** `Journal of Materials Chemistry A`_ 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`_ 2023
+- B\. Peng et al. **Advancing understanding of structural, electronic, and magnetic properties in 3d-transition-metal TM-doped α-Ga₂O₃ (TM = V, Cr, Mn, and Fe)** `Journal of Applied Physics <https://doi.org/10.1063/5.0173544>`__ 2023
 - Y\. T. Huang & S. R. Kavanagh et al. **Strong absorption and ultrafast localisation in NaBiS₂ nanocrystals with slow charge-carrier recombination** `Nature Communications`_ 2022
 - S\. R. Kavanagh, D. O. Scanlon, A. Walsh, C. Freysoldt **Impact of metastable defect structures on carrier recombination in solar cells** `Faraday Discussions`_ 2022
-- Y-S\. Choi et al. **Intrinsic Defects and Their Role in the Phase Transition of Na-Ion Anode Na₂Ti₃O₇** `ACS Appl. Energy Mater. <https://doi.org/10.1021/acsaem.2c03466>`__ 2022 (Early version)
+- Y-S\. Choi et al. **Intrinsic Defects and Their Role in the Phase Transition of Na-Ion Anode Na₂Ti₃O₇** `ACS Applied Energy Materials <https://doi.org/10.1021/acsaem.2c03466>`__ 2022 (Early version)
 - 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₃Bi₂Br₉ through mixed-valence Sn(II)/Sn(IV) doping** `Chemical Science`_ 2021 (Early version)
 - (News & Views): A. Mannodi-Kanakkithodi **The devil is in the defects** `Nature Physics`_ 2023 (`Free-to-read link <https://t.co/EetpnRgjzh>`__)