pymatgen

Was macht pymatgen?

Verwenden Sie pymatgen für explizite, herkunftssichernde Arbeit mit Zusammensetzungen, Molekülen, periodischen Strukturen, berechneten Einträgen, Symmetrie, Phasendiagrammen, elektronischen Strukturen und Elektronenstruktur-Code-Dateien. Behandeln Sie jedes Parsen, Konvertieren, jede Symmetriezuweisung, Transformation und jedes Datenbankergebnis als methoden- und parameterabhängig.

Die MIT-Frontmatter-Lizenz deckt diese Fähigkeit ab. pymatgen und pymatgen-core sind MIT; mp-api deklariert BSD-3-Clause-LBNL. Daten des Materials Project sind in der Regel CC BY 4.0, während beigesteuerte Daten im Besitz ihrer Beitragenden bleiben. Überprüfen Sie die genauen Artefakt- und Datenbedingungen vor einer Weiterverbreitung.

Verifizierter Snapshot (2026-07-23)

• pymatgen==2026.5.4 ist die neueste stabile Wrapper-Version (2026-05-04). Die Paketmetadaten erfordern Python 3.11+ und direkt pymatgen-core>=2026.4.16.
• pymatgen-core==2026.7.16 ist die neueste stabile Kernversion (2026-07-16). Sie enthält jetzt Kernobjekte, Symmetrie/Gitter-Operationen und die I/O-Schicht, alles unter dem bestehenden pymatgen.*-Namespace.
• mp-api==0.46.4 ist der neueste stabile Materials Project-Client (2026-06-15), erfordert Python 3.11+ und hängt von pymatgen>2024.2.20 ab.
• Die aktuelle API-Seite basiert auf der Kerndokumentation von 2026.7.16. Das Pinnen beider Distributionen verhindert, dass pymatgen==2026.5.4 stillschweigend zu einem anderen zukünftigen Kern aufgelöst wird.
• Pymatgen verwendet datumsbasierte Versionen. PyPI rendert das Datum mit Punkten; leiten Sie keine semantische Versionskompatibilität aus den Zahlen ab.

Erstellen Sie ein Projektschloss für Reproduzierbarkeit:

uv init --python 3.11
uv add "pymatgen==2026.5.4" "pymatgen-core==2026.7.16" "mp-api==0.46.4"
uv lock
uv sync --frozen

Für eine verwertbare, geprüfte Umgebung:

uv venv --python 3.11 .venv-pymatgen
uv pip install --python .venv-pymatgen/bin/python \
  "pymatgen==2026.5.4" "pymatgen-core==2026.7.16" "mp-api==0.46.4"

Direkte Pins frieren nicht alle transitiven Räder ein. Bewahren Sie uv.lock, Plattform, Python-Version, Paketversionen und Artefakt-Hashes auf.

Erforderlicher Arbeitsablauf

1. Geben Sie an, ob das Objekt ein nicht-periodisches Molecule oder eine periodische Structure ist; notieren Sie Gitter und periodische Randbedingungen.
2. Geben Sie Einheiten an. Pymatgen verwendet üblicherweise Å, Grad, eV, eV/Atom, amu und g/cm³, aber der dokumentierte Vertrag jeder API ist maßgeblich.
3. Geben Sie den Koordinatenmodus an. Structure-Koordinaten sind fraktional, es sei denn, coords_are_cartesian=True; Molecule-Koordinaten sind kartesisch.
4. Überprüfen Sie jede Parser-Warnung. Bewahren Sie für CIF Warnungen zu Besetzung, Site-Merging, Stöchiometrie und Korrektur auf; akzeptieren Sie Korrekturen nicht stillschweigend.
5. Melden Sie Fehlordnung/Teilbesetzungen und Oxidationsstufendekoration. Raten Sie niemals implizit Oxidationsstufen.
6. Führen Sie eine Validierung vor Symmetrie-, Nachbar-, Transformations-, Konvertierungs- oder thermodynamischer Analyse durch.
7. Durchsuchen Sie Symmetrietoleranzen und melden Sie symprec in Å und angle_tolerance in Grad bei jeder Zuweisung.
8. Behandeln Sie Transformationen als neue Artefakte. Bewahren Sie die Eingabe, Parameter, Softwareversionen, Warnungen und Prüfsummen von Eltern/Kind auf.
9. Identifizieren Sie vor der Konvertierung den Repräsentationsverlust. Schreiben Sie nur in einen neuen Pfad und überprüfen Sie wissenschaftlich relevante Eigenschaften im Round-Trip.
10. Erstellen Sie Phasendiagramme nur aus kompatiblen Gesamtenergien und Korrekturschemata. Ein berechneter Hull ist abhängig vom gelieferten Eintragssatz.
11. Halten Sie jeglichen Datenbankzugriff standardmäßig deaktiviert. Legen Sie Endpunkt, Filter, Felder, Ergebnislimit, Cache-Verhalten, Ausgabe, Lizenz und Zitation vor einem expliziten Ausführungsschritt offen.
12. Bewahren Sie ein Artefaktmanifest auf. Verwenden Sie niemals Pickle oder laden Sie ein nicht vertrauenswürdiges allgemeines Objektgraph; verwenden Sie schema-validiertes JSON und explizite Konstruktoren.

Kernobjekte

Verwenden Sie die öffentlichen Convenience-Importe:

from pymatgen.core import Composition, Element, Lattice, Molecule, Structure

composition = Composition("LiFePO4", strict=True)
iron = Element("Fe")

lattice = Lattice.cubic(5.64)  # Å
structure = Structure(
    lattice,
    ["Na", "Cl"],
    [[0, 0, 0], [0.5, 0.5, 0.5]],
    coords_are_cartesian=False,
    validate_proximity=True,
)

molecule = Molecule(
    ["O", "H", "H"],
    [[0.0, 0.0, 0.0], [0.758, 0.0, 0.504], [-0.758, 0.0, 0.504]],
    charge=0,
    spin_multiplicity=1,
)

Structure und Molecule sind veränderbar; verwenden Sie IStructure/IMolecule oder eine explizite Kopie, wenn Mutation die Herkunft gefährden würde. Siehe Kernklassen.

Sichere lokale Strukturaufnahme

Bevorzugen Sie den gebündelten Validator, der CIF- und Python-Warnungen erfasst und Einheiten, Besetzung, Fehlordnung, Oxidationsstufen, Periodizität, Koordinatenmodus und Mindestabstände meldet:

python scripts/composition_structure_validator.py composition "Fe2O3"
python scripts/composition_structure_validator.py structure structure.cif
python scripts/structure_analyzer.py structure.cif --symmetry

Für direkte CIF-Arbeit verwenden Sie die aktuelle Parser-Methode und überprüfen Sie beide Warnkanäle:

import warnings
from pymatgen.io.cif import CifParser

with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    parser = CifParser("input.cif", check_cif=True)
    structures = parser.parse_structures(
        primitive=False,
        check_occu=True,
        on_error="raise",
    )

parser_messages = list(parser.warnings)
python_messages = [str(item.message) for item in caught]

Analysieren Sie keine nicht vertrauenswürdigen Dateien in einem privilegierten Prozess. Ein kritischer bösartiger CIF-Codeausführungsfehler betraf pymatgen bis 2024.2.8 und wurde in 2024.2.20 behoben; die gepinnte Version ist neuer, aber Parser verarbeiten immer noch angreifergesteuerte Eingaben. Verwenden Sie Isolation und CPU/RAM/Disk/Zeit-Limits.

Symmetrie

Die Raumgruppenzuweisung hängt von Toleranzen und Strukturqualität ab:

from pymatgen.symmetry.analyzer import SpacegroupAnalyzer

analyzer = SpacegroupAnalyzer(
    structure,
    symprec=0.01,          # Å
    angle_tolerance=5.0,   # Grad
)
symbol = analyzer.get_space_group_symbol()
number = analyzer.get_space_group_number()

Die Pipeline des Materials Project verwendet üblicherweise symprec=0.1 Å, während der dokumentierte Standard von pymatgen 0.01 Å ist; diese können unterschiedliche Zuweisungen erzeugen. Generieren Sie einen Empfindlichkeitsbericht, anstatt die Toleranz zu ändern, bis eine bevorzugte Antwort erscheint:

python scripts/symmetry_sensitivity_report.py structure.cif \
  --symprec 0.001,0.01,0.1 --angle-tolerance 1,5

Siehe Analysemodule.

Konvertierung und Parser/Writer I/O

Planen Sie zuerst; der Planer öffnet keine Dateien oder importiert pymatgen:

python scripts/io_conversion_plan.py \
  --input input.cif --input-format cif \
  --output POSCAR.new --output-format poscar \
  --periodic --coordinate-mode direct

Konvertieren Sie dann zu einem neuen Pfad mit expliziter Verlustbestätigung:

python scripts/structure_converter.py input.cif POSCAR.new \
  --output-format poscar --coordinate-mode direct --allow-lossy \
  --acknowledge-parser-warnings

CIF, POSCAR, XYZ und JSON bewahren nicht dieselbe Semantik. Überprüfen Sie Gitter, Periodizität, Koordinatenmodus, Spezies-Reihenfolge, selektive Dynamik, Site-Eigenschaften, Oxidationsstufen, Bezeichnungen und Fehlordnung nach jeder Konvertierung. Siehe I/O-Formate.

Transformationen und Herkunft

Transformieren Sie eine Kopie und bewahren Sie die Historie:

from pymatgen.alchemy.materials import TransformedStructure
from pymatgen.transformations.standard_transformations import (
    SubstitutionTransformation,
    SupercellTransformation,
)

tracked = TransformedStructure(structure.copy(), [])
tracked.append_transformation(SupercellTransformation([2, 2, 2]))
tracked.append_transformation(SubstitutionTransformation({"Na": "K"}))
derived = tracked.final_structure
history = tracked.history

Eins-zu-Viele-Ordnungs-, Dotierungs-, Slab- und magnetische Transformationen können kombinatorisch expandieren oder optionale ausführbare Dateien aufrufen. Begrenzen Sie Kandidaten, Sites, Supercell-Größe, Laufzeit und Ausgabeanzahl. Siehe Transformationen und Arbeitsabläufe.

Lokale Phasendiagramme

Der gebündelte Generator ist offline und akzeptiert nur ein strenges JSON-Schema mit Gesamt-eV pro Eintrag und Herkunft:

{
  "schema_version": "1.0",
  "energy_unit": "eV",
  "energy_basis": "total_per_entry",
  "provenance": {
    "source": "überprüfte lokale Berechnungen",
    "method": "ein kompatibles Energie/Korrektur-Schema"
  },
  "entries": [
    {
      "entry_id": "local-Li",
      "composition": "Li",
      "energy_eV": -1.0,
      "provenance": {"source": "Berechnungsmanifest sha256:..."}
    }
  ]
}

python scripts/phase_diagram_generator.py entries.json --analyze Li2O

Elementare Endpunkte und alle konkurrierenden Phasen müssen vorhanden sein. Mischen Sie keine rohen Energien aus verschiedenen Funktionalen, Pseudopotentialen, magnetischen Zuständen oder Korrekturkonventionen. Der berechnete On-Hull-Status ist keine experimentelle Stabilität.

Bandstrukturen, DOS, VASP und Q-Chem

Analysieren Sie nur die benötigten Daten:

from pymatgen.io.vasp import Vasprun

run = Vasprun(
    "vasprun.xml",
    parse_dos=True,
    parse_eigen=True,
    parse_projected_eigen=False,
    parse_potcar_file=False,
)
band_structure = run.get_band_structure(line_mode=True)
band_gap = band_structure.get_band_gap()
complete_dos = run.complete_dos

Projizierte Eigenwerte können extremen Speicher erfordern. Überprüfen Sie Konvergenz, k-Pfad, Spin/SOC-Einstellungen, Fermi-Level-Konventionen, Smearing und Projektionsbasis, bevor Sie Bandlücken oder DOS interpretieren. Ein Parser-Erfolg ist keine konvergierte Berechnung.

Aktuelle Q-Chem-Schnittstellen sind pymatgen.io.qchem.inputs.QCInput und pymatgen.io.qchem.outputs.QCOutput:

from pymatgen.io.qchem.inputs import QCInput

job = QCInput(
    molecule,
    rem={"job_type": "sp", "method": "wb97x-v", "basis": "def2-svpd"},
)
text = str(job)

Pymatgen schreibt Eingaben und analysiert Ausgaben; es gewährt keine VASP- oder Q-Chem-Lizenz oder stellt die Methodengültigkeit fest. POTCAR-Dateien sind VASP-lizenziert und werden nicht von pymatgen verteilt. Verteilen Sie sie niemals weiter oder durchsuchen Sie nicht verwandte Verzeichnisse danach. Optionale Tools wie enumlib, Bader, packmol, ffmpeg und Zeo++ sind native/externe ausführbare Dateien: Überprüfen Sie Herkunft, Lizenzen, argv, Arbeitsverzeichnis und Ressourcenlimits vor einem separaten expliziten Aufruf.

Materials Project: Planen vor Netzwerk

Verwenden Sie nur:

from mp_api.client import MPRester

Der Client liest MP_API_KEY beim Erstellen. Stellen Sie nur diese benannte Umgebungsvariable über die Shell des Benutzers oder den Secret-Manager bereit. Akzeptieren Sie den Schlüssel nicht als CLI-Argument, durchsuchen Sie .env-Dateien, geben Sie Umgebungsvariablen aus oder drucken Sie Ausnahmedaten ohne Schwärzung.

Trockenlauf-Planung ist die Standardeinstellung:

python scripts/mp_query.py \
  --chemsys Li-Fe-O \
  --energy-above-hull 0 0.05 \
  --fields formula_pretty,energy_above_hull,band_gap,origins \
  --limit 25

Nur --execute erlaubt eine begrenzte Zusammenfassungsabfrage und erfordert eine neue Ausgabe:

python scripts/mp_query.py \
  --material-id mp-149 \
  --fields formula_pretty,structure,origins,last_updated \
  --limit 1 --output mp-149.json --execute

Das CLI setzt num_chunks=1, erfordert explizite Felder und Filter, begrenzt Ergebnisse, implementiert keinen impliziten Ergebnis-Cache und überschreibt niemals die Ausgabe. Die MPRester-Initialisierung führt auch Kompatibilitäts-/Heartbeat-Metadatenanfragen durch; der Plan legt diese offen, deaktiviert den Plattform-Detail-User-Agent und das lokale Datenbankversions-Benachrichtigungslog und zeichnet die zurückgegebene Datenbankversion auf. Der Zusammenfassungs-Workflow fordert keine Cache-Downloads des vollständigen Datensatzes an. mp-api 0.46.4 wiederholt HTTP 429/502/504 gemäß seiner eigenen konfigurierten Richtlinie und respektiert Retry-After; erfinden Sie kein numerisches Service-Kontingent oder fügen Sie eine unbegrenzte Wiederholungsschleife hinzu.

Die Kernwerte des Materials Project sind berechnete, methodenabhängige Daten – keine experimentelle Wahrheit. PBE überschätzt üblicherweise Gitterparameter und unterschätzt systematisch Bandlücken; aggregierte Werte können sich über Datenbankversionen hinweg ändern. Bewahren Sie Abrufzeitpunkt, Abfrage, Felder, Material-/Aufgabenherkunft, Datenbankversion (sofern verfügbar), Client-Versionen, CC BY-Attribution und die kanonischen plus eigenschaftsspezifischen Zitationen auf. Siehe Materials Project API.

Gebündelte CLIs

Alle CLIs haben abhängigkeitsfreies --help, träge wissenschaftliche Importe, begrenztes JSON und kein implizites Netzwerk:

• scripts/composition_structure_validator.py — strenge Zusammensetzungs-/Strukturprüfungen; optionales Oxidationsstufenraten ist explizit und begrenzt.
• scripts/structure_analyzer.py — begrenzter Gitter-, Site-, Symmetrie-, Abstands- und optionaler CrystalNN-Bericht.
• scripts/symmetry_sensitivity_report.py — Toleranzgitter-Raumgruppen.
• scripts/io_conversion_plan.py — abhängigkeitsfreier Repräsentationsverlustplan.
• scripts/structure_converter.py — Ein-Datei-Konvertierung in einen neuen Pfad.
• scripts/phase_diagram_generator.py — strenger lokaler berechneter Eintrags-Hull.
• scripts/mp_query.py — Trockenlauf-MP-Abfrageplan und opt-in begrenzter Client.
• scripts/artifact_manifest.py — Prüfsummen, Versionen, Quellen und Herkunft.

Verwenden Sie:

python scripts/artifact_manifest.py \
  --artifact input.cif --artifact analysis.json \
  --workflow "local symmetry sensitivity" --output manifest.json

Referenzen

• Kernklassen
• I/O-Formate, VASP und Q-Chem
• Analyse, Symmetrie, Phasendiagramme, Bänder und DOS
• Transformationen und Arbeitsabläufe
• Materials Project API, Herkunft, Lizenz und Limits

Quellen (verifiziert 2026-07-23)

• pymatgen 2026.5.4 auf PyPI
• pymatgen-core 2026.7.16 auf PyPI
• pymatgen API-Dokumentation
• pymatgen Changelog
• mp-api 0.46.4 auf PyPI