pymatgen

Par mkurman · zorai

Boîte à outils pour la science des matériaux. Structures cristallines (CIF, POSCAR), diagrammes de phases, structure de bandes, DOS, intégration Materials Project, conversion de formats, pour la science computationnelle des matériaux.

npx skills add https://github.com/mkurman/zorai --skill pymatgen

Pymatgen - Python Materials Genomics

Présentation

Pymatgen est une bibliothèque Python complète pour l'analyse des matériaux qui alimente le Materials Project. Créez, analysez et manipulez des structures cristallines et des molécules, calculez des diagrammes de phase et des propriétés thermodynamiques, analysez la structure électronique (structures de bandes, DOS), générez des surfaces et interfaces, et accédez à la base de données du Materials Project de matériaux calculés. Supporte plus de 100 formats de fichiers provenant de divers codes de calcul.

Quand utiliser cette compétence

Cette compétence doit être utilisée quand :

  • Vous travaillez avec des structures cristallines ou des systèmes moléculaires en science des matériaux
  • Vous convertissez entre des formats de fichiers de structures (CIF, POSCAR, XYZ, etc.)
  • Vous analysez la symétrie, les groupes d'espace ou les environnements de coordination
  • Vous calculez des diagrammes de phase ou évaluez la stabilité thermodynamique
  • Vous analysez des données de structure électronique (bandes interdites, DOS, structures de bandes)
  • Vous générez des surfaces, des feuillets ou étudiez des interfaces
  • Vous accédez à la base de données du Materials Project par programmation
  • Vous configurez des workflows de calcul haut débit
  • Vous analysez la diffusion, le magnétisme ou les propriétés mécaniques
  • Vous travaillez avec VASP, Gaussian, Quantum ESPRESSO ou d'autres codes de calcul

Guide de démarrage rapide

Installation

# Pymatgen principal
uv pip install pymatgen

# Avec accès à l'API du Materials Project
uv pip install pymatgen mp-api

# Dépendances optionnelles pour une fonctionnalité étendue
uv pip install pymatgen[analysis]  # Outils d'analyse supplémentaires
uv pip install pymatgen[vis]       # Outils de visualisation

Opérations de structure basiques

from pymatgen.core import Structure, Lattice

# Lire une structure depuis un fichier (détection automatique du format)
struct = Structure.from_file("POSCAR")

# Créer une structure de zéro
lattice = Lattice.cubic(3.84)
struct = Structure(lattice, ["Si", "Si"], [[0,0,0], [0.25,0.25,0.25]])

# Écrire dans un format différent
struct.to(filename="structure.cif")

# Propriétés basiques
print(f"Formule : {struct.composition.reduced_formula}")
print(f"Groupe d'espace : {struct.get_space_group_info()}")
print(f"Densité : {struct.density:.2f} g/cm³")

Intégration du Materials Project

# Configurer la clé API
export MP_API_KEY="your_api_key_here"
from mp_api.client import MPRester

with MPRester() as mpr:
    # Obtenir une structure par ID de matériau
    struct = mpr.get_structure_by_material_id("mp-149")

    # Rechercher des matériaux
    materials = mpr.materials.summary.search(
        formula="Fe2O3",
        energy_above_hull=(0, 0.05)
    )

Capacités principales

1. Création et manipulation de structures

Créez des structures via plusieurs méthodes et effectuez des transformations.

À partir de fichiers :

# Détection automatique du format
struct = Structure.from_file("structure.cif")
struct = Structure.from_file("POSCAR")
mol = Molecule.from_file("molecule.xyz")

De zéro :

from pymatgen.core import Structure, Lattice

# En utilisant les paramètres de réseau
lattice = Lattice.from_parameters(a=3.84, b=3.84, c=3.84,
                                  alpha=120, beta=90, gamma=60)
coords = [[0, 0, 0], [0.75, 0.5, 0.75]]
struct = Structure(lattice, ["Si", "Si"], coords)

# À partir du groupe d'espace
struct = Structure.from_spacegroup(
    "Fm-3m",
    Lattice.cubic(3.5),
    ["Si"],
    [[0, 0, 0]]
)

Transformations :

from pymatgen.transformations.standard_transformations import (
    SupercellTransformation,
    SubstitutionTransformation,
    PrimitiveCellTransformation
)

# Créer une supercellule
trans = SupercellTransformation([[2,0,0],[0,2,0],[0,0,2]])
supercell = trans.apply_transformation(struct)

# Substituer des éléments
trans = SubstitutionTransformation({"Fe": "Mn"})
new_struct = trans.apply_transformation(struct)

# Obtenir la cellule primitive
trans = PrimitiveCellTransformation()
primitive = trans.apply_transformation(struct)

Référence : Voir references/core_classes.md pour la documentation exhaustive des classes Structure, Lattice, Molecule et connexes.

2. Conversion de formats de fichiers

Convertissez entre plus de 100 formats de fichiers avec détection automatique du format.

En utilisant les méthodes pratiques :

# Lire n'importe quel format
struct = Structure.from_file("input_file")

# Écrire dans n'importe quel format
struct.to(filename="output.cif")
struct.to(filename="POSCAR")
struct.to(filename="output.xyz")

En utilisant le script de conversion :

# Conversion d'un seul fichier
python scripts/structure_converter.py POSCAR structure.cif

# Conversion par lot
python scripts/structure_converter.py *.cif --output-dir ./poscar_files --format poscar

Référence : Voir references/io_formats.md pour la documentation détaillée de tous les formats supportés et intégrations de codes.

3. Analyse de structures et symétrie

Analysez les structures pour la symétrie, la coordination et d'autres propriétés.

Analyse de symétrie :

from pymatgen.symmetry.analyzer import SpacegroupAnalyzer

sga = SpacegroupAnalyzer(struct)

# Obtenir les informations du groupe d'espace
print(f"Groupe d'espace : {sga.get_space_group_symbol()}")
print(f"Numéro : {sga.get_space_group_number()}")
print(f"Système cristallin : {sga.get_crystal_system()}")

# Obtenir les cellules conventionnelles/primitives
conventional = sga.get_conventional_standard_structure()
primitive = sga.get_primitive_standard_structure()

Environnement de coordination :

from pymatgen.analysis.local_env import CrystalNN

cnn = CrystalNN()
neighbors = cnn.get_nn_info(struct, n=0)  # Voisins du site 0

print(f"Nombre de coordination : {len(neighbors)}")
for neighbor in neighbors:
    site = struct[neighbor['site_index']]
    print(f"  {site.species_string} à {neighbor['weight']:.3f} Å")

En utilisant le script d'analyse :

# Analyse exhaustive
python scripts/structure_analyzer.py POSCAR --symmetry --neighbors

# Exporter les résultats
python scripts/structure_analyzer.py structure.cif --symmetry --export json

Référence : Voir references/analysis_modules.md pour la documentation détaillée de toutes les capacités d'analyse.

4. Diagrammes de phase et thermodynamique

Construisez des diagrammes de phase et analysez la stabilité thermodynamique.

Construction de diagrammes de phase :

from mp_api.client import MPRester
from pymatgen.analysis.phase_diagram import PhaseDiagram, PDPlotter

# Obtenir les entrées du Materials Project
with MPRester() as mpr:
    entries = mpr.get_entries_in_chemsys("Li-Fe-O")

# Construire le diagramme de phase
pd = PhaseDiagram(entries)

# Vérifier la stabilité
from pymatgen.core import Composition
comp = Composition("LiFeO2")

# Trouver l'entrée pour la composition
for entry in entries:
    if entry.composition.reduced_formula == comp.reduced_formula:
        e_above_hull = pd.get_e_above_hull(entry)
        print(f"Énergie au-dessus de la coque convexe : {e_above_hull:.4f} eV/atome")

        if e_above_hull > 0.001:
            # Obtenir la décomposition
            decomp = pd.get_decomposition(comp)
            print("Se décompose en :", decomp)

# Tracer
plotter = PDPlotter(pd)
plotter.show()

En utilisant le script de diagramme de phase :

# Générer un diagramme de phase
python scripts/phase_diagram_generator.py Li-Fe-O --output li_fe_o.png

# Analyser une composition spécifique
python scripts/phase_diagram_generator.py Li-Fe-O --analyze "LiFeO2" --show

Référence : Voir references/analysis_modules.md (section Diagrammes de phase) et references/transformations_workflows.md (Workflow 2) pour des exemples détaillés.

5. Analyse de la structure électronique

Analysez les structures de bandes, la densité d'états et les propriétés électroniques.

Structure de bandes :

from pymatgen.io.vasp import Vasprun
from pymatgen.electronic_structure.plotter import BSPlotter

# Lire depuis un calcul VASP
vasprun = Vasprun("vasprun.xml")
bs = vasprun.get_band_structure()

# Analyser
band_gap = bs.get_band_gap()
print(f"Bande interdite : {band_gap['energy']:.3f} eV")
print(f"Direct : {band_gap['direct']}")
print(f"Est un métal : {bs.is_metal()}")

# Tracer
plotter = BSPlotter(bs)
plotter.save_plot("band_structure.png")

Densité d'états :

from pymatgen.electronic_structure.plotter import DosPlotter

dos = vasprun.complete_dos

# Obtenir la DOS projetée par élément
element_dos = dos.get_element_dos()
for element, element_dos_obj in element_dos.items():
    print(f"{element} : {element_dos_obj.get_gap():.3f} eV")

# Tracer
plotter = DosPlotter()
plotter.add_dos("DOS totale", dos)
plotter.show()

Référence : Voir references/analysis_modules.md (section Structure électronique) et references/io_formats.md (section VASP).

6. Analyse de surfaces et interfaces

Générez des feuillets, analysez des surfaces et étudiez des interfaces.

Génération de feuillets :

from pymatgen.core.surface import SlabGenerator

# Générer des feuillets pour un indice de Miller spécifique
slabgen = SlabGenerator(
    struct,
    miller_index=(1, 1, 1),
    min_slab_size=10.0,      # Å
    min_vacuum_size=10.0,    # Å
    center_slab=True
)

slabs = slabgen.get_slabs()

# Écrire les feuillets
for i, slab in enumerate(slabs):
    slab.to(filename=f"slab_{i}.cif")

Construction de la forme de Wulff :

from pymatgen.analysis.wulff import WulffShape

# Définir les énergies de surface
surface_energies = {
    (1, 0, 0): 1.0,
    (1, 1, 0): 1.1,
    (1, 1, 1): 0.9,
}

wulff = WulffShape(struct.lattice, surface_energies)
print(f"Aire de surface : {wulff.surface_area:.2f} Ų")
print(f"Volume : {wulff.volume:.2f} ų")

wulff.show()

Recherche de sites d'adsorption :

from pymatgen.analysis.adsorption import AdsorbateSiteFinder
from pymatgen.core import Molecule

asf = AdsorbateSiteFinder(slab)

# Trouver les sites
ads_sites = asf.find_adsorption_sites()
print(f"Sites on-top : {len(ads_sites['ontop'])}")
print(f"Sites bridge : {len(ads_sites['bridge'])}")
print(f"Sites creux : {len(ads_sites['hollow'])}")

# Ajouter un adsorbat
adsorbate = Molecule("O", [[0, 0, 0]])
ads_struct = asf.add_adsorbate(adsorbate, ads_sites["ontop"][0])

Référence : Voir references/analysis_modules.md (section Surface et interface) et references/transformations_workflows.md (Workflows 3 et 9).

7. Accès à la base de données du Materials Project

Accédez par programmation à la base de données du Materials Project.

Configuration :

  1. Obtenir une clé API sur https://next-gen.materialsproject.org/
  2. Définir la variable d'environnement : export MP_API_KEY="your_key_here"

Recherche et récupération :

from mp_api.client import MPRester

with MPRester() as mpr:
    # Rechercher par formule
    materials = mpr.materials.summary.search(formula="Fe2O3")

    # Rechercher par système chimique
    materials = mpr.materials.summary.search(chemsys="Li-Fe-O")

    # Filtrer par propriétés
    materials = mpr.materials.summary.search(
        chemsys="Li-Fe-O",
        energy_above_hull=(0, 0.05),  # Stable/métastable
        band_gap=(1.0, 3.0)            # Semi-conducteur
    )

    # Obtenir une structure
    struct = mpr.get_structure_by_material_id("mp-149")

    # Obtenir une structure de bandes
    bs = mpr.get_bandstructure_by_material_id("mp-149")

    # Obtenir les entrées pour un diagramme de phase
    entries = mpr.get_entries_in_chemsys("Li-Fe-O")

Référence : Voir references/materials_project_api.md pour la documentation exhaustive de l'API et des exemples.

8. Configuration de workflows de calcul

Configurez des calculs pour divers codes de structure électronique.

Génération d'entrées VASP :

from pymatgen.io.vasp.sets import MPRelaxSet, MPStaticSet, MPNonSCFSet

# Relaxation
relax = MPRelaxSet(struct)
relax.write_input("./relax_calc")

# Calcul statique
static = MPStaticSet(struct)
static.write_input("./static_calc")

# Structure de bandes (non auto-cohérente)
nscf = MPNonSCFSet(struct, mode="line")
nscf.write_input("./bandstructure_calc")

# Paramètres personnalisés
custom = MPRelaxSet(struct, user_incar_settings={"ENCUT": 600})
custom.write_input("./custom_calc")

Autres codes :

# Gaussian
from pymatgen.io.gaussian import GaussianInput

gin = GaussianInput(
    mol,
    functional="B3LYP",
    basis_set="6-31G(d)",
    route_parameters={"Opt": None}
)
gin.write_file("input.gjf")

# Quantum ESPRESSO
from pymatgen.io.pwscf import PWInput

pwin = PWInput(struct, control={"calculation": "scf"})
pwin.write_file("pw.in")

Référence : Voir references/io_formats.md (section I/O des codes de structure électronique) et references/transformations_workflows.md pour des exemples de workflows.

9. Analyse avancée

Motifs de diffraction :

from pymatgen.analysis.diffraction.xrd import XRDCalculator

xrd = XRDCalculator()
pattern = xrd.get_pattern(struct)

# Obtenir les pics
for peak in pattern.hkls:
    print(f"2θ = {peak['2theta']:.2f}°, hkl = {peak['hkl']}")

pattern.plot()

Propriétés élastiques :

from pymatgen.analysis.elasticity import ElasticTensor

# À partir de la matrice du tenseur élastique
elastic_tensor = ElasticTensor.from_voigt(matrix)

print(f"Module de compressibilité : {elastic_tensor.k_voigt:.1f} GPa")
print(f"Module de cisaillement : {elastic_tensor.g_voigt:.1f} GPa")
print(f"Module de Young : {elastic_tensor.y_mod:.1f} GPa")

Ordre magnétique :

from pymatgen.transformations.advanced_transformations import MagOrderingTransformation

# Énumérer les ordres magnétiques
trans = MagOrderingTransformation({"Fe": 5.0})
mag_structs = trans.apply_transformation(struct, return_ranked_list=True)

# Obtenir la structure magnétique avec l'énergie la plus basse
lowest_energy_struct = mag_structs[0]['structure']

Référence : Voir references/analysis_modules.md pour la documentation exhaustive du module d'analyse.

Ressources intégrées

Scripts (scripts/)

Scripts Python exécutables pour les tâches courantes :

  • structure_converter.py : Convertir entre des formats de fichiers de structures

    • Supporte la conversion par lot et la détection automatique du format
    • Utilisation : python scripts/structure_converter.py POSCAR structure.cif

  • structure_analyzer.py : Analyse exhaustive de structures

    • Symétrie, coordination, paramètres de réseau, matrice de distance
    • Utilisation : python scripts/structure_analyzer.py structure.cif --symmetry --neighbors

  • phase_diagram_generator.py : Générer des diagrammes de phase à partir du Materials Project

    • Analyse de stabilité et propriétés thermodynamiques
    • Utilisation : python scripts/phase_diagram_generator.py Li-Fe-O --analyze "LiFeO2"

Tous les scripts incluent une aide détaillée : python scripts/script_name.py --help

Références (references/)

Documentation exhaustive chargée dans le contexte au besoin :

  • core_classes.md : Classes Element, Structure, Lattice, Molecule, Composition
  • io_formats.md : Support des formats de fichiers et intégration de codes (VASP, Gaussian, etc.)
  • analysis_modules.md : Diagrammes de phase, surfaces, structure électronique, symétrie
  • materials_project_api.md : Guide complet de l'API du Materials Project
  • transformations_workflows.md : Framework des transformations et workflows courants

Chargez les références quand des informations détaillées sur des modules ou workflows spécifiques sont nécessaires.

Workflows courants

Génération de structures haut débit

from pymatgen.transformations.standard_transformations import SubstitutionTransformation
from pymatgen.io.vasp.sets import MPRelaxSet

# Générer des structures dopées
base_struct = Structure.from_file("POSCAR")
dopants = ["Mn", "Co", "Ni", "Cu"]

for dopant in dopants:
    trans = SubstitutionTransformation({"Fe": dopant})
    doped_struct = trans.apply_transformation(base_struct)

    # Générer les entrées VASP
    vasp_input = MPRelaxSet(doped_struct)
    vasp_input.write_input(f"./calcs/Fe_{dopant}")

Workflow de calcul de structure de bandes

# 1. Relaxation
relax = MPRelaxSet(struct)
relax.write_input("./1_relax")

# 2. Statique (après relaxation)
relaxed = Structure.from_file("1_relax/CONTCAR")
static = MPStaticSet(relaxed)
static.write_input("./2_static")

# 3. Structure de bandes (non auto-cohérente)
nscf = MPNonSCFSet(relaxed, mode="line")
nscf.write_input("./3_bandstructure")

# 4. Analyse
from pymatgen.io.vasp import Vasprun
vasprun = Vasprun("3_bandstructure/vasprun.xml")
bs = vasprun.get_band_structure()
bs.get_band_gap()

Calcul d'énergie de surface

# 1. Obtenir l'énergie du bulk
bulk_vasprun = Vasprun("bulk/vasprun.xml")
bulk_E_per_atom = bulk_vasprun.final_energy / len(bulk)

# 2. Générer et calculer les feuillets
slabgen = SlabGenerator(bulk, (1,1,1), 10, 15)
slab = slabgen.get_slabs()[0]

MPRelaxSet(slab).write_input("./slab_calc")

# 3. Calculer l'énergie de surface (après le calcul)
slab_vasprun = Vasprun("slab_calc/vasprun.xml")
E_surf = (slab_vasprun.final_energy - len(slab) * bulk_E_per_atom) / (2 * slab.surface_area)
E_surf *= 16.021766  # Convertir eV/Ų en J/m²

Plus de workflows : Voir references/transformations_workflows.md pour 10 exemples de workflows détaillés.

Bonnes pratiques

Manipulation de structures

  1. Utiliser la détection automatique du format : Structure.from_file() gère la plupart des formats
  2. Préférer les structures immuables : Utiliser IStructure quand la structure ne doit pas changer
  3. Vérifier la symétrie : Utiliser SpacegroupAnalyzer pour réduire à la cellule primitive
  4. Valider les structures : Vérifier les atomes qui se chevauchent ou les longueurs de liaison déraisonnables

Entrée/sortie de fichiers

  1. Utiliser les méthodes pratiques : from_file() et to() sont préférés
  2. Spécifier les formats explicitement : Quand la détection automatique échoue
  3. Gérer les exceptions : Envelopper l'entrée/sortie de fichiers dans des blocs try-except
  4. Utiliser la sérialisation : as_dict()/from_dict() pour le stockage en toute sécurité de version

API du Materials Project

  1. Utiliser le gestionnaire de contexte : Toujours utiliser with MPRester() as mpr:
  2. Requêtes par lot : Demander plusieurs éléments à la fois
  3. Mettre en cache les résultats : Enregistrer les données fréquemment utilisées localement
  4. Filtrer efficacement : Utiliser les filtres de propriétés pour réduire le transfert de données

Workflows de calcul

  1. Utiliser les ensembles d'entrée : Préférer MPRelaxSet, MPStaticSet à la configuration manuelle de INCAR
  2. Vérifier la convergence : Toujours vérifier que les calculs ont convergé
  3. Suivre les transformations : Utiliser TransformedStructure pour la traçabilité
  4. Organiser les calculs : Utiliser des structures de répertoires claires

Performance

  1. Réduire la symétrie : Utiliser les cellules primitives si possible
  2. Limiter les recherches de voisins : Spécifier des rayons de coupure raisonnables
  3. Utiliser les méthodes appropriées : Différents outils d'analyse ont différents compromis vitesse/précision
  4. Paralléliser si possible : De nombreuses opérations peuvent être parallélisées

Unités et conventions

Pymatgen utilise les unités atomiques partout :

  • Longueurs : Angströms (Å)
  • Énergies : Électronvolts (eV)
  • Angles : Degrés (°)
  • Moments magnétiques : Magnétons de Bohr (μB)
  • Temps : Femtosecondes (fs)

Convertir les unités en utilisant pymatgen.core.units au besoin.

Intégration avec d'autres outils

Pymatgen s'intègre parfaitement avec :

  • ASE (Atomic Simulation Environment)
  • Phonopy (calculs de phonons)
  • BoltzTraP (propriétés de transport)
  • Atomate/Fireworks (gestion de workflows)
  • AiiDA (suivi de traçabilité)
  • Zeo++ (analyse de pores)
  • OpenBabel (conversion de molécules)

Dépannage

Erreurs d'importation : Installer les dépendances manquantes

uv pip install pymatgen[analysis,vis]

Clé API non trouvée : Définir la variable d'environnement MP_API_KEY

export MP_API_KEY="your_key_here"

Échecs de lecture de structures : Vérifier le format et la syntaxe du fichier

# Essayer une spécification de format explicite
struct = Structure.from_file("file.txt", fmt="cif")

L'analyse de symétrie échoue : La structure peut avoir des problèmes de précision numérique

# Augmenter la tolérance
from pymatgen.symmetry.analyzer import SpacegroupAnalyzer
sga = SpacegroupAnalyzer(struct, symprec=0.1)

Ressources supplémentaires

Notes de version

Cette compétence est conçue pour pymatgen 2024.x et ultérieur. Pour l'API du Materials Project, utiliser le package mp-api (distinct de l'ancien pymatgen.ext.matproj).

Exigences :

  • Python 3.10 ou supérieur
  • pymatgen >= 2023.x
  • mp-api (pour l'accès au Materials Project)

Skills similaires

hf-cli
huggingface / skills

Gérer dépôts, fichiers et authentification sur le Hub Hugging Face via CLI.

10 626
exploratory-data-analysis
mkurman / zorai

Analyser automatiquement des fichiers scientifiques et générer des rapports EDA détaillés.

309
rowan
mkurman / zorai

Modéliser des molécules et orchestrer des workflows de chimie médicinale dans le cloud.

309
foldseek-structural-search
mkurman / zorai

Rechercher des protéines structurellement similaires via Foldseek à partir d'un fichier 3D.

309
phoenix-cli
github / awesome-copilot

Inspecter traces, spans, sessions et datasets d'agents IA via une CLI Phoenix.

34 530