From c0c177ce062f4a4a0bf8c3262d4caaa5215c91d9 Mon Sep 17 00:00:00 2001 From: Doga Gursoy Date: Fri, 26 Jun 2026 17:27:16 +0300 Subject: [PATCH 1/2] feat(cdi): scaffold NSLS-II CDI (9-ID) deployment (coherent diffractive imaging: forward CDI, ptychography, Bragg CDI on a KB nanofocus), reverse-engineered CDI is the NSLS-II coherent-imaging beamline at sector 9-ID: it focuses a coherent beam with a Kirkpatrick-Baez mirror pair, records the far-field diffraction pattern on photon-counting area detectors (Eiger2, Merlin), and recovers the real-space image offline by phase retrieval. Reverse-engineered from public open source updated today (NSLS2/cdi-profile-collection startup scripts + the NSLS2/cditools device classes). Descriptor + docs scaffold; EPICS PVs real and read from source, every value carried confirm; scenarios deferred. Same mode as CHX / HXN. NAME GUARD. This is NSLS-II 9-ID. CORA already models APS 9-ID (the CSSI surface- scattering instrument, deployments/9-id), a different beamline at a different facility with a different PV namespace. CDI lives at XF:09ID* / SR:C09-ID*. The descriptor and the site.yaml comment carry this guard so the two 9-IDs are never conflated, and the APS-9-ID coherent_surface_scattering / grazing_incidence_scattering pending Methods are left untouched. WHY no catalog change, and where the value is. The instrument is NOT the novelty: CDI is a reuse-and-reinforce deployment with zero new families and nothing graduating. The coherent area detectors reuse Camera (the Eiger-to-Camera precedent, also CHX / HXN); the KB nanofocus pair and the vertical / horizontal pre-mirrors reuse Mirror (the FMX / SRX KB precedent); the silicon DCM and the double-multilayer DMM both reuse Monochromator (the CHX Si-DCM-plus-multilayer-DMM precedent); the sample stack reuses Goniometer; the foil intensity monitor FluxMonitor; the white-beam / branch / beam- conditioning slits Slit; the attenuator foils Filter; the undulator InsertionDevice; the master energy a PseudoAxis; the endstation towers LinearStage. The quadrant and diamond beam-position monitors bind the loose BeamPositionMonitor (held; DIAG-1) and the machine reads a loose StorageRing supply (MACHINE-1). The value to CORA is reinforcement: the coherent-detector shape CHX brought and the deferred ptychography HXN brought port to a beamline dedicated to phase-retrieval imaging with no new vocabulary. MODELLING: zero new families, nothing graduates, the catalog is unchanged. The coherent- imaging Methods (forward CDI, ptychography, Bragg CDI) are NOT coined: following 8-ID / CHX (coherent) and HXN (ptychography deliberately not coined; the reconstruction is ComputePort work, not a Method), they are the deferred owner-scope cohort (TECH-1), so no CDI Practice is recorded. CDI's distinctive honest gap is that the profile collection exposes no hardware trigger box (no Zebra / PandA startup file, no shutter PVs); the Eiger2 / Merlin carry internal and external trigger modes, but the floor gating chain is the headline open question (TIMING-1), modelled by what is real, not invented. Wiring: CDI added to the NSLS-II Site beamline list (no Practice, comment explains why); deployments index row; mkdocs nav block; the BeamPositionMonitor promotion-review note broadened to + cdi. Gate: 389 deployment unit tests pass, mkdocs --strict builds clean, adversarial per-file verify (11 independent verifiers vs the cloned source) caught four over-specifications (a non-existent KB bend axis, the DMM mlm1/mlm2 mislabeled as stripe selectors, a stale "deferred xpcs" since graduated, an invented "piezo" actuator), all corrected and re-gated. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../deployments/test_beamline_descriptor.py | 2 +- deployments/cdi/beamline.yaml | 261 ++++++++++++++++++ deployments/nsls2/site.yaml | 10 +- docs/deployments/cdi/equipment/controls.md | 30 ++ docs/deployments/cdi/equipment/detector.md | 20 ++ docs/deployments/cdi/equipment/index.md | 19 ++ docs/deployments/cdi/equipment/sample.md | 32 +++ docs/deployments/cdi/governance.md | 17 ++ docs/deployments/cdi/index.md | 49 ++++ docs/deployments/cdi/inventory.md | 60 ++++ docs/deployments/cdi/model.md | 24 ++ docs/deployments/cdi/questions.md | 38 +++ docs/deployments/cdi/techniques.md | 20 ++ docs/deployments/index.md | 1 + mkdocs.yml | 13 + 15 files changed, 594 insertions(+), 2 deletions(-) create mode 100644 deployments/cdi/beamline.yaml create mode 100644 docs/deployments/cdi/equipment/controls.md create mode 100644 docs/deployments/cdi/equipment/detector.md create mode 100644 docs/deployments/cdi/equipment/index.md create mode 100644 docs/deployments/cdi/equipment/sample.md create mode 100644 docs/deployments/cdi/governance.md create mode 100644 docs/deployments/cdi/index.md create mode 100644 docs/deployments/cdi/inventory.md create mode 100644 docs/deployments/cdi/model.md create mode 100644 docs/deployments/cdi/questions.md create mode 100644 docs/deployments/cdi/techniques.md diff --git a/apps/api/tests/unit/deployments/test_beamline_descriptor.py b/apps/api/tests/unit/deployments/test_beamline_descriptor.py index 2e4725dc49..c6f4f72c55 100644 --- a/apps/api/tests/unit/deployments/test_beamline_descriptor.py +++ b/apps/api/tests/unit/deployments/test_beamline_descriptor.py @@ -400,7 +400,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=3 (i22/7-bm/lix); graduation candidate (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)", diff --git a/deployments/cdi/beamline.yaml b/deployments/cdi/beamline.yaml new file mode 100644 index 0000000000..97eae726d8 --- /dev/null +++ b/deployments/cdi/beamline.yaml @@ -0,0 +1,261 @@ +# CDI beamline descriptor (NSLS-II), reverse-engineered +# +# CDI (Coherent Diffraction Imaging) is the NSLS-II coherent-imaging beamline at +# sector 9-ID. Its defining techniques are coherent diffractive imaging: forward +# (plane-wave) CDI, ptychography, and Bragg CDI, all formed by focusing a coherent +# beam to a small spot with a Kirkpatrick-Baez (KB) mirror pair and recording the +# far-field diffraction pattern on a photon-counting area detector (Eiger2, Merlin). +# The real-space image is recovered offline by phase retrieval. It is bound to the +# NSLS-II Site (deployments/nsls2/site.yaml). +# +# NAME GUARD: this is NSLS-II 9-ID. CORA also models APS 9-ID (the CSSI surface- +# scattering instrument, deployments/9-id), a different beamline at a different +# facility with a different PV namespace. CDI lives at XF:09ID* / SR:C09-ID*. +# +# STATUS: reverse-engineered, design-phase. Every value is read from public open +# source (the bluesky profile collection NSLS2/cdi-profile-collection and the +# device library NSLS2/cditools) or inferred, carried `confirm: true` pending CDI +# staff. EPICS PVs are real and verified against the startup scripts and the +# cditools device classes; vendor part numbers, serials, and physical positions +# are not in them and are open questions. Same descriptor mode as CHX / HXN; this +# scaffold is descriptor + docs, scenarios deferred. +# +# CDI is a COHERENT-IMAGING reinforcement: it reuses the coherent-detector shape +# CHX brought (a photon-counting area detector recording a coherent pattern) and +# the deferred ptychography HXN brought (the reconstruction is ComputePort work, +# not a beamline Method), at a beamline dedicated to phase-retrieval imaging. It +# introduces NO new catalog family: the area detectors reuse Camera (the Eiger-to- +# Camera precedent), the KB nanofocus pair and the pre-mirrors reuse Mirror (the +# FMX / SRX KB precedent), the two monochromators reuse Monochromator (the CHX +# Si-DCM-plus-multilayer-DMM precedent), the goniometer reuses Goniometer, the +# foil intensity monitor reuses FluxMonitor, the slits Slit, the attenuator foils +# Filter, the undulator InsertionDevice, the master energy a PseudoAxis, the +# diagnostic cameras Camera. The quadrant and diamond beam-position monitors bind +# the loose BeamPositionMonitor family (held; DIAG-1) and the machine reads a loose +# StorageRing supply (MACHINE-1). Per the 8-ID / CHX / HXN precedent the coherent- +# imaging Methods are NOT coined here; they are the deferred owner-scope cohort +# (TECH-1). + +beamline: + name: CDI + facility: nsls2 # NSLS-II Site (facility_code: nsls2) + sector: "Sector 9" # PV namespace XF:09ID* + tier: Unit + parent: null + source: insertion-device + source_confirm: "IVU18 in-vacuum undulator (SR:C09-ID:G1{IVU18:1}), verified in source; period/gap parameters not fully in the profile collection (SRC-1)" + +enclosures: + # PV zones: 09IDA first-optics hutch (FOE), 09IDB branch (DM3 slit, quadrant BPM), + # 09IDC endstation (KB nanofocus, beam-conditioning unit, goniometer, towers), and + # the 09ID1 detector namespace. Modelled as an optics hutch plus an experiment + # hutch; whether the 09IDB branch is a distinct enclosure is a staff question (ENC-1). + - name: 9-ID-A + role: optics-hutch + facility_code: nsls2 + permit_signal: {confirm: "PSS search-and-secure permit leaf not in source; no shutter PVs are in the profile collection either (PSS-1)"} + - name: 9-ID-C + role: experiment-hutch + facility_code: nsls2 + permit_signal: {confirm: "PSS permit leaf unknown; 9-ID-C is the endstation carrying the KB nanofocus, the sample goniometer, and the detectors. The 09IDB branch zone may be a distinct enclosure (ENC-1)"} + +# =========================================================================== +# SOURCE STAGE: the undulator and the machine readback +# =========================================================================== + +source: + stage: source + enclosure: 9-ID-A + intro: The in-vacuum undulator source and the storage-ring readback. + devices: + - name: Source + family: InsertionDevice + pv: "SR:C09-ID:G1{IVU18:1}" + confirm: true + note: "IVU18 in-vacuum undulator (class InsertionDevice over IVUGap, instance ivu); gap-driven through the CS2:Gap motor. Period / field parameters pending (SRC-1)." + - name: StorageRing + family: StorageRing # loose supply (MACHINE-1) + pv: "SR:OPS-BI{DCCT:1}I:Real-I" + confirm: true + note: "Storage-ring current readback (ring_current), an observe-only machine-state signal. Binds the loose StorageRing supply family (never an Asset Family, MACHINE-1)." + +# =========================================================================== +# OPTICS STAGE: the monochromators, the pre-mirrors, the slits and foils, the +# master energy, and the upstream beam diagnostics +# =========================================================================== + +optics: + stage: source + enclosure: 9-ID-A + intro: "Condition the beam and set its energy: 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, and the upstream beam diagnostics. PVs verified against startup/10-machine.py, 20-motors.py, 31-electrometers.py and cditools/motors.py." + devices: + - name: WhiteBeamSlit + family: Slit + pv: "XF:09IDA-OP:1{Slt:WB1" + confirm: true + note: "White-beam-defining slit on the DM1 diagnostic module (class DM1, instance dm1): inboard / outboard / top / bottom blades plus HG / HC / VG / VC gap-and-center axes. Reuses Slit." + - name: AttenuatorFoil + family: Filter + pv: "XF:09IDA-OP:1{Fltr:DM1" + confirm: true + note: "DM1 attenuator foil paddle (dm1.filt, a Y-translation selecting absorber thickness); reuses Filter. Foil materials / thicknesses pending (DET-1)." + - name: VerticalPreMirror + family: Mirror + pv: "XF:09IDA-OP:1{Mir:VPM" + confirm: true + note: "Vertical pre-mirror (class VPM, instance vpm): pitch / roll / bend plus jack and translation axes, with a fluorescent-screen diagnostic (FS:VPM) and a defining slit (Slt:VPM) on the same module. Coating / stripe pending (DCM-1)." + - name: HorizontalPreMirror + family: Mirror + pv: "XF:09IDA-OP:1{Mir:HPM" + confirm: true + note: "Horizontal pre-mirror (class HPM, instance hpm): the horizontal-deflection partner of the VPM, same pitch / roll / bend / jack axis set, with its own FS:HPM screen and Slt:HPM slit. Reuses Mirror." + - name: Monochromator + family: Monochromator + pv: "XF:09IDA-OP:1{Mono:HDCM" + confirm: true + note: "Silicon double-crystal monochromator (class DCMBase plus the Energy pseudopositioner, instances dcm_base / energy): pitch / fine-pitch / roll plus the Bragg and crystal-gap axes the energy model drives. The Si(111) reflection is read from the Energy model (d = 3.1287 A); cryo detail and full range pending (DCM-1). The EnergyAxis below is the master energy." + - name: MultilayerMonochromator + family: Monochromator + pv: "XF:09IDA-OP:1{Mono:DMM" + confirm: true + note: "Double-multilayer monochromator (class DMM, instance dmm): a wider-bandpass, higher-flux alternative to the Si DCM for coherent imaging, with its own Bragg / gap and two multilayer-crystal orientation groups (mlm1 roll / fine-roll, mlm2 pitch / fine-pitch). Reuses Monochromator (the CHX DCM-plus-DMM precedent). Coating and bandwidth pending (DCM-1)." + - name: IntensityMonitorFoil + family: Filter + pv: "XF:09IDA-OP:1{IM:DM2" + confirm: true + note: "DM2 intensity-monitor foil (dm2.foil, a Y-translation), with a fluorescent screen (FS:DM2) on the same module; reuses Filter." + - name: BranchSlit + family: Slit + pv: "XF:09IDB-OP:1{Slt:DM3" + confirm: true + note: "Branch-defining slit on the DM3 module (class DM3, instance dm3), in the 09IDB branch zone (ENC-1): inboard / outboard / top / bottom plus gap-and-center axes, with a co-located BPM stage and screen. Reuses Slit." + - name: EnergyAxis + family: PseudoAxis + confirm: true + note: "Master energy pseudo-axis (class Energy, instance energy). Driving it sets the DCM Bragg angle and the crystal gap through a real forward / inverse model (Si(111), d = 3.1287 A, 12.3984 A.keV). The provisional 5-15 keV range is marked TODO-CHECK in source; whether energy is ever scanned as the measurement is ENERGY-1." + - name: FluxMonitor + family: FluxMonitor + pv: "XF:09IDA-BI{i400:1}" + confirm: true + note: "Foil intensity monitor (class I400, instance fmon) read for I0 normalization; reuses FluxMonitor. Channel map pending (DIAG-1)." + - name: BeamPositionMonitor + family: BeamPositionMonitor # loose Family (held; DIAG-1) + pv: "XF:09IDB-BI{i404:1}" + confirm: true + note: "Quadrant beam-position monitor (class I404, instance qbpm) on the branch, plus the DM3 / DM4 BPM translation stages. Binds the loose BeamPositionMonitor family that 4-ID / 8-ID / iss / fmx also use (held; DIAG-1), matching the catalog note that position monitors stay loose. Channel map pending (DIAG-1)." + +# =========================================================================== +# SAMPLE STAGE: the KB nanofocus, the beam-conditioning unit, the goniometer, +# the endstation positioning towers, and the endstation diagnostics +# =========================================================================== + +sample: + stage: sample + enclosure: 9-ID-C + intro: "The endstation optics that form and condition the coherent nano-spot and the sample positioning around it: the KB mirror pair, the beam-conditioning unit, the sample goniometer, and the endstation towers. PVs verified against cditools/motors.py (KB / BCU / GON classes), startup/18-screens.py, 21-tdms.py, 31-electrometers.py." + note: > + CDI focuses the coherent beam to a small spot with a Kirkpatrick-Baez mirror + pair (the KB nanofocus) and conditions it through the beam-conditioning unit + just before the sample, then records the far-field diffraction pattern. The + sample side carries the goniometer and the endstation positioning towers; the + real-space image is recovered offline by phase retrieval (a ComputePort leg, + not modelled here). + devices: + - name: KBMirror + family: Mirror + pv: "XF:09IDC-OP:1{Mir:KBv" + confirm: true + note: "Kirkpatrick-Baez nanofocusing mirror pair (class KB: a vertical VKB at Mir:KBv and a horizontal HKB at Mir:KBh, plus an exit window Wnd:Exit), each with pitch / roll / yaw plus jack and translation axes, a defining slit, and a fluorescent screen. This is the focusing optic that forms the coherent spot; reuses Mirror (the FMX / SRX KB precedent). Focal size and coating pending (KB-1)." + - name: ConditioningSlit + family: Slit + pv: "XF:09IDC-OP:1{Slt:BCUU" + confirm: true + note: "Beam-conditioning-unit slits (class BCU, instance bcu): an upstream pair (Slt:BCUU) and a downstream pair (Slt:BCUD) trimming and guarding the coherent beam at the endstation, with an inline-camera stage (Qstar:1). Reuses Slit." + - name: InlineCamera + family: Camera + pv: "XF:09IDC-BI{BCU-Cam:9}" + confirm: true + note: "Beam-conditioning-unit inline beam-viewing camera (cam_C9, a masked Prosilica), carried on the BCU Qstar stage; reuses Camera. Live diagnostic set pending (CAM-1)." + - name: Goniometer + family: Goniometer + pv: "XF:09IDC-OP:1{Gon:1" + confirm: true + note: "Sample goniometer and stack (classes GON / SAM, instance gon): sample lab-frame translations and rotations (Rx / Rz / X / Y / Z, with small-sample and large-sample axis sets) plus alignment axes and a sample-viewing screen. Reuses Goniometer; the full axis modelling is STAGE-1." + - name: SampleTower1 + family: LinearStage + pv: "XF:09IDC-ES:1{TDMS:T1" + confirm: true + note: "Endstation positioning tower 1 (class TDMSTower, instance T1): TX / TY / TZ translations plus camera and angle axes. One of the two CDI endstation towers; which tower carries the sample versus the detector, and the sample-to-detector distance that sets the q-range, are STAGE-1. Reuses LinearStage." + - name: SampleTower2 + family: LinearStage + pv: "XF:09IDC-ES:1{TDMS:T2" + confirm: true + note: "Endstation positioning tower 2 (class TDMSTower, instance T2), the partner of SampleTower1. Reuses LinearStage; some axes are read-only pending commissioning in source (STAGE-1)." + - name: DiamondBeamMonitor + family: BeamPositionMonitor # loose Family (held; DIAG-1) + pv: "XF:09IDC-BI{BPM:1}" + confirm: true + note: "Transmissive diamond beam-position monitor read through a TetrAMM electrometer (class TetrAMM, instance dbpm) just ahead of the sample; renamed in source on 2026-06-18 from ion-chamber use to the diamond BPM. Binds the loose BeamPositionMonitor family (held; DIAG-1)." + - name: SampleCamera + family: Camera + pv: "XF:09IDC-BI{SMPL-Cam:10}" + confirm: true + note: "Sample-viewing camera (cam_C10, a masked Prosilica); a further endstation Prosilica (cam_C15) sits alongside. Reuses Camera. Live set pending (CAM-1)." + +# =========================================================================== +# DETECTION STAGE: the coherent-diffraction area detectors +# =========================================================================== + +detector: + stage: detection + enclosure: 9-ID-C + intro: "The photon-counting area detectors that record the coherent far-field diffraction pattern. PVs verified against startup/30-area-detectors.py and cditools/eiger_async.py / merlin_async.py." + note: > + CDI's measurement lives on its area detectors: an Eiger2 and a Merlin record + the far-field coherent-diffraction pattern (a single frame for forward CDI, a + scan of frames for ptychography, a rocking series for Bragg CDI). Both reuse + Camera. The hardware exposure-gating chain is not exposed in source (TIMING-1); + the detectors carry internal and external trigger modes in their device classes. + devices: + - name: EigerDetector + family: Camera + pv: "XF:09ID1-ES{Det:Eig1}" + confirm: true + note: "Eiger2 photon-counting area detector (class EigerDetector, instance eiger2-1), the primary coherent-diffraction / ptychography detector recording the far-field pattern; reuses Camera (the Eiger-to-Camera precedent). Module size and trigger wiring pending (DET-1 / TIMING-1)." + - name: MerlinDetector + family: Camera + pv: "XF:09ID1-ES{Det:Merlin1}" + confirm: true + note: "Merlin photon-counting detector (class MerlinDetector, instance merlines-1), the second coherent-diffraction detector; reuses Camera. Which detector is primary for which technique is DET-1." + +# =========================================================================== +# Cross-cutting controls +# =========================================================================== + +controls: + intro: > + Unlike the other NSLS-II coherent beamlines, the CDI profile collection exposes + no hardware trigger box: there is no Zebra or PandA startup file, and no shutter + PVs. The Eiger2 and Merlin carry internal and external trigger modes in their + device classes, but how an exposure is gated on the floor is not in source + (TIMING-1). The motors sit on EPICS motor records whose controller boxes, + firmware, and IPs are likewise not exposed (DRIVE-1). + motion_controllers: + - name: EndstationMotionController + family: MotionController + confirm: true + note: "The motion controllers driving the optics, KB, goniometer, and tower axes; box models / protocol / IP not in the profile collection (DRIVE-1)." + triggering: [] + software_iocs_not_modeled: + [Eiger, Merlin, Prosilica, TetrAMM, i400, i404, TDMS] + +resources: + intro: Continuously-available resources. Facility-scope supplies live in deployments/nsls2/site.yaml. + supplies: + - kind: PhotonBeam + - kind: CoolingWater + - kind: Vacuum + - kind: LiquidNitrogen # DCM cryocooler + - kind: Power + replaceable_parts: + swappable_with_identity: ["area detectors", "attenuator foils", "KB mirrors"] diff --git a/deployments/nsls2/site.yaml b/deployments/nsls2/site.yaml index 3e359e4ca4..73eff7b69b 100644 --- a/deployments/nsls2/site.yaml +++ b/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] + beamlines: [FXI, HXN, BMM, SRX, SIX, CHX, CSX, IOS, XPD, ESM, SMI, IXS, SST, ISS, FMX, CMS, XFM, LIX, HEX, 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 @@ -134,6 +134,14 @@ practices: - {name: HEX_radiography_practice, method: radiography, pending: true, note: "time-resolved high-speed radiography on the Phantom Veo; reuses the radiography Method APS 7-BM left pending, the second consumer (TECH-1)"} - {name: HEX_energy_dispersive_diffraction_practice, method: energy_dispersive_diffraction, pending: true, note: "spatially-resolved energy-dispersive X-ray diffraction (EDXD) on the GeRM germanium strip detector; reuses the energy_dispersive_diffraction Method APS 7-BM left pending, the second consumer (TECH-1)"} - {name: HEX_powder_diffraction_practice, method: powder_diffraction, pending: true, note: "monochromatic angle-dispersive / powder diffraction (ADXD) on the PerkinElmer flat panel; reuses the powder_diffraction Method Diamond i11 left pending, the second consumer (TECH-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 coherent-imaging Methods are + # not in the catalog; following 8-ID / CHX (coherent) and HXN (ptychography), no CDI + # Practice is recorded until a Method 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 diff --git a/docs/deployments/cdi/equipment/controls.md b/docs/deployments/cdi/equipment/controls.md new file mode 100644 index 0000000000..27a721492d --- /dev/null +++ b/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. diff --git a/docs/deployments/cdi/equipment/detector.md b/docs/deployments/cdi/equipment/detector.md new file mode 100644 index 0000000000..212eb9720e --- /dev/null +++ b/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. diff --git a/docs/deployments/cdi/equipment/index.md b/docs/deployments/cdi/equipment/index.md new file mode 100644 index 0000000000..726a109e2f --- /dev/null +++ b/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. diff --git a/docs/deployments/cdi/equipment/sample.md b/docs/deployments/cdi/equipment/sample.md new file mode 100644 index 0000000000..da9f9ffa3b --- /dev/null +++ b/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. diff --git a/docs/deployments/cdi/governance.md b/docs/deployments/cdi/governance.md new file mode 100644 index 0000000000..d91dcecbdb --- /dev/null +++ b/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. diff --git a/docs/deployments/cdi/index.md b/docs/deployments/cdi/index.md new file mode 100644 index 0000000000..d79128ff73 --- /dev/null +++ b/docs/deployments/cdi/index.md @@ -0,0 +1,49 @@ +# CDI + +*Coherent diffraction imaging at NSLS-II, beamline 9-ID: a forward-CDI, ptychography, and Bragg-CDI beamline that focuses a coherent beam with a KB mirror pair and records the far-field diffraction pattern on photon-counting area detectors. This page describes how CORA would model and run CDI; the model is reverse-engineered from public configuration, not yet confirmed by CDI staff.* + +| Property | Value | +| --- | --- | +| Asset | `CDI` (root Asset, `tier = Unit`, `parent_id = None`) | +| Facility | [NSLS-II](../nsls2/index.md) (bound via `facility_code = "nsls2"`, `FacilityKind = Site`) | +| Sector | `Sector 9` (PV namespace `XF:09ID*`) | +| Institution | Brookhaven National Laboratory (context; not modeled as an Asset or Facility) | +| Status | Reverse-engineered from public config (design-phase scaffold) | +| Source | IVU18 in-vacuum undulator (`SR:C09-ID:G1{IVU18:1}`) | + +!!! note "How CORA would land on CDI" + This is NSLS-II 9-ID. CORA also models APS [9-ID](../9-id/index.md), a different beamline at a different facility; CDI lives at `XF:09ID*`. These pages describe how CORA would model, govern, and conduct CDI, joining the NSLS-II coherent siblings [CHX](../chx/index.md) and [CSX](../csx/index.md) and the ptychography-capable nanoprobe [HXN](../hxn/index.md). They are not a survey of the beamline's current software. The hardware facts (devices, EPICS PVs, axes) are read from public NSLS-II open source (the [`NSLS2/cdi-profile-collection`](https://github.com/NSLS2/cdi-profile-collection) profile collection and the [`NSLS2/cditools`](https://github.com/NSLS2/cditools) device library) and verified against them; vendor part numbers and physical positions are not in them, so they, and every read value, are carried `confirm` until CDI staff verify them ([Open questions](questions.md)). This is a design-phase scaffold: the descriptor and these docs, with scenarios deferred. + +## The defining shape: coherent imaging + +CDI is CORA's first beamline dedicated to **coherent diffractive imaging**: it focuses a coherent beam to a small spot, records the far-field diffraction pattern on a photon-counting area detector, and recovers the real-space image offline by phase retrieval. The fleet has met coherence before, but in different acts: APS [8-ID](../8-id/index.md) and [CHX](../chx/index.md) record correlation time series (XPCS), [CSX](../csx/index.md) records coherent soft X-ray scattering, and [HXN](../hxn/index.md) runs ptychography as one of several scanning-probe modes. CDI brings the imaging act to its own beamline. + +The value to CORA is reinforcement, not new vocabulary. The coherent area detector that records the diffraction pattern is the same `Camera` shape CHX and HXN already carry; the KB nanofocus that forms the coherent spot is the same `Mirror` shape FMX and SRX carry; the offline reconstruction is a `ComputePort` leg, the imaging analogue of CHX's correlation analysis, not a beamline Method. CDI introduces **no new catalog Family**, and its techniques sit on the same deferred-Method discipline HXN's ptychography follows. + +The three imaging techniques differ only in how the frames are taken: a single far-field frame (forward CDI), a scan of overlapping frames across the sample (ptychography), or a rocking series around a Bragg peak (Bragg CDI). All three share the KB nanofocus, the goniometer, and the coherent detectors. + +## The beamline + +Along the beam, in order: + +- [Source](beamline.md): the IVU18 in-vacuum undulator and the first-optics hutch (`9-ID-A`), rendered as the generated source-stage device walk: 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. +- [Sample](equipment/sample.md): 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](equipment/detector.md): the Eiger2 and Merlin photon-counting area detectors that record the far-field coherent-diffraction pattern. + +Cutting across all three: + +- [Controls](equipment/controls.md): the motion controllers and the timing seam. Unlike the other NSLS-II coherent beamlines, the CDI profile collection exposes no hardware trigger box, which is the headline controls question. + +The cross-cutting reference view is the [Inventory](inventory.md). + +## Techniques + +[Techniques](techniques.md): the coherent-imaging techniques CDI runs (forward CDI, ptychography, Bragg CDI), each a [Catalog](../../catalog/methods.md) Method, and why their Methods stay deferred (the 8-ID / CHX / HXN owner-scope cohort). + +## Governance + +[Governance](governance.md): who may act at CDI and the trust shape CORA applies; CORA brings its own per-Actor authority. + +## Model + +[Model](model.md): the developer's by-kind index into where each CORA aggregate's CDI content lives. diff --git a/docs/deployments/cdi/inventory.md b/docs/deployments/cdi/inventory.md new file mode 100644 index 0000000000..eac6f48183 --- /dev/null +++ b/docs/deployments/cdi/inventory.md @@ -0,0 +1,60 @@ +# Inventory + +*The CORA Asset model for CDI: the device tree read from the profile collection and what still needs confirming.* + +This is the cross-cutting reference view of the [Source](beamline.md) walk and the [Sample](equipment/sample.md), [Detector](equipment/detector.md), and [Controls](equipment/controls.md) pages. It is generated-honest: authored from the same [`beamline.yaml`](https://github.com/xmap/cora/blob/main/deployments/cdi/beamline.yaml) descriptor the Source page renders from. + +Devices bind to catalog [Families](../../catalog/families.md) and carry real EPICS PVs (verified against `NSLS2/cdi-profile-collection` and `NSLS2/cditools`). No vendor Model is bound: part numbers are not in the profile collection. CDI introduces **no new catalog family**: every device reuses an existing Family, including the ones graduated from earlier reverse-engineered deployments (`Camera` for the Eiger2 and Merlin detectors and the diagnostic cameras, `FluxMonitor` for the foil intensity monitor, `Monochromator` for both monochromators, `Mirror` for the pre-mirrors and the KB pair, `Goniometer` for the sample stack). Two loose families are bound: the `BeamPositionMonitor` (shared with 4-ID, 8-ID, ISS, FMX, held for gate-review) and the `StorageRing` supply observation (machine state, never an Asset Family). + +## The Asset tree + +Root Asset `CDI` (`tier = Unit`, `facility_code = nsls2`); sub-systems nest below by `parent_id`. + +| Asset | Family | PV (verified) | What it is | +| --- | --- | --- | --- | +| `CDI` | (root) | `XF:09ID*` | bound to the NSLS-II Site | +| `Source` | InsertionDevice | `SR:C09-ID:G1{IVU18:1}` | IVU18 in-vacuum undulator | +| `StorageRing` | StorageRing (loose) | `SR:OPS-BI{DCCT:1}` | storage-ring current readback (machine state) | +| `WhiteBeamSlit` | Slit | `XF:09IDA-OP:1{Slt:WB1}` | DM1 white-beam-defining slit | +| `AttenuatorFoil` | Filter | `XF:09IDA-OP:1{Fltr:DM1}` | DM1 attenuator foil paddle | +| `VerticalPreMirror` | Mirror | `XF:09IDA-OP:1{Mir:VPM}` | vertical pre-mirror (pitch / roll / bend) | +| `HorizontalPreMirror` | Mirror | `XF:09IDA-OP:1{Mir:HPM}` | horizontal pre-mirror | +| `Monochromator` | Monochromator | `XF:09IDA-OP:1{Mono:HDCM}` | silicon double-crystal monochromator (Si(111)) | +| `MultilayerMonochromator` | Monochromator | `XF:09IDA-OP:1{Mono:DMM}` | double-multilayer mono (high coherent flux) | +| `IntensityMonitorFoil` | Filter | `XF:09IDA-OP:1{IM:DM2}` | DM2 intensity-monitor foil | +| `BranchSlit` | Slit | `XF:09IDB-OP:1{Slt:DM3}` | DM3 branch-defining slit (09IDB zone) | +| `EnergyAxis` | PseudoAxis | (computed) | master energy (Si(111) Bragg + gap model) | +| `FluxMonitor` | FluxMonitor | `XF:09IDA-BI{i400:1}` | foil intensity monitor (I0) | +| `BeamPositionMonitor` | BeamPositionMonitor (loose) | `XF:09IDB-BI{i404:1}` | quadrant beam-position monitor | +| `KBMirror` | Mirror | `XF:09IDC-OP:1{Mir:KBv}` | KB nanofocusing mirror pair (VKB + HKB) | +| `ConditioningSlit` | Slit | `XF:09IDC-OP:1{Slt:BCUU}` | beam-conditioning-unit slits | +| `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 (TetrAMM) | +| `SampleCamera` | Camera | `XF:09IDC-BI{SMPL-Cam:10}` | sample-viewing camera | +| `EigerDetector` | Camera | `XF:09ID1-ES{Det:Eig1}` | Eiger2, primary coherent-diffraction detector | +| `MerlinDetector` | Camera | `XF:09ID1-ES{Det:Merlin1}` | Merlin, second coherent-diffraction detector | +| `EndstationMotionController` | MotionController | (pending) | optics / KB / goniometer / tower motion | + +Every family is in the catalog except the loose `BeamPositionMonitor` (shared and held) and the loose `StorageRing` supply; CDI coins none. Notably the area detectors reuse `Camera` (the Eiger-to-Camera precedent, also used at [CHX](../chx/equipment/detector.md) and [HXN](../hxn/equipment/detector.md)), the KB pair reuses `Mirror` (the [FMX](../fmx/equipment/sample.md) / SRX KB precedent), both monochromators reuse `Monochromator` (the CHX Si-DCM-plus-multilayer-DMM precedent), and the foil intensity monitor reuses `FluxMonitor`, so CDI is a clean reuse-and-reinforce deployment. + +## Pending confirmations + +Every value below is read from the profile collection or inferred, awaiting the CDI team. Each is tracked by an [open question](questions.md). + +| Value to confirm | Applies to | Status | Tracking | +| --- | --- | --- | --- | +| IVU18 undulator period / gap range | `Source` | `unknown-pending-confirmation` | (SRC-1) | +| PSS permit-leaf PVs; the 09IDB branch as a distinct enclosure | both enclosures | `unknown-pending-confirmation` | (PSS-1) (ENC-1) | +| DCM cryo detail and full range (Si(111) is read from source); DMM coating and bandpass | `Monochromator` / `MultilayerMonochromator` | `unknown-pending-confirmation` | (DCM-1) | +| KB focal size, coating, and working distance | `KBMirror` | `unknown-pending-confirmation` | (KB-1) | +| Whether incident energy is ever scanned as the measurement (provisional 5-15 keV) | `EnergyAxis` | `unknown-pending-confirmation` | (ENERGY-1) | +| Which tower carries the sample vs the detector; sample-to-detector distance / q-range; full goniometer axis set | `SampleTower1` / `SampleTower2` / `Goniometer` | `unknown-pending-confirmation` | (STAGE-1) | +| Which detector is primary per technique; foil materials; whether a beamstop is installed | `EigerDetector` / `MerlinDetector` / `AttenuatorFoil` | `unknown-pending-confirmation` | (DET-1) | +| Live diagnostic-camera set | `InlineCamera` / `SampleCamera` | `unknown-pending-confirmation` | (CAM-1) | +| Foil-monitor and BPM channel maps | `FluxMonitor` / `BeamPositionMonitor` / `DiamondBeamMonitor` | `unknown-pending-confirmation` | (DIAG-1) | +| The exposure-gating chain (no trigger box in source) | detectors | `unknown-pending-confirmation` | (TIMING-1) | +| Motion-controller box models / firmware / IP | `EndstationMotionController` | `unknown-pending-confirmation` | (DRIVE-1) | +| Whether the coherent-imaging Methods enter the catalog | techniques | `unknown-pending-confirmation` | (TECH-1) | diff --git a/docs/deployments/cdi/model.md b/docs/deployments/cdi/model.md new file mode 100644 index 0000000000..7233b134b6 --- /dev/null +++ b/docs/deployments/cdi/model.md @@ -0,0 +1,24 @@ +# Model + +*The developer's by-kind index: where each CORA aggregate's CDI content lives. It hosts no content of its own. Design-phase scaffold.* + +For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC +[modules](../../architecture/modules/index.md). + +| Aggregate (BC) | Where at CDI | +| --- | --- | +| Asset (Equipment) | [Inventory](inventory.md#the-asset-tree) (in this zone) | +| Computed / virtual axes (Equipment) | [Inventory](inventory.md#the-asset-tree) (`EnergyAxis`) | +| Capability, Method (Recipe) | [Techniques](techniques.md) | +| Enclosure (Enclosure) | [The beamline](equipment/index.md) (9-ID-A optics, 9-ID-C endstation) | +| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](governance.md) | +| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | + +## Deliberately not here yet + +This is a design-phase scaffold (descriptor + docs), mirroring CHX, HXN, and the other reverse-engineered deployments. Left out on purpose: + +- **No new Family.** CDI is a reuse-and-reinforce deployment: the area detectors and diagnostic cameras bind `Camera`, the foil intensity monitor `FluxMonitor`, the pre-mirrors and the KB nanofocus pair `Mirror`, both monochromators `Monochromator`, the sample stack `Goniometer`, the white-beam / branch / conditioning slits `Slit`, the attenuator foils `Filter`, the undulator `InsertionDevice`, the master energy a `PseudoAxis`, and the endstation towers `LinearStage`. Nothing graduates and the catalog is unchanged. +- **The held loose families.** The `BeamPositionMonitor` (shared with 4-ID, 8-ID, ISS, FMX) binds a loose family that stays loose, matching the catalog note that position monitors stay loose; it is recorded in the promotion-review register. The `StorageRing` current readback is a loose supply observation (machine state), never an Asset Family. +- **No new Capability or Method.** Forward CDI, ptychography, and Bragg CDI sit on the deferred coherent-imaging Methods (`TECH-1`); CDI reinforces them without coining either, and records no Practice until they land. The phase retrieval and ptychographic reconstruction are `ComputePort` work, not a Method. +- **Operations and experiment views, integration scenarios, vendor Models.** A runbook and registered Assets for a beamline CORA does not yet drive would be invention; they land when the design firms and the team confirms. The [2-BM Model page](../2-bm/model.md) shows the shape a fully-modelled deployment carries. diff --git a/docs/deployments/cdi/questions.md b/docs/deployments/cdi/questions.md new file mode 100644 index 0000000000..4ff72f8fca --- /dev/null +++ b/docs/deployments/cdi/questions.md @@ -0,0 +1,38 @@ +# Open questions + +*What CORA needs the CDI team to confirm. This model is reverse-engineered from public open source (the [`NSLS2/cdi-profile-collection`](https://github.com/NSLS2/cdi-profile-collection) profile collection and the [`NSLS2/cditools`](https://github.com/NSLS2/cditools) device library): the EPICS PVs are read from them, but vendor identities, physical positions, and the timing configuration are not. Each row is a fact the beamline team owns. It is a delete-on-answer queue.* + +Priorities: `Blocks-build`, `Blocks-go-live`, `Nice-to-have`. + +## Source and safety + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| SRC-1 | Nice-to-have | IVU18 undulator period, gap range, and harmonic usage. The device (`SR:C09-ID:G1{IVU18:1}`) is confirmed. | An in-vacuum undulator, identity-only. | The InsertionDevice settings. | +| PSS-1 | Blocks-go-live | The PSS search-and-secure permit-leaf PVs and the photon-shutter PVs. Neither is in source. | The permit signal is a confirm note, not a guessed PV. | The Enclosure permit signals. | +| ENC-1 | Nice-to-have | Whether the 09IDB branch zone (`Slt:DM3`, the quadrant BPM) is a distinct access-gated enclosure or part of the optics hutch. | Two enclosures (9-ID-A optics, 9-ID-C endstation); 09IDB folded into the optics zone. | The Enclosure boundaries. | + +## Optics + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| DCM-1 | Nice-to-have | The Si DCM cryo detail and full range (the Si(111) reflection and `d = 3.1287 A` are read from the Energy model), and the DMM multilayer coating and bandpass. Both monochromators (`Mono:HDCM`, `Mono:DMM`) are in source. | Two Monochromator Assets, Si(111) recorded, other settings blank. | The Monochromator settings. | +| KB-1 | Blocks-go-live | The KB mirror focal size, coating / stripe, and working distance; whether both VKB and HKB are always installed. | A `Mirror` Asset (the KB pair); focus geometry blank. | The KB nanofocus spec. | +| ENERGY-1 | Nice-to-have | Whether incident energy is ever scanned as the measurement, and the true energy range (the `5-15 keV` bounds are marked `TODO: CHECK` in source). | Fixed-energy imaging; the range left provisional. | The energy Capability decision. | + +## Sample and detectors + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| STAGE-1 | Blocks-go-live | Which endstation tower (`TDMS:T1` / `TDMS:T2`) carries the sample versus the detector, the sample-to-detector distance that sets the q-range, and the full `Gon:1` goniometer axis set. Some tower axes are read-only pending commissioning in source. | Two `LinearStage` towers and a `Goniometer`; roles and distance deferred. | The endstation geometry. | +| DET-1 | Blocks-go-live | Which detector (Eiger2 / Merlin) is primary for which technique, the foil materials / thicknesses, and whether a direct-beam beamstop is installed (none is in source). | Both Cameras; Eiger2 primary; no beamstop modelled. | The detector roster and beamstop. | +| CAM-1 | Nice-to-have | Which diagnostic cameras (the BCU inline camera, the sample camera, the optics-module Prosilicas) are live. | The inline and sample cameras modelled; others noted. | The diagnostic-camera set. | +| DIAG-1 | Nice-to-have | The foil-monitor channel map and the quadrant / diamond BPM channels (the diamond BPM was repurposed from ion-chamber use in source). | Read-only flux and beam-position probes; channel maps blank. | The `FluxMonitor` and `BeamPositionMonitor` bindings. | + +## Controls and technique scope + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| TIMING-1 | Blocks-go-live | The exposure-gating chain. The profile collection exposes no trigger box (no Zebra / PandA startup file, no shutter PVs); the Eiger2 and Merlin carry internal and external trigger modes. How is a coherent-imaging exposure gated and synchronized with the scan? | Detector-internal triggering; no floor trigger box modelled. | The triggering chain. | +| DRIVE-1 | Blocks-go-live | The motion-controller box models, firmware, IPs behind the EPICS motor records. | One `MotionController` family bound (`EndstationMotionController`), specifics blank. | The MotionController Models. | +| TECH-1 | Blocks-go-live | Do the coherent-imaging Methods (forward CDI, ptychography, Bragg CDI) enter CORA's catalog, or stay deferred? This is the same owner-scope decision 8-ID opened. | Methods deferred (rendered unlinked), no Practice recorded. | The coherent-imaging Method scope. | diff --git a/docs/deployments/cdi/techniques.md b/docs/deployments/cdi/techniques.md new file mode 100644 index 0000000000..cf0e6598fe --- /dev/null +++ b/docs/deployments/cdi/techniques.md @@ -0,0 +1,20 @@ +# Techniques + +*What CORA would run at CDI: coherent-imaging techniques, each a [Catalog](../../catalog/methods.md) Method. CDI follows the deferral the coherent and scanning beamlines already set, after APS [8-ID](../8-id/techniques.md), [CHX](../chx/techniques.md), and [HXN](../hxn/techniques.md).* + +CDI's techniques are coherent diffractive imaging: focus a coherent beam, record the far-field diffraction pattern, and recover the real-space image offline by phase retrieval. These Methods are new to CORA's imaging- and spectroscopy-heritage catalog, so the Methods below render unlinked and are carried pending until the owner-scope decision (TECH-1) brings them into the catalog. + +| Technique | Catalog method | Notes | +| --- | --- | --- | +| Forward CDI | `coherent_diffraction_imaging` | a single far-field coherent-diffraction frame on the Eiger2 / Merlin from an isolated object; Method not yet in catalog | +| Ptychography | `ptychography` | a scan of overlapping coherent-diffraction frames across the sample; the reconstruction is a `ComputePort` leg, not a beamline Method (the HXN framing) | +| Bragg CDI | `coherent_diffraction_imaging` | a rocking series around a Bragg peak for strain imaging of a crystalline grain; the same imaging Method with the [goniometer](equipment/sample.md) setting the orientation | +| Alignment | [`alignment`](../../catalog/methods.md) | beam, KB, mirror, and slit tuning; reuses the existing Method | + +All three imaging techniques need the [KB nanofocus and sample stack](equipment/sample.md) and the [coherent detectors](equipment/detector.md); how the exposure is gated on the floor is the open timing question (TIMING-1). + +## Why the Methods stay deferred + +8-ID opened the question of which coherent Methods enter CORA's catalog (TECH-1): its XPCS has since graduated to a catalog `xpcs` Method, but its small-angle scattering and diffraction stayed pending, and CDI's coherent-imaging Methods are not coined at all. The concrete acquisition recipes (frame counts, scan grids, rocking ranges, exposures) join as the deployment approaches the point where CORA drives the beamline. CDI reinforces the case for a coherent-imaging Method without coining it, the same earn-the-abstraction discipline the deferred `small_angle_scattering` (8-ID, CHX) and ptychography (HXN) techniques follow. Because the defining Methods are not in the catalog, CDI records **no Practice** in the [NSLS-II Site](../nsls2/index.md), as CHX records none for its coherent-scattering Methods; the binding lands when the Method does. + +The phase retrieval itself (the iterative reconstruction that turns the diffraction frames into a real-space image, and the ptychographic engine that solves for object and probe together) is `ComputePort` work, not a beamline Method. This is the imaging analogue of CHX's correlation analysis: the beamline takes the frames, CORA's compute leg turns them into the result. diff --git a/docs/deployments/index.md b/docs/deployments/index.md index fcf4141f8b..5213b5fd42 100644 --- a/docs/deployments/index.md +++ b/docs/deployments/index.md @@ -65,6 +65,7 @@ The fourth Site CORA models. Like the Diamond exercise, its beamlines are revers | [XFM](xfm/index.md) | Reverse-engineered | scanning X-ray fluorescence microprobe (raster XRF mapping on the Xspress3 + Maia detectors, bending magnet), 4-BM; CORA's 2nd scanning-XRF after 2-ID; modelled from public beamline config | | [LIX](lix/index.md) | Reverse-engineered | life-science solution scattering (bio-SAXS/WAXS, in-line SEC-SAXS) and scanning-microbeam mapping, 16-ID; the fleet's first solution beamline and fluidic sample-delivery chain; modelled from public beamline config | | [HEX](hex/index.md) | Reverse-engineered | high-energy engineering X-ray scattering (imaging/tomography + energy-dispersive and powder diffraction on a superconducting wiggler, white 30-250 keV / mono 30-200 keV), 27-ID; the fleet's first true high-energy hard X-ray beamline; modelled from public beamline config | +| [CDI](cdi/index.md) | Reverse-engineered | coherent diffractive imaging (forward CDI, ptychography, Bragg CDI) with a KB nanofocus and Eiger2 / Merlin photon-counting detectors, 9-ID; the fleet's first dedicated coherent-imaging beamline (distinct from APS 9-ID); modelled from public beamline config | ## [SLAC](slac/index.md) diff --git a/mkdocs.yml b/mkdocs.yml index abeb0273ff..7264e56b76 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -602,6 +602,19 @@ nav: - Techniques: deployments/hex/techniques.md - Governance: deployments/hex/governance.md - Model: deployments/hex/model.md + - CDI: + - deployments/cdi/index.md + - Open questions: deployments/cdi/questions.md + - The beamline: + - deployments/cdi/equipment/index.md + - Source: deployments/cdi/beamline.md + - Sample: deployments/cdi/equipment/sample.md + - Detector: deployments/cdi/equipment/detector.md + - Controls: deployments/cdi/equipment/controls.md + - Inventory: deployments/cdi/inventory.md + - Techniques: deployments/cdi/techniques.md + - Governance: deployments/cdi/governance.md + - Model: deployments/cdi/model.md - SLAC: - deployments/slac/index.md - LCLS-MFX: From 8a16ef8f1fe15a124fbd6cc6c64eef8faedaa51c Mon Sep 17 00:00:00 2001 From: Doga Gursoy Date: Fri, 26 Jun 2026 18:13:32 +0300 Subject: [PATCH 2/2] fix(cdi): add MACHINE-1 and GOV-1 question rows for the dangling references The CDI governance page cites (GOV-1) and the descriptor references MACHINE-1 (the loose StorageRing supply readback) three times, but questions.md carried neither row, so both citations pointed nowhere. Every other NSLS-II deployment that binds a StorageRing or cites GOV-1 surfaces these rows; add them to match, keeping the delete-on-answer queue resolvable. Surfaced by the adversarial per-file verification on the PDF twin. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/deployments/cdi/questions.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/deployments/cdi/questions.md b/docs/deployments/cdi/questions.md index 4ff72f8fca..f385ad22f1 100644 --- a/docs/deployments/cdi/questions.md +++ b/docs/deployments/cdi/questions.md @@ -11,6 +11,8 @@ Priorities: `Blocks-build`, `Blocks-go-live`, `Nice-to-have`. | SRC-1 | Nice-to-have | IVU18 undulator period, gap range, and harmonic usage. The device (`SR:C09-ID:G1{IVU18:1}`) is confirmed. | An in-vacuum undulator, identity-only. | The InsertionDevice settings. | | PSS-1 | Blocks-go-live | The PSS search-and-secure permit-leaf PVs and the photon-shutter PVs. Neither is in source. | The permit signal is a confirm note, not a guessed PV. | The Enclosure permit signals. | | ENC-1 | Nice-to-have | Whether the 09IDB branch zone (`Slt:DM3`, the quadrant BPM) is a distinct access-gated enclosure or part of the optics hutch. | Two enclosures (9-ID-A optics, 9-ID-C endstation); 09IDB folded into the optics zone. | The Enclosure boundaries. | +| MACHINE-1 | Nice-to-have | The storage-ring state CDI reads (current, fill, status). | Observe-only machine state, a loose `StorageRing`; the exact PVs beyond `ring_current` pending. | The machine-state observation. | +| GOV-1 | Nice-to-have | The NSLS-II operator pool and safety-review structure (site-level, shared across the beamlines). | Carried pending on the NSLS-II Site, not instantiated per beamline. | The governance principals. | ## Optics