Merge branch 'main' into js_runs

.github/workflows/testing.yml

@@ -54,9 +54,12 @@ jobs:
           pip install -e .[strict]
           pip install -e .[tests]
 
-      - name: Test
+      - name: Test Modules
         run: pytest --cov=pymatgen --cov-report=xml
 
+      - name: Test Notebooks
+        run: pytest --nbmake ./docs/source/content
+
       - uses: codecov/codecov-action@v1
         if: matrix.python-version == 3.10
         with:

.pre-commit-config.yaml

@@ -1,56 +1,15 @@
+exclude: ^(docs|tests)
+
 repos:
-- repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v4.4.0
-  hooks:
-  - id: check-yaml
-  - id: fix-encoding-pragma
-    args:
-    - --remove
-  - id: end-of-file-fixer
-  - id: trailing-whitespace
-- repo: https://github.com/PyCQA/autoflake
-  rev: v2.2.1
-  hooks:
-  - id: autoflake
-- repo: https://github.com/psf/black
-  rev: 23.9.1
-  hooks:
-  - id: black
-- repo: https://github.com/asottile/blacken-docs
-  rev: 1.16.0
-  hooks:
-  - id: blacken-docs
-    additional_dependencies: [black]
-    exclude: README.md
-- repo: https://github.com/pycqa/isort
-  rev: 5.12.0
-  hooks:
-  - id: isort
-- repo: https://github.com/pycqa/flake8
-  rev: 6.1.0
-  hooks:
-  - id: flake8
-    entry: pflake8
-    files: ^src/
-    additional_dependencies:
-    - pyproject-flake8==6.1.0
-    - flake8-bugbear==22.12.6
-    - flake8-typing-imports==1.14.0
-    - flake8-docstrings==1.6.0
-    - flake8-rst-docstrings==0.3.0
-    - flake8-rst==0.8.0
-- repo: https://github.com/pycqa/pydocstyle
-  rev: 6.3.0
-  hooks:
-    - id: pydocstyle
-      additional_dependencies: ["tomli==2.0.1"]
-- repo: https://github.com/pre-commit/pygrep-hooks
-  rev: v1.10.0
-  hooks:
-  - id: python-use-type-annotations
-  - id: rst-backticks
-  - id: rst-directive-colons
-  - id: rst-inline-touching-normal
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  # Ruff version.
+  rev: v0.1.8
+  hooks:
+    # Run the linter.
+    - id: ruff
+      args: [ --fix ]
+    # Run the formatter.
+    - id: ruff-format
 - repo: https://github.com/pre-commit/mirrors-mypy
   rev: v1.5.1
   hooks:

README.rst

@@ -70,8 +70,42 @@ Previous versions of the defects code
 This package replaces the older ``pymatgen.analysis.defects`` modules.
 The previous module was used by ``pyCDT`` code which will continue to work with version ``2022.7.8`` of ``pymatgen``.
 
-Contributor
------------
+Contributing
+------------
+
+The source code can be downloaded from the GitHub repository at
+
+.. code-block:: bash
+
+    $ git clone https://github.com/materialsproject/pymatgen-analysis-defects.git
+
+All code contributions are welcome. Please submit a pull request on GitHub.
+To make maintenance easier, please use a workflow similar to the automated CI
+`workflow <https://github.com/materialsproject/pymatgen-analysis-defects/blob/main/.github/workflows/testing.yml>`_.
+
+Specifically, please make sure to run the following commands for linting:
+
+.. code-block:: bash
+
+    $ pip install -e .[strict]
+    $ pip install -e .[dev]
+    $ pre-commit install
+    $ pre-commit run --all-files
+
+And run these commands for testing:
+
+.. code-block:: bash
+
+    $ pip install -e .[strict]
+    $ pip install -e .[tests]
+    $ pytest --cov=pymatgen
+    $ pytest --nbmake ./docs/source/content
+
+For more details about what is actually installed with each of the ``pip install .[arg]`` commands, please inspect the
+``pyproject.toml`` file.
+
+Contributors
+------------
 
 * Lead developer: Dr. Jimmy-Xuan Shen
 * This code contains contributions from the original defects analysis module of ``pymatgen`` from Dr. Danny Broberg and Dr. Shyam Dwaraknath.

code-of-conduct.md

@@ -0,0 +1,47 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at [email protected]. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident to the extent possible by law and institutional policy.
+
+This Code of Conduct is adapted from the [Contributor Covenant][covenant],
+version 1.3.0, available at <https://contributor-covenant.org/version/1/3/0/code-of-conduct.html>
+
+[covenant]: https://contributor-covenant.org

docs/source/content/defining-defects.ipynb

@@ -159,11 +159,18 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The `defect_structure` for each complex is shown blow.\n",
+    "The `defect_structure` for each complex is shown below.\n",
     "\n",
     "<img src=\"https://raw.githubusercontent.com/materialsproject/pymatgen-analysis-defects/main/docs/source/_static/img/defect_complex_equiv.png\" width=\"800\"/>\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"
+    "By inspection, `def_comp0` and `def_comp2` appear symmetrically equivalent to each other at first and distinct from `def_comp1`.\n",
+    "However, there are two distinct Mg_Ga+V_N complexes in the structure:\n",
+    "\n",
+    "- One where the two parts of the defect complex are nearest neighbors (`def_comp0`).\n",
+    "- One where the two defects are next-nearest neighbors (`def_comp2`).\n",
+    "\n",
+    "Since our defect complex definition accounts for an effective _Center of Mass_ site, we can properly account for periodic boundary conditions. the two defect complexes will be considered not equal.\n",
+    "For complexes, we recommend checking the structure with the center of mass (`defect_structure_with_com`) to make sure you understand exactly what will be simulated in the supercell."
    ]
   },
   {
@@ -172,21 +179,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "assert def_comp0 == def_comp2\n",
+    "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",
-    "<div class=\"alert alert-block alert-info\"><b>Note:</b> 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",
-    "</div>\n"
-   ]
-  },
   {
    "attachments": {},
    "cell_type": "markdown",
@@ -245,12 +241,7 @@
    "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"
-   }
+   "version": "3.9.16"
   }
  },
  "nbformat": 4,

docs/source/content/formation-energy.ipynb

@@ -8,11 +8,11 @@
     "# Formation Energy Diagrams\n",
     "\n",
     "The formation energy diagram is perhaps the most important tool in analyzing the defect properties.\n",
-    "It informs both the likelihood of a defect to form and transition level where the charge state of the defect changes.\n",
+    "It informs both the likelihood of a defect forming and the transition level where the charge state of the defect changes.\n",
     "\n",
     "The formation energy of a defect is determined by the chemical potential of everything that goes into forming the defect.\n",
     "While all of the different chemical potentials are interconnected, it is conceptually easier to separate them into two groups: the chemical potential of the elements and the chemical potential of the electron.\n",
-    "The chemical potential of the electron, often called the *Fermi level*, accounts for how all of the external conditions, including the presence of other defects, affect the thermodynamics of adding or removing an electron from the defect.\n",
+    "The chemical potential of the electron often called the *Fermi level*, accounts for how all of the external conditions, including the presence of other defects, affect the thermodynamics of adding or removing an electron from the defect.\n",
     "Since the electrons in the system can be manipulated after the defect is formed, the *Fermi level* is often considered a free variable and is shown as the x-axis in the formation energy diagram.\n",
     "The chemical potentials of the different atoms added or removed to form the defect are less dynamic and assumed to be fixed after the defect is formed.\n",
     "\n",
@@ -104,21 +104,21 @@
    "source": [
     "## Getting the Elemental Chemical Potentials\n",
     "\n",
-    "All of the chemical potentials are, in principle, free variables that indicates the conditions of the surrounding environment while the defect is formed.\n",
+    "All of the chemical potentials are, in principle, free variables that indicate the conditions of the surrounding environment while the defect is formed.\n",
     "These free variables are bound by the enthalpies of formation of the various compounds that share the same elements as the defect and bulk material.\n",
     "These competing compounds essentially establish the boundaries of the allowed chemical potentials, while the VBM and CBM of the bulk material determine the allowed range of the Fermi level.\n",
     "As such, first-principles calculations can be used to determine the limits of the various chemical potentials. \n",
     "As an example, the elemental chemical potentials for the Mg$_{\\rm Ga}$ defect in GaN are shown below:\n",
     "\n",
     "$$\n",
     "\\begin{aligned}\n",
-    "\\mu_{\\rm Ga} + \\mu_{\\rm N} &= \\Delta H_{\\rm GaN} \\\\\n",
-    "5\\mu_{\\rm Mg} + 2\\mu_{\\rm Ga} + \\mu_{\\rm N} &\\leq \\Delta H_{\\rm Mg_5Ga_2} \\\\\n",
-    "3\\mu_{\\rm Mg} + 2\\mu_{\\rm N} &\\leq \\Delta H_{\\rm Mg_3N_2} \\\\\n",
+    "\\Delta\\mu_{\\rm Ga} + \\Delta\\mu_{\\rm N} &= \\Delta H_{\\rm GaN} \\\\\n",
+    "5\\Delta\\mu_{\\rm Mg} + 2\\Delta\\mu_{\\rm Ga} + \\Delta\\mu_{\\rm N} &\\leq \\Delta H_{\\rm Mg_5Ga_2} \\\\\n",
+    "3\\Delta\\mu_{\\rm Mg} + 2\\Delta\\mu_{\\rm N} &\\leq \\Delta H_{\\rm Mg_3N_2} \\\\\n",
     "\\end{aligned}\n",
     "$$\n",
     "\n",
-    "Here since the defect must for in GaN the chemical potentials are pinned by the plane defined by the enthalpy of formation of GaN.\n",
+    "Here since the defect must form in GaN the chemical potentials are pinned by the plane defined by the enthalpy of formation of GaN.\n",
     "The limits imposed by the competing compounds are shown by the additional inequalities.\n",
     "The points of interest are usually vertex points in the constrained chemical potential space so we report the full set of vertex points in `FormationEnergyDiagram.chempot_limits`."
    ]
@@ -130,9 +130,9 @@
    "outputs": [],
    "source": [
     "for i, p in enumerate(fed.chempot_limits):\n",
-    "    print(f\"Chemical potential limits for point {i}\")\n",
+    "    print(f\"Limits for the chemical potential changes for point {i}\")\n",
     "    for k,v in p.items():\n",
-    "        print(f\"μ_{k} = {v:.2f} eV\")"
+    "        print(f\"Δμ_{k} = {v:.2f} eV\")"
    ]
   },
   {
@@ -164,7 +164,7 @@
    "outputs": [],
    "source": [
     "from pymatgen.analysis.defects.corrections.freysoldt import plot_plnr_avg\n",
-    "plot_data = fed.defect_entries[1].correction_metadata[\"freysoldt\"]\n",
+    "plot_data = fed.defect_entries[1].corrections_metadata[\"freysoldt\"][\"plot_data\"]\n",
     "plot_plnr_avg(plot_data[0], title=\"Lattice Direction 1\")\n",
     "plot_plnr_avg(plot_data[1], title=\"Lattice Direction 2\")\n",
     "plot_plnr_avg(plot_data[2], title=\"Lattice Direction 3\")\n"
@@ -182,12 +182,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.6"
-  },
-  "vscode": {
-   "interpreter": {
-    "hash": "68485e4e4f6ba0276341f7d764a6dd3a7d31473cb629faa542bbbd38a80276a6"
-   }
+   "version": "3.9.16"
   }
  },
  "nbformat": 4,

docs/source/content/freysoldt-correction.ipynb

@@ -146,28 +146,32 @@
     "        )\n",
     "        plot_plnr_avg(\n",
     "            freysoldt_results[q].metadata[\"plot_data\"][direction], ax=axs[direction, 0]\n",
-    "        )"
+    "        )\n",
+    "        axs[direction, 0].set_title(f\"q={q} direction={direction} (Python)\")\n",
+    "        axs[direction, 1].set_title(f\"q={q} direction={direction} (SXDefectAlign)\")\n",
+    "        axs[direction, 0].set_xlabel(\"\")\n",
+    "        axs[direction, 1].set_xlabel(\"\")"
    ]
   },
   {
    "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The results from `sxdefectalign` is show on the right column. \n",
-    "The peak in the LOCPOT difference correspond to the position of the defect. \n",
-    "And we find that in region furthest away from that peak, the plateau value computed by python matched the plateau value visually.\n",
-    "Note the in the case of the python-only plots the defect position is set to the origin and the different alignment terms are set to zero far from the origin.\n",
+    "The results from `sxdefectalign` are shown in the right column. \n",
+    "The peak in the LOCPOT difference corresponds to the position of the defect. \n",
+    "We find that in the region furthest away from that peak, the plateau value computed by Python matched the plateau value visually.\n",
+    "Note that in the case of the Python-only plots the defect position is set to the origin and the different alignment terms are set to zero far from the origin.\n",
     "\n",
-    "It is recommend to check the results of your Freysoldt correction by running something like\n",
+    "We recommend checking the results of your Freysoldt correction by running something like\n",
     "\n",
     "```python\n",
     "plot_plnr_avg(\n",
     "    result.metadata[\"plot_data\"][0],\n",
     ")\n",
     "```\n",
     "\n",
-    "Since this immediately lets you know that, the defect positions was identified correctly if the LOCPOT diff is peaked at the origin and the curves are relatively flat in the sampling region.\n",
+    "This immediately lets you know that, the defect positions were identified correctly if the LOCPOT diff is peaked at the origin and the curves are relatively flat in the sampling region.\n",
     "\n",
     "Note that in the example here, the simulation cell is far too small for standard defect calculations but the defect finder is still able to find the defect position automatically.  Expect it to behave better in larger simulation cells.\n"
    ]
@@ -187,7 +191,7 @@
    "metadata": {},
    "source": [
     "_Result from larger simulation cell_ The LOCPOT data is too large to be included in the repository.\n",
-    "For a 144 atom cell, the positions of the defect is visually obvious.\n",
+    "For a 144-atom cell, the positions of the defect is visually obvious.\n",
     "<img src=\"https://raw.githubusercontent.com/materialsproject/pymatgen-analysis-defects/main/docs/source/_static/img/freysoldt_compare_large_cell.png\" width=\"850\"/>"
    ]
   },
@@ -196,7 +200,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "After accounting for the electrostatic and potential alignment corrections we can see how the python correction compares with the results of `sxdefectalign`"
+    "After accounting for the electrostatic and potential alignment corrections we can see how the Python correction compares with the results of `sxdefectalign`"
    ]
   },
   {