gsasii

name	gsasii
description	Use when a user asks to simulate powder diffraction patterns, run GSAS-II Rietveld/Pawley/Le Bail refinement, fit powder diffraction data, inspect GSAS-II service health, or build workflows combining CIF structures with XRD/neutron powder data through the deployed chemistry gateway.

GSAS-II Gateway

GSAS-II powder-diffraction simulation and Rietveld refinement, exposed as a stateless JSON adapter over the chemistry gateway. Use it for the diffraction consequences of crystal structures: simulate a powder pattern from a CIF, or refine a structure against experimental powder data. Prefer the public gateway over local GSAS-II 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

Use GSAS-II for diffraction consequences of crystal structures. Use $pymatgen before GSAS-II when the structure needs validation, symmetry analysis, or conversion to CIF.

Default decision flow:

1. If the user provides CIF text and asks for a simulated powder pattern, call /chem/gsasii/powder/simulate.
2. If the user provides POSCAR/JSON/CSSR/XSF or asks to validate/edit/check a crystal structure before diffraction, use $pymatgen first:
   • /chem/pymatgen/structure/summary
   • /chem/pymatgen/structure/symmetry
   • /chem/pymatgen/structure/convert with output_format: "cif"
3. If the user provides experimental powder data plus at least one CIF phase, call /chem/gsasii/powder/refine.
4. Send JSON to the gateway. The gateway wraps normal results as {code,message,data}. Raw HTTP validation errors may appear as {detail: ...}; surface those directly.
5. Treat data.valid == false as a GSAS-II setup/refinement failure and surface data.error plus data.warnings.

Quickstart

Check health:

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

Get sample data. The example below uses the official GSAS-II PbSO4 tutorial files; download them first (see references/examples.md "Sample Data" for the full set and the placeholder mapping):

curl --retry 3 --retry-all-errors -L \
  -o /tmp/PbSO4-Wyckoff.cif \
  https://advancedphotonsource.github.io/GSAS-II-tutorials/PythonScript/data/PbSO4-Wyckoff.cif

Simulate a quick powder pattern from just the CIF plus a radiation default (no instrument file needed):

curl -s "$CHEM_API/chem/gsasii/powder/simulate" \
  -H "Content-Type: application/json" \
  -d "$(jq -nc \
    --rawfile cif /tmp/PbSO4-Wyckoff.cif \
    '{
      cif: $cif,
      phase_name: "PbSO4",
      radiation: "CuKa",
      histogram_name: "quick CuKa simulation",
      t_min: 10.0,
      t_max: 80.0,
      t_step: 0.02,
      include_profile: true,
      max_profile_points: 100,
      include_reflections: true,
      max_reflections: 50
    }')" \
  | jq '{valid: .data.valid, n_profile: (.data.profile | length), n_reflections: (.data.reflections | length), warnings: .data.warnings, error: .data.error}'

Or run the bundled smoke test, which auto-downloads the CIF and instrument files to /tmp if missing:

python3 scripts/smoke_gsasii.py

Response Shape & Quirks

GSAS-II responses include valid, mode, histogram_name, residuals, phases, profile, reflections, warnings, error, and metadata. When return_project is true, responses may also include a base64-encoded .gpx project in project_base64. When return_refined_cif is true, responses may also include refined_cif and refined_cif_filename.

Interpretation:

• profile is a sampled powder diffraction profile. x is usually 2theta for X-ray powder data, while y_calc is the calculated intensity.
• max_profile_points controls how many profile points are returned through the API. It does not necessarily mean GSAS-II only computed that many points internally.
• reflections is a bounded best-effort peak/reflection list from GSAS-II with hkl, d-spacing, 2theta, common intensity fields, and a raw numeric row for version-specific columns.
• project_base64 is a native GSAS-II .gpx project. Decode it only when the user asks to save/inspect the project or when a workflow needs a reusable GSAS-II artifact.
• refined_cif is text intended for direct handoff back to $pymatgen when available.

Known behavior:

• Good refinement needs realistic powder data, a compatible GSAS-II instrument parameter file, and CIF phases with sensible unit cells and occupancies.
• Powder simulation can omit instrument_parameters for quick XRD previews; the service generates a simple CW X-ray instrument model from wavelength or radiation (CuKa by default). Use real instrument parameters for instrument-specific simulation and all refinement workflows.
• refinement_steps is passed through to GSAS-II's scriptable refinement API, so callers should keep recipes narrow and incremental.
• refinement_mode: "rietveld" is currently the implemented mode. pawley and lebail return a clear not-implemented error instead of silently behaving as Rietveld until the service wires the mode-specific GSAS-II setup.
• Use this service for diffraction simulation/refinement; use $pymatgen for general structure parsing and symmetry analysis.
• Refinement can report valid: false while still returning partial profile or phase information when GSAS-II was able to construct a project but refinement failed.
• When GSAS-II's direct CIF importer rejects a CIF, the service may construct a phase from CIF cell, space group, and atom-site records. Surface response warnings because they disclose whether this fallback was used.
• Refinement quality depends strongly on realistic powder data, compatible instrument parameters, and an explicit refinement recipe. Keep early refinement tests conservative, often max_cycles: 0 or a small cycle count.
• The deployed gateway may lag the repo. If a request unexpectedly returns raw 422 validation details, show the raw response and adjust to the deployed schema, for example max_profile_points >= 10 on older gateway images.

Advanced & Cross-Service Workflows

For the full structure -> simulation -> diffraction sequences and other multi-service plans, load $delta-science-bundle; it owns the orchestration. This section documents only GSAS-II's own handoff contract.

Handoff notes:

• refined_cif from a refinement is real CIF text. Feed it straight to $pymatgen (format: "cif") for a symmetry/summary cross-check, or use it as a structure source for a follow-up $lammps run.
• reflections (hkl, d-spacing, 2theta, intensity) is the handoff for peak-position comparison against an experimental or reference peak list.
• Structures coming from $lammps are LAMMPS data/dump files, which are not pymatgen or GSAS-II inputs. Rebuild a CIF from the relaxed cell and coordinates first ($lammps documents this boundary).

Run the cross-service workflow verifier (bundled under scripts/):

python3 scripts/workflow_pymatgen_gsasii.py

Reference & Scripts

• references/endpoints.md — concrete payload schemas for powder/simulate and powder/refine.
• references/examples.md — copyable curl recipes plus the "Sample Data" download commands (CIF, instrument .PRM, and the PBSO4.XRA powder file, which is GSAS format so powder_format: "gsas").
• scripts/ (see scripts/README.md):
  • scripts/smoke_gsasii.py — quick GSAS-II-only deployment check.
  • scripts/workflow_pymatgen_gsasii.py — structure-validation plus diffraction pipeline.