pymatgen
Analyzes, validates, converts, and transforms crystal structures and molecules with pymatgen. It covers CIF/POSCAR/XYZ/JSON conversion, symmetry-tolerance sweeps, local phase diagrams from computed entries, VASP and Q-Chem I/O, band structure and DOS parsing, and bounded Materials Project (mp-api) queries. Use when validating a CIF or checking disorder and oxidation states. Use when assigning space groups and testing symprec sensitivity. Use when converting structure files and checking for representation loss. Use when building a convex hull from total energies. Use when querying Materials Project with explicit fields and limits. Not for general molecular dynamics or non-materials cheminformatics.
- License 许可
- MIT
- 最近更新
- 2026-11-08
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- pymatgen
- license
- MIT
- metadata
- { "tags": "materials science, crystal structures, computational materials, VASP, physics", "version": "1.3", "category": "physical-sciences", "maintainer": "Kalaris Labs", "last-reviewed": "2026-07-23" }
- description
- Analyzes, validates, converts, and transforms crystal structures and molecules with pymatgen. It covers CIF/POSCAR/XYZ/JSON conversion, symmetry-tolerance sweeps, local phase diagrams from computed entries, VASP and Q-Chem I/O, band structure and DOS parsing, and bounded Materials Project (mp-api) queries. Use when validating a CIF or checking disorder and oxidation states. Use when assigning space groups and testing symprec sensitivity. Use when converting structure files and checking for representation loss. Use when building a convex hull from total energies. Use when querying Materials Project with explicit fields and limits. Not for general molecular dynamics or non-materials cheminformatics.
- allowed-tools
- Read Write Bash Glob Python
- 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.
02 资源文件 14
- 参考文档references/analysis_modules.md10.6 KB
- 参考文档references/core_classes.md8.9 KB
- 参考文档references/io_formats.md10.6 KB
- 参考文档references/materials_project_api.md12.9 KB
- 参考文档references/transformations_workflows.md12.3 KB
- 脚本scripts/_common.py10.4 KB
- 脚本scripts/artifact_manifest.py5.5 KB
- 脚本scripts/composition_structure_validator.py11.3 KB
- 脚本scripts/io_conversion_plan.py6.8 KB
- 脚本scripts/mp_query.py14.7 KB
- 脚本scripts/phase_diagram_generator.py14.3 KB
- 脚本scripts/structure_analyzer.py10.8 KB
- 脚本scripts/structure_converter.py7.4 KB
- 脚本scripts/symmetry_sensitivity_report.py7.5 KB
03 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.4is the latest stable wrapper release (2026-05-04). Package metadata requires Python 3.11+ and directly requirespymatgen-core>=2026.4.16.pymatgen-core==2026.7.16is the latest stable core release (2026-07-16). It now contains core objects, symmetry/lattice operations, and the I/O layer, all under the existingpymatgen.*namespace.mp-api==0.46.4is the latest stable Materials Project client (2026-06-15), requires Python 3.11+, and depends onpymatgen>2024.2.20.- The current API site is built from 2026.7.16 core documentation. Pinning both
distributions prevents
pymatgen==2026.5.4from 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
- State whether the object is a non-periodic
Moleculeor periodicStructure; 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.
Structurecoordinates are fractional unlesscoords_are_cartesian=True;Moleculecoordinates 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
symprecin Å andangle_tolerancein 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.
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)
- pymatgen 2026.5.4 on PyPI
- pymatgen-core 2026.7.16 on PyPI
- pymatgen API documentation
- pymatgen changelog
- mp-api 0.46.4 on PyPI
- Materials Project API getting started
- Materials Project query guide
- Materials Project FAQ and computed-data caveats
- Materials Project citation page
- Official tutorial series endorsed by pymatgen
Agent operating procedure
- Check the environment. Confirm library versions, units, coordinate systems and data formats (FITS, CIF, HDF5, netCDF).
- Pin down the inputs. Confirm formats, identifiers and parameters from the data or the user. Ask rather than guess any value that changes the result.
- Run a small version first. Run on a small grid, region or subset and check physical plausibility.
- Execute the full task using the instructions and references above.
- Validate the result. Check units and dimensional consistency, conservation laws or known limits, and numerical convergence.
- Report. State what was run (versions, commands, parameters), what was checked, and what is still uncertain.
| If this happens | Do this |
|---|---|
| Results violate known physical limits | Check units, boundary conditions and solver tolerances before reporting. |
| A function, flag or endpoint in these instructions is missing in the installed version | Check the installed version's own documentation (help(), --help, official docs), adapt, and tell the user. Never invent an API. |
| A required input, identifier or parameter is ambiguous | Ask the user, or state the assumption explicitly before running. |
Integrity rules
- Never fabricate results, parameters, identifiers, citations or statistics. If something cannot be run or verified, say so plainly.
- Report uncertainties and numerical tolerances with every quantitative result.
- Treat version-specific details here as possibly outdated: confirm them against the official documentation for the installed version.
- Ask before actions that cost money, consume shared GPUs or cloud quota, touch personal or patient data, or cannot be undone.
Related skills
molfeat: Converts SMILES strings or RDKit/datamol molecules into numerical features using molfeat (0.11.0), which provides calculators, scikit-learn…protocolsio-integration: Reads, validates, and exports protocols.io data using the documented REST v3/v4 endpoints and the official MCP endpoint, and builds non-exe…
04 同仓库更多 Skills
youtube-full
Use when the user needs YouTube transcripts, video search, channel browsing, playlist extraction, or content monitoring. Trigger phrases: 'get the transcript for', 'search YouTube for', 'what are the latest videos on', 'list this playlist', 'monitor this channel', or any request involving a YouTube URL, video ID, or @handle. Do NOT use for downloading video or audio files, YouTube engagement data (likes, comments), or private/age-restricted videos.
x-twitter-growth
X/Twitter growth engine for building audience, crafting viral content, and analyzing engagement. Use when the user wants to grow on X/Twitter, write tweets or threads, analyze their X profile, research competitors on X, plan a posting strategy, or optimize engagement. Complements social-content (generic multi-platform) with X-specific depth: algorithm mechanics, thread engineering, reply strategy, profile optimization, and competitive intelligence via web search.
write-a-skill
Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, build, or author a new skill.
wrap-up
Close out a launched Claude Managed Agent — recap every primitive the founder now owns, regenerate the single-file overview page, and suggest the next 1-2 upgrades. Use when the user says "wrap up", "close this out", "what do I own now", "give me the summary", "recap the agent", or when the orchestrator routes phase=wrap-up. primitives_inventory.py tables everything owned (agent, environment, session, memory, outcome, deployment); overview_page.py regenerates a self-contained ./my-agent/agent-overview.html; upgrade_suggester.py ranks the next moves from recorded deferrals plus standing hardening steps. Companion to run-without-you; the last stop before phase=done.
workflow-builder
Design and write deterministic multi-agent workflow scripts (.js files in .claude/workflows/) for Claude Code's Workflow tool. Use when a user wants to build, create, author, scaffold, or run a custom Claude Code workflow, orchestrate sub-agents (fan-out, pipeline, loop, judge-panel), or automate a repeatable multi-step task across fresh-context agents.
weekly-review
Use when someone wants to run a weekly review, close open loops, audit stalled projects and commitments, get their system back to trusted, restart a lapsed review habit, or says "/cs:weekly-review". Walks David Allen's three-phase loop — GET CLEAR, GET CURRENT, GET CREATIVE — with deterministic scripts that inventory open loops, gate the checklist with named gaps, and score commitment health 0-100.