How to Use Extras#

Some solver modes define extras: optional named parameters that are not part of the diffractometer’s real or pseudo axes, but still affect solver calculations. This guide shows how to inspect and change them through extras.

Setup#

Create a simulated K6C diffractometer and choose a mode with extras:

>>> import hklpy2
>>> k6c = hklpy2.creator(name="k6c", geometry="K6C", solver="hkl_soleil")
>>> k6c.core.mode = "constant_incidence"
>>> k6c.core.extras
{'x': 0.0, 'y': 0.0, 'z': 0.0, 'incidence': 0.0, 'azimuth': 0.0}

Reading extras#

The getter returns a dictionary-like view of the extras available in the current mode:

>>> k6c.core.extras
{'x': 0.0, 'y': 0.0, 'z': 0.0, 'incidence': 0.0, 'azimuth': 0.0}
>>> k6c.core.extras["x"]
0.0
>>> list(k6c.core.extras)
['x', 'y', 'z', 'incidence', 'azimuth']

Setting one extra#

Set a single extra by key assignment:

>>> k6c.core.extras["x"] = 0.5
>>> k6c.core.extras["x"]
0.5

Unknown names are rejected:

>>> k6c.core.extras["invalid_key"] = 0.5
Traceback (most recent call last):
  ...
ConfigurationError: Unexpected extra axis name(s) ['invalid_key'].
  Expected names: {'x': 0, 'y': 0, 'z': 0, 'incidence': 0, 'azimuth': 0}.

Setting several extras at once#

Use update() to change multiple extras together:

>>> k6c.core.extras.update({"x": 0.5, "y": 0.25})
>>> k6c.core.extras
{'x': 0.5, 'y': 0.25, 'z': 0.0, 'incidence': 0.0, 'azimuth': 0.0}

Keyword arguments are supported too:

>>> k6c.core.extras.update(x=0.1, y=0.2)
>>> k6c.core.extras
{'x': 0.1, 'y': 0.2, 'z': 0.0, 'incidence': 0.0, 'azimuth': 0.0}

If any supplied key is invalid, the update is rejected before any change is applied:

>>> k6c.core.extras.update(x=0.5, invalid_key=0.1)
Traceback (most recent call last):
  ...
ConfigurationError: Unexpected extra axis name(s) ['invalid_key'].
  Expected names: {'x': 0, 'y': 0, 'z': 0, 'incidence': 0, 'azimuth': 0}.

Compatibility with whole-dict assignment#

The existing setter still works:

>>> k6c.core.extras = {"x": 0.5, "y": 0.25}
>>> k6c.core.extras
{'x': 0.5, 'y': 0.25, 'z': 0.0, 'incidence': 0.0, 'azimuth': 0.0}

This is useful when you already have a dictionary of values and want to apply it in one step.

Resetting extras#

Use clear() to reset every extra in the current mode to its default value (0.0):

>>> k6c.core.extras.update(x=0.5, y=0.25, z=0.1)
>>> k6c.core.extras.clear()
>>> k6c.core.extras
{'x': 0.0, 'y': 0.0, 'z': 0.0, 'incidence': 0.0, 'azimuth': 0.0}

clear() is also safe when the mode has no extras.

What `setdefault()` does here#

Extras are pre-populated for the current mode, so setdefault() usually returns the value that is already present:

>>> k6c.core.extras.setdefault("x", 1.0)
0
>>> k6c.core.extras["x"]
0.0

In other words, setdefault() follows normal dictionary semantics, but the keys already exist in the extras view for the active mode.

What `pop()` does here#

pop() only removes a key from the temporary dictionary view you accessed; it does not delete the underlying extra from Core state:

>>> extras = k6c.core.extras
>>> extras["x"] = 0.5
>>> extras.pop("x")
0.5
>>> "x" in extras
False
>>> k6c.core.extras["x"]
0.5

This is intentional: the set of extras for a mode is defined by the solver and is not user-removable.

Deletion is forbidden#

Explicit deletion with del is not allowed:

>>> del k6c.core.extras["x"]
Traceback (most recent call last):
  ...
TypeError: Deletion of extras is not allowed.

Modes with no extras#

Some modes expose no extras at all:

>>> e4cv = hklpy2.creator(name="e4cv", geometry="E4CV")
>>> e4cv.core.mode = "bissector"
>>> e4cv.core.extras
{}

You may still read the empty dict or call methods such as clear() and update({}) on it.