refactor(#298) rename AdHocDiffractometer.azimuthal_reference -> azimuth

CHANGES.md

@@ -9,6 +9,19 @@ issue tracker.  The initial project development roadmap is documented here:
 ## Unreleased
 
 Note any unreleased items inside the comment here.  Not visible until release.
+
+### Added
+
+- `azimuth` property and constructor kwarg as canonical name. (#298)
+
+### Changed
+
+- `required_reference_vector` returns `"azimuth"` instead of `"azimuthal_reference"`. (#298)
+
+### Deprecated
+
+- `azimuthal_reference` property and kwarg; use `azimuth` instead. (#298)
+
 -->
 
 ## Release v0.11.1

docs/source/concepts.md

@@ -96,7 +96,7 @@ the geometry's basis dict.
 ``n_axis`` here is the **per-stage rotation axis** vector — internal
 to the stage definition.  It is **not** the same as ``n̂`` (written as
 the ``n_hat`` key in mode ``extras``, or as
-``g.surface_normal`` / ``g.azimuthal_reference`` on the geometry),
+``g.surface_normal`` / ``g.azimuth`` on the geometry),
 which is the *user-facing reference vector* required by surface and
 azimuthal modes.  See the {ref}`glossary <glossary>` entries for
 "n̂ (reference vector)" and "Stage rotation axis" for the full
@@ -527,12 +527,12 @@ vectors may be set:
 
 - **`surface_normal`** — direction perpendicular to the sample surface;
   used by incidence/exit angle functions and surface diffraction modes.
-- **`azimuthal_reference`** — direction defining ψ = 0; used by
+- **`azimuth`** — direction defining ψ = 0; used by
   `psi_angle` and `fixed_psi_*` modes.
 
 ```python
 g.surface_normal = (0, 0, 1)    # (001)-cut sample
-g.azimuthal_reference = (1, 0, 0)
+g.azimuth = (1, 0, 0)
 ```
 
 Vectors are stored as Miller indices and converted to the lab frame

docs/source/geometries/fourch.md

@@ -114,13 +114,13 @@ Override at run time with `g.modes["fixed_omega"].with_constraint_values(omega=.
 
 {class}`~ad_hoc_diffractometer.mode.ReferenceConstraint`:
 azimuthal angle ψ validation filter.
-Set ``g.azimuthal_reference = (h, k, l)`` before calling ``forward()``.
+Set ``g.azimuth = (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`.
 
 | | |
 |---|---|
-| **Extras (input)** | n̂ → set `g.azimuthal_reference = (h, k, l)`; ψ target via `with_constraint_values(psi=...)` |
+| **Extras (input)** | n̂ → set `g.azimuth = (h, k, l)`; ψ target via `with_constraint_values(psi=...)` |
 | **Extras (output)** | psi (computed azimuth) |
 
 ### `double_diffraction`

docs/source/geometries/fourcv.md

@@ -114,13 +114,13 @@ Override at run time with `g.modes["fixed_omega"].with_constraint_values(omega=.
 
 {class}`~ad_hoc_diffractometer.mode.ReferenceConstraint`:
 azimuthal angle ψ validation filter.
-Set ``g.azimuthal_reference = (h, k, l)`` before calling ``forward()``.
+Set ``g.azimuth = (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`.
 
 | | |
 |---|---|
-| **Extras (input)** | n̂ → set `g.azimuthal_reference = (h, k, l)`; ψ target via `with_constraint_values(psi=...)` |
+| **Extras (input)** | n̂ → set `g.azimuth = (h, k, l)`; ψ target via `with_constraint_values(psi=...)` |
 | **Extras (output)** | psi (computed azimuth) |
 
 ### `double_diffraction`

docs/source/geometries/kappa4ch.md

@@ -175,14 +175,14 @@ Override at run time with `g.modes["fixed_phi"].with_constraint_values(phi=...)`
 
 {class}`~ad_hoc_diffractometer.mode.ReferenceConstraint`:
 azimuthal angle ψ validation filter.
-Set ``g.azimuthal_reference = (h, k, l)`` before calling ``forward()``.
+Set ``g.azimuth = (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`.
 
 | | |
 |---|---|
-| **Extras (input)** | n̂ → set `g.azimuthal_reference = (h, k, l)`; ψ target via `with_constraint_values(psi=...)` |
+| **Extras (input)** | n̂ → set `g.azimuth = (h, k, l)`; ψ target via `with_constraint_values(psi=...)` |
 | **Extras (output)** | psi (computed azimuth) |
 
 ## API reference

docs/source/geometries/kappa4cv.md

@@ -185,15 +185,15 @@ Override at run time with `g.modes["fixed_phi"].with_constraint_values(phi=...)`
 
 {class}`~ad_hoc_diffractometer.mode.ReferenceConstraint`:
 azimuthal angle ψ validation filter.
-Set ``g.azimuthal_reference = (h, k, l)`` before calling ``forward()``.
+Set ``g.azimuth = (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`.
 
 | | |
 |---|---|
 | **Computed** | komega, kappa, kphi, ttheta |
-| **Extras (input)** | n̂ → set `g.azimuthal_reference = (h, k, l)`; ψ target via `with_constraint_values(psi=...)` |
+| **Extras (input)** | n̂ → set `g.azimuth = (h, k, l)`; ψ target via `with_constraint_values(psi=...)` |
 | **Extras (output)** | psi (computed azimuth) |
 
 ### `double_diffraction`

docs/source/geometries/kappa6c.md

@@ -173,7 +173,7 @@ Override at run time with `g.modes["fixed_nu"].with_constraint_values(nu=...)` 
 ### `fixed_psi_vertical`
 
 Vertical bisecting with azimuthal angle ψ validation.
-Set ``g.azimuthal_reference = (h, k, l)`` before calling ``forward()``.
+Set ``g.azimuth = (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`.
@@ -182,7 +182,7 @@ Override the ψ target at run time with `g.modes["fixed_psi_vertical"].with_cons
 |---|---|
 | **Computed** | komega, kappa, kphi, delta |
 | **Constant during** `forward()` | mu = 0, nu = 0 |
-| **Extras (input)** | n̂ → set `g.azimuthal_reference = (h, k, l)`; ψ target via `with_constraint_values(psi=...)` |
+| **Extras (input)** | n̂ → set `g.azimuth = (h, k, l)`; ψ target via `with_constraint_values(psi=...)` |
 | **Extras (output)** | psi (computed azimuth) |
 
 ### `double_diffraction_vertical`
@@ -245,14 +245,14 @@ Override at run time with `g.modes["fixed_delta"].with_constraint_values(delta=.
 
 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()``.
+Set ``g.azimuth = (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`.
 
 | | |
 |---|---|
 | **Computed** | mu, kappa, kphi, nu |
 | **Constant during** `forward()` | komega = 0, delta = 0 |
-| **Extras (input)** | n̂ → set `g.azimuthal_reference = (h, k, l)`; ψ target via `with_constraint_values(psi=...)` |
+| **Extras (input)** | n̂ → set `g.azimuth = (h, k, l)`; ψ target via `with_constraint_values(psi=...)` |
 | **Extras (output)** | psi (computed azimuth) |
 
 ### `double_diffraction_horizontal`

docs/source/geometries/psic.md

@@ -150,7 +150,7 @@ 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
+validation.  Set ``g.azimuth = (h, k, l)`` before calling
 ``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
@@ -164,7 +164,7 @@ validated ψ.  See {doc}`../howto/surface`.
 |---|---|
 | **Computed** | eta, chi, phi, delta |
 | **Constant during** `forward()` | nu = 0, mu = constraint value, ψ = target |
-| **Extras (input)** | n̂ → set `g.azimuthal_reference = (h, k, l)`; ψ target via `with_constraint_values(psi=...)` |
+| **Extras (input)** | n̂ → set `g.azimuth = (h, k, l)`; ψ target via `with_constraint_values(psi=...)` |
 | **Extras (output)** | psi (computed azimuth) |
 
 ### `fixed_alpha_i_fixed_chi_fixed_phi`
@@ -349,7 +349,7 @@ Override the eta pin or the psi target at run time with `g.modes["fixed_psi_hori
 |---|---|
 | **Computed** | mu, chi, phi, nu |
 | **Constant during** `forward()` | delta = 0, eta = constraint value, ψ = target |
-| **Extras (input)** | n̂ → set `g.azimuthal_reference = (h, k, l)`; ψ target via `with_constraint_values(psi=...)` |
+| **Extras (input)** | n̂ → set `g.azimuth = (h, k, l)`; ψ target via `with_constraint_values(psi=...)` |
 | **Extras (output)** | psi |
 
 ### `fixed_omega_horizontal`

docs/source/glossary.md

@@ -19,15 +19,18 @@ Azimuthal reference vector
    The reciprocal-space direction (Miller indices
    ``(h, k, l)``) about which the azimuthal angle **ψ** is measured.
    Stored on the geometry as
-   {attr}`~ad_hoc_diffractometer.diffractometer.AdHocDiffractometer.azimuthal_reference`
+   {attr}`~ad_hoc_diffractometer.diffractometer.AdHocDiffractometer.azimuth`
    and consumed by the ``"psi"`` and ``"naz"``
    {class}`~ad_hoc_diffractometer.mode.ReferenceConstraint` modes.
-   Set with ``g.azimuthal_reference = (h, k, l)`` (a length-3 sequence
+   Set with ``g.azimuth = (h, k, l)`` (a length-3 sequence
    of numbers; ``(0, 0, 0)`` is rejected).  Default is ``None``.  In
    per-mode ``Extras (input)`` tables this same vector is referred to
    by its mathematical symbol **n̂** (rendered as the ``n_hat`` key in
    ``mode.extras``).  See {term}`n̂ (reference vector)` for the full
-   surface-form table, and {doc}`howto/surface`.
+   surface-form table, and {doc}`howto/surface`.  The attribute was
+   named ``azimuthal_reference`` before v0.12.0 (issue #298); the old
+   name remains as a deprecated forwarding alias and will be removed
+   in a future release.
 
 B matrix
    The matrix that encodes the reciprocal lattice and maps Miller indices
@@ -218,14 +221,14 @@ n̂ (reference vector)
           ``g.surface_normal = (h, k, l)``.
       * - On the geometry, when used by ``"psi"`` or ``"naz"``
           reference constraints
-        - {attr}`~ad_hoc_diffractometer.diffractometer.AdHocDiffractometer.azimuthal_reference`
+        - {attr}`~ad_hoc_diffractometer.diffractometer.AdHocDiffractometer.azimuth`
         - The actual stored vector.  Set via
-          ``g.azimuthal_reference = (h, k, l)``.
+          ``g.azimuth = (h, k, l)``.
 
    **Which attribute does the active mode need?** Use
    {attr}`~ad_hoc_diffractometer.diffractometer.AdHocDiffractometer.required_reference_vector`
    to ask the geometry directly — it returns
-   ``"surface_normal"``, ``"azimuthal_reference"``, or ``None`` based
+   ``"surface_normal"``, ``"azimuth"``, or ``None`` based
    on the active mode's reference constraint.
 
    **Not to be confused with** the {term}`Stage rotation axis` (the

docs/source/howto/constraints.md

@@ -309,19 +309,19 @@ print(cs.extras)
 Modes whose constraint patterns do not yet have a solver implementation
 return `False` from `is_implemented()` and raise `NotImplementedError`
 when `forward()` is called.  Some modes require a prerequisite to be
-set on the geometry (e.g. ``azimuthal_reference`` for psi modes,
+set on the geometry (e.g. ``azimuth`` for psi modes,
 ``surface_normal`` for surface modes) — they are considered stubs until
 the prerequisite is met:
 
 ```python
 g = ahd.make_geometry("fourcv")
 g.mode_name = "fixed_psi"
 
-# Without azimuthal_reference: not implemented
+# Without azimuth: not implemented
 print(g.modes["fixed_psi"].is_implemented(g))  # False
 
-# With azimuthal_reference: implemented
-g.azimuthal_reference = (0, 0, 1)
+# With azimuth: implemented
+g.azimuth = (0, 0, 1)
 print(g.modes["fixed_psi"].is_implemented(g))  # True
 ```
 

docs/source/howto/forward.md

@@ -162,7 +162,7 @@ Attributes: `solution_index`, `constraint_repr`, `residual`, `tolerance`.
 ### NotImplementedError
 
 Raised when the active mode is `None` or its `is_implemented(geometry)`
-returns `False` (e.g. a prerequisite like ``azimuthal_reference`` or
+returns `False` (e.g. a prerequisite like ``azimuth`` or
 ``surface_normal`` is not set):
 
 ```python
@@ -172,9 +172,9 @@ try:
 except NotImplementedError as e:
     print(e)
 
-# fixed_psi requires azimuthal_reference to be set
+# fixed_psi requires azimuth to be set
 g.mode_name = "fixed_psi"
-g.azimuthal_reference = None
+g.azimuth = None
 try:
     g.forward(1, 0, 0)
 except NotImplementedError as e:

docs/source/howto/fourcv_alignment_howto.ipynb

@@ -909,7 +909,7 @@
    ],
    "source": [
     "# Set the azimuthal reference to the c-axis (conventional for surface work)\n",
-    "g.azimuthal_reference = (0, 0, 1)\n",
+     "g.azimuth = (0, 0, 1)\n",
     "\n",
     "# pa() prints the full SPEC-style diffractometer status\n",
     "g.pa(print=True)"
@@ -1022,7 +1022,7 @@
     "- **Refine lattice constants** from several measured 2θ values with\n",
     "  `ahd.refine_lattice_bl1967()` or `ahd.refine_lattice_simplex()`.\n",
     "- **Compute the azimuthal angle ψ** with `g.psi()` once the UB matrix\n",
-    "  is fully refined (requires `g.azimuthal_reference` to be set).\n",
+     "  is fully refined (requires `g.azimuth` to be set).\n",
     "- **Save and restore the alignment** with `g.to_dict()` / `g.from_dict()`,\n",
     "  which serialises the full state (lattice, reflections, UB matrix,\n",
     "  wavelength, modes, cut-points) to a JSON-compatible dict."
@@ -1075,7 +1075,7 @@
      "output_type": "stream",
      "text": [
       "Keys in saved alignment state:\n",
-      "['name', 'description', 'wavelength', 'kappa_alpha_deg', 'azimuthal_reference', 'surface_normal', 'detector_distance', 'detector_tilt', 'detector_offset', 'inclination_matrix', 'basis', 'stages', 'active_sample', 'samples', 'modes', 'mode_name', 'cut_points']\n",
+      "['name', 'description', 'wavelength', 'kappa_alpha_deg', 'azimuth', 'surface_normal', 'detector_distance', 'detector_tilt', 'detector_offset', 'inclination_matrix', 'basis', 'stages', 'active_sample', 'samples', 'modes', 'mode_name', 'cut_points']\n",
       "\n",
       "JSON-serialisable: True\n",
       "\n",

docs/source/howto/modes.md

@@ -139,13 +139,13 @@ print(cs.is_implemented(g))
 ## Check if a mode is implemented
 
 Some modes require a prerequisite on the geometry.  For example,
-`fixed_psi` requires ``g.azimuthal_reference`` to be set:
+`fixed_psi` requires ``g.azimuth`` to be set:
 
 ```python
 g.mode_name = "fixed_psi"
-print(g.modes["fixed_psi"].is_implemented(g))  # False (no azimuthal_reference)
+print(g.modes["fixed_psi"].is_implemented(g))  # False (no azimuth)
 
-g.azimuthal_reference = (0, 0, 1)
+g.azimuth = (0, 0, 1)
 print(g.modes["fixed_psi"].is_implemented(g))  # True
 
 # forward() raises NotImplementedError for unimplemented modes