pymatgen

name	pymatgen
description	Use when a user asks to parse material formulas, inspect compositions, parse or summarize crystal structures, convert CIF/POSCAR/JSON/CSSR/XSF structures, or analyze symmetry through the deployed chemistry pymatgen gateway service. Triggers on pymatgen, materials, composition, formula parsing, CIF, POSCAR, crystal structure, lattice, space group, symmetry, primitive cell, or structure conversion.

pymatgen Gateway

pymatgen materials analysis, exposed as a stateless JSON adapter over the chemistry gateway. Use it to parse formulas/compositions, parse and summarize crystal structures, convert between structure formats, and analyze symmetry. Prefer the public gateway over local pymatgen imports unless the user explicitly asks for local-only code.

Default base URL:

CHEM_API="${CHEM_API:-http://111.2.199.31:52317/api/v1}"

When To Use

1. Pick the endpoint:
   • formula/composition: /chem/pymatgen/composition/parse
   • structure parse/summary: /chem/pymatgen/structure/parse or /summary
   • format conversion: /chem/pymatgen/structure/convert
   • symmetry: /chem/pymatgen/structure/symmetry
2. Send JSON to the gateway. The gateway wraps results as {code,message,data}.
3. Treat data.valid == false as a materials parsing/validation failure and surface data.error.
4. Use pymatgen for materials formulas, crystal structures, CIF/POSCAR conversion, and symmetry; use $rdkit for molecular SMILES/InChI validation.

Quickstart

Check health:

curl -s "$CHEM_API/chem/pymatgen/health"

Parse a composition:

curl -s "$CHEM_API/chem/pymatgen/composition/parse" \
  -H "Content-Type: application/json" \
  -d '{"formula":"LiFePO4"}'

Or run the bundled smoke test:

python3 scripts/test_composition.py

Response Shape & Quirks

Composition parse responses include formula, reduced_formula, alphabetic_formula, anonymous_formula, chemical_system, number_of_atoms, weight, element_amounts, atomic_fractions, weight_fractions, valid, and error.

Known behavior:

• reduced_formula and element ordering may be normalized by pymatgen and may differ from the user's input order.
• Use pymatgen for materials formulas, crystal structures, CIF/POSCAR conversion, and symmetry; use $rdkit for molecular SMILES/InChI validation.
• For formula lists, batch manually by calling composition parse for each formula and returning one table.
• structure/convert handles cif, poscar, json, cssr, and xsf only. It does not read or write LAMMPS data/dump files; translate across the LAMMPS boundary yourself (see $lammps).

Advanced & Cross-Service Workflows

Single-service recipe: a formula list becomes one pymatgen composition table with reduced formula, chemical system, atomic fractions, weight fractions, and molecular weight (call composition parse per formula and combine).

pymatgen is the structure broker for materials workflows: it validates and converts inputs, but it only handles cif/poscar/json/cssr/xsf (see Quirks). Across the LAMMPS boundary you hand-build the data file and rebuild a CIF from relaxed output yourself. GSAS-II refined_cif feeds straight back in.

For the full structure -> simulation -> diffraction sequences and other multi-service plans, load $delta-science-bundle; it owns the orchestration.

Reference & Scripts

• references/endpoints.md — structure request schemas.
• references/examples.md — copyable curl recipes.
• scripts/ (see scripts/README.md):
  • scripts/test_composition.py — quick composition-parse smoke test.