Materials science toolkit. Crystal structures (CIF, POSCAR), phase diagrams, band structure, DOS, Materials Project integration, format conversion, for computational materials science.
SKILL.md
pymatgen
Use pymatgen for explicit, provenance-preserving work with compositions,
molecules, periodic structures, computed entries, symmetry, phase diagrams,
electronic structures, and electronic-structure-code files. Treat every parse,
conversion, symmetry assignment, transformation, and database result as
method- and parameter-dependent.
The MIT frontmatter license covers this skill. pymatgen and
pymatgen-core are MIT; mp-api declares BSD-3-Clause-LBNL. Materials Project
data is generally CC BY 4.0, while contributed data remains owned by its
contributors. Check the exact artifact and data terms before redistribution.
Verified snapshot (2026-07-23)
pymatgen==2026.5.4 is the latest stable wrapper release (2026-05-04).
Package metadata requires Python 3.11+ and directly requires
pymatgen-core>=2026.4.16.
pymatgen-core==2026.7.16 is the latest stable core release (2026-07-16).
It now contains core objects, symmetry/lattice operations, and the I/O layer,
all under the existing pymatgen.* namespace.
mp-api==0.46.4 is the latest stable Materials Project client
(2026-06-15), requires Python 3.11+, and depends on
pymatgen>2024.2.20.
The current API site is built from 2026.7.16 core documentation. Pinning both
distributions prevents pymatgen==2026.5.4 from silently resolving to a
different future core.
Pymatgen uses date-based versions. PyPI renders the date with dots; do not
infer semantic-version compatibility from the numbers.
Direct pins do not freeze all transitive wheels. Preserve uv.lock, platform,
Python version, package versions, and artifact hashes.
Required workflow
State whether the object is a non-periodic Molecule or periodic
Structure; record lattice and periodic boundary conditions.
State units. Pymatgen commonly uses Å, degrees, eV, eV/atom, amu, and
g/cm³, but each API's documented contract is authoritative.
State coordinate mode. Structure coordinates are fractional unless
coords_are_cartesian=True; Molecule coordinates are Cartesian.
Inspect every parser warning. For CIF, preserve occupancy, site-merging,
stoichiometry, and correction warnings; do not silently accept fixes.
Report disorder/partial occupancies and oxidation-state decoration. Never
guess oxidation states implicitly.
Run validation before symmetry, neighbor, transformation, conversion, or
thermodynamic analysis.
Sweep symmetry tolerances and report symprec in Å and
angle_tolerance in degrees with every assignment.
Treat transformations as new artifacts. Preserve the input, parameters,
software versions, warnings, and parent/child checksums.
Before conversion, identify representation loss. Write only to a new path
and round-trip-check scientifically relevant properties.
Build phase diagrams only from compatible total energies and correction
schemes. A computed hull is conditional on the supplied entry set.
Keep all database access off by default. Disclose endpoint, filters,
fields, result limit, cache behavior, output, license, and citation before
an explicit execution step.
Preserve an artifact manifest. Never use pickle or load an untrusted
general object graph; use schema-validated JSON and explicit constructors.
Structure and Molecule are mutable; use IStructure/IMolecule or an
explicit copy when mutation would compromise provenance. See
core classes.
Safe local structure intake
Prefer the bundled validator, which captures CIF and Python warnings and
reports units, occupancy, disorder, oxidation states, periodicity, coordinate
mode, and minimum distances:
For direct CIF work, use the current parser method and inspect both warning
channels:
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]
Do not parse untrusted files in a privileged process. A critical malicious-CIF
code-execution flaw affected pymatgen through 2024.2.8 and was fixed in
2024.2.20; the pinned release is newer, but parsers still process attacker
controlled input. Use isolation and CPU/RAM/disk/time limits.
Symmetry
Space-group assignment depends on tolerances and structure quality:
from pymatgen.symmetry.analyzer import SpacegroupAnalyzer
analyzer = SpacegroupAnalyzer(
structure,
symprec=0.01, # Å
angle_tolerance=5.0, # degrees
)
symbol = analyzer.get_space_group_symbol()
number = analyzer.get_space_group_number()
The Materials Project pipeline commonly uses symprec=0.1 Å, while pymatgen's
documented default is 0.01 Å; these can produce different assignments.
Generate a sensitivity report instead of changing tolerance until a preferred
answer appears:
CIF, POSCAR, XYZ, and JSON do not preserve the same semantics. Check lattice,
periodicity, coordinate mode, species ordering, selective dynamics, site
properties, oxidation states, labels, and disorder after every conversion.
See I/O formats.
Transformations and provenance
Transform a copy and preserve history:
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
One-to-many ordering, doping, slab, and magnetic transformations can expand
combinatorially or invoke optional executables. Bound candidates, sites,
supercell size, runtime, and output count. See
transformations and workflows.
Local phase diagrams
The bundled generator is offline and accepts only a strict JSON schema with
total eV per entry and provenance:
Elemental endpoints and all competing phases must be present. Do not mix raw
energies from different functionals, pseudopotentials, magnetic states, or
correction conventions. Computed on-hull status is not experimental stability.
Projected eigenvalues can require extreme memory. Verify convergence, k-path,
spin/SOC settings, Fermi-level conventions, smearing, and projection basis
before interpreting gaps or DOS. A parser success is not a converged
calculation.
Current Q-Chem interfaces are pymatgen.io.qchem.inputs.QCInput and
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 writes inputs and parses outputs; it does not grant a VASP or Q-Chem
license or establish method validity. POTCAR files are VASP-licensed and are
not distributed by pymatgen. Never redistribute them or scan unrelated
directories for them. Optional tools such as enumlib, Bader, packmol, ffmpeg,
and Zeo++ are native/external executables: review provenance, licenses, argv,
working directory, and resource limits before a separate explicit invocation.
Materials Project: plan before network
Use only:
from mp_api.client import MPRester
The client reads MP_API_KEY when constructed. Supply only that named
environment variable through the user's shell or secret manager. Do not accept
the key as a CLI argument, traverse .env files, dump environment variables,
or print exception data without redaction.
The CLI sets num_chunks=1, requires explicit fields and filters, caps results,
does not implement an implicit result cache, and never overwrites output.
MPRester initialization also performs compatibility/heartbeat metadata
requests; the plan discloses these, disables the platform-detail user agent and
local database-version notification log, and records the returned database
version. The summary workflow does not request full-dataset cache downloads.
mp-api 0.46.4 retries HTTP 429/502/504 according to its own configured policy
and respects Retry-After; do not invent a numeric service quota or add an
unbounded retry loop.
Materials Project core values are computed, method-dependent data—not
experimental truth. PBE commonly overestimates lattice parameters and
systematically underestimates band gaps; aggregated values can change across
database releases. Preserve retrieval time, query, fields, material/task
origins, database release when available, client versions, CC BY attribution,
and the canonical plus property-specific citations. See
Materials Project API.
Bundled CLIs
All CLIs have dependency-free --help, lazy scientific imports, bounded JSON,
and no implicit network:
scripts/composition_structure_validator.py — strict composition/structure
checks; optional oxidation-state guessing is explicit and bounded.
