Solvers

A Solver is a Python class that connects hklpy2 with a (backend) library that provides diffractometer capabilities, including:

• definition(s) of physical diffractometer geometries

  • axes (angles and reciprocal space)

  • operating modes for the axes (angles and reciprocal space)

• calculations that convert:

  • forward: reciprocal space coordinates into diffractometer angles

  • inverse: diffractometer angles into reciprocal space coordinates

• support operations include:

  • calculate the UB matrix

  • refine the crystal lattice

  • sample definition

    • name

    • crystal lattice parameters: \(a, b, c, \alpha, \beta, \gamma\)

    • list of orientation reflections

A Solver class is written as a plugin for hklpy2 and is connected by an entry point using the "hklpy2.solver" group. Here’s an example from hklpy2’s pyproject.toml file for two such Solver classes:

[project.entry-points."hklpy2.solver"]
no_op = "hklpy2.backends.no_op:NoOpSolver"
hkl_soleil = "hklpy2.backends.hkl_soleil:HklSolver"

How to select a Solver

To list all available Solver classes (by their entry point name), call solvers(). This example shows the Solver classes supplied with hklpy2:

>>> from hklpy2 import solvers
>>> solvers()
{'hkl_soleil': 'hklpy2.backends.hkl_soleil:HklSolver',
 'no_op': 'hklpy2.backends.no_op:NoOpSolver'}

This is a dictionary, keyed by the solver names. To create an instance of a specific Solver class, use solver_factory(). In the next example (Linux-only), the first argument, hkl_soleil, picks the HklSolver, the geometry keyword picks the Eulerian 4-circle geometry with the hkl engine:

>>> from hklpy2 import solver_factory
>>> solver = solver_factory("hkl_soleil", "E4CV")
>>> print(solver)
HklSolver(name='hkl_soleil', version='v5.0.0.3434', geometry='E4CV', engine='hkl')

To select a Solver class without creating an instance, call get_solver(). This example selects the Hkl/Soleil Solver (using its entry point name: "hkl_soleil"):

>>> from hklpy2 import get_solver
>>> Solver = get_solver("hkl_soleil")
>>> print(f"{Solver=}")
Solver=<class 'hklpy2.backends.hkl_soleil.HklSolver'>

How to write a new Solver

Caution

TODO:: work-in-progress

Solver classes always subclass SolverBase:

from hklpy2.backends.SolverBase

class MySolver(SolverBase):
    ...

Source Code Documentation

A Solver connects hklpy2 with a backend calculation library.

A Solver class (also described as a backend) is a Python class that connects hklpy2 with a library that provides diffractometer geometries & calculations. See the API documentation for details.

Built-in Solvers

HklSolver(geometry, *[, engine, mode])	"hkl_soleil" (Linux x86_64 only) Hkl/Soleil.
NoOpSolver(geometry, **kwargs)	"no_op" (any OS) no transformations.
ThTthSolver(geometry, **kwargs)	"th_tth" (any OS) \(\theta,2\theta\) and \(Q\).

Base class for all solvers

SolverBase(geometry, *[, mode])

Base class for all hklpy2 Solver classes.