feat(i13-1): scaffold Diamond I13-1 (I13 coherence branch) deployment, the fleet's first coherent lensless imaging (ptychography / CDI), reverse-engineered and deliberately partial

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

@@ -275,6 +275,7 @@ def test_practice_method_links_only_known() -> None:
     "small_angle_scattering": "i22 + 8-ID SAXS; portable Method not yet earned",
     "wide_angle_scattering": "i22 + 9-ID WAXS; portable Method not yet earned",
     "ultra_small_angle_scattering": "12-ID-E Bonse-Hart USAXS; not yet earned (USAXS-1)",
+    "ptychography": "I13-1 ptychography / coherent diffraction imaging; not yet earned (TECH-1)",
     "total_scattering": "i15-1 total scattering / PDF; Method not yet earned",
     "powder_diffraction": "i11 powder diffraction; portable Method not yet earned",
     "energy_dispersive_exafs": "i20-1 EDE; dispersive devices not yet in source (POLY-1 / STRIP-1)",

deployments/diamond/site.yaml

@@ -27,7 +27,7 @@ facility:
   heading: "Diamond Light Source"
   kind: Site
   institution: Diamond Light Source Ltd, Harwell Campus, Didcot, UK
-  beamlines: [I22, I03, I15-1, I11, I24, I06, I10, I20-1, I19]
+  beamlines: [I22, I03, I15-1, I11, I24, I06, I10, I20-1, I19, I13-1]
 
 # ISA-88 Site Recipes: the facility-adapted form of a catalog Method. All
 # pending in the design phase. I22 is a scattering beamline, so its practices
@@ -68,6 +68,10 @@ practices:
   # single crystal is a Practice-level science difference. The serial / microfocus
   # fixed-target raster sub-mode is deferred (SERIAL-1), not a separate practice.
   - {name: I19_diffraction_practice, method: diffraction, pending: true, note: "small-molecule single-crystal X-ray diffraction (chemical crystallography) on the Newport kappa four-circle + Eiger; reuses the 4-ID diffraction Method, a further consumer (TECH-1)"}
+  # I13-1 (I13 coherence branch) coherent lensless imaging. Ptychography raster-scans a
+  # coherent beam and reconstructs an image from the far-field diffraction; the fleet's
+  # first coherent diffractive imaging, a new Capability not yet in the catalog (TECH-1).
+  - {name: I13-1_ptychography_practice, method: ptychography, pending: true, note: "hard X-ray ptychography / coherent diffraction imaging: raster the piezo stage, capture far-field coherent diffraction on the Merlin, reconstruct downstream; new Capability not yet in the catalog (TECH-1)"}
 
 # Access BC Actors conceptually facility-wide at Diamond. Pending until the
 # Diamond operator and review structure is confirmed.

deployments/i13-1/beamline.yaml

@@ -0,0 +1,135 @@
+# I13-1 beamline descriptor (Diamond), reverse-engineered
+#
+# I13-1 is the coherence branch of Diamond's I13 (Hard X-ray Imaging and Coherence)
+# beamline: hard X-ray ptychography and coherent diffraction imaging (CDI), a coherent
+# lensless-imaging technique that raster-scans a coherent beam across a sample and
+# reconstructs an image from the far-field diffraction it records. It is bound to the
+# Diamond Site (deployments/diamond/site.yaml), and is CORA's FIRST coherent
+# lensless-imaging deployment (the fleet has tomography, XRF microprobe, and a hard
+# X-ray nanoprobe, but no ptychography / CDI).
+#
+# STATUS: reverse-engineered, design-phase, and DELIBERATELY PARTIAL. The dodal source
+# (github.com/DiamondLightSource/dodal, src/dodal/beamlines/i13_1.py) currently exposes
+# only the coherence-branch endstation: a piezo sample-scanning stage, a side viewing
+# camera, and the Merlin coherent-diffraction area detector. The shared I13 source and
+# optics (the undulator, the monochromator, the mirrors, the slits) are NOT in dodal, so
+# they are deferred, not invented (SRC-1, OPT-1), the same partial-first-cut posture as
+# I20-1. EPICS PVs are real and read from dodal (the BL13J prefix); vendor part numbers,
+# serials, and physical positions are not in dodal and are open questions. Descriptor +
+# docs scaffold; scenarios deferred.
+#
+# WHAT IS NEW: the coherent lensless-imaging acquisition. Ptychography raster-scans a
+# coherent illumination across overlapping points on the sample and records a far-field
+# coherent-diffraction pattern at each point; the real-space image is reconstructed
+# downstream from the diffraction stack. That is a new Capability (the fleet's first
+# coherent diffractive imaging), deferred as a pending Method (TECH-1).
+#
+# MODELLING: I13-1 coins NO new Family and changes nothing in the catalog. The
+# scout-anticipated "coherent imaging" novelty is an acquisition shape (a Method), not a
+# device class: the devices are a raster sample stage and an area detector, both existing
+# families. The piezo sample-scanning stage binds the catalog LinearStage (the ptychography
+# raster is its operative motion; the fixed-angle lab-frame variant is a setting on the same
+# stage); the Merlin photon-counting detector and the side viewing camera bind the catalog
+# Camera; the machine state binds the loose StorageRing. Ptychography / CDI reuses no
+# existing technique (it is new to the fleet), so it is carried as a new pending Method
+# (TECH-1).
+#
+# Items left open are tagged inline with a (QUESTION-ID) answered on
+# docs/deployments/i13-1/questions.md.
+
+beamline:
+  name: I13-1
+  facility: diamond            # Diamond Site (facility_code: diamond)
+  sector: "Sector 13 (I13 coherence branch)"   # PV prefix BL13J
+  tier: Unit
+  parent: null
+  source: insertion-device
+  source_confirm: "I13 is an undulator beamline; dodal exposes only the I13-1 coherence-branch endstation, not the shared source, so the undulator and the shared optics are deferred (SRC-1, OPT-1)"
+
+# PV prefix: BL13J (the I13-1 coherence branch endstation). The shared I13 source and
+# optics are upstream and absent from dodal. Whether I13-1 is its own hutch and the PSS
+# permit leaves are open (ENC-1, PSS-1).
+enclosures:
+  - name: i13-1
+    role: experiment-hutch
+    facility_code: diamond
+    permit_signal: {confirm: "PSS permit leaf not in dodal; the I13-1 coherence-branch experiment hutch (BL13J), hutch grouping is ENC-1 (PSS-1)"}
+
+# ===========================================================================
+# SOURCE STAGE: the machine state (the shared source and optics are deferred)
+# ===========================================================================
+
+machine:
+  stage: source
+  enclosure: i13-1
+  intro: "The machine-level source state, observed not driven. The shared I13 source and optics are upstream and not yet in scope (SRC-1, OPT-1)."
+  note: "dodal's Synchrotron device is the observe-only machine state, the loose StorageRing pattern reused from the Diamond siblings (MACHINE-1). The undulator, monochromator, mirrors, and slits are absent from the i13_1 dodal module and are deferred (SRC-1, OPT-1)."
+  devices:
+    - name: StorageRing
+      family: StorageRing              # loose Family (machine-level observe-only source state; MACHINE-1)
+      pv: {confirm: "Diamond storage-ring state (current, fill); observe-only, the exact PVs are MACHINE-1"}
+      new: true
+      confirm: true
+      note: "Diamond storage-ring state; observe-only; the shared I13 source / optics are deferred (SRC-1, OPT-1, MACHINE-1)"
+
+# ===========================================================================
+# ENDSTATION STAGE: the ptychography sample stage and the coherent-diffraction detector
+# ===========================================================================
+
+endstation:
+  stage: sample
+  enclosure: i13-1
+  intro: "The coherence-branch endstation: the piezo sample-scanning stage, the side viewing camera, and the Merlin coherent-diffraction area detector."
+  note: >
+    All reuse existing catalog Families. The piezo sample-scanning stage binds LinearStage
+    (the ptychography raster is its operative motion; the fixed-angle lab-frame variant is a
+    setting on the same stage, SAMPLE-1). The Merlin photon-counting detector and the side
+    viewing camera bind Camera (DET-1). The coherent lensless-imaging acquisition is a
+    Method, not a device (TECH-1).
+  devices:
+    - name: SampleStage
+      family: LinearStage
+      pv: "BL13J-MO-PI-02:"
+      new: true
+      confirm: true
+      note: "the PI piezo sample-scanning stage (x / y / z); the ptychography raster motion; a fixed-angle lab-frame variant is on BL13J-MO-PI-02:FIXANG: as a setting on the same stage (SAMPLE-1)"
+    - name: SideCamera
+      family: Camera
+      pv: "BL13J-OP-FLOAT-03:"
+      new: true
+      confirm: true
+      note: "the side viewing camera (an Aravis / GenICam optical camera) for sample alignment (DET-1)"
+    - name: Detector
+      family: Camera
+      pv: "BL13J-EA-DET-04:"
+      new: true
+      confirm: true
+      note: "the Merlin (Medipix3) photon-counting area detector recording the far-field coherent-diffraction pattern; the science detector for ptychography / CDI (DET-1)"
+
+# Cross-cutting control. I13-1 runs EPICS (the floor); CORA observes and, where it
+# replaces bluesky-style orchestration, conducts over it. The handles above were read
+# from dodal and carried confirm (CTRL-1).
+controls:
+  intro: >
+    I13-1 runs on the Diamond EPICS / ophyd-async control stack, the same floor as the
+    other Diamond beamlines. The device handles above are bound from the
+    DiamondLightSource/dodal i13_1 module (the BL13J coherence-branch endstation), carried
+    confirm pending staff verification (CTRL-1). The shared I13 source and optics are
+    upstream and not yet in the dodal module, so they are deferred (SRC-1, OPT-1). The
+    ptychography acquisition (the raster scan of the piezo stage coupled to the Merlin
+    far-field capture, then the downstream reconstruction) runs through bluesky plans and
+    a reconstruction pipeline; that orchestration is the seam CORA's edge replaces, driving
+    through ophyd-async / EPICS, while the reconstruction is ComputePort work, not a beamline
+    device (TECH-1). The detector file-writing to the Diamond filestore is plumbing CORA
+    observes, not data it owns (see model.md).
+
+# Continuously-available resources a run draws on.
+resources:
+  intro: >
+    The continuously-available facility resources an I13-1 run needs. The coherent beam
+    path runs under vacuum (SUP-1).
+  supplies:
+    - kind: PhotonBeam
+    - kind: CoolingWater
+    - kind: Vacuum
+      note: "the coherent-beam flight path (SUP-1)"

docs/deployments/i13-1/equipment/controls.md

@@ -0,0 +1,58 @@
+# Controls
+
+*The control stack and the orchestration seam. Diamond EPICS / ophyd-async, with the dodal-derived handles for the coherence-branch endstation recorded. A deliberately partial first cut: only the endstation is in the module.*
+
+I13-1 runs the Diamond EPICS control stack driven through ophyd-async, the same floor as the other dodal-modelled Diamond beamlines. CORA observes that floor and, where it replaces bluesky-style orchestration, conducts over it; it does not replace EPICS. As at the other Diamond beamlines, the control handles are read from Diamond's open [`dodal`](https://github.com/DiamondLightSource/dodal) library, which records the real EPICS PV root for each device. The honest scope caveat sits at the top: the dodal `i13_1` module exposes **only** the coherence-branch endstation, so this scaffold carries handles for the sample stage and the two cameras and nothing upstream. The shared I13 source and optics (the undulator, monochromator, mirrors, and slits) are not in the module and are deferred, not invented (SRC-1, OPT-1).
+
+## Device handles
+
+CORA models each device's control handle as an opaque string set at the edge. For I13-1 the EPICS PV roots are read from dodal (`src/dodal/beamlines/i13_1.py`) and carried `confirm`, because a controls-library snapshot is not a guarantee against the live system (CTRL-1). The handles follow the Diamond convention, a PV root that encodes a functional zone rather than a hutch, all on the `BL13J` prefix of the coherence branch:
+
+| Asset | Family | PV root | What it does |
+| --- | --- | --- | --- |
+| `SampleStage` | [`LinearStage`](../../../catalog/families.md) | `BL13J-MO-PI-02:` | the PI piezo sample-scanning stage; the ptychography raster is its operative motion (SAMPLE-1) |
+| `SideCamera` | [`Camera`](../../../catalog/families.md) | `BL13J-OP-FLOAT-03:` | the Aravis / GenICam optical viewing camera, for sample alignment (DET-1) |
+| `Detector` | [`Camera`](../../../catalog/families.md) | `BL13J-EA-DET-04:` | the Merlin / Medipix3 photon-counting area detector, recording the far-field coherent-diffraction pattern (DET-1) |
+
+The fixed-angle lab-frame variant of the sample stage (`BL13J-MO-PI-02:FIXANG:`) is a setting on the same stage, not a second Asset (SAMPLE-1). The full handle list, Asset by Asset, is in the [Inventory](../inventory.md), and the source walk that binds each one is the generated [Source](../beamline.md) page.
+
+What dodal does **not** give for I13-1, and so is not invented here:
+
+- the shared source and optics: the module starts at the endstation, so there is no undulator, monochromator, mirror, or slit Asset to carry, and none is coined (SRC-1, OPT-1). The machine state above the branch is observed as a loose `StorageRing`, observe-only, with the source-side control story left to a later cut (MACHINE-1).
+- which access-gated enclosure the endstation maps to: the PV prefix encodes a functional zone, not the coherence-branch hutch or its safety meaning (ENC-1).
+- the calibrated values behind the handles, and the supporting infrastructure around the endstation (SUP-1).
+
+## The orchestration seam
+
+The ptychography acquisition is the seam a CORA edge replaces. Today it runs as bluesky plans over ophyd-async / EPICS: a raster scan of the PI piezo sample stage coupled to the Merlin far-field capture, the coherent beam stepped across the sample point by point while the photon-counting detector records the diffraction pattern at each position. That raster-coupled-to-capture loop is the orchestration CORA's edge conducts over the same floor, driving through ophyd-async rather than EPICS owning the loop.
+
+This is CORA's first coherent lensless-imaging deployment. The novelty is an acquisition shape and a reconstruction, not a device class: the devices are a raster `LinearStage` plus `Camera`s, so no new device Family is coined. Ptychography / CDI is carried as a new pending Method, the fleet's first coherent diffractive imaging (TECH-1), with the Site Practice `I13-1_ptychography_practice` carried pending alongside it.
+
+The downstream image reconstruction is not a beamline device. Recovering the real-space image from the recorded far-field diffraction stack is `ComputePort` work, the coherent-imaging analogue of the reconstruction legs at the imaging beamlines, run over the port rather than modelled as an endstation Asset.
+
+### The seam: CORA and the floor
+
+This is where CORA's design meets the I13-1 floor. The shape matches the other dodal-modelled Diamond beamlines'.
+
+CORA **owns** (its conducting engine, over the `ControlPort`):
+
+- the ptychography acquisition: emitting the raster trajectory over the PI piezo sample stage, coupling it to the Merlin far-field capture, and reading the diffraction frames through the series;
+- the choice of technique and timing, 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-async device layer (dodal): the PI sample stage, the side camera, the Merlin detector, the `ControlPort` boundary;
+- the shared source and optics once they are in scope and PV-bound (SRC-1, OPT-1);
+- the detector file-writing to the Diamond filestore, where the Merlin far-field frames land. That is plumbing CORA observes; CORA moves the frames, over the `TransferPort`, into CORA's own Dataset of record, and records the Dataset rather than adopting the facility's data catalog.
+
+So CORA brings one conducting engine to I13-1, working over the ports: the ptychography raster over the `ControlPort`, the image reconstruction (the diffraction-stack to real-space-image retrieval) over the `ComputePort`, and data egress over the `TransferPort` into the CORA Dataset. The reconstruction is a clean `ComputePort` leg, not a beamline device (TECH-1).
+
+The software IOCs (`Merlin`, the GenICam camera) are referenced by interface only, never registered as Assets.
+
+## Equipment protection
+
+The PSS search-and-secure permit signals, the photon and front-end shutters, and any interlock tier are **absent from the `i13_1` dodal module** and are not invented here (PSS-1). dodal is a device-control library, not a safety-system description: the coherence-branch module carries the endstation motion and camera handles, not the permit leaves behind an interlocked hutch. CORA names neither a permit signal nor a shutter for I13-1 until the beamline team supplies them. This is the same partial-first-cut posture the rest of the page takes: the shutters and interlocks live upstream with the shared source and optics that are also out of this cut (SRC-1, OPT-1).
+
+The Enclosure permit shape for the coherence-branch hutch and the hazard tier are carried pending at the Diamond Site; the governance and safety envelope follow the 2-BM shape (see [Governance](../governance.md) and [the safety envelope](../../diamond/index.md#the-safety-envelope)). The Diamond operator pool and review are pending at the Site (GOV-1), and Clearances are issued at the Diamond Site.
+
+See [Open questions](../questions.md) for the control, detection, and safety items still to confirm, and [Model](../model.md#deliberately-not-here-yet) for the deferred source and optics decisions and the pending ptychography Method (TECH-1).