# pymatgen-analysis-defects
[](https://github.com/materialsproject/pymatgen-analysis-defects/actions/workflows/testing.yml)
[](https://codecov.io/gh/materialsproject/pymatgen-analysis-defects)
[](https://zenodo.org/badge/latestdoi/452872799)
[](https://badge.fury.io/py/pymatgen-analysis-defects)
📄 [Full
Documentation](https://materialsproject.github.io/pymatgen-analysis-defects/)
[Paper](https://joss.theoj.org/papers/10.21105/joss.05941)
This package is an extension to `pymatgen` for performing defect
analysis. The package is designed to work with VASP inputs and output
files and is meant to be used as a namespace package extension to the
main `pymatgen` library. The new module has been redesigned to work
closely with `atomate2`.
While the `atomate2` automation framework is not required for this code
to be useful, users are strongly encouraged to to adopt the `atomate2`
framework as it contains codified \"best practices\" for running defect
calculations as well as orchestrating the running of calculations and
storing the results.
The package serves as an object-oriented interface to defect physics and
is capable of generating a list of non-equivalent defect objects
directly from the Materials Project API.
``` python
from pymatgen.analysis.defects.generators import ChargeInterstitialGenerator, generate_all_native_defects
from pymatgen.ext.matproj import MPRester
with MPRester() as mpr:
chgcar = mpr.get_charge_density_from_material_id("mp-804")
for defect in generate_all_native_defects(chgcar):
print(defect)
```
# Non-exhaustive list of features:
## Reproducible definition of defects
Defects are defined based on the physical concept they represent,
independent of the calculation details such as simulation cell size. As
an example, a Vacancy defect is defined by the primitive cell of the
pristine material plus a single site that represents the vacancy site in
the unit cell.
## Formation energy calculations
The formation energy diagram is a powerful tool for understanding the
thermodynamics of defects. This package provides a simple interface for
calculating the formation energy diagram from first-principles results.
This package handles the energy accounting of the chemical species for
the chemical potential calculations, which determines the y-offset of
the formation energy. This package also performs finite-size corrections
for the formation energy which is required when studying charged defects
in periodic simulation cells.
## Defect Position
Identification of the defect positions in a simulation cell after atomic
relaxation is not trivial since the many atoms can collectively shift in
response to the creation of the defect. Yet the exact location of the
defect is required for the calculation of finite-size corrections as
well as other physical properties. We devised a method based on
calculating a SOAP-based distortion field that can be used to identify
the defect position in a simulation cell. Note, this method only
requires the reference pristine supercell and does not need prior
knowledge of how the defect was created.
## Defect Complexes
Multiple defects can be composed into defect complexes. The complex is
can be treated as a normal defect object for subsequent analysis.
## Defect Interactions
Simulation of defect-photon and defect-phonon interactions under the
independent particle approximation.
# 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`.
# Contributing
The source code can be downloaded from the GitHub repository at
``` 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:
``` bash
$ pip install -e .[strict]
$ pip install -e .[dev]
$ pre-commit install
$ pre-commit run --all-files
```
And run these commands for testing:
``` 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "pymatgen-analysis-defects",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "high-throughput, automated, dft, defects",
"author": null,
"author_email": "Jimmy-Xuan Shen <jmmshn@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f7/2a/dd66ba2424b4007ce3e149c8dbd1d0ae12ad7b3bd8f70a32e4e3092056de/pymatgen_analysis_defects-2024.4.23.tar.gz",
"platform": null,
"description": "# pymatgen-analysis-defects\n\n[](https://github.com/materialsproject/pymatgen-analysis-defects/actions/workflows/testing.yml)\n[](https://codecov.io/gh/materialsproject/pymatgen-analysis-defects)\n[](https://zenodo.org/badge/latestdoi/452872799)\n[](https://badge.fury.io/py/pymatgen-analysis-defects)\n\n\ud83d\udcc4 [Full\nDocumentation](https://materialsproject.github.io/pymatgen-analysis-defects/)\n[Paper](https://joss.theoj.org/papers/10.21105/joss.05941)\n\nThis package is an extension to `pymatgen` for performing defect\nanalysis. The package is designed to work with VASP inputs and output\nfiles and is meant to be used as a namespace package extension to the\nmain `pymatgen` library. The new module has been redesigned to work\nclosely with `atomate2`.\n\nWhile the `atomate2` automation framework is not required for this code\nto be useful, users are strongly encouraged to to adopt the `atomate2`\nframework as it contains codified \\\"best practices\\\" for running defect\ncalculations as well as orchestrating the running of calculations and\nstoring the results.\n\nThe package serves as an object-oriented interface to defect physics and\nis capable of generating a list of non-equivalent defect objects\ndirectly from the Materials Project API.\n\n``` python\nfrom pymatgen.analysis.defects.generators import ChargeInterstitialGenerator, generate_all_native_defects\nfrom pymatgen.ext.matproj import MPRester\nwith MPRester() as mpr:\nchgcar = mpr.get_charge_density_from_material_id(\"mp-804\")\nfor defect in generate_all_native_defects(chgcar):\n print(defect)\n```\n\n# Non-exhaustive list of features:\n\n## Reproducible definition of defects\n\nDefects are defined based on the physical concept they represent,\nindependent of the calculation details such as simulation cell size. As\nan example, a Vacancy defect is defined by the primitive cell of the\npristine material plus a single site that represents the vacancy site in\nthe unit cell.\n\n## Formation energy calculations\n\nThe formation energy diagram is a powerful tool for understanding the\nthermodynamics of defects. This package provides a simple interface for\ncalculating the formation energy diagram from first-principles results.\nThis package handles the energy accounting of the chemical species for\nthe chemical potential calculations, which determines the y-offset of\nthe formation energy. This package also performs finite-size corrections\nfor the formation energy which is required when studying charged defects\nin periodic simulation cells.\n\n## Defect Position\n\nIdentification of the defect positions in a simulation cell after atomic\nrelaxation is not trivial since the many atoms can collectively shift in\nresponse to the creation of the defect. Yet the exact location of the\ndefect is required for the calculation of finite-size corrections as\nwell as other physical properties. We devised a method based on\ncalculating a SOAP-based distortion field that can be used to identify\nthe defect position in a simulation cell. Note, this method only\nrequires the reference pristine supercell and does not need prior\nknowledge of how the defect was created.\n\n## Defect Complexes\n\nMultiple defects can be composed into defect complexes. The complex is\ncan be treated as a normal defect object for subsequent analysis.\n\n## Defect Interactions\n\nSimulation of defect-photon and defect-phonon interactions under the\nindependent particle approximation.\n\n# Previous versions of the defects code\n\nThis package replaces the older `pymatgen.analysis.defects` modules. The\nprevious module was used by `pyCDT` code which will continue to work\nwith version `2022.7.8` of `pymatgen`.\n\n# Contributing\n\nThe source code can be downloaded from the GitHub repository at\n\n``` bash\n$ git clone https://github.com/materialsproject/pymatgen-analysis-defects.git\n```\n\nAll code contributions are welcome. Please submit a pull request on\nGitHub. To make maintenance easier, please use a workflow similar to the\nautomated CI\n[workflow](https://github.com/materialsproject/pymatgen-analysis-defects/blob/main/.github/workflows/testing.yml).\n\nSpecifically, please make sure to run the following commands for\nlinting:\n\n``` bash\n$ pip install -e .[strict]\n$ pip install -e .[dev]\n$ pre-commit install\n$ pre-commit run --all-files\n```\n\nAnd run these commands for testing:\n\n``` bash\n$ pip install -e .[strict]\n$ pip install -e .[tests]\n$ pytest --cov=pymatgen\n$ pytest --nbmake ./docs/source/content\n```\n\nFor more details about what is actually installed with each of the\n`pip install .[arg]` commands, please inspect the `pyproject.toml` file.\n\n# Contributors\n\n- Lead developer: Dr. Jimmy-Xuan Shen\n- This code contains contributions from the original defects analysis\n module of `pymatgen` from Dr. Danny Broberg and Dr. Shyam\n Dwaraknath.\n",
"bugtrack_url": null,
"license": "modified BSD",
"summary": "Pymatgen extension for defects analysis",
"version": "2024.4.23",
"project_urls": {
"documentation": "https://materialsproject.github.io/pymatgen-analysis-defects/",
"homepage": "https://materialsproject.github.io/pymatgen-analysis-defects/",
"repository": "https://github.com/materialsproject/pymatgen-analysis-defects"
},
"split_keywords": [
"high-throughput",
" automated",
" dft",
" defects"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1811772fe666c28fbf8a3bbd51c463be39bcbadbadbdae6e455dee27d5f2abfe",
"md5": "e0934465b2a172e5deac843050eee0f3",
"sha256": "0ddee4c601a6ac41734dafd8b0bd6e64ac3104431a072fda4f3de7d5c53a4d72"
},
"downloads": -1,
"filename": "pymatgen_analysis_defects-2024.4.23-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e0934465b2a172e5deac843050eee0f3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 77233,
"upload_time": "2024-04-22T22:38:57",
"upload_time_iso_8601": "2024-04-22T22:38:57.963788Z",
"url": "https://files.pythonhosted.org/packages/18/11/772fe666c28fbf8a3bbd51c463be39bcbadbadbdae6e455dee27d5f2abfe/pymatgen_analysis_defects-2024.4.23-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f72add66ba2424b4007ce3e149c8dbd1d0ae12ad7b3bd8f70a32e4e3092056de",
"md5": "3256ff6107a07812699d515b453dc0e0",
"sha256": "d6997e331d585df2cc7caab78724365daa4412480a2e403811fb72914485bb6c"
},
"downloads": -1,
"filename": "pymatgen_analysis_defects-2024.4.23.tar.gz",
"has_sig": false,
"md5_digest": "3256ff6107a07812699d515b453dc0e0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 73678,
"upload_time": "2024-04-22T22:38:59",
"upload_time_iso_8601": "2024-04-22T22:38:59.714503Z",
"url": "https://files.pythonhosted.org/packages/f7/2a/dd66ba2424b4007ce3e149c8dbd1d0ae12ad7b3bd8f70a32e4e3092056de/pymatgen_analysis_defects-2024.4.23.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-22 22:38:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "materialsproject",
"github_project": "pymatgen-analysis-defects",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pymatgen-analysis-defects"
}
JSON
