feat(catalog): graduate the FlowController Family (n=4 rule-of-three i22/7-BM/LIX/XFP)

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)",

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.
 

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

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 ---
 

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: