Ways to Specify Real and Pseudo Axis Positions#

hklpy2 accepts several equivalent forms when specifying axis positions to forward(), inverse(), forward(), inverse(), add_reflection(), and related methods.

The examples use an E4CV diffractometer restored from a saved configuration:

import hklpy2
sim = hklpy2.simulator_from_config("e4cv-config.yml")

Pseudo axis positions (for `diffractometer.forward()`)#

Pseudo axes are the reciprocal-space coordinates (h, k, l for an HKL geometry).

Pass values in the order the solver expects (h, k, l for E4CV):

sim.forward(1, 0, 0)

Name each axis explicitly — order does not matter:

sim.forward(h=1, k=0, l=0)
sim.forward(l=0, h=1, k=0)   # same result

Pass a dict mapping axis names to values:

sim.forward({"h": 1, "k": 0, "l": 0})

Use the diffractometer’s PseudoPosition named tuple:

pp = sim.PseudoPosition(h=1, k=0, l=0)
sim.forward(pp)

Values are mapped positionally in solver order (h, k, l):

sim.forward((1, 0, 0))

Real axis positions (for `diffractometer.inverse()`)#

Real axes are the physical motor angles (omega, chi, phi, tth for E4CV).

Pass values in the order the solver expects:

sim.inverse(-145, 0, 0, 69)

Name each axis explicitly:

sim.inverse(omega=-145, chi=0, phi=0, tth=69)

Pass a dict mapping axis names to values:

sim.inverse({"omega": -145, "chi": 0, "phi": 0, "tth": 69})

Use the diffractometer’s RealPosition named tuple:

rp = sim.RealPosition(omega=-145, chi=0, phi=0, tth=69)
sim.inverse(rp)

Values are mapped positionally in solver order (omega, chi, phi, tth):

sim.inverse((-145, 0, 0, 69))

Lower-level: `core.forward()` and `core.inverse()`#

The forward() and inverse() methods on the core object are lower-level and behave differently:

core.forward() returns all solutions as a list (unfiltered by constraints or the forward-solution picker).
core.inverse() returns a plain dict (not a named tuple).
Positional args and keyword args are not accepted.

Not available for core.forward() or core.inverse().

# forward — returns all solutions
solutions = sim.core.forward({"h": 1, "k": 0, "l": 0})

# inverse — returns a dict
hkl = sim.core.inverse({"omega": -145, "chi": 0, "phi": 0, "tth": 69})

# forward
pp = sim.PseudoPosition(h=1, k=0, l=0)
solutions = sim.core.forward(pp)

# inverse
rp = sim.RealPosition(omega=-145, chi=0, phi=0, tth=69)
hkl = sim.core.inverse(rp)

Values are mapped positionally in solver order:

# forward: (h, k, l)
solutions = sim.core.forward((1, 0, 0))

# inverse: (omega, chi, phi, tth)
hkl = sim.core.inverse((-145, 0, 0, 69))

Use diffractometer.forward() and diffractometer.inverse() for everyday work — they apply constraints, pick the best solution, and return named tuples. Use core.forward() when you need access to all solutions before filtering.

Reflections: `core.add_reflection()`#

add_reflection() accepts Dictionary, Named tuple, and Bare tuple for both the pseudo (hkl) and real (motor angles) position arguments — Positional args and Keyword args are not available:

# Dictionary (recommended)
sim.core.add_reflection(
    dict(h=4, k=0, l=0),
    dict(omega=-145.451, chi=0, phi=0, tth=69.066),
)

# Named tuple
sim.core.add_reflection(
    sim.PseudoPosition(h=4, k=0, l=0),
    sim.RealPosition(omega=-145.451, chi=0, phi=0, tth=69.066),
)

# Bare tuple (positionally mapped in solver order)
sim.core.add_reflection((4, 0, 0), (-145.451, 0, 0, 69.066))

Reflections: `user.setor()` / `user.add_reflection()`#

The setor() function (also aliased as add_reflection()) has a distinct and more flexible interface. Pseudo positions are always Positional args (h, k, l). Real positions can be provided in three ways:

Real positions in solver order, appended after h, k, l:

from hklpy2.user import setor
setor(4, 0, 0, -145.451, 0, 0, 69.066)

Real positions as named keyword arguments — any order:

from hklpy2.user import setor
setor(4, 0, 0, omega=-145.451, chi=0, phi=0, tth=69.066)

Not available for setor()/user.add_reflection().

When no real positions are given, the current motor positions are used:

from hklpy2.user import setor
setor(4, 0, 0)   # uses current omega, chi, phi, tth

Which form to use#

Method	Positional args	Keyword args	Dictionary	Named tuple	Bare tuple
`diffractometer.forward()`	✓	✓	✓	✓	✓
`diffractometer.inverse()`	✓	✓	✓	✓	✓
`core.forward()`	✗	✗	✓	✓	✓
`core.inverse()`	✗	✗	✓	✓	✓
`core.add_reflection()`	✗	✗	✓	✓	✓
`user.setor()`	✓ (reals)	✓ (reals)	✗	✗	✗

Ways to Specify Real and Pseudo Axis Positions#

Pseudo axis positions (for diffractometer.forward())#

Real axis positions (for diffractometer.inverse())#

Lower-level: core.forward() and core.inverse()#

Reflections: core.add_reflection()#

Reflections: user.setor() / user.add_reflection()#