document the support for constraints

[prjemian]

• close Constraints stack needs documentation #290
• close BUG: restore(configuration) should push constraints to stack #301

[prjemian]

During testing (and confirming user reports), the value and fit parameters have no effect on the forward solutions. This needs further testing.

Marking this PR as draft for now.

[prjemian]

The diffractometer (engine) mode is used to hold an axis at a constant value for a forward(hkl) calculation. The Constraints value attribute:

Constant value to be used if held constant by forward mode.

[prjemian]

This comment describes the meaning of fit, but not in the context of forward() computations.

- Crystal lattice refinement
  - with more than 2 reflections you can select which parameter must
    be fitted.

Here are the places in libhkl source where fit_get appears and this parameter might be used:

(base) prjemian@arf:~/.../picca/hkl$ git grep fit_get
gui/hkl-gui.c:          fit = hkl_parameter_fit_get(p);                         \
gui/hkl-gui.c:          gboolean fit = hkl_parameter_fit_get(p);                \
hkl.h:HKLAPI int hkl_parameter_fit_get(const HklParameter *self) HKL_ARG_NONNULL(1);
hkl/hkl-parameter.c: * hkl_parameter_fit_get:
hkl/hkl-parameter.c:int hkl_parameter_fit_get(const HklParameter *self)
tests/hkl-axis-t.c:     ok(TRUE == hkl_parameter_fit_get(axis), __func__);
tests/hkl-axis-t.c:     ok(TRUE == hkl_parameter_fit_get(axis), __func__);
tests/hkl-axis-t.c:     ok(TRUE == hkl_parameter_fit_get(copy), __func__);
tests/hkl-axis-t.c:     ok(TRUE == hkl_parameter_fit_get(copy), __func__);

Not apparent it is used anywhere in the computation of forward(hkl) solutions.

[prjemian]

To avoid making a breaking change, by dropping this parameter altogether, consider these actions now:

• deprecate its use
• provide warning messages

[prjemian]

Confirmed with Fred Picca that the fit parameter is not used when calculating angles from h,k,l:

This interface was developped for the sample parameters a/b/c/alpha/beta/gamma/ux/uy/uz in order to fit the UB martix.
The parameter interface define a fit_get/set and since the axes derived from this interface, the functions are available, but of no use.

[prjemian]

@mrakitin @rodolakis @strempfer @padraic-shafer -- This is ready for review now.

[padraic-shafer]

The updated documentation is helpful and clearer. Thanks for that!

(Btw, I skipped the SPEC docs in this review)

[mrakitin]

Looks good!
I have a suggestion about the .ipynb files rendering, which can be addressed in a separate PR.

[mrakitin]

The notebooks like this one are already rendered, which makes it hard to review as there are huge image diffs there. I think we can use https://github.com/kynan/nbstripout and auto-render the notebooks during the sphinx docs building process using https://nbsphinx.readthedocs.io/en/0.9.3/.