-
Notifications
You must be signed in to change notification settings - Fork 31
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #29 from SMTG-UCL/pymatgen_refactor
`doped` 2.0, btchs
- Loading branch information
Showing
1,384 changed files
with
38,185 additions
and
293,876 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| exclude: ^(docs|examples|.github|doped/pycdt/test_files|tests/data) | ||
| repos: | ||
| # Lint and format, isort, docstrings... | ||
| - repo: https://github.com/charliermarsh/ruff-pre-commit | ||
| rev: v0.0.270 | ||
| 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 | ||
| hooks: | ||
| - id: check-yaml | ||
| - id: end-of-file-fixer | ||
| exclude: '\.dat$' | ||
| - id: trailing-whitespace | ||
|
|
||
| # Code formatting | ||
| - repo: https://github.com/psf/black | ||
| rev: 23.3.0 | ||
| hooks: | ||
| - id: black # max line length 107 specified in pyproject.toml | ||
|
|
||
| - repo: https://github.com/pre-commit/mirrors-mypy | ||
| rev: v1.3.0 | ||
| hooks: | ||
| - id: mypy | ||
|
|
||
| # Check typos: | ||
| - repo: https://github.com/codespell-project/codespell | ||
| rev: v2.2.4 | ||
| hooks: | ||
| - id: codespell | ||
| stages: [commit,commit-msg] | ||
| exclude_types: [html] | ||
| additional_dependencies: [tomli] # needed to read pyproject.toml for python < 3.11 | ||
|
|
||
| # format docstring length: | ||
| - repo: https://github.com/PyCQA/docformatter | ||
| rev: v1.7.1 | ||
| hooks: | ||
| - id: docformatter | ||
| additional_dependencies: [tomli] | ||
| args: [--in-place,--config,./pyproject.toml] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| # .readthedocs.yaml | ||
| # Read the Docs configuration file | ||
| # See https://docs.readthedocs.io/en/stable/config-file/v2.html for detail | ||
|
|
||
| # Required | ||
| version: 2 | ||
|
|
||
| build: | ||
| os: ubuntu-20.04 | ||
| tools: | ||
| python: "3.8" | ||
|
|
||
| # Build from the docs/ directory with Sphinx | ||
| sphinx: | ||
| configuration: docs/conf.py | ||
|
|
||
| # Explicitly set the version of Python and its requirements | ||
| python: | ||
| install: | ||
| - requirements: docs/docs_requirements.txt |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,109 +1,81 @@ | ||
| [](https://github.com/SMTG-UCL/doped/actions) | ||
| [](https://doped.readthedocs.io/en/latest/) | ||
| [](https://pypi.org/project/doped) | ||
| [](https://anaconda.org/conda-forge/doped) | ||
| [](https://shakenbreak.readthedocs.io/en/latest/) | ||
| [](https://pypi.org/project/doped) | ||
|
|
||
| # **D**efect **O**riented **P**ython **E**nvironment **D**istribution (`doped`) | ||
| This is a (mid-development) Python package for managing solid-state defect calculations, | ||
| geared toward VASP. Much of it is a modified version of the excellent [PyCDT](https://bitbucket.org/mbkumar/pycdt). | ||
| See [this link](https://www.sciencedirect.com/science/article/pii/S0010465518300079) for the original PyCDT paper. | ||
| <img align="right" width="275" src="docs/doped_v2_logo.png">`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. | ||
|
|
||
| Defect formation energy plots are templated from [AIDE](https://github.com/SMTG-UCL/aide) and follow the aesthetics | ||
| philosopy of [sumo](https://smtg-ucl.github.io/sumo/), both developed by the dynamic duo Adam Jackson and Alex Ganose. | ||
|
|
||
| Example Jupyter notebooks (the `.ipynb` files) are provided in [examples](examples) to show the code functionality and usage. | ||
| 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: | ||
|
|
||
| <img src="https://raw.githubusercontent.com/SMTG-UCL/doped/master/files/doped_chempot_plotting.png" width="420"> <img src="https://raw.githubusercontent.com/SMTG-UCL/doped/master/files/doped_TLD_plot.png" width="390"> | ||
| <img align="left" src="docs/doped_chempot_plotting.png" width="365"> <img src="docs/doped_TLD_plot.png" width="385" align="right"> | ||
| <br><br><br><br><br><br><br><br><br><br><br> | ||
|
|
||
| ## Requirements | ||
| `doped` requires `pymatgen<2022.8.23` and its dependencies. | ||
|
|
||
| ## Installation | ||
| - Because of breaking changes made to the `pymatgen` defects code in version `2022.8.23`, `doped` requires | ||
| `pymatgen<2022.8.23`, which is installed automatically when installing `doped`. | ||
| However, as discussed briefly below and in the example notebooks, the | ||
| [`ShakeNBreak`](https://shakenbreak.readthedocs.io/en/latest/) approach is highly recommended when calculating | ||
| defects in solids, and this package has been updated to be compatible with the latest version of `pymatgen`. | ||
| As such, it is recommended to install `doped` in a virtual python environment as follows: | ||
|
|
||
| 1. Create virtual environment and install: | ||
| ```bash | ||
| conda create -n doped python=3.10 # create conda environment named doped | ||
| conda activate doped # activate doped conda environment | ||
| pip install doped # install doped and dependencies, can also | ||
| pip install --force --no-cache-dir numpy==1.23 # install numpy after doped to avoid binary incompatibility | ||
| pip install doped # install doped and dependencies | ||
| ``` | ||
| And then use this environment whenever using `doped`. | ||
|
|
||
| Alternatively if desired, `doped` can also be installed from `conda` with: | ||
|
|
||
| ```bash | ||
| conda install -c conda-forge doped | ||
| ``` | ||
|
|
||
| If you want to use the [example files](examples), | ||
| you should clone the repository and install with `pip install -e .` from the `doped` directory, but still make sure to `pip install numpy --upgrade`. | ||
|
|
||
| 2. (If not set) Set the VASP pseudopotential directory and your Materials Project API key in `$HOME/.pmgrc.yaml` | ||
| (`pymatgen` config file) as follows: | ||
| ```bash | ||
| PMG_VASP_PSP_DIR: <Path to VASP pseudopotential top directory> | ||
| PMG_MAPI_KEY: <Your MP API key obtained from https://legacy.materialsproject.org/open> | ||
| ``` | ||
| Within your `VASP pseudopotential top directory`, you should have a folder named | ||
| `POT_GGA_PAW_PBE`/`potpaw_PBE.54`/`POT_GGA_PAW_PBE_54` which contains `POTCAR.X(.gz)` files, generated using `pmg config`. | ||
|
|
||
| If you have not previously setup your `POTCAR` directory in this way with `pymatgen`, then follow these steps: | ||
| ```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 | ||
| 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`) | ||
| rm -r temp_potcars # remove the temporary POTCAR directory | ||
| ``` | ||
| If this has been successful, you should be able to run `pmg potcar -s Na_pv`, and `grep PBE POTCAR` should show | ||
| `PAW_PBE Na_pv {date}` (you can ignore any `pymatgen` warnings about recognising the `POTCAR`). | ||
|
|
||
| If it does not work check that the `PMG_DEFAULT_FUNCTIONAL` is set to whatever your functionals are (e.g. `PBE` or `PBE_54`) | ||
| 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. | ||
|
|
||
| This is necessary to generate `POTCAR` input files, and auto-determine `INCAR` settings such as `NELECT` for charged | ||
| defects. | ||
|
|
||
| The Materials Project API key is required for determining the necessary competing phases to calculate in order to | ||
| determine the chemical potential limits (required for defect formation energies). This should correspond to the legacy | ||
| MP API, with your unique key available at: https://legacy.materialsproject.org/open. | ||
|
|
||
|
|
||
| ## `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://arxiv.org/abs/2207.09862), 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-UCL/doped/blob/master/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: | ||
|  | ||
|  | ||
|
|
||
| `SnB` CLI Usage: | ||
|  | ||
|
|
||
|
|
||
| ### Developer Installation | ||
|  | ||
|
|
||
| 1. Download the `doped` source code using the command: | ||
| ```bash | ||
| git clone https://github.com/SMTG-UCL/doped | ||
| ``` | ||
| 2. Navigate to root directory: | ||
| ```bash | ||
| cd doped | ||
| ``` | ||
| 3. Install the code, using the command: | ||
| ```bash | ||
| pip install -e . | ||
| ``` | ||
|
|
||
| ## Acknowledgments | ||
| `doped` has benefitted from feedback from many users, in particular members of the Walsh and Scanlon 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. | ||
| `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` | ||
|
|
||
| We'll add papers that use `doped` to this list as they come out! | ||
|
|
||
| - A. T. J. Nicolson et al. [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 [ACS Energy Letters](https://doi.org/10.1021/acsenergylett.2c02306) 2023 | ||
| - P. A. Hyde et al. [Inorganic Chemistry](https://doi.org/10.1021/acs.inorgchem.3c01510) 2023 | ||
| - J. Willis, K. B. Spooner, D. O. Scanlon. [ChemRxiv](https://chemrxiv.org/engage/chemrxiv/article-details/64c29140ce23211b20a787bb) 2023 | ||
| - X. Wang et al. arXiv 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://www.nature.com/articles/s41524-023-00973-1) 2023 | ||
| - Y. T. Huang & S. R. Kavanagh et al. [Nature Communications](https://www.nature.com/articles/s41467-022-32669-3) 2022 | ||
| - S. R. Kavanagh, D. O. Scanlon, A. Walsh, C. Freysoldt [Faraday Discussions](https://doi.org/10.1039/D2FD00043A) 2022 | ||
| - S. R. Kavanagh, D. O. Scanlon, A. Walsh [ACS Energy Letters](https://pubs.acs.org/doi/full/10.1021/acsenergylett.1c00380) 2021 | ||
| - C. J. Krajewska et al. [Chemical Science](https://doi.org/10.1039/D1SC03775G) 2021 |
Oops, something went wrong.