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