grok_phase_solver

Open physics / AI phasing assistant for X-ray crystallography
Version 0.13.2 · Python ≥ 3.10 · MIT

Recover phases $\varphi(hkl)$ from measured amplitudes $|F(hkl)|$, write density maps and a SHELXL-ready trial model, then refine elsewhere (Olex2 / SHELXL).

$$ \rho(\mathbf{r})

\frac{1}{V}\sum_{\mathbf{h}} |F(\mathbf{h})|,e^{i\varphi(\mathbf{h})},e^{-2\pi i \mathbf{h}\cdot\mathbf{r}} $$

1. Five-minute start (scientist path)

Install (recommended: PyPI)

python -m pip install grok-phase-solver
gps-solve --help

# Optional browser UI
python -m pip install "grok-phase-solver[gui]"
gps-gui
# → http://localhost:8501  (upload HKL/INS, download trial.res)

On macOS, use python3 or Anaconda if python is not found:

source ~/anaconda3/bin/activate   # if you use Anaconda
python -m pip install grok-phase-solver

Install from source (developers)

git clone https://github.com/pileofflapjacks1/grok_phase_solver.git
cd grok_phase_solver
python -m pip install -e ".[gui]"
gps-solve --help

Optional PhAI weights (not on PyPI): see third_party/phai/README.md and pip install -e ".[ml]".
Release notes: docs/RELEASE.md · v0.13.2 notes · Paper PDF

Phase your data

# Recommended: SHELX-style pair
gps-solve --hkl mycrystal.hkl --ins mycrystal.ins --out ./solve_out

# Without .ins
gps-solve --hkl mycrystal.hkl \
  --cell 9.75,8.89,7.57,90,112.7,90 \
  --sg "P 1 21/c 1" \
  --out ./solve_out

# AI-PhaSeed hybrid (Carrozzini 2025-aligned DM+AI tangent + seed-quality diagnostics)
gps-solve --hkl mycrystal.hkl --ins mycrystal.ins \
  --method phai_phaseed --ai-dm-hybrid --seed-quality-filter --out ./solve_out

# Predicted model fragment seed (AF / OpenFold3 / Boltz CIF) → partial-φ path
gps-solve --hkl mycrystal.hkl --ins mycrystal.ins \
  --predicted-model model.cif --method partial_phaseed --out ./solve_out

# Experimental diffusion hybrid (Langevin; not production default)
gps-solve --hkl mycrystal.hkl --ins mycrystal.ins \
  --method diffusion_hybrid --n-diffusion-steps 20 --out ./solve_out

What you get

This tool phases. It does not replace least-squares refinement. Always check chemical sense and refinement R-factors.

Demos (no lab data)

# Easy: multistart ensemble (best open ab initio on easy cells in our benchmarks)
gps-solve --hkl examples/demo_solve/demo.hkl --ins examples/demo_solve/demo.ins \
  --method ensemble --n-iter 100 --out examples/demo_solve/out

# Hard-ish + partial phases (path that works when pure ab initio fails)
python scripts/run_partial_seed_demo.py

2. Which method should I use?

Have partial info (φ / fragment / HA)?
   YES →  partial_phaseed + seed source:
            --phase-seed-csv | --phase-seed-res | --seed-peaks-csv
            | --native-hkl + --derivative-hkl | gps-make-seed …
   NO  →  resolution good (d ≲ 1.15 Å)?
            YES → --method auto   (→ ensemble)
            NO  → --method auto   (→ prior/CF; may fail — get partial φ or try shelxs)
Finish → report.md Next action (Vol-band) → trial.res → SHELXL / Olex2

Full table and flags: docs/USER_GUIDE.md.

3. What this project is (and is not)

It is

• An open, modular implementation of classical phasing (charge flipping, HIO, RAAR, DiffMap, direct methods, Patterson)
• A scientist CLI (gps-solve) with free figures of merit and strict success metrics
• A hybrid research stack: AI-PhaSeed, GraphPhaseNet prior, partial-φ API, Wilson domain matching
• Head-to-head harnesses vs academic SHELXS (and optional SHELXD/E if you install them)
• Documented math and reproducible scoreboards under data/processed/

It is not

• A claim that the crystallographic phase problem is “solved”
• A general protein ab initio solver
• A replacement for SHELXL refinement or industrial small-molecule pipelines (SHELXT/SHELXS + Olex2)
• A redistributor of SHELX or PhAI binaries/weights (obtain under their licenses)

Honest hard-region result: pure ab initio (CF, ensemble, GraphPhaseNet, even SHELXS on our hard panel) remains ~0% strict success for harder synthetic cells ($n\gtrsim 12$, $d_{\min}\gtrsim 1.5,\text{Å}$). With ≥ ~30% correct strong-|E| phases (≲20° error), AI-PhaSeed can strict-solve those cells — so the open path for hard data is partial information, not more polish alone.

4. Key scientific findings (start here if reviewing the work)

One-pager for referees: docs/FOR_REVIEWERS.md (claims C1–C8, non-claims, reproduce steps).

Strict success = mapCC_OI ≥ 0.7 and peak recovery ≥ 0.5 and R1 ≤ 0.45 (metrics/success.py).

Pedagogy: Cowtan ELS notes · Phase problem overview · Uniqueness & non-claims

5. Methods at a glance

What auto does

1. Easy / high-res ($d_{\min} \le 1.15,\text{Å}$) → ensemble (CF+RAAR multistart, free-FOM pick)
2. P2₁/c + PhAI weights → AI-PhaSeed
3. Harder res → GraphPhaseNet / hard-P1 prior if available, else charge flipping
4. Partial phases are never auto-detected — pass --phase-seed-csv yourself

Core algorithms (in-repo)

External SHELX (optional)

Place academic binaries in ShelX/ (gitignored — do not commit):

xattr -dr com.apple.quarantine ShelX   # macOS if needed
chmod +x ShelX/shelxs ShelX/shelxe ShelX/shelxl

gps-solve --hkl data.hkl --ins data.ins --method shelxs+shelxe --out out_sx
# Refine: cp out_sx/trial.res work.ins && cp data.hkl work.hkl && ShelX/shelxl work

Download: https://shelx.uni-goettingen.de/

6. Library API (short)

from grok_phase_solver.pipeline.solve import SolveConfig, solve_structure
from grok_phase_solver.pipeline.export import export_solution

result = solve_structure(
    "mycrystal.hkl",
    ins_path="mycrystal.ins",
    config=SolveConfig(method="auto", n_iter=120, n_starts=3),
)
export_solution(result, "solve_out")
print(result.method, result.diagnostics.get("free_fom_composite"))

# Multistart ensemble (no ground truth needed for ranking)
from grok_phase_solver.solvers.ensemble import ensemble_cf_raar
phases, rho, info = ensemble_cf_raar(hkl, amplitudes, cell, n_starts=5, n_iter=120)

# Partial phases → extension
from grok_phase_solver.solvers.partial_seed import partial_phaseed_solve, load_phase_seed_csv
seed, mask, meta = load_phase_seed_csv("known.csv", hkl)
phases, rho, info = partial_phaseed_solve(hkl, amplitudes, cell, seed, mask=mask)

7. Reproduce research reports

python -m pip install -e ".[dev]"
pytest -q

# Core scoreboards (subset)
python scripts/run_shelxs_h2h.py              # vs local SHELXS if installed
python scripts/run_partial_seed_benchmark.py  # hard-cliff oracle curves
python scripts/run_wilson_domain_gap.py
python scripts/train_strong_prior.py --scale-xl --wilson-match
python scripts/run_experimental_scoreboard.py
python scripts/run_failure_taxonomy.py

8. Repository map

src/grok_phase_solver/
  pipeline/   # gps-solve: solve, peaks, export (trial.res)
  solvers/    # CF, ensemble, free FOM, AI-PhaSeed, partial_seed, SHELXS/E runners
  physics/    # Fcalc, density FFT, Patterson, form factors
  metrics/    # mapCC_OI, R1, success thresholds, strong-seed bar
  models/     # GraphPhaseNet, hard_p1, PhAI fair packing
  data/       # synthetic, Wilson match, MIR/MAD/MR simulators
  io/         # HKL, INS, CIF, MTZ, SHELX writers
docs/         # USER_GUIDE + math/ + Cowtan notes
examples/     # demo_solve (easy), partial_seed_demo (hard + partial φ)
scripts/      # benchmarks and training
data/processed/  # committed scoreboard .md/.json
notebooks/    # pedagogical 01–03
tests/        # pytest (100+ tests)
ShelX/        # YOUR local SHELX binaries only (gitignored)

9. Sample data (COD)

gps-download-cod          # helper for COD samples

10. Documentation index

11. Tests & packaging

pytest -q
python -m build && python -m twine check dist/grok_phase_solver-0.3.0*
# PyPI (needs API token): python -m twine upload dist/grok_phase_solver-0.3.0*

PyPI upload is optional (twine upload dist/* with your API token). GitHub source install is fully supported.

12. Citation

If you use this framework, please cite the upstream methods you rely on (and this repository if useful):

@article{Larsen2024PhAI,
  author  = {Larsen, Anders S. and Rekis, Toms and Madsen, Anders {\O}.},
  title   = {PhAI: A deep-learning approach to solve the crystallographic phase problem},
  journal = {Science},
  year    = {2024},
  doi     = {10.1126/science.adn2777}
}
@incollection{Cowtan2001Phase,
  author    = {Cowtan, Kevin},
  title     = {Phase Problem in X-ray Crystallography, and Its Solution},
  booktitle = {Encyclopedia of Life Sciences},
  year      = {2001}
}

SHELX (Sheldrick): use under academic terms from shelx.uni-goettingen.de.
COD: crystallography.net/cod.
gemmi: gemmi.readthedocs.io.

13. License & contributing

MIT — see LICENSE. Third-party data/models keep their own terms. Do not commit SHELX binaries or PhAI weights.

Contributions: prefer mathematical correctness and physics fallbacks over marketing claims. Workflow: plan → code → test → document limits → commit.

Plan → Code → Test → Analyze math → Refine → Commit

14. Contact / status

• Checklist: TODO.md
• Version notes: CHANGELOG.md
• Issues / PRs: GitHub repository above

Bottom line for a new reader: clone → pip install -e . → run gps-solve on examples/ → read report.md → refine in SHELXL. For hard structures, bring partial phases. For the science, start with §4 and the linked scoreboards.