pymatgen

Que fait pymatgen ?

Utilisez pymatgen pour un travail explicite et préservant la provenance avec les compositions, molécules, structures périodiques, entrées calculées, symétrie, diagrammes de phases, structures électroniques et fichiers de codes de structure électronique. Traitez chaque analyse, conversion, assignation de symétrie, transformation et résultat de base de données comme dépendant de la méthode et des paramètres.

La licence MIT de l'en-tête couvre cette compétence. pymatgen et pymatgen-core sont sous licence MIT ; mp-api déclare BSD-3-Clause-LBNL. Les données de Materials Project sont généralement sous licence CC BY 4.0, tandis que les données contribuées restent la propriété de leurs contributeurs. Vérifiez les termes exacts de l'artefact et des données avant redistribution.

Instantané vérifié (2026-07-23)

• pymatgen==2026.5.4 est la dernière version stable de l'ensemble (2026-05-04). Les métadonnées du paquet exigent Python 3.11+ et nécessitent directement pymatgen-core>=2026.4.16.
• pymatgen-core==2026.7.16 est la dernière version stable du noyau (2026-07-16). Il contient désormais les objets centraux, les opérations de symétrie/réseau et la couche d'E/S, le tout sous l'espace de noms existant pymatgen.*.
• mp-api==0.46.4 est le dernier client stable pour Materials Project (2026-06-15), nécessite Python 3.11+ et dépend de pymatgen>2024.2.20.
• Le site API actuel est construit à partir de la documentation du noyau 2026.7.16. Épingler les deux distributions empêche pymatgen==2026.5.4 de se résoudre silencieusement en un noyau futur différent.
• Pymatgen utilise des versions basées sur des dates. PyPI affiche la date avec des points ; ne pas inférer la compatibilité sémantique des versions à partir des nombres.

Créez un verrou de projet pour la reproductibilité :

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

Pour un environnement révisé jetable :

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"

Les épinglages directs ne gèlent pas toutes les roues transitives. Préservez uv.lock, la plateforme, la version de Python, les versions de paquets et les hachages des artefacts.

Flux de travail requis

1. Indiquez si l'objet est une Molecule non périodique ou une Structure périodique ; enregistrez le réseau et les conditions aux limites périodiques.
2. Indiquez les unités. Pymatgen utilise couramment Å, degrés, eV, eV/atome, uma et g/cm³, mais le contrat documenté de chaque API fait autorité.
3. Indiquez le mode de coordonnées. Les coordonnées de Structure sont fractionnaires sauf si coords_are_cartesian=True ; les coordonnées de Molecule sont cartésiennes.
4. Inspectez chaque avertissement de l'analyseur. Pour CIF, préservez les avertissements d'occupation, de fusion de sites, de stœchiométrie et de correction ; n'acceptez pas silencieusement de correctifs.
5. Signalez le désordre/les occupations partielles et la décoration des états d'oxydation. Ne devinez jamais les états d'oxydation de manière implicite.
6. Exécutez la validation avant l'analyse de symétrie, de voisinage, de transformation, de conversion ou thermodynamique.
7. Parcourez les tolérances de symétrie et rapportez symprec en Å et angle_tolerance en degrés avec chaque assignation.
8. Traitez les transformations comme de nouveaux artefacts. Préservez l'entrée, les paramètres, les versions logicielles, les avertissements et les sommes de contrôle parent/enfant.
9. Avant la conversion, identifiez la perte de représentation. Écrivez uniquement vers un nouveau chemin et vérifiez par aller-retour les propriétés scientifiquement pertinentes.
10. Construisez des diagrammes de phases uniquement à partir d'énergies totales compatibles et de schémas de correction. Une enveloppe convexe calculée est conditionnelle à l'ensemble d'entrées fourni.
11. Gardez tout accès à la base de données désactivé par défaut. Divulguez le point de terminaison, les filtres, les champs, la limite de résultats, le comportement du cache, la sortie, la licence et la citation avant une étape d'exécution explicite.
12. Préservez un manifeste d'artefact. N'utilisez jamais pickle et ne chargez pas un graphe d'objets général non fiable ; utilisez du JSON validé par schéma et des constructeurs explicites.

Objets centraux

Utilisez les importations de commodité publiques :

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 et Molecule sont mutables ; utilisez IStructure/IMolecule ou une copie explicite lorsque la mutation compromettrait la provenance. Voir classes centrales.

Prise en charge locale sécurisée des structures

Préférez le validateur fourni, qui capture les avertissements CIF et Python et rapporte les unités, l'occupation, le désordre, les états d'oxydation, la périodicité, le mode de coordonnées et les distances minimales :

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

Pour un travail direct avec CIF, utilisez la méthode actuelle de l'analyseur et inspectez les deux canaux d'avertissement :

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]

N'analysez pas de fichiers non fiables dans un processus privilégié. Une vulnérabilité critique d'exécution de code par CIF malveillant a affecté pymatgen jusqu'à la version 2024.2.8 et a été corrigée dans 2024.2.20 ; la version épinglée est plus récente, mais les analyseurs traitent toujours des entrées contrôlées par un attaquant. Utilisez l'isolation et les limites de CPU/RAM/disque/temps.

Symétrie

L'assignation du groupe d'espace dépend des tolérances et de la qualité de la structure :

from pymatgen.symmetry.analyzer import SpacegroupAnalyzer

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

Le pipeline de Materials Project utilise couramment symprec=0.1 Å, tandis que la valeur par défaut documentée de pymatgen est 0.01 Å ; ces valeurs peuvent produire des assignations différentes. Générez un rapport de sensibilité au lieu de modifier la tolérance jusqu'à obtenir une réponse préférée :

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

Voir modules d'analyse.

Conversion et E/S d'analyseur/rédacteur

Planifiez d'abord ; le planificateur n'ouvre pas de fichiers et n'importe pas pymatgen :

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

Convertissez ensuite vers un nouveau chemin avec une reconnaissance explicite de perte :

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

CIF, POSCAR, XYZ et JSON ne préservent pas la même sémantique. Vérifiez le réseau, la périodicité, le mode de coordonnées, l'ordre des espèces, la dynamique sélective, les propriétés de site, les états d'oxydation, les étiquettes et le désordre après chaque conversion. Voir formats d'E/S.

Transformations et provenance

Transformez une copie et préservez l'historique :

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

Les transformations de type un-à-plusieurs (ordonnancement, dopage, surface, magnétique) peuvent se développer de manière combinatoire ou invoquer des exécutables optionnels. Limitez les candidats, les sites, la taille de la supercellule, le temps d'exécution et le nombre de sorties. Voir transformations et flux de travail.

Diagrammes de phases locaux

Le générateur fourni est hors ligne et n'accepte qu'un schéma JSON strict avec l'énergie totale en eV par entrée et la provenance :

{
  "schema_version": "1.0",
  "energy_unit": "eV",
  "energy_basis": "total_per_entry",
  "provenance": {
    "source": "reviewed local calculations",
    "method": "one compatible energy/correction scheme"
  },
  "entries": [
    {
      "entry_id": "local-Li",
      "composition": "Li",
      "energy_eV": -1.0,
      "provenance": {"source": "calculation manifest sha256:..."}
    }
  ]
}

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

Les points de terminaison élémentaires et toutes les phases concurrentes doivent être présents. Ne mélangez pas des énergies brutes provenant de différentes fonctionnelles, pseudopotentiels, états magnétiques ou conventions de correction. L'état calculé sur l'enveloppe convexe n'est pas une stabilité expérimentale.

Structures de bandes, DOS, VASP et Q-Chem

Analysez uniquement les données nécessaires :

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

Les valeurs propres projetées peuvent nécessiter une mémoire extrême. Vérifiez la convergence, le chemin-k, les réglages de spin/SOC, les conventions de niveau de Fermi, l'élargissement et la base de projection avant d'interpréter les gaps ou DOS. Un succès de l'analyseur n'est pas un calcul convergé.

Les interfaces Q-Chem actuelles sont pymatgen.io.qchem.inputs.QCInput et 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 écrit les entrées et analyse les sorties ; il n'accorde pas de licence VASP ou Q-Chem ni n'établit la validité de la méthode. Les fichiers POTCAR sont sous licence VASP et ne sont pas distribués par pymatgen. Ne les redistribuez jamais et ne parcourez pas des répertoires non liés pour les trouver. Les outils optionnels tels que enumlib, Bader, packmol, ffmpeg et Zeo++ sont des exécutables natifs/externes : examinez la provenance, les licences, argv, le répertoire de travail et les limites de ressources avant une invocation explicite séparée.

Materials Project : planifier avant le réseau

Utilisez uniquement :

from mp_api.client import MPRester

Le client lit MP_API_KEY lors de la construction. Fournissez uniquement cette variable d'environnement nommée via le shell de l'utilisateur ou un gestionnaire de secrets. N'acceptez pas la clé comme argument CLI, ne parcourez pas les fichiers .env, ne videz pas les variables d'environnement et n'imprimez pas les données d'exception sans rédaction.

La planification à sec est la valeur par défaut :

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

Seulement --execute permet une requête de résumé bornée et nécessite une nouvelle sortie :

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

Le CLI définit num_chunks=1, exige des champs et filtres explicites, limite les résultats, n'implémente pas de cache implicite des résultats et n'écrase jamais la sortie. L'initialisation de MPRester effectue également des requêtes de métadonnées de compatibilité/battement de cœur ; le plan divulgue ces requêtes, désactive le journal d'agent utilisateur de détails de plateforme et de notification de version de base de données locale, et enregistre la version de base de données retournée. Le flux de travail de résumé ne demande pas de téléchargement complet du cache de l'ensemble de données. mp-api 0.46.4 réessaie les codes HTTP 429/502/504 selon sa propre politique configurée et respecte Retry-After ; n'inventez pas de quota de service numérique ni n'ajoutez de boucle de réessai non bornée.

Les valeurs centrales de Materials Project sont des données calculées, dépendantes de la méthode — pas des vérités expérimentales. PBE surestime couramment les paramètres de réseau et sous-estime systématiquement les gaps de bande ; les valeurs agrégées peuvent changer à travers les versions de base de données. Préservez l'heure de récupération, la requête, les champs, les origines du matériau/tâche, la version de la base de données lorsqu'elle est disponible, les versions du client, l'attribution CC BY et les citations canoniques plus spécifiques à la propriété. Voir API Materials Project.

CLI fournis

Tous les CLI ont une aide --help sans dépendance, des importations scientifiques paresseuses, du JSON borné et aucun réseau implicite :

• scripts/composition_structure_validator.py — vérifications strictes de composition/structure ; la devinette d'état d'oxydation optionnelle est explicite et bornée.
• scripts/structure_analyzer.py — rapport borné du réseau, des sites, de la symétrie, des distances et de CrystalNN optionnel.
• scripts/symmetry_sensitivity_report.py — groupes d'espace par grille de tolérance.
• scripts/io_conversion_plan.py — plan de perte de représentation sans dépendance.
• scripts/structure_converter.py — conversion d'un seul fichier vers un nouveau chemin.
• scripts/phase_diagram_generator.py — enveloppe convexe stricte d'entrée locale calculée.
• scripts/mp_query.py — plan de requête MP à sec et client borné sur option.
• scripts/artifact_manifest.py — sommes de contrôle, versions, sources et provenance.

Utilisez :

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

Références

• Classes centrales
• Formats d'E/S, VASP et Q-Chem
• Analyse, symétrie, diagrammes de phases, bandes et DOS
• Transformations et flux de travail
• API Materials Project, provenance, licence et limites

Sources (vérifié le 2026-07-23)

• pymatgen 2026.5.4 sur PyPI
• pymatgen-core 2026.7.16 sur PyPI
• Documentation de l'API pymatgen
• Journal des modifications de pymatgen
• mp-api 0.46.4 sur PyPI