XRD-GD

This repository contains a study on X-ray diffraction (XRD) pattern-based structure refinement using the Snap module from the Crystalyze Repository.

Paper

This code accompanies the paper: "The Loss Landscape of Powder X-Ray Diffraction-Based Structure Optimization Is Too Rough for Gradient Descent" (arXiv:2512.04036)

Figure: The loss landscape for XRD pattern matching reveals a challenging optimization problem. Different local minima produce similar XRD patterns despite different lattice parameters, illustrating why gradient-based optimization struggles.

Structure

The main components include:

• snap/: Structure snapping and refinement code
• data_utils/: Data processing utilities
• evals/: Evaluation scripts

How to run

1. Create and activate the conda environment

   conda env create -f environment.yml
   conda activate xrd-gd

2. Prepare data (create noisy initial structures)
   • Place your input CSV with CIFs under the data/ directory. The structures used in our study are provided in data/gd_subset.csv.
   • Generate perturbed initial structures using:

     python data_utils/perturb.py \
       --dataset_name gd_subset \
       --type_ablation lattice \
       --max_strain 0.1 \
       --augs_per_datapoint 50 \
       --preserve_symmetry False

     This writes data/lattice_0.1.csv. To perturb only coordinates, use --type_ablation coords.
3. Run structure snapping (Snap from Crystalyze)

   python snap/full_structure_snap.py \
     --noise_level 0.1 \
     --perturb_type lattice \
     --gt_structures_file data/gd_subset.csv \
     --loss_func cos_sim

   • --perturb_type must match the ablation type used in perturb.py (lattice or coords).
   • --noise_level must match the max_strain used when creating the noisy CSV (e.g. 0.1 → lattice_0.1.csv).
   • Optional flags:
     • --apply_sym_const to enforce crystal-family symmetry constraints during snapping.
     • --demo_mode to run on a tiny subset for a quick sanity check.
4. Run evaluation / metrics

   python evals/calc_metrics.py

   • The script expects:
     • Ground-truth structures (as in data/gd_subset.csv).
     • Snap outputs (e.g. snap_structures_lattice_0.1.pt and losses_log.txt) under output/<loss_func>/<noise_type>_<noise_level>/, as produced by full_structure_snap.py.
   • It computes structure match rate, cosine similarity, space-group agreement, and AMD–metric correlations, and saves plots and metrics next to the snap outputs.