From 2b484aa1f8293d03f89c4dc9f421c2ed695d516e Mon Sep 17 00:00:00 2001 From: Doga Gursoy Date: Fri, 26 Jun 2026 20:02:18 +0300 Subject: [PATCH] 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 I13-1 is the coherence branch of Diamond's I13 (Hard X-ray Imaging and Coherence) and CORA's FIRST coherent lensless-imaging deployment: hard X-ray ptychography and coherent diffraction imaging (raster a coherent beam across the sample, capture the far-field coherent diffraction, reconstruct a real-space image downstream). The fleet has tomography, an XRF microprobe, and a hard X-ray nanoprobe, but no ptychography / CDI. Reverse-engineered from DiamondLightSource/dodal (src/dodal/beamlines/i13_1.py), the 10th Diamond beamline. DELIBERATELY PARTIAL (the I20-1 posture). The dodal i13_1 module exposes only the coherence-branch endstation: a piezo sample-scanning stage, a side viewing camera, and the Merlin coherent-diffraction detector. The shared I13 source and optics (undulator, monochromator, mirrors, slits) are upstream and not in the module, so they are deferred, not invented (SRC-1, OPT-1). EPICS PVs (the BL13J prefix) are real, carried confirm. WHY zero new families. The novelty is an acquisition shape plus a reconstruction, i.e. a Method, NOT a device class: the devices the technique needs are a sample-scanning stage and area detectors, both already in the catalog. The scout that surfaced I13-1 anticipated a new "coherent imaging" device family; that is the wrong axis (the same over-prediction the eval corrected for i19's four-circle). So the PI piezo sample-scanning stage binds LinearStage (the ptychography raster is its operative motion; the fixed-angle lab-frame variant on BL13J-MO-PI-02:FIXANG: is a setting on the same stage), the Merlin (Medipix3) photon-counting detector and the Aravis side viewing camera bind Camera, and the machine state binds the loose StorageRing. Ptychography / CDI is carried as a new pending Method (the fleet's first coherent diffractive imaging); the image reconstruction from the diffraction stack is ComputePort work, not a beamline device (TECH-1). Zero new families, nothing graduates, the catalog is unchanged. Wiring: I13-1 added to the Diamond Site beamline list with a ptychography Practice; the new pending ptychography method added to the registry; mkdocs nav block. Gate: 410 deployment tests pass, mkdocs --strict builds clean, adversarial per-doc verify (generated-page list pre-fed: three wrong-depth cross-references fixed, a Detector / Controls / Merlin link pointing at the generated beamline.md instead of the equipment pages; no invention, the deferred shared source / optics confirmed absent not fabricated). Co-Authored-By: Claude Opus 4.8 --- .../unit/deployments/test_site_descriptor.py | 1 + deployments/diamond/site.yaml | 6 +- deployments/i13-1/beamline.yaml | 135 ++++++++++++++++++ docs/deployments/i13-1/equipment/controls.md | 58 ++++++++ docs/deployments/i13-1/equipment/detector.md | 26 ++++ docs/deployments/i13-1/equipment/index.md | 31 ++++ docs/deployments/i13-1/equipment/sample.md | 23 +++ docs/deployments/i13-1/governance.md | 46 ++++++ docs/deployments/i13-1/index.md | 71 +++++++++ docs/deployments/i13-1/inventory.md | 35 +++++ docs/deployments/i13-1/model.md | 38 +++++ docs/deployments/i13-1/questions.md | 36 +++++ docs/deployments/i13-1/techniques.md | 36 +++++ mkdocs.yml | 13 ++ 14 files changed, 554 insertions(+), 1 deletion(-) create mode 100644 deployments/i13-1/beamline.yaml create mode 100644 docs/deployments/i13-1/equipment/controls.md create mode 100644 docs/deployments/i13-1/equipment/detector.md create mode 100644 docs/deployments/i13-1/equipment/index.md create mode 100644 docs/deployments/i13-1/equipment/sample.md create mode 100644 docs/deployments/i13-1/governance.md create mode 100644 docs/deployments/i13-1/index.md create mode 100644 docs/deployments/i13-1/inventory.md create mode 100644 docs/deployments/i13-1/model.md create mode 100644 docs/deployments/i13-1/questions.md create mode 100644 docs/deployments/i13-1/techniques.md diff --git a/apps/api/tests/unit/deployments/test_site_descriptor.py b/apps/api/tests/unit/deployments/test_site_descriptor.py index 6ad41c7542..3c018b6531 100644 --- a/apps/api/tests/unit/deployments/test_site_descriptor.py +++ b/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)", diff --git a/deployments/diamond/site.yaml b/deployments/diamond/site.yaml index dfe27cc074..a71208ffdf 100644 --- a/deployments/diamond/site.yaml +++ b/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. diff --git a/deployments/i13-1/beamline.yaml b/deployments/i13-1/beamline.yaml new file mode 100644 index 0000000000..cd846dffee --- /dev/null +++ b/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)" diff --git a/docs/deployments/i13-1/equipment/controls.md b/docs/deployments/i13-1/equipment/controls.md new file mode 100644 index 0000000000..31ecd8f3f9 --- /dev/null +++ b/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). diff --git a/docs/deployments/i13-1/equipment/detector.md b/docs/deployments/i13-1/equipment/detector.md new file mode 100644 index 0000000000..907e7b91d1 --- /dev/null +++ b/docs/deployments/i13-1/equipment/detector.md @@ -0,0 +1,26 @@ +# Detector + +*The detection side. PVs reverse-engineered from dodal `src/dodal/beamlines/i13_1.py`, carried `confirm`. This is the coherence-branch endstation only; the shared I13 source and optics are upstream and deferred (SRC-1, OPT-1, see [the beam path](../beamline.md)).* + +Ptychography reconstructs a real-space image from the far-field diffraction a coherent beam throws as it is raster-scanned across the sample. So the detection side has two cameras with very different jobs: the science detector that records the far-field coherent-diffraction pattern, and the optical side camera that lets you see the sample to align it. + +| Asset | Family | PV | Role | +| --- | --- | --- | --- | +| `Detector` | [Camera](../../../catalog/families.md) | `BL13J-EA-DET-04:` | Merlin / Medipix3 photon-counting area detector; records the far-field coherent-diffraction pattern (DET-1) | +| `SideCamera` | [Camera](../../../catalog/families.md) | `BL13J-OP-FLOAT-03:` | Aravis / GenICam optical viewing camera; sample alignment (DET-1) | + +## The science detector: the Merlin + +The `Detector` is the Merlin photon-counting area detector built on a Medipix3 readout (`BL13J-EA-DET-04:`). It sits in the far field and records the coherent-diffraction pattern, the raw signal ptychography reconstructs from. It reuses the catalog `Camera` family: an area detector that returns frames is what `Camera` is, and a photon-counting far-field detector is a thin instance of it. CORA carries the PV `confirm` (DET-1) until it is bound on a live run. + +## The side camera: sample alignment + +The `SideCamera` is an Aravis / GenICam optical viewing camera (`BL13J-OP-FLOAT-03:`), the in-hutch eye used to align the sample before a scan. It also reuses `Camera` (DET-1). Two cameras, one family, different framing: one watches the diffraction, one watches the sample. + +## Why no new family for coherent imaging + +The scout anticipated a "coherent imaging device family." That is the wrong axis, and CORA does not coin it. What is new at I13-1 is not a device class, it is an *acquisition shape*: a coherent beam raster-scanned across the sample, plus a reconstruction. The hardware that carries that shape is ordinary, a raster `LinearStage` (the PI piezo sample stage, see [Sample](sample.md), SAMPLE-1) and two `Camera` instances. The novelty lives in the **Method**, ptychography / CDI, the fleet's first coherent diffractive imaging, carried pending (TECH-1). And the step that turns the diffraction stack into an image is `ComputePort` work, not a beamline device. Zero new families graduate from this cut; the catalog is unchanged. + +## What is deferred + +The shared I13 source and optics (undulator, monochromator, mirrors, slits) are upstream of the coherence branch and absent from the dodal module, so they are deferred rather than invented (SRC-1, OPT-1). The PSS search-and-secure permit signals and the photon / front-end shutters are likewise absent from the module and carried pending (PSS-1). The detection side modelled here is the endstation, not the beam that feeds it; see [the beam path](../beamline.md) for the generated source-walk. diff --git a/docs/deployments/i13-1/equipment/index.md b/docs/deployments/i13-1/equipment/index.md new file mode 100644 index 0000000000..24a9988fd0 --- /dev/null +++ b/docs/deployments/i13-1/equipment/index.md @@ -0,0 +1,31 @@ +# The beamline + +*The I13-1 coherence-branch endstation, area by area. CORA models the beamline as one root Asset (`I13-1`) with the devices nested below it; this page is the human walk, the [Inventory](../inventory.md) is the flat reference. This is a partial first cut: only the coherence-branch endstation is modelled, because that is all the public source exposes.* + +I13-1 is the coherence branch of Diamond's I13 (Hard X-ray Imaging and Coherence), where a coherent hard X-ray beam is raster-scanned across the sample and a real-space image is reconstructed from the far-field diffraction it records (ptychography and coherent diffraction imaging, TECH-1). The PV prefix is `BL13J`. The public dodal module (`src/dodal/beamlines/i13_1.py`) exposes only the endstation: the sample-scanning stage, a side viewing camera, and the Merlin coherent-diffraction detector. The shared I13 source and optics (undulator, monochromator, mirrors, slits) are upstream and absent from that module, so they are deferred, not invented (SRC-1, OPT-1). This is the same partial-first-cut posture as I20-1. + +CORA models stations as containment trees: an Asset nests under its station through `parent_id`, and controls relate sideways through `controller_id`. The root Asset is `I13-1` (`tier=Unit`, `facility_code=diamond`); the coherence-branch experiment hutch is the enclosure `i13-1` (ENC-1). + +``` + Source (storage ring, observe-only) i13-1 (coherence-branch hutch, BL13J) + ---------------------------------------- ------------------------------------------ + storage ring [shared src/optics: SRC-1, sample stage -> Merlin detector + OPT-1] side camera (alignment) +``` + +## Stations + +- [Source](../beamline.md): the machine-level storage ring (a loose `StorageRing`, machine state, observe-only). The shared I13 source and optics are upstream of the endstation and absent from the dodal module, so they are deferred (MACHINE-1, SRC-1, OPT-1). This page is generated from the descriptor. +- [Sample](sample.md): the PI piezo sample-scanning stage (`BL13J-MO-PI-02:`), whose raster is the operative ptychography motion (SAMPLE-1). +- [Detector](detector.md): the Merlin / Medipix3 photon-counting area detector that records the far-field coherent-diffraction pattern (`BL13J-EA-DET-04:`), plus the Aravis / GenICam side viewing camera used for sample alignment (`BL13J-OP-FLOAT-03:`) (DET-1). + +Each modelled device binds a catalog [Family](../../../catalog/families.md) and a verified EPICS PV (the storage ring has none); none binds a vendor Model, and no loose family is coined for coherent imaging. The novelty of this beamline is an acquisition shape and a reconstruction, that is a [Method](../../../catalog/methods.md) (ptychography / CDI, TECH-1), not a new device class: the devices are a raster `LinearStage` and two `Camera` instances. + +## Shared + +- [Controls](controls.md): the seam between CORA and the Diamond floor (Diamond EPICS / ophyd-async over the `ControlPort`), and where the deferred and absent pieces are tracked (CTRL-1). The PSS search-and-secure permit signals and the photon / front-end shutters are absent from the dodal module and carried pending, not invented (PSS-1). +- Resources: the photon beam delivered from the shared source, plus cooling water and vacuum. These site utilities are not in the endstation module and are carried pending (SUP-1). + +## Reference + +- [Inventory](../inventory.md): the flat list of every modelled Asset, its Family, its PV, and its open question. diff --git a/docs/deployments/i13-1/equipment/sample.md b/docs/deployments/i13-1/equipment/sample.md new file mode 100644 index 0000000000..11ff122bbb --- /dev/null +++ b/docs/deployments/i13-1/equipment/sample.md @@ -0,0 +1,23 @@ +# Sample + +*The sample-scanning side. PVs verified against dodal `src/dodal/beamlines/i13_1.py`, carried `confirm`.* + +I13-1 raster-scans a coherent beam across the sample and reconstructs a real-space image from the far-field diffraction it records (ptychography / CDI). On this side that means one thing: a stage that drives the raster. The dodal coherence-branch module exposes the sample stage and the two cameras, and nothing of the shared I13 source and optics upstream (SRC-1, OPT-1), so this page is the sample side only. + +| Asset | Family | PV | What it does | +| --- | --- | --- | --- | +| `SampleStage` | LinearStage | `BL13J-MO-PI-02:` | rasters the sample across the coherent beam (the ptychography scan) | + +## The sample stage + +The `SampleStage` is a PI piezo sample-scanning stage. Its operative motion is the ptychography raster: the scan trajectory that steps the sample through the coherent beam while the [detector](detector.md) records a far-field diffraction pattern at each point. CORA binds it to the catalog [`LinearStage`](../../../catalog/families.md) family; it carries the PVs `confirm` and tracks the stage's live status and full axis set as SAMPLE-1. + +The same stage also carries a fixed-angle lab-frame variant (`BL13J-MO-PI-02:FIXANG:`). This is **a setting on the one stage, not a second Asset**: the same `SAMPLE-1` hardware, addressed in a lab-frame fixed-angle configuration. It is noted here so the reader knows the two PV faces are one stage (SAMPLE-1). + +## Why no new family here + +The scout anticipated a "coherent imaging device family" for I13-1. That is the wrong axis. The novelty at a ptychography / CDI beamline is not a kind of device; it is an **acquisition shape plus a reconstruction**: raster the coherent beam, capture the far-field diffraction, and invert the diffraction stack into a real-space image. That belongs to a [Method](../../../catalog/methods.md), not to a device class. + +So the devices stay plain. The stage is a `LinearStage`, the [side camera and the Merlin detector](detector.md) are `Camera`s, and no family graduates. Ptychography / CDI is carried as a new pending Method (the fleet's first coherent diffractive imaging), TECH-1; the image reconstruction from the diffraction stack is `ComputePort` work, not a beamline device. The full deployment-level reasoning is on the [model](../model.md) page. + +The honest caveat is the partial scope: the shared I13 source and optics (the undulator, monochromator, and mirrors that condition the coherent beam this stage scans through) are absent from the dodal module and deferred, not invented (SRC-1, OPT-1). An in-situ sample environment, if I13-1 runs one, is likewise not in the module and left to a later cut. The [beamline](../beamline.md) source-walk and the [inventory](../inventory.md) carry the flat reference. diff --git a/docs/deployments/i13-1/governance.md b/docs/deployments/i13-1/governance.md new file mode 100644 index 0000000000..1df30ea52b --- /dev/null +++ b/docs/deployments/i13-1/governance.md @@ -0,0 +1,46 @@ +# Governance + +*Who may act at I13-1 and the trust shape CORA applies. This is CORA's governance design landing on the coherence-branch endstation, not a description of the beamline's current controls authority. Scaffold, not yet instantiated.* + +People and autonomous agents are facility principals at the [Diamond Site](../diamond/index.md#who-acts-here); on the beamline they surface through the actions they take. The human roster is not in the `i13_1` dodal module (GOV-1), so the principals are the design shape, not a registered list. This page follows the same model as the other Diamond beamlines, and the same partial-first-cut posture as the I13-1 scaffold overall: only the coherence-branch endstation is in this cut, and the shared I13 source and optics are deferred (SRC-1, OPT-1). + +## 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 Diamond Site. An I13-1 beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. The Diamond operator pool and review structure are site-level and shared across the beamlines, so they are not instantiated per beamline; they are carried pending on the [Diamond Site page](../diamond/index.md#who-acts-here) (GOV-1). None of this is in dodal, which is a controls library, not an organizational record. + +## 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 drive the [sample stage](equipment/sample.md) through a ptychography raster, arm the [Merlin detector](equipment/detector.md) to record the far-field coherent-diffraction pattern, view the sample on the side camera, override a caution, or commit an alignment. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer. The Diamond proposal and cycle are a fact CORA's Campaign uses for custody. + +Because I13-1 is a reverse-engineered scaffold rather than a pilot, the concrete trust shape (the Zone grouping the coherence-branch resources, the Conduit binding the surfaces that may issue commands, and the Policies that say who may do what) is named here, not built. It would land, following the [2-BM governance](../2-bm/governance.md) shape, if and when the deployment approaches real scope. + +## The Enclosure I13-1 gates + +This cut covers a single enclosure, the grouping CORA's Zone would follow (ENC-1): + +| Enclosure | PV zone | What it holds | +| --- | --- | --- | +| `i13-1` | `BL13J` | the coherence-branch experiment hutch: the PI piezo sample-scanning stage, the Aravis / GenICam side camera, and the Merlin / Medipix3 detector | + +The shared I13 source and the I13-2 imaging branch are out of this cut and not part of the Zone here (SRC-1, OPT-1). + +## The safety tier behind the beam + +The safety tier behind the beam is the personnel safety system. The leaves that must be satisfied before the beam can enter an enclosure are the PSS search-and-secure permit signals, and the photon and front-end shutters are what those leaves gate. Both the permit signals and the shutters are absent from the `i13_1` dodal module, so CORA does not name them and does not invent them: the Enclosure permit signals and the shutters are carried pending (PSS-1). When staff confirm the signal and shutter handles, they bind to the Enclosure as the permit leaves the way the Diamond siblings carry theirs. No interlock, PSS, or equipment-protection tier is invented in the meantime. + +Clearances (the safety forms that must be active to start) are issued at the Diamond Site, not on the beamline, and the beamline links up to them rather than restating them (GOV-1). The Diamond PSS clearance is carried pending because its form names are not confirmed (PSS-1). + +## Coherent imaging under custody + +I13-1's reason for existing is coherent lensless imaging: a ptychography or coherent-diffraction-imaging acquisition raster-scans the coherent beam across the sample and records the far-field diffraction, and a real-space image is reconstructed from that diffraction stack. In CORA's model this novelty is an acquisition shape and a reconstruction, a Method, not a new device class (TECH-1); the devices it gates are a raster LinearStage and Cameras (SAMPLE-1, DET-1), and the reconstruction is ComputePort work, not a beamline device. That makes the repeated raster acquisition the place CORA's custody and trust shapes would earn their keep: the trust boundary bounds who may drive the raster and arm the Merlin detector, and the Campaign and Subject shapes carry the sample's custody and the diffraction record. + +If an autonomous Agent were added (for example to step the raster or decide when a diffraction stack is complete enough to reconstruct), 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; with the shared source and optics deferred and the ptychography Method carried pending (SRC-1, OPT-1, TECH-1), this stays design intent. + +## What is deliberately not modelled + +- **The PSS permit signals and shutters (PSS-1).** Absent from the `i13_1` dodal module, carried pending, not invented. +- **The Diamond operator pool and review structure (GOV-1).** Site-level and shared across the beamlines, carried pending on the Diamond Site, not instantiated per beamline. +- **The shared I13 source and optics (SRC-1, OPT-1).** Upstream and absent from the module; deferred, not invented. No monochromator, mirror, slit, or undulator Asset is coined. +- **The concrete Zone, Conduit, and Policy instances.** Named as the trust shape, not built; they would land if and when the deployment approaches real scope, following the [2-BM governance](../2-bm/governance.md) shape. + +The full delete-on-answer queue is on [Open questions](questions.md); where each device and Method lands is on [Model](model.md). diff --git a/docs/deployments/i13-1/index.md b/docs/deployments/i13-1/index.md new file mode 100644 index 0000000000..c85b57eee1 --- /dev/null +++ b/docs/deployments/i13-1/index.md @@ -0,0 +1,71 @@ +# I13-1 + +*Hard X-ray ptychography and coherent diffraction imaging (CDI) on the coherence branch of Diamond I13: a coherent lensless-imaging technique that raster-scans a coherent beam across the sample and reconstructs a real-space image from the far-field diffraction it records. This page describes how CORA would model and run I13-1; the model is reverse-engineered from the dodal controls library, not yet confirmed by Diamond staff, and is a deliberately partial first cut.* + +| Property | Value | +| --- | --- | +| Asset | `I13-1` (root Asset, `tier = Unit`, `parent_id = None`) | +| Facility | [Diamond Light Source](../diamond/index.md) (bound via `facility_code = "diamond"`, `FacilityKind = Site`) | +| Sector | i13-1, the coherence branch of I13 (Hard X-ray Imaging and Coherence), Sector 13 (PV root `BL13J`, dodal module `i13_1`) | +| Status | First cut, **deliberately partial**: only the coherence-branch endstation; shared source and optics deferred (SRC-1, OPT-1) | +| Source | shared I13 undulator, upstream and not in the dodal module (deferred, SRC-1) | +| Control stack | Diamond EPICS / ophyd-async, read from dodal and carried `confirm` (CTRL-1) | + +!!! warning "How CORA would land on I13-1, and why this scaffold is partial" + These pages describe how CORA would model, govern, and conduct I13-1. They are not a survey of the beamline's current software. The hardware facts (devices, EPICS PVs) are read from the public [dodal](https://github.com/DiamondLightSource/dodal) controls library (`src/dodal/beamlines/i13_1.py`) and verified against it; every read value is carried `confirm` until staff verify it ([Open questions](questions.md)). **This is a deliberately partial first cut:** the dodal `i13_1` module exposes only the coherence-branch endstation (the sample stage, the side camera, the Merlin detector). The shared I13 source and optics (undulator, monochromator, mirrors, slits) are upstream and not in the module, so they are deferred, not invented (SRC-1, OPT-1). This is the same partial-first-cut posture as [I20-1](../i20-1/index.md). This is a design-phase scaffold: the descriptor and these docs, with scenarios deferred. + +## What makes I13-1 different + +I13-1 is CORA's first coherent lensless-imaging beamline. The fleet has tomography, an XRF microprobe, and a hard X-ray nanoprobe, but no ptychography or CDI. 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. + +The novelty is **a Method, not a device family**: it is an acquisition shape (the coherent raster) plus a reconstruction, not a new class of hardware. The devices the technique needs are a sample-scanning stage and area detectors, both already in the catalog. So I13-1 coins no new Family and changes nothing in the catalog. The scout that surfaced I13-1 anticipated a new "coherent imaging" device family; that is the wrong axis (TECH-1). + +## Scope: what is and is not modelled + +| In this cut (the endstation) | Deferred (not invented) | +| --- | --- | +| `SampleStage`, the PI piezo sample-scanning stage, the ptychography raster (SAMPLE-1) | the shared I13 undulator source, upstream (SRC-1) | +| `SideCamera`, the Aravis / GenICam side viewing camera, for alignment (DET-1) | the shared I13 optics: monochromator, mirrors, slits (OPT-1) | +| `Detector`, the Merlin (Medipix3) photon-counting science detector (DET-1) | the PSS search-and-secure permit signals and the photon / front-end shutters (PSS-1) | +| `StorageRing`, machine state, observe-only (MACHINE-1) | the I13-2 imaging branch (out of this cut) | + +The coherence-branch experiment hutch `i13-1` (`BL13J`) is the modelled Enclosure (ENC-1). + +## Key modelling decisions + +- **Zero new families.** Coherent imaging is an acquisition shape plus reconstruction, a Method, not a device class. Nothing graduates and the catalog is unchanged (TECH-1). +- **Coherent imaging is a Method.** Ptychography / CDI enters as a new pending Method, the fleet's first coherent diffractive imaging, carried pending; no `cora.capability.ptychography` is coined yet (TECH-1). +- **The raster binds `LinearStage`.** The PI piezo sample-scanning stage is the operative motion of the technique; the fixed-angle lab-frame variant (`BL13J-MO-PI-02:FIXANG:`) is a setting on the same stage, not a separate device (SAMPLE-1). +- **The detectors bind `Camera`.** The Merlin records the far-field coherent-diffraction pattern (the science detector); the side camera is for sample alignment (DET-1). The image reconstruction from the diffraction stack is `ComputePort` work, not a beamline device. +- **Deliberately partial.** The shared I13 source and optics are absent from dodal and deferred, not invented (SRC-1, OPT-1). + +## The beamline + +Along the beam, in order: + +- [Source](beamline.md): the shared I13 undulator source (upstream, absent from the dodal module, SRC-1) and the shared optics (OPT-1). +- [Sample](equipment/sample.md): the PI piezo sample-scanning stage, the ptychography raster (SAMPLE-1). +- [Detector](equipment/detector.md): the Merlin (Medipix3) coherent-diffraction science detector and the side viewing camera (DET-1). + +Cutting across: + +- [Controls](equipment/controls.md): the EPICS PV handles read from dodal and carried `confirm` (CTRL-1); the PSS permit signals and shutters are absent from the module and pending (PSS-1). + +The cross-cutting reference view is the [Inventory](inventory.md), authored from the same descriptor as the generated [Source](beamline.md) walk. + +## Techniques + +[Techniques](techniques.md): ptychography / CDI, the fleet's first coherent lensless imaging, recorded as a pending Diamond Practice (`I13-1_ptychography_practice`, TECH-1). + +## Governance + +[Governance](governance.md): who may act at I13-1 and the trust shape CORA applies. People and autonomous agents are facility principals at the [Diamond Site](../diamond/index.md#who-acts-here), gated by a trust shape (Zone + Conduit + Policy). Clearances are issued at the Diamond Site; the operator pool and review are carried pending (GOV-1). + +## Model + +[Model](model.md): the developer's by-kind index into where each I13-1 aggregate's content lives, why coherent imaging coins no new family, and what the partial roster defers. + +## Not yet documented + +- **The shared I13 source and optics.** The undulator, monochromator, mirrors, and slits are upstream and absent from the dodal module, so they are deferred, not invented (SRC-1, OPT-1). +- **Operations and experiment views.** A runbook and a live experiment view for a beamline CORA does not yet drive would be invention; they land when the shared source and optics are PV-bound and the team confirms. diff --git a/docs/deployments/i13-1/inventory.md b/docs/deployments/i13-1/inventory.md new file mode 100644 index 0000000000..ed2b394081 --- /dev/null +++ b/docs/deployments/i13-1/inventory.md @@ -0,0 +1,35 @@ +# Inventory + +*The CORA Asset model for the operational core of I13-1 modelled today: the planned device tree and what still needs confirming.* + +This is a **deliberately partial** first cut: the dodal source (`src/dodal/beamlines/i13_1.py`) exposes only the coherence-branch endstation (the piezo sample stage, the side viewing camera, the Merlin detector), so the shared I13 source and optics are deferred, not invented (see [Model](model.md#deliberately-not-here-yet)). It is the cross-cutting reference view of the [Source](beamline.md) walk and the [Sample](equipment/sample.md) and [Detector](equipment/detector.md) pages, authored from the same [`beamline.yaml`](https://github.com/xmap/cora/blob/main/deployments/i13-1/beamline.yaml) descriptor. + +Devices bind to a catalog [Family](../../catalog/families.md) wherever one fits. I13-1, CORA's first coherent lensless-imaging beamline, coins **no new Family and changes nothing in the catalog**: the coherent imaging is an acquisition shape (a Method), not a device class, so the raster stage binds `LinearStage` and the detectors bind `Camera` (see [Model](model.md#what-makes-i13-1-new)). Control handles are filled from dodal; no vendor Models are bound. + +## The Asset tree + +Root Asset `I13-1` (`tier = Unit`, `facility_code = diamond`); sub-systems nest below by `parent_id`. + +| Asset | Tier | Family | Enclosure | Design spec / note | +| --- | --- | --- | --- | --- | +| `I13-1` | `Unit` | (root) | - | bound to the Diamond Site; the I13 coherence branch (BL13J) | +| `StorageRing` | `Device` | StorageRing (loose) | - | machine-level ring state, observe-only; shared source / optics deferred (MACHINE-1, SRC-1, OPT-1) | +| `SampleStage` | `Device` | LinearStage | i13-1 | PI piezo sample-scanning stage (the ptychography raster), `BL13J-MO-PI-02` (SAMPLE-1) | +| `SideCamera` | `Device` | Camera | i13-1 | Aravis / GenICam side viewing camera for alignment, `BL13J-OP-FLOAT-03` (DET-1) | +| `Detector` | `Device` | Camera | i13-1 | Merlin (Medipix3) photon-counting coherent-diffraction detector, `BL13J-EA-DET-04` (DET-1) | + +Families reused from the catalog: `LinearStage`, `Camera`. Loose families reused from siblings: `StorageRing` (supply). No new family is coined and nothing graduates. + +## Pending confirmations + +| Value to confirm | Applies to | Status | Tracking | +| --- | --- | --- | --- | +| I13-1 hutch grouping and the I13-2 / shared-source relation | the enclosures | `unknown-pending-confirmation` | (ENC-1) | +| The shared I13 undulator source | the source | `unknown-pending-confirmation` | (SRC-1) | +| The shared I13 optics (mono, mirrors, slits) | the optics | `unknown-pending-confirmation` | (OPT-1) | +| Control handles (EPICS PVs) | all devices | `read-from-config-pending-confirmation` | (CTRL-1) | +| PSS permit signals and shutters | the enclosure | `unknown-pending-confirmation` | (PSS-1) | +| Storage-ring state read | `StorageRing` | `unknown-pending-confirmation` | (MACHINE-1) | +| Sample-stage axes and the fixed-angle frame | `SampleStage` | `unknown-pending-confirmation` | (SAMPLE-1) | +| Merlin detector config and the side-camera role | `Detector`, `SideCamera` | `unknown-pending-confirmation` | (DET-1) | +| Vacuum extent | `resources` | `unknown-pending-confirmation` | (SUP-1) | diff --git a/docs/deployments/i13-1/model.md b/docs/deployments/i13-1/model.md new file mode 100644 index 0000000000..a391bf7623 --- /dev/null +++ b/docs/deployments/i13-1/model.md @@ -0,0 +1,38 @@ +# Model + +*The developer's index into where I13-1 content lives, why coherent imaging coins no new family, and the record of what is deliberately deferred. First cut, deliberately partial.* + +I13-1 is a descriptor-and-docs scaffold today, reverse-engineered from the beamline's dodal device layer: it exists as the descriptor and docs below, not yet as registered events or integration scenarios. This page points to where each piece lives, and records the scope decisions that are CORA's to make (kept off the staff [Open questions](questions.md), which carry only world-facts). + +| Kind | Where | Notes | +| --- | --- | --- | +| Beamline descriptor | [`deployments/i13-1/beamline.yaml`](https://github.com/xmap/cora/blob/main/deployments/i13-1/beamline.yaml) | the device walk with bound PVs; source of the generated [Source](beamline.md) page | +| Site descriptor | [`deployments/diamond/site.yaml`](https://github.com/xmap/cora/blob/main/deployments/diamond/site.yaml) | the Diamond facility surface; `I13-1` added to its beamline list, with a ptychography Practice | +| Extraction provenance | [DiamondLightSource/dodal](https://github.com/DiamondLightSource/dodal) | the `src/dodal/beamlines/i13_1.py` factory the descriptor was curated from | +| Catalog Family | [`catalog/catalog.yaml`](https://github.com/xmap/cora/blob/main/catalog/catalog.yaml) | none changed; every device reuses an existing catalog or loose Family | +| Catalog Method | [`catalog/catalog.yaml`](https://github.com/xmap/cora/blob/main/catalog/catalog.yaml) | none added; the ptychography Method is pending (TECH-1) | +| Equipment Assets | not yet registered | the [Inventory](inventory.md) is the planned shape; no scenario registers I13-1 Assets yet | +| Trust / governance | not yet instantiated | see [Governance](governance.md) | + +## What makes I13-1 new + +I13-1 is CORA's first coherent lensless-imaging beamline. The fleet has tomography, XRF microprobe, and a hard X-ray nanoprobe (HXN), but no ptychography or coherent diffraction imaging (CDI). 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 the novelty, and it is an **acquisition shape plus a reconstruction**, a new Capability deferred as a pending Method (`TECH-1`), not a new device class. + +## No new families + +The scout that surfaced I13-1 anticipated a new "coherent imaging" device family. That is the wrong axis: coherent imaging is a Method, not a device. The devices the technique needs are a sample-scanning stage and an area detector, both of which the catalog already covers, so I13-1 coins no new Family and changes nothing in the catalog: + +- **The piezo sample-scanning stage binds the catalog `LinearStage`.** The ptychography raster is its operative motion; the fixed-angle lab-frame variant (`BL13J-MO-PI-02:FIXANG:`) is a setting on the same stage, not a separate device class (`SAMPLE-1`). +- **The Merlin photon-counting detector and the side viewing camera bind the catalog `Camera`.** The Merlin records the far-field coherent-diffraction pattern (the science detector); the side camera is for alignment (`DET-1`). +- **The machine state binds the loose `StorageRing`** (`MACHINE-1`). + +The coherent imaging itself is the `ptychography` Method, the fleet's first, carried pending (`TECH-1`). + +## Deliberately not here yet + +- **The shared I13 source and optics (`SRC-1`, `OPT-1`).** The dodal `i13_1` module exposes only the coherence-branch endstation; the undulator, monochromator, mirrors, and slits are upstream and not in the module, so they are deferred, not invented. This is the same partial-first-cut posture as I20-1. +- **The ptychography Method and the reconstruction.** Whether ptychography / CDI enters CORA's catalog as a Capability / Method is an owner decision; the Practice renders unlinked, pending (`TECH-1`). The image reconstruction from the diffraction stack is `ComputePort` work, not a beamline device. +- **The simulated devices and full asset-tree scenarios.** No `test_i13_1_*.py` registers the asset tree, and no vendor Models are bound. +- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). + +The [2-BM Model page](../2-bm/model.md) shows the by-kind index a fully-modelled deployment carries. diff --git a/docs/deployments/i13-1/questions.md b/docs/deployments/i13-1/questions.md new file mode 100644 index 0000000000..255b9d74a6 --- /dev/null +++ b/docs/deployments/i13-1/questions.md @@ -0,0 +1,36 @@ +# Open questions + +*What CORA needs the I13-1 team to confirm before the model can be trusted.* + +I13-1 was reverse-engineered from the beamline's own bluesky device layer ([DiamondLightSource/dodal](https://github.com/DiamondLightSource/dodal), `src/dodal/beamlines/i13_1.py`), so the control handles in the [Inventory](inventory.md) are the beamline's real PVs, read from dodal rather than confirmed by staff. This is a **deliberately partial** first cut: dodal currently exposes only the coherence-branch endstation, so the shared I13 source and optics are deferred, not invented. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](model.md#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. + +## Topology and scope + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| ENC-1 | Blocks-go-live | Is I13-1 its own experiment hutch, and how does it relate to the I13-2 imaging branch and the shared I13 source? | One `i13-1` experiment hutch on the `BL13J` prefix. | The Enclosure grouping. | +| SRC-1 | Blocks-go-live | The shared I13 undulator source, absent from the i13_1 dodal module. | An undulator upstream, not modelled in this partial cut. | The source Asset. | +| OPT-1 | Blocks-go-live | The shared I13 optics (monochromator, mirrors, slits), absent from the i13_1 dodal module. | Shared optics upstream, not modelled in this partial cut. | The optics Assets. | + +## Endstation + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| SAMPLE-1 | Blocks-go-live | The piezo sample-scanning stage axes, and the fixed-angle lab-frame variant (`BL13J-MO-PI-02:FIXANG:`): one stage with two reference frames or two stages? | One `LinearStage` (the ptychography raster); the fixed-angle frame a setting on the same stage. | The sample-stage modelling. | +| DET-1 | Blocks-go-live | The Merlin (Medipix3) detector configuration and the side viewing camera role. | The Merlin and the side camera bind `Camera`; the Merlin is the coherent-diffraction science detector. | The detector modelling. | + +## Control and safety + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| CTRL-1 | Blocks-go-live | Are the EPICS PV handles read from dodal current and correct? | The handles in the descriptor are taken from dodal and carried confirm. | Verifying each Asset's control handle. | +| PSS-1 | Blocks-go-live | The PSS search-and-secure permit signals and the photon / front-end shutters (absent from the i13_1 dodal module). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | +| MACHINE-1 | Nice-to-have | The storage-ring state I13-1 reads. | Observe-only machine state, a loose `StorageRing`; the exact PVs pending. | The machine-state observation. | +| SUP-1 | Nice-to-have | The vacuum extent of the coherent-beam path. | Photon beam, cooling water, and vacuum on the flight path. | The Supply observations. | +| GOV-1 | Nice-to-have | The Diamond operator pool and safety-review structure (site-level, shared across the beamlines). | Carried pending on the Diamond Site, not instantiated per beamline. | The governance principals. | + +## Technique + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| TECH-1 | Blocks-go-live | Does ptychography / coherent diffraction imaging enter CORA's catalog as a Capability / Method? | Deferred: carried as a pending Practice; the fleet's first coherent diffractive imaging, no `cora.capability.ptychography` coined. | The ptychography Capability. | diff --git a/docs/deployments/i13-1/techniques.md b/docs/deployments/i13-1/techniques.md new file mode 100644 index 0000000000..ac0c974860 --- /dev/null +++ b/docs/deployments/i13-1/techniques.md @@ -0,0 +1,36 @@ +# Techniques + +*What CORA would run at I13-1: hard X-ray ptychography and coherent diffraction imaging, a [Catalog](../../catalog/methods.md) Method bound through a [Diamond Practice](../diamond/index.md#the-techniques-adapted-here). It is the fleet's first coherent lensless imaging, and its Capability is new and deferred, the more so because only the coherence-branch endstation is in source.* + +| Technique | Catalog method | Notes | +| --- | --- | --- | +| Ptychography / coherent diffraction imaging (CDI) | `ptychography` | a coherent beam is raster-scanned across overlapping points on the sample and the far-field coherent-diffraction pattern is captured at each point; the real-space image is reconstructed downstream. The fleet's first coherent lensless imaging. New Capability, pending (TECH-1) | + +The technique is recorded as a pending [Practice](../diamond/index.md#the-techniques-adapted-here) on the Diamond Site, `I13-1_ptychography_practice` (TECH-1). + +## The acquisition shape + +Ptychography is not a new kind of device, it is a way of acquiring. A coherent beam is rastered across the sample in overlapping points, the [sample stage](equipment/sample.md) moving point to point (SAMPLE-1); at each point the Merlin (the Medipix3 photon-counting detector) records the far-field coherent-diffraction pattern; and the stack of diffraction patterns, together with the known scan positions, is enough to reconstruct a real-space image of the sample. The overlap between adjacent points is what makes the reconstruction tractable. + +CDI is the same lensless-imaging idea read from far-field coherent diffraction; CORA carries the pair under the one `ptychography` Method (TECH-1). + +So the parts in source are a raster `LinearStage` (the PI piezo sample-scanning stage, SAMPLE-1) and two `Camera`s: the Merlin as the science detector that records each diffraction frame, and the Aravis / GenICam side camera for sample alignment (DET-1). The novelty lives in how they are driven and in what happens afterward, not in a new device class. + +## Why the Capability is new, and deferred + +Ptychography is a genuinely new science Capability for CORA. The fleet has tomography, an XRF microprobe, and a hard X-ray nanoprobe, but no coherent lensless imaging: nowhere yet does a beamline raster a coherent beam and reconstruct an image from the diffraction it scatters. CORA carries the `ptychography` Method as pending rather than coining it outright, the same earn-the-abstraction discipline every new-domain technique follows (TECH-1). + +It would be tempting to read the novelty as a new device family, a "coherent imaging" class. That is the wrong axis. The coherence is a property of the beam and the acquisition, and the devices that realise it are a raster `LinearStage` and `Camera`s already in the Catalog. The new thing is a Method, an acquisition shape plus a reconstruction, and it adds no Family ([Model](model.md)). + +The image reconstruction, turning the stack of far-field diffraction patterns into a real-space image, is `ComputePort` work, not a beamline Method. It runs downstream of the acquisition, not on a device on the floor. + +## Not modelled yet + +This is a deliberately partial first cut, the same posture as the sibling i20-1 scaffold. The public dodal module exposes only the coherence-branch endstation, the sample stage, the side camera, and the Merlin detector. What sits upstream is absent from source and deferred, not invented: + +- The shared I13 source and the optics that condition the coherent beam (the undulator, monochromator, mirrors, and slits) are upstream of the endstation and not in the module. They are carried as open questions, not fabricated (SRC-1, OPT-1). +- The machine state is observe-only against a loose `StorageRing`; the shared source is deferred with it (MACHINE-1, SRC-1). +- The PSS search-and-secure permit signals and the photon / front-end shutters are absent from the dodal module and carried pending, not invented (PSS-1). +- Beam-conditioning and shutter conduct paths, and the supporting infrastructure around the endstation, follow once their devices are in source (CTRL-1, SUP-1). + +Each of these is named on the [Open questions](questions.md) page rather than guessed at. The source walk that grounds what is and is not present is the generated [beamline](beamline.md) view. diff --git a/mkdocs.yml b/mkdocs.yml index 7d33e95345..b9cc1f9e3f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -359,6 +359,19 @@ nav: - Techniques: deployments/i19/techniques.md - Governance: deployments/i19/governance.md - Model: deployments/i19/model.md + - I13-1: + - deployments/i13-1/index.md + - Open questions: deployments/i13-1/questions.md + - The beamline: + - deployments/i13-1/equipment/index.md + - Source: deployments/i13-1/beamline.md + - Sample: deployments/i13-1/equipment/sample.md + - Detector: deployments/i13-1/equipment/detector.md + - Controls: deployments/i13-1/equipment/controls.md + - Inventory: deployments/i13-1/inventory.md + - Techniques: deployments/i13-1/techniques.md + - Governance: deployments/i13-1/governance.md + - Model: deployments/i13-1/model.md - NSLS-II: - deployments/nsls2/index.md - FXI: