Merge pull request #61 from SMTG-Bham/sorted_structure_update

Sorted structure update

.github/workflows/pip_install_test.yml

@@ -9,18 +9,18 @@ on:
   workflow_dispatch:
 
 jobs:
-  build-linux:
-    runs-on: ubuntu-latest
+  build:
     if: ${{ github.event_name == 'workflow_dispatch' || (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success') }}
     # only run when tests have passed (or manually triggered)
 
     strategy:
-      max-parallel: 5
+      fail-fast: false
 
       matrix:
-        python-version: ['3.8', '3.9', '3.10', '3.11']
+        python-version: [ '3.8', '3.9', '3.10', '3.11' ]
+        os: [ ubuntu-latest,macos-latest,windows-latest ]
 
-    name: Python ${{ matrix.python-version }} pip install
+    runs-on: ${{matrix.os}}
 
     steps:
       - uses: actions/checkout@v2

.github/workflows/test.yml

@@ -12,16 +12,15 @@ on:
   workflow_dispatch:
 
 jobs:
-  build-linux:
-    runs-on: ubuntu-latest
+  build:
     strategy:
-      max-parallel: 5
+      fail-fast: false
 
       matrix:
         python-version: ['3.8', '3.9', '3.10', '3.11']
+        os: [ubuntu-latest,macos-latest,windows-latest]
 
-    name: Python ${{ matrix.python-version }} Test Pop
-
+    runs-on: ${{matrix.os}}
     steps:
       - uses: actions/checkout@v2
 

CHANGELOG.rst

@@ -1,6 +1,15 @@
 Change Log
 ==========
 
+v3.2.3
+----------
+- Ensure the sorted `pymatgen` `Structure` is created for the VASP input (fixes a rare bug in `v3.2.1`
+  and `v3.2.2` where for certain structures the order of elements in the POSCAR was not properly sorted,
+  which is usually fine, but messed with the `ROPT` `INCAR` setting).
+- Plotting format updates (make legend frame more transparent to make datapoints behind it easier to see).
+- Update tests
+- Update docs (note about handling AFM systems)
+
 v3.2.2
 ----------
 - Consolidate ``SnB``/``doped`` ``INCAR`` defaults and remove redundant settings.

README.md

@@ -1,4 +1,4 @@
-[![Build status](https://github.com/SMTG-UCL/ShakeNBreak/actions/workflows/test.yml/badge.svg)](https://github.com/SMTG-UCL/ShakeNBreak/actions)
+[![Build status](https://github.com/SMTG-Bham/ShakeNBreak/actions/workflows/test.yml/badge.svg)](https://github.com/SMTG-Bham/ShakeNBreak/actions)
 [![Documentation Status](https://readthedocs.org/projects/shakenbreak/badge/?version=latest&style=flat)](https://shakenbreak.readthedocs.io/en/latest/)
 [![JOSS](https://joss.theoj.org/papers/10.21105/joss.04817/status.svg)](https://doi.org/10.21105/joss.04817)
 [![PyPI](https://img.shields.io/pypi/v/shakenbreak)](https://pypi.org/project/shakenbreak)
@@ -7,7 +7,7 @@
 [![npj](https://img.shields.io/badge/npj%20Comput%20Mater%20-Mosquera--Lois%2C%20I.%2C%20Kavanagh%2C%20S.R.%2C%20Walsh%2C%20A.%20%26%20Scanlon%2C%20D.O.%20--%202023-9cf)](https://www.nature.com/articles/s41524-023-00973-1)
 
 # `ShakeNBreak` (`SnB`)
-<a href="https://shakenbreak.readthedocs.io/en/latest/"><img align="right" width="400" src="https://raw.githubusercontent.com/SMTG-UCL/ShakeNBreak/main/docs/toc.png"></a> `ShakeNBreak` is a defect structure-searching method employing chemically-guided bond distortions to
+<a href="https://shakenbreak.readthedocs.io/en/latest/"><img align="right" width="400" src="https://raw.githubusercontent.com/SMTG-Bham/ShakeNBreak/main/docs/toc.png"></a> `ShakeNBreak` is a defect structure-searching method employing chemically-guided bond distortions to
 locate ground-state and metastable structures of point defects in solid materials. [Docs here!](https://shakenbreak.readthedocs.io/en/latest/)
 
 Main features include:
@@ -22,7 +22,7 @@ Main features include:
 
 The code currently supports `VASP`, `CP2K`, `Quantum-Espresso`, `CASTEP` & `FHI-aims`. Code contributions to support additional solid-state packages are welcome.
 
-![ShakeNBreak Summary](https://raw.githubusercontent.com/SMTG-UCL/ShakeNBreak/main/docs/SnB_Supercell_Schematic_PES_2sec_Compressed.gif)
+![ShakeNBreak Summary](https://raw.githubusercontent.com/SMTG-Bham/ShakeNBreak/main/docs/SnB_Supercell_Schematic_PES_2sec_Compressed.gif)
 
 ### Literature
 - Preview: Mosquera-Lois, I.; Kavanagh, S. R. [In Search of Hidden Defects](https://doi.org/10.1016/j.matt.2021.06.003), _Matter_ 4 (8), 2602-2605, **2021**
@@ -56,7 +56,7 @@ For development work, ShakeNBreak can also be installed from a copy of the sourc
 
 1. Download `ShakeNBreak` source code using the command:
 ```bash
-  git clone https://github.com/SMTG-UCL/ShakeNBreak
+  git clone https://github.com/SMTG-Bham/ShakeNBreak
 ```
 2. Navigate to root directory:
 ```bash
@@ -76,7 +76,7 @@ For development work, ShakeNBreak can also be installed from a copy of the sourc
 
 ### Command line interface
 Alternatively, the code can be used via the command line:
-![ShakeNBreak CLI](https://raw.githubusercontent.com/SMTG-UCL/ShakeNBreak/main/docs/SnB_CLI.gif)
+![ShakeNBreak CLI](https://raw.githubusercontent.com/SMTG-Bham/ShakeNBreak/main/docs/SnB_CLI.gif)
 
 The functions provided include:
 * [`snb-generate`](https://shakenbreak.readthedocs.io/en/latest/shakenbreak.cli.html#snb-generate): Generate distorted structures for a given defect
@@ -111,7 +111,7 @@ Please let us know if you have any issues with compatibility, or if you would li
 ## Contributing
 
 ### Bugs reports, feature requests and questions
-Please use the [Issue Tracker](https://github.com/SMTG-UCL/ShakeNBreak/issues) to report bugs or request new features.
+Please use the [Issue Tracker](https://github.com/SMTG-Bham/ShakeNBreak/issues) to report bugs or request new features.
 
 Contributions to extend this package are very welcome! Please use the
 ["Fork and Pull"](https://docs.github.com/en/get-started/quickstart/contributing-to-projects)
@@ -128,9 +128,11 @@ Automatic testing is run on the master and develop branches using Github Actions
 
 ## Studies using `ShakeNBreak`
 We'll add papers that use `ShakeNBreak` to this list as they come out!
+
+- X. Wang et al. [_Physical Review B_](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.108.134102) 2023
+- Y. Kumagai, S. R. Kavanagh et al [_PRX Energy_](http://dx.doi.org/10.1103/PRXEnergy.2.043002) 2023
 - J. Willis, K. B. Spooner, D. O. Scanlon. [_ChemRxiv_](https://chemrxiv.org/engage/chemrxiv/article-details/64c29140ce23211b20a787bb) 2023
 - A. T. J. Nicolson et al. [_Journal of Materials Chemistry A_](https://doi.org/10.1039/D3TA02429F) 2023
-- X. Wang et al. [_arXiv_](https://arxiv.org/abs/2302.04901) 2023
 - J. Cen et al. [_Journal of Materials Chemistry A_](https://doi.org/10.1039/D3TA00532A) 2023
 - J. Willis & R. Claes et al. [_ChemRxiv_](https://doi.org/10.26434/chemrxiv-2023-lttnf) 2023
 - I. Mosquera-Lois & S. R. Kavanagh, A. Walsh, D. O. Scanlon [_npj Computational Materials_](https://doi.org/10.1038/s41524-023-00973-1) 2023

docs/Analysis.rst

@@ -246,7 +246,7 @@ manually (not recommended) or using the other defect codes listed on the
 
 As shown in the `doped <https://doped.readthedocs.io/en/latest/index.html>`_ tutorials and docs, you may
 want to further analyse the behaviour and impact on material properties of your defects using advanced
-defect analysis codes such as `easyunfold <https://smtg-ucl.github.io/easyunfold/>`_ (to analyse the
+defect analysis codes such as `easyunfold <https://smtg-bham.github.io/easyunfold/>`_ (to analyse the
 electronic structure of defects in your material),
 `py-sc-fermi <https://py-sc-fermi.readthedocs.io/en/latest/>`_ (to analyse defect concentrations, doping
 and Fermi level tuning), or `nonrad <https://nonrad.readthedocs.io/en/latest/>`_ /

docs/Contributing.rst

@@ -4,7 +4,7 @@ Contributing
 Bugs reports, feature requests and questions
 ---------------------------------------------
 
-Please use the `Issue Tracker <https://github.com/SMTG-UCL/ShakeNBreak/issues>`_ to report bugs or
+Please use the `Issue Tracker <https://github.com/SMTG-Bham/ShakeNBreak/issues>`_ to report bugs or
 request new features. Contributions to extend this package are welcome! Please use the
 `Fork and Pull <https://docs.github.com/en/get-started/quickstart/contributing-to-projects>`_
 workflow to do so and follow the `PEP8 <https://peps.python.org/pep-0008/>`_ style guidelines.
@@ -49,7 +49,7 @@ workflow to do so and follow the `PEP8 <https://peps.python.org/pep-0008/>`_ sty
 Tests
 -------
 
-Unit tests are in the `tests <https://github.com/SMTG-UCL/ShakeNBreak/tree/main/tests>`_ directory
+Unit tests are in the `tests <https://github.com/SMTG-Bham/ShakeNBreak/tree/main/tests>`_ directory
 and can be run from the top directory using ``unittest``. Automatic testing is run on the master and
 develop branches using `Github Actions <https://docs.github.com/en/actions>`_. Please
 run tests and add new tests for any new features whenever submitting pull requests.

docs/Generation.rst

@@ -32,7 +32,7 @@ we'll get a warning and we'll need to specify the defect site with the ``--defec
 
 .. NOTE::
     To specify additional distortion parameters, we can use a
-    `config.yaml <https://github.com/SMTG-UCL/ShakeNBreak/blob/main/SnB_input_files/example_generate_config.yaml>`_
+    `config.yaml <https://github.com/SMTG-Bham/ShakeNBreak/blob/main/SnB_input_files/example_generate_config.yaml>`_
     file like the one below and use the ``--config`` flag to specify its path (i.e. ``snb-generate --config ./my_config.yaml``).
     A detailed description of all the parameters is available in the Python API section
     (:ref:`shakenbreak.input.Distortions class <api_input>`).
@@ -122,7 +122,7 @@ the following directory structures will be parsed correctly:
 
 .. NOTE::
     To specify the charge state range for each defect, as well as other optional arguments, we can use a
-    `config.yaml <https://github.com/SMTG-UCL/ShakeNBreak/blob/main/SnB_input_files/example_generate_all_config.yaml>`_ file
+    `config.yaml <https://github.com/SMTG-Bham/ShakeNBreak/blob/main/SnB_input_files/example_generate_all_config.yaml>`_ file
     like the one below. A detailed description of all the parameters is available in the
     Python API section (:ref:`shakenbreak.input.Distortions class <api_input>`).
 

docs/Installation.rst

@@ -41,7 +41,7 @@ For development work, ``ShakeNBreak`` can also be installed from a copy of the s
 
    .. code:: bash
 
-      git clone https://github.com/SMTG-UCL/ShakeNBreak
+      git clone https://github.com/SMTG-Bham/ShakeNBreak
 
 2. Navigate to root directory:
 

docs/ShakeNBreak_Example_Workflow.ipynb

@@ -4096,7 +4096,7 @@
     "### Further Defect Analysis\n",
     "Once the ground state (and metastable) defect structures have been identified, we will want to compute their formation energies using our final fully-converged calculation parameters (i.e. plane-wave cutoff and k-point sampling). This can be done using [`doped`](https://doped.readthedocs.io/en/latest/), manually (not recommended) or using the other defect codes listed on the [Code Compatibility](https://shakenbreak.readthedocs.io/en/latest/Code_Compatibility.html) page.\n",
     "\n",
-    "As shown in the [`doped`](https://doped.readthedocs.io/en/latest/) examples and docs, you may want to further analyse the behaviour and impact on material properties of your defects using advanced defect analysis codes such as [`easyunfold`](https://smtg-ucl.github.io/easyunfold/) (to analyse the electronic structure of defects in your material), [`py-sc-fermi`](https://py-sc-fermi.readthedocs.io/en/latest/) (to analyse defect concentrations, doping and Fermi level tuning), or [`nonrad`](https://nonrad.readthedocs.io/en/latest/)/[`CarrierCapture.jl`](https://wmd-group.github.io/CarrierCapture.jl/dev/) (to analyse non-radiative electron-hole recombination at defects)."
+    "As shown in the [`doped`](https://doped.readthedocs.io/en/latest/) examples and docs, you may want to further analyse the behaviour and impact on material properties of your defects using advanced defect analysis codes such as [`easyunfold`](https://smtg-bham.github.io/easyunfold/) (to analyse the electronic structure of defects in your material), [`py-sc-fermi`](https://py-sc-fermi.readthedocs.io/en/latest/) (to analyse defect concentrations, doping and Fermi level tuning), or [`nonrad`](https://nonrad.readthedocs.io/en/latest/)/[`CarrierCapture.jl`](https://wmd-group.github.io/CarrierCapture.jl/dev/) (to analyse non-radiative electron-hole recombination at defects)."
    ]
   },
   {

docs/Tips.rst

@@ -84,10 +84,33 @@ to:
   specified element (see next section).
 
 - Specify the total magnetic moment (``NUPDOWN`` in ``VASP``). We recommend to use a wider distortion mesh
-  (``delta = 0.2``) and run main ``NUPDOWN`` possibilities, e.g. if there are two extra/missing electrons run
-  ``NUPDOWN = 0`` (anti-parallel arrangement) and ``NUPDOWN = 2`` (parallel arrangement).
+  (``delta = 0.2``) and test the main ``NUPDOWN`` possibilities, e.g. if there are two extra/missing
+  electrons, trial ``NUPDOWN = 0`` (anti-parallel arrangement) and ``NUPDOWN = 2`` (parallel arrangement).
 
-:code:`neighbour_elements` Use Cases
+Magnetism
+---------
+
+If your host system is magnetic (e.g. (anti-)ferromagnetic), you should initialise the magnetic moments
+(i.e. set the ``MAGMOM`` values in the ``INCAR`` files using ``user_incar_settings`` in
+``Distortions.write_vasp_files()``) to match this.
+
+In these cases, the defect ground-state often involves a polaronic localisation which alters the local
+magnetic moment(s).
+Often the defect formation breaks the (magnetic) symmetry of the host, and so the choice of spin up/down
+for an *anti-ferromagnetic* (AFM) system is no longer arbitrary within a ``VASP`` calculation, as the
+initialisation favours spin-up as the majority spin of the system (by only allowing positive ``NUPDOWN``
+values). To account for this magnetic symmetry-breaking and thus differing localisation solutions for
+different choices of AFM orderings, it is recommended to test both equivalent\ :sup:`‡` AFM orderings for
+each potential polaronic defect state (i.e. when ``NUPDOWN`` is not zero).
+This can be done by 'flipping' the ``MAGMOM`` values (to flip the AFM ordering) by changing the sign of
+each ``MAGMOM`` value for the supercell. If doing this, it is recommended to use a wider distortion mesh
+(``delta = 0.2``) to reduce the number of calculations required, as the testing of both AFM orderings
+should allow sufficient coverage of the defect PES with this reduced sampling.
+
+:sup:`‡` = equivalent for the pristine host system, but not for the defect supercell with ``NUPDOWN`` ≠ 0.
+
+
+``neighbour_elements`` Use Cases
 -------------------------------------
 
 When generating atomic distortions with :code:`ShakeNBreak`, the :code:`neighbour_elements` optional parameter can be

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.2.2'
+release = '3.2.3'
 
 
 # -- General configuration ---------------------------------------------------
@@ -89,7 +89,7 @@
 # html_show_sphinx = True
 
 html_theme_options = {
-    "repository_url": "https://github.com/SMTG-UCL/ShakeNBreak",
+    "repository_url": "https://github.com/SMTG-Bham/ShakeNBreak",
     "repository_branch": "develop",
     "path_to_docs": "docs",
     "use_repository_button": True,
@@ -99,7 +99,7 @@
 # Adding “Edit Source” links on your Sphinx theme
 html_context = {
     "display_github": True, # Integrate GitHub
-    "github_user": "SMTG-UCL", # Username
+    "github_user": "SMTG-Bham", # Username
     "github_repo": "ShakeNBreak", # Repo name
     "github_version": "master", # Version
     "conf_py_path": "/docs/", # Path in the checkout to the docs root

docs/docs_requirements.txt

@@ -1,4 +1,5 @@
 sphinx
+recommonmark
 myst-nb
 sphinx-book-theme
 sphinx_click
@@ -7,7 +8,7 @@ numpy>=1.21  # needed for numpy.typing.NDArray
 pymatgen>2022.0.17 #==2022.10.22
 pymatgen-analysis-defects #>=2022.10.28
 ase
-matplotlib
+matplotlib>=3.6
 pandas>=1.1.0
 seaborn
 hiphive

docs/index.rst

@@ -3,8 +3,8 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-.. image:: https://github.com/SMTG-UCL/ShakeNBreak/actions/workflows/test.yml/badge.svg
- :target: https://github.com/SMTG-UCL/ShakeNBreak/actions
+.. image:: https://github.com/SMTG-Bham/ShakeNBreak/actions/workflows/test.yml/badge.svg
+ :target: https://github.com/SMTG-Bham/ShakeNBreak/actions
 
 .. image:: https://readthedocs.org/projects/shakenbreak/badge/?version=latest&style=flat
  :target: https://shakenbreak.readthedocs.io/en/latest/
@@ -106,7 +106,7 @@ For development work, ``ShakeNBreak`` can also be installed from a copy of the s
 
    .. code:: bash
 
-      git clone https://github.com/SMTG-UCL/ShakeNBreak
+      git clone https://github.com/SMTG-Bham/ShakeNBreak
 
 2. Navigate to root directory:
 
@@ -191,7 +191,7 @@ Contributing
 Bugs reports, feature requests and questions
 ----------------------------------------------
 
-Please use the `Issue Tracker <https://github.com/SMTG-UCL/ShakeNBreak/issues>`_
+Please use the `Issue Tracker <https://github.com/SMTG-Bham/ShakeNBreak/issues>`_
 to report bugs or request new features.
 
 Contributions to extend this package are very welcome! Please use the
@@ -213,9 +213,10 @@ Studies using ``ShakeNBreak``
 
 We'll add papers that use `ShakeNBreak` to this list as they come out!
 
+- X\. Wang et al. `Physical Review B <https://journals.aps.org/prb/abstract/10.1103/PhysRevB.108.134102>`_ 2023
+- Y\. Kumagai, S. R. Kavanagh et al. `PRX Energy <http://dx.doi.org/10.1103/PRXEnergy.2.043002>`__ 2023
 - J\. Willis, K. B. Spooner, D. O. Scanlon. `ChemRxiv <https://chemrxiv.org/engage/chemrxiv/article-details/64c29140ce23211b20a787bb>`__ 2023
 - A\. T. J. Nicolson et al. `Journal of Materials Chemistry A <https://doi.org/10.1039/D3TA02429F>`__ 2023
-- X\. Wang et al. `arXiv`_ 2023
 - J\. Cen et al. `Journal of Materials Chemistry A`_ 2023
 - J\. Willis & R. Claes et al. `ChemRxiv <https://doi.org/10.26434/chemrxiv-2023-lttnf>`__ 2023
 - I\. Mosquera-Lois & S. R. Kavanagh, A. Walsh, D. O. Scanlon `npj Computational Materials`_ 2023
@@ -234,7 +235,6 @@ We'll add papers that use `ShakeNBreak` to this list as they come out!
 .. Kat YTOS
 .. Squires (and mention benchmark test against AIRSS? See Slack message)
 
-.. _arXiv: https://arxiv.org/abs/2302.04901
 .. _Journal of Materials Chemistry A: https://doi.org/10.1039/D3TA00532A
 .. _npj Computational Materials: https://www.nature.com/articles/s41524-023-00973-1
 .. _Nature Communications: https://www.nature.com/articles/s41467-022-32669-3
@@ -257,7 +257,7 @@ You may also find this Preview paper useful, which discusses the general problem
 
 - Mosquera-Lois, I.; Kavanagh, S. R. `In Search of Hidden Defects`_. *Matter* 4 (8), 2602-2605, **2021**
 
-``BibTeX`` entries for these papers are provided in the repository `CITATIONS.md <https://github.com/SMTG-UCL/ShakeNBreak/blob/main/CITATIONS.md>`_ file.
+``BibTeX`` entries for these papers are provided in the repository `CITATIONS.md <https://github.com/SMTG-Bham/ShakeNBreak/blob/main/CITATIONS.md>`_ file.
 
 .. _ShakeNBreak\: Navigating the defect configurational landscape: https://doi.org/10.21105/joss.04817
 .. _Journal of Open Source Software: https://doi.org/10.21105/joss.04817
@@ -298,4 +298,4 @@ Requirements
    Code_Compatibility
    Contributing
    changelog_link
-   ShakeNBreak on GitHub <https://github.com/SMTG-UCL/ShakeNBreak>
+   ShakeNBreak on GitHub <https://github.com/SMTG-Bham/ShakeNBreak>

setup.py

@@ -130,7 +130,7 @@ def package_files(directory):
 
 setup(
     name="shakenbreak",
-    version="3.2.2",
+    version="3.2.3",
     description="Package to generate and analyse distorted defect structures, in order to "
     "identify ground-state and metastable defect configurations.",
     long_description=long_description,
@@ -163,7 +163,7 @@ def package_files(directory):
         "numpy",  # >=1.21.2" needed for numpy.typing.NDArray?
         "pymatgen>=2022.10.22",
         "pymatgen-analysis-defects>=2022.10.28",
-        "matplotlib",
+        "matplotlib>=3.6",
         "ase",
         "pandas>=1.1.0",
         "seaborn",
@@ -228,7 +228,7 @@ def package_files(directory):
         "Homepage": "https://shakenbreak.readthedocs.io/en/latest/index.html",
         "Documentation": "https://shakenbreak.readthedocs.io/en/latest/index.html",
         "Package": "https://pypi.org/project/shakenbreak/",
-        "Repository": "https://github.com/SMTG-UCL/shakenbreak",
+        "Repository": "https://github.com/SMTG-Bham/shakenbreak",
     },
 )