How to write a new Solver

An hklpy2 Solver is an adapter [2] for a backend diffractometer computation library.

Steps

Overview

• Create a new Python package.

• Create a Solver class.

• Register as Entry Point.

• Install and test.

To write a new solver for hklpy2, you need to create a Python class that inherits from SolverBase and register it as an entry point.

Tip

Create a new project [6] for this work.

Here are the essential steps:

Step 1. Create a Solver Class

Create a Python class that inherits from SolverBase and implement all required abstract methods (methods marked with decorator @abstractmethod [1]):

from hklpy2.backends.base import SolverBase
from hklpy2.misc import IDENTITY_MATRIX_3X3
from hklpy2.misc import KeyValueMap
from hklpy2.misc import Matrix3x3
from hklpy2.misc import NamedFloatDict

class MySolver(SolverBase):
    name = "my_solver"
    version = "1.0.0"

    def __init__(self, geometry: str, **kwargs):
        super().__init__(geometry, **kwargs)

    # Required abstract methods
    def addReflection(self, reflection: KeyValueMap) -> None:
        """Add an observed diffraction reflection."""
        pass  # TODO: send to your library

    def calculate_UB(self, r1: KeyValueMap, r2: KeyValueMap) -> Matrix3x3:
        """Calculate the UB matrix with two reflections."""
        return IDENTITY_MATRIX_3X3  # TODO: calculate with your library

    def forward(self, pseudos: NamedFloatDict) -> list[NamedFloatDict]:
        """Compute list of solutions(reals) from pseudos."""
        return [{}]  # TODO: calculate with your library

    def inverse(self, reals: NamedFloatDict) -> NamedFloatDict:
        """Compute pseudos from reals."""
        return {}  # TODO: calculate with your library

    def refineLattice(self, reflections: list[KeyValueMap]) -> NamedFloatDict:
        """Refine lattice parameters from reflections."""
        return {}  # TODO: calculate with your library

    def removeAllReflections(self) -> None:
        """Remove all reflections."""
        pass  # TODO: use your library

    # Required properties
    @property
    def extra_axis_names(self) -> list[str]:
        """Ordered list of extra axis names."""
        return []

    @classmethod
    def geometries(cls) -> list[str]:
        """Supported diffractometer geometries."""
        return ["MY_GEOMETRY"]

    @property
    def modes(self) -> list[str]:
        """Available operating modes."""
        return []

    @property
    def pseudo_axis_names(self) -> list[str]:
        """Ordered list of pseudo axis names (h, k, l)."""
        return []

    @property
    def real_axis_names(self) -> list[str]:
        """Ordered list of real axis names (omega, chi, phi, tth)."""
        return []

Step 2. Register as Entry Point

Create a [project.entry-points."hklpy2.solver"] section in your project’s pyproject.toml file and declare your solver. Here’s an example:

[project.entry-points."hklpy2.solver"]
my_solver = "my_package.my_solver:MySolver"

Step 3. Install and Test

Install your package to make the solver discoverable. Then test that it loads correctly:

import hklpy2

# List available solvers
print(hklpy2.solvers())

# Load your solver class
SolverClass = hklpy2.get_solver("my_solver")

# Create an instance
solver = SolverClass("MY_GEOMETRY")

Use the creator() factory to create a diffractometer with your solver and test it. Here’s a suggested start:

import hklpy2

sim = hklpy2.creator(name="sim", solver="my_solver")
sim.wh()

Key Implementation Details

Required Methods Contract

All solvers must implement these attributes, methods, and properties:

method (or property)	description
name	(string attribute) Name of this solver.
version	(string attribute) Version of this solver.
addReflection(reflection)	Add an observed diffraction reflection.
calculate_UB(r1, r2)	Calculate the UB matrix with two reflections.
extra_axis_names	Returns list of any extra axes in the current mode.
forward(pseudos)	Compute list of solutions(reals) from pseudos. A single-element list is acceptable (see forward() contract).
geometries	@classmethod [3] : Returns list of all geometries support by this solver.
inverse(reals)	Compute pseudos from reals.
modes	Returns list of all modes support by this geometry.
pseudo_axis_names	Returns list of all pseudos support by this geometry.
real_axis_names	Returns list of all reals support by this geometry.
refineLattice(reflections)	Return refined lattice parameters given reflections.
removeAllReflections()	Clears sample of all stored reflections.

forward() Contract

The forward() method appears at three layers, each with a distinct role and return type:

SolverBase.forward(pseudos)

Returns list[NamedFloatDict] — all valid real-axis solutions the backend engine can find for the given pseudo-axis values, geometry, and mode. A single-element list is a valid return value.

Core.forward(pseudos)

Calls the solver’s forward(), then applies constraint filtering to each solution. Returns the filtered list — the full set of candidate motor angle combinations that satisfy all constraints.

DiffractometerBase.forward(pseudos)

The ophyd.PseudoPositioner interface, called by motion commands during bluesky plans. Calls Core.forward(), then applies a solution picker to select one solution for motor motion. Returns a single NamedTuple.

When writing a solver, only SolverBase.forward() needs to be implemented. The number of solutions depends on the backend library’s capabilities. An empty list (or raising NoForwardSolutions) signals that no solution exists for the requested pseudo-axis values.

The four-stage forward pipeline

All three backend libraries (Hkl/Soleil, diffcalc, SPEC) follow the same pattern: the engine returns all theoretical solutions; post-processing stages then wrap, filter, and select. hklpy2 implements the same four stages. A solver adapter is responsible only for Stage 1; Stages 2–4 are handled by the hklpy2 Core and DiffractometerBase layers.

Four-stage forward() pipeline in hklpy2 (equivalent stages in SPEC and diffcalc shown in parentheses).

Backend Library Requirements

A Solver is an adapter for a backend computation library. The backend library must provide (or enable the adapter to implement) the following capabilities.

Required

Geometry-aware rotation chain.

The library must know the physical axis directions and stacking order for each geometry it supports. This is the irreducible foundation for all diffractometer calculations.

Forward transform (pseudos to reals).

Given pseudo-axis values, orientation matrix, and wavelength, compute real-axis angles. This is geometry- and mode-specific.

Inverse transform (reals to pseudos).

Given real-axis angles, lattice parameters, orientation matrix, and wavelength, compute pseudo-axis values.

UB matrix calculation.

Given two measured reflections (each with known pseudos, measured angles, and wavelength), compute the orientation matrix. This requires the geometry’s rotation chain to convert measured angles into lab-frame scattering vectors. calculate_UB(), forward(), and inverse() all depend on the same rotation chain and cannot be separated.

Reflection management.

Store and retrieve measured reflections for UB matrix calculation. The backend library must manage reflections because UB calculation consumes them — the solver adapter passes reflections through to the backend, not buffering them in the adapter layer.

Optional

The following capabilities enhance a solver but are not required. Solvers that lack these features remain valid — the Core layer handles their absence gracefully.

Lattice refinement.

Refine lattice parameters from multiple reflections. Solvers that lack this capability return None from refineLattice(); Core raises an informative error to the user.

Multi-solution enumeration.

Return multiple valid angle solutions for a given set of pseudo-axis values. A single-element list is a valid return from forward() (see forward() Contract).

Operating modes.

Named configurations (e.g., bisector, constant-phi) that define which axes will be modified by forward().

Design Rationale

The required capabilities above are coupled through the geometry’s rotation chain: the same axis definitions that drive forward() and inverse() are needed to compute lab-frame scattering vectors for calculate_UB(), and to manage the reflections that feed it. A library that can compute forward() and inverse() necessarily has the geometry knowledge to also compute calculate_UB(). A library that lacks this knowledge cannot serve as a complete hklpy2 solver backend.

This coupling is why these capabilities cannot be factored into SolverBase. A “generic” implementation would require embedding a full geometry engine — effectively becoming a backend library itself, violating the separation of concerns between the adapter layer and the computation engine.

The Solver should be a thin adapter: it translates SolverBase method calls into whatever the backend library needs. Computation, data management (including reflections), and transport (for remote backends) belong in the backend or its solver adapter, not in the base class.

Backend library APIs vary widely. For example, HklSolver.forward() calls engine.pseudo_axis_values_set() — a Hkl/Soleil GObject introspection binding that sets pseudo-axis values and returns a GeometryList of solutions as a side effect. The backend function name gives no indication it is computing forward solutions. This is exactly why the solver adapter exists: to present a consistent forward(pseudos) interface regardless of how the backend library exposes its capabilities.

Engineering Units System

Define your solver’s internal units via class constants:

• ANGLE_UNITS: Default “degrees”

• LENGTH_UNITS: Default “angstrom”

Example Reference

Compare with these Solver classes:

class	description
HklSolver	Full-featured (Linux x86_64 only)
NoOpSolver	No-operation (demonstration & testing)
ThTthSolver	Minimal pure-Python (demonstration)
TrivialSolver() [7]	Minimal requirements, non-functional (internal testing)

Notes

• hklpy2 identifies a Solver [4] as a plugin using Python’s entry point [5] support.

• All solvers must inherit from SolverBase which enforces a consistent interface.

• The Core class handles unit conversion between diffractometer and solver units.

• Solvers can be platform-specific (such as HklSolver which is C code compiled only for Linux x86_64 architectures).

• Consider using NoOpSolver or TrivialSolver() [7] as starting references for testing infrastructure.

Footnotes

[1]

The @abstractmethod decorator, from the Python standard library module abc, enforces that subclasses implement the decorated method. See @abstractmethod for more details or this tutorial.

[2]

Adapter pattern ( or wrapper) is a software design pattern. For more details, see this explanation.

[3]

The @classmethod_decorator decorator, from the Python standard library module abc, enforces that subclasses implement the decorated method. See @classmethod_decorator for more details.

[4]

Analysis of hklpy2 Solver backend

[5]

Entry Points: Entry points are a way for Python packages to advertise components they provide to be discovered and used by other packages at runtime.

[6]

Guide to Create a Python Project on GitHub.

[7] (1,2)

TrivialSolver(): Source code in the test suite.