How to write a new Solver#

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

Steps#

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.
`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.

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.