Merge pull request #57 from SMTG-UCL/develop

Develop

.pre-commit-config.yaml

@@ -19,7 +19,7 @@ repos:
 
 # Sort/format imports
   - repo: https://github.com/PyCQA/isort
-    rev: 5.10.1
+    rev: 5.12.0
     hooks:
       - id: isort
         args: [--profile, black]

CHANGELOG.rst

@@ -1,6 +1,14 @@
 Change Log
 ==========
 
+v3.2.0
+----------
+- Following the major release of `doped` `v2.0`, now compatible with the new `pymatgen`
+  defects code (`pymatgen>2022.7.25`), this update:
+    - Allows input of `doped` `DefectsGenerator` object to `Distortions`
+    - Updates the tutorials to reflect the current recommended workflow of generating defects
+      with `doped` and then applying `ShakeNBreak`, no longer requiring separate virtual environments 🎉
+
 v3.1.0
 ----------
 - Update dependencies, as `hiphive=1.2` has been released, making `ShakeNBreak` compatible with

README.md

@@ -2,12 +2,12 @@
 [![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)
-[![Conda Version](https://img.shields.io/conda/vn/conda-forge/shakenbreak.svg)](https://anaconda.org/conda-forge/shakenbreak)
+[![Conda](https://img.shields.io/conda/pn/conda-forge/shakenbreak?label=conda)](https://anaconda.org/conda-forge/shakenbreak)
 [![Downloads](https://img.shields.io/pypi/dm/shakenbreak)](https://shakenbreak.readthedocs.io/en/latest/)
 [![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-UCL/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.
 
-![](docs/SnB_Supercell_Schematic_PES_2sec_Compressed.gif)
+![ShakeNBreak Summary](https://raw.githubusercontent.com/SMTG-UCL/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**
@@ -45,7 +45,9 @@ If using `VASP`, in order for `ShakeNBreak` to automatically generate the pseudo
 ```bash
   PMG_VASP_PSP_DIR: <Path to VASP pseudopotential top directory>
 ```
-   Within your `VASP` pseudopotential top directory, you should have a folder named `POT_GGA_PAW_PBE` which contains the `POTCAR.X(.gz)` files (in this case for PBE `POTCAR`s). Please refer to the [`doped README`](https://github.com/SMTG-UCL/doped/tree/master#installation) instructions if you have difficulty with this.
+   Within your `VASP` pseudopotential top directory, you should have a folder named `POT_GGA_PAW_PBE`
+   which contains the `POTCAR.X(.gz)` files (in this case for PBE `POTCAR`s). Please refer to the `doped Installation docs <https://doped.readthedocs.io/en/latest/Installation.html>`_ if you have
+   difficulty with this.
 
 The font Montserrat ([Open Font License](https://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=OFL)) will be installed with the package, and will be used by default for plotting.
 
@@ -74,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](docs/SnB_CLI.gif)
+![ShakeNBreak CLI](https://raw.githubusercontent.com/SMTG-UCL/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
@@ -98,9 +100,9 @@ pip install --upgrade pymatgen shakenbreak
 ```
 
 `ShakeNBreak` can take `pymatgen` `Defect` objects as input (to then generate the trial distorted structures),
-**_but also_** can take in `pymatgen` `Structure` objects, `doped` defect dictionaries or structure files
+**_but also_** can take in `pymatgen` `Structure` objects, `doped` defects or structure files
 (e.g. `POSCAR`s for `VASP`) as inputs. As such, it should be compatible with any defect code
-(such as [`doped`](https://github.com/SMTG-UCL/doped), [`pydefect`](https://github.com/kumagai-group/pydefect),
+(such as [`doped`](https://doped.readthedocs.io/en/latest/index.html), [`pydefect`](https://github.com/kumagai-group/pydefect),
 [`PyCDT`](https://github.com/mbkumar/pycdt), [`PyLada`](https://github.com/pylada/pylada-defects),
 [`DASP`](http://hzwtech.com/files/software/DASP/htmlEnglish/index.html), [`Spinney`](https://gitlab.com/Marrigoni/spinney/-/tree/master),
 [`DefAP`](https://github.com/DefAP/defap), [`PyDEF`](https://github.com/PyDEF2/PyDEF-2.0)...) that generates these files.

SnB_input_files/incar.yaml

@@ -1,24 +1,25 @@
 '# May want to change NCORE, KPAR, AEXX, ENCUT, NUPDOWN, ISPIN, POTIM': ''
 '# ShakeNBreak INCAR with coarse settings to maximise speed with sufficient accuracy for qualitative structure searching': ''
 '# KPAR': '# No KPAR, only one kpoint'
-ALGO: Normal
+ALGO: "Normal  # Change to All if ZHEGV, FEXCP/F or ZBRENT errors encountered (done automatically by snb-run)"
 EDIFFG: -0.01
 ENCUT: 300
-HFSCREEN: 0.2
-IBRION: '2 # While often slower than ''1'' (RMM-DIIS), this is more stable and reliable,
-    and vasp_gam relaxations are typically cheap enough to justify it'
+HFSCREEN: 0.208  # correct HSE screening parameter; see https://aip.scitation.org/doi/10.1063/1.2404663
+# Note this 👆 differs from the Materials Project MPHSERelaxSet default of 0.2! (Will cause systematic
+# energy shifts in HSE supercell calculations.)
+IBRION: '2  # Typically more stable / reliable than "1" (RMM-DIIS), but change if ionic convergence is poor (done automatically by snb-run)'
 ISIF: 2
 ISMEAR: 0
-ISPIN: '2 # Spin polarisation likely for defects'
-ISYM: '0 # Symmetry breaking extremely likely for defects'
+ISPIN: '2  # Spin polarisation likely for defects'
+ISYM: '0  # Symmetry breaking extremely likely for defects'
 LASPH: true
 LCHARG: false
 LHFCALC: true
-LORBIT: 14
+LORBIT: 11  # lm-decomposed orbital projections; useful for DOS analysis (e.g. sumo-dosplot)
 LREAL: Auto
 LWAVE: false
-NCORE: 12
-NEDOS: 2000
+NCORE: 16
+NEDOS: 2000  # dense energy mesh output in OUTCAR; useful for DOS analysis (e.g. sumo-dosplot)
 NELM: 40
 NSW: 300
 PREC: Accurate

docs/Analysis.rst

@@ -18,7 +18,7 @@ Alternatively, we can run from a different directory and specify the defect to p
 
 .. code:: bash
 
-    $ snb-parse --defect v_Cd_s0_0 --path defects_folder --code FHI-aims
+    $ snb-parse --defect v_Cd_0 --path defects_folder --code FHI-aims
 
 Where ``defects_folder`` is the path to the top level directory containing the defect folder, and is only required if
 different from the current directory.
@@ -32,7 +32,7 @@ in a given/current directory using the ``-a``/``--all`` flag:
 
 This generates a ``yaml`` file for each defect, mapping each distortion to the
 final energy of the relaxed structures (in eV). These files are saved to the
-corresponding defect directory (e.g. ``defects_folder/v_Cd_s0_0/v_Cd_s0_0.yaml``).
+corresponding defect directory (e.g. ``defects_folder/v_Cd_0/v_Cd_0.yaml``).
 
 .. code:: yaml
 
@@ -61,7 +61,7 @@ was used (if not :code:`VASP`) and which reference structure to use (default = `
 
 .. code:: bash
 
-    $ snb-analyse --defect v_Cd_s0_0 --code FHI-aims --path defects_folder --ref_struct -0.4 --verbose
+    $ snb-analyse --defect v_Cd_0 --code FHI-aims --path defects_folder --ref_struct -0.4 --verbose
 
 Again if we want to analyse the results for **all** defects present in a given/current directory, we can use the
 ``-a``/``--all`` flag:
@@ -90,7 +90,7 @@ the defect directory:
 
 which will generate a figure like the one below:
 
-.. image:: ./v_Cd_s0_0.svg
+.. image:: ./v_Cd_0.svg
     :width: 400px
 
 ..
@@ -103,7 +103,7 @@ structures, using the ``-cb``/``--colorbar`` flag:
 
     $ snb-plot -cb
 
-.. image:: ./v_Cd_s0_0_colorbar.svg
+.. image:: ./v_Cd_0_colorbar.svg
     :width: 450px
 
 ..
@@ -114,7 +114,7 @@ was used (if not :code:`VASP`) and other options (what ``metric`` to use for col
 
 .. code:: bash
 
-    $ snb-plot --defect v_Cd_s0_0 --code FHI-aims --path defects_folder --colorbar -0.4 --metric disp --units meV --verbose
+    $ snb-plot --defect v_Cd_0 --code FHI-aims --path defects_folder --colorbar -0.4 --metric disp --units meV --verbose
 
 Again if we want to plot the results for **all** defects present in a given/current directory, we can use the
 ``-a``/``--all`` flag:
@@ -143,15 +143,15 @@ For example, if we have the following directory structure
 .. code:: bash
 
     ./
-    |--- v_Cd_s0_0/ <-- Neutral Cd vacancy
+    |--- v_Cd_0/ <-- Neutral Cd vacancy
     |       |--- Unperturbed
     |       |
     |       |--- Bond_Distortion_-30.0% <-- Favourable distortion
     |       |
     |       |--- Bond_Distortion_30.0%
     |       | ...
     |
-    |--- v_Cd_s0_-1/ <-- Negatively charged Cd vacancy
+    |--- v_Cd_-1/ <-- Negatively charged Cd vacancy
             |--- Unperturbed
             | ...
             |--- Bond_Distortion_50% <-- Favourable distortion
@@ -171,7 +171,7 @@ for the code specified with the flag ``--code`` (default = :code:`VASP`).
 .. code:: bash
 
     ./
-    |--- v_Cd_s0_0/
+    |--- v_Cd_0/
     |       |--- Unperturbed
     |       |
     |       |--- Bond_Distortion_-30.0% <-- Favourable distortion
@@ -180,7 +180,7 @@ for the code specified with the flag ``--code`` (default = :code:`VASP`).
     |       | ...
     |       |--- Bond_Distortion_50.0%_from_-1 <-- Distortion from the -1 charge state
     |
-    |--- v_Cd_s0_-1/
+    |--- v_Cd_-1/
             |--- Unperturbed
             | ...
             |--- Bond_Distortion_50% <-- Favourable distortion
@@ -214,7 +214,7 @@ This command will generate a ``Groundstate`` directory within each defect folder
 .. code:: bash
 
     ./
-    |--- v_Cd_s0_0/
+    |--- v_Cd_0/
     |       |--- Unperturbed
     |       |
     |       |--- Bond_Distortion_-30.0%
@@ -224,7 +224,7 @@ This command will generate a ``Groundstate`` directory within each defect folder
     |       |--- Groundstate
     |               |--- POSCAR <-- Ground state structure
     |
-    |--- v_Cd_s0_-1/
+    |--- v_Cd_-1/
             |--- Unperturbed
             | ...
             |--- Bond_Distortion_50%
@@ -240,16 +240,17 @@ Further Defect Analysis
 -------------------------
 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://github.com/SMTG-UCL/doped>`_, manually (not
-recommended) or using the other defect codes listed on the
+and k-point sampling). This can be done using `doped <https://doped.readthedocs.io/en/latest/index.html>`_,
+manually (not recommended) or using the other defect codes listed on the
 `Code Compatibility <https://shakenbreak.readthedocs.io/en/latest/Code_Compatibility.html>`_ page.
 
-As shown in the `doped <https://github.com/SMTG-UCL/doped>`_ 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/>`_
+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
+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).
 
 .. NOTE::

docs/Code_Compatibility.rst

@@ -14,7 +14,7 @@ most recent version of :code:`pymatgen`. If you are receiving :code:`pymatgen`-r
 :code:`ShakeNBreak` can take :code:`pymatgen` :code:`DefectEntry` objects as input (to then generate the trial distorted
 structures), **but also** can take in :code:`pymatgen` :code:`Structure` objects, :code:`doped` defect dictionaries or
 structure files (e.g. :code:`POSCAR`\s for :code:`VASP`) as inputs. As such, it should be compatible with any defect code
-(such as `doped <https://github.com/SMTG-UCL/doped>`_, `pydefect <https://github.com/kumagai-group/pydefect>`_,
+(such as `doped <https://doped.readthedocs.io/en/latest/index.html>`_, `pydefect <https://github.com/kumagai-group/pydefect>`_,
 `PyCDT <https://github.com/mbkumar/pycdt>`_, `PyLada <https://github.com/pylada/pylada-defects>`_,
 `DASP <http://hzwtech.com/files/software/DASP/htmlEnglish/index.html>`_, `Spinney <https://gitlab.com/Marrigoni/spinney/-/tree/master>`_,
 `DefAP <https://github.com/DefAP/defap>`_, `PyDEF <https://github.com/PyDEF2/PyDEF-2.0>`_...) that generates these files.

docs/Installation.rst

@@ -23,8 +23,8 @@ configuration file ``$HOME/.pmgrc.yaml`` as follows:
 
 Within your ``VASP`` pseudopotential top directory, you should have a folder named ``POT_GGA_PAW_PBE``
 which contains the ``POTCAR.X(.gz)`` files (in this case for PBE ``POTCARs``). Please refer to the
-`doped README <https://github.com/SMTG-UCL/doped/tree/master#installation>`_ instructions if you have difficulty with
-this.
+`doped Installation docs <https://doped.readthedocs.io/en/latest/Installation.html>`_ if you have
+difficulty with this.
 
 .. NOTE::
    The font `Montserrat <https://fonts.google.com/specimen/Montserrat/about>`_