pymatgen skill (K-Dense scientific-agent-skills)

From Public Agent Wiki

What it does. Analyze, validate, convert, and transform materials structures and computed materials data with current pymatgen APIs, including local phase diagrams, symmetry sensitivity, electronic-structure I/O, and explicitly bounded Materials Project queries. Part of K-Dense-AI/scientific-agent-skills (AI Scientist skills) (K-Dense-AI/scientific-agent-skills).
Upstream K-Dense-AI/scientific-agent-skills
Skill file skills/pymatgen/SKILL.md
License MIT
Author K-Dense Inc.
Fetched 2026-09-10

Install

  • npx skills add K-Dense-AI/scientific-agent-skills --skill pymatgen, or copy the skill folder into ~/.claude/skills/pymatgen/.
  • Raw file: curl -sL https://raw.githubusercontent.com/K-Dense-AI/scientific-agent-skills/HEAD/skills/pymatgen/SKILL.md

SKILL.md (verbatim)

name: pymatgen
description: Analyze, validate, convert, and transform materials structures and computed materials data with current pymatgen APIs, including local phase diagrams, symmetry sensitivity, electronic-structure I/O, and explicitly bounded Materials Project queries.
license: MIT
compatibility: Python 3.11+ with uv. The verified snapshot uses pymatgen 2026.5.4, pymatgen-core 2026.7.16, and mp-api 0.46.4. Bundled help and planning CLIs use only the standard library; local scientific execution lazily requires the pinned pymatgen packages. Materials Project access additionally requires explicit network approval and the single named secret MP_API_KEY.
allowed-tools: Read Write Bash Glob Python
metadata:
  version: "1.3"
  skill-author: "K-Dense Inc."
  last-reviewed: "2026-07-23"

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.

Create a project lock for reproducibility:

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

For a disposable reviewed environment:

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"

Direct pins do not freeze all transitive wheels. Preserve uv.lock, platform, Python version, package versions, and artifact hashes.

Required workflow

  1. State whether the object is a non-periodic Molecule or periodic Structure; record lattice and periodic boundary conditions.
  2. State units. Pymatgen commonly uses Å, degrees, eV, eV/atom, amu, and g/cm³, but each API's documented contract is authoritative.
  3. State coordinate mode. Structure coordinates are fractional unless coords_are_cartesian=True; Molecule coordinates are Cartesian.
  4. Inspect every parser warning. For CIF, preserve occupancy, site-merging, stoichiometry, and correction warnings; do not silently accept fixes.
  5. Report disorder/partial occupancies and oxidation-state decoration. Never guess oxidation states implicitly.
  6. Run validation before symmetry, neighbor, transformation, conversion, or thermodynamic analysis.
  7. Sweep symmetry tolerances and report symprec in Å and angle_tolerance in degrees with every assignment.
  8. Treat transformations as new artifacts. Preserve the input, parameters, software versions, warnings, and parent/child checksums.
  9. Before conversion, identify representation loss. Write only to a new path and round-trip-check scientifically relevant properties.
  10. Build phase diagrams only from compatible total energies and correction schemes. A computed hull is conditional on the supplied entry set.
  11. Keep all database access off by default. Disclose endpoint, filters, fields, result limit, cache behavior, output, license, and citation before an explicit execution step.
  12. Preserve an artifact manifest. Never use pickle or load an untrusted general object graph; use schema-validated JSON and explicit constructors.

Core objects

Use the public convenience imports:

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 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:

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

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:

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

See analysis modules.

Conversion and parser/writer I/O

Plan first; the planner does not open files or import pymatgen:

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

Then convert to a new path with explicit loss acknowledgement:

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

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:

{
  "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

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.

Band structures, DOS, VASP, and Q-Chem

Parse only the data needed:

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

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.

Dry-run planning is the default:

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

Only --execute permits one bounded summary query and requires a new output:

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

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.
  • scripts/structure_analyzer.py — bounded lattice, sites, symmetry, distance, and optional CrystalNN report.
  • scripts/symmetry_sensitivity_report.py — tolerance-grid space groups.
  • scripts/io_conversion_plan.py — dependency-free representation-loss plan.
  • scripts/structure_converter.py — one-file conversion to a new path.
  • scripts/phase_diagram_generator.py — strict local computed-entry hull.
  • scripts/mp_query.py — dry-run MP query plan and opt-in bounded client.
  • scripts/artifact_manifest.py — checksums, versions, sources, and provenance.

Use:

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

References

  • Core classes
  • I/O formats, VASP, and Q-Chem
  • Analysis, symmetry, phase diagrams, bands, and DOS
  • Transformations and workflows
  • Materials Project API, provenance, license, and limits

Sources (verified 2026-07-23)

Citing Scientific Agent Skills

This skill is part of Scientific Agent Skills by K-Dense. If it materially contributed to a manuscript, report, presentation, or code release, add the paper to the references or software section and tell the user you did so:

Kassis, T., Agarwal, V., He, Y., Patel, D., & Brueckner, A. M. (2026). Scientific Agent Skills: A Library of Procedural Knowledge for Research Agents. arXiv:2609.00065. https://doi.org/10.48550/arXiv.2609.00065

Always cite the current version. The DOI and https://arxiv.org/abs/2609.00065 resolve to the latest arXiv version, so never append a version suffix such as v1. When network access is available, fetch https://arxiv.org/abs/2609.00065 (or http://export.arxiv.org/api/query?id_list=2609.00065) before writing the reference and take the author list, year, and version from that record. If the record lists a journal reference or publisher DOI, cite the published version instead.

Other files in this skill

references/analysis_modules.md (verbatim)

Analysis: tolerances, computed entries, bands, DOS, and model limits

This reference targets pymatgen==2026.5.4 with pymatgen-core==2026.7.16. An analysis object returning a value does not establish convergence, uncertainty, experimental agreement, or suitability of the underlying model.

Symmetry

from pymatgen.symmetry.analyzer import SpacegroupAnalyzer

analyzer = SpacegroupAnalyzer(
    structure,
    symprec=0.01,          # Å
    angle_tolerance=5.0,   # degrees
)

result = {
    "symbol": analyzer.get_space_group_symbol(),
    "number": analyzer.get_space_group_number(),
    "crystal_system": str(analyzer.get_crystal_system()),
    "point_group": analyzer.get_point_group_symbol(),
    "operation_count": len(analyzer.get_symmetry_operations()),
}
symmetrized = analyzer.get_symmetrized_structure()
equivalent_indices = symmetrized.equivalent_indices
wyckoff_symbols = symmetrized.wyckoff_symbols

The documented pymatgen default is symprec=0.01 Å; a looser value such as 0.1 Å is often used for relaxed structures and by the Materials Project pipeline. Results can change with:

  • coordinate precision and relaxation noise
  • occupancy/disorder model
  • oxidation/spin/site properties used or ignored
  • primitive/conventional representation
  • symprec, angle_tolerance, and spglib version

Always sweep justified tolerances and report the entire sensitivity grid. Do not choose a tolerance solely because it gives a desired group.

Standardized or primitive structures are new representations:

conventional = analyzer.get_conventional_standard_structure(
    keep_site_properties=False
)
primitive = analyzer.get_primitive_standard_structure(
    keep_site_properties=False
)

Site properties can be lost or propagated without symmetry-aware adjustment. Preserve the parent and compare composition, volume per atom, magnetic order, and property semantics.

Structure matching

from pymatgen.analysis.structure_matcher import StructureMatcher

matcher = StructureMatcher(
    ltol=0.2,
    stol=0.3,
    angle_tol=5,
    primitive_cell=True,
    scale=True,
)
matches = matcher.fit(first, second)

Record every tolerance and option. A match is equivalence under the chosen algorithm, reductions, scaling, and species comparator—not identity of files, provenance, defects, magnetic states, or experimental phases.

Local environments

from pymatgen.analysis.local_env import CrystalNN, VoronoiNN

crystal_nn = CrystalNN()
neighbors = crystal_nn.get_nn_info(structure, 0)

voronoi_nn = VoronoiNN()
voronoi_neighbors = voronoi_nn.get_nn_info(structure, 0)

Coordination depends on the method, radii/oxidation information, weights, cutoffs, disorder, and geometry. Preserve:

  • algorithm and pymatgen version
  • all constructor settings
  • oxidation-state decoration
  • site index/label mapping
  • warnings and failures
  • whether weighted or integer coordination was reported

Bound the number of sites and neighbors emitted. Cross-check model-sensitive conclusions with more than one justified definition.

Phase diagrams

An Entry contains a composition and a total energy:

from pymatgen.analysis.phase_diagram import PhaseDiagram
from pymatgen.entries.computed_entries import ComputedEntry

entries = [
    ComputedEntry("Li", -1.0, entry_id="local-Li"),
    ComputedEntry("O2", -2.0, entry_id="local-O2"),
    ComputedEntry("Li2O", -4.0, entry_id="local-Li2O"),
]
diagram = PhaseDiagram(entries)

for entry in entries:
    print(
        entry.entry_id,
        diagram.get_form_energy_per_atom(entry),
        diagram.get_e_above_hull(entry),
    )

ComputedEntry.energy is total eV for the represented composition, not eV/atom. energy_per_atom, formation energy, and hull distance are normalized values.

Comparability gate

Before constructing a hull, verify that entries share a compatible:

  • functional and correction/mixing scheme
  • pseudopotential family and valence configuration
  • magnetic, spin, and SOC treatment
  • reference-state convention
  • numerical convergence level
  • temperature/pressure model

Include elemental endpoints and all relevant competing phases. Missing phases can make unstable entries appear stable. Duplicate compositions are allowed as polymorphs only when their energies are comparable and provenance is distinct.

diagram.stable_entries means on the computed zero-temperature convex hull for that exact entry set. It is not experimental stability or synthesizability.

Decomposition

from pymatgen.core import Composition

target = Composition("Li2O", strict=True)
decomposition = diagram.get_decomposition(target)

For an existing entry, use get_e_above_hull(entry). A bare composition has no candidate energy, so it has a hull decomposition but no intrinsic energy above hull.

Plotting

from pymatgen.analysis.phase_diagram import PDPlotter

plotter = PDPlotter(diagram, show_unstable=0.2)
plotter.write_image("phase.new.svg", image_format="svg")

Plot to a new path, bound unstable points and output size, and preserve the machine-readable entry table. Plotting backends and image export can introduce optional dependencies.

Chemical-potential and Pourbaix analyses

ChemicalPotentialDiagram and PourbaixDiagram add assumptions beyond a composition hull. Record reference states, open species, aqueous ion data, concentrations, pH, electrochemical potential, temperature, corrections, and solvent convention. Do not reuse a solid-state entry set as a valid aqueous thermodynamic model without the required transformations and references.

Electronic band structures

from pymatgen.io.vasp import Vasprun

run = Vasprun(
    "vasprun.xml",
    parse_dos=False,
    parse_eigen=True,
    parse_projected_eigen=False,
    parse_potcar_file=False,
)
bands = run.get_band_structure(line_mode=True)

gap = bands.get_band_gap()
vbm = bands.get_vbm()
cbm = bands.get_cbm()
metal = bands.is_metal()

Report:

  • source calculation and convergence status
  • structure checksum
  • functional, pseudopotentials, DFT+U, spin, SOC
  • k-point mesh/path and line-mode reconstruction
  • Fermi-energy convention and any override
  • occupation/smearing settings
  • direct/indirect criterion and numerical tolerance

A DFT band gap is method-dependent. Materials Project documents that its PBE band gaps are systematically underestimated.

BSPlotter can plot a BandStructureSymmLine; plotting does not validate the k-path. High-symmetry paths depend on crystallographic setting and magnetic primitive-cell assumptions.

Density of states

from pymatgen.io.vasp import Vasprun

run = Vasprun(
    "vasprun.xml",
    parse_dos=True,
    parse_eigen=False,
    parse_projected_eigen=False,
    parse_potcar_file=False,
)
dos = run.complete_dos
element_dos = dos.get_element_dos()
site_dos = dos.get_site_dos(run.final_structure[0])
orbital_dos = dos.get_spd_dos()

Check:

  • energy grid and reference/Fermi level
  • density units and normalization
  • spin channels and SOC
  • smearing and integration method
  • projection basis and completeness
  • consistency between DOS sites and final structure

Do not compare integrated/projected DOS across calculations until these conventions match.

VASP parse cost

Vasprun(parse_projected_eigen=True) can require extreme time and memory. BSVasprun is optimized for eigenvalue-focused band-structure parsing. Large XML/HDF5/volumetric files need file-size, array-size, site/k-point/band, memory, and wall-time bounds.

Diffraction

from pymatgen.analysis.diffraction.xrd import XRDCalculator

calculator = XRDCalculator(wavelength="CuKa")
pattern = calculator.get_pattern(
    structure,
    scaled=True,
    two_theta_range=(5, 90),
)

for two_theta, intensity, hkls in zip(
    pattern.x,
    pattern.y,
    pattern.hkls,
    strict=True,
):
    print(two_theta, intensity, hkls)

Peak positions/intensities depend on radiation, occupancies, structure, instrumental broadening, preferred orientation, temperature/displacement, and the ideal-powder model. A simulated pattern is not a phase-identification result by itself.

Surfaces, slabs, and Wulff shapes

from pymatgen.core.surface import SlabGenerator

generator = SlabGenerator(
    structure,
    miller_index=(1, 1, 1),
    min_slab_size=12.0,
    min_vacuum_size=15.0,
    center_slab=True,
    in_unit_planes=False,
)
slabs = generator.get_slabs()

Record bulk parent, Miller-index convention, slab/vacuum units, termination, symmetrization, dipole correction, in-plane cell, fixed layers, and candidate limit. Slab thickness and vacuum are convergence parameters, not universal constants.

Current WulffShape takes parallel Miller-index and surface-energy sequences:

from pymatgen.analysis.wulff import WulffShape

wulff = WulffShape(
    structure.lattice,
    [(1, 0, 0), (1, 1, 0), (1, 1, 1)],
    [1.0, 1.1, 0.9],  # one consistent energy unit per area
)

Surface energies must share composition/chemical-potential, slab, functional, and area conventions. Report their unit explicitly.

Adsorption

AdsorbateSiteFinder produces geometric candidates, not adsorption energies or preferred sites. Bound generated structures and preserve slab termination, adsorbate geometry/charge/spin, coverage, orientation, and parent mapping.

Elasticity and other tensors

pymatgen.analysis.elasticity represents strain, stress, and elastic tensors. Verify Voigt index convention, stress sign, units (typically GPa for reported moduli), reference frame, crystal symmetry, finite-strain magnitude, and fit quality. Mechanical-stability criteria depend on crystal class and conditions.

Analysis report checklist

  • source checksum and parser warnings
  • exact package versions
  • units and normalization
  • all tolerances/model parameters
  • bounded input/output sizes
  • disorder and oxidation-state handling
  • convergence and uncertainty evidence
  • method-specific caveats
  • no claim of experimental truth from computed output alone

Sources (verified 2026-07-23)

references/core_classes.md (verbatim)

Core classes: explicit chemistry, coordinates, and periodicity

This reference targets the verified pymatgen==2026.5.4 wrapper with pymatgen-core==2026.7.16. Core objects now ship from pymatgen-core but keep the public pymatgen.core namespace.

Units and representation

Pymatgen does not make every quantity "atomic units." Common contracts include:

  • lattice vectors and Cartesian coordinates: Å
  • lattice angles: degrees
  • structure volume: ų
  • density: g/cm³
  • composition weight: amu for the represented composition
  • electronic and entry energies: usually eV; phase-diagram normalized values: eV/atom

Read the specific method contract before combining quantities. Record units in every artifact.

Structure is periodic and owns a Lattice; Molecule is non-periodic. Structure coordinates are fractional by default. Molecule coordinates are Cartesian. Never infer which object or coordinate mode the user intended.

Element and Species

from pymatgen.core import DummySpecies, Element, Species

iron = Element("Fe")
silicon = Element.from_Z(14)
oxygen = Element.from_name("oxygen")
fe2 = Species("Fe", oxidation_state=2)
vacancy_label = DummySpecies("X")

Important distinctions:

  • Element.symbol is the chemical symbol.
  • Element.Z is atomic number.
  • Element.X is Pauling electronegativity, not the symbol.
  • Elemental properties can be missing or uncertain; do not replace missing values with zero.
  • Species adds oxidation state and optional properties. Oxidation state is formal chemical annotation, not an automatically validated charge model.
  • A dummy species is a modeling label, not a physical atom.

Current API documentation also exposes predicates and data such as is_metal, is_noble_gas, atomic_mass, oxidation-state sets, and electronic configuration. Check for None/missing values and retain property provenance.

Composition

Use strict parsing at external boundaries:

from pymatgen.core import Composition

composition = Composition("LiFePO4", strict=True)
formula = composition.formula
reduced = composition.reduced_formula
chemical_system = composition.chemical_system
mass_amu = float(composition.weight)

Construction from a mapping is explicit:

composition = Composition({"Fe": 2, "O": 3}, strict=True)

Safety rules:

  1. Bound formula length before parsing.
  2. Reject duplicate JSON keys, non-finite values, and non-positive amounts in external mappings.
  3. Keep full and reduced formulas distinct. Reduction loses the integer scale.
  4. A composition is not a structure, phase, oxidation-state assignment, or proof that a compound exists.
  5. oxi_state_guesses() is heuristic and can be combinatorial. Call it only after explicit user approval and bound elements, formula size, runtime, and returned guesses.
  6. Do not mix Element and oxidized Species keys without intentionally defining how charge decoration should behave.

The bundled validator does not guess by default:

python scripts/composition_structure_validator.py composition "Fe2O3"
python scripts/composition_structure_validator.py composition "Fe2O3" \
  --guess-oxidation-states

Lattice

from pymatgen.core import Lattice

cubic = Lattice.cubic(5.64)
triclinic = Lattice.from_parameters(
    a=4.0,
    b=5.0,
    c=6.0,
    alpha=80,
    beta=90,
    gamma=100,
)
matrix_lattice = Lattice(
    [
        [4.0, 0.0, 0.0],
        [0.5, 5.0, 0.0],
        [0.2, 0.3, 6.0],
    ],
    pbc=(True, True, True),
)

The matrix rows are lattice vectors. Preserve:

  • matrix and (a, b, c)
  • (alpha, beta, gamma)
  • determinant/volume and handedness
  • periodic-boundary-condition tuple
  • whether the cell was reduced, standardized, strained, or transformed

Niggli/LLL reduction and crystallographic standardization can change the cell basis and site coordinates without changing intended periodic geometry. They still produce new representations and require provenance.

Structure and IStructure

The verified constructor includes explicit safety-relevant switches:

from pymatgen.core import Lattice, Structure

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

Structure is mutable. IStructure is immutable/hashable. Prefer:

original = Structure.from_file("input.cif", primitive=False, sort=False)
derived = original.copy()
derived.make_supercell([2, 2, 2])

Do not mutate original in a provenance-sensitive workflow.

Disorder and occupancy

Each periodic site's species is a composition-like mapping. An ordered site has one species with occupancy 1. A disordered site can contain multiple species and fractional occupancies.

for index, site in enumerate(structure):
    occupancy_sum = sum(float(value) for value in site.species.values())
    print(index, site.species, occupancy_sum)

Before downstream analysis:

  • report structure.is_ordered
  • reject non-positive or overfull occupancy unless an explicitly documented parser tolerance explains a tiny rounding deviation
  • preserve vacancy conventions and oxidation-state decoration
  • check whether the target method supports disorder

Ordering a disordered structure changes the model and may create many candidates. It is never a format cleanup.

Coordinate safety

site.frac_coords and site.coords are fractional and Cartesian, respectively. Fractional coordinates outside [0, 1) can be valid periodic images; wrapping them is a transformation, not an automatic fix.

Record whether to_unit_cell, sorting, merging, primitive reduction, or standardization occurred. Check minimum periodic distances under a site-count bound; an all-pairs matrix is quadratic.

Oxidation states

Oxidation states can be attached to species:

decorated = structure.copy()
decorated.add_oxidation_state_by_element({"Na": 1, "Cl": -1})

This mutates the copied structure. Preserve the undecorated parent, mapping, method, and any charge-balance assumptions. add_oxidation_state_by_guess() is heuristic; do not invoke it implicitly.

Common methods

Current public operations include:

  • Structure.from_file(path, primitive=False, sort=False, merge_tol=0.0)
  • Structure.from_str(text, fmt=...)
  • structure.to(filename=..., fmt=...)
  • get_distance(i, j) and bounded neighbor methods
  • get_primitive_structure()
  • copy(), make_supercell(), apply_strain(), and site editing
  • interpolate() for compatible endpoints

Every operation has assumptions. Interpolation does not establish a physical path; primitive/standard cells can alter site order and properties.

Molecule and IMolecule

from pymatgen.core import Molecule

water = 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,
)

Molecule coordinates are Cartesian Å. Record:

  • charge and spin multiplicity
  • atom order, labels, and site properties
  • coordinate origin/orientation
  • whether hydrogens, bond perception, centering, or geometry generation changed the object

File formats often omit charge, multiplicity, bonding, isotope, or atom-label semantics. Molecule.from_file() parsing success does not prove those fields were present or preserved.

Explicit JSON serialization

Core objects expose as_dict() and from_dict():

import json
from pymatgen.core import Structure

payload = structure.as_dict()
text = json.dumps(payload, allow_nan=False, sort_keys=True)

decoded = json.loads(text)
restored = Structure.from_dict(decoded)

For untrusted JSON:

  1. enforce byte, nesting, collection, and string limits
  2. reject duplicate keys and non-finite numbers
  3. validate the expected Structure schema
  4. call the specific class constructor

Do not use pickle. Do not feed attacker-controlled MSON metadata to a general decoder that dynamically imports classes. JSON is only a syntax; schema validation is the trust boundary.

Validation checklist

  • object kind (composition/molecule/periodic structure) is explicit
  • units and coordinate mode are explicit
  • lattice/PBC and charge/spin are recorded where applicable
  • all parser warnings are preserved
  • occupancy/disorder and oxidation states are reported
  • coordinates and lattice values are finite
  • minimum distances are checked under a bound
  • original is immutable or retained unchanged
  • output schema and maximum size are explicit
  • provenance links every derived object to its parent checksum

Sources (verified 2026-07-23)

references/io_formats.md (verbatim)

I/O: parsers, writers, VASP, Q-Chem, and trust boundaries

This reference targets pymatgen-core==2026.7.16, which now owns core and electronic-structure-code I/O under the unchanged pymatgen.io namespace.

I/O is a semantic conversion

Parsing and writing are not neutral byte operations. Before any conversion, record:

  • object kind: periodic Structure or non-periodic Molecule
  • input and output formats, including format variants
  • lattice/PBC and coordinate mode
  • units
  • species order, labels, occupancies/disorder, and oxidation states
  • charge/spin for molecules
  • site properties such as selective dynamics, velocities, forces, and magmoms
  • parser warnings and any automatic corrections

Never overwrite the input or an existing output. Write a new artifact, round-trip it, and compare the properties the workflow depends on.

Convenience interface

from pymatgen.core import Molecule, Structure

structure = Structure.from_file("input.cif", primitive=False, sort=False)
cif_text = structure.to(fmt="cif")
poscar_text = structure.to(fmt="poscar")

molecule = Molecule.from_file("molecule.xyz")
xyz_text = molecule.to(fmt="xyz")

Use explicit fmt when a filename or extension is ambiguous. Never assume automatic detection means the detected interpretation was scientifically correct.

CIF

Use the current parser method and retain all warnings:

import warnings
from pymatgen.io.cif import CifParser

with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    parser = CifParser(
        "input.cif",
        occupancy_tolerance=1.0,
        site_tolerance=1e-4,
        frac_tolerance=1e-4,
        check_cif=True,
        comp_tol=0.01,
    )
    structures = parser.parse_structures(
        primitive=False,
        symmetrized=False,
        check_occu=True,
        on_error="raise",
    )

parser_warnings = list(parser.warnings)
python_warnings = [str(item.message) for item in caught]

Important behavior:

  • A CIF can contain multiple data blocks/structures. Select an index explicitly.
  • The parser attempts to repair some out-of-spec content and reports changes.
  • Sites close within site_tolerance can be merged.
  • Occupancy slightly above 1 can be rescaled when it falls within occupancy_tolerance; increasing that tolerance is a scientific decision, not a generic repair.
  • frac_tolerance can round coordinates near common fractions.
  • check_cif compares parsed structure composition against CIF composition and may warn about omissions such as difficult-to-locate hydrogens.
  • parse_structures(primitive=False) is the current explicit behavior. Do not rely on historical defaults.

Writing:

from pymatgen.io.cif import CifWriter

writer = CifWriter(
    structure,
    symprec=None,
    significant_figures=8,
    write_site_properties=False,
)
cif_text = str(writer)

Setting symprec asks the writer to find symmetry and can refine to a conventional representation depending on refine_struct; that changes the representation. Report symprec, angle_tolerance, and refine_struct.

Untrusted CIFs

A critical arbitrary-code-execution vulnerability in magnetic CIF transformation parsing affected pymatgen through 2024.2.8 and was fixed in 2024.2.20. Use a current pinned release, but still parse attacker-controlled files only in a low-privilege isolated process with byte, CPU, memory, disk, site-count, and wall-time limits.

POSCAR/CONTCAR

from pymatgen.io.vasp import Poscar

poscar = Poscar.from_file(
    "POSCAR",
    check_for_potcar=False,
    read_velocities=True,
)
structure = poscar.structure

direct_text = poscar.get_str(direct=True, significant_figures=16)
cartesian_text = poscar.get_str(direct=False, significant_figures=16)

Record:

  • direct/fractional versus Cartesian coordinates
  • scale factor interpretation and units
  • element-name source, especially VASP 4 files
  • species order
  • selective-dynamics flags
  • velocities, predictor-corrector data, and lattice velocities if present

POSCAR cannot faithfully represent partial occupancies. Oxidation states and arbitrary site properties generally do not round-trip. Never "fix" a POSCAR by searching nearby directories for POTCAR files without explicit approval.

XYZ and other low-context formats

XYZ is a Cartesian, non-periodic coordinate format. Converting a periodic structure to XYZ drops lattice and periodicity. Basic XYZ also does not define oxidation states, partial occupancies, bonds, charge, spin multiplicity, or arbitrary site properties.

CSSR and XSF have their own representational limits. Treat support in Structure.to() as syntactic capability, not proof of losslessness.

JSON and MSON

Pymatgen core objects implement as_dict()/from_dict():

import json
from pymatgen.core import Structure

text = json.dumps(structure.as_dict(), allow_nan=False, sort_keys=True)
payload = json.loads(text)
restored = Structure.from_dict(payload)

For untrusted input, use a bounded strict JSON parser, reject duplicate keys and non-finite values, validate the expected schema, and call a specific constructor. Do not use pickle. Do not pass attacker-controlled @module or @class metadata to a general dynamic object decoder.

YAML is not used by the bundled CLIs. If a workflow truly needs YAML, use a safe loader plus schema validation; YAML safety does not solve object-schema or resource-exhaustion risks.

VASP input objects

from pymatgen.io.vasp import Incar, Kpoints, Poscar

incar = Incar({"ENCUT": 520, "ISMEAR": 0, "SIGMA": 0.05})
kpoints = Kpoints.automatic_density(structure, 1000)
poscar = Poscar(structure)

Input sets encode versioned methodological choices:

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

relax = MPRelaxSet(structure)
static = MPStaticSet(structure)
bands = MPNonSCFSet(structure, mode="line")

Before writing:

  1. inspect the generated INCAR, KPOINTS, POSCAR, and POTCAR specification
  2. record input-set class, pymatgen/core versions, all user overrides, and the source structure checksum
  3. check magnetic moments, DFT+U, functional, pseudopotential family, ENCUT, k-point density/path, smearing, spin/SOC, symmetry, and convergence criteria
  4. write to a new calculation directory

POTCAR datasets are VASP-licensed and not distributed by pymatgen. A POTCAR.spec is not a POTCAR. Do not redistribute pseudopotential contents or silently use files from an unrelated installation.

VASP output parsing

from pymatgen.io.vasp import Vasprun

run = Vasprun(
    "vasprun.xml",
    ionic_step_skip=None,
    parse_dos=True,
    parse_eigen=True,
    parse_projected_eigen=False,
    parse_potcar_file=False,
    exception_on_bad_xml=True,
)

final_structure = run.final_structure
final_energy_eV = float(run.final_energy)
band_structure = run.get_band_structure(line_mode=True)
complete_dos = run.complete_dos

Use BSVasprun when only eigenvalue/band-structure information is needed. Projected eigenvalues can take extreme time and memory; leave parse_projected_eigen=False unless they are required and resources are bounded.

Parser success does not establish:

  • electronic or ionic convergence
  • a correct k-path or line-mode reconstruction
  • comparable energies
  • valid pseudopotential hashes
  • correct Fermi level, occupations, spin/SOC, or projection interpretation

Preserve source-file checksums and parsing options. Large XML, HDF5, CHGCAR, LOCPOT, WAVECAR, and trajectory files need explicit byte and memory limits.

Band structures and DOS

Vasprun.get_band_structure() returns a BandStructure or BandStructureSymmLine depending on inputs. Relevant methods include is_metal(), get_band_gap(), get_vbm(), and get_cbm().

run.complete_dos is a CompleteDos; current analyses include total, element-, site-, and orbital-projected DOS. Verify energy reference, Fermi level, normalization, smearing, spin channels, projection completeness, and whether the DOS and band run correspond to the same structure/method.

Q-Chem

Current imports:

from pymatgen.io.qchem.inputs import QCInput
from pymatgen.io.qchem.outputs import QCOutput

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

parsed = QCOutput("qchem.out")
data = parsed.data

QCInput accepts explicit sections such as rem, opt, pcm, solvent, smx, scan, plots, nbo, geom_opt, and others. Validate each setting against the licensed Q-Chem version and manual. Preserve molecule atom order, charge, spin multiplicity, method/basis, solvent model, job type, and input text.

QCOutput parses a file into structured data; inspect parser errors, completion, SCF/geometry convergence, imaginary frequencies, and units before using a result.

External and native programs

Pymatgen interfaces can call or depend on optional external tools, including:

  • enumlib (enum.x, makestr.x) for derivative-structure enumeration
  • Bader analysis executable
  • packmol
  • ffmpeg
  • Zeo++/Voro++
  • graph and visualization libraries

Do not invoke them automatically. Verify official source, version, hash, license, native build scripts, executable path, exact argv, working directory, input/output paths, and CPU/RAM/disk/time bounds. Never interpolate untrusted text into a shell command.

Safe conversion sequence

  1. Inventory source bytes, checksum, format, and parser warnings.
  2. Validate lattice/PBC, coordinates, species order, occupancy/disorder, oxidation states, labels, and site properties.
  3. Generate a dry-run representation-loss plan.
  4. Refuse an incompatible target (for example, disordered structure to POSCAR).
  5. Require explicit acknowledgement for remaining losses.
  6. Render in memory, enforce an output-byte bound, and create a new file exclusively.
  7. Parse the output under the same safety bounds.
  8. Compare formula, site count, lattice, PBC, coordinates, occupancy, labels, and required properties with explicit numerical tolerances.
  9. Record both checksums and every warning in the artifact manifest.

Sources (verified 2026-07-23)

Back to K-Dense-AI/scientific-agent-skills (AI Scientist skills) or Agent skills.