fix(#293) add ConstraintSet.with_constraint_values and document fixed-axis overrides

CHANGES.md

@@ -13,6 +13,11 @@ Note any unreleased items inside the comment here.  Not visible until release.
 ### Added
 
 - `register_geometry_yaml` in-memory registration entry point. (#288)
+- `ConstraintSet.with_constraint_values()` one-call value override. (#293)
+
+### Changed
+
+- Document how to override fixed-axis constraint values. (#293)
 
 ### Fixed
 

docs/source/geometries/fivec.md

@@ -86,8 +86,7 @@ Reduces to standard four-circle bisecting geometry.
 {class}`~ad_hoc_diffractometer.mode.SampleConstraint` × 2:
 `mu = 0`.
 `chi` is held at the value declared in the constraint (default in the demo geometry: 90°).
-The caller chooses the value by constructing a {class}`~ad_hoc_diffractometer.mode.ConstraintSet`; the constraint
-persists until replaced — see {doc}`../howto/constraints`.
+Override at run time with `g.modes["fixed_chi"].with_constraint_values(chi=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|
@@ -99,7 +98,7 @@ persists until replaced — see {doc}`../howto/constraints`.
 {class}`~ad_hoc_diffractometer.mode.SampleConstraint` × 2:
 `mu = 0`.
 `phi` is held at the value declared in the constraint (default in the demo geometry: 0°).
-The caller chooses the value by constructing a {class}`~ad_hoc_diffractometer.mode.ConstraintSet`.
+Override at run time with `g.modes["fixed_phi"].with_constraint_values(phi=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|
@@ -111,7 +110,7 @@ The caller chooses the value by constructing a {class}`~ad_hoc_diffractometer.mo
 {class}`~ad_hoc_diffractometer.mode.SampleConstraint` + {class}`~ad_hoc_diffractometer.mode.BisectConstraint`:
 `omega = ttheta / 2`.
 `mu` is held at the value declared in the constraint (default in the demo geometry: 0°).
-The caller chooses the value by constructing a {class}`~ad_hoc_diffractometer.mode.ConstraintSet`.
+Override at run time with `g.modes["fixed_mu"].with_constraint_values(mu=...)` — see {doc}`../howto/constraints`.
 Intended for non-zero mu once the tilted-plane solver is implemented.
 
 | | |
@@ -124,7 +123,7 @@ Intended for non-zero mu once the tilted-plane solver is implemented.
 {class}`~ad_hoc_diffractometer.mode.SampleConstraint` × 2:
 `mu = 0`.
 `omega` is held at the value declared in the constraint (default in the demo geometry: 0°).
-The caller chooses the value by constructing a {class}`~ad_hoc_diffractometer.mode.ConstraintSet`.
+Override at run time with `g.modes["fixed_omega_noncoplanar"].with_constraint_values(omega=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|

docs/source/geometries/fourch.md

@@ -81,8 +81,7 @@ Places the sample symmetrically between the incident and diffracted beams.
 
 {class}`~ad_hoc_diffractometer.mode.SampleConstraint`:
 `chi` is held at the value declared in the constraint (default in the demo geometry: 90°).
-The caller chooses the value by constructing a {class}`~ad_hoc_diffractometer.mode.ConstraintSet`; the constraint
-persists until replaced — see {doc}`../howto/constraints`.
+Override at run time with `g.modes["fixed_chi"].with_constraint_values(chi=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|
@@ -93,7 +92,7 @@ persists until replaced — see {doc}`../howto/constraints`.
 
 {class}`~ad_hoc_diffractometer.mode.SampleConstraint`:
 `phi` is held at the value declared in the constraint (default in the demo geometry: 0°).
-The caller chooses the value by constructing a {class}`~ad_hoc_diffractometer.mode.ConstraintSet`.
+Override at run time with `g.modes["fixed_phi"].with_constraint_values(phi=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|
@@ -104,7 +103,7 @@ The caller chooses the value by constructing a {class}`~ad_hoc_diffractometer.mo
 
 {class}`~ad_hoc_diffractometer.mode.SampleConstraint`:
 `omega` is held at the value declared in the constraint (default in the demo geometry: 0°).
-The caller chooses the value by constructing a {class}`~ad_hoc_diffractometer.mode.ConstraintSet`.
+Override at run time with `g.modes["fixed_omega"].with_constraint_values(omega=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|

docs/source/geometries/fourcv.md

@@ -81,8 +81,7 @@ Places the sample symmetrically between the incident and diffracted beams.
 
 {class}`~ad_hoc_diffractometer.mode.SampleConstraint`:
 `chi` is held at the value declared in the constraint (default in the demo geometry: 90°).
-The caller chooses the value by constructing a {class}`~ad_hoc_diffractometer.mode.ConstraintSet`; the constraint
-persists until replaced — see {doc}`../howto/constraints`.
+Override at run time with `g.modes["fixed_chi"].with_constraint_values(chi=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|
@@ -93,7 +92,7 @@ persists until replaced — see {doc}`../howto/constraints`.
 
 {class}`~ad_hoc_diffractometer.mode.SampleConstraint`:
 `phi` is held at the value declared in the constraint (default in the demo geometry: 0°).
-The caller chooses the value by constructing a {class}`~ad_hoc_diffractometer.mode.ConstraintSet`.
+Override at run time with `g.modes["fixed_phi"].with_constraint_values(phi=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|
@@ -104,7 +103,7 @@ The caller chooses the value by constructing a {class}`~ad_hoc_diffractometer.mo
 
 {class}`~ad_hoc_diffractometer.mode.SampleConstraint`:
 `omega` is held at the value declared in the constraint (default in the demo geometry: 0°).
-The caller chooses the value by constructing a {class}`~ad_hoc_diffractometer.mode.ConstraintSet`.
+Override at run time with `g.modes["fixed_omega"].with_constraint_values(omega=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|

docs/source/geometries/kappa4ch.md

@@ -134,6 +134,7 @@ decomposition.
 
 {class}`~ad_hoc_diffractometer.mode.SampleConstraint`:
 `kphi` held at declared value (default 0°) — real stage, no kappa inversion needed.
+Override at run time with `g.modes["fixed_kphi"].with_constraint_values(kphi=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|
@@ -143,6 +144,7 @@ decomposition.
 ### `fixed_omega`
 
 Fix virtual Eulerian omega at declared value (default 0°) — see {doc}`kappa4cv` for details.
+Override at run time with `g.modes["fixed_omega"].with_constraint_values(omega=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|
@@ -152,6 +154,7 @@ Fix virtual Eulerian omega at declared value (default 0°) — see {doc}`kappa4c
 ### `fixed_chi`
 
 Fix virtual Eulerian chi at declared value (default 90°).
+Override at run time with `g.modes["fixed_chi"].with_constraint_values(chi=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|
@@ -161,6 +164,7 @@ Fix virtual Eulerian chi at declared value (default 90°).
 ### `fixed_phi`
 
 Fix virtual Eulerian phi at declared value (default 0°).
+Override at run time with `g.modes["fixed_phi"].with_constraint_values(phi=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|
@@ -174,6 +178,7 @@ azimuthal angle ψ validation filter.
 Set ``g.azimuthal_reference = (h, k, l)`` before calling ``forward()``.
 Returns bisecting solutions only when the natural ψ for (h,k,l) matches
 the stored target.  See {doc}`../howto/surface`.
+Override the ψ target at run time with `g.modes["fixed_psi"].with_constraint_values(psi=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|

docs/source/geometries/kappa4cv.md

@@ -140,7 +140,7 @@ decomposition.
 
 {class}`~ad_hoc_diffractometer.mode.SampleConstraint`:
 `kphi` held at declared value (default 0°) — real stage, no kappa inversion needed.
-The caller chooses the value by constructing a {class}`~ad_hoc_diffractometer.mode.ConstraintSet`.
+Override at run time with `g.modes["fixed_kphi"].with_constraint_values(kphi=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|
@@ -151,9 +151,8 @@ The caller chooses the value by constructing a {class}`~ad_hoc_diffractometer.mo
 
 {class}`~ad_hoc_diffractometer.mode.SampleConstraint`:
 Fix the virtual Eulerian omega at declared value (default 0°).
-Solved analytically via the equivalent-Eulerian dispatch — the
-caller chooses the value by constructing a
-{class}`~ad_hoc_diffractometer.mode.ConstraintSet`.
+Solved analytically via the equivalent-Eulerian dispatch.
+Override at run time with `g.modes["fixed_omega"].with_constraint_values(omega=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|
@@ -164,7 +163,7 @@ caller chooses the value by constructing a
 
 {class}`~ad_hoc_diffractometer.mode.SampleConstraint`:
 Fix the virtual Eulerian chi at declared value (default 90°).
-The caller chooses the value by constructing a {class}`~ad_hoc_diffractometer.mode.ConstraintSet`.
+Override at run time with `g.modes["fixed_chi"].with_constraint_values(chi=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|
@@ -175,7 +174,7 @@ The caller chooses the value by constructing a {class}`~ad_hoc_diffractometer.mo
 
 {class}`~ad_hoc_diffractometer.mode.SampleConstraint`:
 Fix the virtual Eulerian phi at declared value (default 0°).
-The caller chooses the value by constructing a {class}`~ad_hoc_diffractometer.mode.ConstraintSet`.
+Override at run time with `g.modes["fixed_phi"].with_constraint_values(phi=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|
@@ -189,6 +188,7 @@ azimuthal angle ψ validation filter.
 Set ``g.azimuthal_reference = (h, k, l)`` before calling ``forward()``.
 Returns bisecting solutions only when the natural ψ for (h,k,l) matches
 the stored target.  See {doc}`../howto/surface`.
+Override the ψ target at run time with `g.modes["fixed_psi"].with_constraint_values(psi=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|

docs/source/geometries/kappa6c.md

@@ -140,6 +140,7 @@ Vertical scattering plane (psic-style).
 
 {class}`~ad_hoc_diffractometer.mode.SampleConstraint`:
 `kphi` held at declared value (default 0°), `mu = 0`, `nu = 0`.
+Override at run time with `g.modes["fixed_kphi"].with_constraint_values(kphi=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|
@@ -150,6 +151,7 @@ Vertical scattering plane (psic-style).
 
 {class}`~ad_hoc_diffractometer.mode.SampleConstraint` + {class}`~ad_hoc_diffractometer.mode.BisectConstraint` + {class}`~ad_hoc_diffractometer.mode.DetectorConstraint`:
 `mu` held at declared value (default 0°), `komega = delta/2`, `nu = 0`.
+Override at run time with `g.modes["fixed_mu"].with_constraint_values(mu=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|
@@ -161,6 +163,7 @@ Vertical scattering plane (psic-style).
 {class}`~ad_hoc_diffractometer.mode.DetectorConstraint` + {class}`~ad_hoc_diffractometer.mode.BisectConstraint` + {class}`~ad_hoc_diffractometer.mode.SampleConstraint`:
 `nu` held at declared value (default 0°), `komega = delta/2`, `mu = 0`.
 Analogous to psic `fixed_nu`.
+Override at run time with `g.modes["fixed_nu"].with_constraint_values(nu=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|
@@ -173,6 +176,7 @@ Vertical bisecting with azimuthal angle ψ validation.
 Set ``g.azimuthal_reference = (h, k, l)`` before calling ``forward()``.
 The solver returns bisecting solutions only when the natural ψ for the
 requested (h,k,l) matches the stored target.  See {doc}`../howto/surface`.
+Override the ψ target at run time with `g.modes["fixed_psi_vertical"].with_constraint_values(psi=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|
@@ -230,6 +234,7 @@ Horizontal scattering plane.
 {class}`~ad_hoc_diffractometer.mode.DetectorConstraint` + {class}`~ad_hoc_diffractometer.mode.BisectConstraint` + {class}`~ad_hoc_diffractometer.mode.SampleConstraint`:
 `delta` held at declared value (default 0°), `mu = nu/2`, `komega = 0`.
 Horizontal plane with delta frozen.
+Override at run time with `g.modes["fixed_delta"].with_constraint_values(delta=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|
@@ -241,6 +246,7 @@ Horizontal plane with delta frozen.
 Horizontal bisecting with azimuthal angle ψ validation.
 Symmetric with `fixed_psi_vertical` in the horizontal plane.
 Set ``g.azimuthal_reference = (h, k, l)`` before calling ``forward()``.
+Override the ψ target at run time with `g.modes["fixed_psi_horizontal"].with_constraint_values(psi=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|

docs/source/geometries/psic.md

@@ -85,6 +85,7 @@ Vertical scattering plane bisecting condition (You 1999, §5.3).
 ### `fixed_phi_vertical`
 
 `phi` held at declared value (default 0°), `mu = 0`, `nu = 0`.
+Override at run time with `g.modes["fixed_phi_vertical"].with_constraint_values(phi=...)` — see {doc}`../howto/constraints`.
 The scattering plane is locked vertical by `mu = 0` and `nu = 0`;
 `eta`, `chi`, and `delta` are solved from the hkl equations.
 
@@ -96,7 +97,7 @@ The scattering plane is locked vertical by `mu = 0` and `nu = 0`;
 ### `fixed_chi_vertical`
 
 `chi` held at declared value (default 90°), `mu = 0`, `nu = 0`.
-The caller chooses the chi value by constructing a {class}`~ad_hoc_diffractometer.mode.ConstraintSet` — see {doc}`../howto/constraints`.
+Override at run time with `g.modes["fixed_chi_vertical"].with_constraint_values(chi=...)` — see {doc}`../howto/constraints`.
 The scattering plane is locked vertical by `mu = 0` and `nu = 0`;
 `eta`, `phi`, and `delta` are solved from the hkl equations.
 
@@ -109,6 +110,7 @@ The scattering plane is locked vertical by `mu = 0` and `nu = 0`;
 
 Incidence angle α_i fixed at declared value (default 0°) in the
 vertical scattering plane.
+Override at run time with `g.modes["fixed_alpha_i_vertical"].with_constraint_values(alpha_i=...)` — see {doc}`../howto/constraints`.
 Set ``g.surface_normal = (h, k, l)`` before calling ``forward()``.
 
 | | |
@@ -122,6 +124,7 @@ Set ``g.surface_normal = (h, k, l)`` before calling ``forward()``.
 
 Exit angle β_out fixed at declared value (default 0°) in the
 vertical scattering plane.
+Override at run time with `g.modes["fixed_beta_out_vertical"].with_constraint_values(beta_out=...)` — see {doc}`../howto/constraints`.
 Set ``g.surface_normal = (h, k, l)`` before calling ``forward()``.
 
 | | |
@@ -148,7 +151,9 @@ Set ``g.surface_normal = (h, k, l)`` before calling ``forward()``.
 Issue #264 revision.  Vertical scattering plane (`nu = 0`) with `mu`
 fixed at the user-specified value (default 0) and azimuthal angle ψ
 validation.  Set ``g.azimuthal_reference = (h, k, l)`` before calling
-``forward()``.  The previous bisect(`eta`, `delta`) constraint was
+``forward()``.
+Override the mu pin or the psi target at run time with `g.modes["fixed_psi_vertical"].with_constraint_values(mu=..., psi=...)` — see {doc}`../howto/constraints`.
+The previous bisect(`eta`, `delta`) constraint was
 dropped per the @jwkim-anl review.  The solver returns the
 fixed-sample solutions only when the natural ψ for the requested
 (h, k, l) matches the stored target; the free angles ``eta``, ``chi``,
@@ -170,6 +175,7 @@ are solved jointly from the Bragg condition plus the α_i target.
 This is a 4-D Newton solve that routes through the
 ``_solve_free_detectors`` solver (both detector stages float to lift
 the detector arm out of plane as needed).
+Override any of the three pinned values at run time with `g.modes["fixed_alpha_i_fixed_chi_fixed_phi"].with_constraint_values(chi=..., phi=..., alpha_i=...)` — see {doc}`../howto/constraints`.
 
 Set ``g.surface_normal = (h, k, l)`` before calling ``forward()``.
 
@@ -194,6 +200,7 @@ reduces exactly to ``bisecting_vertical`` (above) because OMEGA = 0
 ⇔ Q lies in the chi-circle plane ⇔ bisecting condition.  Non-zero
 targets tilt Q out of the chi-circle plane and are solved by a 1-D
 Newton refinement on the free outer sample stage (`eta`).
+Override the OMEGA target at run time with `g.modes["fixed_omega_vertical"].with_constraint_values(omega=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|
@@ -260,6 +267,7 @@ Horizontal scattering plane bisecting condition (You 1999, §5.1).
 ### `fixed_phi_horizontal`
 
 `phi` held at declared value (default 0°), `eta = 0`, `delta = 0`.
+Override at run time with `g.modes["fixed_phi_horizontal"].with_constraint_values(phi=...)` — see {doc}`../howto/constraints`.
 The scattering plane is locked horizontal by `eta = 0` and `delta = 0`;
 `mu`, `chi`, and `nu` are solved from the hkl equations.
 
@@ -271,6 +279,7 @@ The scattering plane is locked horizontal by `eta = 0` and `delta = 0`;
 ### `fixed_chi_horizontal`
 
 `chi` held at declared value (default 0°), `eta = 0`, `delta = 0`.
+Override at run time with `g.modes["fixed_chi_horizontal"].with_constraint_values(chi=...)` — see {doc}`../howto/constraints`.
 The scattering plane is locked horizontal by `eta = 0` and `delta = 0`;
 `mu`, `phi`, and `nu` are solved from the hkl equations.
 
@@ -291,6 +300,7 @@ is kinematically infeasible in this mode.
 
 Incidence angle α_i fixed at declared value (default 0°) in the
 horizontal scattering plane.
+Override at run time with `g.modes["fixed_alpha_i_horizontal"].with_constraint_values(alpha_i=...)` — see {doc}`../howto/constraints`.
 Set ``g.surface_normal = (h, k, l)`` before calling ``forward()``.
 
 | | |
@@ -304,6 +314,7 @@ Set ``g.surface_normal = (h, k, l)`` before calling ``forward()``.
 
 Exit angle β_out fixed at declared value (default 0°) in the
 horizontal scattering plane.
+Override at run time with `g.modes["fixed_beta_out_horizontal"].with_constraint_values(beta_out=...)` — see {doc}`../howto/constraints`.
 Set ``g.surface_normal = (h, k, l)`` before calling ``forward()``.
 
 | | |
@@ -332,6 +343,7 @@ Issue #264 revision.  Horizontal scattering plane (`delta = 0`) with
 angle ψ validation.  The previous bisect(`mu`, `nu`) constraint was
 dropped per the @jwkim-anl review.  Free angles `mu`, `chi`, `phi`,
 `nu` jointly satisfy the Bragg condition under the validated ψ.
+Override the eta pin or the psi target at run time with `g.modes["fixed_psi_horizontal"].with_constraint_values(eta=..., psi=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|
@@ -347,6 +359,7 @@ plane (`eta = 0`, `delta = 0`).  Same OMEGA pseudo-angle definition as
 ``fixed_omega_vertical`` above; at ``omega = 0`` the mode reduces
 exactly to ``bisecting_horizontal``.  The free outer sample stage
 rocked by the 1-D Newton is `mu`.
+Override the OMEGA target at run time with `g.modes["fixed_omega_horizontal"].with_constraint_values(omega=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|

docs/source/geometries/s2d2.md

@@ -69,9 +69,7 @@ See {doc}`../howto/constraints` for the constraint framework.
 {class}`~ad_hoc_diffractometer.mode.SampleConstraint`:
 `mu` held at declared value (default 0°) — the incidence angle when the
 surface normal is aligned.
-The caller chooses the value by constructing a
-{class}`~ad_hoc_diffractometer.mode.ConstraintSet` — see
-{doc}`../howto/constraints`.
+Override at run time with `g.modes["fixed_mu"].with_constraint_values(mu=...)` — see {doc}`../howto/constraints`.
 
 | | |
 |---|---|