Advisor-Scattering — Advanced Visual Scattering Toolkit for Reciprocal-space

Advisor-Scattering is a PyQt5 desktop app for X-ray scattering/diffraction experiments. It helps you convert scattering angles ↔ momentum transfer (HKL), explore scattering geometry, and visualize structure factors—all with interactive plots. Full docs on Read the Docs.

or use the link below to view the demo video. ▶ Demo video (MP4)

Features

• Convert scattering angles to momentum transfer (HKL) and vice versa.
• Visualize scattering geometry and unit cells
• Compute and visualize structure factors in reciprocal space.
• CIF file drop-in support
• Import crystal orientation from diffraction test data

Install

• Python 3.8+ with PyQt5, numpy, scipy, matplotlib, Dans_Diffraction (see requirements.txt).

It is recommened to install from PyPI:

pip install advisor-scattering

Run

advisor
# or
advisor-scattering
# or
python -m advisor

Note: the install command is pip install advisor-scattering, and the import is import advisor.

Minimal workflow (60 seconds)

1. Launch the app.
2. Enter lattice constants/angles and beam energy, or drop a CIF file.
3. Click Initialize.
4. Use the feature tabs (Scattering Geometry / Structure Factor) to calculate and visualize.

Using the app

1. Initialization window

• Enter lattice constants (a, b, c) and angles (alpha, beta, gamma); beam energy auto-updates wavelength/|k|.
• Optional: drop a CIF to autofill lattice parameters and preview the unit cell.
• Adjust Euler angles (roll, pitch, yaw) to orient the lattice/sample relative to the goniometer.
• New: Use Import from Diffraction Test to automatically determine Euler angles from known diffraction measurements.
• Click Initialize to load the main interface and pass parameters to all tabs.

2. Scattering Geometry tab

• Angles → HKL: enter 2θ/θ/χ/φ, compute HKL.
• HKL → Angles: enter HKL, compute feasible angles.
• HK to Angles (fixed 2θ) and HKL scan (fixed 2θ) subtabs for trajectory planning.

3. Structure Factor tab

• Requires a CIF (from init) and an energy in the tab.
• HKL plane: explore a 3D HKL cube with linked HK/HL/KL slices.
• Customized plane: choose U/V vectors and a center to sample an arbitrary plane in reciprocal space.

4. Resetting

Use the toolbar button or File → Reset Parameters to return to the init window, clear the CIF lock, and re-enter parameters.

Project structure (at a glance)

advisor/          application package
  app.py          bootstrap
  controllers/    app/feature coordinators
  domain/         math and geometry helpers (no PyQt)
  features/       per-feature domain/controller/ui code
  ui/             shared UI pieces (init window, main window, base tab, visualizers)
  resources/      QSS, icons, config JSON, sample data
docs/             Sphinx sources and assets

Documentation

• Full Sphinx docs live in docs/ and on Read the Docs.
• Appendix covers scattering angle definitions and HKL conventions.

Contributing

Bug reports, feature requests, and pull requests are welcome — see CONTRIBUTING.md for dev setup, testing, and architecture pointers. This project follows the Contributor Covenant Code of Conduct.