Guides

User-facing how-to guides for beamline scientists and instrument scientists. For developer and contributor documentation, see the Developer / Contributor section below.

Getting started

Guide	Description
How to Work with a Diffractometer	Define a diffractometer (custom subclass or creator()), use custom axis names, handle axes out of order, and scan with the bluesky RunEngine.
Solvers Guide	List, select, and instantiate solvers; understand solver entry points.

Diffractometer axes

Guide	Description
Crystal Analyzer on the Detector Arm	Add crystal analyzer axes (atheta, attheta) to a diffractometer as additional positioners on the detector arm; save and restore the configuration.
Ways to Specify Real and Pseudo Axis Positions	All accepted forms for specifying real and pseudo axis positions: positional args, keyword args, dict, and named tuple.
Diffractometer Extra Motors and/or Pseudos	Add extra real motors or pseudo axes beyond the solver defaults.
Diffractometer Extra Solver Parameters	Pass extra solver parameters (e.g. psi) to the backend.

Computation

Guide	Description
How to Compute and Set the UB Matrix	Add orientation reflections, compute the UB matrix, set it manually, inspect, refine, and reset it.
How to Use Constraints	Set axis limits and cut points; write a custom constraint subclass.
How to Use Presets	Hold a real axis at a fixed value during forward() without moving any motor (SPEC freeze/unfreeze equivalent).
How to Choose the Default forward() Solution	Choose which forward() solution the diffractometer uses by default.
Understanding forward() and inverse() Performance	Understand factors that affect forward() and inverse() throughput, including solver choice, mode, axis count, and workstation load.
How to Use the hklpy2.user Interface	Use the hklpy2.user interactive convenience functions: pa, wh, cahkl, setor, set_wavelength, and more.
Use E4CV’s q calculation engine	Switch between calculation engines (e.g. hkl, q) on the same geometry.
How to Perform a Zone Scan	Move to or scan along a crystallographic zone axis (SPEC mz/scanzone equivalent).
How to Perform an Azimuthal (ψ) Scan	Scan the azimuthal angle ψ at fixed (h, k, l) using the psi_constant mode (hkl_soleil solver feature).

Configuration and solvers

Guide	Description
Diffractometer Configuration – Save and Restore	Save a full diffractometer configuration (orientation, samples, reflections) and restore it later.
How to Create a Simulator from a Config	Create a simulated diffractometer directly from a saved config file.

Reference and background

Guide	Description
SPEC commands in hklpy2	Cross-reference of common SPEC commands to their hklpy2 equivalents.
Migration from hklpy (v1)	How code written for hklpy (v1) (v1) maps to hklpy2.

Developer / Contributor

These guides are aimed at developers extending hklpy2 or maintaining the project — not at beamline users.

Guide	Description
Architecture & Design Decisions	Architecture and design decisions behind hklpy2.
How to write a new Solver	Write and register a new solver plugin using Python entry points.
How to Make a Release	Step-by-step release process for maintainers.
Feature Checklist for v2	Feature checklist tracking the v2 build (historical reference).