ENERGY-7: channel-cut crystal calibration IS current practice;

[decarlof]

ENERGY-7: channel-cut crystal calibration IS current practice; 2d = 3.84 Å (consistent with Si (220)); 36 × 3 mm removable crystal mounted on the 2-BM-B sample-rotation stage (Aerotech ABRS-150MP) in place of the sample for the calibration; modelled correctly by cora as a calibration Subject

ENERGY-7: All four sub-questions answered. Cora's existing provisional answer is correct in shape; this ticket confirms each piece with operational details from the 2-BM docs.

Is calibration current practice?

Yes. Documented in two places that work together:

Doc	Role
ops/item_012 — Beamline alignment	Broader operational workflow: white-beam alignment → pink-beam tuning → DMM mono-beam setup. The energy-calibration step happens once the DMM mono beam is established at the end of this walk-through. Last line: *"For the full procedure to calibrate the DMM energy using a cha
nnel-cut crystal and multilayer tables, see ops-energy-calibration."*
ops/item_022 — Energy calibration	The focused 8-step recipe for the channel-cut rocking-curve calibration itself. Includes the formula derivations, mdaviz instructions for fitting the rocking-curve peak, and Python snippets for the angle ↔ energy conversion.

So energy calibration is a current, documented step in the standard beamline-alignment workflow at 2-BM. Operator confirmation worth getting: how often is this re-run in practice (every shutdown? every commissioning? quarterly? on operator suspicion of drift?).

Which crystal — 2d = 3.84 Å

From ops/item_022 lines 13-15:

• Length: 36 mm
• Width: 3 mm
• Lattice spacing (2d): 3.84 Å

So 2d = 3.84 Å is confirmed. This is consistent with Si (220) — Si lattice constant a = 5.4309 Å; for the (220) reflection d_220 = a / √8 = 1.92 Å, so 2d_220 = 3.840 Å ✓ to 3 significant figures.

Operator confirmation worth getting: explicit confirmation that the crystal is Si(220) (vs another material with that 2d). Common channel-cut crystals at synchrotrons are Si(111) (2d = 6.271 Å), Si(220) (2d = 3.840 Å), Si(311) (2d = 3.275 Å) — only Si(220) matches.

Removable reference standard, OR installed equipment?

Removable reference standard. The ops/item_022 procedure starts with:

"Mount the channel-cut crystal — Secure the channel-cut crystal on the rotation stage in the x-ray beam path."

This explicitly describes a per-calibration mount, not permanently installed hardware. Between calibrations the crystal lives off the beamline on its own kinematic mount.

Cora's framing as a calibration Subject — the same pattern as the resolution phantom — is correct. Operationally:

• The crystal occupies the sample slot for the duration of the calibration.
• A real sample cannot be in the beam during energy calibration.
• The crystal has its own provenance fields (length, width, 2d) but no per-beamline configuration of its own.

Which rotation stage is it rocked on?

The 2-BM-B sample-rotation stage — the Aerotech ABRS-150MP confirmed in STAGE-3 / cora#164. The same rotation stage that does tomography acquisitions is reused as the rocking axis for the energy calibration. The crystal is mounted in place of the sample on the sample tower (specifically on top of the rotation stage); no separate dedicate
d rocking hardware exists.

This is operator-inferred from ops/item_022 step 1 ("Secure the channel-cut crystal on the rotation stage in the x-ray beam path" — the only rotation stage in the x-ray beam path at 2-BM-B is the sample rotation) — worth explicit operator confirmation.

CORA-side application

Cora's existing model — energy_characterization Procedure with the crystal as a calibration Subject — can be promoted from provisional to confirmed. To complete the model:

• Calibration Subject: si_channel_cut_220 (proposed handle) with fields:
  • crystal_material: Si
  • reflection: (220) — operator-confirmation pending
  • two_d_angstrom: 3.84
  • length_mm: 36
  • width_mm: 3
  • mount_type: kinematic (removable; brought into the beam only for calibration)
• Procedure: energy_characterization Method with parameters:
  • nominal_energy_keV (default 20.0 per the ops walk-through)
  • rocking_range_deg, rocking_step_deg (operator-set; not standardised in the docs today)
• Rocking axis: the sample-rotation stage Asset (Aerotech ABRS-150MP, cora STAGE-3 / cora#164's SampleRotaryDrive). Reused; not a separate Asset.
• Output / postcondition: per-energy measured E_meas and offset = E_meas - nominal_energy_keV; cora can carry these as per-Run provenance (calibration_date, calibration_offset_keV per a study's nominal energy).
• Application of the offset: not addressed by this procedure itself. See [ENERGY-8 / cora#TBD] for whether the offset is folded back into energy2bm.json store_0 or applied as a runtime correction.

Downstream alignment

A formal procedure stub has been drafted at procedures/item_014 (energy_characterization), cross-linking to both ops/item_022 (focused recipe) and ops/item_012 (broader alignment context). The stub captures Devices, Preconditions, Parameters, Steps, Postconditions, and Failure modes in the cora-Proced
ure format, ready for a formal 2bm-procedures script implementation later.

Cross-references

• ENERGY-3 / cora#252 — saved-table mechanism (the calibrated energies in energy2bm.json are the artefacts produced by the calibration procedure described here).
• ENERGY-6 / cora#255 — DMM 24 Å stripe (ops/item_022's comparison table at the end uses d = 24 Å for calculated-vs-measured energies, consistent with ENERGY-6's finding that the 24 Å stripe is active).
• [ENERGY-8 / cora ENERGY-8: neither — there is no energy_offset state anywhere in the system #257] — how the measured calibration offset is applied (saved-table update vs runtime correction).
• STAGE-3 / cora#164 — the sample-rotation stage (Aerotech ABRS-150MP) that hosts the channel-cut crystal during calibration.

Net

ENERGY-7 answer: calibration IS current practice (documented in ops/item_012 + ops/item_022); crystal is 2d = 3.84 Å (Si (220), pending explicit operator confirmation), 36 × 3 mm; removable reference standard (mounted only for calibration); rocked on the 2-BM-B sample-rotation stage (Aerotech ABRS-150MP, STAGE-3 / cora#164). Cora's existing energy_characterizat ion Procedure + crystal-as-Subject framing is correct; formal procedure stub now at procedures/item_014.

[decarlof]

Clarification from the 2-BM operator on the "offset" terminology used in the body of this ticket and elsewhere in the 2bm-docs: there is no "energy offset" state stored anywhere in the 2-BM energy-control system. The terminology in step 7 of ops/item_022 ("Apply an energy-offset correction in the control softw
are if required") is operationally misleading and the docs have been updated accordingly.

The actual mechanism: the calibration table itself (energy2bm.json store_0 field in decarlof/energy) IS the authoritative state. The energy CLI's add subcommand saves the current beamline motor positions as the calibrated row for the named energy:

• energy add --energy 20 --mode Mono — overwrites the existing 20.000 row of Mono with the current motor positions.
• energy add --energy 20.05 --mode Mono — adds a new 20.050 row at the measured value, leaving the existing rows in place.

After a channel-cut calibration measures E_meas at a nominal DMM setting:

• If E_meas differs from nominal and the nominal is what subsequent operation will target → tweak optics (Bragg arms, M2 Y) until the rocking-curve peak is at the nominal energy, then energy add --energy <nominal> saves the corrected positions.
• If the measured value itself is what subsequent operation will target, or you want to densify the calibration table → energy add --energy <measured> directly.

Either way, no separate "offset" gets stored. This means cora ENERGY-8's framing ("is the calibration offset folded back into the saved table or applied separately?") does not match the actual mechanism — there is no offset to fold back or apply. The forthcoming ENERGY-8 ticket will address that question with the corrected framing ("neither — the calibration table itself is u
pdated in place via energy add").

Doc updates landed

• ops/item_022.rst step 7 — replaced the "Apply an energy-offset correction" wording with the two explicit energy add workflows.
• procedures/item_014.rst — step 7, Postconditions, Failure modes, and Notes all re-framed off "offset" and onto the direct-table-update mechanism. Notes section now explicitly calls out the ENERGY-8 framing mismatch.

What stays correct in the original ticket

The structural answer to ENERGY-7 is unchanged: calibration IS current practice, crystal is 2d = 3.84 Å (consistent with Si (220), 36 × 3 mm), removable reference standard, rocked on the 2-BM-B sample-rotation stage (STAGE-3 / cora#164). Only the "offset" terminology used in the postcondition / cora-side-application discussion was incorrect.

Apologies for the framing churn — flagging now so ENERGY-8 lands with the right model from the start.