feat(cdi): scaffold NSLS-II CDI (9-ID) coherent diffractive imaging deployment, reverse-engineered

apps/api/tests/unit/deployments/test_beamline_descriptor.py

@@ -401,7 +401,7 @@ def test_no_unexpected_orphan_catalog_models() -> None:
     "Diagnostic": "hold: Sensor fold-vs-promote still open (DIAG-1)",
     "Screen": "hold: phosphor beam-viewing screen (2-BM, BMM); fold-vs-promote open (FLAG-1)",
     "FlowController": "hold: flow/pump actuator n=4 (i22/7-bm/lix/xfp); overdue (FLOW-1)",
-    "BeamPositionMonitor": "hold: Sensor fold-vs-promote across 4-id/8-id/9-id/iss/fmx (DIAG-1)",
+    "BeamPositionMonitor": "hold: fold-vs-promote across 4-id/8-id/9-id/iss/fmx/cdi (DIAG-1)",
     "Laser": "hold: pump-probe laser model-vs-hazard open (4-id + lcls-mfx; SAMPLE-1)",
     "Backlight": "hold: sample-illumination fold-vs-promote open (i03 + i24 + fmx + i19; DET-1)",
     "PolarizationAnalyzer": "hold: 4-id + i10 RASOR PaStage; rule-of-three open (POL-2)",

deployments/nsls2/site.yaml

@@ -25,7 +25,7 @@ facility:
   heading: "NSLS-II"
   kind: Site
   institution: Brookhaven National Laboratory
-  beamlines: [FXI, HXN, BMM, SRX, SIX, CHX, CSX, IOS, XPD, ESM, SMI, IXS, SST, ISS, FMX, CMS, XFM, LIX, HEX, AMX, XFP, ISR]
+  beamlines: [FXI, HXN, BMM, SRX, SIX, CHX, CSX, IOS, XPD, ESM, SMI, IXS, SST, ISS, FMX, CMS, XFM, LIX, HEX, AMX, XFP, ISR, CDI]
 
 # ISA-88 Site Recipes: the facility-adapted form of a catalog Method. All pending
 # because they are reverse-engineered from the FXI profile collection, not yet
@@ -157,6 +157,16 @@ practices:
   # run on is absent from the source (DIFF-1), so these are intent, not a wired capability.
   - {name: ISR_resonant_scattering_practice, method: resonant_scattering, pending: true, note: "resonant hard X-ray scattering near an absorption edge; reuses the 4-ID / CSX resonant_scattering Method; the diffractometer and a wired energy axis are absent from source (TECH-1, DIFF-1, RESONANT-1)"}
   - {name: ISR_surface_diffraction_practice, method: diffraction, pending: true, note: "surface / interface diffraction (crystal truncation rods); reuses the 4-ID / 8-ID diffraction Method; the multi-circle diffractometer is absent from source (TECH-1, DIFF-1)"}
+  # CDI (9-ID) does coherent diffractive imaging: forward (plane-wave) CDI, ptychography,
+  # and Bragg CDI, a coherent beam focused by a KB pair onto the sample with the far-field
+  # pattern recorded on the Eiger2 / Merlin and the real-space image recovered offline by
+  # phase retrieval (a ComputePort leg, not a Method). These sit on the deferred coherent-
+  # imaging Method cohort Diamond i13-1 opened as the pending ptychography Method (the
+  # fleet's first coherent diffractive imaging); CDI reinforces it without coining, and
+  # following CHX / HXN records no Practice until the Method scope lands (TECH-1). CDI is
+  # bound via beamlines.
+  # NAME GUARD: this is NSLS-II 9-ID, not APS 9-ID (CSSI); the coherent_surface_scattering /
+  # grazing_incidence_scattering pending Methods belong to APS 9-ID and are untouched here.
 
 # Access BC Actors conceptually facility-wide at NSLS-II. Pending until the NSLS-II
 # operator and review structure is confirmed; the profile collection only exposes

docs/deployments/cdi/equipment/controls.md

@@ -0,0 +1,30 @@
+# Controls
+
+*The motion controllers, the timing gap, and the seam between CORA and the floor.*
+
+## Triggering: a gap in the source
+
+A coherent-imaging measurement is a gated exposure, often one synchronized with a scan: a ptychographic map steps the sample and takes a frame at each point, a Bragg-CDI series rocks the goniometer and takes a frame at each angle. At the other NSLS-II coherent and scanning beamlines a Zebra or PandA box gates the detector frames against the motion. The CDI profile collection, as read, exposes **no such trigger box**: there is no Zebra or PandA startup file, and no shutter PVs. The `EigerDetector` and `MerlinDetector` carry internal and external trigger modes in their device classes, but how an exposure is gated and synchronized with the scan on the floor is not in source. This is the headline controls question (TIMING-1): it is carried as a deferral, modelled by what is real (the detector trigger modes), not invented.
+
+## Motion controllers
+
+The optics, KB, goniometer, and tower axes are EPICS motor records whose controller boxes, firmware, and IPs are not in the profile collection (DRIVE-1), so `EndstationMotionController` is carried as a single `MotionController` family with the specifics blank.
+
+## The seam: CORA and the floor
+
+This is where CORA's design meets the CDI floor. The shape matches the other NSLS-II beamlines'.
+
+CORA **owns** (its conducting engine, over the `ControlPort`):
+
+- the coherent-imaging acquisition: aligning the KB nanofocus, setting the incident energy, positioning the sample on the goniometer, and arming the area detector for a forward-CDI frame, a ptychographic scan, or a Bragg-CDI rocking series;
+- the choice of technique, detector, scan grid, and exposure, gated by the [trust boundary](../governance.md#the-trust-boundary).
+
+CORA **drives through** (the floor it actuates and observes, and does not replace):
+
+- the EPICS IOCs via the ophyd hardware abstraction: the `ControlPort` boundary;
+- the DCM / DMM drives, the mirror and KB axes, the goniometer and tower motion, the PSS interlock, and the Eiger2 / Merlin detector IOCs;
+- the facility filestore where the per-run frames land. CORA moves them, over the `TransferPort`, into CORA's own Dataset of record.
+
+So CORA brings one conducting engine to CDI, working over the ports: coherent-imaging orchestration over the `ControlPort`, the phase retrieval and ptychographic reconstruction over the `ComputePort`, and data egress over the `TransferPort` into the CORA Dataset. The reconstruction is a clean `ComputePort` leg, the imaging analogue of the correlation analysis at [CHX](../../chx/equipment/controls.md#the-seam-cora-and-the-floor) and the reconstruction legs at the tomography beamlines.
+
+The software IOCs (`Eiger`, `Merlin`, `Prosilica`, the `TetrAMM` and `i400` / `i404` electrometers, the `TDMS` tower IOC) are referenced by PV namespace only, never registered as Assets.

docs/deployments/cdi/equipment/detector.md

@@ -0,0 +1,20 @@
+# Detector
+
+*The coherent-diffraction area detectors. PVs verified against `startup/30-area-detectors.py` and `cditools/eiger_async.py` / `merlin_async.py`.*
+
+CDI's measurement lives on its area detectors. A coherent-imaging measurement records the far-field diffraction pattern of the coherent spot: a single frame for forward CDI, a scan of overlapping frames for ptychography, or a rocking series for Bragg CDI. The real-space image is then recovered offline by phase retrieval.
+
+| Asset | Family | PV | Role |
+| --- | --- | --- | --- |
+| `EigerDetector` | Camera | `XF:09ID1-ES{Det:Eig1}` | primary coherent-diffraction / ptychography detector |
+| `MerlinDetector` | Camera | `XF:09ID1-ES{Det:Merlin1}` | second coherent-diffraction detector |
+
+## Two photon-counting detectors
+
+The `EigerDetector` (an Eiger2) and the `MerlinDetector` are both photon-counting area detectors: their low noise and single-photon sensitivity suit the weak, high-dynamic-range speckle of a coherent-diffraction pattern. Which one is primary for which technique (the larger Eiger2 for ptychography maps, the Merlin for fine Bragg-CDI work, or some other split) is not stated in the public config, so that is a staff question (DET-1), along with whether a direct-beam beamstop is installed (none is in source).
+
+## Reuse, not new vocabulary
+
+This is the reinforcement point of CDI as a CORA exercise: a coherent-imaging beamline with two photon-counting area detectors that needs **no new Family**. Both detectors reuse `Camera`, the Eiger-to-Camera precedent the fleet already carries at [CHX](../../chx/equipment/detector.md) (three Eigers) and [HXN](../../hxn/equipment/detector.md) (a Merlin and an Eiger for ptychography). A coherent area detector recording a diffraction pattern under a gated exposure is the same shape across all three; CDI shows it porting to a dedicated imaging beamline unchanged.
+
+The one honest gap is the exposure gating: how the detector frames are triggered and synchronized with the scan is not in the profile collection (there is no trigger box), so it is carried as the headline controls question (TIMING-1, see [Controls](controls.md)). The detectors carry internal and external trigger modes in their device classes, but the floor chain that drives them is unknown.

docs/deployments/cdi/equipment/index.md

@@ -0,0 +1,19 @@
+# The beamline
+
+*The CDI beam path, area by area. CORA models the beamline as one root Asset (`CDI`) with the devices nested below it; this page is the human walk, the [Inventory](../inventory.md) is the flat reference.*
+
+CDI runs from the in-vacuum undulator through a first-optics hutch into an endstation where a KB mirror pair focuses the coherent beam onto the sample and the far-field diffraction pattern is recorded. Two enclosures carry it:
+
+```
+  9-ID-A  (optics hutch / FOE)              9-ID-C  (endstation)
+  ----------------------------------        --------------------------------------
+  IVU18 -> HDCM / DMM -> VPM / HPM          KB nanofocus -> BCU -> sample (Gon)
+           white-beam / branch slits        towers          Eiger2 / Merlin
+```
+
+- [Source](../beamline.md) (`9-ID-A`): the IVU18 undulator and the storage-ring readback, then the optics, the silicon double-crystal monochromator and the double-multilayer monochromator, the vertical and horizontal pre-mirrors, the white-beam and branch slits, the attenuator foils, the master energy, and the upstream beam diagnostics. This page is generated from the descriptor.
+- [Sample](sample.md) (`9-ID-C`): the KB nanofocusing mirror pair that forms the coherent spot, the beam-conditioning unit that trims it just before the sample, the sample goniometer, the endstation positioning towers, and the endstation diagnostic cameras.
+- [Detector](detector.md) (`9-ID-C`): the Eiger2 and Merlin photon-counting area detectors that record the far-field coherent-diffraction pattern.
+- [Controls](controls.md): the motion controllers and the timing seam, where the CDI profile collection's missing trigger box is the headline question.
+
+Each device binds a catalog [Family](../../../catalog/families.md) and a verified EPICS PV; none binds a vendor Model (part numbers are not in the public config). The one detail to flag is that the 09IDB branch zone (the `BranchSlit` and the quadrant `BeamPositionMonitor`) may be a distinct enclosure (ENC-1); it is folded into the optics hutch here. The loose families are the `BeamPositionMonitor`, shared with other deployments and held for gate-review, and the `StorageRing` machine-state supply.

docs/deployments/cdi/equipment/sample.md

@@ -0,0 +1,32 @@
+# Sample
+
+*The endstation sample side: the KB nanofocus that forms the coherent spot, the beam-conditioning unit, the sample goniometer, the positioning towers, and the endstation diagnostics. PVs verified against `cditools/motors.py` (KB / BCU / GON classes), `startup/18-screens.py`, `21-tdms.py`, `31-electrometers.py`.*
+
+CDI focuses the coherent beam to a small spot with a Kirkpatrick-Baez mirror pair, conditions it through the beam-conditioning unit just before the sample, and records the far-field diffraction pattern. The sample side carries the focusing optic, the goniometer, and the endstation positioning towers; the real-space image is recovered offline by phase retrieval, a `ComputePort` leg, not modelled here.
+
+| Asset | Family | PV | What it does |
+| --- | --- | --- | --- |
+| `KBMirror` | Mirror | `XF:09IDC-OP:1{Mir:KBv}` | KB nanofocus pair (VKB + HKB) forming the coherent spot |
+| `ConditioningSlit` | Slit | `XF:09IDC-OP:1{Slt:BCUU}` | beam-conditioning-unit slits trimming the beam at the sample |
+| `InlineCamera` | Camera | `XF:09IDC-BI{BCU-Cam:9}` | BCU inline beam-viewing camera |
+| `Goniometer` | Goniometer | `XF:09IDC-OP:1{Gon:1}` | sample goniometer and stack |
+| `SampleTower1` | LinearStage | `XF:09IDC-ES:1{TDMS:T1}` | endstation positioning tower 1 |
+| `SampleTower2` | LinearStage | `XF:09IDC-ES:1{TDMS:T2}` | endstation positioning tower 2 |
+| `DiamondBeamMonitor` | BeamPositionMonitor (loose) | `XF:09IDC-BI{BPM:1}` | transmissive diamond BPM ahead of the sample |
+| `SampleCamera` | Camera | `XF:09IDC-BI{SMPL-Cam:10}` | sample-viewing camera |
+
+## Forming and conditioning the coherent spot
+
+The `KBMirror` is the focusing optic that makes CDI a nanofocus beamline: a vertical mirror (VKB) and a horizontal mirror (HKB) in the Kirkpatrick-Baez crossed geometry, each with pitch, roll, and yaw plus jack and translation axes, a defining slit, and a fluorescent screen, with an exit window after the pair. It focuses the coherent beam to the small spot the imaging needs, and reuses the `Mirror` family, the same binding the [FMX](../../fmx/equipment/sample.md) and SRX KB mirrors carry; the focal size and coating are KB-1.
+
+The `ConditioningSlit` is the beam-conditioning unit (BCU): an upstream slit pair and a downstream slit pair that trim and guard the coherent beam just before the sample, with an `InlineCamera` on the same module for beam viewing. For a coherent-imaging beamline these slits are the coherence-conditioning hardware, so CORA models them as first-class `Slit` Assets rather than folding them into settings.
+
+## The sample stack
+
+The `Goniometer` is the sample goniometer and stack (`Gon:1`): sample lab-frame translations and rotations, with small-sample and large-sample axis sets and alignment axes, plus a sample-viewing screen. It reuses the `Goniometer` family; the orientation axes matter for Bragg CDI, where the sample is rocked around a Bragg peak. The full axis set is STAGE-1.
+
+The `SampleTower1` and `SampleTower2` are the two endstation positioning towers (the source's TDMS towers), each carrying translation, camera, and angle axes. Which tower carries the sample and which carries the detector, and the sample-to-detector distance that sets the recorded q-range, are not settled in the public config (some tower axes are read-only pending commissioning), so they are folded into STAGE-1. Both reuse the `LinearStage` family.
+
+## Endstation diagnostics
+
+The `DiamondBeamMonitor` is a transmissive diamond beam-position monitor read through a TetrAMM electrometer, just ahead of the sample; in source it was repurposed from ion-chamber use to the diamond BPM. It binds the loose `BeamPositionMonitor` family (held; DIAG-1). The `SampleCamera` views the sample on-axis (a further endstation Prosilica sits alongside); it reuses `Camera`, and the live diagnostic set is CAM-1.

docs/deployments/cdi/governance.md

@@ -0,0 +1,17 @@
+# Governance
+
+*Who may act at CDI and the trust shape CORA applies. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority.*
+
+People and agents are facility principals at the [NSLS-II Site](../nsls2/index.md); on the beamline they surface through the actions they take. The human roster is not known from the profile collection (GOV-1), so the principals are the design shape, not a registered list.
+
+## Who acts
+
+CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the NSLS-II Site. A CDI beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority.
+
+## The trust boundary
+
+CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may align the KB nanofocus, change the incident energy, arm a ptychographic scan, override a caution, or commit a calibration. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer. The NSLS-II proposal and cycle are a fact CORA's Campaign uses for custody.
+
+## Long unattended scans
+
+A ptychographic map or a Bragg-CDI rocking series can run long and unattended, which is where CORA's trust shape earns its keep: the engine holds the scan while the trust boundary bounds what may change mid-acquisition and who may intervene. If an autonomous Agent were added to steer acquisition (choose the next scan region, decide when the diffraction signal is sufficient, trigger a reconstruction to check convergence), it would be a facility principal scoped at the Site, governed by the same trust boundary, with each choice recorded as a [Decision](../../architecture/modules/decision/index.md). None is declared yet.