From 96ebf8e567c51329f792ecf7d1820aae45983b9a Mon Sep 17 00:00:00 2001 From: Doga Gursoy Date: Mon, 22 Jun 2026 09:03:13 +0300 Subject: [PATCH] docs(2-bm): fold the channel-cut energy-calibration answer (ENERGY-7) Staff confirmed (ENERGY-7, #256) that channel-cut crystal energy calibration is current 2-BM practice: a removable reference crystal (36 x 3 mm, 2d = 3.84 angstrom, consistent with Si(220)) mounted on the sample rotation stage in place of the sample, rocked through its Bragg peak to recover the true beam energy. CORA already models the operation (the energy_characterization Procedure + the crystal as a calibration Subject). This folds the confirmation: - adds the missing energy_characterization Method to the catalog (capability characterization; it was referenced by the site practice but absent from catalog.yaml); - drops pending on the 2BM_energy_characterization_practice (confirmed current practice); - records the crystal identity (Si(220), 2d, dimensions, removable) in the procedures Energy section. Leaves ENERGY-7 OPEN on a residual the answer surfaced: it names the rocking stage as an Aerotech ABRS-150MP, but CORA's Rotary is an ABRS-250MP (datasheet-confirmed, #164). Reframed the question row to that stage-model confirm plus explicit Si(220) and re-run cadence, rather than silently overriding the well-sourced 250MP. Addresses ENERGY-7 (#256). Co-Authored-By: Claude Opus 4.8 --- catalog/catalog.yaml | 4 ++++ deployments/aps/site.yaml | 2 +- docs/deployments/2-bm/procedures.md | 2 +- docs/deployments/2-bm/questions.md | 2 +- 4 files changed, 7 insertions(+), 3 deletions(-) diff --git a/catalog/catalog.yaml b/catalog/catalog.yaml index 26cdcc6dbb..7fdb723f64 100644 --- a/catalog/catalog.yaml +++ b/catalog/catalog.yaml @@ -157,6 +157,10 @@ methods: capability: cora.capability.characterization purpose: "Pre-step measuring motor-sensitivity constants empirically (bump an axis by a known delta, observe centroid shift, K = shift/bump)." needed_families: [RotaryStage, LinearStage, Camera, Scintillator] + - name: energy_characterization + capability: cora.capability.characterization + purpose: "Energy calibration via a channel-cut crystal: rock a crystal of known 2d through its Bragg peak, fit the peak angle, recover the true beam energy, and re-save the corrected per-energy curve as a new revision (ENERGY-7)." + needed_families: [Monochromator, RotaryStage] - name: streaming_tomography capability: cora.capability.tomography purpose: "Live-reconstruction tomography supporting mid-flight adjust_run steering on observed reco quality." diff --git a/deployments/aps/site.yaml b/deployments/aps/site.yaml index a43f6f10ff..b992b84294 100644 --- a/deployments/aps/site.yaml +++ b/deployments/aps/site.yaml @@ -48,7 +48,7 @@ practices: - {name: 2BM_multi_energy_practice, method: tomography} - {name: Per-objective focus variant, method: focus_alignment, pending: true, note: "Mitutoyo 1.1x / 2x / 10x objectives"} - {name: Per-objective resolution variant, method: resolution_alignment, pending: true, note: "Mitutoyo 1.1x / 2x / 10x objectives"} - - {name: 2BM_energy_characterization_practice, method: energy_characterization, pending: true} + - {name: 2BM_energy_characterization_practice, method: energy_characterization} - {name: 2BM_ioc_restart_practice, method: ioc_restart, pending: true} - {name: 2BM_mirror_recoat_practice, method: mirror_recoat_return, pending: true} diff --git a/docs/deployments/2-bm/procedures.md b/docs/deployments/2-bm/procedures.md index 124414cf0c..1122ef0d50 100644 --- a/docs/deployments/2-bm/procedures.md +++ b/docs/deployments/2-bm/procedures.md @@ -49,7 +49,7 @@ The others do not, and the difference is principled rather than accidental: `det `energy_setting` is the coordinating energy-change operation (the Procedure kind names the specific operation, distinct from the `cora.capability.energy_change` Capability code it realizes, as `motor_homing` sits under `maintenance`): given a target energy (a free keV value), it drives the energy-tracking optic axes together to their per-energy positions, reading each axis's [energy curve](inventory.md#energy-tracking-optic-axes). A Method declares the free-keV parameter; the Procedure expresses the coordinated move. Because the curves interpolate, an operator can request an energy between the configured saved points, not just the menu. The operator's `EnergyChange` Decision (modeled in the energy-change scenario) is the forward-looking justification; this Procedure is the motion record. The per-axis curve evaluation is now wired: the runtime interpolates a position for any requested energy (including a value between the saved points), and refuses an energy outside the calibrated range rather than clamping. Executing the coordinated move at the beamline still needs the deferred pieces tracked with the [energy curves](inventory.md#energy-tracking-optic-axes) (the per-facet constituent wiring and live EPICS dispatch; the real saved positions are now recorded), so today the Procedure records the move rather than driving it. -`energy_characterization` is the channel-cut-crystal energy calibration (staff-documented on the [docs2bm energy-calibration page](https://docs2bm.readthedocs.io/en/latest/source/ops/item_022.html)): rock a crystal of known lattice spacing through its Bragg peak, fit the peak angle, and apply Bragg's law to recover the true beam energy. When it completes, the operator re-saves the corrected per-energy positions as a new revision of the affected [energy curves](inventory.md#energy-tracking-optic-axes), appended with a `MeasuredSource` citing the Procedure; the fitted true energy is kept as logbook evidence. There is no separate energy offset (`ENERGY-8`): the beamline updates the saved `store_0` table directly (`energy add`), so the curve itself carries the corrected positions, and CORA models a recalibration as a new curve revision, preserving the prior revision as history. This is distinct from `energy_setting`: that operation *sets* the energy by driving the optic curves; this one *measures* whether the delivered energy matches the command, then updates the curve. Whether the channel-cut crystal is current 2-BM practice is `ENERGY-7`. The channel-cut crystal is the measuring tool, modeled as a calibration [Subject](experiment.md) like the resolution phantom, not a target Asset. +`energy_characterization` is the channel-cut-crystal energy calibration (staff-documented on the [docs2bm energy-calibration page](https://docs2bm.readthedocs.io/en/latest/source/ops/item_022.html)): rock a crystal of known lattice spacing through its Bragg peak, fit the peak angle, and apply Bragg's law to recover the true beam energy. When it completes, the operator re-saves the corrected per-energy positions as a new revision of the affected [energy curves](inventory.md#energy-tracking-optic-axes), appended with a `MeasuredSource` citing the Procedure; the fitted true energy is kept as logbook evidence. There is no separate energy offset (`ENERGY-8`): the beamline updates the saved `store_0` table directly (`energy add`), so the curve itself carries the corrected positions, and CORA models a recalibration as a new curve revision, preserving the prior revision as history. This is distinct from `energy_setting`: that operation *sets* the energy by driving the optic curves; this one *measures* whether the delivered energy matches the command, then updates the curve. Channel-cut calibration is confirmed current 2-BM practice (ENERGY-7): the crystal is a removable reference standard (36 x 3 mm, 2d = 3.84 angstrom, consistent with Si(220)) mounted on the sample rotation stage in place of the sample for the calibration. The channel-cut crystal is the measuring tool, modeled as a calibration [Subject](experiment.md) like the resolution phantom, not a target Asset. ### Staff-validated routines diff --git a/docs/deployments/2-bm/questions.md b/docs/deployments/2-bm/questions.md index 2db8b61c96..5c1224981c 100644 --- a/docs/deployments/2-bm/questions.md +++ b/docs/deployments/2-bm/questions.md @@ -102,7 +102,7 @@ On an energy change the DMM monochromator, its Bragg arms, and the tracking slit | ID | Priority | Question | CORA assumes | Already done? | Resolves | | --- | --- | --- | --- | --- | --- | -| ENERGY-7 | `Nice-to-have` | Is energy calibration via a channel-cut crystal current 2-BM practice, and which crystal (its lattice spacing 2d; the [calibration page](https://docs2bm.readthedocs.io/en/latest/source/ops/item_022.html) lists 3.84 angstrom)? Is the crystal a removable reference standard (CORA models it as a calibration Subject, like the resolution phantom) or installed equipment, and on what rotation stage is it rocked? | modelled as the `energy_characterization` Procedure with the crystal as a calibration Subject; current practice, crystal, and 2d unconfirmed | yes | [Procedures](procedures.md) | +| ENERGY-7 | `Nice-to-have` | Channel-cut energy calibration is confirmed current practice (2d = 3.84 angstrom, 36 x 3 mm removable crystal, modelled as a calibration Subject). Two residual confirms: (a) the answer names the rocking stage as an Aerotech **ABRS-150MP**, but CORA's `Rotary` is an **ABRS-250MP** (datasheet-confirmed, #164): is the crystal rocked on that same sample rotation stage, and is its model 150MP or 250MP? (b) explicit confirmation the crystal is **Si(220)** (only Si(220) matches 2d = 3.84) and how often calibration is re-run. | calibration + 2d + removable confirmed (#256); rocking-stage model (150 vs 250 MP) + Si(220) + re-run cadence open | partly | [Procedures](procedures.md) | ## Beam mode