diff --git a/apps/api/tests/unit/deployments/test_beamline_descriptor.py b/apps/api/tests/unit/deployments/test_beamline_descriptor.py index b1d5c688e4b..16d6cebfb30 100644 --- a/apps/api/tests/unit/deployments/test_beamline_descriptor.py +++ b/apps/api/tests/unit/deployments/test_beamline_descriptor.py @@ -367,7 +367,6 @@ def test_no_unexpected_orphan_catalog_models() -> None: "SlipRing": "passive-deferred: passive rotation feedthrough (TomoWISE)", "Wedge": "passive-deferred: passive fixed wedge (2-BM)", "Diagnostic": "staged: beam-position monitor, Sensor Role; fold-vs-promote open (DIAG-1)", - "FlowController": "staged: settable flow/pump actuator; earn-vs-defer open (FLOW-1/ENV-1)", "Backlight": "staged: new illumination affordance; rule-of-three open (ROBOT-1/DET-1)", "BetrandLens": "staged: novel TXM optic, FXI-only; rule-of-three open (OPTIC-3)", "MultilayerLaueLens": "staged: novel 1D crossed-pair nano-focus optic, HXN-only (OPTIC-3)", @@ -400,7 +399,6 @@ 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=4 (i22/7-bm/lix/xfp); overdue (FLOW-1)", "BeamPositionMonitor": "hold: fold-vs-promote across 4-id/8-id/9-id/iss/fmx/cdi (DIAG-1)", "Laser": "hold: pump-probe laser model-vs-hazard open (4-id + lcls-mfx; SAMPLE-1)", "Backlight": "hold: sample-illumination fold-vs-promote open (i03 + i24 + fmx + i19; DET-1)", diff --git a/catalog/catalog.yaml b/catalog/catalog.yaml index 59c4e64b443..c424193c2b5 100644 --- a/catalog/catalog.yaml +++ b/catalog/catalog.yaml @@ -115,7 +115,9 @@ families: - name: EmissionSpectrometer note: "Crystal-analyzer X-ray emission spectrometer Family: a post-sample instrument that composes one or more bent analyzer crystals and an area / position-sensitive detector along a Rowland-circle (Johann) or wavelength-dispersive (von Hamos) geometry to measure the emitted X-ray spectrum (XES) or select an emission line for high-energy-resolution fluorescence detection (HERFD). Presents the Detector Role (it acquires the emission spectrum). Distinct from EnergyDispersiveSpectrometer (a point Sensor that resolves energy electronically per event, with no analyzer crystal) and from Monochromator (a beam-conditioning Bragg optic upstream of the sample); the discriminator is the post-sample crystal-analyzer emission-dispersing role. Distinct too from the loose EnergyAnalyzer (the IXS diced-crystal analyzer selecting a fixed final energy on the inelastic-scattering arm, ANALYZER-1) and the loose SpectrometerArm (the SIX soft X-ray grating-dispersive multi-chamber RIXS arm, RIXS-1), which stay loose pending their own rule-of-three. Earned in once two deployments shared it, SLAC LCLS-MFX (the von Hamos six-crystal XES spectrometer) and NSLS-II ISS (8-ID, the Johann plus von Hamos crystal emission spectrometers for XES / HERFD); crystal cut, Rowland radius, and Johann-vs-von-Hamos geometry are a per-Asset settings or bound-Model difference, not a Family split (the InsertionDevice / Manipulator precedent). MAX IV Balder is a third near-sighting (SCANIA-2D). Whether each analyzer crystal is a child Asset is deferred (SPEC-1)." - name: TemperatureController - note: "Continuous-setpoint sample-environment temperature actuator Family: drives a sample temperature to a commanded setpoint, typically via a PID control loop. Presents the Regulator Role (requires the Settable affordance). Distinct from Controller (which supervises subordinate Assets without itself performing) and Sensor (which only reports): a TemperatureController performs by acting on the temperature. Graduated on the rule-of-three across Diamond i22 (Linkam), i03 (cryostream, thawer), and i11 (Cyberstar / Eurotherm blowers, Oxford cryostreams); cooling-vs-heating and PID-vs-other are a per-Asset settings or bound-Model difference, not a Family split. FlowController (a settable-setpoint mass-flow / pump actuator that would also present Regulator) stays loose pending its own rule-of-three." + note: "Continuous-setpoint sample-environment temperature actuator Family: drives a sample temperature to a commanded setpoint, typically via a PID control loop. Presents the Regulator Role (requires the Settable affordance). Distinct from Controller (which supervises subordinate Assets without itself performing) and Sensor (which only reports): a TemperatureController performs by acting on the temperature. Graduated on the rule-of-three across Diamond i22 (Linkam), i03 (cryostream, thawer), and i11 (Cyberstar / Eurotherm blowers, Oxford cryostreams); cooling-vs-heating and PID-vs-other are a per-Asset settings or bound-Model difference, not a Family split. FlowController (the settable-setpoint mass-flow / pump actuator sibling that also presents Regulator) graduated alongside it." + - name: FlowController + note: "Continuous-setpoint flow / pump actuator Family: drives a fluid flow rate or a pump delivery (rate / volume) to a commanded setpoint. Presents the Regulator Role (requires the Settable affordance), the settable-actuator sibling of TemperatureController, distinct by what it actuates (mass flow / pump rate, not temperature); and distinct from Controller (which supervises subordinate Assets without performing) and Sensor (which only reports). One Family spans mass-flow controllers and syringe / peristaltic / HPLC pumps; mass-flow-vs-pump and the pump type are a per-Asset settings or bound-Model difference, not a Family split (the TemperatureController precedent). Graduated on the rule-of-three across Diamond i22 (the sample-environment pump), APS 7-BM (the Sierra Smart-Trak mass-flow controllers), NSLS-II LIX (the HPLC sample-delivery pump), and NSLS-II XFP (the footprinting sample-delivery pumps). The wider fluidic chain beyond the pump (selector valves, SEC columns, flow cells, fraction collectors) stays in the ControlPort seam pending its own rule-of-three (FLUID-1)." # Pending in code (documented, not yet defined): none. # future: OpticalRelay. diff --git a/deployments/7-bm/beamline.yaml b/deployments/7-bm/beamline.yaml index 68e57670318..f0c7d50240e 100644 --- a/deployments/7-bm/beamline.yaml +++ b/deployments/7-bm/beamline.yaml @@ -22,12 +22,14 @@ # - No z positions. The 7-BM docs carry no beam-layout table, so z_span_mm and # per-device z_mm are omitted rather than invented (contrast TomoWISE, whose # TDR gave z values). -# - No new catalog Families. The genuinely-new device anatomies (the chopper, the -# flow controllers, the point and energy-dispersive detectors) are bound to -# loose design-intent family names that render as plain text, exactly as -# TomoWISE bound HeatAbsorber / SlipRing; each is tagged with the open question -# that decides whether it is earned into the catalog or folds into an existing -# Family plus settings. +# - No new catalog Families minted here. The flow controllers bind the catalog +# FlowController Family (graduated across i22 / 7-BM / LIX / XFP; presents the +# Regulator Role, the settable-actuator sibling of TemperatureController). The +# remaining genuinely-new device anatomies (the chopper, the point and +# energy-dispersive detectors) are bound to loose design-intent family names that +# render as plain text, exactly as TomoWISE bound HeatAbsorber / SlipRing; each is +# tagged with the open question that decides whether it is earned into the catalog +# or folds into an existing Family plus settings. beamline: name: "7-BM" @@ -174,15 +176,17 @@ sample-environment: confirm: true note: "energy-dispersive-diffraction gauge-volume slits; two tungsten-carbide blocks 511 mm apart, curved for a 3 degree full scattering angle at 150 mm working distance (edd.rst)" - name: FlowController - family: FlowController + family: FlowController # catalog Family (graduated; settable flow/pump actuator, presents Regulator) new: true confirm: true note: > Sierra Smart-Trak mass-flow controllers (three units; Kr / N2 ranges) metering - process gas to the flow and combustion experiments. A SETTABLE actuator with a - commanded setpoint and a flow readback, unlike any 2-BM device. Whether CORA - commands the setpoint (versus reading it back only), and whether a FlowController - Family is earned versus deferred, are open (FLOW-1). + process gas to the flow and combustion experiments. Binds the catalog + FlowController Family (graduated; presents the Regulator Role), the settable-actuator + sibling of TemperatureController, earned across i22 / 7-BM / LIX / XFP. A settable + actuator with a commanded setpoint and a flow readback, unlike any 2-BM device. + What stays open (FLOW-1) is whether CORA commands the setpoint versus reading it + back only. # =========================================================================== # Detection: the multiple detector modalities 7-BM runs diff --git a/deployments/i22/beamline.yaml b/deployments/i22/beamline.yaml index 1dbbf704055..5071d2d37b4 100644 --- a/deployments/i22/beamline.yaml +++ b/deployments/i22/beamline.yaml @@ -23,11 +23,13 @@ # beam-path tier, and the technique/Capability binding. Each gap is tagged inline # with a (QUESTION-ID) answered on docs/deployments/i22/questions.md. # -# Loose families (StorageRing, FlowController) are design-intent names not in the -# catalog; they render as plain text. An adversarial new-kind review refuted all -# five proposed kinds on the strength of I22 alone; FluxMonitor, -# TemperatureController, and Transfocator have since graduated to the catalog on -# their rule-of-three, while these two stay loose and deferred. +# The loose StorageRing family is a design-intent name not in the catalog; it +# renders as plain text. An adversarial new-kind review refuted all five proposed +# kinds on the strength of I22 alone; FluxMonitor, TemperatureController, +# Transfocator, and FlowController have since graduated to the catalog on their +# rule-of-three, while StorageRing stays loose and deferred. FlowController is the +# settable flow/pump actuator catalog Family (presents Regulator), the +# TemperatureController sibling, earned across i22 / 7-BM / LIX / XFP. beamline: name: I22 @@ -189,9 +191,10 @@ sample-environment: The flux monitors present the existing Sensor Role (the Role docstring names ion chambers); they bind the FluxMonitor catalog Family, graduated on the i22/i03/i15-1 rule-of-three (FLUX-1). The Linkam binds the graduated - TemperatureController Family (presents Regulator); the pump is a loose - FlowController that would present Regulator once it graduates. What stays open - is whether CORA commands the setpoints (ENV-1). + TemperatureController Family (presents Regulator); the pump binds the catalog + FlowController Family (graduated; presents Regulator), the TemperatureController + sibling earned across i22 / 7-BM / LIX / XFP. What stays open is whether CORA + commands the setpoints (ENV-1). devices: - name: SampleBase family: LinearStage @@ -223,13 +226,13 @@ sample-environment: pv: "BL22I-EA-TEMPC-05:" new: true confirm: true - note: "sample-environment temperature controller (Linkam); a settable actuator binding the graduated TemperatureController Family (presents Regulator); the loose FlowController pump is its settable-actuator sibling (ENV-1)" + note: "sample-environment temperature controller (Linkam); a settable actuator binding the graduated TemperatureController Family (presents Regulator); the FlowController pump is its settable-actuator sibling, also a graduated catalog Family (ENV-1)" - name: SamplePump family: FlowController pv: "BL22I-EA-PUMP-01:" new: true confirm: true - note: "sample-environment peristaltic pump (Watson-Marlow 323); a settable actuator; pump type is a setting (ENV-1)" + note: "sample-environment peristaltic pump (Watson-Marlow 323); a settable actuator binding the catalog FlowController Family (graduated; presents Regulator); pump type is a setting (ENV-1)" # --- DETECTION STAGE: the SAXS and WAXS detectors and their beamstops --- diff --git a/deployments/lix/beamline.yaml b/deployments/lix/beamline.yaml index 525741fb1d2..64c564f8b8e 100644 --- a/deployments/lix/beamline.yaml +++ b/deployments/lix/beamline.yaml @@ -44,11 +44,11 @@ # loose BeamPositionMonitor (held under review, DIAG-1); the Zebra binds # TimingController. # -# THE ONE REUSE WORTH NAMING: the HPLC delivery pump binds the EXISTING loose -# FlowController Family ("settable flow / pump actuator", FLOW-1), the i22 + 7-BM -# precedent. LIX is its THIRD consumer, which fires the rule-of-three; the -# FlowController graduation is a separate gated decision, flagged here, not folded -# into this scaffold (FLUID-1, FLOW-1). The selector valves (the VICI and Aurora +# THE ONE REUSE WORTH NAMING: the HPLC delivery pump binds the catalog +# FlowController Family ("continuous-setpoint flow / pump actuator", presents the +# Regulator Role, the settable-actuator sibling of TemperatureController), which +# graduated on the rule-of-three across i22, 7-BM, LIX, and XFP. LIX simply reuses +# the graduated Family (FLUID-1, FLOW-1). The selector valves (the VICI and Aurora # buffer / column / detector valves) have no existing Family and are carried in the # fluidic-delivery seam, not coined (FLUID-1). # @@ -208,9 +208,9 @@ sample: rasters a cell or tissue sample on a SmarAct goniometer (Goniometer), with a rotation axis for tomography. The fast raster axes (scan.X / scan.Y) and the tomo rotation are Newport-XPS trajectory axes, the motion-controller seam (SCAN-1). The - HPLC delivery pump that drives the solution and SEC-SAXS flow binds the existing - loose FlowController Family (the i22 / 7-BM precedent); LIX is its third consumer - (FLUID-1, FLOW-1). The selector valves, the SEC column, the flow cell, the sample + HPLC delivery pump that drives the solution and SEC-SAXS flow binds the catalog + FlowController Family (graduated; presents Regulator, the i22 / 7-BM / LIX / XFP + earn) (FLUID-1, FLOW-1). The selector valves, the SEC column, the flow cell, the sample robot, and the buffers are the fluidic-delivery seam and the Subject / Supply / Procedure shape, not devices here (see controls, FLUID-1, SEC-1, ROBOT-1). devices: @@ -227,11 +227,11 @@ sample: confirm: true note: "the scanning-microbeam goniometer (a SmarAct stack: sample x / z, tilt x / z, and a rotation RX), used for cell / tissue mapping and, with the XPS rot.rY trajectory axis, for micro-tomography; the raster scan x / y are XPS trajectory axes (SCAN-1)" - name: DeliveryPump - family: FlowController # EXISTING loose Family (settable flow / pump actuator; n=3 with i22 + 7-BM; FLOW-1) + family: FlowController # catalog Family (graduated; settable flow/pump actuator, presents Regulator) pv: "XF:16IDC-ES{HPLC}REGEN:FLOWRATE" new: true confirm: true - note: "the HPLC sample-delivery pump driving the solution and SEC-SAXS flow (flowrate setpoint / readback, pressure, run / stop); the pcaspy soft-IOC XF:16IDC-ES{HPLC} fronts an Agilent quaternary pump (QUAT_PUMP:FLOWRATE, a .NET OpenLAB SDK on a Windows host) and a regeneration pump (REGEN:FLOWRATE, a raw TCP socket to a Moxa), both the same settable-flow anatomy and represented by this one Asset at this cut; reuses the existing loose FlowController Family, LIX its third consumer, the rule-of-three trigger flagged for a separate gated graduation (FLUID-1, FLOW-1)" + note: "the HPLC sample-delivery pump driving the solution and SEC-SAXS flow (flowrate setpoint / readback, pressure, run / stop); the pcaspy soft-IOC XF:16IDC-ES{HPLC} fronts an Agilent quaternary pump (QUAT_PUMP:FLOWRATE, a .NET OpenLAB SDK on a Windows host) and a regeneration pump (REGEN:FLOWRATE, a raw TCP socket to a Moxa), both the same settable-flow anatomy and represented by this one Asset at this cut; reuses the graduated FlowController Family (presents Regulator, earned across i22 / 7-BM / LIX / XFP) (FLUID-1, FLOW-1)" # =========================================================================== # DETECTION STAGE: the SAXS / WAXS Pilatus detectors, the fluorescence @@ -321,7 +321,7 @@ controls: # The fluidic-delivery chain that makes LIX a solution beamline is a heterogeneous # control plane, modelled the way MX3 modelled its non-EPICS devices: as the # ControlPort seam, the interface named and no EPICS PV where there is none. Only - # the HPLC delivery pump is promoted to a device (it binds the existing loose + # the HPLC delivery pump is promoted to a device (it binds the graduated catalog # FlowController Family, FLUID-1 / FLOW-1); the rest is the seam plus the Subject / # Supply / Procedure shape, not devices. software_iocs_not_modeled: diff --git a/deployments/xfp/beamline.yaml b/deployments/xfp/beamline.yaml index 3df19329449..55caf66bd7b 100644 --- a/deployments/xfp/beamline.yaml +++ b/deployments/xfp/beamline.yaml @@ -42,13 +42,14 @@ # 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. +# delivery pumps bind the graduated catalog 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 REUSE WORTH NAMING: the sample-delivery pumps bind the catalog FlowController +# Family (graduated; settable flow / pump actuator, presents the Regulator Role, the +# settable-actuator sibling of TemperatureController), bound by i22, 7-BM, and LIX. +# XFP is its FOURTH consumer; FlowController graduated on this rule-of-three across +# i22 / 7-BM / LIX / XFP. The wider fluidic chain beyond the pump stays in the +# ControlPort seam (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). @@ -183,8 +184,9 @@ sample: 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 + syringe / sample-delivery pumps bind the graduated catalog FlowController Family (the + i22 / 7-BM / LIX precedent); XFP is its fourth consumer, and FlowController graduated + on this rule-of-three (i22 / 7-BM / LIX / XFP). 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). @@ -208,11 +210,11 @@ sample: 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) + family: FlowController # catalog Family (graduated; settable flow/pump actuator, presents Regulator) 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)" + 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 graduated catalog FlowController Family (presents Regulator) and are folded into this one Asset at this cut, XFP its fourth consumer, with FlowController graduated on the i22 / 7-BM / LIX / XFP rule-of-three (FLUID-1 keeps the wider fluidic chain in the ControlPort seam)" # =========================================================================== # DETECTION STAGE: the flux / dose monitors. There is NO scattering / area / diff --git a/docs/architecture/modules/equipment/index.md b/docs/architecture/modules/equipment/index.md index b972d6fdc98..f2d3ae39544 100644 --- a/docs/architecture/modules/equipment/index.md +++ b/docs/architecture/modules/equipment/index.md @@ -160,7 +160,7 @@ Any field-replaceable, firmware-versioned active-control-electronics box gets a | `MotionController` | Stages, hexapods, sample motors | Aerotech Ensemble (`RotaryDrive`), Aerotech Hexapod drive, Aerotech 2bmbAERO drive, OMS VME58 a-station + b-station drives at 2-BM | | `TimingController` | Hardware timing signal generation (triggers, gates, sync pulses) | softGlueZynq FPGA (`Timing`) at 2-BM; further trigger sources to follow. Replaces the pre-rename `TriggerFPGA` candidate. Presents_as `Controller`, which carries `Pulsing`. | -Plausible siblings not yet modelled: `FlowController` (Bronkhorst mass flow), `PressureController` (MKS Baratron + PID), `DAQController` (Quantum Detectors Merlin, FPGA frame grabbers), `HVPSU` / `BiasController` (CAEN HV crate). The suffix comes last, matching the Family-naming rule above. (`TemperatureController` was such a candidate but has graduated as a catalog Family presenting the `Regulator` Role, not `Controller`: it performs rather than supervises, per the Controller-versus-Regulator note in the naming reference.) +Plausible siblings not yet modelled: `PressureController` (MKS Baratron + PID), `DAQController` (Quantum Detectors Merlin, FPGA frame grabbers), `HVPSU` / `BiasController` (CAEN HV crate). The suffix comes last, matching the Family-naming rule above. (`TemperatureController` and `FlowController` were such candidates but have graduated as catalog Families presenting the `Regulator` Role, not `Controller`: they perform rather than supervise, per the Controller-versus-Regulator note in the naming reference.) ### Function × anatomy matrix diff --git a/docs/deployments/7-bm/equipment/sample.md b/docs/deployments/7-bm/equipment/sample.md index 00ed8de1767..de223ad335f 100644 --- a/docs/deployments/7-bm/equipment/sample.md +++ b/docs/deployments/7-bm/equipment/sample.md @@ -22,11 +22,11 @@ This is the 7-BM-specific axis. Flow and combustion experiments draw on a compre | Device | Family | Notes (from the 7-BM docs) | | --- | --- | --- | -| `FlowController` | `FlowController` (loose) | Sierra Smart-Trak mass-flow controllers (three units, Kr and N2 ranges) metering process gas. A settable actuator with a commanded setpoint and a flow readback, unlike any 2-BM device | +| `FlowController` | `FlowController` (graduated; presents Regulator) | Sierra Smart-Trak mass-flow controllers (three units, Kr and N2 ranges) metering process gas. Binds the graduated catalog `FlowController` Family, the settable-actuator sibling of `TemperatureController`: a settable actuator with a commanded setpoint and a flow readback, unlike any 2-BM device | Two questions shape this part of the model: -- **Does CORA command the setpoints?** The flow controllers and the electronic air regulator are settable, not just readable. The settable-actuator *shape* is now settled: the `TemperatureController` graduation (the i11 rule-of-three) added the `Settable` affordance and the `Regulator` Role, which a `FlowController` would present. What stays open for 7-BM (FLOW-1) is whether CORA commands the setpoints (versus reading them back) and whether `FlowController` itself graduates: it is loose at only 7-BM and I22, short of its own rule-of-three. +- **Does CORA command the setpoints?** The flow controllers and the electronic air regulator are settable, not just readable. The settable-actuator *shape* is settled: the `FlowController` Family has now graduated into the catalog (the settable-actuator sibling of `TemperatureController`, presenting the `Regulator` Role with the `Settable` affordance), earned on the rule-of-three across Diamond i22, APS 7-BM, NSLS-II LIX, and NSLS-II XFP. What stays open for 7-BM (FLOW-1) is whether CORA commands the setpoints versus reading them back. - **Is there a combustion rig?** The compressed-air, gas, and vacuum infrastructure serves flow and combustion experiments, but whether an installed combustion, spray, or fuel-injection device exists (versus combustion being an intended use of the infrastructure) is unconfirmed (ENV-1). Until it is, no combustion-rig Asset is modelled; the specimen carries the hazard on its Subject. The flammable-gas, fuel-vapor, and oxygen-deficiency hazards this environment adds are governance, handled at the [APS Site](../../aps/index.md#the-safety-envelope) by clearances and operator Cautions; whether they need a workflow beyond the standard ESAF is HAZ-1 on [Governance](../governance.md). diff --git a/docs/deployments/7-bm/inventory.md b/docs/deployments/7-bm/inventory.md index 478972767d2..2201cd0fc6e 100644 --- a/docs/deployments/7-bm/inventory.md +++ b/docs/deployments/7-bm/inventory.md @@ -8,7 +8,7 @@ Devices bind to catalog [Families](../../catalog/families.md) where one fits. No ## The Asset tree -Root Asset `7-BM` (`tier = Unit`, `facility_code = aps`); sub-systems nest below by `parent_id`. The families in bold are loose design-intent names that are not in the catalog yet (they render as plain text); each is tagged with the open question that decides whether it is earned into the catalog or folds into an existing Family plus settings. +Root Asset `7-BM` (`tier = Unit`, `facility_code = aps`); sub-systems nest below by `parent_id`. The families in bold are loose design-intent names that are not in the catalog yet (they render as plain text); each is tagged with the open question that decides whether it is earned into the catalog or folds into an existing Family plus settings. `FlowController` is no longer among them: it is a graduated catalog Family (presents the Regulator Role, the settable-actuator sibling of TemperatureController). | Asset | Tier | Family | Notes (from the 7-BM docs) | | --- | --- | --- | --- | @@ -25,7 +25,7 @@ Root Asset `7-BM` (`tier = Unit`, `facility_code = aps`); sub-systems nest below | `TomographyRotation` | `Device` | RotaryStage | sample rotation; tomoScan-driven, as at 2-BM | | `SamplePositioning` | `Device` | LinearStage | sample centring and translation | | `EDDSlit` | `Device` | Slit | energy-dispersive-diffraction gauge slits | -| `FlowController` | `Device` | **FlowController** | Sierra Smart-Trak mass-flow controllers; settable actuator | +| `FlowController` | `Device` | FlowController | Sierra Smart-Trak mass-flow controllers; binds the graduated catalog `FlowController` Family (presents Regulator), the settable-actuator sibling of `TemperatureController` | | `Scintillator` | `Device` | Scintillator | for indirect x-ray imaging | | `TomographyCamera` | `Device` | Camera | area camera via visible optics | | `HighSpeedCamera` | `Device` | Camera | high-speed movie camera (Photron Nova S16) | @@ -33,7 +33,7 @@ Root Asset `7-BM` (`tier = Unit`, `facility_code = aps`); sub-systems nest below | `EnergyDispersiveSpectrometer` | `Device` | EnergyDispersiveSpectrometer | germanium energy-dispersive detector; presents the Sensor Role | | `Timing` | `Device` | TimingController | two DG645 generators plus softGlue; ring-sync and top-up inhibit | -Reused catalog Families (no new Family needed): `Beam`, `Shutter`, `Filter`, `Slit`, `Monochromator`, `Mirror`, `RotaryStage`, `LinearStage`, `Scintillator`, `Camera`, `TimingController`, and `EnergyDispersiveSpectrometer` (graduated once 2-ID and 7-BM shared it). The tomography path (scintillator plus visible optics plus area camera) is the same shape as 2-BM and could later compose the cross-facility `Microscope` Assembly. The three loose families (`Chopper`, `FlowController`, `Photodiode`) are bound by design intent and earned into the catalog only when a confirmed device and the naming review settle them; this mirrors how TomoWISE carried `HeatAbsorber` and `SlipRing`. +Reused catalog Families (no new Family needed): `Beam`, `Shutter`, `Filter`, `Slit`, `Monochromator`, `Mirror`, `RotaryStage`, `LinearStage`, `Scintillator`, `Camera`, `TimingController`, `EnergyDispersiveSpectrometer` (graduated once 2-ID and 7-BM shared it), and `FlowController` (graduated across i22 / 7-BM / LIX / XFP; presents the Regulator Role, the settable-actuator sibling of `TemperatureController`). The tomography path (scintillator plus visible optics plus area camera) is the same shape as 2-BM and could later compose the cross-facility `Microscope` Assembly. The two loose families (`Chopper`, `Photodiode`) are bound by design intent and earned into the catalog only when a confirmed device and the naming review settle them; this mirrors how TomoWISE carried `HeatAbsorber` and `SlipRing`. ## Pending confirmations diff --git a/docs/deployments/7-bm/model.md b/docs/deployments/7-bm/model.md index 8e6bad23060..b54abce1f1e 100644 --- a/docs/deployments/7-bm/model.md +++ b/docs/deployments/7-bm/model.md @@ -8,7 +8,7 @@ | --- | --- | --- | | Beamline descriptor | [`deployments/7-bm/beamline.yaml`](https://github.com/xmap/cora/blob/main/deployments/7-bm/beamline.yaml) | the device walk; source of the generated [Source](beamline.md) page | | Site descriptor | [`deployments/aps/site.yaml`](https://github.com/xmap/cora/blob/main/deployments/aps/site.yaml) | the APS facility surface, shared with 2-BM; 7-BM is added to its beamlines and Sector 7, with 7-BM Practices, Supplies, Clearances, and Cautions carried pending | -| Catalog Family | [`catalog/catalog.yaml`](https://github.com/xmap/cora/blob/main/catalog/catalog.yaml) | 7-BM reuses existing Families including `EnergyDispersiveSpectrometer` (graduated once 2-ID and 7-BM shared it); it carries three loose design-intent families (`Chopper`, `FlowController`, `Photodiode`) that render as plain text until earned | +| Catalog Family | [`catalog/catalog.yaml`](https://github.com/xmap/cora/blob/main/catalog/catalog.yaml) | 7-BM reuses existing Families including `EnergyDispersiveSpectrometer` (graduated once 2-ID and 7-BM shared it) and the graduated `FlowController` Family (presents the Regulator Role, the settable-actuator sibling of TemperatureController, earned across i22 / 7-BM / LIX / XFP); it carries two loose design-intent families (`Chopper`, `Photodiode`) that render as plain text until earned | | Catalog Method | [`catalog/catalog.yaml`](https://github.com/xmap/cora/blob/main/catalog/catalog.yaml) | tomography reuses the existing Methods; the high-speed-imaging, radiography, and EDD Methods are deferred until the techniques enter scope (TECH-1) | | Catalog Model | [`catalog/catalog.yaml`](https://github.com/xmap/cora/blob/main/catalog/catalog.yaml) | none bound; the 7-BM docs name vendors but no part is procured into the catalog | | Equipment Assets | not yet registered | the [Inventory](inventory.md) is the planned shape; no scenario registers 7-BM Assets yet | diff --git a/docs/deployments/7-bm/questions.md b/docs/deployments/7-bm/questions.md index 11bc77362aa..fa457bebf70 100644 --- a/docs/deployments/7-bm/questions.md +++ b/docs/deployments/7-bm/questions.md @@ -41,7 +41,7 @@ A note on what 7-BM tests that 2-BM did not: 7-BM is multi-technique (high-speed | ID | Priority | Question | CORA assumes | Resolves | | --- | --- | --- | --- | --- | -| FLOW-1 | Blocks-build | Must CORA command the gas-flow and compressed-air setpoints (the Sierra Smart-Trak controllers and the electronic air regulator), or only read them back, and is there a third settable sample-environment actuator? | A loose `FlowController` family presenting the now-earned `Regulator` Role (`Settable` affordance); the settable-actuator shape is settled, so what is open is whether CORA commands the setpoints and whether `FlowController` itself graduates (loose at 7-BM + I22, short of rule-of-three). | The command-vs-read decision and FlowController graduation. | +| FLOW-1 | Blocks-build | Must CORA command the gas-flow and compressed-air setpoints (the Sierra Smart-Trak controllers and the electronic air regulator), or only read them back, and is there a third settable sample-environment actuator? | The graduated catalog `FlowController` Family (presents the `Regulator` Role, `Settable` affordance), the settable-actuator sibling of `TemperatureController`, earned across i22 / 7-BM / LIX / XFP; the Family and the settable-actuator shape are settled, so what is open is only whether CORA commands the setpoints versus reading them back, and whether a third settable sample-environment actuator exists. | The command-vs-read decision. | | ENV-1 | Blocks-go-live | Is there an installed combustion, spray, or fuel-injection device at 7-BM, or is combustion an intended use served by the air, gas, and vacuum infrastructure? | No combustion rig Asset is modelled; combustion is served by the facility Supplies and bound to the specimen Subject. | Whether a combustion-rig Asset and a fuel-vapor Caution are modelled. | ## Controls and site diff --git a/docs/deployments/i10/equipment/sample.md b/docs/deployments/i10/equipment/sample.md index d136fdef9db..53ef9c94db5 100644 --- a/docs/deployments/i10/equipment/sample.md +++ b/docs/deployments/i10/equipment/sample.md @@ -50,7 +50,7 @@ The two magnet sample stages reuse `LinearStage`; the cryostat low-temperature e Two families on this page are loose, not catalog Families, and both are at their second sighting: `PolarizationAnalyzer` (the RASOR analysis arm, after 4-ID, POL-2) and `Magnet` (the i10-1 electromagnet and superconducting magnet, after 4-ID, MAG-1). Each was first seen at 4-ID and is carried as a loose family string here, bound to a real device so the modelling is honest about what the endstation does. -Neither graduates at i10. Graduation follows a rule-of-three across deployments, and a second sighting does not meet it; the hold-versus-graduate call is human, and i10 records a hold for both (POL-2, MAG-1). This mirrors how the fleet carries `StorageRing` and `FlowController` loose at i22 until a confirmed device and a naming review settle them. The loose annotation in the tables above marks exactly these two; everything else on this page reuses a catalog Family unchanged. +Neither graduates at i10. Graduation follows a rule-of-three across deployments, and a second sighting does not meet it; the hold-versus-graduate call is human, and i10 records a hold for both (POL-2, MAG-1). This mirrors how the fleet carries `StorageRing` loose at i22 until a confirmed device and a naming review settle it. The loose annotation in the tables above marks exactly these two; everything else on this page reuses a catalog Family unchanged. ## Why no new family here diff --git a/docs/deployments/i22/equipment/sample.md b/docs/deployments/i22/equipment/sample.md index de308a21923..9b71e815199 100644 --- a/docs/deployments/i22/equipment/sample.md +++ b/docs/deployments/i22/equipment/sample.md @@ -29,8 +29,8 @@ I22 sample-environment experiments use settable actuators, not just readbacks. | Device | Family | Control handle | Notes | | --- | --- | --- | --- | | `SampleTemperature` | `TemperatureController` | `BL22I-EA-TEMPC-05:` | Linkam temperature controller; a settable setpoint with a readback (the family has since graduated to the catalog, presenting `Regulator`) | -| `SamplePump` | `FlowController` (loose) | `BL22I-EA-PUMP-01:` | Watson-Marlow 323 peristaltic pump; a settable flow actuator | +| `SamplePump` | `FlowController` | `BL22I-EA-PUMP-01:` | Watson-Marlow 323 peristaltic pump; a settable flow actuator (the family has since graduated to the catalog, presenting `Regulator`) | -The settable-actuator shape these need is now earned. An adversarial review had found that `GenericProbe` (read-only) would mislabel the actuation, `Positioner` is spatial, and `Controller` acts only through subordinates; the fix was a settable-actuator affordance and Role, which landed in #350 as the `Settable` affordance and the `Regulator` Role. The Linkam binds the graduated `TemperatureController` catalog Family (presents `Regulator`); the pump is a loose `FlowController` that would present `Regulator` once it graduates (its own rule-of-three, the sibling of 7-BM's FLOW-1). What stays open is whether CORA commands the setpoints versus reading them back (ENV-1). +The settable-actuator shape these need is now earned. An adversarial review had found that `GenericProbe` (read-only) would mislabel the actuation, `Positioner` is spatial, and `Controller` acts only through subordinates; the fix was a settable-actuator affordance and Role, which landed in #350 as the `Settable` affordance and the `Regulator` Role. The Linkam binds the graduated `TemperatureController` catalog Family (presents `Regulator`); the pump binds the graduated `FlowController` catalog Family (presents `Regulator`), the `TemperatureController` sibling earned on its own rule-of-three across i22 / 7-BM / LIX / XFP. What stays open is whether CORA commands the setpoints versus reading them back (ENV-1). See [Open questions](../questions.md) for the confirmations still needed and [Inventory](../inventory.md) for the Asset tree. diff --git a/docs/deployments/i22/index.md b/docs/deployments/i22/index.md index 65dd355cfbd..60a82467a1f 100644 --- a/docs/deployments/i22/index.md +++ b/docs/deployments/i22/index.md @@ -23,7 +23,7 @@ The CORA pilots (2-BM, and the design-phase 7-BM / 19-BM / 32-ID / TomoWISE) are - **Quantitative flux, not just position.** Incident and transmitted ion chambers (I0 / It) read beam current for transmission and dose, presenting the Sensor Role the imaging camera path never needed. - **It carries real EPICS handles.** Unlike the TomoWISE scaffold (MAX IV Tango, PVs unknown), dodal records I22's real EPICS PV prefixes. So this scaffold carries `pv` on every device: the dry, correct controls fact is the whole point of the exercise. -What I22 does **not** force into the model: it earns no new catalog Family. dodal's device set maps onto existing Families (Camera, Mirror, Monochromator, InsertionDevice, Slit, BeamStop, LinearStage, TimingController), plus a handful of loose design-intent families an adversarial new-kind review deferred (see [Inventory](inventory.md)). +What I22 does **not** force into the model: it earns no new catalog Family. dodal's device set maps onto existing Families (Camera, Mirror, Monochromator, InsertionDevice, Slit, BeamStop, LinearStage, TimingController, plus the now-graduated TemperatureController, FluxMonitor, Transfocator, and FlowController), plus the loose `StorageRing` design-intent family an adversarial new-kind review deferred (see [Inventory](inventory.md)). ## The beamline diff --git a/docs/deployments/i22/inventory.md b/docs/deployments/i22/inventory.md index dbf554b0fe0..774e4034d65 100644 --- a/docs/deployments/i22/inventory.md +++ b/docs/deployments/i22/inventory.md @@ -27,13 +27,13 @@ Root Asset `I22` (`tier = Unit`, `facility_code = diamond`); sub-systems nest be | `I0` | FluxMonitor | `BL22I-EA-XBPM-02:` | incident-flux ion chamber; presents the Sensor Role | | `It` | FluxMonitor | `BL22I-EA-TTRM-02:` | transmitted-flux ion chamber; presents the Sensor Role | | `SampleTemperature` | TemperatureController | `BL22I-EA-TEMPC-05:` | Linkam temperature controller; settable actuator (now a catalog Family, presents Regulator) | -| `SamplePump` | **FlowController** | `BL22I-EA-PUMP-01:` | peristaltic pump; settable actuator | +| `SamplePump` | FlowController | `BL22I-EA-PUMP-01:` | peristaltic pump; settable actuator (a catalog Family, presents Regulator) | | `SaxsDetector` | Camera | `BL22I-EA-PILAT-01:` | Pilatus3 2M, 0.172 mm pixel, Si 0.45 mm (dodal) | | `WaxsDetector` | Camera | `BL22I-EA-PILAT-03:` | second Pilatus3 2M at short camera length | | `BeamStop1`..`BeamStop3` | BeamStop | `BL22I-MO-SAXSP-01:BSn:` | SAXS beamstops (positioned) | | `Panda1`, `Panda2` | TimingController | `BL22I-EA-PANDA-0N:` | PandABox FPGA trigger/gate generation | -Reused catalog Families (no new Family needed): `InsertionDevice`, `Monochromator`, `Mirror`, `Slit`, `LinearStage`, `Camera`, `BeamStop`, `TimingController`. An adversarial new-kind review refuted all five proposed new kinds (`StorageRing`, `Transfocator`, `FluxMonitor`, `TemperatureController`, `FlowController`) as catalog Families on the strength of I22 alone, deferring each as a loose design-intent family. Three have since graduated: `TemperatureController` reached the rule-of-three at i11 and is now a catalog Family presenting the `Regulator` Role (the Linkam here binds it), `FluxMonitor` reached it across i22/i03/i15-1 and is now a catalog Family presenting the Sensor Role (the I0 / It ion chambers here bind it), and `Transfocator` graduated as a catalog Family in its own right (a CRL focusing optic, distinct from `Mirror` / `ZonePlate` / `Condenser`; the transfocator here binds it). The remaining two (`StorageRing`, `FlowController`) stay loose, earned into the catalog only when a confirmed device and a rule-of-three settle them. This mirrors how 7-BM carries `Photodiode` / `FlowController` and TomoWISE carried `HeatAbsorber` / `SlipRing`. +Reused catalog Families (no new Family needed): `InsertionDevice`, `Monochromator`, `Mirror`, `Slit`, `LinearStage`, `Camera`, `BeamStop`, `TimingController`. An adversarial new-kind review refuted all five proposed new kinds (`StorageRing`, `Transfocator`, `FluxMonitor`, `TemperatureController`, `FlowController`) as catalog Families on the strength of I22 alone, deferring each as a loose design-intent family. Four have since graduated: `TemperatureController` reached the rule-of-three at i11 and is now a catalog Family presenting the `Regulator` Role (the Linkam here binds it), `FluxMonitor` reached it across i22/i03/i15-1 and is now a catalog Family presenting the Sensor Role (the I0 / It ion chambers here bind it), `Transfocator` graduated as a catalog Family in its own right (a CRL focusing optic, distinct from `Mirror` / `ZonePlate` / `Condenser`; the transfocator here binds it), and `FlowController` reached the rule-of-three across i22 / 7-BM / LIX / XFP and is now a catalog Family presenting the `Regulator` Role, the `TemperatureController` sibling (the peristaltic pump here binds it). The remaining one (`StorageRing`) stays loose, earned into the catalog only when a confirmed device and a rule-of-three settle it. This mirrors how 7-BM carries `Photodiode` loose and TomoWISE carried `HeatAbsorber` / `SlipRing`. ## Pending confirmations diff --git a/docs/deployments/i22/model.md b/docs/deployments/i22/model.md index 848606ca6b6..41cc92d2872 100644 --- a/docs/deployments/i22/model.md +++ b/docs/deployments/i22/model.md @@ -8,7 +8,7 @@ I22 is a documentation-and-descriptor scaffold: it exists as the descriptor and | --- | --- | --- | | Beamline descriptor | [`deployments/i22/beamline.yaml`](https://github.com/xmap/cora/blob/main/deployments/i22/beamline.yaml) | the device walk, with the dodal-derived EPICS PV handles; source of the generated [Source](beamline.md) page | | Site descriptor | [`deployments/diamond/site.yaml`](https://github.com/xmap/cora/blob/main/deployments/diamond/site.yaml) | the Diamond facility surface, the third Site; I22 practices, supplies, and the PSS clearance carried pending | -| Catalog Family | [`catalog/catalog.yaml`](https://github.com/xmap/cora/blob/main/catalog/catalog.yaml) | no new Family added by I22 itself; it reuses existing Families and carries the loose design-intent families (`StorageRing`, `FlowController`). `TemperatureController` (the Linkam) was carried loose here too but has since graduated to a catalog Family (presenting the `Regulator` Role) once it reached the rule-of-three at i11; `FluxMonitor` (the I0 / It ion chambers) likewise graduated, presenting the Sensor Role, on the i22/i03/i15-1 rule-of-three; `Transfocator` (the CRL focusing optic here) likewise graduated as a catalog Family in its own right, distinct from `Mirror` / `ZonePlate` / `Condenser` | +| Catalog Family | [`catalog/catalog.yaml`](https://github.com/xmap/cora/blob/main/catalog/catalog.yaml) | no new Family added by I22 itself; it reuses existing Families and carries the loose design-intent family (`StorageRing`). `TemperatureController` (the Linkam) was carried loose here too but has since graduated to a catalog Family (presenting the `Regulator` Role) once it reached the rule-of-three at i11; `FluxMonitor` (the I0 / It ion chambers) likewise graduated, presenting the Sensor Role, on the i22/i03/i15-1 rule-of-three; `Transfocator` (the CRL focusing optic here) likewise graduated as a catalog Family in its own right, distinct from `Mirror` / `ZonePlate` / `Condenser`; `FlowController` (the peristaltic pump here) likewise graduated as a catalog Family presenting the `Regulator` Role, the `TemperatureController` sibling, earned across i22 / 7-BM / LIX / XFP | | Catalog Capability / Method | [`catalog/catalog.yaml`](https://github.com/xmap/cora/blob/main/catalog/catalog.yaml) | none added; the SAXS / WAXS scattering Capabilities are new vocabulary deferred until the technique enters scope (TECH-1) | | Catalog Model | [`catalog/catalog.yaml`](https://github.com/xmap/cora/blob/main/catalog/catalog.yaml) | none bound; dodal names hardware but no part is procured into the catalog | | Equipment Assets | not yet registered | the [Inventory](inventory.md) is the planned shape; no scenario registers I22 Assets yet | @@ -16,7 +16,7 @@ I22 is a documentation-and-descriptor scaffold: it exists as the descriptor and ## What is deliberately not here yet -- **New catalog Families, Capabilities, and Methods.** I22 does not earn new catalog kinds in this scaffold. An adversarial new-kind review refuted all five proposed device anatomies as catalog Families on the strength of I22 alone; three (`TemperatureController`, `FluxMonitor`, `Transfocator`) have since graduated to the catalog once a rule-of-three across deployments settled them, and the remaining two (`StorageRing`, `FlowController`) are still carried as loose families with a tracking question. The new scattering Capabilities are carried as pending Practices. A kind is added to the catalog only when a confirmed device or technique and the naming review settle it. This follows the "pilots earn the abstractions" rule, and I22 is explicitly not a pilot (SCOPE-1). +- **New catalog Families, Capabilities, and Methods.** I22 does not earn new catalog kinds in this scaffold. An adversarial new-kind review refuted all five proposed device anatomies as catalog Families on the strength of I22 alone; four (`TemperatureController`, `FluxMonitor`, `Transfocator`, `FlowController`) have since graduated to the catalog once a rule-of-three across deployments settled them, and the remaining one (`StorageRing`) is still carried as a loose family with a tracking question. The new scattering Capabilities are carried as pending Practices. A kind is added to the catalog only when a confirmed device or technique and the naming review settle it. This follows the "pilots earn the abstractions" rule, and I22 is explicitly not a pilot (SCOPE-1). - **Integration scenarios.** No `test_i22_*.py` registers I22 Assets into the event store. Hard-registering a design-phase, off-roadmap beamline would commit speculative structure. - **Vendor Models.** No catalog Model is bound. The hardware dodal names (Dectris, AVT, Watson-Marlow, Linkam) is recorded in the descriptor notes, not bound. - **Operations and experiment views.** A runbook and live experiment view for an unmodelled beamline would be invention; see the note on the [index](index.md#not-yet-documented). diff --git a/docs/deployments/i22/questions.md b/docs/deployments/i22/questions.md index 8bcba548cd7..fb102929739 100644 --- a/docs/deployments/i22/questions.md +++ b/docs/deployments/i22/questions.md @@ -37,7 +37,7 @@ A note on what I22 tests that the tomography pilots did not: I22 is a SAXS/WAXS | ID | Priority | Question | CORA assumes | Resolves | | --- | --- | --- | --- | --- | | FLUX-1 | Blocks-go-live | How are the incident and transmitted ion chambers (I0 / It) modelled: a new `FluxMonitor` Family, or the existing Sensor Role with a deployment-local device? And is the incident-vs-transmitted distinction a placement setting? | The existing Sensor Role (whose docstring names ion chambers), now via the graduated `FluxMonitor` catalog Family (rule-of-three i22/i03/i15-1); incident vs transmitted is placement, not a Family split. | The flux-monitor modelling boundary. | -| ENV-1 | Blocks-go-live | Must CORA command the sample-environment setpoints (the Linkam temperature controller, the peristaltic pump), or only read them back? | The settable-actuator shape is now settled: the Linkam binds the graduated `TemperatureController` Family (presents `Regulator`, requires `Settable`); the pump is a loose `FlowController` that would present `Regulator` once it graduates. What is open is whether CORA commands the setpoints. | The command-vs-read decision (shared with 7-BM FLOW-1). | +| ENV-1 | Blocks-go-live | Must CORA command the sample-environment setpoints (the Linkam temperature controller, the peristaltic pump), or only read them back? | The settable-actuator shape is now settled: the Linkam binds the graduated `TemperatureController` Family (presents `Regulator`, requires `Settable`); the pump binds the graduated `FlowController` Family (presents `Regulator`, the `TemperatureController` sibling, earned across i22 / 7-BM / LIX / XFP). What is open is whether CORA commands the setpoints. | The command-vs-read decision (shared with 7-BM FLOW-1). | ## Techniques and identity diff --git a/docs/deployments/isr/equipment/sample.md b/docs/deployments/isr/equipment/sample.md index 57ce0e8cc50..4b9a01253a8 100644 --- a/docs/deployments/isr/equipment/sample.md +++ b/docs/deployments/isr/equipment/sample.md @@ -18,7 +18,7 @@ The IOC name (`Dif:ISD`) shows a diffractometer exists on the floor, but the sou ## The in-situ environment is absent -ISR's name promises in-situ studies (electrochemistry, gas, temperature, cryostat). The profile collection binds **none** of it: there is no temperature controller, no potentiostat / electrochemistry, no gas / flow controller, and no cryostat anywhere in the source. The in-situ sample environment is a stated mission with zero device representation in the public source, so it is a named open question, not modelled (`INSITU-1`). When it lands, the environments would reuse existing families and the seam (a `TemperatureController` for thermal, a loose `FlowController` for gas / flow, the LIX / XFP precedent), with the sample itself a Subject; none is invented here. +ISR's name promises in-situ studies (electrochemistry, gas, temperature, cryostat). The profile collection binds **none** of it: there is no temperature controller, no potentiostat / electrochemistry, no gas / flow controller, and no cryostat anywhere in the source. The in-situ sample environment is a stated mission with zero device representation in the public source, so it is a named open question, not modelled (`INSITU-1`). When it lands, the environments would reuse existing families and the seam (a `TemperatureController` for thermal, the graduated `FlowController` for gas / flow, the LIX / XFP precedent), with the sample itself a Subject; none is invented here. ## Resonant and polarization, deferred diff --git a/docs/deployments/isr/model.md b/docs/deployments/isr/model.md index e11de7ddbed..4567ba076da 100644 --- a/docs/deployments/isr/model.md +++ b/docs/deployments/isr/model.md @@ -36,7 +36,7 @@ ISR's science reuses two pending Methods rather than coining: `resonant_scatteri ## Deliberately not here yet - **The multi-circle diffractometer (`DIFF-1`).** Only `th` + `zeta` are bound under the `Dif:ISD` IOC; the orientation circles, the detector two-theta arm, and the reciprocal-space / hkl engine are absent from source and not invented. When they land, the sample side would be a `Goniometer` plus reciprocal-space `PseudoAxis` (the IXS six-circle / CSX TARDIS precedent), with a detector-arm `RotaryStage` / `LinearStage`. -- **The in-situ sample environment (`INSITU-1`).** No temperature / electrochemistry / gas / cryostat device is PV-bound. When it lands it reuses `TemperatureController` / the loose `FlowController` and the Subject / Supply / Procedure seam, not a new family. +- **The in-situ sample environment (`INSITU-1`).** No temperature / electrochemistry / gas / cryostat device is PV-bound. When it lands it reuses `TemperatureController` / the graduated `FlowController` and the Subject / Supply / Procedure seam, not a new family. - **The resonant energy axis and polarization analysis (`RESONANT-1`).** The energy axis is a non-functional stub; no polarization analyzer or phase retarder is bound. When wired, the energy axis is a `PseudoAxis` over the DCM and polarization hardware reuses the loose `PolarizationAnalyzer` / `PhaseRetarder` (4-ID). - **The flux monitors (`DET-1`).** The QuadEM electrometers and the secondary-source slit are defined but commented out in source; not modelled until live. - **The Methods.** Whether `resonant_scattering` and `diffraction` enter CORA's catalog is an owner decision; the Practices render unlinked, pending (`TECH-1`). diff --git a/docs/deployments/iss/equipment/sample.md b/docs/deployments/iss/equipment/sample.md index 6b7eb82f7bf..fa3a03b4743 100644 --- a/docs/deployments/iss/equipment/sample.md +++ b/docs/deployments/iss/equipment/sample.md @@ -17,4 +17,4 @@ The `SampleStage` reuses the `LinearStage` family (X / Y at `XF:08IDB-OP{Stage:S ## Sample environment -The `SampleTemperature` Lakeshore 331 reuses the `TemperatureController` family (graduated in #350). ISS's ion chambers are filled and purged through He / N2 mass-flow controllers (`XF:08IDB-OP{IC}FLW:`), and the beamline runs a range of in-situ sample environments; the fill-gas flow fits no catalog family cleanly (the loose FlowController) and, with the broader in-situ environment, is deferred to a named question (ENV-1) rather than modelled at this design phase. +The `SampleTemperature` Lakeshore 331 reuses the `TemperatureController` family (graduated in #350). ISS's ion chambers are filled and purged through He / N2 mass-flow controllers (`XF:08IDB-OP{IC}FLW:`), and the beamline runs a range of in-situ sample environments; the fill-gas flow would bind the graduated `FlowController` Family but, with the broader in-situ environment, is deferred to a named question (ENV-1) rather than modelled at this design phase. diff --git a/docs/deployments/iss/model.md b/docs/deployments/iss/model.md index fd7a5d44e2b..fe04554539a 100644 --- a/docs/deployments/iss/model.md +++ b/docs/deployments/iss/model.md @@ -25,5 +25,5 @@ This is a design-phase scaffold (descriptor + docs), mirroring the other NSLS-II - **No new loose Family.** ISS is otherwise a reuse deployment: the trajectory and high-resolution monochromators bind `Monochromator`, the mirrors `Mirror`, the filter box `Filter`, the slits `Slit`, the shutters `Shutter`, the energy axis `PseudoAxis`, the sample stage `LinearStage`, the goniometer `Goniometer`, the reference foil wheel `RotaryStage`, the thermal stage `TemperatureController`, the ion chambers `FluxMonitor`, the Xspress3 SDD `EnergyDispersiveSpectrometer`, the Pilatus `Camera`, the trajectory controller `MotionController`, the analog pizza box `TimingController`. - **The held `BeamPositionMonitor`.** The beam-position diagnostics bind the loose `BeamPositionMonitor` family that several deployments use; it stays loose pending the sensor fold-vs-promote decision (`DIAG-1`). - **No new Capability or Method.** EXAFS leans on the deferred `energy_scan` Capability (ENERGY-1, the BMM question; ISS strengthens it as a further consumer without forcing it); XES / HERFD reuse the `xas_spectroscopy` Method LCLS-MFX left pending, the second consumer (TECH-1). ISS records that one pending Practice and coins nothing. The per-technique reduction is `ComputePort` work. -- **The deferred in-situ environment.** The ion-chamber fill-gas mass-flow controllers (He / N2) and the broader in-situ sample environment fit no catalog family cleanly (the loose FlowController) and are named in a question (`ENV-1`) rather than modelled at this design phase. ISS models the main transmission / fluorescence / emission legs as the representative configuration. +- **The deferred in-situ environment.** The ion-chamber fill-gas mass-flow controllers (He / N2) would bind the graduated `FlowController` Family, but they and the broader in-situ sample environment are named in a question (`ENV-1`) rather than modelled at this design phase. ISS models the main transmission / fluorescence / emission legs as the representative configuration. - **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/iss/questions.md b/docs/deployments/iss/questions.md index e330d619414..7f6db2a40e4 100644 --- a/docs/deployments/iss/questions.md +++ b/docs/deployments/iss/questions.md @@ -25,7 +25,7 @@ Priorities: `Blocks-build`, `Blocks-go-live`, `Nice-to-have`. | SPEC-1 | Blocks-go-live | The Johann and von Hamos crystal emission spectrometer geometry: the analyzer crystal cut, the Rowland-circle radius, and whether each of the (Johann: main + four auxiliary) analyzer crystals is a child Asset or a setting on the one spectrometer Asset. | Two `EmissionSpectrometer` Assets (catalog Family, graduated at this 2nd sighting after LCLS-MFX); crystals as settings for now. | The emission-spectrometer model and analyzer-crystal composition. | | DET-1 | Blocks-go-live | The detector roster: the ion-chamber channel map (I0 / It / Ir / If through the ICAmplifier / Keithley-428 amps and the analog pizza box), the Xspress3 element count and ROI map, and which Pilatus serves which spectrometer. | The ion chambers, the 4-channel Xspress3, and one Pilatus modelled; channel maps blank. | The detector roster and channel maps. | | TEMP-1 | Nice-to-have | Which sample-environment thermal units are live (the Lakeshore 331 is in source; cryostat / furnace not). | One `TemperatureController` Asset; the others noted. | The sample-environment Assets. | -| ENV-1 | Nice-to-have | The ion-chamber fill-gas flow (He / N2 mass-flow controllers `XF:08IDB-OP{IC}FLW:`) and the broader in-situ sample environment. None fits a catalog family cleanly (the loose FlowController). | Deferred; fill gas and in-situ environment named here, not modelled. | The fill-gas and in-situ Assets. | +| ENV-1 | Nice-to-have | The ion-chamber fill-gas flow (He / N2 mass-flow controllers `XF:08IDB-OP{IC}FLW:`) and the broader in-situ sample environment. The mass-flow controllers would bind the graduated FlowController Family; the broader environment is deferred at this design phase. | Deferred; fill gas and in-situ environment named here, not modelled. | The fill-gas and in-situ Assets. | | DIAG-1 | Nice-to-have | The beam-position channel map (the Prosilica BPM cameras and the sample-positioner cameras) and the `BeamPositionMonitor` sensor fold-vs-promote hold. | Read-only beam-position (loose `BeamPositionMonitor`) probes; channel map blank. | The BeamPositionMonitor bindings. | ## Controls and technique scope diff --git a/docs/deployments/lix/equipment/controls.md b/docs/deployments/lix/equipment/controls.md index f459dab8b93..c0fd9c5a96e 100644 --- a/docs/deployments/lix/equipment/controls.md +++ b/docs/deployments/lix/equipment/controls.md @@ -16,7 +16,7 @@ This is the part that sets LIX apart, and CORA models it the way the [MX3](../.. | Fluidic element | Transport | How CORA models it | | --- | --- | --- | -| HPLC delivery pump (Agilent quaternary + regeneration) | the Agilent OpenLAB .NET SDK (Windows host) and a raw TCP socket to the Moxa, fronted by a pcaspy soft-IOC (`XF:16IDC-ES{HPLC}`) | the `DeliveryPump` device, binding the loose `FlowController` Family; LIX is its third consumer (`FLUID-1`, `FLOW-1`) | +| HPLC delivery pump (Agilent quaternary + regeneration) | the Agilent OpenLAB .NET SDK (Windows host) and a raw TCP socket to the Moxa, fronted by a pcaspy soft-IOC (`XF:16IDC-ES{HPLC}`) | the `DeliveryPump` device, binding the graduated catalog `FlowController` Family (presents Regulator; earned across i22 / 7-BM / LIX / XFP) (`FLUID-1`, `FLOW-1`) | | VICI selector valves (column / purge / detector) | Moxa TCP sockets, no EPICS | the ControlPort seam; N-position routers with no existing Family, not coined (`FLUID-1`) | | Aurora Pro buffer valve | serial over a Moxa socket, mirrored to the soft-IOC (`Buffer_VALVE_POS`) | the seam; the chosen position is observed via the soft-IOC (`FLUID-1`) | | SEC column and buffers | configuration / consumable | Supply consumables (`SEC-1`) | diff --git a/docs/deployments/lix/equipment/index.md b/docs/deployments/lix/equipment/index.md index 923b396b1fc..ac1a7ec7ef6 100644 --- a/docs/deployments/lix/equipment/index.md +++ b/docs/deployments/lix/equipment/index.md @@ -9,7 +9,7 @@ Along the beam, in order, sit the **stations**: the [Source](../beamline.md) tha ## Stations - [Source](../beamline.md): the storage-ring machine state read through a loose `StorageRing` (`MACHINE-1`), the in-vacuum undulator (`SRC-1`), the double-crystal monochromator (`MONO-1`), the white-beam and KB focusing mirrors (`OPT-1`), the mono slit and secondary-source aperture (`OPT-2`), the photon and fast shutters (`PSS-1`, `TRIG-1`), and in the endstation zone the compound refractive lens transfocator (`CRL-1`) and the guard slit (`OPT-2`). The incident energy is a pseudo-axis over the DCM Bragg angle and the undulator gap (`MONO-1`). -- [Sample](sample.md): the solution positioning stack (a `Manipulator`, `SAMPLE-1`) that places the flow cell; the scanning-microbeam goniometer (a `Goniometer`, `SCAN-1`) for cells and tissue; and the HPLC delivery pump (a loose `FlowController`, `FLUID-1`) that flows the solution and SEC peak through the cell. The selector valves, the SEC column, the flow cell, the sample robot, and the solution Subject are the fluidic-delivery seam and the Subject / Supply / Procedure shape (`FLUID-1`, `SEC-1`, `ROBOT-1`, `SUBJECT-1`). +- [Sample](sample.md): the solution positioning stack (a `Manipulator`, `SAMPLE-1`) that places the flow cell; the scanning-microbeam goniometer (a `Goniometer`, `SCAN-1`) for cells and tissue; and the HPLC delivery pump (the graduated `FlowController`, `FLUID-1`) that flows the solution and SEC peak through the cell. The selector valves, the SEC column, the flow cell, the sample robot, and the solution Subject are the fluidic-delivery seam and the Subject / Supply / Procedure shape (`FLUID-1`, `SEC-1`, `ROBOT-1`, `SUBJECT-1`). - [Detector](detector.md): the SAXS and WAXS Pilatus area detectors (`DET-1`), the scanning-mode fluorescence spectrometer (`DET-1`), the detector translations (`DET-1`), the SAXS beamstop (`DET-1`), and the endstation flux and beam-position monitors (`DET-1`, `DIAG-1`). The Zebra triggers the detectors (`TRIG-1`). ## Shared @@ -19,4 +19,4 @@ Along the beam, in order, sit the **stations**: the [Source](../beamline.md) tha ## 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=3. +- [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 graduated FlowController. diff --git a/docs/deployments/lix/equipment/sample.md b/docs/deployments/lix/equipment/sample.md index bef3a8eb756..3c99ea2ca79 100644 --- a/docs/deployments/lix/equipment/sample.md +++ b/docs/deployments/lix/equipment/sample.md @@ -10,7 +10,7 @@ This is where LIX is genuinely different from the rest of the scattering fleet, | --- | --- | --- | --- | | `SampleStage` | `Manipulator` | `XF:16IDC-ES:Scan{Ax:XC}` | the solution-mode positioning stack: a coarse x and a z pusher (EPICS) plus the fast scan x / y (XPS trajectory); it places the flow cell in the beam (`SAMPLE-1`) | | `ScanningGoniometer` | `Goniometer` | `XF:16IDC-ES:Scan2-Gonio{Ax:sX}` | the scanning-microbeam stack: sample x / z, tilts, a rotation, and (with the XPS rot.rY) micro-tomography of cells and tissue (`SCAN-1`) | -| `DeliveryPump` | `FlowController` (loose) | `XF:16IDC-ES{HPLC}REGEN:FLOWRATE` | the HPLC pump that flows the solution and SEC peak through the cell (`FLUID-1`, `FLOW-1`) | +| `DeliveryPump` | `FlowController` | `XF:16IDC-ES{HPLC}REGEN:FLOWRATE` | the HPLC pump that flows the solution and SEC peak through the cell; binds the graduated `FlowController` Family (`FLUID-1`, `FLOW-1`) | ## Placing the sample @@ -24,7 +24,7 @@ The **scanning-microbeam mode** uses the `ScanningGoniometer`, a SmarAct stack w The fluidic sample-delivery chain is what makes LIX a solution beamline, and it is the one genuinely-new axis this deployment brings. CORA models it the way the [MX3](../../mx3/index.md) deployment modelled its non-EPICS hardware: as a heterogeneous control plane, with the interface named and the actuators placed where they belong, not forced into device vocabulary they do not earn. -**The delivery pump is the one device.** The `DeliveryPump` drives the solution and SEC-SAXS flow: a flowrate setpoint and readback, a pressure readback, and run / stop. It is heterogeneous underneath, a pcaspy soft-IOC (`XF:16IDC-ES{HPLC}`) fronts an Agilent quaternary pump driven over the OpenLAB .NET SDK on a Windows host and a regeneration pump driven over a raw TCP socket to a Moxa terminal server, but its CORA-facing anatomy is a settable flow actuator presenting `Regulator`. That is exactly the existing loose `FlowController` Family, the one i22 and 7-BM already use. So the pump **reuses** `FlowController`; it coins nothing. LIX is its **third** consumer, which fires the rule-of-three (see [Model](../model.md#the-flowcontroller-rule-of-three)). +**The delivery pump is the one device.** The `DeliveryPump` drives the solution and SEC-SAXS flow: a flowrate setpoint and readback, a pressure readback, and run / stop. It is heterogeneous underneath, a pcaspy soft-IOC (`XF:16IDC-ES{HPLC}`) fronts an Agilent quaternary pump driven over the OpenLAB .NET SDK on a Windows host and a regeneration pump driven over a raw TCP socket to a Moxa terminal server, but its CORA-facing anatomy is a settable flow actuator presenting `Regulator`. That is exactly the graduated catalog `FlowController` Family, the settable-actuator sibling of `TemperatureController` that i22 and 7-BM also use. So the pump **reuses** the graduated `FlowController`; it coins nothing. LIX is one of the four consumers (i22, 7-BM, LIX, XFP) that earned the graduation (see [Model](../model.md#the-graduated-flowcontroller-family)). **The rest of the chain is the seam plus Subject / Supply / Procedure**, not devices: @@ -46,6 +46,6 @@ The sample-cell temperature controllers, an AccuThermo FTC100D and an SMC chille ## Why no new Family here -The positioning hardware reuses the catalog throughout: `Manipulator` for the solution stack, `Goniometer` for the scanning stage. The one fluidic device, the delivery pump, reuses the existing loose `FlowController` Family rather than coining a new one. The selector valves, the column, the flow cell, the robot, and the solution sample are deliberately not coined as device Families: they are the seam plus the Subject / Supply / Procedure shape, which is where a solution beamline's novelty belongs (`FLUID-1`, `SEC-1`, `ROBOT-1`, `SUBJECT-1`). Nothing here graduates and the catalog is unchanged. +The positioning hardware reuses the catalog throughout: `Manipulator` for the solution stack, `Goniometer` for the scanning stage. The one fluidic device, the delivery pump, reuses the graduated catalog `FlowController` Family rather than coining a new one. The selector valves, the column, the flow cell, the robot, and the solution sample are deliberately not coined as device Families: they are the seam plus the Subject / Supply / Procedure shape, which is where a solution beamline's novelty belongs (`FLUID-1`, `SEC-1`, `ROBOT-1`, `SUBJECT-1`). LIX coins no new Family here. -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. +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 graduated FlowController Family, and [the source walk](../beamline.md) for the PVs as read from the profile collection. diff --git a/docs/deployments/lix/index.md b/docs/deployments/lix/index.md index c05b4e38db4..37ffa76af73 100644 --- a/docs/deployments/lix/index.md +++ b/docs/deployments/lix/index.md @@ -24,7 +24,7 @@ LIX is the fleet's first **life-science solution-scattering** beamline. The spec - **The fluidic sample-delivery chain.** An HPLC delivery pump, selector valves, a size-exclusion column, buffers, and a flow cell move the sample into the beam in lockstep with the exposure. This is the fleet's first fluidic delivery plane, and it is heterogeneous: mostly non-EPICS (a Moxa terminal server, the Agilent OpenLAB .NET SDK, a pcaspy soft-IOC), the same shape the [MX3](../mx3/index.md) deployment established for non-EPICS hardware (`FLUID-1`). - **The SEC-SAXS Procedure.** Purge, equilibrate, inject, flow-during-exposure, and fraction: the run is a flow program correlated to the elution, a Procedure over the seam rather than a device (`FLUID-1`, `SEC-1`). -LIX coins **no new Family**, and the one reuse worth naming is the HPLC delivery pump, which binds the existing loose `FlowController` Family (its third consumer; see below). The catalog is otherwise unchanged. Frame the rest of these docs around the Subject and the delivery chain, and read the scattering itself as the fleet shape ported once more. +LIX coins **no new Family**, and the one reuse worth naming is the HPLC delivery pump, which binds the graduated catalog `FlowController` Family (one of the four consumers, i22 / 7-BM / LIX / XFP, that earned its graduation; see below). The catalog is otherwise unchanged. Frame the rest of these docs around the Subject and the delivery chain, and read the scattering itself as the fleet shape ported once more. ## Scope: what is and is not modelled @@ -33,8 +33,8 @@ LIX coins **no new Family**, and the one reuse worth naming is the HPLC delivery | Optics (`XF:16IDA`, `XF:16IDB`) | Yes | The undulator, the DCM and beam-energy axis, the white-beam and KB mirrors, the mono slit and secondary-source aperture, the photon and fast shutters (`ENC-1`) | | Endstation optics (`XF:16IDC`) | Yes | The compound refractive lens transfocator and the guard slit | | Endstation (`XF:16IDC`) | Yes | The solution positioning stack, the scanning-microbeam goniometer, the HPLC delivery pump, the SAXS / WAXS detectors, the fluorescence spectrometer, the detector stage, the beamstop, the flux and beam-position monitors, the Zebra trigger (`ENC-1`) | -| New device classes | None | Zero new Families coined; nothing graduates; the catalog is unchanged | -| The HPLC delivery pump | Loose `FlowController` | Reuses the existing flow / pump-actuator Family (i22 / 7-BM); LIX is its third consumer, the rule-of-three trigger (`FLUID-1`, `FLOW-1`) | +| New device classes | None | Zero new Families coined in this scaffold; the catalog is unchanged here | +| The HPLC delivery pump | Graduated `FlowController` | Binds the graduated catalog flow / pump-actuator Family (presents Regulator; earned across i22 / 7-BM / LIX / XFP) (`FLUID-1`, `FLOW-1`) | | Selector valves, SEC column, flow cell, sample robot | Seam + Subject / Supply / Procedure | The fluidic-routing valves are the ControlPort seam; the column and buffers are Supply; the robot is a Procedure; the solution is a Subject. None is a device Family (`FLUID-1`, `SEC-1`, `ROBOT-1`, `SUBJECT-1`) | | The attenuator and the cell temperature controllers | No (disabled in source) | The attenuator and both temperature controllers are commented out in the profile collection; not invented (`ATTN-1`, `TEMP-1`) | | Integration scenarios + vendor Models | No | Design-phase; the descriptor and docs come first | @@ -43,12 +43,12 @@ The deferred parts are recorded on [Model](model.md). ## Key modelling decisions -- **Reuse over coin.** Every device binds an existing catalog or loose Family, and the catalog changes nothing. The novelty lands on Subject, Supply, and Procedure, not on device vocabulary. +- **Reuse over coin.** Every device binds an existing catalog or loose Family, and this scaffold changes nothing in the catalog. The novelty lands on Subject, Supply, and Procedure, not on device vocabulary. - **16-ID is an undulator beamline, so it carries an `InsertionDevice`.** Unlike the bending-magnet [CMS](../cms/index.md), LIX has an in-vacuum undulator on the spine, observed alongside the loose `StorageRing`; the device model and period are carried pending (`SRC-1`, `MACHINE-1`). -- **The HPLC delivery pump reuses the loose `FlowController` Family.** A settable flow / pump actuator presenting `Regulator`, it binds the family i22 and 7-BM already use. LIX is its **third** consumer, which fires the rule-of-three; the `FlowController` graduation is a separate gated decision, flagged here, not folded into this scaffold (`FLUID-1`, `FLOW-1`). +- **The HPLC delivery pump reuses the graduated `FlowController` Family.** A settable flow / pump actuator presenting `Regulator`, it binds the catalog Family (the settable-actuator sibling of `TemperatureController`) that graduated on the rule-of-three across i22, 7-BM, LIX, and XFP. LIX is one of the four consumers that earned the graduation (`FLUID-1`, `FLOW-1`). - **The fluidic chain is the seam plus Subject / Supply / Procedure.** The selector valves (no existing Family) stay in the ControlPort seam; the SEC column and buffers are Supply consumables; the sample robot and autosampler are a Procedure over the spine with a Subject custody thread (the i03 / MX3 robot precedent); the liquid sample is a Subject. None is coined as a device Family (`FLUID-1`, `SEC-1`, `ROBOT-1`, `SUBJECT-1`). - **The compound refractive lens reuses the graduated `Transfocator`.** The Transfocator Family is well established across the fleet (the APS / Diamond CRLs and the NSLS-II siblings CHX / IXS / SMI / FMX); LIX adds another consumer, not a new abstraction (`CRL-1`). -- **Zero new Families coined, nothing graduates, the catalog is unchanged.** +- **Zero new Families coined in this scaffold; the catalog is unchanged here.** ## The beamline diff --git a/docs/deployments/lix/inventory.md b/docs/deployments/lix/inventory.md index e861916e0ef..207e3d6eee2 100644 --- a/docs/deployments/lix/inventory.md +++ b/docs/deployments/lix/inventory.md @@ -4,7 +4,7 @@ This cut models the XF:16IDA / XF:16IDB optics and the XF:16IDC solution / scanning endstation; the fluidic-delivery valves, the SEC column, the flow cell, the sample robot, and the disabled attenuator and temperature controllers 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/lix/beamline.yaml) descriptor. -Devices bind to a catalog [Family](../../catalog/families.md) wherever one fits. LIX coins **no new Family and changes nothing in the catalog**: the optics and detectors reuse the existing `InsertionDevice` / `Monochromator` / `Mirror` / `Slit` / `Transfocator` / `Camera` / `EnergyDispersiveSpectrometer` / `FluxMonitor` vocabulary, and the one reuse worth naming is the HPLC delivery pump, which binds the existing loose `FlowController` Family (its third consumer; see [Model](model.md#the-flowcontroller-rule-of-three)). The genuinely-new parts, the solution Subject and the fluidic delivery chain, land on Subject / Supply / Procedure and the seam, not on devices. Control handles are filled from the profile collection; no vendor Models are bound. +Devices bind to a catalog [Family](../../catalog/families.md) wherever one fits. LIX coins **no new Family and changes nothing in the catalog**: the optics and detectors reuse the existing `InsertionDevice` / `Monochromator` / `Mirror` / `Slit` / `Transfocator` / `Camera` / `EnergyDispersiveSpectrometer` / `FluxMonitor` vocabulary, and the one reuse worth naming is the HPLC delivery pump, which binds the graduated catalog `FlowController` Family (one of the four consumers, i22 / 7-BM / LIX / XFP, that earned its graduation; see [Model](model.md#the-graduated-flowcontroller-family)). The genuinely-new parts, the solution Subject and the fluidic delivery chain, land on Subject / Supply / Procedure and the seam, not on devices. Control handles are filled from the profile collection; no vendor Models are bound. ## The Asset tree @@ -28,7 +28,7 @@ Root Asset `LIX` (`tier = Unit`, `facility_code = nsls2`); sub-systems nest belo | `GuardSlit` | `Device` | Slit | lix-endstation | endstation guard slit, `XF:16IDC-OP{Slt:G2}` (OPT-2) | | `SampleStage` | `Device` | Manipulator | lix-endstation | solution positioning stack (x / z + XPS scan x / y), `XF:16IDC-ES:Scan` (SAMPLE-1) | | `ScanningGoniometer` | `Device` | Goniometer | lix-endstation | scanning-microbeam SmarAct gonio + tomo rotation, `XF:16IDC-ES:Scan2-Gonio` (SCAN-1) | -| `DeliveryPump` | `Device` | FlowController (loose) | lix-endstation | HPLC sample-delivery pump, `XF:16IDC-ES{HPLC}REGEN`; third consumer of the loose Family, rule-of-three trigger (FLUID-1, FLOW-1) | +| `DeliveryPump` | `Device` | FlowController | lix-endstation | HPLC sample-delivery pump, `XF:16IDC-ES{HPLC}REGEN`; binds the graduated FlowController Family (presents Regulator; earned across i22 / 7-BM / LIX / XFP) (FLUID-1, FLOW-1) | | `SaxsDetector` | `Device` | Camera | lix-endstation | Pilatus 1M small-angle detector, `XF:16IDC-DT{Det:SAXS}` (DET-1) | | `WaxsDetector` | `Device` | Camera | lix-endstation | Pilatus 900K wide-angle detector, `XF:16IDC-DT{Det:WAXS2}` (DET-1) | | `FluorescenceDetector` | `Device` | EnergyDispersiveSpectrometer | lix-endstation | Xspress3 fluorescence detector (scanning mode), `XF:16IDC-ES{Xsp:1}` (DET-1) | @@ -38,7 +38,7 @@ Root Asset `LIX` (`tier = Unit`, `facility_code = nsls2`); sub-systems nest belo | `BeamPositionMonitor` | `Device` | BeamPositionMonitor (loose) | lix-endstation | Best aggregator over the TetrAMM quadrants, `XF:16IDB-CT{Best}` (DIAG-1) | | `Trigger` | `Device` | TimingController | lix-endstation | Zebra trigger / position capture, `XF:16IDC-ES{Zeb:1}` (TRIG-1) | -Families reused from the catalog: `InsertionDevice`, `Monochromator`, `PseudoAxis`, `Mirror`, `Slit`, `Shutter`, `Transfocator`, `Manipulator`, `Goniometer`, `Camera`, `EnergyDispersiveSpectrometer`, `LinearStage`, `BeamStop`, `FluxMonitor`, `TimingController`. Loose families reused from siblings: `StorageRing` (supply), `FlowController` (the HPLC pump, n=3, graduation candidate), `BeamPositionMonitor` (held under review, DIAG-1). No new family is coined and nothing graduates. +Families reused from the catalog: `InsertionDevice`, `Monochromator`, `PseudoAxis`, `Mirror`, `Slit`, `Shutter`, `Transfocator`, `Manipulator`, `Goniometer`, `Camera`, `EnergyDispersiveSpectrometer`, `LinearStage`, `BeamStop`, `FluxMonitor`, `TimingController`, `FlowController` (the HPLC pump, graduated; presents Regulator). Loose families reused from siblings: `StorageRing` (supply), `BeamPositionMonitor` (held under review, DIAG-1). No new family is coined here. ## Pending confirmations diff --git a/docs/deployments/lix/model.md b/docs/deployments/lix/model.md index 12d746f919e..5aee3a3e663 100644 --- a/docs/deployments/lix/model.md +++ b/docs/deployments/lix/model.md @@ -9,7 +9,7 @@ LIX is a descriptor-and-docs scaffold today, reverse-engineered from the beamlin | Beamline descriptor | [`deployments/lix/beamline.yaml`](https://github.com/xmap/cora/blob/main/deployments/lix/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; `LIX` added to its beamline list, with solution-scattering / SEC-SAXS / scanning Practices | | Extraction provenance | [NSLS2/lix-profile-collection](https://github.com/NSLS2/lix-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 Family | [`catalog/catalog.yaml`](https://github.com/xmap/cora/blob/main/catalog/catalog.yaml) | none coined; every device reuses an existing catalog or loose Family (below), including the now-graduated `FlowController` | | Catalog Method | [`catalog/catalog.yaml`](https://github.com/xmap/cora/blob/main/catalog/catalog.yaml) | none added; `solution_scattering` is a new pending slug and `scanning_fluorescence_microscopy` is reused pending (`TECH-1`) | | Equipment Assets | not yet registered | the [Inventory](inventory.md) is the planned shape; no scenario registers LIX Assets yet | | Trust / governance | not yet instantiated | see [Governance](governance.md) | @@ -32,24 +32,24 @@ LIX coins no new Family and changes nothing in the catalog. - **The DCM binds `Monochromator`** (a silicon double-crystal optic, the energy law implies Si(111)); the incident energy is a `PseudoAxis` over its Bragg angle and the undulator gap. - **The optics and detectors all reuse:** the white-beam and KB mirrors bind `Mirror`; the slits bind `Slit`; the compound refractive lens binds the graduated `Transfocator`; the shutters bind `Shutter`; the solution positioning stack binds the graduated `Manipulator`; the scanning goniometer binds `Goniometer`; the Pilatus detectors bind `Camera`; the Xspress3 binds the graduated `EnergyDispersiveSpectrometer`; the detector translations bind `LinearStage`; the beamstop binds `BeamStop`; the TetrAMM electrometers bind `FluxMonitor`; the diamond-diode / Best beam-position monitor binds the loose `BeamPositionMonitor` (held under review, `DIAG-1`); the Zebra binds `TimingController`. -## The FlowController rule-of-three +## The graduated FlowController Family -The one reuse worth spelling out is the HPLC delivery pump. Its CORA-facing anatomy is a settable flow / pump actuator presenting `Regulator`: a flowrate setpoint and readback, a pressure readback, and run / stop. That is exactly the existing loose `FlowController` Family, staged at `FLOW-1` and already bound by i22 and 7-BM. So the pump **reuses** `FlowController`; it coins nothing. +The one reuse worth spelling out is the HPLC delivery pump. Its CORA-facing anatomy is a settable flow / pump actuator presenting `Regulator`: a flowrate setpoint and readback, a pressure readback, and run / stop. That is exactly the graduated catalog `FlowController` Family, the continuous-setpoint flow / pump actuator that presents `Regulator` and is the settable-actuator sibling of `TemperatureController`. So the pump **reuses** the graduated `FlowController`; it coins nothing. -LIX is `FlowController`'s **third** consumer (i22, 7-BM, LIX), which fires the rule-of-three. Per earn-the-abstraction, three independent consumers is the pressure that earns a graduation, and `FlowController` would graduate the way `TemperatureController` and `FluxMonitor` did: presenting the existing `Regulator` Role, so a YAML-and-docs change with no new Role or affordance. That graduation is a **separate gated decision**, not folded into this scaffold (it touches the i22 and 7-BM docs too, and a Family graduation gets its own gate-reviewed PR). LIX records the trigger: the `_PROMOTION_REVIEWED` note for `FlowController` is updated to n=3 / graduation-candidate, and the decision is flagged here for a follow-up (`FLUID-1`, `FLOW-1`). +`FlowController` graduated into the catalog on the rule-of-three across Diamond i22, APS 7-BM, NSLS-II LIX, and NSLS-II XFP, the same way `TemperatureController`, `FluxMonitor`, and `EmissionSpectrometer` did: presenting the existing `Regulator` Role, so a YAML-and-docs change with no new Role or affordance. LIX is one of the four consumers that earned the graduation, and it now simply **binds the catalog `FlowController` Family (graduated; presents `Regulator`)**. The wider fluidic chain stays deferred (`FLUID-1`, `FLOW-1`). ## How the fluidic chain is modelled (mostly not a device) The fluidic delivery chain is the novel axis, and only one piece of it is a device: -- the **delivery pump** is the `DeliveryPump`, binding the loose `FlowController` (above); +- the **delivery pump** is the `DeliveryPump`, binding the graduated `FlowController` (above); - the **selector valves** (VICI column / purge / detector, the Aurora buffer valve) are the ControlPort **seam**: discrete N-position routers over Moxa TCP sockets, with no existing Family, conducted over the seam and not coined at n=1 (`FLUID-1`); - the **SEC column and buffers** are **Supply** consumables (`SEC-1`); - the **flow cell** is sample environment, living in an external library (lixtools), not a catalog device here (`SEC-1`, `FLUID-1`); - the **sample robot and autosampler** are a **Procedure** over the spine plus a **Subject** custody thread, the i03 / MX3 robot precedent, not a device Family (`ROBOT-1`); - the **solution sample / eluting peak** is a **Subject** (`SUBJECT-1`). -This is the CORA-lens decision for a solution beamline: the experiment's identity lives in the Subject (which protein, which peak), the Supply (which column, which buffers), and the Procedure (the flow program), with the pump and valves as actuators conducted over the seam. Coining `Pump` and `Valve` device Families at n=1 would mint federation vocabulary one deployment cannot earn alone; the pump reuses an existing loose Family instead, and the valves stay in the seam pending a second fluidic beamline (`FLUID-1`). +This is the CORA-lens decision for a solution beamline: the experiment's identity lives in the Subject (which protein, which peak), the Supply (which column, which buffers), and the Procedure (the flow program), with the pump and valves as actuators conducted over the seam. Coining `Pump` and `Valve` device Families at n=1 would mint federation vocabulary one deployment cannot earn alone; the pump reuses the graduated `FlowController` Family instead, and the valves stay in the seam pending a second fluidic beamline (`FLUID-1`). ## Deliberately not here yet diff --git a/docs/deployments/lix/questions.md b/docs/deployments/lix/questions.md index 5fc59d0da05..f46576e42d8 100644 --- a/docs/deployments/lix/questions.md +++ b/docs/deployments/lix/questions.md @@ -28,7 +28,7 @@ LIX was reverse-engineered from the beamline's own bluesky profile collection ([ | --- | --- | --- | --- | --- | | SAMPLE-1 | Blocks-go-live | The solution-mode positioning stack axes (the coarse x and z pusher are EPICS; the scan x / y are Newport-XPS trajectory axes), and how the flow cell mounts on it. | A `Manipulator` for the positioning stack; the flow cell is the fluidic seam. | The solution-stage modelling. | | SCAN-1 | Blocks-go-live | The scanning-microbeam goniometer axes (the SmarAct stack), the fast raster axes (the XPS scan.X / scan.Y trajectory), and the tomo rotation (the XPS rot.rY). | A `Goniometer` for the SmarAct stack; the XPS trajectory axes carried as the motion-controller seam. | The scanning-stage modelling. | -| FLUID-1 | Blocks-go-live | The fluidic sample-delivery chain: the HPLC delivery pump (an Agilent quaternary pump over the .NET SDK plus a regeneration pump over a Moxa socket, fronted by the `XF:16IDC-ES{HPLC}` soft-IOC), the VICI and Aurora selector valves (Moxa TCP sockets, no EPICS), and whether the pump / valve actuators earn a Family. | The pump binds the existing loose `FlowController` (i22 / 7-BM, n=3, graduation candidate); the valves stay in the seam; no Valve Family coined. | The fluidic-delivery modelling; the CORA decisions are on [Model](model.md#deliberately-not-here-yet). | +| FLUID-1 | Blocks-go-live | The fluidic sample-delivery chain: the HPLC delivery pump (an Agilent quaternary pump over the .NET SDK plus a regeneration pump over a Moxa socket, fronted by the `XF:16IDC-ES{HPLC}` soft-IOC), the VICI and Aurora selector valves (Moxa TCP sockets, no EPICS), and whether the valve actuators earn a Family. | The pump binds the graduated catalog `FlowController` (presents Regulator; earned across i22 / 7-BM / LIX / XFP); the valves stay in the seam; no Valve Family coined. | The fluidic-delivery modelling; the CORA decisions are on [Model](model.md#deliberately-not-here-yet). | | SEC-1 | Nice-to-have | The size-exclusion column types, the buffers, the needle wash, and the X-ray flow cell (the flow cell lives in an external library, lixtools). | The column and buffers are Supply consumables; the flow cell is sample environment, not a device. | The consumable / flow-cell modelling. | | ROBOT-1 | Nice-to-have | The sample-handling robot (the `SW:` method soft-IOC, task-verb-driven) and the Agilent autosampler, and whether they earn a Family. | Modelled as a Procedure over the spine and a Subject custody thread, the i03 / MX3 robot precedent; no `SampleExchanger` Family coined. | The sample-handling modelling. | | SUBJECT-1 | Nice-to-have | The solution Subject: a buffer-borne macromolecule or an eluting SEC peak, with its own provenance, distinct from a solid mount. | A liquid Subject; the chromatographic peak as the acquisition axis for SEC-SAXS. | The Subject modelling. | diff --git a/docs/deployments/lix/techniques.md b/docs/deployments/lix/techniques.md index 45c45e6c0d0..9ee2ad45067 100644 --- a/docs/deployments/lix/techniques.md +++ b/docs/deployments/lix/techniques.md @@ -22,7 +22,7 @@ The matching Site Practices (`LIX_solution_scattering_practice`, `LIX_sec_saxs_p ## SEC-SAXS is a Procedure over the fluidic seam -In-line SEC-SAXS is the technique that most exercises the fluidic delivery chain, and CORA models it as a **Procedure**, not a new device. The run equilibrates the size-exclusion column, injects the sample, and reads SAXS frames continuously while the peak elutes through the [flow cell](equipment/sample.md). The actuators it drives, the [HPLC delivery pump](equipment/sample.md) (a `FlowController`) and the selector valves (the seam), are conducted over the `ControlPort`; the [column and buffers](equipment/sample.md) are Supply; the eluting peak is a Subject; the frames correlated to the elution are the Dataset. The technique's identity in CORA's record lives in the Subject, Supply, and Procedure, not in a device or a new detector (`FLUID-1`, `SEC-1`, `SUBJECT-1`). +In-line SEC-SAXS is the technique that most exercises the fluidic delivery chain, and CORA models it as a **Procedure**, not a new device. The run equilibrates the size-exclusion column, injects the sample, and reads SAXS frames continuously while the peak elutes through the [flow cell](equipment/sample.md). The actuators it drives, the [HPLC delivery pump](equipment/sample.md) (the graduated `FlowController`) and the selector valves (the seam), are conducted over the `ControlPort`; the [column and buffers](equipment/sample.md) are Supply; the eluting peak is a Subject; the frames correlated to the elution are the Dataset. The technique's identity in CORA's record lives in the Subject, Supply, and Procedure, not in a device or a new detector (`FLUID-1`, `SEC-1`, `SUBJECT-1`). ## Not modelled yet diff --git a/docs/deployments/xfp/equipment/index.md b/docs/deployments/xfp/equipment/index.md index 707034938c2..ee52cfd15eb 100644 --- a/docs/deployments/xfp/equipment/index.md +++ b/docs/deployments/xfp/equipment/index.md @@ -9,7 +9,7 @@ Unlike every other beamline in the fleet, the stations here do not end in a dete ## 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`). +- [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 (the graduated catalog `FlowController`, presents Regulator, `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 @@ -19,4 +19,4 @@ Unlike every other beamline in the fleet, the stations here do not end in a dete ## 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. +- [Inventory](../inventory.md): the full planned CORA Asset model (every device by `parent_id`, with Families and pending confirmations), including the remaining loose families and the graduated catalog `FlowController` (earned on the i22 / 7-BM / LIX / XFP rule-of-three). diff --git a/docs/deployments/xfp/equipment/sample.md b/docs/deployments/xfp/equipment/sample.md index 7dd10c0cbb8..ee784e4234c 100644 --- a/docs/deployments/xfp/equipment/sample.md +++ b/docs/deployments/xfp/equipment/sample.md @@ -11,7 +11,7 @@ XFP's sample side delivers a biological macromolecule in solution into the white | `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`) | +| `DeliveryPump` | `FlowController` (graduated; presents Regulator) | `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 @@ -23,7 +23,7 @@ The **high-throughput mode** uses the `HighThroughputStage` to position a 96-wel ## 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 `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 catalog `FlowController` Family that i22, 7-BM, and LIX already use. So the pump **reuses** `FlowController`; it coins nothing. XFP is its **fourth** consumer, and `FlowController` graduated into the catalog on this rule-of-three (i22 / 7-BM / [LIX](../../lix/model.md#the-graduated-flowcontroller-family) / XFP), presenting the `Regulator` Role, the settable-actuator sibling of `TemperatureController` (see [Model](../model.md#the-flowcontroller-rule-of-three)). ## The Subject and the sample-custody seam @@ -43,6 +43,6 @@ The only sample-environment readouts in the profile collection are temperature / ## 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. +The sample stages all reuse the catalog `LinearStage`. The one fluidic device, the delivery pump, reuses the graduated catalog `FlowController` Family (presents `Regulator`) rather than coining a new one; XFP's sighting is the fourth that graduated it (i22 / 7-BM / LIX / XFP). 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`). The wider fluidic chain beyond the pump stays in the `ControlPort` seam (`FLUID-1`). 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/index.md b/docs/deployments/xfp/index.md index f2e800032d3..f571e6819cc 100644 --- a/docs/deployments/xfp/index.md +++ b/docs/deployments/xfp/index.md @@ -25,7 +25,7 @@ That inverts the usual shape, and it is what makes XFP worth modelling: - **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). +XFP coins **no new Family**. 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 catalog `FlowController` Family (graduated; presents Regulator), with XFP its fourth consumer (see below). ## Scope: what is and is not modelled @@ -34,8 +34,8 @@ XFP coins **no new Family** and changes nothing in the catalog. The whole device | 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`) | +| New device classes | None | Zero new Families coined by XFP; the delivery pump reuses the graduated catalog `FlowController` | +| The sample-delivery pump | Catalog `FlowController` (graduated; presents Regulator) | Reuses the flow / pump-actuator Family (i22 / 7-BM / LIX); XFP is its fourth consumer, the rule-of-three FlowController graduated on (`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`) | @@ -48,9 +48,9 @@ The deferred parts are recorded on [Model](model.md). - **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 sample-delivery pump reuses the graduated catalog `FlowController`.** XFP is its **fourth** consumer (i22, 7-BM, LIX, XFP); `FlowController` graduated on this rule-of-three, presenting the `Regulator` Role (the settable-actuator sibling of `TemperatureController`). The wider fluidic chain beyond the pump stays in the `ControlPort` seam (`FLUID-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.** +- **Zero new Families coined by XFP; its delivery-pump sighting is the fourth that graduated the catalog `FlowController` Family (presents Regulator).** ## The beamline diff --git a/docs/deployments/xfp/inventory.md b/docs/deployments/xfp/inventory.md index 3de3186ea26..40f336fa211 100644 --- a/docs/deployments/xfp/inventory.md +++ b/docs/deployments/xfp/inventory.md @@ -4,7 +4,7 @@ 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. +Devices bind to a catalog [Family](../../catalog/families.md) wherever one fits. XFP coins **no new Family**: 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 catalog `FlowController` Family (graduated; presents Regulator), with XFP 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 @@ -24,11 +24,11 @@ Root Asset `XFP` (`tier = Unit`, `facility_code = nsls2`); sub-systems nest belo | `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) | +| `DeliveryPump` | `Device` | FlowController | xfp-endstation | sample-delivery syringe pump, `XF:17BMA-ES:1{Pmp:02}`; binds the graduated `FlowController` (presents Regulator), XFP its fourth 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). +Families reused from the catalog: `Mirror`, `Slit`, `Filter`, `Shutter`, `TimingController`, `LinearStage`, `FluxMonitor`, and `FlowController` (the delivery pump; graduated on the i22 / 7-BM / LIX / XFP rule-of-three, presents Regulator). Loose families reused from siblings: `StorageRing` (supply), `BeamPositionMonitor` (held under review, DIAG-1). No new family is coined here; the delivery pump reuses the graduated catalog `FlowController`. There is no Detector-role imaging device: the readout is offline (READOUT-1). ## Pending confirmations diff --git a/docs/deployments/xfp/model.md b/docs/deployments/xfp/model.md index 87ef9de017c..441bb9dcc82 100644 --- a/docs/deployments/xfp/model.md +++ b/docs/deployments/xfp/model.md @@ -9,7 +9,7 @@ XFP is a descriptor-and-docs scaffold today, reverse-engineered from the beamlin | 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 Family | [`catalog/catalog.yaml`](https://github.com/xmap/cora/blob/main/catalog/catalog.yaml) | every device reuses an existing catalog or loose Family (below); the delivery pump binds the catalog `FlowController` Family (graduated; presents Regulator) | | 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) | @@ -42,7 +42,7 @@ This is the deliberate inversion: where a measurement beamline's run is anchored ## 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`). +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 catalog `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), and `FlowController` has now **graduated** into the catalog on this rule-of-three: it presents the existing `Regulator` Role (the settable-actuator sibling of `TemperatureController`), earned across i22 / 7-BM / LIX / XFP, like `EmissionSpectrometer` and `TemperatureController` before it. The wider fluidic chain beyond the pump (selector valves, SEC columns, flow cells, fraction collectors) stays in the `ControlPort` seam pending its own rule-of-three (`FLUID-1`). ## Deliberately not here yet diff --git a/docs/deployments/xfp/questions.md b/docs/deployments/xfp/questions.md index b8183efb3b1..8f0b5c0ed1d 100644 --- a/docs/deployments/xfp/questions.md +++ b/docs/deployments/xfp/questions.md @@ -33,7 +33,7 @@ XFP was reverse-engineered from the beamline's own bluesky profile collection ([ | --- | --- | --- | --- | --- | | 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). | +| FLOW-1 | Nice-to-have | The sample-delivery pumps (an M50 pump and a PHD2000 infusion pump, both with rate / volume setpoints), which units are live, and the per-Asset pump detail. | The pump binds the graduated catalog `FlowController` (presents Regulator; earned on the i22 / 7-BM / LIX / XFP rule-of-three); the wider fluidic chain stays in the seam (`FLUID-1`). | 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. |