¿Qué hace pymatgen?
Utilice pymatgen para trabajar de forma explícita y preservando la procedencia con composiciones, moléculas, estructuras periódicas, entradas computacionales, simetría, diagramas de fase, estructuras electrónicas y archivos de códigos de estructura electrónica. Trate cada análisis, conversión, asignación de simetría, transformación y resultado de base de datos como dependiente del método y de los parámetros.
La licencia MIT del frontmatter cubre esta skill. pymatgen y pymatgen-core tienen licencia MIT; mp-api declara BSD-3-Clause-LBNL. Los datos de Materials Project generalmente tienen licencia CC BY 4.0, mientras que los datos aportados siguen siendo propiedad de sus contribuyentes. Verifique los términos exactos del artefacto y los datos antes de redistribuir.
Instantánea verificada (2026-07-23)
pymatgen==2026.5.4es la última versión estable del paquete envolvente (2026-05-04). Los metadatos del paquete requieren Python 3.11+ y requieren directamentepymatgen-core>=2026.4.16.pymatgen-core==2026.7.16es la última versión estable del núcleo (2026-07-16). Ahora contiene los objetos principales, las operaciones de simetría/reticulado y la capa de E/S, todo bajo el espacio de nombrespymatgen.*existente.mp-api==0.46.4es el último cliente estable de Materials Project (2026-06-15), requiere Python 3.11+ y depende depymatgen>2024.2.20.- El sitio actual de la API está construido a partir de la documentación del núcleo 2026.7.16. Fijar ambas distribuciones evita que
pymatgen==2026.5.4se resuelva silenciosamente a un núcleo futuro diferente. - Pymatgen utiliza versiones basadas en fechas. PyPI representa la fecha con puntos; no infiera compatibilidad semántica de versiones a partir de los números.
Cree un bloqueo de proyecto para reproducibilidad:
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
Para un entorno desechable y revisado:
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"
Las fijaciones directas no congelan todas las ruedas transitivas. Conserve uv.lock, la plataforma, la versión de Python, las versiones de los paquetes y los hashes de los artefactos.
Flujo de trabajo requerido
- Indique si el objeto es una
Moleculeno periódica o unaStructureperiódica; registre la red y las condiciones de contorno periódicas. - Indique las unidades. Pymatgen usa comúnmente Å, grados, eV, eV/átomo, amu y g/cm³, pero el contrato documentado de cada API es autoritativo.
- Indique el modo de coordenadas. Las coordenadas de
Structureson fraccionales a menos quecoords_are_cartesian=True; las coordenadas deMoleculeson cartesianas. - Inspeccione cada advertencia del analizador. Para CIF, conserve las advertencias de ocupación, fusión de sitios, estequiometría y corrección; no acepte correcciones silenciosamente.
- Reporte el desorden/ocupaciones parciales y la decoración de estados de oxidación. Nunca adivine estados de oxidación implícitamente.
- Ejecute la validación antes del análisis de simetría, vecinos, transformación, conversión o análisis termodinámico.
- Varíe las tolerancias de simetría e informe
symprecen Å yangle_toleranceen grados con cada asignación. - Trate las transformaciones como nuevos artefactos. Conserve la entrada, los parámetros, las versiones de software, las advertencias y las sumas de verificación padre/hijo.
- Antes de la conversión, identifique la pérdida de representación. Escriba solo en una nueva ruta y verifique mediante ida y vuelta las propiedades científicamente relevantes.
- Construya diagramas de fase solo a partir de energías totales compatibles y esquemas de corrección. Una envolvente calculada es condicional con respecto al conjunto de entradas suministrado.
- Mantenga todo el acceso a la base de datos desactivado por defecto. Divulgue el punto final, los filtros, los campos, el límite de resultados, el comportamiento de la caché, la salida, la licencia y la cita antes de un paso de ejecución explícito.
- Conserve un manifiesto de artefactos. Nunca use pickle ni cargue un gráfico de objetos general no confiable; use JSON validado por esquema y constructores explícitos.
Objetos principales
Use las importaciones públicas de conveniencia:
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, 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 y Molecule son mutables; use IStructure/IMolecule o una copia explícita cuando la mutación comprometa la procedencia. Consulte clases principales.
Carga segura de estructuras locales
Prefiera el validador incluido, que captura las advertencias de CIF y Python e informa unidades, ocupación, desorden, estados de oxidación, periodicidad, modo de coordenadas y distancias mínimas:
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
Para trabajo directo con CIF, use el método actual del analizador e inspeccione ambos canales de advertencia:
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]
No analice archivos no confiables en un proceso privilegiado. Una vulnerabilidad crítica de ejecución de código malicioso en CIF afectó a pymatgen hasta la versión 2024.2.8 y se corrigió en 2024.2.20; la versión fijada es más reciente, pero los analizadores aún procesan entradas controladas por un atacante. Use aislamiento y límites de CPU/RAM/disco/tiempo.
Simetría
La asignación del grupo espacial depende de las tolerancias y la calidad de la estructura:
from pymatgen.symmetry.analyzer import SpacegroupAnalyzer
analyzer = SpacegroupAnalyzer(
structure,
symprec=0.01, # Å
angle_tolerance=5.0, # grados
)
symbol = analyzer.get_space_group_symbol()
number = analyzer.get_space_group_number()
La canalización de Materials Project usa comúnmente symprec=0.1 Å, mientras que el valor predeterminado documentado de pymatgen es 0.01 Å; estos pueden producir asignaciones diferentes. Genere un informe de sensibilidad en lugar de cambiar la tolerancia hasta que aparezca una respuesta preferida:
python scripts/symmetry_sensitivity_report.py structure.cif \
--symprec 0.001,0.01,0.1 --angle-tolerance 1,5
Consulte módulos de análisis.
Conversión y E/S de analizador/escritor
Planifique primero; el planificador no abre archivos ni importa pymatgen:
python scripts/io_conversion_plan.py \
--input input.cif --input-format cif \
--output POSCAR.new --output-format poscar \
--periodic --coordinate-mode direct
Luego convierta a una nueva ruta con reconocimiento explícito de pérdida:
python scripts/structure_converter.py input.cif POSCAR.new \
--output-format poscar --coordinate-mode direct --allow-lossy \
--acknowledge-parser-warnings
CIF, POSCAR, XYZ y JSON no conservan las mismas semánticas. Verifique la red, la periodicidad, el modo de coordenadas, el orden de las especies, la dinámica selectiva, las propiedades del sitio, los estados de oxidación, las etiquetas y el desorden después de cada conversión. Consulte formatos de E/S.
Transformaciones y procedencia
Transforme una copia y conserve el historial:
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
Las transformaciones de ordenamiento, dopaje, losa y magnéticas de uno a muchos pueden expandirse combinatoriamente o invocar ejecutables opcionales. Acote los candidatos, sitios, tamaño de supercelda, tiempo de ejecución y número de salidas. Consulte transformaciones y flujos de trabajo.
Diagramas de fase locales
El generador incluido funciona sin conexión y solo acepta un esquema JSON estricto con energía total en eV por entrada y procedencia:
{
"schema_version": "1.0",
"energy_unit": "eV",
"energy_basis": "total_per_entry",
"provenance": {
"source": "cálculos locales revisados",
"method": "un esquema de energía/corrección compatible"
},
"entries": [
{
"entry_id": "local-Li",
"composition": "Li",
"energy_eV": -1.0,
"provenance": {"source": "manifiesto de cálculo sha256:..."}
}
]
}
python scripts/phase_diagram_generator.py entries.json --analyze Li2O
Deben estar presentes los puntos finales elementales y todas las fases competidoras. No mezcle energías sin procesar de diferentes funcionales, pseudopotenciales, estados magnéticos o convenciones de corrección. El estado calculado en la envolvente no es estabilidad experimental.
Estructuras de bandas, DOS, VASP y Q-Chem
Analice solo los datos necesarios:
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
Los valores propios proyectados pueden requerir una memoria extrema. Verifique la convergencia, la trayectoria k, la configuración de espín/SOC, las convenciones del nivel de Fermi, el ensanchamiento y la base de proyección antes de interpretar las brechas o la DOS. Un análisis exitoso no es un cálculo convergido.
Las interfaces actuales de Q-Chem son pymatgen.io.qchem.inputs.QCInput y 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 escribe entradas y analiza salidas; no otorga una licencia de VASP o Q-Chem ni establece la validez del método. Los archivos POTCAR tienen licencia de VASP y no son distribuidos por pymatgen. Nunca los redistribuya ni escanee directorios no relacionados para encontrarlos. Herramientas opcionales como enumlib, Bader, packmol, ffmpeg y Zeo++ son ejecutables nativos/externos: revise la procedencia, licencias, argv, directorio de trabajo y límites de recursos antes de una invocación explícita separada.
Materials Project: planifique antes de la red
Use solo:
from mp_api.client import MPRester
El cliente lee MP_API_KEY cuando se construye. Proporcione solo esa variable de entorno nombrada a través del shell del usuario o del administrador de secretos. No acepte la clave como un argumento de CLI, recorra archivos .env, vuelque variables de entorno ni imprima datos de excepción sin redacción.
La planificación en seco es la opción predeterminada:
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
Solo --execute permite una consulta de resumen acotada y requiere una nueva salida:
python scripts/mp_query.py \
--material-id mp-149 \
--fields formula_pretty,structure,origins,last_updated \
--limit 1 --output mp-149.json --execute
La CLI establece num_chunks=1, requiere campos y filtros explícitos, limita los resultados, no implementa una caché de resultados implícita y nunca sobrescribe la salida. La inicialización de MPRester también realiza solicitudes de metadatos de compatibilidad/latido; el plan divulga estas, deshabilita el agente de usuario de detalles de la plataforma y el registro de notificación de versión de base de datos local, y registra la versión de base de datos devuelta. El flujo de trabajo de resumen no solicita descargas completas de la caché del conjunto de datos. mp-api 0.46.4 reintenta HTTP 429/502/504 según su propia política configurada y respeta Retry-After; no invente una cuota de servicio numérica ni agregue un bucle de reintento ilimitado.
Los valores principales de Materials Project son datos computacionales dependientes del método, no una verdad experimental. PBE comúnmente sobreestima los parámetros de red y subestima sistemáticamente las brechas de banda; los valores agregados pueden cambiar entre versiones de la base de datos. Conserve la hora de recuperación, la consulta, los campos, los orígenes del material/tarea, la versión de la base de datos cuando esté disponible, las versiones del cliente, la atribución CC BY y las citas canónicas más las citas específicas de la propiedad. Consulte API de Materials Project.
CLI incluidos
Todos los CLI tienen --help sin dependencias, importaciones científicas diferidas, JSON acotado y ninguna red implícita:
scripts/composition_structure_validator.py: comprobaciones estrictas de composición/estructura; la adivinación opcional del estado de oxidación es explícita y acotada.scripts/structure_analyzer.py: informe acotado de red, sitios, simetría, distancia y CrystalNN opcional.scripts/symmetry_sensitivity_report.py: grupos espaciales de cuadrícula de tolerancia.scripts/io_conversion_plan.py: plan de pérdida de representación sin dependencias.scripts/structure_converter.py: conversión de un archivo a una nueva ruta.scripts/phase_diagram_generator.py: envolvente estricta de entradas computacionales locales.scripts/mp_query.py: plan de consulta de MP en seco y cliente acotado opt-in.scripts/artifact_manifest.py: sumas de verificación, versiones, fuentes y procedencia.
Use:
python scripts/artifact_manifest.py \
--artifact input.cif --artifact analysis.json \
--workflow "sensibilidad de simetría local" --output manifest.json
Referencias
- Clases principales
- Formatos de E/S, VASP y Q-Chem
- Análisis, simetría, diagramas de fase, bandas y DOS
- Transformaciones y flujos de trabajo
- API de Materials Project, procedencia, licencia y límites