From 555ad4836d8cc8b0c32b3b202c48f1ad164df0a6 Mon Sep 17 00:00:00 2001 From: Doga Gursoy Date: Thu, 25 Jun 2026 20:04:13 +0300 Subject: [PATCH 1/2] feat(deployments): NSLS-II SST (soft+tender spectroscopy); graduate ElectronAnalyzer SST (Spectroscopy Soft and Tender, sector 7-ID) is the eleventh NSLS-II beamline and CORA's fourth soft X-ray deployment. Reverse-engineered from the config-driven SST profile collections (NSLS2/sst-rsoxs + sst-haxpes) and the NSLS-II-SST/sst-base library; every PV verified against source via a dedicated extraction pass, no vendor Models. SST is CORA's first config-driven extraction (devices.toml prefix + sst-base class suffix grammar, not startup/*.py), modelled as spine + the SST-1 soft / RSoXS branch + the SST-2 tender / HAXPES branch (UCAL TES microcalorimeter + VPPEM deferred): - GRADUATES ElectronAnalyzer into the catalog: the HAXPES Scienta SES is the 2nd hemispherical electron analyzer after ESM, earning the rule-of-three. ESM's references are swept loose -> graduated; removed from _ALLOWED_LOOSE_FAMILIES. Presents Detector, distinct from the photon detectors. naming-r3 done. - REUSES three graduated families: GratingMonochromator (soft PGM, 4th), Monochromator (tender Si DCM), Manipulator (RSoXS + HAXPES UHV manipulators, 3rd/4th). No new family. - RSoXS reuses resonant_scattering; HAXPES adds a new pending method xray_photoelectron_spectroscopy (distinct from ESM's angle_resolved_photoemission). Anti-fabrication: a verified-extraction workflow cited every PV to source and flagged the one unresolvable item (the full multi-channel I400 is not instantiated; only the single :IC1_MON channel is modelled, carried confirm). The config-driven traps (empty soft-PGM toml prefix -> hardcoded XF:07ID1-OP{Mono:PGM1; tender DCM XF:07ID6-OP{Mono:DCM1) are read from the sst-base library, not invented. Verified: 282 deployment guards green (graduation consistent: ElectronAnalyzer in catalog, ESM + SST bind it, removed from loose allowlist); mkdocs build --strict; ruff full-tree clean. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../deployments/test_beamline_descriptor.py | 1 - .../unit/deployments/test_site_descriptor.py | 1 + catalog/catalog.yaml | 2 + deployments/esm/beamline.yaml | 8 +- deployments/nsls2/site.yaml | 9 +- deployments/sst/beamline.yaml | 270 ++++++++++++++++++ docs/deployments/esm/equipment/detector.md | 6 +- docs/deployments/esm/equipment/index.md | 2 +- docs/deployments/esm/index.md | 2 +- docs/deployments/esm/inventory.md | 6 +- docs/deployments/esm/model.md | 4 +- docs/deployments/esm/questions.md | 2 +- docs/deployments/index.md | 1 + docs/deployments/sst/equipment/controls.md | 19 ++ docs/deployments/sst/equipment/detector.md | 26 ++ docs/deployments/sst/equipment/index.md | 22 ++ docs/deployments/sst/equipment/sample.md | 24 ++ docs/deployments/sst/governance.md | 11 + docs/deployments/sst/index.md | 66 +++++ docs/deployments/sst/inventory.md | 47 +++ docs/deployments/sst/model.md | 42 +++ docs/deployments/sst/questions.md | 35 +++ docs/deployments/sst/techniques.md | 29 ++ mkdocs.yml | 13 + 24 files changed, 630 insertions(+), 18 deletions(-) create mode 100644 deployments/sst/beamline.yaml create mode 100644 docs/deployments/sst/equipment/controls.md create mode 100644 docs/deployments/sst/equipment/detector.md create mode 100644 docs/deployments/sst/equipment/index.md create mode 100644 docs/deployments/sst/equipment/sample.md create mode 100644 docs/deployments/sst/governance.md create mode 100644 docs/deployments/sst/index.md create mode 100644 docs/deployments/sst/inventory.md create mode 100644 docs/deployments/sst/model.md create mode 100644 docs/deployments/sst/questions.md create mode 100644 docs/deployments/sst/techniques.md diff --git a/apps/api/tests/unit/deployments/test_beamline_descriptor.py b/apps/api/tests/unit/deployments/test_beamline_descriptor.py index 2d3abb618e..a5e95d69f8 100644 --- a/apps/api/tests/unit/deployments/test_beamline_descriptor.py +++ b/apps/api/tests/unit/deployments/test_beamline_descriptor.py @@ -385,7 +385,6 @@ def test_no_unexpected_orphan_catalog_models() -> None: "Rheometer": "staged: rheometer shear-cell (8-ID); rule-of-three open (SAMPLE-1)", "FlightPath": "staged: evacuated XPCS flight path (8-ID); rule-of-three open (XPCS-2)", "SpectrometerArm": "staged: energy-dispersive RIXS arm (SIX); no point-Sensor fit (RIXS-1)", - "ElectronAnalyzer": "staged: electron energy analyzer (ESM); not a photon detector (ARPES-1)", "EnergyAnalyzer": "staged: IXS diced crystal energy analyzer; n=1 (ANALYZER-1)", } diff --git a/apps/api/tests/unit/deployments/test_site_descriptor.py b/apps/api/tests/unit/deployments/test_site_descriptor.py index ee3990adf8..9d691a2c83 100644 --- a/apps/api/tests/unit/deployments/test_site_descriptor.py +++ b/apps/api/tests/unit/deployments/test_site_descriptor.py @@ -258,6 +258,7 @@ def test_practice_method_links_only_known() -> None: "resonant_inelastic_scattering": "SIX RIXS; soft X-ray, not yet in pilot scope (TECH-1)", "inelastic_x_ray_scattering": "IXS hard X-ray inelastic scattering; not in scope (TECH-1)", "angle_resolved_photoemission": "ESM ARPES; photoemission, not yet in pilot scope (TECH-1)", + "xray_photoelectron_spectroscopy": "SST HAXPES tender photoemission; not in scope (TECH-1)", "grid_scan": "i03 MX fast grid scan; portable Method not yet earned", "mx_data_collection": "i03 MX rotation data collection; Method not yet earned", "sample_exchange": "i03 autonomous robotic sample exchange; Method not yet earned", diff --git a/catalog/catalog.yaml b/catalog/catalog.yaml index faf6327d45..35f9bec5af 100644 --- a/catalog/catalog.yaml +++ b/catalog/catalog.yaml @@ -108,6 +108,8 @@ families: note: "Multi-axis sample-orientation goniometer Family: omega / chi / phi rotation plus the x / y / z sample-centring translations, with centre-of-rotation control. The MX micro-goniometer. Distinct from RotaryStage (a single tomographic rotation axis that carries PSO fly-scan Following / Marking, which the goniometer does not) and from TiltStage (a limited-range tilt with no primary rotation axis); the discriminator is the multi-axis crystal-orientation role. Graduated from pending on i03 (the Smargon), CORA's first canonical-goniometer deployment; chi-vs-kappa and axis-count are a per-Asset settings or bound-Model difference, not a Family split (the InsertionDevice / Table precedent). The composed multi-stage scattering diffractometer (4-ID / 8-ID, the Diffractometer Assembly) binds one Goniometer Asset for its sample-orientation circles." - name: Manipulator note: "Ultra-high-vacuum multi-axis sample manipulator Family: a serial stack of translations and rotations that positions a sample inside a UHV chamber, typically with cryogenic cooling. Distinct from Hexapod (a parallel-kinematic six-strut positioner), from Goniometer (the crystal-orientation circles for diffraction), and from a plain LinearStage / RotaryStage (a single in-air motion axis); the discriminator is the UHV serial-stack sample-environment role. Earned in once two deployments shared it, the soft X-ray beamlines SIX (NSLS-II 2-ID, the cryostat x/y/z/theta manipulator) and ESM (NSLS-II 21-ID, the LT six-axis cryo manipulator x/y/z/Rx/Ry/Rz); axis count, cryo range, and load-lock transfer are a per-Asset settings or bound-Model difference, not a Family split (the InsertionDevice / Goniometer precedent)." + - name: ElectronAnalyzer + note: "Hemispherical electron energy analyzer Family: a photoemission spectrometer that disperses photoelectrons by kinetic energy (and, in angle-resolved mode, emission angle) over a window set by the pass energy and lens mode. Presents the Detector Role (it acquires the spectrum), but distinct from the photon detectors (Camera, the energy-dispersive Sensor families): it measures electrons out, not photons. Earned in once two deployments shared it, the soft / tender X-ray photoemission beamlines ESM (NSLS-II 21-ID, the ARPES Scienta SES) and SST (NSLS-II 7-ID, the HAXPES Scienta SES); analyzer model, lens-mode set, and pass-energy range are a per-Asset settings or bound-Model difference, not a Family split (the InsertionDevice / Manipulator precedent). The photoemission electron microscope (LEEM / PEEM) is a distinct imaging instrument, deferred (PEEM-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." # Pending in code (documented, not yet defined): none. diff --git a/deployments/esm/beamline.yaml b/deployments/esm/beamline.yaml index 975463f8b4..d41304077a 100644 --- a/deployments/esm/beamline.yaml +++ b/deployments/esm/beamline.yaml @@ -15,8 +15,8 @@ # # ESM is the FIRST PHOTOEMISSION deployment: it measures photon-in / electron-out, # so the detector is a hemispherical ELECTRON ENERGY ANALYZER (Scienta SES), a regime -# no prior CORA beamline modelled. The analyzer binds a new loose ElectronAnalyzer -# Family at n=1 (presents Detector); a second ARPES beamline must earn it. +# no prior CORA beamline modelled. The analyzer binds the ElectronAnalyzer Family, +# which GRADUATED once SST (NSLS-II 7-ID HAXPES) earned the 2nd Scienta SES (presents Detector). # # CONSOLIDATION: ESM is the 3rd soft X-ray PGM (after SIX + CSX), reusing the catalog # GratingMonochromator Family; and the 2nd UHV sample manipulator (after SIX), which @@ -239,11 +239,11 @@ detectors: SES is the Scienta hemispherical electron energy analyzer: the ARPES detector, photon-in / electron-out, recording electron counts over a kinetic-energy x emission-angle window set by the pass energy and lens mode. It binds a NEW loose - ElectronAnalyzer Family at n=1 (presents Detector; no photon-detector Family fits; + ElectronAnalyzer Family (graduated across ESM + SST; presents Detector; no photon-detector Family fits; ARPES-1). The QuadEM electrometers are the I0 / drain-current flux monitors. devices: - name: ElectronAnalyzer - family: ElectronAnalyzer # loose Family (n=1; hemispherical electron energy analyzer; ARPES-1) + family: ElectronAnalyzer # catalog Family (graduated ESM + SST; hemispherical electron energy analyzer) pv: "XF21ID1-ES-SES" new: true confirm: true diff --git a/deployments/nsls2/site.yaml b/deployments/nsls2/site.yaml index 8d683f8ef5..85778a2e7a 100644 --- a/deployments/nsls2/site.yaml +++ b/deployments/nsls2/site.yaml @@ -1,7 +1,7 @@ # CORA Site descriptor: the NSLS-II site-level surface # # NSLS-II (National Synchrotron Light Source II, Brookhaven National Laboratory) -# is a Site CORA models, the home of the FXI, HXN, BMM, SRX, SIX, CHX, CSX, XPD, ESM, and SMI beamlines. This file is +# is a Site CORA models, the home of the FXI, HXN, BMM, SRX, SIX, CHX, CSX, XPD, ESM, SMI, IXS, and SST beamlines. This file is # the single human-readable source for the facility's site-level instances: the # Facility itself, the Practices it would run, and the facility principals. # @@ -24,7 +24,7 @@ facility: heading: "NSLS-II" kind: Site institution: Brookhaven National Laboratory - beamlines: [FXI, HXN, BMM, SRX, SIX, CHX, CSX, XPD, ESM, SMI, IXS] + beamlines: [FXI, HXN, BMM, SRX, SIX, CHX, CSX, XPD, ESM, SMI, IXS, SST] # ISA-88 Site Recipes: the facility-adapted form of a catalog Method. All pending # because they are reverse-engineered from the FXI profile collection, not yet @@ -65,6 +65,11 @@ practices: # technique new to the catalog; rendered pending until a technique enters scope # (TECH-1). The XPEEM/LEEM branch is deferred (see esm/model.md). - {name: ESM_arpes_practice, method: angle_resolved_photoemission, pending: true, note: "angle-resolved photoemission on the hemispherical electron analyzer; Method not yet in catalog (TECH-1)"} + # SST (7-ID) runs RSoXS on the soft branch (reuses the 4-ID resonant_scattering + # Method) and HAXPES on the tender branch (a new pending photoemission Method, + # distinct from ESM's angle-resolved variant). Both pending until scope (TECH-1). + - {name: SST_rsoxs_practice, method: resonant_scattering, pending: true, note: "resonant soft X-ray scattering on the SST-1 RSoXS endstation; reuses the 4-ID resonant_scattering Method (TECH-1)"} + - {name: SST_haxpes_practice, method: xray_photoelectron_spectroscopy, pending: true, note: "hard / tender X-ray photoelectron spectroscopy on the SST-2 HAXPES Scienta SES analyzer; Method not yet in catalog (TECH-1)"} # SMI's defining techniques (SAXS / WAXS / GISAXS) sit on the deferred scattering # Capabilities that Diamond i22 left pending (TECH-1); simultaneous SAXS+WAXS is # coordinated Runs not a new technique. No SMI Practice is recorded until those diff --git a/deployments/sst/beamline.yaml b/deployments/sst/beamline.yaml new file mode 100644 index 0000000000..3f482c4da1 --- /dev/null +++ b/deployments/sst/beamline.yaml @@ -0,0 +1,270 @@ +# SST beamline descriptor (NSLS-II), reverse-engineered +# +# SST (Spectroscopy Soft and Tender) is the NSLS-II soft + tender X-ray spectroscopy +# beamline at sector 7-ID. It has two branches off a shared front end: SST-1 (soft, +# a plane-grating monochromator) and SST-2 (tender, a Si double-crystal mono). It is +# bound to the NSLS-II Site (deployments/nsls2/site.yaml), the tenth NSLS-II beamline +# and CORA's fourth soft X-ray deployment. +# +# STATUS: reverse-engineered, design-phase. Every value is read from public open +# source and carried `new: true` + `confirm: true` pending SST staff. SST is the +# config-driven extraction mode: device instances live in the +# NSLS2/-profile-collection/startup/devices.toml files and the per-axis +# PV grammar in the NSLS-II-SST/sst-base + NSLS-II-SST/haxpes pip libraries; the PVs +# below are the toml prefix combined with the class Cpt suffixes, each verified +# against a source line. No vendor Models bound. +# +# SCOPE: the shared front end + the SST-1 soft PGM + the RSoXS endstation, and the +# SST-2 tender DCM + the HAXPES endstation. CONSOLIDATION: SST is the 4th soft X-ray +# PGM (reuses the catalog GratingMonochromator) and the 3rd UHV manipulator (reuses +# Manipulator); its tender DCM reuses Monochromator. It GRADUATES the ElectronAnalyzer +# Family: the HAXPES Scienta SES is the 2nd hemispherical electron analyzer after ESM, +# earning it into the catalog (ESM's references are swept loose -> graduated this PR). +# +# DELIBERATELY OUT OF THIS CUT (recorded on docs/deployments/sst/model.md): the UCAL / +# NEXAFS TES microcalorimeter endstation; the VPPEM photoemission microscope; the +# secondary flux diagnostics and screen cameras. The I400 ion chamber is modelled as +# its single instantiated channel only (the multi-channel device is not in the profile). +# +# Items left open are tagged inline with a (QUESTION-ID) answered on +# docs/deployments/sst/questions.md. + +beamline: + name: SST + facility: nsls2 # NSLS-II Site (facility_code: nsls2) + sector: "Sector 7" # PV namespace XF:07ID* + tier: Unit + parent: null + source: insertion-device + source_confirm: "two EPUs on the SR:C07-ID straight: EPU60 feeds SST-1 soft (SR:C07-ID:G1A{SST1:1), a U42 feeds SST-2 tender (SR:C07-ID:G1A{SST2:1); periods + polarization are SRC-1" + +# PV zones: XF:07IDA (shared front-end optics), XF:07ID1 / XF:07ID2 (the SST-1 soft +# branch + RSoXS endstation + shared diagnostics), XF:07ID6 / XF:07ID-ES (the SST-2 +# tender branch + HAXPES endstation). Whether each is a separate shielded hutch, and +# the PSS permit leaves, are open (ENC-1, PSS-1). +enclosures: + - name: 7-ID-A + role: optics-hutch + facility_code: nsls2 + permit_signal: {confirm: "PSS permit leaf not in source; front-end shutter XF:07ID-PPS{Sh:FE}, photon shutters XF:07IDA-PPS{PSh:4/7/10} (PSS-1)"} + - name: SST-1 + role: experiment-hutch + facility_code: nsls2 + permit_signal: {confirm: "PSS permit leaf unknown; the soft branch + RSoXS endstation (XF:07ID1 / XF:07ID2); hutch grouping is ENC-1"} + - name: SST-2 + role: experiment-hutch + facility_code: nsls2 + permit_signal: {confirm: "PSS permit leaf unknown; the tender branch + HAXPES endstation (XF:07ID6 / XF:07ID-ES); hutch grouping is ENC-1"} + +# =========================================================================== +# SOURCE STAGE: the EPUs, the shared front-end optics, and the two monochromators +# =========================================================================== + +insertion-devices: + stage: source + enclosure: 7-ID-A + intro: "The two elliptically-polarizing undulators feeding the soft and tender branches." + note: "Two InsertionDevice Assets; each adds a polarization (phase) axis beyond gap, carried as a setting. The EPU PVs are hardcoded in the sst-base EnergySoft/EnergyTender classes, not the devices.toml (SRC-1)." + devices: + - name: Undulator_Soft + family: InsertionDevice + pv: "SR:C07-ID:G1A{SST1:1" + new: true + confirm: true + note: "EPU60 feeding the SST-1 soft branch (gap + phase); period and polarization model are SRC-1" + - name: Undulator_Tender + family: InsertionDevice + pv: "SR:C07-ID:G1A{SST2:1" + new: true + confirm: true + note: "U42 undulator feeding the SST-2 tender branch (gap); coupled to the DCM energy (SRC-1)" + +front-end-optics: + stage: source + enclosure: 7-ID-A + intro: "The shared front-end mirror, the quad slit, and the front-end / photon shutters." + note: "M1 is the front-end FMB hexapod mirror; the FOE quad slits define the shared beam (OPT-1, OPT-2)." + devices: + - name: Mirror_1 + family: Mirror + pv: "XF:07IDA-OP{Mir:M1" + new: true + confirm: true + note: "shared front-end FMB hexapod mirror M1 (x/y/z/pitch/yaw/roll axes -Ax:*}Mtr_MON; OPT-1)" + - name: FrontEndSlit + family: Slit + pv: "XF:07IDA-OP{Slt:01-Ax:" + new: true + confirm: true + note: "FOE FMBO quad slit (top/bottom/inboard/outboard blades; OPT-2)" + - name: FrontEndShutter + family: Shutter + pv: "XF:07ID-PPS{Sh:FE}" + new: true + confirm: true + note: "front-end safety shutter, PPS-gated" + - name: PhotonShutter + family: Shutter + pv: "XF:07IDA-PPS{PSh:7}" + new: true + confirm: true + note: "default photon shutter (psh7); psh4 / psh10 also present (PSS-1)" + +soft-optics: + stage: source + enclosure: SST-1 + intro: "The SST-1 plane-grating monochromator that selects the soft X-ray energy." + note: > + The soft PGM reuses the catalog GratingMonochromator Family (SST is the 4th soft + X-ray PGM after SIX, CSX, ESM). Its instance prefix is empty in the devices.toml + (a config-driven factory); the real base XF:07ID1-OP{Mono:PGM1 is hardcoded in the + sst-base EnergySoft class. Energy range 71-2250 eV; the pseudo energy + polarization + axes live on the EnergySoft layer (MONO-1). + devices: + - name: Monochromator_Soft + family: GratingMonochromator # catalog Family (4th soft X-ray PGM after SIX/CSX/ESM) + pv: { grating_pitch: "XF:07ID1-OP{Mono:PGM1-Ax:GrtP}Mtr", premirror_pitch: "XF:07ID1-OP{Mono:PGM1-Ax:MirP}Mtr", grating_x: "XF:07ID1-OP{Mono:PGM1-Ax:GrtX}Mtr", premirror_x: "XF:07ID1-OP{Mono:PGM1-Ax:MirX}Mtr" } + new: true + confirm: true + note: "plane-grating monochromator (PGM1); CFF :CFF_SP + VLS :VLS_B2.A + energy :ENERGY_SP set the energy; grating set is MONO-1" + +tender-optics: + stage: source + enclosure: SST-2 + intro: "The SST-2 Si double-crystal monochromator and the tender refocusing mirrors." + note: > + The tender DCM reuses the catalog Monochromator Family. Its control PVs hardcode + XF:07ID6-OP{Mono:DCM1 (not the undulator prefix). L1 and L2AB are the tender FMB + hexapod mirrors (OPT-1, MONO-1). + devices: + - name: Monochromator_Tender + family: Monochromator + pv: { bragg: "XF:07ID6-OP{Mono:DCM1-Ax:Bragg}Mtr", crystal_x: "XF:07ID6-OP{Mono:DCM1-Ax:X}Mtr", x2_perp: "XF:07ID6-OP{Mono:DCM1-Ax:Per2}Mtr", x2_pitch: "XF:07ID6-OP{Mono:DCM1-Ax:P2}Mtr" } + new: true + confirm: true + note: "Si double-crystal mono (DCM1); crystal-select :XTAL_SEL, energy :ENERGY_SP; crystal set + range are MONO-1" + - name: Mirror_L1 + family: Mirror + pv: "XF:07IDA-OP{Mir:L1" + new: true + confirm: true + note: "tender FMB hexapod mirror L1 (OPT-1)" + - name: Mirror_L2AB + family: Mirror + pv: "XF:07IDA6-OP{Mir:L2AB" + new: true + confirm: true + note: "tender FMB hexapod mirror L2AB; separate wedge axis (OPT-1)" + +# =========================================================================== +# SAMPLE STAGE: the RSoXS (soft) and HAXPES (tender) sample manipulators +# =========================================================================== + +rsoxs-sample: + stage: sample + enclosure: SST-1 + intro: "The RSoXS UHV sample manipulator (SST-1 soft endstation)." + note: "The RSoXS sample manipulator reuses the catalog Manipulator Family (SST is the 3rd UHV manipulator after SIX + ESM)." + devices: + - name: RSoXSManipulator + family: Manipulator + pv: { x: "XF:07ID2-ES1{Stg-Ax:X}Mtr", y: "XF:07ID2-ES1{Stg-Ax:Y}Mtr", z: "XF:07ID2-ES1{Stg-Ax:Z}Mtr", r: "XF:07ID2-ES1{Stg-Ax:Yaw}Mtr" } + new: true + confirm: true + note: "RSoXS four-axis UHV sample manipulator (x/y/z + yaw); pseudo sample-frame axes on the Manipulator layer (SAMPLE-1)" + +haxpes-sample: + stage: sample + enclosure: SST-2 + intro: "The HAXPES UHV sample manipulator and slit (SST-2 tender endstation)." + note: "The HAXPES sample manipulator reuses the catalog Manipulator Family; the HAXPES quad slit defines the analyzed spot." + devices: + - name: HAXPESManipulator + family: Manipulator + pv: { x: "XF:07ID1-BI{HAX-Ax:SampX}Mtr", y: "XF:07ID1-BI{HAX-Ax:SampY}Mtr", z: "XF:07ID1-BI{HAX-Ax:SampZ}Mtr", r: "XF:07ID1-BI{HAX-Ax:SampTh}Mtr" } + new: true + confirm: true + note: "HAXPES four-axis UHV sample manipulator (x/y/z + theta) (SAMPLE-1)" + - name: HAXPESSlit + family: Slit + pv: "XF:07ID2-OP{Slt:12-Ax:" + new: true + confirm: true + note: "HAXPES quad slit (top/bottom/inboard/outboard); the exit / analyzed-spot slit (OPT-2)" + +# =========================================================================== +# DETECTION STAGE: the RSoXS WAXS camera + flux, and the HAXPES electron analyzer +# =========================================================================== + +rsoxs-detectors: + stage: detection + enclosure: SST-1 + intro: "The RSoXS WAXS area detector and the incident-flux monitors." + note: "The Greateyes WAXS CCD reuses the catalog Camera Family; the Au-mesh and photodiode I0 monitors reuse FluxMonitor (DET-1)." + devices: + - name: WAXSDetector + family: Camera + pv: "XF:07ID1-ES:1{GE:2}" + new: true + confirm: true + note: "Greateyes GE 4k4k WAXS scattering CCD (areaDetector); the SAXS twin is not instantiated (DET-1)" + - name: AuMeshMonitor + family: FluxMonitor + pv: "XF:07ID-BI[ADC:3-Ch:2]" + new: true + confirm: true + note: "Au-mesh I0 monitor (1500 lpi mesh, ~55% transmission), single ADC channel (DET-1)" + - name: IzeroPhotodiode + family: FluxMonitor + pv: "XF:07ID-ES1{DMR:I400-1}:IC3_MON" + new: true + confirm: true + note: "Izero photodiode on the DMR I400 electrometer, channel IC3 (DET-1)" + +haxpes-detectors: + stage: detection + enclosure: SST-2 + intro: "The HAXPES hemispherical electron analyzer and ion chamber." + note: > + The Scienta SES is the HAXPES detector and the device that GRADUATES the + ElectronAnalyzer Family (the 2nd hemispherical electron analyzer after ESM). The + I400 ion chamber is modelled as its one instantiated channel only (DET-1). + devices: + - name: ElectronAnalyzer + family: ElectronAnalyzer # catalog Family (graduated this PR: ESM + SST, 2nd Scienta SES) + pv: "XF:07ID-ES-SES" + new: true + confirm: true + note: "Scienta SES hemispherical electron energy analyzer; pass-energy (:pass_en_SP) / lens-mode (:lens_mode_SP) / kinetic-energy-window controls; the HAXPES detector (PES-1, DET-1)" + - name: IonChamber + family: FluxMonitor + pv: "XF:07ID-BI{DM7:I400-1}:IC1_MON" + new: true + confirm: "only the single IC1_MON channel is instantiated in the profile; the full multi-channel I400 (IC1-IC4) is not, so the channel set is unconfirmed (DET-1)" + note: "I400 electrometer ion-chamber channel (DM7); incident-flux monitor (DET-1)" + +# Cross-cutting control. SST runs EPICS (the floor); CORA observes and, where it +# replaces bluesky-style orchestration, conducts over it. The handles above were read +# from the SST profile collections (config-driven: devices.toml + sst-base) (CTRL-1). +controls: + intro: > + SST runs on the NSLS-II EPICS / ophyd control stack, the same floor as the other + NSLS-II beamlines, but its instrument config is config-driven: device instances are + declared in NSLS2/sst-rsoxs-profile-collection and NSLS2/sst-haxpes-profile-collection + startup/devices.toml, and the per-axis PV grammar lives in the NSLS-II-SST/sst-base + + haxpes libraries (the nbs-bl / sst-base framework). The handles above combine the + toml prefix with the class suffixes, carried confirm (CTRL-1). The soft-energy and + tender-energy moves, the RSoXS scans, and the HAXPES analyzer sweeps run through + bluesky plans + the queue server; that orchestration is the seam CORA's edge + replaces, driving through ophyd / EPICS (see model.md). + +# Continuously-available resources a run draws on. +resources: + intro: > + The continuously-available facility resources an SST run needs. The optics and both + endstations are under vacuum (UHV at the photoemission endstation) (SUP-1). + supplies: + - kind: PhotonBeam + - kind: CoolingWater + - kind: Vacuum + note: "the optics and the soft / tender endstations are UHV (SUP-1)" diff --git a/docs/deployments/esm/equipment/detector.md b/docs/deployments/esm/equipment/detector.md index 2da47cae79..4f99dc0984 100644 --- a/docs/deployments/esm/equipment/detector.md +++ b/docs/deployments/esm/equipment/detector.md @@ -4,17 +4,17 @@ ESM detection is photoemission: the Scienta SES hemispherical electron energy analyzer collects the photoelectrons and disperses them by kinetic energy and emission angle, while the QuadEM electrometers read the incident-beam current. They are modelled in the detection stage of the [descriptor](../inventory.md). -The analyzer binds a **new loose `ElectronAnalyzer` Family at n=1** (no photon-detector Family fits an electron spectrometer; see [Model](../model.md#what-this-deployment-graduates)); the flux monitors reuse the catalog `FluxMonitor`. +The analyzer binds the **`ElectronAnalyzer` Family** (graduated across ESM + SST; no photon-detector Family fits an electron spectrometer; see [Model](../model.md#what-this-deployment-graduates)); the flux monitors reuse the catalog `FluxMonitor`. ## Detection chain | Device | Family | Design spec / note | | --- | --- | --- | -| `ElectronAnalyzer` | `ElectronAnalyzer` (loose) | Scienta SES hemispherical analyzer; pass-energy / lens-mode / kinetic-energy-window controls; the ARPES detector (`ARPES-1`) | +| `ElectronAnalyzer` | `ElectronAnalyzer` | Scienta SES hemispherical analyzer; pass-energy / lens-mode / kinetic-energy-window controls; the ARPES detector (`ARPES-1`) | | `FluxMonitor_Upstream` / `FluxMonitor_Branch` | `FluxMonitor` | QuadEM electrometers (qem01-12); I0 / drain-current monitors (`DET-1`) | The analyzer is the defining instrument of the beamline: it measures electrons, not photons, so it sits outside the photon-detector families CORA had (`Camera`, `EnergyDispersiveSpectrometer`, `FluxMonitor`). It is held loose at n=1 until a second photoemission beamline (a future ESM XPEEM branch, or another ARPES beamline) earns it; its lens modes, pass energies, and acquisition modes are `ARPES-1`. ## Families -New at n=1: `ElectronAnalyzer` for the SES, held loose. Reused from the catalog: `FluxMonitor` for the QuadEM monitors. The flux-monitor channel map is `DET-1`. See [Inventory](../inventory.md) for the Asset tree. +`ElectronAnalyzer` for the SES (graduated across ESM + SST). Reused from the catalog: `FluxMonitor` for the QuadEM monitors. The flux-monitor channel map is `DET-1`. See [Inventory](../inventory.md) for the Asset tree. diff --git a/docs/deployments/esm/equipment/index.md b/docs/deployments/esm/equipment/index.md index 62b8262a3f..e303f395b8 100644 --- a/docs/deployments/esm/equipment/index.md +++ b/docs/deployments/esm/equipment/index.md @@ -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). ESM graduates `Manipulator`, reuses the graduated `GratingMonochromator`, and introduces the loose `ElectronAnalyzer`. +- [Inventory](../inventory.md): the full planned CORA Asset model (every device by `parent_id`, with Families and pending confirmations). ESM graduates `Manipulator`, reuses the graduated `GratingMonochromator`, and introduces `ElectronAnalyzer` (since graduated by SST). diff --git a/docs/deployments/esm/index.md b/docs/deployments/esm/index.md index 2d2d4f5d7c..0cf97b3e1b 100644 --- a/docs/deployments/esm/index.md +++ b/docs/deployments/esm/index.md @@ -18,7 +18,7 @@ ESM is **CORA's first photoemission beamline**. Every prior beamline measures photons; ESM measures **electrons** (photon-in / electron-out), which brings a new detector regime: -- **A hemispherical electron analyzer.** The Scienta SES records electron counts over a kinetic-energy by emission-angle window set by the pass energy and lens mode. No photon-detector Family fits, so it binds a new loose `ElectronAnalyzer` Family at n=1 (presents the Detector Role); a second ARPES beamline earns it. +- **A hemispherical electron analyzer.** The Scienta SES records electron counts over a kinetic-energy by emission-angle window set by the pass energy and lens mode. No photon-detector Family fits, so it binds the `ElectronAnalyzer` Family (presents the Detector Role), which graduated once SST earned the 2nd Scienta SES. It is also a **consolidation** of the soft X-ray regime: diff --git a/docs/deployments/esm/inventory.md b/docs/deployments/esm/inventory.md index 26f8edbbf7..502064766d 100644 --- a/docs/deployments/esm/inventory.md +++ b/docs/deployments/esm/inventory.md @@ -4,7 +4,7 @@ This cut models the `XF:21IDA/B/C` optics and the `XF:21ID1-ES` ARPES endstation; the XPEEM/LEEM branch and the simulated devices 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/esm/beamline.yaml) descriptor. -ESM introduces one new family (`ElectronAnalyzer`, loose at n=1), graduates `Manipulator` into the catalog (its 2nd UHV manipulator after SIX), and reuses the rest, including the graduated `GratingMonochromator` (its 3rd PGM). Control handles are filled from the profile collection; no vendor Models are bound. +ESM introduces one new family (`ElectronAnalyzer`, since graduated once SST earned the 2nd SES), graduates `Manipulator` into the catalog (its 2nd UHV manipulator after SIX), and reuses the rest, including the graduated `GratingMonochromator` (its 3rd PGM). Control handles are filled from the profile collection; no vendor Models are bound. ## The Asset tree @@ -27,10 +27,10 @@ Root Asset `ESM` (`tier = Unit`, `facility_code = nsls2`); sub-systems nest belo | `PhotonShutter_A` / `PhotonShutter_B` | `Device` | Shutter | 21-ID-C | branch photon shutters | | `SampleManipulator` | `Device` | Manipulator | 21-ID-D | LT six-axis UHV cryostat (graduates the Family) (SAMPLE-1) | | `SampleTemperature` | `Device` | TemperatureController | 21-ID-D | Lakeshore cryostat (SAMPLE-1) | -| `ElectronAnalyzer` | `Device` | ElectronAnalyzer (loose) | 21-ID-D | Scienta SES hemispherical analyzer (ARPES-1) | +| `ElectronAnalyzer` | `Device` | ElectronAnalyzer | 21-ID-D | Scienta SES hemispherical analyzer (ARPES-1) | | `FluxMonitor_Upstream` / `FluxMonitor_Branch` | `Device` | FluxMonitor | 21-ID-D | QuadEM I0 monitors (DET-1) | -Families reused from the catalog: `InsertionDevice`, `Mirror`, `Slit`, `Shutter`, `GenericProbe`, `TemperatureController`, `FluxMonitor`, `GratingMonochromator` (3rd PGM), and `Manipulator` (graduated with this deployment). Held loose at n=1: `ElectronAnalyzer` (the SES; ESM only). +Families reused from the catalog: `InsertionDevice`, `Mirror`, `Slit`, `Shutter`, `GenericProbe`, `TemperatureController`, `FluxMonitor`, `GratingMonochromator` (3rd PGM), `Manipulator` (graduated with this deployment), and `ElectronAnalyzer` (graduated once SST earned the 2nd SES). No loose family remains. ## Pending confirmations diff --git a/docs/deployments/esm/model.md b/docs/deployments/esm/model.md index 2af1a891b3..50f6a9d6ff 100644 --- a/docs/deployments/esm/model.md +++ b/docs/deployments/esm/model.md @@ -9,7 +9,7 @@ ESM is a descriptor-and-docs scaffold today, reverse-engineered from the beamlin | Beamline descriptor | [`deployments/esm/beamline.yaml`](https://github.com/xmap/cora/blob/main/deployments/esm/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; `ESM` added to its beamline list, with an ARPES Practice | | Extraction provenance | [NSLS2/esm-arpes-profile-collection](https://github.com/NSLS2/esm-arpes-profile-collection) | the `startup/*.py` device classes the descriptor was curated from | -| Catalog Family | [`catalog/catalog.yaml`](https://github.com/xmap/cora/blob/main/catalog/catalog.yaml) | `Manipulator` graduates with this deployment (below); `ElectronAnalyzer` stays loose at n=1 | +| Catalog Family | [`catalog/catalog.yaml`](https://github.com/xmap/cora/blob/main/catalog/catalog.yaml) | `Manipulator` graduates with this deployment (below); `ElectronAnalyzer` graduated once SST earned the 2nd SES | | Catalog Method | [`catalog/catalog.yaml`](https://github.com/xmap/cora/blob/main/catalog/catalog.yaml) | none added; the ARPES Method is not yet coined (TECH-1) | | Equipment Assets | not yet registered | the [Inventory](inventory.md) is the planned shape; no scenario registers ESM Assets yet | | Trust / governance | not yet instantiated | see [Governance](governance.md) | @@ -18,7 +18,7 @@ ESM is a descriptor-and-docs scaffold today, reverse-engineered from the beamlin ESM both earns a new abstraction and consolidates two existing ones. -- **`ElectronAnalyzer` (new, loose at n=1).** The Scienta SES hemispherical electron energy analyzer is the ARPES detector: photon-in, electron-out, recording electron counts over a kinetic-energy by emission-angle window set by the pass energy and lens mode. No photon-detector Family covers an electron spectrometer, so it binds a new loose `ElectronAnalyzer` Family (presents the Detector Role), held at n=1 until a second photoemission beamline earns it (`ARPES-1`). +- **`ElectronAnalyzer` (new, since graduated).** The Scienta SES hemispherical electron energy analyzer is the ARPES detector: photon-in, electron-out, recording electron counts over a kinetic-energy by emission-angle window set by the pass energy and lens mode. No photon-detector Family covers an electron spectrometer, so ESM introduced a new `ElectronAnalyzer` Family (presents the Detector Role); it GRADUATED into the catalog once SST (NSLS-II 7-ID HAXPES) earned the second Scienta SES (`ARPES-1`). - **`Manipulator` (graduates).** ESM's LT six-axis UHV cryostat manipulator is the **second** UHV sample manipulator after SIX, earning the abstraction at the two-deployment threshold. `Manipulator` graduates into the catalog with this deployment, distinct from `Hexapod` (parallel-kinematic), `Goniometer` (crystal orientation), and a plain `LinearStage` / `RotaryStage`; axis count and cryo range are a per-Asset settings difference. SIX's references are swept loose to graduated in the same change. Its naming-r3 review (done at the SIX sighting, with the watch-item to confirm it is not a `Hexapod` / `Goniometer` synonym) is resolved: a serial UHV stack is a distinct mechanism. - **`GratingMonochromator` (reuses).** ESM's PGM is the third soft X-ray plane-grating monochromator after SIX and CSX, so it binds the catalog Family rather than minting one. diff --git a/docs/deployments/esm/questions.md b/docs/deployments/esm/questions.md index b05fb399ff..2bffc311e6 100644 --- a/docs/deployments/esm/questions.md +++ b/docs/deployments/esm/questions.md @@ -26,7 +26,7 @@ ESM was reverse-engineered from the beamline's own bluesky profile collection ([ | ID | Priority | Question | CORA assumes | Resolves | | --- | --- | --- | --- | --- | -| ARPES-1 | Blocks-build | The Scienta SES analyzer (`XF21ID1-ES-SES`): the model, the lens modes, the pass-energy and kinetic-energy-window controls, and the acquisition modes. | A loose `ElectronAnalyzer` Asset presenting the Detector Role. | The analyzer model and whether the Family stays distinct. | +| ARPES-1 | Blocks-build | The Scienta SES analyzer (`XF21ID1-ES-SES`): the model, the lens modes, the pass-energy and kinetic-energy-window controls, and the acquisition modes. | An `ElectronAnalyzer` Asset (catalog Family) presenting the Detector Role. | The analyzer model and lens/pass-energy controls. | | SAMPLE-1 | Blocks-go-live | The LT UHV cryostat manipulator: the live prefix (the config shows a provisional `{PRV` and a commented `{LT:1-Manip:EA5_1`), the six axes, the cryo range, and the sample-prep / load-lock chambers. | A `Manipulator` Asset (x/y/z + Rx/Ry/Rz) plus a `TemperatureController`. | The sample-environment model. | | DET-1 | Nice-to-have | The QuadEM flux monitors (qem01-12): which are I0 versus drain-current, and where each sits. | Two representative `FluxMonitor` Assets; the full set summarized. | The flux-monitor map. | diff --git a/docs/deployments/index.md b/docs/deployments/index.md index 8881de8022..56fee0e083 100644 --- a/docs/deployments/index.md +++ b/docs/deployments/index.md @@ -53,6 +53,7 @@ The fourth Site CORA models. Like the Diamond exercise, its beamlines are revers | [XPD](xpd/index.md) | Reverse-engineered | high-energy powder diffraction and total scattering / PDF, 28-ID; the NSLS-II twin of Diamond i11 and i15-1, modelled from public beamline config | | [ESM](esm/index.md) | Reverse-engineered | electron spectro-microscopy (ARPES), 21-ID; CORA's first photoemission beamline, graduates the Manipulator Family, modelled from public beamline config | | [SMI](smi/index.md) | Reverse-engineered | small- and wide-angle scattering (SAXS/WAXS) with grazing incidence (GISAXS/GIWAXS), 12-ID; the NSLS-II twin of Diamond i22, modelled from public beamline config | +| [SST](sst/index.md) | Reverse-engineered | soft + tender spectroscopy (RSoXS + HAXPES), 7-ID; graduates the ElectronAnalyzer Family, modelled from public beamline config | ## [SLAC](slac/index.md) diff --git a/docs/deployments/sst/equipment/controls.md b/docs/deployments/sst/equipment/controls.md new file mode 100644 index 0000000000..3a6b2e3391 --- /dev/null +++ b/docs/deployments/sst/equipment/controls.md @@ -0,0 +1,19 @@ +# Controls + +*The control stack, its config-driven instrument map, and the bluesky-orchestration seam. First cut; handles read from the profile, carried confirm.* + +SST runs on the NSLS-II EPICS / ophyd control stack, the same floor as the other NSLS-II beamlines. CORA observes that floor and, where it replaces bluesky-style orchestration, conducts over it; it does not replace EPICS itself. + +## Device handles (config-driven) + +SST is the config-driven extraction mode: device instances are declared in the beamline's bluesky profile collections ([NSLS2/sst-rsoxs-profile-collection](https://github.com/NSLS2/sst-rsoxs-profile-collection), [NSLS2/sst-haxpes-profile-collection](https://github.com/NSLS2/sst-haxpes-profile-collection)) as `devices.toml` blocks (a `prefix` + a `_target` class), and the per-axis PV grammar lives in the shared [NSLS-II-SST/sst-base](https://github.com/NSLS-II-SST/sst-base) library. The descriptor's handles combine the toml prefix with the class suffixes, so they are verified against both sources. They remain confirm-pending (`CTRL-1`). + +Two config-driven subtleties carried into the descriptor: the soft PGM's instance prefix is empty in the toml (a factory call), so its real base `XF:07ID1-OP{Mono:PGM1` is read from the `sst-base` library; and the tender DCM hardcodes `XF:07ID6-OP{Mono:DCM1` rather than inheriting the undulator prefix. Both are confirmed against the library source. + +## The orchestration seam + +The soft-energy and tender-energy moves, the RSoXS scans, and the HAXPES analyzer sweeps run through bluesky plans and the queue server. That orchestration is the seam CORA's edge replaces: CORA conducts the run over the `ControlPort`, driving through ophyd / EPICS rather than replacing it. The detector file-writing to the NSLS-II filestore is plumbing CORA observes, not data it owns; CORA keeps its own data-of-record. + +## Equipment protection + +SST carries an equipment-protection interlock separate from the personnel PSS, as the other NSLS-II beamlines do, with the UHV endstations adding vacuum interlocks (gate valves, pressure trips). CORA does not model the interlock logic; it would only observe outcomes, mapping vacuum and utility faults to Supply status and device faults to an Asset condition. That mapping is not modelled in this cut. diff --git a/docs/deployments/sst/equipment/detector.md b/docs/deployments/sst/equipment/detector.md new file mode 100644 index 0000000000..0de4e58f63 --- /dev/null +++ b/docs/deployments/sst/equipment/detector.md @@ -0,0 +1,26 @@ +# Detector + +*The RSoXS scattering detector and flux monitors (soft), and the HAXPES electron analyzer and ion chamber (tender). First cut; PVs read from the config-driven profile, carried confirm.* + +SST detects two ways, one per branch: the SST-1 soft branch records scattered photons on the Greateyes WAXS area detector with incident-flux monitors, and the SST-2 tender branch records photoelectrons on the Scienta SES hemispherical analyzer with an ion chamber. They are modelled in the detection stage of the [descriptor](../inventory.md). + +The WAXS detector reuses the catalog `Camera` Family and the flux monitors `FluxMonitor`. The Scienta SES is the device that **graduates** the `ElectronAnalyzer` Family (the 2nd hemispherical electron analyzer after ESM; see [Model](../model.md#what-this-deployment-graduates)). + +## RSoXS detection (SST-1) + +| Device | Family | Design spec / note | +| --- | --- | --- | +| `WAXSDetector` | `Camera` | Greateyes GE 4k4k WAXS scattering CCD (areaDetector); the SAXS twin is not instantiated (`DET-1`) | +| `AuMeshMonitor` | `FluxMonitor` | Au-mesh I0 monitor, single ADC channel (`DET-1`) | +| `IzeroPhotodiode` | `FluxMonitor` | Izero photodiode on the DMR I400 electrometer, channel IC3 (`DET-1`) | + +## HAXPES detection (SST-2) + +| Device | Family | Design spec / note | +| --- | --- | --- | +| `ElectronAnalyzer` | `ElectronAnalyzer` | Scienta SES hemispherical analyzer; pass-energy / lens-mode / kinetic-energy controls; graduates the Family (`PES-1`) | +| `IonChamber` | `FluxMonitor` | I400 electrometer ion-chamber channel (DM7); only the one channel is instantiated (`DET-1`) | + +## Families + +Reused from the catalog: `Camera` (the WAXS CCD) and `FluxMonitor` (the Au-mesh, photodiode, and ion chamber). Graduated with this deployment: `ElectronAnalyzer`, for the Scienta SES, earned once SST became the second photoemission beamline after ESM. The photoemission measurement is electrons out, not photons, so the analyzer is distinct from the photon detectors; analyzer model and lens / pass-energy controls are `PES-1`, and the detector channel sets are `DET-1`. See [Inventory](../inventory.md) for the Asset tree. diff --git a/docs/deployments/sst/equipment/index.md b/docs/deployments/sst/equipment/index.md new file mode 100644 index 0000000000..d2c98f78d7 --- /dev/null +++ b/docs/deployments/sst/equipment/index.md @@ -0,0 +1,22 @@ +# The beamline + +*The part of SST CORA models today, as areas you can jump to: the shared optics and the two monochromators, the soft (RSoXS) and tender (HAXPES) sample endstations, and their detectors, plus the controls. First cut.* + +SST is the NSLS-II soft + tender spectroscopy beamline at sector 7-ID, with two branches off a shared front end. Its PV zones run `XF:07IDA` (shared front-end optics), `XF:07ID1` / `XF:07ID2` (the SST-1 soft branch + RSoXS endstation), and `XF:07ID6` / `XF:07ID-ES` (the SST-2 tender branch + HAXPES endstation). This cut models the operational core across both branches; the UCAL TES microcalorimeter and the VPPEM microscope are deferred (see [Model](../model.md#deliberately-not-here-yet)). + +Along the beam, the **stations**: the [Source](../beamline.md) that delivers and energy-selects the soft and tender beams, the [Sample](sample.md) manipulators that place the specimen, and the [Detector](detector.md) that records the scattering (soft) or the photoelectrons (tender). Cutting across them are the [Controls](controls.md). The stations are containment trees of apparatus (`Asset.parent_id`); controls relate to it sideways, by `controller_id`. + +## Stations + +- [Source](../beamline.md): the two EPUs, the shared front-end mirror and slit, the SST-1 soft plane-grating monochromator, and the SST-2 tender Si double-crystal monochromator with its mirrors. +- [Sample](sample.md): the RSoXS UHV manipulator (SST-1) and the HAXPES UHV manipulator and slit (SST-2). +- [Detector](detector.md): the RSoXS Greateyes WAXS detector and I0 monitors (SST-1), and the HAXPES Scienta SES electron analyzer and ion chamber (SST-2). + +## Shared + +- [Controls](controls.md): the NSLS-II EPICS / ophyd control stack, its config-driven instrument map (devices.toml + the sst-base library), and the bluesky-orchestration seam CORA's edge replaces. Handles carried confirm (`CTRL-1`). +- Resources: the continuously-available supplies a run needs (photon beam, cooling water, vacuum / UHV at both endstations); carried in the descriptor. + +## Reference + +- [Inventory](../inventory.md): the full planned CORA Asset model (every device by `parent_id`, with Families and pending confirmations). SST graduates `ElectronAnalyzer` and reuses the rest. diff --git a/docs/deployments/sst/equipment/sample.md b/docs/deployments/sst/equipment/sample.md new file mode 100644 index 0000000000..3935de15d2 --- /dev/null +++ b/docs/deployments/sst/equipment/sample.md @@ -0,0 +1,24 @@ +# Sample + +*The RSoXS (soft) and HAXPES (tender) UHV sample manipulators. First cut; PVs read from the config-driven profile, carried confirm.* + +SST has two sample endstations, one per branch: the RSoXS UHV manipulator on the SST-1 soft branch, and the HAXPES UHV manipulator and analyzed-spot slit on the SST-2 tender branch. They are modelled as sample-stage groups in the [descriptor](../inventory.md). + +Both manipulators reuse the catalog `Manipulator` Family (SST is the 3rd and 4th UHV manipulator after SIX + ESM); the HAXPES slit reuses `Slit`. No new family is introduced (see [Model](../model.md#what-this-deployment-graduates)). + +## The RSoXS sample manipulator (SST-1) + +| Device | Family | Design spec / note | +| --- | --- | --- | +| `RSoXSManipulator` | `Manipulator` | RSoXS UHV sample manipulator (x/y/z + yaw); pseudo sample-frame axes on the Manipulator layer (`SAMPLE-1`) | + +## The HAXPES sample manipulator (SST-2) + +| Device | Family | Design spec / note | +| --- | --- | --- | +| `HAXPESManipulator` | `Manipulator` | HAXPES UHV sample manipulator (x/y/z + theta) (`SAMPLE-1`) | +| `HAXPESSlit` | `Slit` | HAXPES quad slit defining the analyzed spot (`OPT-2`) | + +Both manipulators are serial-stack UHV sample manipulators, the same role that graduated the `Manipulator` Family on SIX + ESM; their axis maps, base pressures, and any cryo or sample-transfer mechanisms are `SAMPLE-1`. The HAXPES sample orientation (theta) and the analyzed-spot slit together set what the [electron analyzer](detector.md) sees. + +See [Open questions](../questions.md) for the sample-environment facts still to confirm, and [Inventory](../inventory.md) for the Asset tree. diff --git a/docs/deployments/sst/governance.md b/docs/deployments/sst/governance.md new file mode 100644 index 0000000000..4091d7d57a --- /dev/null +++ b/docs/deployments/sst/governance.md @@ -0,0 +1,11 @@ +# Governance + +*Who will act at SST, and the trust shape that will gate it. First cut.* + +Governance at SST follows the same model as the other NSLS-II beamlines: people and autonomous agents are facility principals at the [NSLS-II Site](../nsls2/index.md), and on the beamline they surface through the actions they take. Their commands are gated by a trust shape (a Zone grouping the beamline's resources, a Conduit binding the surfaces that may issue commands, and Policies that say who may do what). + +SST is not yet driven by CORA, so this shape is not yet instantiated. The profile collection exposes only coarse queue-server groups, not the human roster, so the NSLS-II operator and review structure is carried pending on the [NSLS-II Site](../nsls2/index.md) (`GOV-1`). SST's two branches (soft and tender) may each carry their own operator assignments; that split lands with the operator pool. + +What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [NSLS-II Site](../nsls2/index.md), not on the beamline, and the beamline links up to them. SST carries the soft / tender X-ray hazard classes (ultra-high vacuum at both endstations, the photoemission analyzer's high voltage) that an experiment Clearance would carry; those land with the instruments that bring them. + +The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives SST, following the [2-BM governance](../2-bm/governance.md) shape. diff --git a/docs/deployments/sst/index.md b/docs/deployments/sst/index.md new file mode 100644 index 0000000000..a78f5157f9 --- /dev/null +++ b/docs/deployments/sst/index.md @@ -0,0 +1,66 @@ +# SST + +*The Spectroscopy Soft and Tender beamline at NSLS-II, and CORA's fourth soft X-ray deployment. This page walks the operational core CORA models today across its two branches. It is a reverse-engineered first cut, not yet a running model.* + +| Property | Value | +| --- | --- | +| Asset | `SST` (root Asset, `tier = Unit`, `parent_id = None`) | +| Facility | [NSLS-II](../nsls2/index.md) (bound via `facility_code = "nsls2"`, `FacilityKind = Site`) | +| Sector | `Sector 7` (PV namespace `XF:07ID*`; not a registered Asset) | +| Status | First cut, reverse-engineered, design-phase (descriptor + docs; scenarios deferred) | +| Source | Two EPUs on the `SR:C07-ID` straight (EPU60 soft, U42 tender) | +| Control stack | NSLS-II EPICS / ophyd, config-driven (devices.toml + the sst-base library); handles carried confirm | + +!!! warning "First cut, and confirm-pending by intent" + This scaffold was reverse-engineered from the beamline's own bluesky profile collections ([NSLS2/sst-rsoxs-profile-collection](https://github.com/NSLS2/sst-rsoxs-profile-collection), [NSLS2/sst-haxpes-profile-collection](https://github.com/NSLS2/sst-haxpes-profile-collection)) and the [NSLS-II-SST/sst-base](https://github.com/NSLS-II-SST/sst-base) device library. SST is the config-driven extraction mode: device instances live in `devices.toml` and the per-axis PV grammar in the pip libraries, so each PV is the toml prefix combined with the class suffixes, carried `confirm` until SST staff verify it. What CORA needs the team to confirm is on [Open questions](questions.md). + +## What SST adds + +SST is the soft + tender X-ray spectroscopy beamline: two branches off a shared front end, a plane-grating monochromator for the soft branch and a Si double-crystal monochromator for the tender branch. It is a **consolidation** deployment that also earns one graduation: + +- **It graduates `ElectronAnalyzer`.** The HAXPES (tender) endstation uses a Scienta SES hemispherical electron energy analyzer, the second after ESM. That earns the rule-of-three, so `ElectronAnalyzer` becomes a catalog Family (ESM's references are swept loose to graduated; see [Model](model.md#what-this-deployment-graduates)). +- **It reuses three graduated families across soft and tender.** The soft PGM is the 4th `GratingMonochromator`; the tender DCM reuses `Monochromator`; the RSoXS and HAXPES UHV manipulators are the 3rd and 4th `Manipulator`. +- **It is the config-driven extraction mode.** Unlike the `startup/*.py` beamlines, SST's instances are TOML + a shared `sst-base` library; the descriptor's PVs are verified against both. + +It runs across two branches: SST-1 (soft, the RSoXS endstation) and SST-2 (tender, the HAXPES endstation). + +## Scope: what is and is not modelled + +| Part | In this cut | Why | +| --- | --- | --- | +| Shared front end (`XF:07IDA`) | Yes | EPUs, M1 mirror, FOE slit, shutters | +| SST-1 soft + RSoXS | Yes | The soft PGM, the RSoXS manipulator, the Greateyes WAXS detector, the I0 monitors | +| SST-2 tender + HAXPES | Yes | The Si DCM, the tender mirrors, the HAXPES manipulator + slit, the Scienta SES | +| UCAL / NEXAFS TES microcalorimeter | No | A cryogenic microcalorimeter detector regime CORA has not modelled (a future family) | +| VPPEM photoemission microscope | No | An electron-microscope endstation, deferred (the `PEEM-1` family, shared with ESM's XPEEM) | +| Full multi-channel I400 | Coarsely | Only the one instantiated ion-chamber channel is modelled (`DET-1`) | + +The deferred parts are recorded on [Model](model.md#deliberately-not-here-yet). + +## The beamline + +- [Source](beamline.md): the generated device walk: the two EPUs, the shared front-end mirror and slit, the soft PGM (SST-1), and the tender DCM and mirrors (SST-2). +- [Sample](equipment/sample.md): the RSoXS UHV manipulator (SST-1) and the HAXPES UHV manipulator and slit (SST-2). +- [Detector](equipment/detector.md): the RSoXS Greateyes WAXS detector and flux monitors (SST-1), and the HAXPES Scienta SES electron analyzer and ion chamber (SST-2). + +Cutting across them: + +- [Controls](equipment/controls.md): the EPICS / ophyd control stack, its config-driven instrument map, and the bluesky-orchestration seam; handles carried confirm. + +The cross-cutting reference view is the [Inventory](inventory.md). The [Source](beamline.md) page is generated from the [`beamline.yaml`](https://github.com/xmap/cora/blob/main/deployments/sst/beamline.yaml) descriptor. + +## Techniques + +[Techniques](techniques.md): what the modelled part of SST is designed to do, as intent. RSoXS reuses the catalog scattering Method; HAXPES is a soft / tender photoemission technique carried pending. + +## Governance + +[Governance](governance.md): who will act at SST and the trust shape that gates their commands. People and agents are facility principals at the [NSLS-II Site](../nsls2/index.md). + +## Model + +[Model](model.md): the developer's by-kind index, the `ElectronAnalyzer` graduation this deployment earns, and the record of what is deliberately deferred. + +## Not yet documented + +SST is not yet driven by CORA, so the operations runbook and the live experiment view are deliberately not written yet. They join as the deployment firms up. The [2-BM deployment](../2-bm/index.md) shows the shape they will take. diff --git a/docs/deployments/sst/inventory.md b/docs/deployments/sst/inventory.md new file mode 100644 index 0000000000..987e378ba3 --- /dev/null +++ b/docs/deployments/sst/inventory.md @@ -0,0 +1,47 @@ +# Inventory + +*The CORA Asset model for the operational core of SST modelled today: the planned device tree across both branches and what still needs confirming.* + +This cut models the shared front end, the SST-1 soft branch + RSoXS endstation, and the SST-2 tender branch + HAXPES endstation; the UCAL TES microcalorimeter and the VPPEM microscope 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/sst/beamline.yaml) descriptor. + +Every device binds an existing catalog [Family](../../catalog/families.md): SST reuses `GratingMonochromator` (soft, its 4th), `Monochromator` (tender Si DCM), and `Manipulator` (its 3rd / 4th), and **graduates** `ElectronAnalyzer` (the HAXPES Scienta SES, the 2nd after ESM). Control handles are filled from the config-driven profile; no vendor Models are bound. + +## The Asset tree + +Root Asset `SST` (`tier = Unit`, `facility_code = nsls2`); sub-systems nest below by `parent_id`. + +| Asset | Tier | Family | Enclosure | Design spec / note | +| --- | --- | --- | --- | --- | +| `SST` | `Unit` | (root) | - | bound to the NSLS-II Site; soft + tender, two branches | +| `Undulator_Soft` | `Device` | InsertionDevice | 7-ID-A | EPU60 feeding SST-1 soft (SRC-1) | +| `Undulator_Tender` | `Device` | InsertionDevice | 7-ID-A | U42 feeding SST-2 tender (SRC-1) | +| `Mirror_1` | `Device` | Mirror | 7-ID-A | shared FOE FMB hexapod mirror (OPT-1) | +| `FrontEndSlit` | `Device` | Slit | 7-ID-A | FOE quad slit (OPT-2) | +| `FrontEndShutter` / `PhotonShutter` | `Device` | Shutter | 7-ID-A | front-end + photon shutters | +| `Monochromator_Soft` | `Device` | GratingMonochromator | SST-1 | plane-grating mono, 71-2250 eV (MONO-1) | +| `Monochromator_Tender` | `Device` | Monochromator | SST-2 | Si double-crystal mono (MONO-1) | +| `Mirror_L1` / `Mirror_L2AB` | `Device` | Mirror | SST-2 | tender FMB hexapod mirrors (OPT-1) | +| `RSoXSManipulator` | `Device` | Manipulator | SST-1 | RSoXS UHV manipulator x/y/z/yaw (SAMPLE-1) | +| `HAXPESManipulator` | `Device` | Manipulator | SST-2 | HAXPES UHV manipulator x/y/z/theta (SAMPLE-1) | +| `HAXPESSlit` | `Device` | Slit | SST-2 | HAXPES analyzed-spot quad slit (OPT-2) | +| `WAXSDetector` | `Device` | Camera | SST-1 | Greateyes GE 4k4k WAXS CCD (DET-1) | +| `AuMeshMonitor` / `IzeroPhotodiode` | `Device` | FluxMonitor | SST-1 | RSoXS I0 monitors (DET-1) | +| `ElectronAnalyzer` | `Device` | ElectronAnalyzer | SST-2 | Scienta SES; graduates the Family (PES-1) | +| `IonChamber` | `Device` | FluxMonitor | SST-2 | I400 ion-chamber channel (DET-1) | + +Families reused from the catalog: `InsertionDevice`, `Mirror`, `Slit`, `Shutter`, `GratingMonochromator`, `Monochromator`, `Manipulator`, `Camera`, `FluxMonitor`. Graduated with this deployment: `ElectronAnalyzer` (the HAXPES Scienta SES, the 2nd after ESM). SST introduces **no loose family of its own**. + +## Pending confirmations + +| Value to confirm | Applies to | Status | Tracking | +| --- | --- | --- | --- | +| EPU types, periods, polarization, dual-EPU coupling | `Undulator_Soft/Tender` | `unknown-pending-confirmation` | (SRC-1) | +| Hutch grouping of the PV zones | the enclosures | `unknown-pending-confirmation` | (ENC-1) | +| PSS permit signals | the enclosures | `unknown-pending-confirmation` | (PSS-1) | +| Control handles (config-driven PVs) | all devices | `read-from-config-pending-confirmation` | (CTRL-1) | +| Soft PGM grating set + tender DCM crystal/range | the monochromators | `unknown-pending-confirmation` | (MONO-1) | +| Mirror coatings and axis roles | `Mirror_1`, `Mirror_L1/L2AB` | `unknown-pending-confirmation` | (OPT-1) | +| Slit axis maps | `FrontEndSlit`, `HAXPESSlit` | `unknown-pending-confirmation` | (OPT-2) | +| Manipulator axes + UHV / cryo spec | `RSoXSManipulator`, `HAXPESManipulator` | `unknown-pending-confirmation` | (SAMPLE-1) | +| Scienta SES analyzer model + lens / pass-energy controls | `ElectronAnalyzer` | `unknown-pending-confirmation` | (PES-1) | +| Detector models + ion-chamber channel set | `WAXSDetector`, `IonChamber`, the flux monitors | `unknown-pending-confirmation` | (DET-1) | diff --git a/docs/deployments/sst/model.md b/docs/deployments/sst/model.md new file mode 100644 index 0000000000..570f355c55 --- /dev/null +++ b/docs/deployments/sst/model.md @@ -0,0 +1,42 @@ +# Model + +*The developer's index into where SST content lives, the `ElectronAnalyzer` graduation this deployment earns, and the record of what is deliberately deferred. First cut.* + +SST is a descriptor-and-docs scaffold today, reverse-engineered from the beamline's config-driven profile collections: it exists as the descriptor and docs below, not yet as registered events or integration scenarios. This page points to where each piece lives, and records the scope decisions that are CORA's to make (kept off the staff [Open questions](questions.md), which carry only world-facts). + +| Kind | Where | Notes | +| --- | --- | --- | +| Beamline descriptor | [`deployments/sst/beamline.yaml`](https://github.com/xmap/cora/blob/main/deployments/sst/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; `SST` added with RSoXS + HAXPES Practices | +| Extraction provenance | [NSLS2/sst-rsoxs-profile-collection](https://github.com/NSLS2/sst-rsoxs-profile-collection) + [sst-haxpes](https://github.com/NSLS2/sst-haxpes-profile-collection) + [sst-base](https://github.com/NSLS-II-SST/sst-base) | the config-driven (devices.toml + library) source the descriptor was curated from | +| Catalog Family | [`catalog/catalog.yaml`](https://github.com/xmap/cora/blob/main/catalog/catalog.yaml) | `ElectronAnalyzer` graduates with this deployment (below); no other change | +| Catalog Method | [`catalog/catalog.yaml`](https://github.com/xmap/cora/blob/main/catalog/catalog.yaml) | none added; RSoXS reuses `resonant_scattering`, HAXPES is a new pending photoemission Method (TECH-1) | +| Equipment Assets | not yet registered | the [Inventory](inventory.md) is the planned shape; no scenario registers SST Assets yet | +| Trust / governance | not yet instantiated | see [Governance](governance.md) | + +## What this deployment graduates + +SST is a consolidation deployment for the soft / tender X-ray regime. It graduates one family and reuses three: + +- **`ElectronAnalyzer` graduates.** ESM (NSLS-II 21-ID) introduced it as a loose family at n=1 (the ARPES Scienta SES). SST's HAXPES endstation carries the **second** Scienta SES hemispherical electron energy analyzer, which earns the rule-of-three, so `ElectronAnalyzer` becomes a catalog Family that both ESM and SST bind (analyzer model, lens-mode set, and pass-energy range are per-Asset settings, not a Family split). ESM's references are swept loose to graduated in the same change. It presents the Detector Role, distinct from the photon detectors. Its naming-r3 review is done. +- **`GratingMonochromator` reused (4th).** The soft PGM is the fourth soft X-ray plane-grating mono after SIX, CSX, ESM. +- **`Monochromator` reused.** The tender Si double-crystal mono binds the catalog crystal-DCM Family. +- **`Manipulator` reused (3rd / 4th).** The RSoXS and HAXPES UHV sample manipulators bind the catalog Family graduated by SIX + ESM. + +No new family of SST's own is introduced. + +## Deliberately not here yet + +- **The UCAL / NEXAFS TES microcalorimeter endstation.** SST-1 also carries a transition-edge-sensor microcalorimeter array with an ADR cryostat: a cryogenic energy-dispersive detector regime CORA has not modelled. It is deferred (a future loose family at first sighting), not extracted in this cut. + +- **The VPPEM photoemission electron microscope.** The SST-2 variable-polarization photoemission microscope is an electron-imaging instrument, the same shape as ESM's deferred XPEEM/LEEM branch; deferred to the future `ElectronMicroscope` family (`PEEM-1`). + +- **The full multi-channel I400 ion chamber.** Only the single instantiated `:IC1_MON` channel is modelled as a flux monitor; the multi-channel I400 device is not instantiated in the profile, so the channel set is carried `confirm` rather than invented (`DET-1`). + +- **The config-driven extraction caveats.** The soft PGM's instance prefix is empty in the devices.toml (a factory call); its real base `XF:07ID1-OP{Mono:PGM1` and the tender DCM's `XF:07ID6-OP{Mono:DCM1` are hardcoded in the `sst-base` library, verified there. The secondary flux diagnostics and the many alignment / screen cameras are not core beam-path devices and are deferred. + +- **Full asset-tree scenarios and vendor Models.** No `test_sst_*.py` registers the SST asset tree, and no vendor Models are bound. Those land when the design firms and the team approves. + +- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). + +The [2-BM Model page](../2-bm/model.md) shows the by-kind index a fully-modelled deployment carries. diff --git a/docs/deployments/sst/questions.md b/docs/deployments/sst/questions.md new file mode 100644 index 0000000000..c33f440eac --- /dev/null +++ b/docs/deployments/sst/questions.md @@ -0,0 +1,35 @@ +# Open questions + +*What CORA needs the SST team to confirm before the model can be trusted.* + +SST was reverse-engineered from the beamline's own bluesky profile collections (RSoXS + HAXPES) and the shared [NSLS-II-SST/sst-base](https://github.com/NSLS-II-SST/sst-base) library, so the control handles in the [Inventory](inventory.md) are the beamline's real PVs, combined from the `devices.toml` instance prefixes and the library's per-axis grammar rather than confirmed by staff. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](model.md#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. + +## Topology and scope + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| SRC-1 | Blocks-go-live | The two EPUs (EPU60 soft on `SST1:1`, U42 tender on `SST2:1`): periods, polarization model, and how the tender U42 couples to the DCM energy. | Two `InsertionDevice` Assets; phase carried as a setting. | The insertion-device specs. | +| ENC-1 | Blocks-go-live | Are the PV zones `XF:07IDA` / `07ID1` / `07ID2` / `07ID6` / `07ID-ES` separate shielded hutches, and how do they group into the soft / tender branches? | A shared FOE enclosure plus an SST-1 and an SST-2 branch enclosure. | The Enclosure grouping. | + +## Control and safety + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| CTRL-1 | Blocks-go-live | Are the config-driven PV handles (devices.toml prefix + sst-base class suffix) current and correct? | The handles in the descriptor are taken from the profile + library and carried confirm. | Verifying each Asset's control handle. | +| PSS-1 | Blocks-go-live | The PSS search-and-secure permit signals for the hutches. | Permit leaves to be named; the shutters are `XF:07ID-PPS{Sh:FE}` and `XF:07IDA-PPS{PSh:4/7/10}`. | The Enclosure permit signals. | + +## Source and optics + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| MONO-1 | Blocks-go-live | The soft PGM (grating line densities, c-value, 71-2250 eV) and the tender Si DCM (crystal set, energy range). | A `GratingMonochromator` (soft) and a `Monochromator` (tender Si DCM). | The monochromator models. | +| OPT-1 | Nice-to-have | The mirrors (M1 FOE, L1 / L2AB tender): coatings, stripes, and the hexapod axis roles. | `Mirror` Assets with the FMB hexapod axis grammar; coatings unconfirmed. | The mirror specs. | +| OPT-2 | Nice-to-have | The quad slits (FOE, HAXPES analyzed-spot): the blade axis maps. | `Slit` Assets (top/bottom/inboard/outboard blades). | The slit axis maps. | + +## Endstations + +| ID | Priority | Question | CORA assumes | Resolves | +| --- | --- | --- | --- | --- | +| SAMPLE-1 | Blocks-go-live | The RSoXS and HAXPES UHV manipulators: the axis maps, the base pressure, and any cryo / sample-transfer. | Two `Manipulator` Assets (x/y/z + a rotation). | The sample-environment models. | +| PES-1 | Blocks-go-live | The HAXPES Scienta SES analyzer (`XF:07ID-ES-SES`): the model, the lens modes, and the pass-energy / kinetic-energy controls. | An `ElectronAnalyzer` Asset presenting the Detector Role. | The analyzer model. | +| DET-1 | Blocks-go-live | The RSoXS Greateyes WAXS detector, the I0 monitors, and the I400 ion chamber: models and the full channel set (only one I400 channel is instantiated in the profile). | `Camera` + `FluxMonitor` Assets; the I400 channel set carried confirm. | The detector models and channels. | diff --git a/docs/deployments/sst/techniques.md b/docs/deployments/sst/techniques.md new file mode 100644 index 0000000000..a354ff6154 --- /dev/null +++ b/docs/deployments/sst/techniques.md @@ -0,0 +1,29 @@ +# Techniques + +*What the modelled part of SST is designed to do, as intent. First cut.* + +A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../nsls2/index.md) is how a facility adapts it. SST's two branches run two technique families, one reusing an existing pending Method and one new, both carried pending until a technique enters scope (`TECH-1`). + +## Resonant soft X-ray scattering (SST-1) + +The soft branch tunes the plane-grating monochromator to an absorption edge and records the scattered soft X-rays on the Greateyes area detector, resolving chemical and orientational order. + +| Technique | Catalog method | Notes | +| --- | --- | --- | +| Resonant soft X-ray scattering (RSoXS) | `resonant_scattering` | reuses the 4-ID `resonant_scattering` Method, in a soft X-ray regime (a Plan / settings difference) on the [RSoXS endstation](equipment/sample.md) | + +It needs the [soft PGM](beamline.md), the [RSoXS manipulator](equipment/sample.md), and the [WAXS detector and I0 monitors](equipment/detector.md). + +## Photoelectron spectroscopy (SST-2) + +The tender branch tunes the Si double-crystal monochromator and measures the kinetic-energy spectrum of emitted photoelectrons on the Scienta SES analyzer, probing chemical state and electronic structure. + +| Technique | Catalog method | Notes | +| --- | --- | --- | +| X-ray photoelectron spectroscopy (HAXPES) | `xray_photoelectron_spectroscopy` | tender photoemission on the [Scienta SES analyzer](equipment/detector.md); a new pending Method, distinct from ESM's angle-resolved variant | + +It needs the [tender DCM](beamline.md), the [HAXPES manipulator and slit](equipment/sample.md), and the [SES analyzer](equipment/detector.md). + +## Not modelled yet + +The concrete acquisition recipes (energy scans, scattering exposures, analyzer sweeps) are not written yet; they join as the deployment approaches the point where CORA drives SST. The UCAL NEXAFS (TES microcalorimeter) and VPPEM techniques are deferred with their endstations (see [Model](model.md#deliberately-not-here-yet)). Whether RSoXS and HAXPES Methods enter CORA's catalog is an owner-scope decision; see [Open questions](questions.md) for the world-facts to confirm first. diff --git a/mkdocs.yml b/mkdocs.yml index 7db59cdb83..d6314209f3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -420,6 +420,19 @@ nav: - Techniques: deployments/ixs/techniques.md - Governance: deployments/ixs/governance.md - Model: deployments/ixs/model.md + - SST: + - deployments/sst/index.md + - Open questions: deployments/sst/questions.md + - The beamline: + - deployments/sst/equipment/index.md + - Source: deployments/sst/beamline.md + - Sample: deployments/sst/equipment/sample.md + - Detector: deployments/sst/equipment/detector.md + - Controls: deployments/sst/equipment/controls.md + - Inventory: deployments/sst/inventory.md + - Techniques: deployments/sst/techniques.md + - Governance: deployments/sst/governance.md + - Model: deployments/sst/model.md - SLAC: - deployments/slac/index.md - LCLS-MFX: From abc83f29b6e4f9f3b9554186d24af3db510fac9f Mon Sep 17 00:00:00 2001 From: Doga Gursoy Date: Thu, 25 Jun 2026 20:38:14 +0300 Subject: [PATCH 2/2] fix(sst): audit follow-ups; complete the ESM ElectronAnalyzer sweep, x_ray naming Pre-merge audit (GO) follow-ups: - deployments/esm/beamline.yaml + equipment/detector.md: finish the loose -> graduated sweep (two residual sentences still called ElectronAnalyzer "NEW loose" / "held loose at n=1" on the same lines that say graduated). - rename the new Method x_ray_photoelectron_spectroscopy (was xray_...) to match the sibling inelastic_x_ray_scattering spelling. - SST descriptor: rename the DCM axis key crystal_x -> goni_lateral (the profile labels that PV the DCM goniometer lateral stage, not a crystal-x; the PV is unchanged). Verified: 282 deployment guards green; mkdocs build --strict; ruff full-tree clean. Co-Authored-By: Claude Opus 4.8 (1M context) --- apps/api/tests/unit/deployments/test_site_descriptor.py | 2 +- deployments/esm/beamline.yaml | 2 +- deployments/nsls2/site.yaml | 2 +- deployments/sst/beamline.yaml | 2 +- docs/deployments/esm/equipment/detector.md | 2 +- docs/deployments/sst/techniques.md | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/apps/api/tests/unit/deployments/test_site_descriptor.py b/apps/api/tests/unit/deployments/test_site_descriptor.py index 9d691a2c83..9a696f15fb 100644 --- a/apps/api/tests/unit/deployments/test_site_descriptor.py +++ b/apps/api/tests/unit/deployments/test_site_descriptor.py @@ -258,7 +258,7 @@ def test_practice_method_links_only_known() -> None: "resonant_inelastic_scattering": "SIX RIXS; soft X-ray, not yet in pilot scope (TECH-1)", "inelastic_x_ray_scattering": "IXS hard X-ray inelastic scattering; not in scope (TECH-1)", "angle_resolved_photoemission": "ESM ARPES; photoemission, not yet in pilot scope (TECH-1)", - "xray_photoelectron_spectroscopy": "SST HAXPES tender photoemission; not in scope (TECH-1)", + "x_ray_photoelectron_spectroscopy": "SST HAXPES tender photoemission; not in scope (TECH-1)", "grid_scan": "i03 MX fast grid scan; portable Method not yet earned", "mx_data_collection": "i03 MX rotation data collection; Method not yet earned", "sample_exchange": "i03 autonomous robotic sample exchange; Method not yet earned", diff --git a/deployments/esm/beamline.yaml b/deployments/esm/beamline.yaml index d41304077a..963339ac24 100644 --- a/deployments/esm/beamline.yaml +++ b/deployments/esm/beamline.yaml @@ -238,7 +238,7 @@ detectors: note: > SES is the Scienta hemispherical electron energy analyzer: the ARPES detector, photon-in / electron-out, recording electron counts over a kinetic-energy x - emission-angle window set by the pass energy and lens mode. It binds a NEW loose + emission-angle window set by the pass energy and lens mode. It binds the catalog ElectronAnalyzer Family (graduated across ESM + SST; presents Detector; no photon-detector Family fits; ARPES-1). The QuadEM electrometers are the I0 / drain-current flux monitors. devices: diff --git a/deployments/nsls2/site.yaml b/deployments/nsls2/site.yaml index 85778a2e7a..e376d3b598 100644 --- a/deployments/nsls2/site.yaml +++ b/deployments/nsls2/site.yaml @@ -69,7 +69,7 @@ practices: # Method) and HAXPES on the tender branch (a new pending photoemission Method, # distinct from ESM's angle-resolved variant). Both pending until scope (TECH-1). - {name: SST_rsoxs_practice, method: resonant_scattering, pending: true, note: "resonant soft X-ray scattering on the SST-1 RSoXS endstation; reuses the 4-ID resonant_scattering Method (TECH-1)"} - - {name: SST_haxpes_practice, method: xray_photoelectron_spectroscopy, pending: true, note: "hard / tender X-ray photoelectron spectroscopy on the SST-2 HAXPES Scienta SES analyzer; Method not yet in catalog (TECH-1)"} + - {name: SST_haxpes_practice, method: x_ray_photoelectron_spectroscopy, pending: true, note: "hard / tender X-ray photoelectron spectroscopy on the SST-2 HAXPES Scienta SES analyzer; Method not yet in catalog (TECH-1)"} # SMI's defining techniques (SAXS / WAXS / GISAXS) sit on the deferred scattering # Capabilities that Diamond i22 left pending (TECH-1); simultaneous SAXS+WAXS is # coordinated Runs not a new technique. No SMI Practice is recorded until those diff --git a/deployments/sst/beamline.yaml b/deployments/sst/beamline.yaml index 3f482c4da1..7956852d11 100644 --- a/deployments/sst/beamline.yaml +++ b/deployments/sst/beamline.yaml @@ -139,7 +139,7 @@ tender-optics: devices: - name: Monochromator_Tender family: Monochromator - pv: { bragg: "XF:07ID6-OP{Mono:DCM1-Ax:Bragg}Mtr", crystal_x: "XF:07ID6-OP{Mono:DCM1-Ax:X}Mtr", x2_perp: "XF:07ID6-OP{Mono:DCM1-Ax:Per2}Mtr", x2_pitch: "XF:07ID6-OP{Mono:DCM1-Ax:P2}Mtr" } + pv: { bragg: "XF:07ID6-OP{Mono:DCM1-Ax:Bragg}Mtr", goni_lateral: "XF:07ID6-OP{Mono:DCM1-Ax:X}Mtr", x2_perp: "XF:07ID6-OP{Mono:DCM1-Ax:Per2}Mtr", x2_pitch: "XF:07ID6-OP{Mono:DCM1-Ax:P2}Mtr" } new: true confirm: true note: "Si double-crystal mono (DCM1); crystal-select :XTAL_SEL, energy :ENERGY_SP; crystal set + range are MONO-1" diff --git a/docs/deployments/esm/equipment/detector.md b/docs/deployments/esm/equipment/detector.md index 4f99dc0984..22316709c7 100644 --- a/docs/deployments/esm/equipment/detector.md +++ b/docs/deployments/esm/equipment/detector.md @@ -13,7 +13,7 @@ The analyzer binds the **`ElectronAnalyzer` Family** (graduated across ESM + SST | `ElectronAnalyzer` | `ElectronAnalyzer` | Scienta SES hemispherical analyzer; pass-energy / lens-mode / kinetic-energy-window controls; the ARPES detector (`ARPES-1`) | | `FluxMonitor_Upstream` / `FluxMonitor_Branch` | `FluxMonitor` | QuadEM electrometers (qem01-12); I0 / drain-current monitors (`DET-1`) | -The analyzer is the defining instrument of the beamline: it measures electrons, not photons, so it sits outside the photon-detector families CORA had (`Camera`, `EnergyDispersiveSpectrometer`, `FluxMonitor`). It is held loose at n=1 until a second photoemission beamline (a future ESM XPEEM branch, or another ARPES beamline) earns it; its lens modes, pass energies, and acquisition modes are `ARPES-1`. +The analyzer is the defining instrument of the beamline: it measures electrons, not photons, so it sat outside the photon-detector families CORA had (`Camera`, `EnergyDispersiveSpectrometer`, `FluxMonitor`). ESM introduced the `ElectronAnalyzer` Family for it; it graduated into the catalog once SST (NSLS-II 7-ID HAXPES) earned the second Scienta SES. Its lens modes, pass energies, and acquisition modes are `ARPES-1`. ## Families diff --git a/docs/deployments/sst/techniques.md b/docs/deployments/sst/techniques.md index a354ff6154..9e6168bad4 100644 --- a/docs/deployments/sst/techniques.md +++ b/docs/deployments/sst/techniques.md @@ -20,7 +20,7 @@ The tender branch tunes the Si double-crystal monochromator and measures the kin | Technique | Catalog method | Notes | | --- | --- | --- | -| X-ray photoelectron spectroscopy (HAXPES) | `xray_photoelectron_spectroscopy` | tender photoemission on the [Scienta SES analyzer](equipment/detector.md); a new pending Method, distinct from ESM's angle-resolved variant | +| X-ray photoelectron spectroscopy (HAXPES) | `x_ray_photoelectron_spectroscopy` | tender photoemission on the [Scienta SES analyzer](equipment/detector.md); a new pending Method, distinct from ESM's angle-resolved variant | It needs the [tender DCM](beamline.md), the [HAXPES manipulator and slit](equipment/sample.md), and the [SES analyzer](equipment/detector.md).