Registry /
data / pymatgen-analysis-defects
Install & Compatibility
Where this runs
tested against v2026.3.20 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 29.3s · import 6.979s · 610MB
645MB installed
● package 645MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
generate_all_native_defects
✓ from pymatgen.analysis.defects.generators import generate_all_native_defects
ChargeInterstitialGenerator
✓ from pymatgen.analysis.defects.generators import ChargeInterstitialGenerator
DefectEntry
✓ from pymatgen.analysis.defects.thermo import DefectEntry
FormationEnergyDiagram
✓ from pymatgen.analysis.defects.thermo import FormationEnergyDiagram
Defect
✓ from pymatgen.analysis.defects.core import Defect
✗ defect_instance = Defect(structure=my_structure, ...)
Defect is an abstract base class and cannot be instantiated directly. Use its concrete subclasses like Vacancy, Interstitial, Substitution, etc., or functions that return Defect objects.
This quickstart demonstrates how to use `pymatgen-analysis-defects` to generate a list of native point defects for a material fetched from the Materials Project database. It utilizes `MPRester` from `mp-api` to retrieve a structure and then `generate_all_native_defects` to enumerate possible defects.
import os
from mp_api.client import MPRester
from pymatgen.analysis.defects.generators import generate_all_native_defects
# Replace with your Materials Project API key if needed
# For quickstart, using os.environ.get is safer for direct execution
api_key = os.environ.get("MP_API_KEY", "")
if api_key:
try:
with MPRester(api_key=api_key) as mpr:
# Fetch a charge density object for a material (e.g., mp-804 for SrTiO3)
print("Fetching charge density from Materials Project...")
chgcar = mpr.get_charge_density_from_material_id("mp-804")
# Generate all native defects for the fetched structure
print("Generating native defects...")
native_defects = generate_all_native_defects(chgcar.structure)
print(f"Found {len(native_defects)} native defects. First 3 examples:")
for i, defect in enumerate(native_defects[:3]):
print(f" Defect {i+1}: {defect.name}, Charge states: {defect.charge_states}")
except Exception as e:
print(f"An error occurred while connecting to MPRester or processing data: {e}")
print("Ensure your MP_API_KEY is correct and you have internet access.")
else:
print("MP_API_KEY not found. Skipping Materials Project API example.")
print("Please set the MP_API_KEY environment variable to run this example.")
Debug
Known issues
breakingDefect analysis functionality was extracted from the main `pymatgen` library into this dedicated `pymatgen-analysis-defects` package starting from `pymatgen` version `2022.0.3` onwards. Direct imports from `pymatgen.analysis.defects` will no longer work if `pymatgen-analysis-defects` is not installed or if using older `pymatgen` versions without the explicit add-on.fixEnsure `pymatgen-analysis-defects` is installed (`pip install pymatgen-analysis-defects`). Update import statements to reflect the package's structure, e.g., `from pymatgen.analysis.defects.generators import ...`.
affects: pymatgen >= 2022.0.3
gotchaThe `pymatgen.analysis.defects.core.Defect` class is an abstract base class. You cannot directly instantiate `Defect` objects; instead, you should use its concrete subclasses (e.g., `Vacancy`, `Interstitial`, `Substitution`) or use generator functions that return pre-formed defect objects.fixDo not attempt to create instances of `Defect` directly. Utilize specific defect classes like `Vacancy(...)` or `generate_all_native_defects(...)` to obtain valid defect objects.
affects: All versions
gotchaErrors during parsing of VASP output files (e.g., `vasprun.xml`, `LOCPOT`) using `pymatgen-analysis-defects` (or related `pymatgen` parsing utilities) often indicate corrupted, incomplete, or malformed VASP output files.fixInspect the VASP output file mentioned in the error traceback for integrity. If it's corrupted or incomplete, re-run the VASP calculation to obtain valid output files. Using `DefectParser.from_paths` individually can provide more verbose error messages.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pymatgen.analysis.defects'
The defect analysis code was moved to a separate package. The old `pymatgen.analysis.defects` module no longer exists in recent `pymatgen` versions by default.
fixInstall the dedicated package: `pip install pymatgen-analysis-defects`. Ensure your import statements are updated to reflect the new package structure.
TypeError: Can't instantiate abstract class Defect with abstract methods get_bulk_supercell, get_charge_state_site_mapping, get_defect_structure
Attempting to create an object directly from the abstract base class `pymatgen.analysis.defects.core.Defect`.
fixInstead of `Defect(...)`, use concrete subclasses like `Vacancy(...)`, `Interstitial(...)`, `Substitution(...)`, or functions designed to generate defect objects, such as `generate_all_native_defects(...)`.
ParseError: no element found: line 1, column 0
This error, often related to `ElementTree` in tracebacks, typically indicates that a `vasprun.xml` (or similar XML-based VASP output file) is empty, truncated, or severely corrupted, preventing `pymatgen`'s parsers from reading it.
fixVerify the integrity of your VASP output file (e.g., `vasprun.xml` or `vasprun.xml.gz`). If it's incomplete or invalid, you must re-run the VASP calculation to generate a proper output file. Sometimes, using `zcat` or `gunzip -c` on a gzipped XML can reveal issues.
Upgrade
Version history
2026.3.20latest on PyPI · released Mar 20, 2026
Audit
Dependencies
pymatgenrequiredCore materials science library on which this package is built.
mp-apioptionalUsed for accessing Materials Project database, common in quickstart examples.
atomate2optionalRecommended for high-throughput defect calculation workflows.