Pymatgen Skill (K-Dense)

Overview

Pymatgen Skill (K-Dense) is an individual resource in the Scientific Agent Skills collection. It supplies procedural instructions, references, and optional Python helpers for working with pymatgen; it is neither the upstream library nor an independently running agent. Its role is to guide materials-analysis workflows while preserving assumptions, parser warnings, and artifact provenance.

Inputs include composition strings, molecular or periodic structures, structure files, local computed-energy entries, and explicitly scoped Materials Project query criteria. Documented outputs include validation reports, symmetry-sensitivity reports, converted structures, local phase-diagram analyses, query plans, and artifact manifests. The workflow asks users to establish units, coordinate conventions, occupancies, and oxidation-state treatment before downstream analysis. Conversion is preceded by a representation-loss plan, with new output paths and checks of scientifically relevant properties after round-tripping.

Local analysis is separated from external retrieval. The bundled Materials Project helper plans queries without network access by default; execution requires explicit approval, bounded filters and fields, and authentication. Materials Project is the upstream data service, while mp-api is its client dependency—not a service supplied by this Skill. Phase diagrams depend on compatible energies and the supplied competing phases; computed hull membership does not establish experimental stability.

The source reports execution of its local CLI suite and synthetic examples, but identifies authenticated retrieval and file-dependent VASP/Q-Chem examples as illustrative rather than executed. The Skill does not run those electronic-structure packages or provide their licences. Structure validation also has documented limits, including incomplete contact checking across very short lattice vectors. These boundaries should inform any intended evaluation on real research data.

Key Features

• Composition and structure validation helpers report parser warnings, units, coordinate mode, periodicity, occupancy, disorder, oxidation states, and minimum inter-site distances.
• A symmetry-sensitivity helper evaluates space-group assignments across explicit distance and angle tolerance grids.
• Separate conversion planning and execution helpers identify representation loss and write converted structures to new paths.
• An offline phase-diagram helper accepts strict JSON entries with total energies and provenance, supporting local hull analysis and optional plotting.
• A Materials Project query helper defaults to dry-run planning and supports explicitly approved, bounded summary retrieval with selected fields and new output files.
• An artifact-manifest helper records checksums, software versions, sources, and workflow provenance.

Use Cases

• Intended evaluation: assess CIF intake for a materials-screening workflow by inspecting parser corrections, partial occupancies, and structural warnings before analysis.
• Intended evaluation: test whether a reported space group is sensitive to symmetry tolerances rather than relying on one assignment.
• Intended evaluation: convert structures between supported representations while checking lattice, species ordering, site properties, and other potentially lost information.
• Intended evaluation: construct a local phase diagram from compatible computed entries, or plan a narrowly scoped Materials Project retrieval with retained provenance.

How to Use

1. Read the named Skill and locate its helpers in the collection repository. Treat it as workflow guidance, not an autonomous application.
2. Prepare an isolated Python environment using the Skill’s documented dependency setup. Preserve the dependency lock and environment details; planning helpers do not require the scientific packages, but local analysis does.
3. Select a small evaluation input. Record whether it is molecular or periodic, its units and coordinate mode, then use the documented validator and inspect all warnings before proceeding.
4. Choose the relevant local workflow: sweep symmetry tolerances, plan conversion before writing a new artifact, or supply provenance-bearing energy entries for a phase diagram. Consult the pymatgen documentation for API contracts.
5. For external data, inspect a dry-run plan first and obtain explicit network approval. Follow the Materials Project API guide, keeping authentication outside saved artifacts.
6. Save analysis outputs and an artifact manifest. Review representation changes, excluded entries, and scientific assumptions before using results in research.