From 7b29e1c6134443ec00f358533048ce2ba926d441 Mon Sep 17 00:00:00 2001 From: Doga Gursoy Date: Fri, 26 Jun 2026 18:09:42 +0300 Subject: [PATCH] feat(pdf): scaffold NSLS-II PDF (28-ID-1) deployment (high-energy total scattering / pair distribution function, XPD's twin), reverse-engineered PDF is the NSLS-II high-energy total-scattering and powder-diffraction beamline at sector 28-ID-1, the dedicated pair-distribution-function endstation: a high-energy beam through a powder or capillary sample onto large flat-panel and pixel area detectors, with a near and a far detector distance merged to reach the high Q a PDF needs. Reverse-engineered from public open source (NSLS2/pdf-profile-collection startup scripts + the NSLS2/pdftools device classes). Descriptor + docs scaffold; EPICS PVs real and read from source, every value carried confirm; scenarios deferred. TWIN. PDF (28-ID-1, XF:28ID1*) and XPD (28-ID-2, deployments/xpd) are the two endstations on the shared 28-ID damping wiggler: same science family (high-energy powder diffraction and total scattering / PDF), different branch and PV namespace. PDF is the dedicated total-scattering / PDF endstation and reuses XPD's modelling. WHY no catalog change, and where PDF differs. Zero new families, nothing graduates. The flat-panel and pixel area detectors reuse Camera; the photodiode flux monitor FluxMonitor; the cryostream / cryostat / furnace cluster TemperatureController (graduated #350); the side-bounce Laue monochromator Monochromator; the focusing mirror Mirror; the capillary spinner Goniometer; the slits Slit; the fast shutter Shutter; the beamstops BeamStop; the detector and sample-environment stages LinearStage; the master energy a PseudoAxis. The one loose family is the StorageRing supply readback (MACHINE-1). Two shapes distinguish PDF from XPD and are carried by what is real, not coined: a side-bounce (single Laue) monochromator instead of XPD's bent double-Laue (a Monochromator settings difference), and an explicit two-detector / two-distance acquisition that merges a near and a far panel for the PDF Q-range (DIST-1). The gas-handling / humidity rig present in source is carried deferred (ENV-1), the discipline that models the settled thermal environment and defers the in-situ actuators until they earn modelling. MODELLING: powder diffraction and total scattering / PDF sit on the deferred powder_diffraction / total_scattering Methods Diamond i11 and i15-1 left pending; PDF reinforces both at a second NSLS-II endstation without coining either, and following XPD records no Practice (TECH-1). Wiring: PDF added to the NSLS-II Site beamline list (no Practice, comment explains why); deployments index row; mkdocs nav block. No test-registry change (StorageRing is the supply-exempt loose family; PDF binds no other loose family and records no practice). The missing IOS index row noted earlier was already fixed upstream, so it is untouched here. Gate: 410 deployment unit tests pass, mkdocs --strict builds clean, adversarial per-file verify (11 independent verifiers vs the cloned source) caught four issues (a Linkam file miscitation, a "same set as XPD" overclaim for the Goniometer / BeamStop families XPD does not bind, and missing MACHINE-1 / GOV-1 question rows), all corrected and re-gated. Co-Authored-By: Claude Opus 4.8 (1M context) --- deployments/nsls2/site.yaml | 7 +- deployments/pdf/beamline.yaml | 230 +++++++++++++++++++++ docs/deployments/index.md | 1 + docs/deployments/pdf/equipment/controls.md | 30 +++ docs/deployments/pdf/equipment/detector.md | 24 +++ docs/deployments/pdf/equipment/index.md | 19 ++ docs/deployments/pdf/equipment/sample.md | 25 +++ docs/deployments/pdf/governance.md | 17 ++ docs/deployments/pdf/index.md | 50 +++++ docs/deployments/pdf/inventory.md | 54 +++++ docs/deployments/pdf/model.md | 25 +++ docs/deployments/pdf/questions.md | 44 ++++ docs/deployments/pdf/techniques.md | 19 ++ mkdocs.yml | 13 ++ 14 files changed, 557 insertions(+), 1 deletion(-) create mode 100644 deployments/pdf/beamline.yaml create mode 100644 docs/deployments/pdf/equipment/controls.md create mode 100644 docs/deployments/pdf/equipment/detector.md create mode 100644 docs/deployments/pdf/equipment/index.md create mode 100644 docs/deployments/pdf/equipment/sample.md create mode 100644 docs/deployments/pdf/governance.md create mode 100644 docs/deployments/pdf/index.md create mode 100644 docs/deployments/pdf/inventory.md create mode 100644 docs/deployments/pdf/model.md create mode 100644 docs/deployments/pdf/questions.md create mode 100644 docs/deployments/pdf/techniques.md diff --git a/deployments/nsls2/site.yaml b/deployments/nsls2/site.yaml index 641952d8e8..57d57443b5 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, AMX, XFP] + beamlines: [FXI, HXN, BMM, SRX, SIX, CHX, CSX, IOS, XPD, ESM, SMI, IXS, SST, ISS, FMX, CMS, XFM, LIX, HEX, AMX, XFP, PDF] # 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 @@ -150,6 +150,11 @@ practices: # footprinting) is new to the catalog; both modes share it, carried pending (TECH-1). - {name: XFP_footprinting_practice, method: x_ray_footprinting, pending: true, note: "X-ray footprinting of a biological macromolecule in solution: gate a timed white-beam dose onto a flowing capillary / flow-cell sample, recording exposure time x flux x attenuation as the delivered dose; the fleet's first dose-delivery Method, new to the catalog; structural readout is offline mass spec (TECH-1, READOUT-1)"} - {name: XFP_high_throughput_footprinting_practice, method: x_ray_footprinting, pending: true, note: "shutterless high-throughput footprinting: sweep a fly-cell row through the defining slit at a set stage velocity so the exposure (dose) is the slit gap over the velocity, across a 96-well plate; the same x_ray_footprinting Method with the HTFly stage as the dose-timing (TECH-1, HT-1)"} + # PDF (28-ID-1) is XPD's dedicated total-scattering / PDF twin on the shared 28-ID + # damping wiggler: high-energy powder diffraction and rapid-acquisition pair + # distribution function. Its techniques sit on the same deferred powder_diffraction / + # total_scattering Methods Diamond i11 and i15-1 left pending (TECH-1); following XPD, + # no PDF Practice is recorded until those land. PDF is bound via beamlines. # 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/deployments/pdf/beamline.yaml b/deployments/pdf/beamline.yaml new file mode 100644 index 0000000000..c271420adb --- /dev/null +++ b/deployments/pdf/beamline.yaml @@ -0,0 +1,230 @@ +# PDF beamline descriptor (NSLS-II), reverse-engineered +# +# PDF (Pair Distribution Function) is the NSLS-II high-energy total-scattering and +# powder-diffraction beamline at sector 28-ID-1. Its defining technique is the +# rapid-acquisition pair distribution function (total scattering): a high-energy beam +# through a powder or capillary sample onto large flat-panel area detectors, with the +# sample-to-detector distance setting the accessible Q and a near / far detector pair +# merged to reach the high Q a PDF needs. It is bound to the NSLS-II Site +# (deployments/nsls2/site.yaml). +# +# TWIN GUARD. PDF (28-ID-1, XF:28ID1*) and XPD (28-ID-2, XF:28ID*; deployments/xpd) +# are the two endstations on the shared 28-ID damping wiggler: same science family +# (high-energy powder diffraction and total scattering / PDF), different branch and +# PV namespace. PDF is the dedicated total-scattering / PDF endstation; XPD is its +# already-modelled twin. This descriptor reuses XPD's modelling wholesale. +# +# STATUS: reverse-engineered, design-phase. Every value is read from public open +# source (the bluesky profile collection NSLS2/pdf-profile-collection and the device +# library NSLS2/pdftools) or inferred, carried `confirm: true` pending PDF staff. +# EPICS PVs are real and verified against the startup scripts and the pdftools device +# classes; vendor part numbers, serials, and physical positions are not in them and +# are open questions. Same descriptor mode as XPD / CHX; this scaffold is descriptor +# + docs, scenarios deferred. +# +# PDF is the POWDER-DIFFRACTION / PDF reinforcement, the twin of XPD and (through it) +# of Diamond i11 (powder diffraction) and i15-1 (total scattering / PDF). It introduces +# NO new catalog family: the flat-panel and pixel area detectors reuse Camera, the +# photodiode flux monitor FluxMonitor, the cryostream / cryostat / furnace +# TemperatureController (graduated #350), the side-bounce Laue monochromator +# Monochromator, the focusing mirror Mirror, the spinner sample stage Goniometer, the +# slits Slit, the fast shutter Shutter, the beamstops BeamStop, the detector and +# sample-environment stages LinearStage, the master energy a PseudoAxis. Its one loose +# family is the StorageRing supply readback (MACHINE-1). Per the i11 / i15-1 / XPD +# precedent the powder-diffraction and total-scattering Methods are NOT coined here; +# they are the deferred owner-scope cohort (TECH-1). The two distinctive shapes vs XPD +# are carried by what is real, not coined: a side-bounce (single-bounce Laue) +# monochromator instead of XPD's bent double-Laue (a Monochromator settings +# difference), and an explicit two-detector / two-distance acquisition that merges a +# near and a far panel for the PDF Q-range (DIST-1). + +beamline: + name: PDF + facility: nsls2 # NSLS-II Site (facility_code: nsls2) + sector: "Sector 28" # PV namespace XF:28ID1* + tier: Unit + parent: null + source: insertion-device + source_confirm: "the source is the shared 28-ID damping wiggler (the high-flux high-energy source PDF and XPD both need); no source PV or parameters are in the profile collection, so the subtype is an inference pending staff confirmation (SRC-1)" + +enclosures: + # PV zones: 28ID1A first-optics hutch (FOE: the side-bounce mono and focusing + # mirror), 28ID1B the experiment hutch (the PDF / total-scattering endstation, with + # the spinner, the detector towers, the beamstops, and the sample environment). + - name: 28-ID-1-A + role: optics-hutch + facility_code: nsls2 + permit_signal: {confirm: "PSS search-and-secure permit leaf not in source; only the fast shutter (XF:28ID1B-OP{PSh:1-Det:2}) and a photon shutter are exposed, not the front-end PPS leaves (PSS-1)"} + - name: 28-ID-1-B + role: experiment-hutch + facility_code: nsls2 + permit_signal: {confirm: "PSS permit leaf unknown; 28-ID-1-B is the PDF / total-scattering endstation carrying the spinner, detector towers, and sample environment (PSS-1)"} + +# =========================================================================== +# SOURCE STAGE: the damping-wiggler source and the machine readback +# =========================================================================== + +source: + stage: source + enclosure: 28-ID-1-A + intro: The shared 28-ID damping-wiggler source feeding the high-energy beam, and the storage-ring readback. + devices: + - name: Source + family: InsertionDevice + confirm: true + note: "28-ID insertion-device source. No source PV or parameters are in the profile collection; from facility knowledge (not the public config) it is the shared 28-ID damping wiggler, the high-flux high-energy regime PDF needs, an inference pending staff confirmation (SRC-1). The same source feeds the XPD twin." + - 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 side-bounce monochromator, the focusing mirror, the slits +# =========================================================================== + +optics: + stage: source + enclosure: 28-ID-1-A + intro: "Condition the high-energy beam and set its energy: the side-bounce monochromator, the vertical focusing mirror, and the white-beam slits. PVs verified against startup/12-optics.py and pdftools/motors.py." + devices: + - name: Monochromator + family: Monochromator + pv: "XF:28ID1A-OP{Mono:SBM-Ax:" + confirm: true + note: "Side-bounce monochromator (class SideBounceMono, instance sbm): a single-bounce Laue crystal on wedge-mount X / Y, yaw / pitch / roll, and a four-corner bender (inboard / outboard, upper / lower). A high-flux high-energy mono, the PDF counterpart of XPD's bent double-Laue (a Monochromator settings difference, not a new family). The EnergyAxis below is the master energy; crystal cut and range pending (MONO-1)." + - name: VerticalFocusingMirror + family: Mirror + pv: "XF:28ID1A-OP{Mir:VFM-Ax:" + confirm: true + note: "Vertical focusing mirror (class Mirror, instance Mirror_VFM): upstream / downstream jacks and an upstream / downstream bender with encoders. Reuses the Mirror family." + - name: WhiteBeamSlit + family: Slit + pv: "XF:28ID1A-OP{Slt:0-Ax:" + confirm: true + note: "White-beam-defining slit (class Slits, instance WB_slits): top / bottom / inboard / outboard blades. A beam-defining slit (BDM_slits, Slt:1) sits on the same module. Reuses the Slit family." + - name: EnergyAxis + family: PseudoAxis + confirm: true + note: "The master energy axis set by the side-bounce monochromator. PDF runs at a fixed high energy per experiment; whether energy is ever scanned as the measurement is ENERGY-1." + +# =========================================================================== +# SAMPLE STAGE: the cleanup slit, the fast shutter, the spinner, the sample +# environment stages, and the thermal environment cluster +# =========================================================================== + +sample: + stage: sample + enclosure: 28-ID-1-B + intro: "The endstation beam conditioning and the sample side: the cleanup slit, the fast shutter, the capillary spinner, the sample-environment stage, and the thermal-environment cluster. PVs verified against startup/12-optics.py, 11-motors.py, 14-lakeshore_cryostat.py, 15-cs800crystream.py, 17-linkam.py and pdftools/sample_environment.py." + note: > + PDF positions a powder or capillary sample in the high-energy beam and records the + total-scattering pattern on the area detectors. The capillary spinner averages the + powder texture; the rich thermal-environment cluster (cryostream, cryostat, + furnace) drives in-situ variable-temperature studies. A gas-handling and humidity + rig is present in source but carried deferred (ENV-1). + devices: + - name: CleanupSlit + family: Slit + pv: "XF:28ID1B-OP{Slt:AS-Ax:" + confirm: true + note: "Endstation cleanup / guard slit (class Slits, instance cleanup_slits) trimming parasitic scatter ahead of the sample; an optics-cabin OCM slit (OCM_slits, Slt:2) sits upstream. Reuses the Slit family." + - name: FastShutter + family: Shutter + pv: "XF:28ID1B-OP{PSh:1-Det:2}" + confirm: true + note: "Fast exposure shutter (class PDFFastShutter, instance fs) gating the detector exposure; a slower photon shutter (class PDFShutter) sits alongside. Reuses the Shutter family." + - name: SpinnerGoniohead + family: Goniometer + pv: "XF:28ID1B-ES{Stg:Smpl-Ax:" + confirm: true + note: "Capillary-spinner goniohead (class SpinnerGoniohead / XYZSpinner, instance spinner_goniohead): sample X / Y / Z plus a spin axis (Ry) that rotates the capillary to average powder texture. An analyzer goniohead (analyzer_goniohead, Spn:Anlzr) sits alongside. Reuses the Goniometer family; the full axis modelling is STAGE-1." + - name: SampleEnvironmentStage + family: LinearStage + pv: "XF:28ID1B-ES{Env:1-Ax:" + confirm: true + note: "Sample-environment positioning stage (Grid_X / Grid_Y / Grid_Z) presenting the sample-environment cell to the beam; reuses the LinearStage family." + - name: SampleTemperature + family: TemperatureController + pv: "XF:28ID1-ES:1{Env:01}" + confirm: true + note: "Sample-environment thermal cluster: a cs800 cryostream controller (class CS800TemperatureController, XF:28ID1-ES:1{Env:01}, understood to be an Oxford Cryostream, inference, TEMP-1), a Lakeshore 336 cryostat (XF:28ID1-ES{LS336:1), and a Linkam T96 furnace (class LinkamFurnace_T96, XF:28ID1-ES{LINKAM:T96}:). Modelled as one thermal-environment Asset; reuses TemperatureController (graduated #350). Which units are live is TEMP-1." + +# =========================================================================== +# DETECTION STAGE: the flat-panel and pixel detectors, the two detector towers, +# the beamstops, and the flux monitor +# =========================================================================== + +detector: + stage: detection + enclosure: 28-ID-1-B + intro: "The large flat-panel and pixel area detectors for total scattering / PDF, the two detector towers that set the near and far distances, the beamstops, and the flux monitor. PVs verified against startup/80-areadetector2.py, 81-pilatus.py, 72-two-detector.py, 11-motors.py, 10-machine.py." + note: > + PDF's measurement is the total-scattering pattern on a large area detector. To + reach the high Q a pair distribution function needs, the detector sits close; a + near panel and a far panel are merged across two distances. The two detector towers + move the panels in and out, the explicit two-detector acquisition (DIST-1). All + reuse existing families. Which panels are live versus the spare set is DET-1. + devices: + - name: AreaDetector + family: Camera + pv: "XF:28ID1-ES{Det:PE1}" + confirm: true + note: "PerkinElmer flat-panel area detector (class PerkinElmerStandard, instance pe1; a second panel pe2 at Det:PE2). The primary total-scattering / powder detector; reuses Camera." + - name: PixelDetector + family: Camera + pv: "XF:28ID1-ES{Det:Pilatus}" + confirm: true + note: "Pilatus photon-counting pixel detector (class PilatusV33, instance pilatus-1) with an energy-thresholded readout, used alongside the flat panels for high-Q / low-background frames; reuses Camera. Which detector serves which distance is DET-1 / DIST-1." + - name: DetectorStage1 + family: LinearStage + pv: "XF:28ID1B-ES{Det:1-Ax:" + confirm: true + note: "First detector tower (Det_1_X / Det_1_Y / Det_1_Z): the Z axis sets the sample-to-detector distance and hence the accessible Q. In the two-detector acquisition this is the static panel. Reuses LinearStage." + - name: DetectorStage2 + family: LinearStage + pv: "XF:28ID1B-ES{Det:2-Ax:" + confirm: true + note: "Second detector tower (Det_2_X / Det_2_Y / Det_2_Z): the moving panel that steps in and out of the beam for the near / far two-distance merge (the TwoDetectors plan, 72-two-detector.py). Reuses LinearStage; the two-distance geometry is DIST-1." + - name: BeamStop + family: BeamStop + pv: "XF:28ID1B-ES{BS:1-Ax:" + confirm: true + note: "Direct-beam stop (class BeamStop, instance BStop1, X / Y); a second beamstop (BStop2, BS:2) and a table-mounted stop sit alongside, one per detector distance. Reuses the BeamStop family." + - name: FluxMonitor + family: FluxMonitor + pv: "XF:28ID1B-OP{Det:1-Det:2}Amp:bkgnd" + confirm: true + note: "Background photodiode (photodiode) reading incident-flux / background for normalization; reuses FluxMonitor (graduated #353). Channel detail pending (DIAG-1)." + +# =========================================================================== +# Cross-cutting controls +# =========================================================================== + +controls: + intro: > + PDF acquisition is software-triggered: the flat-panel detectors run in continuous + or multi-trigger mode gated by the fast exposure shutter, with no separate hardware + timing box in the profile collection, the same shape as XPD. The two-detector + two-distance merge is sequenced by a bluesky plan (the TwoDetectors helper), not a + hardware trigger. Controller box models / firmware are not in the profile + collection (DRIVE-1). + motion_controllers: + - name: EndstationMotionController + family: MotionController + confirm: true + note: "The optics and endstation motion controllers driving the monochromator, mirror, spinner, sample-environment, and detector-tower axes; box model / protocol / IP not in the profile collection (DRIVE-1)." + triggering: [] + software_iocs_not_modeled: + [PerkinElmer, Pilatus, Cryostream, Lakeshore, Linkam, Eurotherm, Prosilica] + +resources: + intro: Continuously-available resources. Facility-scope supplies live in deployments/nsls2/site.yaml. + supplies: + - kind: PhotonBeam + - kind: CoolingWater + - kind: Vacuum + - kind: LiquidNitrogen # cryostream / cryostat + - kind: Power + replaceable_parts: + swappable_with_identity: ["area detectors", "capillary samples", "sample-environment cells"] diff --git a/docs/deployments/index.md b/docs/deployments/index.md index b0481d6b99..40ad8bd355 100644 --- a/docs/deployments/index.md +++ b/docs/deployments/index.md @@ -68,6 +68,7 @@ The fourth Site CORA models. Like the Diamond exercise, its beamlines are revers | [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 | | [AMX](amx/index.md) | Reverse-engineered | highly automated macromolecular crystallography (rotation MX on a single-omega goniometer + Eiger, EMBL robot sample exchange), 17-ID-1; FMX's sibling, CORA's 3rd MX; modelled from public beamline config | | [XFP](xfp/index.md) | Reverse-engineered | X-ray footprinting of biological macromolecules in solution (white/pink-beam radiolytic dose delivery, offline mass-spec readout), 17-BM; the fleet's first dose-delivery beamline (no scattering detector); modelled from public beamline config | +| [PDF](pdf/index.md) | Reverse-engineered | high-energy total scattering / pair distribution function and powder diffraction (side-bounce Laue mono, two-detector two-distance merge on PerkinElmer + Pilatus panels), 28-ID-1; XPD's dedicated PDF twin on the shared 28-ID damping wiggler; modelled from public beamline config | ## [SLAC](slac/index.md) diff --git a/docs/deployments/pdf/equipment/controls.md b/docs/deployments/pdf/equipment/controls.md new file mode 100644 index 0000000000..b9f9682850 --- /dev/null +++ b/docs/deployments/pdf/equipment/controls.md @@ -0,0 +1,30 @@ +# Controls + +*The software-triggered acquisition, the two-detector plan, the motion controllers, and the seam between CORA and the floor.* + +## Triggering: software, not a hardware box + +A total-scattering measurement is a gated exposure on a flat-panel detector. PDF, like its twin XPD, runs the detectors in continuous or multi-trigger mode gated by the fast exposure shutter, with no separate hardware timing box in the profile collection. The two-detector, two-distance merge is sequenced by a bluesky plan (the `TwoDetectors` helper, `72-two-detector.py`): it moves one panel out, counts the static panel, moves it back, and counts the moving panel, so the near and far frames are collected in one acquisition. This is a software-sequenced acquisition, not a hardware trigger chain (DIST-1). + +## Motion controllers + +The optics, spinner, sample-environment, and detector-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 PDF floor. The shape matches the other NSLS-II beamlines'. + +CORA **owns** (its conducting engine, over the `ControlPort`): + +- the total-scattering acquisition: setting the incident energy, positioning the sample on the spinner, driving the detector towers to the near and far distances, ramping the sample-environment temperature, and arming the detectors for the two-distance merge; +- the choice of technique, detector, distance, 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 side-bounce mono and mirror drives, the spinner and detector-tower motion, the cryostream / cryostat / furnace controllers, the PSS interlock, and the PerkinElmer / Pilatus 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 PDF, working over the ports: total-scattering orchestration over the `ControlPort`, the PDF reduction (azimuthal integration and the Fourier transform to G(r)) over the `ComputePort`, and data egress over the `TransferPort` into the CORA Dataset. The PDF reduction is a clean `ComputePort` leg, the total-scattering analogue of the reconstruction legs at the imaging beamlines. + +The software IOCs (`PerkinElmer`, `Pilatus`, `Cryostream`, `Lakeshore`, `Linkam`, the Eurotherm) are referenced by PV namespace only, never registered as Assets. diff --git a/docs/deployments/pdf/equipment/detector.md b/docs/deployments/pdf/equipment/detector.md new file mode 100644 index 0000000000..65e82d940b --- /dev/null +++ b/docs/deployments/pdf/equipment/detector.md @@ -0,0 +1,24 @@ +# Detector + +*The flat-panel and pixel area detectors, the two detector towers, the beamstops, and the flux monitor. PVs verified against `startup/80-areadetector2.py`, `81-pilatus.py`, `72-two-detector.py`, `11-motors.py`, `10-machine.py`.* + +PDF's measurement is the total-scattering pattern on a large area detector. To reach the high Q a pair distribution function needs, the detector sits close to the sample; a near panel and a far panel are merged across two distances to cover the full range. This two-distance, two-detector geometry is the shape that distinguishes PDF from its twin XPD. + +| Asset | Family | PV | Role | +| --- | --- | --- | --- | +| `AreaDetector` | Camera | `XF:28ID1-ES{Det:PE1}` | PerkinElmer flat panel, primary PDF detector | +| `PixelDetector` | Camera | `XF:28ID1-ES{Det:Pilatus}` | Pilatus photon-counting pixel detector | +| `DetectorStage1` | LinearStage | `XF:28ID1B-ES{Det:1}` | first detector tower (static distance) | +| `DetectorStage2` | LinearStage | `XF:28ID1B-ES{Det:2}` | second detector tower (moving distance) | +| `BeamStop` | BeamStop | `XF:28ID1B-ES{BS:1}` | direct-beam stop | +| `FluxMonitor` | FluxMonitor | `XF:28ID1B-OP{Det:1-Det:2}` | background photodiode (I0) | + +## Two detectors, two distances + +The `AreaDetector` is a PerkinElmer flat panel (a second panel sits alongside), the primary total-scattering / powder detector; the `PixelDetector` is a Pilatus photon-counting detector with an energy-thresholded readout, used for high-Q or low-background frames. Both reuse `Camera`, the flat-panel precedent XPD already carries. + +The `DetectorStage1` and `DetectorStage2` are the two detector towers (`Det_1` and `Det_2`, each X / Y / Z). The Z axis sets the sample-to-detector distance and hence the accessible Q. PDF carries two towers so a near and a far panel can be merged into one wide-Q dataset: one panel stays static while the other steps in and out of the beam, the explicit two-detector acquisition the `TwoDetectors` plan sequences. Which tower is static versus moving, and how the panels merge, are DIST-1. Each `BeamStop` (`BStop1`, with `BStop2` and a table-mounted stop alongside) blocks the direct beam ahead of its panel. + +## Reuse, not new vocabulary + +This is the reinforcement point of PDF as a CORA exercise: a high-energy total-scattering beamline with flat-panel and pixel detectors, two distance towers, and beamstops that needs **no new Family**. The detectors reuse `Camera`, the `FluxMonitor` photodiode reuses the graduated flux Family (#353), and the beamstops reuse `BeamStop`. The total-scattering detector chain is the same shape its twin [XPD](../../xpd/equipment/detector.md) carries; PDF adds the second physical detector tower for the simultaneous near / far merge, but the families are unchanged. diff --git a/docs/deployments/pdf/equipment/index.md b/docs/deployments/pdf/equipment/index.md new file mode 100644 index 0000000000..8ea5e0324e --- /dev/null +++ b/docs/deployments/pdf/equipment/index.md @@ -0,0 +1,19 @@ +# The beamline + +*The PDF beam path, area by area. CORA models the beamline as one root Asset (`PDF`) with the devices nested below it; this page is the human walk, the [Inventory](../inventory.md) is the flat reference.* + +PDF runs from the shared 28-ID damping wiggler through a first-optics hutch into an endstation where a high-energy beam meets a powder or capillary sample and the total-scattering pattern is recorded on flat-panel and pixel detectors at two distances. Two enclosures carry it: + +``` + 28-ID-1-A (optics hutch / FOE) 28-ID-1-B (endstation) + ---------------------------------- -------------------------------------- + wiggler -> SBM mono -> VFM mirror cleanup slit -> spinner -> sample env + white-beam slit near / far detector towers (PE, Pilatus) +``` + +- [Source](../beamline.md) (`28-ID-1-A`): the shared 28-ID damping wiggler and the storage-ring readback, then the optics, the side-bounce monochromator, the vertical focusing mirror, the white-beam slit, and the master energy. This page is generated from the descriptor. +- [Sample](sample.md) (`28-ID-1-B`): the endstation cleanup slit, the fast shutter, the capillary spinner, the sample-environment stage, and the thermal-environment cluster (cryostream, cryostat, furnace). +- [Detector](detector.md) (`28-ID-1-B`): the PerkinElmer flat-panel and Pilatus pixel area detectors, the two detector towers that set the near and far distances, the beamstops, and the flux monitor. +- [Controls](controls.md): the software-triggered acquisition (no hardware timing box, as at XPD), the two-detector plan, and the motion controllers. + +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). PDF is the twin of [XPD](../../xpd/equipment/index.md) on the shared 28-ID damping wiggler and reuses its modelling; the one loose family is the `StorageRing` machine-state supply. diff --git a/docs/deployments/pdf/equipment/sample.md b/docs/deployments/pdf/equipment/sample.md new file mode 100644 index 0000000000..af6bc8f320 --- /dev/null +++ b/docs/deployments/pdf/equipment/sample.md @@ -0,0 +1,25 @@ +# Sample + +*The endstation sample side: the cleanup slit, the fast shutter, the capillary spinner, the sample-environment stage, and the thermal-environment cluster. PVs verified against `startup/12-optics.py`, `11-motors.py`, the temperature-controller startup files, and `pdftools/sample_environment.py`.* + +PDF positions a powder or capillary sample in the high-energy beam and records the total-scattering pattern on the area detectors. The sample side conditions the beam at the endstation, spins the capillary to average the powder texture, and carries the rich thermal environment that variable-temperature total scattering needs. + +| Asset | Family | PV | What it does | +| --- | --- | --- | --- | +| `CleanupSlit` | Slit | `XF:28ID1B-OP{Slt:AS}` | trims parasitic scatter ahead of the sample | +| `FastShutter` | Shutter | `XF:28ID1B-OP{PSh:1}` | gates the detector exposure | +| `SpinnerGoniohead` | Goniometer | `XF:28ID1B-ES{Stg:Smpl}` | spins and positions the capillary sample | +| `SampleEnvironmentStage` | LinearStage | `XF:28ID1B-ES{Env:1}` | presents the sample-environment cell to the beam | +| `SampleTemperature` | TemperatureController | `XF:28ID1-ES:1{Env:01}` | cryostream / cryostat / furnace cluster | + +## Conditioning and spinning + +The `CleanupSlit` (the endstation `cleanup_slits`) trims the parasitic scatter the upstream optics throw before the beam reaches the sample; an optics-cabin slit (`OCM_slits`) sits further upstream. The `FastShutter` (the `PDFFastShutter`) gates the detector exposure, with a slower photon shutter alongside. Both reuse existing families (`Slit`, `Shutter`). + +The `SpinnerGoniohead` is the capillary-spinner goniohead: sample X / Y / Z plus a spin axis that rotates the capillary so the area detector sees a smooth powder ring rather than individual crystallite spots. An analyzer goniohead sits alongside. It reuses the `Goniometer` family; the full axis set, and whether the orientation warrants a `Goniometer` plus an Assembly (the i11 precedent), are STAGE-1. + +## The sample environment + +The `SampleEnvironmentStage` (the `Grid` X / Y / Z stage) presents the sample-environment cell to the beam. The `SampleTemperature` is the thermal-environment cluster: a cs800 cryostream controller (understood to be an Oxford Cryostream, an inference, TEMP-1), a Lakeshore 336 cryostat, and a Linkam T96 furnace. CORA models one thermal-environment Asset, reusing the `TemperatureController` family (graduated in #350, the same Family Diamond i11 graduated for variable-temperature powder diffraction); which units are live is TEMP-1. + +A gas-handling and humidity rig (flow valves, a residual-gas analyzer, a humidity readout) is present in the profile collection. It is the settable in-situ environment, but CORA carries it deferred (ENV-1): a design-phase scaffold models the thermal environment that is settled and defers the gas / humidity actuators until they earn modelling, where they would likely bind the loose `FlowController` family other deployments use. diff --git a/docs/deployments/pdf/governance.md b/docs/deployments/pdf/governance.md new file mode 100644 index 0000000000..4915f64774 --- /dev/null +++ b/docs/deployments/pdf/governance.md @@ -0,0 +1,17 @@ +# Governance + +*Who may act at PDF 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 PDF 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 change the incident energy, move a detector tower to a new distance, set a sample-environment temperature ramp, 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. + +## In-situ and high-throughput runs + +A variable-temperature total-scattering series or a high-throughput sample queue can run long and unattended, which is where CORA's trust shape earns its keep: the engine holds the temperature ramp and the acquisition while the trust boundary bounds what may change mid-series and who may intervene. If an autonomous Agent were added to steer acquisition (choose the next temperature point, decide when the pattern statistics are sufficient, trigger a PDF reduction to check the result), 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/pdf/index.md b/docs/deployments/pdf/index.md new file mode 100644 index 0000000000..6445dbfa80 --- /dev/null +++ b/docs/deployments/pdf/index.md @@ -0,0 +1,50 @@ +# PDF + +*Pair distribution function and total scattering at NSLS-II, beamline 28-ID-1: a high-energy beam through a powder or capillary sample onto flat-panel and pixel area detectors, with a near and a far detector distance merged to reach the high Q a PDF needs. This page describes how CORA would model and run PDF; the model is reverse-engineered from public configuration, not yet confirmed by PDF staff.* + +| Property | Value | +| --- | --- | +| Asset | `PDF` (root Asset, `tier = Unit`, `parent_id = None`) | +| Facility | [NSLS-II](../nsls2/index.md) (bound via `facility_code = "nsls2"`, `FacilityKind = Site`) | +| Sector | `Sector 28` (PV namespace `XF:28ID1*`) | +| Institution | Brookhaven National Laboratory (context; not modeled as an Asset or Facility) | +| Status | Reverse-engineered from public config (design-phase scaffold) | +| Source | Shared 28-ID damping wiggler (inferred; no source PV in config) | + +!!! note "How CORA would land on PDF" + PDF (28-ID-1) and [XPD](../xpd/index.md) (28-ID-2) are the two endstations on the shared 28-ID damping wiggler: the same science family (high-energy powder diffraction and total scattering / PDF), different branch and PV namespace. These pages describe how CORA would model, govern, and conduct PDF, the dedicated total-scattering endstation, reusing XPD's modelling wholesale. 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/pdf-profile-collection`](https://github.com/NSLS2/pdf-profile-collection) profile collection and the [`NSLS2/pdftools`](https://github.com/NSLS2/pdftools) 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 PDF staff verify them ([Open questions](questions.md)). This is a design-phase scaffold: the descriptor and these docs, with scenarios deferred. + +## The defining shape: total scattering at a second endstation + +PDF is the **twin of XPD** on the shared 28-ID damping wiggler, and through XPD the NSLS-II counterpart of Diamond [i11](../i11/index.md) (powder diffraction) and [i15-1](../i15-1/index.md) (total scattering / PDF). Its value to CORA is reinforcement: the high-energy powder / PDF shape, a high-flux beam onto a large flat-panel detector with the detector distance setting the accessible Q, ports to a second NSLS-II endstation with no new vocabulary. PDF introduces **no new catalog Family**, and its techniques sit on the same deferred Methods XPD and the Diamond beamlines leave pending. + +Two things distinguish PDF from XPD, and CORA carries both by what is real rather than coining anything new: + +- A **side-bounce monochromator** (a single-bounce Laue crystal) in place of XPD's bent double-Laue. Both are high-energy Laue monochromators, so this is a `Monochromator` settings difference, not a new Family. +- An explicit **two-detector, two-distance** acquisition: a near panel and a far panel, one static and one stepping in and out of the beam, merged to cover the wide Q-range a pair distribution function needs. XPD reaches the two distances by moving one detector; PDF carries two (DIST-1). + +## The beamline + +Along the beam, in order: + +- [Source](beamline.md): the shared 28-ID damping wiggler and the optics hutch (`28-ID-1-A`), rendered as the generated source-stage device walk: the side-bounce monochromator, the vertical focusing mirror, the white-beam slit, and the master energy. +- [Sample](equipment/sample.md): the endstation cleanup slit, the fast shutter, the capillary spinner, the sample-environment stage, and the thermal-environment cluster (cryostream, cryostat, furnace). +- [Detector](equipment/detector.md): the PerkinElmer flat-panel and Pilatus pixel area detectors, the two detector towers that set the near and far distances, the beamstops, and the flux monitor. + +Cutting across all three: + +- [Controls](equipment/controls.md): the software-triggered acquisition (no hardware timing box, as at XPD), the two-detector plan that sequences the two distances, and the motion controllers. + +The cross-cutting reference view is the [Inventory](inventory.md). + +## Techniques + +[Techniques](techniques.md): the total-scattering and powder-diffraction techniques PDF runs, each a [Catalog](../../catalog/methods.md) Method, and why their Methods stay deferred (the i11 / i15-1 / XPD owner-scope cohort). + +## Governance + +[Governance](governance.md): who may act at PDF 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 PDF content lives. diff --git a/docs/deployments/pdf/inventory.md b/docs/deployments/pdf/inventory.md new file mode 100644 index 0000000000..6a86f57072 --- /dev/null +++ b/docs/deployments/pdf/inventory.md @@ -0,0 +1,54 @@ +# Inventory + +*The CORA Asset model for PDF: 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/pdf/beamline.yaml) descriptor the Source page renders from. + +Devices bind to catalog [Families](../../catalog/families.md) and carry real EPICS PVs (verified against `NSLS2/pdf-profile-collection` and `NSLS2/pdftools`). No vendor Model is bound: part numbers are not in the profile collection. PDF introduces **no new catalog family**: every device reuses an existing Family. Most are the same Families its twin [XPD](../xpd/inventory.md) carries (`Camera` for the flat-panel and pixel detectors, `FluxMonitor` for the photodiode, `TemperatureController` for the thermal cluster, `Monochromator` for the high-energy Laue mono, `Mirror` for the focusing mirror); the capillary `Goniometer` spinner and the `BeamStop` reuse existing Families that XPD does not happen to bind. One loose family is bound: the `StorageRing` supply observation (machine state, never an Asset Family). + +## The Asset tree + +Root Asset `PDF` (`tier = Unit`, `facility_code = nsls2`); sub-systems nest below by `parent_id`. + +| Asset | Family | PV (verified) | What it is | +| --- | --- | --- | --- | +| `PDF` | (root) | `XF:28ID1*` | bound to the NSLS-II Site | +| `Source` | InsertionDevice | (no PV in config) | shared 28-ID damping wiggler | +| `StorageRing` | StorageRing (loose) | `SR:OPS-BI{DCCT:1}` | storage-ring current readback (machine state) | +| `Monochromator` | Monochromator | `XF:28ID1A-OP{Mono:SBM}` | side-bounce (single-Laue) monochromator | +| `VerticalFocusingMirror` | Mirror | `XF:28ID1A-OP{Mir:VFM}` | vertical focusing mirror (benders) | +| `WhiteBeamSlit` | Slit | `XF:28ID1A-OP{Slt:0}` | white-beam-defining slit | +| `EnergyAxis` | PseudoAxis | (computed) | master energy (side-bounce mono) | +| `CleanupSlit` | Slit | `XF:28ID1B-OP{Slt:AS}` | endstation cleanup / guard slit | +| `FastShutter` | Shutter | `XF:28ID1B-OP{PSh:1}` | fast exposure shutter | +| `SpinnerGoniohead` | Goniometer | `XF:28ID1B-ES{Stg:Smpl}` | capillary-spinner sample goniohead | +| `SampleEnvironmentStage` | LinearStage | `XF:28ID1B-ES{Env:1}` | sample-environment positioning stage | +| `SampleTemperature` | TemperatureController | `XF:28ID1-ES:1{Env:01}` | cryostream / cryostat / furnace cluster | +| `AreaDetector` | Camera | `XF:28ID1-ES{Det:PE1}` | PerkinElmer flat panel (primary PDF detector) | +| `PixelDetector` | Camera | `XF:28ID1-ES{Det:Pilatus}` | Pilatus photon-counting pixel detector | +| `DetectorStage1` | LinearStage | `XF:28ID1B-ES{Det:1}` | first detector tower (static distance) | +| `DetectorStage2` | LinearStage | `XF:28ID1B-ES{Det:2}` | second detector tower (moving distance) | +| `BeamStop` | BeamStop | `XF:28ID1B-ES{BS:1}` | direct-beam stop | +| `FluxMonitor` | FluxMonitor | `XF:28ID1B-OP{Det:1-Det:2}` | background photodiode (I0) | +| `EndstationMotionController` | MotionController | (pending) | optics / endstation / detector-tower motion | + +Every family is in the catalog except the loose `StorageRing` supply; PDF coins none. Notably the area detectors reuse `Camera` (the flat-panel precedent XPD already carries), the thermal cluster reuses `TemperatureController` (graduated in #350, the same Family Diamond i11 graduated for variable-temperature powder work), the photodiode reuses `FluxMonitor` (graduated in #353), and the spinner reuses `Goniometer`, so PDF is a clean reuse-and-reinforce deployment, the twin of XPD. + +## Pending confirmations + +Every value below is read from the profile collection or inferred, awaiting the PDF team. Each is tracked by an [open question](questions.md). + +| Value to confirm | Applies to | Status | Tracking | +| --- | --- | --- | --- | +| Damping-wiggler identity and parameters | `Source` | `unknown-pending-confirmation` | (SRC-1) | +| PSS permit-leaf PVs | both enclosures | `unknown-pending-confirmation` | (PSS-1) | +| Side-bounce mono crystal cut and energy range | `Monochromator` | `unknown-pending-confirmation` | (MONO-1) | +| Whether incident energy is ever scanned as the measurement | `EnergyAxis` | `unknown-pending-confirmation` | (ENERGY-1) | +| Full spinner / analyzer axis set; Goniometer vs Assembly modelling | `SpinnerGoniohead` | `unknown-pending-confirmation` | (STAGE-1) | +| Which thermal units are live (cryostream make, cryostat, furnace) | `SampleTemperature` | `unknown-pending-confirmation` | (TEMP-1) | +| The gas-handling and humidity rig (present in source, not modelled) | `SampleEnvironmentStage` | `unknown-pending-confirmation` | (ENV-1) | +| Which panels are live vs the spare set | `AreaDetector` / `PixelDetector` | `unknown-pending-confirmation` | (DET-1) | +| The two-detector / two-distance geometry and near / far merge | `DetectorStage1` / `DetectorStage2` | `unknown-pending-confirmation` | (DIST-1) | +| Photodiode / flux channel map | `FluxMonitor` | `unknown-pending-confirmation` | (DIAG-1) | +| Motion-controller box models / firmware / IP | `EndstationMotionController` | `unknown-pending-confirmation` | (DRIVE-1) | +| Whether the powder / total-scattering Methods enter the catalog | techniques | `unknown-pending-confirmation` | (TECH-1) | diff --git a/docs/deployments/pdf/model.md b/docs/deployments/pdf/model.md new file mode 100644 index 0000000000..685a52b913 --- /dev/null +++ b/docs/deployments/pdf/model.md @@ -0,0 +1,25 @@ +# Model + +*The developer's by-kind index: where each CORA aggregate's PDF 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 PDF | +| --- | --- | +| 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) (28-ID-1-A optics, 28-ID-1-B 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 its twin [XPD](../xpd/model.md) and the other reverse-engineered deployments. Left out on purpose: + +- **No new Family.** PDF is a reuse-and-reinforce deployment: the flat-panel and pixel detectors bind `Camera`, the photodiode `FluxMonitor`, the thermal cluster `TemperatureController`, the side-bounce mono `Monochromator`, the focusing mirror `Mirror`, the spinner `Goniometer`, the slits `Slit`, the fast shutter `Shutter`, the beamstops `BeamStop`, the detector and sample-environment stages `LinearStage`, the master energy a `PseudoAxis`. Nothing graduates and the catalog is unchanged. +- **The held loose family.** The `StorageRing` current readback is a loose supply observation (machine state), never an Asset Family. +- **No new Capability or Method.** Total scattering / PDF and powder diffraction sit on the deferred `total_scattering` / `powder_diffraction` Methods Diamond i11 and i15-1 left pending (`TECH-1`); PDF reinforces them at a second NSLS-II endstation without coining either, and records no Practice until they land. The PDF reduction (azimuthal integration and the Fourier transform to G(r)) is `ComputePort` work, not a Method. +- **The gas-handling and humidity rig.** Present in the profile collection but carried deferred (`ENV-1`): a design-phase scaffold models the thermal environment that is settled (`TemperatureController`) and defers the in-situ gas / humidity actuators until they earn modelling, the same discipline the other deployments follow. +- **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/pdf/questions.md b/docs/deployments/pdf/questions.md new file mode 100644 index 0000000000..fb48b2d317 --- /dev/null +++ b/docs/deployments/pdf/questions.md @@ -0,0 +1,44 @@ +# Open questions + +*What CORA needs the PDF team to confirm. This model is reverse-engineered from public open source (the [`NSLS2/pdf-profile-collection`](https://github.com/NSLS2/pdf-profile-collection) profile collection and the [`NSLS2/pdftools`](https://github.com/NSLS2/pdftools) device library): the EPICS PVs are read from them, but vendor identities, physical positions, and the detector geometry 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 | The 28-ID source identity and parameters. No source PV is in the profile collection; CORA infers the shared 28-ID damping wiggler from facility knowledge. | An insertion device, the shared damping wiggler, identity-only. | The InsertionDevice settings. | +| PSS-1 | Blocks-go-live | The PSS search-and-secure permit-leaf PVs. Only the fast and photon shutters are in source. | The permit signal is a confirm note, not a guessed PV. | The Enclosure permit signals. | +| MACHINE-1 | Nice-to-have | The storage-ring state PDF 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 + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| MONO-1 | Nice-to-have | The side-bounce monochromator crystal cut, reflection, and energy range. The device (`Mono:SBM`) is confirmed. | A single high-energy Laue `Monochromator` Asset; cut and range blank. | The Monochromator settings. | +| ENERGY-1 | Nice-to-have | Is PDF always fixed-energy per experiment, or does any routine scan energy as the measurement? | Fixed-energy; energy scan deferred. | The energy Capability decision. | + +## Sample and environment + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| STAGE-1 | Blocks-go-live | The full spinner and analyzer goniohead axis set, and whether the sample orientation warrants a `Goniometer` plus an Assembly (the i11 precedent). | A `Goniometer` spinner; the analyzer noted, the Assembly deferred. | The sample-stage modelling. | +| TEMP-1 | Nice-to-have | Which thermal units are live (the cs800 cryostream make, the Lakeshore cryostat, the Linkam furnace) and their ranges. | One thermal-environment `TemperatureController` Asset; units blank. | The sample-environment roster. | +| ENV-1 | Nice-to-have | The gas-handling and humidity rig (flow valves, residual-gas analyzer, humidity) is present in source but not modelled. Does it warrant a settable actuator Asset (the loose `FlowController` family)? | Deferred; the thermal cluster is modelled, the gas / humidity rig noted. | The in-situ environment modelling. | + +## Detectors + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| DET-1 | Blocks-go-live | Which detectors are live (the two PerkinElmer panels, the Pilatus) and which serves which role. | Both Cameras; PerkinElmer primary; Pilatus alongside. | The detector roster. | +| DIST-1 | Blocks-go-live | The two-detector / two-distance geometry: the near and far distances, which tower is static vs moving, and how the panels merge for the PDF Q-range (the `TwoDetectors` plan). | Two `LinearStage` towers; the merge deferred. | The detector geometry and Q-range. | +| DIAG-1 | Nice-to-have | The background-photodiode / flux channel detail. | A read-only `FluxMonitor` probe; channel map blank. | The FluxMonitor binding. | + +## Controls and technique scope + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| 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 total-scattering and powder-diffraction Methods enter CORA's catalog, or stay deferred? This is the same owner-scope decision Diamond i11 / i15-1 and XPD opened. | Methods deferred (rendered unlinked), no Practice recorded. | The powder / PDF Method scope. | diff --git a/docs/deployments/pdf/techniques.md b/docs/deployments/pdf/techniques.md new file mode 100644 index 0000000000..935db89005 --- /dev/null +++ b/docs/deployments/pdf/techniques.md @@ -0,0 +1,19 @@ +# Techniques + +*What CORA would run at PDF: high-energy total-scattering and powder-diffraction techniques, each a [Catalog](../../catalog/methods.md) Method. PDF is the twin of [XPD](../xpd/techniques.md) and follows its deferral exactly, after Diamond [i11](../i11/techniques.md) and [i15-1](../i15-1/techniques.md).* + +PDF's techniques are high-energy total scattering and powder diffraction: a high-energy beam through a powder or capillary sample onto a large area detector, with the sample-to-detector distance setting the accessible Q. These Methods are new to CORA's imaging- and spectroscopy-heritage catalog. As at XPD, 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 | +| --- | --- | --- | +| Total scattering / PDF | `total_scattering` | rapid-acquisition pair distribution function: a near and a far detector distance merged to high Q (DIST-1); Method not yet in catalog, shared with i15-1 and XPD | +| Powder diffraction | `powder_diffraction` | the same high-energy beam and detector for Rietveld-quality powder patterns; Method not yet in catalog, shared with i11 and XPD | +| Alignment | [`alignment`](../../catalog/methods.md) | beam, monochromator, mirror, and slit tuning; reuses the existing Method | + +Both techniques need the [sample spinner and environment](equipment/sample.md) and the [area detectors](equipment/detector.md); the exposure is gated by the fast shutter, with the two-distance merge sequenced in software (DIST-1). + +## Why the Methods stay deferred + +Diamond i11 (powder diffraction) and i15-1 (total scattering / PDF) opened the question of whether these Methods enter CORA's catalog (TECH-1), and `main` deliberately left them pending: the concrete acquisition recipes (energies, distances, exposures, the near / far merge) join as the deployment approaches the point where CORA drives the beamline. PDF reinforces both Methods at a second NSLS-II endstation without coining either, the same earn-the-abstraction discipline XPD follows. Because the defining Methods are not in the catalog, PDF records **no Practice** in the [NSLS-II Site](../nsls2/index.md), exactly as XPD records none; the binding lands when the Method does. + +The PDF reduction itself (the azimuthal integration of the detector frames and the Fourier transform of the structure function into the pair distribution function G(r)) is `ComputePort` work, not a beamline Method: the beamline takes the frames, CORA's compute leg turns them into the result. diff --git a/mkdocs.yml b/mkdocs.yml index 7d33e95345..112f640659 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -641,6 +641,19 @@ nav: - Techniques: deployments/xfp/techniques.md - Governance: deployments/xfp/governance.md - Model: deployments/xfp/model.md + - PDF: + - deployments/pdf/index.md + - Open questions: deployments/pdf/questions.md + - The beamline: + - deployments/pdf/equipment/index.md + - Source: deployments/pdf/beamline.md + - Sample: deployments/pdf/equipment/sample.md + - Detector: deployments/pdf/equipment/detector.md + - Controls: deployments/pdf/equipment/controls.md + - Inventory: deployments/pdf/inventory.md + - Techniques: deployments/pdf/techniques.md + - Governance: deployments/pdf/governance.md + - Model: deployments/pdf/model.md - SLAC: - deployments/slac/index.md - LCLS-MFX: