diff --git a/apps/api/tests/unit/deployments/test_beamline_descriptor.py b/apps/api/tests/unit/deployments/test_beamline_descriptor.py index 8552dc189c..c430204c40 100644 --- a/apps/api/tests/unit/deployments/test_beamline_descriptor.py +++ b/apps/api/tests/unit/deployments/test_beamline_descriptor.py @@ -400,7 +400,7 @@ def test_no_unexpected_orphan_catalog_models() -> None: _PROMOTION_REVIEWED = { "Diagnostic": "hold: Sensor fold-vs-promote still open (DIAG-1)", "Screen": "hold: phosphor beam-viewing screen (2-BM, BMM); fold-vs-promote open (FLAG-1)", - "FlowController": "hold: flow/pump actuator n=3 (i22/7-bm/lix); graduation candidate (FLOW-1)", + "FlowController": "hold: flow/pump actuator n=4 (i22/7-bm/lix/xfp); overdue (FLOW-1)", "BeamPositionMonitor": "hold: Sensor fold-vs-promote across 4-id/8-id/9-id/iss/fmx (DIAG-1)", "Laser": "hold: pump-probe laser model-vs-hazard open (4-id + lcls-mfx; SAMPLE-1)", "Backlight": "hold: sample-illumination fold-vs-promote open (i03 + i24 + fmx + i19; DET-1)", diff --git a/apps/api/tests/unit/deployments/test_site_descriptor.py b/apps/api/tests/unit/deployments/test_site_descriptor.py index 2c70c9cbad..6ad41c7542 100644 --- a/apps/api/tests/unit/deployments/test_site_descriptor.py +++ b/apps/api/tests/unit/deployments/test_site_descriptor.py @@ -271,6 +271,7 @@ def test_practice_method_links_only_known() -> None: "mx_data_collection": "i03 + FMX + AMX MX rotation collection; 3 consumers (TECH-1)", "sample_exchange": "i03 + FMX + AMX robotic sample exchange; 3 consumers (ROBOT-1)", "solution_scattering": "lix bio-SAXS / SEC-SAXS; new Method not yet earned (TECH-1)", + "x_ray_footprinting": "xfp dose-delivery footprinting; offline MS readout; new Method (TECH-1)", "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)", diff --git a/deployments/nsls2/site.yaml b/deployments/nsls2/site.yaml index ed318edbbd..641952d8e8 100644 --- a/deployments/nsls2/site.yaml +++ b/deployments/nsls2/site.yaml @@ -2,7 +2,7 @@ # # NSLS-II (National Synchrotron Light Source II, Brookhaven National Laboratory) # is a Site CORA models, the home of the reverse-engineered NSLS-II beamline -# scaffolds listed in the facility.beamlines field below (FXI ... HEX). This file is +# scaffolds listed in the facility.beamlines field below (FXI ... XFP). This file is # the single human-readable source for the facility's site-level instances: the # Facility itself, the Practices it would run, and the facility principals. # @@ -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] + beamlines: [FXI, HXN, BMM, SRX, SIX, CHX, CSX, IOS, XPD, ESM, SMI, IXS, SST, ISS, FMX, CMS, XFM, LIX, HEX, AMX, XFP] # 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 @@ -143,6 +143,13 @@ practices: - {name: AMX_mx_data_collection_practice, method: mx_data_collection, pending: true, note: "rotation / oscillation MX data collection on the single-omega goniometer + Eiger via the mxtools vector / Zebra flyer; reuses the i03 / FMX mx_data_collection Method, the third consumer (TECH-1)"} - {name: AMX_grid_scan_practice, method: grid_scan, pending: true, note: "fast grid scan for sample location / centring via the Zebra-triggered goniometer raster; reuses the i03 / FMX grid_scan Method, the third consumer (TECH-1)"} - {name: AMX_sample_exchange_practice, method: sample_exchange, pending: true, note: "autonomous EMBL-robot load / centre / collect / unmount loop coordinated by the LSDC Governor; reuses the i03 / FMX sample_exchange Method, the third consumer; a Procedure over the spine + a Subject custody thread (ROBOT-1)"} + # XFP (17-BM) X-ray footprinting Practices (first cut). XFP is a DOSE-DELIVERY + # beamline, not a scattering / diffraction one: a white / pink beam irradiates a + # biological macromolecule in solution to footprint it via hydroxyl radicals, and the + # structural readout is OFFLINE mass spectrometry. The Method (radiolytic / X-ray + # 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)"} # 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/xfp/beamline.yaml b/deployments/xfp/beamline.yaml new file mode 100644 index 0000000000..3df1932944 --- /dev/null +++ b/deployments/xfp/beamline.yaml @@ -0,0 +1,288 @@ +# XFP beamline descriptor (NSLS-II), reverse-engineered +# +# XFP (X-ray Footprinting of Biological Materials) is the NSLS-II 17-BM beamline, +# a Case Western Reserve University partner beamline. It does synchrotron X-ray +# footprinting: an intense white / pink beam irradiates a biological macromolecule +# (protein or nucleic acid) in solution, generating hydroxyl radicals that +# covalently modify the molecule at solvent-accessible sites. The structural +# readout (which sites were modified) is done OFFLINE by mass spectrometry, not on +# the beamline. It is bound to the NSLS-II Site (deployments/nsls2/site.yaml). +# +# STATUS: reverse-engineered, design-phase. Every value is read from public open +# source (the beamline's own bluesky profile collection, github.com/NSLS2/ +# xfp-profile-collection, its startup/*.py device definitions) or inferred, carried +# new: true + confirm: true pending XFP staff. EPICS PVs are real and verified +# against the profile collection; vendor part numbers, serials, dose calibrations, +# and physical positions are not in it and are open questions. The syringe pumps +# and the fraction collector are PV-bound fluidic actuators; the high-throughput +# 96-well plate is addressed in pure Python (no robot, no PV) and the science +# readout (mass spec) is entirely offline. This scaffold is descriptor + docs, +# scenarios deferred. +# +# WHAT IS GENUINELY NEW: XFP is the fleet's first DOSE-DELIVERY beamline. It is not +# a scattering, diffraction, or imaging beamline and has NO scattering / area / +# imaging detector at all. The experiment variable is the delivered radiolytic DOSE +# (exposure time x incident flux x attenuation); the run produces (a) a footprinted +# SAMPLE, an irradiated aliquot captured into a tube, and (b) a DOSE RECORD +# (exposure time, filter thickness, flux time-series, well / tube identity). The +# structural analysis is the OFFLINE-readout seam: the mass spectrometry happens +# downstream, off the instrument. So the novelty lands on the Method (radiolytic +# footprinting), the Subject (a biomolecule in solution being irradiated), and the +# offline-readout seam, NOT on device vocabulary. +# +# MODELLING: XFP coins NO new Family and changes nothing in the catalog. 17-BM is a +# bending-magnet source (the 2-BM / 7-BM / CMS pattern), observed through the loose +# StorageRing; the footprinting beam is WHITE / pink (there is NO monochromator in +# the footprinting path, the only mono is a separate XAS endstation excluded here, +# WHITE-1). The bendable front-end mirror binds Mirror; the white-beam and defining +# slits bind Slit; the eight-position Al filter wheel binds Filter (it sets the dose +# rate); the personnel and timed dose shutters bind Shutter; the delay generator +# that fires the millisecond Uniblitz fast shutter binds TimingController (it sets +# the dose opening-time); the QuadEM electrometers bind FluxMonitor (incident flux +# to compute dose); the Sydor beam-position monitor binds the loose +# BeamPositionMonitor (held under review, DIAG-1); the capillary-flow, high- +# throughput, and HTFly sample stages bind LinearStage; the syringe / sample +# delivery pumps bind the existing loose FlowController Family. +# +# THE REUSE WORTH NAMING: the sample-delivery pumps bind the loose FlowController +# Family ("settable flow / pump actuator", FLOW-1), already bound by i22, 7-BM, and +# LIX. XFP is its FOURTH consumer, reinforcing the rule-of-three that LIX fired; the +# FlowController graduation stays a separate gated decision, not folded here +# (FLOW-1, FLUID-1). The fraction collector (a PV-bound aliquot-routing actuator), +# the 96-well plate addressing (pure Python, no PV), and the offline mass-spec +# readout are the sample-custody and offline-readout seam, not devices (FC-1, HT-1, +# READOUT-1). +# +# Items left open are tagged inline with a (QUESTION-ID) answered on +# docs/deployments/xfp/questions.md. + +beamline: + name: XFP + facility: nsls2 # NSLS-II Site (facility_code: nsls2) + sector: "17-BM" # PV zones XF:17BM (beamline) / XF:17BMA (A-branch) / FE:C17B (front-end) + tier: Unit + parent: null + source: bending-magnet + source_confirm: "17-BM is a bending-magnet source (the name and the white-beam footprinting design imply it), but the profile collection exposes no source / dipole device, only the ring-current PV SR:OPS-BI{DCCT:1}I:Real-I. Source identity is SRC-1" + +# PV zones: FE:C17B (the front-end: the white-beam slits), XF:17BM-OP / XF:17BMA-OP +# (the optics: the bendable mirror, the beamline slits), XF:17BMA-EPS / -PPS / -CT +# (the shutters), XF:17BM-BI (the flux and beam-position monitors), XF:17BMA-ES:1 / +# ES:2 (the footprinting endstations: filters, sample stages, pumps), XF:17BMA-ES:3 +# (a separate monochromatic XAS endstation, OUT OF SCOPE here, WHITE-1). Whether the +# optics and endstation are separate hutches and the PSS permit leaves are open +# (ENC-1, PSS-1). +enclosures: + - name: xfp-optics + role: optics-hutch + facility_code: nsls2 + permit_signal: {confirm: "PSS permit leaf not fully in the profile collection; only the front-end photon-shutter enable status (XF:17BM-PPS{Sh:FE} enabled_status) is read; the optics zone (FE:C17B, XF:17BM-OP / XF:17BMA-OP), the hutch grouping is ENC-1 (PSS-1)"} + - name: xfp-endstation + role: experiment-hutch + facility_code: nsls2 + permit_signal: {confirm: "PSS permit leaf unknown; the footprinting endstations (XF:17BMA-ES:1, ES:2); the monochromatic XAS endstation ES:3 is out of scope (ENC-1, PSS-1, WHITE-1)"} + +# =========================================================================== +# SOURCE STAGE: the machine state, the white-beam optics, and the dose-delivery +# gating (shutters + the dose timer) +# =========================================================================== + +machine: + stage: source + enclosure: xfp-optics + intro: "The machine-level source state, observed not driven." + note: "Observe-only NSLS-II machine state, the loose StorageRing pattern reused from the NSLS-II siblings. 17-BM is a bending-magnet source, not an insertion device, so no InsertionDevice Asset (SRC-1, MACHINE-1)." + devices: + - name: StorageRing + family: StorageRing # loose Family (machine-level observe-only source state; MACHINE-1) + pv: "SR:OPS-BI{DCCT:1}I:Real-I" + new: true + confirm: true + note: "NSLS-II storage-ring current, read as a beam-present suspender input; observe-only; the rest of the ring state is MACHINE-1; the 17-BM bending-magnet source detail is SRC-1" + +optics: + stage: source + enclosure: xfp-optics + intro: "The white / pink beam optics: the bendable front-end mirror, the white-beam and beam-defining slits, and the dose-rate filter wheel. There is no monochromator in the footprinting path." + note: > + The footprinting beam is white / pink: the bendable mirror sets the cutoff and + binds Mirror; the slits bind Slit; the eight-position Al filter wheel binds Filter + (it sets the dose rate, with the pinhole apertures as a further attenuator, ATTN-1). + The only monochromator in the source is a separate XAS endstation (ES:3), out of + scope for footprinting (WHITE-1). Everything here reuses the catalog and coins nothing. + devices: + - name: FrontEndMirror + family: Mirror + pv: "XF:17BM-OP{Mir:1-Ax:P}Mtr" + new: true + confirm: true + note: "the bendable front-end mirror (horizontal / lift / pitch / yaw / roll plus a Bend focus axis and thermocouples) that takes the heat load and sets the high-energy cutoff of the white beam; coating and bend are OPT-1" + - name: WhiteBeamSlit + family: Slit + pv: "FE:C17B-OP{Slt:1-Ax:T}Mtr" + new: true + confirm: true + note: "the front-end white-beam slit (T / B / I / O blades with virtual size / center); defines the white-beam footprint (OPT-2)" + - name: DefiningSlit + family: Slit + pv: "XF:17BMA-OP{Slt:ADC-Ax:XGap}Mtr" + new: true + confirm: true + note: "the ADC beam-defining slit; its horizontal gap (adcslits.xgap) sets the exposure window for the shutterless high-throughput fly mode (the PB / PDS white-beam slit shares the same anatomy); OPT-2, HT-1" + - name: FilterWheel + family: Filter + pv: "XF:17BMA-ES:1{Fltr:1-Ax:Rot}Mtr" + new: true + confirm: true + note: "the eight-position rotary aluminium filter wheel (0 / 25 / 76 / 152 / 203 / 305 / 508 / 762 um Al) that attenuates the white beam to set the dose RATE; a beam-defining pinhole stage and a 0-9 mm Al z-attenuator are further, intermittently-connected attenuators (ATTN-1)" + +dose: + stage: source + enclosure: xfp-optics + intro: "The dose-delivery gating: the personnel and timed exposure shutters, and the delay generator that fires the millisecond fast shutter. Exposure time times flux times attenuation is the delivered dose." + note: > + Footprinting dose is delivered by gating the white beam onto the sample. The + personnel-protection and timed exposure shutters bind Shutter; the delay generator + that fires the millisecond Uniblitz fast shutter binds TimingController (its opening-time + setpoint is the dose time). Seconds-scale exposures are software-timed on the + pre-shutter; millisecond exposures use the delay-generator-fired Uniblitz, or in + the high-throughput fly mode the stage velocity through the defining slit sets the + exposure (DOSE-1, HT-1). + devices: + - name: PhotonShutter + family: Shutter + pv: "XF:17BM-PPS{Sh:FE}" + new: true + confirm: true + note: "the personnel-protection front-end photon shutter; its enabled-status leaf is interlock-gated (plans refuse to open it when disabled); the rest of the PSS search-and-secure leaves are PSS-1" + - name: DoseShutter + family: Shutter + pv: "XF:17BMA-EPS{Sh:1}" + new: true + confirm: true + note: "the equipment-protection pre-shutter, the workhorse timed-exposure shutter for seconds-scale dose (open, software-timed sleep, close); a separate inner DIODE sample shutter (XF:17BMA-CT{DIODE-Local:1}...) protects the sample (DOSE-1)" + - name: DoseTimer + family: TimingController + pv: "XF:17BMA-ES:2{DG:1}" + new: true + confirm: true + note: "the DG535 delay generator that fires the millisecond Uniblitz fast shutter: a settable opening-time (bDelaySetAO, the source's exp_time, the dose time), a trigger mode, and a single-shot fire (genSingleShotTrigBO); the Uniblitz itself has no EPICS PV and is driven downstream of this timer (DOSE-1)" + +# =========================================================================== +# SAMPLE STAGE: the capillary-flow, high-throughput, and HTFly sample stages, +# and the sample-delivery pump (the fraction collector + 96-well plate are the +# sample-custody seam, see controls) +# =========================================================================== + +sample: + stage: sample + enclosure: xfp-endstation + intro: "The capillary-flow, high-throughput plate, and shutterless HTFly sample stages, and the syringe sample-delivery pump that flows solution through the beam." + note: > + XFP runs several sample-delivery modes. The capillary-flow stage flows a solution + sample through the beam; the high-throughput stage positions a 96-well plate; the + HTFly stage sweeps a fly-cell through the beam at a set velocity so the exposure + (dose) is the slit width over the stage velocity (HT-1). All bind LinearStage. The + syringe / sample-delivery pumps bind the existing loose FlowController Family (the + i22 / 7-BM / LIX precedent); XFP is its fourth consumer (FLOW-1, FLUID-1). The + fraction collector that captures footprinted aliquots into tubes, the pure-Python + 96-well plate addressing (no robot, no PV), and the solution Subject are the + sample-custody and offline-readout seam, not devices here (FC-1, HT-1, SUBJECT-1). + devices: + - name: CapillaryFlowStage + family: LinearStage + pv: "XF:17BMA-ES:1{Stg:5-Ax:X}Mtr" + new: true + confirm: true + note: "the capillary-flow sample stage (x / y, 100 mm travel) that places a flowing solution capillary in the beam; an ES:1 three-axis table positions auxiliary sample hardware (SAMPLE-1)" + - name: HighThroughputStage + family: LinearStage + pv: "XF:17BMA-ES:2{Stg:7-Ax:X}Mtr" + new: true + confirm: true + note: "the high-throughput sample stage (x / y, 200 mm travel) that positions a 96-well plate; the well / slot addressing is pure Python plus a coordinate table, no robot and no PV, modelled as a Procedure over the spine plus a Subject custody thread (HT-1)" + - name: HtFlyStage + family: LinearStage + pv: "XF:17BMA-ES:2{HTFly:1-Ax:X}Mtr" + new: true + confirm: true + note: "the shutterless high-throughput fly stage that sweeps a fly-cell row through the beam; the exposure (dose) is the defining-slit gap over the stage velocity, not a shutter, so the dose-timing is in the Procedure not a device (HT-1, DOSE-1)" + - name: DeliveryPump + family: FlowController # EXISTING loose Family (settable flow / pump actuator; n=4 with i22 + 7-bm + lix; FLOW-1) + pv: "XF:17BMA-ES:1{Pmp:02}" + new: true + confirm: true + note: "the sample-delivery syringe pump (an M50 pump with velocity / volume / slew setpoints, driving the dose-response / fraction-collection mode; a second PHD2000 infusion pump at XF:17BM-ES:1{Pmp:01} drives the capillary-flow / time-resolved mode) flowing solution through the capillary or flow cell during irradiation; both bind the existing loose FlowController Family and are folded into this one Asset at this cut, XFP its fourth consumer, reinforcing the LIX-fired rule-of-three (FLOW-1, FLUID-1)" + +# =========================================================================== +# DETECTION STAGE: the flux / dose monitors. There is NO scattering / area / +# imaging detector: the footprinting readout is offline mass spectrometry. +# =========================================================================== + +detection: + stage: detection + enclosure: xfp-endstation + intro: "The incident-flux and beam-position monitors that measure the delivered dose. There is no scattering, area, or imaging detector: the footprinting structural readout is done offline by mass spectrometry." + note: > + XFP has no Detector-role imaging device. The flux it delivers is the measurement + that matters: the QuadEM electrometers bind FluxMonitor (incident flux plus a + time-series trace to compute the delivered dose, with a diode array-logger as a + further dose accumulator); the Sydor four-channel monitor binds the loose + BeamPositionMonitor (beam position plus a sum-current flux readback, held under + review, DIAG-1). The footprinting structural readout (which residues were modified) + is OFFLINE mass spectrometry, downstream of the beamline and absent from the + profile collection; what the beamline produces is a footprinted sample plus a dose + record (READOUT-1, DET-1). + devices: + - name: FluxMonitor + family: FluxMonitor + pv: "XF:17BM-BI{EM:1}EM180:" + new: true + confirm: true + note: "the primary QuadEM electrometer reading incident flux and a per-exposure time-series, the basis for the delivered dose; a DIODE PDM array-logger (XF:17BMA-CT{DIODE-PDM:1}) accumulates the dose array and a second electrometer (XF:17BM-BI{EM:2}) adds channels; the flux-to-absorbed-dose calibration lives in offline analysis (DET-1, DOSE-1, READOUT-1)" + - name: BeamPositionMonitor + family: BeamPositionMonitor # loose Family, held under review (DIAG-1) + pv: "XF:17BM-BI{EM:BPM1}" + new: true + confirm: true + note: "the Sydor four-channel beam-position monitor (per-quadrant currents, beam x / y, and a sum-current total-flux readback); binds the loose BeamPositionMonitor (held under review, DIAG-1); the position-vs-intensity split is DIAG-1" + +# Cross-cutting control. XFP runs EPICS plus PV-bound fluidic actuators; CORA +# observes the floor and, where it replaces bluesky-style orchestration, conducts +# over it. The handles above were read from the profile collection and carried +# confirm (CTRL-1). +controls: + intro: > + XFP runs on the NSLS-II EPICS / ophyd control stack, the same floor as the rest of + the NSLS-II fleet. The device handles above are bound from the beamline's bluesky + profile collection (github.com/NSLS2/xfp-profile-collection, its startup files), + carried confirm (CTRL-1). The dose-delivery acquisition (open a timed shutter or + fire the delay-generator Uniblitz, or sweep the HTFly stage, while a pump flows the + sample and the QuadEM records the flux trace) runs through bluesky plans publishing + to Kafka with metadata in Redis (no Tiled, no queue-server in the profile + collection); that orchestration is the seam CORA's edge replaces, driving through + ophyd / EPICS. Crucially, the science readout is OFF the beamline: a footprinting + run produces a footprinted sample plus a dose record, and the mass-spectrometry + analysis is downstream (READOUT-1). + software_iocs_not_modeled: + # The sample-custody and offline-readout seam: the fraction collector, the 96-well + # plate addressing, and the offline mass spec. Only the delivery pump is a device + # (it binds FlowController). The rest is the Subject / Supply / Procedure shape. + - "XF:17BM-ES:1{FC:1}: the fraction collector (a PV-bound aliquot-routing actuator: a collect / waste valve, a tube index, a fill pattern, home) that captures footprinted aliquots into tubes; no existing Family fits an aliquot-router cleanly, so it is carried in the sample-custody seam (the footprinted-sample hand-off to offline MS) and not coined at n=1 (FC-1, READOUT-1)" + - "the 96-well high-throughput plate: addressed alpha-numerically (8 columns x 12 rows) by pure Python (locate_slot.py) plus a coordinate table, with no robot, no sample-changer, and no PV; moving to a well is a move on the HighThroughputStage; modelled as a Procedure over the spine plus a Subject custody thread (HT-1, the i03 / MX3 / LIX custody-as-Procedure precedent, here at the no-robot end of that spectrum)" + - "the offline mass-spectrometry readout: the footprinting structural analysis (which residues were modified) is done downstream, off the beamline, and is entirely absent from the profile collection; the beamline's run produces a footprinted sample plus a dose record (exposure time, filter thickness, flux time-series, well / tube identity), the offline-readout seam (READOUT-1)" + - "the SR630 thermocouple monitor (XF:17BMA-ES:2{TCM:1}) and the Sydor bias / thermocouple controller (XF:17BM-ES{PBG:1}): read-only temperature / bias diagnostics, used as alignment-flux proxies; not core footprinting devices, deferred (TEMP-1)" + - "the data plane is Kafka (document publishing) plus Redis (metadata), with no Tiled and no queue-server in the profile collection; CORA keeps its own data-of-record, the dose record being the system-of-record for a footprinting run (CTRL-1, READOUT-1)" + +# Continuously-available resources a run draws on. +resources: + intro: > + The continuously-available facility resources an XFP run needs, plus the + footprinting consumables. The optics run under vacuum (SUP-1). A footprinting run + draws on buffers, radical scavengers, and the flow medium as Supply consumables, + distinct from the facility-wide supplies (SUP-1, SUBJECT-1). + supplies: + - kind: PhotonBeam + - kind: CoolingWater + - kind: Vacuum + note: "the white-beam optics run under vacuum (SUP-1)" diff --git a/docs/deployments/index.md b/docs/deployments/index.md index 217d3259a4..b0481d6b99 100644 --- a/docs/deployments/index.md +++ b/docs/deployments/index.md @@ -67,6 +67,7 @@ The fourth Site CORA models. Like the Diamond exercise, its beamlines are revers | [LIX](lix/index.md) | Reverse-engineered | life-science solution scattering (bio-SAXS/WAXS, in-line SEC-SAXS) and scanning-microbeam mapping, 16-ID; the fleet's first solution beamline and fluidic sample-delivery chain; modelled from public beamline config | | [HEX](hex/index.md) | Reverse-engineered | high-energy engineering X-ray scattering (imaging/tomography + energy-dispersive and powder diffraction on a superconducting wiggler, white 30-250 keV / mono 30-200 keV), 27-ID; the fleet's first true high-energy hard X-ray beamline; modelled from public beamline config | | [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 | ## [SLAC](slac/index.md) diff --git a/docs/deployments/xfp/equipment/controls.md b/docs/deployments/xfp/equipment/controls.md new file mode 100644 index 0000000000..c47d2cc3f1 --- /dev/null +++ b/docs/deployments/xfp/equipment/controls.md @@ -0,0 +1,37 @@ +# Controls + +*The control stack, the dose-delivery timing, the sample-custody seam, and the offline-readout seam. First cut; handles read from the profile collection, carried confirm.* + +XFP runs on the NSLS-II EPICS / ophyd control stack, the same floor as the rest of the NSLS-II fleet, with a handful of PV-bound fluidic actuators on top. CORA observes that floor and, where it replaces bluesky-style orchestration, conducts over it; it does not replace EPICS itself. + +## Device handles + +The control handles are filled from the beamline's own bluesky profile collection ([NSLS2/xfp-profile-collection](https://github.com/NSLS2/xfp-profile-collection), the `startup/` files), so the descriptor carries the real PV roots. The optics zone carries the bendable mirror (`XF:17BM-OP{Mir:1}`, `OPT-1`) and the slits (`FE:C17B-OP{Slt:1}`, `XF:17BMA-OP{Slt:ADC}`, `OPT-2`); the dose gating carries the shutters (`XF:17BMA-EPS{Sh:1}`, `XF:17BM-PPS{Sh:FE}`) and the delay-generator dose timer (`XF:17BMA-ES:2{DG:1}`, `DOSE-1`); the endstation carries the sample stages (`XF:17BMA-ES:1{Stg:5}`, `XF:17BMA-ES:2{Stg:7}`), the delivery pump (`XF:17BMA-ES:1{Pmp:02}`, `FLOW-1`), and the flux monitors (`XF:17BM-BI{EM:1}`, `DET-1`). They remain confirm-pending: a value read from the profile collection is evidence to verify with staff, not a CORA-owned fact (`CTRL-1`). + +## The dose-delivery timing + +The dose is the experiment, so its timing is worth spelling out. There are three ways a dose is delivered, and CORA conducts each over the `ControlPort`: + +| Dose mode | How the exposure is timed | Devices conducted | +| --- | --- | --- | +| Seconds-scale | software-timed: open the pre-shutter, wait the exposure time, close it | `DoseShutter` (Shutter), `FluxMonitor` | +| Millisecond | the DG535 delay generator sets an opening-time and fires the Uniblitz fast shutter once | `DoseTimer` (TimingController), the Uniblitz (a PV-less shutter downstream of the timer), `FluxMonitor` | +| Shutterless high-throughput | the HTFly stage sweeps through the defining slit at a set velocity; exposure = slit gap / velocity | `HtFlyStage` (LinearStage), `DefiningSlit` (Slit), `FluxMonitor` | + +In every mode the `FilterWheel` sets the dose rate and the `FluxMonitor` records the flux time-series; the delivered dose is exposure time times flux times attenuation. The dose timer (`DoseTimer`) binds `TimingController` because its anatomy is a settable opening-time plus a single-shot trigger, the same timing-box role the fleet's other position-capture / trigger boxes fill; the Uniblitz it fires has no EPICS PV of its own and is modelled downstream of the timer (`DOSE-1`). + +## The sample-custody and offline-readout seam + +XFP's run produces a footprinted sample and a dose record, and the structural readout is offline. Three pieces sit in the seam rather than the device tree: + +- **The fraction collector** (`XF:17BM-ES:1{FC:1}`) is a PV-bound aliquot-routing actuator (a collect / waste valve, a tube index, a fill pattern, home). No existing Family fits an aliquot-router cleanly, and at n=1 CORA does not coin a `FractionCollector` Family; it is carried in the sample-custody seam, the hand-off that captures footprinted aliquots into tubes for offline analysis (`FC-1`, `READOUT-1`). +- **The 96-well plate** is addressed in pure Python (8 columns x 12 rows, a coordinate table, no robot and no PV); moving to a well is a move on the `HighThroughputStage`. It is a Procedure over the spine plus a Subject custody thread, the i03 / MX3 / LIX custody-as-Procedure precedent, here at the no-robot end of that spectrum (`HT-1`). +- **The offline mass-spectrometry readout** is downstream, off the beamline, and absent from the profile collection. CORA keeps the dose record as the system of record for a footprinting run; the MS structural analysis is a separate, later step (`READOUT-1`). + +## The orchestration seam + +The XFP acquisition runs through bluesky plans (gate a timed dose, or sweep the HTFly stage, while the pump flows the sample and the QuadEM records the flux trace), publishing documents to Kafka with run metadata in Redis; there is no Tiled and no queue-server in the profile collection (`CTRL-1`). That orchestration is the seam CORA's edge replaces: CORA conducts the dose program over the `ControlPort`, driving through ophyd / EPICS and the fluidic actuators rather than replacing them. The temperature / bias diagnostics (an SR630 thermocouple monitor, the Sydor bias controller) are read-only alignment-flux proxies, deferred (`TEMP-1`). + +## Equipment protection + +Only the front-end photon-shutter enable status (`XF:17BM-PPS{Sh:FE}` enabled-status, interlock-derived) is in the profile collection; plans refuse to open it when disabled. The rest of the PSS search-and-secure permit signals are absent and not invented here (`PSS-1`). Because the experiment is high-flux white-beam irradiation of biological samples, the dose itself is a hazard the safety tier would gate; that mapping is not modelled in this cut and is carried against the safety questions (`PSS-1`, `DOSE-1`). diff --git a/docs/deployments/xfp/equipment/detector.md b/docs/deployments/xfp/equipment/detector.md new file mode 100644 index 0000000000..00c48470cc --- /dev/null +++ b/docs/deployments/xfp/equipment/detector.md @@ -0,0 +1,35 @@ +# Detector + +*The flux and beam-position monitors that measure the delivered dose, and why XFP has no imaging detector: the footprinting structural readout is offline mass spectrometry. Reverse-engineered from `NSLS2/xfp-profile-collection` (`startup/`); PVs read from the profile collection, carried confirm.* + +This is the page where XFP departs most sharply from the rest of the fleet, so state it plainly: **XFP has no scattering, area, or imaging detector at all.** It is a dose-delivery beamline. The thing it "measures" on the instrument is the **incident flux**, which together with the exposure time and the attenuation is the **delivered dose**. The structural readout, which residues of the macromolecule were modified, is done **offline by mass spectrometry**, downstream of the beamline and entirely absent from the profile collection. So the detection side models flux / dose monitors plus the offline-readout seam. + +## Detection chain (flux / dose monitors) + +| Device | Family | PV | Role | +| --- | --- | --- | --- | +| `FluxMonitor` | `FluxMonitor` | `XF:17BM-BI{EM:1}EM180:` | the primary QuadEM electrometer: incident flux plus a per-exposure time-series, the basis for the delivered dose (`DET-1`, `DOSE-1`) | +| `BeamPositionMonitor` | `BeamPositionMonitor` (loose) | `XF:17BM-BI{EM:BPM1}` | the Sydor four-channel monitor: per-quadrant currents, beam x / y, and a sum-current total flux (`DIAG-1`) | + +The chain measures the beam, not a sample signal. The QuadEM electrometer reads the incident flux and records a per-exposure time-series, which is what lets a run compute the delivered dose; a DIODE PDM array-logger (`XF:17BMA-CT{DIODE-PDM:1}`) accumulates the dose array as a further monitor, and a second electrometer (`XF:17BM-BI{EM:2}`) adds channels. The Sydor monitor reads the beam position (for stability and alignment) and a sum current (a further total-flux readback). Beamline alignment is done by scanning a motor against one of these flux monitors and taking the centre of mass, not by imaging (there is no alignment camera in the profile collection). + +The **flux-to-absorbed-dose calibration**, the conversion from measured photons to the hydroxyl-radical dose the sample actually received, is not in the profile collection; it lives in offline analysis. CORA records the measured flux and the exposure as the dose evidence and treats the absorbed-dose calibration as a seam constant to be sourced from staff (`DOSE-1`, `READOUT-1`). + +## Why there is no imaging detector: the offline-readout seam + +A footprinting experiment is read out by mass spectrometry, which is a separate instrument in a separate lab. The beamline's role ends when it has delivered a known dose to a sample and captured the irradiated aliquot. So what a CORA run at XFP produces is: + +- a **footprinted sample**, the irradiated aliquot, often captured into a fraction-collector tube (see [Sample](sample.md)); and +- a **dose record**: the exposure time, the filter thickness, the flux time-series, and the well or tube identity. + +There are no measurement frames to store. The mass-spectrometry analysis that turns the footprinted sample into a structural map is the **offline-readout seam**: it happens downstream, off the beamline, and is absent from the profile collection. CORA is the system of record for the dose and the sample provenance; the structural readout is a separate, later step that a future integration could link back to the run, but is not modelled here (`READOUT-1`). + +This is the genuinely-new shape XFP brings to the fleet: a beamline whose product is a dosed sample plus a provenance record, not a detector image. + +## Why no new detector family + +The detection side reuses the catalog: the QuadEM electrometer binds `FluxMonitor`, the same role the fleet's other flux monitors fill, and the Sydor monitor binds the loose `BeamPositionMonitor` already held under review across the fleet (4-ID, 8-ID, 9-ID, ISS, FMX) pending the sensor fold-versus-promote decision; XFP adds a sighting, not a new Family (`DIAG-1`). No `Camera`, no `Scintillator`, no area detector is modelled, because none exists: the readout is offline. The dose-delivery role is expressed by the [Source](../beamline.md) gating (shutters + `TimingController` + `Filter`) and these flux monitors, not by a new detector class. + +## Families + +Reused from the catalog: `FluxMonitor` (the QuadEM electrometer and the DIODE array-logger). Loose and held under review: `BeamPositionMonitor` (the Sydor monitor, `DIAG-1`). New families: none; nothing graduates and the catalog is unchanged. There is no Detector-role imaging device; the footprinting readout is offline mass spectrometry (`READOUT-1`). The flux-to-dose calibration is a seam constant (`DOSE-1`). See [Inventory](../inventory.md) for the Asset tree, [Model](../model.md) for the family decisions, and [beamline.md](../beamline.md) for the source walk. diff --git a/docs/deployments/xfp/equipment/index.md b/docs/deployments/xfp/equipment/index.md new file mode 100644 index 0000000000..707034938c --- /dev/null +++ b/docs/deployments/xfp/equipment/index.md @@ -0,0 +1,22 @@ +# The beamline + +*The part of XFP CORA models today, as areas you can jump to: the white-beam optics and dose-delivery gating, the solution sample stages and delivery pump, and the flux / dose monitors, plus the controls. First cut.* + +XFP (X-ray Footprinting of Biological Materials) is the NSLS-II dose-delivery beamline at sector 17-BM, a Case Western Reserve University partner beamline. It irradiates a biological macromolecule in solution with an intense white / pink beam to footprint it via hydroxyl radicals; the structural readout is done offline by mass spectrometry. Its PV zones run `FE:C17B` (the front-end white-beam slit), `XF:17BM-OP` / `XF:17BMA-OP` (the optics: the bendable mirror, the beamline slits), `XF:17BMA-EPS` / `-PPS` / `-CT` (the shutters), `XF:17BM-BI` (the flux and beam-position monitors), and `XF:17BMA-ES:1` / `ES:2` (the footprinting endstations: the filter wheel, the sample stages, the pumps) (`ENC-1`). 17-BM is a bending-magnet, white / pink beam source, with no monochromator in the footprinting path (`SRC-1`, `WHITE-1`). + +Unlike every other beamline in the fleet, the stations here do not end in a detector that records a measurement. They end in a **dose** delivered to a sample, and a **dose record**; the structural readout is offline (see [Detector](detector.md)). Along the beam, in order, sit the **stations**: the [Source](../beamline.md) that conditions the white beam, sets the dose rate, and gates the timed dose; the [Sample](sample.md) that flows or positions the solution sample in the beam; and the [Detector](detector.md), which here is the flux / dose monitoring (no imaging detector). Cutting across them are the [Controls](controls.md). The stations are containment trees of apparatus (`Asset.parent_id`); controls relate to it sideways, by `controller_id`. + +## Stations + +- [Source](../beamline.md): the storage-ring machine state read through a loose `StorageRing` (`MACHINE-1`), the bendable front-end mirror (`OPT-1`), the white-beam and defining slits (`OPT-2`), the eight-position Al filter wheel that sets the dose rate (`ATTN-1`), and the dose-delivery gating, the personnel and timed shutters (`PSS-1`, `DOSE-1`) and the delay-generator dose timer that fires the millisecond Uniblitz fast shutter (`DOSE-1`). +- [Sample](sample.md): the capillary-flow sample stage (`SAMPLE-1`), the high-throughput plate and shutterless HTFly stages (`HT-1`), and the sample-delivery pump (a loose `FlowController`, `FLOW-1`). The fraction collector, the pure-Python 96-well plate addressing, and the solution Subject are the sample-custody seam (`FC-1`, `HT-1`, `SUBJECT-1`). +- [Detector](detector.md): the QuadEM flux monitor and the Sydor beam-position monitor that measure the delivered dose (`DET-1`, `DIAG-1`). There is no scattering, area, or imaging detector: the footprinting structural readout is offline mass spectrometry (`READOUT-1`). + +## Shared + +- [Controls](controls.md): the NSLS-II EPICS / ophyd control stack, the dose-delivery timing, the sample-custody seam, and the offline-readout seam (the run produces a footprinted sample plus a dose record; the mass spec is downstream). The device handles are bound from the beamline's profile collection and carried confirm (`CTRL-1`). +- Resources: the continuously-available supplies a run needs (the photon beam, cooling water, and vacuum for the white-beam optics), plus the footprinting consumables (buffers, radical scavengers, the flow medium) as Supply; carried in the descriptor (`SUP-1`). + +## Reference + +- [Inventory](../inventory.md): the full planned CORA Asset model (every device by `parent_id`, with Families and pending confirmations), including the loose families and the FlowController held at n=4. diff --git a/docs/deployments/xfp/equipment/sample.md b/docs/deployments/xfp/equipment/sample.md new file mode 100644 index 0000000000..7dd10c0cbb --- /dev/null +++ b/docs/deployments/xfp/equipment/sample.md @@ -0,0 +1,48 @@ +# Sample + +*The endstation sample side: the capillary-flow, high-throughput, and HTFly sample stages, and the sample-delivery pump, plus where the fraction collector, the 96-well plate, and the solution Subject sit. First cut; PVs read from the `NSLS2/xfp-profile-collection` startup files, carried confirm.* + +XFP's sample side delivers a biological macromolecule in solution into the white beam to be footprinted, then captures the irradiated aliquot for offline analysis. Like [LIX](../../lix/index.md), the specimen is a liquid, not a solid mount, and the delivery is fluidic. What is distinctive here is that the "result" of placing the sample in the beam is not a measurement but a **delivered dose**, and the sample itself, now footprinted, is carried off the beamline to a mass spectrometer (see [Detector](detector.md) and [Controls](controls.md)). The hardware is modelled in the sample stage of the [descriptor](../inventory.md); the custody chain is described here and in [Controls](controls.md). + +## The sample side at a glance + +| Asset | Family | PV | What it does | +| --- | --- | --- | --- | +| `CapillaryFlowStage` | `LinearStage` | `XF:17BMA-ES:1{Stg:5-Ax:X}` | places a flowing solution capillary in the beam (x / y, 100 mm travel) (`SAMPLE-1`) | +| `HighThroughputStage` | `LinearStage` | `XF:17BMA-ES:2{Stg:7-Ax:X}` | positions a 96-well plate (x / y, 200 mm travel); the well addressing is a Procedure, no robot (`HT-1`) | +| `HtFlyStage` | `LinearStage` | `XF:17BMA-ES:2{HTFly:1-Ax:X}` | sweeps a fly-cell row through the beam; the velocity sets the exposure (dose) (`HT-1`, `DOSE-1`) | +| `DeliveryPump` | `FlowController` (loose) | `XF:17BMA-ES:1{Pmp:02}` | the syringe pump flowing solution through the capillary / flow cell during irradiation (`FLOW-1`) | + +## Delivering the sample to the beam + +XFP runs several sample-delivery modes, each with its own stage, and all reuse the catalog `LinearStage` Family. + +The **capillary-flow mode** uses the `CapillaryFlowStage` to place a flowing solution capillary at the beam. A solution sample is pushed through the capillary by the delivery pump so that fresh, un-irradiated material is continuously presented, and the timed dose shutter (see [Source](../beamline.md)) gates the exposure (`SAMPLE-1`). + +The **high-throughput mode** uses the `HighThroughputStage` to position a 96-well plate, exposing one well at a time. The **HTFly mode** is shutterless: the `HtFlyStage` sweeps a fly-cell row through the defining slit at a set velocity, so the exposure time, and therefore the dose, is the slit gap divided by the stage velocity rather than a shutter opening (`HT-1`, `DOSE-1`). All three are plain translation stages; the dose-timing for HTFly lives in the Procedure, not in a special device. + +## The fluidic delivery: the pump + +The `DeliveryPump` flows the solution sample through the capillary or flow cell during irradiation. It is a settable flow / pump actuator (an M50 syringe pump with rate / volume setpoints and a run command, driving the dose-response / fraction-collection mode; a second PHD2000 infusion pump drives the capillary-flow / time-resolved mode), exactly the anatomy of the existing loose `FlowController` Family that i22, 7-BM, and LIX already use. So the pump **reuses** `FlowController`; it coins nothing. XFP is its **fourth** consumer, reinforcing the rule-of-three that [LIX](../../lix/model.md#the-flowcontroller-rule-of-three) already fired (see [Model](../model.md#the-flowcontroller-rule-of-three)). + +## The Subject and the sample-custody seam + +The deepest part of XFP's sample side is not a device. The **Subject** is a biological macromolecule (a protein or nucleic acid) in a buffer; the run irradiates it and produces a **footprinted aliquot**, which is the output that matters. Two pieces of the custody chain are deliberately modelled as the seam plus the Subject / Procedure shape, not as device Families: + +| Part of the chain | How CORA models it | Why | +| --- | --- | --- | +| The fraction collector | the sample-custody seam (`FC-1`) | a PV-bound aliquot-routing actuator (a collect / waste valve, a tube index, a fill pattern) that captures footprinted aliquots into tubes; no existing Family fits an aliquot-router cleanly, so it is carried in the custody seam, not coined at n=1 | +| The 96-well plate addressing | a Procedure + a Subject custody thread (`HT-1`) | the plate is addressed alpha-numerically (8 columns x 12 rows) by pure Python plus a coordinate table, with no robot, no sample-changer, and no PV; moving to a well is a move on the `HighThroughputStage`, the i03 / MX3 / LIX custody-as-Procedure precedent (XFP at the no-robot end) | +| The footprinted aliquot | a Subject carried to offline MS (`SUBJECT-1`, `READOUT-1`) | the run's output is the irradiated sample plus a dose record; the structural analysis (mass spec) is downstream, off the beamline | + +These aggregates are not instantiated in this descriptor-and-docs cut; they are the shape the deployment will take, recorded so the reader knows where the footprinting experiment's identity lives: the Subject (which macromolecule, which buffer), the Supply (buffers, radical scavengers, the flow medium), and the Procedure (the dose program plus the aliquot collection), with the dose record as the system of record. + +## Sample environment + +The only sample-environment readouts in the profile collection are temperature / bias diagnostics (an SR630 thermocouple monitor and the Sydor bias controller), used as alignment-flux proxies rather than as a controlled sample environment; they are read-only and deferred (`TEMP-1`). + +## Why no new Family here + +The sample stages all reuse the catalog `LinearStage`. The one fluidic device, the delivery pump, reuses the existing loose `FlowController` Family rather than coining a new one. The fraction collector, the 96-well plate, and the solution sample are deliberately not coined as device Families: they are the sample-custody and offline-readout seam, which is where a dose-delivery beamline's novelty belongs (`FC-1`, `HT-1`, `SUBJECT-1`, `READOUT-1`). Nothing here graduates and the catalog is unchanged. + +See [Open questions](../questions.md) for the sample-side facts still to confirm, [Inventory](../inventory.md) for the Asset tree, [Model](../model.md) for the family-reuse rationale and the FlowController rule-of-three, and [the source walk](../beamline.md) for the PVs as read from the profile collection. diff --git a/docs/deployments/xfp/governance.md b/docs/deployments/xfp/governance.md new file mode 100644 index 0000000000..64ccce5cf0 --- /dev/null +++ b/docs/deployments/xfp/governance.md @@ -0,0 +1,26 @@ +# Governance + +*Who will act at XFP, and the trust shape that will gate it. First cut.* + +Governance at XFP follows the same model as the other NSLS-II beamlines: people and autonomous agents are facility principals at the [NSLS-II Site](../nsls2/index.md#who-acts-here), and on the beamline they surface through the actions they take. Their commands are gated by a trust shape (a Zone grouping the beamline's resources, a Conduit binding the surfaces that may issue commands, and Policies that say who may do what). + +XFP is not yet driven by CORA, so this shape is not yet instantiated. As a modelling-exercise scaffold, the deployment is descriptor and docs today, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized. XFP is a Case Western Reserve University partner beamline operated within NSLS-II, so its operator and review structure is carried pending on the [NSLS-II Site](../nsls2/index.md#who-acts-here), with the partner-beamline operating model itself an open question (`GOV-1`). + +## The safety boundary + +The safety tier is the other piece that is not yet settled. Only the front-end photon-shutter enable status is in the beamline's profile collection (interlock-derived; plans refuse to open the shutter when it is disabled), so the Enclosure permit leaves and the rest of the search-and-secure structure are carried pending and not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [NSLS-II Site](../nsls2/index.md#the-safety-envelope), not on the beamline, and the beamline links up to them. + +XFP brings two distinctive hazards: a high-flux white beam, and the dose it delivers. They land with the equipment and the experiment that bring them, and an experiment Clearance would carry them. + +| Hazard class | Where it lands | Tracking | +| --- | --- | --- | +| High-flux white / pink X-ray beam | the [optics](inventory.md) and [endstation](inventory.md) enclosures (FE:C17B, XF:17BM / XF:17BMA) (`ENC-1`) | (`PSS-1`, `WHITE-1`) | +| Delivered radiolytic dose to biological samples | the [dose-delivery gating](beamline.md) and the [Sample](equipment/sample.md) side | (`DOSE-1`, `SUBJECT-1`) | +| Vacuum white-beam optics | the [Source](beamline.md) walk | (`SUP-1`) | +| Biological samples, buffers, and fluidics | the [Sample](equipment/sample.md) delivery chain | (`FLOW-1`, `SUBJECT-1`) | + +The high-flux white beam is the interlocked hazard; its permit leaves stay pending until the PSS signals are confirmed (`PSS-1`). The delivered dose is itself a controlled hazard at a footprinting beamline, distinctive to its dose-delivery character, and travels with the dose-gating chain and the Subject (`DOSE-1`, `SUBJECT-1`). The biological-sample and fluidics hazards travel with the delivery chain (`FLOW-1`). None of these is invented; each is carried against its question. + +## When the shape lands + +The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives XFP, following the [2-BM governance](../2-bm/governance.md) shape. Because XFP shares the NSLS-II EPICS and ophyd floor with the rest of the fleet, it re-tests the Site and Federation kernel rather than introducing a new trust model. The distinctive wrinkles are the partner-beamline operating model (`GOV-1`) and the offline-readout seam: a Conduit would bound the dose-delivery command surfaces, while the downstream mass-spec analysis sits outside the beamline's trust boundary entirely (`READOUT-1`). The Zone groups the same optics and endstation resources the [inventory](inventory.md) lists; the Policies bind to the NSLS-II operator roles carried pending at the Site (`GOV-1`). diff --git a/docs/deployments/xfp/index.md b/docs/deployments/xfp/index.md new file mode 100644 index 0000000000..f2e800032d --- /dev/null +++ b/docs/deployments/xfp/index.md @@ -0,0 +1,81 @@ +# XFP + +*The X-ray Footprinting beamline at NSLS-II, beamline 17-BM (a Case Western Reserve University partner beamline): synchrotron X-ray footprinting of biological macromolecules in solution. An intense white / pink beam generates hydroxyl radicals that covalently modify a protein or nucleic acid at solvent-accessible sites; the structural readout is done offline by mass spectrometry. This page walks the operational core CORA models today. It is a reverse-engineered first cut, not yet a running model.* + +| Property | Value | +| --- | --- | +| Asset | `XFP` (root Asset, `tier = Unit`, `parent_id = None`) | +| Facility | [NSLS-II](../nsls2/index.md) (bound via `facility_code = "nsls2"`, `FacilityKind = Site`) | +| Sector | `Sector 17` (PV namespace `XF:17BM*`; not a registered Asset) | +| Status | First cut, reverse-engineered, design-phase (descriptor + docs; scenarios deferred) | +| Source | A bending magnet, white / pink beam, no monochromator in the footprinting path (`SRC-1`, `WHITE-1`) | +| Control stack | NSLS-II EPICS / ophyd, Kafka + Redis data plane (no Tiled, no queue-server); handles bound from the profile collection, carried confirm (`CTRL-1`) | + +!!! warning "First cut, and confirm-pending by intent" + This scaffold was reverse-engineered from the beamline's own bluesky profile collection ([NSLS2/xfp-profile-collection](https://github.com/NSLS2/xfp-profile-collection)). EPICS PVs are real and read from the `startup/` files; vendor part numbers, serials, dose calibrations, and physical positions are not in the profile collection and are open questions. Every value is carried as `confirm` until XFP staff verify it. What CORA needs the team to confirm is on [Open questions](questions.md). + +## What makes XFP different + +XFP is the most structurally different beamline in the fleet, so read this carefully. Every other deployment CORA models is a **measurement** beamline: it conditions a beam, puts a sample in it, and a detector records a signal (a scattering pattern, a diffraction image, a spectrum, a tomogram). XFP is a **dose-delivery** beamline. It has **no scattering, area, or imaging detector at all**. Its job is to deliver a controlled radiolytic **dose** to a biological sample in solution; the actual structural readout, which residues were modified, is done **offline by mass spectrometry**, downstream and off the instrument. + +That inverts the usual shape, and it is what makes XFP worth modelling: + +- **The experiment variable is dose, not a measured signal.** Delivered dose is exposure time times incident flux times attenuation. The beamline's whole apparatus, the timed shutters, the delay-generator-fired millisecond fast shutter, the Al filter wheel, and the flux monitors, exists to set and measure that dose (`DOSE-1`). +- **The run produces a sample and a record, not frames.** A footprinting run produces (a) a footprinted **sample**, an irradiated aliquot, often captured into a fraction-collector tube, and (b) a **dose record**: exposure time, filter thickness, the flux time-series, and the well or tube identity. There are no measurement frames to store (`READOUT-1`). +- **The structural readout is the offline-readout seam.** The mass spectrometry that turns a footprinted sample into a structural map is downstream, off the beamline, and absent from the profile collection. CORA's run is the system of record for the dose and the sample provenance; the MS analysis is a separate, later step (`READOUT-1`). +- **The Subject is a biomolecule in solution.** Like [LIX](../lix/index.md), the specimen is a protein or nucleic acid in a buffer, delivered by a fluidic chain, not a solid mount (`SUBJECT-1`). + +XFP coins **no new Family** and changes nothing in the catalog. The whole device tree reuses existing vocabulary; the novelty lands on the Method (radiolytic footprinting), the Subject, and the offline-readout seam, not on device classes. The one reuse worth naming is the sample-delivery pump, which binds the existing loose `FlowController` Family (its fourth consumer; see below). + +## Scope: what is and is not modelled + +| Part | In this cut | Why | +| --- | --- | --- | +| Optics (`FE:C17B`, `XF:17BM-OP`, `XF:17BMA-OP`) | Yes | The bendable front-end mirror, the white-beam and defining slits, the Al filter wheel (`ENC-1`, `WHITE-1`) | +| Dose-delivery gating | Yes | The personnel and timed dose shutters, the delay generator that fires the millisecond Uniblitz fast shutter (`DOSE-1`) | +| Endstation (`XF:17BMA-ES:1`, `ES:2`) | Yes | The capillary-flow, high-throughput, and HTFly sample stages, the delivery pump, the flux and beam-position monitors (`ENC-1`) | +| New device classes | None | Zero new Families coined; nothing graduates; the catalog is unchanged | +| The sample-delivery pump | Loose `FlowController` | Reuses the flow / pump-actuator Family (i22 / 7-BM / LIX); XFP is its fourth consumer (`FLOW-1`) | +| Any scattering / area / imaging detector | No (does not exist) | XFP is dose-delivery; the readout is offline MS, so the detection side is flux / dose monitors only (`READOUT-1`, `DET-1`) | +| The fraction collector + 96-well plate | Seam + Subject / Procedure | The aliquot-routing collector and the pure-Python well addressing are the sample-custody seam, not devices (`FC-1`, `HT-1`) | +| The monochromatic XAS endstation (`ES:3`) | No (out of scope) | A separate endstation; footprinting is white / pink beam (`WHITE-1`) | +| Integration scenarios + vendor Models | No | Design-phase; the descriptor and docs come first | + +The deferred parts are recorded on [Model](model.md). + +## Key modelling decisions + +- **XFP is a dose-delivery beamline with no Detector-role device.** The detection side models flux / dose monitors (`FluxMonitor`, loose `BeamPositionMonitor`) and the offline-readout seam, not an imaging detector (`READOUT-1`, `DET-1`). +- **17-BM is a bending-magnet, white / pink beam source.** There is no insertion device and no monochromator in the footprinting path; machine state is observed through the loose `StorageRing`, and the white-versus-mono scope is carried pending (`SRC-1`, `WHITE-1`). +- **The dose chain reuses the catalog.** The Al filter wheel binds `Filter` (it sets the dose rate); the timed shutters bind `Shutter`; the delay generator that fires the millisecond Uniblitz fast shutter binds `TimingController` (its opening-time setpoint is the dose time); the QuadEM electrometers bind `FluxMonitor` (incident flux to compute dose) (`DOSE-1`). +- **The sample-delivery pump reuses the loose `FlowController`.** XFP is its **fourth** consumer (i22, 7-BM, LIX, XFP), reinforcing the rule-of-three LIX already fired; the FlowController graduation stays a separate gated decision (`FLOW-1`). +- **The fraction collector, the 96-well plate, and the offline MS are the sample-custody and offline-readout seam.** The aliquot-routing fraction collector has no clean Family at n=1 and is carried in the custody seam; the 96-well plate is addressed in pure Python (no robot, no PV) as a Procedure plus a Subject custody thread, the i03 / MX3 / LIX custody-as-Procedure precedent (XFP at the no-robot end); the mass-spec readout is downstream and off the beamline (`FC-1`, `HT-1`, `READOUT-1`, `SUBJECT-1`). +- **Zero new Families coined, nothing graduates, the catalog is unchanged.** + +## The beamline + +- [Source](beamline.md): the generated device walk: the storage-ring machine state, the bendable front-end mirror, the white-beam and defining slits, the Al filter wheel, and the dose-delivery gating (the personnel and timed shutters, the delay-generator dose timer). +- [Sample](equipment/sample.md): the capillary-flow, high-throughput, and HTFly sample stages, the sample-delivery pump, and where the fraction collector, the 96-well plate, and the solution Subject sit. +- [Detector](equipment/detector.md): the flux and beam-position monitors that measure the delivered dose, and why there is no imaging detector (the offline mass-spec readout). + +Cutting across them: + +- [Controls](equipment/controls.md): the EPICS / ophyd control stack, the dose-delivery timing, the sample-custody seam, and the offline-readout seam; handles bound from the profile collection and carried confirm (`CTRL-1`). + +The cross-cutting reference view is the [Inventory](inventory.md). The [Source](beamline.md) page is generated from the [`beamline.yaml`](https://github.com/xmap/cora/blob/main/deployments/xfp/beamline.yaml) descriptor. + +## Techniques + +[Techniques](techniques.md): what the modelled part of XFP is designed to do, as intent. X-ray footprinting (static / capillary-flow and shutterless high-throughput) maps to a new `x_ray_footprinting` Method, the fleet's first dose-delivery Method. It renders unlinked, carried pending (`TECH-1`). + +## Governance + +[Governance](governance.md): who will act at XFP and the trust shape that gates their commands. People and autonomous agents are facility principals at the [NSLS-II Site](../nsls2/index.md#who-acts-here), surfacing through their actions and gated by a Zone-plus-Conduit-plus-Policy trust shape. The NSLS-II operator pool and review are pending at the Site (`GOV-1`); only the front-end photon-shutter enable status is in the profile collection, so the rest of the PSS signals are carried pending, not invented (`PSS-1`). + +## Model + +[Model](model.md): the developer's by-kind index into where each CORA aggregate's XFP content lives, and the record of what is deliberately deferred. XFP introduces no new Family. + +## Not yet documented + +XFP is not yet driven by CORA, so the operations runbook and the live experiment view are deliberately not written yet. They join as the deployment firms up. The [2-BM deployment](../2-bm/index.md) shows the shape they will take. The PSS search-and-secure permit signals and the offline mass-spec readout integration are not invented here (`PSS-1`, `READOUT-1`). diff --git a/docs/deployments/xfp/inventory.md b/docs/deployments/xfp/inventory.md new file mode 100644 index 0000000000..3de3186ea2 --- /dev/null +++ b/docs/deployments/xfp/inventory.md @@ -0,0 +1,56 @@ +# Inventory + +*The CORA Asset model for the operational core of XFP modelled today: the planned device tree and what still needs confirming.* + +This cut models the XF:17BM white-beam optics, the dose-delivery gating, and the XF:17BMA-ES:1 / ES:2 footprinting endstations; the fraction collector, the 96-well plate addressing, the temperature diagnostics, the intermittently-connected stages, and the monochromatic XAS endstation (ES:3) are deferred (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/xfp/beamline.yaml) descriptor. + +Devices bind to a catalog [Family](../../catalog/families.md) wherever one fits. XFP coins **no new Family and changes nothing in the catalog**: the dose-delivery and sample devices reuse the existing `Mirror` / `Slit` / `Filter` / `Shutter` / `TimingController` / `LinearStage` / `FluxMonitor` vocabulary, and the one reuse worth naming is the sample-delivery pump, which binds the existing loose `FlowController` Family (its fourth consumer; see [Model](model.md#the-flowcontroller-rule-of-three)). The genuinely-new parts, the dose-as-experiment-variable, the solution Subject, and the offline mass-spec readout, land on the Method, the Subject, and the seam, not on devices. Notably there is **no Detector-role imaging device**: the readout is offline. Control handles are filled from the profile collection; no vendor Models are bound. + +## The Asset tree + +Root Asset `XFP` (`tier = Unit`, `facility_code = nsls2`); sub-systems nest below by `parent_id`. + +| Asset | Tier | Family | Enclosure | Design spec / note | +| --- | --- | --- | --- | --- | +| `XFP` | `Unit` | (root) | - | bound to the NSLS-II Site; 17-BM | +| `StorageRing` | `Device` | StorageRing (loose) | - | machine-level ring current, observe-only, `SR:OPS-BI{DCCT:1}` (MACHINE-1, SRC-1) | +| `FrontEndMirror` | `Device` | Mirror | xfp-optics | bendable white-beam mirror, `XF:17BM-OP{Mir:1}` (OPT-1) | +| `WhiteBeamSlit` | `Device` | Slit | xfp-optics | front-end white-beam slit, `FE:C17B-OP{Slt:1}` (OPT-2) | +| `DefiningSlit` | `Device` | Slit | xfp-optics | ADC defining slit (its gap sets the HTFly exposure), `XF:17BMA-OP{Slt:ADC}` (OPT-2, HT-1) | +| `FilterWheel` | `Device` | Filter | xfp-optics | eight-position Al filter wheel (dose rate), `XF:17BMA-ES:1{Fltr:1}` (ATTN-1) | +| `PhotonShutter` | `Device` | Shutter | xfp-optics | PPS front-end photon shutter, `XF:17BM-PPS{Sh:FE}` (PSS-1) | +| `DoseShutter` | `Device` | Shutter | xfp-optics | EPS timed-exposure pre-shutter, `XF:17BMA-EPS{Sh:1}` (DOSE-1) | +| `DoseTimer` | `Device` | TimingController | xfp-optics | DG535 delay generator firing the ms Uniblitz fast shutter, `XF:17BMA-ES:2{DG:1}` (DOSE-1) | +| `CapillaryFlowStage` | `Device` | LinearStage | xfp-endstation | capillary-flow sample stage (x / y), `XF:17BMA-ES:1{Stg:5}` (SAMPLE-1) | +| `HighThroughputStage` | `Device` | LinearStage | xfp-endstation | 96-well plate stage (x / y); well addressing is a Procedure, no robot (HT-1) | +| `HtFlyStage` | `Device` | LinearStage | xfp-endstation | shutterless HTFly stage (velocity = exposure), `XF:17BMA-ES:2{HTFly:1}` (HT-1, DOSE-1) | +| `DeliveryPump` | `Device` | FlowController (loose) | xfp-endstation | sample-delivery syringe pump, `XF:17BMA-ES:1{Pmp:02}`; fourth FlowController consumer (FLOW-1) | +| `FluxMonitor` | `Device` | FluxMonitor | xfp-endstation | QuadEM electrometer, incident flux + time-series = dose, `XF:17BM-BI{EM:1}` (DET-1, DOSE-1) | +| `BeamPositionMonitor` | `Device` | BeamPositionMonitor (loose) | xfp-endstation | Sydor 4-channel position + sum-flux monitor, `XF:17BM-BI{EM:BPM1}` (DIAG-1) | + +Families reused from the catalog: `Mirror`, `Slit`, `Filter`, `Shutter`, `TimingController`, `LinearStage`, `FluxMonitor`. Loose families reused from siblings: `StorageRing` (supply), `FlowController` (the delivery pump, n=4, graduation overdue), `BeamPositionMonitor` (held under review, DIAG-1). No new family is coined and nothing graduates. There is no Detector-role imaging device: the readout is offline (READOUT-1). + +## Pending confirmations + +| Value to confirm | Applies to | Status | Tracking | +| --- | --- | --- | --- | +| Optics-vs-endstation hutch grouping | the enclosures | `unknown-pending-confirmation` | (ENC-1) | +| Bending-magnet source | the source | `unknown-pending-confirmation` | (SRC-1) | +| White vs pink vs mono in the footprinting path | the beam conditioning | `unknown-pending-confirmation` | (WHITE-1) | +| Control handles (EPICS PVs) and data plane | all devices | `read-from-config-pending-confirmation` | (CTRL-1) | +| PSS permit signals and shutters | the enclosures | `unknown-pending-confirmation` | (PSS-1) | +| Storage-ring state read | `StorageRing` | `unknown-pending-confirmation` | (MACHINE-1) | +| Front-end mirror coating and bend | `FrontEndMirror` | `unknown-pending-confirmation` | (OPT-1) | +| Slit blade-axis maps | the slits | `unknown-pending-confirmation` | (OPT-2) | +| Attenuator chain (filter wheel, z-attenuator, pinholes) | `FilterWheel` | `unknown-pending-confirmation` | (ATTN-1) | +| Dose-delivery chain and flux-to-dose calibration | `DoseShutter`, `DoseTimer`, `FluxMonitor` | `unknown-pending-confirmation` | (DOSE-1) | +| Capillary-flow sample stage | `CapillaryFlowStage` | `unknown-pending-confirmation` | (SAMPLE-1) | +| High-throughput plate + HTFly + well addressing | `HighThroughputStage`, `HtFlyStage` | `unknown-pending-confirmation` | (HT-1) | +| Delivery-pump Family | `DeliveryPump` | `unknown-pending-confirmation` | (FLOW-1) | +| Fraction collector and aliquot custody | the sample handling | `unknown-pending-confirmation` | (FC-1) | +| The solution Subject | the sample | `unknown-pending-confirmation` | (SUBJECT-1) | +| Temperature / bias diagnostics | the diagnostics | `unknown-pending-confirmation` | (TEMP-1) | +| Flux / dose-monitor channel map | `FluxMonitor` | `unknown-pending-confirmation` | (DET-1) | +| Beam-position-monitor position-vs-intensity split | `BeamPositionMonitor` | `unknown-pending-confirmation` | (DIAG-1) | +| Offline mass-spec readout hand-off | the readout | `unknown-pending-confirmation` | (READOUT-1) | +| Vacuum extent and cooling supply | `resources` | `unknown-pending-confirmation` | (SUP-1) | diff --git a/docs/deployments/xfp/model.md b/docs/deployments/xfp/model.md new file mode 100644 index 0000000000..87ef9de017 --- /dev/null +++ b/docs/deployments/xfp/model.md @@ -0,0 +1,58 @@ +# Model + +*The developer's index into where XFP content lives, why this dose-delivery beamline coins no new family, how it models a beamline with no detector and an offline readout, and the record of what is deliberately deferred. First cut.* + +XFP is a descriptor-and-docs scaffold today, reverse-engineered from the beamline's profile collection: 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/xfp/beamline.yaml`](https://github.com/xmap/cora/blob/main/deployments/xfp/beamline.yaml) | the device walk with bound PVs; source of the generated [Source](beamline.md) page | +| Site descriptor | [`deployments/nsls2/site.yaml`](https://github.com/xmap/cora/blob/main/deployments/nsls2/site.yaml) | the NSLS-II facility surface; `XFP` added to its beamline list, with the footprinting Practices | +| Extraction provenance | [NSLS2/xfp-profile-collection](https://github.com/NSLS2/xfp-profile-collection) | the `startup/` device definitions 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 (below) | +| Catalog Method | [`catalog/catalog.yaml`](https://github.com/xmap/cora/blob/main/catalog/catalog.yaml) | none added; `x_ray_footprinting` is a new pending slug, the fleet's first dose-delivery Method (`TECH-1`) | +| Equipment Assets | not yet registered | the [Inventory](inventory.md) is the planned shape; no scenario registers XFP Assets yet | +| Trust / governance | not yet instantiated | see [Governance](governance.md) | + +## What makes XFP new + +XFP is the most structurally distinct deployment in the fleet. Every other beamline CORA models is a measurement beamline: condition a beam, place a sample, record a detector signal. XFP is a **dose-delivery** beamline with **no detector**. Its contributions: + +- **Dose as the experiment variable.** The controlled quantity is the delivered radiolytic dose (exposure time times incident flux times attenuation), not a detector setting. The whole apparatus, the timed shutters, the delay-generator-fired millisecond fast shutter, the Al filter wheel, and the flux monitors, exists to set and measure that dose. +- **A sample-and-record output, not frames.** A footprinting run produces a footprinted sample (an irradiated aliquot) plus a dose record (exposure time, filter thickness, flux time-series, well / tube identity). There are no measurement frames. +- **The offline-readout seam.** The structural readout (which residues were modified) is offline mass spectrometry, downstream and off the beamline. CORA is the system of record for the dose and the sample provenance; the MS analysis is a separate, later step. +- **A solution Subject.** Like LIX, the specimen is a biological macromolecule in a buffer, delivered fluidically. + +## No new families + +XFP coins no new Family and changes nothing in the catalog. The whole device tree reuses existing vocabulary; the novelty is in the Method, the Subject, and the seam, not in device classes. + +- **17-BM is a bending-magnet, white / pink beam source** (no insertion device, no monochromator in the footprinting path); machine state is observed through the loose `StorageRing`, and the white-versus-mono scope is `SRC-1` / `WHITE-1`. +- **The dose chain reuses the catalog:** the bendable mirror binds `Mirror`; the slits bind `Slit`; the Al filter wheel binds `Filter` (it sets the dose rate); the timed shutters bind `Shutter`; the delay generator that fires the millisecond Uniblitz fast shutter binds `TimingController` (its opening-time setpoint is the dose time); the QuadEM electrometers bind `FluxMonitor`; the Sydor beam-position monitor binds the loose `BeamPositionMonitor` (held under review, `DIAG-1`); the sample stages bind `LinearStage`. + +## How a beamline with no detector is modelled + +XFP has no Detector-role imaging device, and CORA models that honestly rather than inventing one: + +- the detection side holds **flux / dose monitors** (`FluxMonitor`, the loose `BeamPositionMonitor`), which measure the delivered dose, not a sample signal; +- the dose-delivery role is expressed by the **Source gating** (Shutter + `TimingController` + `Filter`) plus those flux monitors, not by a detector; +- the structural readout is the **offline-readout seam**: the run's product is a footprinted sample plus a dose record, and the mass-spec analysis happens downstream, off the beamline (`READOUT-1`). + +This is the deliberate inversion: where a measurement beamline's run is anchored on a Dataset of detector frames, an XFP run is anchored on a dose record and a Subject (the footprinted aliquot), with the structural Dataset produced elsewhere and linked back later. + +## The FlowController rule-of-three + +The one device reuse worth naming is the sample-delivery pump. Its anatomy is a settable flow / pump actuator (rate / volume setpoints, a run command), exactly the existing loose `FlowController` Family that i22, 7-BM, and LIX already use. So the pump **reuses** `FlowController`; it coins nothing. XFP is its **fourth** consumer (i22, 7-BM, LIX, XFP), past the rule-of-three that LIX already fired, so the graduation is now overdue. As with LIX, the `_PROMOTION_REVIEWED` note for `FlowController` is updated (to n=4) and the graduation itself, a YAML-and-docs change presenting the existing `Regulator` Role, like `TemperatureController` and `FluxMonitor`, re-pointing i22 / 7-BM / LIX / XFP, stays a separate gated decision, not folded into this scaffold (`FLOW-1`, `FLUID-1`). + +## Deliberately not here yet + +- **The fraction collector Family (`FC-1`).** The fraction collector is a PV-bound aliquot-routing actuator with no clean existing Family. At n=1 CORA does not coin a `FractionCollector` Family; it is carried in the sample-custody seam (the footprinted-sample hand-off to offline MS). +- **The 96-well plate handler (`HT-1`).** The plate is addressed in pure Python (8 columns x 12 rows, a coordinate table, no robot and no PV); it is a Procedure over the spine plus a Subject custody thread, the i03 / MX3 / LIX custody-as-Procedure precedent (XFP at the no-robot end of that spectrum), not a device Family. +- **The offline mass-spec readout (`READOUT-1`).** The structural analysis is downstream, off the beamline, and absent from the profile collection. A future integration could link the offline MS result back to the dose record; it is not modelled here. +- **The Method.** Whether `x_ray_footprinting` (or a broader controlled-dose / irradiation Capability) enters CORA's catalog is an owner decision; the Practices render unlinked, pending (`TECH-1`). +- **The intermittently-connected and out-of-scope hardware.** The 0-9 mm Al z-attenuator, the beam-defining pinhole stages, the greenfield Galil stages, and the temperature / bias diagnostics are intermittently connected or read-only and not modelled as core devices (`ATTN-1`, `TEMP-1`); the monochromatic XAS endstation (ES:3) is a separate endstation, out of scope for footprinting (`WHITE-1`). +- **The time-resolved mixing mode.** The stopped-flow time-resolved footprinting mode is flagged unfinished in the source; no Practice is recorded for it (`TECH-1`). +- **The simulated devices and full asset-tree scenarios.** No `test_xfp_*.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/xfp/questions.md b/docs/deployments/xfp/questions.md new file mode 100644 index 0000000000..b8183efb3b --- /dev/null +++ b/docs/deployments/xfp/questions.md @@ -0,0 +1,62 @@ +# Open questions + +*What CORA needs the XFP team to confirm before the model can be trusted.* + +XFP was reverse-engineered from the beamline's own bluesky profile collection ([NSLS2/xfp-profile-collection](https://github.com/NSLS2/xfp-profile-collection)), so the control handles in the [Inventory](inventory.md) are the beamline's real PVs, read from the `startup/` files rather than confirmed by staff. 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 | Are the optics (FE:C17B, XF:17BM-OP / XF:17BMA-OP) and the endstations (XF:17BMA-ES:1, ES:2) separate hutches? | Two enclosures: a `xfp-optics` zone and the `xfp-endstation` hutch. | The Enclosure grouping. | +| SRC-1 | Nice-to-have | The 17-BM source (a bending magnet is implied by the name and the white-beam design; the profile collection exposes no source device, only ring current). | A bending-magnet source, observed only through the machine state. | The source Asset detail. | +| WHITE-1 | Blocks-go-live | Is routine footprinting white beam or pink beam (filtered by the mirror cutoff and the Al filters), and is there any monochromator in the footprinting path? (A DCM exists only on a separate XAS endstation, ES:3, excluded here.) | White / pink beam, no monochromator in the footprinting path; ES:3 out of scope. | The beam-conditioning model. | + +## Source and optics + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| MACHINE-1 | Nice-to-have | The storage-ring state XFP reads (only the ring current is read for a beam-present suspender). | Observe-only machine state, a loose `StorageRing`; the rest pending. | The machine-state observation. | +| OPT-1 | Nice-to-have | The front-end mirror coating and bend mechanism (a bendable mirror with a Bend focus axis and thermocouples). | A bendable focusing `Mirror`; coating and bend pending. | The mirror Asset detail. | +| OPT-2 | Nice-to-have | The blade-axis roles of the white-beam, PB / PDS, and ADC defining slits (the ADC horizontal gap sets the HTFly exposure window). | Four-blade / center-gap slits bound to `Slit`. | The slit Asset detail. | +| ATTN-1 | Blocks-go-live | The attenuation chain that sets the dose RATE: the eight-position Al filter wheel, plus the intermittently-connected 0-9 mm Al z-attenuator and the beam-defining pinhole apertures. | The filter wheel binds `Filter`; the pinhole / z-attenuator are further attenuators carried pending. | The dose-rate attenuator modelling. | + +## Dose delivery + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| DOSE-1 | Blocks-go-live | The dose-delivery chain: the timed shutters (the EPS pre-shutter, the PPS photon shutter, the inner DIODE sample shutter), the DG535 delay generator that fires the millisecond Uniblitz fast shutter (its opening-time setpoint is the dose time), and the flux-to-absorbed-dose calibration (which lives in offline analysis). | Seconds-scale dose is software-timed on the pre-shutter (`Shutter`); millisecond dose is the delay-generator-fired Uniblitz (`TimingController`); the dose calibration is offline. | The dose-delivery modelling. | + +## Sample and delivery + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| SAMPLE-1 | Blocks-go-live | The capillary-flow sample stage axes and how a flowing solution capillary mounts in the beam. | A `LinearStage` for the capillary-flow stage; the flow is the fluidic seam. | The sample-stage modelling. | +| HT-1 | Blocks-go-live | The high-throughput modes: the 96-well plate stage and addressing (8 columns x 12 rows, addressed in pure Python with a coordinate table, no robot and no PV), and the shutterless HTFly stage (exposure = defining-slit gap over stage velocity). | `LinearStage` stages; the well addressing and the HTFly dose-timing are Procedures over the spine plus a Subject custody thread. | The high-throughput modelling. | +| FLOW-1 | Nice-to-have | The sample-delivery pumps (an M50 pump and a PHD2000 infusion pump, both with rate / volume setpoints) and whether the pump actuator earns a Family. | The pump binds the existing loose `FlowController` (i22 / 7-BM / LIX, n=4, graduation overdue); no new family coined. | The pump modelling; the CORA decision is on [Model](model.md#deliberately-not-here-yet). | +| FC-1 | Nice-to-have | The fraction collector (a PV-bound aliquot-routing actuator: a collect / waste valve, a tube index, a fill pattern) that captures footprinted aliquots, and whether it earns a Family. | Carried in the sample-custody seam (the footprinted-sample hand-off to offline MS); no `FractionCollector` Family coined at n=1. | The fraction-collector modelling. | +| SUBJECT-1 | Nice-to-have | The solution Subject: a biological macromolecule (protein / nucleic acid) in a buffer, irradiated, with its own provenance. | A liquid Subject; the footprinted aliquot is the run's output, carried to offline MS. | The Subject modelling. | +| TEMP-1 | Nice-to-have | The temperature / bias diagnostics (the SR630 thermocouple monitor and the Sydor bias / thermocouple controller), used as alignment-flux proxies. | Read-only diagnostics, not core footprinting devices; deferred. | The temperature-diagnostic modelling. | + +## Detection and readout + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| DET-1 | Blocks-go-live | The flux / dose monitors: the QuadEM electrometers (incident flux plus a per-exposure time-series), the DIODE PDM array-logger, and which channels measure the delivered dose. | `FluxMonitor` Assets; the channel map and the dose computation carried pending. | The flux / dose-monitor modelling. | +| DIAG-1 | Nice-to-have | The Sydor beam-position monitor (per-quadrant currents, beam x / y, a sum-current total flux) and the position-versus-intensity split (the fleet-wide question). | A loose `BeamPositionMonitor` (held under review across 4-ID / 8-ID / 9-ID / ISS / FMX). | The beam-position-monitor catalog home. | +| READOUT-1 | Blocks-go-live | The offline mass-spectrometry readout: what artifact the beamline hands off (a footprinted aliquot in a fraction-collector tube? a capillary?), whether a sample-ID barcode is recorded, and where the dose record is the system of record. | The beamline produces a footprinted sample plus a dose record; the MS structural analysis is downstream, off the beamline. | The offline-readout seam. | + +## Control and safety + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| CTRL-1 | Blocks-go-live | Are the EPICS PV handles read from the profile collection current and correct, and is the data plane Kafka plus Redis (no Tiled, no queue-server)? | The handles in the descriptor are taken from the profile collection and carried confirm; the data plane is the seam CORA's edge replaces. | Verifying each Asset's control handle and the data plane. | +| PSS-1 | Blocks-go-live | The PSS search-and-secure permit signals and the front-end / photon shutters (only the front-end photon-shutter enable status is in the profile collection). | Permit leaves to be named; not invented here. | The Enclosure permit signals and the safety tier. | +| SUP-1 | Nice-to-have | The vacuum extent (the white-beam optics) and the cooling supply, plus the footprinting consumables (buffers, radical scavengers, the flow medium). | Photon beam, cooling water, and vacuum on the optics; the consumables as Supply. | The Supply observations. | +| GOV-1 | Nice-to-have | The NSLS-II operator pool and safety-review structure, and XFP's partner-beamline (Case Western) operating model. | Carried pending on the NSLS-II Site, not instantiated per beamline. | The governance principals. | + +## Technique + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| TECH-1 | Blocks-go-live | Does X-ray footprinting (the dose-delivery technique, with offline MS readout) enter CORA's catalog as a Capability / Method? | Deferred: carried as pending Practices; `x_ray_footprinting` is new, the fleet's first dose-delivery Method; not coined. | The technique Capability. | diff --git a/docs/deployments/xfp/techniques.md b/docs/deployments/xfp/techniques.md new file mode 100644 index 0000000000..385ccac499 --- /dev/null +++ b/docs/deployments/xfp/techniques.md @@ -0,0 +1,34 @@ +# Techniques + +*What the modelled part of XFP is designed to do, as intent. First cut.* + +A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../nsls2/index.md#the-techniques-adapted-here) is how a facility adapts it. XFP does one technique, **X-ray footprinting**, in two delivery modes: static / capillary-flow, and shutterless high-throughput. The Method below renders unlinked and is carried pending until the owner-scope decision (`TECH-1`) brings it into the catalog. + +| Technique | Catalog method | Notes | +| --- | --- | --- | +| X-ray footprinting (capillary-flow / static) | `x_ray_footprinting` | gate a timed white-beam dose onto a flowing solution capillary or 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; readout is offline mass spec (`TECH-1`, `READOUT-1`) | +| High-throughput footprinting (HTFly) | `x_ray_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`) | + +Both modes need the [white-beam chain](beamline.md) (the mirror, the slits, the Al filter wheel for dose rate), the [dose gating](beamline.md) (the timed shutters or the delay-generator-fired Uniblitz, or the HTFly velocity), the [sample side](equipment/sample.md) (a stage and the delivery pump), and the [flux monitors](equipment/detector.md) (to record the delivered dose). They differ only in how the exposure is timed and how many samples are handled. + +## The technique is dose delivery, and the readout is offline + +This is the heart of what makes XFP a new shape for CORA. X-ray footprinting is not a measurement technique in the sense the rest of the fleet uses: the beamline does not record a structural signal. It **delivers a controlled radiolytic dose** to a biological macromolecule in solution, generating hydroxyl radicals that covalently modify the molecule at solvent-accessible sites. The modified sample is then analysed **offline by mass spectrometry**, which reveals which residues were exposed and thus maps the molecule's surface and conformational changes. + +So the Method `x_ray_footprinting` is a **dose-delivery** Method: + +- its controlled variable is the delivered dose (exposure time times flux times attenuation), not a detector setting; +- its product is a footprinted sample plus a dose record, not a measurement frame; +- its structural readout is the offline-readout seam (mass spec, downstream and off the beamline, `READOUT-1`). + +That is why `x_ray_footprinting` is proposed as a Method distinct from anything in the catalog: not because the optics are unusual (a white beam, a filter, a shutter), but because the experiment shape, dose-in, sample-out, structure-read-elsewhere, is genuinely new. Whether the catalog ultimately holds a `x_ray_footprinting` Capability, or a broader "controlled-dose / irradiation" Capability with footprinting as a Practice adaptation, is the owner-scope decision (`TECH-1`); XFP records the case, it does not mint the vocabulary. The matching Site Practices (`XFP_footprinting_practice`, `XFP_high_throughput_footprinting_practice`) are carried pending in the [NSLS-II Site](../nsls2/index.md#the-techniques-adapted-here); each binding lands when its Capability does. + +## A time-resolved mode, deferred + +The profile collection also contains a time-resolved capillary-flow mode (a stopped-flow style mixing experiment before irradiation), but it is flagged unfinished in the source, so no Practice is recorded for it here; it is a later mode that would reuse the same `x_ray_footprinting` Method with a mixing step in the Procedure (`TECH-1`). + +## Not modelled yet + +The concrete acquisition recipes are not written yet. For footprinting that is the dose series (the set of exposure times or filter thicknesses that build a dose-response curve), the flow program that presents fresh sample, the aliquot-collection pattern, and the flux-to-absorbed-dose calibration that converts the measured flux to the dose the sample received (a seam constant that lives in offline analysis, `DOSE-1`). The downstream linkage to the offline mass-spec result is the offline-readout seam, not a beamline recipe (`READOUT-1`). These join as the deployment approaches the point where CORA drives XFP. + +Whether `x_ray_footprinting` enters CORA's catalog is an owner-scope decision on [Model](model.md): a modelling exercise reinforces the case but does not mint cross-facility Method vocabulary on its own. See [Open questions](questions.md) for the world-facts to confirm first. diff --git a/mkdocs.yml b/mkdocs.yml index 70017f0a86..7d33e95345 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -628,6 +628,19 @@ nav: - Techniques: deployments/amx/techniques.md - Governance: deployments/amx/governance.md - Model: deployments/amx/model.md + - XFP: + - deployments/xfp/index.md + - Open questions: deployments/xfp/questions.md + - The beamline: + - deployments/xfp/equipment/index.md + - Source: deployments/xfp/beamline.md + - Sample: deployments/xfp/equipment/sample.md + - Detector: deployments/xfp/equipment/detector.md + - Controls: deployments/xfp/equipment/controls.md + - Inventory: deployments/xfp/inventory.md + - Techniques: deployments/xfp/techniques.md + - Governance: deployments/xfp/governance.md + - Model: deployments/xfp/model.md - SLAC: - deployments/slac/index.md - LCLS-MFX: