diff --git a/.github/workflows/python-publish.yml b/.github/workflows/python-publish.yml index 9da04f6c..52ff94ed 100644 --- a/.github/workflows/python-publish.yml +++ b/.github/workflows/python-publish.yml @@ -15,7 +15,7 @@ jobs: steps: - uses: actions/checkout@v3 - name: Set up Python - uses: actions/setup-python@v3 + uses: actions/setup-python@v4 with: python-version: '3.x' - name: Install dependencies @@ -41,7 +41,7 @@ jobs: - name: Install pandoc run: sudo apt-get install pandoc - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 with: python-version: '3.10' cache: pip @@ -52,7 +52,7 @@ jobs: pip install -e .[strict] pip install -e .[docs] - name: Build - run: sphinx-build docs/source docs_build + run: jupyter-book build --path-output docs docs/source - name: Deploy uses: peaceiris/actions-gh-pages@v3 diff --git a/.github/workflows/testing.yml b/.github/workflows/testing.yml index 5e67e101..1ce1bf9d 100644 --- a/.github/workflows/testing.yml +++ b/.github/workflows/testing.yml @@ -4,9 +4,8 @@ on: push: branches: - main - tags: - - 'v*' + - "v*" pull_request: branches: @@ -18,10 +17,9 @@ jobs: steps: - uses: actions/checkout@v3 - - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 with: - python-version: '3.10' + python-version: "3.10" cache: pip cache-dependency-path: pyproject.toml @@ -32,7 +30,6 @@ jobs: pip install -e .[dev] pre-commit install - - name: Lint run: | pre-commit run --all-files --show-diff-on-failure @@ -41,34 +38,34 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - python-version: [ '3.8', '3.9', '3.10' ] + python-version: ["3.8", "3.9", "3.10"] env: PMG_MAPI_KEY: ${{ secrets.PMG_MAPI_KEY }} steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v3 - - uses: actions/setup-python@v3 - with: - python-version: ${{ matrix.python-version }} - cache: pip - cache-dependency-path: pyproject.toml + - uses: actions/setup-python@v4 + with: + python-version: ${{ matrix.python-version }} + cache: pip + cache-dependency-path: pyproject.toml - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install -e .[strict] - pip install -e .[tests] + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -e .[strict] + pip install -e .[tests] - - name: Test - run: pytest --cov=pymatgen --cov-report=xml + - name: Test + run: pytest --cov=pymatgen --cov-report=xml - - uses: codecov/codecov-action@v1 - if: matrix.python-version == 3.10 - with: - token: ${{ secrets.CODECOV_TOKEN }} - file: ./coverage.xml + - uses: codecov/codecov-action@v1 + if: matrix.python-version == 3.10 + with: + token: ${{ secrets.CODECOV_TOKEN }} + file: ./coverage.xml docs: runs-on: ubuntu-latest @@ -82,9 +79,9 @@ jobs: - name: Install pandoc run: sudo apt-get install pandoc - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 with: - python-version: '3.10' + python-version: "3.10" cache: pip cache-dependency-path: pyproject.toml @@ -93,8 +90,4 @@ jobs: pip install -e .[strict] pip install -e .[docs] - name: Build - run: sphinx-build docs/source docs_build - - - name: Test Jupyter Notebooks - run: | - pytest --nbmake --nbmake-kernel=python3 tutorials + run: jupyter-book build --path-output docs docs/source diff --git a/.github/workflows/update-precommit.yml b/.github/workflows/update-precommit.yml index 1f32dd2f..265132a9 100644 --- a/.github/workflows/update-precommit.yml +++ b/.github/workflows/update-precommit.yml @@ -12,7 +12,7 @@ jobs: - uses: actions/checkout@v3 - name: Set up Python - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 with: python-version: ${{ 3.10 }} cache: pip diff --git a/.gitignore b/.gitignore index 3c09f6cd..b76953c0 100644 --- a/.gitignore +++ b/.gitignore @@ -139,3 +139,7 @@ examples/wip* .vscode/ pymatgen/analysis/defects/corrections/kumagai_old.py + +docs.old/_build/ + +docs.old/ diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d0c3cbf1..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 747ffb7b..00000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -if "%1" == "" goto help - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/source/_config.yml b/docs/source/_config.yml new file mode 100644 index 00000000..fed55a4b --- /dev/null +++ b/docs/source/_config.yml @@ -0,0 +1,43 @@ +# Book settings +# Learn more at https://jupyterbook.org/customize/config.html + +title: pymatgen-analysis-defects +author: Jimmy-Xuan Shen + +# Patterns to skip when building the book. Can be glob-style (e.g. "*skip.ipynb") +exclude_patterns : [_build, Thumbs.db, .DS_Store, "**.ipynb_checkpoints"] + +# Cache re-execution of notebooks on each build. +# See https://jupyterbook.org/content/execute.html +execute: + execute_notebooks: cache + +# Define the name of the latex output file for PDF builds +latex: + latex_documents: + targetname: book.tex + +# Add a bibtex file so that we can create citations +bibtex_bibfiles: + - references.bib + +# Information about where the book exists on the web +repository: + url: https://github.com/materialsproject/pymatgen-analysis-defects # Online location of your book + path_to_book: docs # Optional path to your book, relative to the repository root + branch: main # Which branch of the repository should be used when creating links (optional) + +# Add GitHub buttons to your book +# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository +html: + use_issues_button: true + use_repository_button: true + home_page_in_navbar: false + use_edit_page_button: true + baseurl: https://materialsproject.github.io/pymatgen-analysis-defects + + +sphinx: + config: + extra_extensions: + - IPython.sphinxext.ipython_console_highlighting diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css deleted file mode 100644 index 419cd980..00000000 --- a/docs/source/_static/custom.css +++ /dev/null @@ -1,70 +0,0 @@ -html { - font-size: 100% !important; - font-weight: 400; -} - -@media (min-width: 97em) { - html { - font-size: 100%; - } -} - -/* Hide link icons in external links*/ -.rst-content.style-external-links a.reference.external:after { - display: none; -} -.sidebar-tree .reference.external:after { - display: none; -} - -h1 { - font-size: 2rem; -} -h2 { - font-size: 1.5rem; -} -h3 { - font-size: 1.15rem; -} - -@font-face { - font-family: 'Lato'; - src: url('fonts/lato-normal.woff2') format('woff2'), url('fonts/lato-normal.woff') format('woff'); - font-weight: 400; - font-style: normal; - font-display: block; -} - -@font-face { - font-family: 'Lato'; - src: url('fonts/lato-bold.woff2') format('woff2'), url('fonts/lato-bold.woff') format('woff'); - font-weight: 700; - font-style: normal; - font-display: block; - } - -@font-face { - font-family: 'Lato'; - src: url('fonts/lato-bold-italic.woff2') format('woff2'), url('fonts/lato-bold-italic.woff') format('woff'); - font-weight: 700; - font-style: italic; - font-display: block; -} - -@font-face { - font-family: 'Lato'; - src: url('fonts/lato-normal-italic.woff2') format('woff2'), url('fonts/lato-normal-italic.woff') format('woff'); - font-weight: 400; - font-style: italic; - font-display: block; - } - -/* Hide nbsphinx prompt numbers */ -div.nbinput div.prompt { - display: none; -} - -/* Hide nbsphinx prompt numbers */ -div.nboutput div.prompt { - display: none; -} diff --git a/docs/source/_static/fonts/lato-bold-italic.woff b/docs/source/_static/fonts/lato-bold-italic.woff deleted file mode 100644 index 88ad05b9..00000000 Binary files a/docs/source/_static/fonts/lato-bold-italic.woff and /dev/null differ diff --git a/docs/source/_static/fonts/lato-bold-italic.woff2 b/docs/source/_static/fonts/lato-bold-italic.woff2 deleted file mode 100644 index c4e3d804..00000000 Binary files a/docs/source/_static/fonts/lato-bold-italic.woff2 and /dev/null differ diff --git a/docs/source/_static/fonts/lato-bold.woff b/docs/source/_static/fonts/lato-bold.woff deleted file mode 100644 index c6dff51f..00000000 Binary files a/docs/source/_static/fonts/lato-bold.woff and /dev/null differ diff --git a/docs/source/_static/fonts/lato-bold.woff2 b/docs/source/_static/fonts/lato-bold.woff2 deleted file mode 100644 index bb195043..00000000 Binary files a/docs/source/_static/fonts/lato-bold.woff2 and /dev/null differ diff --git a/docs/source/_static/fonts/lato-normal-italic.woff b/docs/source/_static/fonts/lato-normal-italic.woff deleted file mode 100644 index 76114bc0..00000000 Binary files a/docs/source/_static/fonts/lato-normal-italic.woff and /dev/null differ diff --git a/docs/source/_static/fonts/lato-normal-italic.woff2 b/docs/source/_static/fonts/lato-normal-italic.woff2 deleted file mode 100644 index 3404f37e..00000000 Binary files a/docs/source/_static/fonts/lato-normal-italic.woff2 and /dev/null differ diff --git a/docs/source/_static/fonts/lato-normal.woff b/docs/source/_static/fonts/lato-normal.woff deleted file mode 100644 index ae1307ff..00000000 Binary files a/docs/source/_static/fonts/lato-normal.woff and /dev/null differ diff --git a/docs/source/_static/fonts/lato-normal.woff2 b/docs/source/_static/fonts/lato-normal.woff2 deleted file mode 100644 index 3bf98433..00000000 Binary files a/docs/source/_static/fonts/lato-normal.woff2 and /dev/null differ diff --git a/docs/source/_static/orcid.svg b/docs/source/_static/img/orcid.svg similarity index 100% rename from docs/source/_static/orcid.svg rename to docs/source/_static/img/orcid.svg diff --git a/docs/source/_toc.yml b/docs/source/_toc.yml new file mode 100644 index 00000000..1170bcd1 --- /dev/null +++ b/docs/source/_toc.yml @@ -0,0 +1,8 @@ +# Table of contents +# Learn more at https://jupyterbook.org/customize/toc.html + +format: jb-book +root: intro +chapters: +- file: content/quickstart +- file: content/defining-defects diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index c3a706b5..00000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,131 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -import os -import sys - -sys.path.insert(0, os.path.abspath("../..")) - - -# -- Project information ----------------------------------------------------- - -project = "pymatgen-analysis-defects" -copyright = "2022, Materials Project Team" -author = "Jimmy-Xuan Shen" - - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.napoleon", - "sphinx.ext.viewcode", - "sphinx_autodoc_typehints", - "m2r2", - "nbsphinx", - "nbsphinx_link", -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ["Thumbs.db", ".DS_Store", "test*.py"] - -# use type hints -# autodoc_typehints = "description" -autoclass_content = "both" -autodoc_member_order = "bysource" - -# better napoleon support -# napoleon_use_param = True -# napoleon_use_rtype = True -# napoleon_use_ivar = True - -# The suffix(es) of source filenames. -source_suffix = [".rst", ".md"] - -# Ensure env.metadata[env.docname]['nbsphinx-link-target'] points relative to repo root: -nbsphinx_link_target_root = os.path.join(__file__, "..", "..") - -nbsphinx_prolog = r""" -{% if env.metadata[env.docname]['nbsphinx-link-target'] %} -{% set docpath = env.metadata[env.docname]['nbsphinx-link-target'] %} -{% else %} -{% set docpath = env.doc2path(env.docname, base='docs/source/') %} -{% endif %} -.. only:: html - .. role:: raw-html(raw) - :format: html - .. nbinfo:: - This page is available as a Jupyter notebook: `{{ docpath }}`__. - __ https://github.com/materialsproject/jobflow/tree/main/{{ docpath }}""" - - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "furo" - -# hide sphinx footer -html_show_sphinx = False -html_show_sourcelink = False - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -fonts = [ - "Lato", - "-apple-system", - "BlinkMacSystemFont", - "Segoe UI", - "Helvetica", - "Arial", - "sans-serif", - "Apple Color Emoji", - "Segoe UI Emoji", -] -html_static_path = ["_static"] -html_css_files = ["custom.css"] -html_theme_options = { - "light_css_variables": { - "admonition-font-size": "92%", - "admonition-title-font-size": "92%", - "font-stack": ",".join(fonts), - "font-size--small": "92%", - "font-size--small--2": "87.5%", - "font-size--small--3": "87.5%", - "font-size--small--4": "87.5%", - }, - "dark_css_variables": { - "admonition-font-size": "92%", - "admonition-title-font-size": "92%", - "font-stack": ",".join(fonts), - "font-size--small": "92%", - "font-size--small--2": "87.5%", - "font-size--small--3": "87.5%", - "font-size--small--4": "87.5%", - }, -} -html_title = "pymatgen-analysis-defects" diff --git a/docs/source/content/defining-defects.ipynb b/docs/source/content/defining-defects.ipynb new file mode 100644 index 00000000..6d64f014 --- /dev/null +++ b/docs/source/content/defining-defects.ipynb @@ -0,0 +1,258 @@ +{ + "cells": [ + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Defining Defects\n", + "\n", + "A persistent challenge with organizing computational defect data is the ambiguity with which a defect simulation is defined.\n", + "The standard practice is to simulate the isolated defects by using a larger simulation to create an isolated defect and then using charge-state corrections to approximate the properties of a defect in the dilute limit.\n", + "This means that the same defect can be simulated with different simulation cells.\n", + "Ideally, if you want to build a computational defects database that lasts many years, you cannot rely on user-supplied provenance to aggregate the data.\n", + "You must have the external method for tracking whether two calculations are for the same defect.\n", + "\n", + "
Note: This is only important for large database building. For an example of this please see the Materials Project battery database which only relies on structure matching to arrive at the list of insertion electrodes.\n", + "
\n", + "\n", + "A core concept in this package is that a defect is defined independently of the simulation cell.\n", + "All of the information about which defect we are simulating is captured by the `Defect` object.\n", + "A point defect is defined by the Wigner-Seitz unit cell representation of the bulk material stored as a `structure` attribute and a `site` attribute that indicates where the defect is in the unit cell.\n", + "Different kinds of point defects all subclass the `Defect` objects which gives easy access to functions such as generating a cubic simulation supercell.\n", + "As along as the database or any algorithm keeps track of this `Defect` object, you can just use simple structure matching to find out if two simulations represent the same defect.\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Basic Example Using GaN" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from pathlib import Path\n", + "\n", + "TEST_FILES = Path(\"../../../tests/test_files\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from pymatgen.analysis.defects.core import DefectComplex, Substitution, Vacancy\n", + "from pymatgen.core import PeriodicSite, Species, Structure\n", + "\n", + "bulk = Structure.from_file(TEST_FILES / \"GaN.vasp\")\n", + "if (\n", + " bulk.lattice == bulk.get_primitive_structure().lattice\n", + "): # check that you have the primitive structure\n", + " print(\"The bulk unit cell is the unique primitive WS cell\")" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Since the two Ga sites are equivalent the Mg substitution we derive from both should be equivalent.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "ga_site0 = bulk.sites[0]\n", + "ga_site1 = bulk.sites[1]\n", + "n_site0 = bulk.sites[2]\n", + "n_site1 = bulk.sites[3]\n", + "\n", + "mg_site0 = PeriodicSite(Species(\"Mg\"), ga_site0.frac_coords, bulk.lattice)\n", + "mg_site1 = PeriodicSite(Species(\"Mg\"), ga_site1.frac_coords, bulk.lattice)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "mg_ga_defect0 = Substitution(structure=bulk, site=mg_site0)\n", + "mg_ga_defect1 = Substitution(structure=bulk, site=mg_site1)\n", + "if mg_ga_defect0 == mg_ga_defect1:\n", + " print(\"The two Mg_Ga defects are equivalent.\")" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Equivalence here is determined using the standard StructureMatcher settings.\n", + "\n", + "```python\n", + " def __eq__(self, __o: object) -> bool:\n", + " \"\"\"Equality operator.\"\"\"\n", + " if not isinstance(__o, Defect):\n", + " raise TypeError(\"Can only compare Defects to Defects\")\n", + " sm = StructureMatcher(comparator=ElementComparator())\n", + " return sm.fit(self.defect_structure, __o.defect_structure)\n", + "```\n", + "\n", + "If you are in the situation where your lattice parameters have changed overtime (i.e. by inclusion of different functionals) you might consider using more custom maching between the defect.\n", + "\n", + "Since the defect equivalence is only determined by the `defect_structure` field, all defects can be compared using `__eq__`.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "vac_defect0 = Vacancy(structure=bulk, site=mg_site0)\n", + "vac_defect1 = Vacancy(structure=bulk, site=n_site0)\n", + "vac_defect2 = Vacancy(structure=bulk, site=n_site1)\n", + "if vac_defect0 != vac_defect1:\n", + " print(\n", + " f\"The two vacancies {vac_defect0.name} and {vac_defect1.name} are not equivalent.\"\n", + " )\n", + "\n", + "if vac_defect2 == vac_defect1:\n", + " print(\n", + " f\"The two vacancies {vac_defect2.name} and {vac_defect1.name} are equivalent.\"\n", + " )" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Defining defect complexes\n", + "\n", + "Defining defect complexes can be done by providing a list of defect objects generated using the same pristine structure.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def_comp0 = DefectComplex(defects=[mg_ga_defect0, vac_defect1])\n", + "def_comp1 = DefectComplex(defects=[mg_ga_defect1, vac_defect1])\n", + "def_comp2 = DefectComplex(defects=[mg_ga_defect1, vac_defect2])" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The `defect_structure` for each complex is shown blow.\n", + "\n", + "\n", + "\n", + "By inspection it is clear that `def_comp0` and `def_comp2` are symmetrically equivalent to each other and distinct from `def_comp1`, and our basic implementation of defect equivalence is able to verify this:\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "assert def_comp0 == def_comp2\n", + "assert def_comp0 != def_comp1" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "However some defect complexes might become nonequivalent based on the periodic image you consider for the combination of sites.\n", + "\n", + "
Note: To deal with these edge cases, we might have to add a dummy \"DefectComplex\" species at the \"center\" of the defect complex which will fix the selection of periodic for the different sites. This is easy to implement but should be done when there is a good test case.\n", + "
\n" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Obtaining the simulation supercell\n", + "\n", + "The simplest way to generate a supercell for simulating the defect is to just call the `get_supercell_structure` method for the defect.\n", + "\n", + "Note that, under the hood, the `get_supercell_structure` method first attempts a \"quick and dirty\" inversion of a large cube in the bases of the lattice parameters.\n", + "If a valid supercell is not discovered this way, ASE's `find_optimal_cell_shape` will be called to exhaustively search for the best supercell structure.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "sc_struct = mg_ga_defect0.get_supercell_structure()\n", + "sc_struct.num_sites" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The supercell generated with default settings looks like this:\n", + "\n", + "\n", + "\n", + "You can also reduce the `max_atoms` field to obtain a smaller simulation cell.\n", + "Note that in this case, the conditions for the for cubic cell cannot be satisfied by the lattice vector inversion approach and the more expensive algorithm from ASE will be used. Uncomment the following cell to see this in action." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "#sc_struct_smaller = mg_ga_defect0.get_supercell_structure(max_atoms=100)\n", + "#sc_struct_smaller.num_sites" + ] + } + ], + "metadata": { + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.6 | packaged by conda-forge | (main, Aug 22 2022, 20:38:29) [Clang 13.0.1 ]" + }, + "vscode": { + "interpreter": { + "hash": "68485e4e4f6ba0276341f7d764a6dd3a7d31473cb629faa542bbbd38a80276a6" + } + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/source/content/nonradiative.ipynb b/docs/source/content/nonradiative.ipynb new file mode 100644 index 00000000..0a667b48 --- /dev/null +++ b/docs/source/content/nonradiative.ipynb @@ -0,0 +1,223 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "6930b94a-4443-45b0-94a5-452f6280fd5a", + "metadata": {}, + "source": [ + "# Simulation of non-radiative capture\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "239c7281-3a24-49cb-a161-64124c59dbc4", + "metadata": {}, + "outputs": [], + "source": [ + "from pathlib import Path\n", + "\n", + "import numpy as np\n", + "from matplotlib import pyplot as plt\n", + "from pymatgen.analysis.defects.ccd import HarmonicDefect, SRHCapture" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2d5264bc-c907-4d74-bb70-bc79c9050e7a", + "metadata": {}, + "outputs": [], + "source": [ + "TEST_FILES = Path(\"../../../tests/test_files/v_Ga/\")" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "id": "e410b507-e465-438b-95e3-64dce28f6f00", + "metadata": {}, + "source": [ + "## Read a single Harmonic Defect\n", + "\n", + "We can parse an sorted list of directories with `HarmonicDefect.from_directories`.\n", + "This will look into each directory for a `vasprun.xml` file from which the structures and energies will be extracted.\n", + "\n", + "The different constructors for `HarmonicDefect` all accept a list of sources where the energies and structures come from.\n", + "The relaxed structure will be taken from the `relaxed_index` entry from this list and the electronic structure from this entry will be parsed to help identify the defect band in the band structure.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "ceaa50d4-57d2-4438-80e7-7cb4491985c1", + "metadata": {}, + "outputs": [], + "source": [ + "dirs01 = [TEST_FILES / \"ccd_0_-1\" / str(i) for i in [0, 1, 2]]\n", + "hd0 = HarmonicDefect.from_directories(\n", + " directories=dirs01,\n", + " store_bandstructure=True,\n", + ")\n", + "print(f\"The relaxed structure is in dirs01[{hd0.relaxed_index}]\")\n", + "print(hd0)\n", + "print(\n", + " f\"The spin channel ({hd0.spin}) is also automaticalliy determined by the \"\n", + " \"IPR, by taking the spin channel with the lowest average IPR.\"\n", + ")" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "id": "8e0c86ec-8fa4-4399-9900-c161b8149fbe", + "metadata": {}, + "source": [ + "Note that `HarmonicDefect.defect_band` consists of multiple states presented as `(iband, ikpt, ispin)` index tuples, if `defect_band` was not provided to the constructor, the `relaxed_index` entry in the directory list will be checked for a Procar file, which will be parsed to give the \"best guess\" of the defect state in the band structure.\n", + "The band index is automatically determined by the inverse participation ratio.\n", + "Note that the defect state reports the \"most-localized\" bands at each k-point so it is possible for the band index of the defect band to change for different kpoint indices `ikpt`.\n", + "\n", + "
Note: The automated defect state identification is still in testing you can provide the `defect_band` manually to over-ride the automatic behavior if you notice any issues.\n", + "Please report any issues you encounter to the github issue tracker.\n", + "
\n" + ] + }, + { + "cell_type": "markdown", + "id": "43e620e9-93be-4883-b3a0-ecf5218a6355", + "metadata": {}, + "source": [ + "### Potential energy surface\n", + "\n", + "The potential energy surface of the defect in a particular charge state is given by:\n", + "\n", + "$$\\frac{1}{2} \\omega^2 Q^2$$\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c4226814-ccfc-41f9-8eeb-5ad6a2d58eeb", + "metadata": {}, + "outputs": [], + "source": [ + "plt.plot(\n", + " hd0.distortions,\n", + " (np.array(hd0.energies) - hd0.energies[hd0.relaxed_index]) * 1000,\n", + " \"o\",\n", + " ms=10,\n", + ")\n", + "xx = np.linspace(-0.2, 0.2, 20)\n", + "yy = 0.5 * hd0.omega**2 * xx**2\n", + "plt.plot(xx, yy * 1000)\n", + "plt.xlabel(\"Q [amu$^{1/2}$Å]\")\n", + "plt.ylabel(\"Energy [meV]\");" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a8b9111d-40dd-4be5-ac24-2140c4ce7570", + "metadata": { + "tags": [] + }, + "outputs": [], + "source": [ + "bs = hd0.relaxed_bandstructure\n", + "eigs = bs.bands[hd0.spin][:, 1]\n", + "eigs_ref_efermi = eigs\n", + "plt.hlines([eigs_ref_efermi], 0, 1)\n", + "plt.hlines(eigs_ref_efermi[hd0.defect_band_index], 0, 1, colors=\"red\")\n", + "plt.ylim(bs.efermi - 0.1, bs.efermi + 2.5)\n", + "plt.xticks([])\n", + "plt.ylabel(f\"Energy Level Spin:{hd0.spin}\");" + ] + }, + { + "cell_type": "markdown", + "id": "3c47a859-9ed4-4e2f-a72a-22a8dabe79b7", + "metadata": {}, + "source": [ + "From the eigenvalue file:\n", + "\n", + "```\n", + "# nband eig (+1) eig (-1) occ (+1) occ (-1)\n", + " 138 4.281429 4.983887 0.999759 0.000000\n", + " 139 4.341242 5.752503 0.963967 0.000000 <- Defect\n", + " 140 6.269717 6.356752 0.000000 0.000000\n", + " 141 8.441992 8.536628 0.000000 0.000000\n", + "```" + ] + }, + { + "cell_type": "markdown", + "id": "4f23a97c-d658-43f5-9e73-e916a2af6c53", + "metadata": {}, + "source": [ + "## Combined two HarmonicDefects and a series of WSWQ\n", + "\n", + "Read the information required for SRH recombination from directories.\n", + "\n", + "
Note: I'm seriously considering changing this to be functional since this feels really over-engineered at this point.\n", + "
\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0734c1ce-0ad6-4247-855a-67f41bc84aa3", + "metadata": {}, + "outputs": [], + "source": [ + "srh = SRHCapture.from_directories(\n", + " initial_dirs=[TEST_FILES / \"ccd_0_-1\" / str(i) for i in [0, 1, 2]],\n", + " final_dirs=[TEST_FILES / \"ccd_-1_0\" / str(i) for i in [0, 1, 2]],\n", + " wswq_dir=TEST_FILES / \"ccd_0_-1\" / \"wswqs\",\n", + " store_bandstructure=True,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2bd1ea7c-2af0-4e85-bd6a-bddd2f0b06e4", + "metadata": {}, + "outputs": [], + "source": [ + "T = np.linspace(100, 1000, 20)\n", + "cc = srh.get_coeff(T, 0.3, kpt_index=1)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "de9f39cd-0061-4e97-96a4-bb36f599e78d", + "metadata": {}, + "outputs": [], + "source": [ + "plt.plot(T, cc)" + ] + } + ], + "metadata": { + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.6" + }, + "vscode": { + "interpreter": { + "hash": "68485e4e4f6ba0276341f7d764a6dd3a7d31473cb629faa542bbbd38a80276a6" + } + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/source/content/quickstart.ipynb b/docs/source/content/quickstart.ipynb new file mode 100644 index 00000000..a7933acc --- /dev/null +++ b/docs/source/content/quickstart.ipynb @@ -0,0 +1,229 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "tags": [] + }, + "source": [ + "# Quick Start\n", + "\n", + "## Installation\n", + "\n", + "The package can be installed from PyPI using `pip install pymatgen-analysis-defects`. \n", + "\n", + "Once installed, the different modules can be imported via the `pymatgen.analysis.defects` namespace.\n", + "\n", + "```python\n", + "from pymatgen.analysis.defects import core, ccd, finder\n", + "```\n", + "\n", + "To ensure that the namespace is installed properly run" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from pymatgen.analysis.defects.core import __file__" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "and look at the `__file__` variable to make sure that it is accessing the code from `pymatgen-analysis-defect` and not `pymatgen`." + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Definition of a defect\n", + "\n", + "Our code defines defects using a combination of bulk structure and sites.\n", + "Since the bulk primitive structure is, in principle, unique up to arbitrary translations, equivalence of defects can be now easily checked using `StructureMatcher`.\n", + "\n", + "Below we show how you can create a basic substitutional defect from a `pymatgen.core.Structure` object by replacing one of the Ga atoms in GaN with Mg.\n", + "\n", + "Note that we create a MgGa defect by creating a PeriodicSite Object `mg_ga` with the data of the first Ga site but \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from pathlib import Path\n", + "\n", + "from pymatgen.analysis.defects.core import Substitution\n", + "from pymatgen.core import PeriodicSite, Species, Structure\n", + "\n", + "TEST_FILES = Path(\"../../../tests/test_files\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "gan_struct = Structure.from_file(TEST_FILES / \"GaN.vasp\")\n", + "# make a substitution site\n", + "ga_site = gan_struct[0]\n", + "mg_site = PeriodicSite(\n", + " species=Species(\"Mg\"), coords=ga_site.frac_coords, lattice=gan_struct.lattice\n", + ")\n", + "# instantiate the defect object\n", + "mg_ga = Substitution(structure=gan_struct, site=mg_site)\n", + "print(mg_ga)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "mg_ga.defect_structure" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Instantiating `FormationEnergyDiagram`\n", + "\n", + "The object responsible for analyzing the formation energy is described by the following fields.\n", + "\n", + "```python\n", + "FormationEnergyDiagram(\n", + " bulk_entry: 'ComputedStructureEntry',\n", + " defect_entries: 'List[DefectEntry]',\n", + " pd_entries: 'list[ComputedEntry]',\n", + " vbm: 'float',\n", + " band_gap: 'Optional[float]' = None,\n", + " inc_inf_values: 'bool' = True,\n", + ")\n", + "```\n", + "\n", + "Using a convenience constructor `with_directories` you can just feed in dictionary of {`str`: `Path`} \n", + "pointing to the directories where the supercell calculations are stored.\n", + "The keys, other than `bulk` will be the charge states of the calculations.\n", + "As long as the `vasprun.xml` and `LOCPOT` files are in the directories the `FormationEnergyDiagram` object can be constructed." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import warnings\n", + "\n", + "from monty.serialization import loadfn\n", + "from pymatgen.analysis.defects.thermo import FormationEnergyDiagram\n", + "from pymatgen.io.vasp import Vasprun\n", + "\n", + "warnings.filterwarnings(\"ignore\")\n", + "\n", + "sc_dir = TEST_FILES / \"Mg_Ga\"\n", + "# ents = MPRester().get_entries_in_chemsys(\"Mg-Ga-N\") # Query from MPRester\n", + "ents = loadfn(TEST_FILES / \"Ga_Mg_N.json\") # Load from local\n", + "fed = FormationEnergyDiagram.with_directories(\n", + " directory_map={\n", + " \"bulk\": sc_dir / \"bulk_sc\",\n", + " 0: sc_dir / \"q=0\",\n", + " -1: sc_dir / \"q=-1\",\n", + " 1: sc_dir / \"q=1\",\n", + " },\n", + " defect=mg_ga,\n", + " pd_entries=ents,\n", + " dielectric=10,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Getting the formation energy diagram\n", + "\n", + "The chemical potential limits can be access using:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "fed.chempot_limits" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "If you have `crystal_toolkit` and the its jupyter lab extensions installed you can view the chemical potential diagram by importing `crystal_toolkit` and running a cell with the the `chempot_diagram` on the last line.\n", + "\n", + "```python\n", + "import crystal_toolkit\n", + "fed.chempot_diagram\n", + "```\n", + "\n", + "Note that it is different from chemical potential plot hosted on the material project because the elemental phases are set to zero energy.\n", + "\n", + "\n", + "\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Now we can plot the formation energy diagram by calculating the _Fermi level_ and _formation energy_ at the different charge state transitions. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import numpy as np\n", + "from matplotlib import pyplot as plt\n", + "\n", + "ts = np.array(fed.get_transitions(fed.chempot_limits[1], x_max=5))\n", + "plt.plot(ts[:, 0], ts[:, 1], \"-o\")\n", + "plt.xlabel(\"Fermi Level (eV)\")\n", + "plt.ylabel(\"Formation Energy(eV)\")" + ] + } + ], + "metadata": { + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.6 | packaged by conda-forge | (main, Aug 22 2022, 20:38:29) [Clang 13.0.1 ]" + }, + "vscode": { + "interpreter": { + "hash": "68485e4e4f6ba0276341f7d764a6dd3a7d31473cb629faa542bbbd38a80276a6" + } + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/source/genindex.rst b/docs/source/genindex.rst deleted file mode 100644 index 76cc03fa..00000000 --- a/docs/source/genindex.rst +++ /dev/null @@ -1,2 +0,0 @@ -Index -***** diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 076fa268..00000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. toctree:: - :caption: Getting Started - :hidden: - - Introduction - -.. toctree:: - :caption: Reference - :maxdepth: -1 - :hidden: - - API - Tutorials - GitHub Repo - genindex - -Introduction -============ - -.. mdinclude:: ../../README.rst - :start-line: 7 diff --git a/docs/source/intro.md b/docs/source/intro.md new file mode 100644 index 00000000..777e7ea9 --- /dev/null +++ b/docs/source/intro.md @@ -0,0 +1,27 @@ +# `pymatgen-analysis-defects` + +This package is an extension to `pymatgen` for performing defect analysis. +The package is meant to be installed as a namespace package extension to the main `pymatgen` library. +The code will be accessible as `pymatgen.analysis.defects` after installation. +The new module has been redesigned to work closely with `atomate2`. + +## Installation + +The new `pymatgen-analysis-defects` module can be installed using `pip`: +``` +pip install pymatgen-analysis-defects +``` + +## What happened to the old module? + +The old `pymatgen.analysis.defects` module has been deprecated and removed from the main `pymatgen` library. +If you need to use the old module, you can install `pymatgen` version `<=2022.7.8` which is the last version that contains the old module. +This was a difficult decision, but the having two separate modules with the same name would be confusing and difficult to maintain. +The old module was not being actively developed and was not compatible with the new `atomate2` framework. + + +## Table of Contents + +```{tableofcontents} + +``` diff --git a/docs/source/logo.png b/docs/source/logo.png new file mode 100644 index 00000000..06d56f40 Binary files /dev/null and b/docs/source/logo.png differ diff --git a/docs/source/reference/ccd.rst b/docs/source/reference/ccd.rst deleted file mode 100644 index dd78e15d..00000000 --- a/docs/source/reference/ccd.rst +++ /dev/null @@ -1,6 +0,0 @@ -pymatgen.analysis.defects.ccd -============================= - -.. automodule:: pymatgen.analysis.defects.ccd - :members: - :show-inheritance: diff --git a/docs/source/reference/core.rst b/docs/source/reference/core.rst deleted file mode 100644 index ff7d1ff9..00000000 --- a/docs/source/reference/core.rst +++ /dev/null @@ -1,6 +0,0 @@ -pymatgen.analysis.defects.core -============================== - -.. automodule:: pymatgen.analysis.defects.core - :members: - :show-inheritance: diff --git a/docs/source/reference/corrections.rst b/docs/source/reference/corrections.rst deleted file mode 100644 index d7dea97d..00000000 --- a/docs/source/reference/corrections.rst +++ /dev/null @@ -1,6 +0,0 @@ -pymatgen.analysis.defects.corrections -===================================== - -.. automodule:: pymatgen.analysis.defects.corrections - :members: - :show-inheritance: diff --git a/docs/source/reference/finder.rst b/docs/source/reference/finder.rst deleted file mode 100644 index 7ecfd709..00000000 --- a/docs/source/reference/finder.rst +++ /dev/null @@ -1,6 +0,0 @@ -pymatgen.analysis.defects.finder -================================ - -.. automodule:: pymatgen.analysis.defects.finder - :members: - :show-inheritance: diff --git a/docs/source/reference/generators.rst b/docs/source/reference/generators.rst deleted file mode 100644 index e86d2fa7..00000000 --- a/docs/source/reference/generators.rst +++ /dev/null @@ -1,6 +0,0 @@ -pymatgen.analysis.defects.generators -==================================== - -.. automodule:: pymatgen.analysis.defects.generators - :members: - :show-inheritance: diff --git a/docs/source/reference/root.rst b/docs/source/reference/root.rst deleted file mode 100644 index 7872c009..00000000 --- a/docs/source/reference/root.rst +++ /dev/null @@ -1,14 +0,0 @@ -pymatgen.analysis.defects -========================= - -.. toctree:: - :caption: Documentation for each module - :maxdepth: -1 - - core - ccd - corrections - finder - generators - thermo - utils diff --git a/docs/source/reference/thermo.rst b/docs/source/reference/thermo.rst deleted file mode 100644 index e2bac1d0..00000000 --- a/docs/source/reference/thermo.rst +++ /dev/null @@ -1,6 +0,0 @@ -pymatgen.analysis.defects.thermo -================================ - -.. automodule:: pymatgen.analysis.defects.thermo - :members: - :show-inheritance: diff --git a/docs/source/reference/utils.rst b/docs/source/reference/utils.rst deleted file mode 100644 index 44496f55..00000000 --- a/docs/source/reference/utils.rst +++ /dev/null @@ -1,6 +0,0 @@ -pymatgen.analysis.defects.utils -=============================== - -.. automodule:: pymatgen.analysis.defects.utils - :members: - :show-inheritance: diff --git a/docs/source/references.bib b/docs/source/references.bib new file mode 100644 index 00000000..e69de29b diff --git a/docs/source/requirements.txt b/docs/source/requirements.txt new file mode 100644 index 00000000..7e821e45 --- /dev/null +++ b/docs/source/requirements.txt @@ -0,0 +1,3 @@ +jupyter-book +matplotlib +numpy diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst deleted file mode 100644 index a3a63f1a..00000000 --- a/docs/source/tutorials.rst +++ /dev/null @@ -1,10 +0,0 @@ -Tutorials -========= - -.. Note:: - These tutorials are a work in progress. - -.. toctree:: - - tutorials/1-quickstart - tutorials/3-nonradiative-capture diff --git a/docs/source/tutorials/1-quickstart.nblink b/docs/source/tutorials/1-quickstart.nblink deleted file mode 100644 index 606a6629..00000000 --- a/docs/source/tutorials/1-quickstart.nblink +++ /dev/null @@ -1,3 +0,0 @@ -{ - "path": "../../../tutorials/1-quickstart.ipynb" -} diff --git a/docs/source/tutorials/2-defining-defects.nblink b/docs/source/tutorials/2-defining-defects.nblink deleted file mode 100644 index 6de6aa98..00000000 --- a/docs/source/tutorials/2-defining-defects.nblink +++ /dev/null @@ -1,3 +0,0 @@ -{ - "path": "../../../tutorials/2-defining-defects.ipynb" -} diff --git a/pyproject.toml b/pyproject.toml index 6a674332..ff082248 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -28,14 +28,7 @@ requires-python = '>=3.8' finder = ["dscribe>=1.2.1"] dev = ["pre-commit>=2.12.1"] docs = [ - "sphinx>=5.0.2", - "furo>=2022.6.21", - "m2r2>=0.3.3", - "ipython>=8.7.0", - "nbsphinx>=0.8.10", - "nbsphinx-link>=1.3.0", - "sphinx-autodoc-typehints>=1.19.5", - "nbmake>=1.3.3", + "jupyter-book>=0.13.1", ] strict = [ @@ -44,7 +37,7 @@ strict = [ "scikit-image==0.19.3", ] -tests = ["pytest==7.1.2", "pytest-cov==3.0.0", "nbmake==1.3.3"] +tests = ["pytest==7.1.2", "pytest-cov==3.0.0"] [tool.setuptools.dynamic] readme = { file = ["README.rst"] }