From 6c57d12dbc3004308b62ddd6bda3467627e232d5 Mon Sep 17 00:00:00 2001 From: xmap <16776958+xmap@users.noreply.github.com> Date: Wed, 9 Sep 2026 10:00:17 -0500 Subject: [PATCH 1/2] Move the 93 non-pilot beamline/site descriptors to xmap/descriptors CORA has one real deployment: 2-BM. The other 93 deployments// directories (79 further beamlines, 13 further Sites) were never a deployment in any operational sense; they were CORA modeling real, named instruments at facilities it has no relationship with, from public source, to stress-test that the domain vocabulary generalizes. The website presented them with the same page-tree depth as the real pilot, which is the false-parity problem the last PR's collapse narrowed but did not fix, and the user's own framing settled it: these aren't deployments, they're descriptors, and they should not be in cora's website at all. Moved via git-filter-repo (175 commits of history preserved, deployments/ promoted to the new repo's root) to the private github.com/xmap/descriptors, minus 2-bm and aps (2-BM's Facility record), which stay. The narrative write-up each used to carry (docs/deployments//notes.md, from the last PR's merge) is deleted rather than relocated: it described a public-presentation shape that is itself being retired, not ported somewhere else to be retired later. In cora: - delete the 93 deployments// directories and their 80 docs narrative pages (2-bm's 18 real pages and index.md are untouched) - rewrite docs/deployments/index.md down to the one real deployment - collapse mkdocs.yml's Deployments nav to just APS + 2-BM's subtree (846 lines -> 35 in the prior PR -> ~10 now), and revert validation.nav.omitted_files to warn: with the fleet gone there is no longer a legitimate unlisted generated page, so the guard should bite again - drop 8ID_xpcs_practice and 9ID_xpcs_practice from aps/site.yaml: both were backed by 8-ID's and 9-ID's own descriptors, which just left; keeping the claim without the hardware behind it would be exactly the drift these fitness tests exist to catch Test suite: deleted test_pending_method_alignment.py outright (a fleet-wide IOU tracker over 93 files that are now gone; nothing 2-BM's own descriptor cites falls under it). Rewrote test_beamline_descriptor.py, test_site_descriptor.py, test_practice_derivation.py, and test_techniques_not_stale.py to drop every fleet-wide mechanism whose only subject was the departed corpus (orphan-model/loose-family/ promotion-threshold signals, the ~100-line Site-ordinal drift guard, the badge-count floor, _PENDING_METHODS entries that belonged to the 13 departed Sites) while keeping everything that exercises 2-BM's real descriptor or a synthetic fixture. The reasoning throughout: a drift guard only earns its keep against data cora's own commits can still change; re-running it forever against data cora no longer owns or edits guards nothing (see project_beamline_seeder_design's identical finding for why the analogous full-fleet seeder was never built). Also updated 8 integration/scenarios test files whose docstrings cited a now-moved deployments//beamline.yaml path (prose citations only, no runtime reads, so nothing was functionally coupled). Verified: mkdocs build --strict clean, apps/api/tests/unit (14159 tests) green, apps/api/tests/unit/deployments (113 tests, down from 830) green, xmap/descriptors confirmed private and 404 unauthenticated. --- .../test_bernina_diffractometer_setup.py | 4 +- .../scenarios/test_cdi_kb_mirror_setup.py | 4 +- .../test_cristallina_diffractometer_setup.py | 4 +- .../test_i06_diffractometer_setup.py | 5 +- .../test_i10_diffractometer_setup.py | 4 +- .../test_i19_diffractometer_setup.py | 4 +- .../test_id32_diffractometer_setup.py | 4 +- .../scenarios/test_ios_kb_mirror_setup.py | 5 +- .../deployments/test_beamline_descriptor.py | 507 ++++-------------- .../test_pending_method_alignment.py | 165 ------ .../deployments/test_practice_derivation.py | 35 +- .../unit/deployments/test_site_descriptor.py | 33 +- .../deployments/test_techniques_not_stale.py | 125 ++--- deployments/12-id/beamline.yaml | 271 ---------- deployments/13-id/beamline.yaml | 284 ---------- deployments/19-bm/beamline.yaml | 296 ---------- deployments/2-id/beamline.yaml | 185 ------- deployments/32-id/beamline.yaml | 280 ---------- deployments/4-id/beamline.yaml | 502 ----------------- deployments/7-bm/beamline.yaml | 302 ----------- deployments/8-3-2/beamline.yaml | 239 --------- deployments/8-id/beamline.yaml | 329 ------------ deployments/9-id/beamline.yaml | 315 ----------- deployments/alba/site.yaml | 68 --- deployments/als/site.yaml | 65 --- deployments/alvra/beamline.yaml | 413 -------------- deployments/amx/beamline.yaml | 243 --------- deployments/aps/site.yaml | 10 +- deployments/as/site.yaml | 75 --- deployments/bernina/beamline.yaml | 408 -------------- deployments/bmm/beamline.yaml | 229 -------- deployments/cdi/beamline.yaml | 269 ---------- deployments/chx/beamline.yaml | 262 --------- deployments/cms/beamline.yaml | 292 ---------- deployments/cristallina/beamline.yaml | 405 -------------- deployments/csx/beamline.yaml | 257 --------- deployments/diamond/site.yaml | 100 ---- deployments/elettra/site.yaml | 88 --- deployments/esm/beamline.yaml | 296 ---------- deployments/esrf/site.yaml | 90 ---- deployments/faxtor/beamline.yaml | 198 ------- deployments/fmx/beamline.yaml | 262 --------- deployments/fxi/beamline.yaml | 338 ------------ deployments/hex/beamline.yaml | 318 ----------- deployments/hxn/beamline.yaml | 272 ---------- deployments/i-tomcat/beamline.yaml | 270 ---------- deployments/i03/beamline.yaml | 327 ----------- deployments/i06/beamline.yaml | 288 ---------- deployments/i10/beamline.yaml | 356 ------------ deployments/i11/beamline.yaml | 228 -------- deployments/i13-1/beamline.yaml | 144 ----- deployments/i15-1/beamline.yaml | 304 ----------- deployments/i19/beamline.yaml | 304 ----------- deployments/i20-1/beamline.yaml | 156 ------ deployments/i22/beamline.yaml | 332 ------------ deployments/i24/beamline.yaml | 241 --------- deployments/id16b/beamline.yaml | 242 --------- deployments/id19/beamline.yaml | 272 ---------- deployments/id28/beamline.yaml | 256 --------- deployments/id32/beamline.yaml | 274 ---------- deployments/ios/beamline.yaml | 315 ----------- deployments/isr/beamline.yaml | 236 -------- deployments/iss/beamline.yaml | 271 ---------- deployments/ixs/beamline.yaml | 419 --------------- deployments/lcls-mfx/beamline.yaml | 347 ------------ deployments/lix/beamline.yaml | 354 ------------ deployments/manaca/beamline.yaml | 214 -------- deployments/maxiv/site.yaml | 59 -- deployments/mogno/beamline.yaml | 226 -------- deployments/mx3/beamline.yaml | 222 -------- deployments/nsls2/site.yaml | 206 ------- deployments/nsrrc/site.yaml | 93 ---- deployments/p01/beamline.yaml | 399 -------------- deployments/p02/beamline.yaml | 249 --------- deployments/p03/beamline.yaml | 337 ------------ deployments/p04/beamline.yaml | 279 ---------- deployments/p06/beamline.yaml | 364 ------------- deployments/p07/beamline.yaml | 259 --------- deployments/p08/beamline.yaml | 232 -------- deployments/p09/beamline.yaml | 358 ------------- deployments/p10/beamline.yaml | 391 -------------- deployments/p11/beamline.yaml | 213 -------- deployments/p13/beamline.yaml | 250 --------- deployments/p14/beamline.yaml | 334 ------------ deployments/p21/beamline.yaml | 179 ------- deployments/p22/beamline.yaml | 188 ------- deployments/p23/beamline.yaml | 131 ----- deployments/p24/beamline.yaml | 189 ------- deployments/p61/beamline.yaml | 131 ----- deployments/p64/beamline.yaml | 199 ------- deployments/p65/beamline.yaml | 175 ------ deployments/pdf/beamline.yaml | 238 -------- deployments/petra-iii/site.yaml | 183 ------- deployments/psi/site.yaml | 113 ---- deployments/sirius/site.yaml | 76 --- deployments/six/beamline.yaml | 328 ----------- deployments/slac/site.yaml | 69 --- deployments/smi/beamline.yaml | 258 --------- deployments/srx/beamline.yaml | 229 -------- deployments/sst/beamline.yaml | 267 --------- deployments/syrmep/beamline.yaml | 286 ---------- deployments/tomowise/beamline.yaml | 477 ---------------- deployments/tps-05a/beamline.yaml | 214 -------- deployments/tps-07a/beamline.yaml | 219 -------- deployments/xfm/beamline.yaml | 180 ------- deployments/xfp/beamline.yaml | 298 ---------- deployments/xpd/beamline.yaml | 222 -------- docs/deployments/12-id/notes.md | 135 ----- docs/deployments/13-id/notes.md | 176 ------ docs/deployments/19-bm/notes.md | 104 ---- docs/deployments/2-id/notes.md | 134 ----- docs/deployments/32-id/notes.md | 126 ----- docs/deployments/4-id/notes.md | 172 ------ docs/deployments/7-bm/notes.md | 117 ---- docs/deployments/8-3-2/notes.md | 128 ----- docs/deployments/8-id/notes.md | 149 ----- docs/deployments/9-id/notes.md | 145 ----- docs/deployments/alvra/notes.md | 135 ----- docs/deployments/amx/notes.md | 112 ---- docs/deployments/bernina/notes.md | 148 ----- docs/deployments/bmm/notes.md | 100 ---- docs/deployments/cdi/notes.md | 106 ---- docs/deployments/chx/notes.md | 104 ---- docs/deployments/cms/notes.md | 174 ------ docs/deployments/cristallina/notes.md | 153 ------ docs/deployments/csx/notes.md | 120 ----- docs/deployments/esm/notes.md | 105 ---- docs/deployments/faxtor/notes.md | 126 ----- docs/deployments/fmx/notes.md | 110 ---- docs/deployments/fxi/notes.md | 129 ----- docs/deployments/hex/notes.md | 191 ------- docs/deployments/hxn/notes.md | 101 ---- docs/deployments/i-tomcat/notes.md | 114 ---- docs/deployments/i03/notes.md | 118 ---- docs/deployments/i06/notes.md | 210 -------- docs/deployments/i10/notes.md | 225 -------- docs/deployments/i11/notes.md | 105 ---- docs/deployments/i13-1/notes.md | 157 ------ docs/deployments/i15-1/notes.md | 103 ---- docs/deployments/i19/notes.md | 188 ------- docs/deployments/i20-1/notes.md | 95 ---- docs/deployments/i22/notes.md | 111 ---- docs/deployments/i24/notes.md | 133 ----- docs/deployments/id16b/notes.md | 175 ------ docs/deployments/id19/notes.md | 178 ------ docs/deployments/id28/notes.md | 129 ----- docs/deployments/id32/notes.md | 143 ----- docs/deployments/index.md | 185 +------ docs/deployments/ios/notes.md | 167 ------ docs/deployments/isr/notes.md | 150 ------ docs/deployments/iss/notes.md | 106 ---- docs/deployments/ixs/notes.md | 142 ----- docs/deployments/lcls-mfx/notes.md | 136 ----- docs/deployments/lix/notes.md | 180 ------- docs/deployments/manaca/notes.md | 133 ----- docs/deployments/mogno/notes.md | 137 ----- docs/deployments/mx3/notes.md | 108 ---- docs/deployments/p01/notes.md | 143 ----- docs/deployments/p02/notes.md | 144 ----- docs/deployments/p03/notes.md | 134 ----- docs/deployments/p04/notes.md | 128 ----- docs/deployments/p06/notes.md | 135 ----- docs/deployments/p07/notes.md | 138 ----- docs/deployments/p08/notes.md | 124 ----- docs/deployments/p09/notes.md | 139 ----- docs/deployments/p10/notes.md | 135 ----- docs/deployments/p11/notes.md | 138 ----- docs/deployments/p13/notes.md | 140 ----- docs/deployments/p14/notes.md | 148 ----- docs/deployments/p21/notes.md | 124 ----- docs/deployments/p22/notes.md | 119 ---- docs/deployments/p23/notes.md | 117 ---- docs/deployments/p24/notes.md | 123 ----- docs/deployments/p61/notes.md | 119 ---- docs/deployments/p64/notes.md | 114 ---- docs/deployments/p65/notes.md | 118 ---- docs/deployments/pdf/notes.md | 110 ---- docs/deployments/six/notes.md | 118 ---- docs/deployments/smi/notes.md | 109 ---- docs/deployments/srx/notes.md | 96 ---- docs/deployments/sst/notes.md | 104 ---- docs/deployments/syrmep/notes.md | 155 ------ docs/deployments/tomowise/notes.md | 94 ---- docs/deployments/tps-05a/notes.md | 118 ---- docs/deployments/tps-07a/notes.md | 115 ---- docs/deployments/xfm/notes.md | 106 ---- docs/deployments/xfp/notes.md | 181 ------- docs/deployments/xpd/notes.md | 109 ---- mkdocs.yml | 18 +- 189 files changed, 196 insertions(+), 34975 deletions(-) delete mode 100644 apps/api/tests/unit/deployments/test_pending_method_alignment.py delete mode 100644 deployments/12-id/beamline.yaml delete mode 100644 deployments/13-id/beamline.yaml delete mode 100644 deployments/19-bm/beamline.yaml delete mode 100644 deployments/2-id/beamline.yaml delete mode 100644 deployments/32-id/beamline.yaml delete mode 100644 deployments/4-id/beamline.yaml delete mode 100644 deployments/7-bm/beamline.yaml delete mode 100644 deployments/8-3-2/beamline.yaml delete mode 100644 deployments/8-id/beamline.yaml delete mode 100644 deployments/9-id/beamline.yaml delete mode 100644 deployments/alba/site.yaml delete mode 100644 deployments/als/site.yaml delete mode 100644 deployments/alvra/beamline.yaml delete mode 100644 deployments/amx/beamline.yaml delete mode 100644 deployments/as/site.yaml delete mode 100644 deployments/bernina/beamline.yaml delete mode 100644 deployments/bmm/beamline.yaml delete mode 100644 deployments/cdi/beamline.yaml delete mode 100644 deployments/chx/beamline.yaml delete mode 100644 deployments/cms/beamline.yaml delete mode 100644 deployments/cristallina/beamline.yaml delete mode 100644 deployments/csx/beamline.yaml delete mode 100644 deployments/diamond/site.yaml delete mode 100644 deployments/elettra/site.yaml delete mode 100644 deployments/esm/beamline.yaml delete mode 100644 deployments/esrf/site.yaml delete mode 100644 deployments/faxtor/beamline.yaml delete mode 100644 deployments/fmx/beamline.yaml delete mode 100644 deployments/fxi/beamline.yaml delete mode 100644 deployments/hex/beamline.yaml delete mode 100644 deployments/hxn/beamline.yaml delete mode 100644 deployments/i-tomcat/beamline.yaml delete mode 100644 deployments/i03/beamline.yaml delete mode 100644 deployments/i06/beamline.yaml delete mode 100644 deployments/i10/beamline.yaml delete mode 100644 deployments/i11/beamline.yaml delete mode 100644 deployments/i13-1/beamline.yaml delete mode 100644 deployments/i15-1/beamline.yaml delete mode 100644 deployments/i19/beamline.yaml delete mode 100644 deployments/i20-1/beamline.yaml delete mode 100644 deployments/i22/beamline.yaml delete mode 100644 deployments/i24/beamline.yaml delete mode 100644 deployments/id16b/beamline.yaml delete mode 100644 deployments/id19/beamline.yaml delete mode 100644 deployments/id28/beamline.yaml delete mode 100644 deployments/id32/beamline.yaml delete mode 100644 deployments/ios/beamline.yaml delete mode 100644 deployments/isr/beamline.yaml delete mode 100644 deployments/iss/beamline.yaml delete mode 100644 deployments/ixs/beamline.yaml delete mode 100644 deployments/lcls-mfx/beamline.yaml delete mode 100644 deployments/lix/beamline.yaml delete mode 100644 deployments/manaca/beamline.yaml delete mode 100644 deployments/maxiv/site.yaml delete mode 100644 deployments/mogno/beamline.yaml delete mode 100644 deployments/mx3/beamline.yaml delete mode 100644 deployments/nsls2/site.yaml delete mode 100644 deployments/nsrrc/site.yaml delete mode 100644 deployments/p01/beamline.yaml delete mode 100644 deployments/p02/beamline.yaml delete mode 100644 deployments/p03/beamline.yaml delete mode 100644 deployments/p04/beamline.yaml delete mode 100644 deployments/p06/beamline.yaml delete mode 100644 deployments/p07/beamline.yaml delete mode 100644 deployments/p08/beamline.yaml delete mode 100644 deployments/p09/beamline.yaml delete mode 100644 deployments/p10/beamline.yaml delete mode 100644 deployments/p11/beamline.yaml delete mode 100644 deployments/p13/beamline.yaml delete mode 100644 deployments/p14/beamline.yaml delete mode 100644 deployments/p21/beamline.yaml delete mode 100644 deployments/p22/beamline.yaml delete mode 100644 deployments/p23/beamline.yaml delete mode 100644 deployments/p24/beamline.yaml delete mode 100644 deployments/p61/beamline.yaml delete mode 100644 deployments/p64/beamline.yaml delete mode 100644 deployments/p65/beamline.yaml delete mode 100644 deployments/pdf/beamline.yaml delete mode 100644 deployments/petra-iii/site.yaml delete mode 100644 deployments/psi/site.yaml delete mode 100644 deployments/sirius/site.yaml delete mode 100644 deployments/six/beamline.yaml delete mode 100644 deployments/slac/site.yaml delete mode 100644 deployments/smi/beamline.yaml delete mode 100644 deployments/srx/beamline.yaml delete mode 100644 deployments/sst/beamline.yaml delete mode 100644 deployments/syrmep/beamline.yaml delete mode 100644 deployments/tomowise/beamline.yaml delete mode 100644 deployments/tps-05a/beamline.yaml delete mode 100644 deployments/tps-07a/beamline.yaml delete mode 100644 deployments/xfm/beamline.yaml delete mode 100644 deployments/xfp/beamline.yaml delete mode 100644 deployments/xpd/beamline.yaml delete mode 100644 docs/deployments/12-id/notes.md delete mode 100644 docs/deployments/13-id/notes.md delete mode 100644 docs/deployments/19-bm/notes.md delete mode 100644 docs/deployments/2-id/notes.md delete mode 100644 docs/deployments/32-id/notes.md delete mode 100644 docs/deployments/4-id/notes.md delete mode 100644 docs/deployments/7-bm/notes.md delete mode 100644 docs/deployments/8-3-2/notes.md delete mode 100644 docs/deployments/8-id/notes.md delete mode 100644 docs/deployments/9-id/notes.md delete mode 100644 docs/deployments/alvra/notes.md delete mode 100644 docs/deployments/amx/notes.md delete mode 100644 docs/deployments/bernina/notes.md delete mode 100644 docs/deployments/bmm/notes.md delete mode 100644 docs/deployments/cdi/notes.md delete mode 100644 docs/deployments/chx/notes.md delete mode 100644 docs/deployments/cms/notes.md delete mode 100644 docs/deployments/cristallina/notes.md delete mode 100644 docs/deployments/csx/notes.md delete mode 100644 docs/deployments/esm/notes.md delete mode 100644 docs/deployments/faxtor/notes.md delete mode 100644 docs/deployments/fmx/notes.md delete mode 100644 docs/deployments/fxi/notes.md delete mode 100644 docs/deployments/hex/notes.md delete mode 100644 docs/deployments/hxn/notes.md delete mode 100644 docs/deployments/i-tomcat/notes.md delete mode 100644 docs/deployments/i03/notes.md delete mode 100644 docs/deployments/i06/notes.md delete mode 100644 docs/deployments/i10/notes.md delete mode 100644 docs/deployments/i11/notes.md delete mode 100644 docs/deployments/i13-1/notes.md delete mode 100644 docs/deployments/i15-1/notes.md delete mode 100644 docs/deployments/i19/notes.md delete mode 100644 docs/deployments/i20-1/notes.md delete mode 100644 docs/deployments/i22/notes.md delete mode 100644 docs/deployments/i24/notes.md delete mode 100644 docs/deployments/id16b/notes.md delete mode 100644 docs/deployments/id19/notes.md delete mode 100644 docs/deployments/id28/notes.md delete mode 100644 docs/deployments/id32/notes.md delete mode 100644 docs/deployments/ios/notes.md delete mode 100644 docs/deployments/isr/notes.md delete mode 100644 docs/deployments/iss/notes.md delete mode 100644 docs/deployments/ixs/notes.md delete mode 100644 docs/deployments/lcls-mfx/notes.md delete mode 100644 docs/deployments/lix/notes.md delete mode 100644 docs/deployments/manaca/notes.md delete mode 100644 docs/deployments/mogno/notes.md delete mode 100644 docs/deployments/mx3/notes.md delete mode 100644 docs/deployments/p01/notes.md delete mode 100644 docs/deployments/p02/notes.md delete mode 100644 docs/deployments/p03/notes.md delete mode 100644 docs/deployments/p04/notes.md delete mode 100644 docs/deployments/p06/notes.md delete mode 100644 docs/deployments/p07/notes.md delete mode 100644 docs/deployments/p08/notes.md delete mode 100644 docs/deployments/p09/notes.md delete mode 100644 docs/deployments/p10/notes.md delete mode 100644 docs/deployments/p11/notes.md delete mode 100644 docs/deployments/p13/notes.md delete mode 100644 docs/deployments/p14/notes.md delete mode 100644 docs/deployments/p21/notes.md delete mode 100644 docs/deployments/p22/notes.md delete mode 100644 docs/deployments/p23/notes.md delete mode 100644 docs/deployments/p24/notes.md delete mode 100644 docs/deployments/p61/notes.md delete mode 100644 docs/deployments/p64/notes.md delete mode 100644 docs/deployments/p65/notes.md delete mode 100644 docs/deployments/pdf/notes.md delete mode 100644 docs/deployments/six/notes.md delete mode 100644 docs/deployments/smi/notes.md delete mode 100644 docs/deployments/srx/notes.md delete mode 100644 docs/deployments/sst/notes.md delete mode 100644 docs/deployments/syrmep/notes.md delete mode 100644 docs/deployments/tomowise/notes.md delete mode 100644 docs/deployments/tps-05a/notes.md delete mode 100644 docs/deployments/tps-07a/notes.md delete mode 100644 docs/deployments/xfm/notes.md delete mode 100644 docs/deployments/xfp/notes.md delete mode 100644 docs/deployments/xpd/notes.md diff --git a/apps/api/tests/integration/scenarios/test_bernina_diffractometer_setup.py b/apps/api/tests/integration/scenarios/test_bernina_diffractometer_setup.py index a9676712b51..b97918627cb 100644 --- a/apps/api/tests/integration/scenarios/test_bernina_diffractometer_setup.py +++ b/apps/api/tests/integration/scenarios/test_bernina_diffractometer_setup.py @@ -10,7 +10,7 @@ end-to-end against Postgres. The blueprint was earned across 4-ID + 8-ID and graduated to the catalog; this scenario proves it composes at a non-APS facility from the assets Bernina's deployment descriptor actually carries -(`deployments/bernina/beamline.yaml`, DIFF-1), rather than re-modelling the +(`bernina/beamline.yaml` in the private xmap/descriptors repo, DIFF-1), rather than re-modelling the sample circles per platform. Bernina runs two independent diffractometer platforms (eco gps + eco xrd), so @@ -83,7 +83,7 @@ _CAP_PSEUDO_AXIS_ID = family_stream_id(FamilyName("PseudoAxis")) # The five diffractometer constituent Assets (scenario-supplied ids), mirroring -# the named devices in deployments/bernina/beamline.yaml. GPS carries a goniometer +# the named devices in bernina/beamline.yaml (now in xmap/descriptors). GPS carries a goniometer # + reciprocal-space (no modelled detector arm); XRD carries all three. _ASSET_GPS_GONIOMETER_ID = UUID("01900000-0000-7000-8000-000000be0a11") _ASSET_GPS_RECIPROCAL_SPACE_ID = UUID("01900000-0000-7000-8000-000000be0a21") diff --git a/apps/api/tests/integration/scenarios/test_cdi_kb_mirror_setup.py b/apps/api/tests/integration/scenarios/test_cdi_kb_mirror_setup.py index 4feb2d45bfa..e9d36088d50 100644 --- a/apps/api/tests/integration/scenarios/test_cdi_kb_mirror_setup.py +++ b/apps/api/tests/integration/scenarios/test_cdi_kb_mirror_setup.py @@ -8,7 +8,7 @@ Materializes CDI's Kirkpatrick-Baez nanofocusing mirror pair as the FIRST binding of the catalog KirkpatrickBaez Assembly (which shipped with zero Fixtures), end-to-end against Postgres, from the assets CDI's deployment descriptor carries -(`deployments/cdi/beamline.yaml`, KB-1). +(`cdi/beamline.yaml` in the private xmap/descriptors repo, KB-1). CDI's descriptor collapses the pair into ONE `KBMirror` Mirror Asset, but its note names both physical mirrors with their real PVs: a vertical VKB at `Mir:KBv` and a @@ -70,7 +70,7 @@ _CAP_MIRROR_ID = family_stream_id(FamilyName("Mirror")) # The two KB mirror Assets (scenario-supplied ids), split from the collapsed -# `KBMirror` device in deployments/cdi/beamline.yaml per its note (Mir:KBv + +# `KBMirror` device in cdi/beamline.yaml (now in xmap/descriptors) per its note (Mir:KBv + # Mir:KBh) and the catalog KirkpatrickBaez split-on-materialize sanction. _ASSET_VKB_ID = UUID("01900000-0000-7000-8000-000000cd0a11") _ASSET_HKB_ID = UUID("01900000-0000-7000-8000-000000cd0a21") diff --git a/apps/api/tests/integration/scenarios/test_cristallina_diffractometer_setup.py b/apps/api/tests/integration/scenarios/test_cristallina_diffractometer_setup.py index fa0aca08de1..607cea80576 100644 --- a/apps/api/tests/integration/scenarios/test_cristallina_diffractometer_setup.py +++ b/apps/api/tests/integration/scenarios/test_cristallina_diffractometer_setup.py @@ -8,7 +8,7 @@ Materializes Cristallina's DM1 diffractometer as a THIRD independent binding of the Assembly(Diffractometer) blueprint (after 8-ID and Bernina), end-to-end against Postgres, from the assets Cristallina's deployment descriptor actually -carries (`deployments/cristallina/beamline.yaml`, DIFF-1). +carries (`cristallina/beamline.yaml` in the private xmap/descriptors repo, DIFF-1). Cristallina instantiates two diffractometer platforms in slic (DM1 + DM2), but only DM1 is materializable from the descriptor: @@ -78,7 +78,7 @@ _CAP_PSEUDO_AXIS_ID = family_stream_id(FamilyName("PseudoAxis")) # The three DM1 constituent Assets (scenario-supplied ids), mirroring the named -# devices in deployments/cristallina/beamline.yaml. DM2 is not materialized +# devices in cristallina/beamline.yaml (now in xmap/descriptors). DM2 is not materialized # (goniometer-only, DISABLED-1, no reciprocal-space Asset; see module docstring). _ASSET_DM1_GONIOMETER_ID = UUID("01900000-0000-7000-8000-000000ca0a11") _ASSET_DM1_DETECTOR_ARM_ID = UUID("01900000-0000-7000-8000-000000ca0a21") diff --git a/apps/api/tests/integration/scenarios/test_i06_diffractometer_setup.py b/apps/api/tests/integration/scenarios/test_i06_diffractometer_setup.py index 672a3cb2954..96bdb85812c 100644 --- a/apps/api/tests/integration/scenarios/test_i06_diffractometer_setup.py +++ b/apps/api/tests/integration/scenarios/test_i06_diffractometer_setup.py @@ -7,7 +7,8 @@ Materializes Diamond i06's diffraction-dichroism diffractometer as a binding of the catalog Diffractometer Assembly, end-to-end against Postgres, from the assets -i06's deployment descriptor carries (`deployments/i06/beamline.yaml`, DIFF-1). +i06's deployment descriptor carries (`i06/beamline.yaml` in the private +xmap/descriptors repo, DIFF-1). This extends the blueprint beyond the hard X-ray six-circle it was earned on (4-ID + 8-ID) and the SwissFEL platforms (Bernina + Cristallina) to a soft X-ray @@ -73,7 +74,7 @@ _CAP_PSEUDO_AXIS_ID = family_stream_id(FamilyName("PseudoAxis")) # The two constituent Assets (scenario-supplied ids), mirroring the named devices -# in deployments/i06/beamline.yaml. +# in i06/beamline.yaml (now in xmap/descriptors). _ASSET_GONIOMETER_ID = UUID("01900000-0000-7000-8000-000000060a11") _ASSET_RECIPROCAL_SPACE_ID = UUID("01900000-0000-7000-8000-000000060a21") diff --git a/apps/api/tests/integration/scenarios/test_i10_diffractometer_setup.py b/apps/api/tests/integration/scenarios/test_i10_diffractometer_setup.py index 19121982256..6638771c0e0 100644 --- a/apps/api/tests/integration/scenarios/test_i10_diffractometer_setup.py +++ b/apps/api/tests/integration/scenarios/test_i10_diffractometer_setup.py @@ -8,7 +8,7 @@ Materializes Diamond i10's RASOR sample diffractometer (two-theta scattering arm, sample theta / chi, chamber X, alpha) as a binding of the catalog Diffractometer Assembly, end-to-end against Postgres, from the assets i10's deployment descriptor -carries (`deployments/i10/beamline.yaml`, DIFF-1). +carries (`i10/beamline.yaml` in the private xmap/descriptors repo, DIFF-1). This extends the blueprint beyond the hard X-ray six-circle it was earned on (4-ID + 8-ID) and the SwissFEL platforms (Bernina + Cristallina) to a soft X-ray @@ -74,7 +74,7 @@ _CAP_PSEUDO_AXIS_ID = family_stream_id(FamilyName("PseudoAxis")) # The two constituent Assets (scenario-supplied ids), mirroring the named devices -# in deployments/i10/beamline.yaml. +# in i10/beamline.yaml (now in xmap/descriptors). _ASSET_GONIOMETER_ID = UUID("01900000-0000-7000-8000-000000100a11") _ASSET_RECIPROCAL_SPACE_ID = UUID("01900000-0000-7000-8000-000000100a21") diff --git a/apps/api/tests/integration/scenarios/test_i19_diffractometer_setup.py b/apps/api/tests/integration/scenarios/test_i19_diffractometer_setup.py index aabf4df2ee5..f484f76c723 100644 --- a/apps/api/tests/integration/scenarios/test_i19_diffractometer_setup.py +++ b/apps/api/tests/integration/scenarios/test_i19_diffractometer_setup.py @@ -8,7 +8,7 @@ Materializes Diamond i19's Newport kappa four-circle diffractometer (phi / omega / kappa sample circles + the 2THETA detector arm + det_z) as a binding of the catalog Diffractometer Assembly, end-to-end against Postgres, from the assets i19's -deployment descriptor carries (`deployments/i19/beamline.yaml`, DIFF-1). +deployment descriptor carries (`i19/beamline.yaml` in the private xmap/descriptors repo, DIFF-1). This is a fifth independent binding of the one blueprint (after 4-ID + 8-ID + Bernina + Cristallina), a hard X-ray kappa-geometry small-molecule instrument: @@ -75,7 +75,7 @@ _CAP_PSEUDO_AXIS_ID = family_stream_id(FamilyName("PseudoAxis")) # The two constituent Assets (scenario-supplied ids), mirroring the named devices -# in deployments/i19/beamline.yaml. +# in i19/beamline.yaml (now in xmap/descriptors). _ASSET_GONIOMETER_ID = UUID("01900000-0000-7000-8000-000000190a11") _ASSET_RECIPROCAL_SPACE_ID = UUID("01900000-0000-7000-8000-000000190a21") diff --git a/apps/api/tests/integration/scenarios/test_id32_diffractometer_setup.py b/apps/api/tests/integration/scenarios/test_id32_diffractometer_setup.py index 66209c11b98..1b6a6de186c 100644 --- a/apps/api/tests/integration/scenarios/test_id32_diffractometer_setup.py +++ b/apps/api/tests/integration/scenarios/test_id32_diffractometer_setup.py @@ -8,7 +8,7 @@ Materializes ESRF ID32's four-circle sample diffractometer (BLISS DiffE4CH, E4CH geometry) as a binding of the catalog Diffractometer Assembly, end-to-end against Postgres, from the assets ID32's deployment descriptor carries -(`deployments/id32/beamline.yaml`, DIFF-1). +(`id32/beamline.yaml` in the private xmap/descriptors repo, DIFF-1). This extends the blueprint beyond the hard X-ray six-circle it was earned on (4-ID + 8-ID) and the SwissFEL platforms (Bernina + Cristallina) to an ESRF soft @@ -73,7 +73,7 @@ _CAP_PSEUDO_AXIS_ID = family_stream_id(FamilyName("PseudoAxis")) # The two constituent Assets (scenario-supplied ids), mirroring the named devices -# in deployments/id32/beamline.yaml. +# in id32/beamline.yaml (now in xmap/descriptors). _ASSET_GONIOMETER_ID = UUID("01900000-0000-7000-8000-000000320a11") _ASSET_RECIPROCAL_SPACE_ID = UUID("01900000-0000-7000-8000-000000320a21") diff --git a/apps/api/tests/integration/scenarios/test_ios_kb_mirror_setup.py b/apps/api/tests/integration/scenarios/test_ios_kb_mirror_setup.py index 4646b6fddd3..1c9d73bf449 100644 --- a/apps/api/tests/integration/scenarios/test_ios_kb_mirror_setup.py +++ b/apps/api/tests/integration/scenarios/test_ios_kb_mirror_setup.py @@ -7,7 +7,8 @@ Materializes IOS's Kirkpatrick-Baez focusing mirror pair as a binding of the catalog KirkpatrickBaez Assembly, end-to-end against Postgres, from the assets -IOS's deployment descriptor carries (`deployments/ios/beamline.yaml`, OPT-1). +IOS's deployment descriptor carries (`ios/beamline.yaml` in the private +xmap/descriptors repo, OPT-1). Unlike CDI (which collapses its KB pair into one Asset that the Fixture splits), IOS's descriptor already models the two mirrors as distinct Mirror Assets, so the @@ -62,7 +63,7 @@ _CAP_MIRROR_ID = family_stream_id(FamilyName("Mirror")) # The two KB mirror Assets (scenario-supplied ids), mirroring the distinct named -# devices in deployments/ios/beamline.yaml. +# devices in ios/beamline.yaml (now in xmap/descriptors). _ASSET_VKB_ID = UUID("01900000-0000-7000-8000-000000e50a11") _ASSET_HKB_ID = UUID("01900000-0000-7000-8000-000000e50a21") diff --git a/apps/api/tests/unit/deployments/test_beamline_descriptor.py b/apps/api/tests/unit/deployments/test_beamline_descriptor.py index 7d7e1226757..52067a6f88e 100644 --- a/apps/api/tests/unit/deployments/test_beamline_descriptor.py +++ b/apps/api/tests/unit/deployments/test_beamline_descriptor.py @@ -7,6 +7,16 @@ fails loudly. It is a pure parser test (no I/O beyond reading the file), hence the unit tier. +2-BM is the one deployment cora carries: the further 93 beamlines this file +used to stress-test the catalog vocabulary against (orphan-model, loose-family, +and Site-ordinal drift guards) moved to the private xmap/descriptors repo, and +that stress-test value left with them. A guard against drift in data cora no +longer owns or edits was not guarding anything real; see +project_beamline_seeder_design's reasoning for why the analogous full-fleet +seeder was never built for the same reason. The tests below either exercise +2-BM directly or a synthetic fixture, so they stay meaningful with one real +deployment in the repo. + The scripts/ modules are loaded via importlib (the dynamic-import bridge used by tests/integration/scenarios/conftest.py), since scripts/ is not on the type-checker's path. @@ -38,9 +48,9 @@ def _beamline_descriptors() -> list[Path]: - # Every deployment's beamline descriptor. The catalog cross-checks run per - # descriptor so a second beamline cannot drift its model/family bindings - # unguarded; the 2-BM-only _DESCRIPTOR is kept for 2-BM-specific content. + # Every deployment cora carries (2-BM today). Kept as a glob rather than a + # hardcoded [_DESCRIPTOR] so a future beamline added back to cora is + # auto-enrolled in the catalog cross-checks below without editing this file. return sorted(_DEPLOYMENTS.glob("*/beamline.yaml")) @@ -204,22 +214,47 @@ def _render_all_pages(slug: str) -> dict[str, str]: ) -def test_stages_layout_dissolves_inventory_into_flat_stage_pages() -> None: - # SRX opts into page_layout: stages: Inventory is dissolved into flat - # source/sample/detector/controls siblings, with no equipment/ folder and no - # beamline.md or inventory.md. - pages = _render_all_pages("srx") - assert "deployments/srx/source.md" in pages - assert "deployments/srx/sample.md" in pages - assert "deployments/srx/detector.md" in pages - assert "deployments/srx/controls.md" in pages - assert "deployments/srx/beamline.md" not in pages - assert "deployments/srx/inventory.md" not in pages - assert not any(path.startswith("deployments/srx/equipment/") for path in pages) +_SYNTHETIC_STAGES_MODEL = ( + "beamline:\n" + " name: Synthetic\n" + " maturity: model\n" + " evidence: controls_config\n" + " coverage: full\n" + " page_layout: stages\n" + " shape: A synthetic stages-layout model beamline, for pinning the generator.\n" + "source:\n" + " stage: source\n" + " devices:\n" + " - {name: SynMotor, family: LinearStage, pv: 'syn:m1'}\n" + "sample:\n" + " stage: sample\n" + " devices: []\n" + "detector:\n" + " stage: detection\n" + " devices: []\n" +) + + +def test_stages_layout_dissolves_inventory_into_flat_stage_pages(tmp_path: Path) -> None: + # A model-tier beamline with page_layout: stages dissolves Inventory into + # flat source/sample/detector/controls siblings, with no equipment/ folder + # and no beamline.md or inventory.md. Pinned with a synthetic descriptor + # (the real fleet exercising this layout now lives in xmap/descriptors). + path = tmp_path / "beamline.yaml" + path.write_text(_SYNTHETIC_STAGES_MODEL, encoding="utf-8") + descriptor = bd.load(path) + pages = bp.render_all(descriptor, slug="syn", model_tier=True) + assert "deployments/syn/source.md" in pages + assert "deployments/syn/sample.md" in pages + assert "deployments/syn/detector.md" in pages + assert "deployments/syn/controls.md" in pages + assert "deployments/syn/beamline.md" not in pages + assert "deployments/syn/inventory.md" not in pages + assert not any(p.startswith("deployments/syn/equipment/") for p in pages) # the flat source page is the source stage itself, with no Inventory pointer # and none of the walk-layout framing (no "walk", no composed-fixture pages, # and no dangling Operations reference, which is not a page in this layout) - source = pages["deployments/srx/source.md"] + source = pages["deployments/syn/source.md"] assert source.startswith("# Source") assert "inventory.md" not in source assert "walk" not in source.lower() @@ -230,74 +265,57 @@ def test_stages_layout_dissolves_inventory_into_flat_stage_pages() -> None: # off the Source page in the stages layout. assert "## Enclosures" not in source # the index presents the stages as first-class sibling pages, not a "Walk the - # beam" spine, carries the Enclosures table, and no longer points at Inventory - index = pages["deployments/srx/index.md"] + # beam" spine, and no longer points at Inventory + index = pages["deployments/syn/index.md"] assert "[Source](source.md)" in index assert "Walk the beam" not in index assert "## The beamline" in index - assert "## Enclosures" in index - assert "`5-ID-A`" in index assert "inventory.md" not in index assert "equipment/" not in index -def _model_stages_slugs() -> list[str]: - # Model-tier beamlines on the stages layout: these generate their whole - # reader set (index + flat stage pages) from the descriptor. Pilots also use - # the stages layout but hand-author index / sample / detector, so they are - # excluded from the generated-content guarantees below. - slugs: list[str] = [] - for path in sorted(_DEPLOYMENTS.glob("*/beamline.yaml")): - b = bd.load(path).beamline - if b.page_layout == "stages" and b.deployment_tier == "model": - slugs.append(path.parent.name) - return slugs - - -@pytest.mark.parametrize("slug", _model_stages_slugs()) -def test_stages_layout_preserves_shape_and_all_devices(slug: str) -> None: - # Every model-tier stages beamline must carry a one-line defining-shape - # sentence (the one bespoke line generation cannot reconstruct) as the lead - # of its generated index's beamline section, and every modelled device must - # still appear across the flat stage pages, so a migration cannot drop content. - descriptor = bd.load(_DEPLOYMENTS / slug / "beamline.yaml") - assert descriptor.beamline.shape, f"{slug}: stages layout without a shape line" - pages = _render_all_pages(slug) - index = pages[f"deployments/{slug}/index.md"] - assert descriptor.beamline.shape.strip() in index, f"{slug}: shape line missing from index" - joined = "\n".join(pages.values()) - for _name, group in descriptor.groups: - for device in group.devices: - if device.name and not device.new: - assert f"`{device.name}`" in joined, f"{slug}: {device.name} lost from pages" - - def test_pilot_stages_layout_generates_only_flat_source() -> None: # A pilot on the stages layout generates ONLY its Source page (flat source.md); # its index, sample, detector, controls, and operational pages are hand-authored. - # 2-BM is the sole operational pilot (FXI is reverse-engineered, so model-tier). pages = _render_all_pages("2-bm") assert set(pages) == {"deployments/2-bm/source.md"}, sorted(pages) assert pages["deployments/2-bm/source.md"].startswith("# Source") -def test_source_ref_renders_as_provenance_link_in_banner() -> None: - # A beamline with a source_ref surfaces it in the generated-from banner as a - # link, so a reader can trace the facts to the public source they came from. - descriptor = bd.load(_DEPLOYMENTS / "hxn" / "beamline.yaml") - ref = descriptor.beamline.source_ref - assert ref is not None, "hxn should carry a source_ref" - banner_page = _render_all_pages("hxn")["deployments/hxn/index.md"] - assert f"[{ref.label}]({ref.url})" in banner_page +_SYNTHETIC_SOURCE_REF_MODEL = ( + "beamline:\n" + " name: Synthetic\n" + " maturity: model\n" + " evidence: controls_config\n" + " coverage: full\n" + " page_layout: stages\n" + " shape: A synthetic stages-layout model beamline with a source_ref.\n" + " source_ref:\n" + ' label: "org/repo"\n' + ' url: "https://example.test/org/repo"\n' + "source:\n" + " stage: source\n" + " devices: []\n" +) + + +def test_source_ref_renders_as_provenance_link_on_index_not_source(tmp_path: Path) -> None: + # A model-tier beamline with a source_ref surfaces it in the index's + # generated-from banner as a link, so a reader can trace the facts to the + # public source they came from, and does NOT duplicate it on the Source + # page (that placement is reserved for a pilot, see the test below). + path = tmp_path / "beamline.yaml" + path.write_text(_SYNTHETIC_SOURCE_REF_MODEL, encoding="utf-8") + descriptor = bd.load(path) + pages = bp.render_all(descriptor, slug="syn", model_tier=True) + assert "[org/repo](https://example.test/org/repo)" in pages["deployments/syn/index.md"] + assert "Source: [" not in pages["deployments/syn/source.md"] -def test_pilot_source_ref_surfaces_on_source_page_not_duplicated_on_model_tier( - tmp_path: Path, -) -> None: +def test_pilot_source_ref_surfaces_on_source_page(tmp_path: Path) -> None: # A pilot has no generated index, so its Source page is the only place a - # source_ref can land; a model-tier beamline shows it on the index and must - # NOT duplicate it on the source page. No real pilot currently carries a - # source_ref (2-BM is live), so render a synthetic pilot to pin the path. + # source_ref can land. No real pilot currently carries a source_ref (2-BM + # is live), so render a synthetic pilot to pin the path. descriptor_yaml = ( "beamline:\n" " name: T\n" @@ -318,8 +336,6 @@ def test_pilot_source_ref_surfaces_on_source_page_not_duplicated_on_model_tier( descriptor = bd.load(path) pages = bp.render_all(descriptor, slug="t", model_tier=False) assert "[org/repo](https://example.test/org/repo)" in pages["deployments/t/source.md"] - # a model-tier beamline keeps its source page free of the pointer (on the index) - assert "Source: [" not in _render_all_pages("hxn")["deployments/hxn/source.md"] def test_live_pilot_has_no_source_ref() -> None: @@ -335,9 +351,8 @@ def test_live_pilot_has_no_source_ref() -> None: def test_walk_layout_keeps_beamline_and_inventory_pages(tmp_path: Path) -> None: # The walk layout (page_layout omitted -> "walk") still emits beamline.md, # inventory.md, and the equipment/ stage pages with a "Walk the beam" spine. - # The whole real fleet has migrated to the stages layout (only the 2-BM pilot - # keeps a non-stages generated set), so this pins the walk path with a - # synthetic model-tier descriptor rather than a real beamline. + # 2-BM (the only real deployment left) uses the stages layout, so this pins + # the walk path with a synthetic model-tier descriptor. descriptor_yaml = ( "beamline:\n" " name: W\n" @@ -440,18 +455,6 @@ def test_device_family_is_declared_by_its_bound_model(descriptor_path: Path) -> ) -# Catalog models bound by no deployment device today. Each is a rename-trap -# landing pad, so a NEW orphan must be bound, removed, or added here with a -# reason. The two non-kit entries are catalog models whose 2-BM devices are not -# yet model-bound (a descriptor follow-up, distinct from the kit alternatives). -_ALLOWED_ORPHAN_MODELS = { - "aerotech_abrs150mp": "rotary swap-kit alternative; installed rotary is ABRS-250MP", - "aerotech_abs2000": "rotary swap-kit alternative; installed rotary is ABRS-250MP", - "mitutoyo_plan_apo": "objective product-line model; Objective_* devices not yet model-bound", - "crytur_luag": "scintillator model; Scintillator device not yet model-bound", -} - - def _count_binding_keys(node: Any) -> dict[str, int]: # Count mappings carrying a non-null model:/family: anywhere in the raw YAML. # Compared against the typed walk to catch a binding hidden under an untyped @@ -490,121 +493,6 @@ def _catalog_marker_models(md_path: Path) -> list[str]: return names -def test_no_unexpected_orphan_catalog_models() -> None: - catalog = cd.load(_CATALOG) - bound = { - device.model - for path in _beamline_descriptors() - for device in _walk_devices(bd.load(path)) - if device.model - } - orphans = {m.name for m in catalog.models} - bound - unexpected = orphans - set(_ALLOWED_ORPHAN_MODELS) - assert not unexpected, ( - "catalog models bound by no deployment device (rename-trap landing pads); " - f"bind, remove, or allowlist with a reason: {sorted(unexpected)}" - ) - stale_allowlist = set(_ALLOWED_ORPHAN_MODELS) - orphans - assert not stale_allowlist, ( - f"bound or removed; drop from _ALLOWED_ORPHAN_MODELS: {sorted(stale_allowlist)}" - ) - - -# --------------------------------------------------------------------------- -# Family integrity and federation-alignment guards. -# -# A device family with NO bound model is otherwise checked against nothing -# (test_device_family_is_declared_by_its_bound_model fires only when a model is -# bound), so a typo'd or synonym family would pass silently. These guards make -# every loose family (a family string not in the catalog) a deliberate, reasoned -# registry entry, surface promotion candidates as the fleet grows, and keep the -# beamline -> site facility pointer resolvable. They mirror the two-sided -# orphan-model guard above (assert no unexpected AND no stale allowlist entry). -# --------------------------------------------------------------------------- - -PROMOTION_THRESHOLD = 2 - -# Loose families: a device family string that is not (yet) a catalog Family. -# Each is either a Supply observation that never becomes an Asset Family, a -# passive beam-path element deferred under that tier, a component of another -# Asset (not a standalone Asset Family), or a real candidate staged behind an -# open question (the bucket leads each reason). A NEW loose family must -# land here with a reason: that forces a synonym or typo to surface in review -# without forcing premature promotion into the catalog. -_ALLOWED_LOOSE_FAMILIES = { - "Beam": "supply: Supply(PhotonBeam) source observation; never an Asset Family", - "Vacuum": "supply: Supply(Vacuum) observation; never an Asset Family", - "StorageRing": "supply: machine-level observe-only ring state (MACHINE-1); not an Asset Family", - "HeatAbsorber": "passive-deferred: passive beam-path tier (TomoWISE front-end absorber)", - "SafetyStack": "passive-deferred: passive safety composite (2-BM P6-50)", - "Shielding": "passive-deferred: passive PSS-grade shielding (19-BM guillotines, ENC-1)", - "SlipRing": "component: rotation-stage feedthrough, a Positioner component not an Asset", - "Wedge": "passive-deferred: passive fixed wedge (2-BM)", - "Diagnostic": "staged: arrival-time / photon-spectrum Sensor; fold-vs-promote open (DIAG-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)", - "Chopper": "staged: rotary duty-cycle device; fold-vs-Family open (CHOP-1)", - "Photodiode": "staged: PIN photodiode, Sensor Role; Family-vs-Sensor open (RAD-1)", - "Baffle": "staged: passive baffle inside the 2-BM SafetyStack; review name/role", - "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)", - "EnergyAnalyzer": "staged: IXS diced crystal energy analyzer; n=1 (ANALYZER-1)", -} - -# The subset of loose families that is conceptually a Supply observation (a -# facility resource or machine state), not an Asset, so it never counts toward -# catalog promotion. -_SUPPLY_LOOSE_FAMILIES = {"Beam", "Vacuum", "StorageRing"} - -# Loose families that have reached the promotion threshold and whose -# promote-or-hold decision has been recorded. A non-supply loose family that -# crosses PROMOTION_THRESHOLD deployments fails the build until it is either -# graduated into the catalog or recorded here with a one-line decision: the -# signal is mechanical, the decision stays human. -_PROMOTION_REVIEWED = { - "Diagnostic": "hold: arrival-time / photon-spectrum Sensor fold-vs-promote still open (DIAG-1)", - "SlipRing": "hold: rotation-stage feedthrough; a Positioner component, not a standalone Asset", -} - -# Catalog families bound by no deployment device. Symmetric to the orphan-model -# guard: an un-earned family contradicts "the model only contains what a real -# deployment forced." Empty today (GenericProbe is bound by FXI flux monitors). -_ALLOWED_ORPHAN_FAMILIES: dict[str, str] = {} - - -def _classify(observed: set[str], allowed: set[str]) -> tuple[list[str], list[str]]: - # (unexpected, stale): observed-not-allowed, allowed-not-observed. The shared - # core of the two-sided allowlist guards, unit-tested on synthetic input below - # so a future refactor cannot quietly weaken them. - return sorted(observed - allowed), sorted(allowed - observed) - - -def _catalog_family_names() -> set[str]: - return {f.name for f in cd.load(_CATALOG).families} - - -def _used_families() -> set[str]: - return { - device.family - for path in _beamline_descriptors() - for device in _walk_devices(bd.load(path)) - if device.family - } - - -def _loose_family_deployments() -> dict[str, set[str]]: - # family (not in the catalog) -> the deployments that bind it. - catalog_families = _catalog_family_names() - spread: dict[str, set[str]] = {} - for path in _beamline_descriptors(): - deployment = path.parent.name - for device in _walk_devices(bd.load(path)): - family = device.family - if family and family not in catalog_families: - spread.setdefault(family, set()).add(deployment) - return spread - - def _site_descriptors() -> list[Path]: return sorted(_DEPLOYMENTS.glob("*/site.yaml")) @@ -613,56 +501,11 @@ def _site_facility_codes() -> set[str]: return {sd.load(path).facility.code for path in _site_descriptors()} -def test_no_unexpected_loose_families() -> None: - loose = _used_families() - _catalog_family_names() - unexpected, stale = _classify(loose, set(_ALLOWED_LOOSE_FAMILIES)) - assert not unexpected, ( - "device families not in the catalog and not allowlisted (a typo, a synonym, or a " - "genuinely new device class); add to catalog.families or to _ALLOWED_LOOSE_FAMILIES " - f"with a reason: {unexpected}" - ) - assert not stale, ( - f"promoted into the catalog or no longer used; drop from _ALLOWED_LOOSE_FAMILIES: {stale}" - ) - - -def test_loose_families_past_promotion_threshold_are_reviewed() -> None: - spread = _loose_family_deployments() - candidates = { - family - for family, deployments in spread.items() - if len(deployments) >= PROMOTION_THRESHOLD and family not in _SUPPLY_LOOSE_FAMILIES - } - unreviewed = sorted( - f"{family} {sorted(spread[family])}" - for family in candidates - if family not in _PROMOTION_REVIEWED - ) - assert not unreviewed, ( - f"loose families at >= {PROMOTION_THRESHOLD} deployments with no recorded decision; " - "graduate them into catalog.families or record a promote-or-hold note in " - f"_PROMOTION_REVIEWED: {unreviewed}" - ) - stale = sorted(set(_PROMOTION_REVIEWED) - candidates) - assert not stale, ( - "no longer a sub-threshold candidate (promoted, removed, or now a Supply family); " - f"drop from _PROMOTION_REVIEWED: {stale}" - ) - - -def test_no_unexpected_orphan_catalog_families() -> None: - orphans = _catalog_family_names() - _used_families() - unexpected, stale = _classify(orphans, set(_ALLOWED_ORPHAN_FAMILIES)) - assert not unexpected, ( - "catalog families bound by no deployment device (un-earned abstractions); " - f"bind, remove, or allowlist with a reason: {unexpected}" - ) - assert not stale, f"now bound or removed; drop from _ALLOWED_ORPHAN_FAMILIES: {stale}" - - def test_site_facility_codes_cover_known_sites() -> None: # Anchor so the resolution check below cannot pass vacuously on an empty set. - assert {"aps", "diamond", "maxiv", "nsls2", "slac", "esrf"} <= _site_facility_codes() + # aps is the one Site cora carries; the further 13 moved with their + # beamlines to xmap/descriptors. + assert {"aps"} <= _site_facility_codes() @pytest.mark.parametrize("descriptor_path", _beamline_descriptors(), ids=lambda p: p.parent.name) @@ -684,30 +527,18 @@ def test_beamline_and_enclosure_facility_codes_resolve(descriptor_path: Path) -> ) -def test_allowlist_guard_logic_detects_unexpected_and_stale() -> None: - # The two-sided guards reduce to _classify; prove it on synthetic input. - # "Scintilator" is the canonical typo of the catalog family Scintillator. - unexpected, stale = _classify({"Scintilator", "Beam"}, {"Beam"}) - assert unexpected == ["Scintilator"] - assert stale == [] - unexpected, stale = _classify(set(), {"GoneFamily"}) - assert unexpected == [] - assert stale == ["GoneFamily"] - - # --------------------------------------------------------------------------- # Descriptor <-> deployment-docs drift guard. # -# Each deployment's docs/deployments// pages carry a hand-authored, curated -# inventory (editorial columns, live condition, and, for the operational pilot, -# derived PseudoAxis Assets that exist only in scenario setup), so they are NOT -# generated from the descriptor. This guard keeps only the factual subset honest: -# every device the descriptor MODELS (not marked new:, i.e. a real CORA Asset or -# a live verified device) must be mentioned by name somewhere in its deployment -# docs, so renaming or removing a device in the descriptor cannot leave a stale -# doc, and a documented Asset cannot quietly lose its descriptor source. Devices -# marked new: are not yet modelled and are legitimately absent, so a pure -# design-phase scaffold (all-new) is not pinned until its devices materialize. +# 2-BM's docs/deployments/2-bm/ pages carry a hand-authored, curated inventory +# (editorial columns, live condition, and derived PseudoAxis Assets that exist +# only in scenario setup), so they are NOT generated from the descriptor. This +# guard keeps only the factual subset honest: every device the descriptor +# MODELS (not marked new:, i.e. a real CORA Asset or a live verified device) +# must be mentioned by name somewhere in its deployment docs, so renaming or +# removing a device in the descriptor cannot leave a stale doc, and a +# documented Asset cannot quietly lose its descriptor source. Devices marked +# new: are not yet modelled and are legitimately absent. # --------------------------------------------------------------------------- _DOCS_DEPLOYMENTS = _REPO_ROOT / "docs" / "deployments" @@ -810,13 +641,9 @@ def test_doc_catalog_markers_reference_real_catalog_models() -> None: # # Every beamline declares three orthogonal badge axes (see beamline_descriptor # for the vocabularies). These guards keep the vocabulary closed (an enum-mirror -# per axis, matching the DrawingSystem mirror above) and the combinations logical -# (the two invariants that must hold for the axes to mean what they claim): there -# is exactly one live pilot, and live evidence and the pilot maturity are the same -# beamline. Evidence and coverage are otherwise free of maturity, by design: a -# roadmap beamline can be modelled from a design report or from narrative facts, -# and an off-roadmap model can be a partial cut, so no further cross-axis law is -# asserted (that would encode a coincidence of today's corpus as a rule). +# per axis, matching the DrawingSystem mirror above) and the combinations logical: +# there is exactly one live pilot, and live evidence and the pilot maturity are +# the same beamline. # --------------------------------------------------------------------------- _BADGE_MATURITIES = frozenset({"pilot", "design", "model"}) @@ -850,27 +677,13 @@ def test_badge_axes_are_logically_consistent() -> None: ) -def test_badge_axes_are_not_vacuous() -> None: - # Pin a floor so the per-descriptor check cannot pass on an empty glob, and so - # a bulk misclassification that flattens an axis to one value is caught: the - # fleet spans multiple evidence tiers and carries at least one partial cut. - beamlines = [bd.load(p).beamline for p in _beamline_descriptors()] - assert len(beamlines) >= 50 - assert len({b.evidence for b in beamlines}) >= 3 - assert any(b.coverage == "partial" for b in beamlines) - - # --------------------------------------------------------------------------- # Deployments index drift guard. # -# docs/deployments/index.md is the hand-authored hub: it groups every beamline -# by Site and carries the three badge cells per row. Hand-authored means it can -# go stale (81 deployments exist, an earlier index listed only 67) and its badge -# cells can disagree with the descriptor. These guards make the index self-police -# without a generator: every deployment appears as a row, and each row's three -# badge cells equal the beamline's descriptor. They mirror the doc-drift guard -# test_modeled_devices_are_documented above (the descriptor is the source of -# truth, the docs must not drift from it). +# docs/deployments/index.md is the hand-authored hub: it lists every deployment +# cora carries with its three badge cells. These guards make the index +# self-police without a generator: every deployment appears as a row, and each +# row's three badge cells equal the beamline's descriptor. # --------------------------------------------------------------------------- _INDEX = _DOCS_DEPLOYMENTS / "index.md" @@ -932,10 +745,9 @@ def test_index_badge_cells_match_descriptor() -> None: # Beamline summary: single source for the "What it is" one-liner. # # The one-line description of a beamline is authored once, in its descriptor's -# `summary`, and rendered in two places: the "What it is" cell on the landing -# page and the beamline's row in its Site facility-page roster. This guard makes -# the descriptor the single source: every beamline declares a summary, and the -# landing-page cell equals it, so the two surfaces cannot drift. +# `summary`, and rendered on the landing page's "What it is" cell. This guard +# makes the descriptor the single source: every beamline declares a summary, +# and the landing-page cell equals it, so the two cannot drift. # --------------------------------------------------------------------------- @@ -975,109 +787,6 @@ def test_index_what_it_is_matches_descriptor_summary() -> None: ) -# --------------------------------------------------------------------------- -# Site-ordinal drift guard. -# -# Deployment prose repeatedly claims "CORA's Nth Site" for the facility a -# beamline sits on. Because each page was written when the fleet was a different -# size, these ordinals drifted: four separate facilities once all claimed -# "eighth Site". The canonical order is the sequence in which CORA took each Site -# on, pinned here as the single source of truth. This guard scans every -# deployment's docs and descriptor for an "CORA's Site" claim and -# fails if the ordinal word does not match the facility's canonical position, so -# a future beamline cannot reintroduce a stale count. Only Site-level ordinals -# are mechanized (they have one right answer); technique / per-facility-sequence -# ordinals are phrased without a hard count on purpose. -# --------------------------------------------------------------------------- - -# Canonical Site order: the sequence CORA took each facility on. Position i (1-based) -# is the ordinal every "CORA's Nth Site" claim about that facility must use. -_CANONICAL_SITE_ORDER = ( - "aps", - "maxiv", - "diamond", - "nsls2", - "slac", - "as", - "esrf", - "sirius", - "alba", - "als", - "elettra", - "nsrrc", - "petra-iii", - "psi", -) - -_ORDINAL_WORDS = { - 1: {"first"}, - 2: {"second"}, - 3: {"third"}, - 4: {"fourth"}, - 5: {"fifth"}, - 6: {"sixth"}, - 7: {"seventh"}, - 8: {"eighth"}, - 9: {"ninth", "9th"}, - 10: {"tenth"}, - 11: {"eleventh", "11th"}, - 12: {"twelfth"}, - 13: {"thirteenth"}, - 14: {"fourteenth"}, -} - -# "CORA's Site", "the Site CORA models", "is the Site", -# " is the Site", ", the Site", and the -# "Nth)" short form used in a few page bullets (e.g. "ALBA, the 9th)"). -_SITE_ORDINAL_RE = re.compile( - r"(?:the|is the|its|CORA's)\s+" - r"(first|second|third|fourth|fifth|sixth|seventh|eighth|ninth|tenth|" - r"eleventh|twelfth|thirteenth|fourteenth|9th|11th)\s+Site", - re.IGNORECASE, -) - - -def _facility_ordinal(facility_code: str) -> int: - return _CANONICAL_SITE_ORDER.index(facility_code) + 1 - - -def test_canonical_site_order_covers_every_facility() -> None: - # Anchor: the pinned order must list exactly the facilities that have a - # site.yaml, so a new Site cannot be added without placing it in the order. - assert set(_CANONICAL_SITE_ORDER) == _site_facility_codes() - - -def test_site_ordinal_claims_match_canonical_order() -> None: - # For every deployment, its facility fixes the one correct Site ordinal; any - # "CORA's Nth Site" claim in its docs or descriptor must use that word. - wrong: list[str] = [] - for descriptor_path in _beamline_descriptors(): - deployment = descriptor_path.parent.name - facility = bd.load(descriptor_path).beamline.facility - if facility is None or facility not in _CANONICAL_SITE_ORDER: - continue - expected_n = _facility_ordinal(facility) - expected_words = _ORDINAL_WORDS[expected_n] - site_yaml = _DEPLOYMENTS / facility / "site.yaml" - sources = [ - descriptor_path, - site_yaml, - *sorted((_DOCS_DEPLOYMENTS / deployment).rglob("*.md")), - ] - for source in sources: - if not source.exists(): - continue - for claim in _SITE_ORDINAL_RE.findall(source.read_text(encoding="utf-8")): - if claim.lower() not in expected_words: - wrong.append( - f"{source.relative_to(_REPO_ROOT)}: claims '{claim} Site' but " - f"{facility} is CORA's #{expected_n} Site" - ) - assert not wrong, ( - "stale Site ordinals (canonical order in _CANONICAL_SITE_ORDER):\n" + "\n".join(wrong) - ) - - def test_malformed_descriptor_raises(tmp_path: Path) -> None: missing_beamline = tmp_path / "no_beamline.yaml" missing_beamline.write_text("enclosures: []\n", encoding="utf-8") diff --git a/apps/api/tests/unit/deployments/test_pending_method_alignment.py b/apps/api/tests/unit/deployments/test_pending_method_alignment.py deleted file mode 100644 index 64e776e15bb..00000000000 --- a/apps/api/tests/unit/deployments/test_pending_method_alignment.py +++ /dev/null @@ -1,165 +0,0 @@ -"""Fitness guard: pending Method/Capability references stay enumerated, not silent. - -A `beamline.yaml` documents the operations a beamline runs by naming the -Method or Capability that models each. When the modelling note references a -technique the catalog does not yet carry, it writes an IOU: - - reusing the pending `xas_spectroscopy` Method - -Left unguarded, these IOUs multiply invisibly: an audit of the fleet found -~13 distinct technique slugs referenced this way across most beamline.yaml -files, none of them present in `catalog/catalog.yaml` or in `apps/api/src`. -The operations vocabulary (Capabilities / Methods) had grown against one -deployment while the device vocabulary (Families) grew against the whole -fleet, so the notes promised a model that was never queued. - -This guard makes every pending reference explicit. A slug named in a -`pending ... Method` / `pending ... Capability` construct must either: - - - exist in the catalog descriptor (`catalog/catalog.yaml`), meaning the - IOU has been paid; or - - appear on `_PENDING_ALLOWLIST` below, an enumerated queue of techniques - known to be unmodelled, each carrying its disposition. - -A new untracked IOU (a slug that is neither in the catalog nor on the -allowlist) fails the build, so the queue cannot silently grow. When a -technique is authored into the catalog, its slug is removed from the -allowlist and the guard confirms the citation now resolves. - -The allowlist also cannot rot: every entry must still be referenced by at -least one beamline.yaml (a slug authored into the catalog, or a citation -deleted, leaves a dead allowlist entry the guard rejects). - -Disposition tags on each allowlist entry (documentation, not enforced): - - earned-not-yet-authored: the rule-of-three has fired (3+ deployments - share the technique, measured by Family binding); authoring lagged. - - not-yet-earned: fewer than three deployments; stays pending until the - trigger fires. - - decompose: too coarse to author as one Method (the generic - `diffraction` slug); splits into specific capabilities at author time. -""" - -from __future__ import annotations - -import importlib.util -import re -import sys -from pathlib import Path -from typing import TYPE_CHECKING - -import pytest - -if TYPE_CHECKING: - from types import ModuleType - -pytestmark = pytest.mark.unit - -_REPO_ROOT = Path(__file__).resolve().parents[5] -_SCRIPTS_DIR = _REPO_ROOT / "scripts" -_DEPLOYMENTS = _REPO_ROOT / "deployments" -_CATALOG = _REPO_ROOT / "catalog" / "catalog.yaml" - - -def _load(name: str) -> ModuleType: - # scripts/ is not on the package path; the descriptor is loaded by file, - # mirroring test_catalog_descriptor.py so the lean docs interpreter (no - # cora package) can run this guard too. - spec = importlib.util.spec_from_file_location(name, _SCRIPTS_DIR / f"{name}.py") - if spec is None or spec.loader is None: - raise RuntimeError(f"cannot load {name} from {_SCRIPTS_DIR}") - module = importlib.util.module_from_spec(spec) - sys.modules[name] = module - spec.loader.exec_module(module) - return module - - -catalog_descriptor = _load("catalog_descriptor") - -# The IOU construct: "pending <...> Method(s)" or "pending <...> Capability|Capabilities", -# with zero or more backtick-quoted slugs in the span between "pending" and the kind noun. -_PENDING_SPAN = re.compile(r"pending\s+([^.\n]*?)\b(?:Methods?|Capabilit(?:y|ies))\b") -_SLUG = re.compile(r"`([a-z][a-z0-9_]+)`") - -# Enumerated queue of technique slugs referenced as pending but not yet in the -# catalog. Each maps to its disposition (see module docstring). Removing a slug -# here without authoring it into the catalog (or deleting its citation) fails -# the no-dead-entry check; adding an unlisted pending slug fails the coverage -# check. Names here are the slugs AS CITED today; the authoring slice renames -# citations to the convention-checked canonical names as it pays each IOU. -_PENDING_ALLOWLIST: dict[str, str] = { - # Authored in the catalog under a canonical name (Lock 1); the slug stays - # only because a beamline.yaml citation still uses the old spelling. These - # clear when the citation-rewrite sweep renames the reference (then the slug - # becomes unreferenced and is removed). - "mx_data_collection": "authored-as-macromolecular_crystallography; citation-rewrite pending", - "xas_spectroscopy": "authored-as-absorption_spectroscopy; citation-rewrite pending", - "scanning_fluorescence_microscopy": "authored-as-xray_fluorescence_mapping; rewrite pending", - "small_angle_scattering": "authored-as-small_wide_angle_scattering; citation-rewrite pending", - "wide_angle_scattering": "authored-as-small_wide_angle_scattering; citation-rewrite pending", - "resonant_scattering": "authored-as-resonant_inelastic_scattering; citation-rewrite pending", - # Genuinely not yet earned (n<3) or deferred; stay pending until authored. - "magnetic_scattering": "not-yet-earned", - "total_scattering": "not-yet-earned", - "energy_dispersive_diffraction": "not-yet-earned", - "xmcd": "not-yet-earned", -} - - -def _catalog_slugs() -> set[str]: - """Method names and Capability code tails carried by the catalog today.""" - cat = catalog_descriptor.load(_CATALOG) - method_names = {m.name for m in cat.methods} - capability_tails = {c.code.rsplit(".", 1)[-1] for c in cat.capabilities} - return method_names | capability_tails - - -def _pending_references() -> dict[str, set[str]]: - """Map each cited pending slug to the set of beamlines citing it.""" - refs: dict[str, set[str]] = {} - for beamline_yaml in sorted(_DEPLOYMENTS.glob("*/beamline.yaml")): - beamline = beamline_yaml.parent.name - text = beamline_yaml.read_text(encoding="utf-8") - for span in _PENDING_SPAN.findall(text): - for slug in _SLUG.findall(span): - refs.setdefault(slug, set()).add(beamline) - return refs - - -def test_pending_references_are_discovered() -> None: - # Guards the parser: if the construct or path drifts, the checks below - # would pass vacuously. The fleet is known to carry pending references. - assert _pending_references(), ( - "no `pending ... Method/Capability` references parsed from any " - "deployments/*/beamline.yaml (parser or path drift?)" - ) - - -def test_every_pending_slug_is_in_catalog_or_allowlisted() -> None: - known = _catalog_slugs() - refs = _pending_references() - untracked = { - slug: sorted(beamlines) - for slug, beamlines in refs.items() - if slug not in known and slug not in _PENDING_ALLOWLIST - } - assert not untracked, ( - "beamline.yaml references a pending Method/Capability slug that is " - "neither in catalog/catalog.yaml nor on _PENDING_ALLOWLIST. Author it " - "into the catalog, or add it to the allowlist with its disposition:\n" - + "\n".join(f" `{slug}` cited by {bls}" for slug, bls in sorted(untracked.items())) - ) - - -def test_no_dead_allowlist_entries() -> None: - known = _catalog_slugs() - refs = _pending_references() - authored = sorted(slug for slug in _PENDING_ALLOWLIST if slug in known) - assert not authored, ( - "allowlisted slug(s) now exist in the catalog; remove them from " - f"_PENDING_ALLOWLIST (the IOU is paid): {authored}" - ) - unreferenced = sorted(slug for slug in _PENDING_ALLOWLIST if slug not in refs) - assert not unreferenced, ( - "allowlisted slug(s) no longer cited by any beamline.yaml; remove the " - f"dead allowlist entr(ies): {unreferenced}" - ) diff --git a/apps/api/tests/unit/deployments/test_practice_derivation.py b/apps/api/tests/unit/deployments/test_practice_derivation.py index 09ec965fb51..c995f2e4641 100644 --- a/apps/api/tests/unit/deployments/test_practice_derivation.py +++ b/apps/api/tests/unit/deployments/test_practice_derivation.py @@ -6,22 +6,25 @@ set-cover the spine enforces at `define_plan` bind time. The derivation kernel is `scripts/practice_derivation.py`. -Two guarantees: - - - fleet-wide computability: the derivation runs for every deployment and - never yields a Method the catalog does not define (the roster is a subset - of the catalog's Methods, so a renderer or the spine can trust it). - - bridge integrity: every REAL (non-pending) Practice hand-authored in a - `site.yaml` names a Method that at least one of that Site's hosted - beamlines can actually derive (its families cover the Method). A curated - Practice asserting hardware no hosted beamline models is drift: either the - beamline's device model is missing hardware, or the Practice is aspirational - and belongs under `pending:`. Pending Practices are exempt (they ARE the - acknowledged IOUs). +Two guarantees, scoped to what cora still carries (2-BM at APS; the further 93 +beamlines this guard used to run across moved to the private xmap/descriptors +repo): + + - computability: the derivation runs for every deployment cora has and never + yields a Method the catalog does not define (the roster is a subset of the + catalog's Methods, so a renderer or the spine can trust it). + - bridge integrity: every REAL (non-pending) Practice hand-authored in + `aps/site.yaml` names a Method that 2-BM's device model can actually + derive (its families cover the Method). A curated Practice asserting + hardware 2-BM does not model is drift: either 2-BM's device model is + missing hardware, or the Practice is aspirational and belongs under + `pending:`. Pending Practices are exempt (they ARE the acknowledged IOUs). + Two practices that were genuinely backed by 8-ID's and 9-ID's own + (now-departed) descriptors, not 2-BM's, were removed from aps/site.yaml + rather than left asserting hardware this repo no longer models. The bridge check is the point of Lock 2: it makes the operations layer answer -to the whole fleet's device model instead of accreting only where someone -hand-authored a site page. +to the real device model instead of accreting unchecked. """ from __future__ import annotations @@ -84,8 +87,8 @@ def _facility_of(slug: str) -> str | None: def test_derivation_covers_every_deployment() -> None: rosters = _rosters() # Guards against discovery drift: a moved path would make the checks below - # pass vacuously. The fleet is known to be non-trivial. - assert len(rosters) >= 80, f"expected the full fleet, derived only {len(rosters)} rosters" + # pass vacuously. 2-BM is the one deployment cora carries today. + assert len(rosters) >= 1, f"expected at least 2-BM, derived {len(rosters)} rosters" def test_derived_rosters_are_catalog_methods() -> None: diff --git a/apps/api/tests/unit/deployments/test_site_descriptor.py b/apps/api/tests/unit/deployments/test_site_descriptor.py index 94fec805c97..f661f93da56 100644 --- a/apps/api/tests/unit/deployments/test_site_descriptor.py +++ b/apps/api/tests/unit/deployments/test_site_descriptor.py @@ -331,11 +331,10 @@ def test_practice_method_links_only_known() -> None: # guards in test_beamline_descriptor.py: # - a non-pending practice method must resolve in the catalog; # - a pending method must be a deliberate, reasoned registry entry. -# The >=2-deployment promotion SIGNAL (the family-promotion analog) is not added -# yet: methods are staged per-site, so a method's beamline spread is not -# structurally measurable today (it lives only in the practice-name prefix), and -# no pending method spans two sites. _PENDING_METHODS is the registry a future -# signal would read once practices carry a typed beamline. +# +# _PENDING_METHODS used to span all 14 Sites cora carried; the other 13 moved +# to xmap/descriptors along with the beamlines whose practices cited them, so +# only aps/site.yaml's own pending methods remain here. # --------------------------------------------------------------------------- _PENDING_METHODS = { @@ -344,31 +343,15 @@ def test_practice_method_links_only_known() -> None: "first_light": "19-BM commissioning method; design phase", "ioc_restart": "2-BM maintenance recovery; portable Method not yet authored", "mirror_recoat_return": "2-BM mirror recoat-and-return; Method not yet authored", - "scanning_fluorescence_microscopy": "2-ID + XFM scanning XRF; 2 consumers (METHOD-1)", - "diffraction": "single-crystal diffraction (4-ID/8-ID/CSX/i19); not yet earned (TECH-1)", + "scanning_fluorescence_microscopy": "2-ID scanning XRF; Method not yet earned (METHOD-1)", + "diffraction": "single-crystal diffraction (4-ID/8-ID); not yet earned (TECH-1)", "magnetic_scattering": "4-ID magnetic scattering; not yet in pilot scope (TECH-1)", "resonant_scattering": "4-ID resonant scattering; not yet in pilot scope (TECH-1)", "xmcd": "4-ID magnetic circular dichroism; not yet in pilot scope (TECH-1)", - "xmld": "i06 magnetic linear dichroism on the APPLE-II; not yet in pilot scope (TECH-1)", - "photoemission_microscopy": "i06 PEEM electron-imaging microscopy; not yet earned (PEEM-1)", - "reflectivity": "i10 + CMS reflectivity (soft + hard X-ray); rule-of-three watch (TECH-1)", "coherent_surface_scattering": "9-ID CSSI surface scattering; not yet in pilot scope (TECH-1)", - "inelastic_x_ray_scattering": "IXS hard X-ray inelastic scattering; not in scope (TECH-1)", - "grid_scan": "i03 + FMX + AMX MX fast grid scan; 3 consumers (TECH-1)", - "mx_data_collection": "i03 + FMX + AMX MX rotation collection; 3 consumers (TECH-1)", - "sample_exchange": "i03 + FMX + AMX robotic sample exchange; 3 consumers (ROBOT-1)", - "solution_scattering": "lix bio-SAXS / SEC-SAXS; new Method not yet earned (TECH-1)", - "x_ray_footprinting": "xfp dose-delivery footprinting; offline MS readout; new Method (TECH-1)", - "small_angle_scattering": "i22 + 8-ID SAXS; portable Method not yet earned", - "wide_angle_scattering": "i22 + 9-ID WAXS; portable Method not yet earned", + "small_angle_scattering": "8-ID SAXS on the XPCS detectors; portable Method not yet earned", + "wide_angle_scattering": "9-ID GIWAXS; portable Method not yet earned", "ultra_small_angle_scattering": "12-ID Bonse-Hart USAXS; not yet earned (USAXS-1)", - "total_scattering": "i15-1 total scattering / PDF; Method not yet earned", - "energy_dispersive_exafs": "i20-1 EDE; dispersive devices not yet in source (POLY-1 / STRIP-1)", - "pump_probe": "LCLS-MFX fs optical-laser pump / X-ray probe; XFEL Method not yet earned", - "xas_spectroscopy": "MFX + ISS emission-spectrometer XAS / XES; 2 consumers (TECH-1)", - "helical_tomography": "SYRMEP helical large-specimen CT; not yet earned (TECH-1)", - "white_beam_tomography": "SYRMEP white / pink-beam fast tomography; not yet in scope (TECH-1)", - "phase_retrieval": "SYRMEP TIE-HOM / Paganin phase retrieval; compute Method (COMPUTE-1)", } diff --git a/apps/api/tests/unit/deployments/test_techniques_not_stale.py b/apps/api/tests/unit/deployments/test_techniques_not_stale.py index 3f204567dcf..fedf72acc6c 100644 --- a/apps/api/tests/unit/deployments/test_techniques_not_stale.py +++ b/apps/api/tests/unit/deployments/test_techniques_not_stale.py @@ -1,29 +1,22 @@ -"""Fitness guard: a beamline's Techniques section cannot call an AUTHORED Method pending. +"""Fitness guard: 2-BM's techniques.md cannot call an AUTHORED Method pending. -The per-beamline `docs/deployments//notes.md` pages are hand-authored intent -prose (unlike the generated `beamline.md`), and each carries a `## Techniques` -section. When a technique was cited as "a new Method, pending (TECH-1)" and that -Method is later authored into the catalog (the operations-layer re-derivation -Lock 1), the section rots: it describes a future that already arrived. +`docs/deployments/2-bm/techniques.md` is hand-authored intent prose (unlike the +generated `beamline.md`). When a technique was cited as "a new Method, pending +(TECH-1)" and that Method is later authored into the catalog (the +operations-layer re-derivation Lock 1), the page rots: it describes a future +that already arrived. -This guard catches that specific drift. A Techniques-section table row is STALE -when it both: +This guard catches that specific drift. A table row is STALE when it both: - cites a backtick method slug that now exists in `catalog/catalog.yaml`, and - frames that row as not-yet-real (pending / "new Method" / "not yet in catalog" / a bare TECH-tag). -A stale row must be either fixed (drop the pending framing now that the Method -exists) or listed in `_KNOWN_STALE` below. `_KNOWN_STALE` is an enumerated -backlog: the rows already stale when Lock 1 landed, deliberately left for a -future content pass to clear (the four hand-authored pages per beamline were -merged into one `notes.md` afterward, a structural move only; it did not touch -row content, so the backlog carries over unchanged). The guard's value is -catching NEW drift: a newly-authored Method whose citing row still says pending -fails the build unless explicitly parked here. - -Keyed by (beamline, method_slug). Removing an entry once its row is fixed is -required: a _KNOWN_STALE entry that is no longer stale fails the no-dead-entry -check, so the backlog cannot rot silent. +The further 93 beamlines this guard used to cover (each with its own +techniques.md, merged into a since-retired notes.md) moved to the private +xmap/descriptors repo; cora's test suite no longer iterates over them (see +project_beamline_seeder_design's reasoning: a drift guard only earns its keep +against data cora's own commits can still change). 2-BM is the one deployment +left, and the one whose techniques.md cora keeps editing. """ from __future__ import annotations @@ -43,7 +36,7 @@ _REPO_ROOT = Path(__file__).resolve().parents[5] _SCRIPTS_DIR = _REPO_ROOT / "scripts" -_DEPLOYMENTS_DOCS = _REPO_ROOT / "docs" / "deployments" +_TECHNIQUES = _REPO_ROOT / "docs" / "deployments" / "2-bm" / "techniques.md" _CATALOG = _REPO_ROOT / "catalog" / "catalog.yaml" # A row is framed not-yet-real when it carries one of these phrases. @@ -52,29 +45,6 @@ re.IGNORECASE, ) _SLUG = re.compile(r"`([a-z][a-z0-9_]+)`") -_SECTION = re.compile(r"^## (.+)$", re.MULTILINE) - -# Rows already stale when Lock 1 landed (2026-07-02): the page cites a now-authored -# Method but still frames it pending. Backlog for a future content pass to clear; -# each removal is verified by the no-dead-entry check below. -_KNOWN_STALE: set[tuple[str, str]] = { - ("13-id", "powder_diffraction"), - ("cdi", "ptychography"), - ("chx", "xpcs"), - ("cms", "grazing_incidence_scattering"), - ("esm", "angle_resolved_photoemission"), - ("faxtor", "radiography"), - ("fxi", "tomography"), - ("hex", "radiography"), - ("hex", "powder_diffraction"), - ("i13-1", "ptychography"), - ("id32", "resonant_inelastic_scattering"), - ("ixs", "inelastic_scattering"), - ("mogno", "tomography"), - ("p10", "ptychography"), - ("pdf", "powder_diffraction"), - ("six", "resonant_inelastic_scattering"), -} def _load(name: str) -> ModuleType: @@ -94,61 +64,26 @@ def _catalog_methods() -> set[str]: return {m.name for m in catalog_descriptor.load(_CATALOG).methods} -def _techniques_section(notes_text: str) -> str: - """The `## Techniques` section body, up to the next `## ` heading or EOF. - - notes.md carries Techniques, Governance, Model, and Open questions as - sibling sections; Open questions has its own pipe-table rows that must not - leak into this scan (a "pending" confirmation there is not a stale Method - citation). - """ - headings = list(_SECTION.finditer(notes_text)) - for i, m in enumerate(headings): - if m.group(1).strip() != "Techniques": - continue - end = headings[i + 1].start() if i + 1 < len(headings) else len(notes_text) - return notes_text[m.end() : end] - return "" - - -def _stale_rows() -> set[tuple[str, str]]: - """Every (beamline, authored-method-slug) whose Techniques row is stale.""" +def _stale_slugs() -> set[str]: + """Every authored-method-slug whose 2-BM techniques.md row is stale.""" methods = _catalog_methods() - stale: set[tuple[str, str]] = set() - for notes_md in sorted(_DEPLOYMENTS_DOCS.glob("*/notes.md")): - beamline = notes_md.parent.name - section = _techniques_section(notes_md.read_text(encoding="utf-8")) - for line in section.splitlines(): - if not line.startswith("| ") or not _PENDING_PHRASE.search(line): - continue - for slug in _SLUG.findall(line): - if slug in methods: - stale.add((beamline, slug)) + stale: set[str] = set() + for line in _TECHNIQUES.read_text(encoding="utf-8").splitlines(): + if not line.startswith("| ") or not _PENDING_PHRASE.search(line): + continue + for slug in _SLUG.findall(line): + if slug in methods: + stale.add(slug) return stale -def test_techniques_pages_discovered() -> None: - pages = [ - p - for p in _DEPLOYMENTS_DOCS.glob("*/notes.md") - if _techniques_section(p.read_text(encoding="utf-8")) - ] - assert len(pages) >= 80, f"expected the full fleet of Techniques sections, found {len(pages)}" - - -def test_no_new_stale_technique_rows() -> None: - new_stale = sorted(_stale_rows() - _KNOWN_STALE) - assert not new_stale, ( - "notes.md Techniques row(s) call a Method 'pending' / 'new' / 'not in catalog' that now " - "EXISTS in catalog/catalog.yaml. Drop the pending framing now the Method is authored, " - "or add to _KNOWN_STALE with intent:\n" - + "\n".join(f" {bl}: `{slug}`" for bl, slug in new_stale) - ) +def test_techniques_page_discovered() -> None: + assert _TECHNIQUES.is_file(), "docs/deployments/2-bm/techniques.md not found" -def test_no_dead_known_stale_entries() -> None: - fixed = sorted(_KNOWN_STALE - _stale_rows()) - assert not fixed, ( - "_KNOWN_STALE entr(ies) are no longer stale (page fixed or method removed); " - f"drop them from the backlog: {fixed}" +def test_no_stale_technique_rows() -> None: + stale = sorted(_stale_slugs()) + assert not stale, ( + "2-bm/techniques.md row(s) call a Method 'pending' / 'new' / 'not in catalog' that now " + f"EXISTS in catalog/catalog.yaml. Drop the pending framing: {stale}" ) diff --git a/deployments/12-id/beamline.yaml b/deployments/12-id/beamline.yaml deleted file mode 100644 index 067c7fcda43..00000000000 --- a/deployments/12-id/beamline.yaml +++ /dev/null @@ -1,271 +0,0 @@ -# 12-ID beamline descriptor (APS), reverse-engineered -# -# 12-ID is the APS ultra-small-angle X-ray scattering (USAXS) instrument, a -# Bonse-Hart crystal-analyzer beamline that also runs pinhole SAXS and WAXS. It is -# bound to the APS Site (deployments/aps/site.yaml), the ninth APS beamline after -# 2-BM, 2-ID, 7-BM, 32-ID, 19-BM, 4-ID, 8-ID, and 9-ID, and CORA's FIRST -# crystal-analyzer USAXS deployment. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the BCDA-APS bluesky/BITS instrument, github.com/BCDA-APS/usaxs-bits, its -# src/usaxs/devices/*.py classes and src/usaxs/configs/*.yml device tables) or -# inferred, carried `new: true` + `confirm: true` pending 12-ID staff. EPICS PVs -# are real and verified against the instrument config; vendor part numbers, serials, -# and physical positions are not in it and are open questions. Same descriptor mode -# as the other APS deployments; this scaffold is descriptor + docs, scenarios -# deferred. -# -# WHAT IS NEW: USAXS is a Bonse-Hart rocking-curve technique, the fleet's first. -# A matched pair of channel-cut crystal stages, the collimator and the analyzer, is -# rocked through the Bragg condition while a single autoranging photodiode counts -# the transmitted intensity across several decades of gain; this reaches q far below -# the pinhole-SAXS regime (i22 / SMI). The acquisition shape is an angular rocking -# fly-scan with a multi-decade autoranging point detector, distinct from the -# pixel-detector SAXS/WAXS the fleet already models. This is a new Capability, -# deferred as a question (USAXS-1); the same instrument also runs pinhole SAXS and -# WAXS on area detectors, which reuse the existing scattering Capabilities. -# -# MODELLING: every device reuses an existing catalog or loose Family. 12-ID coins -# NO new Family and changes nothing in the catalog. The Bonse-Hart collimator and -# analyzer stages reuse RotaryStage (the crystal rocking is the operative axis; -# channel-cut is a per-Asset setting, not a new optic Family); the autoranging Femto -# photodiode detector and the I0/I00/I000/TRD monitors and scalers reuse FluxMonitor -# (current-integrating point detectors, the BMM quad-electrometer precedent; the -# gain autorange is a device-state setting); the Linkam and PTC10 reuse the -# graduated TemperatureController (Regulator); the SAXS/WAXS Pilatus detectors reuse -# Camera. The optional in-situ load frame is in the device library but not the active -# instrument config, so it is carried as a deferred question (LOADFRAME-1), no -# Family coined for an un-instantiated device. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/12-id/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "Bonse-Hart ultra-small-angle X-ray scattering (USAXS) plus pinhole SAXS / WAXS, Sector 12; CORA's first USAXS deployment" - name: 12-ID - facility: aps # APS Site (facility_code: aps) - sector: "Sector 12" # PV namespaces usxLAX / usxAERO / 12idPyFilter / usxRIO - tier: Unit - parent: null - source: insertion-device - source_confirm: "12-ID is an undulator sector; the USAXS instrument config does not expose the insertion-device gap as a device, so the undulator detail is SRC-1" - page_layout: stages - shape: "The fleet's first Bonse-Hart USAXS beamline: a matched channel-cut crystal pair is rocked through Bragg while an autoranging point detector counts the transmitted beam, reaching q far below pinhole SAXS." - source_ref: - label: "BCDA-APS/usaxs-bits" - url: "https://github.com/BCDA-APS/usaxs-bits" - -# PV namespaces: usxLAX (the LAX soft-IOC: USAXS calcs, scalers, slits, many -# motors), usxAERO (Aerotech motors), 12idPyFilter (attenuator), usxRIO (Femto -# amplifier RIO), usxLINKAM / usxTEMP (sample temperature), usxPI (sample rotator). -# Whether 12-ID is one experiment hutch plus shared upstream optics, and the PSS -# permit leaves, are open (ENC-1, PSS-1). -enclosures: - - name: 12-ID-optics - role: optics-hutch - facility_code: aps - permit_signal: {confirm: "PSS permit leaf not in source; the shared 12-ID optics zone, hutch grouping is ENC-1 (PSS-1)"} - - name: 12-ID-E - role: experiment-hutch - facility_code: aps - permit_signal: {confirm: "PSS permit leaf unknown; the USAXS experiment hutch (ENC-1, PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the machine source state and the optics -# =========================================================================== - -machine: - stage: source - enclosure: 12-ID-optics - intro: "The machine-level source state, observed not driven." - note: "Observe-only APS machine state, the loose StorageRing pattern reused from the other APS deployments (MACHINE-1). The undulator gap is not in the USAXS instrument config (SRC-1)." - devices: - - name: StorageRing - family: StorageRing # loose Family (machine-level observe-only source state; MACHINE-1) - pv: {confirm: "APS storage-ring state (current, fill, status); observe-only, the exact PVs are MACHINE-1"} - new: true - confirm: true - note: "machine source state; observe-only, not photon-path flux (MACHINE-1)" - -optics: - stage: source - enclosure: 12-ID-optics - intro: "The monochromator, the attenuator filter bank, and the guard and USAXS slits." - note: "All reuse existing catalog Families. The attenuator reuses the Filter Family (the I03 / i15-1 precedent), not a new Attenuator kind." - devices: - - name: Monochromator - family: Monochromator - pv: {confirm: "the 12-ID monochromator (dodal MyMonochromator wraps the energy/feedback PVs); crystal cut, d-spacing, energy range are MONO-1"} - new: true - confirm: true - note: "the shared 12-ID monochromator; the instrument config wraps it as a soft device, the real PVs are MONO-1" - - name: Attenuator - family: Filter - pv: "12idPyFilter:" - new: true - confirm: true - note: "Al/Ti attenuator filter bank (FilterBank FL1); reuses the Filter Family, not a new Attenuator kind (ATTN-1)" - - name: GuardSlit - family: Slit - pv: "usxLAX:" - new: true - confirm: true - note: "guard slit (GSlitDevice); blade-axis map is OPT-2" - - name: UsaxsSlit - family: Slit - pv: "usxLAX:" - new: true - confirm: true - note: "USAXS-defining slit (UsaxsSlitDevice); blade-axis map is OPT-2" - -# =========================================================================== -# USAXS STAGE: the Bonse-Hart collimator and analyzer crystal stages -# =========================================================================== - -usaxs-optics: - stage: source - enclosure: 12-ID-E - intro: "The Bonse-Hart matched crystal pair: the collimator stage upstream of the sample and the analyzer stage downstream, rocked through the Bragg condition to resolve ultra-small angles." - note: > - The collimator and analyzer are channel-cut crystal stages, each carrying a - crystal rocking rotation plus alignment translations and a piezo fine-tilt. They - reuse the catalog RotaryStage (the rocking rotation is the operative axis; - channel-cut versus multi-bounce is a per-Asset setting, not a new optic Family). - The rocking-curve angular scan is the USAXS Capability, deferred (USAXS-1, BONSE-1). - devices: - - name: CollimatorStage - family: RotaryStage - pv: {confirm: "Bonse-Hart collimator stage (UsaxsCollimatorStageDevice): rocking rotation usxAERO:m12, x/y align, r2p piezo usxLAX:pi:c0:m2; axis detail is BONSE-1"} - new: true - confirm: true - note: "Bonse-Hart collimator crystal stage; channel-cut is a setting; the crystal cut and rocking tolerance are BONSE-1" - - name: AnalyzerStage - family: RotaryStage - pv: {confirm: "Bonse-Hart analyzer stage (UsaxsAnalyzerStageDevice): rocking rotation usxAERO:m6, x/y align, r2p piezo usxLAX:pi:c0:m1; axis detail is BONSE-1"} - new: true - confirm: true - note: "Bonse-Hart analyzer crystal stage; the rocking-curve scan against the collimator is the USAXS measurement (USAXS-1, BONSE-1)" - -# =========================================================================== -# SAMPLE STAGE: the sample stage, rotator, and temperature environments -# =========================================================================== - -sample: - stage: sample - enclosure: 12-ID-E - intro: "The sample positioning stage, the sample rotator, and the in-situ temperature environments." - note: > - The sample stage reuses LinearStage and the sample rotator RotaryStage. The - Linkam T96 and the PTC10 reuse the graduated TemperatureController Family - (presents Regulator). An optional in-situ load frame exists in the instrument's - device library but is not in the active config, so it is carried as a deferred - question (LOADFRAME-1), not modelled as a device here. - devices: - - name: SampleStage - family: LinearStage - pv: {confirm: "USAXS sample stage (UsaxsSampleStageDevice); axis set is SAMPLE-1"} - new: true - confirm: true - note: "sample positioning stage (SAMPLE-1)" - - name: SampleRotator - family: RotaryStage - pv: "usxPI:c867:c0:m1" - new: true - confirm: true - note: "PI C-867 sample rotator (SAMPLE-1)" - - name: LinkamStage - family: TemperatureController - pv: "usxLINKAM:tc1:" - new: true - confirm: true - note: "Linkam T96 temperature stage; reuses the graduated Family (presents Regulator); range is TEMP-1" - - name: Ptc10Controller - family: TemperatureController - pv: "usxTEMP:tc1:" - new: true - confirm: true - note: "PTC10 multi-channel temperature controller; reuses the graduated Family (presents Regulator); channels are TEMP-1" - -# =========================================================================== -# DETECTION STAGE: the autoranging USAXS point detector, the flux monitors, the -# scalers, and the SAXS/WAXS area detectors -# =========================================================================== - -detection: - stage: detection - enclosure: 12-ID-E - intro: "The autoranging USAXS photodiode detector, the incident and transmitted flux monitors, the counting scalers, the detector and SAXS/WAXS stages, and the pinhole SAXS and WAXS area detectors." - note: > - USAXS detection is point / current-integrating: the UPD photodiode reads the - rocked-analyzer intensity through an autoranging Femto transimpedance amplifier - across several gain decades, the science detector. It, and the I0 / I00 / I000 / - TRD monitor channels and the counting scalers, reuse the catalog FluxMonitor (the - BMM quad-electrometer-as-primary precedent; the gain autorange is a device-state - setting, DET-1). The same instrument runs pinhole SAXS and WAXS on Pilatus area - detectors, which reuse Camera. - devices: - - name: PhotodiodeDetector - family: FluxMonitor - pv: { amplifier: "usxLAX:fem09:seq02:", autorange: "usxLAX:pd01:seq02:", photocurrent: "usxLAX:USAXS:upd" } - new: true - confirm: true - note: "UPD photodiode, the primary USAXS detector; autoranging Femto amplifier (DDPCA300) across several gain decades; gain autorange is a device-state setting (DET-1)" - - name: FluxMonitors - family: FluxMonitor - pv: {confirm: "I0 / I00 / I000 / TRD photocurrent channels via Femto amplifiers (usxRIO:fem02-05:seq01:, usxLAX:USAXS:I0/I00/I000/trd); incident and transmitted flux monitors (DET-1)"} - new: true - confirm: true - note: "incident / transmitted flux monitor channels for normalization (DET-1)" - - name: Scaler - family: FluxMonitor - pv: "usxLAX:vsc:c0" - new: true - confirm: true - note: "counting scaler (ScalerCH usxLAX:vsc:c0/c1, Struck SIS3820 usxLAX:3820:) that counts the amplifier channels (DET-1)" - - name: DetectorStage - family: LinearStage - pv: {confirm: "USAXS detector stage (UsaxsDetectorStageDevice) and the SAXS stage; axes are OPT-2"} - new: true - confirm: true - note: "detector translation stages (USAXS + SAXS); axis roles are OPT-2" - - name: SaxsDetector - family: Camera - pv: {confirm: "pinhole SAXS Pilatus area detector (pilatus_module); the AD prefix is DET-1"} - new: true - confirm: true - note: "pinhole SAXS area detector (Detector Role); reuses Camera (DET-1)" - - name: WaxsDetector - family: Camera - pv: { x: "usxAERO:m3", x2: "usxAERO:m7" } - new: true - confirm: true - note: "WAXS area detector on its translation (waxsx / waxs2x); reuses Camera (DET-1)" - -# Cross-cutting control. 12-ID runs EPICS (the floor); CORA observes and, where it -# replaces bluesky-style orchestration, conducts over it. The handles above were -# read from the usaxs-bits instrument config and carried confirm (CTRL-1). -controls: - intro: > - 12-ID runs on the APS EPICS / ophyd control stack, the same floor as the other - APS beamlines. The device handles above are bound from the BCDA-APS usaxs-bits - instrument (its src/usaxs/configs/*.yml device tables and src/usaxs/devices/*.py - classes), carried confirm pending staff verification (CTRL-1). The USAXS - acquisition (the rocking-curve fly-scan trajectory, the amplifier autoranging, - the scaler counting) runs through bluesky plans and the BITS instrument; that - orchestration is the seam CORA's edge replaces, driving through ophyd / EPICS, - while the area-detector file-writing to the APS filestore is plumbing CORA - observes, not data it owns (see model.md). - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a 12-ID run needs. The optics run - under vacuum (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the optics and the flight paths are under vacuum (SUP-1)" diff --git a/deployments/13-id/beamline.yaml b/deployments/13-id/beamline.yaml deleted file mode 100644 index f87effc62ab..00000000000 --- a/deployments/13-id/beamline.yaml +++ /dev/null @@ -1,284 +0,0 @@ -# 13-ID beamline descriptor (APS, GSECARS), reverse-engineered -# -# 13-ID is the GSECARS (GeoSoilEnviroCARS, sector 13) high-pressure X-ray -# diffraction station at APS: monochromatic powder and single-crystal XRD on a sample -# held in a diamond anvil cell (DAC) under extreme pressure and double-sided laser -# heating. It is bound to the APS Site (deployments/aps/site.yaml), and is CORA's -# FIRST extreme-conditions (high-pressure) sample-environment deployment, the axis the -# EMA/Sirius scout flagged as a genuinely new device class with no fleet analog. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the GSECARS EPICS support tree, github.com/CARS-UChicago/GSECARS-EPICS: the -# iocBoot st.cmd / .substitutions, the CARSApp/Db device templates, and the -# CARSApp/op/adl MEDM screens that embed the device PV prefixes) or inferred, carried -# new: true + confirm: true pending GSECARS staff. EPICS PVs are real and read from the -# support tree; this source is EPICS-native (.db / .substitutions / .adl), not a dodal -# or BITS Python roster, so the device-to-PV reconstruction is rougher and carried at -# medium source-confidence. Vendor part numbers, serials, and physical positions beyond -# what the templates name are open questions. Descriptor + docs scaffold; scenarios -# deferred. -# -# WHAT IS NEW: the high-pressure sample environment. CORA has modelled thermal -# (TemperatureController), magnetic (loose Magnet), and pump-probe (catalog Laser) sample -# environments, but never an extreme-PRESSURE one. The DAC is a diamond anvil cell -# whose pressure is loaded by a gas membrane (a GE/Druck PACE5000 pneumatic controller -# pressurising a bellows that squeezes the anvils) to the megabar regime, with the -# sample heated from both sides by two IPG YLR fibre lasers to thousands of kelvin and -# the in-situ pressure and temperature read optically (spectroradiometry of the -# thermal-emission greybody, plus ruby fluorescence / Raman / Brillouin pressure -# metrology). This composite is a genuinely new device class with no fleet analog. -# -# MODELLING: 13-ID introduced the PressureCell Family (now a catalog Family). -# - The DAC binds the catalog PressureCell Family (user-named via naming-r3, -# 2026-06-26; chosen over HighPressureCell / DiamondAnvilCell / AnvilCell because a -# bare regime-generic role-noun spans the DAC, the large-volume press, and clamp -# cells without forcing a near-duplicate family, the Table / InsertionDevice -# device-type-is-a-setting precedent). It graduated on the rule-of-three across -# APS 13-ID and PETRA III P02 (the P02.2 diamond-anvil-cell environment); further -# consumers (HPCAT 16-ID, the 13-BM-D large-volume press, the 4-ID PACE cell) reuse -# it like any catalog Family (HP-1, PRESSURE-1). -# The cell is ONE Asset presenting the Regulator Role for its membrane pressure -# (PACE5000 setpoint + readback); its double-sided laser heating (HEAT-1) and its -# in-situ pressure / temperature metrology (a Sensor capability) are capabilities of -# the same cell, not separate families. -# - The heating lasers do NOT bind the catalog Laser Family: a heating laser is a -# power-delivery / thermal-actuation role, distinct from the pump-probe Laser -# (4-ID / LCLS-MFX). Whether the laser path is a clean TemperatureController -# is HEAT-1 (the live heating is open-loop on commanded power, temperature inferred -# from emission, so it is a power actuator, not a temperature Regulator, today). -# - The XRD probe spine reuses the catalog throughout: the Si DCM binds Monochromator, -# the K-B and carbon mirrors bind Mirror, the slits bind Slit, the clean-up pinhole -# binds Aperture, the attenuator binds Filter, the DAC sample stage binds Goniometer, -# the Eiger2 / Pilatus area detectors and the LightField metrology spectrometer bind -# Camera, the ion chambers and photodiode bind FluxMonitor, the Dante MCA binds -# EnergyDispersiveSpectrometer, the incident energy and the mirror curvature axes -# bind PseudoAxis, the fibre illumination binds the catalog Backlight Family (graduated -# across the MX / imaging fleet, DET-1), and the machine -# state binds the loose StorageRing. -# - High-pressure XRD is NOT a new technique: it reuses the pending diffraction and -# powder_diffraction Methods, with high pressure a Plan / sample-environment -# difference (the 4-ID high-pressure-diffraction precedent, TECH-1). -# -# DEFERRED: the laser-safety PLC (a Koyo DL205 gating laser emission) is the laser- -# enclosure permit / interlock axis, an Enclosure concern, not a device (PSS-1, LASER-1). -# The detector 2theta-arm transform PV was seen only in a Galil test template, so its -# binding is deferred (DET-1). The 13-BM stations and the large-volume press are out of -# this station's scope (HP-1). -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/13-id/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "GSECARS high-pressure X-ray diffraction on a diamond anvil cell, Sector 13; the fleet's first extreme-conditions sample environment" - name: 13-ID - facility: aps # APS Site (facility_code: aps); GSECARS CAT, sector 13 - sector: "Sector 13 (GSECARS)" - tier: Unit - parent: null - source: insertion-device - source_confirm: "13-ID is an undulator sector shared with 13-ID-C / 13-ID-E; the undulator is energy-tracked with the mono but not exposed as a device in the support tree read, so the source detail is SRC-1" - page_layout: stages - shape: "The fleet's first extreme-conditions beamline: the sample sits in a laser-heated diamond anvil cell under gas-membrane pressure, read optically in situ; introduced the PressureCell Family." - source_ref: - label: "CARS-UChicago/GSECARS-EPICS" - url: "https://github.com/CARS-UChicago/GSECARS-EPICS" - -# PV zones: 13IDA (the shared 13-ID-A first optics: Si DCM), 13IDE:En (the derived -# beamline energy), 13IDD (the 13-ID-D endstation: DAC stage, detectors, slits, flux, -# the high-pressure cell), 13IDD_PACE5000 (the membrane pressure controller), -# 13IDD_Dante1 (the MCA), 13EIG2_9M / 13PIL1MCdTe / 13PIL1MSi (the area detectors), -# 13IDDLF1 (the metrology spectrometer), 13RAMAN2 (the metrology excitation host), -# 13IDD_laserPLC (the laser-safety PLC). Whether 13-ID-A and 13-ID-D are separate -# hutches, and the PSS and laser-enclosure permit leaves, are open (ENC-1, PSS-1). -enclosures: - - name: 13-ID-optics - role: optics-hutch - facility_code: aps - permit_signal: {confirm: "PSS permit leaf not in the support tree; the shared 13-ID-A first optics zone, hutch grouping is ENC-1 (PSS-1)"} - - name: 13-ID-D - role: experiment-hutch - facility_code: aps - permit_signal: {confirm: "PSS permit leaf unknown; the 13-ID-D high-pressure endstation; the Koyo laser-safety PLC adds a laser-emission enclosure permit axis (ENC-1, PSS-1, LASER-1)"} - -# =========================================================================== -# SOURCE STAGE: the machine state and the shared 13-ID-A optics -# =========================================================================== - -machine: - stage: source - enclosure: 13-ID-optics - intro: "The machine-level source state, observed not driven." - note: "Observe-only APS machine state, the loose StorageRing pattern reused across the APS deployments (MACHINE-1). The undulator is energy-tracked with the mono but not surfaced as a device here (SRC-1)." - devices: - - name: StorageRing - family: StorageRing # loose Family (machine-level observe-only source state; MACHINE-1) - pv: {confirm: "APS storage-ring state (current, fill, status); observe-only, the exact PVs are MACHINE-1"} - new: true - confirm: true - note: "APS storage-ring state; observe-only (MACHINE-1)" - -optics: - stage: source - enclosure: 13-ID-optics - intro: "The shared 13-ID-A silicon monochromator, the incident-energy axis, the K-B and carbon focusing mirrors, the slits, the clean-up pinhole, and the attenuator." - note: "All reuse existing catalog Families. The DCM binds Monochromator (the 2-BM precedent); the mirrors bind Mirror with their curvature / ellipticity as PseudoAxis; the slits bind Slit; the pinhole binds Aperture; the attenuator binds Filter." - devices: - - name: Monochromator - family: Monochromator - pv: "13IDA:" - new: true - confirm: true - note: "the shared 13-ID-A silicon double-crystal monochromator (status 13IDA_EMONO:); undulator-tracked; crystal cut and energy range are MONO-1" - - name: BeamEnergy - family: PseudoAxis - pv: "13IDE:En" - new: true - confirm: true - note: "the derived beamline-energy virtual axis over the DCM and the tracked undulator (MONO-1)" - - name: FocusingMirror - family: Mirror - pv: {confirm: "the K-B focusing mirror pair (vertical / horizontal, curvature and ellipticity sum-and-difference axes) and the upstream carbon mirrors; coatings and the curvature PseudoAxis are OPT-1"} - new: true - confirm: true - note: "K-B focusing mirror pair plus carbon harmonic-rejection mirrors; curvature / ellipticity bind PseudoAxis (OPT-1)" - - name: BeamSlit - family: Slit - pv: {confirm: "the table-top DAC-defining slits (DACV / DACH) and the upstream beam-defining slits; blade-axis map is OPT-2"} - new: true - confirm: true - note: "the beam-defining and DAC table-top slits (DACV / DACH); blade-axis map is OPT-2" - - name: CleanupPinhole - family: Aperture - pv: {confirm: "the clean-up pinhole on its X / Y / Z carriers, removing the slit-scatter halo before the DAC; the carriers bind LinearStage, the opening binds Aperture (APERTURE-1)"} - new: true - confirm: true - note: "the clean-up pinhole before the cell (APERTURE-1)" - - name: Attenuator - family: Filter - pv: "13IDD:filter:" - new: true - confirm: true - note: "the attenuator paddle / filter set protecting the detector and trimming flux (the 2-BM C / Al precedent); foil set is ATTN-1" - -# =========================================================================== -# SAMPLE STAGE: the diamond anvil cell (the catalog PressureCell family) + the DAC stage -# =========================================================================== - -sample: - stage: sample - enclosure: 13-ID-D - intro: "The diamond anvil cell (the high-pressure sample environment) and the DAC positioning stage / micro-diffractometer." - note: > - The DAC binds the catalog PressureCell Family (HP-1). It is one Asset presenting - the Regulator Role for its membrane pressure (the PACE5000 setpoint + readback); - its double-sided laser heating (HEAT-1) and its in-situ pressure / temperature - metrology are capabilities of the same cell. The DAC positioning stage binds the - catalog Goniometer (the i03 Smargon precedent; the single Omega plus the - Galil-versus-XPS controller are per-Asset settings, SAMPLE-1). - devices: - - name: PressureCell - family: PressureCell # catalog Family, the high-pressure sample environment (HP-1) - pv: "13IDD_PACE5000:PC1:" - new: true - confirm: true - note: "the diamond anvil cell: membrane gas pressure set and read on the PACE5000 (PC1:Setpoint / Pressure_RBV / Control / Vent), presenting the Regulator Role; double-sided IPG YLR laser heating (13IDD:Laser1 / Laser2, power on 13IDD:US_LaserPower / DS_LaserPower) is the cell's heating capability (HEAT-1); the in-situ temperature (spectroradiometry, 13IDD:us_las_temp / ds_las_temp) and pressure (ruby / Raman / Brillouin) are its metrology Sensor capability. catalog Family, graduated on the rule-of-three across 13-ID and PETRA III P02 (PRESSURE-1)" - - name: SampleStage - family: Goniometer - pv: {confirm: "the DAC positioning stage / micro-diffractometer (Galil m1-m4 X / Z / Y / Omega, plus the Newport XPS-16 PSO trajectory stage); single Omega and the Galil-vs-XPS controller are settings (SAMPLE-1)"} - new: true - confirm: true - note: "the DAC sample-positioning stage with the Omega rotation; binds Goniometer (the i03 Smargon precedent); single Omega and the Galil-vs-XPS controller are settings (SAMPLE-1)" - - name: SampleTable - family: Table - pv: {confirm: "the DAC lift table the cell rides on; binds Table (SAMPLE-1)"} - new: true - confirm: true - note: "the DAC lift table supporting the cell (SAMPLE-1)" - - name: MetrologySpectrometer - family: Camera - pv: "13IDDLF1:" - new: true - confirm: true - note: "the LightField (PIMAX / PIXIS) spectrometer reading the thermal-emission and ruby / Raman spectra for the cell's in-situ temperature and pressure metrology; reuses Camera as the metrology detector (HP-1)" - -# =========================================================================== -# DETECTION STAGE: the XRD area detectors, the detector arm, the flux, the MCA -# =========================================================================== - -detection: - stage: detection - enclosure: 13-ID-D - intro: "The high-pressure XRD area detectors, the detector positioning, the incident-flux monitors, and the energy-dispersive MCA." - note: > - All reuse existing catalog Families. The Eiger2 and Pilatus area detectors bind - Camera; the detector table and 2theta arm bind LinearStage and TiltStage (the swing - transform binds PseudoAxis, binding deferred DET-1); the ion chambers and photodiode - bind FluxMonitor; the Dante MCA binds EnergyDispersiveSpectrometer. - devices: - - name: AreaDetector - family: Camera - pv: "13EIG2_9M:" - new: true - confirm: true - note: "the Eiger2 X 9M area detector for high-pressure powder and single-crystal XRD; the Pilatus 1M CdTe / Si (13PIL1MCdTe: / 13PIL1MSi:) are the alternative detectors, CdTe-vs-Si sensor a setting (DET-1)" - - name: DetectorStage - family: LinearStage - pv: {confirm: "the detector table radius and the 2theta / chi arm; the swing transform binds PseudoAxis but its live prefix was seen only in a Galil test template, so the binding is deferred (DET-1)"} - new: true - confirm: true - note: "the detector table and 2theta arm (LinearStage + TiltStage); the 2theta transform PseudoAxis binding is DET-1" - - name: FluxMonitor - family: FluxMonitor - pv: "13IDD:scaler1" - new: true - confirm: true - note: "the ion chambers (scaler1 over the USB-CTR multi-channel scaler) and the DAC photodiode (13IDD:Photodiode) for incident-flux and transmission monitoring (DET-1)" - - name: FluorescenceDetector - family: EnergyDispersiveSpectrometer - pv: "13IDD_Dante1:" - new: true - confirm: true - note: "the XGLab Dante multi-channel-analyzer for energy-dispersive fluorescence (the 2-ID / 7-BM precedent); reuse, not novelty (DET-1)" - - name: SampleIllumination - family: Backlight # catalog Family (DET-1) - pv: "13IDD:US_IllumOnOff" - new: true - confirm: true - note: "the fibre sample illumination (upstream / downstream on / off + splitter) for the viewing microscope; binds the catalog Backlight Family (graduated across the MX / imaging fleet, DET-1)" - -# Cross-cutting control. 13-ID runs EPICS (the floor); CORA observes and, where it -# replaces SPEC / bluesky-style orchestration, conducts over it. The handles above were -# reconstructed from the GSECARS EPICS support tree and carried confirm (CTRL-1). -controls: - intro: > - 13-ID runs on the APS EPICS control stack (GSECARS uses EPICS plus SPEC and Python - orchestration), the same floor as the other APS beamlines. The device handles above - were reconstructed from the public GSECARS EPICS support tree - (github.com/CARS-UChicago/GSECARS-EPICS: the iocBoot st.cmd / .substitutions, the - CARSApp/Db templates, and the CARSApp/op/adl MEDM screens), carried confirm pending - staff verification (CTRL-1). This is an EPICS-native source, so the reconstruction is - rougher than a dodal or BITS roster and carried at medium confidence. The - high-pressure acquisition (the coupled XRD-plus-temperature collection, the balanced - double-sided laser-power ramp, the membrane pressure steps, the metrology spectra) - runs through GSECARS SPEC / Python today; that orchestration is the seam CORA's edge - replaces, conducting over the cell, the sample stage, and the detectors. The - laser-safety PLC (a Koyo DL205, 13IDD_laserPLC: / 13IDD:LaserPLC:) enforces the - laser-emission enclosure permit; CORA observes that permit, it does not model the - interlock logic (LASER-1, PSS-1). The detector file-writing to the APS / GSECARS - filestore is plumbing CORA observes, not data it owns (see model.md). - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a 13-ID run needs. The membrane - pressure controller draws on a high-pressure gas supply (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the optics and flight paths (SUP-1)" - - kind: ProcessGas - note: "the high-pressure gas the PACE5000 uses to load the DAC membrane (SUP-1)" diff --git a/deployments/19-bm/beamline.yaml b/deployments/19-bm/beamline.yaml deleted file mode 100644 index 809d8e4b74a..00000000000 --- a/deployments/19-bm/beamline.yaml +++ /dev/null @@ -1,296 +0,0 @@ -# CORA Beamline descriptor: 19-BM (APS), design phase -# -# 19-BM (formerly branded FACT, Fast Autonomous Computed Tomography) is a planned filtered -# white-beam bending-magnet imaging beamline at the APS (Sector 19), bound to -# the existing APS Site (deployments/aps/site.yaml). It is built for -# high-throughput, autonomous, micron-resolution CT with robotic sample -# handling. -# -# STATUS: design phase. The beamline was under construction when the Final -# Design Report (Alan Kastengren, IMG/XSD, 6 June 2026) was written; first -# light is targeted for the 2026-3 beam cycle. Every value here is an FDR -# design specification, not a commissioned measurement, so every device carries -# `new: true` (not yet modelled in CORA) and `confirm: true` (value to be -# verified by 19-BM staff). EPICS PV names are mostly TBD until the control -# system is brought up, so no `pv` field is invented (CTRL-1). Devices bind to -# catalog Families only, with no `model`, because vendors/part-numbers are not -# yet procured; reused-equipment notes (K1-20, A359-K2, F3-30 from 1-ID) carry -# provenance, not bindings. -# -# Items the FDR defers are tagged inline with a (QUESTION-ID) that is answered -# on docs/deployments/19-bm/questions.md. -# -# Source of truth for the values below: the 19-BM FDR and the docs at -# docs19bm.readthedocs.io. APS sketch ids (A359-Mxx / A359-Kxx / K1-20 / F3-30) -# and ICMS document numbers (PSS APS_1181415, BLEPS APS_2388098) come from the -# FDR; they are carried as plain spec lines, not as typed drawing refs. - -beamline: - maturity: design - evidence: design_report - coverage: full - summary: "bending-magnet autonomous high-throughput tomography (formerly branded FACT)" - name: 19-BM - facility: aps - sector: Sector 19 - tier: Unit - parent: null - source: bending-magnet - source_confirm: "APS bending magnet (M3); 0.8 mrad horizontal acceptance, referenced to an alternate centerline 0.4 mrad inboard of the default new-BM centerline (FDR design phase)" - z_span_mm: [0, 55000] - z_span_confirm: true - page_layout: stages - shape: "A filtered white-beam bending-magnet micro-CT beamline, 2-BM's sibling, built for autonomous high-throughput tomography with a robotic sample changer across three enclosures." - -# Three access-gated enclosures. 19-BM-A is the front-end optics enclosure; -# 19-BM-C is a pure shielded UHV transport with no beam intercepts; 19-BM-D is -# the endstation. 19-BM-C and 19-BM-D share a downstream-wall guillotine held -# open during operation, so they act as one shielded volume from a -# radiation-safety perspective (ENC-1). PSS permit signals are APS facility -# signals, not yet named (PSS-1). -enclosures: - - name: 19-BM-A - role: front-end-optics - facility_code: aps - permit_signal: {confirm: "APS PSS permit signal TBD (PSS-1)"} - note: "FOE: exit mask, slits, filters, bremsstrahlung control, gate valve, UHV transport" - - name: 19-BM-C - role: transport - facility_code: aps - permit_signal: {confirm: "shares the 19-BM-D search/secure volume via the held-open guillotine; permit arrangement TBD (ENC-1, PSS-1)"} - note: "shielded UHV transport only; the beam passes through entirely in vacuum, no intercepts, so no Device Assets are registered here" - - name: 19-BM-D - role: endstation - facility_code: aps - permit_signal: {confirm: "APS PSS permit signal TBD (PSS-1)"} - note: "endstation: Be + Kapton windows, in-air sample stage, indirect-detection imaging, downstream beam stops" - -# --- SOURCE STAGE: beam delivery and conditioning in 19-BM-A (FOE) --- - -source: - stage: source - enclosure: 19-BM-A - intro: "The bending-magnet source. 19-BM accepts 0.8 mrad of the available horizontal BM fan, referenced to an alternate centerline 0.4 mrad inboard of the default new-BM centerline. The source is recorded as a Supply (PhotonBeam), not an Asset." - note: > - Filtered white-beam only: there is no monochromator and no mirror optics, so - the spectrum is set entirely by the filter unit, not by optic moves. All - 19-BM components that intercept synchrotron radiation are water-cooled and - covered by the APSU bending-magnet thermal-analysis waiver (ICMS - APSU_2286907). - devices: - - name: Source - family: Beam - new: true - confirm: true - kind: "APS bending magnet (M3 magnet)" - max_fan: "2.7 mrad horizontal (front-end first-mask limit 2.5 mrad)" - used_acceptance: "0.8 mrad horizontal" - centerline_offset: "0.4 mrad inboard of the default new-BM centerline" - note: "bending-magnet source, recorded as a Supply(kind=PhotonBeam), not an Asset; renders as a loose family" - -front-end: - stage: source - enclosure: 19-BM-A - intro: "The front-end termination and beam-defining apertures in 19-BM-A: the single exit Be window bolted to the exit mask, the bremsstrahlung collimators, the white-beam slits, the filter unit, and the vacuum isolation gate valve." - note: > - The 19-BM design removes one of the two front-end Be windows at ~23 m (to - minimise wavefront-distorting scatter) and in exchange terminates the - beamline vacuum at ~50 m with the water-cooled Be window at the entrance of - 19-BM-D. The only components that intercept the beam in 19-BM-A are the exit - mask, the slits, and the filters. - devices: - - name: FEExitWindow - family: Window - z_mm: 23000 - new: true - confirm: true - material: beryllium (FE-standard thickness) - cooling: integrated with the front end - note: "single front-end exit Be window; bolted rigidly to the exit mask A359-M20 so the two share one survey fiducial" - - name: ExitMask - family: Mask - z_mm: 23000 - new: true - confirm: true - passive: true - sketch: A359-M20 - acceptance: "0.8 mrad horizontal (of 2.5 mrad available from the FE)" - centerline_offset: "0.4 mrad inboard of the default new-BM centerline" - cooling: water-cooled (APSU BM thermal-waiver scope) - classification: "RSS component; PSS-tracked under ICMS APS_1181415" - survey: "fiducialised before installation; cannot be re-aligned in place" - note: "first in-line aperture; limits the transmitted fan to the 0.8 mrad acceptance" - - name: UpstreamCollimator - family: Collimator - new: true - confirm: true - passive: true - sketch: K1-20 - material: Pb - note: "first lead bremsstrahlung collimator (reused former insertion-device front-end collimator); immediately downstream of the exit mask" - - name: WhiteBeamSlit - family: Slit - new: true - confirm: true - cooling: water-cooled (intercepts white beam) - note: "defines the horizontal and vertical beam footprint; also a vacuum conductance limit sufficient to maintain control during a downstream breach" - - name: FilterUnit - family: Filter - new: true - confirm: true - sketch: F3-30 - materials: "Si, Ge, and Cu filter media in two selectable banks" - cooling: water-cooled - banks: "Bank 1 (Open / Si 1000 / Ge 330 / Ge 830 / Cu 2000 um); Bank 2 (Open / Si 1000 / Ge 500 / Ge 1000 / slot 5 TBD um); combining gives Si 1000/2000, Ge 330/500/830/1000/1330/1830, Cu 2000 um equivalent (FILTER-1)" - note: "modified F3-30 carriage reused from 1-ID; filters the white beam to the desired spectrum and reduces downstream heat load" - - name: BeamlineVacuum - family: Vacuum - new: true - confirm: true - vacuum: "UHV, ion-pumped, no water-to-vacuum joints (APS Engineering Standard APS_2018473)" - gate_valve: "isolates 19-BM-A from the rest of the beamline; interlocked to vacuum sensors and coordinated with the FE exit valve by the BLEPS (ICMS APS_2388098) (BLEPS-1)" - note: "the vacuum system and its isolation gate valve, recorded as a Supply(kind=Vacuum) observation rather than an actuatable Asset, following 2-BM" - - name: DownstreamCollimator - family: Collimator - new: true - confirm: true - passive: true - sketch: A359-K2 - material: Pb - note: "second lead bremsstrahlung collimator, after the gate valve (reused first-collimator assembly from the previous 19-BM beamline)" - -# --- SAMPLE STAGE: the in-air endstation in 19-BM-D --- -# 19-BM-C carries the shielded UHV transport only and registers no devices; it -# is declared above as an enclosure. - -endstation: - stage: sample - enclosure: 19-BM-D - intro: "The in-air sample environment in 19-BM-D. The beamline vacuum terminates at the water-cooled Be window; a short rough-vacuum section protects that window before the Kapton window transitions to air, where the sample stage sits in the white beam." - note: > - The detailed sample-manipulator design and the future robotic sample - changer are out of FDR scope and are carried as questions (STAGE-1, - ROBOT-1); they expand as the endstation is commissioned. - devices: - - name: DEntryWindow - family: Window - z_mm: 50000 - new: true - confirm: true - material: beryllium, 250 um - cooling: "water-cooled, in series with the downstream photon stop A359-M100; flow monitored by the BLEPS (BLEPS-1)" - note: "beamline-vacuum terminus at the entrance to 19-BM-D; separates UHV from the rough-vacuum / air section" - - name: RoughVacuumSection - family: Vacuum - new: true - confirm: true - note: "short rough-vacuum volume just downstream of the Be window, to protect it from oxidation in the warm air of the experimental enclosure" - - name: KaptonWindow - family: Window - new: true - confirm: true - material: Kapton - note: "transition from the rough-vacuum protective section to the in-air experimental volume" - - name: SampleRotary - family: RotaryStage - new: true - confirm: "sample-manipulator design out of FDR scope; rotary + linear stack, model TBD (STAGE-1)" - note: "tomographic rotation axis, in air; the candidate master clock for high-throughput triggering (TRIG-1)" - - name: SamplePositioning - family: LinearStage - new: true - confirm: "sample-manipulator design out of FDR scope; model TBD (STAGE-1)" - note: "sample centring / positioning stage carried on the rotation stack; designed to host the robotic sample changer (ROBOT-1)" - -# --- DETECTION STAGE: the indirect-detection imaging system in 19-BM-D --- - -detector: - stage: detection - enclosure: 19-BM-D - intro: "The indirect-detection imaging system: a scintillator converts the transmitted X-ray image to visible light, visible-light microscope optics relay it, and a camera records 2-D projections that are reconstructed off-line into 3-D micron-resolution tomograms." - note: > - Specific scintillator, microscope-optics, and camera selections are procured - after the FDR and are carried as questions (DET-1). The microscope composes - the cross-facility `Microscope` Assembly (scintillator + optics + camera - presenting the Detector Role), the same blueprint 2-BM uses; it is not a - Family of its own. - devices: - - name: DetectorStage - family: Table - new: true - confirm: true - note: "positions the indirect-detection system in air, downstream of the sample; axis layout TBD" - - name: Scintillator - family: Scintillator - new: true - confirm: "scintillator selection procured post-FDR (DET-1)" - note: "converts the X-ray projection to a visible-light image" - - name: Microscope - family: Housing - new: true - confirm: "microscope-optics selection procured post-FDR (DET-1)" - note: "the visible-light microscope chassis: a Housing that anchors the cross-facility Microscope Assembly (scintillator + optics + camera) presenting the Detector Role; the Fixture is registered once hardware is chosen" - - name: Camera - family: Camera - new: true - confirm: "camera selection procured post-FDR (DET-1)" - note: "records 2-D projection images for off-line reconstruction" - -beam-stops: - stage: detection - enclosure: 19-BM-D - intro: "The photon and bremsstrahlung stops at the downstream end of 19-BM-D, plus the extra downstream-wall shielding required for a white-beam BM station." - note: "all RSS / safety elements at the downstream wall; the guillotines provide the APS TB-44 extra lead area." - devices: - - name: PhotonStop - family: BeamStop - new: true - confirm: true - passive: true - sketch: A359-M100 - material: water-cooled copper block - cooling: "water-cooled, in series with the upstream Be window; flow monitored by the BLEPS (BLEPS-1)" - note: "absorbs the transmitted white beam after the sample / detector region" - - name: BremsstrahlungStop - family: BeamStop - new: true - confirm: true - passive: true - sketch: A359-K3 - material: chevron stack of lead bricks - note: "absorbs bremsstrahlung behind the photon stop, at the downstream wall" - - name: DownstreamGuillotines - family: Shielding - new: true - confirm: true - passive: true - material: "Pb, >= 12 mm thick each (two guillotines)" - note: "movable PSS-grade shielding on the inside of the downstream wall; the 1 x 1 m2 extra-lead area required by APS TB-44; aligned in place (no internal fiducialisation). One is held open during operation, coupling 19-BM-C and 19-BM-D into one shielded volume (ENC-1)" - -# Cross-cutting drive electronics and triggering. 19-BM runs EPICS (APS -# standard); PV names and the trigger scheme are TBD. -controls: - intro: > - The control stack is EPICS (APS standard), expected to follow the 2-BM - TomoScan / MCTOptics idioms; PV names are not yet assigned (CTRL-1). - triggering: - - name: Triggering - family: TimingController - new: true - confirm: "high-throughput trigger/sync scheme TBD; the sample rotary TTL encoder is the candidate master clock, possibly with PSO-style fly-scan triggering (TRIG-1)" - note: "trigger/sync hardware for autonomous high-throughput acquisition" - software_iocs_not_modeled: - - "EPICS IOCs (TomoScan, area-detector, motion) are referenced by PV prefix once assigned, never registered as Assets (CTRL-1)" - -# Continuously-available resources a run draws on (design phase). The facility -# tracks their availability; equipment-protection (BLEPS) folds vacuum and -# cooling-water faults into the beam-availability signal (BLEPS-1). -resources: - intro: > - The continuously-available APS facility resources a run needs present before - it can start. Availability is observed through the BLEPS for the - equipment-protection legs (vacuum, cooling water). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/2-id/beamline.yaml b/deployments/2-id/beamline.yaml deleted file mode 100644 index 6785f047c14..00000000000 --- a/deployments/2-id/beamline.yaml +++ /dev/null @@ -1,185 +0,0 @@ -# CORA Beamline descriptor: 2-ID (APS), design phase -# -# 2-ID is the APS hard X-ray microprobe beamline in Sector 2 (Argonne): one -# insertion-device source feeding more than one experiment hutch. This scaffold -# models its 2-ID-D hutch, the scanning fluorescence microprobe, the same way the -# 32-ID scaffold modelled only the 32-ID-C TXM hutch and deferred the rest. 2-ID -# is bound to the APS Site (deployments/aps/site.yaml), the same Site as 2-BM. -# -# STATUS: design phase. This scaffold is mined from the APS-microprobe integration -# in the Experiment Automation Agents (EAA) project (github.com/AdvancedPhotonSource/EAA, -# packages/eaa-imaging .../tool/imaging/aps_mic) and its 2-ID-D launcher -# (github.com/AdvancedPhotonSource/eaa_driver_scripts_aps_2idd). EAA is mined as -# DATA to learn the beamline FROM, not mirrored as a spec: CORA's Conductor -# replaces EAA's scan and autofocus orchestration over EPICS, and EAA registers as -# an external Agent (see docs/deployments/2-id/model.md). The launcher is a pure -# simulation, so it yields no real PV handles, detector identities, or motor -# bindings; none are invented here. -# -# The verified function (the 2-ID-D hutch) is a sample-scanning XRF microprobe: a -# Fresnel zone plate focuses the monochromatic beam to a spot, the sample is -# rastered through it (fly 2D / step 1D), and an energy-dispersive detector records -# the fluorescence spectrum per point. The source-side optics (undulator, -# monochromator) sit upstream, shared across the sector's hutches, and are NOT -# described by EAA, so they are carried thin and confirm; the focusing zone plate -# and the sample and detection chain in 2-ID-D are the parts EAA evidences. -# -# Every device carries new: true (not yet modelled in CORA) and confirm: true -# (value to be verified with 2-ID staff). Control handles (pv) and vendor models -# are omitted on purpose. New device classes bind to loose Family strings (rendered -# as plain text), not coined catalog Families. -# -# DELIBERATELY OUT OF THIS SCAFFOLD (recorded on docs/deployments/2-id/model.md, -# not modelled here): the sister experiment hutch (a 2-ID-E-class station) and the -# rest of the sector's hutch roster; micro-XANES and ptychography (named by -# world-facts, not in EAA's aps_mic code path); scanning fluorescence tomography (a -# Plan setpoint over the scanning-XRF Method, not a new Method, and needs a -# rotation axis not evidenced here); and the coining of a scanning-fluorescence- -# microscopy Method and a fluorescence-detector Family (naming-review decisions, -# not made in a design-phase scaffold). -# -# THE TOPOLOGY QUESTION (TOPO-1): Sector 2's hutch roster, which hutch the source -# optics serve, the optics-hutch identity, and the post-APS-U sector layout are -# unconfirmed. This scaffold models one root Unit Asset 2-ID with one modelled -# experiment hutch (2-ID-D) and flags the multiplicity and the optics location as -# TOPO-1, rather than committing to a hutch roster or an optics-hutch name the -# corpus does not give. -# -# Items the corpus leaves open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/2-id/questions.md. - -beamline: - maturity: design - evidence: narrative - coverage: full - summary: "scanning fluorescence microprobe (2-ID-D hutch), mined from the EAA toolkit" - name: 2-ID - facility: aps # APS, the Site-level Facility (facility_code: aps) - sector: "Sector 2" # organizational label, not a registered asset - tier: Unit - parent: null - source: insertion-device - source_confirm: "Sector 2 undulator; exact device type, period, and the post-APS-U source configuration unconfirmed (SRC-1, TOPO-1)" - page_layout: stages - shape: "A scanning X-ray fluorescence microprobe (the 2-ID-D hutch of a multi-hutch insertion-device beamline): it rasters a focused spot and reads the fluorescence spectrum per point, mined from the EAA automation tooling." - source_ref: - label: "AdvancedPhotonSource/EAA" - url: "https://github.com/AdvancedPhotonSource/EAA" - -# The one experiment hutch this scaffold models: 2-ID-D, the scanning fluorescence -# microprobe. The sister station(s) and a shared upstream optics hutch are flagged -# as TOPO-1, not declared, because the corpus does not name them. The source -# groups (undulator, monochromator) sit upstream of 2-ID-D and leave their -# enclosure unset rather than assert they live in the experiment hutch; the -# focusing optics, sample stage, and detector are in 2-ID-D. The PSS permit signal -# is an APS facility signal, not yet on file (PSS-1). -enclosures: - - name: 2-ID-D - role: experiment-hutch - facility_code: aps - permit_signal: {confirm: "APS PSS search-and-secure signal TBD (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the upstream source and beam-conditioning optics -# (shared across the sector; EAA-undescribed, carried thin) -# =========================================================================== - -insertion-device: - stage: source - intro: "The Sector 2 insertion-device source, upstream of the hutches. EAA does not describe the source, so it is carried thin and confirm as a single undulator pending the source table and the post-APS-U configuration." - note: "Modelled as one InsertionDevice Asset. Device type, period, and gap, and whether the front end feeds more than one hutch, are unconfirmed (SRC-1, TOPO-1)." - devices: - - name: Undulator - family: InsertionDevice - new: true - confirm: true - note: "Sector 2 undulator source; type and period unconfirmed (SRC-1)" - -monochromator: - stage: source - intro: "The monochromator that selects the scanning energy, in the upstream optics area. A hard X-ray microprobe runs monochromatic; the device is carried as a double-crystal monochromator pending confirmation, since EAA does not describe the optics." - note: "Presence assumed from the technique (a monochromatic scanning microprobe); crystal, energy range, axes, and the optics-hutch it sits in unconfirmed (MONO-1, TOPO-1)." - devices: - - name: Monochromator - family: Monochromator - new: true - confirm: true - note: "double-crystal monochromator assumed; crystal and energy range unconfirmed (MONO-1)" - -focusing-optics: - stage: source - enclosure: 2-ID-D - intro: "The probe-forming optic in the 2-ID-D hutch: a Fresnel zone plate focuses the monochromatic beam to the scanning spot just upstream of the sample. This is the defining optic of the microprobe and the one EAA's autofocus loop drives (the zp_z focus axis)." - note: > - The zone plate binds the catalog ZonePlate Family (graduated with 32-ID + FXI). - Its focus axis (zp_z in EAA) is the actuator CORA's Conductor would drive during - autofocus; the order-sorting aperture standard to a zone-plate microprobe is not - evidenced and is folded into OPTICS-1, not invented. - devices: - - name: ZonePlate - family: ZonePlate - new: true - confirm: true - note: "probe-forming Fresnel zone plate with a zp_z focus axis (EAA aps_mic autofocus); outermost-zone width, diameter, and the order-sorting aperture unconfirmed (OPTICS-1)." - -# =========================================================================== -# SAMPLE STAGE: the sample-scanning stack in the 2-ID-D hutch (the raster axes) -# =========================================================================== - -sample-stage: - stage: sample - enclosure: 2-ID-D - intro: "The sample-scanning stack in 2-ID-D: the sample is rastered through the focused spot (fly 2D / step 1D) while the fluorescence detector reads each point. This is the moving part of the microprobe and the one EAA's scan_control drives." - note: > - Modelled coarsely as one sample-positioning stack pending the confirmed axis - complement. EAA evidences a vertical raster axis (samy) and a standoff axis - (samz); the horizontal scan axis is inferred, and the coarse-versus-fine - (piezo) split a real microprobe carries is unconfirmed (AXIS-1). No rotation - axis is evidenced, so scanning fluorescence tomography is deferred (see model.md). - devices: - - name: SamplePositioning - family: LinearStage - new: true - confirm: true - note: "sample-scanning stack; vertical raster (samy) and standoff (samz) evidenced, horizontal scan axis and coarse/fine piezo split unconfirmed (AXIS-1)" - -# =========================================================================== -# DETECTION STAGE: the energy-dispersive fluorescence detector in 2-ID-D -# =========================================================================== - -fluorescence-detector: - stage: detection - enclosure: 2-ID-D - intro: "The energy-dispersive detector in 2-ID-D that records the X-ray fluorescence spectrum at each scan point; element maps are fit from the spectra downstream (EAA's XRF-Maps lineage)." - note: > - Binds the catalog EnergyDispersiveSpectrometer Family (graduated once 2-ID and - 7-BM shared it), presenting the Sensor Role. The readout chain EAA names (a - preamplifier and EPICS scalers, plus the I0 flux monitors a microprobe - normalizes against) is the detection electronics, identities unconfirmed (DET-2). - devices: - - name: FluorescenceDetector - family: EnergyDispersiveSpectrometer - new: true - confirm: true - note: "energy-dispersive fluorescence detector; element channels, model, and segmentation unconfirmed (DET-1)." - -# Cross-cutting control. 2-ID runs EPICS (the floor) with a Bluesky RunEngine over -# the EPICS scanRecord for the raster. CORA observes and, where it replaces EAA's -# scan and autofocus orchestration, conducts over it. Control handles are not in -# the corpus (the launcher is a simulation), so none are bound (CTRL-1). -controls: - intro: > - 2-ID runs on EPICS, like 2-BM, with a Bluesky RunEngine submitting the fly-2D - and step-1D rasters over the EPICS scanRecord (EAA aps_mic). The drive crates, - IOC hosts, and PV handles are not in the EAA corpus (its 2-ID-D launcher is a - simulation) and are left unbound (CTRL-1). - -# Continuously-available resources a run draws on (design phase). -resources: - intro: > - The continuously-available facility resources a 2-ID-D run needs, carried - pending in the design phase. The endstation supplies (cooling, any - sample-environment gases) are unconfirmed (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater diff --git a/deployments/32-id/beamline.yaml b/deployments/32-id/beamline.yaml deleted file mode 100644 index 99dec8d0ae5..00000000000 --- a/deployments/32-id/beamline.yaml +++ /dev/null @@ -1,280 +0,0 @@ -# CORA Beamline descriptor: 32-ID (APS), design phase -# -# 32-ID is a canted insertion-device beamline at APS (Argonne). It is bound to -# the APS Site (deployments/aps/site.yaml), the same Site as the 2-BM pilot. -# -# STATUS: design phase. This scaffold models only what the published 32-ID docs -# (github.com/decarlof/32id-docs) state with confidence: the shared optics-hutch -# spine and the transmission X-ray microscope (TXM) endstation in 32-ID-C. Every -# device carries `new: true` (not yet modelled in CORA) and `confirm: true` -# (value to be verified with 32-ID staff), because the source corpus mixes -# pre-APS-U and current values. Control handles (`pv`) and vendor `model`s are -# omitted on purpose: PV names are not published and parts are not catalogued, so -# none are invented. Devices bind to catalog Families where one fits, or to a -# loose Family string (rendered as plain text) where the device class is genuinely -# new and not yet earned into the catalog (the TomoWISE HeatAbsorber precedent). -# -# DELIBERATELY OUT OF THIS SCAFFOLD (recorded on docs/deployments/32-id/model.md, -# not modelled here): the 32-ID-B white-beam high-speed imaging (HSI) and -# ultrafast white-beam diffraction (HSID) instruments; the additive-manufacturing -# (AM) powder-bed-fusion laser rig; and the in-house projection microscope (PM, -# still "space holder" in the source docs). These leave CORA's tomography and -# imaging heritage (diffraction, an actuated laser, a robotic sample changer) and -# are owner-scope decisions, not staff facts. -# -# THE CANTED QUESTION (TOPO-1): 32-ID is canted, two undulators in one straight -# section feeding two experimental branches (32-ID-B white beam, 32-ID-C mono). -# Whether the 32-ID-A optics below are shared by both branches or duplicated -# per-branch, and which undulator feeds which branch, is the single structural -# unknown. This scaffold models one root Unit Asset and one optics train, and -# flags the multiplicity as TOPO-1 rather than committing to two roots. -# -# Items the docs leave open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/32-id/questions.md. - -beamline: - maturity: design - evidence: narrative - coverage: partial - summary: "canted multi-instrument: optics spine and transmission X-ray microscope" - name: 32-ID - facility: aps # APS, the Site-level Facility (facility_code: aps) - sector: "Sector 32" # organizational label, not a registered asset - tier: Unit - parent: null - source: insertion-device - source_confirm: "canted pair of planar undulators (downstream Planar 1.35, upstream Planar 2.8; U33 tuning curve published); the two feed the two branches, mapping unconfirmed (TOPO-1, SRC-1)" - z_span_mm: [24000, 70000] # front-end mask (~24 m) to C-hutch detector; approximate (LAYOUT-1) - z_span_confirm: "approximate; the published layout gives no single z reference (LAYOUT-1)" - page_layout: stages - shape: "A canted-source, three-station beamline hosting four in-house instruments; CORA models the transmission X-ray microscope (TXM) that sits in its tomography heritage and defers the rest." - source_ref: - label: "decarlof/32id-docs" - url: "https://github.com/decarlof/32id-docs" - -# Three lead-shielded stations, all rated for white and mono beam. 32-ID-A holds -# beam-defining optics only (no experiments); 32-ID-B and 32-ID-C are the two -# experimental hutches. PSS permit signals are APS facility signals, not yet on -# file (PSS-1). 32-ID-B is declared because it is a real access-gated hutch, but -# its instruments (HSI, AM) are out of this scaffold (see model.md). -enclosures: - - name: 32-ID-A - role: optics-hutch - facility_code: aps - permit_signal: {confirm: "APS PSS search-and-secure signal TBD (PSS-1)"} - - name: 32-ID-B - role: experiment-hutch - facility_code: aps - permit_signal: {confirm: "APS PSS search-and-secure signal TBD (PSS-1)"} - - name: 32-ID-C - role: experiment-hutch - facility_code: aps - permit_signal: {confirm: "APS PSS search-and-secure signal TBD (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the 32-ID-A optics spine, shared by both branches (TOPO-1) -# =========================================================================== - -insertion-devices: - stage: source - enclosure: 32-ID-A - branch: A-shared - intro: "The canted source: two planar undulators in one straight section, angled apart to feed the two experimental branches. The U33 tuning curve is published; exact device types and which undulator feeds which branch are unconfirmed." - note: > - Modelled as two InsertionDevice Assets for the canted pair. The downstream - and upstream labels follow the published source table; the planar-period and - U33 relationship are carried as SRC-1, the branch mapping as TOPO-1. - devices: - - name: Undulator_DS - family: InsertionDevice - new: true - confirm: true - device_type: planar-undulator - label: "Planar 1.35 (downstream source)" - note: "downstream canted undulator; feeds one branch (TOPO-1)" - - name: Undulator_US - family: InsertionDevice - new: true - confirm: true - device_type: planar-undulator - label: "Planar 2.8 (upstream source)" - note: "upstream canted undulator; feeds the other branch (TOPO-1)" - -front-end: - stage: source - enclosure: 32-ID-A - branch: A-shared - intro: "The fixed beam-defining mask, front-end window, and white-beam slits that shape and condition the beam before the monochromator." - note: > - Mask, Window, and BeamStop are shared catalog Families, as at 2-BM. JJ X-Ray - slits are a four-motor compact slit set on a Beckhoff controller (manual_002). - devices: - - name: FrontEndMask - family: Mask - z_mm: 24000 - new: true - confirm: true - note: "fixed beam-defining aperture; size and exact position unconfirmed (SRC-2)" - - name: FrontEndWindow - family: Window - new: true - confirm: true - note: "front-end window (Be assumed); count and thickness unconfirmed (SRC-2)" - - name: WhiteBeamSlit - family: Slit - new: true - confirm: true - mechanism: "four motors: per dimension one sets aperture size, one sets position" - note: "JJ X-Ray compact high-precision slits on a Beckhoff controller (manual_002); the primary slits lose calibration on IOC restart (troubleshoot_002)" - -optics-hutch: - stage: source - enclosure: 32-ID-A - branch: A-shared - intro: "The Si(111) monochromator and the P4-50 mode shutter that select between white-beam and monochromatic operation. The monochromator serves the monochromatic branch; in white-beam mode it is bypassed." - note: > - The white-to-mono switch is a coordinated, safety-interlocked move (the P4-50 - mode shutter plus a white-beam stop and combined monochromatic stops, - safety_001). Whether CORA models it as a new Capability or as an extension of - the existing energy_change vocabulary is an owner decision (see model.md); - the world-fact half is MODE-1. - devices: - - name: Monochromator - family: Monochromator - new: true - confirm: true - crystal: Si(111) - energy_range: 7 to 40 keV - note: "double-crystal monochromator; bypassed in white-beam mode; per-axis motors and saved positions unconfirmed (MONO-1)" - - name: ModeShutter - family: Shutter - new: true - confirm: true - note: "P4-50 mode shutter selecting white-beam vs monochromatic mode; switching sequence and interlock unconfirmed (MODE-1, safety_001)" - - name: WhiteBeamStop - family: BeamStop - new: true - confirm: true - note: "white-beam stop positioned and locked per mode change (safety_001)" - - name: MonochromaticBeamStop - family: BeamStop - new: true - confirm: true - note: "combined monochromatic-beam stops set per mode change (safety_001)" - -safety-shutters: - stage: source - enclosure: 32-ID-A - branch: A-shared - intro: "The personnel-safety shutters between the optics hutch and the experimental hutches, gated by the PSS." - note: "PSS permit signals TBD (PSS-1)." - devices: - - name: StationShutter - family: Shutter - new: true - confirm: true - note: "safety shutter gating beam into the experimental hutches; PV TBD (PSS-1)" - -# =========================================================================== -# SAMPLE STAGE: the TXM endstation in 32-ID-C (the one instrument scaffolded) -# =========================================================================== - -txm-endstation: - stage: sample - enclosure: 32-ID-C - branch: C - intro: "The in-house transmission X-ray microscope (TXM): a granite-supported sample stage carrying the rotation axis and the zone-plate optics for in-situ nano-tomography. This is 32-ID's tomography instrument and the one endstation this scaffold models." - note: > - The published TXM overview mixes pre-APS-U and current hardware (TXM-1), so - every device is carried confirm. The TXM-specific optics (condenser, objective - zone plate, phase ring) bind to the Condenser, ZonePlate, and PhaseRing catalog - Families, which graduated once FXI became a second deployment sharing them. - Their optical details are OPTICS-1..3. - devices: - - name: TXMGranite - family: Table - z_mm: 64000 - new: true - confirm: true - note: "granite stage support carrying the TXM sample system and optics (TXM overview labels 1, 4, 5)" - - name: TXMRotary - family: RotaryStage - new: true - confirm: true - note: "tomographic rotation axis (Aerotech assumed); model and encoder unconfirmed (TXM-1)" - - name: TXMSamplePositioning - family: LinearStage - new: true - confirm: true - note: "sample centring and alignment stack (Kohzu assumed); axes and travel unconfirmed (TXM-1)" - - name: Condenser - family: Condenser - new: true - confirm: true - note: "beam-condensing optic upstream of the sample (capillary or condenser zone plate); type unconfirmed (OPTICS-1). Catalog Family (graduated once FXI shared it)" - - name: ZonePlate - family: ZonePlate - new: true - confirm: true - note: "objective Fresnel zone plate forming the magnified image; outermost-zone width and diameter unconfirmed (OPTICS-2). Catalog Family (graduated once FXI shared it)" - - name: PhaseRing - family: PhaseRing - new: true - confirm: true - note: "Zernike phase ring for phase contrast, inserted or retracted (txm img phase_ring_out); details unconfirmed (OPTICS-3). Catalog Family (graduated once FXI shared it)" - -# =========================================================================== -# DETECTION STAGE: the TXM detector chain in 32-ID-C -# =========================================================================== - -txm-detector: - stage: detection - enclosure: 32-ID-C - branch: C - intro: "The TXM indirect-detection chain: a scintillator, microscope objective, and camera on a granite-supported detector stack, downstream of a flight path that reduces air scatter." - note: > - Reuses the existing detector Families (Scintillator, Objective, Camera, - Housing). The flight path is helium-filled in the projection microscope; for - the TXM the path-gas and flight-tube details are unconfirmed (SUP-1). - devices: - - name: TXMDetectorSupport - family: Table - new: true - confirm: true - note: "granite detector support and follower mechanics (TXM overview labels 3, 10)" - - name: TXMObjective - family: Objective - new: true - confirm: true - note: "visible-light microscope objective coupling the scintillator image to the camera; magnification set unconfirmed (DET-2)" - - name: TXMScintillator - family: Scintillator - new: true - confirm: true - note: "converts the X-ray image to visible light; material and thickness unconfirmed (DET-2)" - - name: TXMCamera - family: Camera - new: true - confirm: true - note: "detector camera; model, sensor, and frame rate unconfirmed (DET-1)" - -# Cross-cutting control. 32-ID runs EPICS (the floor); CORA observes and, where -# it replaces TomoScan-style orchestration, conducts over it. Control handles are -# not published, so none are bound (CTRL-1). -controls: - intro: > - 32-ID runs on EPICS, like 2-BM. The drive crates, IOC hosts, and PV handles - for each device are not published in the source docs and are left unbound - (CTRL-1). The TXM is operated from the TXMTWO workstation, reachable remotely - over delos.aps.anl.gov (manual_005). - -# Continuously-available resources a run draws on (design phase). -resources: - intro: > - The continuously-available facility resources a 32-ID run needs. Carried - pending in the design phase; the flight-path gas (helium) is unconfirmed for - the TXM (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/4-id/beamline.yaml b/deployments/4-id/beamline.yaml deleted file mode 100644 index 2ce5b31bf61..00000000000 --- a/deployments/4-id/beamline.yaml +++ /dev/null @@ -1,502 +0,0 @@ -# CORA Beamline descriptor: 4-ID (APS), operational-PV first cut -# -# 4-ID (formerly branded POLAR) is the polarization and magnetic-scattering beamline at APS (Argonne), -# operational across stations 4-ID-A (optics), 4-ID-B, 4-ID-G, and 4-ID-H. It is -# bound to the APS Site (deployments/aps/site.yaml), the same Site as the 2-BM -# pilot. It is CORA's first non-tomography APS deployment: diffraction, magnetism, -# and X-ray polarization control rather than imaging. -# -# STATUS: first cut, reverse-engineered. Unlike the 7-BM / 32-ID design-phase -# scaffolds, this descriptor binds the real EPICS control handles (`pv`), because -# 4-ID is operational and its handles were read from the beamline's own Bluesky -# instrument repo (BCDA-APS/polar-bits). A second snapshot of the -# same instrument (BCDA-APS/6idb-bits, a 4-ID fork carrying a grafted 6-ID-B psic -# endstation) was cross-checked to fill a few gaps (the emag magnet axes, the Euler -# diffractometer chi/phi circles); see docs/deployments/4-id/model.md. Every value is still -# carried `confirm: true` until 4-ID staff verify it: a PV read from the operator's -# config is strong evidence, not a CORA-owned fact (the docs-drift rule). Devices -# carry `new: true` (not yet registered in CORA). No vendor `model` is bound (parts -# are not catalogued). Devices bind to a catalog Family where one fits, or to a -# loose Family string (rendered as plain text) where the device class is genuinely -# new and not yet earned into the catalog. -# -# DELIBERATELY OUT OF THIS CUT (recorded on docs/deployments/4-id/model.md): -# - The 4-ID-Raman station: its devices.yml is a symlink that did not resolve in -# the source clone, so it did not extract. Scope + devices are TOPO-2. -# - Assembly(Diffractometer): the Huber diffractometers are modelled here as -# plain devices with axis maps; the reusable Assembly (RotaryStage circles + -# reciprocal-space PseudoAxis, the Microscope pattern) is designed on model.md -# and deferred until a scenario registers a Fixture (DIFF-1). -# - Integration scenarios, vendor Models, z-positions. -# -# PREFIX-INFERENCE CAVEATS (TOPO-3): the extractor inferred a "4-ID-D" enclosure -# from `4iddMZ0:` (the SGZ Vortex fluorescence detector) and a "4-ID-K" from -# `4idkepco:` (a Kepco magnet power supply; "kepco" is a vendor, not a station). -# Neither is treated as a real enclosure here; both devices are placed in their -# best-guess station with a confirm note. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/4-id/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "polarization and magnetic scattering across four stations (formerly branded POLAR); introduces the POLAR polarization / magnetism vocabulary (the graduated `PhaseRetarder`, `PolarizationAnalyzer`, and `Magnet` catalog Families)" - name: 4-ID - facility: aps # APS, the Site-level Facility (facility_code: aps) - sector: "Sector 4" # organizational label, not a registered asset - tier: Unit - parent: null - source: insertion-device - source_confirm: "undulator pair on the S04ID straight section (PolarUndulatorPair, prefix S04ID:); periods and gaps unconfirmed (SRC-1)" - page_layout: stages - shape: "The fleet's first polarization and magnetic-scattering beamline: diamond phase retarders set the X-ray polarization, with superconducting magnets and low-temperature environments driving resonant magnetic scattering across four stations." - source_ref: - label: "BCDA-APS/polar-bits" - url: "https://github.com/BCDA-APS/polar-bits" - -# Four lead-shielded stations: 4-ID-A holds the polarization and beam-defining -# optics; 4-ID-B, 4-ID-G, and 4-ID-H are the experimental stations (4-ID-G carries -# the diffractometers). PSS permit signals are APS facility signals, not yet on -# file (PSS-1). The Raman station is out of this cut (TOPO-2). -enclosures: - - name: 4-ID-A - role: optics-hutch - facility_code: aps - permit_signal: {confirm: "APS PSS search-and-secure signal TBD (PSS-1)"} - - name: 4-ID-B - role: experiment-hutch - facility_code: aps - permit_signal: {confirm: "APS PSS search-and-secure signal TBD (PSS-1)"} - - name: 4-ID-G - role: experiment-hutch - facility_code: aps - permit_signal: {confirm: "APS PSS search-and-secure signal TBD (PSS-1)"} - - name: 4-ID-H - role: experiment-hutch - facility_code: aps - permit_signal: {confirm: "APS PSS search-and-secure signal TBD (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the 4-ID-A optics spine (source, polarization, monochromator) -# =========================================================================== - -insertion-devices: - stage: source - enclosure: 4-ID-A - intro: "The undulator source: a pair on the S04ID straight section feeding the 4-ID optics." - note: "Modelled as one InsertionDevice Asset for the pair (PolarUndulatorPair); the period and gap detail is SRC-1, and whether to split it into two Assets is SRC-2." - devices: - - name: Undulators - family: InsertionDevice - pv: "S04ID:" - new: true - confirm: true - note: "undulator pair (PolarUndulatorPair); energy-tracking source (SRC-1)" - -polarization-optics: - stage: source - enclosure: 4-ID-A - intro: "The phase retarders that set the X-ray polarization state: 4-ID's defining capability. Three diamond phase-retarder stages, energy-tracking, on the 4idam motor crate." - note: > - pr1, pr2, pr3 are PRDevice / PRDeviceBase stages (each th/x/y). They bind the - catalog PhaseRetarder Family (graduated on the rule-of-three across 4-ID, P09, - and P22). - devices: - - name: PhaseRetarder_1 - family: PhaseRetarder - pv: { th: "4idam4", x: "4idam1", y: "4idam2" } - new: true - confirm: true - note: "diamond phase retarder, energy-tracking (PRDevice); polarization control" - - name: PhaseRetarder_2 - family: PhaseRetarder - pv: { th: "4idam9", x: "4idam6", y: "4idam7" } - new: true - confirm: true - note: "second phase retarder (PRDevice); polarization control" - - name: PhaseRetarder_3 - family: PhaseRetarder - pv: { th: "4idam12", x: "4idam10", y: "4idam11" } - new: true - confirm: true - note: "third phase retarder (PRDeviceBase); polarization control" - -monochromator: - stage: source - enclosure: 4-ID-A - intro: "The vertical double-crystal monochromator (4idVDCM) and its white-beam and mono slits." - note: "mono is the VDCM with a crystal-select axis; mono_feedback is a beam-stabilization loop folded into the Monochromator note (MONO-1)." - devices: - - name: Monochromator - family: Monochromator - pv: { th: "4idVDCM:m1", crystal_select: "4idVDCM:m2", y2: "4idVDCM:m3", thf2: "4idVDCM:m4", chi2: "4idVDCM:m5" } - new: true - confirm: true - note: "vertical DCM with crystal-select; energy range and saved positions unconfirmed (MONO-1)" - - name: WhiteBeamSlit - family: Slit - pv: { hor: "4idVDCM:m9", diag: "4idVDCM:m10", pitch: "4idVDCM:m11", yaw: "4idVDCM:m12" } - new: true - confirm: true - note: "white-beam slit upstream of the mono (4idVDCM crate)" - - name: MonoSlit - family: Slit - pv: { top: "4idVDCM:m14", bot: "4idVDCM:m13", inb: "4idVDCM:m15", out: "4idVDCM:m16" } - new: true - confirm: true - note: "post-mono slit (4idVDCM crate)" - -front-end-optics: - stage: source - enclosure: 4-ID-B - intro: "The diamond window, toroidal pre-focusing mirror, and HHL (high-heat-load) mirror that condition the beam into the experimental stations." - note: "hhl_mirror is a multi-axis HHL mirror (bend, pitch, ellipticity); t_mirror is a toroidal mirror. Window/Mirror are catalog Families." - devices: - - name: DiamondWindow - family: Window - pv: { x: "4idbSoft:m1", y: "4idbSoft:m2" } - new: true - confirm: true - note: "diamond window on a 2-axis stage" - - name: ToroidalMirror - family: Mirror - pv: "4idbToro:" - new: true - confirm: true - note: "toroidal pre-focusing mirror (OPT-1)" - - name: HHLMirror - family: Mirror - pv: { y: "4idHHLM:m1", x: "4idHHLM:pm1", pitch: "4idHHLM:pm2", curvature: "4idHHLM:pm3", ellipticity: "4idHHLM:pm4", us_bend: "4idHHLM:m4", ds_bend: "4idHHLM:m5" } - new: true - confirm: true - note: "high-heat-load bendable mirror; piezo fine axes plus benders (OPT-1)" - -beam-conditioning: - stage: source - enclosure: 4-ID-G - intro: "The compound refractive lens transfocator and the per-station filters and KB mirrors shared across the experimental branches." - note: > - crl is a CRL transfocator: it reuses the graduated catalog Transfocator - Family, a CRL focusing optic; its lens spec is OPT-2. The KB - mirrors (bkb/gkb/hkb) are per-station Kirkpatrick-Baez focusing pairs bound to - the Mirror Family; their internal axis maps are OPT-3. - devices: - - name: Transfocator - family: Transfocator # catalog Family; lens spec OPT-2 - pv: "4idPyCRL:CRL4ID:" - new: true - confirm: true - note: "compound refractive lens transfocator, energy-tracking; serves 4-ID-G and 4-ID-H (OPT-2)" - - name: KBMirror_B - family: Mirror - pv: { rot: "4idbSoft:m15", x: "4idbSoft:m16" } - new: true - confirm: true - enclosure: 4-ID-B - note: "4-ID-B KB focusing mirror (bkb); full axis map is OPT-3" - - name: KBMirror_G - family: Mirror - pv: "4idgKB:" - new: true - confirm: true - note: "4-ID-G KB focusing mirror (gkb, GKBDevice); axis map is OPT-3" - - name: KBMirror_H - family: Mirror - pv: "4idhKB:" - new: true - confirm: true - enclosure: 4-ID-H - note: "4-ID-H KB focusing mirror (hkb, HKBDevice); axis map is OPT-3" - -filters: - stage: source - enclosure: 4-ID-B - intro: "The per-station attenuator filter banks." - note: "APSFilter / AVSfilters banks; bound to the Filter catalog Family." - devices: - - name: Filter_B - family: Filter - pv: "4idbSoft:filter:" - new: true - confirm: true - note: "4-ID-B filter bank" - - name: Filter_G - family: Filter - pv: "4idPyFilter:FL1:" - new: true - confirm: true - enclosure: 4-ID-G - note: "4-ID-G filter bank" - - name: Filter_H - family: Filter - pv: "4idPyFilter:FL2:" - new: true - confirm: true - enclosure: 4-ID-H - note: "4-ID-H filter bank" - -# =========================================================================== -# SAMPLE STAGE: the diffractometers and sample environments per station -# =========================================================================== - -diffractometers: - stage: sample - enclosure: 4-ID-G - intro: "The 4-ID-G diffractometers: a Huber Eulerian cradle and a high-pressure diffractometer. These are 4-ID's diffraction core." - note: > - huber_euler and huber_hp are modelled as plain multi-axis devices with their - circle axis maps. The reusable Assembly(Diffractometer) (omega/chi/phi - RotaryStage circles plus a reciprocal-space PseudoAxis, the Microscope-assembly - pattern) is in the catalog as an Assembly composing the Goniometer Family, with - an 8-ID Fixture scenario; the 4-ID Fixture is the follow-on (DIFF-1). Meanwhile - these devices bind the Goniometer Family directly. - devices: - - name: Diffractometer_Euler - family: Goniometer # catalog Family; the sample-orientation goniometer of the Diffractometer Assembly (DIFF-1) - pv: { chi: "4idgSoft:m37", phi: "4idgSoft:m38", x: "4idgSoft:m40", y: "4idgSoft:m41", z: "4idgSoft:m42" } - new: true - confirm: true - note: "Huber Eulerian-cradle diffractometer (CradleDiffractometer); chi and phi circles added from the 6idb-bits snapshot, the full circle set is DIFF-1" - - name: Diffractometer_HighPressure - family: Goniometer # catalog Family; the sample-orientation goniometer of the Diffractometer Assembly (DIFF-1) - pv: { chi: "4idgSoft:m5", phi: "4idgSoft:m6", sample_tilt: "4idgSoft:m11", x: "4idgSoft:m12", y: "4idgSoft:m14", z: "4idgSoft:m13" } - new: true - confirm: true - note: "high-pressure diffractometer (HPDiffractometer); reciprocal-space axis via hklpy2 (DIFF-1, DIFF-2)" - - name: PolarizationAnalyzer - family: PolarizationAnalyzer - pv: { th: "4idbSoft:m9", y: "4idbSoft:m17" } - new: true - confirm: true - enclosure: 4-ID-B - note: "polarization analyzer crystal stage (PolAnalyzer); analyzes scattered-beam polarization; binds the catalog PolarizationAnalyzer Family" - -sample-environment: - stage: sample - enclosure: 4-ID-B - intro: "The sample-environment apparatus: superconducting magnets, temperature controllers, and the sample positioning tables. 4-ID's magnetic-scattering signature." - note: > - Magnets (bmag/emag 2 T, magnet911, the Kepco-driven gmag) bind the catalog Magnet - Family (graduated; presents Regulator; MAG-1, FAM-1); the LakeShore 336/340 controllers bind the catalog - TemperatureController Family (presents Regulator; TEMP-1). Tables bind the catalog Table - Family. gmag was misinferred as a "4-ID-K" enclosure from the Kepco vendor - prefix; it is placed at 4-ID-G pending confirmation (TOPO-3). - devices: - - name: Magnet_2T_B - family: Magnet # catalog Family (graduated; presents Regulator, MAG-1) - pv: {confirm: "Magnet2T (bmag); control PV not in the extracted config (MAG-1)"} - new: true - confirm: true - note: "2 T sample magnet at 4-ID-B (MAG-1)" - - name: Magnet_2T_E - family: Magnet # catalog Family (graduated; presents Regulator, MAG-1) - pv: { mrot: "4idb:m20", mx: "4idb:m22", my: "4idb:m21", srot: "4idb:m19", sx: "4idb:m18", sy: "4idb:m17" } - new: true - confirm: true - note: "second 2 T sample magnet at 4-ID-B (emag), with magnet rotate/translate and sample rotate/translate axes from the 6idb-bits snapshot; the field-control PV is still pending (MAG-1)" - - name: Magnet_9T_H - family: Magnet # catalog Family (graduated; presents Regulator, MAG-1) - pv: "4idhSoft:" - new: true - confirm: true - enclosure: 4-ID-H - note: "high-field magnet at 4-ID-H (Magnet911); field range unconfirmed (MAG-1)" - - name: Magnet_Kepco_G - family: Magnet # catalog Family (graduated; presents Regulator, MAG-1) - pv: "4idkepco:" - new: true - confirm: "station is a guess: the 4idkepco prefix is a Kepco power-supply vendor name, not a station (TOPO-3, MAG-1)" - enclosure: 4-ID-G - note: "Kepco-driven electromagnet (gmag); station and field unconfirmed (TOPO-3, MAG-1)" - - name: TemperatureController_336 - family: TemperatureController # catalog Family (graduated #350; presents Regulator) - pv: "4idgSoft:LS336:TC1:" - new: true - confirm: true - enclosure: 4-ID-G - note: "LakeShore 336 sample temperature controller (TEMP-1)" - - name: TemperatureController_340 - family: TemperatureController # catalog Family (graduated #350; presents Regulator) - pv: "4idgSoftX:LS340:TC1:" - new: true - confirm: true - enclosure: 4-ID-G - note: "LakeShore 340 sample temperature controller (TEMP-1)" - - name: SampleTable_B - family: Table - pv: { x_us: "4idbSoft:m5", x_ds: "4idbSoft:m8", y_us: "4idbSoft:m4", y_ds_in: "4idbSoft:m7", y_ds_out: "4idbSoft:m6" } - new: true - confirm: true - note: "4-ID-B sample positioning table (Table4idb)" - - name: SampleTable_H - family: Table - pv: { x_us: "4idhSoft:m1", x_ds: "4idhSoft:m2", y_us: "4idhSoft:m3", y_ds: "4idhSoft:m4" } - new: true - confirm: true - enclosure: 4-ID-H - note: "4-ID-H sample positioning table (Table4idh)" - - name: PumpProbeLaser - family: Laser # catalog Family (SAMPLE-1) - pv: "4idhSoft:LQE1:" - new: true - confirm: true - enclosure: 4-ID-H - note: "Ventus laser for pump-probe at 4-ID-H; whether CORA models or only hazards it is SAMPLE-1" - -station-slits: - stage: sample - enclosure: 4-ID-B - intro: "The per-station sample-defining slits." - note: "Standard four-blade slits on each station's soft IOC; Slit catalog Family." - devices: - - name: SampleSlit_B - family: Slit - pv: { top: "4idbSoft:m11", bot: "4idbSoft:m10", inb: "4idbSoft:m12", out: "4idbSoft:m13" } - new: true - confirm: true - note: "4-ID-B sample slit" - - name: SampleSlit_G - family: Slit - pv: { top: "4idgSoft:m44", bot: "4idgSoft:m43", inb: "4idgSoft:m45", out: "4idgSoft:m46" } - new: true - confirm: true - enclosure: 4-ID-G - note: "4-ID-G sample slit" - - name: SampleSlit_H - family: Slit - pv: { top: "4idhSoft:m11", bot: "4idhSoft:m10", inb: "4idhSoft:m13", out: "4idhSoft:m12" } - new: true - confirm: true - enclosure: 4-ID-H - note: "4-ID-H sample slit" - -# =========================================================================== -# DETECTION STAGE: area detectors, beam-position monitors, counters -# =========================================================================== - -area-detectors: - stage: detection - enclosure: 4-ID-G - intro: "The area and point detectors: an Eiger 1M, flag-view cameras, and a Vortex fluorescence detector." - note: "Eiger binds the Camera Family (area detector); the Vimba flag cameras are alignment views. sgz_vortex was misinferred as a 4-ID-D enclosure (4iddMZ0 prefix); placed at 4-ID-G pending confirmation (TOPO-3, DET-2)." - devices: - - name: Eiger1M - family: Camera - pv: "4idEiger:" - new: true - confirm: true - note: "Eiger 1M area detector (DET-1)" - - name: FlagCamera_HHL - family: Camera - pv: "4idaPostMirrBeam:" - new: true - confirm: true - enclosure: 4-ID-A - note: "post-mirror beam-view flag camera (Vimba)" - - name: FlagCamera_Mono - family: Camera - pv: "4idaPostMonoBeam:" - new: true - confirm: true - enclosure: 4-ID-A - note: "post-mono beam-view flag camera (Vimba)" - - name: VortexFluorescence - family: PositionMonitor # catalog Family (graduated); placeholder classification for a fluorescence point detector pending reclassification (DET-2; not the EnergyDispersiveSpectrometer) - pv: "4iddMZ0:" - new: true - confirm: "station is a guess: the 4iddMZ0 prefix was misread as a 4-ID-D enclosure (TOPO-3, DET-2)" - note: "SGZ Vortex fluorescence detector; classification and station unconfirmed (DET-2, TOPO-3)" - -beam-position-monitors: - stage: detection - enclosure: 4-ID-G - intro: "The beam-position and intensity monitors (XBPMs, Sydor electrometers, TetrAMM, I0 chambers) that diagnose beam position and normalize intensity." - note: > - These bind the graduated PositionMonitor Family (presenting the Sensor Role), - a consumer alongside the wide fleet that earned it; the per-Asset beam-center - calibration and channel map stay pending (BPM-1, FAM-1). - devices: - - name: XBPM_G - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1, BPM-1) - pv: { x: "4idgSoft:m48", y: "4idgSoft:m47" } - new: true - confirm: true - note: "4-ID-G X-ray beam-position monitor" - - name: XBPM_H - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1, BPM-1) - pv: { x: "4idhSoft:m6", y: "4idhSoft:m5" } - new: true - confirm: true - enclosure: 4-ID-H - note: "4-ID-H X-ray beam-position monitor" - - name: Sydor_G - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1, BPM-1) - pv: "4idgSydor:T4U_BPM:" - new: true - confirm: true - note: "4-ID-G Sydor electrometer beam-position monitor" - - name: Sydor_H - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1, BPM-1) - pv: "4idhSydor:T4U_BPM:" - new: true - confirm: true - enclosure: 4-ID-H - note: "4-ID-H Sydor electrometer beam-position monitor" - - name: TetrAMM_B - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1, BPM-1) - pv: "4idbSoft:TetrAMM:" - new: true - confirm: true - enclosure: 4-ID-B - note: "4-ID-B TetrAMM picoammeter / position monitor" - -counters: - stage: detection - enclosure: 4-ID-B - intro: "The scaler / counter channels shared across the stations." - note: "CTR8-based scalers; bound to the GenericProbe Family (the APS facility-scope counter probe)." - devices: - - name: Scaler_1 - family: GenericProbe - pv: "4idCTR8_1:scaler1" - new: true - confirm: true - note: "CTR8 scaler channel set 1 (shared B/G/H)" - - name: Scaler_2 - family: GenericProbe - pv: "4idCTR8_1:scaler2" - new: true - confirm: true - note: "CTR8 scaler channel set 2 (shared B/G/H)" - -# Cross-cutting control. 4-ID runs EPICS (the floor); CORA observes and, where it -# replaces Bluesky-style scan and alignment orchestration, conducts over it. The -# PV handles above were read from the beamline's polar-bits instrument config and -# are carried confirm pending staff verification (CTRL-1). -controls: - intro: > - 4-ID runs on the APS EPICS control stack, like 2-BM. Unlike the design- - phase scaffolds, the device control handles above are bound from the beamline's - own Bluesky instrument repo (BCDA-APS/polar-bits) rather than left empty, but - they remain confirm-pending: a value read from the operator's config is evidence - to verify with staff, not a CORA-owned fact (CTRL-1). The preamplifiers - (LocalPreAmp, a loose Preamplifier Family, PREAMP-1), the lock-in (srs810), the - LabJacks, and the high-pressure-cell controllers (Pace PC1/PC2) are present in - the config but not modelled as Assets in this cut (SAMPLE-2). - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a 4-ID run needs. Carried pending - in this first cut; the cryogen and process-gas supplies for the magnet and - high-pressure environments are unconfirmed (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: LiquidHelium - note: "for the superconducting magnets and low-temperature sample environment (SUP-1)" - - kind: LiquidNitrogen - note: "sample cooling (SUP-1)" diff --git a/deployments/7-bm/beamline.yaml b/deployments/7-bm/beamline.yaml deleted file mode 100644 index 7812293214a..00000000000 --- a/deployments/7-bm/beamline.yaml +++ /dev/null @@ -1,302 +0,0 @@ -# CORA Beamline descriptor: 7-BM (APS), design phase -# -# 7-BM is a multi-technique flow and combustion imaging beamline at the APS -# (Argonne). It is bound to the APS Site (deployments/aps/site.yaml), the same -# Site the operational 2-BM pilot runs at; 7-BM is a separate beamline in its -# own sector, not a part of 2-BM. -# -# STATUS: design phase. 7-BM is being recommissioned for APS-U and its operations -# documentation is partial (the source xray-imaging/7bm-docs has empty technique -# stubs and "to be completed once APS-U operation starts" sections). So this file -# is a SHAPE, not a commissioned record: every device carries `new: true` (not yet -# modelled in CORA) and `confirm: true` (a value taken from the 7-BM docs or -# inferred, to be verified by 7-BM staff). No `model` is bound (vendors are named -# in the docs but not procured into CORA's catalog), and no `pv` handle is invented. -# -# What makes 7-BM a different shape from 2-BM, the questions it raises, and what -# CORA reuses unchanged are written up in docs/deployments/7-bm/. Items deferred to -# staff are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/7-bm/questions.md. -# -# Two things this scaffold does NOT do, on purpose: -# - 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 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: - maturity: design - evidence: narrative - coverage: full - summary: "multi-technique flow and combustion imaging, recommissioned for APS-U" - name: "7-BM" - facility: aps # APS, a Site-level Facility (facility_code: aps) - sector: "Sector 7" # organizational label, not a registered asset today - tier: Unit - parent: null - source: bending-magnet - source_confirm: "historically a bending-magnet source; the post-APS-U source for 7-BM is not stated in the docs (SRC-1)" - page_layout: stages - shape: "A multi-technique flow and combustion imaging beamline: high-speed imaging, energy-dispersive diffraction, radiography, and tomography over partly-shared apparatus, with a metered process-gas sample environment 2-BM has nothing like." - -enclosures: - # Two access-gated hutches. 7-BM-A holds the conditioning optics; 7-BM-B is the - # experiment hutch (flow, combustion, the endstations and detectors). The PSS - # permit signals are APS facility signals, not named in the 7-BM docs (PSS-1). - - name: 7-BM-A - role: optics-hutch - facility_code: aps - permit_signal: {confirm: "APS PSS search-and-secure permit signal for 7-BM-A, to be named (PSS-1)"} - - name: 7-BM-B - role: experiment-hutch - facility_code: aps - permit_signal: {confirm: "APS PSS search-and-secure permit signal for 7-BM-B, to be named (PSS-1)"} - -# =========================================================================== -# The beam path: source -> sample -> detection -# =========================================================================== - -front-end: - stage: source - enclosure: 7-BM-A - intro: "The source and the first station shutter that admits beam to the optics hutch." - note: > - 7-BM runs white, monochromatic, and focused beam in different modes; the beam - mode is a per-technique choice, not a fixed property of the source (BEAM-1). - The source itself is carried loosely as the bending-magnet beam, mirroring the - 2-BM source representation, never a catalog Family. - devices: - - name: Source - family: Beam - new: true - confirm: true - note: "the storage-ring source feeding 7-BM; bending-magnet historically, post-APS-U source to confirm (SRC-1)" - - name: StationShutterA - family: Shutter - new: true - confirm: true - note: "7-BM-A station shutter; closed before the filters are moved (optics.rst)" - -beam-conditioning: - stage: source - enclosure: 7-BM-A - intro: "The filters, chopper, and white-beam slits that shape the white beam and manage its heat load before the optics." - note: > - White-beam heat load is a 7-BM-specific concern absent at the monochromatic - 2-BM pilot: prolonged white beam cracks scintillators and damages samples, so - filtering and the rotary chopper duty-cycle reduction are routine mitigations. - devices: - - name: Filters - family: Filter - new: true - confirm: true - note: "water-cooled filter set in 7-BM-A; two filter units, up to two filters at once (optics.rst)" - - name: Chopper - family: Chopper - new: true - confirm: true - note: > - rotary chopper: two notched copper disks on a stepper (Motor 27), two - notches per disk so the beam transmits twice per rotation; relative disk - rotation sets the duty cycle; a 12 VDC photoeye picks off position and feeds - DG645 #2. Reduces white-beam duty cycle to protect samples and scintillators. - Bound to a loose Chopper family pending the decision on whether this is a new - catalog Family or an existing Shutter / RotaryStage plus settings (CHOP-1). - - name: WhiteBeamSlit - family: Slit - new: true - confirm: true - note: "white-beam slits; horizontal centre and size are repositioned per monochromator stripe (optics.rst)" - -optics: - stage: source - enclosure: 7-BM-A - intro: "The energy-selecting and focusing optics that condition the beam delivered to the experiment hutch." - note: > - Which of these optics sit in the routine pilot path, and the dual-energy - split-stripe mode of the monochromator, are open (OPT-1). The polycapillary - optics (for confocal fluorescence) and the channel-cut calibration crystals - named in the docs are deferred until a confirmed technique needs them, and are - not modelled here. - devices: - - name: Monochromator - family: Monochromator - new: true - confirm: true - note: "double multilayer monochromator (DMM), 6 to 18 keV; two Rigaku-coated Si substrates with three stripes (2.0 nm, 3.5 nm, split mixed) (optics.rst)" - - name: MultilayerMirror - family: Mirror - new: true - confirm: true - note: "7-BM-B single-bounce multilayer mirror; 2.1 nm and 4.0 nm coatings on a 200 mm Si substrate; white-beam mode, requires hutch DI cooling water (optics.rst)" - - name: FocusingMirrors - family: Mirror - new: true - confirm: true - note: "Kirkpatrick-Baez focusing mirror pair (IDT, Si, Rh-coated, dynamically bendable); monochromatic focused-beam mode, requires a helium purge (optics.rst)" - -safety-shutters: - stage: source - enclosure: 7-BM-A - intro: "The safety shutter gating the beam between the optics hutch and the experiment hutch." - note: "PSS permit signals are APS facility signals, not named in the docs (PSS-1)." - devices: - - name: SafetyShutter - family: Shutter - new: true - confirm: true - note: "safety shutter gating beam from 7-BM-A into the 7-BM-B experiment hutch" - -sample-environment: - stage: sample - enclosure: 7-BM-B - intro: "The sample stage in the experiment hutch: tomography rotation and sample positioning, the energy-dispersive gauge slits, and the flow / combustion sample environment that distinguishes 7-BM." - note: > - 7-BM hosts several techniques over partly-shared, partly-distinct sample-side - apparatus (TECH-1). The flow and combustion sample environment (compressed-air - plant, vacuum, process gases) is a 7-BM-specific axis the 2-BM pilot has nothing - like; the continuously-available services are carried as Supplies in `resources` - below, and the settable flow control as a device here. The combustion / spray - rig itself is not modelled until staff confirm an installed device (ENV-1). - devices: - - name: TomographyRotation - family: RotaryStage - new: true - confirm: true - note: "sample rotation for tomography; tomoScan-driven, the same scanning engine 2-BM uses" - - name: SamplePositioning - family: LinearStage - new: true - confirm: true - note: "sample centring and translation stage" - - name: EDDSlit - family: Slit - new: true - 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 # 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. 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. - CORA COMMANDS the setpoint (a one-shot SetpointStep), not read-back-only (FLOW-1, - command-vs-read: settled to command). What it cannot yet express is a continuous - setpoint PROGRAM (a hold or ramp held during a Run, orthogonal to the scan - step-list); the regulation loop is device/IOC-owned and CORA programs and observes - it, not hosts it. That is the continuous-regulation runtime gap, deferred to the - axis research (see model.md). - -# =========================================================================== -# Detection: the multiple detector modalities 7-BM runs -# =========================================================================== - -detector: - stage: detection - enclosure: 7-BM-B - intro: "7-BM runs several detector modalities, not the single 2D camera path of the 2-BM micro-CT pilot: an indirect-imaging camera for tomography, a high-speed movie camera, a point photodiode for time-resolved radiography, and an energy-dispersive detector for diffraction." - note: > - The tomography path (scintillator plus visible optics plus area camera) reuses the - 2-BM detector shape and could later compose the cross-facility Microscope Assembly; - it is left as plain devices in this scaffold. The point photodiode and the - energy-dispersive detector both present the Sensor Role (a scalar or short-vector - Reading, not a 2D frame); they are bound to loose family names pending the decision - on whether each is a new catalog Family or a deployment-local Sensor device. - devices: - - name: Scintillator - family: Scintillator - new: true - confirm: true - note: "scintillator crystal for indirect x-ray imaging; subject to thermal cracking under white beam (high_speed_imaging.rst)" - - name: TomographyCamera - family: Camera - new: true - confirm: true - note: "area camera coupled to the scintillator through visible optics for tomography and radiographic imaging" - - name: HighSpeedCamera - family: Camera - new: true - confirm: true - note: > - high-speed movie camera (Photron Nova S16 in the docs); captures short movie - bursts, one per chopper opening, hardware-gated by the DG645 timing chain and - optionally synced to the storage ring at 271 kHz. The acquisition unit (one - burst as one Run / Dataset) and top-up blanking are open (HSI-1). - - name: Photodiode - family: Photodiode - new: true - confirm: true - note: > - PIN photodiode for time-resolved radiography (focused beam, ~8 keV); presents the - Sensor Role (a scalar intensity Reading), read out through a high-speed digitizer - (ADQ14) or oscilloscope plus the DataGrabber program, not as a camera frame. The - detector Family question and the data unit (one trace as one Dataset) are open (RAD-1). - - name: EnergyDispersiveSpectrometer - family: EnergyDispersiveSpectrometer - new: true - confirm: true - note: > - germanium energy-dispersive detector for energy-dispersive diffraction; records a - per-photon energy spectrum (an MCA histogram), not a 2D frame, and presents the - Sensor Role. Binds the catalog EnergyDispersiveSpectrometer Family (graduated once - 2-ID and 7-BM shared it). Whether this is the same physical detector as the - fluorescence MCA is open (DET-1). - -# Cross-cutting timing and triggering. 7-BM's floor carries several technique-specific -# orchestrators (tomoScan, DataGrabber, the ADQ14 Python scripts, the EPICS scan -# record, the high-speed-imaging string sequence); these are control-system software, -# listed here for the record, not modelled as CORA Assets. -controls: - intro: > - Timing and synchronization run on two Stanford DG645 delay generators plus a - softGlue FPGA, referenced to the storage-ring P0 signal from the Machine Status - Link, with a top-up inhibit that vetoes acquisition during ring top-up. EPICS PV - handles are not invented here (CTRL-1). - triggering: - - name: Timing - family: TimingController - new: true - confirm: true - note: > - two Stanford DG645 delay generators (one ring-synced at 271 kHz, one delaying the - chopper-to-camera trigger) plus a softGlue FPGA and the Machine Status Link P0 - reference; a top-up inhibit signal vetoes data during ring top-up. Modelled as one - TimingController carrying the scheme, mirroring the 2-BM Timing device (TIMING-1). - software_iocs_not_modeled: - - "tomoScan: the tomography scanning engine (single / vertical / horizontal / mosaic), shared with 2-BM" - - "DataGrabber: Java oscilloscope driver for time-resolved radiography, handshaking over the EPICS busy record 7bmb1:rad:get_data" - - "ADQ14 acquisition: custom Python (scan_script2.py) bridging the EPICS scan record to the digitizer soft IOC" - - "EPICS scan record: the step-scanning framework (linear / table / relative, daisy-chained for multidimensional scans)" - - "high-speed-imaging string sequence: sequences the chopper-gated movie-burst acquisition" - - "RecordSaver: EPICS record save and restore by PV prefix" - - "DMagic / APS Data Management: data movement and the scheduling-system bridge" - -# Continuously-available facility resources a run draws on. The flow and combustion -# utilities (compressed air, vacuum, process gas) are the 7-BM-specific additions over -# the 2-BM supply set; all carried pending confirmation in the design phase. -resources: - intro: > - The continuously-available facility resources a 7-BM run needs present before it can - start. The compressed-air plant, the vacuum system, and the process gases serve the - flow and combustion experiments and have no 2-BM analogue. - supplies: - - kind: PhotonBeam - - kind: CompressedAir - note: "high-volume compressed-air plant (Kaeser BS61 compressor, accumulator tanks, electronic regulator) for flow and combustion (flow_infrastructure.rst)" - - kind: Vacuum - note: "high-volume vacuum system, two rotary-claw pumps (flow_infrastructure.rst)" - - kind: ProcessGas - note: "He / N2 / Ar / Kr cylinders, with a ventilated flammable-gas cabinet (safety, operations)" - - kind: CoolingWater - note: "hutch DI cooling water for the multilayer mirror and filters" diff --git a/deployments/8-3-2/beamline.yaml b/deployments/8-3-2/beamline.yaml deleted file mode 100644 index d604b1aad8a..00000000000 --- a/deployments/8-3-2/beamline.yaml +++ /dev/null @@ -1,239 +0,0 @@ -# CORA Beamline descriptor: ALS 8.3.2 (hard X-ray micro-tomography), reverse-engineered -# -# 8.3.2 is the Advanced Light Source hard X-ray micro-tomography (micro-CT) -# beamline at Lawrence Berkeley National Laboratory: a Superbend source, -# 6,000-43,000 eV, ~1 micron resolution, non-destructive 3D imaging. It is bound -# to the ALS Site (deployments/als/site.yaml), CORA's FIRST ALS Site and its -# FIRST BCS (Beamline Control System, a LabVIEW house-style) control plane. -# -# STATUS: reverse-engineered, design-phase first cut. This is a NEW descriptor -# posture, the "data-record" mode, distinct from the two prior modes: -# - 2-BM is operational and fully measured (real handles, vendor models). -# - FXI reads real EPICS PVs from a public bluesky profile collection. -# - FAXTOR has NO public device manifest at all (handles fully omitted). -# 8.3.2 sits between them: the device STRUCTURE (the named device hierarchy and -# its axes) is verified from the DXchange / DXfile HDF5 data-record schema that -# the als-computing tooling reads (the SciCat ingester -# scicat_beamline/src/scicat_beamline/ingesters/als_832_dx_4.py and the -# reconstruction backend microct/backend/ALS_recon_functions.py), but the LIVE -# control handles are NOT public. ALS runs BCS, a LabVIEW Beamline Control -# System (als-computing/als.bcs, als-computing/bcs-api), NOT EPICS, so there are -# no PVs to read; the BCS channel handles live with ALS staff. Each device -# therefore cites its HDF5 metadata path as the existence evidence for its -# structure, and carries the live control handle as confirm-pending (CTRL-1). No -# `pv` field is invented and no vendor `model` is bound (detector model and specs -# are per-dataset values in the data record, not a fixed manifest). -# -# WHAT IS NEW: a new Site and a new control house-style, no new vocabulary. -# - A wholly NEW Site (ALS, the first) re-tests the Site / Federation kernel. -# - The FIRST BCS / LabVIEW controls house-style in the fleet (every prior Site -# is EPICS, Tango / Sardana, or BLISS). -# - 8.3.2 coins NO new Family and changes nothing in the catalog: it is a -# tomography beamline reusing the imaging Families and Methods the fleet -# already carries (the 2-BM / FXI / FAXTOR precedent). -# -# ALS-U: the ALS-U upgrade dark time starts no sooner than October 2027 (>= 2 -# years). Whether 8.3.2 goes dark, is rebuilt, or relocates is a staff question -# (ALSU-1). -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/8-3-2/questions.md. - -beamline: - maturity: model - evidence: narrative - coverage: full - summary: "hard X-ray micro-tomography (micro-CT) on a Superbend source, 6-43 keV, ~1 micron; reuses the 2-BM / FXI / FAXTOR tomography Families and Methods, novelty is the Site and its BCS / LabVIEW control plane" - name: "8.3.2" - facility: als # ALS Site (facility_code: als) - sector: "8.3.2" # ALS beamline number; not a registered Asset - tier: Unit - parent: null - source: bending-magnet - source_confirm: "8.3.2 is fed by a Superbend (superconducting bending magnet); the field and critical energy are not in the public data record, carried pending (SRC-1)" - page_layout: stages - shape: "CORA's first ALS beamline: hard X-ray micro-tomography from a Superbend source, its first BCS (LabVIEW) control house-style, reusing the tomography spine with control handles unbound." - source_ref: - label: "als-computing" - url: "https://github.com/als-computing" - -# Access-gated volume. 8.3.2 is modelled as a single experiment hutch pending -# staff confirmation of the optics / experiment grouping (ENC-1). The ALS PSS -# permit signals are not published, carried pending (PSS-1). -enclosures: - - name: 8-3-2-hutch - role: experiment-hutch - facility_code: als - permit_signal: {confirm: "ALS PSS permit signal not published per beamline (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the machine state, the Superbend, and the conditioning optics -# =========================================================================== - -machine: - stage: source - enclosure: 8-3-2-hutch - intro: "The machine-level source state, observed not driven." - note: "The ALS storage-ring state, the loose StorageRing pattern reused across the fleet. The data record carries /measurement/instrument/source/source_name and /measurement/instrument/source/current (MACHINE-1)." - devices: - - name: StorageRing - family: StorageRing # loose Family (machine-level observe-only source state; MACHINE-1) - new: true - confirm: true - note: "ALS storage-ring state (source_name, ring current); observe-only. Structure from /measurement/instrument/source/{source_name,current,beam_intensity_incident}; live handle pending (MACHINE-1, CTRL-1)" - -source-magnet: - stage: source - enclosure: 8-3-2-hutch - intro: "The Superbend, the superconducting bending-magnet source delivering the hard X-ray beam (6,000-43,000 eV)." - note: "The Superbend is recorded as a Supply (PhotonBeam) at the Site, identity-only here, the 2-BM bending-magnet precedent. Field and critical energy pending (SRC-1)." - devices: - - name: Superbend - family: InsertionDevice - new: true - confirm: true - device_type: superconducting-bending-magnet (Superbend) - note: "the Superbend source feeding 8.3.2 (6-43 keV); recorded as a Supply (PhotonBeam) at the Site, identity-only here. Field, critical energy, and live handle pending (SRC-1, CTRL-1)" - -optics: - stage: source - enclosure: 8-3-2-hutch - intro: "The conditioning optics: a monochromator setting the incident energy, the beam-defining slits, and the attenuating filter. 8.3.2 operates 6,000-43,000 eV." - note: "The monochromator binds Monochromator; the slits bind Slit; the attenuator binds Filter. Structure is read from the DXfile data record; multilayer / crystal detail and live handles pending (MONO-1, OPT-2, FILT-1, CTRL-1)." - devices: - - name: Monochromator - family: Monochromator - new: true - confirm: true - energy_range: 6,000 to 43,000 eV - note: > - the energy-setting monochromator; the data record exposes - /measurement/instrument/monochromator/energy as the master energy and the - setup channels Z2, turret1, turret2 (the multilayer / mirror turrets) plus - crystal-temperature monitors temperature_tc2 / temperature_tc3. The - mechanism (multilayer vs crystal), d-spacing, and live handles are pending - (MONO-1, CTRL-1) - - name: BeamSlit - family: Slit - new: true - confirm: true - note: > - the beam-defining slits; the data record exposes a horizontal slit - (hslits_A_Door, hslits_A_Wall, hslits_center, hslits_size) and a vertical - slit (vslits_Lead_Flag). The full blade-axis map and live handles are - pending (OPT-2, CTRL-1) - - name: BeamFilter - family: Filter - new: true - confirm: true - note: > - the attenuating filter; the data record exposes - /measurement/instrument/attenuator/setup/filter_y (the filter-position - axis). Filter materials and thicknesses are pending (FILT-1, CTRL-1) - -# =========================================================================== -# SAMPLE STAGE: the tomography sample-motor stack -# =========================================================================== - -sample-stack: - stage: sample - enclosure: 8-3-2-hutch - intro: "The tomography sample-motor stack: the rotation stage that sweeps the sample through the beam and the linear stages that centre it." - note: "Reuses the imaging Families the fleet already carries (RotaryStage, LinearStage). The data record exposes a sample_motor_stack with axis1pos, axis2pos, axis5pos, sample_x, sample_y; which axis is the tomographic rotation is pending (SAMPLE-1, ROT-1)." - devices: - - name: SampleRotary - family: RotaryStage - new: true - confirm: true - trigger_source: confirm - note: > - the tomographic rotation stage, the fly-scan trigger master for - continuous-rotation micro-CT. The data record's sample_motor_stack carries - axis1pos / axis2pos / axis5pos; which axis is the rotation, and the - triggering / synchronization scheme, are pending (SAMPLE-1, ROT-1, TRIG-1). - Live handle pending (CTRL-1) - - name: SamplePositioning - family: LinearStage - new: true - confirm: true - note: > - the sample centring / centre-of-rotation translation; the data record - exposes sample_x and sample_y. The full axis set, travel, and live handles - are pending (SAMPLE-1, CTRL-1) - -# =========================================================================== -# DETECTION STAGE: the indirect detector and its motorized stack -# =========================================================================== - -detector: - stage: detection - enclosure: 8-3-2-hutch - intro: "The indirect imaging detector: a scintillator converting X-rays to visible light, a microscope objective relaying the image, and a camera, all carried on a motorized stack that sets the sample-to-detector distance." - note: "The scintillator binds Scintillator, the objective binds Objective, the camera binds Camera, and the detector motion binds LinearStage / TiltStage. Detector specs (model, pixel size, binning, exposure) are per-dataset values in the data record, so no fixed vendor model is bound (DET-1)." - devices: - - name: Scintillator - family: Scintillator - new: true - confirm: true - note: "the X-ray-to-visible scintillator; the data record exposes /measurement/instrument/detection_system/scintillator/scintillator_type. Material and thickness pending (DET-1)" - - name: CameraObjective - family: Objective - new: true - confirm: true - note: "the microscope objective relaying the scintillator image to the camera; the data record exposes /measurement/instrument/detection_system/objective/camera_objective (the selected magnification). The objective set is pending (DET-1)" - - name: Camera - family: Camera - new: true - confirm: true - note: > - the imaging camera; the data record exposes the detector parameters - model, pixel_size, binning_x, binning_y, exposure_time, temperature, - dimension_x, dimension_y, dark_field_value, delay_time. These are - per-dataset acquisition values, not a fixed manifest, so no vendor model is - bound; the installed camera roster and live handle are pending (DET-1, CTRL-1) - - name: DetectorStack - family: LinearStage - new: true - confirm: true - note: > - the motorized detector stack setting the sample-to-detector propagation - distance; the data record exposes a camera_motor_stack with camera_distance, - camera_elevation, and tilt_motor. The camera_distance is the propagation - distance used in phase-contrast reconstruction. Axis models and live - handles pending (DET-2, CTRL-1) - -# Cross-cutting control. 8.3.2 runs ALS BCS (a LabVIEW Beamline Control System); -# CORA observes and, where it replaces BCS scan orchestration, conducts over it. -# No public per-beamline control handles exist (BCS is LabVIEW, not EPICS), so -# none are invented (CTRL-1). -controls: - intro: > - 8.3.2 runs on the ALS BCS (Beamline Control System), a LabVIEW control - house-style, CORA's FIRST BCS plane (every prior Site is EPICS, Tango / - Sardana, or BLISS). Device IO is BCS, surfaced as scan files (Time Scan, - Single Motor Scan, Trajectory Scan) whose headers carry the device-state data - record (als-computing/als.bcs). The emerging acquisition layer wraps BCS scans - as bluesky ophyd fly devices through the LabVIEW BCS API - (als-computing/bcs-api). No public per-beamline BCS channel manifest is - published, so the live control handles are not bound here, carried pending - staff verification (CTRL-1); when bound they would be modelled as opaque edge - handles over the ControlPort, the way the MX3 and ID32 heterogeneous-control - precedents do. The continuous-rotation tomography acquisition (the rotary - trajectory, the camera triggering, the flat / dark sequencing) runs as a BCS - Trajectory Scan; that orchestration is the seam CORA's edge replaces, - conducting over BCS rather than replacing it. The downstream data movement and - reconstruction (als-computing/splash_flows: Prefect + Globus to NERSC / ALCF, - SciCat cataloguing, TomoPy / ASTRA / SVMBIR reconstruction in - als-computing/microct) is plumbing CORA observes and subsumes at the debrief - layer, not data it owns (see model.md). - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources an 8.3.2 run needs present before - it can start. All carried pending confirmation (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: Power diff --git a/deployments/8-id/beamline.yaml b/deployments/8-id/beamline.yaml deleted file mode 100644 index b359cfde58e..00000000000 --- a/deployments/8-id/beamline.yaml +++ /dev/null @@ -1,329 +0,0 @@ -# CORA Beamline descriptor: 8-ID (APS), operational-PV first cut -# -# 8-ID is the X-ray Photon Correlation Spectroscopy (XPCS) beamline at APS -# (Argonne), operational across stations 8-ID-A (optics), 8-ID-D (focusing), -# 8-ID-E (a six-circle diffractometer endstation), and 8-ID-I (the XPCS sample and -# coherent-detector endstation). It is bound to the APS Site -# (deployments/aps/site.yaml). It is the second diffraction-capable APS deployment -# after 4-ID, and it independently carries the device classes 4-ID -# introduced (a diffractometer, a transfocator, a temperature controller, and -# beam-position monitors), so it is the deployment that earns those into the -# catalog. -# -# STATUS: first cut, reverse-engineered. Like 4-ID, this binds the real EPICS -# control handles, read from the beamline's own Bluesky instrument repo -# (BCDA-APS/8id-bits). Every value is carried -# `confirm: true` until 8-ID staff verify it, and `new: true` (not yet registered -# in CORA). No vendor `model` is bound. Devices bind to a catalog Family where one -# fits, or to a loose Family string where the device class is new to the catalog. -# -# DELIBERATELY OUT OF THIS CUT (recorded on docs/deployments/8-id/model.md): the -# UR5 robotic sample changer (a sample-changer shape CORA does not have yet); the -# softGlue timing fabric beyond a single TimingController; integration scenarios, -# vendor Models, z-positions. The six-circle diffractometer is modelled as plain -# devices; the Assembly(Diffractometer) is designed in model.md. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/8-id/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "X-ray photon correlation spectroscopy (XPCS) across four stations; the fleet's first coherent XPCS beamline, earns the xpcs Method" - name: 8-ID - facility: aps # APS, the Site-level Facility (facility_code: aps) - sector: "Sector 8" # organizational label, not a registered asset - tier: Unit - parent: null - source: insertion-device - source_confirm: "two undulators on the S08ID straight section (downstream DSID, upstream USID); whether canted feeding two branches is SRC-1 / TOPO-1" - page_layout: stages - shape: "The coherent-scattering (XPCS) beamline: fast area detectors gated by an FPGA timing fabric downstream of an evacuated flight path, plus a six-circle diffractometer; the deployment that earned 4-ID's device classes into the catalog." - source_ref: - label: "BCDA-APS/8id-bits" - url: "https://github.com/BCDA-APS/8id-bits" - -# Four lead-shielded stations: 8-ID-A holds the optics; 8-ID-D the focusing -# transfocators; 8-ID-E the six-circle diffractometer endstation; 8-ID-I the XPCS -# sample and coherent-detector endstation. PSS permit signals are APS facility -# signals, not yet on file (PSS-1). -enclosures: - - name: 8-ID-A - role: optics-hutch - facility_code: aps - permit_signal: {confirm: "APS PSS search-and-secure signal TBD (PSS-1)"} - - name: 8-ID-D - role: optics-hutch - facility_code: aps - permit_signal: {confirm: "APS PSS search-and-secure signal TBD (PSS-1)"} - - name: 8-ID-E - role: experiment-hutch - facility_code: aps - permit_signal: {confirm: "APS PSS search-and-secure signal TBD (PSS-1)"} - - name: 8-ID-I - role: experiment-hutch - facility_code: aps - permit_signal: {confirm: "APS PSS search-and-secure signal TBD (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the 8-ID-A optics spine and the 8-ID-D focusing -# =========================================================================== - -insertion-devices: - stage: source - enclosure: 8-ID-A - intro: "The undulator source: a downstream and an upstream undulator on the S08ID straight section." - note: "Two InsertionDevice Assets; whether the pair is canted feeding two branches is SRC-1 / TOPO-1." - devices: - - name: Undulator_Downstream - family: InsertionDevice - pv: "S08ID:DSID:" - new: true - confirm: true - note: "downstream undulator (SRC-1)" - - name: Undulator_Upstream - family: InsertionDevice - pv: "S08ID:USID:" - new: true - confirm: true - note: "upstream undulator (SRC-1)" - -optics: - stage: source - enclosure: 8-ID-A - intro: "The monochromator, the high-heat-load mirrors, and the white-beam and mono slits." - note: "mono is the MN1 monochromator (energy/theta/wavelength); mr1/mr2 are the FMBO mirrors with coarse and piezo fine pitch and benders. A second in-line monochromator (idt_mono) is MONO-2." - devices: - - name: Monochromator - family: Monochromator - pv: { energy: "8idaSoft:MN1:Energy", theta: "8idaSoft:MN1:Bragg", gap: "8idaSoft:MN1:Gap", offset: "8idaSoft:MN1:Offset", wavelength: "8idaSoft:MN1:Lambda" } - new: true - confirm: true - note: "main monochromator (MONO-1)" - - name: Mirror_1 - family: Mirror - pv: { x: "8idaSoft:FMBO:m4", y: "8idaSoft:FMBO:m2", coarse_pitch: "8idaSoft:FMBO:m6", fine_pitch: "8idaSoft:FMBO:Piezo:m1", flag: "8idaSoft:CR8-A1:m5" } - new: true - confirm: true - note: "first FMBO mirror; coarse and piezo fine pitch (OPT-1)" - - name: Mirror_2 - family: Mirror - pv: { x: "8idaSoft:FMBO:m3", y: "8idaSoft:FMBO:m1", coarse_pitch: "8idaSoft:FMBO:m5", fine_pitch: "8idaSoft:FMBO:Piezo:m2", bender1: "8idaSoft:FMBO:m7", bender2: "8idaSoft:FMBO:m8", flag: "8idaSoft:CR8-A1:m6" } - new: true - confirm: true - note: "second FMBO mirror with benders (OPT-1)" - - name: WhiteBeamSlit - family: Slit - pv: "8idaSoft:CR8-A1:US" - new: true - confirm: true - note: "white-beam slit (8-ID-A)" - - name: MonoSlit - family: Slit - pv: "8idaSoft:CR8-A1:US" - new: true - confirm: true - note: "post-mono slit; full axis map is OPT-2" - -focusing: - stage: source - enclosure: 8-ID-D - intro: "The compound refractive lens transfocators that focus the coherent beam for XPCS, and the 8-ID-D slits." - note: > - rl1 and rl2 are CRL transfocator lens stacks (ten lenses each on 8iddSoft:TRANS), - bound to the graduated Transfocator catalog Family (a CRL focusing optic, also - used at 4-ID); the lens spec stays open (OPT-3; see model.md). - devices: - - name: Transfocator_1 - family: Transfocator # catalog Family (lens spec OPT-3) - pv: { x: "8iddSoft:TRANS:m2", y: "8iddSoft:TRANS:m1", pitch: "8iddSoft:TRANS:m4", yaw: "8iddSoft:TRANS:m3" } - new: true - confirm: true - lens_count: 10 - note: "first CRL transfocator (rl1); ten lens actuators 8iddSoft:TRANS:m5-m14, summarized (OPT-3)" - - name: Transfocator_2 - family: Transfocator # catalog Family (lens spec OPT-3) - pv: { x: "8iddSoft:TRANS:m26", y: "8iddSoft:TRANS:m25", pitch: "8iddSoft:TRANS:m28", yaw: "8iddSoft:TRANS:m27" } - new: true - confirm: true - lens_count: 10 - note: "second CRL transfocator (rl2); ten lens actuators 8iddSoft:TRANS:m15-m24, summarized (OPT-3)" - - name: Slit_8idd - family: Slit - pv: "8iddSoft:Slit1" - new: true - confirm: true - note: "8-ID-D slit" - -# =========================================================================== -# SAMPLE STAGE: the 8-ID-E six-circle diffractometer and the 8-ID-I XPCS sample -# =========================================================================== - -diffractometer: - stage: sample - enclosure: 8-ID-E - intro: "The 8-ID-E six-circle Huber diffractometer endstation, with its temperature controllers and beam-position monitor." - note: > - huber is a six-circle diffractometer (mu, eta, chi, phi, nu, delta) plus x/y/z - sample translation, modelled as a plain device with its circle axis map; the - reusable Assembly(Diffractometer) is designed on model.md (DIFF-1). psic is the - reciprocal-space pseudo-axis layer (hklpy2). The LakeShore controllers and the - Sydor beam-position monitor bind loose Families that 4-ID also uses, held for - gate-review (see model.md). - devices: - - name: Diffractometer_SixCircle - family: Goniometer # catalog Family; the sample-orientation goniometer of the Diffractometer Assembly (DIFF-1) - pv: { mu: "8ideSoft:CR8-E1:m6", eta: "8ideSoft:CR8-E1:m7", chi: "8ideSoft:CR8-E1:m8", phi: "8ideSoft:CR8-E1:m9", nu: "8ideSoft:CR8-E1:m4", delta: "8ideSoft:CR8-E1:m5", x: "8ideSoft:CR8-E1:m15", y: "8ideSoft:CR8-E1:m10", z: "8ideSoft:CR8-E1:m11" } - new: true - confirm: true - note: "six-circle Huber diffractometer; the six circles (mu/eta/chi/phi/nu/delta) confirm the Assembly slot shape (DIFF-1)" - - name: ReciprocalSpace - family: PseudoAxis - pv: "8ideSoft:CR8-E1:" - new: true - confirm: true - note: "hklpy2 reciprocal-space pseudo-axis over the six-circle geometry (psic); the partition rule is DIFF-2" - - name: TemperatureController_1 - family: TemperatureController # catalog Family (graduated #350; presents Regulator) - pv: "8ideSoft:LS336:1:" - new: true - confirm: true - note: "LakeShore 336 sample temperature controller (TEMP-1)" - - name: TemperatureController_2 - family: TemperatureController # catalog Family (graduated #350; presents Regulator) - pv: "8ideSoft:LS336:2:" - new: true - confirm: true - note: "second LakeShore 336 controller (TEMP-1)" - - name: BeamPositionMonitor_E - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1, BPM-1) - pv: "8ideBPM:T4U_BPM:" - new: true - confirm: true - note: "Sydor TetrAMM beam-position monitor at 8-ID-E (BPM-1)" - - name: FastShutter - family: Shutter - pv: "8ideSoft:fastshutter:" - new: true - confirm: true - note: "fast shutter gating the XPCS exposure (XPCS-1)" - -xpcs-sample: - stage: sample - enclosure: 8-ID-I - intro: "The XPCS sample endstation in 8-ID-I: the Aerotech sample and rheometer stages and the temperature-controlled sample holders." - note: > - sample is a three-axis Aerotech translation stage (LinearStage); the rheometer - is a six-axis shear-cell sample environment bound to a loose Rheometer Family. - The Quantum Northwest holders (qnw) are temperature-controlled sample cells. - devices: - - name: SampleStage - family: LinearStage - pv: { x: "8idiAerotech:m1", y: "8idiAerotech:m3", z: "8idiAerotech:m2" } - new: true - confirm: true - note: "Aerotech XPCS sample positioning stage" - - name: Rheometer - family: Rheometer # loose Family (SAMPLE-1) - pv: { x: "8idiAerotech:m8", y: "8idiAerotech:m9", z: "8idiAerotech:m7", pitch: "8idiAerotech:m11", roll: "8idiAerotech:m10", yaw: "8idiAerotech:m12" } - new: true - confirm: true - note: "six-axis rheometer shear-cell sample environment (SAMPLE-1)" - - name: SampleHolder_QNW - family: TemperatureController # catalog Family (graduated #350; presents Regulator) - pv: "8idiSoft:QNWenv_1:" - new: true - confirm: true - note: "Quantum Northwest temperature-controlled sample holder; three units QNWenv_1..3 (TEMP-1)" - - name: SampleSlit - family: Slit - pv: "8idiSoft:Slit1" - new: true - confirm: true - note: "8-ID-I sample slit" - -# =========================================================================== -# DETECTION STAGE: the XPCS coherent area detectors and the flight path -# =========================================================================== - -xpcs-detectors: - stage: detection - enclosure: 8-ID-I - intro: "The XPCS coherent-scattering area detectors (Eiger, Lambda, Rigaku), their positioning stage, and the evacuated flight path that carries the scattered beam to them." - note: > - Three area detectors on a translation stage, downstream of an evacuated flight - path with a beam stop. The flight path binds a loose FlightPath Family; the beam - stop binds the catalog BeamStop Family. - devices: - - name: Eiger4M - family: Camera - pv: "8idEiger4m:" - new: true - confirm: true - note: "Eiger 4M coherent-scattering detector (DET-1)" - - name: Lambda2M - family: Camera - pv: "8idLambda2m:" - new: true - confirm: true - note: "Lambda 2M detector (DET-1)" - - name: Rigaku3M - family: Camera - pv: "8idRigaku3m:" - new: true - confirm: true - note: "Rigaku 3M high-frame-rate detector (DET-1)" - - name: DetectorStage - family: LinearStage - pv: { x: "8idiAerotech:m4", y: "8idiAerotech:m5" } - new: true - confirm: true - note: "Aerotech detector positioning stage" - - name: FlightPath - family: FlightPath # loose Family (XPCS-2) - pv: { length: "8idiSoft:FLIGHT:m1", swing: "8idiSoft:FLIGHT:m2", ds_x: "8idiSoft:FLIGHT:m5", ds_y: "8idiSoft:FLIGHT:m6", us: "8idiSoft:FLIGHT:m7" } - new: true - confirm: true - note: "evacuated flight path carrying the scattered beam to the detectors (XPCS-2)" - - name: BeamStop - family: BeamStop - pv: { ds_x: "8idiSoft:FLIGHT:m5", ds_y: "8idiSoft:FLIGHT:m6", us: "8idiSoft:FLIGHT:m7" } - new: true - confirm: true - note: "flight-tube beam stop" - - name: TetrAMM_QUAD1 - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1, BPM-1) - pv: "8idTetra:QUAD1:" - new: true - confirm: true - note: "TetrAMM picoammeter / position monitor; four channels QUAD1..4 (BPM-1)" - -# Cross-cutting control. 8-ID runs EPICS (the floor); CORA observes and, where it -# replaces Bluesky-style orchestration, conducts over it. The handles above were -# read from the 8id-bits instrument config and carried confirm (CTRL-1). -controls: - intro: > - 8-ID runs on the APS EPICS control stack. The device handles above are bound - from the beamline's Bluesky instrument repo (BCDA-APS/8id-bits), carried - confirm pending staff verification (CTRL-1). XPCS acquisition timing runs on a - softGlueZynq FPGA fabric (8idMZ1:), modelled here as a single TimingController; - the full softGlue signal graph is XPCS-3. - triggering: - - name: Timing - family: TimingController - pv: "8idMZ1:SG:" - new: true - confirm: true - note: "softGlueZynq timing fabric driving the coherent-detector exposure gating (XPCS-3)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources an 8-ID run needs. The flight - path and sample environments draw on vacuum and process gases (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the evacuated flight path and the XPCS sample environment (SUP-1)" diff --git a/deployments/9-id/beamline.yaml b/deployments/9-id/beamline.yaml deleted file mode 100644 index 5f45cd506e5..00000000000 --- a/deployments/9-id/beamline.yaml +++ /dev/null @@ -1,315 +0,0 @@ -# CORA Beamline descriptor: 9-ID (APS), operational-PV first cut -# -# 9-ID is the Coherent Surface Scattering Instrument (CSSI) at APS (Argonne), -# operational across stations 9-ID-A (optics) and 9-ID-D (the CSSI endstation). It -# is bound to the APS Site (deployments/aps/site.yaml). It is a coherent-scattering -# beamline whose signature technique is grazing-incidence surface scattering: the -# sample sits at a shallow incidence angle and a coherent beam probes its surface -# structure and dynamics (GISAXS / GIWAXS and surface XPCS). -# -# It is almost entirely catalog REUSE: every optic and detector binds a catalog -# Family (InsertionDevice, Monochromator, Mirror, Aperture, Filter, Slit, Camera, -# BeamStop, Hexapod, plus the graduated CRL Transfocator), so it adds no new -# catalog Family. Its beam-position monitors bind the graduated PositionMonitor -# Family, the same catalog Family 4-ID and 8-ID use (earned across the wide fleet). -# -# STATUS: first cut, reverse-engineered. Like 4-ID and 8-ID, this binds the real -# EPICS control handles, read from the beamline's own Bluesky instrument repo -# (BCDA-APS/9id_bits). Every value is carried -# `confirm: true` until 9-ID staff verify it, and `new: true` (not yet registered -# in CORA). No vendor `model` is bound. -# -# DELIBERATELY OUT OF THIS CUT (recorded on docs/deployments/9-id/model.md): the -# bluesky / APS Data Management metadata PVs (experiment_name, file_path, qmap_file, -# workflow_name, the DM_WorkflowConnector), which are the experiment-record -# bookkeeping CORA's own system of record replaces rather than models as Assets; -# the simulated devices; integration scenarios; vendor Models; z-positions. The -# grazing-incidence sample stack is modelled as plain devices, not yet an Assembly. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/9-id/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "the Coherent Surface Scattering Instrument (CSSI) across two stations" - name: 9-ID - facility: aps # APS, the Site-level Facility (facility_code: aps) - sector: "Sector 9" # organizational label, not a registered asset - tier: Unit - parent: null - source: insertion-device - source_confirm: "one planar undulator on the S09ID straight section (DSID extracted); whether a second undulator or a canted pair feeds a branch is SRC-1 / TOPO-1" - page_layout: stages - shape: "A coherent grazing-incidence scattering beamline (GISAXS / GIWAXS / surface XPCS): the sample sits at a shallow angle to a coherent beam for surface sensitivity, in almost pure catalog reuse." - source_ref: - label: "BCDA-APS/9id_bits" - url: "https://github.com/BCDA-APS/9id_bits" - -# Two lead-shielded stations: 9-ID-A holds the optics; 9-ID-D the CSSI endstation -# (focusing, the grazing-incidence sample stack, and the detectors). PSS permit -# signals are APS facility signals, not yet on file (PSS-1). -enclosures: - - name: 9-ID-A - role: optics-hutch - facility_code: aps - permit_signal: {confirm: "APS PSS search-and-secure signal TBD (PSS-1)"} - - name: 9-ID-D - role: experiment-hutch - facility_code: aps - permit_signal: {confirm: "APS PSS search-and-secure signal TBD (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the 9-ID-A optics spine and the 9-ID-D focusing -# =========================================================================== - -insertion-devices: - stage: source - enclosure: 9-ID-A - intro: "The undulator source on the S09ID straight section." - note: "One InsertionDevice Asset; whether a second undulator or a canted pair feeds a branch is SRC-1 / TOPO-1." - devices: - - name: Undulator - family: InsertionDevice - pv: "S09ID:DSID:" - new: true - confirm: true - note: "planar undulator (SRC-1)" - -optics: - stage: source - enclosure: 9-ID-A - intro: "The monochromator, the high-heat-load mirrors, the white-beam apertures, and the attenuator." - note: > - mono is the Kohzu double-crystal monochromator; mr1/mr2 are the FMBO mirrors - with coarse pitch, piezo fine pitch, and benders. The diagnostic flag cameras - (flag1-3) and the DAMM mask carried only their insertion-motor PVs in the - config and are folded into this note pending identification (DIAG-1). - devices: - - name: Monochromator - family: Monochromator - pv: "9ida:" - new: true - confirm: true - note: "Kohzu sequence-controlled double-crystal monochromator (idt_mono); energy range and crystal set unconfirmed (MONO-1)" - - name: Mirror_1 - family: Mirror - pv: { x: "9ida:FMBO:m4", y: "9ida:FMBO:m2", coarse_pitch: "9ida:FMBO:m6", fine_pitch: "9ida:FMBO:Piezo:m1", bender: "9ida:FMBO:m8" } - new: true - confirm: true - note: "first FMBO mirror; coarse and piezo fine pitch (OPT-1)" - - name: Mirror_2 - family: Mirror - pv: { x: "9ida:FMBO:m3", y: "9ida:FMBO:m1", coarse_pitch: "9ida:FMBO:m5", fine_pitch: "9ida:FMBO:Piezo:m2", bender: "9ida:FMBO:m7" } - new: true - confirm: true - note: "second FMBO mirror with bender (OPT-1)" - - name: Aperture_1 - family: Aperture - pv: "9ida:SL-1:" - new: true - confirm: true - note: "high-heat-load white-beam aperture (HHLApertureWBA); axis map is OPT-2" - - name: Aperture_2 - family: Aperture - pv: "9ida:SL-2:" - new: true - confirm: true - note: "second high-heat-load white-beam aperture; axis map is OPT-2" - - name: Filter - family: Filter - pv: "9idPyFilter:FL1:" - new: true - confirm: true - note: "AVS filter bank attenuator (fl1); lens/foil set is OPT-4" - -focusing: - stage: source - enclosure: 9-ID-D - intro: "The compound refractive lens transfocator and the Kirkpatrick-Baez mirror that focus the coherent beam into the CSSI endstation." - note: > - crl is a JJ CRL transfocator lens stack (9idPyCRL:CRL9ID), bound to the - graduated Transfocator catalog Family (a CRL focusing optic) that 4-ID and - 8-ID also use; its lens material and count stay open (OPT-3; see model.md). kb - is the KB focusing pair carrying capacitive-sensor bender axes; modelled as one - Mirror Asset (OPT-5). - devices: - - name: Transfocator - family: Transfocator # catalog Family (OPT-3: lens spec) - pv: "9idPyCRL:CRL9ID:" - new: true - confirm: true - note: "JJ CRL transfocator focusing the coherent beam (crl9id2x); lens material and count are OPT-3" - - name: KBMirror - family: Mirror - pv: { hor_upstream: "9idKB:", hor_downstream: "9idKB:", ver_upstream: "9idKB:", ver_downstream: "9idKB:", granite: "9idd:CR9D1M1:m29" } - new: true - confirm: true - note: "Kirkpatrick-Baez focusing pair; the four bender axes carry capacitive-sensor suffixes resolved at runtime, the granite support is a base motor (OPT-5)" - -beam-defining: - stage: source - enclosure: 9-ID-D - intro: "The guard slits that define the focused beam entering the CSSI endstation." - note: "Three guard slits (slit3/4/5) on the 9-ID-D soft-IOC optics; the per-blade axis maps are OPT-2." - devices: - - name: Slit_3 - family: Slit - pv: "9idd:Slit3" - new: true - confirm: true - note: "first 9-ID-D guard slit (OPT-2)" - - name: Slit_4 - family: Slit - pv: "9idd:Slit4" - new: true - confirm: true - note: "second 9-ID-D guard slit (OPT-2)" - - name: Slit_5 - family: Slit - pv: "9idd:Slit5" - new: true - confirm: true - note: "third 9-ID-D guard slit (OPT-2)" - -# =========================================================================== -# SAMPLE STAGE: the 9-ID-D grazing-incidence CSSI sample stack -# =========================================================================== - -cssi-sample: - stage: sample - enclosure: 9-ID-D - intro: "The Coherent Surface Scattering Instrument sample stack: the grazing-incidence sample stage, its incidence rotation, the alignment hexapods, and the on-axis viewing microscope." - note: > - The CSSI signature is grazing incidence: the sample translation places the - surface in the beam and the incidence rotation sets the shallow angle that makes - the measurement surface-sensitive. The stack is modelled as plain devices with - its axis maps; whether it composes into a sample Assembly is deferred (CSSI-1). - A sample-positioning Kohzu stage (kohzu_linear / kohzu_rotate) is folded into - this note pending its role (CSSI-1). - devices: - - name: CSSISampleStage - family: LinearStage - pv: { x: "9idCSSI:mcs2-01:m4", y: "9idCSSI:mcs2-01:m3", z: "9idCSSI:mcs2-01:m2", fly_z: "9idANT95:aero:c0:m1", gixs_x: "9idd:CR9D4M1:m3" } - new: true - confirm: true - note: "grazing-incidence sample translation; fly_z is the Aerotech fly-scan axis (CSSI-1)" - - name: CSSIIncidence - family: RotaryStage - pv: { theta: "9idCSSI:mcs2-01:m1" } - new: true - confirm: true - note: "grazing-incidence rotation setting the shallow surface angle; a second capacitive theta (theta3) is resolved at runtime (CSSI-1)" - - name: Hexapod_1 - family: Hexapod - pv: "9idAerotech:HP1:" - new: true - confirm: true - note: "Aerotech six-axis alignment hexapod (CSSI-2)" - - name: Hexapod_2 - family: Hexapod - pv: "9idAerotech2:HP2:" - new: true - confirm: true - note: "second Aerotech six-axis alignment hexapod (CSSI-2)" - - name: ViewingMicroscope - family: Camera - pv: { x: "9idCSSI:CR9D1M2:m5", y: "9idCSSI:CR9D1M2:m9", z: "9idCSSI:CR9D1M2:m6", focus: "9idCSSI:CR9D1M2:m10" } - new: true - confirm: true - note: "on-axis sample-viewing microscope (uscope); an optical alignment camera, not the TXM Microscope Assembly (CSSI-3)" - -# =========================================================================== -# DETECTION STAGE: the coherent area detectors and the beam-position monitors -# =========================================================================== - -detectors: - stage: detection - enclosure: 9-ID-D - intro: "The coherent-scattering area detectors (a Pilatus, an Eiger on a translation stage, and a WAXS detector on a pedestal), the beam stop, and the beam-position monitors." - note: > - Pilatus and Eiger record the small-angle coherent pattern; the WAXS detector on - its pedestal records the wide-angle signal for GIWAXS. The beam stop and its - carriage block the direct beam. The TetrAMM and the two XBPMs bind the graduated - PositionMonitor Family (a consumer alongside 4-ID and 8-ID; DIAG-1 / FLUX-1, BPM-1). - devices: - - name: Pilatus1M - family: Camera - pv: "PILATUS_1MF:" - new: true - confirm: true - note: "Pilatus 1M coherent-scattering detector (DET-1)" - - name: EigerDetector - family: Camera - pv: "9idEiger:" - new: true - confirm: true - note: "Eiger coherent-scattering detector; model unconfirmed, prefix is a guess pending CTRL-1 (DET-1)" - - name: DetectorStage - family: LinearStage - pv: { x: "9idGT:m11", y: "9idGT:m12" } - new: true - confirm: true - note: "Eiger detector positioning stage (eiger_x / eiger_y)" - - name: WAXSDetector - family: Camera - pv: { pedestal_x: "9idd:CR9D1M1:m31", pedestal_y: "9idd:CR9D1M1:m32" } - new: true - confirm: true - note: "wide-angle (GIWAXS) detector on its pedestal; detector model is DET-1" - - name: BeamStop - family: BeamStop - pv: { x: "9idd:CR9D4M1:m14", z: "9idd:CR9D4M1:m15", carriage_y: "9idGT:m1", carriage_bottom: "9idGT:mcs2-02:m3" } - new: true - confirm: true - note: "direct-beam stop and its carriage" - - name: TetrAMM - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1, BPM-1) - pv: "9idTetra:QUAD1:" - new: true - confirm: true - note: "TetrAMM picoammeter / position monitor, four channels (BPM-1)" - - name: XBPM_1 - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1, BPM-1) - pv: "9idd:" - new: true - confirm: "device prefix inferred from the 9-ID-D station; the xpbm1 sum/x/y signals carried no device prefix in the config (CTRL-1)" - note: "X-ray beam-position monitor (xpbm1 sum/x/y signals, lifted from the config's metadata bucket as a genuine diagnostic); position-vs-intensity role is BPM-1" - - name: XBPM_2 - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1, BPM-1) - pv: "9idd:" - new: true - confirm: "device prefix inferred from the 9-ID-D station; the xpbm2 sum/x/y signals carried no device prefix in the config (CTRL-1)" - note: "second X-ray beam-position monitor (xpbm2 sum/x/y signals, lifted from the config's metadata bucket); position-vs-intensity role is BPM-1" - -# Cross-cutting control. 9-ID runs EPICS (the floor); CORA observes and, where it -# replaces Bluesky-style orchestration, conducts over it. The handles above were -# read from the 9id_bits instrument config and carried confirm (CTRL-1). -controls: - intro: > - 9-ID runs on the APS EPICS control stack. The device handles above are bound - from the beamline's Bluesky instrument repo (BCDA-APS/9id_bits), carried confirm - pending staff verification (CTRL-1). The instrument config also carries a large - set of metadata PVs (experiment_name, file_path, qmap_file, workflow_name) and a - DM_WorkflowConnector that trigger APS Data Management workflows; these are the - experiment-record bookkeeping CORA's own system of record replaces, so they are - a seam, not modelled as Assets (see model.md). - triggering: - - name: FlyScanScaler - family: GenericProbe - pv: "9idCSSI:mcs2-01:" - new: true - confirm: true - note: "multi-channel scaler gating the grazing-incidence fly scans (coarse; the full timing graph is CTRL-2)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a 9-ID run needs. The transfocator, - the KB mirror, and the detector flight draw on vacuum (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the focusing optics and the detector flight path (SUP-1)" diff --git a/deployments/alba/site.yaml b/deployments/alba/site.yaml deleted file mode 100644 index a87b4bc3399..00000000000 --- a/deployments/alba/site.yaml +++ /dev/null @@ -1,68 +0,0 @@ -# CORA Site descriptor: the ALBA site-level surface -# -# ALBA (Barcelona, Spain), operated by the CELLS consortium, is the ninth Site -# CORA models, and the home of the BL31 FAXTOR fast-tomography beamline. This file -# is the single human-readable source for the facility's site-level instances: the -# Facility itself, the Practices it runs, and the facility principals. -# -# Status: FAXTOR is a reverse-engineered, design-phase first cut (like the Diamond -# / NSLS-II / ESRF modelling exercises). ALBA is CORA's SECOND Tango / Sardana / -# Taurus controls house-style (MAX IV is the first; the rest are EPICS, and the -# ESRF is BLISS). Facts here are taken from ALBA's public facility pages -# (www.cells.es), not from a live connection; concrete -# facility details (safety forms, supply names, the operator pool) are carried -# pending until ALBA staff confirm them. Do not invent facility specifics here; -# carry them as questions on the FAXTOR open-questions page. -# -# Source-of-truth boundary (same as the other sites): -# - the closed facility-kind / actor-kind vocabularies are validated against -# code-mirrored frozensets in scripts/site_descriptor.py. -# - the facility records the bootstrap invariants (kind=Site, display_name -# equals code); `heading` carries the human title used on the rendered page. -# - a non-pending practice method must resolve to a catalog Method; FAXTOR's -# tomography practices reuse the catalog tomography Methods, so they are not -# pending; the radiography practice names a Method not yet in the catalog and -# is carried pending (TECH-1). - -facility: - code: alba - display_name: alba - heading: "ALBA" - kind: Site - institution: ALBA Synchrotron (CELLS) - control_plane: "Tango / Sardana / Taurus" - beamlines: [FAXTOR] - -# ISA-88 Site Recipes: the facility-adapted form of a catalog Method. FAXTOR is a -# tomography beamline, so its imaging practices reuse the catalog tomography -# Methods and are not pending. Radiography is named pending: it has no portable -# catalog Method yet (the 7-BM precedent), reusing the registered radiography slug -# (TECH-1). Confirm scope with ALBA staff before any becomes active. -practices: - - {name: FAXTOR_microtomography_practice, method: tomography, note: "fast absorption / phase-contrast micro-CT on the experiment endstation"} - - {name: FAXTOR_continuous_tomography_practice, method: continuous_rotation_tomography, note: "fast continuous-rotation tomography, up to 20 Hz acquisition"} - - {name: FAXTOR_radiography_practice, method: radiography, pending: true, note: "time-resolved radiography; reuses the 7-BM radiography slug, no portable Method yet (TECH-1)"} - -# Access BC Actors conceptually facility-wide at ALBA. Pending until the ALBA -# operator and review structure is confirmed. -actors: - - {name: ALBA beamline staff, kind: human, pending: true, note: "operator and beamline-scientist pool; structure TBD (GOV-1)"} - - {name: ALBA safety review, kind: human, pending: true, note: "facility safety review body; membership TBD (GOV-1)"} - -# Agent BC Agents seeded at this deployment. None declared: the CORA system agents -# are not wired for an ALBA deployment, and FAXTOR is a modelling exercise. -agents: [] - -# Supply BC: facility-wide continuously-available resources. Pending in design. -supplies: - - {name: Storage-ring beam current, kind: PhotonBeam, pending: true, note: "ALBA 3 GeV storage-ring beam, shared across the beamlines (SUP-1)"} - - {name: Cooling water, kind: CoolingWater, pending: true} - - {name: Beamline vacuum, kind: Vacuum, pending: true} - -# Safety BC: facility-issued Clearances. ALBA safety-form names are not yet -# confirmed; carried pending with a note rather than guessed. -clearances: - - {name: ALBA personnel safety system, kind: PSS, pending: true, note: "facility safety-form names TBD; confirm with ALBA staff (PSS-1)"} - -# Caution BC: operator tribal knowledge. None yet for a modelling exercise. -cautions: [] diff --git a/deployments/als/site.yaml b/deployments/als/site.yaml deleted file mode 100644 index 00d1f08ef7f..00000000000 --- a/deployments/als/site.yaml +++ /dev/null @@ -1,65 +0,0 @@ -# CORA Site descriptor: the ALS site-level surface -# -# The Advanced Light Source (ALS), at Lawrence Berkeley National Laboratory -# (Berkeley, California), is CORA's first ALS Site, and the home of the 8.3.2 -# hard X-ray micro-tomography beamline. This file is the single human-readable -# source for the facility's site-level instances: the Facility itself, the -# Practices it runs, and the facility principals. -# -# Status: 8.3.2 is a reverse-engineered, design-phase first cut (like the Diamond -# / NSLS-II / ESRF / ALBA modelling exercises). ALS is CORA's FIRST BCS -# (Beamline Control System, a LabVIEW house-style) control plane; every prior -# Site is EPICS, Tango / Sardana, or BLISS. Facts here are taken from ALS's -# public facility pages (als.lbl.gov) and the public als-computing GitHub org -# (github.com/als-computing), not from a live connection; concrete facility -# details (safety forms, supply -# names, the operator pool) are carried pending until ALS staff confirm them. Do -# not invent facility specifics here; carry them as questions on the 8.3.2 -# open-questions page. -# -# ALS-U context: the ALS is undergoing the ALS-U storage-ring upgrade. Dark time -# is projected to start no sooner than October 2027 and last at least two years. -# Whether 8.3.2 goes dark, is rebuilt, or relocates is a staff question -# (ALSU-1), not modelled here. -# -# Source-of-truth boundary (same as the other sites): -# - the closed facility-kind / actor-kind vocabularies are validated against -# code-mirrored frozensets in scripts/site_descriptor.py. -# - the facility records the bootstrap invariants (kind=Site, display_name -# equals code); `heading` carries the human title used on the rendered page. -# - a non-pending practice method must resolve to a catalog Method; 8.3.2's -# tomography practices reuse the catalog tomography Methods, so they are not -# pending. - -facility: - code: als - display_name: als - heading: "ALS" - kind: Site - institution: Lawrence Berkeley National Laboratory (ALS) - control_plane: "BCS (LabVIEW)" - beamlines: ["8.3.2"] - -# ISA-88 Site Recipes: the facility-adapted form of a catalog Method. 8.3.2 is a -# hard X-ray micro-tomography beamline, so its imaging practices reuse the -# catalog tomography Methods and are not pending. Confirm scope with ALS staff -# before any becomes active. -practices: - - {name: 8.3.2_microtomography_practice, method: tomography, note: "hard X-ray absorption and propagation-phase micro-CT on the experiment endstation"} - - {name: 8.3.2_continuous_rotation_practice, method: continuous_rotation_tomography, note: "fast continuous-rotation fly-scan tomography"} - -# Access BC Actors conceptually facility-wide at ALS. Pending until the ALS -# operator and review structure is confirmed. -actors: - - {name: ALS beamline staff, kind: human, pending: true, note: "operator and beamline-scientist pool; structure TBD (GOV-1)"} - - {name: ALS safety review, kind: human, pending: true, note: "facility safety review body; membership TBD (GOV-1)"} - -# Agent BC Agents seeded at this deployment. None declared: the CORA system -# agents are not wired for an ALS deployment, and 8.3.2 is a modelling exercise. -agents: [] - -# Supply BC: facility-wide continuously-available resources. Pending in design. -supplies: - - {name: Storage-ring beam current, kind: PhotonBeam, pending: true, note: "ALS storage-ring beam from the 8.3.2 Superbend, shared across the facility (SUP-1)"} - - {name: Cooling water, kind: CoolingWater, pending: true} - - {name: Beamline vacuum, kind: Vacuum, pending: true} diff --git a/deployments/alvra/beamline.yaml b/deployments/alvra/beamline.yaml deleted file mode 100644 index a5261afc395..00000000000 --- a/deployments/alvra/beamline.yaml +++ /dev/null @@ -1,413 +0,0 @@ -# CORA Beamline descriptor: Alvra (SwissFEL, PSI), modelling exercise -# -# Alvra is an operating hard-X-ray pump-probe experimental station on SwissFEL's -# Aramis branch at PSI. It is bound to the PSI Site (deployments/psi/site.yaml), -# CORA's fourteenth Site and its SECOND XFEL after SLAC LCLS-MFX. -# -# STATUS: off-roadmap modelling exercise, NOT a CORA pilot. The device shape and the -# EPICS control handles are reverse-engineered from PSI's open `eco` controls library -# (paulscherrerinstitute/eco, the SwissFEL device library; the Alvra manifest is the -# `aliases` dict in eco/alvra/config.py, with each device's driver class deriving its -# motor PVs from the prefix). It is treated as a dry, correct DATA source and modelled -# intentionally, not mirrored. Scope is the Alvra beam-path spine + the Prime endstation -# core; peripheral/floor devices are deferred. -# -# WHY ALVRA (what it tests): Alvra is the SECOND XFEL CORA models, and its value is -# REINFORCEMENT FROM AN INDEPENDENT CONTROL STACK. LCLS-MFX was mined from `pcdshub`; -# Alvra is mined from `eco`. The two XFELs were built by different teams with different -# house styles (PV conventions SARFE10-/SAROP11-/SARES11- here, vs LCLS's). If the same -# family-fold finding and the same architectural gaps recur, the model generalizes -# beyond one facility, not just beyond storage rings. -# -# THE HEADLINE FINDING (same as LCLS-MFX): ALVRA'S DEVICE FAMILIES FOLD. Every device -# in the eco manifest reuses a catalog Family or an existing loose family. The von Hamos -# emission spectrometer reuses the EmissionSpectrometer Family that LCLS-MFX introduced -# and NSLS-II ISS GRADUATED (Alvra is a fourth sighting). The genuine gaps are the same -# ARCHITECTURAL XFEL gaps recorded for LCLS-MFX, not taxonomic ones; they are recorded -# as deliberate deferrals on docs/deployments/alvra/model.md (not invented here): -# - per-shot pulse-ID event DAQ (DAQ-1; the sf-daq / bsread data plane) -# - beam-synchronous event-code timing (TIMING-1; the SwissFEL event system / EVR) -# - femtosecond pump-probe laser/X-ray synchronization (LASER-1; the lxt timing chain) -# - one switched Aramis source feeding co-equal stations (TOPO-1; Alvra/Bernina/Cristallina) -# - attenuator transmission solver (ATT-1; the AttenuatorAramis energy-dependent solve) -# -# Family folds (each adversarially reviewed, the LCLS-MFX precedent): OffsetMirror / -# KB mirror -> Mirror; AttenuatorAramis -> Filter; SlitFourBlades/SlitBlades/SlitPosWidth -# -> Slit; X-ray pulse picker -> Shutter (fast pulse gate; Shutter-vs-Chopper open, -# PULSE-1); Pprm profile monitor -> Scintillator + Camera; PBPS / PBIG intensity-position -# monitor -> FluxMonitor + Diagnostic (loose, reused); Double_Crystal_Mono -> Monochromator; -# the experiment laser -> catalog Laser Family (the LCLS-MFX / 4-ID precedent); the von Hamos -> -# EmissionSpectrometer (graduated catalog Family); the Jungfrau area detector -> Camera. -# The reference / alignment laser -> catalog Laser Family. The SwissFEL event timing -> TimingController. -# Vacuum gate valves and the DAQ are floor and not modelled (as at LCLS-MFX / i03). -# -# Every device carries `new: true` (not a registered Asset) and `confirm: true` (PVs + -# values to be verified by PSI staff). The `eco` manifest carries NO units, NO motor -# limits, and NO Aramis undulator source parameters; those, the PSS safety structure, -# and the Capability / Method binding are NOT invented; each gap carries a (QUESTION-ID) -# answered on the open-questions page. Some eco entries reference SAROP21-* (a sibling -# Aramis line) inside Alvra drivers; whether that is correct for Alvra or a copy-paste -# artifact is carried confirm (XREF-1). -# -# DEFERRED (out of spine+core scope, noted not modelled): the sf-daq data plane (CORA -# references a Dataset, does not own per-shot data, DAQ-1); the pump-probe optical-laser -# delay chain + lxt fs timing (the laser binds the catalog Laser Family; its fs -# X-ray/laser synchronization has no CORA model, LASER-1); the fixed-target / liquid-jet -# sample delivery (SAMPLE-1); the sibling Aramis stations Bernina / Cristallina that -# share the source (TOPO-1). - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "hard X-ray femtosecond pump-probe (time-resolved XAS / XES / HERFD and serial crystallography) on the SwissFEL Aramis branch; CORA's second XFEL, reinforcing the LCLS-MFX family-fold and acquisition-gap findings from an independent control stack (`eco`)" - name: Alvra - facility: psi - tier: Unit - parent: null - source: free-electron-laser - source_confirm: > - SASE hard-X-ray FEL on the shared SwissFEL Aramis undulator line; photon energy is - set per-shot and the same source feeds the Alvra, Bernina, and Cristallina stations - one at a time (SRC-1 / TOPO-1). The Aramis undulator parameters are not in the eco - manifest and are carried confirm. - page_layout: stages - shape: "A soft / tender XFEL endstation on PSI's Aramis branch (pump-probe spectroscopy, von Hamos emission); CORA's second XFEL, mined from an independent control stack, confirming the device families fold and the gaps are architectural." - source_ref: - label: "paulscherrerinstitute/eco" - url: "https://github.com/paulscherrerinstitute/eco" - -# Two access-gated zones. The Aramis optics hutch conditions the beam shared with the -# other Aramis stations; the Alvra experiment hutch holds the Prime endstation. The eco -# manifest records z positions and PV prefixes but not which access-gated hutch a device -# is in or its safety meaning (ENC-1). SwissFEL PPS permit + the pump-probe laser -# interlock are carried confirm (PSS-1, LASER-1). -enclosures: - - name: Aramis-Optics - role: optics-hutch - facility_code: psi - permit_signal: {confirm: "SwissFEL PPS search-and-secure signal TBD; the Aramis optics are shared across the Aramis stations (TOPO-1, PSS-1)"} - - name: Alvra - role: experiment-hutch - facility_code: psi - permit_signal: {confirm: "SwissFEL PPS + pump-probe laser interlock TBD (PSS-1, LASER-1)"} - -# --- SOURCE STAGE: the FEL source, shared front end, and Aramis optics --- - -undulator-source: - stage: source - enclosure: Aramis-Optics - intro: "The SwissFEL Aramis free-electron-laser source and its front-end pulse-intensity monitors." - note: > - SwissFEL is a linac-driven FEL, not a storage ring, so the loose StorageRing family - used by the synchrotron exercises does not fit; machine beam is carried as a PhotonBeam - Supply (MACHINE-1). The Aramis undulator photon energy is set per shot; CORA has no - per-shot energy setpoint, and the undulator-as-driven-source is deferred (SRC-1). The - undulator parameters are absent from the eco manifest (SRC-1). - devices: - - name: Undulator - family: InsertionDevice - pv: {confirm: "SwissFEL Aramis undulator line; per-segment handles not in eco (SRC-1)"} - new: true - confirm: true - note: "the FEL source; SASE mode and per-shot photon energy are a DAQ-plane datum, not a standing setpoint (SRC-1, DAQ-1)" - - name: GasMonitor - family: FluxMonitor - pv: "SARFE10-PBIG050" - new: true - confirm: true - note: "gas intensity monitor (PBIG); FEL pulse-energy diagnostic, presents the Sensor Role; loose family reused. Per-shot pulse energy is correlated in the DAQ by pulse-ID (DAQ-1). eco entry has no driver (catalogued, not instantiated)" - - name: FrontEndIntensityMonitor - family: FluxMonitor - pv: "SARFE10-PBPS053" - new: true - confirm: true - note: "intensity / position monitor after the undulator (PBPS); presents the Sensor Role for both flux (FluxMonitor) and beam position (Diagnostic, loose). eco entry has no driver (catalogued, not instantiated)" - -front-end: - stage: source - enclosure: Aramis-Optics - intro: "The front-end shutters, slit, attenuator, and profile monitor that gate and condition the beam before the Aramis optics." - note: > - The photon shutters fold into the Shutter Family; their permit binding to the PSS is - not in eco (PSS-1). The front-end attenuator is a solid attenuator solving a foil - combination for a requested transmission, energy-dependent (the AttenuatorAramis - driver); the Filter Family covers the discrete selection, and the target-transmission - solve is the deferred Attenuable leg (ATT-1). - devices: - - name: UndulatorShutter - family: Shutter - pv: "SARFE10-OPSH044" - new: true - confirm: true - note: "photon shutter after the undulator; permit binding to the PSS to confirm (PSS-1). eco entry has no driver (catalogued, not instantiated)" - - name: UndulatorSlit - family: Slit - pv: "SARFE10-OAPU044" - new: true - confirm: true - note: "4-blade slit after the undulator; the eco SlitFourBlades driver derives eight blade motors from the prefix" - - name: FrontEndAttenuator - family: Filter - pv: "SARFE10-OATT053" - new: true - confirm: true - note: "solid front-end attenuator; the existing Filter Family covers the discrete foil selection. Target-transmission solving (energy-dependent, the AttenuatorAramis solver) is the deferred Attenuable leg (ATT-1)" - - name: FrontEndScreen - family: Scintillator - pv: "SARFE10-PPRM053" - new: true - confirm: true - note: "profile monitor (Pprm; YAG screen + camera): the screen presents Scintillator, the camera presents Camera (Detector Role)" - - name: FrontEndShutter - family: Shutter - pv: "SARFE10-SBST060" - new: true - confirm: true - note: "photon shutter at the end of the front end; permit binding to the PSS to confirm (PSS-1). eco entry has no driver (catalogued, not instantiated)" - -aramis-optics: - stage: source - enclosure: Aramis-Optics - intro: "The Aramis offset mirrors, double-crystal monochromator, slits, pulse picker, attenuator, KB focusing mirrors, the timing diagnostics, and the profile / intensity monitors that condition and focus the beam onto the Alvra sample." - note: > - The offset mirrors and the KB pair fold into the Mirror Family. The double-crystal - monochromator (ODCM105) folds into Monochromator; Alvra also runs pink / SASE beam - with the mono out (MONO-1). The X-ray pulse picker is a fast single-pulse gate folded - into Shutter (PULSE-1). The PALM and PSEN timing diagnostics measure the X-ray-to-laser - arrival time; they present the Sensor Role (loose Diagnostic) but exist to drift-correct - the fs pump-probe delay, a cross-timing-domain relationship CORA has no model for - (LASER-1). Several eco entries reference SAROP21-* (a sibling Aramis line) inside Alvra - drivers; carried confirm (XREF-1). - devices: - - name: OpticsScreen - family: Scintillator - pv: "SARFE10-PPRM064" - new: true - confirm: true - note: "profile monitor after the front end (Pprm)" - - name: HorizontalMirror1 - family: Mirror - pv: "SAROP11-OOMH064" - new: true - confirm: true - note: "first Alvra horizontal offset mirror; OffsetMirror folds into the Mirror Family. eco entry has no driver (catalogued, not instantiated)" - - name: HorizontalMirror2 - family: Mirror - pv: "SAROP11-OOMH076" - new: true - confirm: true - note: "second Alvra horizontal offset mirror. eco entry has no driver (catalogued, not instantiated)" - - name: SwitchyardSlit - family: Slit - pv: "SAROP11-OAPU104" - new: true - confirm: true - note: "4-blade slit after the photon switchyard, before the Alvra mono; the eco SlitBlades driver derives four blade motors from the prefix" - - name: Monochromator - family: Monochromator - pv: "SAROP11-ODCM105" - new: true - confirm: true - note: "Alvra double-crystal monochromator (the eco Double_Crystal_Mono driver derives the Bragg theta, x-translation, gap, roll, and pitch axes plus an energy setpoint). Alvra also runs pink / SASE beam mono-out (MONO-1). The joint mono + FEL energy device (eco monoFEL) reads cross-system energy PVs (SRC-1, XREF-1)" - - name: VerticalMirror1 - family: Mirror - pv: "SAROP11-OOMV108" - new: true - confirm: true - note: "first Alvra vertical offset mirror. eco entry has no driver (catalogued, not instantiated)" - - name: VerticalMirror2 - family: Mirror - pv: "SAROP11-OOMV109" - new: true - confirm: true - note: "second Alvra vertical offset mirror. eco entry has no driver (catalogued, not instantiated)" - - name: VerticalMirrorScreen - family: Scintillator - pv: "SAROP11-PPRM110" - new: true - confirm: true - note: "profile monitor after the vertical mirrors (Pprm)" - - name: PulsePicker - family: Shutter - pv: "SAROP11-OPPI110" - new: true - confirm: true - note: "X-ray pulse picker; folded into the Shutter Family (a fast single-pulse gate). Whether a rotary pulse-picking chopper is a distinct Family is open (PULSE-1). eco entry has no driver (catalogued, not instantiated)" - - name: OpticsShutter - family: Shutter - pv: "SAROP11-SBST114" - new: true - confirm: true - note: "shutter after the optics hutch; permit binding to confirm (PSS-1). eco entry has no driver (catalogued, not instantiated)" - - name: OpticsIntensityMonitor - family: FluxMonitor - pv: "SAROP11-PBPS117" - new: true - confirm: true - note: "solid-target intensity / position monitor after the optics hutch (PBPS); presents the Sensor Role for flux (FluxMonitor) and position (Diagnostic, loose). Per-shot intensity normalization is a DAQ-plane concern (DAQ-1)" - - name: OpticsScreenEnd - family: Scintillator - pv: "SAROP11-PPRM117" - new: true - confirm: true - note: "profile monitor after the optics hutch (Pprm)" - - name: ArrivalTimeMonitorPALM - family: Diagnostic - pv: "SAROP11-PALM118" - new: true - confirm: true - note: "THz-streaking timing diagnostic (PALM); presents the Sensor Role (loose Diagnostic). It measures the X-ray / optical-laser arrival time to drift-correct the fs pump-probe delay (LASER-1). eco entry has no driver (catalogued, not instantiated)" - - name: ArrivalTimeMonitorPSEN - family: Diagnostic - pv: "SAROP11-PSEN119" - new: true - confirm: true - note: "spectral-encoding timing diagnostic (PSEN); the LCLS-MFX TimeTool analog. Presents the Sensor Role (loose Diagnostic); exists to correct the fs pump-probe delay jitter (LASER-1, DAQ-1). eco entry has no driver (catalogued, not instantiated)" - - name: ExperimentAttenuator - family: Filter - pv: "SAROP11-OATT120" - new: true - confirm: true - note: "solid attenuator for Alvra (AttenuatorAramis); the Filter Family covers the discrete foil selection, the energy-dependent target-transmission solve is the deferred Attenuable leg (ATT-1)" - - name: AttenuatorSlit - family: Slit - pv: "SAROP11-OAPU120" - new: true - confirm: true - note: "position / width slit behind the attenuator (the eco SlitPosWidth driver derives offset and gap virtual axes)" - - name: ReferenceLaser - family: Laser - pv: "SAROP11-OLAS120" - new: true - confirm: true - note: "beamline reference / alignment laser before the KB mirrors (OLAS); binds the catalog Laser Family (alignment, not the pump-probe laser). The eco driver hardcodes an aperture PV on SAROP21-* (XREF-1)" - - name: AttenuatorIntensityMonitor - family: FluxMonitor - pv: "SAROP11-PBPS122" - new: true - confirm: true - note: "intensity / position monitor after the attenuator (PBPS); flux + position Sensor; loose families reused" - - name: AttenuatorScreen - family: Scintillator - pv: "SAROP11-PPRM122" - new: true - confirm: true - note: "profile monitor after the attenuator (Pprm)" - - name: VerticalKBMirror - family: Mirror - pv: "SAROP11-OKBV123" - new: true - confirm: true - note: "Alvra vertical KB focusing mirror (the eco KBver driver derives the three physical-y bender, pitch / roll / yaw, and bend axes plus a curvature setpoint). KB folds into Mirror" - - name: HorizontalKBMirror - family: Mirror - pv: "SAROP11-OKBH124" - new: true - confirm: true - note: "Alvra horizontal KB focusing mirror (the eco KBhor driver derives the same bender / pitch / roll / yaw / bend axes). KB folds into Mirror" - -# --- SAMPLE STAGE: the Alvra Prime endstation --- - -prime-endstation: - stage: sample - enclosure: Alvra - intro: "The Alvra Prime endstation: the sample manipulator, the optical table, the sample-view microscope, the pump-probe laser, and the von Hamos emission spectrometer." - note: > - The Huber sample manipulator and the optical table fold into LinearStage and Table. - The fixed-target / liquid-jet sample delivery for serial crystallography has no - storage-ring analog and is deferred (SAMPLE-1). The pump-probe laser binds the - catalog Laser Family (the LCLS-MFX precedent); its fs laser / X-ray synchronization (the - eco lxt timing chain) is the cross-timing-domain gap CORA cannot express (LASER-1). The - von Hamos spectrometer composes its crystal-translation stage (eco vonHamosBragg) with - the Jungfrau detector and binds the graduated EmissionSpectrometer Family (Alvra is a - fourth sighting after LCLS-MFX, ISS, and the Balder near-sighting; SPEC-1). - devices: - - name: SampleStage - family: LinearStage - pv: "SARES11-XSAM125" - new: true - confirm: true - note: "Huber sample XYZ manipulator (the eco driver derives x / y / z motors). The fixed-target / liquid-jet sample delivery on it is endstation-specific and deferred, no Family coined (SAMPLE-1)" - - name: OpticalTable - family: Table - pv: "SARES11-XOTA125" - new: true - confirm: true - note: "Prime optical table (the eco driver derives six physical motors plus virtual x / y / z / pitch / yaw axes). Reuses the Table Family" - - name: SampleMicroscope - family: Camera - pv: "SARES11-XMI125" - new: true - confirm: true - note: "on-axis sample-view microscope (focus + zoom, with appended SmarAct gonio / rotation axes); presents the Detector Role for sample viewing / alignment, binds Camera (the i13-1 side-camera precedent)" - - name: PumpProbeLaser - family: Laser - pv: {confirm: "SLAAR11-LMOT (experiment laser motors: waveplate, pump delay, compressors); fs timing via the eco lxt chain (LASER-1)"} - new: true - confirm: true - note: "femtosecond optical pump-probe laser; binds the catalog Laser Family (the LCLS-MFX / 4-ID precedent). The delay stages are LinearStages, but the laser / X-ray fs synchronization (the eco lxt timing) is a cross-timing-domain relationship CORA cannot express (LASER-1)" - - name: LaserShutter - family: Shutter - pv: "SLAAR11-LTIM01-EVR0" - new: true - confirm: true - note: "pump-probe laser shutter, driven through a SwissFEL event receiver (EVR). Folds into Shutter; the EVR is the beam-synchronous timing system (TIMING-1)" - - name: EmissionSpectrometer - family: EmissionSpectrometer - pv: "SARES11-XCRY125" - new: true - confirm: true - note: "von Hamos X-ray emission spectrometer (XES / HERFD): a crystal-analyzer dispersive spectrometer composing the analyzer-crystal translation stage (eco vonHamosBragg, two crystal axes) with the Jungfrau detector. Binds the EmissionSpectrometer Family, graduated into the catalog (Alvra is a fourth sighting; whether each analyzer crystal is a child Asset is open, SPEC-1)" - -# --- DETECTION STAGE: the per-shot Jungfrau area detector --- - -detector: - stage: detection - enclosure: Alvra - intro: "The Alvra Jungfrau science detector. It reuses the Camera Family, but its acquisition mode is the headline gap." - note: > - The detector reuses the Camera Family (Detector Role). What does NOT fold is how it is - read: the SwissFEL sf-daq records a free-running stream of per-shot frames tagged by - pulse-ID at beam rate, correlated downstream, not a poll-Acquire-to-Done frame loop. - CORA's acquisition bodies do not represent this; the per-shot event DAQ is the deepest - gap (DAQ-1). eco binds Alvra to a Jungfrau named JF_4.5M (the von Hamos 4.5M, serial - JF02T09V03 inferred via sf_daq_broker); the broker lists further Alvra Jungfrau options - (16M, 4M, 2M TXS, and 0.5M variants), carried confirm (DET-1). - devices: - - name: Detector - family: Camera - pv: {confirm: "Alvra Jungfrau JF_4.5M (von Hamos 4.5M; serial JF02T09V03 inferred); sf-daq-managed, not polled (DET-1, DAQ-1)"} - new: true - confirm: true - note: "the science detector; per-shot frames flow through the sf-daq data plane, which CORA references as a Dataset rather than owns (DAQ-1). Detector model and the further Jungfrau options are to confirm (DET-1)" - -# Cross-cutting timing + the software systems CORA does not model. -controls: - intro: > - Alvra runs the PSI EPICS stack plus the SwissFEL event-driven DAQ. The SwissFEL event - system (EVR receivers) programs the beam-synchronous trigger pattern; the sf-daq, bsread - streaming, and the eco scan / acquisition suite are software / floor. - triggering: - - name: EventTiming - family: TimingController - pv: {confirm: "SwissFEL event system / EVR receivers (e.g. SLAAR11-LTIM01-EVR0); beam-synchronous trigger pattern handles TBD (TIMING-1)"} - new: true - confirm: true - note: "the SwissFEL event-receiver timing that gates acquisition at beam rate. TimingController carries the device, but 'acquire on event-code N at rate R' has no typed parameter home (TIMING-1). The fs laser / X-ray sync (the eco lxt chain) is a further gap (LASER-1)" - software_iocs_not_modeled: - - sf-daq (the per-shot, pulse-ID-tagged event acquisition broker, DAQ-1) - - bsread / mflow (the beam-synchronous ZMQ data streaming transport, DAQ-1) - - the eco / slic acquisition + scan suite (the Python beamline-control layer the descriptor is mined from) - - the SwissFEL data API / databuffer (the per-shot data-analysis plane; CORA references a Dataset, does not own per-shot data) - -# Continuously-available resources a run draws on (modelling exercise). -resources: - intro: > - The continuously-available facility resources a run needs present before it can start. - All pending confirmation. The FEL beam is a shared, switched resource across the Aramis - stations (TOPO-1); its per-shot character is an acquisition concern, not a supply one. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/amx/beamline.yaml b/deployments/amx/beamline.yaml deleted file mode 100644 index 00347681ef1..00000000000 --- a/deployments/amx/beamline.yaml +++ /dev/null @@ -1,243 +0,0 @@ -# AMX beamline descriptor (NSLS-II), reverse-engineered -# -# AMX (Highly Automated Macromolecular Crystallography) is the NSLS-II high-throughput MX -# beamline at sector 17-ID-1, the sibling of FMX (17-ID-2): they share the 17-ID straight -# and the IVU21 undulator. A vertical double-crystal monochromator, tandem-deflection and -# KB focusing mirrors, and a beam-conditioning unit feed a single-omega micro-goniometer; -# an EMBL robot loads cryo-cooled crystals from a 48-position dewar, and an Eiger pixel -# detector reads the rotation data. It is bound to the NSLS-II Site -# (deployments/nsls2/site.yaml), the seventeenth NSLS-II beamline after FXI, HXN, BMM, SRX, -# SIX, CHX, CSX, XPD, ESM, SMI, IXS, SST, ISS, FMX, CMS, XFM, and CORA's third -# macromolecular-crystallography deployment after Diamond i03 and NSLS-II FMX. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open source -# (the NSLS2/amx-profile-collection bluesky / ophyd startup files; the real MX acquisition -# logic lives in the lsdc / mxtools libraries, referenced not modelled) or inferred, -# carried `confirm: true` pending AMX staff. EPICS PVs are real and verified against the -# startup/*.py device classes; the goniometer / robot / detector vendor identities and the -# crystal cut are not in source and are open questions. Same descriptor mode as the other -# NSLS-II beamlines: descriptor + docs, scenarios deferred. -# -# AMX is a PURE-REUSE deployment: it coins NO new Family and graduates nothing. It reuses -# the MX vocabulary i03 / FMX established: the graduated Goniometer (the single-omega -# micro-goniometer), the Camera (the Eiger), the Monochromator (the vertical DCM), the -# Mirror (the tandem-deflection + KB mirrors), the Filter (the BCU attenuator), the -# BeamStop, the EnergyDispersiveSpectrometer (the Mercury fluorescence detector), the -# FluxMonitor (the Keithley), the TimingController (the Zebra), and the graduated -# PositionMonitor Family (DIAG-1). The robotic sample changer is one Positioner-presenting -# Asset (NO new SampleChanger Family), the i03 / 19-BM / FMX precedent (ROBOT-1). The MX -# Methods (mx_data_collection, grid_scan, sample_exchange) stay PENDING: AMX is their THIRD -# consumer (after i03, FMX), which strengthens but does not coin them (Methods coin on a -# conduct-path, not a sighting count; the energy_scan deferral discipline; TECH-1). Unlike -# FMX, AMX has no CRL transfocator and no on-axis backlight in source. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "highly automated macromolecular crystallography (rotation MX on a single-omega goniometer + Eiger, EMBL robot sample exchange), 17-ID-1; FMX's sibling, CORA's 3rd MX; modelled from public beamline config" - name: AMX - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "Sector 17" # PV namespace XF:17ID* (the 17-ID-1 branch) - tier: Unit - parent: null - source: insertion-device - source_confirm: "AMX (17-ID-1) shares its IVU21 in-vacuum undulator (SR:C17-ID:G1{IVU21:1}) and the 17-ID straight with its sibling FMX (17-ID-2, which uses IVU21:2); modelled as one root Unit feeding the 17-ID-1 branch (the FMX / CSX precedent), not two roots. Undulator period and gap range not fully in the profile collection (SRC-1, TOPO-1)." - page_layout: stages - shape: "FMX's high-throughput sibling on the shared 17-ID straight, completing the NSLS-II MX pair: CORA's third MX deployment, pure reuse that coins no new Family." - source_ref: - label: "NSLS2/amx-profile-collection" - url: "https://github.com/NSLS2/amx-profile-collection" -enclosures: - # 17-ID has a shared front-end / optics enclosure (PV zone XF:17IDA, the FOE: the - # high-heat-load slit, the vertical DCM, the tandem-deflection mirrors) and the AMX - # experiment enclosure (PV zone XF:17IDB: the KB mirrors, the goniometer, the robot, the - # Eiger). The zone letters A / B are grounded in the PV prefixes (note AMX's endstation - # is 17IDB, where FMX's is 17IDC); the AMX-shared layout is not fully in source (TOPO-1). - - name: 17-ID-A - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS search-and-secure permit leaf and the shutter PVs are not in the profile collection; the front end is shared with FMX (PSS-1, TOPO-1)"} - - name: 17-ID-B - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; 17-ID-B (PV zone XF:17IDB) is the AMX experiment enclosure carrying the KB mirrors, the goniometer, the robot, and the Eiger (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the shared insertion device and the shutters -# =========================================================================== - -source: - stage: source - enclosure: 17-ID-A - intro: The shared 17-ID insertion device, the front-end and photon shutters, and the high-heat-load slit. - devices: - - name: Undulator - family: InsertionDevice - pv: "SR:C17-ID:G1{IVU21:1}" - confirm: true - note: "IVU21 in-vacuum undulator on the NSLS-II 3 GeV ring (ring current SR:OPS-BI{DCCT:1}I:Real-I), shared with FMX (17-ID-2, IVU21:2) on the 17-ID straight; AMX drives gap index :1. Gap axis SR:C17-ID:G1{IVU21:1-Ax:Gap}-Mtr. Period and range not fully in source (SRC-1, TOPO-1)." - - name: FrontEndShutter - family: Shutter - confirm: "shared FMX / AMX front-end (FOE) photon shutter; PV not in the profile collection (PSS-1)" - note: "Front-end photon shutter (not exposed in the profile collection)." - - name: PhotonShutter - family: Shutter - confirm: "AMX photon shutter into the experiment enclosure; PV not in the profile collection (PSS-1)" - note: "Photon shutter gating the beam into the experiment enclosure (not exposed in the profile collection)." - - name: FrontEndSlit - family: Slit - pv: "FE:C17A-OP{Slt" - confirm: true - note: "Front-end white-beam slit (FE:C17A-OP{Slt:1 / Slt:2 / Slt:12 blades and center / gap) defining the accepted beam, shared with FMX." - - name: HighHeatLoadSlit - family: Slit - pv: "XF:17IDA-OP:AMX{Slt:0" - confirm: true - note: "High-heat-load white-beam slit ahead of the monochromator." - -# =========================================================================== -# OPTICS STAGE: the monochromator, the focusing mirrors, the attenuator -# =========================================================================== - -optics: - stage: source - enclosure: 17-ID-A - intro: "Condition the beam and set its energy: the vertical double-crystal monochromator, the tandem-deflection harmonic-rejection mirrors and the KB focusing pair, the beam-conditioning attenuator, and the slits. PVs verified against the amx-profile-collection startup files." - devices: - - name: Monochromator - family: Monochromator - pv: "XF:17IDA-OP:AMX{Mono:DCM" - confirm: true - note: "Vertical double-crystal monochromator (VDCM; Bragg / gap / pitch / roll / W axes XF:17IDA-OP:AMX{Mono:DCM-Ax:B/G/P/R/W}Mtr and an energy axis XF:17IDA-OP:AMX{Mono:DCM-Ax:E}Mtr). The vertical geometry is the AMX-vs-FMX difference (FMX is horizontal). Reuses the Monochromator family. Crystal cut and energy range pending (DCM-1)." - - name: TandemMirror - family: Mirror - pv: "XF:17IDA-OP:AMX{Mir:TDM" - confirm: true - note: "Tandem-deflection mirror pair (TDM; pitch / roll / X / Y up-and-down-stream axes) for harmonic rejection and steering, AMX's analog of FMX's horizontal focusing mirror. Reuses the Mirror family (KB-1)." - - name: KBMirrors - family: Mirror - pv: "XF:17IDB-OP:AMX{Mir" - enclosure: 17-ID-B - confirm: true - note: "Kirkpatrick-Baez microfocus mirror pair (horizontal KBH with P/R/X/Y axes, vertical KBV with P/X/Y, XF:17IDB-OP:AMX{Mir:KBH / KBV-Ax:...}Mtr) focusing the microbeam at the sample, with a piezo tweaker. Reuses the Mirror family (KB-1)." - - name: BeamConditioningAttenuator - family: Filter - pv: "XF:17IDB-OP:AMX{Attn:BCU" - enclosure: 17-ID-B - confirm: true - note: "Beam-conditioning-unit attenuator (BCU; four insertable absorber foils XF:17IDB-OP:AMX{Attn:BCU-Ax:1-4}Mtr solving a foil combination for a requested transmission XF:17IDB-OP:AMX{Attn:BCU}). Reuses the Filter family; the energy-dependent transmission solver is the deferred Attenuable leg (the LCLS-MFX ATT-1 precedent). Unlike FMX, AMX has no CRL transfocator in source." - - name: ExperimentSlits - family: Slit - pv: "XF:17IDB-OP:AMX{Slt:2" - enclosure: 17-ID-B - confirm: true - note: "Beam-defining slits in the experiment enclosure (XF:17IDB-OP:AMX{Slt:2 / Slt:3 / Slt:4}); a first slit station sits at XF:17IDA-OP:AMX{Slt:1} in the FOE. Reuses the Slit family." - - name: EnergyAxis - family: PseudoAxis - confirm: true - note: "The master energy axis: a pseudopositioner coordinating the undulator gap, the VDCM, and the mirrors from per-energy look-up tables (the set_energy plan). Energy is set for the experiment and scanned for anomalous (SAD / MAD) data collection; the MX technique scope is TECH-1." - -# =========================================================================== -# SAMPLE STAGE: the goniometer, the robot, the sample environment -# =========================================================================== - -sample: - stage: sample - enclosure: 17-ID-B - intro: "The micro-goniometer, the automated sample-changing robot, the on-axis viewing, and the sample cooling. PVs verified against the amx-profile-collection startup files." - note: > - AMX mounts cryo-cooled protein crystals on a single-omega micro-goniometer with x/y/z - centring and PI fine stages, exchanged by an EMBL robot from a 48-position dewar. The - goniometer reuses the graduated Goniometer family; the robot is one Positioner Asset - (not a new Family). Sample cryo-cooling (the cold-gas cryostream) is not exposed in the - profile collection, so it is deferred (CRYO-1). - devices: - - name: Goniometer - family: Goniometer - pv: "XF:17IDB-ES:AMX{Gon:1" - confirm: true - note: "The MX micro-goniometer (single omega rotation XF:17IDB-ES:AMX{Gon:1-Ax:O}Mtr plus GX / GY / GZ sample-centring and PY / PZ pin fine stages). Reuses the Goniometer family (graduated on the i03 Smargon, reused at FMX); per-axis decomposition and centre-of-rotation calibration pending (GONIO-1)." - - name: Robot - pv: "XF:17IDB-ES:AMX{EMBL}:" - confirm: true - note: "Automated sample-changing EMBL robot (XF:17IDB-ES:AMX{EMBL}:) coordinated by the LSDC / mxtools Governor state machine (XF:17IDB-ES:AMX{Gov:...}) with a 48-position dewar and a sample-detection smart magnet. Per the i03 / 19-BM / FMX precedent: one Positioner-presenting Asset loading / unloading a Subject, gated by a Clearance, vendor in a bound Model; NOT a new SampleChanger Family. The exchange workflow and Subject custody lifecycle are deferred (ROBOT-1)." - - name: SampleCamera - family: Camera - pv: "XF:17IDB-ES:AMX{Cam:7}" - confirm: true - note: "On-axis sample-viewing camera (a Prosilica; low-mag XF:17IDB-ES:AMX{Cam:6} and X-eye XF:17IDB-ES:AMX{Cam:9} cameras serve alignment). Reuses the Camera family. AMX exposes no separate on-axis backlight PV (an FMX-vs-AMX difference)." - -# =========================================================================== -# DETECTION STAGE: the Eiger, the fluorescence detector, the beam monitors -# =========================================================================== - -detector: - stage: detection - enclosure: 17-ID-B - intro: "The Eiger area detector, the fluorescence detector for energy / edge selection, the on-axis beamstop, and the beam-position and flux monitors. PVs verified against the amx-profile-collection startup files." - note: > - The Eiger reads the rotation diffraction data; the Mercury multi-element detector reads - fluorescence for energy-edge selection (anomalous MX); both bind catalog Families. The - full detector roster (Eiger model, beam centre, fluorescence ROIs) is DET-1. - devices: - - name: AreaDetector - family: Camera - confirm: "the MX science detector (an Eiger pixel-array detector); its PV is not exposed in the AMX profile collection (DET-1)" - note: "The Eiger area detector reading the rotation diffraction data. Reuses the Camera family (Detector Role). Not exposed in the profile collection, so model and beam centre are pending (DET-1)." - - name: FluorescenceDetector - family: EnergyDispersiveSpectrometer - pv: "XF:17IDB-ES:AMX{Det:Mer}" - confirm: true - note: "Mercury multi-element fluorescence detector (an energy-dispersive multi-channel analyzer reading the XRF spectrum to pick the absorption edge for anomalous data collection). Reuses the EnergyDispersiveSpectrometer family. Element count and ROI map pending (DET-1)." - - name: BeamStop - family: BeamStop - pv: "XF:17IDB-ES:AMX{BS:1" - confirm: true - note: "On-axis motorized beamstop (XF:17IDB-ES:AMX{BS:1-Ax:FX / FY}Mtr) blocking the direct beam ahead of the Eiger. Reuses the BeamStop family." - - name: BeamPositionMonitor - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1) - pv: "XF:17IDA-BI:AMX{BPM:1}" - confirm: true - note: "Beam-position monitors along the beam (XF:17IDA-BI:AMX{BPM:1}, XF:17IDB-BI:AMX{BPM:2 / BPM:3} four-quadrant monitors). Binds the graduated PositionMonitor Family (a consumer alongside the other NSLS-II beamlines; DIAG-1)." - - name: FluxMonitor - family: FluxMonitor - pv: "XF:17IDB-BI:AMX{Keith:1}readFloat" - confirm: true - note: "Keithley picoammeter reading the beam-intensity photocurrent (I0 normalization). Reuses the FluxMonitor family." - -# =========================================================================== -# Cross-cutting controls -# =========================================================================== - -controls: - intro: > - AMX runs the NSLS-II EPICS control stack driven by LSDC (the macromolecular- - crystallography acquisition system) and the mxtools bluesky library. Rotation data - collection is triggered against the Eiger by a Zebra FPGA; the autonomous sample - exchange is coordinated by the Governor state machine. Controller box models / firmware - are not fully in source (DRIVE-1). - motion_controllers: - - name: MotionController - family: MotionController - confirm: "the goniometer / optics motion controllers (a PowerBrick vector controller drives rotation data collection); box model / firmware not reliably in the profile collection (DRIVE-1)" - note: "Drives the goniometer vector and the optics axes. Reuses the MotionController family. The profile's PowerBrick vector PV is misconfigured to the FMX prefix in source, so it is not quoted here (DRIVE-1)." - triggering: - - name: Zebra - family: TimingController - pv: "XF:17IDB-ES:AMX{Zeb:1}:" - confirm: true - note: "Zebra FPGA position-capture and trigger box (a second Zebra sits at XF:17IDB-ES:AMX{Zeb:2}): gates the Eiger against the goniometer for rotation and fast grid scans. Reuses the TimingController family." - software_iocs_not_modeled: - [LSDC, mxtools, EigerIOC, EMBL, Governor, MercuryDXP] - -resources: - intro: Continuously-available resources. Facility-scope supplies live in deployments/nsls2/site.yaml. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum # in-vacuum undulator + optics beam path - - kind: LiquidNitrogen # sample cryo-cooling - - kind: Power - replaceable_parts: - swappable_with_identity: ["sample pucks / pins", "attenuator foils", "KB mirror stripes", "the Eiger detector"] diff --git a/deployments/aps/site.yaml b/deployments/aps/site.yaml index f00cbd159bc..36b3d8b2426 100644 --- a/deployments/aps/site.yaml +++ b/deployments/aps/site.yaml @@ -81,10 +81,11 @@ practices: - {name: 4ID_magnetic_scattering_practice, method: magnetic_scattering, pending: true, note: "resonant magnetic scattering in field and at low temperature; Method not yet in catalog (TECH-1)"} - {name: 4ID_xmcd_practice, method: xmcd, pending: true, note: "X-ray magnetic circular dichroism via the phase retarders; Method not yet in catalog (TECH-1)"} - {name: 4ID_resonant_scattering_practice, method: resonant_scattering, pending: true, note: "energy-resonant scattering across an absorption edge; Method not yet in catalog (TECH-1)"} - # 8-ID XPCS Practices (first cut). Coherent-scattering correlation spectroscopy - # and the 8-ID-E diffraction; Methods not in the imaging-heritage catalog, render - # unlinked, carried pending until a technique enters scope (TECH-1). - - {name: 8ID_xpcs_practice, method: xpcs, note: "X-ray photon correlation spectroscopy; coherent-scattering time series on the area detectors"} + # 8-ID SAXS/diffraction Practices (first cut). The XPCS practice this group + # once carried was backed by 8-ID's own descriptor, which now lives outside + # cora (see xmap/descriptors); removed rather than left claiming hardware + # this repo no longer models. Methods not in the imaging-heritage catalog, + # render unlinked, carried pending until a technique enters scope (TECH-1). - {name: 8ID_saxs_practice, method: small_angle_scattering, pending: true, note: "small-angle scattering on the XPCS detectors; Method not yet in catalog (TECH-1)"} - {name: 8ID_diffraction_practice, method: diffraction, pending: true, note: "six-circle diffraction at 8-ID-E; shares the 4-ID diffraction Method (TECH-1)"} # 9-ID CSSI Practices (first cut). Coherent surface scattering at grazing @@ -92,7 +93,6 @@ practices: # carried pending until a technique enters scope (TECH-1). - {name: 9ID_coherent_surface_scattering_practice, method: coherent_surface_scattering, pending: true, note: "coherent surface scattering at grazing incidence; the CSSI signature; Method not yet in catalog (TECH-1)"} - {name: 9ID_gisaxs_practice, method: grazing_incidence_scattering, pending: true, note: "grazing-incidence small- and wide-angle scattering (GISAXS / GIWAXS); Method not yet in catalog (TECH-1)"} - - {name: 9ID_xpcs_practice, method: xpcs, note: "surface XPCS on the coherent detectors; shares the 8-ID XPCS Method"} - {name: 9ID_waxs_practice, method: wide_angle_scattering, pending: true, note: "wide-angle scattering on the GIWAXS detector; shares the i22 WAXS Method (TECH-1)"} # 12-ID USAXS Practices (first cut). Bonse-Hart crystal-analyzer # ultra-small-angle scattering plus pinhole SAXS and WAXS; Methods not in the diff --git a/deployments/as/site.yaml b/deployments/as/site.yaml deleted file mode 100644 index 91d0f7192c7..00000000000 --- a/deployments/as/site.yaml +++ /dev/null @@ -1,75 +0,0 @@ -# CORA Site descriptor: the Australian Synchrotron site-level surface -# -# The Australian Synchrotron (operated by ANSTO, the Australian Nuclear Science and -# Technology Organisation) is the sixth Site CORA models, and its first Australian -# facility. 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. It is the home of the MX3 macromolecular-crystallography -# beamline. -# -# Status: reverse-engineered. CORA has not been connected to the Australian -# Synchrotron and no staff have confirmed this model. Every value below is read from -# public open source (the AustralianSynchrotron/mx3-beamline-library device library) -# or inferred, and is carried as `pending` until staff confirm it. Do not invent -# facility specifics here; carry them as questions on the MX3 open-questions page. -# -# Source-of-truth boundary (same as the APS / MAX IV / Diamond / NSLS-II / SLAC sites): -# - the closed facility-kind / actor-kind vocabularies are validated against -# code-mirrored frozensets in scripts/site_descriptor.py. -# - the facility records the bootstrap invariants (kind=Site, display_name equals -# code); `heading` carries the human title used on the rendered page. -# -# Controls house-style (the distinctive Site fact): MX3 is EPICS-PV-bound at the -# facility level (literal in-code PVs, the storage ring at SR11*, the beamline at -# MX3*), but it drives three first-class non-EPICS control planes: the MD3 -# microdiffractometer over the MXCuBE Exporter protocol (TCP), the DECTRIS Eiger over -# the SIMPLON REST API, and the ISARA sample robot over a TCP client library. CORA's -# ControlPort spans all four planes; see docs/deployments/mx3/equipment/controls.md. - -facility: - code: as - display_name: as - heading: "Australian Synchrotron" - kind: Site - institution: ANSTO (Australian Nuclear Science and Technology Organisation) - control_plane: "EPICS + MXCuBE Exporter + SIMPLON REST" - beamlines: [MX3] - -# ISA-88 Site Recipes: the facility-adapted form of a catalog Method. All pending -# because they are reverse-engineered from the mx3-beamline-library, not yet confirmed -# with Australian Synchrotron staff. MX3's rotation-MX techniques reuse the same -# pending cross-facility Methods Diamond i03 introduced (mx_data_collection, grid_scan, -# sample_exchange), none yet in the catalog (TECH-1 / ROBOT-1). -practices: - - {name: MX3_mx_data_collection_practice, method: mx_data_collection, pending: true, note: "rotation / oscillation MX data collection on the MD3 microdiffractometer goniometer + the DECTRIS Eiger; reuses the i03 Method, not yet in the catalog (TECH-1)"} - - {name: MX3_grid_scan_practice, method: grid_scan, pending: true, note: "fast grid scan for sample location / centring on the MD3 (TECH-1)"} - - {name: MX3_sample_exchange_practice, method: sample_exchange, pending: true, note: "unattended ISARA robot load / centre / collect / unmount loop; a Procedure over the spine + a Subject custody thread (ROBOT-1)"} - -# Access BC Actors conceptually facility-wide at the Australian Synchrotron. Pending -# until the operator and review structure is confirmed; the device library exposes no -# human roster. -actors: - - {name: Australian Synchrotron beamline staff, kind: human, pending: true, note: "operator and beamline-scientist pool; structure TBD (GOV-1)"} - - {name: Australian Synchrotron safety review, kind: human, pending: true, note: "facility safety review body; membership TBD"} - -# Agent BC Agents seeded at this deployment. None declared: the CORA system agents are -# not yet wired for an Australian Synchrotron deployment. -agents: [] - -# Supply BC: facility-wide continuously-available resources. Pending in this -# reverse-engineered model. LiquidNitrogen is the Cryojet cryostream supply. -supplies: - - {name: Storage-ring beam current, kind: PhotonBeam, pending: true} - - {name: Cooling water, kind: CoolingWater, pending: true} - - {name: Beamline vacuum, kind: Vacuum, pending: true} - - {name: Cryojet liquid nitrogen, kind: LiquidNitrogen, pending: true} - -# Safety BC: facility-issued Clearances. The Australian Synchrotron PSS form names are -# not in the device library (only the PSS photon-shutter enable / status PVs at -# MX3FE01SHT01 / MX3BLSH01SHT01); carried pending rather than guessed. -clearances: - - {name: Australian Synchrotron personal safety system, kind: PSS, pending: true, note: "facility safety-form and permit-leaf names TBD; confirm with staff (PSS-1)"} - -# Caution BC: operator tribal knowledge. Beamline-level cautions reverse-engineered -# for MX3 would live on docs/deployments/mx3/, not here. -cautions: [] diff --git a/deployments/bernina/beamline.yaml b/deployments/bernina/beamline.yaml deleted file mode 100644 index b4198377205..00000000000 --- a/deployments/bernina/beamline.yaml +++ /dev/null @@ -1,408 +0,0 @@ -# CORA Beamline descriptor: Bernina (SwissFEL, PSI), modelling exercise -# -# Bernina is an operating hard-X-ray diffraction / scattering pump-probe station on -# SwissFEL's Aramis branch at PSI, the sibling of the Alvra station. It is bound to -# the PSI Site (deployments/psi/site.yaml). It is CORA's SECOND beamline on a single -# shared source: the Aramis undulator line feeds Alvra, Bernina, and Cristallina one -# at a time, so Bernina is the deployment that turns the deferred shared-switched- -# source seam (TOPO-1) from a hypothetical into a concrete two-Unit-on-one-source case. -# -# STATUS: off-roadmap modelling exercise, NOT a CORA pilot. Reverse-engineered from -# PSI's open `eco` controls library (paulscherrerinstitute/eco, the SwissFEL device -# library). It is treated as a dry, correct DATA source and modelled intentionally, -# not mirrored. -# -# DELIBERATELY PARTIAL FIRST CUT (the i13-1 / i20-1 posture, but for a specific -# reason): Bernina's eco config is PARTIALLY EXTERNALIZED. eco/bernina/config.py's -# entire `components` device list is commented out and loaded at runtime from a NON- -# PUBLIC path (/sf/bernina/config/eco/bernina_config_eco.json), and the live module -# eco/bernina/bernina.py reads a second non-public config object -# (/sf/bernina/config/eco/configuration/bernina_config.json) for which sub-assemblies -# are mounted and which detectors attach to each diffractometer. So what is recoverable -# from PUBLIC source is: the device list with inline PV prefixes (the -# `namespace.append_obj(...)` calls in bernina.py) and the full diffractometer motor- -# axis topology (axes built by literal string suffix in -# eco/endstations/bernina_diffractometers.py). What is NOT recoverable: the -# configuration STATE (which of base/arm/polana/kappa/heavy-load/hexapod/robot sub- -# assemblies are active), the detector-to-diffractometer wiring, and all units/limits. -# Those are carried unknown (CONFIG-1), not invented. -# -# THE HEADLINE: Bernina is materially MORE than the catalog Goniometer (i03/MX3). It is -# a reconfigurable diffraction PLATFORM: a six-circle GPS station (SARES22-GPS) and a -# You-geometry XRD station (SARES21-XRD) with a 2-theta detector arm, a polarization- -# analyzer branch, a kappa goniometer (with on-the-fly kappa<->Eulerian conversion), a -# heavy-load goniometer table, a PI hexapod sample stage, and an optional Staeubli -# TX200 robot contributing gamma/delta. This is EXACTLY the graduated Diffractometer -# ASSEMBLY (4-ID / 8-ID): it COMPOSES a Goniometer (the sample circles + x/y/z), zero- -# or-more RotaryStage detector-arm circles, and a reciprocal-space PseudoAxis. So -# Bernina coins NO new Family: each platform is modelled as a Goniometer Asset + a -# PseudoAxis Asset reusing the catalog Diffractometer Assembly, with the composition -# designed on model.md (DIFF-1). The Assembly is the right home, NOT a new "FEL -# diffractometer" Family. -# -# Family folds (each reviewed; the LCLS-MFX / Alvra precedent): AttenuatorAramis -> -# Filter; SlitBlades/SlitPosWidth/JJSlit/SlitBladesGeneral -> Slit; OffsetMirrorsBernina -# / KBMirrorBernina -> Mirror; DoubleCrystalMono -> Monochromator; XrayPulsePicker -> -# Shutter (PULSE-1); Pprm -> Scintillator + Camera; SolidTargetDetectorPBPS / GasDetector -# -> FluxMonitor + Diagnostic (loose); SpectralEncoder (PSEN timetool) -> Diagnostic -# (loose, the arrival-time monitor, LASER-1); GPS / XRDYou -> Goniometer (composed in the -# Diffractometer Assembly, DIFF-1); HexapodPI / HexapodSymmetrie -> Hexapod; LaserBernina -# -> catalog Laser Family; the Jungfrau -> Camera; the event system / EVRs -> TimingController. -# The Staeubli TX200 robot is a sample/detector handler over PShell (HTTP), not EPICS; -# its modelling is deferred (ROBOT-1, the i03 / MX3 sample-exchange precedent). -# -# Every device carries `new: true` and `confirm: true`. eco carries no units, no motor -# limits, and no Aramis undulator source parameters; those are deferred, not invented. -# eco-specific ambiguities are carried as open questions: a live Bernina entry uses an -# Alvra-line PV (SAROP11-PPRM066) (XREF-1); the eco / sf_daq_broker Jungfrau version -# strings differ (JF07T32V01 vs V02) (DET-1). -# -# DEFERRED (out of scope, noted not modelled): the externalized config state (CONFIG-1); -# the sf-daq data plane (DAQ-1); the fs pump-probe laser delay + lxt timing (the laser -# binds the catalog Laser Family; its fs sync has no CORA model, LASER-1); the Staeubli robot -# (ROBOT-1); the sibling Aramis stations Alvra / Cristallina sharing the source (TOPO-1); -# the RIXS / tape-drive / liquid-jet sample-environment variants whose appends are -# commented out in eco (ENV-1). - -beamline: - maturity: model - evidence: controls_config - coverage: partial - summary: "hard X-ray femtosecond pump-probe diffraction / scattering on two reconfigurable diffractometers (GPS six-circle, XRD You-geometry); the second co-equal station on the shared Aramis source, makes the shared-switched-source seam concrete, reuses the graduated Diffractometer Assembly; a deliberately partial first cut (`eco`), the live device config is externalized" - name: Bernina - facility: psi - tier: Unit - parent: null - source: free-electron-laser - source_confirm: > - SASE hard-X-ray FEL on the shared SwissFEL Aramis undulator line; photon energy is - set per-shot and the same source feeds the Alvra, Bernina, and Cristallina stations - one at a time (SRC-1 / TOPO-1). The Aramis undulator parameters are not in the eco - manifest and are carried confirm. - page_layout: stages - shape: "A hard X-ray XFEL diffractometer platform sharing the Aramis source with Alvra and Cristallina; the first deployment to make the switched-shared-source seam concrete as a second co-equal station." - source_ref: - label: "paulscherrerinstitute/eco" - url: "https://github.com/paulscherrerinstitute/eco" - -# Two access-gated zones. The Aramis optics hutch (the SAROP21 line) conditions the beam -# shared with the other Aramis stations; the Bernina experiment hutch holds the GPS and -# XRD diffractometers. The eco manifest records PV prefixes but not which access-gated -# hutch a device is in or its safety meaning (ENC-1). SwissFEL PPS permit + the pump-probe -# laser interlock are carried confirm (PSS-1, LASER-1). -enclosures: - - name: Aramis-Optics-SAROP21 - role: optics-hutch - facility_code: psi - permit_signal: {confirm: "SwissFEL PPS search-and-secure signal TBD; the SAROP21 Aramis optics serve Bernina (TOPO-1, PSS-1)"} - - name: Bernina - role: experiment-hutch - facility_code: psi - permit_signal: {confirm: "SwissFEL PPS + pump-probe laser interlock TBD (PSS-1, LASER-1)"} - -# --- SOURCE STAGE: the FEL source, shared front end, and SAROP21 Aramis optics --- - -undulator-source: - stage: source - enclosure: Aramis-Optics-SAROP21 - intro: "The SwissFEL Aramis free-electron-laser source and its front-end pulse-intensity monitors." - note: > - SwissFEL is a linac-driven FEL, not a storage ring; machine beam is carried as a - PhotonBeam Supply (MACHINE-1). The Aramis undulator photon energy is set per shot; - CORA has no per-shot energy setpoint, and the undulator-as-driven-source is deferred - (SRC-1). The undulator parameters are absent from the eco manifest (SRC-1). - devices: - - name: Undulator - family: InsertionDevice - pv: {confirm: "SwissFEL Aramis undulator line; per-segment handles not in eco (SRC-1)"} - new: true - confirm: true - note: "the FEL source; SASE mode and per-shot photon energy are a DAQ-plane datum, not a standing setpoint (SRC-1, DAQ-1)" - - name: GasMonitor - family: FluxMonitor - pv: {confirm: "SwissFEL Aramis gas detector (eco mon_und_gas; no PV passed inline)"} - new: true - confirm: true - note: "gas intensity monitor; FEL pulse-energy diagnostic, presents the Sensor Role; loose family reused. Per-shot pulse energy is correlated in the DAQ by pulse-ID (DAQ-1)" - - name: FrontEndIntensityMonitor - family: FluxMonitor - pv: "SARFE10-PBPS053" - new: true - confirm: true - note: "solid-target intensity / position monitor after the undulator (PBPS); presents the Sensor Role for flux (FluxMonitor) and position (Diagnostic, loose)" - -front-end: - stage: source - enclosure: Aramis-Optics-SAROP21 - intro: "The front-end and safety shutters, the undulator slit, and the front-end attenuator that gate and condition the beam before the SAROP21 optics." - note: > - The photon and safety shutters fold into the Shutter Family; their permit binding to - the PSS is not in eco (PSS-1). The front-end attenuator is a solid attenuator solving - an energy-dependent foil combination (AttenuatorAramis); the Filter Family covers the - discrete selection, the solve is the deferred Attenuable leg (ATT-1). - devices: - - name: UndulatorShutter - family: Shutter - pv: "SARFE10-OPSH044" - new: true - confirm: true - note: "photon shutter after the undulator (eco pshut_und); permit binding to confirm (PSS-1)" - - name: FrontEndShutter - family: Shutter - pv: "SARFE10-OPSH059" - new: true - confirm: true - note: "photon shutter at the front-end exit (eco pshut_fe); permit binding to confirm (PSS-1)" - - name: FrontEndAttenuator - family: Filter - pv: "SARFE10-OATT053" - new: true - confirm: true - note: "solid front-end attenuator (AttenuatorAramis); the Filter Family covers the discrete selection, the energy-dependent target-transmission solve is the deferred Attenuable leg (ATT-1)" - - name: UndulatorSlit - family: Slit - pv: {confirm: "SwissFEL front-end JJ slit (eco slit_und, JJSlitUnd; no PV passed inline)"} - new: true - confirm: true - note: "front-end JJ slit; the eco driver derives the blade motors" - -aramis-optics: - stage: source - enclosure: Aramis-Optics-SAROP21 - intro: "The SAROP21 Aramis optics: the offset mirrors, the double-crystal monochromator, the switchyard and mono slits, the X-ray pulse picker, the attenuator, the KB focusing mirrors, the PSEN timing diagnostic, and the profile / intensity monitors that condition and focus the beam onto the Bernina sample." - note: > - The offset mirrors and the KB pair fold into Mirror. The double-crystal monochromator - (ODCM098) folds into Monochromator; Bernina also runs pink / SASE beam with the mono - out (MONO-1). The X-ray pulse picker is a fast single-pulse gate folded into Shutter - (PULSE-1). The PSEN spectral-encoder measures the X-ray-to-laser arrival time; it - presents the Sensor Role (loose Diagnostic) but exists to drift-correct the fs pump- - probe delay (LASER-1). One live Bernina profile monitor (prof_mirr_alv1) carries an - Alvra-line PV (SAROP11-PPRM066); carried confirm (XREF-1). - devices: - - name: OffsetMirrors - family: Mirror - pv: {confirm: "SAROP21 Bernina offset mirror pair (eco offset, OffsetMirrorsBernina; no base PV passed inline)"} - new: true - confirm: true - note: "the Bernina horizontal offset mirror pair; OffsetMirror folds into the Mirror Family" - - name: Monochromator - family: Monochromator - pv: "SAROP21-ODCM098" - new: true - confirm: true - note: "Bernina double-crystal monochromator (eco DoubleCrystalMono); Bragg / translation / gap axes derived in the driver. Bernina also runs pink / SASE beam mono-out (MONO-1)" - - name: SwitchyardSlit - family: Slit - pv: "SAROP21-OAPU092" - new: true - confirm: true - note: "4-blade slit on the SAROP21 line (eco slit_switch, SlitBlades); blade motors derived" - - name: MonoSlit - family: Slit - pv: "SAROP21-OAPU102" - new: true - confirm: true - note: "4-blade slit after the mono (eco slit_mono, SlitBlades)" - - name: PulsePicker - family: Shutter - pv: "SAROP21-OPPI113" - new: true - confirm: true - note: "X-ray pulse picker (eco xp, XrayPulsePicker, EVR-based); folded into the Shutter Family (a fast single-pulse gate). Shutter-vs-Chopper open (PULSE-1)" - - name: Attenuator - family: Filter - pv: "SAROP21-OATT135" - new: true - confirm: true - note: "solid attenuator for Bernina (eco att, AttenuatorAramis); Filter covers the discrete selection, the energy-dependent solve is the deferred Attenuable leg (ATT-1)" - - name: AttenuatorSlit - family: Slit - pv: "SAROP21-OAPU138" - new: true - confirm: true - note: "position / width slit behind the attenuator (eco slit_att, SlitPosWidth)" - - name: MonoIntensityMonitor - family: FluxMonitor - pv: "SAROP21-PBPS103" - new: true - confirm: true - note: "solid-target intensity / position monitor after the mono (eco mon_mono, PBPS); flux + position Sensor (DIAG-1)" - - name: OpticsIntensityMonitor - family: FluxMonitor - pv: "SAROP21-PBPS133" - new: true - confirm: true - note: "solid-target intensity / position monitor after the optics (eco mon_opt, PBPS); flux + position Sensor (DIAG-1)" - - name: MonoScreen - family: Scintillator - pv: "SAROP21-PPRM113" - new: true - confirm: true - note: "profile monitor after the mono (eco prof_mono, Pprm)" - - name: OpticsScreen - family: Scintillator - pv: "SAROP21-PPRM133" - new: true - confirm: true - note: "profile monitor after the optics (eco prof_opt, Pprm)" - - name: AttenuatorScreen - family: Scintillator - pv: "SAROP21-PPRM138" - new: true - confirm: true - note: "profile monitor after the attenuator (eco prof_att, Pprm)" - - name: ArrivalTimeMonitorPSEN - family: Diagnostic - pv: "SAROP21-PSEN135" - new: true - confirm: true - note: "spectral-encoding arrival-time monitor (eco tt_opt, SpectralEncoder; the Alvra PSEN / LCLS-MFX TimeTool analog). Presents the Sensor Role (loose Diagnostic); exists to correct the fs pump-probe delay jitter (LASER-1, DAQ-1)" - - name: ReferenceLaser - family: Laser - pv: "SAROP21-OLAS134" - new: true - confirm: true - note: "beamline reference / alignment laser (eco reflaser_beamline, RefLaser_Aramis); binds the catalog Laser Family (alignment, not the pump-probe laser)" - - name: VerticalKBMirror - family: Mirror - pv: "SAROP21-OKBV139" - new: true - confirm: true - note: "Bernina vertical KB focusing mirror (eco kb, KBMirrorBernina); KB folds into Mirror" - - name: HorizontalKBMirror - family: Mirror - pv: "SAROP21-OKBH140" - new: true - confirm: true - note: "Bernina horizontal KB focusing mirror (eco kb, KBMirrorBernina); KB folds into Mirror" - -# --- SAMPLE STAGE: the Bernina diffraction endstation (the GPS and XRD platforms) --- - -bernina-endstation: - stage: sample - enclosure: Bernina - intro: "The Bernina diffraction endstation: the GPS six-circle diffractometer, the XRD You-geometry diffractometer, the downstream-diagnostic table, the pump-probe laser, and the sample-view cameras." - note: > - The defining endstation. GPS (SARES22-GPS, a six-circle station) and XRD (SARES21-XRD, - a You-geometry station with a kappa goniometer, a 2-theta detector arm, a polarization- - analyzer branch, a heavy-load goniometer table, and a PI hexapod) are both reconfigurable - diffraction PLATFORMS. Each reuses the graduated Diffractometer ASSEMBLY (4-ID / 8-ID): - it COMPOSES a Goniometer (the sample circles + x/y/z, one Asset), zero-or-more RotaryStage - detector-arm circles, and a reciprocal-space PseudoAxis. So each platform is modelled here - as a Goniometer Asset + a PseudoAxis Asset, with the Assembly composition designed on - model.md (DIFF-1); NO new Family is coined. WHICH sub-assemblies (base/arm/polana/kappa/ - heavy-load/hexapod/robot) are actually mounted is read from the non-public bernina_config - JSON and is carried unknown (CONFIG-1). The Staeubli TX200 robot (over PShell HTTP, not - EPICS) handling samples / the detector is deferred (ROBOT-1). The fs pump-probe laser - binds the catalog Laser Family; its fs sync (the eco lxt chain) is the cross-timing- - domain gap (LASER-1). - devices: - - name: GPS_Goniometer - family: Goniometer - pv: "SARES22-GPS" - new: true - confirm: true - note: "the GPS six-circle diffractometer's sample-orientation goniometer (eco gps, GPS; recspace SixCircleBernina). The sample-orientation circles + x/y/z bind the Goniometer Family; the full platform is the Diffractometer Assembly (DIFF-1)" - - name: GPS_ReciprocalSpace - family: PseudoAxis - pv: {confirm: "GPS reciprocal-space pseudo-axis (eco SixCircleBernina recspace conversion); the partition rule is DIFF-2"} - new: true - confirm: true - note: "the GPS six-circle reciprocal-space (hkl) pseudo-axis layer; the reciprocal_space slot of the Diffractometer Assembly (DIFF-1, DIFF-2)" - - name: XRD_Goniometer - family: Goniometer - pv: "SARES21-XRD" - new: true - confirm: true - note: "the XRD You-geometry diffractometer's sample-orientation goniometer (eco xrd, XRDYou). Recoverable axes: base (gamma/mu + translations/tilts), arm (delta/tdet), polana (pol/pthe/ptth), kappa (with kappa<->Eulerian conversion), heavy-load table, PI hexapod; WHICH are mounted is external (CONFIG-1). Binds the Goniometer Family; the platform is the Diffractometer Assembly (DIFF-1)" - - name: XRD_DetectorArm - family: RotaryStage - pv: {confirm: "XRD 2-theta detector arm (eco xrd delta = SARES21-XRD:MOT_DT_RX2TH); the detector_arm slot of the Diffractometer Assembly (DIFF-1)"} - new: true - confirm: true - note: "the XRD detector-arm 2-theta circle (delta); the ZeroOrMore detector_arm slot of the Diffractometer Assembly (DIFF-1). Axis suffix recoverable, mount state external (CONFIG-1)" - - name: XRD_ReciprocalSpace - family: PseudoAxis - pv: {confirm: "XRD reciprocal-space pseudo-axis (eco diffcalc, Crystals recspace; kappa<->You conversion); the partition rule is DIFF-2"} - new: true - confirm: true - note: "the XRD reciprocal-space (hkl) pseudo-axis layer (eco diffcalc); the reciprocal_space slot of the Diffractometer Assembly (DIFF-1, DIFF-2)" - - name: USDTable - family: Hexapod - pv: {confirm: "upstream-diagnostic / sample hexapod table (eco usd_table, HexapodSymmetrie; 6-axis)"} - new: true - confirm: true - note: "the upstream sample / diagnostic hexapod table; folds into the Hexapod Family" - - name: SampleCamera - family: Camera - pv: "SARES20-CAMS142-C1" - new: true - confirm: true - note: "below-sample view microscope (eco samplecam_below, MicroscopeMotorRecord; zoom on SARES20-MF1:MOT_14); presents the Detector Role for sample viewing / alignment, binds Camera" - - name: PumpProbeLaser - family: Laser - pv: "SLAAR21-LMOT" - new: true - confirm: true - note: "femtosecond optical pump-probe laser (eco las, LaserBernina); binds the catalog Laser Family (the Alvra / LCLS-MFX precedent). The laser / X-ray fs synchronization (the eco lxt chain) is the cross-timing-domain gap (LASER-1)" - - name: LaserShutter - family: Shutter - pv: "SLAAR21-LTIM01-EVR0" - new: true - confirm: true - note: "pump-probe laser shutter (eco laser_shutter), driven through a SwissFEL event receiver (EVR). Folds into Shutter; the EVR is the beam-synchronous timing system (TIMING-1)" - -# --- DETECTION STAGE: the per-shot Jungfrau area detector --- - -detector: - stage: detection - enclosure: Bernina - intro: "The Bernina Jungfrau science detectors. They reuse the Camera Family, but their acquisition mode is the headline gap." - note: > - The detectors reuse the Camera Family (Detector Role). What does NOT fold is how they - are read: the SwissFEL sf-daq records a free-running stream of per-shot frames tagged by - pulse-ID at beam rate, not a poll-Acquire-to-Done loop (DAQ-1). eco wires a 1.5M Jungfrau - (JF01T03V01) inline; sf_daq_broker lists Bernina's main 16M (JF07T32V02) plus I0 / vacuum - / fluorescence / RIXS 0.5M variants. WHICH detector attaches to which diffractometer is - read from the non-public config (CONFIG-1); the eco / broker version strings differ for - the 16M (V01 vs V02), carried confirm (DET-1). - devices: - - name: AreaDetector - family: Camera - pv: {confirm: "Bernina 16M Jungfrau (sf_daq_broker JF07T32V02; eco wires the 1.5M JF01T03V01 inline). sf-daq-managed, not polled (DET-1, DAQ-1, CONFIG-1)"} - new: true - confirm: true - note: "the science detector; per-shot frames flow through the sf-daq data plane, which CORA references as a Dataset rather than owns (DAQ-1). The detector-to-diffractometer wiring is external (CONFIG-1); the eco / broker version mismatch is carried confirm (DET-1)" - -# Cross-cutting timing + the software systems CORA does not model. -controls: - intro: > - Bernina runs the PSI EPICS stack plus the SwissFEL event-driven DAQ. The SwissFEL event - system (the master timing, the CTA sequencer, and EVR receivers) programs the beam- - synchronous trigger pattern; the sf-daq, bsread streaming, and the eco scan / acquisition - suite are software / floor. The live device list and the diffractometer configuration are - loaded at runtime from non-public PSI config files (CONFIG-1). - triggering: - - name: EventTiming - family: TimingController - pv: {confirm: "SwissFEL event system (eco event_system: master SIN-TIMAST-TMA, pulse-id SARES20-CVME-01-EVR0:RX-PULSEID, CTA sequencer SAR-CCTA-ESB) and per-hutch EVRs; trigger-pattern handles TBD (TIMING-1)"} - new: true - confirm: true - note: "the SwissFEL event-receiver / sequencer timing that gates acquisition at beam rate. TimingController carries the device, but 'acquire on event-code N at rate R' has no typed parameter home (TIMING-1). The fs laser / X-ray sync (the eco lxt chain) is a further gap (LASER-1)" - software_iocs_not_modeled: - - sf-daq (the per-shot, pulse-ID-tagged event acquisition broker, DAQ-1) - - bsread / mflow (the beam-synchronous ZMQ data streaming transport, DAQ-1) - - the eco / slic acquisition + scan suite (the Python beamline-control layer the descriptor is mined from) - - the non-public bernina_config JSON (the device list + diffractometer mount state + detector wiring, CONFIG-1) - - the Staeubli TX200 sample / detector robot over PShell HTTP (ROBOT-1) - -# Continuously-available resources a run draws on (modelling exercise). -resources: - intro: > - The continuously-available facility resources a run needs present before it can start. - All pending confirmation. The FEL beam is a shared, switched resource across the Aramis - stations (TOPO-1); its per-shot character is an acquisition concern, not a supply one. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/bmm/beamline.yaml b/deployments/bmm/beamline.yaml deleted file mode 100644 index de6c911061c..00000000000 --- a/deployments/bmm/beamline.yaml +++ /dev/null @@ -1,229 +0,0 @@ -# BMM beamline descriptor (NSLS-II), reverse-engineered -# -# BMM (Beamline for Materials Measurement) is the NSLS-II X-ray absorption -# spectroscopy beamline at sector 6-BM (a bending-magnet source). It does -# transmission and fluorescence XAS / EXAFS: the experiment IS an energy scan -# across an absorption edge, recording the incident, transmitted, and reference -# ion-chamber currents (and the fluorescence spectrum) at each energy point. It is -# bound to the NSLS-II Site (deployments/nsls2/site.yaml), the third NSLS-II -# beamline after FXI and HXN. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the bluesky profile collection NSLS2/bmm-profile-collection) or inferred, -# carried `new: true` + `confirm: true` pending BMM staff. EPICS PVs are real and -# verified against the profile collection; vendor part numbers, serials, and -# physical positions are not in it and are open questions. Same descriptor mode as -# FXI / HXN; this scaffold is descriptor + docs, scenarios deferred. -# -# BMM's defining new shape is ENERGY-SCAN-AS-THE-MEASUREMENT: every prior CORA -# deployment measures by scanning position (raster, rotation) or imaging at a fixed -# energy; BMM sweeps the monochromator energy across an edge and the per-energy -# detector readings ARE the data. This is the first real consumer of the -# energy_scan Capability the catalog already anticipates ("pending in code", noted -# beside cora.capability.energy_change). Per the design-phase discipline (Diamond / -# 32-ID / HXN coined no Capability at scaffold time), energy_scan is NOT coined -# here; it is the live earn-the-abstraction question (see techniques.md, ENERGY-1). -# -# No new family is introduced: every device reuses an existing catalog Family (the -# ion chambers reuse FluxMonitor, graduated in #353; the fluorescence detector the -# catalog EnergyDispersiveSpectrometer) or another catalog family already carried -# by a sibling deployment (the diagnostic screens bind the catalog Screen Family). - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "X-ray absorption spectroscopy (transmission + fluorescence XAS/EXAFS), 6-BM; modelled from public beamline config" - name: BMM - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "Sector 6" # PV namespace XF:06BM* - tier: Unit - parent: null - source: bending-magnet - source_confirm: "6-BM bending-magnet source (BMPS/IDPS on SR:C06-EPS); not an insertion device (SRC-1)" - page_layout: stages - shape: "Measures by scanning energy, not position: it sweeps the monochromator across an absorption edge, recording the ion-chamber currents per point; CORA's first spectroscopy beamline." - source_ref: - label: "NSLS2/bmm-profile-collection" - url: "https://github.com/NSLS2/bmm-profile-collection" -enclosures: - # 6-BM-A optics + the endstation. PV zones XF:06BMA (optics) and XF:06BM-ES - # (endstation); the photon shutter is XF:06BM-PPS{Sh:A}. - - name: 6-BM-A - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS search-and-secure permit leaf not in source; the front-end and photon shutters are XF:06BM-PPS{Sh:FE} and {Sh:A} (PSS-1)"} - - name: 6-BM-B - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; endstation hutch boundary to confirm (ENC-1)"} - -# =========================================================================== -# SOURCE STAGE: the bending-magnet source, mirrors, monochromator, slits, filters -# =========================================================================== - -source: - stage: source - enclosure: 6-BM-A - intro: The bending-magnet source and the front-end / photon shutters. - devices: - - name: Source - family: Beam - new: true - confirm: true - note: "6-BM bending-magnet source, recorded as a PhotonBeam Supply, not an Asset (the 2-BM precedent). Beam-parameter machine state is on SR:C06." - - name: FrontEndShutter - family: Shutter - pv: "XF:06BM-PPS{Sh:FE}" - confirm: true - note: "Front-end safety shutter (sha); PPS-gated." - - name: PhotonShutter - family: Shutter - pv: "XF:06BM-PPS{Sh:A}" - confirm: true - note: "Photon shutter into the optics (shb); PPS permit leaf pending (PSS-1)." - -optics: - stage: source - enclosure: 6-BM-A - intro: "Condition the beam and set its energy: two mirrors, the double-crystal monochromator, the beam-defining slits, and the attenuating filters. PVs verified against startup/BMM/user_ns/instruments.py and dcm.py." - devices: - - name: CollimatingMirror - family: Mirror - pv: "XF:06BM-OP{Mir:M1" - confirm: true - note: "First mirror M1 (class Mirrors, 556 mm), collimating; bend/translation axes (YU/YDO/YDI/XU/XD)." - - name: Monochromator - family: Monochromator - pv: "XF:06BMA-OP{Mono:DCM1" - axis_channels: { Bragg: "XF:06BMA-OP{Mono:DCM1-Ax:Bragg}Mtr" } - crystal_cut: "Si(111)" - confirm: true - note: "Double-crystal monochromator (class DCM, instance dcm, Si(111)). The Bragg angle is the energy actuator; the EnergyAxis below is the master energy. A second crystal set may be available (DCM-1)." - - name: FocusingMirror - family: Mirror - pv: "XF:06BMA-OP{Mir:M2" - confirm: true - note: "Second mirror M2 (class Mirrors, 1288 mm), focusing and harmonic-rejection; bend/translation axes." - - name: ConditioningSlit - family: Slit - pv: "XF:06BMA-OP{Slt:01" - confirm: true - note: "Optics-hutch beam-defining slit (slits2, class StandardSlits): outboard/inboard/top/bottom blades." - - name: SampleSlit - family: Slit - pv: "XF:06BM-BI{Slt:02" - confirm: true - note: "Endstation entrance slit (slits3): O/I/T/B blades defining the beam onto the sample." - - name: Filter - family: Filter - pv: "XF:06BMA-BI{Fltr:01" - confirm: true - note: "Attenuating filter paddles (dm1_filters, Y1/Y2) in the first diagnostic module." - - name: EnergyAxis - family: PseudoAxis - confirm: true - note: "The master energy axis: driving it sets the monochromator Bragg angle. An XAS measurement SWEEPS this axis across an absorption edge; that sweep is the energy_scan Capability the catalog anticipates but does not yet coin (ENERGY-1)." - - name: DiagnosticScreen - family: Screen - pv: "XF:06BMA-BI{Diag:02" - new: true - confirm: true - note: "Fluorescent diagnostic screens (dm2_fs, dm3_fs) for beam viewing; binds the catalog Screen Family (the 2-BM FLAG precedent)." - - name: BeamPositionMonitor - family: GenericProbe - pv: "XF:06BM-BI{BPM:1" - confirm: true - note: "Beam-position monitor and beam-current transmitter (dm3_bpm, dm3_bct) in the diagnostic module; read-only." - -# =========================================================================== -# SAMPLE STAGE: the XAFS sample table, the sample wheel, and the reference holder -# =========================================================================== - -sample: - stage: sample - enclosure: 6-BM-B - intro: "The endstation XAFS stages: the sample positioning table, the rotating sample wheel for batch scans, and the reference-foil holder. PVs verified against startup/BMM/user_ns/motors.py." - note: > - BMM runs batch XAS: many samples mounted on a rotating wheel, each indexed into - the beam and scanned in turn. The wheel reuses the RotaryStage family (the - sample-changer behaviour is an automation / Method concern, not a new device - kind); whether a dedicated sample-changer Family is earned across BMM and the - Diamond robots is an open question (WHEEL-1). - devices: - - name: SampleStage - family: LinearStage - pv: "XF:06BM-ES{MC:09" - axis_channels: { x: "XF:06BM-ES{MC:09-Ax:6}Mtr", y: "XF:06BM-ES{MC:09-Ax:7}Mtr" } - confirm: true - note: "Sample positioning table (xafs_x, xafs_y), with pitch/roll (xafs_pitch, xafs_roll) on the XAFS table; encoded." - - name: SampleWheel - family: RotaryStage - pv: "XF:06BMA-BI{XAFS-Ax:RotB}Mtr" - confirm: true - note: "Rotating sample wheel (xafs_wheel, xafs_rotb) indexing many samples through the beam for batch XAS; a second rotation (xafs_rots) carries a reference wheel. Sample-changer role noted (WHEEL-1)." - - name: ReferenceHolder - family: LinearStage - pv: "XF:06BMA-BI{XAFS-Ax:RefX}Mtr" - confirm: true - note: "Reference-foil holder (xafs_refx, xafs_refy) positioning a standard foil for per-scan energy calibration (the reference channel Ir is measured through it)." - -# =========================================================================== -# DETECTION STAGE: the ion chambers (transmission XAS) and the fluorescence detector -# =========================================================================== - -detector: - stage: detection - enclosure: 6-BM-B - intro: "The XAS detectors read at each energy point: the ion chambers for transmission (I0, It, Iref) and the energy-dispersive detector for fluorescence. PVs verified against startup/BMM/user_ns/detectors.py." - note: > - For a transmission XAS scan the absorption is ln(I0 / It) versus energy; for a - dilute sample the fluorescence yield from the EnergyDispersiveSpectrometer is - used instead. The ion chambers are the primary signal here, not auxiliary flux - monitors, but they are the same device kind as the FluxMonitor Family (graduated - in #353 from the i22 / i03 / i15-1 ion chambers), which BMM reuses. - devices: - - name: IonChambers - family: FluxMonitor - pv: "XF:06BM-BI{EM:1}EM180:" - confirm: true - note: "Quad electrometer (quadem1, class BMMQuadEM) reading the I0 (incident), It (transmitted), and Ir (reference) ion chambers, the transmission-XAS signal. Reuses the catalog FluxMonitor Family (graduated #353); at BMM these are the primary measurement detector, not an auxiliary monitor (DIAG-1 covers the gas fill)." - - name: FluorescenceSpectrometer - family: EnergyDispersiveSpectrometer - pv: "XF:06BM-ES" - confirm: true - note: "Xspress3 energy-dispersive fluorescence detector (1-, 4-, and 7-element configurations in source) for fluorescence-yield XAS of dilute samples; presents the Sensor Role. Element count / vendor pending (DET-1)." - - name: ScalerCounter - family: GenericProbe - pv: "XF:06BM-ES:1{Sclr:1}" - confirm: true - note: "Scaler-counted scintillation / point detector (bicron, class GonioStruck) for alignment and auxiliary counting; read-only." - -# =========================================================================== -# Cross-cutting controls -# =========================================================================== - -controls: - intro: > - BMM is a step/continuous XAS beamline: the conducting engine sweeps the - monochromator energy and reads the detectors per point. The motion-controller - boxes (model, firmware, IP) are not in the profile collection (DRIVE-1). - motion_controllers: - - name: EndstationMotionController - family: MotionController - pv: "XF:06BM-ES{MC:09" - confirm: true - note: "Endstation motion controller (MC:09) driving the XAFS sample table; box model/firmware pending (DRIVE-1)." - software_iocs_not_modeled: - [Xspress3, QuadEM, Struck] - -resources: - intro: Continuously-available resources. Facility-scope supplies live in deployments/nsls2/site.yaml. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: LiquidNitrogen # DCM crystal cooling - - kind: Power - replaceable_parts: - swappable_with_identity: ["reference foils", "DCM crystal sets", "fluorescence detector elements"] diff --git a/deployments/cdi/beamline.yaml b/deployments/cdi/beamline.yaml deleted file mode 100644 index 42bf4aaa1fa..00000000000 --- a/deployments/cdi/beamline.yaml +++ /dev/null @@ -1,269 +0,0 @@ -# CDI beamline descriptor (NSLS-II), reverse-engineered -# -# CDI (Coherent Diffraction Imaging) is the NSLS-II coherent-imaging beamline at -# sector 9-ID. Its defining techniques are coherent diffractive imaging: forward -# (plane-wave) CDI, ptychography, and Bragg CDI, all formed by focusing a coherent -# beam to a small spot with a Kirkpatrick-Baez (KB) mirror pair and recording the -# far-field diffraction pattern on a photon-counting area detector (Eiger2, Merlin). -# The real-space image is recovered offline by phase retrieval. It is bound to the -# NSLS-II Site (deployments/nsls2/site.yaml). -# -# NAME GUARD: this is NSLS-II 9-ID. CORA also models APS 9-ID (the CSSI surface- -# scattering instrument, deployments/9-id), a different beamline at a different -# facility with a different PV namespace. CDI lives at XF:09ID* / SR:C09-ID*. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the bluesky profile collection NSLS2/cdi-profile-collection and the -# device library NSLS2/cditools) or inferred, carried `confirm: true` pending CDI -# staff. EPICS PVs are real and verified against the startup scripts and the -# cditools device classes; vendor part numbers, serials, and physical positions -# are not in them and are open questions. Same descriptor mode as CHX / HXN; this -# scaffold is descriptor + docs, scenarios deferred. -# -# CDI is a COHERENT-IMAGING reinforcement: it reuses the coherent-detector shape -# CHX brought (a photon-counting area detector recording a coherent pattern) and -# the deferred ptychography HXN brought (the reconstruction is ComputePort work, -# not a beamline Method), at a beamline dedicated to phase-retrieval imaging. It -# introduces NO new catalog family: the area detectors reuse Camera (the Eiger-to- -# Camera precedent), the KB nanofocus pair and the pre-mirrors reuse Mirror (the -# FMX / SRX KB precedent), the two monochromators reuse Monochromator (the CHX -# Si-DCM-plus-multilayer-DMM precedent), the goniometer reuses Goniometer, the -# foil intensity monitor reuses FluxMonitor, the slits Slit, the attenuator foils -# Filter, the undulator InsertionDevice, the master energy a PseudoAxis, the -# diagnostic cameras Camera. The quadrant and diamond beam-position monitors bind -# the graduated PositionMonitor Family (DIAG-1) and the machine reads a loose -# StorageRing supply (MACHINE-1). Per the 8-ID / CHX / HXN precedent the coherent- -# imaging Methods are NOT coined here; they are the deferred owner-scope cohort -# (TECH-1). - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "coherent diffractive imaging (forward CDI, ptychography, Bragg CDI) with a KB nanofocus and Eiger2 / Merlin photon-counting detectors, 9-ID; NSLS-II's coherent-imaging beamline after Diamond i13-1, distinct from APS 9-ID; modelled from public beamline config" - name: CDI - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "Sector 9" # PV namespace XF:09ID* - tier: Unit - parent: null - source: insertion-device - source_confirm: "IVU18 in-vacuum undulator (SR:C09-ID:G1{IVU18:1}), verified in source; period/gap parameters not fully in the profile collection (SRC-1)" - page_layout: stages - shape: "Coherent diffractive imaging: a focused coherent beam, the far-field diffraction pattern on an area detector, and the real-space image recovered offline by phase retrieval." - source_ref: - label: "NSLS2/cdi-profile-collection" - url: "https://github.com/NSLS2/cdi-profile-collection" -enclosures: - # PV zones: 09IDA first-optics hutch (FOE), 09IDB branch (DM3 slit, quadrant BPM), - # 09IDC endstation (KB nanofocus, beam-conditioning unit, goniometer, towers), and - # the 09ID1 detector namespace. Modelled as an optics hutch plus an experiment - # hutch; whether the 09IDB branch is a distinct enclosure is a staff question (ENC-1). - - name: 9-ID-A - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS search-and-secure permit leaf not in source; no shutter PVs are in the profile collection either (PSS-1)"} - - name: 9-ID-C - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; 9-ID-C is the endstation carrying the KB nanofocus, the sample goniometer, and the detectors. The 09IDB branch zone may be a distinct enclosure (ENC-1)"} - -# =========================================================================== -# SOURCE STAGE: the undulator and the machine readback -# =========================================================================== - -source: - stage: source - enclosure: 9-ID-A - intro: The in-vacuum undulator source and the storage-ring readback. - devices: - - name: Source - family: InsertionDevice - pv: "SR:C09-ID:G1{IVU18:1}" - confirm: true - note: "IVU18 in-vacuum undulator (class InsertionDevice over IVUGap, instance ivu); gap-driven through the CS2:Gap motor. Period / field parameters pending (SRC-1)." - - name: StorageRing - family: StorageRing # loose supply (MACHINE-1) - pv: "SR:OPS-BI{DCCT:1}I:Real-I" - confirm: true - note: "Storage-ring current readback (ring_current), an observe-only machine-state signal. Binds the loose StorageRing supply family (never an Asset Family, MACHINE-1)." - -# =========================================================================== -# OPTICS STAGE: the monochromators, the pre-mirrors, the slits and foils, the -# master energy, and the upstream beam diagnostics -# =========================================================================== - -optics: - stage: source - enclosure: 9-ID-A - intro: "Condition the beam and set its energy: the silicon double-crystal monochromator and the double-multilayer monochromator, the vertical and horizontal pre-mirrors, the white-beam and branch slits, the attenuator foils, and the upstream beam diagnostics. PVs verified against startup/10-machine.py, 20-motors.py, 31-electrometers.py and cditools/motors.py." - devices: - - name: WhiteBeamSlit - family: Slit - pv: "XF:09IDA-OP:1{Slt:WB1" - confirm: true - note: "White-beam-defining slit on the DM1 diagnostic module (class DM1, instance dm1): inboard / outboard / top / bottom blades plus HG / HC / VG / VC gap-and-center axes. Reuses Slit." - - name: AttenuatorFoil - family: Filter - pv: "XF:09IDA-OP:1{Fltr:DM1" - confirm: true - note: "DM1 attenuator foil paddle (dm1.filt, a Y-translation selecting absorber thickness); reuses Filter. Foil materials / thicknesses pending (DET-1)." - - name: VerticalPreMirror - family: Mirror - pv: "XF:09IDA-OP:1{Mir:VPM" - confirm: true - note: "Vertical pre-mirror (class VPM, instance vpm): pitch / roll / bend plus jack and translation axes, with a fluorescent-screen diagnostic (FS:VPM) and a defining slit (Slt:VPM) on the same module. Coating / stripe pending (DCM-1)." - - name: HorizontalPreMirror - family: Mirror - pv: "XF:09IDA-OP:1{Mir:HPM" - confirm: true - note: "Horizontal pre-mirror (class HPM, instance hpm): the horizontal-deflection partner of the VPM, same pitch / roll / bend / jack axis set, with its own FS:HPM screen and Slt:HPM slit. Reuses Mirror." - - name: Monochromator - family: Monochromator - pv: "XF:09IDA-OP:1{Mono:HDCM" - confirm: true - note: "Silicon double-crystal monochromator (class DCMBase plus the Energy pseudopositioner, instances dcm_base / energy): pitch / fine-pitch / roll plus the Bragg and crystal-gap axes the energy model drives. The Si(111) reflection is read from the Energy model (d = 3.1287 A); cryo detail and full range pending (DCM-1). The EnergyAxis below is the master energy." - - name: MultilayerMonochromator - family: Monochromator - pv: "XF:09IDA-OP:1{Mono:DMM" - confirm: true - note: "Double-multilayer monochromator (class DMM, instance dmm): a wider-bandpass, higher-flux alternative to the Si DCM for coherent imaging, with its own Bragg / gap and two multilayer-crystal orientation groups (mlm1 roll / fine-roll, mlm2 pitch / fine-pitch). Reuses Monochromator (the CHX DCM-plus-DMM precedent). Coating and bandwidth pending (DCM-1)." - - name: IntensityMonitorFoil - family: Filter - pv: "XF:09IDA-OP:1{IM:DM2" - confirm: true - note: "DM2 intensity-monitor foil (dm2.foil, a Y-translation), with a fluorescent screen (FS:DM2) on the same module; reuses Filter." - - name: BranchSlit - family: Slit - pv: "XF:09IDB-OP:1{Slt:DM3" - confirm: true - note: "Branch-defining slit on the DM3 module (class DM3, instance dm3), in the 09IDB branch zone (ENC-1): inboard / outboard / top / bottom plus gap-and-center axes, with a co-located BPM stage and screen. Reuses Slit." - - name: EnergyAxis - family: PseudoAxis - confirm: true - note: "Master energy pseudo-axis (class Energy, instance energy). Driving it sets the DCM Bragg angle and the crystal gap through a real forward / inverse model (Si(111), d = 3.1287 A, 12.3984 A.keV). The provisional 5-15 keV range is marked TODO-CHECK in source; whether energy is ever scanned as the measurement is ENERGY-1." - - name: FluxMonitor - family: FluxMonitor - pv: "XF:09IDA-BI{i400:1}" - confirm: true - note: "Foil intensity monitor (class I400, instance fmon) read for I0 normalization; reuses FluxMonitor. Channel map pending (DIAG-1)." - - name: BeamPositionMonitor - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1) - pv: "XF:09IDB-BI{i404:1}" - confirm: true - note: "Quadrant beam-position monitor (class I404, instance qbpm) on the branch, plus the DM3 / DM4 BPM translation stages. Binds the graduated PositionMonitor Family (a consumer alongside 4-ID / 8-ID / iss / fmx; DIAG-1), matching the catalog note that position monitors stay loose. Channel map pending (DIAG-1)." - -# =========================================================================== -# SAMPLE STAGE: the KB nanofocus, the beam-conditioning unit, the goniometer, -# the endstation positioning towers, and the endstation diagnostics -# =========================================================================== - -sample: - stage: sample - enclosure: 9-ID-C - intro: "The endstation optics that form and condition the coherent nano-spot and the sample positioning around it: the KB mirror pair, the beam-conditioning unit, the sample goniometer, and the endstation towers. PVs verified against cditools/motors.py (KB / BCU / GON classes), startup/18-screens.py, 21-tdms.py, 31-electrometers.py." - note: > - CDI focuses the coherent beam to a small spot with a Kirkpatrick-Baez mirror - pair (the KB nanofocus) and conditions it through the beam-conditioning unit - just before the sample, then records the far-field diffraction pattern. The - sample side carries the goniometer and the endstation positioning towers; the - real-space image is recovered offline by phase retrieval (a ComputePort leg, - not modelled here). - devices: - - name: KBMirror - family: Mirror - pv: "XF:09IDC-OP:1{Mir:KBv" - confirm: true - note: "Kirkpatrick-Baez nanofocusing mirror pair (class KB: a vertical VKB at Mir:KBv and a horizontal HKB at Mir:KBh, plus an exit window Wnd:Exit), each with pitch / roll / yaw plus jack and translation axes, a defining slit, and a fluorescent screen. This is the focusing optic that forms the coherent spot; reuses Mirror (the FMX / SRX KB precedent). Focal size and coating pending (KB-1)." - - name: ConditioningSlit - family: Slit - pv: "XF:09IDC-OP:1{Slt:BCUU" - confirm: true - note: "Beam-conditioning-unit slits (class BCU, instance bcu): an upstream pair (Slt:BCUU) and a downstream pair (Slt:BCUD) trimming and guarding the coherent beam at the endstation, with an inline-camera stage (Qstar:1). Reuses Slit." - - name: InlineCamera - family: Camera - pv: "XF:09IDC-BI{BCU-Cam:9}" - confirm: true - note: "Beam-conditioning-unit inline beam-viewing camera (cam_C9, a masked Prosilica), carried on the BCU Qstar stage; reuses Camera. Live diagnostic set pending (CAM-1)." - - name: Goniometer - family: Goniometer - pv: "XF:09IDC-OP:1{Gon:1" - confirm: true - note: "Sample goniometer and stack (classes GON / SAM, instance gon): sample lab-frame translations and rotations (Rx / Rz / X / Y / Z, with small-sample and large-sample axis sets) plus alignment axes and a sample-viewing screen. Reuses Goniometer; the full axis modelling is STAGE-1." - - name: SampleTower1 - family: LinearStage - pv: "XF:09IDC-ES:1{TDMS:T1" - confirm: true - note: "Endstation positioning tower 1 (class TDMSTower, instance T1): TX / TY / TZ translations plus camera and angle axes. One of the two CDI endstation towers; which tower carries the sample versus the detector, and the sample-to-detector distance that sets the q-range, are STAGE-1. Reuses LinearStage." - - name: SampleTower2 - family: LinearStage - pv: "XF:09IDC-ES:1{TDMS:T2" - confirm: true - note: "Endstation positioning tower 2 (class TDMSTower, instance T2), the partner of SampleTower1. Reuses LinearStage; some axes are read-only pending commissioning in source (STAGE-1)." - - name: DiamondBeamMonitor - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1) - pv: "XF:09IDC-BI{BPM:1}" - confirm: true - note: "Transmissive diamond beam-position monitor read through a TetrAMM electrometer (class TetrAMM, instance dbpm) just ahead of the sample; renamed in source on 2026-06-18 from ion-chamber use to the diamond BPM. Binds the graduated PositionMonitor Family (DIAG-1)." - - name: SampleCamera - family: Camera - pv: "XF:09IDC-BI{SMPL-Cam:10}" - confirm: true - note: "Sample-viewing camera (cam_C10, a masked Prosilica); a further endstation Prosilica (cam_C15) sits alongside. Reuses Camera. Live set pending (CAM-1)." - -# =========================================================================== -# DETECTION STAGE: the coherent-diffraction area detectors -# =========================================================================== - -detector: - stage: detection - enclosure: 9-ID-C - intro: "The photon-counting area detectors that record the coherent far-field diffraction pattern. PVs verified against startup/30-area-detectors.py and cditools/eiger_async.py / merlin_async.py." - note: > - CDI's measurement lives on its area detectors: an Eiger2 and a Merlin record - the far-field coherent-diffraction pattern (a single frame for forward CDI, a - scan of frames for ptychography, a rocking series for Bragg CDI). Both reuse - Camera. The hardware exposure-gating chain is not exposed in source (TIMING-1); - the detectors carry internal and external trigger modes in their device classes. - devices: - - name: EigerDetector - family: Camera - pv: "XF:09ID1-ES{Det:Eig1}" - confirm: true - note: "Eiger2 photon-counting area detector (class EigerDetector, instance eiger2-1), the primary coherent-diffraction / ptychography detector recording the far-field pattern; reuses Camera (the Eiger-to-Camera precedent). Module size and trigger wiring pending (DET-1 / TIMING-1)." - - name: MerlinDetector - family: Camera - pv: "XF:09ID1-ES{Det:Merlin1}" - confirm: true - note: "Merlin photon-counting detector (class MerlinDetector, instance merlines-1), the second coherent-diffraction detector; reuses Camera. Which detector is primary for which technique is DET-1." - -# =========================================================================== -# Cross-cutting controls -# =========================================================================== - -controls: - intro: > - Unlike the other NSLS-II coherent beamlines, the CDI profile collection exposes - no hardware trigger box: there is no Zebra or PandA startup file, and no shutter - PVs. The Eiger2 and Merlin carry internal and external trigger modes in their - device classes, but how an exposure is gated on the floor is not in source - (TIMING-1). The motors sit on EPICS motor records whose controller boxes, - firmware, and IPs are likewise not exposed (DRIVE-1). - motion_controllers: - - name: EndstationMotionController - family: MotionController - confirm: true - note: "The motion controllers driving the optics, KB, goniometer, and tower axes; box models / protocol / IP not in the profile collection (DRIVE-1)." - triggering: [] - software_iocs_not_modeled: - [Eiger, Merlin, Prosilica, TetrAMM, i400, i404, TDMS] - -resources: - intro: Continuously-available resources. Facility-scope supplies live in deployments/nsls2/site.yaml. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: LiquidNitrogen # DCM cryocooler - - kind: Power - replaceable_parts: - swappable_with_identity: ["area detectors", "attenuator foils", "KB mirrors"] diff --git a/deployments/chx/beamline.yaml b/deployments/chx/beamline.yaml deleted file mode 100644 index 58a7311315c..00000000000 --- a/deployments/chx/beamline.yaml +++ /dev/null @@ -1,262 +0,0 @@ -# CHX beamline descriptor (NSLS-II), reverse-engineered -# -# CHX (Coherent Hard X-ray scattering) is the NSLS-II coherence beamline at sector -# 11-ID. Its defining technique is X-ray photon correlation spectroscopy (XPCS): -# it records long, fast time series of a coherent speckle pattern on an area -# detector to measure sample dynamics, plus static small- and wide-angle scattering -# (SAXS/WAXS) and grazing-incidence scattering (GISAXS) on the same detectors. It -# is bound to the NSLS-II Site (deployments/nsls2/site.yaml), the sixth NSLS-II -# beamline after FXI, HXN, BMM, SRX, and SIX. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the bluesky profile collection NSLS2/chx-profile-collection) or inferred, -# carried `confirm: true` pending CHX staff. EPICS PVs are real and verified against -# the startup scripts; vendor part numbers, serials, and physical positions are not -# in it and are open questions. Same descriptor mode as FXI / HXN / BMM / SRX; this -# scaffold is descriptor + docs, scenarios deferred. -# -# CHX is the COHERENT-SCATTERING reinforcement: it is the second coherent beamline -# CORA models (after APS 8-ID XPCS) and the second facility for that axis, so it -# proves the coherent-beamline families and the detector/timing seam port across -# facilities. It introduces NO new catalog family: the area detectors reuse Camera -# (the Eiger-to-Camera precedent), the ion-chamber/diode flux reuses FluxMonitor -# (#353), the thermal stage TemperatureController (#350), the occasional anomalous -# fluorescence EnergyDispersiveSpectrometer (#345), the beamstop BeamStop, the -# mirrors Mirror, the two monochromators Monochromator. The compound-refractive-lens -# focusing optic reuses the graduated Transfocator catalog Family (a CRL focusing -# optic, also bound at 4-ID, 8-ID, 9-ID, and i22): the abstraction is settled, so -# the only residual is the per-optic lens material and count for the transfocator -# and the endstation kinoform lenses (CRL-1). Per the 8-ID precedent the -# XPCS / small-angle-scattering Methods are NOT coined here; they are the deferred -# owner-scope cohort (TECH-1). - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "coherent hard X-ray scattering (XPCS, SAXS/WAXS, GISAXS), 11-ID; the second coherent beamline after APS 8-ID, modelled from public beamline config" - name: CHX - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "Sector 11" # PV namespace XF:11ID* - tier: Unit - parent: null - source: insertion-device - source_confirm: "IVU20 in-vacuum undulator (SR:C11-ID:G1{IVU20:1}), verified in source; parameters not fully in the profile collection (SRC-1)" - page_layout: stages - shape: "CORA's second coherent beamline: an area detector records a speckle time series (XPCS) under a fast-gated exposure, the coherent shape ported to a second facility." - source_ref: - label: "NSLS2/chx-profile-collection" - url: "https://github.com/NSLS2/chx-profile-collection" -enclosures: - # PV zones: 11IDA first-optics hutch (FOE), 11IDB endstation (the long coherence - # hutch, where the sample, flight path, and area detectors sit). Shutters span - # XF:11ID-PPS (front end) and XF:11IDA-PPS (FOE). - - name: 11-ID-A - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS search-and-secure permit leaf not in source; the shutters are XF:11ID-PPS{Sh:FE} (front end) and XF:11IDA-PPS{PSh} (FOE) (PSS-1)"} - - name: 11-ID-B - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; 11-ID-B is the endstation hutch carrying the sample, flight path, and detectors (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the undulator and front-end shutter -# =========================================================================== - -source: - stage: source - enclosure: 11-ID-A - intro: The in-vacuum undulator source and the front-end shutter. - devices: - - name: Source - family: InsertionDevice - pv: "SR:C11-ID:G1{IVU20:1}" - confirm: true - note: "IVU20 in-vacuum undulator (instance ivu_gap); gap-driven. Parameters pending (SRC-1)." - - name: FrontEndShutter - family: Shutter - pv: "XF:11ID-PPS{Sh:FE}" - confirm: true - note: "Front-end photon shutter (fe_sh); a second FOE shutter foe_sh gates 11-ID-A at XF:11IDA-PPS{PSh}." - -# =========================================================================== -# OPTICS STAGE: the two monochromators, the focusing mirror and CRL, the slits -# =========================================================================== - -optics: - stage: source - enclosure: 11-ID-A - intro: "Condition the coherent beam and set its energy: the silicon double-crystal monochromator, the double-multilayer monochromator for high coherent flux, the horizontal-deflecting mirror, the compound-refractive-lens transfocator, and the pink- and mono-beam slits. PVs verified against startup/10-optics.py and 15-machines.py." - devices: - - name: Monochromator - family: Monochromator - pv: "XF:11IDA-OP{Mono:DCM-Ax:" - confirm: true - note: "Silicon double-crystal monochromator (dcm, class DCM; axes Energy/B/R/X/FP/P). The production energy routine defaults to the Si(111) crystal at harmonic 5 (move_E xtal=Si111cryo), read from source; the cryo detail and full range are pending (DCM-1). The EnergyAxis below is the master energy." - - name: MultilayerMonochromator - family: Monochromator - pv: "XF:11IDA-OP{Mono:DMM-Ax:" - confirm: true - note: "Double-multilayer monochromator (dmm, class DMM): a wider-bandpass alternative to the Si DCM giving higher coherent flux for XPCS. Coating and bandwidth pending (DCM-1); reuses the Monochromator family." - - name: HorizontalMirror - family: Mirror - pv: "XF:11IDA-OP{Mir:HDM-Ax:" - confirm: true - note: "Horizontal-deflecting focusing mirror (hdm, class HorizontalDiffractionMirror); pitch on a separate read/write PV pair." - - name: Transfocator - family: Transfocator - pv: "XF:11IDA-OP{Lens:" - confirm: true - note: "Compound-refractive-lens transfocator (tran, class Transfocator) focusing the coherent beam. Reuses the graduated Transfocator catalog Family (a CRL focusing optic, also bound at 4-ID/8-ID/9-ID/i22). Lens material and count pending (CRL-1)." - - name: PinkBeamSlit - family: Slit - pv: "XF:11IDA-OP{Slt:PB-Ax:" - confirm: true - note: "Pink-beam-defining slit (pbs, class MotorSlits)." - - name: MonoBeamSlit - family: Slit - pv: "XF:11IDA-OP{Slt:MB-Ax:" - confirm: true - note: "Mono-beam slit (mbs, class VirtualMotorSlits) defining the coherence-matched beam." - - name: EnergyAxis - family: PseudoAxis - confirm: true - note: "The DCM energy axis (dcm.en, -Ax:Energy}Mtr), which sets the Bragg angle (dcm.b); modelled as the master energy PseudoAxis. CHX runs mostly fixed-energy; anomalous XPCS sweeps it across an edge. Whether energy is ever scanned as the measurement is ENERGY-1." - - name: BeamPositionMonitor - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1) - pv: "XF:11IDA-BI{Bpm:1-Ax:" - confirm: true - note: "Beam-position monitor bpm1 (XF:11IDA-BI{Bpm:1}); a second monitor bpm2 sits on the endstation branch (XF:11IDB-BI{BPM:2}, note the capitalization) and the AH401B electrometer (elm, XF:11IDA-BI{AH401B}AH401B:) reads diode currents. Binds the graduated PositionMonitor Family (a consumer alongside 4-ID/8-ID/9-ID; DIAG-1), matching the catalog note that position monitors stay loose. Channel map pending (DIAG-1)." - -# =========================================================================== -# SAMPLE STAGE: the grazing-incidence mirror, the sample stack, the environment -# =========================================================================== - -sample: - stage: sample - enclosure: 11-ID-B - intro: "The endstation beam-conditioning slits that define the coherent beam at the sample, the grazing-incidence mirror for GISAXS, the sample stack, and the sample-environment thermal stage. PVs verified against startup/10-optics.py, 80-pseudomotors.py, 51_Linkam.py." - note: > - CHX positions the sample in a coherent focused spot and records speckle time - series (XPCS). The beam-defining and guard slits in the endstation are the - coherence-conditioning hardware: they trim the beam to the coherent core and - block parasitic scatter ahead of the sample. The grazing-incidence mirror - steers the beam onto a surface for GISAXS; the sample stack reuses LinearStage; - the Linkam stage reuses the TemperatureController family for in-situ studies. - devices: - - name: BeamDefiningSlit - family: Slit - pv: "XF:11IDB-OP{Slt:BDS-Ax:" - confirm: true - note: "Endstation beam-defining slit (s2, a SmarAct slit, class VirtualMotorSlits) trimming the beam to its coherent core at the sample; reuses the Slit family. It replaced an older large JJ slit (Slt:2). This is the coherence-defining slit for XPCS." - - name: GuardSlit - family: Slit - pv: "XF:11IDB-OP{Slt:Guard-Ax:" - confirm: true - note: "Guard slit (gsl, a SmarAct slit) cleaning up parasitic scatter from the beam-defining slit ahead of the sample; reuses the Slit family." - - name: GrazingIncidenceMirror - family: Mirror - pv: "XF:11IDB-OP{Mir:GI-Ax:" - confirm: true - note: "Grazing-incidence mirror (gi, class XYThetaMotor) steering the beam onto a surface for GISAXS; reuses the Mirror family. Whether GISAXS is a live routine is GI-1." - - name: SampleStage - family: LinearStage - pv: "XF:11IDB-ES{Dif-Ax:" - confirm: true - note: "Sample stack on the diffractometer base (diff, class Diffractometer at XF:11IDB-ES{Dif; physical_sample_holder XF:11IDB-ES{Dif-Ax:XH}Mtr, driven by the SamplePositioner pseudomotor). Bound to LinearStage as a design-phase placeholder; the diffractometer also carries goniometric axes, so whether its sample orientation is modelled as a Goniometer plus a Diffractometer Assembly (the 8-ID precedent) is folded into STAGE-1. Full axis set pending (STAGE-1)." - - name: SampleTemperature - family: TemperatureController - pv: "XF:11ID-ES{LINKAM}:" - confirm: true - note: "Linkam thermal stage (LThermal) with a tensile variant (LTensile) for in-situ studies; reuses the TemperatureController family (graduated #350)." - -# =========================================================================== -# DETECTION STAGE: the coherent area detectors, flight path, flux, fluorescence -# =========================================================================== - -detector: - stage: detection - enclosure: 11-ID-B - intro: "The coherent area detectors for XPCS and scattering, the SAXS detector positioner and beamstop, the flux counter, the occasional fluorescence detector, and the beam-viewing cameras. PVs verified against startup/20-area-detectors.py, 10-optics.py, 26-scalers.py, 98-xspress3.py." - note: > - CHX's measurement lives on its area detectors: the Eiger captures the coherent - speckle time series (XPCS) or the static scattering pattern (SAXS/WAXS). The - detector positioner centers the detector transversely on the scattered beam and - the beamstop blocks the direct beam. All reuse existing families. Which Eiger is - primary versus the spare set is a staff question (DET-1). - devices: - - name: Eiger4M - family: Camera - pv: "XF:11IDB-ES{Det:Eig4M}" - confirm: true - note: "Eiger 4M pixel detector (eiger4m), the primary XPCS / scattering detector; fast-trigger gated for speckle time series. Reuses Camera." - - name: Eiger1M - family: Camera - pv: "XF:11IDB-ES{Det:Eig1M}" - confirm: true - note: "Eiger 1M pixel detector (eiger1m); reuses Camera." - - name: Eiger500K - family: Camera - pv: "XF:11IDB-ES{Det:Eig500K}" - confirm: true - note: "Eiger 500K pixel detector (eiger500k); reuses Camera." - - name: SAXSDetectorStage - family: LinearStage - pv: "XF:11IDB-ES{Det:SAXS-Ax:" - confirm: true - note: "Detector positioner (saxs_detector, class XYMotor: X/Y only) centering the area detector transversely on the scattered beam. Whether a separate along-beam stage sets the sample-to-detector distance (and hence the q-range) is not in source; routed to DET-1." - - name: SAXSBeamStop - family: BeamStop - pv: "XF:11IDB-ES{BS:SAXS-Ax:" - confirm: true - note: "SAXS beamstop (saxs_bst, class SAXSBeamStop) blocking the direct beam ahead of the detector; reuses BeamStop." - - name: FluxCounter - family: FluxMonitor - pv: "XF:11IDB-ES{Sclr:1}" - confirm: true - note: "Scaler-counted ion-chamber / diode flux channels (I0 and others) for normalization; reuses FluxMonitor (graduated #353). Channel map pending (DIAG-1)." - - name: FluorescenceSpectrometer - family: EnergyDispersiveSpectrometer - pv: "XF:11IDB-ES{Xsp:1}:" - confirm: true - note: "Xspress3 energy-dispersive detector (the mca.xs component, class CHXXspress3Detector) for occasional element-sensitive / anomalous work; reuses EnergyDispersiveSpectrometer (graduated #345). Element count pending (DET-1)." - - name: BeamViewingCamera - family: Camera - pv: "XF:11IDB-BI{Cam:10}" - confirm: true - note: "Prosilica on-axis beam-viewing camera (OAV); x-ray-eye Prosilicas (xray_eye1-4) and a PointGrey (BCam) serve alignment views. Reuses Camera. Live set pending (CAM-1)." - -# =========================================================================== -# Cross-cutting controls -# =========================================================================== - -controls: - intro: > - The Zebra position / time trigger that gates the fast shutter and the detector - frame triggers for an XPCS time series, and the endstation motion controllers. - Controller box models / firmware are not in the profile collection (DRIVE-1). - triggering: - - name: Zebra - family: TimingController - pv: "XF:11IDB-ES{Zebra}:" - trigger_source: TTL - confirm: true - note: "Zebra FPGA box (Zebra) gating the fast shutter (OUT1_TTL / SOFT_IN) and the Eiger frame triggers for the XPCS time series; a soft-IOC delay generator (delaygen:DG0:) and a fast shutter on the Pel-IO digital-output line sit alongside. Gating chain detail and vendor identities pending (TIMING-1)." - - name: EndstationMotionController - family: MotionController - confirm: true - note: "Endstation motion controllers driving the sample and optics axes; box model/protocol/IP not in the profile collection (DRIVE-1)." - software_iocs_not_modeled: - [Eiger, Xspress3, Zebra, Prosilica, Scaler, Linkam, DelayGenerator] - -resources: - intro: Continuously-available resources. Facility-scope supplies live in deployments/nsls2/site.yaml. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: LiquidNitrogen # DCM cryocooler - - kind: Power - replaceable_parts: - swappable_with_identity: ["Eiger detectors", "CRL lenses", "SAXS beamstop"] diff --git a/deployments/cms/beamline.yaml b/deployments/cms/beamline.yaml deleted file mode 100644 index f72ce361a47..00000000000 --- a/deployments/cms/beamline.yaml +++ /dev/null @@ -1,292 +0,0 @@ -# CMS beamline descriptor (NSLS-II), reverse-engineered -# -# CMS (Complex Materials Scattering) is the NSLS-II 11-BM beamline for soft-matter -# and thin-film structure by small- and wide-angle X-ray scattering (SAXS / WAXS / -# MAXS), grazing-incidence scattering (GISAXS / GIWAXS), and specular X-ray -# reflectivity (XR). It is bound to the NSLS-II Site (deployments/nsls2/site.yaml). -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the beamline's own bluesky profile collection, github.com/NSLS2/ -# cms-profile-collection, its startup/*.py device definitions) or inferred, carried -# `new: true` + `confirm: true` pending CMS staff. EPICS PVs are real and verified -# against the profile collection; vendor part numbers, serials, and physical -# positions are not in it and are open questions. Same descriptor mode as SMI, CMS's -# NSLS-II soft-matter-scattering twin; this scaffold is descriptor + docs, scenarios -# deferred. -# -# WHAT IS (AND IS NOT) NEW: CMS's SAXS / WAXS / MAXS / GISAXS scattering overlaps the -# fleet heavily. It is the direct NSLS-II twin of SMI (12-ID), and shares its science -# axis with Diamond I22 and APS 9-ID / 12-ID. The scattering reuses the existing -# Camera / Goniometer / Slit / BeamStop / FluxMonitor / Monochromator / Mirror -# vocabulary and coins nothing. CMS's two genuinely distinct contributions are: -# 1. Specular X-ray REFLECTIVITY (XR), the fleet's first hard X-ray reflectometry. -# It is purely a Method, not a device: there is no physical two-theta detector -# arm. The detector stays fixed and the "two-theta" is synthetic, a software -# region-of-interest that slides across the fixed Pilatus face as the sample -# theta (sth) is stepped. So XR reuses Goniometer (sth) + Camera (the Pilatus, -# read over a tracked region) + FluxMonitor (the incident-flux monitor), and -# coins no device. The reflectivity Method is shared with i10 (its soft X-ray -# sibling), CMS the second consumer (XR-1, TECH-1). -# 2. CMS as a further NSLS-II beamline, re-testing the Site / Federation kernel; -# its double-multilayer monochromator reuses the same Monochromator Family as -# the APS 2-BM DMM. -# -# MODELLING: CMS coins NO new Family and changes nothing in the catalog. 11-BM is a -# bending-magnet source (not an insertion device, the 2-BM / 7-BM pattern), observed -# through the loose StorageRing; the DMM binds Monochromator; the toroidal and -# elliptical mirrors bind Mirror; the slits bind Slit; the attenuator foils bind -# Filter; the sample-orientation circles bind Goniometer (sth is the grazing / -# specular incidence axis); the surface-leveling sub-stage binds TiltStage; the -# SAXS / WAXS / MAXS Pilatus detectors bind Camera; the detector translations and -# the telescoping flight path bind LinearStage; the beamstop binds BeamStop; the ion -# chambers, electrometers, and scintillation counter bind FluxMonitor; the diamond -# diode beam-position monitor binds the graduated PositionMonitor Family -# (DIAG-1); the Linkam stage binds TemperatureController; the support table binds -# Table. Two genuinely-new endstation devices are modelled by reuse rather than -# coinage: the GIBar sample-exchange arm is carried as stage axes (LinearStage) at -# n=1, no SampleExchanger Family coined (ROBOT-1); the generic analog diode box is -# carried as flux / diagnostic channels, no Family (folded into the detection note). -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/cms/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "complex-materials scattering (SAXS/WAXS/MAXS, GISAXS/GIWAXS) and the fleet's first hard X-ray reflectivity (XR), 11-BM; the NSLS-II twin of SMI; modelled from public beamline config" - name: CMS - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "11-BM" # PV zones XF:11BMA (FOE optics) / XF:11BMB (endstation) - tier: Unit - parent: null - source: bending-magnet - source_confirm: "11-BM is a bending-magnet (or three-pole-wiggler) source; the profile collection does not expose the source as a device, so the source detail is SRC-1" - page_layout: stages - shape: "Materials scattering (SAXS / WAXS / GISAXS) as the fleet shape ported once more, plus one distinct addition: specular reflectivity realized as a Method on a fixed area detector, no two-theta arm." - source_ref: - label: "NSLS2/cms-profile-collection" - url: "https://github.com/NSLS2/cms-profile-collection" -# PV zones: XF:11BMA (the first optics enclosure: the DMM, the toroidal mirror, the -# FOE slit and flux monitors), XF:11BMB (the endstation: the sample chamber, the -# detectors, the endstation slits and monitors), XF:11BM1 (the newer elliptical -# mirror). Whether the FOE and the endstation are separate hutches and the PSS -# permit leaves are open (ENC-1, PSS-1). -enclosures: - - name: cms-optics - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf not in the profile collection; the first optics enclosure (XF:11BMA), hutch grouping is ENC-1 (PSS-1)"} - - name: cms-endstation - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; the scattering / reflectivity endstation (XF:11BMB), ENC-1 (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the machine state and the FOE optics -# =========================================================================== - -machine: - stage: source - enclosure: cms-optics - intro: "The machine-level source state, observed not driven." - note: "Observe-only NSLS-II machine state, the loose StorageRing pattern reused from the NSLS-II siblings. 11-BM is a bending-magnet source, not an insertion device, so no InsertionDevice Asset (SRC-1, MACHINE-1)." - devices: - - name: StorageRing - family: StorageRing # loose Family (machine-level observe-only source state; MACHINE-1) - pv: {confirm: "NSLS-II storage-ring state (current, fill, status); observe-only, the exact PVs are MACHINE-1"} - new: true - confirm: true - note: "NSLS-II storage-ring state; observe-only; the 11-BM bending-magnet source detail is SRC-1 (MACHINE-1)" - -optics: - stage: source - enclosure: cms-optics - intro: "The double-multilayer monochromator, the focusing mirrors, the FOE slit and attenuator, and the incident-energy axis." - note: > - The DMM binds Monochromator (the 2-BM double-multilayer precedent, a multilayer - Bragg optic, not the soft X-ray GratingMonochromator). The mirrors bind Mirror, - the slit binds Slit, the attenuator foils bind Filter, and the incident energy is - a PseudoAxis over the DMM Bragg angle. - devices: - - name: Monochromator - family: Monochromator - pv: "XF:11BMA-OP{Mono:DMM-Ax:Bragg}Mtr" - new: true - confirm: true - note: "double-multilayer monochromator (DMM): Bragg angle sets the energy, with second-multilayer pitch / roll / offset (P2 / R2 / Y2) alignment sub-axes; the d-spacing and energy range are MONO-1" - - name: ToroidalMirror - family: Mirror - pv: "XF:11BMA-OP{Mir:Tor-Ax:UB}Mtr" - new: true - confirm: true - note: "FOE toroidal focusing mirror (X / Y alignment plus the UB bender setting the curvature); coating and bend are OPT-1" - - name: EllipticalMirror - family: Mirror - pv: "XF:11BM1-OP{MDrive:1}Mtr" - new: true - confirm: true - note: "the newer 1D elliptical focusing mirror on its MDrive controller (pitch / x / z); coating is OPT-1" - - name: FoeSlit - family: Slit - pv: "XF:11BMA-OP{Slt:0-Ax:XGap}Mtr" - new: true - confirm: true - note: "the FOE four-blade defining slit (T / B / O / I with virtual center / gap); blade-axis map is OPT-2" - - name: AttenuatorFoils - family: Filter - pv: "XF:11BMB-OP{Fltr:1}Pos-Sts" - new: true - confirm: true - note: "the eight pneumatic absorber foils (Fltr:1-8, in / out) that set transmission, important for the high dynamic range of reflectivity; the foil set is ATTN-1" - - name: BeamEnergy - family: PseudoAxis - pv: {confirm: "incident-energy virtual axis (calibrations near 13.5 keV) over the DMM Bragg angle (lambda = 2 d sin(Bragg)); the partition rule and d-spacing are MONO-1"} - new: true - confirm: true - note: "incident-energy pseudo-axis over the DMM (the 2-BM beam-energy pattern); MONO-1" - - name: FoeFluxMonitor - family: FluxMonitor - pv: {confirm: "the FOE quad electrometers (bim1 / bim2 on XF:11BMA-BI{IM:1}) reading incident flux; the channel map is DET-1"} - new: true - confirm: true - note: "FOE incident-flux monitors (quad electrometers); scalar current readings (DET-1)" - -# =========================================================================== -# SAMPLE STAGE: the sample chamber, surface stage, exchange arm, environment -# =========================================================================== - -sample: - stage: sample - enclosure: cms-endstation - intro: "The sample-orientation goniometer (whose theta is the grazing / specular incidence axis), the surface-leveling stage, the sample-exchange arm, and the in-situ temperature stage." - note: > - The sample circles bind Goniometer; the sample theta (sth) is the grazing-incidence - and specular-reflectivity angle (SAMPLE-1). Operational quirk: staff have at times - swapped sth and schi, and alternate chamber configurations rebind the logical axes - across physical PVs at startup; CORA models the logical Goniometer and carries the - binding as a setting (SAMPLE-1). The surface-leveling sub-stage binds TiltStage. - The GIBar sample-exchange arm is modelled by its stage axes (LinearStage) at n=1, - no SampleExchanger Family coined (ROBOT-1). The Linkam stage binds the graduated - TemperatureController. - devices: - - name: SampleGoniometer - family: Goniometer - pv: "XF:11BMB-ES{Chm:Smpl-Ax:theta}Mtr" - new: true - confirm: true - note: "sample-orientation circles (x / y translations, theta incidence sth, chi schi, phi sphi); sth is the grazing / specular angle; the sth-vs-schi swap and the chamber rebinding are SAMPLE-1" - - name: SurfaceStage - family: TiltStage - pv: "XF:11BMB-ES{SM:1-Ax:Stilt}Mtr" - new: true - confirm: true - note: "the surface-leveling sub-stage (Srot rotation, Strans translations, Stilt tilts) for thin-film samples; the leveling tilts bind TiltStage (SAMPLE-1)" - - name: SampleExchangeArm - family: LinearStage - pv: "XF:11BMB-ES{SM:1-Ax:Z}Mtr" - new: true - confirm: true - note: "the GIBar sample-exchange arm (x / y / z translations plus a yaw); a multi-axis sample-bar loader modelled by its stage axes at n=1, no SampleExchanger Family coined pending a second fleet sample robot (ROBOT-1)" - - name: TemperatureStage - family: TemperatureController - pv: {confirm: "the Linkam thermal / tensile stage; reuses the graduated Family (presents Regulator); the range and the tensile-load axis are TEMP-1"} - new: true - confirm: true - note: "Linkam in-situ temperature stage; reuses the graduated Family (presents Regulator); range is TEMP-1" - -# =========================================================================== -# DETECTION STAGE: the SAXS / WAXS / MAXS area detectors, the reflectivity ROI, -# the beamstop, the flux monitors, the beam-position monitor -# =========================================================================== - -detection: - stage: detection - enclosure: cms-endstation - intro: "The SAXS, WAXS, and MAXS Pilatus area detectors and their translations, the beamstop, the endstation flux monitors, and the diamond-diode beam-position monitor. The specular reflectivity (XR) is read on the fixed SAXS detector over a tracked region, not a separate device." - note: > - The Pilatus area detectors bind Camera; the detector translations and the - telescoping flight path bind LinearStage; the beamstop binds BeamStop; the ion - chamber, scintillation counter, and electrometers bind FluxMonitor; the diamond - diode beam-position monitor binds the graduated PositionMonitor Family - (DIAG-1). The reflectivity (XR) reuses the SAXS Camera read over a - sliding region-of-interest (the synthetic two-theta), with no two-theta arm and no - point detector (XR-1). - devices: - - name: SaxsDetector - family: Camera - pv: "XF:11BMB-ES{Det:PIL2M}:" - new: true - confirm: true - note: "the Pilatus 2M SAXS area detector; ALSO the detector for specular reflectivity (XR), read over a tracked region-of-interest as the sample theta is stepped (XR-1, DET-1)" - - name: WaxsDetector - family: Camera - pv: "XF:11BMB-ES{Det:PIL800K}:" - new: true - confirm: true - note: "the Pilatus 800K WAXS area detector (DET-1)" - - name: MaxsDetector - family: Camera - pv: "XF:11BMB-ES{Det:PIL800K2}:" - new: true - confirm: true - note: "the second Pilatus 800K at the medium-angle (MAXS) position; one 800K head is powered at a time per configuration (DET-1)" - - name: DetectorStage - family: LinearStage - pv: "XF:11BMB-ES{Det:SAXS-Ax:X}Mtr" - new: true - confirm: true - note: "the SAXS / WAXS / MAXS detector translations (SAXSx/y, WAXSx/y/z, MAXSx/y) and the telescoping flight path (fpn / fpr); detector positions are calibration (DET-1)" - - name: Beamstop - family: BeamStop - pv: "XF:11BMB-ES{BS:SAXS-Ax:X}Mtr" - new: true - confirm: true - note: "the SAXS beamstop (x / y / phi) in front of the area detector (DET-1)" - - name: EndstationFluxMonitor - family: FluxMonitor - pv: "XF:11BMB-BI{IM:3}" - new: true - confirm: true - note: "endstation flux monitors: the ion chamber (IM:3), the BIM4 scintillation counter (IM:4), and the endstation electrometer (IM:2); scalar readings, the channel map is DET-1" - - name: BeamPositionMonitor - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1) - pv: "XF:11BMB-BI{BPM:1}Cur:I0-I" - new: true - confirm: true - note: "the BIM5 four-quadrant diamond-diode beam-position monitor; binds the graduated PositionMonitor Family (DIAG-1); position vs intensity split is DIAG-1" - - name: SupportTable - family: Table - pv: "XF:11BMB-ES{Tbl:Rear-Ax:Z}Mtr" - new: true - confirm: true - note: "the endstation modular support table on three vertical jacks (rear / near / end) for height / pitch / roll" - -# Cross-cutting control. CMS runs EPICS (the floor); CORA observes and, where it -# replaces bluesky-style orchestration, conducts over it. The handles above were read -# from the profile collection and carried confirm (CTRL-1). -controls: - intro: > - CMS runs on the NSLS-II EPICS / ophyd control stack, the same floor as FXI, HXN, - SRX, BMM, SIX, CHX, ESM, and SMI. The device handles above are bound from the - beamline's bluesky profile collection (github.com/NSLS2/cms-profile-collection, - its startup/*.py files), carried confirm pending staff verification (CTRL-1). The - CMS acquisition (the SAXS / WAXS / GISAXS exposures, the GIBar sample exchange, - and the reflectivity (XR) scans) runs through bluesky plans; that orchestration is - the seam CORA's edge replaces, driving through ophyd / EPICS. The reflectivity XR - scan in particular is a bluesky-orchestrated sequence (step the sample theta, - slide the detector region-of-interest in lockstep, integrate the specular - intensity); CORA conducts that over the Goniometer and the Camera region rather - than EPICS owning the loop (XR-1). The area-detector file-writing to the NSLS-II - filestore is plumbing CORA observes, not data it owns (see model.md). - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a CMS run needs. The optics and the - sample chamber and flight path run under vacuum (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the optics, the sample chamber, and the SAXS flight path run under vacuum (SUP-1)" diff --git a/deployments/cristallina/beamline.yaml b/deployments/cristallina/beamline.yaml deleted file mode 100644 index 417295ea561..00000000000 --- a/deployments/cristallina/beamline.yaml +++ /dev/null @@ -1,405 +0,0 @@ -# CORA Beamline descriptor: Cristallina (SwissFEL, PSI), modelling exercise -# -# Cristallina is an operating hard-X-ray pump-probe station on SwissFEL's Aramis branch -# at PSI, the third station alongside Alvra and Bernina. It is bound to the PSI Site -# (deployments/psi/site.yaml). It is CORA's THIRD beamline on the single shared Aramis -# source: the undulator line feeds Alvra, Bernina, and Cristallina one at a time. Adding -# the third co-equal station CLOSES the Aramis triad and turns the shared-switched-source -# seam (TOPO-1) from a two-Unit case (Alvra + Bernina) into the full three-Unit routing. -# -# STATUS: off-roadmap modelling exercise, NOT a CORA pilot. Reverse-engineered, modelled -# intentionally, not mirrored. -# -# SOURCE (the distinctive provenance fact): Cristallina is CORA's FIRST deployment mined -# from `slic`, NOT `eco`. Cristallina has NO presence in paulscherrerinstitute/eco (no -# eco/cristallina/, zero code hits). Its controls live in the slic library on PSI's gitea -# (https://gitea.psi.ch/slic/cristallina, branch master), which is PUBLICLY reachable -# without login (verified). slic is eco's active successor. The device facts are in-repo -# Python literals (channels/pv_channels.py categorized PV lists + beamline/ driver -# classes), so this is a FULLER cut than Bernina (whose device list was externalized to a -# non-public JSON). Only runtime paths (CWD, data dirs, a PSSS helper script, a SECoP -# magnet server, a pulse-tube sync HTTP service) are non-public, not device definitions. -# -# THE HEADLINE: Cristallina coins NO new Family, the same finding as Alvra and Bernina, -# but it tests the model against two things the prior PSI stations did not have: -# (1) a DILUTION-FRIDGE + 3-AXIS VECTOR SUPERCONDUCTING MAGNET sample environment (DilSc: -# a LakeShore 372 thermometry/heater + an Oxford Mercury iPS vector magnet PSU, field -# limits X,Y = +/-0.6 T and Z = +/-5.2 T). The magnet binds the catalog Magnet family, -# which has GRADUATED (4-ID + i10-1 + ESRF ID32 earned the rule-of-three; MAG-1 PR -# landed). Cristallina is a FURTHER Magnet consumer that reinforced the graduation. -# The LakeShore 372 binds -# the graduated TemperatureController Family (the ID32 VTI precedent). -# (2) NO pump-probe optical laser in the controls source. Unlike Alvra and Bernina, the -# slic repo has NO SLAAR / PALM / PSEN devices; the only laser is the X-ray ALIGNMENT -# laser (SAROP31-OLAS147). Pump-probe timing is mediated by the CTA sequencer -# (SAR-CCTA-ESC) and the EVR, with a server-side pulse-tube sync service. So this cut -# carries NO PumpProbeLaser Asset; whether one exists in another controls layer is an -# open question (LASER-1, reframed). -# -# DIFFRACTOMETERS: two platforms, DM1 (the dilution-fridge diffractometer, SARES31-GPS) and -# DM2 (the pulsed-magnet diffractometer, SARES32-GPS), both built by the slic -# Diffractometer driver from derived ECMC servo-motor axes (twotheta/theta + base/sample -# translations; DM2 adds rot_x/rot_z). As at Bernina, each reuses the graduated Diffractometer -# ASSEMBLY (Goniometer + RotaryStage detector arm + reciprocal-space PseudoAxis); the GPS/XRD -# platforms were its 3rd/4th bindings, the Cristallina DM1/DM2 are the 5th/6th (DIFF-1). NO -# new Family or Assembly is coined. -# -# Family folds (each reviewed; the Alvra / Bernina precedent): aramis_attenuator -> Filter; -# SlitUnitCenterWidth / SlitUnitCenterWidthJJ -> Slit; OffsetMirror / KBVer / KBHor -> Mirror; -# CristallinaMono (DCCM double channel-cut) -> Monochromator; PulsePicker -> Shutter (PULSE-1); -# profile monitor / screen -> Scintillator + Camera; IntensityMonitorPBPS / gas monitor -> -# FluxMonitor + Diagnostic (loose); the photon single-shot spectrometer (PSSS) -> Diagnostic -# (loose, the spectral diagnostic); Diffractometer -> Goniometer (composed in the Diffractometer -# Assembly, DIFF-1); the DilSc Mercury iPS magnet -> catalog Magnet (graduated, further consumer, MAG-1); -# the LakeShore 372 -> TemperatureController (graduated); the alignment laser -> catalog Laser Family; -# the Jungfrau -> Camera; the CTA sequencer / EVR -> TimingController. The swissmx fast XY -# stage -> LinearStage; the I0 chamber slits -> Slit. -# -# Every device carries `new: true` and `confirm: true`. slic carries motor units/limits only -# for a few axes (the photon-energy 5000-13000 eV range, the magnet field limits, the LakeShore -# PID tables); all other units/limits and the Aramis undulator source params are deferred, not -# invented. slic-specific provenance cautions are carried as open questions: many drivers are -# instantiated but commented out of the active channel tuples (DM2, PuMa, several SmarAct -# stages, cameras), carried as present-hardware-not-acquired (DISABLED-1); the Jungfrau -# human-readable labels come from a commented sf_daq_broker block (DET-1). -# -# DEFERRED (out of scope, noted not modelled): the sf-daq data plane (DAQ-1); the absent -# pump-probe laser layer (LASER-1); the SECoP / Frappy magnet path and the pulse-tube sync -# HTTP service (server-side, ENV-1); the Cristallina-MX serial-crystallography sample delivery -# beyond the fast XY stage (SAMPLE-1); the sibling Aramis stations Alvra / Bernina sharing the -# source (TOPO-1); the disabled stages (DISABLED-1). - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "hard X-ray time-resolved diffraction / scattering on quantum materials (DM1 / DM2 diffractometers in a dilution-fridge vector superconducting magnet) plus serial crystallography; the third Aramis station, closes the shared-source triad, CORA's first deployment mined from `slic`, a further consumer of the graduated `Magnet` Family, no new Family" - name: Cristallina - facility: psi - tier: Unit - parent: null - source: free-electron-laser - source_confirm: > - SASE hard-X-ray FEL on the shared SwissFEL Aramis undulator line (SARUN03-15); photon - energy is set per-shot, the setpoint limited to 5000-13000 eV in slic, and the same source - feeds the Alvra, Bernina, and Cristallina stations one at a time (SRC-1 / TOPO-1). The - undulator period (15 mm) and the K-to-energy constants are in slic; the gap tables and - source size are not, and are carried confirm (SRC-1). - page_layout: stages - shape: "A hard X-ray XFEL station, the third on PSI's shared Aramis source, closing the switched-source triad (Alvra / Bernina / Cristallina fed one at a time)." - source_ref: - label: "gitea.psi.ch slic/cristallina" - url: "https://gitea.psi.ch/slic/cristallina" - -# Two access-gated zones. The SAROP31 Aramis optics hutch conditions the beam shared with the -# other Aramis stations; the Cristallina experiment hutch holds the diffractometers and the -# dilution-fridge magnet. The slic PV lists separate an "optics hutch" from an "experimental -# hutch" but do not encode the access-gated safety meaning (ENC-1). SwissFEL PPS permit and the -# high-field-magnet hazard are carried confirm (PSS-1, MAG-1). -enclosures: - - name: Aramis-Optics-SAROP31 - role: optics-hutch - facility_code: psi - permit_signal: {confirm: "SwissFEL PPS search-and-secure signal TBD; the SAROP31 Aramis optics serve Cristallina (TOPO-1, PSS-1)"} - - name: Cristallina - role: experiment-hutch - facility_code: psi - permit_signal: {confirm: "SwissFEL PPS + high-field-magnet hazard TBD (PSS-1, MAG-1)"} - -# --- SOURCE STAGE: the FEL source, shared front end, and SAROP31 Aramis optics --- - -undulator-source: - stage: source - enclosure: Aramis-Optics-SAROP31 - intro: "The SwissFEL Aramis free-electron-laser source, its front-end gas pulse-energy monitors, and the photon single-shot spectrometer." - note: > - SwissFEL is a linac-driven FEL, not a storage ring; machine beam is carried as a PhotonBeam - Supply (MACHINE-1). The Aramis undulator photon energy is set per shot; CORA has no per-shot - energy setpoint (SRC-1). The photon single-shot spectrometer (PSSS) measures the per-shot - spectrum; it presents the Sensor Role (loose Diagnostic). - devices: - - name: Undulator - family: InsertionDevice - pv: {confirm: "SwissFEL Aramis undulator line SARUN03-15-UIND030 (slic builds the per-segment K setpoints); gap tables not in slic (SRC-1)"} - new: true - confirm: true - note: "the FEL source; SASE mode and per-shot photon energy are a DAQ-plane datum, not a standing setpoint (SRC-1, DAQ-1)" - - name: GasMonitor - family: FluxMonitor - pv: "SARFE10-PBPG050" - new: true - confirm: true - note: "gas pulse-energy monitor (PBPG); presents the Sensor Role; loose family reused. Used as a scan beam-intensity condition (500-2000 uJ window in slic). Per-shot pulse energy is correlated in the DAQ by pulse-ID (DAQ-1)" - - name: FrontEndIntensityMonitor - family: FluxMonitor - pv: "SARFE10-PBPS053" - new: true - confirm: true - note: "intensity / position monitor after the undulator (PBPS); flux + position Sensor (DIAG-1)" - - name: PhotonSpectrometer - family: Diagnostic - pv: "SARFE10-PSSS059" - new: true - confirm: true - note: "photon single-shot spectrometer (PSSS; a grating / crystal spectrometer with a fit COM / FWHM readout, and a large-bandwidth camera variant). Presents the Sensor Role (loose Diagnostic); the per-shot spectrum is a DAQ-plane datum (DAQ-1)" - -front-end: - stage: source - enclosure: Aramis-Optics-SAROP31 - intro: "The shared front-end slit, attenuator, and profile monitor that gate and condition the beam before the SAROP31 optics." - note: > - The front-end attenuator is a solid attenuator solving an energy-dependent foil combination - (the slic aramis_attenuator); the Filter Family covers the discrete selection, the solve is - the deferred Attenuable leg (ATT-1). - devices: - - name: FrontEndSlit - family: Slit - pv: "SARFE10-OAPU044" - new: true - confirm: true - note: "front-end 4-blade slit (slic exposes x / y / width / height motors)" - - name: FrontEndAttenuator - family: Filter - pv: "SARFE10-OATT053" - new: true - confirm: true - note: "solid front-end attenuator (aramis_attenuator); the Filter Family covers the discrete foil selection, the energy-dependent target-transmission solve is the deferred Attenuable leg (ATT-1). Transmission readbacks alias to SAROP31-OATT053 (XREF-1)" - - name: FrontEndScreen - family: Scintillator - pv: "SARFE10-PPRM053" - new: true - confirm: true - note: "front-end profile monitor (YAG screen + camera)" - -aramis-optics: - stage: source - enclosure: Aramis-Optics-SAROP31 - intro: "The SAROP31 Aramis optics: the offset mirrors, the double-channel-cut monochromator, the slits, the pulse picker, the experiment attenuator, the KB focusing mirrors, the alignment laser, and the intensity / profile monitors that condition and focus the beam onto the Cristallina sample." - note: > - The offset mirrors and the KB pair fold into Mirror. The monochromator is a DOUBLE CHANNEL-CUT - (DCCM, ODCC110), distinct from Bernina's double-crystal mono (ODCM098); it folds into Monochromator, - and Cristallina also runs pink / SASE beam mono-out (the mono screen selects out / mono / pink) - (MONO-1). The X-ray pulse picker is a fast single-pulse gate folded into Shutter (PULSE-1). The - only laser in the optics is the X-ray ALIGNMENT laser (OLAS147), a catalog Laser Family device, NOT a - pump-probe laser (LASER-1). - devices: - - name: HorizontalMirror1 - family: Mirror - pv: "SAROP31-OOMH067" - new: true - confirm: true - note: "first Cristallina horizontal offset mirror (M1); OffsetMirror folds into Mirror" - - name: HorizontalMirror2 - family: Mirror - pv: "SAROP31-OOMH084" - new: true - confirm: true - note: "second Cristallina horizontal offset mirror (M2)" - - name: OpticsSlit - family: Slit - pv: "SAROP31-OAPU107" - new: true - confirm: true - note: "4-blade slit (SlitUnitCenterWidth) before the mono" - - name: Monochromator - family: Monochromator - pv: "SAROP31-ODCC110" - new: true - confirm: true - note: "Cristallina DOUBLE CHANNEL-CUT monochromator (DCCM; the slic CristallinaMono driver derives the two Bragg axes, the translation, and the energy / offset axes). Distinct from Bernina's DCM. Also runs pink / SASE mono-out via the mono screen (MONO-1)" - - name: OpticsIntensityMonitor - family: FluxMonitor - pv: "SAROP31-PBPS113" - new: true - confirm: true - note: "solid-target intensity / position monitor in the optics hutch (PBPS); flux + position Sensor (DIAG-1)" - - name: OpticsScreen - family: Scintillator - pv: "SAROP31-PPRM113" - new: true - confirm: true - note: "profile monitor after the mono (Pprm)" - - name: ExperimentSlit - family: Slit - pv: "SAROP31-OAPU149" - new: true - confirm: true - note: "4-blade slit (SlitUnitCenterWidth) in the experimental hutch" - - name: ExperimentIntensityMonitor - family: FluxMonitor - pv: "SAROP31-PBPS149" - new: true - confirm: true - note: "solid-target intensity / position monitor in the experimental hutch (PBPS); flux + position Sensor (DIAG-1)" - - name: ExperimentAttenuator - family: Filter - pv: "SAROP31-OATA150" - new: true - confirm: true - note: "solid attenuator for Cristallina (aramis_attenuator); Filter covers the discrete selection, the energy-dependent solve is the deferred Attenuable leg (ATT-1)" - - name: PulsePicker - family: Shutter - pv: "SAROP31-OPPI151" - new: true - confirm: true - note: "X-ray pulse picker (slic PulsePicker, with an EVR gate); folded into the Shutter Family (a fast single-pulse gate). Shutter-vs-Chopper open (PULSE-1)" - - name: OffsetMirror3 - family: Mirror - pv: "SAROP31-ODMV152" - new: true - confirm: true - note: "vertical offset mirror (M3); folds into Mirror" - - name: VerticalKBMirror - family: Mirror - pv: "SAROP31-OKBV153" - new: true - confirm: true - note: "Cristallina vertical KB focusing mirror (slic KBVer); KB folds into Mirror" - - name: HorizontalKBMirror - family: Mirror - pv: "SAROP31-OKBH154" - new: true - confirm: true - note: "Cristallina horizontal KB focusing mirror (slic KBHor); KB folds into Mirror" - - name: AlignmentLaser - family: Laser - pv: "SAROP31-OLAS147" - new: true - confirm: true - note: "X-ray alignment laser (slic AlignmentLaser, an in / out mirror); binds the catalog Laser Family. This is NOT a pump-probe laser; no SLAAR / PALM / PSEN pump-probe laser exists in the slic source (LASER-1)" - -# --- SAMPLE STAGE: the Cristallina-Q and Cristallina-MX endstations --- - -cristallina-endstation: - stage: sample - enclosure: Cristallina - intro: "The Cristallina endstation: the I0 chamber, the DM1 dilution-fridge and DM2 pulsed-magnet diffractometers, the DilSc dilution refrigerator with its vector superconducting magnet, and the Cristallina-MX fast sample stage." - note: > - The defining endstation, and the most novel sample environment in the PSI set. The two - diffractometers DM1 (dilution-fridge) and DM2 (pulsed-magnet) reuse the graduated Diffractometer - ASSEMBLY (a Goniometer + RotaryStage detector arm + reciprocal-space PseudoAxis), the 5th and 6th - bindings after Bernina's GPS / XRD (DIFF-1); their axes are ECMC servo motors derived in the slic - Diffractometer driver. The DilSc sample environment is a dilution refrigerator (LakeShore 372 - thermometry / heater, the graduated TemperatureController Family) plus an Oxford Mercury iPS 3-axis - VECTOR superconducting magnet (field limits X,Y = +/-0.6 T, Z = +/-5.2 T); the magnet binds the - catalog Magnet family, which has graduated. Cristallina is a FURTHER Magnet consumer (after - 4-ID, i10-1, ESRF ID32) that reinforced the graduation (MAG-1). DM2 and - several SmarAct / Attocube / PuMa stages are instantiated in slic but commented out of the active - channel tuples, carried as present-hardware-not-acquired (DISABLED-1). There is NO pump-probe laser - in source (LASER-1). - devices: - - name: I0Chamber - family: Slit - pv: "SARES30-MCS20610" - new: true - confirm: true - note: "the I0 chamber: SmarAct-driven slit blades plus a foil changer and a calc slit-position / width readout (slic i0_chamber). The slit-defining function binds Slit; the foils are a setting (DIAG-1)" - - name: DM1_Goniometer - family: Goniometer - pv: "SARES31-GPS" - new: true - confirm: true - note: "DM1, the Cristallina dilution-fridge diffractometer's sample-orientation goniometer (slic Diffractometer; ECMC servo axes twotheta / theta + base / sample translations). Binds the Goniometer Family; the platform is the Diffractometer Assembly (DIFF-1)" - - name: DM1_DetectorArm - family: RotaryStage - pv: {confirm: "DM1 2-theta detector arm (slic SARES31-GPS:ROT2THETA); the detector_arm slot of the Diffractometer Assembly (DIFF-1)"} - new: true - confirm: true - note: "the DM1 detector-arm 2-theta circle; the ZeroOrMore detector_arm slot of the Diffractometer Assembly (DIFF-1)" - - name: DM1_ReciprocalSpace - family: PseudoAxis - pv: {confirm: "DM1 reciprocal-space pseudo-axis (slic diffractometer recspace); the partition rule is DIFF-2"} - new: true - confirm: true - note: "the DM1 reciprocal-space (hkl) pseudo-axis layer; the reciprocal_space slot of the Diffractometer Assembly (DIFF-1, DIFF-2)" - - name: DM2_Goniometer - family: Goniometer - pv: "SARES32-GPS" - new: true - confirm: true - note: "DM2, the Cristallina pulsed-magnet diffractometer's goniometer (slic Diffractometer; DM1 axes plus rot_x / rot_z swivels). Instantiated in slic but its PV channels are commented out of the active config (DISABLED-1). Binds the Goniometer Family (DIFF-1)" - - name: DilutionFridgeThermometry - family: TemperatureController - pv: "SARES31-DIL-LS1" - new: true - confirm: true - note: "the DilSc dilution-refrigerator thermometry and heater (a LakeShore 372 regulating the mixing-chamber channel via a PID loop, with per-band calibration curves). Binds the graduated TemperatureController Family (the ID32 VTI precedent); presents the Regulator Role" - - name: VectorMagnet - family: Magnet - pv: "SARES31-MAG-IPS1" - new: true - confirm: true - note: "the DilSc 3-axis VECTOR superconducting magnet (an Oxford Mercury iPS PSU; field limits X,Y = +/-0.6 T, Z = +/-5.2 T, ramp cap 0.5 T/min). Binds the graduated catalog Magnet family (presents Regulator). Cristallina is a FURTHER consumer (4-ID + i10-1 + ESRF ID32 earned it) that reinforced the graduation (MAG-1). Modelled as a hazard via a Clearance, not a safety-driven Asset" - - name: SampleStageMX - family: LinearStage - pv: "SAR-EXPMX" - new: true - confirm: true - note: "the Cristallina-MX fast XY sample stage (slic swissmx; MOT_FX / MOT_FY). Serial-crystallography sample delivery beyond the fast stage is deferred (SAMPLE-1)" - -# --- DETECTION STAGE: the per-shot Jungfrau area detectors --- - -detector: - stage: detection - enclosure: Cristallina - intro: "The Cristallina Jungfrau science detectors. They reuse the Camera Family, but their acquisition mode is the headline gap." - note: > - The detectors reuse the Camera Family (Detector Role). What does NOT fold is how they are read: - the SwissFEL sf-daq records a free-running stream of per-shot frames tagged by pulse-ID at beam - rate, not a poll-Acquire-to-Done loop (DAQ-1). slic's live config binds a 1.5M Jungfrau - (JF16T03V02) plus a 0.5M I0 (JF20T01V01) for the Q endstation, and an 8M (JF17T16V01) for MX; - Cristallina shares DAQ crate 10 with Bernina (port 1). The Jungfrau human-readable labels come - from a commented sf_daq_broker block, carried confirm (DET-1). - devices: - - name: AreaDetectorQ - family: Camera - pv: {confirm: "Cristallina-Q Jungfrau JF16T03V02 (1.5M); sf-daq-managed, not polled (DET-1, DAQ-1)"} - new: true - confirm: true - note: "the Cristallina-Q science detector; per-shot frames flow through the sf-daq data plane, which CORA references as a Dataset rather than owns (DAQ-1)" - - name: IntensityDetectorI0 - family: Camera - pv: {confirm: "Cristallina-Q I0 Jungfrau JF20T01V01 (0.5M); sf-daq-managed (DET-1, DAQ-1)"} - new: true - confirm: true - note: "the Cristallina-Q I0 monitor Jungfrau; a 0.5M detector reading incident intensity, read through the sf-daq plane (DAQ-1)" - - name: AreaDetectorMX - family: Camera - pv: {confirm: "Cristallina-MX Jungfrau JF17T16V01 (8M); sf-daq-managed (DET-1, DAQ-1)"} - new: true - confirm: true - note: "the Cristallina-MX science detector; an 8M Jungfrau for serial crystallography, read through the sf-daq plane (DAQ-1). Selected by the MX experiment configuration" - -# Cross-cutting timing + the software systems CORA does not model. -controls: - intro: > - Cristallina runs the PSI EPICS stack plus the SwissFEL event-driven DAQ. The CTA sequencer and the - EVR program the beam-synchronous trigger pattern (and, in the absence of a pump-probe laser device, - mediate the pump-probe timing); the sf-daq, bsread streaming, and the slic acquisition suite are - software / floor. The live device facts are in-repo slic Python literals; only runtime paths and a - couple of server-side services are non-public (ENV-1). - triggering: - - name: EventTiming - family: TimingController - pv: {confirm: "SwissFEL CTA sequencer SAR-CCTA-ESC and the EVR SARES30-LTIM01-EVR0; trigger-pattern handles TBD (TIMING-1)"} - new: true - confirm: true - note: "the SwissFEL CTA sequencer / event-receiver timing that gates acquisition at beam rate and mediates the pump-probe delay (there is no pump-probe laser device in source, LASER-1). TimingController carries the device, but 'acquire on event-code N at rate R' has no typed parameter home (TIMING-1)" - software_iocs_not_modeled: - - sf-daq (the per-shot, pulse-ID-tagged event acquisition broker, DAQ-1) - - bsread / mflow (the beam-synchronous ZMQ data streaming transport, DAQ-1) - - the slic acquisition + scan suite on gitea.psi.ch (the Python beamline-control layer the descriptor is mined from) - - the DilSc SECoP / Frappy magnet server (dilsc.psi.ch:5000) and the pulse-tube synchronization service (oscillations.psi.ch:8000), both server-side (ENV-1) - - the SwissFEL data API / databuffer (the per-shot data-analysis plane; CORA references a Dataset, does not own per-shot data) - -# Continuously-available resources a run draws on (modelling exercise). -resources: - intro: > - The continuously-available facility resources a run needs present before it can start. All pending - confirmation. The FEL beam is a shared, switched resource across the Aramis stations (TOPO-1). The - dilution fridge and vector magnet draw liquid helium (MAG-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: LiquidHelium diff --git a/deployments/csx/beamline.yaml b/deployments/csx/beamline.yaml deleted file mode 100644 index e648bcef17b..00000000000 --- a/deployments/csx/beamline.yaml +++ /dev/null @@ -1,257 +0,0 @@ -# CSX beamline descriptor (NSLS-II), reverse-engineered -# -# CSX (Coherent Soft X-ray scattering) is the NSLS-II coherent soft X-ray -# scattering and resonant soft X-ray scattering (RSXS) beamline at sector 23-ID -# (the inboard 23-ID-1 branch). It is bound to the NSLS-II Site -# (deployments/nsls2/site.yaml), the sixth NSLS-II beamline after FXI, HXN, BMM, -# SRX, and SIX, and CORA's second soft X-ray deployment. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the bluesky profile collection NSLS2/csx-profile-collection) or inferred, -# carried `new: true` + `confirm: true` pending CSX staff. EPICS PVs are real and -# verified against the startup/csx1 files; vendor part numbers, serials, and -# physical positions are not in it and are open questions. Same descriptor mode as -# FXI / HXN / BMM / SRX / SIX; this scaffold is descriptor + docs, scenarios deferred. -# -# CSX is the CONSOLIDATION deployment for the soft X-ray regime SIX opened: it is -# the second soft X-ray PGM beamline, so it EARNS the GratingMonochromator Family -# into the catalog (the rule-of-three; the Family graduates in this PR, see -# docs/deployments/csx/model.md and the SIX model page). It also REUSES the -# Diffractometer Assembly: its TARDIS endstation is an hkl E6C diffractometer that -# binds the catalog Goniometer Family, a third hkl diffractometer after 4-ID / 8-ID. -# It introduces NO new family of its own; everything reuses the catalog. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/csx/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "coherent soft X-ray scattering and RSXS (TARDIS diffractometer), 23-ID; graduates the GratingMonochromator Family, modelled from public beamline config" - name: CSX - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "Sector 23" # PV namespace XF:23ID* - tier: Unit - parent: null - source: insertion-device - source_confirm: "two elliptically-polarizing undulators (EPU:1, EPU:2) on the canted SR:C23-ID straight, with a canting magnet / phaser at SR:C23-MG; modelled as one root Unit feeding the 23-ID-1 (CSX) branch (the 32-ID canted precedent), not two roots (TOPO-1); EPU type / period / polarization are SRC-1" - page_layout: stages - shape: "The consolidation of the soft X-ray regime SIX opened: it graduates GratingMonochromator and reuses the Diffractometer Assembly on its in-vacuum TARDIS endstation." - source_ref: - label: "NSLS2/csx-profile-collection" - url: "https://github.com/NSLS2/csx-profile-collection" -# PV zones: XF:23IDA (front-end optics), XF:23ID1-OP (the 23-ID-1 branch optics, -# the PGM), XF:23ID1-ES (the CSX endstation). Whether the front-end, branch optics, -# and endstation are separate shielded hutches, and the PSS permit leaves, are open -# (ENC-1, PSS-1). -enclosures: - - name: 23-ID-A - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf not in source; front-end shutter XF:23ID1-PPS{Sh:FE} (PSS-1)"} - - name: 23-ID-1 - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; the 23-ID-1 (CSX) branch; whether branch optics and endstation are separate hutches is ENC-1"} - -# =========================================================================== -# SOURCE STAGE: the canted EPUs, the front-end mirror, the PGM, the branch optics -# =========================================================================== - -insertion-devices: - stage: source - enclosure: 23-ID-A - intro: "The two elliptically-polarizing undulators on the canted SR:C23-ID straight." - note: "Two InsertionDevice Assets (the canted twin-EPU straight); each adds a polarization (phase) axis beyond gap, carried as a setting (SRC-1). Canted-vs-separate-root is TOPO-1 (32-ID precedent: one root)." - devices: - - name: Undulator_1 - family: InsertionDevice - pv: "SR:C23-ID:G1A{EPU:1" - new: true - confirm: true - note: "first EPU (epu1, XF:23ID-ID{EPU:1); gap + polarization phase (SRC-1)" - - name: Undulator_2 - family: InsertionDevice - pv: "SR:C23-ID:G1A{EPU:2" - new: true - confirm: true - note: "second EPU (epu2, XF:23ID-ID{EPU:2); gap + polarization phase (SRC-1)" - -optics: - stage: source - enclosure: 23-ID-A - intro: "The front-end hexapod mirror and the front-end shutter." - note: "m1a is the FMB hexapod-mounted front-end mirror; coatings and axis roles are OPT-1." - devices: - - name: Mirror_1 - family: Mirror - pv: "XF:23IDA-OP:1{Mir:1" - new: true - confirm: true - note: "FMB hexapod-mounted front-end mirror M1A (OPT-1)" - - name: FrontEndShutter - family: Shutter - pv: "XF:23ID1-PPS{Sh:FE}" - new: true - confirm: true - note: "front-end photon shutter, PPS-gated" - -monochromator: - stage: source - enclosure: 23-ID-1 - intro: "The variable-line-spacing plane-grating monochromator that selects the soft X-ray energy, the refocusing mirror, and the slits." - note: > - pgm is the VLS-PGM (200-2200 eV): a premirror (mir_pit / mir_x) plus an - interchangeable grating (grt_pit / grt_x) set the energy. It binds the catalog - GratingMonochromator Family, which graduates in this PR: CSX is the second soft - X-ray PGM beamline after SIX, earning the rule-of-three (MONO-1, see model.md). - m3a is the branch refocusing mirror; slt1/2/3 are the branch slits. - devices: - - name: Monochromator - family: GratingMonochromator # catalog Family (graduated this PR: SIX + CSX rule-of-three) - pv: { energy: "XF:23ID1-OP{Mono}Enrgy-SP", mirror_pitch: "XF:23ID1-OP{Mono-Ax:MirP}Mtr", mirror_x: "XF:23ID1-OP{Mono-Ax:MirX}Mtr", grating_pitch: "XF:23ID1-OP{Mono-Ax:GrtP}Mtr", grating_x: "XF:23ID1-OP{Mono-Ax:GrtX}Mtr" } - new: true - confirm: true - note: "VLS-PGM, 200-2200 eV; energy fly-scan capable; grating line densities are MONO-1" - - name: Mirror_3 - family: Mirror - pv: { x: "XF:23ID1-OP{Mir:3-Ax:XAvg}Mtr", pitch: "XF:23ID1-OP{Mir:3-Ax:P}Mtr", bender: "XF:23ID1-OP{Mir:3-Ax:Bdr}Mtr" } - new: true - confirm: true - note: "branch refocusing mirror M3A (OPT-1)" - - name: Slit_1 - family: Slit - pv: "XF:23ID1-OP{Slt:1" - new: true - confirm: true - note: "branch slit 1, gap/center (OPT-2)" - - name: Slit_2 - family: Slit - pv: "XF:23ID1-OP{Slt:2" - new: true - confirm: true - note: "branch slit 2, gap/center (OPT-2)" - - name: Slit_3 - family: Slit - pv: "XF:23ID1-OP{Slt:3" - new: true - confirm: true - note: "branch slit 3, x/y (OPT-2)" - -# =========================================================================== -# SAMPLE STAGE: the TARDIS diffractometer endstation -# =========================================================================== - -rsxs-sample: - stage: sample - enclosure: 23-ID-1 - intro: "The TARDIS soft X-ray diffractometer endstation: the scattering circles, the reciprocal-space coordination, the sample stage, and the cryostat." - note: > - TARDIS is an in-vacuum 6-circle (hkl E6C) soft X-ray diffractometer; its - circles bind the catalog Goniometer Family and the composed Assembly(Diffractometer), - a third hkl diffractometer after 4-ID and 8-ID. The reciprocal-space pseudo-axis - runs through hkl. sx/say/saz are the sample translations; stemp is the cryostat - temperature controller (DIFF-1 / SAMPLE-1). - devices: - - name: Diffractometer - family: Goniometer # catalog Family; the TARDIS E6C circles, composes the Diffractometer Assembly (DIFF-1) - pv: { theta: "XF:23ID1-ES{Dif-Ax:Th}Mtr", delta: "XF:23ID1-ES{Dif-Ax:Del}Mtr", gamma: "XF:23ID1-ES{Dif-Ax:Gam}Mtr", mu_rotation: "XF:23ID1-ES{Dif-Ax:MuR}Mtr", mu_translation: "XF:23ID1-ES{Dif-Ax:MuT}Mtr" } - new: true - confirm: true - note: "TARDIS in-vacuum 6-circle (hkl E6C) diffractometer; theta / delta / gamma circles + mu (DIFF-1)" - - name: ReciprocalSpace - family: PseudoAxis - pv: "XF:23ID1-ES{Dif-Ax:" - new: true - confirm: true - note: "hkl reciprocal-space pseudo-axis over the TARDIS E6C geometry; partition rule is DIFF-2" - - name: SampleStage - family: LinearStage - pv: { x: "XF:23ID1-ES{Dif-Ax:X}Mtr", y: "XF:23ID1-ES{Dif-Ax:Y}Mtr", z: "XF:23ID1-ES{Dif-Ax:Z}Mtr", holography_y: "XF:23ID1-ES{Holo:Sample-Ax:Y}Mtr" } - new: true - confirm: true - note: "sample translation (sx / say / saz) plus the holography sample stage (SAMPLE-1)" - - name: SampleTemperature - family: TemperatureController - pv: "XF:23ID1-ES{TCtrl:1" - new: true - confirm: true - note: "Lakeshore 336 cryostat sample temperature controller (SAMPLE-1)" - -# =========================================================================== -# DETECTION STAGE: the coherent area detectors and the counters -# =========================================================================== - -detectors: - stage: detection - enclosure: 23-ID-1 - intro: "The coherent-scattering area detectors (the FastCCD and the AXIS detector), the diffractometer fast shutter and diode, and the counting electronics." - note: > - fccd is the custom FastCCD coherent-scattering detector; axis is the newer AXIS - area detector. Both reuse the catalog Camera Family (the soft X-ray / overscan - specifics are per-Asset settings). The scaler reuses FluxMonitor (DET-1). - devices: - - name: FastCCD - family: Camera - pv: "XF:23ID1-ES{FCCD}" - new: true - confirm: true - note: "custom FastCCD coherent-scattering detector (DET-1)" - - name: AxisDetector - family: Camera - pv: "XF:23ID1-ES{AXIS}" - new: true - confirm: true - note: "AXIS area detector (DET-1)" - - name: DiagnosticCamera - family: Camera - pv: "XF:23ID1-ES{Diag:5-Cam:1}" - new: true - confirm: true - note: "diffractometer beam-view diagnostic camera" - - name: Scaler - family: FluxMonitor - pv: "XF:23ID1-ES{Sclr:1}" - new: true - confirm: true - note: "scaler / Struck MCS counting electronics for the diode and I0 channels (DET-1)" - - name: DiffractometerDiode - family: GenericProbe - pv: "XF:23ID1-ES{Dif-Abs}" - new: true - confirm: true - note: "diffractometer absorber / diode (DET-1)" - - name: FastShutter - family: Shutter - pv: "XF:23ID1-ES{Dif-FS}" - new: true - confirm: true - note: "diffractometer fast shutter gating the exposure" - -# Cross-cutting control. CSX runs EPICS (the floor); CORA observes and, where it -# replaces bluesky-style orchestration, conducts over it. The handles above were -# read from the csx-profile-collection startup files and carried confirm (CTRL-1). -controls: - intro: > - CSX runs on the NSLS-II EPICS / ophyd control stack, the same floor as the other - NSLS-II beamlines. The device handles above are bound from the beamline's bluesky - profile collection (NSLS2/csx-profile-collection), carried confirm pending staff - verification (CTRL-1). The RSXS / coherent-scattering acquisition (the energy - fly-scans, the TARDIS reciprocal-space moves, the coherent / holography plans) - runs through bluesky plans and the queue server; that orchestration is the seam - CORA's edge replaces, driving through ophyd / EPICS, while the FastCCD HDF5 - file-writing to the NSLS-II filestore is plumbing CORA observes, not data it owns - (see model.md). - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a CSX run needs. The PGM, the - in-vacuum TARDIS diffractometer, and the detectors are under UHV; the cryostat - draws on cryogens (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the optics and the in-vacuum TARDIS endstation are UHV (SUP-1)" diff --git a/deployments/diamond/site.yaml b/deployments/diamond/site.yaml deleted file mode 100644 index 99db71b4bdc..00000000000 --- a/deployments/diamond/site.yaml +++ /dev/null @@ -1,100 +0,0 @@ -# CORA Site descriptor: the Diamond Light Source site-level surface -# -# Diamond Light Source (Didcot, UK) is the third Site CORA models, and the home -# of the I22 beamline scaffold. 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. -# -# Status: Diamond / I22 is a design-phase modelling exercise. I22 is a real, -# operating SAXS/WAXS beamline, but it is NOT on the CORA pilot roadmap -# (APS -> MAX IV); it is modelled here to test that the dodal-derived dry-fact -# seed feeds CORA's intentional model, and to stress the generalize-beyond- -# tomography axis. Almost everything below is design-phase intent carried as -# `pending`, not an operating fact. Concrete facility details (safety forms, -# supply names, the operator pool) are deferred to the I22 open questions until -# Diamond staff confirm them. Do not invent facility specifics here; carry them -# as questions. -# -# Source-of-truth boundary (same as the APS and MAX IV sites): -# - the closed facility-kind / actor-kind vocabularies are validated against -# code-mirrored frozensets in scripts/site_descriptor.py. -# - the facility records the bootstrap invariants (kind=Site, display_name -# equals code); `heading` carries the human title used on the rendered page. - -facility: - code: diamond - display_name: diamond - heading: "Diamond Light Source" - kind: Site - institution: Diamond Light Source Ltd, Harwell Campus, Didcot, UK - control_plane: "EPICS / dodal" - beamlines_note: "Ten operating beamlines across MX, scattering, spectroscopy, and coherent imaging, all read from Diamond's shared dodal controls library." - beamlines: [I22, I03, I15-1, I11, I24, I06, I10, I20-1, I19, I13-1] - -# ISA-88 Site Recipes: the facility-adapted form of a catalog Method. All -# pending in the design phase. I22 is a scattering beamline, so its practices -# adapt scattering Methods that are not yet in the cross-facility catalog (they -# render unlinked); confirm with Diamond staff before any becomes active (TECH-1). -practices: - - {name: I22_small_angle_scattering_practice, method: small_angle_scattering, pending: true, note: "SAXS via the Pilatus3 2M at long camera length"} - - {name: I22_wide_angle_scattering_practice, method: wide_angle_scattering, pending: true, note: "WAXS via the second Pilatus3 2M at short camera length"} - - {name: I22_simultaneous_saxs_waxs_practice, method: small_angle_scattering, pending: true, note: "simultaneous SAXS+WAXS, the routine I22 mode; the combined-technique shape is an open question (TECH-1)"} - - {name: I03_mx_data_collection_practice, method: mx_data_collection, pending: true, note: "rotation/oscillation MX data collection on the Smargon goniometer + Eiger; new Capability not yet in the catalog (TECH-1)"} - - {name: I03_grid_scan_practice, method: grid_scan, pending: true, note: "fast grid scan for sample location/centring via the Zebra/PandA fast-grid-scan (TECH-1)"} - - {name: I03_autonomous_sample_exchange_practice, method: sample_exchange, pending: true, note: "unattended robot load/centre/collect/unmount loop; a Procedure over the spine + a Subject custody thread (ROBOT-1)"} - - {name: I15-1_total_scattering_practice, method: total_scattering, pending: true, note: "XPDF / pair-distribution-function total scattering on the bent-Laue mono + Eiger; new Capability not yet in the catalog (TECH-1)"} - - {name: I11_powder_diffraction_practice, method: powder_diffraction, pending: true, note: "high-resolution powder diffraction on the diffractometer + Mythen3 strip detector + spinner, often with a temperature ramp; new Capability not yet in the catalog (TECH-1)"} - - {name: I24_serial_crystallography_practice, method: serial_crystallography, pending: true, note: "fixed-target serial MX: raster a chip of thousands of static crystals, one snapshot per window, Zebra-gated, no rotation; the serial_crystallography Method is pending, now at i24 + LCLS-MFX (SSX-1)"} - # i06 nanoscience soft X-ray Practices (first cut). Magnetic / electronic - # structure on the APPLE-II variable-polarization source; Methods not yet in the - # catalog, carried pending until a technique enters scope (TECH-1). - - {name: I06_xmcd_practice, method: xmcd, pending: true, note: "X-ray magnetic circular dichroism on the APPLE-II polarization axis; shares the 4-ID XMCD Method (TECH-1)"} - - {name: I06_xmld_practice, method: xmld, pending: true, note: "X-ray magnetic linear dichroism on the APPLE-II polarization axis; new Capability not yet in the catalog (TECH-1)"} - - {name: I06_peem_practice, method: photoemission_microscopy, pending: true, note: "photoemission electron microscopy: a magnified electron image of the photoemitting surface; new Capability not yet in the catalog, the imaging detector is deferred (PEEM-1)"} - - {name: I06_resonant_diffraction_practice, method: resonant_scattering, pending: true, note: "resonant soft X-ray diffraction / dichroism on the i06-1 diffractometer; shares the 4-ID resonant-scattering Method (TECH-1)"} - # i10 (BLADE) magnetic-materials soft X-ray Practices (first cut). RASOR resonant - # scattering + reflectivity, and i10-1 dichroism in applied field; Methods not yet - # in the catalog, carried pending until a technique enters scope (TECH-1). - - {name: I10_resonant_scattering_practice, method: resonant_scattering, pending: true, note: "resonant soft X-ray scattering on the RASOR diffractometer, polarization-analyzed; shares the 4-ID resonant-scattering Method (TECH-1)"} - - {name: I10_reflectivity_practice, method: reflectivity, pending: true, note: "soft X-ray reflectivity on the RASOR diffractometer (the R in RASOR); new Capability not yet in the catalog (TECH-1)"} - - {name: I10_xmcd_practice, method: xmcd, pending: true, note: "X-ray magnetic circular dichroism at i10-1 in an applied magnetic field; shares the 4-ID XMCD Method (TECH-1)"} - - {name: I10_xmld_practice, method: xmld, pending: true, note: "X-ray magnetic linear dichroism at i10-1 in an applied magnetic field; shares the i06 XMLD Method (TECH-1)"} - # i20-1 energy-dispersive EXAFS (EDE) Practice (deliberately partial first cut). The - # dispersive complement to scanning XAS: a polychromator fans the energy band and a - # strip detector reads the spectrum in one shot. Method not in the catalog; the - # dispersive polychromator + strip detector are not yet in the dodal source (POLY-1 / - # STRIP-1), carried pending until a technique enters scope (TECH-1). - - {name: I20-1_ede_practice, method: energy_dispersive_exafs, pending: true, note: "energy-dispersive / time-resolved EXAFS: a bent-crystal polychromator + position-sensitive strip detector read the absorption spectrum in one shot; the dispersive complement to scanning XAS, Method not yet in the catalog (TECH-1), dispersive devices not yet in source (POLY-1 / STRIP-1)"} - # i19 chemical (small-molecule) single-crystal crystallography. Reuses the pending - # diffraction Method (4-ID / 8-ID / CSX are the prior consumers); chemical vs magnetic - # single crystal is a Practice-level science difference. The serial / microfocus - # fixed-target raster sub-mode is deferred (SERIAL-1), not a separate practice. - - {name: I19_diffraction_practice, method: diffraction, pending: true, note: "small-molecule single-crystal X-ray diffraction (chemical crystallography) on the Newport kappa four-circle + Eiger; reuses the 4-ID diffraction Method, a further consumer (TECH-1)"} - # I13-1 (I13 coherence branch) coherent lensless imaging. Ptychography raster-scans a - # coherent beam and reconstructs an image from the far-field diffraction; the fleet's - # first coherent diffractive imaging, a new Capability not yet in the catalog (TECH-1). - - {name: I13-1_ptychography_practice, method: ptychography, pending: true, note: "hard X-ray ptychography / coherent diffraction imaging: raster the piezo stage, capture far-field coherent diffraction on the Merlin, reconstruct downstream; new Capability not yet in the catalog (TECH-1)"} - -# Access BC Actors conceptually facility-wide at Diamond. Pending until the -# Diamond operator and review structure is confirmed. -actors: - - {name: Diamond beamline staff, kind: human, pending: true, note: "I22 operator and beamline-scientist pool; structure TBD"} - - {name: Diamond safety review, kind: human, pending: true, note: "facility safety review body; membership TBD"} - -# Agent BC Agents seeded at this deployment. None declared: the CORA system -# agents are not yet wired for a Diamond deployment, and I22 is a scaffold. -agents: [] - -# Supply BC: facility-wide continuously-available resources. Pending in design. -supplies: - - {name: Storage-ring beam current, kind: PhotonBeam, pending: true} - - {name: Cooling water, kind: CoolingWater, pending: true} - - {name: Beamline vacuum, kind: Vacuum, pending: true} - -# Safety BC: facility-issued Clearances. Diamond PSS form names are not yet -# confirmed; carried pending with a note rather than guessed (PSS-1). -clearances: - - {name: Diamond personnel safety system, kind: PSS, pending: true, note: "facility safety-form names TBD; confirm with Diamond staff (PSS-1)"} - -# Caution BC: operator tribal knowledge. None yet for a scaffold deployment. -cautions: [] diff --git a/deployments/elettra/site.yaml b/deployments/elettra/site.yaml deleted file mode 100644 index f0ef5b454e7..00000000000 --- a/deployments/elettra/site.yaml +++ /dev/null @@ -1,88 +0,0 @@ -# CORA Site descriptor: the Elettra Sincrotrone Trieste site-level surface -# -# Elettra Sincrotrone Trieste (operated by Elettra Sincrotrone Trieste S.C.p.A., -# which also runs the FERMI free-electron laser) is the eleventh Site CORA models, -# and its first Italian facility. 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. It is the home of the SYRMEP hard X-ray -# microtomography beamline. -# -# Status: reverse-engineered from public sources. CORA has not been connected to -# Elettra and no staff have confirmed this model. Every value below is read from -# public material (the elettra.eu beamline pages, the ElettraSciComp / ELETTRA- -# SincrotroneTrieste GitHub orgs, the public gitlab.elettra.eu, and ICALEPCS -# proceedings) or inferred, and is carried -# `pending` until staff confirm it. Do not invent facility specifics here; carry -# them as questions on the SYRMEP open-questions page. -# -# Source-of-truth boundary (same as the APS / MAX IV / Diamond / NSLS-II / SLAC / -# ESRF / Australian Synchrotron sites): -# - the closed facility-kind / actor-kind vocabularies are validated against -# code-mirrored frozensets in scripts/site_descriptor.py. -# - the facility records the bootstrap invariants (kind=Site, display_name equals -# code); `heading` carries the human title used on the rendered page. -# - a non-pending practice method must resolve to a catalog Method; SYRMEP is -# design-phase, so every practice is carried pending until the deployment -# enters pilot scope. -# -# Controls house-style (the distinctive Site fact): Elettra is Tango-native across -# both the synchrotron and the FERMI FEL (no EPICS at the facility level). The -# device / interlock floor is Tango plus the Elettra 2.0 GeCo PLC stack (Siemens -# S7-1500 over PROFINET), with Tango motion / detector device servers and HDB++ -# archiving. The beamline scan / orchestration layer is the in-house, trigger- -# driven DonkiOrchestra framework (the Elettra 2.0 successor names it the abstract -# "Executer" Tango device server); this is the seam CORA's edge would conduct over, -# NOT EPICS and NOT Sardana. See docs/deployments/syrmep/equipment/controls.md. - -facility: - code: elettra - display_name: elettra - heading: "Elettra Sincrotrone Trieste" - kind: Site - institution: Elettra Sincrotrone Trieste S.C.p.A. - control_plane: "Tango + DonkiOrchestra" - beamlines: [SYRMEP] - -# ISA-88 Site Recipes: the facility-adapted form of a catalog Method. SYRMEP is a -# hard X-ray microtomography beamline, so its imaging Practices reuse the catalog's -# existing tomography-family Methods directly (the same Methods 2-BM / 7-BM use); -# the alignment / field-correction Practices reuse the alignment + acquisition -# Methods. All are carried pending because SYRMEP is design-phase, reverse- -# engineered, and not yet in pilot scope (TECH-1). Methods not yet in the catalog -# (phase retrieval, white-beam imaging) render unlinked and are carried pending. -practices: - - {name: SYRMEP_tomography_practice, method: tomography, pending: true, note: "absorption / propagation-based phase-contrast microtomography on the rotation stage + sCMOS/CCD; reuses the 2-BM tomography Method (TECH-1)"} - - {name: SYRMEP_continuous_rotation_practice, method: continuous_rotation_tomography, pending: true, note: "continuous (fly) rotation tomography; reuses the catalog Method (TECH-1)"} - - {name: SYRMEP_mosaic_practice, method: mosaic_tomography, pending: true, note: "wide / laminar-beam tiled tomography for samples beyond the field of view; reuses the catalog Method (TECH-1)"} - - {name: SYRMEP_dark_field_practice, method: dark_field, pending: true, note: "dark-frame stack for reconstruction subtraction; reuses the catalog Method (TECH-1)"} - - {name: SYRMEP_flat_field_practice, method: flat_field, pending: true, note: "flat-field stack (beam, no sample) for reconstruction division; reuses the catalog Method (TECH-1)"} - - {name: SYRMEP_center_alignment_practice, method: center_alignment, pending: true, note: "rotation-axis centring; reuses the catalog alignment Method (TECH-1)"} - - {name: SYRMEP_helical_tomography_practice, method: helical_tomography, pending: true, note: "helical / continuous-pitch CT (the large-specimen mode, e.g. the XC Hydra photon-counting setup); Method not yet in the catalog, renders unlinked (TECH-1)"} - - {name: SYRMEP_white_beam_tomography_practice, method: white_beam_tomography, pending: true, note: "white / pink-beam fast tomography; Method not yet in the catalog (TECH-1)"} - - {name: SYRMEP_phase_retrieval_practice, method: phase_retrieval, pending: true, note: "single-distance TIE-HOM / Paganin phase retrieval (the SYRMEP Tomo Project pipeline); a compute Method not yet in the catalog (COMPUTE-1, TECH-1)"} - -# Access BC Actors conceptually facility-wide at Elettra. Pending until the operator -# and review structure is confirmed; the public sources expose no human roster. -actors: - - {name: Elettra beamline staff, kind: human, pending: true, note: "operator and beamline-scientist pool; structure TBD (GOV-1)"} - - {name: Elettra safety review, kind: human, pending: true, note: "facility safety review body; membership TBD (GOV-1)"} - -# Agent BC Agents seeded at this deployment. None declared: the CORA system agents -# are not yet wired for an Elettra deployment, and SYRMEP is a modelling exercise. -agents: [] - -# Supply BC: facility-wide continuously-available resources. Pending in this -# reverse-engineered model. The SYRMEP source is the storage-ring bending-magnet -# photon beam; the optics and sample paths draw cooling water and run under vacuum. -supplies: - - {name: Elettra photon beam, kind: PhotonBeam, pending: true, note: "Elettra storage-ring beam at 2.0 GeV (300 mA) / 2.4 GeV, shared across the beamlines; SYRMEP is fed by a bending-magnet source (SRC-1)"} - - {name: Cooling water, kind: CoolingWater, pending: true} - - {name: Beamline vacuum, kind: Vacuum, pending: true, note: "the white-beam optics and beam-transport path (SUP-1)"} - -# Safety BC: facility-issued Clearances. Elettra personnel safety is carried -# pending; the safety-form identity is not in the public sources. -clearances: - - {name: Elettra personnel safety system, kind: PSS, pending: true, note: "facility safety-form names TBD; confirm with Elettra staff (PSS-1)"} - -# Caution BC: operator tribal knowledge. None yet for a modelling exercise. -cautions: [] diff --git a/deployments/esm/beamline.yaml b/deployments/esm/beamline.yaml deleted file mode 100644 index 0e5b6c72d31..00000000000 --- a/deployments/esm/beamline.yaml +++ /dev/null @@ -1,296 +0,0 @@ -# ESM beamline descriptor (NSLS-II), reverse-engineered -# -# ESM (Electron Spectro-Microscopy) is the NSLS-II soft X-ray photoemission beamline -# at sector 21-ID. It has two endstation branches: ARPES (angle-resolved photoemission, -# 21-ID-1) and XPEEM/LEEM (photoemission electron microscopy, 21-ID-2). It is bound to -# the NSLS-II Site (deployments/nsls2/site.yaml), the eighth NSLS-II beamline and -# CORA's third soft X-ray deployment. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the bluesky profile collection NSLS2/esm-arpes-profile-collection) or -# inferred, carried `new: true` + `confirm: true` pending ESM staff. EPICS PVs are -# real and verified against the startup/*.py files; vendor part numbers, serials, and -# physical positions are not in it and are open questions. Same descriptor mode as the -# other NSLS-II beamlines; scenarios deferred. -# -# 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 the catalog ElectronAnalyzer -# Family at n=1 (presents Detector); a second ARPES beamline must earn it. -# -# 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 -# GRADUATES the Manipulator Family into the catalog (2nd UHV manipulator after SIX) -- SIX's references -# are swept loose -> graduated in this PR (see docs/deployments/esm/model.md). -# -# DELIBERATELY OUT OF THIS CUT (recorded on docs/deployments/esm/model.md): the -# XPEEM/LEEM branch (21-ID-2, the LEEM/PEEM electron microscope -> a future loose -# ElectronMicroscope Family); the sample-prep / analysis-chamber manipulators and the -# load-lock sample-transfer claw; the simulated devices. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/esm/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "electron spectro-microscopy (ARPES), 21-ID; CORA's first photoemission beamline, graduates the Manipulator Family, modelled from public beamline config" - name: ESM - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "Sector 21" # PV namespace XF:21ID* - tier: Unit - parent: null - source: insertion-device - source_confirm: "two elliptically-polarizing undulators on the SR:C21-ID straight (EPU57 on G1A, EPU105 on G1B); gap + phase (polarization) per device; the dual-EPU coordination and periods are SRC-1" - page_layout: stages - shape: "CORA's first photoemission beamline: it measures electrons, not photons, binding a hemispherical ElectronAnalyzer and graduating the UHV Manipulator." - source_ref: - label: "NSLS2/esm-arpes-profile-collection" - url: "https://github.com/NSLS2/esm-arpes-profile-collection" -# PV zones: XF:21IDA (front-end optics), XF:21IDB (the PGM), XF:21IDC (branch optics + -# exit slits), XF:21IDD-ES / XF:21ID1-ES (the ARPES endstation). Whether these are -# separate shielded hutches, and the PSS permit leaves, are open (ENC-1, PSS-1). -enclosures: - - name: 21-ID-A - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf not in source; front-end / FOE shutters XF:21ID-PPS{Sh:FE} and XF:21IDA-PPS{PSh} (PSS-1)"} - - name: 21-ID-B - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; the PGM optics zone (ENC-1)"} - - name: 21-ID-C - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; the branch optics + exit slits; branch shutters XF:21IDC-PPS{PSh:1A/1B} (ENC-1)"} - - name: 21-ID-D - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; the ARPES endstation (ENC-1)"} - -# =========================================================================== -# SOURCE STAGE: the dual EPUs, the front-end mirror, the PGM, the refocusing optics -# =========================================================================== - -insertion-devices: - stage: source - enclosure: 21-ID-A - intro: "The two elliptically-polarizing undulators on the SR:C21-ID straight." - note: "Two InsertionDevice Assets; each adds a polarization (phase) axis beyond gap, carried as a setting (SRC-1)." - devices: - - name: Undulator_1 - family: InsertionDevice - pv: "SR:C21-ID:G1A{EPU:1" - new: true - confirm: true - note: "EPU57 elliptically-polarizing undulator (gap + phase); period and polarization model are SRC-1" - - name: Undulator_2 - family: InsertionDevice - pv: "SR:C21-ID:G1B{EPU:2" - new: true - confirm: true - note: "EPU105 elliptically-polarizing undulator (gap + phase); coordinated with EPU57 (SRC-1)" - -optics: - stage: source - enclosure: 21-ID-A - intro: "The front-end mirror, the polarization diagnostic, and the front-end / FOE shutters." - note: "M1 is the first mirror; Diagon is the soft X-ray polarization diagnostic (DIAG-1)." - devices: - - name: Mirror_1 - family: Mirror - pv: "XF:21IDA-OP{Mir:1-Ax:4_" - new: true - confirm: true - note: "first mirror M1; coatings and axis roles are OPT-1" - - name: PolarizationDiagnostic - family: GenericProbe - pv: "XF:21IDA-OP{Diag:1" - new: true - confirm: true - note: "ESM Diagon soft X-ray polarization diagnostic; classification a placeholder (DIAG-1)" - - name: FrontEndShutter - family: Shutter - pv: "XF:21ID-PPS{Sh:FE}" - new: true - confirm: true - note: "front-end safety shutter, PPS-gated" - - name: FOEShutter - family: Shutter - pv: "XF:21IDA-PPS{PSh}" - new: true - confirm: true - note: "first-optics-enclosure photon shutter" - -monochromator: - stage: source - enclosure: 21-ID-B - intro: "The plane-grating monochromator that selects the soft X-ray energy, the M3 mirror, and the PGM slits." - note: > - PGM is the plane-grating monochromator: a premirror (Mirror_Pitch) plus an - interchangeable grating (Grating_Pitch / Grating_Trans) at a fixed-focus c-value - (Focus_Const) set the energy. It reuses the catalog GratingMonochromator Family - (ESM is the 3rd soft X-ray PGM after SIX + CSX). M3 is a hexapod-mounted mirror. - devices: - - name: Monochromator - family: GratingMonochromator # catalog Family (3rd soft X-ray PGM after SIX + CSX) - pv: { energy: "XF:21IDB-OP{Mono:1-Ax:8_Eng}Mtr", focus_const: "XF:21IDB-OP{Mono:1-Ax:8_Cff}Mtr", grating_translation: "XF:21IDB-OP{Mono:1-Ax:8_GT}Mtr", mirror_pitch: "XF:21IDB-OP{Mono:1-Ax:8_MP}Mtr", grating_pitch: "XF:21IDB-OP{Mono:1-Ax:8_GP}Mtr" } - new: true - confirm: true - note: "plane-grating monochromator; grating line densities and energy range are MONO-1" - - name: Mirror_3 - family: Mirror - pv: "XF:21IDB-OP{Mir:3-Ax:11" - new: true - confirm: true - note: "hexapod-mounted mirror M3 (OPT-1)" - - name: MonoSlit_Upstream - family: Slit - pv: "XF:21IDB-OP{Mono:1-Slt:7_U_1" - new: true - confirm: true - note: "upstream PGM slit (OPT-2)" - - name: MonoSlit_Downstream - family: Slit - pv: "XF:21IDB-OP{Mono:1-Slt:8_D_1" - new: true - confirm: true - note: "downstream PGM slit (OPT-2)" - - name: MirrorSlit_3 - family: Slit - pv: "XF:21IDB-OP{Mir:3-Slt:10_U_1" - new: true - confirm: true - note: "M3 slit (OPT-2)" - -refocusing: - stage: source - enclosure: 21-ID-C - intro: "The KB refocusing pair, the M4B mirror, the exit slits that set the energy resolution, and the branch shutters." - note: "M4A is the KB focusing pair, M4B a hexapod mirror; the A/B exit slits are the PGM resolution-defining elements for the two endstation branches (OPT-1, OPT-2)." - devices: - - name: Mirror_4A - family: Mirror - pv: "XF:21IDC-OP{Mir:4A-" - new: true - confirm: true - note: "Kirkpatrick-Baez refocusing pair M4A (OPT-1)" - - name: Mirror_4B - family: Mirror - pv: "XF:21IDC-OP{Mir:4B-Ax:B4" - new: true - confirm: true - note: "hexapod-mounted mirror M4B (OPT-1)" - - name: ExitSlit_A - family: Slit - pv: "XF:21IDC-OP{Slt:1A-Ax:A1" - new: true - confirm: true - note: "A-branch exit slit; sets the energy resolution (OPT-2)" - - name: ExitSlit_B - family: Slit - pv: "XF:21IDC-OP{Slt:1B-Ax:B1" - new: true - confirm: true - note: "B-branch exit slit (OPT-2)" - - name: PhotonShutter_A - family: Shutter - pv: "XF:21IDC-PPS{PSh:1A}" - new: true - confirm: true - note: "A-branch photon shutter" - - name: PhotonShutter_B - family: Shutter - pv: "XF:21IDC-PPS{PSh:1B}" - new: true - confirm: true - note: "B-branch photon shutter" - -# =========================================================================== -# SAMPLE STAGE: the ARPES UHV cryostat manipulator -# =========================================================================== - -arpes-sample: - stage: sample - enclosure: 21-ID-D - intro: "The ARPES UHV cryostat sample manipulator and the sample temperature readback." - note: > - LT is the low-temperature six-axis UHV sample manipulator (x/y/z + three - rotations), bound to the catalog Manipulator Family, which GRADUATES with this - deployment (ESM is the 2nd UHV manipulator after SIX; see model.md). The sample- - prep and analysis-chamber manipulators and the load-lock transfer claw are - deferred (SAMPLE-1). Stinger/D3 are the cryostat temperature readbacks. - devices: - - name: SampleManipulator - family: Manipulator # catalog Family (graduated this PR: 2nd UHV manipulator, SIX + ESM) - pv: { x: "XF:21IDD-ES{PRV-Ax:X}Mtr", y: "XF:21IDD-ES{PRV-Ax:Y}Mtr", z: "XF:21IDD-ES{PRV-Ax:Z}Mtr", ry: "XF:21IDD-ES{PRV-Ax:R1}Mtr", rz: "XF:21IDD-ES{PRV-Ax:R2}Mtr", rx: "XF:21IDD-ES{PRV-Ax:R3}Mtr" } - new: true - confirm: "the live manipulator prefix is the provisional {PRV; the config also carries a commented {LT:1-Manip:EA5_1 form, so the prefix is unconfirmed (SAMPLE-1)" - note: "LT six-axis UHV cryostat sample manipulator (x/y/z + Rx/Ry/Rz); cryo range and load-lock are SAMPLE-1" - - name: SampleTemperature - family: TemperatureController - pv: "XF:21ID1-ES{TCtrl:2" - new: true - confirm: true - note: "Lakeshore cryostat temperature controller (Stinger / D3 channels); sample stages it regulates are SAMPLE-1" - -# =========================================================================== -# DETECTION STAGE: the hemispherical electron analyzer and the flux monitors -# =========================================================================== - -detectors: - stage: detection - enclosure: 21-ID-D - intro: "The ARPES hemispherical electron energy analyzer and the beam-current flux monitors." - 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 - 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 # catalog Family (graduated ESM + SST; hemispherical electron energy analyzer) - pv: "XF21ID1-ES-SES" - new: true - confirm: true - note: "Scienta SES hemispherical electron energy analyzer; pass-energy / lens-mode / kinetic-energy-window controls; the ARPES detector (ARPES-1, DET-1)" - - name: FluxMonitor_Upstream - family: FluxMonitor - pv: "XF:21IDB-BI{EM:4}EM180:" - new: true - confirm: true - note: "QuadEM electrometer (one of qem01-12 along the beamline); I0 / drain-current monitor (DET-1)" - - name: FluxMonitor_Branch - family: FluxMonitor - pv: "XF:21IDC-BI{EM:6}EM180:" - new: true - confirm: true - note: "branch QuadEM electrometer; I0 monitor (DET-1)" - -# Cross-cutting control. ESM runs EPICS (the floor); CORA observes and, where it -# replaces bluesky-style orchestration, conducts over it. The handles above were -# read from the esm-arpes-profile-collection startup files and carried confirm (CTRL-1). -controls: - intro: > - ESM runs on the NSLS-II EPICS / ophyd control stack, the same floor as the other - NSLS-II beamlines. The device handles above are bound from the beamline's bluesky - profile collection (NSLS2/esm-arpes-profile-collection), carried confirm pending - staff verification (CTRL-1). The ARPES acquisition (the energy moves, the analyzer - sweeps, the manipulator scans) runs through bluesky plans and the queue server - (40-ESM_plans.py, 41-ESM_motion.py); that orchestration is the seam CORA's edge - replaces, driving through ophyd / EPICS. The analyzer's spectrum file-writing is - plumbing CORA observes, not data it owns (see model.md). - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources an ESM run needs. The optics, the - analyzer, and the sample chamber are under UHV; the cryostat manipulator draws on - cryogens (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the optics and the ARPES endstation are UHV (SUP-1)" diff --git a/deployments/esrf/site.yaml b/deployments/esrf/site.yaml deleted file mode 100644 index 2e2ef6ea335..00000000000 --- a/deployments/esrf/site.yaml +++ /dev/null @@ -1,90 +0,0 @@ -# CORA Site descriptor: the ESRF site-level surface -# -# The ESRF (European Synchrotron Radiation Facility, Grenoble, France) is the -# seventh Site CORA models, and the home of the ID32, ID19, and ID16B beamline -# scaffolds. This file is the single human-readable source for the facility's -# site-level instances: the Facility itself, the Practices it runs, and the -# facility principals. -# -# Status: every ESRF beamline here is an off-roadmap modelling exercise (like the -# Diamond / NSLS-II / APS / SLAC beamlines), reverse-engineered from the ESRF's -# open BLISS Beacon `beamline_configuration` device databases on gitlab.esrf.fr. -# The ESRF is the first BLISS / Tango / IcePAP controls house-style CORA models -# (the rest are EPICS or, at MAX IV, Tango / Sardana), so it is the first live -# non-EPICS control floor. Everything below is carried `pending` until ESRF staff -# confirm it; do not invent facility specifics here, carry them as questions on -# each beamline's open-questions page. -# -# Source-of-truth boundary (same as the other sites): -# - the closed facility-kind / actor-kind vocabularies are validated against -# code-mirrored frozensets in scripts/site_descriptor.py. -# - the facility records the bootstrap invariants (kind=Site, display_name -# equals code); `heading` carries the human title used on the rendered page. -# - a non-pending practice method must resolve to a catalog Method; the imaging -# beamlines (ID19, ID16B) reuse the tomography family, the spectroscopy -# beamline (ID32) runs none of the catalog's tomography methods, so each -# practice is carried pending until its Method is earned (registered in the -# methods-axis guard). - -facility: - code: esrf - display_name: esrf - heading: "ESRF" - kind: Site - institution: European Synchrotron Radiation Facility - control_plane: "BLISS / Beacon / Tango / IcePAP" - beamlines_note: "All four sit on the shared ESRF-EBS storage ring and the common BLISS / Tango floor; ID32 opened the BLISS seam for the fleet." - beamlines_note: "All four sit on the shared ESRF-EBS storage ring and the common BLISS / Tango floor; ID32 opened the BLISS seam for the fleet." - beamlines: [ID32, ID19, ID16B, ID28] - -# ISA-88 Site Recipes: the facility-adapted form of a catalog Method. -# -# ID32 (soft X-ray RIXS / XMCD): none of CORA's catalog Methods (all -# tomography-family today) fit, so every ID32 practice is pending, naming the -# Method it would earn. RIXS reuses the resonant_inelastic_scattering slug SIX -# left pending; XMCD reuses the xmcd slug 4-ID / i06 / i10 share; XES reuses the -# xas_spectroscopy slug the emission spectrometers at ISS / LCLS-MFX left pending. -# -# ID19 (microtomography) and ID16B (nano-analysis) reuse the existing tomography -# Method (the 2-BM pilot and MAX IV TomoWise carry it); ID16B nano-XRF mapping -# reuses the pending scanning_fluorescence_microscopy Method that 2-ID / XFM / LIX -# already carry (METHOD-1). Confirm with ESRF staff (TECH-1). -practices: - - {name: ID32_rixs_practice, method: resonant_inelastic_scattering, pending: true, note: "soft X-ray resonant inelastic scattering on the ~5 m dispersive spectrometer arm; reuses the SIX RIXS Method, the second consumer (TECH-1)"} - - {name: ID32_xmcd_practice, method: xmcd, pending: true, note: "X-ray magnetic circular / linear dichroism in the 9 T XMCD high-field magnet; reuses the 4-ID / i06 / i10 dichroism Method (TECH-1)"} - - {name: ID32_xes_practice, method: xas_spectroscopy, pending: true, note: "X-ray emission spectroscopy on the XMCD-endstation Rowland emission arm; reuses the xas_spectroscopy Method ISS / LCLS-MFX left pending for XES (TECH-1)"} - - {name: ID19_microtomography_practice, method: tomography, pending: true, note: "parallel-beam hard X-ray microtomography / radiography / phase-contrast imaging on the rotation stage + Lima area detector; reuses the catalog tomography Method, a further consumer (TECH-1)"} - # ID16B nano-analysis / nano-imaging: nano-tomography reuses the tomography Method; nano-XRF - # mapping reuses the pending scanning_fluorescence_microscopy Method that 2-ID / XFM / LIX - # already carry (METHOD-1). Both pending until ESRF staff confirm. - - {name: ID16B_nanotomography_practice, method: tomography, pending: true, note: "KB-focused hard X-ray nano-tomography on the sample rotation stage + PCO / Zyla area detector; reuses the catalog tomography Method, a further consumer (TECH-1)"} - - {name: ID16B_scanning_fluorescence_microscopy_practice, method: scanning_fluorescence_microscopy, pending: true, note: "KB-focused nano-XRF mapping (incl. fluorescence-tomography) on the piezo raster scanner + FalconX silicon-drift detector; reuses the existing pending scanning_fluorescence_microscopy Method, a further consumer (METHOD-1)"} - - {name: ID28_ixs_practice, method: inelastic_x_ray_scattering, pending: true, note: "momentum-resolved hard X-ray inelastic scattering: meV-resolution incident energy scanned against the multi-analyzer crystal spectrometer arm to map phonon dispersions; reuses the inelastic_x_ray_scattering Method that NSLS-II IXS left pending, the second consumer (TECH-1)"} - -# Access BC Actors conceptually facility-wide at the ESRF. Pending until the ESRF -# operator and review structure is confirmed. -actors: - - {name: ESRF beamline staff, kind: human, pending: true, note: "beamline scientist and operator pool; structure TBD"} - - {name: ESRF safety review, kind: human, pending: true, note: "facility safety review body; membership TBD"} - -# Agent BC Agents seeded at this deployment. None: the CORA system agents are not -# wired for an ESRF deployment, and these are modelling exercises. -agents: [] - -# Supply BC: facility-wide continuously-available resources. Pending in design. -# The ESRF storage-ring beam is a PhotonBeam supply; the 9 T XMCD magnet cryostat -# draws on liquid helium for its superconducting coils and VTI. -supplies: - - {name: ESRF photon beam, kind: PhotonBeam, pending: true, note: "ESRF-EBS storage-ring beam, shared across the beamlines (SRC-1)"} - - {name: Cooling water, kind: CoolingWater, pending: true} - - {name: Beamline vacuum, kind: Vacuum, pending: true} - - {name: Liquid helium, kind: LiquidHelium, pending: true, note: "for the 9 T XMCD superconducting magnet coils and VTI cryostat (MAG-1, SUP-1)"} - -# Safety BC: facility-issued Clearances. ESRF personnel safety (PSS) is carried -# pending; the 9 T high-field magnet and its cryogens are hazards carried with the -# XMCD endstation, not Assets CORA drives separately. -clearances: - - {name: ESRF personnel safety system, kind: PSS, pending: true, note: "facility safety-form names TBD; confirm with ESRF staff (PSS-1)"} - -# Caution BC: operator tribal knowledge. None yet for a modelling exercise. -cautions: [] diff --git a/deployments/faxtor/beamline.yaml b/deployments/faxtor/beamline.yaml deleted file mode 100644 index 43f6276e595..00000000000 --- a/deployments/faxtor/beamline.yaml +++ /dev/null @@ -1,198 +0,0 @@ -# CORA Beamline descriptor: FAXTOR (ALBA, BL31), reverse-engineered, design phase -# -# FAXTOR (FAst X-ray TOmography and Radiography) is ALBA's BL31 fast micro-CT and -# radiography beamline (Barcelona, Spain). It is bound to the ALBA Site -# (deployments/alba/site.yaml), CORA's NINTH Site and its FIRST ALBA deployment. -# -# STATUS: reverse-engineered, design / commissioning phase. Every value is read -# from ALBA's public facility pages (www.cells.es/en/beamlines/bl31-faxtor), -# or inferred; -# each device carries new: true (not yet modelled in CORA) and confirm: true (value -# to be verified by ALBA staff). Control handles are OMITTED on purpose: ALBA runs -# Tango / Sardana / Taurus (not EPICS), and NO public per-beamline device manifest -# exists (the sardana-alba repo is generic, with no bl31-* config), so no `pv` field -# is invented. This follows the MAX IV / TomoWISE precedent (handles-omitted-pending), -# NOT the ESRF / ID32 precedent (handles read from a public BLISS Beacon config). -# Devices bind to catalog Families only, with no `model`, because vendor part -# numbers are not published; the fast-camera model in particular is an open question. -# -# WHAT IS NEW: a new Site, no new vocabulary. -# - A wholly NEW Site (ALBA, the 9th) re-tests the Site / Federation kernel and -# brings the SECOND Tango / Sardana controls house-style (MAX IV is the first). -# - FAXTOR coins NO new Family and changes nothing in the catalog: it is a -# tomography beamline that reuses the imaging Families and Methods the fleet -# already carries (the 2-BM / TomoWISE precedent). -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/faxtor/questions.md. - -beamline: - maturity: model - evidence: narrative - coverage: full - summary: "BL31 fast X-ray micro-CT and radiography (continuous-rotation tomography up to 20 Hz) on a multipole wiggler; reuses the tomography Families and Methods, novelty is the Site and its Tango / Sardana control plane" - name: FAXTOR - facility: alba # ALBA Site (facility_code: alba) - sector: "BL31" - tier: Unit - parent: null - source: insertion-device - source_confirm: "FAXTOR is driven by a multipole wiggler; the period, pole count, and field are not published, carried pending (SRC-1)" - page_layout: stages - shape: "ALBA's fast X-ray tomography and radiography beamline (continuous-rotation micro-CT to 20 Hz) on a Tango / Sardana / Taurus control plane, reusing the imaging spine." - source_ref: - label: "cells.es beamline page" - url: "https://www.cells.es/en/beamlines/bl31-faxtor" - -# Two access-gated hutches. PSS permit signals are ALBA facility signals, not -# published per beamline (PSS-1). The optics / experiment grouping is inferred from -# the standard ALBA layout, carried pending (ENC-1). -enclosures: - - name: faxtor-optics - role: optics-hutch - facility_code: alba - permit_signal: {confirm: "ALBA PSS permit signal not published per beamline (PSS-1)"} - - name: faxtor-experiment - role: experiment-hutch - facility_code: alba - permit_signal: {confirm: "ALBA PSS permit signal not published per beamline (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the machine state, the wiggler, and the conditioning optics -# =========================================================================== - -machine: - stage: source - enclosure: faxtor-optics - intro: "The machine-level source state, observed not driven." - note: "The ALBA 3 GeV storage-ring state, the loose StorageRing pattern reused across the fleet (MACHINE-1)." - devices: - - name: StorageRing - family: StorageRing # loose Family (machine-level observe-only source state; MACHINE-1) - new: true - confirm: true - note: "ALBA 3 GeV storage-ring state (current, fill); observe-only, the exact handles are MACHINE-1" - -insertion-devices: - stage: source - enclosure: faxtor-optics - intro: "The multipole wiggler, the white-beam source feeding the filtered-white and monochromatic imaging modes." - note: "The wiggler binds the catalog InsertionDevice; its period, pole count, and field are not published, carried pending (SRC-1)." - devices: - - name: Wiggler - family: InsertionDevice - new: true - confirm: true - device_type: multipole-wiggler - note: "the multipole-wiggler source driving FAXTOR; segment count, period, and field pending (SRC-1)" - -optics: - stage: source - enclosure: faxtor-optics - intro: "The conditioning optics: a double multilayer monochromator for mono imaging, the filters that shape the filtered-white beam, the beam-defining slits, and the focusing / harmonic-rejection mirrors." - note: "The DMM binds Monochromator; the filters bind Filter; the slits bind Slit; the mirrors bind Mirror (carried pending, OPT-1). FAXTOR runs 8-50 keV monochromatic via the DMM and 30-70 keV filtered white beam (MONO-1)." - devices: - - name: Monochromator - family: Monochromator - new: true - confirm: true - mechanism: double multilayer monochromator (DMM) - energy_range: 8 to 50 keV (mono) - note: "double multilayer monochromator for mono imaging; bypassed in filtered-white mode (30-70 keV). Multilayer coating and d-spacing pending (MONO-1)" - - name: BeamFilter - family: Filter - new: true - confirm: true - note: "the filter set shaping the filtered-white beam (30-70 keV) and trimming heat load; materials and thicknesses pending (FILT-1)" - - name: BeamSlit - family: Slit - new: true - confirm: true - note: "the beam-defining slits; blade-axis map and handles pending (OPT-2)" - - name: FocusingMirror - family: Mirror - new: true - confirm: true - note: "the focusing / harmonic-rejection mirrors; presence, coatings, and handles not published, deferred not invented (OPT-1)" - -# =========================================================================== -# SAMPLE STAGE: the experiment endstation (the rotary, positioning, shutter) -# =========================================================================== - -experiment-endstation: - stage: sample - enclosure: faxtor-experiment - intro: "The fast-tomography experiment endstation: a sample table carrying the rotary stage, the sample positioning, and a fast shutter, supporting continuous-rotation tomography up to 20 Hz." - note: "Reuses the imaging Families the fleet already carries (Table, RotaryStage, LinearStage, Shutter); axis sets and handles pending (SAMPLE-1)." - devices: - - name: SampleTable - family: Table - new: true - confirm: true - note: "the sample-positioning support table at the experiment endstation; degrees of freedom pending (SAMPLE-1)" - - name: Rotary - family: RotaryStage - new: true - confirm: true - note: "the tomographic rotation stage; continuous-rotation tomography up to 20 Hz, the master clock for triggering (SAMPLE-1, TRIG-1)" - - name: SamplePositioning - family: LinearStage - new: true - confirm: true - note: "the sample centring / centre-of-rotation stage; axis set pending (SAMPLE-1)" - - name: FastShutter - family: Shutter - new: true - confirm: true - note: "the sample-side fast shutter limiting dose between projections; model pending (SAMPLE-1)" - -# =========================================================================== -# DETECTION STAGE: the imaging detector (scintillator + fast camera) -# =========================================================================== - -detector: - stage: detection - enclosure: faxtor-experiment - intro: "The indirect imaging detector: a scintillator converting X-rays to visible light, relayed to a fast camera. FAXTOR images at 0.5-10 um pixel size with absorption, propagation-phase, and grating-based contrast." - note: "The scintillator binds Scintillator and the camera binds Camera; the fast-camera model is not published, carried fully pending (DET-1)." - devices: - - name: Scintillator - family: Scintillator - new: true - confirm: true - note: "the X-ray-to-visible scintillator screen; material and thickness pending (DET-1)" - - name: Camera - family: Camera - new: true - confirm: true - note: "the fast imaging camera supporting up to 20 Hz tomography; sensor, frame rate, and model not published, carried pending (DET-1)" - -# Cross-cutting control. FAXTOR runs ALBA Tango / Sardana / Taurus (the floor); -# CORA observes and, where it replaces Sardana-style scan orchestration, conducts -# over it. No public per-beamline handles exist, so none are invented (CTRL-1). -controls: - intro: > - FAXTOR runs on the ALBA Tango / Sardana / Taurus control stack, CORA's second - Tango / Sardana controls house-style after MAX IV. Device IO is a layer of Tango - device servers (motors over IcePAP-class controllers, detectors via the Lima - framework), with Sardana (a Pool of controllers / motors / measurement groups - plus a MacroServer running scan macros) as the experiment-orchestration layer and - Taurus as the operator UI. No public per-beamline device manifest is published, so - the Tango / Sardana / IcePAP handles are not bound here, carried pending staff - verification (CTRL-1); when bound they would be modelled as opaque edge handles - over the ControlPort, the way the MX3 and ID32 heterogeneous-control precedents do. - The fast continuous-rotation tomography acquisition (the rotary trajectory, the - camera triggering, the flat / dark sequencing) runs through Sardana macros; that - orchestration is the seam CORA's edge replaces, conducting over Tango / IcePAP - rather than replacing Sardana. The Lima detector file-writing to the ALBA data - store is plumbing CORA observes, not data it owns (see model.md). - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a FAXTOR run needs present before it - can start. All carried pending confirmation (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/fmx/beamline.yaml b/deployments/fmx/beamline.yaml deleted file mode 100644 index f760eb6db03..00000000000 --- a/deployments/fmx/beamline.yaml +++ /dev/null @@ -1,262 +0,0 @@ -# FMX beamline descriptor (NSLS-II), reverse-engineered -# -# FMX (Frontier Microfocusing Macromolecular Crystallography) is the NSLS-II -# microfocus MX beamline at sector 17-ID-2. A hard-X-ray undulator feeds a horizontal -# double-crystal monochromator, focusing mirrors (HFM + a KB pair), and a beam -# conditioning unit onto a single-omega micro-goniometer; a robotic sample changer -# loads cryo-cooled crystals, and an Eiger pixel-array detector reads the rotation -# data. It is bound to the NSLS-II Site (deployments/nsls2/site.yaml), the fourteenth -# NSLS-II beamline after FXI, HXN, BMM, SRX, SIX, CHX, CSX, XPD, ESM, SMI, IXS, SST, -# ISS, and CORA's second macromolecular-crystallography deployment after Diamond i03. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the NSLS2/fmx-profile-collection bluesky / ophyd startup files; the real MX -# acquisition logic lives in the lsdc / mxtools libraries, referenced not modelled) or -# inferred, carried `confirm: true` pending FMX staff. EPICS PVs are real and verified -# against the startup/*.py device classes; the goniometer / robot / detector vendor -# identities, crystal cut, and physical positions are not in source and are open -# questions. Same descriptor mode as the other NSLS-II beamlines: descriptor + docs, -# scenarios deferred. -# -# FMX is a PURE-REUSE deployment: it coins NO new Family and graduates nothing. It -# reuses the MX vocabulary Diamond i03 established: the graduated Goniometer (the -# single-omega micro-goniometer), the Camera (the Eiger), the graduated Transfocator -# (the CRL), the Monochromator, the Mirror (HFM + KB), the Filter (the BCU / RI -# attenuators), the BeamStop, the FluxMonitor, the EnergyDispersiveSpectrometer (the -# Mercury fluorescence detector, modelled here rather than deferred as at i03), and the -# catalog Backlight Family (the on-axis illumination, graduated across the MX / imaging -# fleet, DET-1) and the graduated PositionMonitor Family (DIAG-1). The robotic -# sample changer is one Positioner-presenting Asset (NO new SampleChanger Family), the -# i03 / 19-BM precedent (ROBOT-1). The MX Methods (mx_data_collection, grid_scan, -# sample_exchange) stay PENDING: FMX is their second consumer (after i03), which -# strengthens but does not coin them (TECH-1; the energy_scan deferral discipline). - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "frontier microfocusing macromolecular crystallography (rotation MX on a single-omega goniometer + Eiger, autonomous robot sample exchange), 17-ID-2; CORA's 2nd MX after i03; modelled from public beamline config" - name: FMX - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "Sector 17" # PV namespace XF:17ID* (the 17-ID-2 branch) - tier: Unit - parent: null - source: insertion-device - source_confirm: "FMX (17-ID-2) shares its IVU21 in-vacuum undulator (SR:C17-ID:G1{IVU21:2}) and the 17-ID straight with its sibling AMX (17-ID-1); modelled as one root Unit feeding the 17-ID-2 branch (the CSX canted-23-ID / 32-ID precedent), not two roots. Undulator period and gap range not fully in the profile collection (SRC-1, TOPO-1)." - page_layout: stages - shape: "CORA's first NSLS-II macromolecular crystallography beamline: rotation MX on a micro-goniometer and Eiger with an autonomous robot sample-exchange loop, pure reuse." - source_ref: - label: "NSLS2/fmx-profile-collection" - url: "https://github.com/NSLS2/fmx-profile-collection" -enclosures: - # 17-ID has a shared front-end / optics enclosure (PV zone XF:17IDA, the FOE: the - # high-heat-load slit, the FMX horizontal DCM, the HFM) and the FMX experiment - # enclosure (PV zone XF:17IDC: the KB mirrors, the BCU, the goniometer, the robot, - # the Eiger). The zone letters A / C are grounded in the PV prefixes; the physical - # hutch names and the AMX-shared layout are not fully in source (TOPO-1). - - name: 17-ID-A - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS search-and-secure permit leaf not in source; the shared front-end shutter is XF:17ID-PPS:FAMX{Sh:FE} and the FMX photon shutter is XF:17IDA-PPS:FMX{PSh} (PSS-1)"} - - name: 17-ID-C - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; 17-ID-C (PV zone XF:17IDC) is the FMX experiment enclosure carrying the KB mirrors, the goniometer, the robot, and the Eiger (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the shared insertion device and the shutters -# =========================================================================== - -source: - stage: source - enclosure: 17-ID-A - intro: The shared 17-ID insertion device, the front-end and photon shutters, and the high-heat-load slit. - devices: - - name: Undulator - family: InsertionDevice - pv: "SR:C17-ID:G1{IVU21:2}" - confirm: true - note: "IVU21 in-vacuum undulator on the NSLS-II 3 GeV ring (ring current SR:OPS-BI{DCCT:1}I:Real-I), shared with AMX (17-ID-1) on the 17-ID straight. Gap axis SR:C17-ID:G1{IVU21:2-Ax:Gap}-Mtr. Period and range not fully in source (SRC-1, TOPO-1)." - - name: FrontEndShutter - family: Shutter - pv: "XF:17ID-PPS:FAMX{Sh:FE}" - confirm: true - note: "Shared FMX / AMX front-end (FOE) photon shutter." - - name: PhotonShutter - family: Shutter - pv: "XF:17IDA-PPS:FMX{PSh}" - confirm: true - note: "FMX photon shutter gating the beam into the experiment enclosure." - - name: HighHeatLoadSlit - family: Slit - pv: "XF:17IDA-OP:FMX{Slt:0" - confirm: true - note: "High-heat-load white-beam slit defining the accepted beam ahead of the monochromator." - -# =========================================================================== -# OPTICS STAGE: the monochromator, the focusing mirrors, the conditioning unit -# =========================================================================== - -optics: - stage: source - enclosure: 17-ID-A - intro: "Condition the beam and set its energy: the horizontal double-crystal monochromator, the horizontal focusing mirror and the KB mirror pair, the compound-refractive-lens transfocator, the beam-conditioning attenuators, and the slits. PVs verified against the fmx-profile-collection startup files." - devices: - - name: Monochromator - family: Monochromator - pv: "XF:17IDA-OP:FMX{Mono:DCM" - confirm: true - note: "Horizontal double-crystal monochromator (HDCM; Bragg / gap / pitch / roll axes XF:17IDA-OP:FMX{Mono:DCM-Ax:B/G/P/R}Mtr and an energy axis XF:17IDA-OP:FMX{Mono:DCM-Ax:E}Mtr). Reuses the Monochromator family. Crystal cut and energy range pending (DCM-1)." - - name: HorizontalFocusingMirror - family: Mirror - pv: "XF:17IDA-OP:FMX{Mir:HFM" - confirm: true - note: "Horizontal focusing mirror (HFM; X / Y / pitch axes), bimorph-shaped (XF:17IDA-OP:FMX{Mir:HFM-PS} power supply). Reuses the Mirror family (KB-1)." - - name: KBMirrors - family: Mirror - pv: "XF:17IDC-OP:FMX{Mir" - enclosure: 17-ID-C - confirm: true - note: "Kirkpatrick-Baez microfocus mirror pair (horizontal KBH and vertical KBV, XF:17IDC-OP:FMX{Mir:KBH / KBV-Ax:P/R/X/Y}Mtr), bimorph-shaped (XF:17IDC-OP:FMX{Mir:KB-PS}) with piezo pitch tweaks, focusing the microbeam at the sample. Reuses the Mirror family (KB-1)." - - name: Transfocator - family: Transfocator - pv: "XF:17IDC-OP:FMX{CRL:" - enclosure: 17-ID-C - confirm: true - note: "Compound-refractive-lens transfocator (CRL banks) for beam collimation / focusing. Reuses the graduated Transfocator family (CHX / SMI / IXS / 4-ID / 8-ID / 9-ID / i22 / LCLS-MFX). Lens count and focal configuration pending (KB-1)." - - name: BeamConditioningAttenuator - family: Filter - pv: "XF:17IDC-OP:FMX{Attn:BCU" - enclosure: 17-ID-C - confirm: true - note: "Beam-conditioning-unit attenuator (BCU; four insertable absorber foils XF:17IDC-OP:FMX{Attn:BCU-Ax:1-4}Mtr solving a foil combination for a requested transmission XF:17IDC-OP:FMX{Attn:BCU}). Reuses the Filter family; the energy-dependent transmission solver is the deferred Attenuable leg (the LCLS-MFX ATT-1 precedent)." - - name: ResearchIrisAttenuator - family: Filter - pv: "XF:17IDC-OP:FMX{Attn:RI" - enclosure: 17-ID-C - confirm: true - note: "Twelve-foil rotary attenuator (RI; XF:17IDC-OP:FMX{Attn:} sliders, transmission XF:17IDC-OP:FMX{Attn:RI}). Reuses the Filter family." - - name: ExperimentSlits - family: Slit - pv: "XF:17IDC-OP:FMX{Slt:2" - enclosure: 17-ID-C - confirm: true - note: "Beam-defining slits in the experiment enclosure (XF:17IDC-OP:FMX{Slt:2-5}); a first slit station sits at XF:17IDA-OP:FMX{Slt:1} in the FOE. Reuses the Slit family." - - name: EnergyAxis - family: PseudoAxis - confirm: true - note: "The master energy axis: a pseudopositioner coordinating the undulator gap, the HDCM, the HFM, and the KB mirrors from per-energy look-up tables (XF:17ID-ES:FMX{Misc-LUT:...}). Energy is set for the experiment and scanned for anomalous (SAD / MAD) data collection; the MX technique scope is TECH-1." - -# =========================================================================== -# SAMPLE STAGE: the goniometer, the robot, the sample environment -# =========================================================================== - -sample: - stage: sample - enclosure: 17-ID-C - intro: "The micro-goniometer, the automated sample-changing robot, the on-axis viewing and illumination, and the sample cooling. PVs verified against the fmx-profile-collection startup files." - note: > - FMX mounts cryo-cooled protein crystals on a single-omega micro-goniometer with - x/y/z centring and PI fine stages, exchanged by a robot from a dewar. The - goniometer reuses the graduated Goniometer family; the robot is one Positioner - Asset (not a new Family); the on-axis illumination binds the catalog Backlight - Family. Sample cryo-cooling (the cold-gas cryostream) is not exposed in the - profile collection (an annealer / thaw-air actuator XF:17IDC-ES:FMX{Wago:} is), - so it is deferred (CRYO-1). - devices: - - name: Goniometer - family: Goniometer - pv: "XF:17IDC-ES:FMX{Gon:1" - confirm: true - note: "The MX micro-goniometer (single omega rotation XF:17IDC-ES:FMX{Gon:1-Ax:O}Mtr plus GX / GY / GZ sample-centring and PY / PZ pin stages, with PI fine X / Y / Z scanners). Reuses the Goniometer family (graduated on the i03 Smargon); per-axis decomposition and centre-of-rotation calibration pending (GONIO-1)." - - name: Robot - pv: "XF:17IDC-ES:FMX{Gov:Robot}" - confirm: true - note: "Automated sample-changing robot, coordinated by the LSDC Governor state machine (XF:17IDC-ES:FMX{Gov:Robot}, with a dewar / puck safety interlock XF:17IDC-OP:FMX{DewarSwitch}). Per the i03 / 19-BM precedent: one Positioner-presenting Asset loading / unloading a Subject, gated by a Clearance, vendor in a bound Model; NOT a new SampleChanger Family. The exchange workflow and Subject custody lifecycle are deferred (ROBOT-1)." - - name: Backlight - family: Backlight # catalog Family (DET-1) - pv: "XF:17IDC-ES:FMX{Light:1" - confirm: true - note: "On-axis sample illumination (ring light) for loop centring. Binds the catalog Backlight Family (graduated across the MX / imaging fleet, DET-1)." - - name: SampleCamera - family: Camera - pv: "XF:17IDC-ES:FMX{Cam:7}" - confirm: true - note: "On-axis sample-viewing camera (a Prosilica; a second on-axis camera XF:17IDC-ES:FMX{Cam:8} and several focus-screen cameras XF:17IDx-BI:FMX{FS:n-Cam:1} serve alignment). Reuses the Camera family." - -# =========================================================================== -# DETECTION STAGE: the Eiger, the fluorescence detector, the beam monitors -# =========================================================================== - -detector: - stage: detection - enclosure: 17-ID-C - intro: "The Eiger area detector, the fluorescence detector for energy / edge selection, the on-axis beamstop, and the beam-position and flux monitors. PVs verified against the fmx-profile-collection startup files." - note: > - The Eiger reads the rotation diffraction data; the Mercury multi-element detector - reads fluorescence for energy-edge selection (anomalous MX); both bind catalog - Families. The full detector roster (Eiger model, beam centre, fluorescence ROIs) - is DET-1. - devices: - - name: AreaDetector - family: Camera - pv: "XF:17IDC-ES:FMX{Det:Eig16M}" - confirm: true - note: "Eiger 16M pixel-array detector (the MX science detector; a detector cover sits at XF:17IDC-ES:FMX{Det:FMX-Cover}). Reuses the Camera family (Detector Role). Threshold energy, beam centre, and detector model pending (DET-1)." - - name: FluorescenceDetector - family: EnergyDispersiveSpectrometer - pv: "XF:17IDC-ES:FMX{Det:Mer}" - confirm: true - note: "Mercury multi-element fluorescence detector (an energy-dispersive multi-channel analyzer reading the XRF spectrum to pick the absorption edge for anomalous data collection). Reuses the EnergyDispersiveSpectrometer family (modelled here rather than deferred as at i03). Element count and ROI map pending (DET-1)." - - name: BeamStop - family: BeamStop - pv: "XF:17IDC-ES:FMX{BS:1-Ax:FX}Mtr" - confirm: true - note: "On-axis motorized beamstop blocking the direct beam ahead of the Eiger. Reuses the BeamStop family." - - name: BeamPositionMonitor - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1) - pv: "XF:17IDA-BI:FMX{BPM:1}" - confirm: true - note: "Beam-position monitors along the beam (Prosilica BPM cameras XF:17IDA-BI:FMX{BPM:1}, XF:17IDC-BI:FMX{BPM:n}, plus the sector XBPM SR:C17-BI{XBPM:2} for photon local feedback). Binds the graduated PositionMonitor Family (a consumer alongside the other NSLS-II beamlines; DIAG-1)." - - name: FluxMonitor - family: FluxMonitor - pv: "XF:17IDC-BI:FMX{Keith:1}readFloat" - confirm: true - note: "Keithley picoammeter reading the beam-intensity photocurrent (I0 normalization). Reuses the FluxMonitor family." - -# =========================================================================== -# Cross-cutting controls -# =========================================================================== - -controls: - intro: > - FMX runs the NSLS-II EPICS control stack driven by LSDC (the macromolecular- - crystallography acquisition system) and the mxtools bluesky library. Rotation - data collection is a vector trajectory on the goniometer triggered against the - Eiger by a Zebra FPGA; the fast on-the-fly motion uses a PowerBrick / PPMAC - controller. Controller box models / firmware are not fully in source (DRIVE-1). - motion_controllers: - - name: VectorMotionController - family: MotionController - pv: "XF:17IDC-ES:FMX{Gon:1-Vec}" - confirm: true - note: "The PowerBrick vector program coordinating the goniometer during rotation data collection (start / end / expose / hold), with a PPMAC fast-motion channel XF:17ID-CT:FMX{MC17:Sender}. Standard EPICS motor records drive the remaining axes. Box model / firmware pending (DRIVE-1)." - triggering: - - name: Zebra - family: TimingController - pv: "XF:17IDC-ES:FMX{Zeb:3}:" - confirm: true - note: "Zebra FPGA position-capture and trigger box: gates the Eiger against the goniometer vector for rotation and fast grid scans (the mxtools MXFlyer). Reuses the TimingController family." - software_iocs_not_modeled: - [LSDC, mxtools, EigerIOC, Governor, MercuryDXP, PowerBrick] - -resources: - intro: Continuously-available resources. Facility-scope supplies live in deployments/nsls2/site.yaml. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum # in-vacuum undulator + optics beam path - - kind: LiquidNitrogen # sample cryo-cooling - - kind: Power - replaceable_parts: - swappable_with_identity: ["sample pucks / pins", "attenuator foils", "KB mirror stripes", "the Eiger detector"] diff --git a/deployments/fxi/beamline.yaml b/deployments/fxi/beamline.yaml deleted file mode 100644 index 1f414bc8af6..00000000000 --- a/deployments/fxi/beamline.yaml +++ /dev/null @@ -1,338 +0,0 @@ -# FXI beamline descriptor (NSLS-II), reverse-engineered -# -# FXI (Full-field X-ray Imaging) is the NSLS-II transmission X-ray microscopy and -# tomography beamline at sector 18-ID. It is the structural twin of the APS 2-BM -# pilot (continuous-rotation fly tomography, hardware position-triggering, TomoPy -# reconstruction) and is bound to the NSLS-II Site (deployments/nsls2/site.yaml). -# -# STATUS: reverse-engineered, not staff-confirmed. Every value here is read from -# public NSLS-II open source (the bluesky profile collection -# NSLS2/fxi-profile-collection and the shared NSLS2/nslsii package) or inferred. -# This is a THIRD descriptor mode, between 2-BM (operational, fully measured) and -# TomoWISE (design phase, no control system yet): -# - EPICS PVs ARE real and verified against the profile collection (FXI is a -# live EPICS beamline), so `pv` fields are populated, NOT omitted. -# - vendor part numbers, serial / firmware, motion-controller boxes, physical -# z positions, and the source type are NOT in the profile collection (they -# live in IOC st.cmd files and with FXI staff), so NO catalog `model` is -# bound and those values are carried as open questions. -# Everything is carried `confirm: true` until FXI staff verify it. Items deferred -# are tagged inline with a (QUESTION-ID) answered on docs/deployments/fxi/questions.md. -# -# Three TXM diffractive optics (Condenser, ZonePlate, PhaseRing) are now catalog -# Families: they graduated once a second deployment (FXI, after 32-ID) shared them. -# BetrandLens stays a loose family name (FXI is its only sighting; it renders as -# plain text), pending a second deployment (OPTIC-3). -# -# Fields: see deployments/2-bm/beamline.yaml for the shared shape. - -beamline: - maturity: model - evidence: controls_config - coverage: full - deployment_tier: model - page_layout: stages - summary: "full-field transmission X-ray microscopy and tomography, 18-ID; modelled from public beamline config" - name: FXI - facility: nsls2 # NSLS-II, a Site-level Facility (facility_code: nsls2) - sector: "Sector 18" # organizational label; PV namespace XF:18ID* - tier: Unit - parent: null - source: insertion-device - source_confirm: "insertion-device type (undulator vs damping wiggler) and parameters are not in the public profile collection (SRC-1)" - # No z_span: the profile collection carries no layout / z reference (LAYOUT-1). - shape: "A full-field transmission X-ray microscope: it floods the sample and images the whole field at once (fly and step tomography, radiography, XANES), the full-field counterpart to HXN's scanning probe." - source_ref: - label: "NSLS2/fxi-profile-collection" - url: "https://github.com/NSLS2/fxi-profile-collection" - -enclosures: - # Two access-gated areas, partitioned by the PV branch letter: 18-IDA carries the - # optics (XF:18IDA-*), 18-IDB the endstation (XF:18IDB-* / XF:18ID1-ES-*). The - # only permit handle exposed in the profile collection is the PPS photon-shutter - # status; the PSS search-and-secure permit leaves are not in source (PSS-1), so - # the permit_signal is carried as a confirm note rather than a guessed PV. - - name: 18-IDA - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "only the PPS photon-shutter status XF:18IDA-PPS{PSh}Pos-Sts is in source; the PSS search-and-secure permit leaf is unknown (PSS-1)"} - - name: 18-IDB - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS search-and-secure permit leaf unknown; the XF:18ID1-ES namespace may be a distinct endstation area (ENC-1)"} - -# =========================================================================== -# The beam path: source -> detector -# =========================================================================== - -source: - stage: source - enclosure: 18-IDA - intro: The insertion-device source delivering the beam to the optics hutch. - devices: - - name: Source - family: InsertionDevice - new: true - confirm: true - note: "18-ID insertion device. Type (undulator vs damping wiggler), period, gap, and power are not in the public profile collection (SRC-1); recorded as a Supply (PhotonBeam) at the Site, identity-only here." - -optics: - stage: source - enclosure: 18-IDA - intro: Condition the beam and set its energy. The double-crystal monochromator, two mirrors, the white-beam slit, attenuating filters, and the flux diagnostics. - note: > - PV prefixes are verified against startup/12-optics_motor.py and - startup/10-area-detector.py of NSLS2/fxi-profile-collection. No vendor model is - bound (part numbers unknown); the mirror role labels and crystal cut are - carried confirm. - devices: - - name: Monochromator - family: Monochromator - pv: "XF:18IDA-OP{Mono:DCM" - axis_channels: { Th1: "XF:18IDA-OP{Mono:DCM-Ax:Th1}Mtr", Th2: "XF:18IDA-OP{Mono:DCM-Ax:Th2}Mtr", Chi2: "XF:18IDA-OP{Mono:DCM-Ax:Chi2}Mtr", Dy2: "XF:18IDA-OP{Mono:DCM-Ax:Dy2}Mtr", Energy: "XF:18IDA-OP{Mono:DCM-Ax:En}Mtr" } - crystal_cut: "Si (cut unknown, DCM-1)" - confirm: true - note: > - Double-crystal monochromator (class DCM). The Energy axis (-Ax:En) is the - master energy handle; it is the same EPICS record CORA exposes as the XEng - computed axis below. Th2 and Chi2 carry IOC-level PID fine feedback - (-Ax:Th2}PID.FBON, -Ax:Chi2}PID.FBON): a closed loop that stays on the - floor, not driven by CORA. Crystal cut and energy range pending (DCM-1). - - name: CollimatingMirror - family: Mirror - pv: "XF:18IDA-OP{Mir:CM" - confirm: true - note: > - First mirror (class mirror, instance cm). The "collimating" role label is - inferred from the cm name and is carried confirm: both FXI mirrors are the - same ophyd class with no role string in source (OPTIC-1). Has a piezo - bender with a load-cell (force readout); bender control stays on the floor. - - name: ToroidalMirror - family: Mirror - pv: "XF:18IDA-OP{Mir:TM" - confirm: true - note: "Second mirror (class mirror, instance tm). The 'toroidal' role label is inferred from the tm name, carried confirm (OPTIC-1)." - - name: WhiteBeamSlit - family: Slit - pv: "XF:18IDA-OP{PBSL:1" - confirm: true - note: "White-beam-defining slit (class PBSL). Named gap/center axes; blade-axis suffixes pending (OPTIC-2)." - - name: SecondarySourceSlit - family: Slit - new: true - confirm: true - note: "Secondary-source-defining aperture (class TXM_SSA in startup/11-txm_motor.py); PV prefix not captured in this pass (OPTIC-2)." - - name: Filter - family: Filter - pv: { foil_pattern: "XF:18IDB-ES{IOLOGIK5:E1211}:DO{1..8}-Cmd" } - confirm: true - note: > - Eight pneumatic attenuating foils (filter1..filter8), each a digital-output - relay on a Moxa ioLogik E1211 (not motors). Foil materials and thicknesses - are not in the profile collection (FILT-1). - - name: XEng - family: PseudoAxis - pv: "XF:18IDA-OP{Mono:DCM-Ax:En}Mtr" - confirm: true - note: > - The master energy computed axis (== Monochromator Energy axis, verified - same record). Driving it triggers the coupled energy move move_zp_ccd_xh - (startup/41-scans.py), which over a 5 to 15 keV range interpolates a - calibration table (CALIBER / trans_calib_xh) to co-move the DCM (Chi2, Th2), - zone plate (X, Y), condenser (X, Y1, Y2, P), aperture (X, Y), and detector - (X, Y) so magnification stays constant. The lookup table is built by a - staff calibration procedure (see procedures.md); CORA would own this move - as the energy_change Conductor leg. - - name: WhiteFluxMonitor - family: GenericProbe - pv: "XF:18IDA-BI{WPFS:1}" - confirm: true - note: "White-beam flux/position sensor (Manta camera, read-only diagnostic)." - - name: PinkFluxMonitor - family: GenericProbe - pv: "XF:18IDA-BI{PMFS:1}" - confirm: true - note: "Pink-beam flux/position sensor (Manta camera, read-only diagnostic)." - - name: MonoFluxMonitor - family: GenericProbe - pv: "XF:18IDA-BI{MFS:1}" - confirm: true - note: "Monochromatic-beam flux/position sensor (Manta camera, read-only diagnostic)." - -sample: - stage: sample - enclosure: 18-IDB - intro: The TXM sample stage and the transmission-microscopy optics around it (condenser, aperture, zone plate, phase ring, Bertrand lens). - note: > - All bind to the XF:18IDB-OP prefix and are verified against - startup/11-txm_motor.py. Condenser, ZonePlate, and PhaseRing are catalog - Families (graduated with this deployment); BetrandLens stays a loose family - name (FXI-only, OPTIC-3). - devices: - - name: SampleStage - family: LinearStage - pv: "XF:18IDB-OP" - axis_channels: { sx: "XF:18IDB-OP{Env:1-Ax:Xl}Mtr", sy: "XF:18IDB-OP{Env:1-Ax:Yl}Mtr", sz: "XF:18IDB-OP{Env:1-Ax:Zl}Mtr" } - confirm: true - note: "Sample translation stack (class TXMSampleStage, sx/sy/sz). Vendor and travel pending (STAGE-1)." - - name: SampleRotary - family: RotaryStage - pv: "XF:18IDB-OP{TXM:2-Ax:R}Mtr" - trigger_source: PSO - confirm: true - note: > - The tomography rotation axis (pi_r). The Zebra reads it as encoder enc1 and - position-triggers the camera (fly tomography). Hardware (air-bearing vs - piezo), encoder resolution, and max speed are not in the profile collection; - the "PI / Physik Instrumente" reading of pi_r is a naming inference (STAGE-2). - - name: Condenser - family: Condenser - pv: "XF:18IDB-OP" - axis_channels: { x: "XF:18IDB-OP{CLens:1-Ax:X}Mtr", y1: "XF:18IDB-OP{CLens:1-Ax:Y1}Mtr", y2: "XF:18IDB-OP{CLens:1-Ax:Y2}Mtr", z1: "XF:18IDB-OP{CLens:1-Ax:Z1}Mtr", z2: "XF:18IDB-OP{CLens:1-Ax:Z2}Mtr", p: "XF:18IDB-OP{CLens:1-Ax:P}Mtr" } - new: true - confirm: true - note: "Condenser optic (class Condenser, instance clens). Catalog Family (graduated with this deployment)." - - name: Aperture - family: Aperture - pv: "XF:18IDB-OP" - axis_channels: { x: "XF:18IDB-OP{Aper:1-Ax:X}Mtr", y: "XF:18IDB-OP{Aper:1-Ax:Y}Mtr", z: "XF:18IDB-OP{TXM-Aper:1-Ax:Z}Mtr" } - confirm: true - note: "TXM aperture (class Aperture, instance aper)." - - name: ZonePlate - family: ZonePlate - pv: "XF:18IDB-OP" - axis_channels: { x: "XF:18IDB-OP{ZP:1-Ax:X}Mtr", y: "XF:18IDB-OP{BLens:1-Ax:Y}Mtr", z: "XF:18IDB-OP{TXM-ZP:1-Ax:Z}Mtr" } - manufacturer_reported: "NanoTools" - zone_diameter_um: 244 - outer_zone_width_nm: 30 - new: true - confirm: true - note: > - Zone plate objective (class Zoneplate, instance zp). Catalog Family - (graduated with this deployment). The 244 um / 30 nm and NanoTools values are - code constants (startup/20-global_param.py), not staff-confirmed (OPTIC-4). - CAUTION: zp.y is wired to the {BLens:1-Ax:Y} record while betr.y is wired to - {ZP:1-Ax:Y}; the two Y axes are cross-wired in source (CAUTION, see cautions.md). - - name: PhaseRing - family: PhaseRing - pv: "XF:18IDB-OP" - axis_channels: { x: "XF:18IDB-OP{PR:1-Ax:X}Mtr", y: "XF:18IDB-OP{PR:1-Ax:Y}Mtr", z: "XF:18IDB-OP{TXM-PH:1-Ax:Z}Mtr" } - new: true - confirm: true - note: "Zernike phase ring (class PhaseRing, instance phase_ring). Catalog Family (graduated with this deployment)." - - name: BetrandLens - family: BetrandLens - pv: "XF:18IDB-OP" - axis_channels: { x: "XF:18IDB-OP{BLens:1-Ax:X}Mtr", y: "XF:18IDB-OP{ZP:1-Ax:Y}Mtr" } - new: true - confirm: true - note: "Bertrand lens (class BetrandLens, instance betr; spelled BetrandLens in source). Loose family, genuinely novel optic (OPTIC-3). See the zp/betr Y cross-wiring caution." - - name: IonChamber - family: GenericProbe - pv: "XF:18IDB-BI{" - confirm: true - note: "Beam-intensity ion chambers ic1..ic4 (i404 quad electrometer) plus an FXIScaler; read-only. Exact channel suffixes pending (DIAG-1)." - -detector: - stage: detection - enclosure: 18-IDB - intro: "Convert the transmitted beam to light and record it: the scintillator, the detector support rails, and the imaging camera." - note: > - PV prefixes verified against startup/10-area-detector.py. Multiple camera - classes appear (Andor Neo2, Andor Marana, Photometrics Kinetix); the U/D pairs - (MaranaU/MaranaD, KinetixU/KinetixD) share identical PVs, with KinetixD marked - in source as a placeholder reusing KinetixU's PVs. CORA therefore models ONE - detector position until staff confirm which cameras are physically installed - and active (CAM-1). - devices: - - name: Scintillator - family: Scintillator - pv: "XF:18IDB-OP{Det:Lens" - axis_channels: { x: "XF:18IDB-OP{Det:Lens-Ax:X}Mtr", y: "XF:18IDB-OP{Det:Lens-Ax:Y}Mtr", z: "XF:18IDB-OP{Det:Lens-Ax:Z}Mtr" } - confirm: true - note: "Scintillator-relay lens stage (class Scint, instance scint). Material and thickness pending (DET-1)." - - name: DetectorSupport - family: LinearStage - confirm: true - note: > - Detector support rails (class DetSupport, instances DetU/DetD), x/y/z. The - DetU z position is the sample-to-detector propagation distance used in the - magnification calculation. PV prefix not captured in this pass (DET-2). - - name: Camera - family: Camera - pv: "XF:18ID1-ES{Kinetix-Det:1}" - readout_config_keys: [KINETIX, KINETIX22, MARANA-4BV6X, SONA-4BV6X] - new: true - confirm: true - note: > - The imaging detector, bound to the live Photometrics Kinetix (KinetixU, the - instance carrying RE.md). The roster of camera classes present in source is - Andor Neo2 (XF:18IDB-BI{Det:Neo2}), Andor Marana (XF:18IDB-ES{Det:Marana1}), - and Kinetix (XF:18ID1-ES{Kinetix-Det:1}); detA1 and a VLM are also Manta - cameras. Kinetix 22mm vs 29mm is distinguished at runtime by max_size_x - (2400 vs 3200). Which cameras are physically installed and active, and - whether a second position exists, is unresolved (CAM-1). Vendor part numbers - are inferred from class names, not literal in source (CAM-2). - - name: Magnification - family: PseudoAxis - confirm: true - note: > - The TXM magnification, computed as (DetU.z / zp.z - 1) * VLM, with the - visible-light-microscope factor VLM = 10 (GLOBAL_VLM_MAG, startup/20-global_param.py). - A virtual axis derived from two real Z positions; no PV of its own. - decommissioned: - - Oryx (XF:18IDB-ES{Det:Oryx1}, commented out in source) - -# =========================================================================== -# Cross-cutting controls -# =========================================================================== - -controls: - intro: > - The trigger hardware and the drive-electronics boxes. The motion controllers - are recorded as families only: the controller boxes (model, protocol, axis - count, serial, firmware, IP) are NOT in public open source. FXI has no - IOC-config repo (only fxi-profile-collection + fxi-workflows); NSLS-II's - per-beamline IOC inventory (nsls2.ioc_deploy Ansible device roles plus a - -epics-containers repo) is ops-private. Investigated and confirmed: these - need FXI staff or inventory access (DRIVE-1). - triggering: - - name: Zebra - family: TimingController - pv: "XF:18ID-ES:1{Dev:Zebra1}:" - trigger_source: PSO - confirm: true - note: > - Zebra FPGA position-capture box (class FXIZebra / ZebraPositionCapture). It - reads the sample rotary as encoder enc1 (enc2 = sx, enc3 = sy) and emits - position-compare pulses: PC_PULSE -> TTL1 -> camera, TTL2 -> fast shutter. - This is the NSLS-II analog of 2-BM's Aerotech PSO; the gating is hardware, - armed and configured by CORA over the ControlPort. A second box (Zebra2) is - referenced in source but only Zebra1 is instantiated (ZEBRA-1). The - register-overflow constant ZEBRA_OVERFLOW is a known wrap hazard (see cautions.md). - motion_controllers: - - name: SampleMotionController - family: MotionController - confirm: true - note: "Drives the 18-IDB sample-side EpicsMotors (XF:18IDB-OP*). Box model/protocol/IP unknown; FXI's IOC inventory is ops-private, not in public open source (DRIVE-1)." - - name: OpticsMotionController - family: MotionController - confirm: true - note: "Drives the 18-IDA optics EpicsMotors (XF:18IDA-OP*). Box identity unknown; not in public open source (DRIVE-1)." - software_iocs_not_modeled: - # Software processes referenced by PV namespace, never registered as Assets. - [Andor, Kinetix, Marana, Manta, Zebra, ioLogik, MCTOptics-equivalent] - -resources: - intro: > - Continuously-available resources (the Supply BC) and the field-swappable parts. - Facility-scope supplies live in deployments/nsls2/site.yaml. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum # XF:18IDB-UT{V...} gate/cryo valves observed in source - - kind: LiquidNitrogen # DCM crystal cooling (XF:18IDA-UT Cryo:1; valves V4/V5) - - kind: Power - replaceable_parts: - swappable_with_identity: ["cameras", "zone plates", "scintillator", "objectives"] - passive: ["filter foils"] diff --git a/deployments/hex/beamline.yaml b/deployments/hex/beamline.yaml deleted file mode 100644 index 04d6ec6512f..00000000000 --- a/deployments/hex/beamline.yaml +++ /dev/null @@ -1,318 +0,0 @@ -# HEX beamline descriptor (NSLS-II), reverse-engineered -# -# HEX (High Energy Engineering X-ray Scattering) is the NSLS-II 27-ID beamline for -# engineering-materials and energy-storage science by high-energy X-ray imaging and -# tomography, energy-dispersive X-ray diffraction (EDXD), and angle-dispersive / -# powder diffraction (ADXD). It is bound to the NSLS-II Site (deployments/nsls2/ -# site.yaml). It is the fleet's first true high-energy hard X-ray beamline: a white -# beam of 30 to 250 keV and a monochromatic beam of 30 to 200 keV, from a -# superconducting wiggler. -# -# STATUS: reverse-engineered, design-phase. HEX is an operating beamline (the -# superconducting wiggler was commissioned in 2023 and user operations began in -# 2024), but CORA has not been connected to it and no HEX staff have confirmed this -# model. Every value is read from public open source (the BNL beamline page, the -# wiki-nsls2.bnl.gov/beamline27ID wiki, the github.com/NSLS2/hex-profile-collection -# and github.com/NSLS2/hextools repositories, and peer-reviewed superconducting- -# wiggler papers) or inferred, and is carried new: true + confirm: true pending HEX -# staff. A few EPICS PVs (the endstation detectors) are real and read from the -# profile collection; vendor part numbers, serials, FOE-optics PVs, and physical -# positions are not in it and are open questions. Same descriptor mode as CMS / SMI / -# ISS / FMX, the NSLS-II siblings: this scaffold is descriptor + docs, scenarios -# deferred. -# -# WHAT IS (AND IS NOT) NEW: HEX is mostly reinforcement. Its X-ray imaging and -# tomography overlap the fleet heavily (the 2-BM operational pilot and the NSLS-II -# FXI both do tomography), and its high-energy diffraction reuses the energy- -# dispersive and powder-diffraction shapes the fleet already debates as pending -# Methods (APS 7-BM EDD, Diamond i11 powder diffraction). It coins NO new Family and -# changes nothing in the catalog. HEX's three genuinely distinct contributions are: -# 1. Multi-technique-in-one-experiment. Imaging / tomography, EDXD, and ADXD are -# all available in the single operational endstation (the F-hutch) during the -# same experiment, with detectors and optics moved into place remotely per -# technique. This stresses the one-technique-per-acquisition assumption and the -# Controls seam (a technique switch is a positioning leg over the ControlPort), -# but it is modelled as multiple Methods over one endstation, not a new -# Capability (TECH-1). -# 2. Very large / heavy engineering samples. The sample tower carries up to 500 kg -# and is fully removable for custom in-situ / operando environments. The heavy -# reconfigurable fixture reuses the Table / RotaryStage / LinearStage families -# with capacity and configuration carried as settings; no HeavyStage Family is -# coined (STAGE-1). -# 3. A high-energy hard X-ray source. The superconducting wiggler (4.3 T, 70 mm -# period) reaching 200 keV monochromatic is a first for the fleet; it binds the -# existing InsertionDevice Family (the undulator precedent), the high field and -# energy reach carried as source specs (SCW-1). -# -# MODELLING: HEX coins NO new Family. The superconducting wiggler binds -# InsertionDevice; the low-energy filters bind Filter; the Si bent-Laue monochromator -# binds Monochromator (its in / out crystal selects monochromatic vs white beam) with -# the incident energy a PseudoAxis over it; the front-end slits bind Slit; the -# tomographic rotation binds RotaryStage and the sample translations LinearStage; the -# 500 kg removable sample tower binds Table; the Kinetix sCMOS and Phantom Veo cameras -# and the PerkinElmer flat panel bind Camera; the imaging scintillator-lens table -# binds Scintillator; the GeRM germanium strip detector binds the existing -# EnergyDispersiveSpectrometer Family (HEX is its third consumer, after the APS 2-ID -# fluorescence detector and the 7-BM germanium energy-dispersive-diffraction detector, -# a reuse not a graduation). The detector / optics positioning that switches technique -# binds LinearStage. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/hex/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "high-energy engineering X-ray scattering (imaging/tomography + energy-dispersive and powder diffraction on a superconducting wiggler, white 30-250 keV / mono 30-200 keV), 27-ID; the fleet's first true high-energy hard X-ray beamline; modelled from public beamline config" - name: HEX - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "27-ID" # PV zones XF:27ID1 (endstation) seen in the profile collection; FOE-optics zone is CTRL-1 - tier: Unit - parent: null - source: superconducting-wiggler - source_confirm: "superconducting wiggler (SCW), 4.3 T on-axis peak field, 70 mm period, 1.2 m device length, cell-27 low-beta straight on the 3 GeV NSLS-II ring; cryogen-free (no liquid helium); commissioned 2023. Pole count and critical photon energy are SCW-1" - page_layout: stages - shape: "A high-energy hard X-ray beamline (superconducting wiggler to 200 keV) running imaging, EDXD, and ADXD in one endstation on very large, heavy engineering samples." - source_ref: - label: "NSLS2/hex-profile-collection" - url: "https://github.com/NSLS2/hex-profile-collection" -# All six designed enclosures are declared, forward-looking. Two are operational and -# carry the device walk: the First Optics Enclosure (hex-foe, the A-hutch) and the -# F-hutch endstation (hex-endstation), in a satellite building adjacent to Bldg. 742, -# about 100 m from the source. The intermediate hutches B, C, D, and E are declared as -# device-free shells: B is designed but not erected, and C, D, and E are built for a -# future upgrade but not operational. They carry no devices in this cut (the operational -# beam path is FOE -> F-hutch); their exact positions, roles, and permit signals are -# open (ENC-1, SAT-1, LAYOUT-1, PSS-1). -enclosures: - - name: hex-foe - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS search-and-secure permit leaf not in the profile collection; the First Optics Enclosure (A-hutch), the filters and the monochromator (PSS-1)"} - - name: hex-b - role: future-hutch - facility_code: nsls2 - note: "B-hutch: designed but not erected; beam-guiding provisions made. A device-free forward-looking shell, no devices in this cut (ENC-1, LAYOUT-1)" - - name: hex-c - role: future-hutch - facility_code: nsls2 - note: "C-hutch: built for a future upgrade, not operational. A device-free forward-looking shell (ENC-1, LAYOUT-1)" - - name: hex-d - role: future-hutch - facility_code: nsls2 - note: "D-hutch: built for a future upgrade, not operational. A device-free forward-looking shell (ENC-1, LAYOUT-1)" - - name: hex-e - role: future-hutch - facility_code: nsls2 - note: "E-hutch: built for a future upgrade, not operational. A device-free forward-looking shell (ENC-1, LAYOUT-1)" - - name: hex-endstation - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; the operational F-hutch in the satellite building adjacent to Bldg. 742 (PSS-1, SAT-1)"} - -# =========================================================================== -# SOURCE STAGE: the machine state, the superconducting wiggler, and the FOE optics -# =========================================================================== - -machine: - stage: source - enclosure: hex-foe - intro: "The machine-level source state, observed not driven." - note: "Observe-only NSLS-II machine state, the loose StorageRing pattern reused from the NSLS-II siblings. The exact ring-state PVs are MACHINE-1." - devices: - - name: StorageRing - family: StorageRing # loose Family (machine-level observe-only source state; MACHINE-1) - pv: {confirm: "NSLS-II storage-ring state (current, fill, status); observe-only, the exact PVs are MACHINE-1"} - new: true - confirm: true - note: "NSLS-II 3 GeV storage-ring state; observe-only (MACHINE-1)" - -insertion-device: - stage: source - enclosure: hex-foe - intro: "The superconducting wiggler that delivers the high-energy white beam." - note: > - The superconducting wiggler binds the existing InsertionDevice Family (the - undulator precedent at the NSLS-II siblings). Its high field (4.3 T) and energy - reach (a useful spectrum from about 20 to 200 keV) are what make HEX a high-energy - beamline; the field, period, and length are confirmed from peer-reviewed papers, - but the pole count and critical photon energy are SCW-1. - devices: - - name: Wiggler - family: InsertionDevice - pv: {confirm: "the superconducting wiggler gap / field handle; not in the profile collection (SCW-1, CTRL-1)"} - new: true - confirm: true - note: "superconducting wiggler (SCW): 4.3 T on-axis, 70 mm period, 1.2 m, cell 27; cryogen-free; delivers the 30 to 250 keV white spectrum; pole count and critical energy are SCW-1" - -foe-optics: - stage: source - enclosure: hex-foe - intro: "The low-energy filters that harden the white beam, the bent-Laue monochromator that selects energy (or retracts for white beam), the incident-energy axis, and the front-end defining slits." - note: > - The low-energy filters bind Filter; the monochromator binds Monochromator (a Si - bent-Laue Bragg optic, not the soft X-ray GratingMonochromator), and inserting or - retracting its first crystal selects monochromatic versus white beam, so the beam - mode is a setting on the optic, not a second source (MONO-2). The incident energy - is a PseudoAxis over the monochromator (the 2-BM / CMS beam-energy pattern). The - front-end slits bind Slit. The focusing optic for the monochromatic beam is "being - commissioned" on the official beamline page and is not yet modelled as a device - (FOCUS-1). - devices: - - name: BeamFilters - family: Filter - pv: {confirm: "the FOE low-energy filter / absorber positions (per-branch SiC and Cu); not in the profile collection (FILT-1, CTRL-1)"} - new: true - confirm: true - note: "the FOE low-energy (beam-hardening) filters: center-branch SiC (3 / 6 / 9 / 12 mm) and outboard / inboard Cu (0.5 to 2 mm) plus SiC (12 / 24 mm) on a 35 mm pitch; the materials and thicknesses are FILT-1" - - name: Monochromator - family: Monochromator - pv: {confirm: "the monochromator crystal Bragg / translation handle (a Phytron VSS-42 stepper drives the crystal in / out); not in the profile collection (MONO-1, CTRL-1)"} - new: true - confirm: true - note: "the bent-Laue monochromator: a single first crystal (Si(111) bent Laue, MONO-1) on a vertical translation, inserted for the 30 to 200 keV monochromatic beam and retracted for the 30 to 250 keV white beam; the crystal material / geometry are MONO-1 and the 200 keV upper bound is MONO-2" - - name: BeamEnergy - family: PseudoAxis - pv: {confirm: "incident-energy virtual axis over the monochromator (lambda = 2 d sin(Bragg)); the d-spacing and partition rule are MONO-1 / MONO-2"} - new: true - confirm: true - note: "incident-energy pseudo-axis over the monochromator (the 2-BM / CMS beam-energy pattern); the 30 to 200 keV monochromatic range is MONO-2" - - name: FoeSlit - family: Slit - pv: {confirm: "the front-end defining slits (a center, inboard, and outboard branch); not in the profile collection (BRANCH-1, CTRL-1)"} - new: true - confirm: true - note: "the front-end defining slits; the beam has a center branch and inboard / outboard branches reserved for the future-hutch upgrade, only the center branch is presently in use (BRANCH-1)" - -# =========================================================================== -# SAMPLE STAGE: the heavy reconfigurable sample tower, the tomographic rotation, -# and the sample translations, in the F-hutch endstation -# =========================================================================== - -sample: - stage: sample - enclosure: hex-endstation - intro: "The reconfigurable sample tower (up to 500 kg, fully removable), the tomographic rotation, and the sample translations." - note: > - The tomographic rotation binds RotaryStage and the sample translations LinearStage - (the 2-BM tomography pattern). The 500 kg removable sample tower binds Table; its - load capacity and the configuration set (configs A to D, with interface plates) are - carried as settings, not a new HeavyStage Family (STAGE-1). No in-situ rig (load - frame, furnace, cryostat, battery cycler) is modelled: the endstation is "capable - of housing" user-brought environments but no specific rig is source-confirmed as - installed (INSITU-1). - devices: - - name: SampleTower - family: Table - pv: {confirm: "the modular sample tower / support stage (configs A to D, interface plates); not in the profile collection (STAGE-1, CTRL-1)"} - new: true - confirm: true - note: "the reconfigurable sample tower: up to 500 kg, fully removable for custom in-situ / operando environments, configurable (configs A to D) with interface plates; capacity and config set are STAGE-1" - - name: SampleRotation - family: RotaryStage - pv: {confirm: "the tomographic rotation axis driven by the bluesky tomo_flyscan / tomo_loop plans; the PV is CTRL-1"} - new: true - confirm: true - note: "the tomographic rotation axis (continuous fly-rotation for CT and stepped for diffraction); the axis map is STAGE-1" - - name: SampleStage - family: LinearStage - pv: {confirm: "the sample x / y / z translations (tomo_y_scan_loop drives the vertical); the PVs are CTRL-1"} - new: true - confirm: true - note: "the sample translations (x / y / z) that position the specimen and gauge volume in the beam; the axis map is STAGE-1" - -# =========================================================================== -# DETECTION STAGE: the imaging / tomography cameras, the high-energy diffraction -# detectors (energy-dispersive and area), and the technique-switch positioning -# =========================================================================== - -detection: - stage: detection - enclosure: hex-endstation - intro: "The Kinetix sCMOS imaging / tomography cameras and their scintillator-lens table, the Phantom Veo high-speed camera, the PerkinElmer flat panel for angle-dispersive diffraction, the GeRM germanium strip detector for energy-dispersive diffraction, and the detector / optics positioning that switches technique." - note: > - The sCMOS and high-speed cameras and the flat panel bind Camera; the imaging - scintillator-lens table binds Scintillator; the GeRM germanium strip detector binds - the existing EnergyDispersiveSpectrometer Family (HEX is its third consumer, a - reuse). The detector / optics positioning that moves a detector into the beam per - technique binds LinearStage; it is the mechanism behind HEX's multi-technique-in- - one-experiment endstation (the technique switch is a positioning leg, not a new - Capability). The PerkinElmer's role as the angle-dispersive (ADXD) detector is an - inference (DET-1). - devices: - - name: ImagingCamera - family: Camera - pv: "XF:27ID1-BI{Kinetix-Det:1}" - new: true - confirm: true - note: "the Teledyne Photometrics Kinetix sCMOS cameras for imaging / tomography (kinetix1 default, kinetix3 alternate; PV root XF:27ID1-BI{Kinetix-Det:N}, HEXKinetixDetector); the default-camera and frame details are DET-3" - - name: ImagingScintillator - family: Scintillator - pv: {confirm: "the imaging scintillator-lens table (magnification positions '2 & 4 mm', '20 & 40 mm', 'Dual cam'); the PV is CTRL-1 and the scintillator / lens set is DET-3"} - new: true - confirm: true - note: "the scintillator-lens imaging table that converts the X-ray image for the sCMOS cameras; magnification positions read '2 & 4 mm', '20 & 40 mm', and 'Dual cam', the scintillator and lens set is DET-3" - - name: HighSpeedCamera - family: Camera - pv: {confirm: "the Phantom (Vision Research) Veo high-speed camera (hextools/detectors/phantom.py); the PV is CTRL-1"} - new: true - confirm: true - note: "the Phantom Veo high-speed camera for fast / time-resolved radiography (DET-3)" - - name: FlatPanelDetector - family: Camera - pv: "XF:27ID1-ES{PE-Det:1}" - new: true - confirm: true - note: "the PerkinElmer XRD1621 amorphous-silicon flat-panel area detector (HEXPerkinElmer); inferred to be the angle-dispersive / powder diffraction (ADXD) detector, the model and role are DET-1" - - name: EnergyDispersiveDetector - family: EnergyDispersiveSpectrometer - pv: "XF:27ID1-ES{GeRM-Det:1}" - new: true - confirm: true - note: "the GeRM germanium strip detector for energy-dispersive X-ray diffraction (EDXD), controlled via Phoebus (run-phoebus) with caput thresholds and the edxd_viewer GUI; the third consumer of the existing EnergyDispersiveSpectrometer Family; channel count, energy resolution, and EDXD gauge-volume dimensions are DET-2" - - name: DetectorStage - family: LinearStage - pv: {confirm: "the detector / optics positioning that moves a detector into the beam per technique; the PV is CTRL-1"} - new: true - confirm: true - note: "the remote detector / optics positioning that switches technique in the single endstation (imaging, EDXD, or ADXD into the beam); the positioning leg behind HEX's multi-technique-in-one-experiment endstation (TECH-1, DET-1)" - -# Cross-cutting control. HEX runs EPICS (the floor); CORA observes and, where it -# replaces bluesky-style orchestration, conducts over it. The handles above were read -# from the profile collection and carried confirm (CTRL-1). -controls: - intro: > - HEX runs on the NSLS-II EPICS / ophyd control stack, the same floor as the other - NSLS-II beamlines. The endstation detector handles above are bound from the - beamline's bluesky profile collection (github.com/NSLS2/hex-profile-collection, - its startup/*.py files: 10-kinetix.py, 11-perkin-elmer.py) and the hextools - package, carried confirm pending staff verification (CTRL-1). The FOE-optics PVs - are not in the profile collection and are carried confirm. The HEX acquisition (the - tomo_flyscan / tomo_dark_flat / tomo_loop / tomo_y_scan_loop tomography plans, the - diffraction acquisition, and the technique switch that repositions detectors and - optics) runs through bluesky plans driven from a queue server (run-qserver-gui); - that orchestration is the seam CORA's edge replaces, driving through ophyd / EPICS. - The area-detector and tomography file-writing to the NSLS-II filestore is plumbing - CORA observes, not data it owns (see model.md). The motion layer (Phytron and Delta - Tau PowerBrick controllers) and the fly-scan triggering that gates tomography are - observed, not modelled as devices, until their per-axis functional map is confirmed; - no controller instance is invented from the vendor names alone (CTRL-1). - software_iocs_not_modeled: - - "bluesky + queue server (run-qserver-gui): the acquisition orchestration CORA's edge replaces" - - "CS-Studio / Phoebus (run-css, run-phoebus): the operator GUI layer" - - "Phytron and Delta Tau PowerBrick motion controllers: the motion layer, observed not modelled (functional map is CTRL-1)" - - "fly-scan triggering (for tomo_flyscan): the position / time triggering, observed not modelled (CTRL-1)" - - "Moxa ioLogik relays: discrete I/O, observed not modelled" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a HEX run needs. The FOE optics run - under vacuum, and the superconducting wiggler is cryogen-free, so no liquid-helium - supply is drawn (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the FOE optics (filters, monochromator) run under vacuum (SUP-1)" diff --git a/deployments/hxn/beamline.yaml b/deployments/hxn/beamline.yaml deleted file mode 100644 index d2b1cf35f70..00000000000 --- a/deployments/hxn/beamline.yaml +++ /dev/null @@ -1,272 +0,0 @@ -# HXN beamline descriptor (NSLS-II), reverse-engineered -# -# HXN (Hard X-ray Nanoprobe) is the NSLS-II scanning nanoprobe at sector 3-ID: -# nano-XRF mapping, ptychography, nano-tomography, and spectro-tomography, all by -# rastering a focused spot (zone plate or multilayer Laue lens) across the sample -# and reading multiple detectors per dwell point. It is bound to the NSLS-II Site -# (deployments/nsls2/site.yaml), the second NSLS-II beamline after FXI. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the bluesky profile collection NSLS2/hxn-profile-collection) or inferred, -# carried `new: true` + `confirm: true` pending HXN staff. EPICS PVs are real and -# verified against the profile collection; vendor part numbers, serials, and -# physical z positions are not in it and are open questions. Same descriptor mode -# as FXI; this scaffold is descriptor + docs, scenarios deferred. -# -# HXN's defining new shape vs FXI (full-field TXM) is SCANNING-PROBE acquisition: -# the position axes ARE the scan, and a fluorescence detector, a pixel detector -# (ptychography), and flux counters are read together per point. The scanning and -# ptychography Capabilities are deliberately NOT coined yet (the Diamond/32-ID -# precedent: defer until a raster conduct-path consumes them); see questions.md. -# -# The multilayer Laue lens (MLL) is a loose family `MultilayerLaueLens` (FXI-only- -# equivalent: HXN is its first and only sighting), distinct from ZonePlate (a 1D -# linear-zone crossed pair, not a 2D circular Fresnel optic). - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "scanning hard X-ray nanoprobe (nano-XRF, ptychography, nano-tomography), 3-ID; modelled from public beamline config" - name: HXN - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "Sector 3" # PV namespace XF:03ID* - tier: Unit - parent: null - source: insertion-device - source_confirm: "IVU20 in-vacuum undulator (SR:C3-ID:G1{IVU20:1}), verified in source; period/gap parameters not fully in the profile collection (SRC-1)" - page_layout: stages - shape: "A scanning probe: a zone plate or multilayer Laue lens focuses the beam to a nano-spot and the sample is rastered through it, several detectors read per dwell point." - source_ref: - label: "NSLS2/hxn-profile-collection" - url: "https://github.com/NSLS2/hxn-profile-collection" - -enclosures: - # Three PV zones: 3-ID-A optics, 3-ID-B intermediate (secondary-source aperture, - # slow shutter, PPS), 3-ID-C endstation. Modelled as optics + experiment hutches; - # whether 3-ID-B is a distinct enclosure is a staff question (ENC-1). - - name: 3-ID-A - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS search-and-secure permit leaf not in source; the photon shutter is XF:03IDB-PPS{PSh} (PSS-1)"} - - name: 3-ID-C - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; the XF:03IDB intermediate zone (SSA1, slow shutter) may be a distinct enclosure (ENC-1)"} - -# =========================================================================== -# SOURCE STAGE: the undulator, monochromator, mirrors, and beam-defining slits -# =========================================================================== - -source: - stage: source - enclosure: 3-ID-A - intro: The in-vacuum undulator source. - devices: - - name: Source - family: InsertionDevice - pv: "SR:C3-ID:G1{IVU20:1" - confirm: true - note: "IVU20 in-vacuum undulator (ophyd InsertionDevice, instance ugap); gap-driven. Period/field parameters pending (SRC-1)." - -optics: - stage: source - enclosure: 3-ID-A - intro: "Condition the beam and set its energy: the double-crystal monochromator, three mirrors, and the white-beam slits. PVs verified against startup/10-optics.py." - devices: - - name: Monochromator - family: Monochromator - pv: "XF:03IDA-OP{Mon:1" - axis_channels: { Bragg: "XF:03IDA-OP{Mon:1-Ax:Bragg}Mtr" } - confirm: true - note: "Double-crystal monochromator (class HxnDCM, instance dcm). Energy is the EnergyAxis pseudo-axis below (monoe), which drives Bragg; crystal cut and range pending (DCM-1)." - - name: CollimatingMirror - family: Mirror - pv: "XF:03IDA-OP{HCM:1" - confirm: true - note: "Horizontal collimating mirror (class HxnMirror1, HCM:1)." - - name: FocusingMirror - family: Mirror - pv: "XF:03IDA-OP{HFM:1" - confirm: true - note: "Horizontal focusing mirror (class HxnMirror2, HFM:1), with a pitch-feedback axis." - - name: VerticalMirror - family: Mirror - pv: "XF:03IDA-OP{VMS:1" - axis_channels: { Y: "XF:03IDA-OP{VMS:1-Ax:Y}Mtr", P: "XF:03IDA-OP{VMS:1-Ax:P}Mtr", TX: "XF:03IDA-OP{VMS:1-Ax:TX}Mtr" } - confirm: true - note: "Vertical mirror system (class HxnVMS, VMS:1); bend/pitch/translation axes." - - name: WhiteBeamSlit - family: Slit - pv: "XF:03IDA-OP{Slt:1" - confirm: true - note: "First white-beam-defining slit (class HxnSlitA1, instance s1); a second slit s2 sits at XF:03IDA-OP{Slt:2}." - - name: EnergyAxis - family: PseudoAxis - confirm: true - note: "The master energy pseudo-axis (class PseudoEnergyMotor, instance monoe). Driving it sets the monochromator Bragg angle; an energy change co-moves the zone-plate refocus per element (see techniques.md, ENERGY-1)." - - name: BeamPositionMonitor - family: GenericProbe - pv: "XF:03IDA-BI{Slt:1}" - confirm: true - note: "Beam-position / intensity diagnostics (class HxnI400, instance s1_bpm) plus bpm1..bpm5 stages; read-only." - -intermediate: - stage: source - enclosure: 3-ID-C - intro: The secondary-source aperture that defines the coherent probe, plus the photon shutter. - devices: - - name: SecondarySourceAperture - family: Slit - pv: "XF:03IDB-OP{Slt:SSA1" - confirm: true - note: "Secondary-source aperture (class HxnSSAperture, instance ssa1) defining the coherence-matched source; a second SSA2 sits at XF:03IDC-OP{Slt:SSA2}." - - name: PhotonShutter - family: Shutter - pv: "XF:03IDB-PPS{PSh}" - confirm: true - note: "PPS slow photon shutter (instance bshutter). The fast shutter is on the Zebra (Zeb:2). PPS permit leaf pending (PSS-1)." - -# =========================================================================== -# SAMPLE STAGE: the two focusing optics (zone plate, MLL), their order-sorting -# apertures and beamstops, and the nano-positioning sample stack. -# =========================================================================== - -sample: - stage: sample - enclosure: 3-ID-C - intro: "The focusing optics that form the nano-spot and the sample stack rastered through it. PVs verified against startup/13-mll.py and 15-zp.py." - note: > - HXN runs two interchangeable focusing optics: a Fresnel zone plate and a - crossed multilayer-Laue-lens pair. Whether both are permanently installed and - operator-selected or one is decommissioned is a staff question (OPTIC-1). - devices: - - name: ZonePlate - family: ZonePlate - pv: "XF:03IDC-ES" - confirm: true - note: "Fresnel zone-plate objective (class HxnZonePlate, instance zp); the lab-frame sample axes are the FineSampleLabX pseudo-axes (zplab). Outer-zone width / diameter pending (OPTIC-2)." - - name: ZonePlateAperture - family: Aperture - pv: "XF:03IDC-ES{ANC350:5" - axis_channels: { x: "XF:03IDC-ES{ANC350:5-Ax:0}Mtr", y: "XF:03IDC-ES{ANC350:5-Ax:1}Mtr", z: "XF:03IDC-ES{ANC350:5-Ax:2}Mtr" } - confirm: true - note: "Order-sorting aperture for the zone plate (class HxnZP_OSA, instance zposa)." - - name: ZonePlateBeamStop - family: BeamStop - pv: "XF:03IDC-ES{ANC350:8" - confirm: true - note: "Central beam stop for the zone plate (class HxnZPBeamStop, instance zpbs)." - - name: MLL_Vertical - family: MultilayerLaueLens - pv: "XF:03IDC-ES" - new: true - confirm: true - note: "Vertical multilayer Laue lens (class HxnVerticalMLL, instance vmll). Loose family: HXN is the only sighting, distinct from ZonePlate (1D linear-zone lens, run as a crossed pair) (OPTIC-3)." - - name: MLL_Horizontal - family: MultilayerLaueLens - pv: "XF:03IDC-ES" - new: true - confirm: true - note: "Horizontal multilayer Laue lens (class HxnHorizontalMLL, instance hmll); the crossed partner of MLL_Vertical for 2D focus." - - name: MLLAperture - family: Aperture - pv: "XF:03IDC-ES" - confirm: true - note: "Order-sorting aperture for the MLL (class HxnMLL_OSA, instance mllosa)." - - name: SampleStage - family: LinearStage - pv: "XF:03IDC-ES{Ppmac:1" - axis_channels: { ssx: "XF:03IDC-ES{Ppmac:1-ssx}Mtr", ssy: "XF:03IDC-ES{Ppmac:1-ssy}Mtr", ssz: "XF:03IDC-ES{Ppmac:1-ssz}Mtr" } - confirm: true - note: "Fine sample raster stage (class HxnMLLSample, instance smll): piezo ssx/ssy/ssz on the Power PMAC. These fine axes ARE the scan trajectory in a fly2d map. Coarse axes sit on ANC350:3/4." - - name: SampleRotary - family: RotaryStage - pv: "XF:03IDC-ES{ANC350:1-Ax:0}Mtr" - trigger_source: PSO - confirm: true - note: "Tomographic rotation (sth, theta) on an Attocube ANC350; combined with the raster for nano-tomography. Hardware/encoder pending (STAGE-1)." - - name: SamplePod - family: Hexapod - pv: "XF:03IDC-ES" - confirm: true - note: "SmarAct Smarpod 6-DOF parallel-kinematics sample pod (class SmarpodBase, single coordinated move); reuses the Hexapod family. Confirm Smarpod-to-Hexapod fit (STAGE-2)." - -# =========================================================================== -# DETECTION STAGE: the per-point detectors read simultaneously during a scan. -# =========================================================================== - -detector: - stage: detection - enclosure: 3-ID-C - intro: "The detectors read per dwell point: a fluorescence spectrometer (XRF), pixel detectors (ptychography / diffraction), and flux counters. PVs verified against startup/20-detectors.py, 20-eiger.py, 21-xspress3.py." - note: > - A scanning-probe measurement reads several of these at once: the - EnergyDispersiveSpectrometer for element maps, a Camera pixel detector for - ptychography or diffraction, and the flux counters for normalization. Which - detectors are live vs dormant duplicates is a staff question (CAM-1). - devices: - - name: FluorescenceSpectrometer - family: EnergyDispersiveSpectrometer - pv: "XF:03IDC-ES{Xsp:1}:" - confirm: true - note: "Xspress3 energy-dispersive fluorescence detector (4 channels C1-C4), the XRF-mapping detector; presents the Sensor Role. A second unit xspress3_mk2 is at XF:03IDC-ES{Xsp:2}. Vendor (Quantum Detectors) and element count pending (DET-1)." - - name: MerlinDetector - family: Camera - pv: "XF:03IDC-ES{Merlin:1}" - confirm: true - note: "Merlin pixel detector (class HxnMerlinDetector, instance merlin1) for ptychography / coherent diffraction; a second merlin2 is at {Merlin:2}. Reuses Camera (the Diamond Eiger->Camera precedent)." - - name: EigerDetector - family: Camera - pv: "XF:03IDC-ES{Det:Eiger1M}" - confirm: true - note: "Eiger 1M pixel detector (class HxnEigerDetector, instance eiger1) for ptychography." - - name: DexelaDetector - family: Camera - pv: "XF:03IDC-ES{Dexela:1}" - confirm: true - note: "Dexela flat-panel detector (class HxnDexelaDetector, instance dexela1) for wide-field diffraction." - - name: FluxCounter - family: GenericProbe - pv: "XF:03IDC-ES{Sclr" - confirm: true - note: "Scaler-counted ion-chamber / diode flux channels (sclr1..sclr3) for per-point normalization; read-only Sensor-side. Exact channel map pending (DIAG-1)." - -# =========================================================================== -# Cross-cutting controls -# =========================================================================== - -controls: - intro: > - The trigger box and the motion controllers. Unlike FXI, HXN exposes its - controllers in the profile collection (PMAC, Attocube ANC350), so they are - modelled as families here; box models / serials / IP remain pending (DRIVE-1). - triggering: - - name: Zebra - family: TimingController - pv: "XF:03IDC-ES{Zeb:3}:" - trigger_source: PSO - confirm: true - note: "Zebra FPGA position-capture box (class SRXZebra, instance nanoZebra) gating the per-point detector triggers during a fly raster. A fast shutter sits on a second Zebra (Zeb:2). A PandABox is being introduced (67-nano-panda) and is carried deferred (ZEBRA-1)." - - name: SampleMotionController - family: MotionController - pv: "XF:03IDC-ES{Ppmac:1" - confirm: true - note: "Power PMAC driving the fine raster axes (class, instance Ppmac:1) plus HxnTurboPmacController boxes MC:2-MC:8. Box model/firmware pending (DRIVE-1)." - - name: NanoPositioningController - family: MotionController - pv: "XF:03IDC-ES{ANC350" - confirm: true - note: "Attocube ANC350 controllers (ANC350:1-8) driving the coarse nano-positioning, OSAs, and beam stops. Eight units; model confirmed Attocube, firmware/serials pending (DRIVE-1)." - software_iocs_not_modeled: - [Merlin, Eiger, Dexela, Xspress3, Zebra, PandA, MCS] - -resources: - intro: Continuously-available resources. Facility-scope supplies live in deployments/nsls2/site.yaml. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: Power - replaceable_parts: - swappable_with_identity: ["zone plate", "MLL optics", "pixel detectors"] diff --git a/deployments/i-tomcat/beamline.yaml b/deployments/i-tomcat/beamline.yaml deleted file mode 100644 index 999f4a3730d..00000000000 --- a/deployments/i-tomcat/beamline.yaml +++ /dev/null @@ -1,270 +0,0 @@ -# CORA Beamline descriptor: I-TOMCAT (Swiss Light Source), modelled from design -# -# I-TOMCAT (X02SA) is the insertion-device tomographic-microscopy beamline of the -# rebuilt TOMCAT at the Swiss Light Source (SLS 2.0, Paul Scherrer Institut). It -# is bound to the PSI Site (deployments/psi/site.yaml), CORA's FOURTEENTH Site. Under -# SLS 2.0 the single legacy TOMCAT beamline was split into two: I-TOMCAT (X02SA, -# undulator, this file) and S-TOMCAT (X02DA, 5 T superbend; not modelled here). -# I-TOMCAT is the closest analog to the APS 2-BM micro-CT pilot. -# -# STATUS: off-roadmap modelling exercise, MODELLED FROM DESIGN REPORTS (the -# TomoWISE tradition), not reverse-engineered. No public per-beamline controls -# config exists for TOMCAT (the BEC beamline plugins live on the internal -# gitea.psi.ch); the public ophyd_devices examples cover sibling beamlines -# (cSAXS X12SA, PXIII X06DA) only. So every value here is read from PSI's public -# TOMCAT pages or the SLS 2.0 design reports and carried new: true (not yet -# modelled in CORA) + confirm: true (value to be verified by PSI staff). Some -# optics values are LEGACY TOMCAT specs whose validity for the rebuilt SLS 2.0 -# beamline is itself an open question (MONO-1 / OPT-1). -# -# Control handles are omitted on purpose: SLS runs EPICS at the floor, but the -# TOMCAT EPICS PV prefix scheme is not public and the BEC ophyd device manifest -# is internal, so no `pv` field is invented (CTRL-1). Devices bind to catalog -# Families only, with no `model`, because the vendor part numbers read from the -# public pages (Aerotech ABRX150, pco.edge / pco.dimax, the PSI GigaFRoST camera) -# are not yet catalog Models; they are carried as "(target)" in the notes and as -# open questions, not bindings. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/i-tomcat/questions.md. - -beamline: - maturity: model - evidence: design_report - coverage: full - summary: "insertion-device tomographic microscopy (absorption + propagation phase contrast + dynamic 4D CT on the PSI GigaFRoST camera), X02SA; the SLS 2.0 undulator half of the rebuilt TOMCAT, CORA's micro-CT analog of APS 2-BM" - name: I-TOMCAT - facility: psi # PSI Site (facility_code: psi) - sector: "X02SA" - tier: Unit - parent: null - source: insertion-device - source_confirm: "I-TOMCAT is the undulator branch of the rebuilt TOMCAT; the U15 undulator drives it, with a planned source upgrade to HTSU10 in 2027 (SRC-1)" - z_span_mm: [0, 35000] - z_span_confirm: true - page_layout: stages - shape: "A PSI SLS 2.0 undulator micro-CT beamline (absorption and phase-contrast, fast 4D tomography on the GigaFRoST camera), the closest SLS analog to the APS 2-BM pilot; modelled from its design report." - -# Two access-gated hutches: the shared optics hutch and the I-TOMCAT experiment -# hutch (endstation ES2, ~33 m from source). The PSS permit-signal handles are -# not public (PSS-1); the exact hutch grouping and the X02SA code reassignment -# to the rebuilt I-TOMCAT are carried confirm (ENC-1). -enclosures: - - name: i-tomcat-optics - role: optics-hutch - facility_code: psi - permit_signal: {confirm: "SLS PSS permit signal not public; the shared TOMCAT optics zone (PSS-1, ENC-1)"} - - name: i-tomcat-experiment - role: experiment-hutch - facility_code: psi - permit_signal: {confirm: "SLS PSS permit signal not public; the I-TOMCAT (X02SA) endstation hutch (PSS-1, ENC-1)"} - -# =========================================================================== -# SOURCE STAGE: the machine state, the U15 undulator, the optics -# =========================================================================== - -machine: - stage: source - enclosure: i-tomcat-optics - intro: "The machine-level source state, observed not driven." - note: "The SLS 2.0 storage-ring state, the loose StorageRing pattern reused across the fleet (MACHINE-1)." - devices: - - name: StorageRing - family: StorageRing # loose Family (machine-level observe-only source state; MACHINE-1) - new: true - confirm: true - note: "SLS 2.0 storage-ring state (current, fill); observe-only, the exact handles are MACHINE-1" - -insertion-devices: - stage: source - enclosure: i-tomcat-optics - intro: "The U15 undulator, the variable-gap hard X-ray source feeding the monochromatic tomography endstation." - note: "The U15 undulator binds the catalog InsertionDevice; gap is a setting tracked with the monochromator energy. A source upgrade to HTSU10 is planned for 2027 (SRC-1)." - devices: - - name: Undulator - family: InsertionDevice - new: true - confirm: true - device_type: undulator - note: "the U15 undulator (planned HTSU10 upgrade in 2027); period and gap range read confirm pending staff (SRC-1)" - -optics: - stage: source - enclosure: i-tomcat-optics - intro: "The fixed-exit double-crystal multilayer monochromator, the focusing mirrors, the diamond window, and the filter batteries that condition the beam delivered to the experiment hutch." - note: > - The DCMM binds Monochromator (the GratingMonochromator sibling is for soft - X-ray; this is a hard X-ray multilayer mono). The optics specs below are LEGACY - TOMCAT values whose validity for the rebuilt SLS 2.0 beamline is an open question - (MONO-1); the focusing mirrors are not exposed on the public pages and are - deferred not invented (OPT-1). - devices: - - name: Monochromator - family: Monochromator - new: true - confirm: true - device_type: double-crystal-multilayer-monochromator - energy_range: 8 to 50 keV (8-30 keV recommended until the HTSU10 source upgrade) - bandwidth: "multilayer stripes 2-3%; Si(111) 0.018% (legacy spec, MONO-1)" - note: "fixed-exit DCMM ~7 m from source; multilayer stripes [Ru/C]x100 and [W/Si]x100 on Si(111), active area 150x50 mm2 (legacy TOMCAT spec; validity for the rebuilt beamline is MONO-1)" - - name: DiamondWindow - family: Window - new: true - confirm: true - material: 100 um CVD diamond - note: "CVD diamond vacuum window (legacy spec, MONO-1)" - - name: BeamFilter - family: Filter - new: true - confirm: true - note: "the filter batteries (legacy: five batteries, 10 um Cu to 400 um Al); the rebuilt-beamline filter set is MONO-1" - - name: FocusingMirror - family: Mirror - new: true - confirm: true - note: "the hard X-ray focusing / harmonic-rejection mirror(s); not exposed on the public TOMCAT pages for the rebuilt beamline, deferred not invented (OPT-1)" - - name: BeamSlit - family: Slit - new: true - confirm: true - note: "the beam-defining slits ahead of the endstation; handles and blade-axis map are OPT-2" - -safety-shutters: - stage: source - enclosure: i-tomcat-optics - intro: "The safety shutter gating the beam between the optics hutch and the I-TOMCAT experiment hutch." - note: "PSS permit signals are not public (PSS-1)." - devices: - - name: SafetyShutter - family: Shutter - new: true - confirm: true - note: "the optics-to-experiment safety shutter; permit interlock handle is PSS-1" - -# =========================================================================== -# SAMPLE STAGE: the I-TOMCAT endstation (ES2), ~33 m from source -# =========================================================================== - -sample-environment: - stage: sample - enclosure: i-tomcat-experiment - intro: "The I-TOMCAT endstation (ES2), about 33 m from the source: the air-bearing rotation stage, sample positioning, the continuous-rotation slip ring, and the sample-side fast shutter. The maximum field of view is about 1.5 x 1.5 mm2." - note: > - The rotation stage binds RotaryStage; the Aerotech ABRX150 read from the public - endstations page is carried as a (target) model pending procurement confirmation - (STAGE-1). The positioning stack axis set is not public and is carried confirm - (SAMPLE-1). - devices: - - name: Rotary - family: RotaryStage - new: true - confirm: true - max_speed: ~1500 deg/s - model_target: Aerotech ABRX150 (STAGE-1) - note: "the air-bearing tomographic rotation stage at ES2 (~33 m); the master clock for triggering (TRIG-1). The (target) ABRX150 is read from the public endstations page, carried pending confirmation (STAGE-1)" - - name: SamplePositioning - family: LinearStage - new: true - confirm: true - note: "the sample centring / translation stage on the rotation stage; the exact axis set and handles are SAMPLE-1" - - name: SlipRing - family: SlipRing # loose Family (rotation-stage feedthrough; a Positioner component, not a standalone Asset) - new: true - confirm: true - note: "the continuous-rotation feedthrough for endless tomographic acquisition; channel count is SAMPLE-1" - - name: FastShutter - family: Shutter - new: true - confirm: true - note: "the sample-side fast shutter limiting dose between projections; model is SAMPLE-1" - -# =========================================================================== -# DETECTION STAGE: the microscope + high-speed camera suite -# =========================================================================== - -detector: - stage: detection - enclosure: i-tomcat-experiment - intro: "The detector suite: a visible-light microscope (interchangeable objectives over a scintillator) coupling the X-ray image to a suite of high-speed cameras, including the PSI in-house GigaFRoST continuous-streaming camera that defines I-TOMCAT's fast and dynamic tomography." - note: > - The microscope binds Housing with Objective + Scintillator constituents (the - 2-BM / TomoWISE Microscope-assembly precedent), but no catalog Assembly or Model - is bound here pending confirmation of the rebuilt-beamline optics (DET-2). The - cameras bind Camera; their vendor models (pco.edge family, pco.dimax, the PSI - GigaFRoST) are carried as (target) pending confirmation (DET-1). - devices: - - name: Microscope - family: Housing - new: true - confirm: true - magnification: 1x to 40x (six optical microscopes, legacy) - note: "the visible-light microscope coupling the scintillator image to the cameras; optics model and the catalog-Assembly composition are deferred pending confirmation (DET-2)" - constituents: - - name: Objective - family: Objective - new: true - confirm: true - note: "the interchangeable microscope objective(s) spanning 1x to 40x; per-lens identity and selector are DET-2" - - name: Scintillator - family: Scintillator - new: true - confirm: true - material: LSO:Tb or LuAG:Ce - note: "the scintillator converting X-rays to visible light (legacy: LSO:Tb 5.9 um sub-um res; LuAG:Ce 20 um most used); the rebuilt-beamline set is DET-2" - - name: HighSpeedCamera - family: Camera - new: true - confirm: true - sensor: 2016x2016, 11 um pixel - framerate: up to 1255 fps - model_target: pco.dimax (DET-1) - note: "the high-speed CMOS camera for fast tomography; (target) pco.dimax read from the public detectors page, carried pending confirmation (DET-1)" - - name: StreamingCamera - family: Camera - new: true - confirm: true - sensor: 2016x2016, 11 um pixel - framerate: up to 1255 fps continuous (~8 GB/s streaming) - model_target: GigaFRoST (PSI in-house) (DET-1) - note: "the PSI in-house GigaFRoST continuous-streaming camera that defines I-TOMCAT's dynamic 4D tomography (up to ~33,875 Hz reduced ROI); (target) model carried pending confirmation (DET-1)" - - name: ScienceCamera - family: Camera - new: true - confirm: true - model_target: pco.edge family (4.2 / 5.5 / 10) (DET-1) - note: "the general-throughput sCMOS camera(s); (target) pco.edge family read from the public detectors page, carried pending confirmation (DET-1)" - -# Cross-cutting control. SLS runs EPICS at the floor with the BEC (Beamline and -# Experiment Control) scan/orchestration layer over ophyd for SLS 2.0. The TOMCAT -# EPICS PV handles are not public and the BEC beamline plugin is internal, so the -# device handles above are left empty (CTRL-1). -controls: - intro: > - I-TOMCAT runs on the SLS EPICS control stack at the floor ("control of the - beamline and experiment is fully implemented in EPICS"), with the BEC (Beamline - and Experiment Control, bec-project) microservice scan/orchestration layer over - ophyd introduced for SLS 2.0. The TOMCAT EPICS PV prefix scheme is not public - and the per-beamline BEC ophyd device manifest lives on the internal - gitea.psi.ch, so the device handles above are left empty pending staff - verification (CTRL-1). The tomographic acquisition (the rotation trajectories, - the camera streaming, the energy moves) runs through BEC; that orchestration is - the seam CORA's edge replaces, conducting over EPICS rather than replacing it - (the BEC replace-vs-drive-through boundary is SEAM-1). The camera file-writing - to the PSI data store and the Ra/SLURM reconstruction pipeline (Fiji Reco - Manager) are plumbing CORA observes, not data it owns (see model.md). - triggering: - - name: Triggering - family: TimingController - new: true - confirm: "the air-bearing Rotary is expected to be the master clock feeding the camera triggers; the exact trigger/sync hardware is not public (TRIG-1)" - note: "trigger / sync scheme (TRIG-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources an I-TOMCAT run needs present - before it can start. All pending confirmation in this modelling exercise. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/i03/beamline.yaml b/deployments/i03/beamline.yaml deleted file mode 100644 index ec0562b47f7..00000000000 --- a/deployments/i03/beamline.yaml +++ /dev/null @@ -1,327 +0,0 @@ -# CORA Beamline descriptor: I03 (Diamond Light Source), design-phase scaffold -# -# I03 is an operating macromolecular-crystallography (MX) beamline at Diamond -# Light Source. It is bound to the Diamond Site (deployments/diamond/site.yaml), -# the second Diamond beamline after I22. -# -# STATUS: design-phase modelling exercise, NOT a CORA pilot. The device shape and -# the EPICS control handles are reverse-engineered from Diamond's open `dodal` -# controls library (src/dodal/beamlines/i03.py and its device classes), treated -# as a dry, correct DATA source and modelled intentionally, not mirrored. Scope -# is the MX spine + core collection path (the 32-ID earn-the-abstraction -# precedent); peripheral/floor devices are deferred (see below). -# -# WHAT I03 ADDS over I22: -# - It GRADUATES the Goniometer catalog Family (previously pending/documented): -# the Smargon is CORA's first canonical six-axis MX goniometer. See catalog.yaml. -# - It exercises autonomous sample handling. Per the 19-BM ROBOT-1 precedent, the -# robot is NOT a new Family: it is one Positioner-presenting Asset loading and -# unloading a Subject, gated by a Clearance, vendor in a bound Model. An -# adversarial new-kind review refuted a SampleChanger Family (covered by the -# existing Positioner Role). -# -# Reuses I22's loose StorageRing design-intent family and 2-BM's loose Diagnostic -# family, rather than coining synonyms; FluxMonitor and TemperatureController were -# first carried loose at I22 too and have since graduated to the catalog. The -# on-axis illumination binds the catalog Backlight Family (an illumination affordance -# no prior Family carried; graduated across the MX / imaging fleet, DET-1). -# Attenuator folds into the existing Filter Family; the aperture-scatterguard -# folds into the existing Aperture Family (both adversarially verified). -# -# Every device carries `new: true` (not yet a registered Asset) and `confirm: true` -# (values + snapshot PVs to be verified by Diamond staff). Calibrated numbers, the -# hutch/PSS safety structure, the passive beam-path tier, and the Capability/Method -# binding are absent from dodal and are NOT invented; each gap carries a -# (QUESTION-ID) answered on docs/deployments/i03/questions.md. -# -# DEFERRED (out of spine+core scope, noted not modelled): the undulator-DCM -# energy coupling (dodal's UndulatorDCM, itself being retired upstream; CORA models -# it as an energy_change Method binding the undulator gap + DCM energy, ENERGY-1); -# the fast grid scan (a Method/Plan, not hardware, TRIG-1); zocalo (compute/floor); -# the GDA baton (a governance token); pin-tip detection (CV/software); the cryojet -# and cryostream-gantry variants; the hutch webcam. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "macromolecular crystallography (MX); graduates the Goniometer Family and exercises autonomous sample handling" - name: I03 - facility: diamond - tier: Unit - parent: null - source: insertion-device - source_confirm: "undulator source (dodal UndulatorInKeV on SR03I, harmonic ~3); period / gap range / energy range not in dodal (SRC-1)" - page_layout: stages - shape: "Rotation macromolecular crystallography: it sweeps a crystal through a continuous omega rotation on a six-axis goniometer with an automated sample-changing robot; the deployment that graduated the Goniometer Family." - source_ref: - label: "DiamondLightSource/dodal" - url: "https://github.com/DiamondLightSource/dodal" - -# Two access-gated hutches (standard Diamond MX optics + experiment layout). dodal -# PV prefixes encode functional zones (OP, MO, EA, DI), not the hutch or its PSS -# meaning, so the split is carried confirm (ENC-1). Diamond PSS permit signals TBD (PSS-1). -enclosures: - - name: i03-optics - role: optics-hutch - facility_code: diamond - permit_signal: {confirm: "Diamond PSS permit signal TBD (PSS-1)"} - - name: i03-experiment - role: experiment-hutch - facility_code: diamond - permit_signal: {confirm: "Diamond PSS permit signal TBD (PSS-1)"} - -# --- SOURCE STAGE: beam delivery, conditioning, and beam diagnostics --- - -source: - stage: source - enclosure: i03-optics - intro: "The undulator source and the machine-level storage-ring state it draws on." - note: > - The undulator energy is set in keV via a gap lookup table. dodal couples it to - the DCM (the UndulatorDCM composite, which owns no motors and is being retired - upstream); CORA models that coupling as an energy_change Method binding the - undulator gap and the DCM energy, not as a device (ENERGY-1). - devices: - - name: Undulator - family: InsertionDevice - pv: "SR03I-MO-SERVC-01:" - new: true - confirm: true - mechanism: gap-to-energy via lookup table; harmonic order ~3 - note: "the MX source; energy range and gap curve to confirm (SRC-1)" - - name: StorageRing - family: StorageRing - new: true - confirm: true - note: "machine-level, beamline-shared, observe-only ring state; loose family reused from I22 (MACHINE-1)" - -conditioning-optics: - stage: source - enclosure: i03-optics - intro: "The monochromator, focusing mirror, filters, and collimation table that select energy and condition the beam." - note: > - The DCM energy/wavelength are virtual axes (a PseudoAxis over bragg + perp + - offset); its 7 temperature readbacks present the Sensor Role. The mirror bend - is shaped by a 22-channel bimorph (a PseudoAxis facet of the mirror, not a - separate Asset). Coatings, d-spacing, and bimorph calibration are settings (OPT-1). - devices: - - name: DCM - family: Monochromator - pv: "BL03I-MO-DCM-01:" - new: true - confirm: true - crystal: Si (default reflection 1 1 1) - axes: energy / wavelength (virtual) over bragg / offset / perp + crystal-1 pitch / roll - note: "double-crystal monochromator; crystal cut, d-spacing, and 7 thermal reads to confirm (OPT-1)" - - name: VFM - family: Mirror - pv: "BL03I-OP-VFM-01:" - new: true - confirm: true - axes: yaw / pitch (incident_angle) / roll / x / y / jacks (Y1-3) / translations (X1-2) - coating: selectable stripe Bare / Rhodium / Platinum (energy-driven setting) - bimorph: "22-channel bend, BL03I-MO-PSU-01: (a PseudoAxis facet, not a separate Asset)" - note: "vertical focusing mirror; coatings + bimorph calibration to confirm (OPT-1)" - - name: DiamondFilter - family: Filter - pv: "BL03I-MO-FLTR-01:Y" - new: true - confirm: true - note: "CVD diamond filter paddle" - - name: Attenuator - family: Filter - pv: "BL03I-EA-ATTN-01:" - new: true - confirm: true - note: "binary absorber-foil attenuator (transmission setting); the existing Filter Family covers it, not a new Attenuator kind (adversarial-verified)" - - name: CollimationTable - family: Table - pv: "BL03I-MO-TABLE-01" - new: true - confirm: true - note: "collimation support table" - -beam-defining-safety: - stage: source - enclosure: i03-optics - intro: "The beamstop, the coordinated aperture-scatterguard, and the safety and fast shutters." - note: > - The aperture-scatterguard is a coordinated pair moved as a unit; it folds into - the existing Aperture Family (the scatterguard is the companion, a setting or a - small Assembly), not a new kind (adversarial-verified). - devices: - - name: BeamStop - family: BeamStop - pv: "BL03I-MO-BS-01:" - new: true - confirm: true - note: "on-axis beamstop (positioned)" - - name: ApertureScatterguard - family: Aperture - pv: "BL03I-MO-MAPT-01: (aperture) + BL03I-MO-SCAT-01: (scatterguard)" - new: true - confirm: true - note: "coordinated aperture + scatterguard moved as a unit; existing Aperture Family, scatterguard is the companion" - - name: HutchShutter - family: Shutter - pv: "BL03I (PSS-interlocked)" - new: true - confirm: true - note: "PSS-interlocked hutch safety shutter; permit signal to confirm (PSS-1)" - - name: SampleShutter - family: Shutter - pv: "BL03I-EA-SHTR-01:" - new: true - confirm: true - note: "fast sample shutter (Zebra-driven); gates exposure" - -diagnostics: - stage: source - enclosure: i03-optics - intro: "The beam-position and flux monitors. All present the Sensor Role (scalar Readings)." - note: > - These present the Sensor Role rather than coining synonyms: the beam-position - monitor reuses the loose Diagnostic family from 2-BM (its BeamPositionMonitor - device); the flux monitors bind the FluxMonitor catalog Family (reused from I22, - since graduated). The XBPM feedback loop is carried with its modelling deferred (FEEDBACK-1). - devices: - - name: QBPM - family: PositionMonitor - pv: "BL03I-DI-QBPM-01:" - new: true - confirm: true - note: "quadrant beam-position monitor; presents the Sensor Role; binds the graduated PositionMonitor Family (DIAG-1)" - - name: Flux - family: FluxMonitor - pv: "BL03I-MO-FLUX-01:" - new: true - confirm: true - note: "flux readout (ion-chamber-derived); presents the Sensor Role; FluxMonitor catalog Family (graduated), reused from I22 (DIAG-1)" - - name: IPin - family: FluxMonitor - pv: "BL03I-EA-PIN-01:" - new: true - confirm: true - note: "ion-chamber pin-diode current; presents the Sensor Role; FluxMonitor catalog Family (graduated) (DIAG-1)" - - name: XBPMFeedback - pv: "BL03I-EA-FDBK-01:" - new: true - confirm: true - note: "closed-loop beam-position feedback; whether it is a modelled construct or floor is deferred (FEEDBACK-1)" - -# --- SAMPLE STAGE: the MX endstation --- - -sample: - stage: sample - enclosure: i03-experiment - intro: "The goniometer, the sample-centring base, the automated sample-changing robot, and the sample environment (illumination, cryo-cooling, thawing)." - note: > - The goniometer + aperture-scatterguard + backlight + cryostream could compose - an MX-endstation Assembly (the analogue of 2-BM's SampleTower), but grouping is - promoted only when a feature must act on the whole, so it is carried flat here - and deferred (ASSEMBLY-1). - devices: - - name: Goniometer - family: Goniometer - pv: "BL03I-MO-SGON-01:" - new: true - confirm: true - axes: omega / chi / phi rotation + x / y / z sample-centring; centre-of-rotation control; wrapped (unrestricted) omega - note: "the Smargon MX micro-goniometer, the canonical instance that graduated the Goniometer Family; per-axis decomposition + centre-of-rotation calibration to confirm (GONIO-1)" - - name: LowerGonio - family: LinearStage - pv: "BL03I-MO-GONP-01:" - new: true - confirm: true - note: "lower goniometer x / y / z base" - - name: Robot - pv: "BL03I-MO-ROBOT-01:" - new: true - confirm: true - note: "automated sample-changing robot (BartRobot). Per the 19-BM precedent: one Positioner-presenting Asset loading / unloading a Subject, gated by a Clearance, vendor in a bound Model; NOT a new SampleChanger Family (adversarial-verified). The exchange workflow + Subject custody lifecycle are deferred (ROBOT-1)" - - name: Backlight - family: Backlight - pv: "BL03I" - new: true - confirm: true - note: "sample illumination for on-axis viewing; binds the catalog Backlight Family (the first illumination affordance no prior Family carried, graduated across the MX / imaging fleet, DET-1)" - - name: Cryostream - family: TemperatureController - pv: "BL03I-EA-CSTRM-01:" - new: true - confirm: true - note: "Oxford cryostream cold-gas sample cooling; a settable actuator; TemperatureController catalog Family (graduated, presents Regulator), reused from I22 (ENV-1)" - - name: Thawer - family: TemperatureController - pv: "BL03I-EA-THAW-01" - new: true - confirm: true - note: "sample thawing actuator; a settable actuator; TemperatureController catalog Family (graduated, presents Regulator) (ENV-1)" - -# --- DETECTION STAGE: the Eiger and the fluorescence detector --- - -detector: - stage: detection - enclosure: i03-experiment - intro: "The Eiger area detector on its translation, and a retractable fluorescence detector." - note: > - The Eiger reuses the Camera Family (Detector Role). The fluorescence detector - presents the Sensor Role and is carried loose with its modelling deferred (DET-1). - devices: - - name: Eiger - family: Camera - pv: "BL03I-EA-EIGER-01:" - new: true - confirm: true - detector: Dectris Eiger - note: "the MX science detector; threshold energy + beam-center to confirm (DET-1)" - - name: DetectorMotion - family: LinearStage - pv: "BL03I-MO-DET-01:" - new: true - confirm: true - axes: z + upstream / downstream x (+ derived yaw) - note: "detector translation stage; carries an integrated shutter" - - name: FluorescenceDetector - pv: "BL03I-EA-FLU-01:" - new: true - confirm: true - note: "retractable fluorescence / XRF detector; presents the Sensor Role; carried loose, modelling deferred (DET-1)" - -# Cross-cutting timing. dodal records two FPGA timing boxes; the MX motion -# controllers are not exposed as dodal devices, so none is modelled here. -controls: - intro: > - I03 runs the Diamond EPICS control stack (driven by GDA and the bluesky-based - hyperion / mx-bluesky plan suite). dodal records the device PV prefixes carried - above; the Zebra and PandABox FPGA boxes generate the triggers and gates. - triggering: - - name: Zebra - family: TimingController - pv: "BL03I-EA-ZEBRA-01:" - new: true - confirm: true - note: "FPGA trigger fan-out (the MX trigger box); drives the fast sample shutter" - - name: Panda - family: TimingController - pv: "BL03I-EA-PANDA-01:" - new: true - confirm: true - note: "PandABox FPGA timing + HDF capture; drives the fast grid scan (TRIG-1)" - software_iocs_not_modeled: - - GDA (Generic Data Acquisition; Diamond's acquisition software) - - hyperion / mx-bluesky (the bluesky plan suite that drives MX data collection) - - Zocalo (the data-processing / results system) - - the GDA baton (a beamline-control coordination token, not a device) - -# Continuously-available resources a run draws on (design phase). -resources: - intro: > - The continuously-available facility resources a run needs present before it - can start. All pending confirmation in the design phase. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: LiquidNitrogen diff --git a/deployments/i06/beamline.yaml b/deployments/i06/beamline.yaml deleted file mode 100644 index 958d6225a9d..00000000000 --- a/deployments/i06/beamline.yaml +++ /dev/null @@ -1,288 +0,0 @@ -# i06 beamline descriptor (Diamond), reverse-engineered -# -# i06 is the Diamond nanoscience soft X-ray beamline: magnetic and electronic -# structure by X-ray magnetic dichroism (XMCD / XMLD), photoemission electron -# microscopy (PEEM), and resonant soft X-ray diffraction / dichroism. It is bound -# to the Diamond Site (deployments/diamond/site.yaml), the sixth Diamond beamline -# after I22, I03, I15-1, I11, and I24, and CORA's FIRST APPLE-II (variable -# polarization) source. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the DiamondLightSource/dodal beamline package, its src/dodal/beamlines/ -# i06.py + i06_shared.py + i06_1.py + i06_2.py factories and the device classes in -# src/dodal/devices/) or inferred, carried `new: true` + `confirm: true` pending -# i06 staff. EPICS PVs are real and verified against dodal; vendor part numbers, -# serials, and physical positions are not in dodal and are open questions. Same -# descriptor mode as the other Diamond deployments; this scaffold is descriptor + -# docs, scenarios deferred. -# -# WHAT IS NEW: i06 is the first beamline in the fleet whose source is an APPLE-II -# undulator, so it is the first that drives the X-ray POLARIZATION as an experiment -# axis (linear horizontal / vertical / arbitrary-angle, circular positive / -# negative, and third-harmonic variants), alongside the usual incident-energy axis. -# It is also CORA's first PEEM (photoemission electron microscopy) endstation, an -# electron-IMAGING technique distinct from the electron-energy analysis of ARPES. -# -# MODELLING: i06 coins NO new Family and changes nothing in the catalog. Two -# decisions carry the novelty by REUSE rather than coinage: -# - The two APPLE-II undulators (idd, idu) bind the catalog InsertionDevice -# Family. An APPLE-II is the same source-undulator anatomy as the EPUs already -# bound by SIX / CSX / ESM (InsertionDevice "spans the undulator and the -# wiggler; the device type and its gap / field parameters are a per-Asset -# settings difference"); the variable-polarization rows, the energy <-> gap -# polynomial lookup, and the coordinating controller are the per-Asset settings -# and the bound Model (HOW the gap and phase are driven), not a new device -# class. This resolves the long-standing SRC-1 question toward reuse. -# - POLARIZATION is modelled as a PseudoAxis Asset, a sibling of the incident -# energy PseudoAxis over the same source. The Pol value domain (LH / LV / PC / -# NC / LA + third harmonics) is the axis's value set; the controller's -# polarization-to-phase conversion is its partition rule, carried rule-less by -# default (the live i06 controller owns the kinematics; CORA names the axis, -# writes the value, records the move). This is the 2-BM beam-energy-as-PseudoAxis -# precedent, extended to a second driven source quantity. No new primitive. -# Every other device reuses an existing catalog or loose Family: the soft X-ray -# plane-grating monochromator binds GratingMonochromator (the SIX / CSX / ESM -# precedent); the PEEM UHV sample manipulators bind the graduated Manipulator; the -# diffraction-dichroism sample circles bind Goniometer; the Lakeshore controllers -# bind the graduated TemperatureController; the machine state reuses the loose -# StorageRing. -# -# DEFERRED (absent from dodal, not invented): the PEEM electron-optical column and -# its magnified electron-image detector are not dodal devices (only the PEEM sample -# manipulator and its energy slit are), so the PEEM imaging detector is carried as -# an open question (PEEM-1, the ElectronMicroscope anatomy: an electron-imaging -# column, distinct from the photon Camera and from the energy-analyzing -# ElectronAnalyzer); it is NOT coined here. The i06-1 diffraction detector and the -# incident-flux / drain-current monitors are likewise absent from dodal and carried -# as DET-1; the geometry is modelled now and the detectors bound later. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/i06/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "APPLE-II variable-polarization soft X-ray (XMCD/XMLD, PEEM, resonant diffraction); polarization as a controllable axis" - name: I06 - facility: diamond # Diamond Site (facility_code: diamond) - sector: "Sector 06" # PV zones BL06I (spine) / BL06J (i06-1) / BL06K (i06-2); SR06I (ID servos) - tier: Unit - parent: null - source: insertion-device - source_confirm: "i06 is a soft X-ray APPLE-II undulator beamline; dodal binds the two APPLE-II insertion devices (modelled below) but not their period; the undulator detail is SRC-1" - page_layout: stages - shape: "Soft X-ray magnetic spectroscopy on the fleet's first APPLE-II source, driving polarization as a first-class experiment axis (XMCD / XMLD) plus a PEEM endstation." - source_ref: - label: "DiamondLightSource/dodal" - url: "https://github.com/DiamondLightSource/dodal" - -# PV zones: BL06I (the shared optics spine: PGM, the APPLE-II controllers, the i06 -# PEEM sample stage), SR06I (the APPLE-II servo crates SERVC-01 / SERVC-21), BL06J -# (the i06-1 diffraction-dichroism endstation), BL06K (the i06-2 PEEM endstation). -# Whether the three PV zones are separate hutches and the PSS permit leaves are open -# (ENC-1, PSS-1). -enclosures: - - name: i06-optics - role: optics-hutch - facility_code: diamond - permit_signal: {confirm: "PSS permit leaf not in dodal; the shared soft X-ray optics zone (BL06I), hutch grouping is ENC-1 (PSS-1)"} - - name: i06-1 - role: experiment-hutch - facility_code: diamond - permit_signal: {confirm: "PSS permit leaf unknown; the diffraction-dichroism endstation (BL06J), ENC-1 (PSS-1)"} - - name: i06-2 - role: experiment-hutch - facility_code: diamond - permit_signal: {confirm: "PSS permit leaf unknown; the PEEM endstation (BL06K), ENC-1 (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the machine state, the APPLE-II undulators, and the monochromator -# =========================================================================== - -machine: - stage: source - enclosure: i06-optics - intro: "The machine-level source state, observed not driven." - note: "dodal's Synchrotron device is the observe-only machine state, the loose StorageRing pattern reused from the Diamond siblings (MACHINE-1)." - devices: - - name: StorageRing - family: StorageRing # loose Family (machine-level observe-only source state; MACHINE-1) - pv: "SR-DI-DCCT-01:" - new: true - confirm: true - note: "Diamond storage-ring state (ring current SR-DI-DCCT-01, energy / mode CS-CS-MSTAT-01, top-up SR-CS-FILL-01); observe-only (MACHINE-1)" - -insertion-devices: - stage: source - enclosure: i06-optics - intro: "The twin APPLE-II undulators, the variable-polarization soft X-ray source." - note: > - Both APPLE-II undulators bind the catalog InsertionDevice Family, the same - source-undulator anatomy as the EPUs at SIX / CSX / ESM. The variable-polarization - phase rows, the EPICS energy <-> gap polynomial lookup, and the coordinating - controller are per-Asset settings and the bound Model, not a new Family. Only the - upstream IDU exposes the driven energy / polarization handles in dodal; the - idd / idu asymmetry is POL-2. - devices: - - name: UndulatorDownstream - family: InsertionDevice - pv: "SR06I-MO-SERVC-01:" - new: true - confirm: true - note: "the downstream (IDD) APPLE-II undulator: gap on SR06I-MO-SERVC-01, locked phase rows, the energy <-> gap polynomial on BL06I-OP-IDD-01; period is SRC-1" - - name: UndulatorUpstream - family: InsertionDevice - pv: "SR06I-MO-SERVC-21:" - new: true - confirm: true - note: "the upstream (IDU) APPLE-II undulator: gap on SR06I-MO-SERVC-21, the energy <-> gap polynomial on BL06I-OP-IDU-01; exposes the driven energy / polarization handles (SRC-1, POL-2)" - -optics: - stage: source - enclosure: i06-optics - intro: "The soft X-ray plane-grating monochromator." - note: "The PGM binds GratingMonochromator, the SIX / CSX / ESM soft X-ray precedent; grating line density and cff are per-Asset settings." - devices: - - name: Monochromator - family: GratingMonochromator - pv: "BL06I-OP-PGM-01:" - new: true - confirm: true - note: "soft X-ray plane-grating monochromator: energy on ENERGY, the interchangeable grating (150 / 400 / 1200 l/mm) and the fixed-focus cff are per-Asset settings (MONO-1)" - -# =========================================================================== -# BEAM AXES: the driven source quantities, energy and polarization -# =========================================================================== - -beam-axes: - stage: source - enclosure: i06-optics - intro: "The two driven source quantities a soft X-ray dichroism run sets: the incident energy and, the fleet-first, the X-ray polarization." - note: > - Both are virtual axes over the source, bound to the catalog PseudoAxis Family - (the 2-BM beam-energy precedent). The incident energy decomposes to the PGM and - the APPLE-II gap; the polarization decomposes to the APPLE-II phase rows via the - i06 controller. Modelling polarization as a PseudoAxis sibling of energy is how - i06 carries the variable-polarization novelty without a new primitive; the - polarization partition rule is carried rule-less by default (POL-1). - devices: - - name: BeamEnergy - family: PseudoAxis - pv: {confirm: "incident-energy virtual axis (70-2200 eV) over the PGM energy and the APPLE-II gap (InsertionDeviceEnergy, Flyable); the partition rule (grating + the energy <-> gap polynomial) is MONO-1"} - new: true - confirm: true - note: "incident-energy pseudo-axis over the PGM and the upstream APPLE-II (the 2-BM beam-energy pattern); MONO-1" - - name: Polarization - family: PseudoAxis - pv: {confirm: "polarization virtual axis (InsertionDevicePolarisation); value domain LH / LV / PC / NC / LA plus third-harmonic variants, decomposing to the APPLE-II locked phase rows via the controller; rule-less by default (POL-1)"} - new: true - confirm: true - note: "the fleet-first polarization pseudo-axis over the upstream APPLE-II; the Pol value set is the axis domain, the controller's polarization-to-phase conversion is its partition rule, carried rule-less (POL-1, POL-2)" - -# =========================================================================== -# i06-1 DIFFRACTION-DICHROISM ENDSTATION (BL06J) -# =========================================================================== - -diffraction-dichroism: - stage: sample - enclosure: i06-1 - intro: "The i06-1 endstation: resonant soft X-ray diffraction and dichroism, with a sample-orientation diffractometer, an absorption sample stage, and sample temperature control." - note: > - The diffraction-dichroism sample circles bind the catalog Goniometer (the - sample-orientation role), with a reciprocal-space PseudoAxis over them (the 4-ID / - 8-ID / CSX diffractometer pattern; the Assembly is named, not built, DIFF-1). The - absorption stage binds LinearStage as a design-phase placeholder (STAGE-1). The - scattering detector and the incident-flux / drain-current monitors are not dodal - devices and are carried as DET-1, not invented. - devices: - - name: Diffractometer - family: Goniometer - pv: "BL06J-EA-DDIFF-01:" - new: true - confirm: true - note: "diffraction-dichroism sample circles (sample x/y/z, theta incidence, chi / phi orientation) plus the DET:2THETA / DET:Y detector arm; the circle roles and the Assembly(Diffractometer) binding are DIFF-1" - - name: ReciprocalSpace - family: PseudoAxis - pv: {confirm: "reciprocal-space virtual axis over the diffraction-dichroism circles; the inverse-kinematics partition rule is deferred as on 4-ID / 8-ID / CSX (DIFF-2)"} - new: true - confirm: true - note: "reciprocal-space pseudo-axis over the diffractometer (the Diffractometer reciprocal_space pattern); DIFF-2" - - name: AbsorptionStage - family: LinearStage - pv: "BL06J-EA-XABS-01:" - new: true - confirm: true - note: "the XAS / absorption sample stage (x / y / theta); design-phase placeholder, whether theta warrants Goniometer is STAGE-1" - - name: CoolingController - family: TemperatureController - pv: "BL06J-EA-TCTRL-02:" - new: true - confirm: true - note: "Lakeshore 336 sample cooling controller; reuses the graduated Family (presents Regulator); range is TEMP-1" - - name: HeatingController - family: TemperatureController - pv: "BL06J-EA-TCTRL-03:" - new: true - confirm: true - note: "Lakeshore 336 sample heating controller; reuses the graduated Family (presents Regulator); cooling-vs-heating is a per-Asset setting (TEMP-1)" - -# =========================================================================== -# i06-2 PEEM ENDSTATION (BL06K), plus the i06-branch PEEM stage -# =========================================================================== - -peem: - stage: sample - enclosure: i06-2 - intro: "The PEEM (photoemission electron microscopy) endstation: a UHV sample manipulator under the electron-optical imaging column." - note: > - The PEEM UHV sample manipulators bind the graduated Manipulator Family (the - SIX / ESM serial multi-axis sample-manipulator precedent); the energy-slit - translation and axis count are per-Asset settings. The PEEM electron-optical - column and its magnified electron-image detector are NOT dodal devices (only the - manipulators are), so the PEEM imaging detector is carried as PEEM-1, the - ElectronMicroscope anatomy, NOT coined here: it is electron-imaging, distinct - from the photon Camera and from the energy-analyzing ElectronAnalyzer. - devices: - - name: PeemManipulator - family: Manipulator - pv: "BL06K-MO-PEEM-01:" - new: true - confirm: true - note: "the i06-2 PEEM UHV sample manipulator (x / y / phi plus the es energy-slit translation); reuses the graduated Family; axis set is MANIP-1" - - name: PeemSampleStage - family: Manipulator - pv: "BL06I-MO-PEEM-01:" - new: true - confirm: true - note: "the i06-branch PEEM sample stage (x / y / phi); reuses the graduated Family (MANIP-1)" - -# Cross-cutting control. i06 runs EPICS (the floor); CORA observes and, where it -# replaces bluesky-style orchestration, conducts over it. The handles above were -# read from dodal and carried confirm (CTRL-1). -controls: - intro: > - i06 runs on the Diamond EPICS / ophyd-async control stack, the same floor as - I22 / I03 / I15-1 / I11 / I24. The device handles above are bound from the - DiamondLightSource/dodal beamline package (its i06 / i06_shared / i06_1 / i06_2 - factories and the device classes), carried confirm pending staff verification - (CTRL-1). The i06 acquisition (the coordinated energy / polarization moves over - the APPLE-II controller, the dichroism asymmetry sequences, the PEEM imaging, the - resonant diffraction scans) runs through bluesky plans; that orchestration is the - seam CORA's edge replaces, driving through ophyd-async / EPICS, while the live - APPLE-II energy <-> gap polynomial controller stays the floor (CORA names the - polarization and energy axes and records the moves; the IOC owns the kinematics, - POL-1). The PEEM electron-image stream and the diffraction detector file-writing - are absent from dodal (DET-1, PEEM-1); when bound, the file-writing to the Diamond - filestore is plumbing CORA observes, not data it owns (see model.md). - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources an i06 run needs. The soft X-ray - beam path and the endstations run under ultra-high vacuum (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the soft X-ray optics and the UHV endstations (SUP-1)" diff --git a/deployments/i10/beamline.yaml b/deployments/i10/beamline.yaml deleted file mode 100644 index 1e47c3eb539..00000000000 --- a/deployments/i10/beamline.yaml +++ /dev/null @@ -1,356 +0,0 @@ -# i10 beamline descriptor (Diamond), reverse-engineered -# -# i10 (BLADE) is the Diamond beamline for magnetic materials by resonant soft X-ray -# scattering (RASOR endstation) and X-ray magnetic dichroism in applied magnetic -# fields (the i10-1 / I10J endstation). It is bound to the Diamond Site -# (deployments/diamond/site.yaml), the seventh Diamond beamline after I22, I03, -# I15-1, I11, I24, and I06, and i06's variable-polarization soft X-ray twin. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the DiamondLightSource/dodal beamline package, its src/dodal/beamlines/ -# i10.py + i10_shared.py + i10_1.py factories and the device classes in -# src/dodal/devices/) or inferred, carried `new: true` + `confirm: true` pending i10 -# staff. EPICS PVs are real and verified against dodal; vendor part numbers, serials, -# and physical positions are not in dodal and are open questions. Same descriptor -# mode as the other Diamond deployments; this scaffold is descriptor + docs, -# scenarios deferred. -# -# WHAT IS NEW: i10 is the second APPLE-II (variable-polarization) source in the -# fleet, after i06 (PR #378), and it adds two device families that were loose at one -# beamline (4-ID) to a second sighting: the polarization analyzer (the RASOR PaStage) -# and the sample-environment magnet (the i10-1 electromagnet and superconducting -# field-sweep magnet). Both have since graduated into the catalog: PolarizationAnalyzer -# on the rule-of-three (4-ID, i10, ID32, P09; POL-2) and Magnet (MAG-1), so i10's -# analyzer arm and magnets bind their catalog Families. -# -# MODELLING: i10 coins NO new Family and changes nothing in the catalog. The -# polarization decisions follow the merged i06 precedent: the two APPLE-II undulators -# (idd, idu) bind the catalog InsertionDevice (the phase rows, the energy <-> gap -# polynomial, and the controller are per-Asset settings / bound-Model), and the -# polarization is a PseudoAxis sibling of the incident-energy axis (the Pol value set -# LH / LV / PC / NC / LA plus third-harmonic variants is the axis domain; the -# continuous linear-arbitrary-angle is the continuous realization of the LA value, in -# the same axis, not a second axis; the controller owns the conversion, carried -# rule-less, POL-1). The RASOR polarization-analysis arm binds the catalog -# PolarizationAnalyzer (graduated on the rule-of-three across 4-ID, i10, ID32, P09; -# POL-2). The i10-1 electromagnet and superconducting field-sweep magnet bind the -# catalog Magnet Family (graduated; one family, the fly / sweep capability is a -# per-Asset affordance, not a split; MAG-1). Everything else reuses an existing -# catalog Family: the soft X-ray -# plane-grating monochromator binds GratingMonochromator; the RASOR sample circles bind -# Goniometer with a reciprocal-space PseudoAxis; the collimating / switching / focusing -# mirrors bind Mirror; the slits bind Slit; the pinhole binds Aperture; the sample and -# magnet stages bind LinearStage; the Lakeshore controllers bind TemperatureController; -# and the scaler / current-amplifier counting chains (the incident-flux monitor, the -# scattered-beam point detector, and the fluorescence / drain-current / total-electron- -# yield channels) bind FluxMonitor. The machine state reuses the loose StorageRing. -# -# DEFERRED (absent from dodal, not invented): no area detector exists at either -# endstation; the science detector is the current-amplifier-plus-scaler point counter, -# bound to FluxMonitor and flagged (DET-1). The diffractometer Assembly and the -# reciprocal-space inverse-kinematics rule are named, not built (DIFF-1, DIFF-2). -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/i10/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "BLADE twin APPLE-II soft X-ray: RASOR resonant scattering / reflectivity + i10-1 magnet dichroism" - name: I10 - facility: diamond # Diamond Site (facility_code: diamond) - sector: "Sector 10" # PV zones BL10I (spine) / ME01D (RASOR) / BL10J (i10-1); SR10I (ID servos) - tier: Unit - parent: null - source: insertion-device - source_confirm: "i10 is a soft X-ray twin-APPLE-II beamline; dodal binds the two APPLE-II insertion devices (modelled below) but not their period; the undulator detail is SRC-1" - page_layout: stages - shape: "Soft X-ray resonant scattering and spectroscopy on a twin APPLE-II source, I06's soft X-ray twin, feeding the RASOR polarization-analysis arm and the i10-1 magnet endstation." - source_ref: - label: "DiamondLightSource/dodal" - url: "https://github.com/DiamondLightSource/dodal" - -# PV zones: BL10I (the shared optics spine: PGM, the collimating / switching mirrors, -# the APPLE-II controllers), SR10I (the APPLE-II servo crates SERVC-01 / SERVC-21), -# ME01D (the RASOR endstation), BL10J (the i10-1 / I10J magnet endstation). Whether -# the zones are separate hutches and the PSS permit leaves are open (ENC-1, PSS-1). -enclosures: - - name: i10-optics - role: optics-hutch - facility_code: diamond - permit_signal: {confirm: "PSS permit leaf not in dodal; the shared soft X-ray optics zone (BL10I), hutch grouping is ENC-1 (PSS-1)"} - - name: i10-rasor - role: experiment-hutch - facility_code: diamond - permit_signal: {confirm: "PSS permit leaf unknown; the RASOR resonant-scattering endstation (ME01D), ENC-1 (PSS-1)"} - - name: i10-1 - role: experiment-hutch - facility_code: diamond - permit_signal: {confirm: "PSS permit leaf unknown; the i10-1 / I10J magnet endstation (BL10J), ENC-1 (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the machine state, the APPLE-II undulators, the optics, the axes -# =========================================================================== - -machine: - stage: source - enclosure: i10-optics - intro: "The machine-level source state, observed not driven." - note: "dodal's Synchrotron device is the observe-only machine state, the loose StorageRing pattern reused from the Diamond siblings (MACHINE-1)." - devices: - - name: StorageRing - family: StorageRing # loose Family (machine-level observe-only source state; MACHINE-1) - pv: {confirm: "Diamond storage-ring state (current, energy, fill); observe-only, the exact PVs are MACHINE-1"} - new: true - confirm: true - note: "Diamond storage-ring state; observe-only (MACHINE-1)" - -insertion-devices: - stage: source - enclosure: i10-optics - intro: "The twin APPLE-II undulators, the variable-polarization soft X-ray source." - note: > - Both APPLE-II undulators bind the catalog InsertionDevice Family, the i06 (PR #378) - precedent: the variable-polarization phase rows (RPQ1-4), the jaw phase, the EPICS - energy <-> gap polynomial lookup, and the coordinating controller are per-Asset - settings and the bound Model, not a new Family. Both are driven sources feeding the - two endstations (SRC-1). - devices: - - name: UndulatorDownstream - family: InsertionDevice - pv: "SR10I-MO-SERVC-01:" - new: true - confirm: true - note: "the downstream (IDD) APPLE-II undulator: gap and phase rows (RPQ1-4) on SR10I-MO-SERVC-01, the energy <-> gap / phase polynomial on the I10Apple2Controller; period is SRC-1" - - name: UndulatorUpstream - family: InsertionDevice - pv: "SR10I-MO-SERVC-21:" - new: true - confirm: true - note: "the upstream (IDU) APPLE-II undulator: gap and phase rows on SR10I-MO-SERVC-21; both undulators are driven sources (SRC-1)" - -optics: - stage: source - enclosure: i10-optics - intro: "The soft X-ray plane-grating monochromator, the collimating and branch-switching mirrors, and the optics slits." - note: "The PGM binds GratingMonochromator (the SIX / CSX / ESM / i06 precedent); the mirrors bind Mirror; the slits bind Slit." - devices: - - name: Monochromator - family: GratingMonochromator - pv: "BL10I-OP-PGM-01:" - new: true - confirm: true - note: "soft X-ray plane-grating monochromator: energy on the grating + cff; the interchangeable grating line density and the fixed-focus cff are per-Asset settings (MONO-1)" - - name: CollimatingMirror - family: Mirror - pv: "BL10I-OP-COL-01:" - new: true - confirm: true - note: "the first (collimating) mirror, a piezo collimating mirror" - - name: SwitchingMirror - family: Mirror - pv: "BL10I-OP-SWTCH-01:" - new: true - confirm: true - note: "the branch-switching mirror selecting the RASOR or i10-1 branch (branch role is a setting)" - - name: OpticsSlit - family: Slit - pv: "BL10I-AL-SLITS-" - new: true - confirm: true - note: "the shared optics-spine beam-defining slits (s1 / s2 / s3); blade-axis map is ENC-1" - -# =========================================================================== -# BEAM AXES: the driven source quantities, energy and polarization -# =========================================================================== - -beam-axes: - stage: source - enclosure: i10-optics - intro: "The two driven source quantities a soft X-ray dichroism / scattering run sets: the incident energy and the X-ray polarization." - note: > - Both bind the catalog PseudoAxis Family (the 2-BM / i06 beam-energy precedent). The - incident energy decomposes to the PGM and the APPLE-II gap; the polarization - decomposes to the APPLE-II phase rows via the controller. The polarization is the - second-fleet variable-polarization axis, modelled exactly as i06: the Pol value set - is the axis domain and the linear-arbitrary-angle is the continuous realization of - the LA value within the same axis, carried rule-less (POL-1). - devices: - - name: BeamEnergy - family: PseudoAxis - pv: {confirm: "incident-energy virtual axis over the PGM and the APPLE-II gap (BeamEnergy = InsertionDeviceEnergy + PGM); both undulators are driven sources, so the one-vs-two energy-axis wiring is ENERGY-1"} - new: true - confirm: true - note: "incident-energy pseudo-axis over the PGM and the APPLE-II (the i06 beam-energy pattern); the energy range and partition rule are MONO-1, the two-source wiring is ENERGY-1" - - name: Polarization - family: PseudoAxis - pv: {confirm: "polarization virtual axis (InsertionDevicePolarisation + LinearArbitraryAngle); value domain LH / LV / PC / NC / LA plus third-harmonic variants, with the continuous linear-arbitrary-angle the realization of the LA value; decomposes to the APPLE-II phase rows via the controller; rule-less (POL-1)"} - new: true - confirm: true - note: "the polarization pseudo-axis over the APPLE-II (the i06 precedent; second variable-polarization source in the fleet); the Pol value set is the axis domain, the controller's conversion is its rule-less partition rule (POL-1, POL-2 for the analyzer)" - -# =========================================================================== -# RASOR ENDSTATION (ME01D): resonant soft X-ray scattering + polarization analysis -# =========================================================================== - -rasor: - stage: sample - enclosure: i10-rasor - intro: "The RASOR endstation: a soft X-ray scattering diffractometer with a polarization-analysis arm, a cryostat sample stage, and the counting detectors." - note: > - The sample circles bind the catalog Goniometer, with a reciprocal-space PseudoAxis - over them (the 4-ID / 8-ID / i06-1 diffractometer pattern; the Assembly is named, - not built, DIFF-1). The polarization-analysis arm binds the catalog PolarizationAnalyzer - (graduated on the rule-of-three across 4-ID, i10, ID32, P09; POL-2). Detection is - point / current-integrating: no area detector exists, so the scattered-beam point - detector and the monitor / fluorescence / drain-current channels bind FluxMonitor - (DET-1). - devices: - - name: Diffractometer - family: Goniometer - pv: "ME01D-MO-DIFF-01:" - new: true - confirm: true - note: "RASOR sample diffractometer (two-theta scattering arm TWOTHETA, sample theta / chi, chamber X, alpha); the circle roles and the Assembly(Diffractometer) binding are DIFF-1" - - name: ReciprocalSpace - family: PseudoAxis - pv: {confirm: "reciprocal-space virtual axis over the RASOR circles; the inverse-kinematics partition rule is deferred as on 4-ID / 8-ID / i06-1 (DIFF-2)"} - new: true - confirm: true - note: "reciprocal-space pseudo-axis over the diffractometer (DIFF-2)" - - name: AnalyzerArm - family: PolarizationAnalyzer - pv: "ME01D-MO-POLAN-01:" - new: true - confirm: true - note: "the polarization-analysis arm (POLAN: analyzer two-theta / theta, py / pz, eta) carrying the analyzer crystal; binds the catalog PolarizationAnalyzer Family (POL-2). dodal exposes the motors only; the analyzer crystal is implicit hardware (POL-2)" - - name: DetectorSlit - family: Slit - pv: "ME01D-MO-APTR-0" - new: true - confirm: true - note: "the detector slits in front of the RASOR point detector (APTR-01 / APTR-02)" - - name: Pinhole - family: Aperture - pv: "ME01D-EA-PINH-01:" - new: true - confirm: true - note: "the endstation beam-defining pinhole on its XY stage; Aperture-vs-stage is STAGE-1" - - name: SampleStage - family: LinearStage - pv: "ME01D-MO-CRYO-01:" - new: true - confirm: true - note: "the cryostat sample-positioning stage (x / y / z); plain in-air translation, not a UHV manipulator (STAGE-1)" - - name: SampleTemperatureController - family: TemperatureController - pv: "ME01D-EA-TCTRL-01:" - new: true - confirm: true - note: "Lakeshore 340 cryostat sample temperature controller; reuses the graduated Family (presents Regulator); range is TEMP-1" - - name: FocusingMirror - family: Mirror - pv: "BL10I-OP-FOCS-01:" - new: true - confirm: true - note: "the RASOR-branch focusing mirror (piezo collimating mirror)" - - name: Detector - family: FluxMonitor - pv: { scaler: "ME01D-EA-SCLR-01:SCALER1", amplifiers: "ME01D-EA-IAMP-01..06:" } - new: true - confirm: true - note: "the RASOR counting detection: the scattered-beam point detector (current-amp + Struck scaler, channel S18), the incident-flux monitor (S17), and the fluorescence (S19) and drain-current / total-electron-yield (S20) channels, through Femto / SR570 amplifiers; no area detector exists, so the science detector binds FluxMonitor (DET-1)" - -# =========================================================================== -# i10-1 ENDSTATION (BL10J): X-ray magnetic dichroism in applied magnetic fields -# =========================================================================== - -magnet-endstation: - stage: sample - enclosure: i10-1 - intro: "The i10-1 / I10J endstation: X-ray magnetic dichroism with the sample in an applied magnetic field, at low temperature." - note: > - The electromagnet and the superconducting field-sweep magnet both bind the catalog - Magnet Family (graduated; presents Regulator; one family, the fly / - sweep capability is a per-Asset affordance, not a split; MAG-1). - The magnet sample stages bind LinearStage, the Lakeshore binds TemperatureController, - and the counting chains (TEY / FY / diode / monitor) bind FluxMonitor (DET-1). - devices: - - name: Electromagnet - family: Magnet # catalog Family (graduated; presents Regulator, MAG-1) - pv: "BL10J-EA-MAGC-01:" - new: true - confirm: true - note: "the i10-1 electromagnet (set-and-read field); binds the catalog Magnet Family (graduated; a consumer after 4-ID, MAG-1)" - - name: HighFieldMagnet - family: Magnet # same catalog Family; fly / sweep is a per-Asset affordance, not a split (MAG-1) - pv: "BL10J-EA-SMC-01:" - new: true - confirm: true - note: "the i10-1 superconducting high-field magnet (Flyable field-sweep); the same catalog Magnet Family as the electromagnet, the sweep capability is a per-Asset bound-Model affordance (MAG-1)" - - name: HighFieldMagnetStage - family: LinearStage - pv: "BL10J-EA-MAG-01:" - new: true - confirm: true - note: "the high-field-magnet sample stage (x / y / pitch)" - - name: ElectromagnetStage - family: LinearStage - pv: "BL10J-MO-CRYO-01:" - new: true - confirm: true - note: "the electromagnet cryostat sample stage; cryostat motion folds into the stage Asset (MAG-1 for the low-temperature environment)" - - name: MagnetTemperatureController - family: TemperatureController - pv: "BL10J-EA-TCTRL-41:" - new: true - confirm: true - note: "Lakeshore 336 sample temperature controller at i10-1; reuses the graduated Family (presents Regulator); range is TEMP-1" - - name: MagnetSlit - family: Slit - pv: "BL10J-AL-SLITS-" - new: true - confirm: true - note: "the i10-1 branch beam-defining slits" - - name: MagnetFocusingMirror - family: Mirror - pv: "BL10J-OP-FOCA-01:" - new: true - confirm: true - note: "the i10-1-branch focusing mirror" - - name: MagnetDetector - family: FluxMonitor - pv: { scaler: "BL10J-EA-SCLR-01..02:", amplifiers: "BL10J-EA-IAMP-01..06: / BL10J-DI-IAMP-07..09:" } - new: true - confirm: true - note: "the i10-1 counting detection: the total-electron-yield (TEY), fluorescence-yield (FY), diode, and incident-monitor channels through Femto / SR570 amplifiers and the I10J scaler cards; no area detector, point / current-integrating XMCD detection (DET-1)" - -# Cross-cutting control. i10 runs EPICS (the floor); CORA observes and, where it -# replaces bluesky-style orchestration, conducts over it. The handles above were read -# from dodal and carried confirm (CTRL-1). -controls: - intro: > - i10 runs on the Diamond EPICS / ophyd-async control stack, the same floor as I22, - I03, I15-1, I11, I24, and I06. The device handles above are bound from the - DiamondLightSource/dodal beamline package (its i10 / i10_shared / i10_1 factories - and the device classes), carried confirm pending staff verification (CTRL-1). The - i10 acquisition (the coordinated energy / polarization moves over the APPLE-II - controller, the dichroism asymmetry sequences, the field sweeps at i10-1, the RASOR - reflectivity and resonant-scattering scans) runs through bluesky plans; that - orchestration is the seam CORA's edge replaces, driving through ophyd-async / EPICS, - while the live APPLE-II energy <-> gap / phase polynomial controller stays the floor - (CORA names the polarization and energy axes and records the moves; the controller - owns the kinematics, POL-1). The detector file-writing to the Diamond filestore is - plumbing CORA observes, not data it owns (see model.md). - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources an i10 run needs. The soft X-ray beam - path and the endstations run under ultra-high vacuum (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the soft X-ray optics and the UHV endstations (SUP-1)" diff --git a/deployments/i11/beamline.yaml b/deployments/i11/beamline.yaml deleted file mode 100644 index 543cd1f4f0e..00000000000 --- a/deployments/i11/beamline.yaml +++ /dev/null @@ -1,228 +0,0 @@ -# CORA Beamline descriptor: I11 (Diamond Light Source), design-phase scaffold -# -# I11 is an operating high-resolution powder-diffraction beamline at Diamond Light -# Source, the fourth Diamond beamline after I22, I03, and I15-1. Bound to the -# Diamond Site (deployments/diamond/site.yaml). -# -# STATUS: design-phase modelling exercise, NOT a CORA pilot. Reverse-engineered -# from Diamond's open dodal controls library (src/dodal/beamlines/i11.py + its -# device classes), treated as a dry, correct DATA source and modelled -# intentionally. Spine + core powder-diffraction path; carries the real BL11I PVs. -# -# WHAT I11 EARNS (and how it was handled): i11 was the rule-of-three for the -# TemperatureController family. It carries FOUR continuous-setpoint thermal -# actuators (csb1 / csb2 = Cyberstar blowers wrapping a Eurotherm controller with -# set(value) / setpoint / ramprate / PID / autotune; ocs1 / ocs2 = Oxford -# cryostreams), after TemperatureController was carried loose at i22 and i03. That -# genuinely earns BOTH (a) graduating the TemperatureController catalog Family and -# (b) a NEW settable-continuous-setpoint actuator Role (CORA has none today: -# Positioner is spatial, Controller supervises, GenericProbe is read-only). -# BUT a new Role is a code change to cora.equipment.aggregates.role.SEED_ROLES -# (drift-guarded by an exact-match test) and is core cross-facility vocabulary, so -# it belongs in a SEPARATE gate-reviewed change, NOT in this families-only scaffold. -# So this descriptor carried the four actuators as loose TemperatureController (as -# i22 / i03 did); TEMP-1 tracked the earn, which has SINCE LANDED via a -# gate-reviewed change: TemperatureController is now a catalog Family presenting -# the Regulator Role. No catalog change was made in the i11 scaffold itself. -# -# OTHER intentional decisions the eval settled: -# - The diffractometer (theta / two_theta / delta) is per-axis RotaryStage under a -# DiffractometerStage Assembly, NOT the i03-graduated Goniometer: two_theta / -# delta are detector-arm angles and theta is a single sample rotation, not an MX -# sample-orientation cradle (GONIO-1). -# - The sample robot is one Positioner-presenting Asset + Clearance + Subject (the -# locked 19-BM / i03 posture), NOT a new SampleChanger Family (ROBOT-1). -# - The Mythen3 is a 1D position-sensitive strip detector; it reuses Camera -# (Detector Role), with the strip-vs-2D nuance noted (it is skip-flagged in dodal -# per issue I11-916) (MYTHEN-1). -# -# Every device carries new: true + confirm: true. Families-only (no Model bindings). - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "high-resolution powder diffraction; the rule-of-three that earned the TemperatureController graduation + the Regulator Role (landed via gate-review)" - name: I11 - facility: diamond - tier: Unit - parent: null - source: insertion-device - source_confirm: "source type not pinned in dodal (the Synchrotron device is facility-wide, observe-only); carried confirm (SRC-1)" - page_layout: stages - shape: "High-resolution powder diffraction with continuous-setpoint thermal sample environments; the rule-of-three deployment that graduated the TemperatureController Family and its Regulator Role." - source_ref: - label: "DiamondLightSource/dodal" - url: "https://github.com/DiamondLightSource/dodal" - -enclosures: - - name: i11-optics - role: optics-hutch - facility_code: diamond - permit_signal: {confirm: "Diamond PSS optics-hutch permit TBD (PSS-1)"} - - name: i11-experiment - role: experiment-hutch - facility_code: diamond - permit_signal: {confirm: "Diamond PSS experiment-hutch permit TBD (PSS-1)"} - -# --- SOURCE STAGE --- - -source: - stage: source - enclosure: i11-optics - intro: "The storage-ring source state the beamline draws on." - devices: - - name: StorageRing - family: StorageRing - new: true - confirm: true - note: "machine-level, observe-only ring state; loose family reused from I22 (MACHINE-1)" - -conditioning-optics: - stage: source - enclosure: i11-optics - intro: "The double-crystal monochromator and the beam-defining slits." - devices: - - name: DCM - family: Monochromator - pv: "BL11I-MO-DCM-01:" - new: true - confirm: true - crystal: Si (default reflection 1 1 1) - temperature_pv: "BL11I-DI-DCM-01:" - axes: energy / wavelength (virtual) over bragg / offset / perp + crystal-1 pitch / roll - note: "double-crystal monochromator; crystal d-spacing + thermal reads to confirm (OPT-1)" - - name: Slit1 - family: Slit - pv: "BL11I-AL-SLITS-01:" - new: true - confirm: true - - name: Slit2 - family: Slit - pv: "BL11I-AL-SLITS-02:" - new: true - confirm: true - - name: Slit3 - family: Slit - pv: "BL11I-AL-SLITS-03:" - new: true - confirm: true - - name: Slit4 - family: Slit - pv: "BL11I-AL-SLITS-04:" - new: true - confirm: true - - name: Slit5 - family: Slit - pv: "BL11I-AL-SLITS-05:" - new: true - confirm: true - -# --- SAMPLE STAGE --- - -diffractometer: - stage: sample - enclosure: i11-experiment - intro: "The powder diffractometer (sample rotation + detector-arm angles) and the capillary spinner." - note: > - The diffractometer is per-axis RotaryStage under a DiffractometerStage Assembly, - NOT the Goniometer Family: theta is a single sample rotation and two_theta / - delta are detector-arm angles, not an MX sample-orientation cradle (GONIO-1). - Axis PVs to confirm (the dodal class was not read axis-by-axis) (DIFF-1). - devices: - - name: Diffractometer - family: RotaryStage - pv: "BL11I-MO-DIFF-01:" - new: true - confirm: true - axes: theta (sample) / two_theta / delta (detector arm) / spos - note: "per-axis RotaryStage under a DiffractometerStage Assembly; not a Goniometer (GONIO-1, DIFF-1)" - - name: DiffractometerBase - family: LinearStage - pv: "BL11I-MO-DIFF-01:BASE:" - new: true - confirm: true - note: "diffractometer base translation" - - name: Spinner - family: RotaryStage - pv: "BL11I-EA-ENV-01:" - new: true - confirm: true - note: "capillary sample spinner for powder averaging (enable + speed); a rotation device, RotaryStage (SPIN-1)" - -sample-environment: - stage: sample - enclosure: i11-experiment - intro: "The thermal sample environment and the sample-changing robot." - note: > - The four thermal actuators carry the TemperatureController family. i11 was - the rule-of-three (after i22 and i03) that earned graduating the Family AND a - new settable-continuous-setpoint actuator Role. That Role was a code change - (SEED_ROLES, drift-guarded) and core vocabulary, so it was routed to a SEPARATE - gate-reviewed change rather than this scaffold (TEMP-1); that change has since - landed, and TemperatureController is now a catalog Family presenting Regulator. - devices: - - name: CyberstarBlower1 - family: TemperatureController - pv: "BL11I-EA-BLOW-01:" - new: true - confirm: true - note: "Cyberstar hot-air blower; Eurotherm controller with updating PID; a continuous-setpoint actuator (set/setpoint/ramprate). TemperatureController catalog Family (graduated, presents Regulator); the earn was TEMP-1" - - name: CyberstarBlower2 - family: TemperatureController - pv: "BL11I-EA-BLOW-02:LOOP1:" - new: true - confirm: true - note: "Cyberstar hot-air blower with autotuneable Eurotherm controller; continuous-setpoint actuator (TEMP-1)" - - name: Cryostream1 - family: TemperatureController - pv: "BL11I-CG-CSTRM-01:" - new: true - confirm: true - note: "Oxford Cryostream 700 plus; continuous-setpoint cooling actuator (TEMP-1)" - - name: Cryostream2 - family: TemperatureController - pv: "BL11I-CG-CSTRM-02:" - new: true - confirm: true - note: "Oxford Cryostream 700 standard; continuous-setpoint cooling actuator (TEMP-1)" - - name: Robot - pv: "BL11I-EA-ROBOT-01:" - new: true - confirm: true - note: "sample arm + carousel that loads / unloads samples on the spinner (NX100Robot). Per the 19-BM / I03 precedent: one Positioner-presenting Asset loading / unloading a Subject, gated by a Clearance, vendor in a bound Model; NOT a new SampleChanger Family (ROBOT-1)" - -# --- DETECTION STAGE --- - -detector: - stage: detection - enclosure: i11-experiment - intro: "The Mythen3 position-sensitive strip detector." - devices: - - name: Mythen3 - family: Camera - pv: "BL11I-EA-DET-07:" - new: true - confirm: true - detector: Dectris Mythen3 (PSI design) - note: "a 1D position-sensitive strip detector; reuses Camera (Detector Role), with the strip-vs-2D-frame Role nuance noted; skip-flagged in dodal (issue I11-916); threshold / deadtime to confirm (MYTHEN-1)" - -# Cross-cutting controls. -controls: - intro: > - I11 runs the Diamond EPICS control stack (driven by GDA and bluesky). dodal - records the device PV prefixes carried above. No FPGA timing box is exposed in - the dodal i11 module; triggering is not modelled in this scaffold. - software_iocs_not_modeled: - - GDA (Generic Data Acquisition; Diamond's acquisition software) - - bluesky / blueapi (the bluesky-as-a-service layer dodal feeds) - -# Continuously-available resources a run draws on (design phase). -resources: - intro: > - The continuously-available facility resources a run needs present before it - can start. All pending confirmation in the design phase. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/i13-1/beamline.yaml b/deployments/i13-1/beamline.yaml deleted file mode 100644 index 0adc3ae10dc..00000000000 --- a/deployments/i13-1/beamline.yaml +++ /dev/null @@ -1,144 +0,0 @@ -# I13-1 beamline descriptor (Diamond), reverse-engineered -# -# I13-1 is the coherence branch of Diamond's I13 (Hard X-ray Imaging and Coherence) -# beamline: hard X-ray ptychography and coherent diffraction imaging (CDI), a coherent -# lensless-imaging technique that raster-scans a coherent beam across a sample and -# reconstructs an image from the far-field diffraction it records. It is bound to the -# Diamond Site (deployments/diamond/site.yaml), and is CORA's FIRST coherent -# lensless-imaging deployment (the fleet has tomography, XRF microprobe, and a hard -# X-ray nanoprobe, but no ptychography / CDI). -# -# STATUS: reverse-engineered, design-phase, and DELIBERATELY PARTIAL. The dodal source -# (github.com/DiamondLightSource/dodal, src/dodal/beamlines/i13_1.py) currently exposes -# only the coherence-branch endstation: a piezo sample-scanning stage, a side viewing -# camera, and the Merlin coherent-diffraction area detector. The shared I13 source and -# optics (the undulator, the monochromator, the mirrors, the slits) are NOT in dodal, so -# they are deferred, not invented (SRC-1, OPT-1), the same partial-first-cut posture as -# I20-1. EPICS PVs are real and read from dodal (the BL13J prefix); vendor part numbers, -# serials, and physical positions are not in dodal and are open questions. Descriptor + -# docs scaffold; scenarios deferred. -# -# WHAT IS NEW: the coherent lensless-imaging acquisition. Ptychography raster-scans a -# coherent illumination across overlapping points on the sample and records a far-field -# coherent-diffraction pattern at each point; the real-space image is reconstructed -# downstream from the diffraction stack. That is a new Capability (the fleet's first -# coherent diffractive imaging), deferred as a pending Method (TECH-1). -# -# MODELLING: I13-1 coins NO new Family and changes nothing in the catalog. The -# scout-anticipated "coherent imaging" novelty is an acquisition shape (a Method), not a -# device class: the devices are a raster sample stage and an area detector, both existing -# families. The piezo sample-scanning stage binds the catalog LinearStage (the ptychography -# raster is its operative motion; the fixed-angle lab-frame variant is a setting on the same -# stage); the Merlin photon-counting detector and the side viewing camera bind the catalog -# Camera; the machine state binds the loose StorageRing. Ptychography / CDI reuses no -# existing technique (it is new to the fleet), so it is carried as a new pending Method -# (TECH-1). -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/i13-1/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: partial - summary: "hard X-ray ptychography and coherent diffraction imaging (CDI) on the I13 coherence branch; the fleet's first coherent lensless imaging" - name: I13-1 - facility: diamond # Diamond Site (facility_code: diamond) - sector: "Sector 13 (I13 coherence branch)" # PV prefix BL13J - tier: Unit - parent: null - source: insertion-device - source_confirm: "I13 is an undulator beamline; dodal exposes only the I13-1 coherence-branch endstation, not the shared source, so the undulator and the shared optics are deferred (SRC-1, OPT-1)" - page_layout: stages - shape: "The fleet's first dedicated coherent lensless-imaging beamline: ptychography raster-scans a coherent probe over the sample and reconstructs the real-space image downstream." - source_ref: - label: "DiamondLightSource/dodal" - url: "https://github.com/DiamondLightSource/dodal" - -# PV prefix: BL13J (the I13-1 coherence branch endstation). The shared I13 source and -# optics are upstream and absent from dodal. Whether I13-1 is its own hutch and the PSS -# permit leaves are open (ENC-1, PSS-1). -enclosures: - - name: i13-1 - role: experiment-hutch - facility_code: diamond - permit_signal: {confirm: "PSS permit leaf not in dodal; the I13-1 coherence-branch experiment hutch (BL13J), hutch grouping is ENC-1 (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the machine state (the shared source and optics are deferred) -# =========================================================================== - -machine: - stage: source - enclosure: i13-1 - intro: "The machine-level source state, observed not driven. The shared I13 source and optics are upstream and not yet in scope (SRC-1, OPT-1)." - note: "dodal's Synchrotron device is the observe-only machine state, the loose StorageRing pattern reused from the Diamond siblings (MACHINE-1). The undulator, monochromator, mirrors, and slits are absent from the i13_1 dodal module and are deferred (SRC-1, OPT-1)." - devices: - - name: StorageRing - family: StorageRing # loose Family (machine-level observe-only source state; MACHINE-1) - pv: {confirm: "Diamond storage-ring state (current, fill); observe-only, the exact PVs are MACHINE-1"} - new: true - confirm: true - note: "Diamond storage-ring state; observe-only; the shared I13 source / optics are deferred (SRC-1, OPT-1, MACHINE-1)" - -# =========================================================================== -# ENDSTATION STAGE: the ptychography sample stage and the coherent-diffraction detector -# =========================================================================== - -endstation: - stage: sample - enclosure: i13-1 - intro: "The coherence-branch endstation: the piezo sample-scanning stage, the side viewing camera, and the Merlin coherent-diffraction area detector." - note: > - All reuse existing catalog Families. The piezo sample-scanning stage binds LinearStage - (the ptychography raster is its operative motion; the fixed-angle lab-frame variant is a - setting on the same stage, SAMPLE-1). The Merlin photon-counting detector and the side - viewing camera bind Camera (DET-1). The coherent lensless-imaging acquisition is a - Method, not a device (TECH-1). - devices: - - name: SampleStage - family: LinearStage - pv: "BL13J-MO-PI-02:" - new: true - confirm: true - note: "the PI piezo sample-scanning stage (x / y / z); the ptychography raster motion; a fixed-angle lab-frame variant is on BL13J-MO-PI-02:FIXANG: as a setting on the same stage (SAMPLE-1)" - - name: SideCamera - family: Camera - pv: "BL13J-OP-FLOAT-03:" - new: true - confirm: true - note: "the side viewing camera (an Aravis / GenICam optical camera) for sample alignment (DET-1)" - - name: Detector - family: Camera - pv: "BL13J-EA-DET-04:" - new: true - confirm: true - note: "the Merlin (Medipix3) photon-counting area detector recording the far-field coherent-diffraction pattern; the science detector for ptychography / CDI (DET-1)" - -# Cross-cutting control. I13-1 runs EPICS (the floor); CORA observes and, where it -# replaces bluesky-style orchestration, conducts over it. The handles above were read -# from dodal and carried confirm (CTRL-1). -controls: - intro: > - I13-1 runs on the Diamond EPICS / ophyd-async control stack, the same floor as the - other Diamond beamlines. The device handles above are bound from the - DiamondLightSource/dodal i13_1 module (the BL13J coherence-branch endstation), carried - confirm pending staff verification (CTRL-1). The shared I13 source and optics are - upstream and not yet in the dodal module, so they are deferred (SRC-1, OPT-1). The - ptychography acquisition (the raster scan of the piezo stage coupled to the Merlin - far-field capture, then the downstream reconstruction) runs through bluesky plans and - a reconstruction pipeline; that orchestration is the seam CORA's edge replaces, driving - through ophyd-async / EPICS, while the reconstruction is ComputePort work, not a beamline - device (TECH-1). The detector file-writing to the Diamond filestore is plumbing CORA - observes, not data it owns (see model.md). - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources an I13-1 run needs. The coherent beam - path runs under vacuum (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the coherent-beam flight path (SUP-1)" diff --git a/deployments/i15-1/beamline.yaml b/deployments/i15-1/beamline.yaml deleted file mode 100644 index 4c20483563e..00000000000 --- a/deployments/i15-1/beamline.yaml +++ /dev/null @@ -1,304 +0,0 @@ -# CORA Beamline descriptor: I15-1 (Diamond Light Source), design-phase scaffold -# -# I15-1 (XPDF) is an operating X-ray pair-distribution-function / total-scattering -# beamline at Diamond Light Source, the third Diamond beamline after I22 and I03. -# Bound to the Diamond Site (deployments/diamond/site.yaml). -# -# STATUS: design-phase modelling exercise, NOT a CORA pilot. Reverse-engineered -# from Diamond's open dodal controls library (src/dodal/beamlines/i15_1.py + its -# device classes), treated as a dry, correct DATA source and modelled -# intentionally. Spine + core total-scattering path; carries the real BL15I PVs. -# -# WHAT I15-1 EARNS: nothing new. Like I22, it earns zero new catalog families and -# zero new affordances; every device maps to an existing Family or a reused loose -# one. Its value is consolidation + three intentional-modelling decisions that an -# adversarial eval settled (resisting three mirror-the-controls traps): -# 1. SafeOrBeamPositioner (the blower / cobra / cryostream sample-environment -# devices) is a Movable driving a motor to two NAMED positions (SAFE / BEAM). -# That is the existing Positioner Role with Indexable named positions, NOT a -# new settable-actuator affordance, and NOT a TemperatureController (the dodal -# classes are NAMED for temperature controllers but model only the in/out-of- -# beam position move; modelling them as TemperatureController would mirror the -# class name, not the behaviour). Carried as LinearStage + Positioner/Indexable -# (SAFEBEAM-1). -# 2. The rail (the shared support on which cobra/cryostream are interchanged) is -# the existing Table Family (the TomoWISE DetectorGantry precedent), not a new -# Rail Family (RAIL-1). -# 3. The PSS / gonio interlocks are NOT equipment devices: they are the data -# behind the Enclosure permit_signal (the shipped Enclosure aggregate), so -# they are carried on the enclosures below, not as a device walk (INTERLOCK-1). -# It also reuses FluxMonitor (the JBPM TetrAMM i0); this deployment completed its -# rule-of-three graduation into the catalog, and adds a third robot-as-Positioner instance. -# -# Every device carries new: true + confirm: true. Families-only (no Model bindings). -# DEFERRED out of scope: the bent-Laue energy as a goto-command (dodal exposes it -# read-only, ENERGY-1); puck_detect (a CV web service, not a device); the hutch -# webcams; sam + slits_1 + clean (skip-flagged in dodal). - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "X-ray total scattering / pair distribution function (XPDF); a reuse + reinforce deployment (no new vocabulary)" - name: I15-1 - facility: diamond - tier: Unit - parent: null - source: insertion-device - source_confirm: "source type not pinned in dodal (i15-1 is a branch line); carried confirm (SRC-1)" - page_layout: stages - shape: "High-energy total scattering and PDF: a consolidation deployment that coins nothing new, reusing existing Families and carrying its interlocks as Enclosure permits, not devices." - source_ref: - label: "DiamondLightSource/dodal" - url: "https://github.com/DiamondLightSource/dodal" - -# Two access-gated hutches. Unlike I22/I03, dodal records real interlock PVs here, -# carried as the permit_signal candidates (confirm: these are interlock readbacks, -# not confirmed search-and-secure permits) (PSS-1, ENC-1). -enclosures: - - name: i15-1-optics - role: optics-hutch - facility_code: diamond - permit_signal: {confirm: "Diamond PSS optics-hutch permit TBD; dodal hutch interlock readback BL15I-PS-IOC-02:M11:LOP (PSS-1)"} - - name: i15-1-experiment - role: experiment-hutch - facility_code: diamond - permit_signal: {confirm: "Diamond PSS experiment-hutch permit TBD; dodal gonio interlock readback BL15I-VA-OMRON-01:INT3:ILK (PSS-1)"} - -# --- SOURCE STAGE --- - -source: - stage: source - enclosure: i15-1-optics - intro: "The storage-ring source state the beamline draws on." - devices: - - name: StorageRing - family: StorageRing - new: true - confirm: true - note: "machine-level, observe-only ring state; loose family reused from I22 (MACHINE-1)" - -conditioning-optics: - stage: source - enclosure: i15-1-optics - intro: "The bent-Laue monochromator, the multilayer mirror, and the attenuators." - note: > - The bent-Laue mono selects a fixed energy: dodal exposes energy_kev as a - read-only signal derived from the crystal y position via a lookup table, NOT a - scanned or commanded axis. Energy is an epistemic readback (a Calibration), so - the pending energy_scan Capability is NOT earnable here (ENERGY-1). - devices: - - name: LaueMono - family: Monochromator - pv: "BL15I-OP-LAUE-01:" - new: true - confirm: true - axes: bend / bragg / roll / yaw / y (energy-selecting crystal translation) - note: "bent-Laue monochromator; energy_kev is a read-only y-to-energy lookup readback, not a commanded axis (ENERGY-1); crystal LUT to confirm (OPT-1)" - - name: M1 - family: Mirror - pv: "BL15I-OP-MIRR-01:" - new: true - confirm: true - note: "multilayer mirror; coating to confirm (OPT-1)" - - name: Attenuator - family: Filter - pv: "BL15I-OP-ATTN-02:" - new: true - confirm: true - note: "foil attenuator selecting one of 7 named transmission levels (100% down to 0.001%); the existing Filter Family via the Positioner Role's Indexable named positions, not a new kind (ATTN-1)" - - name: AttenuatorSticks - family: LinearStage - pv: "BL15I-OP-ATTN-01:" - new: true - confirm: true - axes: STICK1 / STICK2 / STICK3 - note: "three-stick attenuator positioning stage (ATTN-01); whether it is the same unit as the ATTN-02 selector is open (ATTN-1)" - - name: AttenuatorY - family: LinearStage - pv: "BL15I-OP-ATTN-02:Y" - new: true - confirm: true - note: "attenuator vertical positioning" - -beam-defining-safety: - stage: source - enclosure: i15-1-optics - intro: "The beam-defining slits, the beamstop, and the safety and fast shutters. The PSS / gonio interlocks are carried on the enclosures (the Enclosure permit_signal), not as devices (INTERLOCK-1)." - devices: - - name: Slit2 - family: Slit - pv: "BL15I-AL-SLITS-02:" - new: true - confirm: true - - name: Slit3 - family: Slit - pv: "BL15I-AL-SLITS-03:" - new: true - confirm: true - - name: Slit4 - family: Slit - pv: "BL15I-AL-SLITS-04:" - new: true - confirm: true - - name: Slit5 - family: Slit - pv: "BL15I-AL-SLITS-05:" - new: true - confirm: true - - name: BeamStop - family: BeamStop - pv: "BL15I-MO-SMAR-02:" - new: true - confirm: true - note: "positioned beamstop" - - name: HutchShutter - family: Shutter - pv: "BL15I (interlocked, -PS-SHTR-01:ILKSTA)" - new: true - confirm: true - note: "PSS-interlocked hutch safety shutter" - - name: FastShutter - family: Shutter - pv: "BL15I-EA-ZEBRA-01:SOFT_IN:B3" - new: true - confirm: true - note: "Zebra-driven fast shutter; gates exposure" - -# --- SAMPLE STAGE --- - -sample-environment: - stage: sample - enclosure: i15-1-experiment - intro: "The sample positioning, the two-theta detector arm, and the interchangeable sample-environment devices on a shared rail." - note: > - The blower / cobra / cryostream are SafeOrBeamPositioner devices: each drives a - motor to a named SAFE or BEAM position. They are modelled as LinearStage Assets - presenting Positioner with two Indexable named positions, NOT TemperatureController - (dodal models the in/out-of-beam move, not the temperature setpoint). cobra and - cryostream share the rail X motor (ENV:X) because they are physically interchanged - on the rail; whether that exchange is a Fixture-style swap or an Assembly is open - (SAFEBEAM-1, RAIL-1). - devices: - - name: Rail - family: Table - pv: "BL15I-MO-RAIL-01:" - new: true - confirm: true - axes: pitch / y / y1 / y2 - note: "the shared support rail the sample-environment devices ride; existing Table Family (the TomoWISE DetectorGantry precedent), not a new Rail kind (RAIL-1)" - - name: EnvX - family: LinearStage - pv: "BL15I-MO-TABLE-01:ENV:X" - new: true - confirm: true - note: "the shared rail X position the cobra / cryostream are interchanged on (SAFEBEAM-1)" - - name: Blower - family: LinearStage - pv: "BL15I-EA-BLOWR-01:TLATE" - new: true - confirm: true - note: "gas-blower sample environment; SafeOrBeamPositioner = Positioner with SAFE / BEAM Indexable named positions, NOT a TemperatureController (SAFEBEAM-1)" - - name: Cobra - family: LinearStage - pv: "BL15I-MO-TABLE-01:ENV:X" - new: true - confirm: true - note: "Oxford Cobra sample environment; SafeOrBeamPositioner (SAFE / BEAM Indexable); interchangeable with the cryostream on the rail (SAFEBEAM-1)" - - name: Cryostream - family: LinearStage - pv: "BL15I-MO-TABLE-01:ENV:X" - new: true - confirm: true - note: "Oxford Cryostream sample environment; SafeOrBeamPositioner (SAFE / BEAM Indexable); interchangeable with the cobra (SAFEBEAM-1)" - - name: SampleTrans - family: LinearStage - pv: "BL15I-MO-TABLE-01:TRANS:" - new: true - confirm: true - axes: x / y / phi - note: "sample translation + rotation" - - name: Hexapod - family: Hexapod - pv: "BL15I-MO-HEX-01:" - new: true - confirm: true - note: "six-axis sample hexapod (linear x/y/z + rotation RX/RY/RZ as virtual axes)" - - name: BaseY - family: LinearStage - pv: "BL15I-MO-TABLE-01:Y" - new: true - confirm: true - note: "sample table base height" - - name: TwoTheta - family: RotaryStage - pv: "BL15I-MO-TABLE-01:TTH" - new: true - confirm: true - note: "the two-theta detector arm angle" - -sample-loading: - stage: sample - enclosure: i15-1-experiment - intro: "The automated sample-changing robot for powder / capillary pucks." - devices: - - name: Robot - pv: "BL15I-MO-ROBOT-01: (+ BL15I-EA-LOC-01: current sample)" - new: true - confirm: true - note: "powder/capillary sample-changing robot. Per the I03 / 19-BM precedent: one Positioner-presenting Asset loading / unloading a Subject, gated by a Clearance, vendor in a bound Model; NOT a new Family. The puck custody lifecycle is deferred (ROBOT-1). puck_detect (a CV web service, not a device) is not modelled." - -# --- DETECTION STAGE --- - -detector: - stage: detection - enclosure: i15-1-experiment - intro: "The Eiger area detector on the two-theta arm, a second detector translation, and the incident-flux monitor." - devices: - - name: Eiger - family: Camera - pv: "BL15I-EA-EIGER-01:" - new: true - confirm: true - detector: Dectris Eiger - note: "the area detector capturing wide-Q total-scattering frames; threshold energy + beam-center to confirm (DET-1)" - - name: Detector2 - family: LinearStage - pv: "BL15I-EA-DET-02:" - new: true - confirm: true - note: "second detector translation (y / z)" - - name: I0 - family: FluxMonitor - pv: "BL15I-EA-JBPM-03:" - new: true - confirm: true - note: "incident-flux monitor (TetrAMM JBPM); presents the Sensor Role; FluxMonitor catalog Family (graduated; this deployment completed the i22/i03/i15-1 rule-of-three) (FLUX-1)" - -# Cross-cutting timing. -controls: - intro: > - I15-1 runs the Diamond EPICS control stack (driven by GDA and bluesky). dodal - records the device PV prefixes carried above; a Zebra FPGA box generates the - triggers and gates. - triggering: - - name: Zebra - family: TimingController - pv: "BL15I-EA-ZEBRA-01:" - new: true - confirm: true - note: "FPGA trigger/gate generation; drives the fast shutter" - software_iocs_not_modeled: - - GDA (Generic Data Acquisition; Diamond's acquisition software) - - bluesky / blueapi (the bluesky-as-a-service layer dodal feeds) - - puck_detect (an image-processing web service for puck/lid detection) - -# Continuously-available resources a run draws on (design phase). -resources: - intro: > - The continuously-available facility resources a run needs present before it - can start. All pending confirmation in the design phase. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/i19/beamline.yaml b/deployments/i19/beamline.yaml deleted file mode 100644 index b2422222ad3..00000000000 --- a/deployments/i19/beamline.yaml +++ /dev/null @@ -1,304 +0,0 @@ -# i19 beamline descriptor (Diamond), reverse-engineered -# -# i19 is the Diamond small-molecule single-crystal diffraction beamline (chemical -# crystallography): monochromatic and variable-wavelength single-crystal diffraction -# on a Newport kappa four-circle goniometer with an Eiger detector, plus a serial / -# microfocus fixed-target arm. It is bound to the Diamond Site -# (deployments/diamond/site.yaml), the eighth Diamond beamline after I22, I03, I15-1, -# I11, I24, I06, I10, I20-1, and CORA's FIRST chemical (small-molecule) crystallography -# deployment (the fleet's other diffraction-imaging crystallography is all -# macromolecular MX: I03, I24, FMX, MX3). -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the DiamondLightSource/dodal beamline package, its src/dodal/beamlines/i19.py -# + i19_shared.py + i19_1.py + i19_2.py factories and the device classes in -# src/dodal/devices/) or inferred, carried new: true + confirm: true pending i19 staff. -# EPICS PVs are real and verified against dodal; vendor part numbers, serials, and -# physical positions are not in dodal and are open questions. Same descriptor mode as -# the other Diamond deployments; this scaffold is descriptor + docs, scenarios deferred. -# -# WHAT IS NEW: the genuine novelty is NOT the instrument (the kappa four-circle is plain -# Goniometer reuse, see MODELLING) but the GOVERNANCE seam. i19 has two experiment -# hutches (EH1 and EH2) in series that SHARE one optics line, and only the active hutch -# may drive the shared optics. dodal expresses this through a central arbiter (the -# i19-blueapi optics service): a hutch reads the shared-optics state directly over EPICS -# but its WRITES (change energy, operate the experiment shutter, move the attenuator, -# set a mirror piezo) are posted to the arbiter, which compares the requesting hutch -# against the active-hutch readback and runs or rejects. This dual-hutch shared-optics -# access-control is modelled as an Enclosure-permit + Trust-gate over the shared-optics -# Assets, with the arbiter as an actuate-floor seam partner (the "EPICS is the floor" -# pattern, here a blueapi-arbiter floor). It is the trigger for ACCESS-1; it is NOT a -# device family. -# -# MODELLING: i19 coins NO new Family and changes nothing in the catalog. -# - The Newport kappa FOUR-CIRCLE (phi / omega / kappa sample circles + a 2theta -# detector arm + sample centring) binds the catalog Goniometer: the catalog -# Goniometer note states "chi-vs-kappa and axis-count are a per-Asset settings -# difference, not a Family split", and the larger four-circle composes the catalog -# Assembly(Diffractometer) (a Goniometer + a RotaryStage 2theta detector arm + a -# reciprocal-space PseudoAxis), the 8-ID / i06-1 pattern, named-not-built here -# (DIFF-1, DIFF-2). -# - The single-crystal diffraction technique reuses the pending `diffraction` Method -# (4-ID / 8-ID / CSX are the prior consumers); i19 is chemical single-crystal -# diffraction, the same Method, a Practice-level science difference (TECH-1). -# - The MAPT pinhole + collimator binds the catalog Aperture (the i03 -# ApertureScatterguard-at-MAPT precedent), composing the pinhole and collimator XY -# stages with a configuration lookup table (APERTURE-1). -# Everything else reuses an existing catalog Family: the DCM binds Monochromator; the -# focusing mirrors bind Mirror; the attenuator binds Filter; the undulator binds -# InsertionDevice; the Eiger and the OAV viewing cameras bind Camera; the Zebra and -# PandA hardware triggers bind TimingController; the serial / microfocus arm binds -# Goniometer; the beamstops bind BeamStop; the shutter binds Shutter; the incident -# energy is a PseudoAxis. The machine state reuses the loose StorageRing; the sample -# backlight binds the catalog Backlight Family (graduated across the MX / imaging fleet, -# DET-1). -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/i19/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "small-molecule single-crystal diffraction; the fleet's first chemical crystallography beamline" - name: I19 - facility: diamond # Diamond Site (facility_code: diamond) - sector: "Sector 19" # PV zones BL19I (optics + both hutches); SR19I (undulator) - tier: Unit - parent: null - source: insertion-device - source_confirm: "i19 is an undulator beamline; dodal binds the undulator (UndulatorInKeV on SR19I-MO-SERVC-01) but not its period; the undulator detail is SRC-1" - page_layout: stages - shape: "The fleet's first chemical (small-molecule) single-crystal crystallography beamline, defined by a dual-hutch shared-optics access arbiter modelled as an Enclosure-permit Trust gate." - source_ref: - label: "DiamondLightSource/dodal" - url: "https://github.com/DiamondLightSource/dodal" - -# PV zones: BL19I (the shared optics and both experiment hutches: -OP / -MO optics and -# motion, -EA endstation, -PS shutter, -RS beamstop), SR19I (the storage-ring undulator -# servo). The two hutches EH1 and EH2 share the BL19I optics; which hutch holds which -# endstation instrument, and the precise EH1 / EH2 grouping, are open (ENC-1). The -# dual-hutch shared-optics access-control seam is ACCESS-1; the PSS permit leaves are -# PSS-1. -enclosures: - - name: i19-optics - role: optics-hutch - facility_code: diamond - permit_signal: {confirm: "PSS permit leaf not in dodal; the shared optics enclosure, the optics shutter is the dodal InterlockedHutchShutter (PSSInterlock); permit-leaf names are PSS-1"} - - name: i19-1 - role: experiment-hutch - facility_code: diamond - permit_signal: {confirm: "PSS permit leaf unknown; the EH1 experiment hutch; the active-hutch shared-optics permit is ACCESS-1 (ENC-1, PSS-1)"} - - name: i19-2 - role: experiment-hutch - facility_code: diamond - permit_signal: {confirm: "PSS permit leaf unknown; the EH2 experiment hutch (the four-circle + serial endstation); the active-hutch shared-optics permit is ACCESS-1 (ENC-1, PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the machine state and the shared optics (contended by EH1 / EH2) -# =========================================================================== - -machine: - stage: source - enclosure: i19-optics - intro: "The machine-level source state, observed not driven." - note: "dodal's Synchrotron device is the observe-only machine state, the loose StorageRing pattern reused from the Diamond siblings (MACHINE-1)." - devices: - - name: StorageRing - family: StorageRing # loose Family (machine-level observe-only source state; MACHINE-1) - pv: {confirm: "Diamond storage-ring state (current, fill); observe-only, the exact PVs are MACHINE-1"} - new: true - confirm: true - note: "Diamond storage-ring state; observe-only (MACHINE-1)" - -optics: - stage: source - enclosure: i19-optics - intro: "The shared optics line: the undulator, the double-crystal monochromator, the focusing mirrors, the attenuator, the incident-energy axis, and the optics shutter. Both hutches share these; only the active hutch may drive them (ACCESS-1)." - note: > - All reuse existing catalog Families. These are SINGLE Assets in the shared optics - enclosure; a non-active hutch may read them but not drive them, and the energy move - is a coordinated procedure over the monochromator, undulator, and mirrors gated by - the active-hutch permit (ACCESS-1). The mirror coating stripe is a hutch-keyed - setting on the mirror (OPT-1). - devices: - - name: Undulator - family: InsertionDevice - pv: "SR19I-MO-SERVC-01:" - new: true - confirm: true - note: "the undulator (UndulatorInKeV, energy-to-gap lookup); coordinated with the DCM on an energy move; period is SRC-1" - - name: Monochromator - family: Monochromator - pv: "BL19I-MO-DCM-01:" - new: true - confirm: true - note: "double-crystal monochromator (Si stationary crystal + pitch/roll crystal); energy / wavelength / Bragg / offset with d-spacing readback; a non-active hutch reads it read-only (ACCESS-1, MONO-1)" - - name: HorizontalFocusingMirror - family: Mirror - pv: "BL19I-OP-HFM-01:" - new: true - confirm: true - note: "horizontal focusing mirror with a piezo fine-pitch; coating stripe (Si / Rh / Pt by energy band) is a hutch-keyed setting; the piezo write is access-gated (OPT-1, ACCESS-1)" - - name: VerticalFocusingMirror - family: Mirror - pv: "BL19I-OP-VFM-01:" - new: true - confirm: true - note: "vertical focusing mirror with a piezo fine-pitch; coating stripe setting as the HFM (OPT-1)" - - name: Attenuator - family: Filter - pv: "BL19I-OP-ATTN-04:" - new: true - confirm: true - note: "absorber-wedge attenuator (X / Y wedge motors, BL19I-OP-ATTN-04 / -05); reuses Filter (the i03 precedent); the wedge write is access-gated (ATTN-1, ACCESS-1)" - - name: BeamEnergy - family: PseudoAxis - pv: {confirm: "incident-energy virtual axis over the DCM and the undulator (the access-controlled energy composite); the coordinated DCM + undulator + mirror-stripe move is gated by the active-hutch permit; partition rule and range are MONO-1 / ACCESS-1"} - new: true - confirm: true - note: "incident-energy pseudo-axis over the DCM and undulator (the 2-BM beam-energy pattern); the coordinated cross-Asset move is the access-gated energy procedure (MONO-1, ACCESS-1)" - - name: OpticsShutter - family: Shutter - pv: "BL19I-PS-SHTR-01:" - new: true - confirm: true - note: "the experiment shutter (InterlockedHutchShutter, PSS-interlocked); the per-hutch operate is access-gated, the interlock is an Enclosure permit concern (PSS-1, ACCESS-1)" - -# =========================================================================== -# EH1 ENDSTATION (i19-1): on-axis sample viewing, triggering, beamstop -# =========================================================================== - -eh1: - stage: sample - enclosure: i19-1 - intro: "The EH1 experiment hutch endstation: the on-axis sample-viewing cameras, the hardware trigger, and the beamstop. Which hutch holds the four-circle is ENC-1." - note: "All reuse existing catalog Families. The OAV viewing cameras bind Camera; their pin-tip image recognition is a centring behaviour, not a device. The Zebra binds TimingController; the beamstop binds BeamStop." - devices: - - name: SampleViewerOnAxis - family: Camera - pv: "BL19I-EA-OAV-01:" - new: true - confirm: true - note: "on-axis OAV viewing camera with zoom lens; pin-tip recognition for sample centring is a Method behaviour on the Camera (DET-1)" - - name: SampleViewerDiagonal - family: Camera - pv: "BL19I-EA-OAV-02:" - new: true - confirm: true - note: "diagonal OAV viewing camera (no zoom); second viewing camera for centring (DET-1)" - - name: TriggerControllerEH1 - family: TimingController - pv: "BL19I-EA-ZEBRA-02:" - new: true - confirm: true - note: "the EH1 Zebra hardware-trigger box (TTL routing); a second Zebra box is connected but unused (DET-1)" - - name: BeamstopEH1 - family: BeamStop - pv: "BL19I-RS-ABSB-01:" - new: true - confirm: true - note: "the EH1 beamstop (X / Y / Z with homing) blocking the direct beam (DET-1)" - -# =========================================================================== -# EH2 ENDSTATION (i19-2): the four-circle, the Eiger, the serial arm, the MAPT -# =========================================================================== - -eh2: - stage: sample - enclosure: i19-2 - intro: "The EH2 experiment hutch endstation: the Newport kappa four-circle diffractometer, the Eiger area detector, the serial / microfocus arm, the MAPT pinhole and collimator, the beamstop, the backlight, and the hardware triggers." - note: > - The four-circle binds the catalog Goniometer (kappa is a setting) composed into the - catalog Assembly(Diffractometer) with a reciprocal-space PseudoAxis, named-not-built - (DIFF-1, DIFF-2). The Eiger binds Camera; the serial / microfocus arm binds a second - Goniometer (SERIAL-1); the MAPT pinhole + collimator binds Aperture (APERTURE-1); the - beamstop binds BeamStop; the backlight binds the catalog Backlight; the Zebra and PandA - bind TimingController. - devices: - - name: Diffractometer - family: Goniometer - pv: "BL19I-MO-CIRC-02:" - new: true - confirm: true - note: "the Newport kappa four-circle: phi / omega / kappa sample circles + the 2THETA detector arm + det_z, with sample centring on BL19I-MO-SAMP-02; kappa is a setting; the circle roles and the Assembly(Diffractometer) binding are DIFF-1" - - name: ReciprocalSpace - family: PseudoAxis - pv: {confirm: "reciprocal-space virtual axis over the four-circle; the kappa-to-eulerian / hkl partition rule is deferred as on 4-ID / 8-ID / i06-1 (DIFF-2)"} - new: true - confirm: true - note: "reciprocal-space pseudo-axis over the diffractometer (the Diffractometer reciprocal_space pattern); DIFF-2" - - name: Detector - family: Camera - pv: "BL19I-EA-EIGER-01:" - new: true - confirm: true - note: "the Eiger area detector recording the single-crystal diffraction pattern (DET-1)" - - name: SerialStage - family: Goniometer - pv: "BL19I-MO-SRL-01:" - new: true - confirm: true - note: "the serial / microfocus fixed-target arm (x / y / z + phi); a second sample-orientation stage; the fixed-target raster sub-mode is SERIAL-1" - - name: Aperture - family: Aperture - pv: "BL19I-OP-PCOL-01:" - new: true - confirm: true - note: "the MAPT pinhole + collimator microfocus aperture (pinhole BL19I-MO-PIN-01, collimator BL19I-MO-COL-01, configuration lookup table BL19I-OP-PCOL-01:CONFIG); reuses Aperture (the i03 MAPT precedent); the aperture-size config is a Capability settings schema (APERTURE-1)" - - name: BeamstopEH2 - family: BeamStop - pv: "BL19I-OP-ABSB-02:" - new: true - confirm: true - note: "the EH2 beamstop (X / Y / Z with homing); same Family as the EH1 beamstop (DET-1)" - - name: Backlight - family: Backlight # catalog Family (DET-1) - pv: "BL19I-EA-IOC-12:" - new: true - confirm: true - note: "the sample backlight (in / out illumination for OAV centring); binds the catalog Backlight Family (graduated across the MX / imaging fleet, DET-1)" - - name: TriggerControllerEH2 - family: TimingController - pv: "BL19I-EA-ZEBRA-03:" - new: true - confirm: true - note: "the EH2 Zebra hardware-trigger box (DET-1)" - - name: TriggerSequencer - family: TimingController - pv: "BL19I-EA-PANDA-01:" - new: true - confirm: true - note: "the EH2 PandA hardware sequencer (HDF-writing); same Family as the Zebra, PandA-vs-Zebra is a bound-Model difference (DET-1)" - -# Cross-cutting control. i19 runs EPICS (the floor) plus a blueapi optics ARBITER that -# enforces the dual-hutch access control; CORA observes and conducts over both. The -# handles above were read from dodal and carried confirm (CTRL-1, ACCESS-1). -controls: - intro: > - i19 runs on the Diamond EPICS / ophyd-async control stack, the same floor as I22, - I03, I15-1, I11, I24, I06, I10, I20-1. The device handles above are bound from the - DiamondLightSource/dodal beamline package (its i19 / i19_shared / i19_1 / i19_2 - factories and the device classes), carried confirm (CTRL-1). i19 adds a SECOND floor - element beyond EPICS: a central blueapi optics ARBITER. The shared-optics writes - (change energy, operate the experiment shutter, move the attenuator, set a mirror - piezo) are not direct EPICS writes; each hutch posts the operation to the arbiter - with its hutch identity, and the arbiter compares it against the active-hutch - readback (BL19I-OP-STAT-01:EHStatus) and runs or rejects it. CORA models this as an - Enclosure-permit + Trust-gate over the shared-optics Assets, with the arbiter as an - actuate-floor seam partner (the "EPICS is the floor" pattern, here a blueapi-arbiter - floor): CORA's edge would conduct the run over its ControlPort, either driving - through the arbiter or replacing its plan-orchestration per routine, a seam decision - not pre-empted here (ACCESS-1). The Eiger file-writing to the Diamond filestore is - plumbing CORA observes, not data it owns (see model.md). - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources an i19 run needs. The optics run under - vacuum (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the shared optics line (SUP-1)" diff --git a/deployments/i20-1/beamline.yaml b/deployments/i20-1/beamline.yaml deleted file mode 100644 index 59e716c727a..00000000000 --- a/deployments/i20-1/beamline.yaml +++ /dev/null @@ -1,156 +0,0 @@ -# I20-1 beamline descriptor (Diamond Light Source), reverse-engineered -# -# I20-1 is the Diamond energy-dispersive EXAFS (EDE) branch of i20: time-resolved -# X-ray absorption spectroscopy. Where scanning XAS (e.g. NSLS-II BMM) steps a -# monochromator through energies, EDE uses a bent-crystal polychromator to fan a band -# of energies across the sample at once and a position-sensitive strip detector to -# read the whole absorption spectrum in a single shot, so a spectrum is captured in -# sub-second time. It is bound to the Diamond Site (deployments/diamond/site.yaml), -# the eighth Diamond beamline, modelled from the dodal controls library. -# -# STATUS: reverse-engineered, design-phase, and DELIBERATELY PARTIAL. The dodal -# module for i20-1 (named p51.py, its commissioning name; PV root BL51P) is a thin -# commissioning roster: it carries the EDE PERIPHERALS (the energy-selecting turbo -# slit, two PandA timing boxes, a trajectory PMAC, a mocked sample stage, a skipped -# Xspress3) but NOT the two devices that define energy-dispersive EXAFS: the -# bent-crystal polychromator and the position-sensitive strip detector. Those, and the -# absent source / mirror / ion-chamber chain, are routed to open questions, NOT -# fabricated (POLY-1, STRIP-1, SRC-1). Every value is read from dodal or inferred, -# carried `confirm: true` pending Diamond staff. -# -# It introduces NO new catalog family: the turbo slit reuses Slit, the PMAC -# MotionController, the PandAs TimingController, the sample stage the graduated -# Manipulator, the Xspress3 the graduated EnergyDispersiveSpectrometer. The dispersive -# polychromator (a genuinely new optic class, an energy-fanning bent crystal distinct -# from a Monochromator) is NOT coined as a family here because it is not in the source -# (POLY-1): no PV to anchor it. No Capability or Method is coined; the EDE technique is -# a pending Practice on the Site (TECH-1). - -beamline: - maturity: model - evidence: controls_config - coverage: partial - summary: "energy-dispersive / time-resolved EXAFS (EDE); a deliberately partial first cut, the dispersive polychromator + strip detector deferred (POLY-1 / STRIP-1)" - name: I20-1 - facility: diamond # Diamond Site (facility_code: diamond) - sector: "i20-1 (EDE)" # PV namespace BL51P* (dodal module p51, commissioning name) - tier: Unit - parent: null - source: insertion-device - source_confirm: "i20 is an undulator beamline, but the source / insertion device / front-end is not in the dodal commissioning module (p51.py); the PV root BL51P would carry it. Source identity and parameters are an open question (SRC-1)" - page_layout: stages - shape: "Energy-dispersive EXAFS (EDE): a bent-crystal polychromator disperses a band of energies across the sample and a strip detector captures the whole absorption spectrum in one shot; a partial scaffold pending the dispersive optics." - source_ref: - label: "DiamondLightSource/dodal" - url: "https://github.com/DiamondLightSource/dodal" - -enclosures: - # The dodal commissioning module exposes no enclosure / hutch layout, only the - # polychromator-enclosure (PCHRO) turbo slit and the experiment devices. Modelled as - # the optics hutch + the experiment hutch; names and PSS permit leaves are a staff - # question (ENC-1, PSS-1). - - name: I20-1-OH - role: optics-hutch - facility_code: diamond - permit_signal: {confirm: "PSS permit leaf not in the dodal module (PSS-1, ENC-1)"} - - name: I20-1-EH - role: experiment-hutch - facility_code: diamond - permit_signal: {confirm: "PSS permit leaf not in the dodal module; the experiment hutch carries the sample stage and the detectors (PSS-1, ENC-1)"} - -# =========================================================================== -# SOURCE STAGE: the insertion-device source (absent from the commissioning module) -# =========================================================================== - -source: - stage: source - enclosure: I20-1-OH - intro: "The insertion-device source. It is not in the dodal commissioning module (SRC-1); no source, front-end, or primary-mirror device is exposed." - devices: - - name: Source - family: InsertionDevice - confirm: true - note: "i20 undulator source. Not in the dodal commissioning module (p51.py); no PV, front-end, or storage-ring monitor is exposed. Identity and parameters pending (SRC-1)." - -# =========================================================================== -# OPTICS STAGE: the energy-dispersive polychromator and its energy-selecting turbo slit -# =========================================================================== - -optics: - stage: source - enclosure: I20-1-OH - intro: "The energy-dispersive optic chain. The bent-crystal polychromator that fans the energy band (the heart of EDE) is NOT in the dodal module (POLY-1); what is modelled is the turbo slit that selects an energy out of the dispersed fan. PVs verified against dodal src/dodal/beamlines/p51.py and devices/turbo_slit.py." - devices: - - name: TurboSlit - family: Slit - pv: "BL51P-OP-PCHRO-01:TS:" - confirm: true - note: "Energy-selecting turbo slit (turbo_slit) at the polychromator: gap (energy resolution), arc (coarse gap-centre), and xfine (the main scanning axis selecting an energy out of the polychromatic fan). Reuses the Slit family. The dispersive polychromator it sits at is not in the source (POLY-1)." - - name: EnergyAxis - family: PseudoAxis - confirm: true - note: "The energy selected from the dispersed fan by the turbo-slit xfine axis (BL51P-OP-PCHRO-01:TS:XFINE, also exposed standalone for the PMAC fly-scan). In full EDE the strip detector reads the whole band at once; the turbo slit picks a single energy for alignment / single-energy work. No separate PV (it is the turbo-slit axis)." - -# =========================================================================== -# SAMPLE STAGE: the sample alignment stage -# =========================================================================== - -sample: - stage: sample - enclosure: I20-1-EH - intro: "The sample alignment stage. PVs verified against dodal src/dodal/beamlines/p51.py." - devices: - - name: SampleStage - family: Manipulator - pv: "BL51P-MO-STAGE-01:" - confirm: true - note: "Sample alignment stage (alignment_x / alignment_y, BL51P-MO-STAGE-01:X / Y). Reuses the graduated Manipulator family. The dodal module currently constructs it as a mock device (mock=True, the comment notes the motors are being reconnected on the beamline), so the PV is real but not yet connected (STAGE-1)." - -# =========================================================================== -# DETECTION STAGE: the strip detector (absent) and the Xspress3 fluorescence detector -# =========================================================================== - -detector: - stage: detection - enclosure: I20-1-EH - intro: "The detectors. The position-sensitive strip detector that reads the dispersed spectrum in one shot (the EDE primary detector) is NOT in the dodal module (STRIP-1); what is present is a fluorescence Xspress3. PVs verified against dodal p51.py and devices/xspress3/xspress3.py." - devices: - - name: FluorescenceSpectrometer - family: EnergyDispersiveSpectrometer - pv: "BL51P-EA-DET-03:" - confirm: true - note: "Xspress3 16-channel energy-dispersive fluorescence detector (xspress3). Reuses the graduated EnergyDispersiveSpectrometer family. The dodal module currently constructs it with skip=True (defined but not loaded by default), so it is carried confirm (DET-1). The EDE primary detector, a position-sensitive strip detector reading the dispersed spectrum, is not in the source (STRIP-1)." - -# =========================================================================== -# Cross-cutting controls -# =========================================================================== - -controls: - intro: > - The trajectory motion controller and the timing boxes that drive the EDE - fly-scan. The turbo-slit xfine axis is swept by a PMAC trajectory program; the - PandA boxes provide hardware triggering and position capture. - triggering: - - name: Timing - family: TimingController - pv: "BL51P-EA-PANDA-02:" - confirm: true - note: "PandA FPGA timing / sequencer + HDF writer (panda1, BL51P-EA-PANDA-02:); a second PandA (panda2, BL51P-EA-PANDA-01:) sits alongside. Hardware triggering and position capture for the fly-scan." - motion_controllers: - - name: TurboSlitController - family: MotionController - pv: "BL51P-MO-STEP-06:" - confirm: true - note: "PMAC trajectory controller (turbo_slit_pmac) running the turbo-slit xfine fly-scan over coordinate system 3. Box firmware / IP not in the dodal module (DRIVE-1)." - software_iocs_not_modeled: - [PandA, PMAC, Xspress3] - -resources: - intro: Continuously-available resources. Facility-scope supplies live in deployments/diamond/site.yaml. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: Power - replaceable_parts: - swappable_with_identity: ["polychromator crystal", "sample"] diff --git a/deployments/i22/beamline.yaml b/deployments/i22/beamline.yaml deleted file mode 100644 index c2ad194ce80..00000000000 --- a/deployments/i22/beamline.yaml +++ /dev/null @@ -1,332 +0,0 @@ -# CORA Beamline descriptor: I22 (Diamond Light Source), design-phase scaffold -# -# I22 is an operating small- and wide-angle X-ray scattering (SAXS/WAXS) beamline -# at Diamond Light Source. It is bound to the Diamond Site -# (deployments/diamond/site.yaml). -# -# STATUS: design-phase modelling exercise, NOT a CORA pilot. The device shape and -# the EPICS control handles below are reverse-engineered from Diamond's open -# `dodal` controls library (github.com/DiamondLightSource/dodal, src/dodal/ -# beamlines/i22.py and its device classes), treated as a dry, correct DATA source -# and modelled here intentionally, not mirrored. -# -# What is DIFFERENT from the TomoWISE scaffold: I22 runs EPICS, and dodal records -# the real PV prefixes, so `pv` IS carried here (dodal is the source). Every -# device still carries `new: true` (not yet modelled in CORA as an Asset) and -# `confirm: true` (the values, and the snapshot PVs, are to be verified by Diamond -# staff). No vendor `model` is bound: families-only, so no part is procured into -# the catalog (this also keeps the descriptor clear of the catalog cross-checks). -# -# What dodal CANNOT supply, and so is NOT invented here: calibrated numbers -# (energy range, beam size, motor limits, beam-center, threshold energy, camera -# lengths as a range, z-positions), the hutch/PSS safety structure, the passive -# beam-path tier, and the technique/Capability binding. Each gap is tagged inline -# with a (QUESTION-ID) answered on docs/deployments/i22/questions.md. -# -# 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: - maturity: model - evidence: controls_config - coverage: full - summary: "small- and wide-angle X-ray scattering (SAXS/WAXS), reverse-engineered from dodal" - name: I22 - facility: diamond - tier: Unit - parent: null - source: insertion-device - source_confirm: "undulator source (dodal UndulatorInKeV on SR22I); period / gap range / energy range not in dodal (SRC-1)" - page_layout: stages - shape: "Small- and wide-angle X-ray scattering (SAXS / WAXS): two area detectors run simultaneously at long and short camera length, with quantitative incident / transmitted flux; the first scattering shape after the tomography pilots." - source_ref: - label: "DiamondLightSource/dodal" - url: "https://github.com/DiamondLightSource/dodal" - -# Two access-gated hutches. dodal PV prefixes encode functional zones (OP optics, -# MO motion, EA end-station, DI diagnostics) but NOT the hutch each device sits in -# or its PSS meaning; the hutch split below is the standard Diamond optics + -# experiment layout, carried confirm (ENC-1). Diamond PSS permit signals TBD (PSS-1). -enclosures: - - name: i22-optics - role: optics-hutch - facility_code: diamond - permit_signal: {confirm: "Diamond PSS permit signal TBD (PSS-1)"} - - name: i22-experiment - role: experiment-hutch - facility_code: diamond - permit_signal: {confirm: "Diamond PSS permit signal TBD (PSS-1)"} - -# --- SOURCE STAGE: beam delivery and conditioning --- - -source: - stage: source - enclosure: i22-optics - intro: "The undulator source and the machine-level storage-ring state it draws on." - note: > - The undulator parameters dodal carries (80 poles, 2.0 m) are dry facts; the - energy range and gap-to-energy curve are calibration the deployment must - supply (SRC-1). The storage-ring device is machine-shared and observe-only; - its modelling boundary is open (MACHINE-1). - devices: - - name: Undulator - family: InsertionDevice - pv: "SR22I-MO-SERVC-01:" - new: true - confirm: true - poles: 80 - length: 2.0 m - mechanism: gap-to-energy via lookup table (BeamLine_Undulator_toGap.txt) - note: "the SAXS/WAXS source; energy range and gap curve to confirm (SRC-1)" - - name: StorageRing - family: StorageRing - new: true - confirm: true - note: "machine-level, beamline-shared, observe-only source state (ring current, energy, fill mode, top-up countdown); loose family, interim observe-only binding (MACHINE-1)" - -conditioning-optics: - stage: source - enclosure: i22-optics - intro: "The mirrors, monochromator, and transfocator that focus, monochromate, and condition the beam." - note: > - Mirror internal axes (yaw/pitch/roll, jacks), the DCM crystal d-spacing and - thermal reads, and the bimorph voltage channels are device internals carried - as notes/settings, not separate Families (OPT-1). The transfocator binds the - graduated Transfocator catalog Family (a CRL focusing optic). - devices: - - name: DCM - family: Monochromator - pv: "BL22I-MO-DCM-01:" - new: true - confirm: true - crystal: Si(111) - temperature_pv: "BL22I-DI-DCM-01:" - note: "double-crystal monochromator; crystal d-spacing + thermal model are settings to confirm (OPT-1)" - - name: VFM - family: Mirror - pv: "BL22I-OP-KBM-01:VFM:" - new: true - confirm: true - axes: yaw / pitch / roll / x / y / jacks (Y1-3) / translations (X1-2) - note: "vertical focusing mirror (KB pair)" - - name: HFM - family: Mirror - pv: "BL22I-OP-KBM-01:HFM:" - new: true - confirm: true - axes: yaw / pitch / roll / x / y / jacks (Y1-3) / translations (X1-2) - note: "horizontal focusing mirror (KB pair)" - - name: BimorphHFM - family: Mirror - pv: "BL22I-OP-KBM-01:G0:" - new: true - confirm: true - channels: 12 - note: "adaptive bimorph wavefront correction on the HFM; the voltage channels are settings, not a new Family (OPT-1)" - - name: BimorphVFM - family: Mirror - pv: "BL22I-OP-KBM-01:G1:" - new: true - confirm: true - channels: 32 - note: "adaptive bimorph wavefront correction on the VFM" - - name: Transfocator - family: Transfocator - pv: "BL22I-MO-FSWT-01:" - new: true - confirm: true - lens_material: Beryllium - lens_geometry: paraboloid (cylindrical) - note: "compound-refractive-lens transfocator; binds the graduated Transfocator catalog Family (a CRL focusing optic); lens count is a per-Asset setting to confirm" - -beam-defining: - stage: source - enclosure: i22-optics - intro: "The beam-defining slits along the conditioning path." - note: > - Five of the six are four-independent-blade slits (the catalog Slit shape - exactly: x/y plus/minus blades forming a variable opening); slit 4 exposes - gap+centre only, a fewer-DOF setting within the same Family. - devices: - - name: Slit1 - family: Slit - pv: "BL22I-AL-SLITS-01:" - new: true - confirm: true - blades: four independent (x_plus/x_minus/y_plus/y_minus) - - name: Slit2 - family: Slit - pv: "BL22I-AL-SLITS-02:" - new: true - confirm: true - blades: four independent - - name: Slit3 - family: Slit - pv: "BL22I-AL-SLITS-03:" - new: true - confirm: true - blades: four independent - - name: Slit4 - family: Slit - pv: "BL22I-AL-SLITS-04:" - new: true - confirm: true - blades: gap + centre only (fewer-DOF setting) - - name: Slit5 - family: Slit - pv: "BL22I-AL-SLITS-05:" - new: true - confirm: true - blades: four independent - - name: Slit6 - family: Slit - pv: "BL22I-AL-SLITS-06:" - new: true - confirm: true - blades: four independent - -# --- SAMPLE STAGE: the experiment hutch --- - -sample-environment: - stage: sample - enclosure: i22-experiment - intro: "The sample base, the on-axis-view alignment camera, the incident and transmitted flux monitors, and the sample-environment actuators." - note: > - 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 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 - pv: "BL22I-MO-STABL-01:" - new: true - confirm: true - axes: X / Y / PITCH - note: "sample base table; the PITCH axis is a TiltStage axis in a per-axis split" - - name: OAV - family: Camera - pv: "BL22I-DI-OAV-01:" - new: true - confirm: true - note: "on-axis-view alignment camera (AVT Mako G-507B); working distance + effective pixel size are placeholders in the controls source, to be supplied (OAV-1)" - - name: I0 - family: FluxMonitor - pv: "BL22I-EA-XBPM-02:" - new: true - confirm: true - note: "incident-flux ion chamber / XBPM (Tetramm, 4-channel current); presents the Sensor Role; FluxMonitor catalog Family (graduated) (FLUX-1)" - - name: It - family: FluxMonitor - pv: "BL22I-EA-TTRM-02:" - new: true - confirm: true - note: "transmitted-flux ion chamber (Tetramm); presents the Sensor Role; FluxMonitor catalog Family (graduated) (FLUX-1)" - - name: SampleTemperature - family: TemperatureController - 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 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 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 --- - -detector: - stage: detection - enclosure: i22-experiment - intro: "The two Pilatus area detectors that record SAXS and WAXS frames simultaneously, and the beamstops that protect them." - note: > - SAXS and WAXS are the same detector model at different camera lengths: one - Camera Family, two Asset instances separated by mount distance and technique - role, not a Family split. The camera lengths dodal carries are a single - calibration snapshot; whether the detector distance is a fixed mount or a - settable axis is open (DET-1). Threshold energy and beam-center are not in - dodal (DET-2). - devices: - - name: SaxsDetector - family: Camera - pv: "BL22I-EA-PILAT-01:" - new: true - confirm: true - detector: Dectris Pilatus3 2M - detector_type: photon-counting hybrid pixel - pixel_size: 0.172 mm - sensor: silicon, 0.45 mm thick - note: "small-angle detector (long camera length); camera length to confirm (DET-1), threshold energy + beam-center to confirm (DET-2)" - - name: WaxsDetector - family: Camera - pv: "BL22I-EA-PILAT-03:" - new: true - confirm: true - detector: Dectris Pilatus3 2M - detector_type: photon-counting hybrid pixel - pixel_size: 0.172 mm - sensor: silicon, 0.45 mm thick - note: "wide-angle detector (short camera length); camera length to confirm (DET-1)" - - name: BeamStop1 - family: BeamStop - pv: "BL22I-MO-SAXSP-01:BS1:" - new: true - confirm: true - note: "SAXS beamstop (positioned X/Y)" - - name: BeamStop2 - family: BeamStop - pv: "BL22I-MO-SAXSP-01:BS2:" - new: true - confirm: true - note: "SAXS beamstop (positioned X/Y)" - - name: BeamStop3 - family: BeamStop - pv: "BL22I-MO-SAXSP-01:BS3:" - new: true - confirm: true - note: "SAXS beamstop (positioned X/Y + roll)" - -# Cross-cutting drive electronics and triggering. dodal records the PandA FPGA -# trigger boxes; the motion controllers are not exposed as dodal devices, so -# none is modelled here. -controls: - intro: > - I22 runs the Diamond EPICS control stack (driven by GDA and bluesky/blueapi - on the floor). dodal records the device PV prefixes carried above; the - PandABox FPGA timing boxes generate the triggers and gates. - triggering: - - name: Panda1 - family: TimingController - pv: "BL22I-EA-PANDA-01:" - new: true - confirm: true - note: "Zynq-FPGA trigger/gate generation + HDF capture; binding to the detectors + flux monitors is open (TRIG-1)" - - name: Panda2 - family: TimingController - pv: "BL22I-EA-PANDA-02:" - new: true - confirm: true - note: "second PandABox; two more (Panda3/4) exist in dodal but are skip-flagged" - software_iocs_not_modeled: - - GDA (Generic Data Acquisition; Diamond's acquisition software) - - bluesky / blueapi (the bluesky-as-a-service layer dodal feeds) - -# Continuously-available resources a run draws on (design phase). -resources: - intro: > - The continuously-available facility resources a run needs present before it - can start. All pending confirmation in the design phase. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/i24/beamline.yaml b/deployments/i24/beamline.yaml deleted file mode 100644 index 6796da46f0d..00000000000 --- a/deployments/i24/beamline.yaml +++ /dev/null @@ -1,241 +0,0 @@ -# i24 beamline descriptor (Diamond), reverse-engineered -# -# i24 is the Diamond Light Source serial / fixed-target macromolecular -# crystallography beamline at sector 24. It is bound to the Diamond Site -# (deployments/diamond/site.yaml), the fifth Diamond beamline after I22, I03, -# I15-1, and I11, and CORA's FIRST synchrotron serial-crystallography deployment. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (Diamond's dodal controls library, src/dodal/beamlines/i24.py + its -# device classes) or inferred, carried `new: true` + `confirm: true` pending i24 -# staff. EPICS PVs are real and verified against dodal; vendor part numbers, -# serials, and physical positions are not in it and are open questions. Same -# descriptor mode as the other Diamond deployments; this scaffold is descriptor + -# docs, scenarios deferred. -# -# WHAT IS NEW: i24 is CORA's first SERIAL / FIXED-TARGET crystallography. Unlike -# I03 rotation MX (one crystal, a continuous omega sweep), i24 raster-scans a -# fixed-target chip holding thousands of static crystals, taking one diffraction -# snapshot per addressable chip window, hardware-sequenced on the PMAC motion -# controller with Zebra TTL gating and no goniometer rotation. The acquisition -# primitive is a triggered chip-raster fly-collection over a sample grid. This is -# a new Capability, deferred as a question (SSX-1); the fleet has serial -# crystallography only as a pending stub at the SLAC LCLS-MFX XFEL. -# -# MODELLING: every device reuses an existing catalog or loose Family. i24 coins -# NO new Family and changes nothing in the catalog. The vertical goniometer reuses -# the catalog Goniometer (graduated at I03); the PMAC chip stage is an XYZ -# LinearStage (the serial raster trajectory and the laser / Zebra triggering are -# the orchestration seam CORA's edge replaces, not a device Family); the -# fixed-target chip itself (the addressable sample grid the stage rasters) is a -# Fixture / Subject-grid, a CORA modelling decision deferred as CHIP-1 (the chip -# well map is not a PV). The serial-crystallography Capability is deferred (SSX-1). -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/i24/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "serial / fixed-target macromolecular crystallography (chip-coordinate single-shot); reuses the Goniometer, first synchrotron serial MX" - name: I24 - facility: diamond # Diamond Site (facility_code: diamond) - sector: "Sector 24" # PV namespace BL24I* - tier: Unit - parent: null - source: insertion-device - source_confirm: "i24 is an undulator MX beamline; dodal exposes the Synchrotron source state (modelled below) but not the insertion-device gap as a device, so the undulator detail is SRC-1" - page_layout: stages - shape: "The fleet's first synchrotron serial / fixed-target crystallography: thousands of static crystals on a chip raster-scanned across the beam, one Zebra-gated snapshot per window, no goniometer rotation." - source_ref: - label: "DiamondLightSource/dodal" - url: "https://github.com/DiamondLightSource/dodal" - -# PV zones: BL24I-OP / -DI (optics, DCM, mirrors, OAV), BL24I-AL (aperture), -# BL24I-MO (motion: goniometer, chip stage, beamstop, detector stage), -# BL24I-EA (endstation: Eiger / Jungfrau detectors, Zebra, sample shutter). -# Whether i24 is one optics hutch plus one experiment hutch, and the PSS permit -# leaves, are open (ENC-1, PSS-1). -enclosures: - - name: i24-optics - role: optics-hutch - facility_code: diamond - permit_signal: {confirm: "PSS permit leaf not in source; the hutch shutter is the dodal InterlockedHutchShutter (PSSInterlock), permit-leaf names are PSS-1"} - - name: i24-experiment - role: experiment-hutch - facility_code: diamond - permit_signal: {confirm: "PSS permit leaf unknown; the serial-crystallography endstation hutch (ENC-1, PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the machine source state and the optics -# =========================================================================== - -machine: - stage: source - enclosure: i24-optics - intro: "The machine-level source state, observed not driven." - note: "dodal's Synchrotron device is the observe-only machine state, the loose StorageRing pattern reused from the Diamond siblings (MACHINE-1). The undulator gap is not a dodal device here (SRC-1)." - devices: - - name: Synchrotron - family: StorageRing # loose Family (machine-level observe-only source state; MACHINE-1) - pv: {confirm: "dodal Synchrotron device (ring current, top-up, machine mode); observe-only, the exact PVs are MACHINE-1"} - new: true - confirm: true - note: "machine source state; observe-only, not photon-path flux (MACHINE-1)" - -optics: - stage: source - enclosure: i24-optics - intro: "The double-crystal monochromator, the focusing mirrors, the attenuator, and the aperture." - note: "All reuse existing catalog Families. The DCM selects the incident energy; the focusing mirrors set the beam at the sample; the attenuator reuses the Filter Family (the I03 / i15-1 attenuator precedent)." - devices: - - name: Monochromator - family: Monochromator - pv: "BL24I-MO-DCM-01:" - new: true - confirm: true - note: "double-crystal monochromator (motion BL24I-MO-DCM-01:, diagnostics BL24I-DI-DCM-01:); crystal cut, d-spacing, energy range are MONO-1" - - name: FocusingMirrors - family: Mirror - pv: "BL24I-OP-MFM-01:" - new: true - confirm: true - note: "focusing mirrors with selectable focus mode (dodal FocusMirrorsMode); coatings and the focus-mode set are OPT-1" - - name: Attenuator - family: Filter - pv: "BL24I-OP-ATTN-01:" - new: true - confirm: true - note: "filter-based attenuator (two filter-selection enums); reuses the Filter Family, not a new Attenuator kind (ATTN-1)" - - name: Aperture - family: Aperture - pv: "BL24I-AL-APTR-01:" - new: true - confirm: true - note: "beam-defining aperture (OPT-2)" - -# =========================================================================== -# SAMPLE STAGE: the goniometer, the fixed-target chip stage, the backlight, OAV -# =========================================================================== - -sample: - stage: sample - enclosure: i24-experiment - intro: "The vertical goniometer, the fixed-target chip stage, the sample backlight, the on-axis-view camera, the beamstop, and the sample shutter." - note: > - vgonio is the vertical pin goniometer, reusing the catalog Goniometer (the - Family I03 graduated). pmac is the fixed-target chip stage: an XYZ LinearStage - that rasters the addressable chip across the beam. The chip itself (the grid of - thousands of static crystals) is a Fixture / Subject grid, a CORA modelling - decision deferred (CHIP-1); the serial raster trajectory, the encoder - position-compare, and the laser triggers run on the PMAC controller and are the - orchestration seam CORA's edge replaces, not device Families (SSX-1, LASER-1). - devices: - - name: Goniometer - family: Goniometer - pv: "BL24I-MO-VGON-01:" - new: true - confirm: true - note: "vertical pin goniometer (dodal VerticalGoniometer); reuses the I03-graduated Goniometer Family; the circle / pin-translation axes are GONIO-1" - - name: ChipStage - family: LinearStage - pv: "BL24I-MO-CHIP-01:" - new: true - confirm: true - note: "fixed-target chip stage (dodal PMAC, an XYZ stage); positions the addressable chip. The chip-as-Fixture / Subject-grid modelling is CHIP-1; the on-controller raster trajectory + laser / encoder triggering is the serial-collection seam (SSX-1)" - - name: Backlight - family: Backlight # catalog Family (illumination; DET-1) - pv: "BL24I" - new: true - confirm: true - note: "dual sample backlight (dodal DualBacklight); binds the catalog Backlight Family (graduated across the MX / imaging fleet, DET-1); the PV root and positions are BACKLIGHT-1" - - name: OnAxisViewer - family: Camera - pv: "BL24I-DI-OAV-01:" - new: true - confirm: true - note: "on-axis-view alignment camera with beam-centre file (dodal OAVBeamCentreFile); the zoom / beam-centre config lives in GDA files under /dls_sw (CTRL-1)" - - name: Beamstop - family: BeamStop - pv: "BL24I-MO-BS-01:" - new: true - confirm: true - note: "beamstop (positioned); axis roles are OPT-2" - - name: SampleShutter - family: Shutter - pv: "BL24I-EA-SHTR-01:" - new: true - confirm: true - note: "fast sample shutter (dodal MXZebraShutter), Zebra-controlled; gates the per-window exposure (SSX-1)" - -# =========================================================================== -# DETECTION STAGE: the area detectors, the detector stage, and the timing -# =========================================================================== - -detection: - stage: detection - enclosure: i24-experiment - intro: "The area detectors, the detector translation stage, and the Zebra timing / triggering." - note: > - The Eiger is the production area detector (modelled as Camera presenting the - Detector Role); the Jungfrau is carried as a commissioning detector (DET-1). - The Zebra hardware-sequences the chip-raster collection (per-window TTL gating - of the detector and the fast shutter), the TimingController Family; the detailed - trigger graph is the serial-collection seam CORA's edge drives (SSX-1). - devices: - - name: EigerDetector - family: Camera - pv: "BL24I-EA-EIGER-01:CAM:" - new: true - confirm: true - note: "Eiger area detector (Detector Role); dodal exposes a DetectorBeamCenter helper here, the full detector + beam-centre are DET-1" - - name: JungfrauDetector - family: Camera - pv: "BL24I-EA-JFRAU-01:" - new: true - confirm: true - note: "Jungfrau area detector, carried as commissioning (dodal CommissioningJungfrauDetector); model the Eiger path as primary (DET-1)" - - name: DetectorStage - family: LinearStage - pv: "BL24I-MO-DET-01:" - new: true - confirm: true - note: "detector translation stage (Y/Z); sets the detector distance / position (OPT-2)" - - name: Timing - family: TimingController - pv: "BL24I-EA-ZEBRA-01:" - new: true - confirm: true - note: "Zebra FPGA timing / triggering (TTL map: Eiger / Jungfrau / fast shutter); hardware-sequences the chip raster (SSX-1)" - - name: HutchShutter - family: Shutter - pv: {confirm: "dodal InterlockedHutchShutter with a PSSInterlock; the photon-shutter and permit-leaf PVs are PSS-1"} - new: true - confirm: true - note: "interlocked hutch photon shutter; the PSS permit structure is PSS-1" - -# Cross-cutting control. i24 runs EPICS (the floor); CORA observes and, where it -# replaces bluesky / GDA-style orchestration, conducts over it. The handles above -# were read from dodal (src/dodal/beamlines/i24.py) and carried confirm (CTRL-1). -controls: - intro: > - i24 runs on the Diamond EPICS / ophyd-async control stack, the same floor as - the other Diamond beamlines. The device handles above are bound from dodal, - carried confirm pending staff verification (CTRL-1). The serial collection (the - PMAC chip-raster motion program, the encoder position-compare, the laser - triggers, the Zebra TTL gating of the detector and fast shutter) is the - orchestration CORA's edge replaces, driving through ophyd / EPICS; the OAV zoom - and beam-centre config and the detector file-writing to the Diamond filestore - are plumbing CORA observes, not data it owns (see model.md). - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources an i24 run needs. The optics run - under vacuum (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the optics beam path is under vacuum (SUP-1)" diff --git a/deployments/id16b/beamline.yaml b/deployments/id16b/beamline.yaml deleted file mode 100644 index 887d530b791..00000000000 --- a/deployments/id16b/beamline.yaml +++ /dev/null @@ -1,242 +0,0 @@ -# ID16B beamline descriptor (ESRF), reverse-engineered from the public BLISS config -# -# ID16B is the nano-analysis / nano-imaging beamline at the ESRF (Grenoble): it -# focuses the hard X-ray beam to a nanoprobe with Kirkpatrick-Baez mirrors and runs -# two modes, nano-tomography and nano-XRF (X-ray fluorescence) mapping, including -# fluorescence-tomography. It is bound to the ESRF Site (deployments/esrf/site.yaml), -# the second ESRF deployment after ID19, and the fleet's first nanoprobe on a BLISS -# (non-EPICS) control floor. -# -# STATUS: reverse-engineered from ID16B's own public BLISS Beacon device database -# (gitlab.esrf.fr/id16b/beamline_configuration, commit 7cba4dd). Device names and -# control handles are real, read from that config; vendor part numbers, serials, -# energy ranges, and physical positions are not in it and are open questions. Every -# value is carried confirm until ID16B staff verify it. -# -# WHAT IS NEW: nothing in the catalog. Nano-tomography is plain `tomography` Method -# reuse (ID19, 2-BM, TomoWise); nano-XRF mapping reuses the pending -# scanning_fluorescence_microscopy Method that 2-ID / XFM / LIX carry. The rotation -# stage binds RotaryStage, the positioning and piezo-scanner stages bind LinearStage, -# the KB mirrors bind Mirror, the XRF detector binds EnergyDispersiveSpectrometer -# (the 2-ID / SRX / XFM precedent), and the area detector binds Camera. ID16B coins -# NO new Family. It is the first nanoprobe (KB nanofocus + XRF) on the BLISS floor, -# a second ESRF deployment deepening the non-EPICS seam evidence. -# -# CONTROL HANDLES: ESRF runs BLISS over Tango. The descriptor `pv` field carries the -# BLISS object name or Tango device name read from the config (control Tango domain -# id16b / id16na). A motion stage is a BLISS axis; a detector is a Lima or MOSCA -# Tango device. -# -# SCOPE: this cut models the source, the optics (DCM, slits, KB nanofocus), the -# sample-scanning stack, and the two detection chains (XRF spectrometers + area -# detectors). The sample environments (cryostream, furnace, xeol) are noted in the -# extraction facts but not modelled here (no Cryostat Family yet; ENV-1). -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/id16b/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "KB-focused hard X-ray nano-tomography and nano-XRF on the ESRF nanoprobe" - name: ID16B - facility: esrf # ESRF Site (facility_code: esrf) - tier: Unit - parent: null - source: insertion-device - source_confirm: "U205 undulator on the ID16B straight (ESRF_Undulator); energy reach and gap mapping are SRC-1" - page_layout: stages - shape: "The fleet's first KB nanoprobe with XRF: nano-XRF mapping and nano-tomography on the ESRF BLISS / Tango floor, coining no new vocabulary." - source_ref: - label: "gitlab.esrf.fr id16b/beamline_configuration" - url: "https://gitlab.esrf.fr/id16b/beamline_configuration" - -enclosures: - - name: id16b-optics - role: optics-hutch - facility_code: esrf - permit_signal: {confirm: "ESRF PSS permit signal behind the front-end shutter; not in the config (PSS-1)"} - - name: id16b-experiment - role: experiment-hutch - facility_code: esrf - permit_signal: {confirm: "ESRF PSS permit signal behind the fast shutter; not in the config (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the undulator and the conditioning optics (DCM, slits, KB) -# =========================================================================== - -source: - stage: source - enclosure: id16b-optics - intro: "The ID16B straight-section undulator source." - note: "ESRF_Undulator (U205); energy reach and per-mode gap mapping are SRC-1." - devices: - - name: InsertionDevice - family: InsertionDevice - pv: "U205" - new: true - confirm: true - note: "the ID16B undulator source (ESRF_Undulator); energy reach is SRC-1" - -optics: - stage: source - enclosure: id16b-optics - intro: "The conditioning optics: the Kohzu double-crystal monochromator, the primary and secondary white-beam slits, and the beam-position monitors. The KB nanofocus mirrors sit in the experiment hutch with the sample." - note: "Handles read from OH/motors/ (kohzu_mono.yml, slits_s1/s2). Crystal-pair selection per energy is OPT-1." - devices: - - name: Monochromator - family: Monochromator - pv: {bragg: "mono", energy: "Edcm", energy_tracker: "Edcmund"} - new: true - confirm: true - note: "Kohzu double-crystal monochromator (ID16Bkohzu, iceid162); Si111 / Si333 / Si311 crystal pairs, energy + tracking (OPT-1)" - - name: PrimarySlits - family: Slit - pv: {fh: "s1fh", bh: "s1bh", fv: "s1fv", bv: "s1bv"} - new: true - confirm: true - note: "white-beam primary slits (s1h_slits / s1v_slits)" - - name: SecondarySlits - family: Slit - pv: {fh: "s2fh", bh: "s2bh"} - new: true - confirm: true - note: "secondary slits (s2_slits)" - - name: BeamMonitors - family: FluxMonitor - pv: {bpm2: "id16na/limaccds/bpm2", bpm3: "id16na/limaccds/bpm3", bpm5: "id16na/limaccds/bpm5"} - new: true - confirm: true - note: "ESRF beamviewer / beam-position monitors (EBV) with diode intensity counters; position-and-flux diagnostics (DIAG-1)" - -safety-shutters: - stage: source - enclosure: id16b-optics - intro: "The front-end and fast shutters gating the beam to the sample." - note: "Handles read from the config; PSS permit signals behind them are not in the config (PSS-1)." - devices: - - name: FastShutter - family: Shutter - pv: "fshut" - new: true - confirm: true - note: "sample-side fast shutter (iceid164 fshut_motor); the PSS permit leaves are PSS-1" - -# =========================================================================== -# SAMPLE STAGE: the KB nanofocus and the sample-scanning stack -# =========================================================================== - -nanofocus: - stage: sample - enclosure: id16b-experiment - intro: "The Kirkpatrick-Baez mirror pair that focuses the monochromatic beam to the nanoprobe, plus the sample-side defining slits." - note: "The KB nanofocus is what makes ID16B a nano-analysis beamline. Focal spot and working distance are OPT-1." - devices: - - name: KBMirrors - family: Mirror - pv: {kbx: "kbx", cfocus: "cfocus", cfocus2: "cfocus2"} - new: true - confirm: true - note: "Kirkpatrick-Baez focusing mirror pair (iceid164); the nanoprobe (OPT-1)" - - name: ThirdSlits - family: Slit - pv: {fh: "s3fh", bh: "s3bh", uv: "s3uv", dv: "s3dv"} - new: true - confirm: true - note: "sample-side defining slits (s3h_slits / s3v_slits, iceid164)" - -sample: - stage: sample - enclosure: id16b-experiment - intro: "The sample-scanning stack: the rotation stage for tomography and fluorescence-tomography, the coarse positioning stage, and the fine piezo raster scanner for XRF mapping." - note: "Rotation via etel Tango (id16b/dsc2p/rot16) and iceid164; the piezo scanner is a PI vscanner (SAMPLE-1)." - devices: - - name: SampleRotation - family: RotaryStage - pv: {srot: "id16b/dsc2p/rot16", srot2: "srot2"} - new: true - confirm: true - note: "tomographic / fluorescence-tomography sample rotation (etel Tango + iceid164); the master motion of a tomo scan (SAMPLE-1)" - - name: SampleStage - family: LinearStage - pv: {sx: "sx", sy: "sy", sz: "sz"} - new: true - confirm: true - note: "coarse sample positioning / centring (etel + iceid164, encoded) (SAMPLE-1)" - - name: SampleScanner - family: LinearStage - pv: {sampy: "sampy", sampz: "sampz", sypz: "sypz"} - new: true - confirm: true - note: "fine PI piezo raster scanner (vscanner1 / vscanner2); the operative motion of nano-XRF mapping (SAMPLE-1)" - -# =========================================================================== -# DETECTION STAGE: the XRF spectrometers and the area detectors -# =========================================================================== - -detection: - stage: detection - enclosure: id16b-experiment - intro: "Two detection chains: the energy-dispersive fluorescence detectors that make the XRF maps, and the area detectors that record the projection radiographs for nano-tomography." - note: "The fluorescence detector reuses the EnergyDispersiveSpectrometer family (the 2-ID / SRX / XFM precedent); the area detectors bind Camera. The operative detector per mode is DET-1." - devices: - - name: FluoDetector - family: EnergyDispersiveSpectrometer - pv: {fxb: "id16b/moscav1/fxb", fx8: "tcp://wid16bfx:8000"} - new: true - confirm: true - note: "multi-element silicon-drift XRF detector (FalconX, MOSCA); the primary nano-XRF mapping detector; reuses the EnergyDispersiveSpectrometer family (DET-1)" - - name: OpticalSpectrometer - family: EnergyDispersiveSpectrometer - pv: {qepro: "id16b/moscav1/qepro", hama1: "id16b/moscav1/hama1"} - new: true - confirm: true - note: "optical-emission spectrometer (QEPro OceanOptics + Hamamatsu) for xeol / optical readout; a Sensor-presenting spectrometer, reuses EnergyDispersiveSpectrometer (DET-2)" - - name: TomoDetector - family: Camera - pv: {pco1: "id16na/limaccds/pco1", pco2: "id16na/limaccds/pco2", zyla: "id16b/limaccds/zyla"} - new: true - confirm: true - note: "indirect-detection area detectors for nano-tomography (PCO, Andor Zyla, Lima); Camera presents the Detector Role (DET-1)" - - name: DetectorStage - family: LinearStage - pv: "DETPOS" - new: true - confirm: true - note: "detector positioning / propagation-distance stage (DetectorPositioning); the phase-contrast control (DET-1)" - -# Cross-cutting control. ID16B runs BLISS (Tango-based), the same non-EPICS floor as ID19. -controls: - intro: > - ID16B runs on the ESRF BLISS control system, Tango-based, NOT EPICS, the same floor - as ID19. A motion stage is a BLISS axis (driven by IcePAP racks iceid162 / iceid164, - PI piezo vscanners, and etel Tango motors); a fluorescence detector is a MOSCA / FalconX - Tango device; an area detector is a Lima device server (id16na/limaccds/); the - monochromator is the Kohzu DCM controller. The handles here are read from ID16B's public - Beacon config and carried confirm (CTRL-1). Nano-tomography and nano-XRF run as BLISS scan - procedures (the daiquiri_tomo and daiquiri_fluo sessions); that orchestration is the seam - CORA's edge would conduct over its ControlPort, with the reconstruction (tomo volume) and - the XRF map fitting being ComputePort work, not beamline devices (TECH-1, CTRL-2). - motion_controllers: - - name: IcePAPControllers - family: MotionController - protocol: BLISS_IcePAP - new: true - confirm: true - note: "IcePAP racks iceid162 (mono) and iceid164 (sample / KB / slits / shutter) (CTRL-1)" - - name: PiezoScanners - family: MotionController - protocol: BLISS_PI - new: true - confirm: true - note: "PI piezo scanner controllers (vscanner1 / vscanner2, E518) driving the fine XRF raster (CTRL-1)" - -resources: - intro: > - The continuously-available facility resources an ID16B run needs present before it - can start. All pending confirmation. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/id19/beamline.yaml b/deployments/id19/beamline.yaml deleted file mode 100644 index 34d988c2440..00000000000 --- a/deployments/id19/beamline.yaml +++ /dev/null @@ -1,272 +0,0 @@ -# ID19 beamline descriptor (ESRF), reverse-engineered from the public BLISS config -# -# ID19 is the long hard X-ray imaging / microtomography beamline at the ESRF -# (Grenoble). Its long source-to-sample distance gives the beam high spatial -# coherence for parallel-beam and phase-contrast microtomography and radiography. -# It is bound to the ESRF Site (deployments/esrf/site.yaml), and is CORA's FIRST -# deployment on a non-EPICS control floor. -# -# STATUS: reverse-engineered from ID19's own public BLISS Beacon device database -# (gitlab.esrf.fr/id19/beamline_configuration, commit b78389a; the live -# /users/blissadm/local/beamline_configuration YAML tree). Device names and -# control handles are real, read from that config; vendor part numbers, serials, -# energy ranges, and physical positions are not in it and are open questions. -# Every value is carried confirm until ID19 staff verify it (a config snapshot is -# strong evidence, not a CORA-owned fact). -# -# WHAT IS NEW: not a device family, and not a technique. Microtomography is plain -# `tomography` Method reuse (the same the 2-BM pilot and MAX IV TomoWise carry); -# the rotation stages bind RotaryStage, the positioning stages bind LinearStage, -# the detectors bind Camera, and the optics bind existing Families. ID19 coins NO -# new Family and changes nothing in the catalog. The genuine novelty is the -# CONTROL PLANE: ESRF runs BLISS (Tango-based), not EPICS, so ID19 is the fleet's -# first live, non-EPICS, BLISS / Tango floor (CTRL-1). Hold the device families -# constant, move one axis. -# -# CONTROL HANDLES: ESRF runs BLISS over Tango. The descriptor `pv` field is the -# opaque control-handle slot (not EPICS-specific); for ID19 it carries the BLISS -# object name or the Tango device name read from the config. A motion stage is a -# BLISS axis (e.g. hrsrot); a detector is a Lima Tango device (e.g. -# id19/limaccd/frelon1); a shutter is a TangoShutter (e.g. id19/bsh/1). -# -# SCOPE: this cut models the source, the optics, and the two main tomography -# endstations, micro-resolution (MR) and high-resolution (HR). The other -# endstations present in the config (MH, MED, laminography LATOMO, RADIO, PCOTOMO, -# the SmarAct multi-tower stack, the fluorescence MCAs) are noted in the -# extraction facts but not modelled here (ENDSTATION-1). -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/id19/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "parallel-beam hard X-ray microtomography, radiography, and phase-contrast imaging on the long imaging beamline" - name: ID19 - facility: esrf # ESRF Site (facility_code: esrf) - tier: Unit - parent: null - source: insertion-device - source_confirm: "ESRF_Undulator set on the ID19 straight (Tango //acs.esrf.fr:10000/ID/MASTER/ID19): undulators u13a/u32a/u17-6c/u32c and the w150b wiggler (gap + taper); which feeds which mode is SRC-1" - page_layout: stages - shape: "The fleet's first imaging beamline on a non-EPICS floor: microtomography on the ESRF BLISS / Tango control system, reusing the established tomography spine." - source_ref: - label: "gitlab.esrf.fr id19/beamline_configuration" - url: "https://gitlab.esrf.fr/id19/beamline_configuration" - -# Two enclosures: the optics hutch carrying the shared source-conditioning optics, -# and the experiment hutch carrying both tomography endstations. ESRF PSS permit -# signals sit behind the frontend / bsh shutters and are not in the config (PSS-1). -enclosures: - - name: id19-optics - role: optics-hutch - facility_code: esrf - permit_signal: {confirm: "ESRF PSS permit signal behind the frontend shutter; not in the config (PSS-1)"} - - name: id19-experiment - role: experiment-hutch - facility_code: esrf - permit_signal: {confirm: "ESRF PSS permit signal behind bsh1/bsh2; not in the config (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the insertion-device source and the conditioning optics -# =========================================================================== - -source: - stage: source - enclosure: id19-optics - intro: "The ID19 straight-section insertion devices: a set of undulators plus a wiggler, selected per operation mode. The wiggler drives white-beam large-field tomography; the undulators drive higher-flux modes." - note: "ESRF_Undulator over Tango //acs.esrf.fr:10000/ID/MASTER/ID19; which device feeds which endstation / mode is SRC-1." - devices: - - name: InsertionDevices - family: InsertionDevice - pv: {u13a: "U13a_GAP_", u32a: "U32a_GAP_", w150b_gap: "W150B_GAP_", w150b_taper: "W150B_TAPER_", u17_6c: "U17-6c_GAP_", u32c: "U32c_GAP_"} - new: true - confirm: true - note: "the ID19 straight-section source set (ESRF_Undulator); undulators u13a/u32a/u17-6c/u32c and the w150b wiggler with taper; energy reach and per-mode selection are SRC-1" - -optics: - stage: source - enclosure: id19-optics - intro: "The conditioning optics that filter, monochromate, and define the beam: the white-beam attenuators and transfocator, the triple monochromator, and the primary and secondary slits. ID19 also runs white beam (mono bypassed) for high-flux tomography." - note: "Handles read from the config (mono/, slits/, attenuators/, transfocators/). Crystal-pair / Laue / multilayer mode mapping and lens recipes are OPT-1." - devices: - - name: Monochromator - family: Monochromator - pv: {x2: "vmx2", y1: "vmy1", y2: "vmy2", z1: "vmz1", z2: "vmz2", thy1: "thy1", thy2: "thy2"} - new: true - confirm: true - note: "TripleMono (Id19Mono): triple monochromator, three crystal pairs, Bragg 17-99 keV plus Laue and multilayer modes; bypassed in white-beam tomography (OPT-1)" - - name: PrimarySlits - family: Slit - pv: {up: "psu", down: "psd", front: "psf", back: "psb", vgap: "psvg", voff: "psvo", hgap: "pshg", hoff: "psho"} - new: true - confirm: true - note: "primary white-beam slits (iceid193)" - - name: SecondarySlits - family: Slit - pv: {up: "ssu", down: "ssd", front: "ssf", back: "ssb"} - new: true - confirm: true - note: "secondary slits (iceid192)" - - name: Transfocator - family: Transfocator - pv: "id19wbtfctrl" - new: true - confirm: true - note: "white-beam transfocator (ID19Transfocator): 8 Be compound-refractive lenses + pinhole; lens recipe per energy is OPT-1" - - name: Attenuators - family: Filter # Attenuator folds into Filter (i03 precedent), not a new Family - pv: {bank1: "wba1", bank2: "wba2"} - new: true - confirm: true - note: "white-beam attenuator banks (WhiteBeamAttenuator), Cu/Al foil MultiplePositions (att11..att25); the existing Filter Family covers it, not a new Attenuator kind (OPT-1)" - -safety-shutters: - stage: source - enclosure: id19-optics - intro: "The front-end and beam shutters gating the beam into the experiment hutch." - note: "TangoShutter handles read from the config; the PSS permit signals behind them are not in the config (PSS-1)." - devices: - - name: FrontEndShutter - family: Shutter - pv: "//acs.esrf.fr:10000/fe/master/id19" - new: true - confirm: true - note: "front-end shutter (frontend)" - - name: BeamShutter1 - family: Shutter - pv: "id19/bsh/1" - new: true - confirm: true - note: "main beam shutter (bsh1, TangoShutter)" - - name: BeamShutter2 - family: Shutter - pv: "id19/bsh/2" - new: true - confirm: true - note: "second beam shutter (bsh2, TangoShutter)" - -# =========================================================================== -# MR ENDSTATION: micro-resolution tomography (BLISS session MRTOMO) -# =========================================================================== - -mr-endstation: - stage: sample - enclosure: id19-experiment - intro: "The micro-resolution tomography endstation: the tomographic rotation stage and the sample positioning / centring stages. Drives large-field, high-throughput microtomography." - note: "Handles read from motors/elmo.yml (mrsrot) and the iceid191/192 IcePAP racks. The XYOnRotation pseudo-axis (mrxyonsrot) keeps the sample centred as it rotates (SAMPLE-1)." - devices: - - name: MR_RotationStage - family: RotaryStage - pv: "mrsrot" - new: true - confirm: true - note: "micro-res tomographic rotation (Elmo, rfc2217://lid192:28319); the master motion, 900 deg/s ceiling, clocks the detector triggering (SAMPLE-1)" - - name: MR_SampleStage - family: LinearStage - pv: {sx: "mrsx", sy: "mrsy", xc: "mrxc", yc: "mryc", yrot: "mryrot", sz: "mrsz"} - new: true - confirm: true - note: "sample centring + centre-of-rotation alignment (iceid191/192) and translation under rotation (Elmo); the XYOnRotation controller is mrxyonsrot (SAMPLE-1)" - -mr-detector: - stage: detection - enclosure: id19-experiment - intro: "The MR area detector and its positioning stages. Indirect detection: scintillator plus visible optics plus a Lima camera; the propagation distance sets phase contrast." - note: "Lima detectors are Tango device servers (id19/limaccd/*). Several cameras are interchangeable per experiment; the operative roster is DET-1." - devices: - - name: MR_Detector - family: Camera - pv: {frelon1: "id19/limaccd/frelon1", frelon2: "id19/limaccd/frelon2", pco4k: "id19/limaccd/pco4k", dimax1: "id19/limaccd/dimax_lid19det1"} - new: true - confirm: true - note: "indirect-detection area detector (Lima); Frelon CCDs, PCO 4k, and PCO Dimax high-speed cameras are interchangeable per experiment (DET-1); Camera presents the Detector Role" - - name: MR_DetectorStage - family: LinearStage - pv: {x: "hdx", y: "hdy", z: "hdz", thz: "hdthz"} - new: true - confirm: true - note: "detector positioning / propagation-distance stages (iceid191); the propagation distance is the phase-contrast control (DET-1)" - -# =========================================================================== -# HR ENDSTATION: high-resolution tomography (BLISS session HRTOMO) -# =========================================================================== - -hr-endstation: - stage: sample - enclosure: id19-experiment - intro: "The high-resolution tomography endstation: a more precise rotation and sample-positioning stack for small-field, high-resolution microtomography. The HRTOMO session aliases its axes srot / sz / sx / sy / yrot." - note: "Handles read from motors/elmo.yml (hrsrot) and the iceid191/192 IcePAP racks; the XYOnRotation controller is hrxyonsrot (SAMPLE-1)." - devices: - - name: HR_RotationStage - family: RotaryStage - pv: "hrsrot" - new: true - confirm: true - note: "high-res tomographic rotation (Elmo_whistle, rfc2217://lid192:28300); the master motion, 900 deg/s ceiling (SAMPLE-1)" - - name: HR_SampleStage - family: LinearStage - pv: {sx: "hrsx", sy: "hrsy", sz: "hrsz", z0: "hrz0", yrot: "hryrot"} - new: true - confirm: true - note: "sample centring + centre-of-rotation alignment (iceid191/192); HRTOMO session aliases srot/sz/sx/sy/yrot; the XYOnRotation controller is hrxyonsrot (SAMPLE-1)" - -hr-detector: - stage: detection - enclosure: id19-experiment - intro: "The HR area detector and its carriage. Indirect detection through a high-magnification microscope optic; the carriage sets the propagation distance." - note: "Lima Tango detectors shared with MR plus the Basler optical cameras; the operative roster per experiment is DET-1." - devices: - - name: HR_Detector - family: Camera - pv: {frelon1: "id19/limaccd/frelon1", pco4k: "id19/limaccd/pco4k", dimax2: "id19/limaccd/dimax_lid19det2", basler1: "id19/limaccds/basler1"} - new: true - confirm: true - note: "indirect-detection area detector (Lima); Frelon, PCO, and Basler cameras interchangeable per experiment (DET-1); Camera presents the Detector Role" - - name: HR_DetectorStage - family: LinearStage - pv: {xc: "hrxc", yc: "hryc", zc: "hrzc"} - new: true - confirm: true - note: "detector carriage / propagation-distance stages (iceid191); the propagation distance is the phase-contrast control (DET-1)" - -# Cross-cutting control. ID19 runs BLISS (Tango-based); this is CORA's first -# non-EPICS deployment. Handles above are read from the public config. -controls: - intro: > - ID19 runs on the ESRF BLISS control system, which is Tango-based, NOT EPICS. - This is CORA's first deployment on a non-EPICS control floor: the seam model - that today reads "EPICS is the floor" generalizes here to "BLISS / Tango is the - floor". In BLISS a motion stage is a controller class with named axes (driven - by Elmo serial controllers and IcePAP racks iceid191-195), and a detector is a - Lima device server addressed by a Tango name (id19/limaccd/). The handles - in this descriptor are read from ID19's public Beacon config and carried confirm - (CTRL-1). The tomographic acquisition (the continuous rotation coupled to the - Lima detector frame capture, then the downstream reconstruction) runs as a BLISS - scan procedure; that orchestration is the seam CORA's edge would conduct over its - ControlPort, driving through or replacing the BLISS scan per routine, while the - reconstruction is ComputePort work, not a beamline device (TECH-1, CTRL-2). - motion_controllers: - - name: ElmoControllers - family: MotionController - protocol: BLISS_Elmo - new: true - confirm: true - note: "Elmo / Elmo_whistle serial motion controllers driving the rotation stages (mrsrot/hrsrot/mhsrot), over rfc2217 serial and Tango serialrp (CTRL-1)" - - name: IcePAPControllers - family: MotionController - protocol: BLISS_IcePAP - new: true - confirm: true - note: "IcePAP racks iceid191-195 driving the sample, detector, slit, and attenuator axes (CTRL-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources an ID19 run needs present before - it can start. All pending confirmation. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/id28/beamline.yaml b/deployments/id28/beamline.yaml deleted file mode 100644 index e48cad9a601..00000000000 --- a/deployments/id28/beamline.yaml +++ /dev/null @@ -1,256 +0,0 @@ -# ID28 beamline descriptor (ESRF), reverse-engineered -# -# ID28 is the ESRF beamline for momentum-resolved inelastic X-ray scattering (IXS): -# a high-resolution backscattering monochromator sets a meV-resolution incident energy, -# and a multi-analyzer crystal spectrometer on a two-theta arm energy-analyzes the -# scattered beam to map phonon and collective-excitation dispersions. It is bound to -# the ESRF Site (deployments/esrf/site.yaml), CORA's second ESRF beamline after ID32. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the ESRF BLISS Beacon device database, gitlab.esrf.fr/id28/beamline_configuration, -# a git mirror of the live config) or inferred, carried new: true + confirm: true pending -# ID28 staff. The BLISS / Tango / IcePAP handles are real and read from the config (the -# ID32 house-style precedent); control handles are BLISS axis/controller names and Tango -# device URLs, carried as opaque edge handles (the MX3 / ID32 heterogeneous-control -# precedent). Descriptor + docs scaffold; scenarios deferred. -# -# WHAT IS NEW: hard X-ray momentum-resolved IXS, and a further SpectrometerArm consumer. -# - IXS deepens the fleet's inelastic-scattering coverage (SIX soft RIXS, IXS 10-ID, ID32 -# soft RIXS): ID28 is hard X-ray, meV-resolution, phonon-dispersion IXS. -# - The multi-analyzer crystal spectrometer is a further SpectrometerArm consumer. The -# family completed its rule-of-three at ID32 and has since GRADUATED into the catalog -# (SIX + ID32 RIXS/XES + ID28); ID28 is a further sighting that reinforced it. -# -# MODELLING: ID28 coins NO new Family. The -# backscattering monochromator binds Monochromator; the HFM / VFM benders bind Mirror; -# the two-theta multi-analyzer spectrometer binds the catalog SpectrometerArm (the array of -# inclined analyzer crystals is a per-Asset setting, not a new family, the IXS-1 question); -# the Basler / PCO detectors bind Camera; the LakeShore / Oxford / nanodac sample -# environments bind TemperatureController; the in-vacuum undulators bind InsertionDevice; -# the incident energy is a PseudoAxis; the beam-defining slits bind Slit; the machine state -# binds the loose StorageRing. -# -# A NOTE ON THE ENERGY MECHANISM: unlike an angular monochromator, ID28's meV incident -# energy is scanned by tuning the temperature of the backscattering silicon crystal (the -# lattice spacing sets the backscattered energy). The ASL F700 controller carries this as -# a paired setpoint / energy axis (monot / deltae); the BeamEnergy PseudoAxis is realized -# over it, not over a Bragg angle. The PI E518 piezo (pimth / pimchi) trims the crystal -# orientation. This is recorded so the model is not read as an ordinary angle-scanned mono. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/id28/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "momentum-resolved hard X-ray inelastic scattering (IXS) on a multi-analyzer crystal spectrometer arm; CORA's second ESRF deployment" - name: ID28 - facility: esrf # ESRF Site (facility_code: esrf) - sector: "ID28" - tier: Unit - parent: null - source: insertion-device - source_confirm: "ID28 is an in-vacuum-undulator beamline; the BLISS config binds two undulators (IVU22a, IVU13-3c, modelled below); the exact period and segment count are SRC-1" - page_layout: stages - shape: "ESRF momentum-resolved hard X-ray inelastic scattering (IXS): a backscattering monochromator scanned by crystal temperature and a multi-analyzer spectrometer arm map phonon dispersions across momentum transfer." - source_ref: - label: "gitlab.esrf.fr id28/beamline_configuration" - url: "https://gitlab.esrf.fr/id28/beamline_configuration" - -# Control plane: BLISS / Beacon over Tango + IcePAP (the ID32 precedent). Handles are -# BLISS axis/controller names and Tango device URLs, carried as opaque edge handles. The -# optics (oh1 / oh2 / oh3) and the eh1 spectrometer endstation are the PV zones. The beam -# shutters (front-end fe, vacuum bsh1 / bsh2 / bsh3) are in the config; the PSS permit -# leaves behind them are not (ENC-1, PSS-1). -enclosures: - - name: id28-optics - role: optics-hutch - facility_code: esrf - permit_signal: {confirm: "the front-end shutter (machine/machine.yml, fe) is in the BLISS config; the PSS permit leaf is not. The oh1 / oh2 / oh3 optics zone, hutch grouping is ENC-1 (PSS-1)"} - - name: id28-eh1 - role: experiment-hutch - facility_code: esrf - permit_signal: {confirm: "the vacuum beam shutters (shutters/safeshut.yml, bsh1 / bsh2 / bsh3 on id28/v-bsh/0..2) are in the BLISS config; the PSS permit leaf is not. The eh1 IXS spectrometer endstation, ENC-1 (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the machine state, the in-vacuum undulators, the high-resolution mono -# =========================================================================== - -machine: - stage: source - enclosure: id28-optics - intro: "The machine-level source state and the front end, observed not driven." - note: "The ESRF-EBS storage-ring state, the loose StorageRing pattern reused across the fleet; the BLISS MachInfo and the front-end shutter are read from machine/machine.yml (MACHINE-1)." - devices: - - name: StorageRing - family: StorageRing # loose Family (machine-level observe-only source state; MACHINE-1) - pv: "BLISS machinfo (MachInfo, tango://acs:10000/fe/master/id28); the ESRF-EBS storage-ring state (current, fill, refill countdown), observe-only" - new: true - confirm: true - note: "ESRF-EBS storage-ring state via the BLISS MachInfo on the front-end master; observe-only (MACHINE-1)" - - name: FrontEndShutter - family: Shutter - pv: "BLISS fe (TangoShutter, FrontEnd, acs.esrf.fr:10000/fe/master/id28)" - new: true - confirm: true - note: "the ID28 front-end shutter; the upstream gate between the machine and the optics zone (PSS-1)" - -insertion-devices: - stage: source - enclosure: id28-optics - intro: "The in-vacuum undulators, the hard X-ray source." - note: "The two in-vacuum undulators bind the catalog InsertionDevice; the gap is the settable axis (machine/undulators.yml). The names imply 22 mm and 13 mm periods; the exact period and segment count are SRC-1." - devices: - - name: Undulator - family: InsertionDevice - pv: "BLISS ESRF_Undulator (//acs:10000/id/master/id28); two in-vacuum segments IVU22a (gap u22gap, 11.1-300 mm) and IVU13-3c (gap u133gap, 11.1-300 mm)" - new: true - confirm: true - note: "the two in-vacuum undulators (IVU22a + IVU13-3c) on the ESRF_Undulator device server; gap per segment (u22gap / u133gap), tracked with the incident energy; the period implied by the names (22 mm / 13 mm) and the segment detail are SRC-1" - -optics: - stage: source - enclosure: id28-optics - intro: "The high-resolution backscattering monochromator, the incident-energy axis, the focusing mirrors, the beam-position monitor, and the beam-defining slits." - note: > - The main backscattering monochromator binds Monochromator (a Si crystal on the PI E518 - piezo, pimth / pimchi); the meV incident energy is set by tuning the crystal temperature - (the ASL F700 monot / deltae axis), carried as the BeamEnergy PseudoAxis. The config also - shows a premono (OH1) and a postmono (OH2) ahead of the main mono (OH3); they fold into - the same monochromation chain (MONO-1). The HFM / VFM benders bind Mirror; the oh2 - Elettra monitor binds the graduated PositionMonitor Family; the primary and mono slits bind Slit. - devices: - - name: Monochromator - family: Monochromator - pv: "BLISS PI_E518 (oh3/main_mono_pi_e518.yml; pimth / pimchi piezo on tcp e518id28, with pimth_enc / pimchi_enc encoders); a premono (OH1) and postmono (OH2) precede it in the chain" - new: true - confirm: true - note: "the high-resolution backscattering monochromator (a Si crystal on a PI E518 piezo, pimth / pimchi); the backscattering reflection sets the meV resolution, a per-Asset setting; energy is scanned by crystal temperature, not Bragg angle (MONO-1)" - - name: BeamEnergy - family: PseudoAxis - pv: "BLISS F700 (oh3/asl_f700.yml; ASL F700 on gpibid28c pad 3, setpoint monot 7-23 C, energy deltae +/-800 keV, T0 22.854, LAMBDA 0.5226)" - new: true - confirm: true - note: "incident-energy pseudo-axis realized by the ASL F700 backscattering-crystal temperature controller (monot setpoint -> deltae energy shift), not an angular mono; the meV energy-transfer scan is the IXS measurement (MONO-1)" - - name: HorizontalFocusingMirror - family: Mirror - pv: "BLISS hfm_ctrl (oh3/hfm.yml, HFM controller; benders hfmb1 / hfmb2, height hfmz1 / hfmz2, rotation hfmth, tiltz hfmtz -> transz hfmz / transy hfmy / tiltx hfmtx / bending hfmb)" - new: true - confirm: true - note: "the horizontal focusing mirror (HFM, two-bender on the dedicated HFM calc controller) (OPT-1)" - - name: VerticalFocusingMirror - family: Mirror - pv: "BLISS vfm_ctrl (oh3/vfm.yml, VFM controller; benders vfmb1 / vfmb2, height vfmz1 / vfmz2 -> transz vfmz / bending vfmb)" - new: true - confirm: true - note: "the vertical focusing mirror (VFM, two-bender on the dedicated VFM calc controller) (OPT-1)" - - name: BeamPositionMonitor - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1) - pv: "BLISS elettra_bpm_oh2 (oh2/elettra_bpm_oh2.yml; Elettra on tango://id28/elettra/oh2; quadrant currents ebpmc1..4, total ebpmct, position ebpmx / ebpmy)" - new: true - confirm: true - note: "the oh2 Elettra beam-position monitor; binds the graduated PositionMonitor Family (DIAG-1)" - - name: PrimarySlit - family: Slit - pv: "BLISS slits_ph / slits_pv (slits/slit_phg.yml, slits/slit_pvg.yml; horizontal phg / pho on pr / pl, vertical pvg / pvo on pu / pd)" - new: true - confirm: true - note: "the primary beam-defining slits ahead of the mono (horizontal + vertical gap / offset) (OPT-2)" - - name: MonoSlit - family: Slit - pv: "BLISS slits_mx (slits/slit_mxgap.yml; main-mono slit hgap mxgap / hoffset mxoff on mxr / mxl)" - new: true - confirm: true - note: "the main-mono beam-defining slit (OPT-2)" - -# =========================================================================== -# EH1 SAMPLE STAGE: the scattering-geometry goniometer + the sample environment -# =========================================================================== - -eh1-sample: - stage: sample - enclosure: id28-eh1 - intro: "The IXS sample stage: the scattering-geometry positioner, the sample-defining slits, and the sample temperature environments." - note: > - The sample is placed in the meV-resolution beam and oriented in the scattering geometry. - The positioning stage binds LinearStage; the sample slits bind Slit; the three - sample-temperature environments (the 10 K displex LakeShore 340, the Oxford 700 - cryostream, the nanodac gas blower) bind TemperatureController. - devices: - - name: SampleStage - family: LinearStage - pv: "BLISS scattering geometry (sessions/bliss_fourc.yml; sax / say / saz translations, th / sphi / chi rotations, ty gonio-table translation) plus the eh1_ss IcePAP iceid285 (phi / omega / sz) and the SmarAct MCS2 smaract1 (Gx / Gy)" - new: true - confirm: true - note: "the IXS sample-positioning stage: the scattering-geometry translations and rotations on the main goniometer, with a side-station IcePAP and a SmarAct fine stage; the precise axis-to-Asset map is SAMPLE-1" - - name: SampleSlit - family: Slit - pv: "BLISS slits_sh / slits_sv (slits/slit_shg.yml, slits/slit_svg.yml; horizontal shg / sho, vertical svg / svo), with the i1sh / i1sv sample-slit axes in the fourc session" - new: true - confirm: true - note: "the sample-defining slits before and after the sample (OPT-2)" - - name: SampleTemperatureController - family: TemperatureController - pv: "BLISS lakeshore340_10kdiplex (regulation/lakeshore340_10k_displex.yml; LakeShore 340 on id28/regulation/lakeshore340_*, inputs A-D, loop ls340_loop1)" - new: true - confirm: true - note: "the 10 K displex cryostat LakeShore 340 sample-temperature controller; an Oxford 700 cryostream (regulation/oxford700.yml, id28/regulation/oxford_700_*) and a nanodac gas blower (regulation/nanodac_gasblower.yml) are the alternative sample environments (TEMP-1)" - -# =========================================================================== -# EH1 DETECTION: the multi-analyzer IXS spectrometer arm + the counting detectors -# =========================================================================== - -eh1-detection: - stage: detection - enclosure: id28-eh1 - intro: "The IXS spectrometer endstation: a two-theta arm carrying an array of inclined analyzer crystals, and the counting detectors." - note: > - The multi-analyzer spectrometer binds the catalog SpectrometerArm Family (graduated - across SIX + ID32 RIXS/XES + ID28; ID28 is a further consumer that reinforced it). - The array of inclined analyzer crystals (a1..a9, each with chi / th and its own cylinder - slit) is a per-Asset setting on the one arm, not a new family (IXS-1). The Basler / PCO - detectors bind Camera; the per-analyzer counting is on the P201 cards. - devices: - - name: SpectrometerArm - family: SpectrometerArm # catalog Family (graduated; further consumer after SIX + ID32) - pv: "BLISS tth_multilayer (eh1/tth_multilayer.yml; TwoThetaMultilayer two-theta arm tth over real tthm rail) carrying the inca InclinedAnalyser crystals a2_inca / a3_inca / a4_inca (eh1/inca.yml; achi / ath per crystal), with analyzer cylinder slits a1h..a9h / a1v..a9v (slits/cylslits.yml, CylSlit radius 43.5)" - new: true - confirm: true - note: "the IXS multi-analyzer spectrometer: a two-theta arm (TwoThetaMultilayer, tth on the tthm rail) carrying an array of inclined analyzer crystals (a1..a9, each with chi / th and a cylinder slit), energy-analyzing the scattered beam in backscattering. Binds the graduated catalog SpectrometerArm Family, a further consumer after SIX + ID32; the nine-crystal array is a per-Asset setting, not a child-Asset family (IXS-1)" - - name: Detector - family: Camera - pv: "BLISS lima basler_ixs / pco (lima/basler.yml id28/limaccds/basler_0, lima/pco.yml id28/limaccds/pco); per-analyzer counters deta1..deta9 and the izero / ione beam monitors on the P201 CT2 cards (eh1/counters/p201-lid282.yml)" - new: true - confirm: true - note: "the counting / imaging detectors: the Basler IXS camera and the PCO, plus the per-analyzer photon counters deta1..deta9 and the izero / ione incident-beam monitors on the P201 cards (DET-1)" - -# Cross-cutting control. ID28 runs BLISS / Beacon over Tango + IcePAP (the floor); CORA -# observes and, where it replaces BLISS-style orchestration, conducts over it. The handles -# above were read from the public BLISS config and carried confirm (CTRL-1). -controls: - intro: > - ID28 runs on the ESRF BLISS / Beacon control stack over Tango and IcePAP, the same - house-style as ID32. The device handles above are bound from the public BLISS Beacon - device database (gitlab.esrf.fr/id28/beamline_configuration), carried confirm pending - staff verification (CTRL-1); they are BLISS axis / controller names (PI_E518, F700, - hfm_ctrl, tth_multilayer, a2_inca) and Tango device URLs, modelled as opaque edge - handles over the ControlPort. The IXS acquisition (the meV incident-energy scan, set by - the F700 crystal temperature against the fixed-angle multi-analyzer arm, the two-theta - moves that set the momentum transfer, the per-analyzer counting on the P201 cards via the - MUSST timing chain) runs through BLISS sequences; that orchestration is the seam CORA's - edge replaces, conducting over Tango / IcePAP rather than replacing BLISS. The detector - file-writing to the ESRF data store is plumbing CORA observes, not data it owns (see - model.md). - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources an ID28 run needs. The optics and the - spectrometer beam path run under vacuum, and the displex cryostat draws on cryogen - (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the optics and the spectrometer flight path (SUP-1)" diff --git a/deployments/id32/beamline.yaml b/deployments/id32/beamline.yaml deleted file mode 100644 index 5923b015d49..00000000000 --- a/deployments/id32/beamline.yaml +++ /dev/null @@ -1,274 +0,0 @@ -# ID32 beamline descriptor (ESRF), reverse-engineered -# -# ID32 is the ESRF soft X-ray beamline for resonant inelastic X-ray scattering (RIXS) -# and X-ray magnetic dichroism (XMCD): a ~5 m dispersive RIXS spectrometer arm on one -# endstation, and a 9 Tesla XMCD high-field magnet with an X-ray emission (XES) -# spectrometer arm on the other, both fed by twin APPLE-II undulators through a soft -# X-ray plane-grating monochromator. It is bound to the ESRF Site -# (deployments/esrf/site.yaml), CORA's SEVENTH Site and its FIRST ESRF deployment. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the ESRF BLISS Beacon device database, gitlab.esrf.fr/id32/beamline_configuration, -# a direct git mirror of the live /users/blissadm/local/beamline_configuration) or -# inferred, carried new: true + confirm: true pending ID32 staff. This is the fleet's -# first BLISS / Tango / IcePAP controls house-style (the rest are EPICS, or Tango / -# Sardana at MAX IV); control handles are Tango device URLs, IcePAP host+address, and -# BLISS axis names, carried as opaque edge handles the way the MX3 heterogeneous-control -# precedent does. Descriptor + docs scaffold; scenarios deferred. -# -# WHAT IS NEW: a new Site, and the loose families it brings to a rule-of-three. -# - A wholly NEW Site (the ESRF, 7th) re-tests the Site / Federation kernel and brings -# the BLISS / Beacon controls house-style. -# - SpectrometerArm reached a genuine rule-of-three here: ID32 carries the SAME -# SpectrometerArmsController class instantiated TWICE (the RIXS arm + the XES arm), -# so with the SIX soft-RIXS arm the family was sighted three times. It has since -# GRADUATED into the catalog (SIX + ID32 RIXS/XES + ID28), so both arms below bind -# the catalog SpectrometerArm Family. -# - The 9 T XMCD magnet is the third Magnet consumer (4-ID + i10-1 + ID32): Magnet has -# since GRADUATED into the catalog (MAG-1). The RIXS polarimeter binds the catalog -# PolarizationAnalyzer Family, graduated on the rule-of-three (4-ID + i10 + ID32 + P09; POL-2). -# -# MODELLING: ID32 coins NO new Family. The twin APPLE-II -# undulators bind InsertionDevice and the polarization is a PseudoAxis (the i06 / i10 -# precedent); the PGM binds GratingMonochromator; the RIXS and XES dispersive spectrometer -# arms bind the catalog SpectrometerArm (graduated); the RIXS polarimeter binds the catalog -# PolarizationAnalyzer (graduated, POL-2); the 9 T XMCD magnet binds the catalog Magnet (graduated); the LakeShore VTI and -# coil-diagnostic controllers bind TemperatureController; the Andor CCDs bind Camera; the -# 4-circle diffractometer binds Goniometer with a reciprocal-space PseudoAxis; the XMCD -# sample stage binds LinearStage; the machine state binds the loose StorageRing. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/id32/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "soft X-ray resonant inelastic scattering (RIXS) and X-ray magnetic dichroism (XMCD) on a ~5 m spectrometer arm + 9 T magnet; CORA's first ESRF deployment and first BLISS control plane" - name: ID32 - facility: esrf # ESRF Site (facility_code: esrf) - sector: "ID32" - tier: Unit - parent: null - source: insertion-device - source_confirm: "ID32 is a soft X-ray APPLE-II beamline; the BLISS config binds the undulators (modelled below) but not their period; the undulator detail is SRC-1" - page_layout: stages - shape: "ESRF soft X-ray RIXS on a ~5 m dispersive spectrometer arm plus a 9 T XMCD / XES endstation; CORA's first BLISS / Beacon / Tango / IcePAP control plane, bringing three loose families to a rule-of-three." - source_ref: - label: "gitlab.esrf.fr id32/beamline_configuration" - url: "https://gitlab.esrf.fr/id32/beamline_configuration" - -# Control plane: BLISS / Beacon (a YAML device DB) over Tango + IcePAP, NOT EPICS. Handles -# are Tango device URLs (id32/limaccds/andor_1), IcePAP host+address (iceid324), or BLISS -# axis names; carried as opaque edge handles (the MX3 non-EPICS precedent). The two -# endstations (RIXS, XMCD) share the upstream APPLE-II + PGM source. Hutch grouping and the -# PSS permit leaves are open (ENC-1, PSS-1). -enclosures: - - name: id32-optics - role: optics-hutch - facility_code: esrf - permit_signal: {confirm: "PSS permit leaf not in the BLISS config; the shared soft X-ray optics zone, hutch grouping is ENC-1 (PSS-1)"} - - name: id32-rixs - role: experiment-hutch - facility_code: esrf - permit_signal: {confirm: "PSS permit leaf unknown; the RIXS spectrometer endstation, ENC-1 (PSS-1)"} - - name: id32-xmcd - role: experiment-hutch - facility_code: esrf - permit_signal: {confirm: "PSS permit leaf unknown; the XMCD high-field-magnet endstation, ENC-1 (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the machine state, the APPLE-II undulators, the PGM, the optics -# =========================================================================== - -machine: - stage: source - enclosure: id32-optics - intro: "The machine-level source state, observed not driven." - note: "The ESRF-EBS storage-ring state, the loose StorageRing pattern reused across the fleet (MACHINE-1)." - devices: - - name: StorageRing - family: StorageRing # loose Family (machine-level observe-only source state; MACHINE-1) - pv: {confirm: "ESRF-EBS storage-ring state (current, fill); observe-only, the exact handles are MACHINE-1"} - new: true - confirm: true - note: "ESRF-EBS storage-ring state; observe-only (MACHINE-1)" - -insertion-devices: - stage: source - enclosure: id32-optics - intro: "The APPLE-II undulators, the variable-polarization soft X-ray source." - note: "The APPLE-II undulators bind the catalog InsertionDevice (the i06 / i10 precedent); gap and phase are settings, and the polarization is a PseudoAxis over the phase (POL-1)." - devices: - - name: Undulator - family: InsertionDevice - pv: "tango://acs:10000/id/master/id32 (ESRF_Undulator); upstream HU70a (gap hu70ag, phase hu70ap), downstream HU70c (gap hu70cg, phase hu70cp)" - new: true - confirm: true - note: "the two APPLE-II undulators (HU70a + HU70c) on the ESRF_Undulator device server; gap / phase per segment (hu70ag / hu70ap, hu70cg / hu70cp), tracked with the PGM energy; period is SRC-1" - - name: Polarization - family: PseudoAxis - pv: "BLISS PolarizationPolicy: polarization_horizontal / polarization_vertical / polarization_linear (over the APPLE-II phase rows)" - new: true - confirm: true - note: "the polarization pseudo-axis over the APPLE-II (the i06 / i10 precedent): the BLISS PolarizationPolicy presets (horizontal / vertical / linear); rule-less, the controller owns the phase conversion (POL-1)" - - name: BeamEnergy - family: PseudoAxis - pv: "BLISS energy (GratingEnergyTrackerCalcMotor over energy_pgm + the hu70a/hu70c undulator gaps/phases)" - new: true - confirm: true - note: "incident-energy pseudo-axis (the BLISS energy calc motor tracking the PGM and both undulators); range and partition rule are MONO-1" - -optics: - stage: source - enclosure: id32-optics - intro: "The soft X-ray plane-grating monochromator, the focusing mirrors, and the beam-defining slits." - note: "The PGM binds GratingMonochromator (the SIX / CSX / i06 precedent); the focusing mirrors bind Mirror (but are absent from the public BLISS config, OPT-1); the slits bind Slit. The PGM and slit handles are read from BLISS; the mirrors are deferred (MONO-1 / OPT-1 / OPT-2)." - devices: - - name: Monochromator - family: GratingMonochromator - pv: "BLISS pgm (MonochromatorGrating); gratings XMCD_300 / XMCD_900 / RIXS_800 / RIXS_1600; energy axis energy_pgm" - new: true - confirm: true - note: "soft X-ray plane-grating monochromator (BLISS pgm); the interchangeable gratings (XMCD_300 / XMCD_900 / RIXS_800 / RIXS_1600) and the cff are per-Asset settings (MONO-1)" - - name: FocusingMirror - family: Mirror - pv: {confirm: "the soft X-ray focusing / harmonic-rejection mirrors are not exposed as named optics in the public BLISS config (only a sample-side smirotx axis appears); coatings and handles are OPT-1"} - new: true - confirm: true - note: "the soft X-ray focusing mirrors; genuinely absent from the public BLISS config, deferred not invented (OPT-1)" - - name: BeamSlit - family: Slit - pv: "BLISS slits (primary ps / secondary ss / mono ms, each horizontal+vertical with hgap / hoffset; blades on IcePAP iceid321)" - new: true - confirm: true - note: "the primary / secondary / mono beam-defining slits (BLISS slits, hgap / hoffset per slit); blade-axis map is OPT-2" - -# =========================================================================== -# RIXS ENDSTATION (id32-rixs): the dispersive spectrometer arm + diffractometer -# =========================================================================== - -rixs: - stage: detection - enclosure: id32-rixs - intro: "The RIXS endstation: a ~5 m dispersive soft X-ray spectrometer arm, a 4-circle sample diffractometer, a scattered-beam polarimeter, and the Andor CCD." - note: > - The dispersive spectrometer arm binds the catalog SpectrometerArm Family (graduated - across SIX + ID32 RIXS/XES + ID28). The sample circles bind Goniometer with a - reciprocal-space PseudoAxis (the diffractometer Assembly, named-not-built, DIFF-1 / - DIFF-2). The scattered-beam polarimeter binds the catalog PolarizationAnalyzer (the - 4-ID / i10 / P09 rule-of-three; POL-2). The CCD binds Camera. - devices: - - name: Diffractometer - family: Goniometer - pv: {confirm: "the 4-circle sample diffractometer (BLISS DiffE4CH, E4CH geometry with hkl); the circle roles and exact axes are DIFF-1"} - new: true - confirm: true - note: "the 4-circle sample diffractometer (E4CH); the circle roles and the Assembly(Diffractometer) binding are DIFF-1" - - name: ReciprocalSpace - family: PseudoAxis - pv: {confirm: "reciprocal-space (hkl) virtual axis over the diffractometer; the partition rule is deferred (DIFF-2)"} - new: true - confirm: true - note: "reciprocal-space pseudo-axis over the diffractometer (DIFF-2)" - - name: RixsSpectrometerArm - family: SpectrometerArm # catalog Family (graduated across SIX + ID32 RIXS/XES + ID28) - pv: "BLISS rixs_spectro (SpectrometerArmsController); IcePAP iceid324: grtx/grty/grtz, gr1roty/gr2roty, detx/detz, army, grmask" - new: true - confirm: true - note: "the ~5 m dispersive RIXS spectrometer arm (rixs_spectro): real axes detx/detz/grtx -> virtual arm radii r1/r2; grating modes RIXS_2500 (radius 122000, gr2roty) and RIXS_1400 (gr1roty). Binds the graduated catalog SpectrometerArm Family; the RIXS arm plus the XES arm below plus SIX + ID28 earned it" - - name: Polarimeter - family: PolarizationAnalyzer - pv: "IcePAP iceid324: thpol/chipol/zpol/ypol/tthpol" - new: true - confirm: true - note: "the scattered-beam polarimeter / polarization-analysis block on the RIXS arm; binds the catalog PolarizationAnalyzer Family, the third consumer after 4-ID + i10 (POL-2)" - - name: RixsDetector - family: Camera - pv: "tango://id32/limaccds/andor_1 (Lima)" - new: true - confirm: true - note: "the Andor deep-depletion CCD at the end of the RIXS arm; reuses Camera (DET-1)" - -# =========================================================================== -# XMCD ENDSTATION (id32-xmcd): the 9 T magnet, the VTI, the XES arm -# =========================================================================== - -xmcd: - stage: sample - enclosure: id32-xmcd - intro: "The XMCD endstation: a 9 Tesla split-coil high-field magnet with a variable-temperature insert (VTI), an X-ray emission (XES) spectrometer arm, and the Andor CCD." - note: > - The 9 T XMCD magnet binds the catalog Magnet Family (graduated; the third consumer - after 4-ID + i10-1, MAG-1). The VTI sample-temperature and the coil / shield diagnostics bind - TemperatureController (the LakeShore precedent). The XES arm binds the catalog - SpectrometerArm Family (the second arm that completed the rule-of-three; graduated). The - CCD binds Camera; the sample stage binds LinearStage. - devices: - - name: Magnet - family: Magnet # catalog Family (graduated; presents Regulator, MAG-1) - pv: "tango://id32/cryogenic_magnet_ps/xmcd1 (CryogenicPSController); serial tango://id32/Serialrp_232/lid323_ttyR33" - new: true - confirm: true - note: "the 9 T / 4 T split-coil superconducting XMCD magnet: 9.02 T coil + 4.05 T coil, one field setpoint axis (the field reads as a settable axis, presenting the Regulator Role). Binds the catalog Magnet Family (graduated; the third consumer after 4-ID + i10-1, MAG-1)" - - name: SampleTemperatureController - family: TemperatureController - pv: "tango://id32/regulation/ls336_hfm_* (LakeShore 336; GPIB gpibid32b pad 11)" - new: true - confirm: true - note: "the VTI sample-temperature LakeShore 336 (inputs hexapod / helium-pot / sample, two control loops); the He needle valve / VTI flow folds into this cryostat regulation (TEMP-1)" - - name: CryostatDiagnostics - family: TemperatureController - pv: "tango://id32/regulation/ls340_hfm_* (LakeShore 340; GPIB gpibid32b pad 12)" - new: true - confirm: true - note: "the magnet-cryostat diagnostic LakeShore 340 (the superconducting-coil, shield, and helium-reservoir temperatures); a second Regulator instance monitoring the magnet plant (TEMP-1)" - - name: XesSpectrometerArm - family: SpectrometerArm # catalog Family (graduated; the 2nd arm that completed the rule-of-three) - pv: "BLISS xes_spectro (SpectrometerArmsController); IcePAP iceid329: xesdetx/xesdetz, xesgrtx/xesgrty, xesgrot, xesmask" - new: true - confirm: true - note: "the XES (X-ray emission) Rowland-geometry spectrometer arm (xes_spectro): real axes xesdetx/xesdetz/xesgrtx -> virtual radii xesr1/xesr2; grating mode XES_1200 (radius 26055, xesgrot). The SAME SpectrometerArmsController class as the RIXS arm, the second instance that made the rule-of-three; binds the graduated catalog SpectrometerArm Family" - - name: XesDetector - family: Camera - pv: "tango://id32/limaccds/andor_2 (Lima)" - new: true - confirm: true - note: "the Andor CCD at the XES / XMCD endstation; reuses Camera (DET-1)" - - name: SampleStage - family: LinearStage - pv: {confirm: "the XMCD sample-positioning stage inside the magnet VTI; the axis set and handles are SAMPLE-1"} - new: true - confirm: true - note: "the XMCD sample-positioning stage in the magnet bore (SAMPLE-1)" - -# Cross-cutting control. ID32 runs BLISS / Beacon over Tango + IcePAP (the floor); CORA -# observes and, where it replaces BLISS-style orchestration, conducts over it. The handles -# above were read from the public BLISS config and carried confirm (CTRL-1). -controls: - intro: > - ID32 runs on the ESRF BLISS / Beacon control stack over Tango and IcePAP, the fleet's - first non-EPICS, non-Sardana controls house-style. The device handles above are bound - from the public BLISS Beacon device database - (gitlab.esrf.fr/id32/beamline_configuration), carried confirm pending staff - verification (CTRL-1); they are Tango device URLs, IcePAP host+address, and BLISS axis - names, modelled as opaque edge handles over the ControlPort the way the MX3 - heterogeneous-control precedent does. The RIXS / XES / XMCD acquisition (the energy + - polarization moves, the spectrometer-arm Rowland trajectories, the field sweeps, the - diffractometer scans) runs through BLISS sequences; that orchestration is the seam - CORA's edge replaces, conducting over Tango / IcePAP rather than replacing BLISS. The - Lima detector file-writing to the ESRF data store is plumbing CORA observes, not data - it owns (see model.md). - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources an ID32 run needs. The soft X-ray beam - path runs under ultra-high vacuum and the 9 T magnet draws on liquid helium (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the soft X-ray optics and the UHV endstations (SUP-1)" - - kind: LiquidHelium - note: "the 9 T XMCD superconducting magnet coils and VTI cryostat (MAG-1, SUP-1)" diff --git a/deployments/ios/beamline.yaml b/deployments/ios/beamline.yaml deleted file mode 100644 index b4a334abca4..00000000000 --- a/deployments/ios/beamline.yaml +++ /dev/null @@ -1,315 +0,0 @@ -# IOS beamline descriptor (NSLS-II), reverse-engineered -# -# IOS (In situ and Operando Soft X-ray Spectroscopy) is the NSLS-II ambient-pressure -# soft X-ray spectroscopy beamline on the outboard 23-ID-2 branch of the canted -# 23-ID straight, the twin of CSX (23-ID-1), which shares the same two -# elliptically-polarizing undulators. It is bound to the NSLS-II Site -# (deployments/nsls2/site.yaml), and is CORA's soft X-ray ambient-pressure -# photoemission + absorption deployment alongside CSX (coherent scattering), ESM -# (ARPES), SIX (RIXS), SST (RSoXS / HAXPES), and SMI. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the bluesky profile collection NSLS2/ios-profile-collection, the -# startup/*.py device classes) or inferred, carried `new: true` + `confirm: true` -# pending IOS staff. EPICS PVs are real and read from the profile collection; -# vendor part numbers, serials, and physical positions are not in it and are open -# questions. Same descriptor mode as CSX / ESM / SST; this scaffold is descriptor + -# docs, scenarios deferred. -# -# WHAT IS NEW: be honest, IOS is reinforcement-heavy. Its SPECS hemispherical -# analyzer binds the catalog ElectronAnalyzer Family (the THIRD sighting after ESM -# and SST, and the first non-Scienta and first ambient-pressure one; analyzer make -# and pass-energy range are a per-Asset settings difference, not a Family split). -# Its VLS-PGM reuses GratingMonochromator (a further consumer after SIX / CSX / ESM -# / SST), its Vortex and Xspress3 silicon-drift detectors reuse -# EnergyDispersiveSpectrometer, its AP-PES sample stage reuses Manipulator, and the -# two canted EPUs are the same CSX twin-EPU straight (TOPO-1). IOS coins NO new -# Family and nothing graduates. Its one genuinely distinct contribution, in-situ / -# operando AMBIENT-PRESSURE spectroscopy, is carried as a deferral, not modelled: -# the profile collection exposes no gas-dosing, pressure, or sample-heating PVs, so -# the ambient-pressure reaction cell is the headline open question (INSITU-1), not -# an invented device. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/ios/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "in situ / operando soft X-ray spectroscopy (ambient-pressure XPS / AP-PES, NEXAFS / XAS), 23-ID-2; the twin of CSX on the canted 23-ID straight; modelled from public beamline config" - name: IOS - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "Sector 23" # PV namespace XF:23ID* - tier: Unit - parent: null - source: insertion-device - source_confirm: "two elliptically-polarizing undulators (EPU:1, EPU:2) on the canted SR:C23-ID straight, the same straight CSX (23-ID-1) reads; modelled as one root Unit feeding the 23-ID-2 (IOS) branch (the 32-ID canted precedent, as CSX), not two roots (TOPO-1); EPU type / period / polarization / edge table are SRC-1" - page_layout: stages - shape: "An ambient-pressure photoemission beamline: soft X-ray spectroscopy under a working gas atmosphere; the in-situ reaction environment is the headline open question, not yet in source." - source_ref: - label: "NSLS2/ios-profile-collection" - url: "https://github.com/NSLS2/ios-profile-collection" -# PV zones: XF:23IDA (front-end optics, shared sector-A optics), XF:23ID2-OP (the -# 23-ID-2 branch optics, the PGM and the KB system), XF:23ID2-ES (the IOS endstation -# and the SPECS analyzer), XF:23ID2-BI (the branch beam instrumentation: the Au mesh, -# the diagnostics, and the IOXAS / Vortex translation stages). Whether the front-end, -# branch optics, and endstation are separate shielded hutches, and the PSS permit -# leaves, are open (ENC-1, PSS-1). -enclosures: - - name: 23-ID-A - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf not in source; front-end shutter XF:23ID-PPS{Sh:FE} (PSS-1)"} - - name: 23-ID-2 - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; the 23-ID-2 (IOS) branch; whether branch optics and endstation are separate hutches is ENC-1"} - -# =========================================================================== -# SOURCE STAGE: the canted EPUs, the front-end mirrors, the PGM, the KB system -# =========================================================================== - -insertion-devices: - stage: source - enclosure: 23-ID-A - intro: "The two elliptically-polarizing undulators on the canted SR:C23-ID straight, shared with CSX." - note: "Two InsertionDevice Assets (the canted twin-EPU straight, the same EPUs CSX reads on the 23-ID-1 branch); each adds a polarization (phase) axis beyond gap, carried as a setting, and EPU:1 carries the energy-edge lookup-table switching seen in the profile (carried as a setting, SRC-1). Canted-vs-separate-root is TOPO-1 (32-ID precedent: one root)." - devices: - - name: Undulator_1 - family: InsertionDevice - pv: "SR:C23-ID:G1A{EPU:1" - new: true - confirm: true - note: "first EPU (epu1, XF:23ID-ID{EPU:1); gap + polarization phase + edge lookup-table switching for the soft X-ray edge map (SRC-1)" - - name: Undulator_2 - family: InsertionDevice - pv: "SR:C23-ID:G1A{EPU:2" - new: true - confirm: true - note: "second EPU (epu2, XF:23ID-ID{EPU:2); gap + polarization phase (SRC-1)" - -optics: - stage: source - enclosure: 23-ID-A - intro: "The front-end mirrors and the front-end shutter." - note: "m1a is the front-end mirror; m1b1 (with a feedback loop) and m1b2 are the sector-A deflecting mirrors that split the canted source toward the branches. Coatings and axis roles are OPT-1." - devices: - - name: Mirror_1 - family: Mirror - pv: "XF:23IDA-OP:1{Mir:1" - new: true - confirm: true - note: "front-end mirror M1A (OPT-1)" - - name: Mirror_1b1 - family: Mirror - pv: "XF:23IDA-OP:2{Mir:1A" - new: true - confirm: true - note: "sector-A deflecting mirror M1B1, with a beam-position feedback loop (OPT-1)" - - name: Mirror_1b2 - family: Mirror - pv: "XF:23IDA-OP:2{Mir:1B" - new: true - confirm: true - note: "sector-A deflecting mirror M1B2 (OPT-1)" - - name: FrontEndShutter - family: Shutter - pv: "XF:23ID-PPS{Sh:FE}" - new: true - confirm: true - note: "front-end photon shutter, PPS-gated" - -monochromator: - stage: source - enclosure: 23-ID-2 - intro: "The variable-line-spacing plane-grating monochromator that selects the soft X-ray energy, the branch mirror, the Kirkpatrick-Baez focusing pair, the slits, and the branch shutter." - note: > - pgm is the VLS-PGM (200-2200 eV): a premirror (mir_pit / mir_x) plus an - interchangeable grating (grt_pit / grt_x) set the energy, and the profile exposes - the energy fly-scan (start / stop / velocity). It binds the catalog - GratingMonochromator Family (a further consumer after SIX / CSX / ESM / SST; - grating line densities and the energy range are MONO-1). m3b is the branch mirror; - dm1 is a downstream deflecting mirror; the KB pair (kb_mirror_h / kb_mirror_v) - focuses the beam at the endstation; slt1 / slt2 are the branch slits (OPT-1, OPT-2). - devices: - - name: Monochromator - family: GratingMonochromator - pv: { energy: "XF:23ID2-OP{Mono}Enrgy-SP", mirror_pitch: "XF:23ID2-OP{Mono-Ax:MirP}Mtr", mirror_x: "XF:23ID2-OP{Mono-Ax:MirX}Mtr", grating_pitch: "XF:23ID2-OP{Mono-Ax:GrtP}Mtr", grating_x: "XF:23ID2-OP{Mono-Ax:GrtX}Mtr" } - new: true - confirm: true - note: "VLS-PGM, 200-2200 eV; energy fly-scan capable (Enrgy:Start / Stop / FlyVelo); grating line densities are MONO-1" - - name: Mirror_3b - family: Mirror - pv: "XF:23ID2-OP{Mir:3B" - new: true - confirm: true - note: "branch mirror M3B (OPT-1)" - - name: DeflectingMirror - family: Mirror - pv: { x: "XF:23ID2-OP{DM1-Ax:X}Mtr", roll: "XF:23ID2-OP{DM1-Ax:Roll}Mtr" } - new: true - confirm: true - note: "downstream deflecting mirror DM1, x / roll (OPT-1)" - - name: KBMirror_Horizontal - family: Mirror - pv: { pitch: "XF:23ID2-OP{KB:MirH-Ax:Pitch}Mtr", roll: "XF:23ID2-OP{KB:MirH-Ax:Roll}Mtr" } - new: true - confirm: true - note: "Kirkpatrick-Baez horizontal-focusing mirror (OPT-1)" - - name: KBMirror_Vertical - family: Mirror - pv: "XF:23ID2-OP{KB:MirV-Ax:Pitch}Mtr" - new: true - confirm: true - note: "Kirkpatrick-Baez vertical-focusing mirror (OPT-1)" - - name: Slit_1 - family: Slit - pv: "XF:23ID2-OP{Slt:1" - new: true - confirm: true - note: "branch slit 1, gap / center (OPT-2)" - - name: Slit_2 - family: Slit - pv: "XF:23ID2-OP{Slt:2-Ax:Y}Mtr" - new: true - confirm: true - note: "branch slit 2, vertical (OPT-2)" - - name: BranchShutter - family: Shutter - pv: "XF:23ID2-PPS{PSh}" - new: true - confirm: true - note: "branch photon shutter, PPS-gated (PSS-1)" - -# =========================================================================== -# SAMPLE STAGE: the AP-PES manipulator, the XAS sample stage, surface prep -# =========================================================================== - -appes-sample: - stage: sample - enclosure: 23-ID-2 - intro: "The ambient-pressure photoemission (AP-PES) sample side: the multi-axis manipulator, the XAS sample stage, and the surface-prep ion gun." - note: > - The APPES manipulator (x / y / z / rotation) places the sample in the analyzer - focus; it binds the catalog Manipulator Family (a further consumer after SIX / - ESM / SST / I06). The IOXAS stage is the single-axis XAS-endstation translation - (LinearStage). The SPECS power supply drives the surface-prep sputter / ion gun - (a GenericProbe auxiliary). IOS's defining ambient-pressure reaction cell, the gas - dosing / mixing manifold, the pressure control, and the sample heating are NOT in - the profile collection (no gas / pressure / temperature PVs), so they are carried - as the headline open question and not invented here (INSITU-1). A load-lock gate - valve (IOXAS-GV:4) is present but no sample-transfer motor PVs are, so the transfer - mechanism is deferred (SAMPLE-1, SAMPLE-2). - devices: - - name: SampleManipulator - family: Manipulator - pv: { x: "XF:23ID2-ES{APPES:1-Ax:X}Mtr", y: "XF:23ID2-ES{APPES:1-Ax:Y}Mtr", z: "XF:23ID2-ES{APPES:1-Ax:Z}Mtr", rotation: "XF:23ID2-ES{APPES:1-Ax:R}Mtr" } - new: true - confirm: true - note: "AP-PES four-axis sample manipulator (x / y / z / rotation); reuses the Manipulator Family (SAMPLE-1)" - - name: XasSampleStage - family: LinearStage - pv: "XF:23ID2-BI{IOXAS:1-Ax:X}Mtr" - new: true - confirm: true - note: "single-axis XAS-endstation sample translation (SAMPLE-1)" - - name: SputterGun - family: GenericProbe - pv: "XF:23ID2-ES{SPECS-PS1}" - new: true - confirm: true - note: "SPECS power-supply surface-prep sputter / ion gun (mode / degas); auxiliary, not the analyzer (SAMPLE-2)" - -# =========================================================================== -# DETECTION STAGE: the SPECS analyzer, the fluorescence detectors, the yield chain -# =========================================================================== - -detectors: - stage: detection - enclosure: 23-ID-2 - intro: "The SPECS hemispherical electron analyzer (the AP-PES detector), the Vortex and Xspress3 fluorescence detectors, the scaler and current amplifiers reading the electron-yield channels, the Au-mesh I0 monitor, and the exit-slit diagnostic camera." - note: > - The SPECS analyzer is the photoemission detector: it disperses photoelectrons by - kinetic energy over a window set by pass energy and lens mode (a photon-in / - electron-out instrument), and binds the catalog ElectronAnalyzer Family, the THIRD - sighting after ESM and SST and the first non-Scienta and first ambient-pressure one - (analyzer make, lens-mode set, and pass-energy range are a per-Asset settings or - bound-Model difference, not a Family split; DET-1). The Vortex (silicon-drift - detector + MCA) and the Xspress3 (four-channel silicon-drift) read the fluorescence - yield and bind EnergyDispersiveSpectrometer (DET-2). The scaler reads the - electron-yield (TEY / PEY) counting channels behind the CurrAmp:1/2/3 current - amplifiers (sample drain, Au-mesh reference, photodiode), and the Au mesh is the I0 - reference; both bind FluxMonitor (DET-3). The exit-slit camera is a beam-diagnostic - Camera. The detection modes (TEY drain current, PEY kinetic-energy-selected - electrons through the analyzer, PFY region-of-interest fluorescence) are settings, - not separate devices. - devices: - - name: ElectronAnalyzer - family: ElectronAnalyzer - pv: "XF:23ID2-ES{SPECS}" - new: true - confirm: true - note: "SPECS hemispherical electron analyzer (the AP-PES detector); pass energy / lens mode / kinetic energy / acquisition mode are settings; model (Phoibos NAP?) and pass-energy range are DET-1" - - name: FluorescenceDetector - family: EnergyDispersiveSpectrometer - pv: "XF:23ID2-ES{Vortex}" - new: true - confirm: true - note: "Vortex silicon-drift detector + MCA for partial-fluorescence-yield XAS; ROI set is a setting (DET-2)" - - name: FluorescenceArray - family: EnergyDispersiveSpectrometer - pv: "XF:23ID2-ES{Xsp:1}:" - new: true - confirm: true - note: "Xspress3 four-channel silicon-drift fluorescence detector; channel / ROI map is DET-2" - - name: Scaler - family: FluxMonitor - pv: "XF:23ID2-ES{Sclr:1}" - new: true - confirm: true - note: "scaler counting electronics for the electron-yield (TEY / PEY) channels behind the CurrAmp:1/2/3 current amplifiers (DET-3)" - - name: IncidentFluxMonitor - family: FluxMonitor - pv: "XF:23ID2-BI{AuMesh:1" - new: true - confirm: true - note: "gold-mesh I0 reference for incident-flux normalization (DET-3)" - - name: DiagnosticCamera - family: Camera - pv: "XF:23ID2-BI{ExitSlt-Cam:1}" - new: true - confirm: true - note: "exit-slit YAG centroid diagnostic camera" - -# Cross-cutting control. IOS runs EPICS (the floor); CORA observes and, where it -# replaces bluesky-style orchestration, conducts over it. The handles above were -# read from the ios-profile-collection startup files and carried confirm (CTRL-1). -controls: - intro: > - IOS runs on the NSLS-II EPICS / ophyd control stack, the same floor as the other - NSLS-II beamlines. The device handles above are bound from the beamline's bluesky - profile collection (NSLS2/ios-profile-collection), carried confirm pending staff - verification (CTRL-1). The AP-PES / NEXAFS acquisition (the PGM energy fly-scans - with their coupled EPU edge-table switching, the SPECS spectrum acquisition, and - the electron- and fluorescence-yield reads) runs through bluesky plans, published - to Kafka and the NSLS-II document store; whether a queue server is in use is not in - the profile (CTRL-1). That orchestration is the seam CORA's edge replaces, driving - through ophyd / EPICS, while the SPECS / Xspress3 HDF5 file-writing to the NSLS-II - filestore is plumbing CORA observes, not data it owns (see model.md). The gate - valves (XF:23ID2-VA) and the storage-ring current readback (XF:23ID-SR) are vacuum - plumbing and facility observation, not modelled as Assets in this cut. - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources an IOS run needs. The PGM, the KB - system, and the analyzer endstation are under UHV (SUP-1). The ambient-pressure - process gas the operando cell would draw on is part of the deferred ambient-pressure - sample environment, not in the profile collection, and is not invented here - (INSITU-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the optics, the KB system, and the analyzer endstation are UHV (SUP-1)" diff --git a/deployments/isr/beamline.yaml b/deployments/isr/beamline.yaml deleted file mode 100644 index 78d8830b593..00000000000 --- a/deployments/isr/beamline.yaml +++ /dev/null @@ -1,236 +0,0 @@ -# ISR beamline descriptor (NSLS-II), reverse-engineered, deliberately partial -# -# ISR (In Situ and Resonant hard X-ray studies) is the NSLS-II 4-ID beamline for -# resonant elastic / inelastic scattering near absorption edges, surface and -# interface diffraction (crystal truncation rods), and in-situ sample environments. -# It is bound to the NSLS-II Site (deployments/nsls2/site.yaml). -# -# STATUS: reverse-engineered, design-phase, and DELIBERATELY PARTIAL. Every value -# is read from public open source (the beamline's own bluesky profile collection, -# github.com/NSLS2/isr-profile-collection, its startup/*.py device definitions) or -# inferred, carried new: true + confirm: true pending ISR staff. EPICS PVs are real -# and verified against the profile collection; vendor part numbers, crystal cuts, -# and physical positions are not in it and are open questions. -# -# WHY PARTIAL: the public profile collection is an early / commissioning, -# optics-and-detectors-first scaffold. It binds the front-end and optics chain (the -# undulator gap, the DCM, the focusing and harmonic-rejection mirrors, the front-end -# slit, the filter bank), the Eiger 1M area detector, and the diagnostic screen -# cameras, but the devices that make ISR's name (the multi-circle DIFFRACTOMETER for -# resonant / surface scattering, the IN-SITU sample environment, a wired RESONANT -# energy axis, and POLARIZATION analysis) are ABSENT or stubbed in the source. Only -# two end-station axes (th, zeta, under the Dif:ISD diffractometer IOC) are bound, -# the flux-monitor electrometers are commented out, and the energy axis is a -# non-functional stub. CORA models what is PV-bound and routes the four -# mission-critical gaps to open questions rather than inventing them, the same -# discipline as the i20-1 (EDE) partial. -# -# WHAT IS (AND IS NOT) NEW: ISR coins NO new Family and changes nothing in the -# catalog. Its science (hard X-ray resonant scattering, surface / CTR diffraction) -# would reuse the existing pending resonant_scattering Method (APS 4-ID, CSX) and -# diffraction Method (4-ID / 8-ID); both are deferred and doubly so here because the -# diffractometer they run on is not yet in source (DIFF-1, TECH-1). -# -# MODELLING: 4-ID is an in-vacuum-undulator source (read-only gap here), observed -# alongside the loose StorageRing; the DCM binds Monochromator; the bendable -# focusing pair and the harmonic-rejection mirror bind Mirror; the front-end slit -# binds Slit; the filter bank binds Filter; the single bound sample rotation binds -# RotaryStage (NOT a full Goniometer, which is absent); the Eiger 1M and the -# diagnostic screen cameras bind Camera; the motorized beam-position-monitor stage -# binds the graduated PositionMonitor Family (DIAG-1). -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/isr/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: partial - summary: "in-situ and resonant hard X-ray scattering / surface diffraction, 4-ID; a deliberately partial first cut, the multi-circle diffractometer + in-situ environment + resonant energy axis deferred (DIFF-1 / INSITU-1 / RESONANT-1); modelled from public beamline config" - name: ISR - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "4-ID" # PV zones XF:04IDA / B / C / D (A-D), FE:C04A front-end, SR:C04 ring - tier: Unit - parent: null - source: insertion-device - source_confirm: "4-ID is an in-vacuum-undulator (IVU) beamline; the profile collection binds only a read-only gap encoder (SR:C04-ID:G1{IVU:1-LEnc}Gap), no gap-drive setpoint and no energy range. Source identity and parameters are SRC-1" - page_layout: stages - shape: "A hard X-ray in-situ and resonant-scattering mission, modelled as a partial optics-and-detectors-first cut because the multi-circle diffractometer and sample environments are not yet in the public source." - source_ref: - label: "NSLS2/isr-profile-collection" - url: "https://github.com/NSLS2/isr-profile-collection" -# PV zones: FE:C04A (front-end slit), XF:04IDA-OP (zone A optics: DCM, focusing -# mirrors), XF:04IDB-OP (zone B optics: harmonic-rejection mirror), XF:04IDA/B/C-BI -# (diagnostics: screen cameras, BPM, electrometers), XF:04IDD-ES (zone D endstation: -# the Dif:ISD sample axes, the filter bank, the Eiger). Whether the zones are -# separate hutches and the PSS permit leaves are open (ENC-1, PSS-1). Modelled here -# as two enclosures (optics + endstation) pending ENC-1. -enclosures: - - name: isr-optics - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf not in the profile collection (no PSS / photon-shutter / hutch-interlock device is bound); the optics zones (FE:C04A, XF:04IDA-OP, XF:04IDB-OP), the hutch grouping is ENC-1 (PSS-1)"} - - name: isr-endstation - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; the zone-D endstation (XF:04IDD-ES), ENC-1 (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the machine state and the optics -# =========================================================================== - -machine: - stage: source - enclosure: isr-optics - intro: "The machine-level source state, observed not driven." - note: "Observe-only NSLS-II machine state, the loose StorageRing pattern reused from the NSLS-II siblings, plus the in-vacuum undulator gap (read-only in source). SRC-1, MACHINE-1." - devices: - - name: StorageRing - family: StorageRing # loose Family (machine-level observe-only source state; MACHINE-1) - pv: "SR:OPS-BI{DCCT:1}I:Real-I" - new: true - confirm: true - note: "NSLS-II storage-ring current, read as a beam-present input; observe-only; the rest of the ring state is MACHINE-1" - - name: Undulator - family: InsertionDevice - pv: "SR:C04-ID:G1{IVU:1-LEnc}Gap" - new: true - confirm: true - note: "the in-vacuum undulator: only a read-only gap encoder is bound in the profile collection (no gap-drive setpoint, no energy range); the device model and parameters are SRC-1" - -optics: - stage: source - enclosure: isr-optics - intro: "The double-crystal monochromator, the bendable focusing mirrors, the harmonic-rejection mirror, the front-end slit, and the filter bank." - note: > - The DCM binds Monochromator (its Bragg axis is the physical energy selector; a - wired resonant energy pseudo-axis is absent in source, RESONANT-1). The focusing - pair and the harmonic-rejection mirror bind Mirror, the front-end slit binds Slit, - the filter bank binds Filter. Everything here reuses the catalog and coins nothing. - devices: - - name: Monochromator - family: Monochromator - pv: "XF:04IDA-OP:1{Mono:DCM-Ax:th}Mtr" - new: true - confirm: true - note: "the double-crystal monochromator (DCM): Bragg theta sets the energy, with crystal-bend, Z / Y2 and second-crystal pitch / roll (coarse + fine) alignment axes; the crystal cut and energy range are MONO-1; a wired energy / resonant pseudo-axis is absent in source (RESONANT-1)" - - name: FocusingMirror - family: Mirror - pv: "XF:04IDA-OP:1{Mir:HFM-Ax:P}Mtr" - new: true - confirm: true - note: "the bendable focusing mirror pair, a horizontal (HFM) and a vertical (VFM) focusing mirror each on x / pitch / y / yaw / roll plus a bender; one Asset for the pair at this cut; coatings are OPT-1" - - name: HarmonicRejectionMirror - family: Mirror - pv: "XF:04IDB-OP:1{Mir:DHRM-Ax:P}Mtr" - new: true - confirm: true - note: "the harmonic-rejection mirror (DHRM) in zone B, with fine roll / pitch axes; coating and cutoff are OPT-1" - - name: FrontEndSlit - family: Slit - pv: "FE:C04A-OP{Slt:12-Ax:X}center" - new: true - confirm: true - note: "the front-end defining slit, a virtual center / gap pseudo-positioner (no plain blade Mtr leaf; x / y center and gap over the underlying blades); blade-axis map is OPT-2; the secondary-source (SSA) slit is defined but commented out in source (OPT-2)" - - name: AttenuatorBank - family: Filter - pv: "XF:04IDD-ES{Fil:1}Cmd:Opn-Cmd" - new: true - confirm: true - note: "the four-foil pneumatic attenuator bank (Fil:1-4, each a two-button shutter with Cmd:Opn-Cmd / Cmd:Cls-Cmd), bit-encoded to a transmission level; sets the incident flux on the sample (ATTN-1)" - -# =========================================================================== -# SAMPLE STAGE: the bound end-station axes (the full diffractometer is absent) -# =========================================================================== - -sample: - stage: sample - enclosure: isr-endstation - intro: "The bound end-station sample axes. The full multi-circle diffractometer that ISR's resonant / surface science needs is absent from the source." - note: > - This is where ISR's partial source shows most. The profile collection binds only - two axes under the Dif:ISD diffractometer IOC, a sample rotation (th) and a second - axis (zeta), modelled here as a single RotaryStage Asset. The full multi-circle - diffractometer (the sample-orientation circles, the detector two-theta arm, and the - reciprocal-space / hkl engine) that resonant and surface-diffraction work require is - NOT in the source, so it is a named open question, not modelled (DIFF-1). The - in-situ sample environment (electrochemistry, gas, temperature, cryostat) that gives - the beamline its name is likewise absent and not PV-bound (INSITU-1). - devices: - - name: SampleStage - family: RotaryStage - pv: "XF:04IDD-ES:1{Dif:ISD-Ax:th}Mtr" - new: true - confirm: true - note: "the only two bound axes of the Dif:ISD diffractometer, a sample rotation (th, the operative scan axis) and a second axis (zeta, rotary-vs-linear unknown); modelled as one RotaryStage at this cut; the full multi-circle diffractometer + detector arm + reciprocal-space engine is absent from source and is DIFF-1" - -# =========================================================================== -# DETECTION STAGE: the Eiger area detector, the diagnostic screen cameras, and -# the motorized beam-position monitor -# =========================================================================== - -detection: - stage: detection - enclosure: isr-endstation - intro: "The Eiger 1M area detector (the primary scattering detector), the diagnostic screen cameras, and the motorized beam-position monitor." - note: > - The Eiger 1M binds Camera (the only detector scanned in the profile collection's - plans); the diagnostic YAG-screen cameras bind Camera; the motorized - beam-position-monitor stage binds the graduated PositionMonitor Family - (DIAG-1). The QuadEM flux-monitor electrometers are defined but commented out in - source, so no FluxMonitor Asset is modelled (DET-1); there is no point / scaler - detector for diffraction counting (intensity is read from the Eiger). - devices: - - name: AreaDetector - family: Camera - pv: "XF:04IDD-ES{Det:Eig1M}" - new: true - confirm: true - note: "the Dectris Eiger 1M area detector, the primary scattering detector (the only detector in the profile collection's scan plans); it carries the scattering-geometry metadata (detector distance, beam center, photon energy) as detector config, not as a motorized arm; the model size and the write path (a commissioning testing/ path) are DET-1" - - name: DiagnosticCamera - family: Camera - pv: "XF:04IDC-BI:1{Scr:3}" - new: true - confirm: true - note: "the diagnostic YAG fluorescent-screen beam-viewing cameras (three Prosilica in zones A and C); beam alignment / diagnostics, not a science detector (DIAG-1)" - - name: BeamPositionMonitor - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1) - pv: "XF:04IDB-BI:1{BPM:3-Ax:X}Mtr" - new: true - confirm: true - note: "the motorized beam-position-monitor stage (x / y) in zone B; only the stage motors are bound, the QuadEM electrometers that would read the flux / position are commented out in source (DIAG-1)" - -# Cross-cutting control. ISR runs EPICS (the floor); CORA observes and, where it -# replaces bluesky-style orchestration, conducts over it. The handles above were -# read from the profile collection and carried confirm (CTRL-1). -controls: - intro: > - ISR runs on the NSLS-II EPICS / ophyd control stack, the same floor as the rest of - the NSLS-II fleet. The device handles above are bound from the beamline's bluesky - profile collection (github.com/NSLS2/isr-profile-collection), carried confirm - (CTRL-1). The acquisition is software / EPICS-triggered step scans (no Zebra, no - Struck scaler, no hardware fly-trigger in source); the bluesky plans (a th rocking - scan, attenuated scans over zeta) are the seam CORA's edge replaces, driving through - ophyd / EPICS. The data plane uses bluesky-queueserver and Tiled (the databroker - catalog is a placeholder name in source, a commissioning signal); CORA keeps its own - data-of-record (CTRL-1). The profile collection is early-stage: several devices are - commented out (the secondary-source slit, the flux-monitor electrometers) and the - energy axis is a non-functional stub (RESONANT-1, DET-1). - software_iocs_not_modeled: - # The mission devices ISR's name implies are absent or stubbed in the source and - # are carried as open questions, not invented here. - - "the multi-circle DIFFRACTOMETER: the Dif:ISD IOC binds only th + zeta; the sample-orientation circles, the detector two-theta arm, and the reciprocal-space / hkl engine that resonant and surface-diffraction (CTR) work need are absent from source (DIFF-1)" - - "the IN-SITU sample environment: no temperature controller, electrochemistry / potentiostat, gas / flow, or cryostat is PV-bound anywhere, despite In Situ being the beamline's name (INSITU-1)" - - "the RESONANT energy axis and POLARIZATION analysis: the DCM Bragg is the physical energy axis but a wired energy pseudo-axis is only a non-functional stub, and no polarization analyzer or phase retarder is bound (RESONANT-1)" - - "the flux-monitor electrometers (QuadEM EM:1 / EM:2 / EM:3) and the secondary-source slit (SSA): defined in source but commented out, so no FluxMonitor / secondary-slit Asset is modelled (DET-1, OPT-2)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources an ISR run needs. The optics run - under vacuum (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the optics run under vacuum (SUP-1)" diff --git a/deployments/iss/beamline.yaml b/deployments/iss/beamline.yaml deleted file mode 100644 index 846ed3ce8f3..00000000000 --- a/deployments/iss/beamline.yaml +++ /dev/null @@ -1,271 +0,0 @@ -# ISS beamline descriptor (NSLS-II), reverse-engineered -# -# ISS (Inner-Shell Spectroscopy) is the NSLS-II X-ray absorption / emission -# spectroscopy beamline at sector 8-ID. A single hard-X-ray insertion-device source -# feeds a high-heat-load trajectory monochromator (HHM) whose energy axis is swept as -# a fly-scan: the energy sweep IS the EXAFS measurement. Transmission and fluorescence -# detectors read absorption; two crystal emission spectrometers (a Johann and a von -# Hamos) read X-ray emission for XES and high-energy-resolution fluorescence detection -# (HERFD). It is bound to the NSLS-II Site (deployments/nsls2/site.yaml), the -# thirteenth NSLS-II beamline after FXI, HXN, BMM, SRX, SIX, CHX, CSX, XPD, ESM, SMI, -# IXS, SST. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the NSLS2/iss-profile-collection bluesky / ophyd startup files) or inferred, -# carried `confirm: true` pending ISS staff. EPICS PVs are real and verified against -# the startup/*.py device classes; crystal cuts, undulator parameters, vendor part -# numbers, and physical positions are not in source and are open questions. Same -# descriptor mode as the other NSLS-II beamlines: this scaffold is descriptor + docs, -# scenarios deferred. -# -# ISS is the EXAFS-AND-EMISSION deployment: CORA's first dedicated X-ray absorption -# spectroscopy beamline driven by a trajectory energy fly-scan, and the SECOND sighting -# of the crystal emission spectrometer. The HHM / HRM monochromators reuse the catalog -# Monochromator, the mirrors Mirror, the filter box Filter, the ion chambers FluxMonitor, -# the Xspress3 SDD EnergyDispersiveSpectrometer, the Pilatus area detector Camera, the -# sample stages LinearStage / Goniometer / RotaryStage, the thermal stage -# TemperatureController, the slits Slit, the shutters Shutter, the energy pseudo-axis -# PseudoAxis. The Johann and von Hamos crystal emission spectrometers bind the -# EmissionSpectrometer family that LCLS-MFX introduced (its von Hamos XES spectrometer): -# ISS is the SECOND sighting, earning the rule-of-three, so EmissionSpectrometer -# GRADUATED into the catalog (SPEC-1). One loose family remains: PositionMonitor -# (DIAG-1). No Capability or Method is coined: the energy sweep strengthens the deferred -# energy_scan case but a descriptor scaffold does not force it (ENERGY-1 stays deferred, -# the BMM question), and the XAS / XES techniques sit on pending Methods (TECH-1). The -# ion-chamber fill-gas flow and the in-situ sample environment are deferred (ENV-1). - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "inner-shell spectroscopy (EXAFS by trajectory energy fly-scan, plus XES / HERFD on the Johann + von Hamos crystal emission spectrometers), 8-ID; modelled from public beamline config" - name: ISS - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "Sector 8" # PV namespace XF:08ID* - tier: Unit - parent: null - source: insertion-device - source_confirm: "8-ID in-vacuum undulator on the NSLS-II 3 GeV ring (SR:OPS-BI{DCCT:1} reads the ring current). The profile collection drives photon energy through the HHM trajectory and does not expose the undulator gap / period PVs, so the source identity and range are inferred (SRC-1)." - page_layout: stages - shape: "The energy sweep is the measurement: a trajectory energy fly-scan for EXAFS, plus two crystal emission spectrometers (Johann and von Hamos) for XES and HERFD." - source_ref: - label: "NSLS2/iss-profile-collection" - url: "https://github.com/NSLS2/iss-profile-collection" -enclosures: - # 8-ID has an optics enclosure (PV zone XF:08IDA, the FOE: mirrors, monochromators, - # filter box) and an experiment enclosure (PV zone XF:08IDB: sample stages, ion - # chambers, detectors, the emission spectrometers). The zone letters A / B are - # grounded in the PV prefixes; the physical hutch names / numbering are not in source. - - name: 8-ID-A - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS search-and-secure permit leaf not in source; the front-end shutter is XF:08ID-PPS{Sh:FE} and the photon shutter is XF:08IDA-PPS{PSh} (PSS-1)"} - - name: 8-ID-B - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; 8-ID-B (PV zone XF:08IDB) is the experiment enclosure carrying the sample stages, ion chambers, detectors, and emission spectrometers (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the insertion-device source and the front-end / photon shutters -# =========================================================================== - -source: - stage: source - enclosure: 8-ID-A - intro: The 8-ID insertion-device source, the front-end beam-defining slit, and the front-end and photon shutters. - devices: - - name: Undulator - family: InsertionDevice - confirm: "8-ID in-vacuum undulator; energy is driven through the HHM trajectory and the undulator gap PV is not in the profile collection (SRC-1)" - note: "The hard-X-ray insertion device feeding 8-ID on the NSLS-II 3 GeV ring (ring current SR:OPS-BI{DCCT:1}I:Real-I). Period, gap range, and the gap-tracking coupling to the monochromator are not in source (SRC-1)." - - name: FrontEndSlit - family: Slit - pv: "FE:C08A-OP{Slt:12-Ax:" - confirm: true - note: "Front-end white-beam slit (FE:C08A-OP{Slt:12-Ax:X} / {Slt:12-Ax:Y}, horizontal and vertical gap / center) defining the accepted beam." - - name: FrontEndShutter - family: Shutter - pv: "XF:08ID-PPS{Sh:FE}" - confirm: true - note: "Front-end photon shutter." - - name: PhotonShutter - family: Shutter - pv: "XF:08IDA-PPS{PSh}" - confirm: true - note: "Photon shutter gating the beam into the optics enclosure (a two-button open / close shutter)." - -# =========================================================================== -# OPTICS STAGE: the monochromators, the mirrors, the filter box, the slits -# =========================================================================== - -optics: - stage: source - enclosure: 8-ID-A - intro: "Condition the beam and set its energy: the high-heat-load trajectory monochromator (HHM) and the high-resolution monochromator (HRM), the collimating and focusing mirrors, the harmonic-rejection mirror, the filter box, and the hutch slits. PVs verified against the iss-profile-collection startup files." - devices: - - name: HighHeatLoadMonochromator - family: Monochromator - pv: "XF:08IDA-OP{Mono:HHM-Ax:" - confirm: true - note: "The primary double-crystal monochromator (HHM; pitch / roll / theta / Y crystal axes XF:08IDA-OP{Mono:HHM-Ax:P/R/Th/Y}Mtr, and a flying energy axis XF:08IDA-OP{Mono:HHM-Ax:E}Mtr). Energy is swept as a trajectory fly-scan: the Bragg angle follows a pre-computed look-up table on the Delta-Tau controller (XF:08IDA-OP{MC:06}, with per-element Traj:1-9 element / edge / E0 descriptors). Reuses the Monochromator family. Crystal cut and energy range pending (DCM-1)." - - name: HighResolutionMonochromator - family: Monochromator - pv: "XF:08IDA-OP{Mono:HRM-Ax:" - confirm: true - note: "The high-resolution monochromator (HRM; theta / Y / pitch axes XF:08IDA-OP{Mono:HRM-Ax:Th/Y/P}Mtr) used for high-energy-resolution incident-beam conditioning. Reuses the Monochromator family. Crystal cut and reflection pending (DCM-1)." - - name: CollimatingMirror1 - family: Mirror - pv: "XF:08IDA-OP{Mir:1-CM" - confirm: true - note: "First collimating mirror (CM1; pitch / roll / X / Y multi-jack axes, with Rh / Si / Pt stripes selected by the X translation). Reuses the Mirror family." - - name: CollimatingMirror2 - family: Mirror - pv: "XF:08IDA-OP{Mir:2-CM" - confirm: true - note: "Second collimating mirror (CM2; Pt / Rh stripes) with a bender (XF:08IDA-OP{Mir:2-CM-Ax:BEN}Mtr and a load-cell readback). Reuses the Mirror family." - - name: FocusingMirror - family: Mirror - pv: "XF:08IDA-OP{Mir:FM" - confirm: true - note: "Focusing mirror (FM; Pt / Rh stripes) with a bender (XF:08IDA-OP{Mir:FM-Bender}Mtr and a load-cell readback). Reuses the Mirror family." - - name: HarmonicRejectionMirror - family: Mirror - pv: "XF:08IDB-OP{Mir:HRM:" - enclosure: 8-ID-B - confirm: true - note: "High-harmonic-rejection mirror (HHRM; YU / YD1 / YD2 / pitch / table axes and a horizontal stripe translation, Si / Pt / Rh). It sits in the experiment enclosure (PV zone XF:08IDB). Reuses the Mirror family." - - name: FilterBox - family: Filter - pv: "XF:08IDA-OP{Fltr:FB" - confirm: true - note: "Attenuator / filter box (XF:08IDA-OP{Fltr:FB-Ax:Y}Mtr positioning five insertable filters Fltr1-5) hardening the beam and limiting flux. Reuses the Filter family." - - name: HutchSlit - family: Slit - pv: "XF:08IDB-OP{Slt" - enclosure: 8-ID-B - confirm: true - note: "Beam-defining slit in the experiment enclosure (XF:08IDB-OP{Slt-Ax:V-GAP / V-POS / XI / XO}Mtr); a second four-blade hutch slit sits at XF:08IDB-OP{Misc:2-Ax:}. Reuses the Slit family." - - name: EnergyAxis - family: PseudoAxis - confirm: true - note: "The master energy axis: a pseudopositioner mapping photon energy to the HHM Bragg angle (and the coupled undulator gap), realized as the trajectory fly-scan. The energy sweep is the EXAFS measurement, which strengthens but does not coin the deferred energy_scan Capability (ENERGY-1, the BMM question); the technique scope is TECH-1." - - name: BeamPositionMonitor - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1) - pv: "XF:08IDA-BI{BPM:FM}" - confirm: true - note: "Beam-position monitors along the optics (Prosilica cameras XF:08IDA-BI{BPM:FM / CM / 1-BT / 2-BT}) and sample-positioning cameras downstream (XF:08IDB-BI{BPM:SP-n}, XF:08IDB-BI{BPM:ES}). Binds the graduated PositionMonitor Family (a consumer alongside 4-ID / 8-ID / 9-ID; DIAG-1)." - -# =========================================================================== -# SAMPLE STAGE: the sample stages, the reference foil wheel, the thermal control -# =========================================================================== - -sample: - stage: sample - enclosure: 8-ID-B - intro: "The sample stages, the energy-calibration reference foil wheel, and the sample-environment thermal control. PVs verified against the iss-profile-collection startup files." - note: > - ISS positions the sample in the transmission / fluorescence beam path on a - multi-axis stage and rotates it on a goniometer; an upstream reference foil wheel - provides an energy-calibration standard read on a reference ion chamber. The thermal - control reuses TemperatureController. The ion-chamber fill-gas mass-flow controllers - (He / N2) and the broader in-situ sample environment are deferred (ENV-1). - devices: - - name: SampleStage - family: LinearStage - pv: "XF:08IDB-OP{Stage:Sample-Ax:" - confirm: true - note: "Primary sample translation stage (X / Y at XF:08IDB-OP{Stage:Sample-Ax:X / Y}Mtr, Z at XF:08IDB-OP{Misc-Ax:2}Mtr); a finer SampleXY (XF:08IDB-OP{SampleXY}) and an auxiliary stage (XF:08IDB-OP{Stage:Aux1}) sit on it. Reuses the LinearStage family." - - name: SampleGoniometer - family: Goniometer - pv: "XF:08IDB-OP{Gon:Th" - confirm: true - note: "Sample rotation goniometer (theta axes XF:08IDB-OP{Gon:Th:1 / :2}Mtr) setting the sample angle to the beam. Reuses the Goniometer family." - - name: ReferenceFoilWheel - family: RotaryStage - pv: "XF:08IDB-OP{FoilWheel1:Rot}Mtr" - confirm: true - note: "Reference-foil wheel (XF:08IDB-OP{FoilWheel1:Rot}Mtr, with a second wheel on the SampleXY stage) presenting metal-foil standards for per-scan energy calibration on the reference ion chamber. Reuses the RotaryStage family." - - name: SampleTemperature - family: TemperatureController - pv: "XF:08ID-ES{LS:331-1}:" - confirm: true - note: "Sample-environment thermal control (a Lakeshore 331 at XF:08ID-ES{LS:331-1}:). Reuses the TemperatureController family. Which sample-environment units are live is TEMP-1." - -# =========================================================================== -# DETECTION STAGE: the ion chambers, the fluorescence + area detectors, the -# Johann and von Hamos emission spectrometers -# =========================================================================== - -detector: - stage: detection - enclosure: 8-ID-B - intro: "The detectors that make ISS an absorption + emission beamline: the transmission / fluorescence ion chambers, the silicon-drift fluorescence detector, the area detector, and the two crystal emission spectrometers (Johann and von Hamos). PVs verified against the iss-profile-collection startup files." - note: > - Which detector is read decides the technique: the ion chambers (I0 / It / Ir) for - transmission EXAFS, the Xspress3 silicon-drift array for fluorescence EXAFS, and the - Johann or von Hamos crystal emission spectrometer for XES and HERFD. The emission - spectrometers are the signature ISS instruments; both bind the EmissionSpectrometer - family (graduated, LCLS-MFX + ISS). The full per-detector channel map is DET-1. - devices: - - name: IonChambers - family: FluxMonitor - pv: "XF:08IDB-CT{Amp-I0}" - confirm: true - note: "The transmission / fluorescence ion chambers I0 / It / Ir / If, read through configurable amplifiers (the in-house ICAmplifier at XF:08IDB-CT{Amp-I0 / It / Ir / If} and, currently, Keithley 428 preamps at XF:08ID-ES:{K428}:A-D:) and digitized by the analog pizza box (XF:08IDB-CT{PBA:1}); each chamber rides a vertical positioner XF:08IDB-OP{IC-Ax:Y:1-3}Mtr. Reuses the FluxMonitor family (graduated #353). The channel-to-chamber map is DET-1." - - name: FluorescenceDetector - family: EnergyDispersiveSpectrometer - pv: "XF:08IDB-ES{Xsp:1}:" - confirm: true - note: "A four-channel silicon-drift fluorescence detector read by an Xspress3 (XF:08IDB-ES{Xsp:1}: channels C1-C4, with per-channel ROIs and an HDF5 stream) for fluorescence EXAFS. Reuses the EnergyDispersiveSpectrometer family. Element count and ROI map pending (DET-1)." - - name: AreaDetector - family: Camera - pv: "XF:08IDB-ES{Det:PIL1}:" - confirm: true - note: "A Pilatus 100k pixel-array detector (XF:08IDB-ES{Det:PIL1}; a second Pilatus PIL2 is also defined) reading the emission-spectrometer focus and 2D patterns. Reuses the Camera family. Which detector is live per spectrometer is DET-1." - - name: JohannSpectrometer - family: EmissionSpectrometer - pv: "XF:08IDB-OP{HRS:1-" - confirm: true - note: "The Johann high-energy-resolution crystal emission spectrometer (XES / HERFD): a Rowland-circle back-scattering analyzer composing a main crystal plus four auxiliary crystals (XF:08IDB-OP{HRS:1-Stk:1-5:X / Y / Roll / Yaw}Mtr) on a Y assembly (XF:08IDB-OP{HRS:1-Ana:Assy:Y}Mtr) with a two-theta detector arm (XF:08IDB-OP{HRS:1-Det:Gon:Theta1 / Theta2}Mtr). Binds the EmissionSpectrometer family (graduated): ISS is the SECOND sighting after LCLS-MFX's von Hamos XES spectrometer (SPEC-1). Crystal cut, Rowland radius, and whether each analyzer crystal is a child Asset are SPEC-1." - - name: VonHamosSpectrometer - family: EmissionSpectrometer - pv: "XF:08IDB-OP{MC:3-Ax:" - confirm: true - note: "The von Hamos wavelength-dispersive crystal emission spectrometer (XES; a cylindrically-bent crystal spreading the emitted spectrum onto the area detector, motors XF:08IDB-OP{MC:3-Ax:} for the assembly and crystal, sharing the XF:08IDB-OP{HRS:1-Det} detector arm; a separate FIP von Hamos sits at XF:08IDB-OP{FIP-VHS:Stage1 / 2}). Binds the EmissionSpectrometer family (graduated). Crystal cut and geometry are SPEC-1." - -# =========================================================================== -# Cross-cutting controls -# =========================================================================== - -controls: - intro: > - ISS scans run as trajectory fly-scans: the HHM energy axis follows a look-up table - on a Delta-Tau motion controller while the ion-chamber and fluorescence detectors - stream against an encoder. The analog pizza box provides the synchronized - multi-channel readout. Controller box models / firmware / IPs are not fully in the - profile collection (DRIVE-1). - motion_controllers: - - name: TrajectoryMotionController - family: MotionController - pv: "XF:08IDA-OP{MC:06}" - confirm: true - note: "The Delta-Tau motion controller running the HHM energy trajectory (LUT load / transfer, prepare / start / stop trajectory, progress); a second controller (the XF:08IDB-OP{MC:3-Ax:} axes) drives the von Hamos spectrometer. Standard EPICS motor records drive the remaining axes. Box model / firmware pending (DRIVE-1)." - triggering: - - name: AnalogPizzaBox - family: TimingController - pv: "XF:08IDB-CT{PBA:1}:" - confirm: true - note: "The analog pizza box (APB): an eight-channel synchronized ADC (XF:08IDB-CT{PBA:1}: streaming the ion-chamber voltages) plus a trigger / pulse generator (apb_trigger) that times the detectors against the encoder pizza box (XF:08IDA-CT{Enc09:1}) during the fly-scan. Reuses the TimingController family." - software_iocs_not_modeled: - [Xspress3, Pilatus, Keithley428, Lakeshore331, AnalogPizzaBox, TrajectoryManager, ProsilicaBPM, Databroker] - -resources: - intro: Continuously-available resources. Facility-scope supplies live in deployments/nsls2/site.yaml. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum # in-vacuum undulator + optics + spectrometer beam path - - kind: LiquidNitrogen # monochromator crystal cooling - - kind: Power - replaceable_parts: - swappable_with_identity: ["analyzer crystals", "reference foils", "ion-chamber fill gas", "silicon-drift detector"] diff --git a/deployments/ixs/beamline.yaml b/deployments/ixs/beamline.yaml deleted file mode 100644 index 08eb37665d2..00000000000 --- a/deployments/ixs/beamline.yaml +++ /dev/null @@ -1,419 +0,0 @@ -# IXS beamline descriptor (NSLS-II), reverse-engineered -# -# IXS (Inelastic X-ray Scattering) is the NSLS-II momentum-resolved hard X-ray -# inelastic-scattering beamline at sector 10-ID. It is bound to the NSLS-II Site -# (deployments/nsls2/site.yaml), the seventh NSLS-II beamline after FXI, HXN, BMM, -# SRX, SIX, and CHX, and CORA's FIRST hard inelastic-scattering deployment. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the bluesky profile collection NSLS2/ixs-profile-collection) or inferred, -# carried `new: true` + `confirm: true` pending IXS staff. EPICS PVs are real and -# verified against the profile collection startup files; vendor part numbers, -# serials, and physical positions are not in it and are open questions. Same -# descriptor mode as FXI / HXN / BMM / SRX / SIX / CHX; this scaffold is descriptor -# + docs, scenarios deferred. -# -# WHAT IS NEW: IXS is CORA's first photon-in / photon-out energy-LOSS technique. -# The fleet has elastic scattering (SAXS/WAXS, XPDF, powder, XPCS, MX), XRF -# microprobe, hard XAS absorption (BMM), and soft RIXS (SIX), but no hard inelastic -# scattering. The acquisition shape is momentum-resolved energy transfer: set the -# momentum transfer Q with a six-circle reciprocal-space pseudo-axis, then SCAN the -# incident energy (the DCM + the high-resolution monochromator) against a FIXED -# crystal analyzer, point-detecting the energy-analyzed scattered beam to build -# I(Q, energy-loss). meV resolution comes from the high-resolution mono plus a -# temperature-stabilized diced crystal analyzer. -# -# MODELLING: every device reuses an existing catalog or loose Family EXCEPT the -# signature instrument, the crystal energy analyzer, which is coined as ONE loose -# Family `EnergyAnalyzer` at n=1 (naming-r3: the Analyzer sibling of -# the catalog PolarizationAnalyzer). It is NOT graduated; a second hard -# crystal-analyzer beamline must independently earn it, and whether EnergyAnalyzer -# and PolarizationAnalyzer merge into one Analyzer Family is the open ANALYZER-1 -# (see model.md). The six-circle scattering arm binds the catalog Goniometer (the -# 8-ID / 4-ID diffractometer anatomy), not SIX's energy-dispersive SpectrometerArm. -# No catalog change; the IXS Capability is deferred as a question (TECH-1). -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/ixs/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "momentum-resolved hard inelastic X-ray scattering, 10-ID; modelled from public beamline config" - name: IXS - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "Sector 10" # PV namespace XF:10ID* - tier: Unit - parent: null - source: insertion-device - source_confirm: "10-ID in-vacuum undulator IVU22 on SR:C10-ID:G1{IVU22:1}; gap axis. The undulator period/type and whether the 10-ID straight is canted with a sibling beamline are SRC-1 / TOPO-1" - page_layout: stages - shape: "CORA's first hard inelastic-scattering beamline: set Q with a six-circle arm, scan the incident energy against a fixed diced-crystal analyzer, and point-detect to build I(Q, energy-loss)." - source_ref: - label: "NSLS2/ixs-profile-collection" - url: "https://github.com/NSLS2/ixs-profile-collection" -# PV zones along the beamline: FE:C10A (front end), XF:10IDA (DCM + first -# diagnostics), XF:10IDB (the high-resolution monochromator + secondary source), -# XF:10IDC (transport optics + table), XF:10IDD (the endstation: KB mirrors, -# sample, six-circle spectrometer, crystal analyzer, detectors). Whether these are -# four separate shielded hutches or beam zones within fewer hutches, and the PSS -# permit leaves, are open (ENC-1, PSS-1). -enclosures: - - name: 10-ID-A - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf not in source; the front-end and photon shutters and interlock tier are absent from the profile collection and are PSS-1"} - - name: 10-ID-B - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; the high-resolution-mono hutch; whether A/B/C are one optics hutch or several is ENC-1 (PSS-1)"} - - name: 10-ID-C - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; transport optics zone (ENC-1, PSS-1)"} - - name: 10-ID-D - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; the IXS endstation hutch (ENC-1, PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the undulator, the front end, the DCM, and the high-resolution mono -# =========================================================================== - -insertion-devices: - stage: source - enclosure: 10-ID-A - intro: "The in-vacuum undulator source on the SR:C10-ID straight." - note: "One InsertionDevice Asset; in-vacuum is a per-Asset setting (hxn / chx / srx precedent), not a Family split. Period and type are SRC-1." - devices: - - name: Undulator - family: InsertionDevice - pv: "SR:C10-ID:G1{IVU22:1-Ax:Gap}-Mtr" - new: true - confirm: true - note: "IVU22 in-vacuum undulator (gap); the incident-energy pseudo-axis tracks its gap against the DCM Bragg angle (SRC-1)" - -machine: - stage: source - enclosure: 10-ID-A - intro: "The machine-level source state and the source-orbit feedback, observed not driven." - note: "Observe-only machine state, the loose StorageRing pattern reused from i22 / i03 / i15-1 (MACHINE-1). The undulator-orbit feedback has no clean motion Family and is carried family-less, modelling deferred (FEEDBACK-1, the i03 XBPMFeedback precedent)." - devices: - - name: StorageRing - family: StorageRing # loose Family (machine-level observe-only ring state; MACHINE-1) - pv: "SR:OPS-BI{DCCT:1}I:Real-I" - new: true - confirm: true - note: "storage-ring current (DCCT); observe-only machine state, not photon-path flux (MACHINE-1)" - - name: OrbitFeedback - pv: {confirm: "SR:UOFB{...} undulator-orbit feedback (id bump / nudge); modelling deferred, no Family coined at n=1 (FEEDBACK-1)"} - new: true - confirm: true - note: "source-orbit feedback construct; carried family-less pending a modelling decision (FEEDBACK-1)" - -front-end: - stage: source - enclosure: 10-ID-A - intro: "The front-end beam-defining slit and the compound-refractive-lens transfocator." - note: "The CRL transfocator reuses the graduated Transfocator catalog Family (a CRL focusing optic; 4-id / 8-id / 9-id / chx / i22); its x/y/th are Asset-layer settings." - devices: - - name: FrontEndSlit - family: Slit - pv: "FE:C10A-OP{Slt:" - new: true - confirm: true - note: "front-end beam-defining slit (blades + virtual centre/gap); axis roles are OPT-2" - - name: Transfocator - family: Transfocator # catalog Family (CRL focusing optic) - pv: { x: "FE:C10A-OP{CRL:1-Ax:X}Mtr", y: "FE:C10A-OP{CRL:1-Ax:Y}Mtr", th: "FE:C10A-OP{CRL:1-Ax:P}Mtr" } - new: true - confirm: true - note: "front-end compound-refractive-lens transfocator; lens-stack composition is a setting" - -monochromator: - stage: source - enclosure: 10-ID-A - intro: "The double-crystal monochromator that selects the incident energy, its downstream slit and beam-position monitor, and the incident-energy pseudo-axes." - note: > - dcm is the Si(111) double-crystal Bragg monochromator: a crystal DCM binds the - catalog Monochromator (unlike SIX's plane-grating PGM, which has no Bragg - crystal and coined GratingMonochromator). The incident energy is a PseudoAxis: - blE couples the DCM Bragg angle to the undulator gap, dcmE drives the DCM alone - (MONO-1). - devices: - - name: Monochromator - family: Monochromator - pv: { theta: "XF:10IDA-OP{Mono:DCM-Ax:P}Mtr", y: "XF:10IDA-OP{Mono:DCM-Ax:Y}Mtr", z2: "XF:10IDA-OP{Mono:DCM-Ax:Z2}Mtr" } - new: true - confirm: true - note: "Si(111) double-crystal monochromator; crystal cut / d-spacing / energy range are MONO-1; the second-crystal offset z2 is a setting" - - name: IncidentEnergy - family: PseudoAxis - pv: {confirm: "blE / dcmE virtual energy axes, 7.835-17.7 keV; blE = DCM Bragg + IVU22 gap tracking, dcmE = DCM only; the partition rule (arcsin(hc/2dE) + gap lookup) is MONO-1"} - new: true - confirm: true - note: "incident-energy pseudo-axis over the DCM and undulator (the 2-BM beamline_energy_change pattern); MONO-1" - - name: MonoSlit - family: Slit - pv: "XF:10IDA-OP{Slt:1" - new: true - confirm: true - note: "post-DCM beam-defining slit (OPT-2)" - - name: BeamPositionMonitor_A - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1, BPM-1) - pv: "XF:10IDA-OP{BPM:1" - new: true - confirm: true - note: "10-ID-A beam-position monitor (x/y + diagnostic foil); NSLS-II-sibling choice (hxn), but the fleet is split with Diagnostic / GenericProbe (DIAG-1/BPM-1); the foil is a setting" - -high-resolution-mono: - stage: source - enclosure: 10-ID-B - intro: "The high-resolution monochromator that sets the meV incident-energy resolution, its secondary source aperture, and the high-resolution energy pseudo-axis." - note: > - hrm2 is the high-resolution monochromator: anatomically still a crystal Bragg - mono (up / down crystals), so it binds the catalog Monochromator as a second - Asset. Resolution is a tunable setting, not a Family discriminator. The in-line - beamstop is a candidate child BeamStop Asset (HRM-1). hrmE is the linear - translation-to-energy pseudo-axis (MONO-1). - devices: - - name: HighResolutionMonochromator - family: Monochromator - pv: { up_offset: "XF:10IDB-OP{Mono:HRM2-Ax:UTO}Mtr", down_offset: "XF:10IDB-OP{Mono:HRM2-Ax:DTO}Mtr" } - new: true - confirm: true - note: "high-resolution crystal monochromator (HRM2, up / down crystals + picomotors); meV resolution is a setting; the in-line beamstop is HRM-1" - - name: HighResolutionEnergy - family: PseudoAxis - pv: {confirm: "hrmE virtual energy axis; linear crystal-translation-to-energy mapping (constants from the legacy SPEC file); MONO-1"} - new: true - confirm: true - note: "high-resolution incident-energy pseudo-axis over HRM2; the meV energy-transfer scan axis (MONO-1)" - - name: SecondarySourceAperture - family: Slit - pv: "XF:10IDB-OP{SSA:1" - new: true - confirm: true - note: "secondary source aperture; two driven blades = a Slit despite the aperture label (fxi / hxn / srx precedent); OPT-2" - -# =========================================================================== -# TRANSPORT STAGE: the transport optics, table, and second beam-position monitor -# =========================================================================== - -transport: - stage: source - enclosure: 10-ID-C - intro: "The transport slit, the support table, and the second beam-position monitor." - devices: - - name: TransportSlit - family: Slit - pv: "XF:10IDC-OP{Slt:4" - new: true - confirm: true - note: "transport beam-defining slit (OPT-2)" - - name: Table - family: Table - pv: "XF:10IDC-OP{Tbl:1" - new: true - confirm: true - note: "support / positioning table; axis set is an Asset-layer setting" - - name: BeamPositionMonitor_C - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1, BPM-1) - pv: "XF:10IDC-OP{BPM:2" - new: true - confirm: true - note: "10-ID-C beam-position monitor (x/y + diagnostic foil); DIAG-1/BPM-1" - -# =========================================================================== -# ENDSTATION OPTICS: the KB mirrors, endstation slit, pinhole, and manipulator -# =========================================================================== - -endstation-optics: - stage: source - enclosure: 10-ID-D - intro: "The KB refocusing mirrors, the endstation slit, the focusing pinhole, the absorber wheel, and the multi-axis optics manipulator." - note: "vfm / hfm are the vertical / horizontal KB focusing mirrors; orientation is a setting (the SIX Mirror precedent covers even hexapod-mounted mirrors). mcm is a six-DOF coupled manipulator = catalog Hexapod (MCM-1)." - devices: - - name: VerticalFocusingMirror - family: Mirror - pv: "XF:10IDD-OP{VFM:1" - new: true - confirm: true - note: "vertical KB focusing mirror; coatings / bend are OPT-1" - - name: HorizontalFocusingMirror - family: Mirror - pv: "XF:10IDD-OP{HFM:1" - new: true - confirm: true - note: "horizontal KB focusing mirror; coatings / bend are OPT-1" - - name: EndstationSlit - family: Slit - pv: "XF:10IDD-OP{Slt:5" - new: true - confirm: true - note: "endstation beam-defining slit (OPT-2)" - - name: Pinhole - family: Aperture - pv: { ux: "XF:10IDD-OP{Pinh:1-Ax:UX}Mtr", uy: "XF:10IDD-OP{Pinh:1-Ax:UY}Mtr", dx: "XF:10IDD-OP{Pinh:1-Ax:DX}Mtr", dy: "XF:10IDD-OP{Pinh:1-Ax:DY}Mtr" } - new: true - confirm: true - note: "positioned focusing pinhole; Aperture (fxi / 9-id round-opening precedent) vs catalog Mask (plain fixed opening) is PH-1" - - name: AbsorberWheel - family: Filter - pv: "XF:10IDD-OP{Abs:1-Ax:Wheel}Mtr" - new: true - confirm: true - note: "discrete absorber-foil wheel; the catalog Filter covers attenuators (i03 / i15-1 precedent), wheel-vs-paddle is a setting" - - name: OpticsManipulator - family: Hexapod - pv: { x: "XF:10IDD-OP{MCM:1-Ax:X}Mtr", y: "XF:10IDD-OP{MCM:1-Ax:Y}Mtr", z: "XF:10IDD-OP{MCM:1-Ax:Z}Mtr", rx: "XF:10IDD-OP{MCM:1-Ax:Rx}Mtr", ry: "XF:10IDD-OP{MCM:1-Ax:Ry}Mtr", rz: "XF:10IDD-OP{MCM:1-Ax:Rz}Mtr" } - new: true - confirm: true - note: "six-DOF coupled optics manipulator (MCM); a parallel-kinematics Hexapod (hxn / i15-1 / 9-id precedent). If the axes are independent serial rotations the read weakens (MCM-1)" - -# =========================================================================== -# SAMPLE STAGE: the sample table and the sample-environment translations -# =========================================================================== - -sample: - stage: sample - enclosure: 10-ID-D - intro: "The sample positioning table and the sample-environment translations." - note: "Pure-translation stacks bind the catalog LinearStage (fxi / hxn SampleStage precedent). Whether the table and the environment translations are one fused Asset or two siblings on their separate PV roots is SAMPLE-1. Not a UHV cryostat Manipulator (SIX): IXS is a hard X-ray ambient endstation, so reusing Manipulator would mirror context not anatomy." - devices: - - name: SampleTable - family: LinearStage - pv: { x: "XF:10IDD-OP{Spec:1-Ax:X}Mtr", y: "XF:10IDD-OP{Spec:1-Ax:Y}Mtr", z: "XF:10IDD-OP{Spec:1-Ax:Z}Mtr" } - new: true - confirm: true - note: "sample positioning table (SAMPLE-1)" - - name: SampleEnvironment - family: LinearStage - pv: { x: "XF:10IDD-OP{Env:1-Ax:X}Mtr", y: "XF:10IDD-OP{Env:1-Ax:Y}Mtr", z: "XF:10IDD-OP{Env:1-Ax:Z}Mtr" } - new: true - confirm: true - note: "sample-environment translation stack on its own Env PV root (SAMPLE-1)" - -# =========================================================================== -# DETECTION STAGE: the six-circle spectrometer arm, the crystal energy analyzer, -# the analyzer thermal stabilization, and the counting detectors -# =========================================================================== - -spectrometer: - stage: detection - enclosure: 10-ID-D - intro: "The six-circle scattering spectrometer arm and its reciprocal-space pseudo-axis, which set the momentum transfer Q." - note: > - The spectrometer arm (tth / th / chi / phi) is a six-circle scattering geometry - driven by the HKL reciprocal-space pseudo-axis, the 8-ID / 4-ID diffractometer - anatomy, so it binds the catalog Goniometer (NOT SIX's energy-dispersive - SpectrometerArm, which is a different, dispersive instrument). Whether the arm - plus the crystal analyzer compose an Assembly(Diffractometer)-style Fixture is - ANALYZER-1; like 8-ID / 4-ID in descriptor mode, the Assembly is named as a - follow-on, not materialized here. - devices: - - name: Spectrometer - family: Goniometer - pv: { two_theta: "XF:10IDD-OP{Spec:1-Ax:2Th}Mtr", theta: "XF:10IDD-OP{Spec:1-Ax:Th}Mtr", chi: "XF:10IDD-OP{Spec:1-Ax:ChiA}Mtr", phi: "XF:10IDD-OP{Spec:1-Ax:PhiA}Mtr" } - new: true - confirm: true - note: "six-circle scattering arm; the scattering angle two_theta sets |Q|, driven by the reciprocal-space pseudo-axis (ANALYZER-1 for the Assembly question)" - - name: ReciprocalSpace - family: PseudoAxis - pv: {confirm: "HKLPseudoV2 (H, K, L) over the six-circle tth / th / chi / phi via the SixCircle kinematics; SamplePrime sample-frame rotation; the geometry constants are from the legacy SPEC file"} - new: true - confirm: true - note: "six-circle reciprocal-space pseudo-axis (the Diffractometer reciprocal_space PseudoAxis pattern); the read-only derived angles present a Sensor read-back facet (ENERGY-1)" - -analyzer: - stage: detection - enclosure: 10-ID-D - intro: "The crystal energy analyzer (a diced multi-crystal Bragg analyzer), its slit, and the per-crystal thermal stabilization." - note: > - The energy analyzer is the signature IXS instrument: a diced multi-crystal Bragg - analyzer (six diced crystals d1-d6, each with theta + phi orientation and PID - temperature stabilization) that Bragg-reflects the scattered beam to select a - fixed final energy, focusing energy-selected photons onto the counting - detectors. No catalog or loose Family fits this anatomy (it is not the catalog - EnergyDispersiveSpectrometer, a per-event point Sensor, nor a Monochromator, an - upstream incident optic, nor SIX's dispersive SpectrometerArm), so it is coined - as ONE loose Family `EnergyAnalyzer` at n=1, the Analyzer sibling of - the catalog PolarizationAnalyzer (naming-r3-cleared). It is NOT graduated; a - second hard crystal-analyzer beamline must independently earn it, and whether - EnergyAnalyzer and PolarizationAnalyzer merge into one Analyzer Family is - ANALYZER-1. The six diced crystals are carried as settings on the one Asset; the - convention for promoting each identity-bearing crystal (own theta / phi + own - temperature) to a child Asset is at a rule-of-three gate (XTAL-1). - devices: - - name: EnergyAnalyzer - family: EnergyAnalyzer # loose Family (n=1; diced crystal Bragg energy analyzer; ANALYZER-1) - pv: { coarse_theta: "XF:10IDD-ES{Ez4:1-Ax:1}Mtr", coarse_chi: "XF:10IDD-ES{Ez4:1-Ax:2}Mtr", wide_theta: "XF:10IDD-ES{Ez4:1-Ax:3}Mtr", wide_chi: "XF:10IDD-ES{Ez4:1-Ax:4}Mtr", up_y: "XF:10IDD-OP{Analy:1-Ax:UY}Mtr", down_y: "XF:10IDD-OP{Analy:1-Ax:DY}Mtr" } - new: true - confirm: true - note: "diced crystal Bragg energy analyzer; six diced crystals d1-d6 (each theta + phi, XF:10IDD-ES{Ez4:2/3/4}) carried as settings; child-Asset-per-crystal is XTAL-1; presents Positioner with Sensor-vs-Positioner a confirm (the SIX SpectrometerArm precedent); the merge with PolarizationAnalyzer is ANALYZER-1" - - name: AnalyzerSlit - family: Slit - pv: "XF:10IDD-ES{Ez4:5" - new: true - confirm: true - note: "analyzer-chamber beam-defining slit (top / bottom / inboard / outboard); OPT-2" - - name: AnalyzerThermalControl - family: TemperatureController - pv: {confirm: "six PID loops XF:10IDD-CT{EPid:01-06}PID.VAL stabilizing the diced crystal temperatures (DxtalTemp)"} - new: true - confirm: true - note: "per-crystal thermal stabilization for energy stability; presents the Regulator Role (graduated Family reused). Six PID channels modelled as one Asset; six-vs-one Assets and the parent (analyzer vs per-crystal child) are TEMP-1 / XTAL-1" - -detection: - stage: detection - enclosure: 10-ID-D - intro: "The counting detectors: the quad electrometers reading the energy-analyzed signal and the incident-flux scaler." - note: > - IXS detection is point / current-integrating, not imaging: the diced analyzer - focuses energy-selected photons onto photodiodes read by quad electrometers, - the science detector (the BMM QuadEM-as-primary precedent). These bind the - catalog FluxMonitor (Sensor). The scaler I0 channel is the incident-flux - monitor, also FluxMonitor. Whether the analyzer-focus photodiode is a separate - Photodiode Asset or just an electrometer channel is DET-1 (default: a channel, - not a standalone Asset). - devices: - - name: AnalyzerElectrometers - family: FluxMonitor - pv: {confirm: "NSLS_EM quad electrometers XF10ID-BI:AH171-175 and XF:10ID-BI:TM176/178 reading the analyzed-beam / drain-current channels; the science point detector (DET-1)"} - new: true - confirm: true - note: "quad electrometers reading the energy-analyzed scattered signal as a scalar current (the BMM primary-detector precedent); DET-1" - - name: IncidentScaler - family: FluxMonitor - pv: "XF:10IDD-ES{Sclr:1}" - new: true - confirm: true - note: "counting scaler; chan21 = the I0 incident-flux monitor for normalization (DET-1)" - -# Cross-cutting control. IXS runs EPICS (the floor); CORA observes and, where it -# replaces bluesky-style orchestration, conducts over it. The handles above were -# read from the ixs-profile-collection startup files and carried confirm (CTRL-1). -controls: - intro: > - IXS runs on the NSLS-II EPICS / ophyd control stack, the same floor as FXI, - HXN, BMM, SRX, SIX, and CHX. The device handles above are bound from the - beamline's bluesky profile collection (NSLS2/ixs-profile-collection), carried - confirm pending staff verification (CTRL-1). The IXS acquisition (the incident- - energy scan, the six-circle Q moves, the analyzer alignment, the counting) runs - through bluesky plans and the queue server (the startup 97-99 plans, the - 98-alignment scans, the SPEC-derived macros); that orchestration is the seam - CORA's edge replaces, driving through ophyd / EPICS, while the file-writing to - the NSLS-II filestore is plumbing CORA observes, not data it owns (see model.md). - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources an IXS run needs. The optics and - the spectrometer run under vacuum; the diced crystal analyzer draws on the PID - thermal-stabilization loops (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the optics and the spectrometer beam path are under vacuum (SUP-1)" diff --git a/deployments/lcls-mfx/beamline.yaml b/deployments/lcls-mfx/beamline.yaml deleted file mode 100644 index 1187483aef5..00000000000 --- a/deployments/lcls-mfx/beamline.yaml +++ /dev/null @@ -1,347 +0,0 @@ -# CORA Beamline descriptor: LCLS-MFX (SLAC), modelling exercise -# -# MFX (Macromolecular Femtosecond Crystallography) is an operating hard-X-ray -# instrument of the LCLS X-ray free-electron laser at SLAC. It is bound to the -# SLAC Site (deployments/slac/site.yaml), CORA's fifth Site and its FIRST XFEL. -# -# STATUS: off-roadmap modelling exercise, NOT a CORA pilot. The device shape and -# the EPICS control handles are reverse-engineered from SLAC's open `pcdshub` -# stack (the happi device database device_config/db.json, the worked hutch config -# mfx/beamline.py, the lightpath beam-walk engine, and pcdsdevices), treated as a -# dry, correct DATA source and modelled intentionally, not mirrored. Scope is the -# MFX beam-path spine + core endstation; peripheral/floor devices are deferred. -# -# WHY MFX (what it tests): every prior modelling exercise (Diamond i22/i03/i11/ -# i15-1, NSLS-II FXI) is a STORAGE-RING beamline: frame-on-trigger detectors and -# sub-Hz scalar monitoring. MFX is an XFEL: per-shot, pulse-ID-tagged event DAQ -# (120 Hz; LCLS-II reaches ~1 MHz), beam-synchronous event-code timing, fs optical -# pump-probe, and one linac feeding many co-equal instruments. It is the test of -# whether CORA generalizes beyond the storage-ring acquisition paradigm. -# -# THE HEADLINE FINDING: MFX's DEVICE FAMILIES FOLD. Of the full device set, exactly -# one type had no CORA Family at the time (the von Hamos emission spectrometer; its -# EmissionSpectrometer family has since graduated, ISS 2nd sighting). -# Everything else reuses a catalog Family or an existing loose family. The genuine -# gaps MFX exposes are ARCHITECTURAL, not taxonomic, and are recorded as deliberate -# deferrals on docs/deployments/lcls-mfx/model.md (not invented here): -# - per-shot pulse-ID event DAQ (DAQ-1; see the event-stream-axis design memo) -# - beam-synchronous event-code timing (TIMING-1) -# - femtosecond pump-probe laser/X-ray synchronization (LASER-1) -# - one switched FEL source feeding co-equal instruments (TOPO-1) -# - attenuator transmission solver (ATT-1) -# - computed device-state -> path-transmission lightpath (LIGHTPATH-1) -# -# Family folds (each adversarially reviewed, i03 precedent): OffsetMirror -> Mirror; -# solid-Si Attenuator -> Filter; Slits(JAWS) -> Slit; PulsePicker -> Shutter (fast -# pulse gate; Shutter-vs-Chopper open, PULSE-1); PIM -> Scintillator + Camera; IPM -# -> FluxMonitor + Diagnostic (loose, reused from i22/2-BM); DCCM -> Monochromator; -# Transfocator/XFLS -> Transfocator (graduated catalog Family, a CRL focusing -# optic); EventSequencer -> -# TimingController; the area detector -> Camera. The gas detector (a BeamStats PV, -# not a happi device) -> FluxMonitor. Vacuum gate valves and the DAQ are floor and -# not modelled (as at i03). One new family at the time: EmissionSpectrometer, since -# GRADUATED into the catalog once NSLS-II ISS (8-ID) earned the second sighting (SPEC-1). -# -# Every device carries `new: true` (not a registered Asset) and `confirm: true` -# (PVs + values to be verified by LCLS staff). Calibrated numbers, the PPS safety -# structure, undulator specifics, and the Capability/Method binding are NOT -# invented; each gap carries a (QUESTION-ID) answered on the open-questions page. -# -# DEFERRED (out of spine+core scope, noted not modelled): the LCLS DAQ data plane -# (psana/psdaq; CORA references a Dataset, does not own per-shot data, DAQ-1); the -# pump-probe optical-laser delay stages + lxt/txt fs timing chain (the laser is -# carried as a catalog Laser Family device, the 4-ID precedent, model-vs-hazard -# open; its fs X-ray/laser synchronization has no CORA model, LASER-1); the -# liquid-jet / fixed-target sample delivery (SAMPLE-1); the sibling instruments -# (CXI/XPP/XCS/MEC/TMO/RIX) that share the linac (TOPO-1). - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "macromolecular femtosecond crystallography at the LCLS free-electron laser; the first XFEL, where the device families fold but the per-shot acquisition paradigm does not" - name: LCLS-MFX - facility: slac - tier: Unit - parent: null - source: free-electron-laser - source_confirm: > - SASE hard-X-ray FEL on the shared LCLS linac + HXR undulator line; photon energy - is set per-shot (vernier / undulator), not as a standing setpoint, and the same - source feeds many co-equal instruments one at a time (SRC-1 / TOPO-1). - page_layout: stages - shape: "CORA's first XFEL (SLAC LCLS): a per-shot, pulse-ID-tagged event stream at beam rate with femtosecond pump-probe; the device families fold and the genuine gaps are the acquisition ontology, not new device kinds." - source_ref: - label: "pcdshub" - url: "https://github.com/pcdshub" - -# Two access-gated zones. The shared front end + X-ray transport (FEE/XRT) feeds -# every hard-X-ray instrument, not just MFX; CORA models it here as one enclosure -# but its sharing across instruments is the headline topology question (TOPO-1). -# LCLS PPS permit + the pump-probe BTPS laser interlock are carried confirm (PSS-1). -enclosures: - - name: LCLS-FEE - role: optics-hutch - facility_code: slac - permit_signal: {confirm: "LCLS PPS search-and-secure signal TBD; shared front-end / transport (TOPO-1, PSS-1)"} - - name: LCLS-MFX - role: experiment-hutch - facility_code: slac - permit_signal: {confirm: "LCLS PPS + pump-probe BTPS laser interlock TBD (PSS-1, LASER-1)"} - -# --- SOURCE STAGE: the FEL source, shared front end, and X-ray transport --- - -undulator-source: - stage: source - enclosure: LCLS-FEE - intro: "The free-electron-laser source and its per-shot pulse-energy monitor." - note: > - LCLS is a linac-driven FEL, not a storage ring, so the loose StorageRing family - used by the synchrotron exercises does not fit; machine beam is carried as a - PhotonBeam Supply (MACHINE-1). The undulator photon energy is set per shot - (vernier / undulator gap); CORA has no per-shot energy setpoint, and the - undulator-as-driven-source with energy->gap control is deferred (SRC-1). - devices: - - name: Undulator - family: InsertionDevice - pv: {confirm: "LCLS HXR undulator line (USEG / vernier energy request); per-segment handles TBD (SRC-1)"} - new: true - confirm: true - device_type: SASE free-electron-laser undulator - note: "the FEL source; SASE / self-seeded mode and per-shot photon energy are a DAQ-plane datum, not a standing setpoint (SRC-1, DAQ-1)" - - name: GasDetector - family: FluxMonitor - pv: {confirm: "GDET:FEE1:241:ENRC (read via BeamStats, not a happi device)"} - new: true - confirm: true - note: "FEL pulse-energy gas detector; presents the Sensor Role; loose family reused from i22 (DIAG-1). Per-shot pulse energy is correlated in the DAQ by pulse-ID (DAQ-1)" - -front-end-transport: - stage: source - enclosure: LCLS-FEE - intro: "The shared solid attenuators, offset mirrors, X-ray transport mirrors, PPS stopper, and transport diagnostics that condition and steer the beam toward MFX." - note: > - The X-ray transport mirrors (XRT) are where the single FEL source is steered down - one branch to one instrument at a time; CORA has no switched-shared-source model, - so the routing is carried here but the topology is deferred (TOPO-1). Vacuum gate - valves are floor (not modelled), as at i03. - devices: - - name: FrontEndAttenuator - family: Filter - pv: "SATT:FEE1:320" - new: true - confirm: true - note: "solid-Si front-end attenuator; the existing Filter Family covers it (adversarial-verified). Target-transmission solving (foil combination for a requested transmission, energy-dependent) is the deferred Attenuable leg (ATT-1)" - - name: FrontEndMirror1 - family: Mirror - pv: "FEE1:M1H" - new: true - confirm: true - note: "first horizontal offset mirror; OffsetMirror folds into the Mirror Family" - - name: FrontEndMirror2 - family: Mirror - pv: "FEE1:M2H" - new: true - confirm: true - note: "second horizontal offset mirror" - - name: TransportMirror2 - family: Mirror - pv: "XRT:M2H" - new: true - confirm: true - note: "X-ray-transport steering mirror" - - name: TransportMirror3 - family: Mirror - pv: "XRT:M3H" - new: true - confirm: true - note: "X-ray-transport steering mirror that routes the beam to the experiment branch; the switched-source seam (one source, many instruments) lives here (TOPO-1)" - - name: TransportStopper - family: Shutter - pv: "HFX:DG2:STP:01" - new: true - confirm: true - note: "PPS-interlocked beam stopper on the transport line; permit signal to confirm (PSS-1)" - - name: TransportSlits - family: Slit - pv: "HFX:DG2:JAWS" - new: true - confirm: true - note: "transport-line 4-blade slits (gap/center virtual axes)" - - name: TransportIPM - family: FluxMonitor - pv: "HFX:DG2:IPM" - new: true - confirm: true - note: "intensity-position monitor; presents the Sensor Role for both flux (FluxMonitor) and beam position (Diagnostic); loose families reused (DIAG-1). Per-shot intensity normalization is a DAQ-plane concern (DAQ-1)" - - name: TransportImager - family: Scintillator - pv: "HFX:DG2:PIM" - new: true - confirm: true - note: "profile-imager (YAG screen + camera); the screen presents Scintillator, the camera presents Camera (Detector Role)" - -# --- SAMPLE STAGE: the MFX endstation conditioning and sample interaction --- - -mfx-conditioning: - stage: sample - enclosure: LCLS-MFX - intro: "The pulse picker, attenuator, channel-cut mono, focusing lenses, slits, and per-shot diagnostics that condition the beam inside the MFX hutch." - note: > - The compound-refractive-lens transfocator + prefocus reuse the graduated - Transfocator catalog Family (a CRL focusing optic). The pulse picker is a fast - single-pulse gate folded into the - Shutter Family; whether a fast pulse-picking chopper deserves its own Family is - open (PULSE-1). The diamond channel-cut mono (DCCM) is used for some modes; - pink-vs-mono operation is carried confirm (MONO-1). - devices: - - name: PulsePicker - family: Shutter - pv: "MFX:DIA:MMS:07" - new: true - confirm: true - note: "fast single-pulse selector; folded into the Shutter Family (a fast beam gate). Whether a rotary pulse-picking chopper is a distinct Family is open (PULSE-1)" - - name: Attenuator - family: Filter - pv: "MFX:ATT" - new: true - confirm: true - note: "solid-Si binary attenuator; the existing Filter Family covers the discrete foil selection. Requesting a target transmission (the AttBase set_transmission solver, energy-dependent) is the deferred Attenuable leg; LCLS is the rule-of-three trigger for it (ATT-1)" - - name: DCCM - family: Monochromator - pv: {confirm: "MFX diamond double-channel-cut mono; handles TBD (MONO-1)"} - new: true - confirm: true - note: "diamond double-channel-cut monochromator for monochromatic / spectroscopy modes; MFX also runs pink/SASE beam mono-out (MONO-1)" - - name: Transfocator - family: Transfocator - pv: "MFX:LENS" - new: true - confirm: true - note: "compound-refractive-lens (Be) transfocator stack; reuses the graduated Transfocator catalog Family (a CRL focusing optic). Selecting a lens set for a target focal length is a transmission/focus solver, like the attenuator (ATT-1)" - - name: Prefocus - family: Transfocator - pv: "MFX:DIA:XFLS" - new: true - confirm: true - note: "upstream X-ray focusing lens set (prefocus CRL); reuses the graduated Transfocator catalog Family (a CRL focusing optic)" - - name: MFXSlits - family: Slit - pv: "MFX:DG1:JAWS" - new: true - confirm: true - note: "DG1 4-blade slits" - - name: MFXSlitsDownstream - family: Slit - pv: "MFX:DG2:JAWS:US" - new: true - confirm: true - note: "DG2 slit set (upstream/midstream/downstream blades)" - - name: MFXIntensityMonitor - family: FluxMonitor - pv: "MFX:DG1:IPM" - new: true - confirm: true - note: "intensity-position monitor (DG1); flux + position Sensor; loose families reused (DIAG-1)" - - name: MFXImager - family: Scintillator - pv: "MFX:DG1:PIM" - new: true - confirm: true - note: "DG1 profile imager (YAG + camera)" - - name: TimeTool - family: Diagnostic - pv: "MFX:ATM" - new: true - confirm: true - note: "arrival-time monitor (X-ray/optical-laser timing jitter); presents the Sensor Role; loose family reused (DIAG-1). It exists to drift-correct the fs pump-probe delay, which CORA has no model for (LASER-1, DAQ-1)" - - name: Wave8 - family: FluxMonitor - pv: "MFX:DG1:MMS:08" - new: true - confirm: true - note: "fast per-shot intensity / wavefront diagnostic; presents the Sensor Role; loose family reused (DIAG-1)" - -mfx-endstation: - stage: sample - enclosure: LCLS-MFX - intro: "The sample-interaction point: sample delivery and the X-ray emission spectrometer." - note: > - Sample delivery at MFX is a liquid jet / fixed target (serial femtosecond - crystallography), with no storage-ring analog; it is deferred (SAMPLE-1). The von - Hamos spectrometer is a crystal-analyzer X-ray emission spectrometer (it composes - analyzer crystals + a 2D detector along a dispersive geometry). It introduced the - EmissionSpectrometer family, which GRADUATED into the catalog once NSLS-II ISS - (8-ID) earned the second sighting (the Johann + von Hamos XES / HERFD spectrometers); - the same gap appeared at MAX IV Balder (SCANIA-2D). Whether each analyzer crystal is - a child Asset is still open (SPEC-1). - devices: - - name: PumpProbeLaser - family: Laser - pv: {confirm: "LAS:FS45 (laser timing) + MFX:LAS:MMN:* (delay / waveplate motors)"} - new: true - confirm: true - note: "femtosecond optical pump-probe laser; binds the catalog Laser Family (the 4-ID precedent, model-vs-hazard open, SAMPLE-1). The delay stage is a LinearStage, but the laser/X-ray fs synchronization (the lxt_ttc SyncAxis, ~50 fs deadband) is a cross-timing-domain relationship CORA cannot express (LASER-1)" - - name: LiquidJet - pv: "MFX:LJH" - new: true - confirm: true - note: "Beckhoff-controlled liquid-jet sample delivery (serial crystallography); also a fixed-target option. Sample-delivery is endstation-specific and deferred (SAMPLE-1); no Family is coined yet" - - name: EmissionSpectrometer - family: EmissionSpectrometer - pv: "MFX:SPEC" - new: true - confirm: true - note: "von Hamos 6-crystal X-ray emission spectrometer (XES / HERFD): a crystal-analyzer dispersive spectrometer composing analyzer crystals + a 2D detector, distinct from a Monochromator. Binds the EmissionSpectrometer family, which it introduced and which GRADUATED into the catalog once NSLS-II ISS (8-ID) earned the second sighting (SPEC-1)" - -# --- DETECTION STAGE: the per-shot area detector --- - -detector: - stage: detection - enclosure: LCLS-MFX - intro: "The MFX area detector. It reuses the Camera Family, but its acquisition mode is the headline gap." - note: > - The detector reuses the Camera Family (Detector Role). What does NOT fold is how - it is read: the LCLS DAQ records a free-running stream of per-shot frames tagged - by pulse-ID at beam rate, correlated downstream by fiducial, not a poll-Acquire- - to-Done frame loop. CORA's acquisition bodies do not represent this; the per-shot - event DAQ is the deepest gap and is sketched in the event-stream-axis design memo - (DAQ-1). The detector model (Rayonix / ePix10k / Jungfrau) is to confirm (DET-1). - devices: - - name: Detector - family: Camera - pv: {confirm: "MFX area detector (Rayonix MX340-XFEL / ePix10k / Jungfrau); DAQ-managed, not polled (DET-1)"} - new: true - confirm: true - note: "the science detector; per-shot frames flow through the DAQ data plane, which CORA references as a Dataset rather than owns (DAQ-1)" - -# Cross-cutting timing + the software systems CORA does not model. -controls: - intro: > - MFX runs the pcdshub EPICS stack plus a separate event-driven DAQ. The - EventSequencer programs the beam-synchronous trigger pattern; the DAQ, analysis, - and scan suites are software/floor. - triggering: - - name: EventSequencer - family: TimingController - pv: "ECS:SYS0:7" - new: true - confirm: true - note: "plays a beam-synchronous event-code sequence (each line [beam_code, delta_beam, delta_fiducial, burst_count]) that gates acquisition at beam rate. TimingController carries the device, but 'acquire on event-code N at rate R, burst B' has no typed parameter home (TIMING-1). Spare on ECS:SYS0:12" - software_iocs_not_modeled: - - LCLS DAQ (psdaq / pcdsdaq; the per-shot, pulse-ID-tagged event acquisition, DAQ-1) - - psana (the per-shot data-analysis plane; CORA references a Dataset, does not own per-shot data) - - hutch-python / nabs (the bluesky-based scan + DAQ-run suite) - - AMI (online per-shot monitoring) - - BTPS (Beam Transport Protection System; the pump-probe optical-laser safety interlock, LASER-1) - -# Continuously-available resources a run draws on (modelling exercise). -resources: - intro: > - The continuously-available facility resources a run needs present before it can - start. All pending confirmation. The FEL beam is a shared, switched resource - (TOPO-1); its per-shot character is an acquisition concern, not a supply one. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/lix/beamline.yaml b/deployments/lix/beamline.yaml deleted file mode 100644 index cad225923fc..00000000000 --- a/deployments/lix/beamline.yaml +++ /dev/null @@ -1,354 +0,0 @@ -# LIX beamline descriptor (NSLS-II), reverse-engineered -# -# LIX (Life Science X-ray scattering) is the NSLS-II 16-ID beamline for the -# structure of biological macromolecules in solution by small- and wide-angle -# X-ray scattering (bio-SAXS / WAXS), including in-line size-exclusion -# chromatography (SEC-SAXS), and a scanning-microbeam endstation for cells and -# tissue. It is bound to the NSLS-II Site (deployments/nsls2/site.yaml). -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the beamline's own bluesky profile collection, github.com/NSLS2/ -# lix-profile-collection, its startup/components, startup/devices, and -# startup/experiments definitions) or inferred, carried new: true + confirm: true -# pending LIX staff. EPICS PVs are real and verified against the profile -# collection; vendor part numbers, serials, and physical positions are not in it -# and are open questions. The fluidic delivery chain is mostly non-EPICS -# (raw TCP sockets to a Moxa terminal server, the Agilent OpenLAB .NET SDK, and -# one pcaspy soft-IOC); it is modelled as the heterogeneous control plane the MX3 -# deployment established (interface-in-note, the soft-IOC PV where one exists). -# This scaffold is descriptor + docs, scenarios deferred. -# -# WHAT IS (AND IS NOT) NEW: LIX's small- and wide-angle scattering shares its -# science axis with the materials-scattering fleet (SMI, CMS, I22, 9-ID, 12-ID). -# What is genuinely new is the SUBJECT and the SAMPLE-DELIVERY chain, not the -# detectors: LIX is the fleet's first life-science SOLUTION-scattering beamline, -# where the specimen is a protein in liquid (often an eluting SEC peak), delivered -# by an HPLC fluidic chain rather than mounted as a solid. The beam path and -# detectors reuse the catalog throughout and coin NOTHING; the novelty lands on -# Subject (the solution sample), Supply (buffers, the SEC column, needle wash), -# and Procedure (the SEC-SAXS flow program and the sample-loading robot), plus the -# fluidic-delivery seam. -# -# MODELLING: LIX coins NO new Family and changes nothing in the catalog. 16-ID is -# an insertion-device beamline (an in-vacuum undulator), so it carries an -# InsertionDevice (unlike the bending-magnet CMS), observed alongside the loose -# StorageRing. The DCM binds Monochromator; the white-beam and KB focusing mirrors -# bind Mirror; the mono slit, secondary-source aperture, and guard slit bind Slit; -# the compound refractive lens binds the graduated Transfocator (well established -# across the fleet); the photon and fast shutters bind Shutter; the solution -# positioning stack binds the graduated Manipulator; the scanning-microbeam -# goniometer binds Goniometer; the SAXS / WAXS Pilatus detectors bind Camera; the -# Xspress3 binds the graduated EnergyDispersiveSpectrometer; the detector -# translations bind LinearStage; the beamstop binds BeamStop; the TetrAMM -# electrometers bind FluxMonitor; the diamond-diode beam-position monitor binds the -# graduated PositionMonitor Family (DIAG-1); the Zebra binds -# TimingController. -# -# 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). -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/lix/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "life-science solution scattering (bio-SAXS/WAXS, in-line SEC-SAXS) and scanning-microbeam mapping, 16-ID; the fleet's first solution beamline and fluidic sample-delivery chain; modelled from public beamline config" - name: LIX - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "16-ID" # PV zones XF:16IDA (optics) / XF:16IDB (transport) / XF:16IDC (endstation) - tier: Unit - parent: null - source: insertion-device - source_confirm: "16-ID is an in-vacuum-undulator (IVU) beamline; the profile collection fits an empirical Keff(gap) curve (a 23 mm period implied, 3 GeV ring) but does not state the device model or length. Source identity and parameters are SRC-1" - page_layout: stages - shape: "The fleet's first life-science solution-scattering beamline: the novelty is the liquid Subject and an HPLC fluidic sample-delivery chain (SEC-SAXS), not the scattering itself." - source_ref: - label: "NSLS2/lix-profile-collection" - url: "https://github.com/NSLS2/lix-profile-collection" -# PV zones: XF:16IDA (the optics hutch: the DCM, the white-beam and KB mirrors, the -# mono slit, the photon shutter), XF:16IDB (the transport hutch: the secondary-source -# aperture, the fast shutter, the upstream beam-position monitor), XF:16IDC (the -# endstation: the compound refractive lens, the guard slit, the sample stacks, the -# detectors, the fluidic delivery). Whether A / B / C are three separate hutches and -# the PSS permit leaves are open (ENC-1, PSS-1). Modelled here as two enclosures -# (optics + endstation) with the transport hutch folded into optics pending ENC-1. -enclosures: - - name: lix-optics - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf not in the profile collection (the security model in the profile collection is a POSIX-ACL login, not a PSS integration); the optics and transport zones (XF:16IDA, XF:16IDB), the hutch grouping is ENC-1 (PSS-1)"} - - name: lix-endstation - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; the solution / scanning endstation (XF:16IDC), ENC-1 (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the machine state and the optics -# =========================================================================== - -machine: - stage: source - enclosure: lix-optics - intro: "The machine-level source state, observed not driven." - note: "Observe-only NSLS-II machine state, the loose StorageRing pattern reused from the NSLS-II siblings. 16-ID has an in-vacuum undulator, modelled as an InsertionDevice in the optics group below (SRC-1, MACHINE-1)." - devices: - - name: StorageRing - family: StorageRing # loose Family (machine-level observe-only source state; MACHINE-1) - pv: {confirm: "NSLS-II storage-ring state (current, fill, status); observe-only; the ring-current PV SR:OPS-BI{DCCT:1}I:Real-I is read for beam suspenders, the rest is MACHINE-1"} - new: true - confirm: true - note: "NSLS-II storage-ring state; observe-only (MACHINE-1)" - -optics: - stage: source - enclosure: lix-optics - intro: "The in-vacuum undulator, the double-crystal monochromator and the incident-energy axis, the white-beam and KB focusing mirrors, the mono slit and secondary-source aperture, and the photon and fast shutters." - note: > - 16-ID is an undulator beamline: the IVU binds InsertionDevice and the incident - energy is a PseudoAxis over the DCM Bragg angle coupled to the undulator gap. The - mirrors bind Mirror, the slits bind Slit, the shutters bind Shutter. Everything - here reuses the catalog and coins nothing. - devices: - - name: Undulator - family: InsertionDevice - pv: "SR:C16-ID:G1{IVU:1-Ax:Gap}-Mtr" - new: true - confirm: true - note: "the in-vacuum undulator: a gap motor (plus brake-disengage interlock signals); the gap-to-energy lookup is an empirical Keff(gap) fit; the device model, period, and length are SRC-1" - - name: Monochromator - family: Monochromator - pv: "XF:16IDA-OP{Mono:DCM-Ax:Bragg}Mtr" - new: true - confirm: true - note: "the double-crystal monochromator (DCM): Bragg angle sets the energy, with second-crystal pitch / roll / offset and a fine-pitch feedback axis; a silicon crystal (lattice constant a = 5.431 angstrom, the energy law's 2/sqrt(3) factor implying the Si(111) reflection), MONO-1" - - name: BeamEnergy - family: PseudoAxis - pv: {confirm: "the incident-energy virtual axis over the DCM Bragg angle coupled to the undulator gap (lambda = 2 d sin(Bragg)); the partition rule and crystal cut are MONO-1"} - new: true - confirm: true - note: "incident-energy pseudo-axis over the DCM Bragg angle and the undulator gap (MONO-1)" - - name: WhiteBeamMirror - family: Mirror - pv: "XF:16IDA-OP{Mir:WBM-Ax:P}Mtr" - new: true - confirm: true - note: "the white-beam mirror (x / y / pitch) taking the heat load and rejecting harmonics; coating is OPT-1" - - name: KbMirror - family: Mirror - pv: "XF:16IDA-OP{Mir:KBH-Ax:YU}Mtr" - new: true - confirm: true - note: "the Kirkpatrick-Baez focusing pair (a horizontal mirror KBH and a vertical mirror KBV, each on tip / tilt / bend); one Asset for the pair at this cut; whether the mirrors are bimorph and their coatings are OPT-1" - - name: MonoSlit - family: Slit - pv: "XF:16IDA-OP{Slt:1-Ax:T}Mtr" - new: true - confirm: true - note: "the mono four-blade defining slit (T / B / O / I); blade-axis map is OPT-2" - - name: SecondarySourceAperture - family: Slit - pv: "XF:16IDB-OP{Slt:SSA1-Ax:T}Mtr" - new: true - confirm: true - note: "the secondary-source aperture in the transport zone (XF:16IDB), defining the focused source size (OPT-2)" - - name: PhotonShutter - family: Shutter - pv: "XF:16IDA-PPS{PSh}Enbl-Sts" - new: true - confirm: true - note: "the personnel-protection photon shutter; only the enable-status leaf is in the profile collection, the front-end shutter and the search-and-secure leaves are PSS-1" - - name: FastShutter - family: Shutter - pv: "XF:16IDB-BI{shutter:1}sts" - new: true - confirm: true - note: "the millisecond fast shutter on its own translation stage, gating the exposure; it is driven by a TTL pulse from the timing seam (the Zebra / XPS), the exposure-timing seam (TRIG-1)" - -focusing: - stage: source - enclosure: lix-endstation - intro: "The endstation-zone focusing and beam-defining optics: the compound refractive lens transfocator, the divergence-defining aperture, and the guard slit." - note: > - These optics sit in the endstation zone (XF:16IDC) but condition the beam, so they - are part of the source stage. The compound refractive lens binds the graduated - Transfocator Family (a well-established graduated optic across the fleet); the - divergence-defining aperture and the guard slit each bind Slit. - devices: - - name: Transfocator - family: Transfocator - pv: "XF:16IDC-OP{CRL-Ax:Z}Mtr" - new: true - confirm: true - note: "the compound refractive lens (CRL) transfocator: a z translation plus upstream / downstream x / y alignment, with nine selectable lens groups (per-group in / out and a busy flag) setting the focal length; reuses the graduated Transfocator Family (also bound by the NSLS-II siblings CHX / IXS / SMI / FMX and the APS / Diamond CRLs); the lens-group configuration is CRL-1" - - name: DivergenceAperture - family: Slit - pv: "XF:16IDC-OP{Slt:DDA-Ax:X}Mtr" - new: true - confirm: true - note: "the divergence-defining aperture (center / gap) setting the beam divergence at the endstation (OPT-2)" - - name: GuardSlit - family: Slit - pv: "XF:16IDC-OP{Slt:G2-Ax:X}Mtr" - new: true - confirm: true - note: "the endstation guard slit (center / gap) cleaning up parasitic scatter before the sample; the upstream Slt:G1 is disabled in the profile collection (OPT-2)" - -# =========================================================================== -# SAMPLE STAGE: the solution and scanning sample stacks, and the fluidic -# delivery pump (the SEC-SAXS chain; valves / column / cell / robot are the -# fluidic-delivery seam, see controls) -# =========================================================================== - -sample: - stage: sample - enclosure: lix-endstation - intro: "The solution-sample positioning stack and the scanning-microbeam goniometer, and the HPLC delivery pump that feeds the solution flow cell." - note: > - LIX runs two endstation modes, selected at startup. The solution mode positions a - flow cell on a translation stack (the Manipulator); the scanning-microbeam mode - 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 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: - - name: SampleStage - family: Manipulator - pv: "XF:16IDC-ES:Scan{Ax:XC}Mtr" - new: true - confirm: true - note: "the solution-mode positioning stack: a coarse x and a z pusher (EPICS), plus the fast scan x / y carried as Newport-XPS trajectory axes; reuses the graduated Manipulator Family; the flow cell it positions is the fluidic seam (SAMPLE-1, FLUID-1)" - - name: ScanningGoniometer - family: Goniometer - pv: "XF:16IDC-ES:Scan2-Gonio{Ax:sX}Mtr" - new: true - 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 # 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 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 -# spectrometer, the detector translations, the beamstop, the flux and -# beam-position monitors, and the Zebra trigger -# =========================================================================== - -detection: - stage: detection - enclosure: lix-endstation - intro: "The SAXS and WAXS Pilatus area detectors, the scanning-mode fluorescence spectrometer, the detector translations, the beamstop, the endstation flux and beam-position monitors, and the Zebra triggering." - note: > - The Pilatus area detectors bind Camera; the Xspress3 fluorescence detector binds - the graduated EnergyDispersiveSpectrometer; the detector translations bind - LinearStage; the beamstop binds BeamStop; the TetrAMM electrometers bind - FluxMonitor; the diamond-diode / Best beam-position monitor binds the graduated - PositionMonitor Family (DIAG-1); the Zebra binds TimingController. - devices: - - name: SaxsDetector - family: Camera - pv: "XF:16IDC-DT{Det:SAXS}" - new: true - confirm: true - note: "the Pilatus 1M small-angle (SAXS) area detector, the primary scattering detector; the model size and the detector-distance calibration are DET-1" - - name: WaxsDetector - family: Camera - pv: "XF:16IDC-DT{Det:WAXS2}" - new: true - confirm: true - note: "the Pilatus 900K wide-angle (WAXS) area detector; the third Pilatus (a 300K WAXS1) is disabled in the profile collection and not modelled (DET-1)" - - name: FluorescenceDetector - family: EnergyDispersiveSpectrometer - pv: "XF:16IDC-ES{Xsp:1}:" - new: true - confirm: true - note: "the Xspress3 multi-channel fluorescence detector, used in the scanning-microbeam mode for element mapping; reuses the graduated Family; it is optional in the profile collection (initialized in a try / except), so per-run availability is DET-1" - - name: DetectorStage - family: LinearStage - pv: "XF:16IDC-ES{Stg:SAXS-Ax:X}Mtr" - new: true - confirm: true - note: "the SAXS / WAXS detector translations (Stg:SAXS / WAXS1 / WAXS2 x / y / z) and the sample-to-detector distance motor; detector positions are calibration (DET-1)" - - name: Beamstop - family: BeamStop - pv: "XF:16IDC-ES{BS:SAXS-Ax:X}Mtr" - new: true - confirm: true - note: "the SAXS beamstop (x / y) in front of the area detector; no separate beamstop diode is in the profile collection, the direct-beam intensity is read off the detector (DET-1)" - - name: EndstationFluxMonitor - family: FluxMonitor - pv: "XF:16IDC-BI{BPM:1}" - new: true - confirm: true - note: "the endstation TetrAMM electrometers (BPM:1 / BPM:2) and an upstream NSLS-II electrometer reading incident and transmitted flux for normalization; scalar readings, the channel map is DET-1" - - name: BeamPositionMonitor - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1) - pv: "XF:16IDB-CT{Best}:BPM0:PosX_Mean" - new: true - confirm: true - note: "the Best beam-position aggregator deriving beam x / y from the TetrAMM quadrant currents; binds the graduated PositionMonitor Family (DIAG-1); the position-vs-intensity split is DIAG-1" - - name: Trigger - family: TimingController - pv: "XF:16IDC-ES{Zeb:1}:" - new: true - confirm: true - note: "the Zebra box generating detector triggers (a soft-input pulse SOFT_IN:B0 and position-capture for fly scans), gated from the Newport XPS; the exposure-timing seam (TRIG-1)" - -# Cross-cutting control. LIX runs EPICS plus a heterogeneous fluidic control plane; -# CORA observes the floor and, where it replaces bluesky-style orchestration, -# conducts over it. The handles above were read from the profile collection and -# carried confirm (CTRL-1). -controls: - intro: > - LIX runs on the NSLS-II EPICS / ophyd control stack, the same floor as FXI, HXN, - SRX, BMM, SIX, CHX, ESM, SMI, and CMS, plus a heterogeneous fluidic control plane - on a separate HPLC cart. The EPICS device handles above are bound from the - beamline's bluesky profile collection (github.com/NSLS2/lix-profile-collection, - its startup/components and startup/devices files), carried confirm (CTRL-1). Motion - is driven by a Newport XPS trajectory controller (the fast scan and tomo axes), a - SmarAct controller (the scanning goniometer), and Delta-Tau racks; the Zebra - generates detector triggers gated from the XPS (TRIG-1). The acquisition (the - SAXS / WAXS exposures, the scanning-microbeam raster, the SEC-SAXS flow program) - runs through bluesky plans publishing to Kafka with metadata in Redis; that - orchestration is the seam CORA's edge replaces, driving through ophyd / EPICS. - The area-detector file-writing to the NSLS-II filestore is plumbing CORA observes, - not data it owns (see model.md). - # 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 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: - - "XF:16IDC-ES{HPLC}: the pcaspy coordination soft-IOC fronting the Agilent OpenLAB .NET SDK (the quaternary pump, the autosampler) and the regeneration pump; its run-control PVs (START_RUN, SAMPLE_NAME, HPLCRunStatus, Buffer_VALVE_POS) are the SEC-SAXS orchestration seam (FLUID-1)" - - "VICI selector valves (Moxa TCP sockets, no EPICS): the ten-port column-selection valve and the purge / detector valves; discrete N-position routers with no existing Family, carried in the seam, not coined (FLUID-1)" - - "Aurora Pro buffer valve (serial over a Moxa socket): the six-position buffer-selection valve, its chosen position mirrored into the soft-IOC (Buffer_VALVE_POS), the rest the seam (FLUID-1)" - - "EM_Robot (SW: method soft-IOC) and the Agilent autosampler: the sample-handling robot (task-verb-driven like the i03 / MX3 robot) and the autosampler, modelled as a Procedure over the spine and a Subject custody thread, not a device Family (ROBOT-1)" - - "the SEC column, buffers, needle wash, and the X-ray flow cell: the column and buffers are Supply consumables, the flow cell lives in an external library (lixtools), and the solution sample is a Subject (SEC-1, SUBJECT-1, FLUID-1)" - - "the FTC100D temperature controller and the SMC chiller (Moxa TCP sockets): the sample-cell temperature controllers; their module-level instances in 50-Tctrl.py are commented out, so this is a scope deferral rather than a clean absence, plus the autosampler thermostatted-tray temperature (SAMPLER:TEMP); the in-situ sample-temperature environment is TEMP-1" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a LIX run needs, plus the bio-SAXS - consumables. The optics and the SAXS flight path run under vacuum (SUP-1). The - solution chain draws on buffers, a size-exclusion column, and needle wash as - Supply consumables, distinct from the facility-wide supplies (SEC-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the optics and the SAXS flight path run under vacuum (SUP-1)" diff --git a/deployments/manaca/beamline.yaml b/deployments/manaca/beamline.yaml deleted file mode 100644 index 77ac8dac071..00000000000 --- a/deployments/manaca/beamline.yaml +++ /dev/null @@ -1,214 +0,0 @@ -# MANACA beamline descriptor (Sirius / LNLS), reverse-engineered, design phase -# -# MANACA is Sirius's macromolecular-crystallography beamline (Campinas, Brazil): -# rotation (oscillation) MX on a goniometer reading an area detector, with an -# automated 48-pin sample changer for high-throughput collection, supporting serial -# and room-temperature MX. It is bound to the Sirius Site -# (deployments/sirius/site.yaml); it is the SECOND Sirius beamline CORA models (after -# the MOGNO tomography scaffold) and Sirius's FIRST macromolecular-crystallography -# beamline. -# -# STATUS: reverse-engineered, design / commissioning phase. Every value is read from -# Sirius's public facility pages (lnls.cnpem.br/facilities/manaca) and the MX device -# anatomy shared with i03 / FMX / AMX / MX3, or inferred; each device -# carries new: true (not yet modelled in CORA) and confirm: true (value to be -# verified by LNLS staff). Control handles are OMITTED on purpose: Sirius is EPICS at -# the device floor, and MANACA drives MXCuBE3 for the MX experiment, but no public -# per-beamline PV manifest exists for MANACA, so no `pv` field is invented (the FAXTOR -# handles-omitted-pending precedent). Vendor part numbers and the exact detector model -# are not published, carried pending. -# -# WHAT IS NEW: a new beamline at an existing Site, no new vocabulary. -# - Sirius's FIRST macromolecular-crystallography beamline (its MOGNO sibling is -# tomography), re-using the MX vocabulary graduated at i03 and exercised at -# FMX / AMX / MX3 on a new control plane (EPICS floor + MXCuBE3). -# - MANACA coins NO new Family and changes nothing in the catalog: the goniometer -# reuses the graduated Goniometer family (the i03 MX precedent), the detector -# Camera, the monochromator Monochromator, the cryostream TemperatureController, -# the attenuator Filter, the beamstop BeamStop, the shutters Shutter; the machine -# state binds the supply-loose StorageRing. The 48-pin sample changer is modelled -# as a deferred Procedure (sample exchange), not a device family (the i03 / i24 / -# MX3 ROBOT-1 precedent). -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/manaca/questions.md. - -beamline: - maturity: model - evidence: narrative - coverage: full - summary: "macromolecular crystallography (rotation MX, serial and room-temperature) on a goniometer + area detector with a 48-pin sample changer; Sirius's first MX beamline, reuses the i03 / FMX / AMX / MX3 Goniometer and MX Methods on the EPICS floor + MXCuBE3, no new Family" - name: MANACA - facility: sirius # Sirius Site (facility_code: sirius) - sector: "MANACA" - tier: Unit - parent: null - source: insertion-device - source_confirm: "MANACA is an undulator beamline (5-20 keV); the insertion-device period and parameters are not published, carried pending (SRC-1)" - page_layout: stages - shape: "Sirius's first macromolecular-crystallography beamline: rotation MX on a goniometer and area detector with a 48-pin sample changer, reusing the fleet MX vocabulary on the Sirius EPICS floor." - source_ref: - label: "lnls.cnpem.br facility page" - url: "https://lnls.cnpem.br/facilities/manaca/" - -enclosures: - # The public sources expose no per-beamline hutch layout or PSS permit leaves. - # Modelled as the optics hutch + the experiment hutch; the hutch names and the PSS - # permit signals are a staff question (ENC-1, PSS-1). - - name: manaca-optics - role: optics-hutch - facility_code: sirius - permit_signal: {confirm: "Sirius PSS permit leaf not published per beamline (PSS-1, ENC-1)"} - - name: manaca-experiment - role: experiment-hutch - facility_code: sirius - permit_signal: {confirm: "Sirius PSS permit leaf not published; the experiment hutch carries the goniometer, the detector, and the sample changer (PSS-1, ENC-1)"} - -# =========================================================================== -# SOURCE STAGE: the machine state and the front-end shutter -# =========================================================================== - -source: - stage: source - enclosure: manaca-optics - intro: "The machine-level source state, observed not driven, and the front-end photon shutter. The insertion-device source itself is not published per beamline (SRC-1)." - note: "The Sirius 3 GeV storage-ring state, the loose StorageRing pattern reused across the fleet (MACHINE-1)." - devices: - - name: StorageRing - family: StorageRing # loose Family (machine-level observe-only source state; MACHINE-1) - new: true - confirm: true - note: "Sirius 3 GeV storage-ring state (current, fill); observe-only, the exact handles are MACHINE-1" - - name: WhiteBeamShutter - family: Shutter - new: true - confirm: true - note: "front-end photon shutter (a PSS shutter); handles not published per beamline (PSS-1)" - -# =========================================================================== -# OPTICS STAGE: the monochromator, the energy axis, the attenuators -# =========================================================================== - -optics: - stage: source - enclosure: manaca-optics - intro: "Set the energy and condition the beam: the monochromator, the master energy axis, and the attenuator / transmission unit. 5-20 keV operating range. No standalone mirror or slit device is published (OPT-1)." - devices: - - name: Monochromator - family: Monochromator - new: true - confirm: true - note: "the MANACA monochromator setting the incident energy (5-20 keV); crystal / multilayer detail and handles pending (MONO-1)" - - name: EnergyAxis - family: PseudoAxis - new: true - confirm: true - note: "the master beamline energy axis the monochromator tracks; whether energy is scanned as the measurement (anomalous MX) is ENERGY-1" - - name: Attenuators - family: Filter - new: true - confirm: true - note: "the attenuator / transmission unit trimming the incident flux; foil set pending (FILT-1)" - -# =========================================================================== -# SAMPLE STAGE: the goniometer, the cryostream, the backlight, the beamstop -# =========================================================================== - -sample: - stage: sample - enclosure: manaca-experiment - intro: "The goniometer that holds and orients the crystal, the cryostream sample cooling, the on-axis backlight, and the beamstop. Supports serial and room-temperature MX." - note: > - MANACA holds a crystal on the goniometer and rotates it through an oscillation - while the area detector reads frames. The goniometer reuses the graduated - Goniometer family (the i03 MX precedent, exercised at FMX / AMX / MX3). The 48-pin - sample changer is modelled as a deferred Procedure (sample exchange), not a device - family, per the i03 / i24 / MX3 ROBOT-1 precedent. - devices: - - name: Goniometer - family: Goniometer - new: true - confirm: true - note: "the MANACA goniometer: omega rotation plus sample centring and alignment, supporting serial / room-temperature MX. Reuses the graduated Goniometer family; axis set and handles pending (GONIO-1)" - - name: SampleTemperature - family: TemperatureController - new: true - confirm: true - note: "the cryostream sample cooling. Reuses the graduated TemperatureController family; handles pending (TEMP-1)" - - name: Backlight - family: Backlight # catalog Family (DET-1) - new: true - confirm: true - note: "the on-axis sample backlight / frontlight for viewing and centring. Binds the catalog Backlight Family (graduated across the MX / imaging fleet, DET-1)" - - name: BeamStop - family: BeamStop - new: true - confirm: true - note: "the beamstop blocking the direct beam at the sample. Reuses BeamStop; handles pending (SAMPLE-1)" - -# =========================================================================== -# DETECTION STAGE: the area detector, its stage, the on-axis viewing camera, flux -# =========================================================================== - -detector: - stage: detection - enclosure: manaca-experiment - intro: "The area detector and its translation stage, the on-axis viewing camera for centring, and the incident-flux monitor. The detector model is not published, carried pending (DET-1)." - devices: - - name: AreaDetector - family: Camera - new: true - confirm: true - note: "the MX area detector reading the rotation frames; sensor and vendor model not published (a Pilatus / Eiger-class photon-counting detector), carried pending (DET-1). Reuses Camera" - - name: DetectorStage - family: LinearStage - new: true - confirm: true - note: "the detector translation setting the sample-to-detector distance; handles pending (DET-1)" - - name: FluxMonitor - family: FluxMonitor - new: true - confirm: true - note: "the incident-flux monitor. Reuses the graduated FluxMonitor family; handles pending (DIAG-1)" - - name: OnAxisCamera - family: Camera - new: true - confirm: true - note: "the on-axis viewing camera for sample centring. Reuses Camera; handles pending (DET-1)" - -# =========================================================================== -# Cross-cutting controls -# =========================================================================== - -controls: - intro: > - MANACA runs on the Sirius control stack: EPICS at the device-IO floor, with MXCuBE3 / - MXCuBE Web as the MX experiment UI driving the goniometer, detector, and sample - changer. Sirius has named Bluesky / Ophyd (the LNLS "sophys" family) as a facility - orchestration direction (its MOGNO sibling records the same migration question), but - whether MANACA runs it is not public (ORCH-1). No public per-beamline PV manifest is - published, so the EPICS handles are not bound here, carried pending staff verification - (CTRL-1); when bound they would be modelled as opaque edge handles over the - ControlPort. The rotation-MX acquisition (the oscillation, the detector triggering, the - sample-changer load / centre / collect loop) runs through MXCuBE and the beamline - orchestration layer; that orchestration is the seam CORA's edge replaces or drives - through, conducting over the EPICS floor rather than owning it. The detector - file-writing to the Sirius data store is plumbing CORA observes, not data it owns (see - model.md). - triggering: - - name: MonoBeamShutter - family: Shutter - new: true - confirm: true - note: "the mono-beam shutter gating the conditioned beam into the experiment hutch, plus a fast shutter gating the per-oscillation exposure; handles pending (PSS-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a MANACA run needs present before it - can start. All carried pending confirmation (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: LiquidNitrogen # cryostream diff --git a/deployments/maxiv/site.yaml b/deployments/maxiv/site.yaml deleted file mode 100644 index 595fe6b3ade..00000000000 --- a/deployments/maxiv/site.yaml +++ /dev/null @@ -1,59 +0,0 @@ -# CORA Site descriptor: the MAX IV site-level surface -# -# MAX IV (Lund, Sweden) is the second Site CORA models, and the home of the -# planned TomoWISE beamline. 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. -# -# Status: MAX IV / TomoWISE is in the design phase. Almost everything below is a -# design-phase intent carried as `pending`, not an operating fact. Concrete -# facility details (safety forms, supply names, the operator pool) are deferred -# to the TomoWISE open questions until MAX IV staff confirm them. Do not invent -# facility specifics here; carry them as questions. -# -# Source-of-truth boundary (same as the APS site): -# - the closed facility-kind / actor-kind vocabularies are validated against -# code-mirrored frozensets in scripts/site_descriptor.py. -# - the facility records the bootstrap invariants (kind=Site, display_name -# equals code); `heading` carries the human title used on the rendered page. - -facility: - code: maxiv - display_name: maxiv - heading: "MAX IV" - kind: Site - institution: MAX IV Laboratory, Lund University - control_plane: "Tango / Sardana" - beamlines: [TomoWISE] - -# ISA-88 Site Recipes: the facility-adapted form of a catalog Method. All -# pending in the design phase; each names the cross-facility Method it would -# adapt. Confirm with MAX IV staff before any becomes active. -practices: - - {name: TomoWISE_microtomography_practice, method: tomography, pending: true, note: "microtomography endstation"} - - {name: TomoWISE_nanotomography_practice, method: tomography, pending: true, note: "nanotomography endstation (KB-focused)"} - - {name: TomoWISE_laminography_practice, method: tomography, pending: true, note: "laminography tilt on the microtomography endstation"} - -# Access BC Actors conceptually facility-wide at MAX IV. Pending until the -# MAX IV operator and review structure is confirmed. -actors: - - {name: MAX IV beamline staff, kind: human, pending: true, note: "operator and beamline-scientist pool; structure TBD"} - - {name: MAX IV safety review, kind: human, pending: true, note: "facility safety review body; membership TBD"} - -# Agent BC Agents seeded at this deployment. None declared: the CORA system -# agents are not yet wired for a MAX IV deployment, and TomoWISE is pre-build. -agents: [] - -# Supply BC: facility-wide continuously-available resources. Pending in design. -supplies: - - {name: Storage-ring beam current, kind: PhotonBeam, pending: true} - - {name: Cooling water, kind: CoolingWater, pending: true} - - {name: Beamline vacuum, kind: Vacuum, pending: true} - -# Safety BC: facility-issued Clearances. MAX IV safety-form names are not yet -# confirmed; carried pending with a note rather than guessed. -clearances: - - {name: MAX IV personal safety system, kind: PSS, pending: true, note: "facility safety-form names TBD; confirm with MAX IV staff"} - -# Caution BC: operator tribal knowledge. None yet for a pre-build facility. -cautions: [] diff --git a/deployments/mogno/beamline.yaml b/deployments/mogno/beamline.yaml deleted file mode 100644 index ab45bbb484c..00000000000 --- a/deployments/mogno/beamline.yaml +++ /dev/null @@ -1,226 +0,0 @@ -# CORA Beamline descriptor: MOGNO (Sirius), reverse-engineered from papers -# -# MOGNO is the X-ray micro and nanotomography beamline at Sirius (LNLS / CNPEM), -# a cone-beam, phase-contrast, time-resolved (4D) tomography instrument. It is -# bound to the Sirius Site (deployments/sirius/site.yaml). -# -# STATUS: reverse-engineered, not staff-confirmed, and thinner than the other -# reverse-engineered beamlines. Unlike FXI (built from a public bluesky profile -# collection with real EPICS PVs), MOGNO has NO public controls config: its facts -# come from two published papers and the facility page: -# - Campoi et al. 2025, "Software architecture at Sirius' MOGNO beamline, towards -# a web-based system", J. Phys.: Conf. Ser. 3010 012137 (the software paper). -# - Archilha et al. 2022, "The MOGNO beamline", J. Phys.: Conf. Ser. 2380 012123 -# (the hardware paper). -# - https://lnls.cnpem.br/facilities/mogno/ (the facility page). -# So this descriptor is design-fact mode (the TomoWISE shape): devices bind to -# catalog Families only, every device carries `new: true` and `confirm: true`, NO -# `pv` field is invented, and NO vendor `model` is bound. Device part-numbers the -# facility page names are carried as model_target notes, not bindings. -# -# Items to verify with MOGNO staff are tagged inline with a (QUESTION-ID) answered -# on docs/deployments/mogno/questions.md. -# -# The orchestration seam (see docs/deployments/mogno/equipment/controls.md): MOGNO -# runs a beamline-owned CUSTOM EPICS stack (mgn-devices / mgn-routines / -# mgn-control-guis over PyEpics, with a TATU FPGA trigger), NOT Bluesky/sophys. -# That custom routine layer is the orchestration CORA's edge would conduct over -# the EPICS floor; Bluesky is a future migration target at the beamline (ORCH-1). - -beamline: - maturity: model - evidence: narrative - coverage: partial - summary: "cone-beam X-ray micro and nanotomography (phase-contrast, time-resolved 4D) across two stations; reuses the 2-BM / FXI tomography vocabulary, novelty is the Site and the fleet's first custom-Python (non-Bluesky) orchestration layer" - name: MOGNO - facility: sirius - tier: Unit - parent: null - source: bending-magnet - source_confirm: "a 3.2 T dipole / superbend source (the hardware paper calls it a permanent-magnet dipole, the facility page a superbend); critical energy ~19 keV. Exact source type and parameters pending (SRC-1)." - page_layout: stages - shape: "The fleet's first South American facility (Sirius): cone-beam X-ray nano- and micro-tomography across two endstations on a beamline-owned PyEpics stack, reusing the tomography spine." - source_ref: - label: "lnls.cnpem.br facility page" - url: "https://lnls.cnpem.br/facilities/mogno/" - -# Two endstations, each its own access-gated experiment area: the nanotomography -# station (elliptical-mirror nanofocus) and the microtomography station (large -# field of view). The optics are shared upstream. PSS permit leaves are not -# public (PSS-1). -enclosures: - - name: mogno-nano - role: experiment-hutch - facility_code: sirius - permit_signal: {confirm: "Sirius PSS permit signal TBD (PSS-1)"} - - name: mogno-micro - role: experiment-hutch - facility_code: sirius - permit_signal: {confirm: "Sirius PSS permit signal TBD (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the beam delivery and conditioning shared by both stations -# =========================================================================== - -source: - stage: source - enclosure: mogno-nano - intro: "The dipole source delivering a quasi-monochromatic cone beam to the two tomography stations." - note: > - The source is a 3.2 T dipole / superbend with a critical energy near 19 keV. - The beam is quasi-monochromatic (dE/E ~ 1e-2) at three working energies; the - hardware paper gives 21.5 / 39.0 / 67.7 keV and the facility page rounds to - 22 / 39 / 67.5 keV (SRC-2). Recorded as a Supply (PhotonBeam) at the Site, - identity-only here. - devices: - - name: Source - family: InsertionDevice - new: true - confirm: true - note: "Sirius dipole / superbend source feeding MOGNO. Type (permanent-magnet dipole vs superbend), field, and the energy-selection mechanism are not in public sources (SRC-1)." - - name: StorageRing - family: StorageRing - new: true - confirm: true - note: "Sirius 3 GeV ring state, observe-only; a loose StorageRing reused across the fleet. Exact machine-state read pending (MACHINE-1)." - -optics: - stage: source - enclosure: mogno-nano - intro: "Condition and focus the beam. A set of elliptical mirrors demagnifies the source to the nanofocus, with beam-defining slits." - note: > - The optics are carried at Family granularity only; the public sources describe - the focusing optics qualitatively, not by handle. The nanotomography station - uses a set of (reported) three elliptical mirrors demagnifying to a ~120 nm - focus (hardware paper) / KB-style multicoated mirrors reaching ~100 x 100 nm - (facility page) (OPT-1). - devices: - - name: FocusingMirror - family: Mirror - new: true - confirm: true - note: "Elliptical / KB-style focusing mirrors demagnifying the source to the nanofocus (~100-120 nm). Count, coatings, geometry, and handles pending (OPT-1)." - - name: BeamSlit - family: Slit - new: true - confirm: true - note: "Beam-defining slits. Blade-axis map and handles not in public sources (OPT-2)." - -# =========================================================================== -# SAMPLE STAGE: the two tomography endstations -# =========================================================================== - -nanotomography-endstation: - stage: sample - enclosure: mogno-nano - intro: "The nanotomography station: the rotation axis and a fine three-axis sample positioner at the elliptical-mirror nanofocus, for ~120 nm to micron-scale cone-beam tomography." - note: > - The software paper names device classes (a three-axis fine-movement 'tripod' - and motor+AsynRecord scannable stages) but no part numbers or handles. The - rotation stage is the master clock for hardware-triggered acquisition (STAGE-1). - devices: - - name: SampleRotary - family: RotaryStage - new: true - confirm: true - note: "The tomographic rotation axis; the scannable driven during a tomogram (projections over rotation). Model, encoder, and handle pending (STAGE-1)." - - name: SampleTripod - family: LinearStage - new: true - confirm: true - note: "Three-axis fine sample positioner (the piezo 'tripod' in the software paper); centring and alignment. Axis set is a per-Asset setting; model and handles pending (STAGE-2)." - -microtomography-endstation: - stage: sample - enclosure: mogno-micro - intro: "The microtomography station: a rotation axis and sample positioner for large-field-of-view cone-beam tomography (field of view to tens of millimetres), conceptually similar to the nano station at coarser resolution." - note: > - The two stations span ~120 nm to ~55 um resolution and ~150 um to ~85 mm field - of view (hardware paper). The micro-station device handles are not separately - given in the public sources; modelled at Family granularity, pending (STAGE-3). - devices: - - name: MicroSampleRotary - family: RotaryStage - new: true - confirm: true - note: "Microtomography rotation axis; the master clock for the micro-station triggered acquisition. Model and handle pending (STAGE-3)." - - name: MicroSampleStage - family: LinearStage - new: true - confirm: true - note: "Microtomography sample positioner. Axis set, model, and handles pending (STAGE-3)." - -# =========================================================================== -# DETECTION STAGE: the detector chain serving the two stations -# =========================================================================== - -detector: - stage: detection - enclosure: mogno-micro - intro: "The detectors converting and recording the transmitted cone beam: a high-Z photon-counting detector and an indirect scintillator-coupled sCMOS chain, plus the cone-beam magnification axis." - note: > - The software paper refers only to a generic AreaDetector; the facility page - names specific models (CAM-1). MOGNO uses a high-Z photon-counting detector - (Pimega, Si, in-house) and an indirect chain (a scintillator + sCMOS, e.g. a - PCO Edge behind a LuAG:Ce scintillator with an Optique Peter microscope), with - a CdTe Medipix/Mobipix option. The per-station detector pairing is uncertain - in public sources (CAM-1); modelled as one detector position until staff - confirm which detectors are installed and active, the FXI multi-camera - precedent. - devices: - - name: Camera - family: Camera - new: true - confirm: true - note: "The imaging detector. Roster from the facility page: Pimega (Si, photon-counting, ~1536x1536, 55 um pixel, in-house/PiTec); PCO Edge 4.2 sCMOS; Medipix/Mobipix CdTe. Which are installed per station, and their configurations, pending (CAM-1). Vendor models not bound (model_target only)." - - name: Scintillator - family: Scintillator - new: true - confirm: true - note: "Scintillator for the indirect detection chain (e.g. LuAG:Ce) coupled to the sCMOS via an Optique Peter microscope. Material, thickness, and the microscope objective set pending (CAM-2)." - - name: Magnification - family: PseudoAxis - new: true - confirm: true - note: "Cone-beam geometric magnification, set by the sample position along the diverging cone between secondary source and detector (the 'zoom' tomography axis). A virtual axis over the sample and detector distances; rule pending (MAG-1). The FXI Magnification precedent." - -# =========================================================================== -# Cross-cutting controls -# =========================================================================== - -# MOGNO runs a beamline-owned custom EPICS application stack, NOT Bluesky/sophys. -# The motion controllers and detector IOCs are recorded as Families only: the -# controller boxes and PV namespaces are not in public open source (CTRL-1). -controls: - intro: > - The trigger hardware and the drive electronics. MOGNO's control floor is EPICS - IOCs plus TATU (an FPGA trigger/timer on CompactRIO, shared Sirius infra). The - application layer above it is the beamline's custom PyEpics stack (mgn-devices / - mgn-routines / mgn-control-guis), the orchestration CORA's edge would conduct - over (ORCH-1). PV namespaces and controller-box identities are not public (CTRL-1). - triggering: - - name: TATU - family: TimingController - new: true - confirm: true - note: "FPGA-based trigger and timer unit on CompactRIO (Piton et al., ICALEPCS 2021), exposing EPICS PVs via the LNLS Nheengatu layer; hardware-triggers the rotation-synchronised projection acquisition. The 2-BM softGlueZynq / FXI Zebra precedent. Handles pending (CTRL-1)." - motion_controllers: - - name: SampleMotionController - family: MotionController - new: true - confirm: true - note: "Drives the sample-side stages (rotation, tripod, micro-station). Box model, protocol, and PV namespace not in public sources (CTRL-1)." - software_iocs_not_modeled: - # Software processes / packages referenced by the papers, never registered as - # Assets: the beamline-owned custom EPICS application stack, plus the ssc-raft - # reconstruction library on the HPC cluster. - [mgn-devices, mgn-routines, mgn-control-guis, ssc-raft, TATU-IOC, areaDetector] - -resources: - intro: > - Continuously-available resources (the Supply BC). Facility-scope supplies live - in deployments/sirius/site.yaml. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/mx3/beamline.yaml b/deployments/mx3/beamline.yaml deleted file mode 100644 index 96718faa70d..00000000000 --- a/deployments/mx3/beamline.yaml +++ /dev/null @@ -1,222 +0,0 @@ -# MX3 beamline descriptor (Australian Synchrotron), reverse-engineered -# -# MX3 is the Australian Synchrotron macromolecular-crystallography beamline: rotation -# (oscillation) MX on an MD3 microdiffractometer goniometer reading a DECTRIS Eiger, -# with an ISARA robot mounting samples from a dewar for unattended high-throughput -# collection. It is bound to the Australian Synchrotron Site (deployments/as/site.yaml), -# CORA's sixth Site and first Australian facility. It is understood to be an undulator -# beamline, but the source is not in the device library (SRC-1), so the descriptor -# carries the source generically. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the AustralianSynchrotron/mx3-beamline-library device library) or inferred, -# carried `confirm: true` pending Australian Synchrotron staff. EPICS PVs are real and -# verified against the device modules; the MD3, the Eiger, and the ISARA robot are NOT -# on EPICS (see below); vendor part numbers, serials, and physical positions are not in -# the library and are open questions. -# -# THE DISTINCTIVE FACT (a new controls house-style): MX3 is EPICS-PV-bound for most -# devices (literal in-code PVs, the ring at SR11*, the beamline at MX3*), but it drives -# THREE first-class non-EPICS control planes: the MD3 microdiffractometer goniometer -# over the MXCuBE Exporter protocol (TCP), the DECTRIS Eiger over the SIMPLON REST API, -# and the ISARA robot over a TCP client library. Those three devices carry no EPICS PV; -# their note records the control interface, and the concrete host / endpoint is -# deployment config, not a baked value. This heterogeneous control plane is the seam -# story (equipment/controls.md). -# -# It introduces NO new catalog family: the MD3 goniometer reuses the graduated -# Goniometer family (the i03 MX precedent), the DECTRIS Eiger and the OAV camera Camera, -# the DMM Monochromator, the cryojet TemperatureController, the attenuator Filter, the -# flux monitor FluxMonitor, the beamstop BeamStop, the shutters Shutter. Two loose -# families are reused (all allowlisted): StorageRing (the ring-current monitor) and -# PositionMonitor (the beam-steering BPM). The MD3 backlight binds the catalog -# Backlight Family (graduated across the MX / imaging fleet, DET-1). The -# ISARA robot is modelled as a deferred Procedure (sample exchange), not a device family -# (the i03 / i24 ROBOT-1 precedent). No Capability or Method is coined; the rotation-MX -# techniques reuse the pending i03 Methods (mx_data_collection / grid_scan / -# sample_exchange) recorded as Practices on the Site. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "macromolecular crystallography (rotation MX) on an MD3 microdiffractometer + DECTRIS Eiger with an ISARA robot; reuses the i03 Goniometer and MX Methods, novelty is the Site and its heterogeneous control plane" - name: MX3 - facility: as # Australian Synchrotron Site (facility_code: as) - sector: "MX3" # PV namespace MX3* (storage ring at SR11*) - tier: Unit - parent: null - source: insertion-device - source_confirm: "MX3 is an undulator beamline, but the insertion-device / front-end source PV is not in the device library; only the storage-ring current monitor (SR11BCM01:CURRENT_MONITOR) is exposed. The source identity and parameters are an open question (SRC-1)" - page_layout: stages - shape: "The first Australian Synchrotron beamline: macromolecular crystallography on a heterogeneous control plane (EPICS plus the MXCuBE Exporter, DECTRIS SIMPLON REST, and a robot TCP), the fleet's first non-EPICS area detector." - source_ref: - label: "AustralianSynchrotron/mx3-beamline-library" - url: "https://github.com/AustralianSynchrotron/mx3-beamline-library" - -enclosures: - # The device library exposes no enclosure / hutch layout, only the front-end and - # mono-beam PSS shutters. Modelled as the optics hutch + the experiment hutch; the - # hutch names and the PSS permit leaves are a staff question (ENC-1, PSS-1). - - name: MX3-OH - role: optics-hutch - facility_code: as - permit_signal: {confirm: "PSS permit leaf not in source; the front-end shutter is MX3FE01SHT01 and the mono-beam shutter MX3BLSH01SHT01 (PSS-1, ENC-1)"} - - name: MX3-EH - role: experiment-hutch - facility_code: as - permit_signal: {confirm: "PSS permit leaf unknown; the experiment hutch carries the MD3 microdiffractometer, the Eiger, and the ISARA robot (PSS-1, ENC-1)"} - -# =========================================================================== -# SOURCE STAGE: the storage ring and the front-end shutter -# =========================================================================== - -source: - stage: source - enclosure: MX3-OH - intro: "The storage-ring source-current monitor and the front-end shutter. The insertion-device source itself is not in the device library (SRC-1)." - devices: - - name: StorageRing - family: StorageRing # loose Family (facility source representation) - pv: "SR11BCM01:CURRENT_MONITOR" - confirm: true - note: "Storage-ring beam-current monitor (ring_current); the only source-side PV in the library. MX3's undulator / insertion device is not exposed here (SRC-1). Reuses the loose StorageRing family." - - name: WhiteBeamShutter - family: Shutter - pv: "MX3FE01SHT01" - confirm: true - note: "Front-end photon shutter (white_beam_shutter, a PSS shutter; OPEN_CLOSE_CMD / OPEN_CLOSE_STATUS / OPEN_ENABLED_STATUS)." - -# =========================================================================== -# OPTICS STAGE: the monochromator, the energy axis, the attenuators -# =========================================================================== - -optics: - stage: source - enclosure: MX3-OH - intro: "Set the energy and condition the beam: the double-multilayer monochromator, the master energy axis, and the attenuator / transmission unit. PVs verified against mx3_beamline_library/devices/beam.py. No standalone mirror or slit device is in the library (OPT-1)." - devices: - - name: Monochromator - family: Monochromator - pv: "MX3MONO01:" - confirm: true - note: "Double-multilayer monochromator (energy_dmm; ENERGY_MONITOR / ENERGY_SP, with a coating-stripe position monitor STRIPE_POSITION_MONITOR, read-only in the library; physical stripe selection inferred). Reuses the Monochromator family; the stripe is a per-Asset setting. Crystal / multilayer detail pending (DCM-1)." - - name: EnergyAxis - family: PseudoAxis - pv: "MX3:MASTER_ENERGY_SP" - confirm: true - note: "The master beamline energy setpoint (MX3:MASTER_ENERGY_SP), which the monochromator tracks. Whether energy is scanned as the measurement (anomalous MX) is ENERGY-1." - - name: Attenuators - family: Filter - pv: "MX3FLT05:" - confirm: true - note: "Attenuator / transmission unit (a filter wheel; AttenuationSet / TransmissionSet, with BeamSize_X / BeamSize_Y readbacks). Reuses the Filter family. Foil set pending (DCM-1)." - -# =========================================================================== -# SAMPLE STAGE: the MD3 microdiffractometer goniometer, environment, robot -# =========================================================================== - -sample: - stage: sample - enclosure: MX3-EH - intro: "The MD3 microdiffractometer goniometer that holds and orients the crystal, the cryojet sample cooling, the MD3 backlight, and the beamstop. PVs / interfaces verified against mx3_beamline_library/devices/{motors,cryo}.py and classes/motors.py." - note: > - MX3 holds a cryocooled crystal on the MD3 microdiffractometer and rotates it - through an oscillation while the Eiger reads frames. The MD3 goniometer reuses the - graduated Goniometer family (the i03 MX precedent), but it is driven over the - MXCuBE Exporter protocol (TCP), not EPICS, so it carries no PV. The ISARA sample - robot is modelled as a deferred Procedure (sample exchange), not a device, per the - i03 / i24 ROBOT-1 precedent. - devices: - - name: Goniometer - family: Goniometer - confirm: true - note: "MD3 (Arinax) microdiffractometer goniometer (md3): omega rotation plus a mini-kappa (kappa / phi), sample centring (CentringX / Y), and alignment (AlignmentX / Y / Z). Reuses the graduated Goniometer family (richer than the i03 Smargon). Driven over the MXCuBE Exporter protocol (TCP at MD3_ADDRESS:MD3_PORT, per-axis Exporter property names), NOT EPICS, so no PV; the host is deployment config (GONIO-1)." - - name: SampleTemperature - family: TemperatureController - pv: "MX3CRYOJET01:" - confirm: true - note: "Cryojet sample cooling (cryo_temperature; SAMPLET_MON / SETP_CMD). Reuses the TemperatureController family (graduated #350)." - - name: Backlight - family: Backlight # catalog Family (DET-1) - confirm: true - note: "MD3 sample backlight / frontlight illumination for on-axis viewing and centring; an Exporter-driven MD3 sub-device (no EPICS PV). Binds the catalog Backlight Family (graduated across the MX / imaging fleet, DET-1)." - - name: BeamStop - family: BeamStop - confirm: true - note: "MD3 beamstop (beamstop_x / y / z), an Exporter-driven MD3 sub-device (no EPICS PV) blocking the direct beam at the sample. Reuses BeamStop." - -# =========================================================================== -# DETECTION STAGE: the Eiger, the detector stage, flux and beam-position monitors -# =========================================================================== - -detector: - stage: detection - enclosure: MX3-EH - intro: "The DECTRIS Eiger area detector and its translation stage, the on-axis viewing camera, the flux monitor, and the beam-position / steering monitor. PVs / interfaces verified against mx3_beamline_library/devices/{detectors,motors,beam}.py." - note: > - The Eiger reads the rotation frames; it is driven over the DECTRIS SIMPLON REST - API (HTTP), not EPICS area-detector, the first such control plane in the fleet, so - it carries no PV (the endpoint base is deployment config). The detector stage, - flux, OAV camera, and beam-position monitor are EPICS. - devices: - - name: EigerDetector - family: Camera - confirm: true - note: "DECTRIS Eiger (16M / 4M) area detector (dectris_detector). Driven over the SIMPLON REST API (arm / trigger / disarm / config at /detector/api/1.8.0/, base URL SIMPLON_API), NOT EPICS area-detector, so it carries no PV; the endpoint is deployment config (DET-1). Reuses Camera (the new REST control-plane is a seam, not a new Family)." - - name: DetectorStage - family: LinearStage - pv: "MX3STG03MOT04" - confirm: true - note: "Detector translation (detector_fast_stage MX3STG03MOT04, detector_slow_stage MX3STG03MOT01) setting the sample-to-detector distance (read back at MX3ES01:SAMPLE_DETECTOR_DISTANCE). Reuses LinearStage." - - name: FluxMonitor - family: FluxMonitor - pv: "MX3FLUXIOC:FLUX" - confirm: true - note: "Incident-flux monitor (flux). Reuses FluxMonitor (graduated #353)." - - name: BeamPositionMonitor - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1) - pv: "MX3DAQIOC04:" - confirm: true - note: "Beam-position monitor and closed-loop steering (BPM0 PosX / PosY / Int readbacks plus a PID steering DAC). Binds the graduated PositionMonitor Family (DIAG-1). The PID beam-steering controller half has no clean existing family and is a deferred new-device question (STEER-1)." - - name: OAVCamera - family: Camera - pv: "MX3MD3ZOOM0" - confirm: true - note: "On-axis viewing camera (blackfly_camera, an EPICS area-detector BlackFly at the MD3 zoom optic) for sample centring; an MD3 coaxial camera also streams over Redis. Reuses Camera." - -# =========================================================================== -# Cross-cutting controls -# =========================================================================== - -controls: - intro: > - The mono-beam and fast shutters that gate the exposure, and the endstation motion - controllers. MX3's control plane is heterogeneous: EPICS for the shutters / stages - / mono / flux, the MXCuBE Exporter protocol for the MD3 goniometer, the SIMPLON - REST API for the Eiger, and a TCP client for the ISARA robot. - triggering: - - name: MonoBeamShutter - family: Shutter - pv: "MX3BLSH01SHT01" - confirm: true - note: "Mono-beam PSS shutter (mono_beam_shutter) gating the conditioned beam into the experiment hutch; an MD3 fast shutter (Exporter-driven) gates the per-oscillation exposure at the sample." - motion_controllers: - - name: EndstationMotionController - family: MotionController - pv: "MX3STG" - confirm: true - note: "The endstation, goniometer-base (MX3STG02), and detector (MX3STG03) stages run on Australian Synchrotron Power Brick (PMAC) motion controllers (the MX3STG..MOT.. axis records, class ASBrickMotor); box firmware / IP not in the library (DRIVE-1)." - software_iocs_not_modeled: - [DECTRIS-SIMPLON, MD3-Exporter, ISARA-robot, BlackFly, MD3-Redis-camera] - -resources: - intro: Continuously-available resources. Facility-scope supplies live in deployments/as/site.yaml. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: LiquidNitrogen # cryojet - - kind: Power - replaceable_parts: - swappable_with_identity: ["sample pucks", "Eiger detector", "attenuator foils"] diff --git a/deployments/nsls2/site.yaml b/deployments/nsls2/site.yaml deleted file mode 100644 index a81f8134f13..00000000000 --- a/deployments/nsls2/site.yaml +++ /dev/null @@ -1,206 +0,0 @@ -# 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 reverse-engineered NSLS-II beamline -# scaffolds listed in the facility.beamlines field below (FXI ... ISR). 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. -# -# Status: reverse-engineered. FXI is an operational NSLS-II beamline, but CORA -# has not been connected to it and no FXI staff have confirmed this model. Every -# value below is read from public NSLS-II open source (the bluesky profile -# collection NSLS2/fxi-profile-collection and the shared NSLS2/nslsii package) or -# inferred, and is carried as `pending` until FXI staff confirm it. Do not invent -# facility specifics here; carry them as questions on the FXI open-questions page. -# -# Source-of-truth boundary (same as the APS and MAX IV sites): -# - the closed facility-kind / actor-kind vocabularies are validated against -# code-mirrored frozensets in scripts/site_descriptor.py. -# - the facility records the bootstrap invariants (kind=Site, display_name -# equals code); `heading` carries the human title used on the rendered page. - -facility: - code: nsls2 - display_name: nsls2 - heading: "NSLS-II" - kind: Site - institution: Brookhaven National Laboratory - control_plane: "EPICS / bluesky" - beamlines_note: "Two dozen operating beamlines spanning nearly the whole hard- and soft-X-ray technique surface, each modelled from its own bluesky profile collection." - beamlines: [FXI, HXN, BMM, SRX, SIX, CHX, CSX, IOS, XPD, ESM, SMI, IXS, SST, ISS, FMX, CMS, XFM, LIX, HEX, AMX, XFP, ISR, CDI, PDF] - -# ISA-88 Site Recipes: the facility-adapted form of a catalog Method. All pending -# because they are reverse-engineered from the FXI profile collection, not yet -# confirmed with FXI staff. Each names the cross-facility Method it would adapt. -practices: - - {name: FXI_tomography_practice, method: tomography, pending: true, note: "full-field transmission tomography; reverse-engineered from the FXI bluesky plans, awaiting staff confirmation"} - - {name: FXI_fly_tomography_practice, method: continuous_rotation_tomography, pending: true, note: "continuous-rotation fly tomography (tomo_zfly / fly_scan), Zebra position-triggered"} - - {name: FXI_energy_change_practice, method: beamline_energy_change, pending: true, note: "coupled energy move (move_zp_ccd_xh) for XANES and spectro-tomography"} - - {name: HXN_nano_tomography_practice, method: tomography, pending: true, note: "scanning nano-tomography (raster x rotation); reverse-engineered from the HXN profile collection"} - - {name: HXN_energy_change_practice, method: beamline_energy_change, pending: true, note: "energy change co-moving the zone-plate refocus per element edge (XANES / spectro-tomo)"} - - {name: SRX_xrf_tomography_practice, method: tomography, pending: true, note: "XRF-tomography (raster x rotation, fluorescence map per angle); reverse-engineered from the SRX profile collection"} - # BMM's defining technique is transmission/fluorescence XAS, an energy SCAN whose - # Method (energy_scan) the catalog anticipates but does not yet coin (ENERGY-1). - # No BMM Practice is recorded until that Method exists; adding one now would - # reference a non-existent or wrong method. BMM is bound to the Site via beamlines. - # SRX's defining techniques (scanning XRF mapping, XANES) sit on the same two - # deferred Methods, scanning (HXN) and energy_scan (BMM); only its XRF-tomography - # leg binds an existing Method, so only that Practice is recorded here. - # SIX's defining technique is RIXS (resonant inelastic X-ray scattering), a soft - # X-ray scattering Method not in the imaging-heritage catalog; rendered pending - # until a technique enters scope (TECH-1). - - {name: SIX_rixs_practice, method: resonant_inelastic_scattering, pending: true, note: "resonant inelastic X-ray scattering on the soft X-ray spectrometer arm; Method not yet in catalog (TECH-1)"} - - {name: IXS_inelastic_scattering_practice, method: inelastic_x_ray_scattering, pending: true, note: "momentum-resolved hard X-ray inelastic scattering: set Q on the six-circle arm, scan incident energy against the fixed crystal analyzer, point-detect I(Q, energy-loss); Method not yet in catalog (TECH-1)"} - # CHX's defining techniques (XPCS, small-angle scattering) sit on the deferred - # xpcs / small_angle_scattering Methods that APS 8-ID left pending (TECH-1); no - # CHX Practice is recorded until those Methods exist. CHX is bound via beamlines. - # CSX (23-ID) does coherent / resonant soft X-ray scattering on the TARDIS - # diffractometer; both legs reuse existing pending Methods (resonant_scattering - # from 4-ID, diffraction from 4-ID / 8-ID). The coherence is a beam-quality - # enabler carried as settings, not coined as its own Method (TECH-1). - - {name: CSX_rsxs_practice, method: resonant_scattering, pending: true, note: "resonant soft X-ray scattering (RSXS); reuses the 4-ID resonant_scattering Method (TECH-1)"} - - {name: CSX_diffraction_practice, method: diffraction, pending: true, note: "coherent soft X-ray diffraction on the TARDIS E6C; reuses the 4-ID / 8-ID diffraction Method (TECH-1)"} - # XPD's defining techniques (powder diffraction, total scattering / PDF) sit on the - # deferred powder_diffraction / total_scattering Capabilities that Diamond i11 and - # i15-1 left pending (TECH-1); no XPD Practice is recorded until those land. XPD is - # bound via beamlines. - # ESM (21-ID) does angle-resolved photoemission (ARPES), a soft X-ray photoemission - # 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)"} - # 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 - # Capabilities land. SMI is bound via beamlines. - # SST's three technique families (soft-scattering RSoXS, NEXAFS absorption, HAXPES - # photoemission) each sit on a deferred / pending Capability (TECH-1, ENERGY-1, the - # ESM angle_resolved_photoemission); no SST Practice is recorded until they land. - # SST is bound via beamlines. - # ISS (8-ID) does X-ray absorption (EXAFS, by HHM trajectory energy fly-scan) and - # X-ray emission (XES, and incident-energy HERFD) on the Johann / von Hamos crystal - # emission spectrometers. This is the same emission-spectrometer XAS / XES shape that - # LCLS-MFX left pending as xas_spectroscopy, so ISS reuses that Method as the second - # consumer rather than coining a new one (TECH-1). The energy sweep also leans on the - # deferred energy_scan Capability (ENERGY-1, the BMM question), which ISS strengthens - # as a further consumer without forcing it in this descriptor scaffold. - - {name: ISS_xas_spectroscopy_practice, method: xas_spectroscopy, pending: true, note: "X-ray absorption (EXAFS) by HHM trajectory energy fly-scan, plus X-ray emission (XES) and high-energy-resolution fluorescence detection (HERFD) on the Johann and von Hamos crystal emission spectrometers; reuses the xas_spectroscopy Method that LCLS-MFX left pending, the second consumer (TECH-1). The incident-energy sweep also leans on the deferred energy_scan Capability (ENERGY-1)"} - # FMX (17-ID-2) does microfocus macromolecular crystallography: rotation data - # collection on a single-omega goniometer + Eiger, fast grid scans for centring, and - # an autonomous robot sample-exchange loop. These reuse the three MX Methods Diamond - # i03 left pending (mx_data_collection, grid_scan, sample_exchange); FMX is the second - # consumer of each. They stay pending (no mechanical promotion for Methods; the - # energy_scan deferral discipline) and the autonomous loop is a Procedure over the - # spine plus a Subject custody thread (TECH-1 / ROBOT-1). The fixed-target chip-scanner - # serial mode is deferred (SERIAL-1), not a practice. - - {name: FMX_mx_data_collection_practice, method: mx_data_collection, pending: true, note: "rotation / oscillation MX data collection on the single-omega goniometer + Eiger via the mxtools vector / Zebra flyer; reuses the i03 mx_data_collection Method, the second consumer (TECH-1)"} - - {name: FMX_grid_scan_practice, method: grid_scan, pending: true, note: "fast grid scan for sample location / centring via the Zebra-triggered goniometer raster; reuses the i03 grid_scan Method, the second consumer (TECH-1)"} - - {name: FMX_sample_exchange_practice, method: sample_exchange, pending: true, note: "autonomous robot load / centre / collect / unmount loop coordinated by the LSDC Governor; reuses the i03 sample_exchange Method, the second consumer; a Procedure over the spine + a Subject custody thread (ROBOT-1)"} - # CMS (11-BM) complex-materials scattering Practices (first cut). SAXS / WAXS / - # GISAXS overlap SMI (the NSLS-II twin), I22, and 9-ID; the distinct one is - # specular reflectivity (XR), the second consumer of the reflectivity Method after - # i10. Methods not yet in the catalog, carried pending (TECH-1). - - {name: CMS_small_angle_scattering_practice, method: small_angle_scattering, pending: true, note: "transmission small-angle scattering on the Pilatus 2M; shares the i22 / SMI SAXS Method (TECH-1)"} - - {name: CMS_wide_angle_scattering_practice, method: wide_angle_scattering, pending: true, note: "wide- and medium-angle scattering on the Pilatus 800K detectors; shares the i22 WAXS Method (TECH-1)"} - - {name: CMS_grazing_incidence_scattering_practice, method: grazing_incidence_scattering, pending: true, note: "grazing-incidence small- and wide-angle scattering (GISAXS / GIWAXS) on thin films; shares the 9-ID Method, SMI the NSLS-II twin (TECH-1)"} - - {name: CMS_reflectivity_practice, method: reflectivity, pending: true, note: "specular hard X-ray reflectivity (XR): step the sample theta and track the reflected beam in a sliding region on the fixed Pilatus; second consumer of the reflectivity Method after i10 (XR-1, TECH-1)"} - # IOS (23-ID-2) does ambient-pressure photoemission (AP-XPS / AP-PES) and soft - # NEXAFS / XAS, the in-situ / operando twin of CSX on the same canted 23-ID straight. - # Its photoemission sits on the pending angle_resolved_photoemission Method ESM coined - # (AP-XPS is chemical-state, not angle-resolved, so the slug names a shape it was not - # coined for), and its NEXAFS sits on the deferred energy_scan Capability (ENERGY-1, - # the BMM question) rather than the crystal-emission-spectrometer xas_spectroscopy. - # Following SST, no IOS Practice is recorded until a Method lands (TECH-1); IOS is - # bound via beamlines. - # XFM (4-BM) is a scanning X-ray fluorescence microprobe: raster the sample through a - # focused bending-magnet beam, read element maps on the Xspress3 / Maia detectors. This - # reuses the scanning_fluorescence_microscopy Method 2-ID left pending; XFM is the second - # consumer. It stays pending (no mechanical promotion for Methods; the energy_scan - # deferral discipline; METHOD-1 / TECH-1). The XANES microspectroscopy leg leans on the - # deferred energy_scan Capability (ENERGY-1, the BMM question), no practice recorded. - - {name: XFM_scanning_fluorescence_microscopy_practice, method: scanning_fluorescence_microscopy, pending: true, note: "4-BM sample-scanning XRF mapping on the UTS raster stage + Xspress3 / Maia detectors; reuses the 2-ID scanning_fluorescence_microscopy Method, the second consumer (METHOD-1)"} - # LIX (16-ID) life-science solution-scattering Practices (first cut). The science - # axis (small- / wide-angle scattering) overlaps the materials-scattering fleet, but - # the SUBJECT (a protein in solution, often an eluting SEC peak) and the fluidic - # SAMPLE DELIVERY are new. The bio-SAXS / SEC-SAXS Method is new to the catalog - # (solution_scattering); the scanning-microbeam mode reuses the existing pending - # scanning_fluorescence_microscopy Method. All carried pending (TECH-1). - - {name: LIX_solution_scattering_practice, method: solution_scattering, pending: true, note: "biological solution small- / wide-angle scattering (bio-SAXS / WAXS) on protein solutions in a flow cell; the fleet's first solution-scattering Method, new to the catalog (TECH-1)"} - - {name: LIX_sec_saxs_practice, method: solution_scattering, pending: true, note: "in-line size-exclusion-chromatography-coupled SAXS (SEC-SAXS): the HPLC delivery pump flows the eluting peak through the cell while the SAXS detector reads; the same solution_scattering Method with the elution as the acquisition axis, a Procedure over the fluidic seam (TECH-1, FLUID-1)"} - - {name: LIX_microbeam_scanning_practice, method: scanning_fluorescence_microscopy, pending: true, note: "scanning-microbeam mapping of cells and tissue (raster x scattering / fluorescence) on the SmarAct goniometer; reuses the existing pending scanning_fluorescence_microscopy Method (TECH-1)"} - # HEX (27-ID) high-energy engineering Practices (first cut). All reuse Methods the fleet - # already holds: tomography is graduated (2-BM / FXI); radiography and - # energy_dispersive_diffraction are the pending APS 7-BM Methods (HEX the second consumer - # of each); powder_diffraction is the pending Diamond i11 Method (HEX the second consumer). - # Nothing new is coined; the diffraction Methods stay pending (TECH-1). - - {name: HEX_tomography_practice, method: tomography, pending: true, note: "high-energy white-beam and monochromatic X-ray tomography (tomo_flyscan / tomo_loop) for engineering-materials and operando imaging on the Kinetix sCMOS cameras; reuses the graduated tomography Method (2-BM / FXI)"} - - {name: HEX_radiography_practice, method: radiography, pending: true, note: "time-resolved high-speed radiography on the Phantom Veo; reuses the radiography Method APS 7-BM left pending, the second consumer (TECH-1)"} - - {name: HEX_energy_dispersive_diffraction_practice, method: energy_dispersive_diffraction, pending: true, note: "spatially-resolved energy-dispersive X-ray diffraction (EDXD) on the GeRM germanium strip detector; reuses the energy_dispersive_diffraction Method APS 7-BM left pending, the second consumer (TECH-1)"} - - {name: HEX_powder_diffraction_practice, method: powder_diffraction, pending: true, note: "monochromatic angle-dispersive / powder diffraction (ADXD) on the PerkinElmer flat panel; reuses the powder_diffraction Method Diamond i11 left pending, the second consumer (TECH-1)"} - # AMX (17-ID-1) is FMX's high-throughput MX sibling on the shared 17-ID straight: rotation - # data collection on a single-omega goniometer + Eiger, fast grid scans, and an autonomous - # EMBL-robot sample-exchange loop. These reuse the three MX Methods i03 / FMX left pending; - # AMX is the third consumer of each. They stay pending: Methods coin on a conduct-path (an - # integration scenario that runs them), not a sighting count, so n=3 strengthens the case - # but does not coin them (the energy_scan discipline; TECH-1 / ROBOT-1). - - {name: AMX_mx_data_collection_practice, method: mx_data_collection, pending: true, note: "rotation / oscillation MX data collection on the single-omega goniometer + Eiger via the mxtools vector / Zebra flyer; reuses the i03 / FMX mx_data_collection Method, the third consumer (TECH-1)"} - - {name: AMX_grid_scan_practice, method: grid_scan, pending: true, note: "fast grid scan for sample location / centring via the Zebra-triggered goniometer raster; reuses the i03 / FMX grid_scan Method, the third consumer (TECH-1)"} - - {name: AMX_sample_exchange_practice, method: sample_exchange, pending: true, note: "autonomous EMBL-robot load / centre / collect / unmount loop coordinated by the LSDC Governor; reuses the i03 / FMX sample_exchange Method, the third consumer; a Procedure over the spine + a Subject custody thread (ROBOT-1)"} - # XFP (17-BM) X-ray footprinting Practices (first cut). XFP is a DOSE-DELIVERY - # beamline, not a scattering / diffraction one: a white / pink beam irradiates a - # biological macromolecule in solution to footprint it via hydroxyl radicals, and the - # structural readout is OFFLINE mass spectrometry. The Method (radiolytic / X-ray - # footprinting) is new to the catalog; both modes share it, carried pending (TECH-1). - - {name: XFP_footprinting_practice, method: x_ray_footprinting, pending: true, note: "X-ray footprinting of a biological macromolecule in solution: gate a timed white-beam dose onto a flowing capillary / flow-cell sample, recording exposure time x flux x attenuation as the delivered dose; the fleet's first dose-delivery Method, new to the catalog; structural readout is offline mass spec (TECH-1, READOUT-1)"} - - {name: XFP_high_throughput_footprinting_practice, method: x_ray_footprinting, pending: true, note: "shutterless high-throughput footprinting: sweep a fly-cell row through the defining slit at a set stage velocity so the exposure (dose) is the slit gap over the velocity, across a 96-well plate; the same x_ray_footprinting Method with the HTFly stage as the dose-timing (TECH-1, HT-1)"} - # ISR (4-ID) in-situ / resonant hard X-ray Practices (deliberately partial first cut). - # Resonant elastic scattering reuses the 4-ID / CSX resonant_scattering Method; surface - # / interface (CTR) diffraction reuses the 4-ID / 8-ID diffraction Method. Both are - # DOUBLY deferred here: the Methods are pending AND the multi-circle diffractometer they - # run on is absent from the source (DIFF-1), so these are intent, not a wired capability. - - {name: ISR_resonant_scattering_practice, method: resonant_scattering, pending: true, note: "resonant hard X-ray scattering near an absorption edge; reuses the 4-ID / CSX resonant_scattering Method; the diffractometer and a wired energy axis are absent from source (TECH-1, DIFF-1, RESONANT-1)"} - - {name: ISR_surface_diffraction_practice, method: diffraction, pending: true, note: "surface / interface diffraction (crystal truncation rods); reuses the 4-ID / 8-ID diffraction Method; the multi-circle diffractometer is absent from source (TECH-1, DIFF-1)"} - # CDI (9-ID) does coherent diffractive imaging: forward (plane-wave) CDI, ptychography, - # and Bragg CDI, a coherent beam focused by a KB pair onto the sample with the far-field - # pattern recorded on the Eiger2 / Merlin and the real-space image recovered offline by - # phase retrieval (a ComputePort leg, not a Method). These sit on the deferred coherent- - # imaging Method cohort Diamond i13-1 opened as the pending ptychography Method (the - # fleet's first coherent diffractive imaging); CDI reinforces it without coining, and - # following CHX / HXN records no Practice until the Method scope lands (TECH-1). CDI is - # bound via beamlines. - # NAME GUARD: this is NSLS-II 9-ID, not APS 9-ID (CSSI); the coherent_surface_scattering / - # grazing_incidence_scattering pending Methods belong to APS 9-ID and are untouched here. - # PDF (28-ID-1) is XPD's dedicated total-scattering / PDF twin on the shared 28-ID - # damping wiggler: high-energy powder diffraction and rapid-acquisition pair - # distribution function. Its techniques sit on the same deferred powder_diffraction / - # total_scattering Methods Diamond i11 and i15-1 left pending (TECH-1); following XPD, - # no PDF Practice is recorded until those land. PDF is bound via beamlines. - -# Access BC Actors conceptually facility-wide at NSLS-II. Pending until the NSLS-II -# operator and review structure is confirmed; the profile collection only exposes -# coarse queue-server groups (root / primary), not the human roster. -actors: - - {name: NSLS-II beamline staff, kind: human, pending: true, note: "operator and beamline-scientist pool; structure TBD (GOV-1)"} - - {name: NSLS-II safety review, kind: human, pending: true, note: "facility safety review body; membership TBD"} - -# Agent BC Agents seeded at this deployment. None declared: the CORA system agents -# are not yet wired for an NSLS-II deployment. -agents: [] - -# Supply BC: facility-wide continuously-available resources. Pending in this -# reverse-engineered model. LiquidNitrogen is the DCM crystal cooling read in the -# profile collection (XF:18IDA-UT Cryo:1 levels/flow; cooling valves V4/V5). -supplies: - - {name: Storage-ring beam current, kind: PhotonBeam, pending: true} - - {name: Cooling water, kind: CoolingWater, pending: true} - - {name: Beamline vacuum, kind: Vacuum, pending: true} - - {name: DCM liquid nitrogen, kind: LiquidNitrogen, pending: true} - -# Safety BC: facility-issued Clearances. NSLS-II PSS form names are not confirmed; -# the profile collection exposes only the PPS photon-shutter status, not the -# search-and-secure permit leaves. Carried pending with a note rather than guessed. -clearances: - - {name: NSLS-II personal safety system, kind: PSS, pending: true, note: "facility safety-form and permit-leaf names TBD; confirm with NSLS-II staff (PSS-1)"} - -# Caution BC: operator tribal knowledge. Beamline-level cautions reverse-engineered -# for FXI live on docs/deployments/fxi/cautions.md, not here. -cautions: [] diff --git a/deployments/nsrrc/site.yaml b/deployments/nsrrc/site.yaml deleted file mode 100644 index 451257a7c96..00000000000 --- a/deployments/nsrrc/site.yaml +++ /dev/null @@ -1,93 +0,0 @@ -# CORA Site descriptor: the NSRRC site-level surface -# -# The National Synchrotron Radiation Research Center (NSRRC, Hsinchu, Taiwan) is the -# Site CORA models for its Taiwan deployment. NSRRC operates two storage rings: the -# Taiwan Light Source (TLS, 1.5 GeV, 1993) and the Taiwan Photon Source (TPS, 3 GeV, -# 2014, users since 2016). 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. It is the home of the TPS 07A micro-focus -# protein-crystallography beamline (the first NSRRC deployment). -# -# Status: reverse-engineered. CORA has not been connected to NSRRC and no staff have -# confirmed this model. Every value below is read from public open source (the -# light911/NSRRC_TPS07A + light911/TPS07A-Meshbest control trees, the SPXF facility -# pages, and JACoW proceedings) or inferred, and is carried as `pending` until staff -# confirm it. Do not invent facility specifics here; carry them as questions on the -# TPS 07A open-questions page. -# -# Source-of-truth boundary (same as the APS / MAX IV / Diamond / NSLS-II / SLAC / -# Australian Synchrotron sites): -# - the closed facility-kind / actor-kind vocabularies are validated against -# code-mirrored frozensets in scripts/site_descriptor.py. -# - the facility records the bootstrap invariants (kind=Site, display_name equals -# code); `heading` carries the human title used on the rendered page. -# -# Controls house-style (the distinctive Site fact): NSRRC runs a single EPICS control -# floor across both rings (>200 IOCs, ~10^5 PVs, EPICS 3.14.12.x as of 2017), but -# there is NO facility-wide beamline scan framework (no Bluesky / Sardana / Tango). -# Each beamline carries its own bespoke acquisition layer over the shared EPICS floor. -# At the MX cluster (TPS 07A/05A, TLS 15A1) the orchestration is Blu-Ice/DCSS over an -# EPICS Device Handler Server (the SSRL lineage), confirmed live by a 2025 J. -# Synchrotron Rad. paper; NOT MXCuBE (NSRRC is a listed MXCuBE partner, but no -# mxcubecore HardwareObjects deployment exists publicly). CORA's EdgeConductor would -# replace the DCSS scan orchestration over the EPICS floor, the 2-BM TomoScan seam. -# See docs/deployments/tps-07a/equipment/controls.md. - -facility: - code: nsrrc - display_name: nsrrc - heading: "NSRRC" - kind: Site - institution: NSRRC (National Synchrotron Radiation Research Center, Hsinchu, Taiwan) - control_plane: "EPICS (Blu-Ice / DCSS)" - beamlines_note: "A shared MX cluster: TPS 07A and TPS 05A run the same MD3 + ISARA kit on the common Blu-Ice / DCSS stack." - beamlines_note: "TPS 07A and TPS 05A are sibling stations of one MX cluster, sharing the Blu-Ice/DCSS-over-EPICS stack and the MD3 + ISARA kit." - beamlines: [TPS 07A, TPS 05A] - -# ISA-88 Site Recipes: the facility-adapted form of a catalog Method. All pending -# because they are reverse-engineered from the NSRRC_TPS07A control trees, not yet -# confirmed with NSRRC staff. TPS 07A's rotation-MX techniques reuse the same pending -# cross-facility Methods Diamond i03 introduced (mx_data_collection, grid_scan, -# sample_exchange), none yet in the catalog (TECH-1 / ROBOT-1). -practices: - - {name: TPS07A_mx_data_collection_practice, method: mx_data_collection, pending: true, note: "rotation / oscillation MX data collection on the MD3 microdiffractometer goniometer + the DECTRIS EIGER2 X 16M, orchestrated through Blu-Ice/DCSS; reuses the i03 Method, not yet in the catalog (TECH-1)"} - - {name: TPS07A_grid_scan_practice, method: grid_scan, pending: true, note: "mesh / grid scan for crystal location and centring on the MD3 (the Meshbest mesh-scan path, Dozor spot-scoring); reuses the i03 Method (TECH-1)"} - - {name: TPS07A_sample_exchange_practice, method: sample_exchange, pending: true, note: "unattended ISARA robot load / centre / collect / unmount loop; a Procedure over the spine + a Subject custody thread (ROBOT-1)"} - # TPS 05A reuses the same MX cluster Practices (the SPXF group runs the same Blu-Ice/DCSS - # stack on the same MD3 + ISARA kit, with an EIGER2 X 9M); a reuse-and-reinforce sibling. - - {name: TPS05A_mx_data_collection_practice, method: mx_data_collection, pending: true, note: "rotation / oscillation MX data collection on the MD3 microdiffractometer goniometer + the DECTRIS EIGER2 X 9M, orchestrated through Blu-Ice/DCSS; reuses the i03 Method, not yet in the catalog (TECH-1)"} - - {name: TPS05A_grid_scan_practice, method: grid_scan, pending: true, note: "mesh / grid scan for crystal location and centring on the MD3; reuses the i03 Method (TECH-1)"} - - {name: TPS05A_sample_exchange_practice, method: sample_exchange, pending: true, note: "unattended ISARA robot load / centre / collect / unmount loop; a Procedure over the spine + a Subject custody thread (ROBOT-1)"} - -# Access BC Actors conceptually facility-wide at NSRRC. Pending until the operator and -# review structure is confirmed; the control trees expose LDAP authentication -# (ldap://10.7.1.1) but no human roster. -actors: - - {name: NSRRC beamline staff, kind: human, pending: true, note: "operator and beamline-scientist pool, LDAP-backed; structure TBD (GOV-1)"} - - {name: NSRRC safety review, kind: human, pending: true, note: "facility safety review body; membership TBD"} - -# Agent BC Agents seeded at this deployment. None declared: the CORA system agents are -# not yet wired for an NSRRC deployment. -agents: [] - -# Supply BC: facility-wide continuously-available resources. Pending in this -# reverse-engineered model. LiquidNitrogen is the cryostream supply for MX cooling. -supplies: - - {name: Storage-ring beam current, kind: PhotonBeam, pending: true} - - {name: Cooling water, kind: CoolingWater, pending: true} - - {name: Beamline vacuum, kind: Vacuum, pending: true} - - {name: Cryostream liquid nitrogen, kind: LiquidNitrogen, pending: true} - -# Safety BC: facility-issued Clearances. The NSRRC PSS form names are not in the -# public control trees; the 07A tree exposes a detector minimum-distance interlock -# (139 mm) and a mandatory safety-training portal (safetytraining.nsrrc.org.tw), but -# no PSS permit-leaf signals. Carried pending rather than guessed. The mandatory -# training portal maps to CORA's worldwide-invariant training axis (a fact on the -# Access principals, not a separate Clearance kind); it is recorded on the governance -# page and as an open question (GOV-1), not coined here. -clearances: - - {name: NSRRC personal safety system, kind: PSS, pending: true, note: "facility safety-form and permit-leaf names not in public source; confirm with staff (PSS-1)"} - -# Caution BC: operator tribal knowledge. Beamline-level cautions reverse-engineered -# for TPS 07A would live on docs/deployments/tps-07a/, not here. -cautions: [] diff --git a/deployments/p01/beamline.yaml b/deployments/p01/beamline.yaml deleted file mode 100644 index 58803a37bc6..00000000000 --- a/deployments/p01/beamline.yaml +++ /dev/null @@ -1,399 +0,0 @@ -# P01 beamline descriptor (PETRA III, DESY), reverse-engineered from the OnlineXML -# -# P01 "Dynamics" is the hard X-ray nuclear-resonant-scattering and inelastic / -# resonant-inelastic-scattering beamline at PETRA III (DESY, Hamburg), 2.5-80 keV. -# It is bound to the PETRA III Site (deployments/petra-iii/site.yaml), and is CORA's -# FIRST PETRA III deployment and second Tango / Sardana control floor (after MAX IV). -# -# STATUS: reverse-engineered from P01's own public OnlineXML device registry -# (gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p01, branch -# debian/jessie; the xml/online_haspp01eh{1,2,3}.xml per-endstation Tango device -# registries). Device logical names and Tango control handles are real, read from -# that registry; vendor part numbers, serials, energy ranges, crystal cuts, and -# physical positions are not in it and are open questions. Every value is carried -# confirm until P01 staff verify it (a registry snapshot is strong evidence, not a -# CORA-owned fact). -# -# WHAT IS NEW: not a device Family. P01's stages bind existing Families -# (Monochromator, Mirror, Slit, Transfocator, LinearStage, RotaryStage, Camera, -# Diffractometer, FluxMonitor). The genuine novelty is twofold: (1) the TECHNIQUE -# (nuclear resonant scattering + IXS / RIXS) earns no catalog Method today, carried -# pending on the Site reusing the inelastic_x_ray_scattering / resonant_inelastic_ -# scattering slugs (TECH-1); (2) the CONTROL PLANE: PETRA III runs Tango with Sardana -# as the scan layer, so the seam "EPICS is the floor" generalizes to "Tango / Sardana -# is the floor" (CTRL-1), the same shape as MAX IV and a sibling of ESRF BLISS. -# -# CONTROL HANDLES: the descriptor `pv` field is the opaque control-handle slot (not -# EPICS-specific); for P01 it carries the Tango device address read from the -# OnlineXML (domain/family/member, e.g. p01/motor/eh1.02). A logical axis maps to one -# Tango motor device; a virtual / pseudo motor maps to a vmexecutor or attributemotor -# device. The OnlineXML lists one device per AXIS; CORA groups axes into Assets at the -# stage granularity (the monochromator, the mirror, the sample stage), carrying the -# per-axis Tango handles in the `pv` map. Asset grouping is the human curation step -# over the machine extraction and is carried confirm (GROUP-1). -# -# SCOPE: this cut models all five hutches present in the OnlineXML: two optics hutches -# (OH1 carrying the DCM and the two horizontal-deflection mirrors, OH2 carrying the -# secondary slits and the RIXS pre-optics) and three experiment hutches (EH1 nuclear -# resonant scattering with the high-resolution monochromator stack, EH2 diffraction, -# EH3 RIXS / KB-focused spectroscopy). Counter / timer / ADC channels and the Sardana -# MeasurementGroup bookkeeping rows are filtered out by the extractor and not modelled -# as devices. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/p01/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "nuclear resonant scattering and inelastic / resonant-inelastic scattering (2.5-80 keV) across two optics hutches and three experiment hutches (EH1 NRS high-resolution-monochromator stack, EH2 diffraction, EH3 RIXS / KB pair); reuses the optics / motion Families, novelty is the Site, its Tango / Sardana control plane read from the OnlineXML, and the NRS / RIXS technique branch (reusing the pending IXS / RIXS Methods)" - name: P01 - facility: petra-iii # PETRA III Site (facility_code: petra-iii) - sector: "P01" - tier: Unit - parent: null - source: insertion-device - source_confirm: "P01 is an undulator beamline (2.5-80 keV); the OnlineXML exposes undulator gap/taper virtual motors (gap_a, gap_b, taper_a, taper_b on p01/attributemotor) but no insertion-device period or parameters, carried pending (SRC-1)" - page_layout: stages - shape: "Hard X-ray dynamics (nuclear resonant scattering, RIXS) across three endstations, defined by a stack of four high-resolution monochromators carving meV bandwidth; CORA's first Tango / Sardana floor after MAX IV." - source_ref: - label: "python-nxstools-extras-p01" - url: "https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p01" - -# Five enclosures: two optics hutches carrying the shared source-conditioning optics, -# and three experiment hutches, one per technique branch. DESY PSS permit signals are -# not in the OnlineXML (which carries beamline devices, not the interlock leaves) (PSS-1). -enclosures: - - name: p01-oh1 - role: optics-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the first optics hutch; not in the OnlineXML (PSS-1)"} - - name: p01-oh2 - role: optics-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the second optics hutch; not in the OnlineXML (PSS-1)"} - - name: p01-eh1 - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for EH1 (nuclear resonant scattering); not in the OnlineXML (PSS-1)"} - - name: p01-eh2 - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for EH2 (diffraction); not in the OnlineXML (PSS-1)"} - - name: p01-eh3 - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for EH3 (RIXS); not in the OnlineXML (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the insertion device and the OH1 / OH2 conditioning optics -# =========================================================================== - -source: - stage: source - enclosure: p01-oh1 - intro: "The P01 undulator source. The OnlineXML exposes the gap and taper as virtual (attributemotor) axes rather than an insertion-device device server; the period and parameters are not published." - note: "Undulator gap / taper virtual motors on p01/attributemotor; which physical insertion device and its period / harmonics is SRC-1." - devices: - - name: Undulator - family: InsertionDevice - pv: {gap_a: "p01/attributemotor/gap.01", gap_b: "p01/attributemotor/gap.02", taper_a: "p01/attributemotor/taper.01", taper_b: "p01/attributemotor/taper.02"} - new: true - confirm: true - note: "P01 undulator source; gap_a/gap_b and taper_a/taper_b are virtual axes, suggesting a two-section or canted-undulator arrangement, unconfirmed (SRC-1); energy reach 2.5-80 keV per the DESY catalog" - -oh1-optics: - stage: source - enclosure: p01-oh1 - intro: "The first optics hutch: the double-crystal monochromator and the two horizontal-deflection mirrors that monochromate and steer the beam, plus the front-end definition slits." - note: "Handles read from the OnlineXML (p01/dcmmotor, p01/dcmener, p01/motor/oh1.*). The DCM energy / Bragg pseudo-motors are virtual; crystal cut and the mirror coatings / stripes are OPT-1." - devices: - - name: Monochromator - family: Monochromator - pv: {bragg: "p01/dcmmotor/oh.01", energy: "p01/dcmener/oh.01", lateral: "p01/motor/oh1.08", parallel: "p01/motor/oh1.10", perpendicular: "p01/motor/oh1.09", pitch: "p01/motor/oh1.11", roll: "p01/motor/oh1.02", offset: "p01/attributemotor/fmbexitoffset.01", y: "p01/vmexecutor/dcm_z", y1: "p01/motor/oh1.03", y2: "p01/motor/oh1.04", y3: "p01/motor/oh1.07"} - new: true - confirm: true - note: "double-crystal monochromator (FMB-Oxford-style: dcm_bragg / dcm_ener virtual energy axis, fixed-exit offset, three y jacks); crystal cut (Si 111 / 311) and energy range are OPT-1" - - name: Mirror1 - family: Mirror - pv: {pitch: "p01/motor/oh1.17", x: "p01/motor/oh1.18", rotation: "p01/motor/oh1.21", y: "p01/motor/oh1.22"} - new: true - confirm: true - note: "first OH1 deflection / harmonic-rejection mirror (oh1_m1); coating / stripe and incidence angle are OPT-1" - - name: Mirror2 - family: Mirror - pv: {pitch: "p01/motor/oh1.25", x: "p01/motor/oh1.26", rotation: "p01/motor/oh1.29", y: "p01/motor/oh1.30"} - new: true - confirm: true - note: "second OH1 deflection mirror (oh1_m2); coating / stripe and incidence angle are OPT-1" - - name: FrontEndSlit1 - family: Slit - pv: {center_y: "p01/motor/oh1.12", gap_y: "p01/motor/oh1.05"} - new: true - confirm: true - note: "first front-end definition slit (fe_slit1); vertical center / gap only in the registry (OPT-1)" - - name: FrontEndSlit2 - family: Slit - pv: {center_y: "p01/motor/oh1.14", gap_y: "p01/motor/oh1.13", left: "p01/motor/oh1.15", right: "p01/motor/oh1.16"} - new: true - confirm: true - note: "second front-end definition slit (fe_slit2)" - -oh2-optics: - stage: source - enclosure: p01-oh2 - intro: "The second optics hutch: the secondary defining slits, a diamond beam monitor, and the RIXS pre-optics translation that selects the EH3 spectroscopy branch." - note: "Handles read from the OnlineXML (p01/motor/oh2.*, p01/vmexecutor/slit1_*). The diamond monitor and rixs translation roles are OPT-1 / DET-1." - devices: - - name: SecondarySlit - family: Slit - pv: {bottom: "p01/motor/oh2.45", top: "p01/motor/oh2.46", left: "p01/motor/oh2.47", right: "p01/motor/oh2.48", center_x: "p01/vmexecutor/slit1_cx", center_y: "p01/vmexecutor/slit1_cy", gap_x: "p01/vmexecutor/slit1_dx", gap_y: "p01/vmexecutor/slit1_dy"} - new: true - confirm: true - note: "secondary defining slit (slit1: four blades + cx/cy/dx/dy virtual center/gap motors on vmexecutor)" - - name: DiamondMonitor - family: FluxMonitor - pv: {y: "p01/motor/oh2.28"} - new: true - confirm: true - note: "diamond beam-position / flux monitor insert (oh2_diam_y); a single y insertion axis, role is a candidate FluxMonitor (OPT-1)" - - name: RIXSPreOptic - family: LinearStage - pv: {x: "p01/motor/oh2.04"} - new: true - confirm: true - note: "RIXS pre-optic translation (rixs_x); selects / positions the EH3 spectroscopy branch optic, role and optic kind are OPT-1" - -# =========================================================================== -# EH1: nuclear resonant scattering (high-resolution monochromator stack) -# =========================================================================== - -eh1-sample: - stage: sample - enclosure: p01-eh1 - intro: "The EH1 nuclear-resonant-scattering endstation: the high-resolution monochromator stack that carves the meV / Moessbauer-energy bandwidth, the compound refractive lens focusing, the beam-defining slit, and the sample table." - note: "Four high-resolution monochromators (hrm400 / hrm1064 / hrm3d / hrm3w) are the nested / sapphire backscattering analyzers; which is in beam depends on the isotope and resolution (NRS-1). Handles read from p01/motor/eh1.* and the hrm_ener / hrm_ener2 virtual energy axes." - devices: - - name: HighResMono400 - family: Monochromator - pv: {theta: "p01/motor/eh1.02", tilt: "p01/motor/eh1.01", x: "p01/motor/eh1.04", y: "p01/motor/eh1.03", piezo_theta: "p01/attributemotor/pieh2.49", piezo_tilt: "p01/attributemotor/pieh2.50"} - new: true - confirm: true - note: "high-resolution monochromator, 400 channel-cut (hrm400: theta / tilt / x / y plus piezo fine theta / tilt); the energy-resolution element for one isotope branch (NRS-1)" - - name: HighResMono1064 - family: Monochromator - pv: {theta: "p01/motor/eh1.34", tilt: "p01/motor/eh1.33", x: "p01/motor/eh1.36", y: "p01/motor/eh1.35", piezo_theta: "p01/attributemotor/pieh2.51", piezo_tilt: "p01/attributemotor/pieh2.52"} - new: true - confirm: true - note: "high-resolution monochromator, 1064 channel-cut (hrm1064: theta / tilt / x / y plus piezo fine theta / tilt); a second isotope / resolution branch (NRS-1)" - - name: HighResMono3D - family: Monochromator - pv: {theta: "p01/motor/eh1.47", tilt: "p01/motor/eh1.46", x: "p01/motor/eh1.42", y: "p01/motor/eh1.48"} - new: true - confirm: true - note: "high-resolution monochromator, 3-bounce 'd' configuration (hrm3d); selectable nested HRM branch (NRS-1)" - - name: HighResMono3W - family: Monochromator - pv: {theta: "p01/motor/eh1.44", tilt: "p01/motor/eh1.43", x: "p01/motor/eh1.41", y: "p01/motor/eh1.45"} - new: true - confirm: true - note: "high-resolution monochromator, 3-bounce 'w' configuration (hrm3w); selectable nested HRM branch (NRS-1)" - - name: HighResMonoEnergy - family: PseudoAxis - pv: {hrm_ener: "p01/vmexecutor/hrm_ener", hrm_ener2: "p01/vmexecutor/hrm_ener2"} - new: true - confirm: true - note: "virtual energy axes coupling the HRM theta motions (hrm_ener / hrm_ener2 on vmexecutor); the scanned coordinate for the NRS energy spectrum (NRS-1)" - - name: CompoundRefractiveLens - family: Transfocator - pv: {rotation: "p01/motor/eh1.17", theta: "p01/motor/eh1.18", x: "p01/motor/eh1.19", y: "p01/motor/eh1.20"} - new: true - confirm: true - note: "compound refractive lens focusing assembly (crl2: rot / th / x / y); lens count / material and whether it is a transfocator stack are OPT-1" - - name: BeamDefiningSlit - family: Slit - pv: {bottom: "p01/motor/eh1.05", top: "p01/motor/eh1.06", left: "p01/motor/eh1.07", right: "p01/motor/eh1.08", center_x: "p01/vmexecutor/jjslit_eh1_cx", center_y: "p01/vmexecutor/jjslit_eh1_cy", gap_x: "p01/vmexecutor/jjslit_eh1_dx", gap_y: "p01/vmexecutor/jjslit_eh1_dy"} - new: true - confirm: true - note: "EH1 beam-defining JJ slit (slit2: four blades + cx/cy/dx/dy virtual motors)" - - name: BeamPositionMonitor - family: FluxMonitor - pv: {x: "p01/motor/eh1.21", y: "p01/motor/eh1.22"} - new: true - confirm: true - note: "EH1 beam-position monitor stage (bpm2); a positioning stage for a BPM insert, role is a candidate FluxMonitor (DET-1)" - - name: IonChamber - family: FluxMonitor - pv: {x: "p01/motor/eh1.23", y: "p01/motor/eh1.24"} - new: true - confirm: true - note: "EH1 ion-chamber positioning stage (ic2); flux normalization monitor (DET-1)" - - name: SampleTable - family: Table - pv: {x: "p01/motor/eh1.31", y: "p01/motor/eh1.32"} - new: true - confirm: true - note: "EH1 sample / instrument table (tab1)" - -# =========================================================================== -# EH2: diffraction (two-circle diffractometer + sample + detector) -# =========================================================================== - -eh2-sample: - stage: sample - enclosure: p01-eh2 - intro: "The EH2 diffraction endstation: the theta / two-theta diffractometer, the sample stage, and the beam-defining slits." - note: "Handles read from p01/motor/eh2.*. The diffractometer geometry (number of circles) beyond the th / tth axes in the registry is DIFF-1." - devices: - - name: Goniometer - family: Goniometer # catalog Family; the sample-orientation circle, would compose a Diffractometer Assembly if a detector arm is confirmed (DIFF-1) - pv: {theta: "p01/motor/eh2.49", two_theta: "p01/motor/eh2.37"} - new: true - confirm: true - note: "EH2 sample-orientation goniometer (diff_th / diff_tth); the registry exposes theta and two-theta only. Modeled as a Goniometer Asset, not the composed Diffractometer Assembly, until the full circle count and a detector arm are confirmed (DIFF-1)" - - name: SampleStage - family: LinearStage - pv: {x: "p01/motor/eh2.34", y: "p01/motor/eh2.33", tilt: "p01/motor/eh2.35"} - new: true - confirm: true - note: "EH2 sample positioning / centring stage (sam: x / y / tilt)" - - name: DefiningSlit - family: Slit - pv: {bottom: "p01/motor/eh2.01", top: "p01/motor/eh2.02", left: "p01/motor/eh2.03", right: "p01/motor/eh2.04", center_x: "p01/vmexecutor/jjslit_eh2_cx", center_y: "p01/vmexecutor/jjslit_eh2_cy", gap_x: "p01/vmexecutor/jjslit_eh2_dx", gap_y: "p01/vmexecutor/jjslit_eh2_dy"} - new: true - confirm: true - note: "EH2 beam-defining JJ slit (slit3)" - - name: DetectorSlit - family: Slit - pv: {bottom: "p01/motor/eh2.27", top: "p01/motor/eh2.28", left: "p01/motor/eh2.26", right: "p01/motor/eh2.25", center_x: "p01/vmexecutor/hslit_eh2_cx", center_y: "p01/vmexecutor/hslit_eh2_cy", gap_x: "p01/vmexecutor/hslit_eh2_dx", gap_y: "p01/vmexecutor/hslit_eh2_dy"} - new: true - confirm: true - note: "EH2 detector / receiving slit (dslit)" - - name: DetectorTable - family: Table - pv: {x: "p01/motor/eh2.39", y: "p01/motor/eh2.40"} - new: true - confirm: true - note: "EH2 detector table (tab2)" - -eh2-detector: - stage: detection - enclosure: p01-eh2 - intro: "The EH2 detector positioning stage. The OnlineXML carries the detector carriage axes; the detector device itself (an avalanche photodiode or area detector) is not a motor row and is DET-1." - note: "Handles read from p01/motor/eh2.* (det_x / det_y). The operative detector model is DET-1." - devices: - - name: DetectorStage - family: LinearStage - pv: {x: "p01/motor/eh2.29", y: "p01/motor/eh2.30"} - new: true - confirm: true - note: "EH2 detector positioning stage (det: x / y); the detector device (APD / area detector) is not in the motor registry (DET-1)" - -# =========================================================================== -# EH3: RIXS / KB-focused spectroscopy (KB mirror pair + sample + detectors) -# =========================================================================== - -eh3-sample: - stage: sample - enclosure: p01-eh3 - intro: "The EH3 RIXS endstation: the Kirkpatrick-Baez mirror pair that focuses the beam to the sample, the sample stage, and the beam-defining slit. This is the resonant-inelastic-scattering branch." - note: "Handles read from p01/motor/eh3.*. The KB pair (kb3h horizontal, kb3v vertical) each carry bender (bu / bd), theta, and a second theta; the bend radii and focal sizes are OPT-1." - devices: - - name: KBMirrorHorizontal - family: Mirror - pv: {bend_upstream: "p01/motor/eh3.01", bend_downstream: "p01/motor/eh3.02", theta: "p01/motor/eh3.03", theta2: "p01/motor/eh3.04"} - new: true - confirm: true - note: "horizontal-focusing KB mirror (kb3h: upstream / downstream benders + theta / theta2); bend radius and focal size are OPT-1" - - name: KBMirrorVertical - family: Mirror - pv: {bend_upstream: "p01/motor/eh3.05", bend_downstream: "p01/motor/eh3.06", theta: "p01/motor/eh3.07", theta2: "p01/motor/eh3.08"} - new: true - confirm: true - note: "vertical-focusing KB mirror (kb3v: upstream / downstream benders + theta / theta2); bend radius and focal size are OPT-1" - - name: SampleStage - family: LinearStage - pv: {x: "p01/motor/eh3.31", y: "p01/motor/eh3.30", b: "p01/motor/eh3.28", rotation: "p01/motor/eh3.32", tilt: "p01/motor/eh3.29"} - new: true - confirm: true - note: "EH3 sample stage (samp: x / y / b / rot / tilt); the RIXS sample positioning and rotation (SAMPLE-1)" - - name: DetectorSlit - family: Slit - pv: {bottom: "p01/motor/eh3.47", top: "p01/motor/eh3.48", left: "p01/motor/eh3.46", right: "p01/motor/eh3.45", center_x: "p01/vmexecutor/hslit_eh3_cx", center_y: "p01/vmexecutor/hslit_eh3_cy", gap_x: "p01/vmexecutor/hslit_eh3_dx", gap_y: "p01/vmexecutor/hslit_eh3_dy"} - new: true - confirm: true - note: "EH3 detector / receiving slit (dslit)" - - name: InstrumentTable - family: Table - pv: {x: "p01/vmexecutor/eh3_tab2_x", x1: "p01/motor/eh3.37", x2: "p01/motor/eh3.38", y: "p01/vmexecutor/eh3_tab2_y", y1: "p01/motor/eh3.34", y2: "p01/motor/eh3.35", y3: "p01/motor/eh3.36"} - new: true - confirm: true - note: "EH3 instrument / spectrometer table (tab4: virtual x / y over x1/x2 and y1/y2/y3 jacks)" - -eh3-detector: - stage: detection - enclosure: p01-eh3 - intro: "The EH3 detector positioning stages: the main RIXS detector carriage and a secondary detector arm. The detector devices themselves are not motor rows (DET-1)." - note: "Handles read from p01/motor/eh3.* (det / det16). The operative RIXS detector model is DET-1." - devices: - - name: DetectorStage - family: LinearStage - pv: {theta: "p01/motor/eh3.44", x: "p01/motor/eh3.42", y: "p01/motor/eh3.43"} - new: true - confirm: true - note: "EH3 main detector positioning stage (det: theta / x / y); the detector device is not in the motor registry (DET-1)" - - name: SecondaryDetectorStage - family: LinearStage - pv: {theta: "p01/motor/eh3.25", x: "p01/motor/eh3.26", y: "p01/motor/eh3.27"} - new: true - confirm: true - note: "EH3 secondary detector arm stage (det16: theta / x / y); role / detector is DET-1" - -# Cross-cutting control. P01 runs Tango with Sardana as the scan layer; this is -# CORA's second Tango / Sardana deployment (after MAX IV) and a sibling of ESRF BLISS. -controls: - intro: > - P01 runs on the PETRA III control system, which is Tango with Sardana as the - scan / motion SCADA layer, NOT EPICS. This is CORA's second Tango / Sardana - control floor (after MAX IV) and a sibling of the ESRF BLISS / Tango floor: the - seam model that today reads "EPICS is the floor" generalizes here to "Tango / - Sardana is the floor". In this stack a motion axis is a Tango motor device - addressed by domain/family/member (p01/motor/.), a virtual / coupled - axis is a vmexecutor or attributemotor device, and a scan is a Sardana macro run - by the MacroServer over a Pool of controllers, with the MeasurementGroup defining - the acquired channels. The handles in this descriptor are read from P01's public - OnlineXML registry and carried confirm (CTRL-1). The NRS / RIXS acquisition (the - high-resolution-monochromator energy scan or the KB-focused spectrometer scan, - coupled to the detector readout) runs as a Sardana macro; that orchestration is - the seam CORA's edge would conduct over its ControlPort, driving through or - replacing the Sardana macro per routine (CTRL-2). - motion_controllers: - - name: OMS58Controllers - family: MotionController - protocol: Tango_oms58 - new: true - confirm: true - note: "OMS MAXv-58 stepper motor controllers (Tango module oms58); the dominant P01 motor controller, fleet-wide the most common PETRA III motor class (CTRL-1)" - - name: TangoMotorControllers - family: MotionController - protocol: Tango_motor_tango - new: true - confirm: true - note: "generic Tango motor controllers (module motor_tango) backing the dcm and virtual-axis devices (CTRL-1)" - - name: VirtualMotorExecutors - family: MotionController - protocol: Tango_vmexecutor - new: true - confirm: true - note: "Sardana virtual-motor executors (vmexecutor) computing the coupled energy / slit-center-gap pseudo axes (CTRL-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a P01 run needs present before it - can start. All pending confirmation. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/p02/beamline.yaml b/deployments/p02/beamline.yaml deleted file mode 100644 index a44b73629f4..00000000000 --- a/deployments/p02/beamline.yaml +++ /dev/null @@ -1,249 +0,0 @@ -# P02 beamline descriptor (PETRA III, DESY), reverse-engineered from the OnlineXML -# -# P02 "Hard X-ray Diffraction Beamline" is the high-energy diffraction beamline at -# PETRA III (DESY, Hamburg), with two branches: P02.1 (powder diffraction / total -# scattering / pair-distribution-function, ~60 keV) and P02.2 (extreme conditions, -# diamond-anvil-cell high-pressure diffraction). It is bound to the PETRA III Site -# (deployments/petra-iii/site.yaml), the eighth PETRA III beamline. -# -# STATUS: reverse-engineered from P02's own public OnlineXML device registry -# (gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p02, branch -# debian/jessie; the online_haspp02* registries). Device logical names and Tango -# control handles are real, read from that registry; vendor part numbers, crystal -# cuts, the pressure-cell detail, energy calibration, and physical positions are not -# in it and are open questions. Every value is carried confirm until P02 staff verify -# it. The extraction is in the xmap/research repo (private), under petra-iii/. -# -# WHAT IS NEW: no new device Family. P02 reuses existing Families end to end. It is -# the fleet's high-energy powder-diffraction / total-scattering beamline and its first -# diamond-anvil-cell extreme-conditions endstation; the high-pressure cell binds the -# catalog PressureCell Family (graduated across APS 13-id and P02). The -# techniques (powder diffraction, total scattering / PDF, high-pressure diffraction) -# earn no catalog Method beyond the existing powder_diffraction / total_scattering -# slugs, carried pending on the Site (TECH-1). -# -# CONTROL HANDLES: the descriptor `pv` field carries the Tango device address read -# from the OnlineXML (e.g. p02/dcmmotor/dcm_bragg). The registry exposes large -# generically-named motor banks (eh1a / eh1b / eh2a / eh2b) whose per-axis roles are -# not labelled; the eh1* banks are the P02.1 powder branch and the eh2* banks the -# P02.2 extreme-conditions branch, grouped as the endstation stages carrying the -# handles, every axis role pending (GROUP-1). The bendable focusing mirrors (HFM / -# VFM) are exposed as attribute motors (curvature / ellipticity / tilt / z) plus their -# gp variants; grouped as two Mirror Assets (OPT-1). -# -# SCOPE: this cut models the shared OH1 optics (the DCM, the HFM / VFM mirrors, the -# slits, the CRL), the P02.1 powder / total-scattering endstation (eh1a / eh1b), and -# the P02.2 extreme-conditions endstation (eh2a / eh2b) with their sample stages, -# pressure cell, sample environment, and detectors (Pilatus 1M, PerkinElmer, MCA / -# SIS3302). The CH1 / CH2 dummy-motor stubs are noted, not modelled (STUB-1). Counter -# / timer / ADC channels and the Sardana MeasurementGroup bookkeeping rows are -# filtered out by the extractor. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/p02/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "high-energy hard X-ray diffraction: P02.1 powder diffraction / total scattering / PDF (~60 keV) + P02.2 extreme conditions (diamond-anvil-cell high-pressure diffraction); the fleet's second diamond-anvil-cell deployment (binds the catalog `PressureCell`, graduated across 13-ID and P02), bendable HFM / VFM mirrors, coins no new Family, reusing the pending `powder_diffraction` / `total_scattering` Methods" - name: P02 - facility: petra-iii # PETRA III Site (facility_code: petra-iii) - sector: "P02" - tier: Unit - parent: null - source: insertion-device - source_confirm: "P02 is an undulator beamline (high-energy diffraction); the OnlineXML exposes the undulator gap (p02/attributemotor/gap) but no period or parameters, carried pending (SRC-1)" - page_layout: stages - shape: "Hard X-ray powder diffraction and total scattering (P02.1) and a diffraction / absorption branch (P02.2), on the PETRA III Tango / Sardana floor." - source_ref: - label: "python-nxstools-extras-p02" - url: "https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p02" - -# Three enclosures: the shared OH1 optics, the P02.1 powder / total-scattering -# endstation, and the P02.2 extreme-conditions endstation. The optics and both -# endstations report on the haspp02oh1 host; the split is inferred from the device- -# name prefixes (ENC-1). DESY PSS permit signals are not in the OnlineXML (PSS-1). -enclosures: - - name: p02-oh1 - role: optics-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the P02 OH1 optics (shared P02 / P03 high-heatload optics); not in the OnlineXML (PSS-1)"} - - name: p02-1-powder - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the P02.1 powder / total-scattering endstation; not in the OnlineXML (PSS-1)"} - - name: p02-2-extreme - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the P02.2 extreme-conditions endstation; not in the OnlineXML (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the undulator and the OH1 optics -# =========================================================================== - -source: - stage: source - enclosure: p02-oh1 - intro: "The P02 undulator source and the OH1 optics: the double-crystal monochromator, the horizontal- and vertical-focusing bendable mirrors, the defining slits, and the CRL. P02 shares the high-heatload optics hutch with P03." - note: "DCM is dcmmotor (bragg / parallel / perp) + dcmener. The HFM / VFM mirrors are bendable, exposed as curvature / ellipticity / tilt / z attribute motors. The OH1 p02/motor bank carries the optics positioning, roles not labelled (GROUP-1)." - devices: - - name: Undulator - family: InsertionDevice - pv: {gap: "p02/attributemotor/gap"} - new: true - confirm: true - note: "P02 undulator; gap read from the registry, period not exposed (SRC-1)" - - name: Monochromator - family: Monochromator - pv: {bragg: "p02/dcmmotor/dcm_bragg", parallel: "p02/dcmmotor/dcm_parallel", perpendicular: "p02/dcmmotor/dcm_perp", energy: "p02/dcmener/mnchrmtr", c2pitch: "p02/motor/c2pitch", c2roll: "p02/motor/c2roll"} - new: true - confirm: true - note: "double-crystal monochromator (dcm_bragg / parallel / perp + the c2 crystal pitch / roll); ~60 keV high-energy, crystal cut is OPT-1" - - name: HorizontalFocusingMirror - family: Mirror - pv: {curvature: "p02/attributemotor/hfm_curvature", ellipticity: "p02/attributemotor/hfm_ellipticity", tilt: "p02/attributemotor/hfm_tilt", z: "p02/attributemotor/hfm_z", gp_curvature: "p02/attributemotor/hfm_gp_curvature", gp_ellipticity: "p02/attributemotor/hfm_gp_ellipticity", gp_tilt: "p02/attributemotor/hfm_gp_tilt", gp_z: "p02/attributemotor/hfm_gp_z"} - new: true - confirm: true - note: "horizontal-focusing bendable mirror (HFM: curvature / ellipticity / tilt / z, with gp glancing-pencil variants); coating / role OPT-1" - - name: VerticalFocusingMirror - family: Mirror - pv: {curvature: "p02/attributemotor/vfm_curvature", ellipticity: "p02/attributemotor/vfm_ellipticity", tilt: "p02/attributemotor/vfm_tilt", z: "p02/attributemotor/vfm_z", gp_curvature: "p02/attributemotor/vfm_gp_curvature", gp_ellipticity: "p02/attributemotor/vfm_gp_ellipticity", gp_tilt: "p02/attributemotor/vfm_gp_tilt", gp_z: "p02/attributemotor/vfm_gp_z"} - new: true - confirm: true - note: "vertical-focusing bendable mirror (VFM: curvature / ellipticity / tilt / z, with gp variants); coating / role OPT-1" - - name: DefiningSlits - family: Slit - pv: {slt1_vgap: "p02/slt/slt1vgap", slt1_voffs: "p02/slt/slt1voffs", slt1_offs: "p02/slt/slt1offs", slt2_left: "p02/slt/slt2left", slt2_right: "p02/slt/slt2right", slt2_vgap: "p02/slt/slt2vgap", slt2_offs: "p02/slt/slt2offs"} - new: true - confirm: true - note: "the OH1 defining slits (slt1 vertical + slt2 four-blade); beam definition (OPT-1)" - - name: OpticsStages - family: LinearStage - pv: {bank: "p02/motor/c2pitch"} - new: true - confirm: true - note: "the OH1 optics / instrument motor bank (p02/motor, the c2 / mirror / slit positioning); per-axis roles not labelled, grouped as one stage (OPT-1, GROUP-1)" - -# =========================================================================== -# P02.1: powder diffraction / total scattering endstation -# =========================================================================== - -powder-sample: - stage: sample - enclosure: p02-1-powder - intro: "The P02.1 powder-diffraction / total-scattering endstation: the sample positioning and instrument motor banks (eh1a / eh1b), with the Anton-Paar and Lakeshore sample-environment controllers for in-situ temperature studies." - note: "The eh1a (48 axes) and eh1b (16 axes) banks carry the P02.1 sample / instrument positioning, roles not labelled (GROUP-1). The Anton-Paar (eurotherm2604) and Lakeshore 336 are the in-situ sample environment." - devices: - - name: SampleStage - family: LinearStage - pv: {eh1a: "p02/motor/eh1a_mot01", eh1b: "p02/motor/eh1b_mot01"} - new: true - confirm: true - note: "the P02.1 sample / instrument motor banks (eh1a_mot01..48, eh1b_mot01..16 on p02/motor); per-axis roles not labelled, grouped as one stage (GROUP-1)" - - name: SampleEnvironment - family: TemperatureController - pv: {anton_paar: "p02/eurotherm2604/antonpaar", eurotherm: "p02/eurotherm2408/eurotherm", lakeshore: "p02/lks336tempctrl/lake336"} - new: true - confirm: true - note: "the P02.1 in-situ sample environment: the Anton-Paar furnace (Eurotherm 2604), a Eurotherm 2408, and a Lakeshore 336 cryo controller (TEMP-1)" - -powder-detector: - stage: detection - enclosure: p02-1-powder - intro: "The P02.1 detection: the Pilatus 1M area detector for powder / total-scattering patterns and the PerkinElmer flat-panel for high-energy PDF." - note: "Handles read from p02/pilatus and p02/pedetector. The detector roles (the high-Q PDF detector vs the powder ring detector) are DET-1." - devices: - - name: PilatusDetector - family: Camera - pv: {pilatus_1m: "p02/pilatus/pilatus1M"} - new: true - confirm: true - note: "the P02.1 Pilatus 1M area detector; powder / total-scattering patterns (DET-1)" - - name: PerkinElmerDetector - family: Camera - pv: {detector: "p02/pedetector/exp.01"} - new: true - confirm: true - note: "the P02.1 PerkinElmer flat-panel area detector; high-energy total-scattering / PDF (DET-1)" - -# =========================================================================== -# P02.2: extreme-conditions (diamond-anvil-cell) endstation -# =========================================================================== - -extreme-sample: - stage: sample - enclosure: p02-2-extreme - intro: "The P02.2 extreme-conditions endstation: the sample positioning and instrument motor banks (eh2a / eh2b), the diamond-anvil-cell high-pressure environment, and the CAEN-ELS picoammeter for beam monitoring." - note: "The eh2a (76 axes) and eh2b (64 axes) banks carry the P02.2 sample / instrument positioning, including the diamond-anvil-cell stages, roles not labelled (GROUP-1). The pressure cell binds the catalog PressureCell Family (PRESSURE-1)." - devices: - - name: SampleStage - family: LinearStage - pv: {eh2a: "p02/motor/eh2a_mot01", eh2b: "p02/motor/eh2b_mot01"} - new: true - confirm: true - note: "the P02.2 sample / instrument motor banks (eh2a_mot01..76, eh2b_mot01..64 on p02/motor); per-axis roles not labelled, grouped as one stage (GROUP-1)" - - name: PressureCell - family: PressureCell - pv: {confirm: "diamond-anvil-cell high-pressure sample environment; the membrane / gas-loading control handles are not separately labelled in the registry (PRESSURE-1)"} - new: true - confirm: true - note: "the P02.2 diamond-anvil-cell high-pressure environment; binds the catalog PressureCell Family; the membrane / load control is not in the registry (PRESSURE-1)" - - name: BeamMonitor - family: FluxMonitor - pv: {picoammeter: "p02/caenelsah501d/a501d"} - new: true - confirm: true - note: "the P02.2 CAEN-ELS AH501D picoammeter; beam-intensity monitoring (DET-1)" - -extreme-detector: - stage: detection - enclosure: p02-2-extreme - intro: "The P02.2 detection: the MCA and SIS3302 fluorescence detectors for the extreme-conditions endstation." - note: "Handles read from p02/mca and p02/sis3302. The high-pressure diffraction area detector is shared / not separately listed in this registry slice (DET-1)." - devices: - - name: FluorescenceDetectors - family: EnergyDispersiveSpectrometer - pv: {mca01: "p02/mca/eh2a_mca01", mca02: "p02/mca/eh2a_mca02", mca03: "p02/mca/eh2a_mca03", mca04: "p02/mca/eh2a_mca04", sis3302: "p02/sis3302/SIS3302_1"} - new: true - confirm: true - note: "the P02.2 MCA and SIS3302 fluorescence detectors (DET-1)" - -# Cross-cutting control. P02 runs Tango with Sardana, the PETRA III house style. -controls: - intro: > - P02 runs on the PETRA III control system, Tango with Sardana as the scan / motion - SCADA layer, the same floor as the other PETRA III beamlines. A motion axis is a - Tango motor device (p02/motor/...), the monochromator a dcmmotor / dcmener device, - the bendable mirrors attributemotor devices (curvature / ellipticity), the slits - slt devices, the detectors pilatus / pedetector / mca / sis3302 device servers, the - sample environment eurotherm / lks336tempctrl devices, and the beam monitor a - caenelsah501d picoammeter. The handles are read from P02's public OnlineXML - registry and carried confirm (CTRL-1). P02 shares the high-heatload optics hutch - with P03 (the haspp02oh1 host). The powder / total-scattering / high-pressure - acquisition (the sample scan coupled to the area-detector capture) runs as a - Sardana macro; that orchestration is the seam CORA's edge would conduct over its - ControlPort (CTRL-2). - motion_controllers: - - name: OMS58Controllers - family: MotionController - protocol: Tango_oms58 - new: true - confirm: true - note: "OMS MAXv-58 stepper controllers (oms58) driving the optics and sample motor banks (CTRL-1)" - - name: TangoMotorControllers - family: MotionController - protocol: Tango_motor_tango - new: true - confirm: true - note: "generic Tango motor controllers (motor_tango / tangomotor) backing the mono, the bendable-mirror attribute motors, and the CH dummy stubs (CTRL-1, STUB-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a P02 run needs present before it - can start. All pending confirmation. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/p03/beamline.yaml b/deployments/p03/beamline.yaml deleted file mode 100644 index ffad04cf477..00000000000 --- a/deployments/p03/beamline.yaml +++ /dev/null @@ -1,337 +0,0 @@ -# P03 beamline descriptor (PETRA III, DESY), reverse-engineered from the OnlineXML -# -# P03 "MiNaXS" (Micro- and Nanofocus Small-Angle X-ray Scattering) is the SAXS / WAXS -# beamline at PETRA III (DESY, Hamburg), 9-23 keV, with a microfocus endstation and a -# nanofocus GINIX endstation. It is bound to the PETRA III Site -# (deployments/petra-iii/site.yaml), the fifth PETRA III beamline after P01, P04, P06, -# P11, and the fleet's entry into small-angle scattering. -# -# STATUS: reverse-engineered from P03's own public OnlineXML device registry -# (gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p03, branch -# debian/jessie; the online_haspp03.xml microfocus and online_haspp03nano.xml -# nanofocus registries). Device logical names and Tango control handles are real, read -# from that registry; vendor part numbers, focal sizes, energy calibration, and -# physical positions are not in it and are open questions. Every value is carried -# confirm until P03 staff verify it. The extraction is in the xmap/research repo (private), under petra-iii/. -# -# WHAT IS NEW: no new device Family. P03 reuses existing Families end to end, but it is -# the fleet's first SAXS / WAXS beamline and brings a two-endstation layout (microfocus -# + nanofocus GINIX) and several new Tango motion-controller protocols (Galil DMC slit -# controllers, SmarPod controllers). The technique (small-angle / wide-angle X-ray -# scattering) earns no catalog Method; it is carried pending on the Site reusing the -# diffraction slug (TECH-1). -# -# CONTROL HANDLES: the descriptor `pv` field carries the Tango device address read -# from the OnlineXML (e.g. p03/pilatus/300k). P03 shares the high-heatload optics with -# P02: the first defining slit reports on the P02 optics host (haspp02oh1); per the -# cross-host mapping decision it is homed in the P03 shared-optics enclosure with the -# host flagged (HOST-1). The registry exposes generically-named motor banks -# (expmi_mot01..64 at the microfocus endstation, mot01..40 at the nanofocus -# endstation) whose per-axis roles are not labelled; these are grouped as the sample / -# instrument stages of their endstation carrying the handles, every axis role pending -# (GROUP-1). -# -# SCOPE: this cut models the shared optics (the multilayer monochromator, the two -# mirrors, the defining slits, the CRL focusing) and the two endstations (the P03 -# microfocus and the P03-NANO GINIX nanofocus) with their sample stages, hexapods, and -# detectors (Pilatus 300k / 1M, MCA / XIA fluorescence). Counter / timer / ADC channels -# and the Sardana MeasurementGroup bookkeeping rows are filtered out by the extractor. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/p03/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "micro- and nanofocus small- and wide-angle X-ray scattering (SAXS / WAXS, 9-23 keV) across shared P02 / P03 optics and two endstations (a microfocus endstation and the nanofocus GINIX waveguide endstation); PETRA III's first SAXS / WAXS beamline, coins no new Family, brings Galil DMC and SmarPod controllers, reusing the pending `small_angle_scattering` / `wide_angle_scattering` Methods" - name: P03 - facility: petra-iii # PETRA III Site (facility_code: petra-iii) - sector: "P03" - tier: Unit - parent: null - source: insertion-device - source_confirm: "P03 is an undulator beamline (SAXS / WAXS, 9-23 keV); the OnlineXML exposes an undulator gap virtual axis (p03/attributemotor/gap) but no period or parameters, carried pending (SRC-1)" - page_layout: stages - shape: "Small- and wide-angle scattering with a micro / nano focus branch (MiNaXS): SAXS / WAXS and GISAXS off films and interfaces." - source_ref: - label: "python-nxstools-extras-p03" - url: "https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p03" - -# Three enclosures: the shared optics (P03 shares the high-heatload optics with P02), -# the microfocus endstation, and the nanofocus GINIX endstation. The first defining -# slit reports on the P02 optics host (HOST-1). DESY PSS permit signals are not in the -# OnlineXML (PSS-1). -enclosures: - - name: p03-optics - role: optics-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the P03 (shared P02 / P03) optics; not in the OnlineXML (PSS-1)"} - - name: p03-microfocus - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the microfocus endstation; not in the OnlineXML (PSS-1)"} - - name: p03-nanofocus - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the nanofocus GINIX endstation; not in the OnlineXML (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the undulator and the shared conditioning optics -# =========================================================================== - -source: - stage: source - enclosure: p03-optics - intro: "The P03 undulator source and the shared conditioning optics: a multilayer monochromator, two mirrors, and the defining slits. P03 shares the high-heatload optics with P02." - note: "The undulator gap is a p03/attributemotor virtual axis. The first defining slit reports on the P02 optics host (haspp02oh1, HOST-1)." - devices: - - name: Undulator - family: InsertionDevice - pv: {gap: "p03/attributemotor/gap"} - new: true - confirm: true - note: "P03 undulator; gap read from the registry, period not exposed (SRC-1)" - - name: Monochromator - family: Monochromator - pv: {pitch1: "p03/lom/exp.01", roll1: "p03/lom/exp.02", pitch2: "p03/lom/exp.03", lateral2: "p03/lom/exp.04", hub2: "p03/lom/exp.05", hub1: "p03/lom/exp.06", linear2: "p03/lom/exp.07", screen: "p03/lom/exp.08", table_height: "p03/lom/exp.09", table_pitch: "p03/lom/exp.10", table_roll: "p03/lom/exp.11", energy: "p03/lomenergy/exp.01"} - new: true - confirm: true - note: "multilayer monochromator (lom: two-bounce pitch / roll / hub / lateral plus the table jacks and the coupled lomenergy axis), 9-23 keV; multilayer d-spacing is OPT-1" - - name: Mirror1 - family: Mirror - pv: {pitch: "p03/spk/exp.07", translation_x: "p03/spk/exp.08", table: "p03/spk/exp.09"} - new: true - confirm: true - note: "first mirror (m1: pitch / transx / table, SmarPod-style spk controller); coating / role OPT-1" - - name: Mirror2 - family: Mirror - pv: {pitch: "p03/spk/exp.10", translation_x: "p03/spk/exp.11", table: "p03/spk/exp.12"} - new: true - confirm: true - note: "second mirror (m2: pitch / transx / table); coating / role OPT-1" - - name: DefiningSlit1 - family: Slit - pv: {v_gap: "p03/slt/exp.01", v_offset: "p03/slt/exp.02"} - new: true - confirm: true - note: "first defining slit (slt1: vertical gap / offset); reports on the P02 optics host (haspp02oh1, HOST-1)" - - name: DefiningSlit2 - family: Slit - pv: {left: "p03/slt/exp.03", right: "p03/slt/exp.04", offset: "p03/slt/exp.05", v_gap: "p03/slt/exp.06"} - new: true - confirm: true - note: "second defining slit (slt2: horizontal blades + vertical gap / offset)" - - name: QuadrantBPMs - family: FluxMonitor - pv: {eh1: "p03/i404/exp.01", oh1: "p03/i404/oh.01"} - new: true - confirm: true - note: "the optics-hutch and experiment-hutch quadrant beam-position monitors (i404 electrometers)" - -# =========================================================================== -# P03 MICROFOCUS ENDSTATION -# =========================================================================== - -microfocus-sample: - stage: sample - enclosure: p03-microfocus - intro: "The microfocus endstation: the CRL focusing hexapod and z-stage, the Galil-controlled guard slit, the slit4, and the sample / instrument motor bank." - note: "The CRL is positioned by a six-axis hexapod (crl1hex) plus a z-stage (CRL1_Z). The expmi_mot01..64 bank carries the sample / instrument positioning, roles not labelled (GROUP-1)." - devices: - - name: CRLHexapod - family: Hexapod - pv: {u: "p03/hexapodmotor/crl1hex_u", v: "p03/hexapodmotor/crl1hex_v", w: "p03/hexapodmotor/crl1hex_w", x: "p03/hexapodmotor/crl1hex_x", y: "p03/hexapodmotor/crl1hex_y", z: "p03/hexapodmotor/crl1hex_z"} - new: true - confirm: true - note: "the microfocus CRL focusing hexapod (crl1hex, six axes) plus the CRL z-stage (CRL1_Z on p03/motor); the compound-refractive-lens positioning (OPT-1)" - - name: GuardSlit - family: Slit - pv: {bottom: "p03/galildmcslit/G1Bottom", top: "p03/galildmcslit/G1Top", left: "p03/galildmcslit/G1Left", right: "p03/galildmcslit/G1Right", cx: "p03/galildmcslit/G1Cx", cy: "p03/galildmcslit/G1Cy", dx: "p03/galildmcslit/G1Dx", dy: "p03/galildmcslit/G1Dy"} - new: true - confirm: true - note: "the microfocus guard slit (G1, Galil DMC slit controller: blades + center / gap virtual axes); the SAXS beam-defining / guard slit (OPT-1)" - - name: BeamlineSlit4 - family: Slit - pv: {x: "p03/motor/S4_X", y: "p03/motor/S4_Y", z: "p03/motor/S4_Z"} - new: true - confirm: true - note: "slit4 positioning (S4_X / Y / Z); a defining / scatter slit (OPT-1)" - - name: SampleStage - family: LinearStage - pv: {bank: "p03/motor/expmi_mot01"} - new: true - confirm: true - note: "the microfocus sample / instrument motor bank (expmi_mot01..64 on p03/motor); per-axis roles not labelled, grouped as one stage carrying the bank prefix (GROUP-1)" - - name: SampleTemperature - family: TemperatureController - pv: {eurotherm: "p03/eurotherm2604/01"} - new: true - confirm: true - note: "the sample-environment Eurotherm 2604 temperature controller (TEMP-1)" - -microfocus-detector: - stage: detection - enclosure: p03-microfocus - intro: "The microfocus detection: the Pilatus 300k and 1M area detectors for SAXS / WAXS, plus the MCA and XIA fluorescence detectors." - note: "Handles read from p03/pilatus, p03/mca, p03/XIA. The SAXS-to-WAXS detector roles and the sample-to-detector distance are DET-1. The Lambda detector (petra3/lambda/01) reports on a bare petra3 host (HOST-1)." - devices: - - name: PilatusDetectors - family: Camera - pv: {pilatus_300k: "p03/pilatus/300k", pilatus_1M: "p03/pilatus/1M"} - new: true - confirm: true - note: "the microfocus Pilatus 300k and 1M area detectors; SAXS / WAXS scattering imaging (DET-1)" - - name: LambdaDetector - family: Camera - pv: {lambda: "petra3/lambda/01"} - new: true - confirm: true - note: "an X-Spectrum Lambda area detector; reports on the petra3 host (HOST-1, DET-1)" - - name: FluorescenceDetectors - family: EnergyDispersiveSpectrometer - pv: {mca01: "p03/mca/exp.01", mca02: "p03/mca/exp.02", mca03: "p03/mca/exp.03", mca04: "p03/mca/exp.04", xia01: "p03/XIA/p03.1", xia02: "p03/XIA/exp.2", xia03: "p03/XIA/exp.3", xia04: "p03/XIA/exp.4"} - new: true - confirm: true - note: "the microfocus MCA and XIA multi-channel-analyzer fluorescence detectors (DET-1)" - -# =========================================================================== -# P03-NANO ENDSTATION: GINIX nanofocus -# =========================================================================== - -nanofocus-sample: - stage: sample - enclosure: p03-nanofocus - intro: "The nanofocus GINIX endstation: a SmarPod hexapod and a second hexapod / cube stage for the waveguide and sample, a Smaract sample rotation, the waveguide linear stages, the Galil guard slit, and the sample motor bank, with LED illumination and a viewing camera." - note: "The GINIX (Goettingen Instrument for Nano-Imaging with X-rays) uses a SmarPod (hexa3) for the waveguide, a hexapod / cube (hexa2 / cube1) for the sample, and a Smaract phi / x rotation. The mot01..40 bank carries the sample positioning, roles not labelled (GROUP-1)." - devices: - - name: WaveguideSmarPod - family: Hexapod - pv: {x: "p03nano/smarpodmotor/hexa3_motX", y: "p03nano/smarpodmotor/hexa3_motY", z: "p03nano/smarpodmotor/hexa3_motZ", rx: "p03nano/smarpodmotor/hexa3_motRX", ry: "p03nano/smarpodmotor/hexa3_motRY", rz: "p03nano/smarpodmotor/hexa3_motRZ"} - new: true - confirm: true - note: "the GINIX waveguide SmarPod (hexa3, six axes); positions the nano-focusing waveguide (OPT-1)" - - name: SampleHexapod - family: Hexapod - pv: {u: "p03nano/hexapodmotor/hexa2_motU", v: "p03nano/hexapodmotor/hexa2_motV", w: "p03nano/hexapodmotor/hexa2_motW", x: "p03nano/hexapodmotor/hexa2_motX", cube_x: "p03nano/hexapodmotor/cube1_motX", cube_z: "p03nano/hexapodmotor/cube1_motZ"} - new: true - confirm: true - note: "the GINIX sample hexapod (hexa2) plus the cube stage (cube1); coarse sample positioning (SAMPLE-1)" - - name: SampleRotation - family: RotaryStage - pv: {phi: "p03nano/smaractmotor/ROT_PHI", x: "p03nano/smaractmotor/ROT_X"} - new: true - confirm: true - note: "the GINIX sample rotation (ROT_PHI / ROT_X, Smaract); the nano-tomography / scanning rotation (SAMPLE-1)" - - name: WaveguideLinearStages - family: LinearStage - pv: {lls1: "p03nano/attributemotor/LLS1", lls2: "p03nano/attributemotor/LLS2"} - new: true - confirm: true - note: "the GINIX waveguide linear stages (LLS1 / LLS2, attributemotor virtual axes) (OPT-1)" - - name: GuardSlit - family: Slit - pv: {cx: "p03nano/galildmcslit/S6_CX", cy: "p03nano/galildmcslit/S6_CY", dx: "p03nano/galildmcslit/S6_DX", dy: "p03nano/galildmcslit/S6_DY"} - new: true - confirm: true - note: "the nanofocus guard slit (S6, Galil DMC slit controller: center / gap virtual axes) (OPT-1)" - - name: SampleStage - family: LinearStage - pv: {bank: "p03nano/motor/mot01"} - new: true - confirm: true - note: "the nanofocus sample / instrument motor bank (mot01..40 on p03nano/motor); per-axis roles not labelled, grouped as one stage (GROUP-1)" - - name: SampleIllumination - family: Camera - pv: {led01: "p03nano/led/exp.01", led02: "p03nano/led/exp.02", camera: "p03/pscameravhr/nano.01"} - new: true - confirm: true - note: "the GINIX sample LED illumination and the PS-camera-VHR viewing camera for sample centring (DET-1)" - -nanofocus-detector: - stage: detection - enclosure: p03-nanofocus - intro: "The nanofocus detection: the Pilatus area detector for the nano-imaging / scattering signal, the MCA fluorescence detectors, and the experiment shutter." - note: "Handles read from p03nano/pilatus, p03nano/mca. The detector roles and the GINIX imaging geometry are DET-1." - devices: - - name: PilatusDetector - family: Camera - pv: {pilatus: "p03nano/pilatus/300k"} - new: true - confirm: true - note: "the nanofocus Pilatus 300k area detector; nano-imaging / scattering (DET-1)" - - name: FluorescenceDetectors - family: EnergyDispersiveSpectrometer - pv: {mca01: "p03nano/mca/p03nano.01", mca02: "p03nano/mca/p03nano.02", mca03: "p03nano/mca/p03nano.03", mca04: "p03nano/mca/p03nano.04", mcatest: "p03nano/sis3302new/exp.01"} - new: true - confirm: true - note: "the nanofocus MCA fluorescence detectors (and a SIS3302 digitizer) (DET-1)" - - name: ExperimentShutter - family: Shutter - pv: {shutter: "p03nano/shutter/exp.01"} - new: true - confirm: true - note: "the nanofocus experiment / fast shutter (the GINIX exposure shutter, role pending PSS-1 / DET-1)" - -# Cross-cutting control. P03 runs Tango with Sardana, the PETRA III house style. -controls: - intro: > - P03 runs on the PETRA III control system, Tango with Sardana as the scan / motion - SCADA layer, the same floor as P01, P04, P06, and P11. P03 brings two motion- - controller protocols new to the PETRA III set CORA models: Galil DMC slit - controllers (galildmcslit, the guard slits) and SmarPod controllers (smarpodmotor, - the GINIX waveguide), alongside the OMS steppers, hexapod, Smaract, and SmarPod- - style spk controllers. A motion axis is a Tango motor device - (p03/motor/... or p03nano/motor/...), the monochromator a lom device, the mirrors - spk devices, the detectors pilatus / mca / XIA / lambda device servers. The - handles are read from P03's public OnlineXML registry and carried confirm (CTRL-1). - The SAXS / WAXS acquisition (the sample scan coupled to the Pilatus frame capture) - runs as a Sardana macro; that orchestration is the seam CORA's edge would conduct - over its ControlPort (CTRL-2). - motion_controllers: - - name: OMS58Controllers - family: MotionController - protocol: Tango_oms58 - new: true - confirm: true - note: "OMS MAXv-58 stepper controllers (oms58) driving the sample / instrument motor banks (CTRL-1)" - - name: GalilSlitControllers - family: MotionController - protocol: Tango_galildmcslit - new: true - confirm: true - note: "Galil DMC slit controllers (galildmcslit) driving the microfocus and nanofocus guard slits (CTRL-1)" - - name: SmarPodControllers - family: MotionController - protocol: Tango_smarpodmotor - new: true - confirm: true - note: "SmarPod controllers (smarpodmotor) driving the GINIX waveguide hexapod (CTRL-1)" - - name: HexapodControllers - family: MotionController - protocol: Tango_hexapod - new: true - confirm: true - note: "hexapod controllers (hexapodmotor) driving the CRL and GINIX sample hexapods (CTRL-1)" - - name: SmarActControllers - family: MotionController - protocol: Tango_smaract - new: true - confirm: true - note: "SmarAct controllers (smaractmotor) driving the GINIX sample rotation (CTRL-1)" - - name: TangoMotorControllers - family: MotionController - protocol: Tango_motor_tango - new: true - confirm: true - note: "generic Tango motor controllers (motor_tango / spk) backing the mono, mirrors, and coupled axes (CTRL-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a P03 run needs present before it - can start. All pending confirmation. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/p04/beamline.yaml b/deployments/p04/beamline.yaml deleted file mode 100644 index d27cea9992c..00000000000 --- a/deployments/p04/beamline.yaml +++ /dev/null @@ -1,279 +0,0 @@ -# P04 beamline descriptor (PETRA III, DESY), reverse-engineered from the OnlineXML -# -# P04 "Variable Polarization XUV Beamline" is the soft X-ray spectroscopy beamline -# at PETRA III (DESY, Hamburg), 250-3000 eV, fed by an APPLE-II-type variable- -# polarization undulator through a plane-grating monochromator. It is bound to the -# PETRA III Site (deployments/petra-iii/site.yaml), the second PETRA III beamline -# after P01, and the fleet's entry into the soft X-ray / grating-monochromator regime. -# -# STATUS: reverse-engineered from P04's own public OnlineXML device registry -# (gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p04, branch -# debian/jessie; the xml/online_haspp04exp{1,2}.xml per-endstation Tango device -# registries). Device logical names and Tango control handles are real, read from -# that registry; vendor part numbers, grating line densities, energy calibration, -# and physical positions are not in it and are open questions. Every value is carried -# confirm until P04 staff verify it. The extraction is in the xmap/research repo (private), under petra-iii/. -# -# WHAT IS NEW: the soft X-ray optics regime. P04's monochromator binds the catalog -# GratingMonochromator Family (a plane-grating monochromator, NOT the crystal -# Monochromator P01 / the hard X-ray beamlines use), CORA's first GratingMonochromator -# deployment. Otherwise no new Family: the undulator binds InsertionDevice, the -# mirrors Mirror, the slits Slit, the diagnostic cameras Camera, the electrometers -# FluxMonitor, the motorized phosphor screens the catalog Screen. The technique (soft -# X-ray spectroscopy: XPS / XAS / photoemission) earns no catalog Method and is -# carried pending on the Site (TECH-1). -# -# CONTROL HANDLES: the descriptor `pv` field carries the Tango device address read -# from the OnlineXML (e.g. p04/monop04/exp2.01). The beamline optics (undulator, -# PGM, mirrors, exit slits) report on the haspp04exp2 Tango host but are logically -# the optics section; per the cross-host mapping decision they are homed in the -# p04-optics enclosure with the host flagged (HOST-1). The registry exposes many -# generically-named motor banks (exp1_mot01..16, ps2.01..14) whose per-axis roles -# are not labelled; these are grouped as manipulator stages carrying the handles, -# every axis role pending (GROUP-1). -# -# SCOPE: this cut models the soft X-ray optics (undulator, plane-grating -# monochromator, the three mirrors, the exit slits) and the two experiment -# endstations (EXP1 and EXP2) present in the OnlineXML, with their sample -# manipulators, diagnostic cameras, electrometers, and motorized screens. Counter / -# timer / ADC channels and the Sardana MeasurementGroup bookkeeping rows are filtered -# out by the extractor and not modelled as devices. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/p04/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "variable-polarization soft X-ray spectroscopy (250-3000 eV: XAS, photoemission) across a soft X-ray optics section and two experiment endstations; CORA's first `GratingMonochromator` deployment (the plane-grating mono), reuses the optics / motion Families otherwise, reusing the pending `xas_spectroscopy` / `angle_resolved_photoemission` Methods" - name: P04 - facility: petra-iii # PETRA III Site (facility_code: petra-iii) - sector: "P04" - tier: Unit - parent: null - source: insertion-device - source_confirm: "P04 is a variable-polarization (APPLE-II-type) undulator beamline, 250-3000 eV; the OnlineXML exposes the undulator and its gap (p04/undulatorp04) but no period, polarization modes, or row-phase axes, carried pending (SRC-1)" - page_layout: stages - shape: "Soft X-ray variable-polarization spectroscopy: a high-resolution plane-grating monochromator feeding photoemission and absorption endstations." - source_ref: - label: "python-nxstools-extras-p04" - url: "https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p04" - -# Three enclosures: the soft X-ray optics section (the PGM and mirrors), and the two -# experiment endstations. The optics devices report on the haspp04exp2 Tango host but -# are logically the optics section (HOST-1). DESY PSS permit signals are not in the -# OnlineXML (PSS-1). -enclosures: - - name: p04-optics - role: optics-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the P04 optics section; not in the OnlineXML (PSS-1)"} - - name: p04-exp1 - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for EXP1; not in the OnlineXML (PSS-1)"} - - name: p04-exp2 - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for EXP2; not in the OnlineXML (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the variable-polarization undulator and the soft X-ray optics -# =========================================================================== - -source: - stage: source - enclosure: p04-optics - intro: "The P04 variable-polarization undulator. The OnlineXML exposes the undulator device and its gap; the polarization modes (horizontal / vertical / circular) and the row-phase axes that set them are not in the registry." - note: "Undulator on p04/undulatorp04; the APPLE-II row-phase / polarization control is SRC-1." - devices: - - name: Undulator - family: InsertionDevice - pv: {undulator: "p04/undulatorp04/exp2.01", gap: "p04/undulatorp04/exp2.01/Gap"} - new: true - confirm: true - note: "P04 variable-polarization (APPLE-II-type) undulator, 250-3000 eV; gap read from the registry, polarization / row-phase axes not exposed (SRC-1); reports on the haspp04exp2 host (HOST-1)" - -optics: - stage: source - enclosure: p04-optics - intro: "The soft X-ray conditioning optics: the plane-grating monochromator that energy-selects the beam, the three mirrors that collimate / focus / refocus it, and the exit slit that sets the resolving power." - note: "Handles read from the OnlineXML (p04/monop04, p04/spk for the mirror axes, p04/slt for the exit slit). The grating line densities, mirror coatings, and exit-slit calibration are OPT-1. These optics report on the haspp04exp2 host but are the optics section (HOST-1)." - devices: - - name: PlaneGratingMonochromator - family: GratingMonochromator - pv: {mono: "p04/monop04/exp2.01"} - new: true - confirm: true - note: "plane-grating monochromator (MonoP04), 250-3000 eV; the grating line densities and the included-angle / c-value mode are OPT-1; CORA's first GratingMonochromator deployment" - - name: Mirror1 - family: Mirror - pv: {rotation_y: "p04/spk/exp.01", translation_x: "p04/spk/exp.02"} - new: true - confirm: true - note: "first soft X-ray mirror (m1: roty / transx, SmarPod-style spk controller); coating and role (collimating / deflection) are OPT-1" - - name: Mirror2 - family: Mirror - pv: {rotation_y: "p04/spk/exp.03", translation_x: "p04/spk/exp.04"} - new: true - confirm: true - note: "second soft X-ray mirror (m2: roty / transx); coating and role are OPT-1" - - name: Mirror3 - family: Mirror - pv: {rotation_y: "p04/spk/exp.06", translation_x: "p04/spk/exp.05", translation_y: "p04/spk/exp.07"} - new: true - confirm: true - note: "third soft X-ray mirror (m3: roty / transx / transy, the refocusing mirror); coating and role are OPT-1" - - name: ExitSlitVertical - family: Slit - pv: {gap: "p04/slt/exp.01", offset: "p04/slt/exp.02"} - new: true - confirm: true - note: "vertical exit slit (slt1: vgap / voffs); sets the soft X-ray resolving power (OPT-1)" - - name: ExitSlit - family: Slit - pv: {left: "p04/slt/exp.03", right: "p04/slt/exp.04", gap: "p04/slt/exp.05", offset: "p04/slt/exp.06", virtual: "p04/vmexecutor/exitslit.01"} - new: true - confirm: true - note: "exit slit (slt2: horizontal blades + vertical gap / offset, plus the vmexecutor virtual exit-slit axis); OPT-1" - -# =========================================================================== -# EXP1 endstation -# =========================================================================== - -exp1-sample: - stage: sample - enclosure: p04-exp1 - intro: "The EXP1 experiment endstation: a sample manipulator stack and a secondary positioner, with a viewing camera and a drain-current electrometer for absorption spectroscopy." - note: "The registry exposes generically-named motor banks (exp1_mot01..16, ps2.01..14) whose per-axis roles are not labelled; they are grouped as manipulator stages carrying the handles, every axis role pending (GROUP-1)." - devices: - - name: SampleManipulator - family: Manipulator - pv: {mot01: "p04/motor/exp1.01", mot02: "p04/motor/exp1.02", mot03: "p04/motor/exp1.03", mot04: "p04/motor/exp1.04", mot05: "p04/motor/exp1.05", mot06: "p04/motor/exp1.06", mot07: "p04/motor/exp1.07", mot08: "p04/motor/exp1.08", mot09: "p04/motor/exp1.09", mot10: "p04/motor/exp1.10", mot11: "p04/motor/exp1.11", mot12: "p04/motor/exp1.12", mot13: "p04/motor/exp1.13", mot14: "p04/motor/exp1.14", mot15: "p04/motor/exp1.15", mot16: "p04/motor/exp1.16"} - new: true - confirm: true - note: "EXP1 sample manipulator motor bank (exp1_mot01..16); the per-axis roles are not labelled in the registry, grouped as one Manipulator (GROUP-1)" - - name: SecondaryPositioner - family: Manipulator - pv: {ax01: "p04/motor/ps2.01", ax02: "p04/motor/ps2.02", ax03: "p04/motor/ps2.03", ax04: "p04/motor/ps2.04", ax05: "p04/motor/ps2.05", ax06: "p04/motor/ps2.06", ax07: "p04/motor/ps2.07", ax08: "p04/motor/ps2.08", ax09: "p04/motor/ps2.09", ax10: "p04/motor/ps2.10", ax11: "p04/motor/ps2.11", ax12: "p04/motor/ps2.12", ax13: "p04/motor/ps2.13", ax14: "p04/motor/ps2.14"} - new: true - confirm: true - note: "EXP1 secondary positioner motor bank (ps2.01..14); roles not labelled, grouped as one Manipulator (GROUP-1)" - - name: ViewCamera - family: Camera - pv: {prosilica: "p04/prosilica/1"} - new: true - confirm: true - note: "EXP1 viewing camera (Prosilica / Allied Vision); sample-viewing diagnostic (DET-1)" - -exp1-detector: - stage: detection - enclosure: p04-exp1 - intro: "The EXP1 drain-current electrometer for total-electron-yield absorption spectroscopy." - note: "Keithley 6517A electrometer on p04/keithley6517a; the measured channel (sample drain current / I0) is DET-1." - devices: - - name: Electrometer - family: FluxMonitor - pv: {keithley: "p04/keithley6517a/exp1.01"} - new: true - confirm: true - note: "EXP1 Keithley 6517A electrometer; drain-current / flux measurement for XAS (total electron yield), bound to FluxMonitor (DET-1)" - -# =========================================================================== -# EXP2 endstation -# =========================================================================== - -exp2-sample: - stage: sample - enclosure: p04-exp2 - intro: "The EXP2 experiment endstation: the exit-shutter unit (EXSU2) with its slit, translation, baffle, and beam-position monitor, plus a generic positioner and the virtual position axes." - note: "Handles read from p04/motor/exp2.*. EXSU2 is the EXP2 exit / experiment shutter-and-diagnostic unit; the individual roles (Spalt = slit, Trans = translation, bpm, baffle) are EXSU-1." - devices: - - name: ExitShutterUnit - family: Slit - pv: {slit: "p04/motor/exp2.01", translation: "p04/motor/exp2.02", bpm: "p04/motor/exp2.03", baffle: "p04/motor/exp2.04"} - new: true - confirm: true - note: "EXP2 exit-shutter / diagnostic unit (EXSU2: Spalt = slit, Trans = translation, bpm, baffle); modelled as a beam-defining Slit, the bpm / baffle roles are EXSU-1" - - name: ExperimentPositioner - family: Manipulator - pv: {mot06: "p04/motor/exp2.06", mot08: "p04/motor/exp2.08"} - new: true - confirm: true - note: "EXP2 generic positioner axes (exp2_mot06 / exp2_mot08); roles not labelled (GROUP-1)" - - name: VirtualPositioners - family: PseudoAxis - pv: {ps_position: "p04/vmexecutor/ps_position_exp2", screen_position: "p04/vmexecutor/screen_position_exp2"} - new: true - confirm: true - note: "EXP2 virtual position axes (vm_ps_position, vm_screen_position on vmexecutor) coupling the positioner / screen motions (GROUP-1)" - -exp2-screens: - stage: detection - enclosure: p04-exp2 - intro: "The EXP2 in-line motorized phosphor screens and the beam-monitor cameras that image them, for beam-path diagnostics along the experiment section." - note: "Eight motorized screens (Screen_*) on p04/motor/exp2.*, imaged by Vimba cameras (p04/tangovimba). The screen positions and the camera-to-screen mapping are DIAG-1." - devices: - - name: DiagnosticScreens - family: Screen - pv: {aft_pgm2: "p04/motor/exp2.05", aft_rmu2: "p04/motor/exp2.07", aft_exp2: "p04/motor/exp2.09", aft_exsu2: "p04/motor/exp2.10", bef_pipe: "p04/motor/exp2.11", aft_pipe: "p04/motor/exp2.12"} - new: true - confirm: true - note: "EXP2 motorized phosphor diagnostic screens (Screen_aft_PGM2 / RMU2 / EXP2 / EXSU2 / PIPE); insert positions for beam-path diagnostics, bound to the catalog Screen Family (FLAG-1)" - - name: BeamMonitorCameras - family: Camera - pv: {aft_pgm2: "p04/tangovimba/bm_aft_pgm2", bef_pipe: "p04/tangovimba/bm_bef_pipe", aft_pipe: "p04/tangovimba/bm_aft_pipe", aft_smu1: "p04/tangovimba/cam10", cam09: "p04/tangovimba/cam09", cam11: "p04/tangovimba/cam11", exsu2: "p04/tangovimba/exsu2"} - new: true - confirm: true - note: "EXP2 beam-monitor cameras (Vimba / Allied Vision) imaging the diagnostic screens along the beam path (DIAG-1)" - - name: Electrometer - family: FluxMonitor - pv: {keithley: "p04/keithley6517a/exp2.01"} - new: true - confirm: true - note: "EXP2 Keithley 6517A electrometer; drain-current / flux measurement (DET-1)" - -# Cross-cutting control. P04 runs Tango with Sardana, the PETRA III house style. -controls: - intro: > - P04 runs on the PETRA III control system, Tango with Sardana as the scan / motion - SCADA layer, the same floor as P01 and CORA's wider Tango / Sardana house style. - A motion axis is a Tango motor device (p04/motor/.), a mirror axis a - SmarPod-style spk controller device (p04/spk/exp.), the monochromator a - MonoP04 device (p04/monop04), the undulator a UndulatorP04 device, and a coupled - axis a vmexecutor. The diagnostic cameras are TangoVimba devices and the - electrometers Keithley 6517A device servers. The handles are read from P04's - public OnlineXML registry and carried confirm (CTRL-1). The soft X-ray - spectroscopy acquisition (the photon-energy scan over the undulator + PGM coupled - to the electrometer / analyzer readout) runs as a Sardana macro; that - orchestration is the seam CORA's edge would conduct over its ControlPort (CTRL-2). - motion_controllers: - - name: OMS58Controllers - family: MotionController - protocol: Tango_oms58 - new: true - confirm: true - note: "OMS MAXv-58 stepper controllers (oms58) driving the experiment and screen motors (CTRL-1)" - - name: SPKControllers - family: MotionController - protocol: Tango_spk - new: true - confirm: true - note: "SmarPod-style spk controllers driving the soft X-ray mirror and exit-slit axes (CTRL-1)" - - name: TangoMotorControllers - family: MotionController - protocol: Tango_motor_tango - new: true - confirm: true - note: "generic Tango motor controllers (motor_tango) backing the monochromator, undulator, and virtual axes (CTRL-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a P04 run needs present before it - can start. All pending confirmation. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/p06/beamline.yaml b/deployments/p06/beamline.yaml deleted file mode 100644 index 42e8b70fe1e..00000000000 --- a/deployments/p06/beamline.yaml +++ /dev/null @@ -1,364 +0,0 @@ -# P06 beamline descriptor (PETRA III, DESY), reverse-engineered from the OnlineXML -# -# P06 "Micro- and Nanoprobe (PETRA III)" is the hard X-ray scanning micro / nano -# fluorescence and diffraction probe at PETRA III (DESY, Hamburg). It is bound to the -# PETRA III Site (deployments/petra-iii/site.yaml), the third PETRA III beamline -# after P01 and P04, and the richest device tree in the public OnlineXML set. -# -# STATUS: reverse-engineered from P06's own public OnlineXML device registry -# (gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p06, branch -# debian/jessie; the xml/online_hasp* registries). Device logical names and Tango -# control handles are real, read from that registry; vendor part numbers, focal -# sizes, energy ranges, and physical positions are not in it and are open questions. -# Every value is carried confirm until P06 staff verify it. The extraction is in -# xmap/research repo (private), under petra-iii/. -# -# WHAT IS NEW: no new device Family. P06 binds existing Families end to end, but it is -# the fleet's most complete scanning-probe instrument: a micro-probe endstation (MC01) -# and a nano-probe endstation (NC1), each a dense stack of hexapods, KB lens stages, -# and piezo scanners, reading the Maia XRF detector array plus the Eiger / Lambda / -# Pilatus / PCO detectors. The technique (scanning X-ray fluorescence / diffraction -# microscopy + nano-tomography) reuses the pending scanning_fluorescence_microscopy -# and tomography slugs (TECH-1). -# -# CONTROL HANDLES: the descriptor `pv` field carries the Tango device address read -# from the OnlineXML (e.g. p06/hexapodmotor/mc01.01). The registry exposes large -# generically-named motor banks (mi_mot01..84 at MC01, nat_mot01..32 at NC1, the -# mono_mot bank) whose per-axis roles are not labelled; these are grouped as the -# sample / instrument stages of their endstation carrying the handles, every axis role -# pending (GROUP-1). Two Maia and detector devices report on a bare p06 / petra3 host -# without an endstation token; per the cross-host mapping decision they are homed in -# the endstation that operates them (the detection stage) with the host flagged -# (HOST-1). -# -# SCOPE: this cut models the optics / monochromator hutch (MONO: undulator, DCM, -# multilayer monochromator, optics-hutch slits) and the two scanning-probe -# endstations (MC01 micro-probe, NC1 nano-probe) with their focusing and sample -# stages, plus the shared detection pool (Maia, the area detectors, the XIA -# fluorescence detectors). Counter / timer / ADC channels and the Sardana -# MeasurementGroup bookkeeping rows are filtered out by the extractor and not modelled. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/p06/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "hard X-ray scanning micro / nano fluorescence and diffraction microscopy + nano-tomography across an optics hutch and two scanning-probe endstations (MC01 micro, NC1 nano); the fleet's fullest scanning-probe instrument (the Maia XRF array as `EnergyDispersiveSpectrometer`, hexapods, Aerotech fly-scan stages), coins no new Family, reusing the pending `scanning_fluorescence_microscopy` / `tomography` Methods" - name: P06 - facility: petra-iii # PETRA III Site (facility_code: petra-iii) - sector: "P06" - tier: Unit - parent: null - source: insertion-device - source_confirm: "P06 is an undulator beamline (hard X-ray micro / nano probe); the OnlineXML exposes the undulator (p06/undulator) and its gap / harmonic / taper virtual axes (p06/attributemotor) but no period or parameters, carried pending (SRC-1)" - page_layout: stages - shape: "The fleet's most complete scanning-probe instrument: hard X-ray micro / nano fluorescence and diffraction microscopy and nano-tomography, with a Maia array across a micro and a nano endstation." - source_ref: - label: "python-nxstools-extras-p06" - url: "https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p06" - -# Four enclosures: the optics / monochromator hutch and the two scanning-probe -# endstations, plus a shared detection pool whose devices report on a bare p06 host. -enclosures: - - name: p06-mono - role: optics-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the P06 optics / monochromator hutch; not in the OnlineXML (PSS-1)"} - - name: p06-mc01 - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the MC01 micro-probe endstation; not in the OnlineXML (PSS-1)"} - - name: p06-nc1 - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the NC1 nano-probe endstation; not in the OnlineXML (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the undulator and the MONO-hutch optics -# =========================================================================== - -source: - stage: source - enclosure: p06-mono - intro: "The P06 undulator source, with its gap, harmonic, and taper as virtual axes coupled into the beamline energy." - note: "Undulator on p06/undulator; the gap / harmonic / taper are attributemotor virtual axes coupled into energy_und. Period and parameters are SRC-1." - devices: - - name: Undulator - family: InsertionDevice - pv: {undulator: "p06/undulator/1", gap: "p06/attributemotor/gap", harmonic: "p06/attributemotor/harmonic", taper: "p06/attributemotor/taper"} - new: true - confirm: true - note: "P06 undulator; gap / harmonic / taper read from the registry, period not exposed (SRC-1)" - -mono-optics: - stage: source - enclosure: p06-mono - intro: "The monochromator hutch: a double-crystal monochromator and a multilayer monochromator (selectable mono branches), the optics-hutch defining slits, and a quadrant beam-position monitor." - note: "The DCM (dcmmotor / dcmener) and the multilayer mono (lom) are selectable; energy_all couples the undulator + mono. The mono_mot bank (29 axes) carries the mono-internal and optics-hutch motions, roles not labelled (GROUP-1). The optics-hutch slits are vmexecutor virtual gap / offset axes." - devices: - - name: Monochromator - family: Monochromator - pv: {bragg: "p06/dcmmotor/mono.01", energy: "p06/dcmener/mono.01", exit_offset: "p06/attributemotor/exitoffset", energy_all: "p06/multiplemotors/mono.01", energy_und: "p06/undulator/1", jacks: "p06/vmexecutors/hhl_jacks", mot09: "p06/motor/mono.09", mot10: "p06/motor/mono.10"} - new: true - confirm: true - note: "double-crystal monochromator (dcm_bragg / energy_fmb, fixed-exit offset, hhl jacks); energy_all is the coupled undulator + mono energy; crystal cut is OPT-1" - - name: MultilayerMonochromator - family: Monochromator - pv: {pitch1: "p06/lom/exp.01", roll1: "p06/lom/exp.02", pitch2: "p06/lom/exp.03", lateral2: "p06/lom/exp.04", hub2: "p06/lom/exp.05", hub1: "p06/lom/exp.06", linear2: "p06/lom/exp.07", lateral1: "p06/lom/exp.08"} - new: true - confirm: true - note: "multilayer monochromator (ML_*, the lom Tango family): higher-flux lower-resolution branch selectable against the DCM; multilayer d-spacing is OPT-1" - - name: MonochromatorStages - family: LinearStage - pv: {bank: "p06/motor/mono.01"} - new: true - confirm: true - note: "the mono-hutch motor bank (mono_mot01..48, 29 modellable axes on p06/motor/mono.*): mono-internal and optics-hutch positioning, per-axis roles not labelled, grouped as one stage carrying the bank prefix (GROUP-1)" - - name: OpticsHutchSlits - family: Slit - pv: {h_gap: "p06/vmexecutors/ohhorizontalgap", h_offset: "p06/vmexecutors/ohhorizontaloffset", v_gap: "p06/vmexecutors/ohverticalgap", v_offset: "p06/vmexecutors/ohverticaloffset"} - new: true - confirm: true - note: "optics-hutch defining slit (oh slit: virtual h/v gap and offset on vmexecutors)" - - name: SecondarySlit - family: Slit - pv: {h_gap: "p06/vmexecutors/ps2horizontalgap", h_offset: "p06/vmexecutors/ps2horizontaloffset"} - new: true - confirm: true - note: "secondary slit (ps2: virtual horizontal gap / offset)" - - name: QuadrantBPM - family: FluxMonitor - pv: {i404: "p06/i404/mono.01"} - new: true - confirm: true - note: "mono-hutch quadrant beam-position monitor (i404 electrometer)" - -# =========================================================================== -# MC01: micro-probe endstation -# =========================================================================== - -mc01-sample: - stage: sample - enclosure: p06-mc01 - intro: "The MC01 micro-probe endstation: a six-axis hexapod, the dense sample-positioning stage (the mi motor bank plus piezo and hydra fine stages), the Aerotech scanning stage, and the pin-alignment piezos." - note: "The mi_mot bank (46 axes on p06/motor/mi.*) is the endstation positioning stack, roles not labelled, grouped as one stage (GROUP-1). The hexapod is six hexapodmotor axes; the scan stage is Aerotech (continuous fly-scan capable); the fine stages are piezopi and hydra." - devices: - - name: Hexapod - family: Hexapod - pv: {x: "p06/hexapodmotor/mc01.01", y: "p06/hexapodmotor/mc01.02", z: "p06/hexapodmotor/mc01.03", u: "p06/hexapodmotor/mc01.04", v: "p06/hexapodmotor/mc01.05", w: "p06/hexapodmotor/mc01.06"} - new: true - confirm: true - note: "MC01 six-axis hexapod (hexx-hexz translations, hexu-hexw rotations); coarse sample orientation" - - name: SampleStage - family: LinearStage - pv: {bank: "p06/motor/mi.01", mmcx: "p06/axis/mi.01", mmcy: "p06/axis/mi.02", piezo1: "p06/piezopi/exp.01", piezo2: "p06/piezopi/exp.02", hydra1: "p06/hydramotor/exp.01", hydra2: "p06/hydramotor/exp.02", hydra3: "p06/hydramotor/exp.03", hydra4: "p06/hydramotor/exp.04"} - new: true - confirm: true - note: "MC01 sample-positioning stack: the mi_mot bank (46 axes on p06/motor/mi.*, grouped, GROUP-1) plus the MMC, piezopi, and SMC-hydra fine stages; per-axis roles pending" - - name: ScanStage - family: LinearStage - pv: {x: "p06/aerotechmotor/exp.01", y: "p06/aerotechmotor/exp.02", z: "p06/aerotechmotor/exp.03"} - new: true - confirm: true - note: "MC01 Aerotech scanning stage (scanx / scany / scanz); the continuous fly-scan raster axes for scanning microscopy (SCAN-1)" - - name: PinAlignment - family: LinearStage - pv: {x: "p06/smaractmotor/exp.01", y: "p06/smaractmotor/exp.02", z: "p06/smaractmotor/exp.03"} - new: true - confirm: true - note: "MC01 pin / sample alignment SmarAct piezos (pinx / piny / pinz)" - - name: VirtualStages - family: PseudoAxis - pv: {csamr: "p06/vmexecutors/csamr", detx: "p06/vmexecutors/detx.01", dety: "p06/vmexecutors/dety.01", fluox: "p06/vmexecutors/fluox.01", samax: "p06/vmexecutors/samax.01", samay: "p06/vmexecutors/samay.01"} - new: true - confirm: true - note: "MC01 virtual coupled axes (sample rotation csamr, detector detx/dety, fluo-detector fluox, sample samax/samay on vmexecutors) (GROUP-1)" - - name: QuadrantBPM - family: FluxMonitor - pv: {i404: "p06/i404/micro.01"} - new: true - confirm: true - note: "MC01 quadrant beam-position monitor (i404 electrometer)" - -# =========================================================================== -# NC1: nano-probe endstation -# =========================================================================== - -nc1-sample: - stage: sample - enclosure: p06-nc1 - intro: "The NC1 nano-probe endstation: two SmarAct hexapods (the horizontal and vertical KB-lens carriers), the KB lens fine stages, the SmarAct sample / phase piezos, the Pegasus sample rotation, the centring piezos, and the nano-positioning motor bank." - note: "The two hexasmarmotor controllers carry nine axes each (x/y/z translations, px/py/pz pusher, rx/ry/rz rotations); the lens fine stages are vmexecutor virtual axes; the nat_mot bank (20 axes) is the endstation positioning, roles not labelled (GROUP-1)." - devices: - - name: KBLensHexapodHorizontal - family: Hexapod - pv: {x: "p06/hexasmarmotor1/x", y: "p06/hexasmarmotor1/y", z: "p06/hexasmarmotor1/z", px: "p06/hexasmarmotor1/px", py: "p06/hexasmarmotor1/py", pz: "p06/hexasmarmotor1/pz", rx: "p06/hexasmarmotor1/rx", ry: "p06/hexasmarmotor1/ry", rz: "p06/hexasmarmotor1/rz"} - new: true - confirm: true - note: "NC1 horizontal KB-lens SmarAct hexapod (hhex*); positions the horizontal-focusing KB mirror / lens (OPT-1)" - - name: KBLensHexapodVertical - family: Hexapod - pv: {x: "p06/hexasmarmotor2/x", y: "p06/hexasmarmotor2/y", z: "p06/hexasmarmotor2/z", px: "p06/hexasmarmotor2/px", py: "p06/hexasmarmotor2/py", pz: "p06/hexasmarmotor2/pz", rx: "p06/hexasmarmotor2/rx", ry: "p06/hexasmarmotor2/ry", rz: "p06/hexasmarmotor2/rz"} - new: true - confirm: true - note: "NC1 vertical KB-lens SmarAct hexapod (vhex*); positions the vertical-focusing KB mirror / lens (OPT-1)" - - name: LensFineStages - family: PseudoAxis - pv: {hlensx: "p06/vmexecutor/hlensx", hlensy: "p06/vmexecutor/hlensy", hlensz: "p06/vmexecutor/hlensz", hlensrx: "p06/vmexecutor/hlensrx", hlensry: "p06/vmexecutor/hlensry", hlensrz: "p06/vmexecutor/hlensrz", vlensx: "p06/vmexecutor/vlensx", vlensy: "p06/vmexecutor/vlensy", vlensz: "p06/vmexecutor/vlensz", vlensrx: "p06/vmexecutor/vlensrx", vlensry: "p06/vmexecutor/vlensry", vlensrz: "p06/vmexecutor/vlensrz"} - new: true - confirm: true - note: "NC1 KB-lens virtual fine-positioning axes (hlens* / vlens* on vmexecutor), coupling the hexapod motions (OPT-1)" - - name: SamplePiezo - family: LinearStage - pv: {phasex: "p06/smaractmotor/exp.01", phasey: "p06/smaractmotor/exp.02", phasez: "p06/smaractmotor/exp.03", intsx: "p06/smaractmotor/exp.04", intsy: "p06/smaractmotor/exp.05", intsz: "p06/smaractmotor/exp.06", pinx: "p06/smaractmotor/exp.07", piny: "p06/smaractmotor/exp.08", pinz: "p06/smaractmotor/exp.09"} - new: true - confirm: true - note: "NC1 SmarAct sample / phase / interferometer piezos (phase*, ints*, pin* on p06/smaractmotor); fine sample positioning (SAMPLE-1)" - - name: SampleRotation - family: RotaryStage - pv: {samr: "p06/pegasusmotor/nc1.02"} - new: true - confirm: true - note: "NC1 sample rotation (samr, Pegasus motor); the nano-tomography rotation axis (SAMPLE-1)" - - name: CentringPiezo - family: LinearStage - pv: {cent1: "p06/piezopie871/exp.01", cent2: "p06/piezopie871/exp.02"} - new: true - confirm: true - note: "NC1 sample-centring piezos (cent1 / cent2, PI E-871)" - - name: ScanStage - family: LinearStage - pv: {u: "p06/aerotechmotor/lab.02", v: "p06/aerotechmotor/lab.01", z: "p06/aerotechmotor/lab.03", scanx: "p06/vmexecutor/scanx", scany: "p06/vmexecutor/scany"} - new: true - confirm: true - note: "NC1 Aerotech scanning stage (scanu / scanv / scanz) plus virtual scanx / scany; the continuous fly-scan raster axes (SCAN-1)" - - name: NanoPositioningStage - family: LinearStage - pv: {bank: "p06/motor/na.01", mot31: "p06/motor/na.31", mot32: "p06/motor/na.32"} - new: true - confirm: true - note: "NC1 nano-positioning motor bank (nat_mot01..32, 20 modellable axes on p06/motor/na.*); per-axis roles not labelled, grouped as one stage (GROUP-1)" - - name: NC1Slits - family: Slit - pv: {h_gap: "p06/vmexecutor/shg", h_offset: "p06/vmexecutor/sho", v_gap: "p06/vmexecutor/svg", v_offset: "p06/vmexecutor/svo"} - new: true - confirm: true - note: "NC1 defining slit (virtual h/v gap and offset on vmexecutor)" - -# =========================================================================== -# DETECTION: the shared detector pool (Maia, area detectors, fluorescence) -# =========================================================================== - -detection: - stage: detection - enclosure: p06-mc01 - intro: "The shared P06 detector pool: the Maia XRF detector array (the high-rate fluorescence-mapping detector and its sub-systems), the area detectors (Eiger, Lambda, Pilatus, PCO), and the XIA fluorescence detectors. The detectors serve both endstations per experiment." - note: "The Maia is a multi-element XRF detector array exposed as several Tango devices (maiadimension / maiaflux / maiasensor / maiainterlock / maialogger / maiaprocessing); modelled as one EnergyDispersiveSpectrometer Asset carrying its sub-device handles. The area detectors and XIA detectors report on a bare p06 / petra3 host (HOST-1); the operative roster per experiment is DET-1." - devices: - - name: MaiaDetector - family: EnergyDispersiveSpectrometer - pv: {dimension0: "p06/maiadimension/exp.00", dimension1: "p06/maiadimension/exp.01", dimension2: "p06/maiadimension/exp.02", flux0: "p06/maiaflux/exp.00", flux1: "p06/maiaflux/exp.01", sensor: "p06/maiasensor/exp.01", interlock: "p06/maiainterlock/exp.01", logger: "p06/maialogger/exp.01", processing: "p06/maiaprocessing/exp.01"} - new: true - confirm: true - note: "Maia high-rate XRF detector array (the dimension / flux / sensor / interlock / logger / processing sub-devices); the scanning-fluorescence-microscopy mapping detector, modelled as one EnergyDispersiveSpectrometer (DET-1)" - - name: XIAFluorescence - family: EnergyDispersiveSpectrometer - pv: {xia01: "p06/xia/p06.1", xia02: "p06/xia/p06.2", xia03: "p06/xia/p06.3", xia04: "p06/xia/p06.4", lab: "p06/xia/exp.1"} - new: true - confirm: true - note: "XIA multi-channel-analyzer fluorescence detectors (p06_xia01..04 plus the lab unit); energy-dispersive fluorescence detection (DET-1)" - - name: EigerDetector - family: Camera - pv: {eiger: "p06/eigerdectris/exp.01"} - new: true - confirm: true - note: "DECTRIS Eiger area detector; diffraction / scanning-diffraction imaging (DET-1)" - - name: LambdaDetector - family: Camera - pv: {lambda: "petra3/lambda/01"} - new: true - confirm: true - note: "X-Spectrum Lambda area detector; reports on the petra3 host (HOST-1); diffraction imaging (DET-1)" - - name: PilatusDetector - family: Camera - pv: {pilatus: "p06/pilatus/300k", pilatus2: "P06/pilatus/300k2"} - new: true - confirm: true - note: "DECTRIS Pilatus 300k area detectors (two units); diffraction imaging (DET-1)" - - name: PCODetector - family: Camera - pv: {pco4000: "p06/ccd/pco4000"} - new: true - confirm: true - note: "PCO 4000 CCD camera; imaging / visible-light diagnostics (DET-1)" - - name: XrayEyeCamera - family: Camera - pv: {xrayeye: "p06/prosilica/xrayeye.01"} - new: true - confirm: true - note: "X-ray-eye Prosilica viewing camera; beam / sample viewing (DET-1)" - -# Cross-cutting control. P06 runs Tango with Sardana, the PETRA III house style. -controls: - intro: > - P06 runs on the PETRA III control system, Tango with Sardana as the scan / motion - SCADA layer, the same floor as P01 and P04. P06 is the most controller-diverse - PETRA III beamline modelled so far: alongside the OMS MAXv-58 steppers it runs - hexapod controllers (hexapodmotor, hexasmarmotor), SmarAct piezo controllers - (smaractmotor), Aerotech fly-scan controllers (aerotechmotor), PI piezo - controllers (piezopi, piezopie871), SMC-Hydra controllers (hydramotor), and - Pegasus controllers (pegasusmotor), with the Maia XRF array and the Eiger / - Lambda / Pilatus / PCO detectors. The handles are read from P06's public OnlineXML - registry and carried confirm (CTRL-1). The scanning fluorescence / diffraction - microscopy acquisition (the Aerotech raster fly-scan coupled to the Maia readout) - runs as a Sardana macro; that orchestration is the seam CORA's edge conducts over - its ControlPort (CTRL-2). - motion_controllers: - - name: OMS58Controllers - family: MotionController - protocol: Tango_oms58 - new: true - confirm: true - note: "OMS MAXv-58 stepper controllers (oms58) driving the mono, mi, and nat motor banks (CTRL-1)" - - name: AerotechControllers - family: MotionController - protocol: Tango_aerotech - new: true - confirm: true - note: "Aerotech fly-scan motion controllers driving the MC01 / NC1 scanning raster stages (SCAN-1, CTRL-1)" - - name: SmarActControllers - family: MotionController - protocol: Tango_smaract - new: true - confirm: true - note: "SmarAct piezo controllers (smaractmotor, hexasmarmotor) driving the nano-probe hexapods and sample piezos (CTRL-1)" - - name: HexapodControllers - family: MotionController - protocol: Tango_hexapod - new: true - confirm: true - note: "hexapod motion controllers (hexapodmotor) driving the MC01 six-axis hexapod (CTRL-1)" - - name: PiezoControllers - family: MotionController - protocol: Tango_piezo - new: true - confirm: true - note: "PI piezo controllers (piezopi, piezopie871) and SMC-Hydra controllers (hydramotor) driving the fine sample stages (CTRL-1)" - - name: TangoMotorControllers - family: MotionController - protocol: Tango_motor_tango - new: true - confirm: true - note: "generic Tango motor controllers (motor_tango) backing the mono, undulator, virtual, and Pegasus axes (CTRL-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a P06 run needs present before it - can start. All pending confirmation. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/p07/beamline.yaml b/deployments/p07/beamline.yaml deleted file mode 100644 index c5cd7201139..00000000000 --- a/deployments/p07/beamline.yaml +++ /dev/null @@ -1,259 +0,0 @@ -# P07 beamline descriptor (PETRA III, DESY), reverse-engineered from the OnlineXML -# -# P07 "High Energy Materials Science (HEMS)" is the high-energy hard X-ray -# materials-science beamline at PETRA III (DESY, Hamburg), jointly operated by -# Helmholtz-Zentrum Hereon (2/3) and DESY (1/3). It runs high-energy diffraction and -# imaging for engineering / materials studies, with a 17 T high-field magnet -# endstation. It is bound to the PETRA III Site (deployments/petra-iii/site.yaml), the -# eleventh PETRA III beamline. -# -# STATUS: reverse-engineered from P07's own public OnlineXML device registry -# (gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p07, branch -# debian/jessie; the online_haspp07eh2.xml registry). Device logical names and Tango -# control handles are real, read from that registry; vendor part numbers, crystal -# cuts, the magnet field, energy calibration, and physical positions are not in it and -# are open questions. Every value is carried confirm until P07 staff verify it. The -# extraction is in the xmap/research repo (private), under petra-iii/. -# -# WHAT IS NEW: no new device Family. P07 reuses existing Families end to end, including -# the graduated catalog Magnet Family (of which P07's 17 T magnet is a further -# consumer that reinforced the graduation). The four-circle Eulerian diffractometer (e4cv) and -# the two-theta arm bind the catalog Goniometer Family (not the composed Diffractometer -# Assembly, the P01 EH2 call). The techniques (high-energy diffraction, high-field -# materials science) reuse the pending diffraction / magnetic_scattering slugs -# (TECH-1). -# -# CONTROL HANDLES: the descriptor `pv` field carries the Tango device address read -# from the OnlineXML (e.g. p07/dcmmotor/dcm_1st_pitch). The registry exposes large -# generically-named motor banks (exp* at EH2, exp01..64 at EH2B, oh* at OH2) whose -# per-axis roles are not labelled; grouped as the optics / endstation stages carrying -# the handles, every axis role pending (GROUP-1). The complex DCM is a multi-bounce -# mono exposed as named 1st/2nd-crystal bend/pitch/roll/yaw axes, so it is resolved. -# -# SCOPE: this cut models the optics (the undulator, the multi-bounce DCM, the OH2/OH3 -# slits), the EH2 main experiment hutch (the four-circle diffractometer, the hexapod, -# the 17 T magnet, the Linkam stage, the detectors), and the EH2B secondary hutch (a -# sample bank). The beamline is also referenced as P07 EH1/EH3/EH4 in places; only the -# EH2 registry slice is public here (HOST-1). Counter / timer / ADC channels and the -# Sardana MeasurementGroup bookkeeping rows are filtered out by the extractor. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/p07/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "high-energy materials-science diffraction (HEMS) on a multi-bounce DCM + four-circle diffractometer, with a 17 T high-field magnet endstation; jointly operated by Helmholtz-Zentrum Hereon + DESY, coins no new Family (a further consumer of the graduated `Magnet` Family), reusing the pending `diffraction` / `magnetic_scattering` Methods" - name: P07 - facility: petra-iii # PETRA III Site (facility_code: petra-iii) - sector: "P07" - tier: Unit - parent: null - source: insertion-device - source_confirm: "P07 is an undulator beamline (high-energy materials science, jointly operated by Helmholtz-Zentrum Hereon 2/3 + DESY 1/3); the OnlineXML exposes the undulator (p07/undulator) and its gap / taper (p07/attributemotor) but no period or parameters, carried pending (SRC-1, OPERATOR-1)" - page_layout: stages - shape: "High-energy materials science (up to ~200 keV): engineering diffraction and imaging of bulk samples on large, heavy sample stages." - source_ref: - label: "python-nxstools-extras-p07" - url: "https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p07" - -# Three enclosures: the optics hutch (the multi-bounce DCM + OH2/OH3 slits), the EH2 -# main experiment hutch, and the EH2B secondary hutch. DESY / Hereon PSS permit -# signals are not in the OnlineXML (PSS-1). -enclosures: - - name: p07-oh2 - role: optics-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY / Hereon PSS permit signal for the P07 optics hutch; not in the OnlineXML (PSS-1)"} - - name: p07-eh2 - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY / Hereon PSS permit signal for the EH2 main experiment hutch; not in the OnlineXML (PSS-1)"} - - name: p07-eh2b - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY / Hereon PSS permit signal for the EH2B secondary hutch; not in the OnlineXML (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the undulator and the OH optics -# =========================================================================== - -source: - stage: source - enclosure: p07-oh2 - intro: "The P07 undulator source and the optics: a multi-bounce double-crystal monochromator (two crystals, each with bend / pitch / roll / yaw) for high-energy operation, plus the OH2/OH3 defining slits." - note: "The DCM is exposed as named 1st / 2nd-crystal axes (dcm_1st_*, dcm_2nd_*) plus the dcmenergy coupling. The OH slits are slt + galildmcslit virtual axes. A Beckhoff z-stage (zpos_shoh1) positions the OH1 component." - devices: - - name: Undulator - family: InsertionDevice - pv: {undulator: "p07/undulator/undu", gap: "p07/attributemotor/gap", taper: "p07/attributemotor/taper"} - new: true - confirm: true - note: "P07 undulator; gap / taper read from the registry, period not exposed (SRC-1)" - - name: Monochromator - family: Monochromator - pv: {first_bend: "p07/dcmmotor/dcm_1st_bend", first_pitch: "p07/dcmmotor/dcm_1st_pitch", first_roll: "p07/dcmmotor/dcm_1st_roll", first_yaw: "p07/dcmmotor/dcm_1st_yaw", second_bend: "p07/dcmmotor/dcm_2nd_bend", second_pitch: "p07/dcmmotor/dcm_2nd_pitch", energy: "p07/dcmenergy/mnchrmtr"} - new: true - confirm: true - note: "multi-bounce double-crystal monochromator (two crystals, each with bend / pitch / roll / yaw, plus the coupled mnchrmtr energy); high-energy operation, crystal cut is OPT-1" - - name: OpticsZStage - family: LinearStage - pv: {zpos: "p07/beckhoffmotor/zpos_shoh1"} - new: true - confirm: true - note: "the OH1 component z-positioning stage (zpos_shoh1, Beckhoff motor) (OPT-1)" - - name: DefiningSlits - family: Slit - pv: {slt1_vgap: "p07/slt/slt1vgap", slt1_voffs: "p07/slt/slt1voffs", slt2_hleft: "p07/slt/slt2hleft", slt2_hright: "p07/slt/slt2hright", slt2_vgap: "p07/slt/slt2vgap", oh2_cx: "p07/galildmcslit/G_oh2_Cx", oh2_cy: "p07/galildmcslit/G_oh2_Cy", oh2_dx: "p07/galildmcslit/G_oh2_Dx", oh2_dy: "p07/galildmcslit/G_oh2_Dy"} - new: true - confirm: true - note: "the OH2 defining slits (slt1 / slt2 + the G_oh2 Galil DMC slit center / gap axes) (OPT-1)" - - name: OpticsStages - family: LinearStage - pv: {bank: "p07/motor/oh01"} - new: true - confirm: true - note: "the OH2 optics / instrument motor bank (oh01..16 on p07/motor); per-axis roles not labelled, grouped as one stage (OPT-1, GROUP-1)" - -# =========================================================================== -# EH2: main experiment hutch -# =========================================================================== - -eh2-sample: - stage: sample - enclosure: p07-eh2 - intro: "The EH2 main experiment hutch: the four-circle Eulerian diffractometer, the two-theta arm, a sample hexapod, the 17 T high-field magnet, the Linkam temperature stage, and the sample / instrument motor bank." - note: "The diffractometer is a four-circle Eulerian (e4cv) + the two-theta arm (twothetap07). The 17 T magnet binds the graduated catalog Magnet Family (presents Regulator). The exp* bank carries the sample positioning, roles not labelled (GROUP-1)." - devices: - - name: Goniometer - family: Goniometer # catalog Family; the four-circle (E4C vertical) + two-theta circles (DIFF-1) - pv: {diffractometer: "p07/e4cv/dffrctmtr", two_theta: "p07/twothetap07/tth", zin: "p07/vmotor2/zin"} - new: true - confirm: true - note: "the EH2 four-circle Eulerian diffractometer (e4cv) + the two-theta arm (twothetap07); modelled as a Goniometer Asset, not the composed Diffractometer Assembly (DIFF-1)" - - name: SampleHexapod - family: Hexapod - pv: {x: "p07/hexapodmotor/hx", y: "p07/hexapodmotor/hy", z: "p07/hexapodmotor/hz", rx: "p07/hexapodmotor/hrx", ry: "p07/hexapodmotor/hry", rz: "p07/hexapodmotor/hrz"} - new: true - confirm: true - note: "the EH2 sample hexapod (hx-hrz); coarse sample positioning / orientation (SAMPLE-1)" - - name: Magnet - family: Magnet - pv: {magnet: "p07/magnet17tf/magnet17tf"} - new: true - confirm: true - note: "the EH2 17 T superconducting sample-environment magnet (magnet17tf); binds the graduated catalog Magnet Family, a further consumer (presents Regulator, MAG-1)" - - name: SampleEnvironment - family: TemperatureController - pv: {linkam: "p07/t95tempproglinkam/linkam"} - new: true - confirm: true - note: "the EH2 Linkam T95 programmable temperature stage; in-situ heating / cooling (TEMP-1)" - - name: SampleStage - family: LinearStage - pv: {bank: "p07/motor/exp33"} - new: true - confirm: true - note: "the EH2 sample / instrument motor bank (exp33..64 on p07/motor); per-axis roles not labelled, grouped as one stage (GROUP-1)" - - name: DetectorSlit - family: Slit - pv: {eh3_cx: "p07/galildmcslit/g_eh3_Cx", eh3_cy: "p07/galildmcslit/g_eh3_Cy", eh3_dx: "p07/galildmcslit/g_eh3_Dx", eh3_dy: "p07/galildmcslit/g_eh3_Dy"} - new: true - confirm: true - note: "the EH2/EH3 detector / receiving slit (g_eh3, Galil DMC slit center / gap axes) (OPT-1)" - -eh2-detector: - stage: detection - enclosure: p07-eh2 - intro: "The EH2 detection: the Pilatus area detector, the PerkinElmer flat-panel for high-energy diffraction / imaging, and the MCA fluorescence detectors." - note: "Handles read from p07/pilatus, p07/pedetector_old, p07/mca. The high-energy diffraction detector roles are DET-1." - devices: - - name: PilatusDetector - family: Camera - pv: {pilatus: "p07/pilatus/pilatus"} - new: true - confirm: true - note: "the EH2 Pilatus area detector; diffraction imaging (DET-1)" - - name: PerkinElmerDetector - family: Camera - pv: {ctrl: "p07/pectrl_old/pe_ctrl", detector: "p07/pedetector_old/pe_detector"} - new: true - confirm: true - note: "the EH2 PerkinElmer flat-panel area detector (pectrl_old / pedetector_old); high-energy diffraction / imaging (DET-1)" - - name: FluorescenceDetectors - family: EnergyDispersiveSpectrometer - pv: {mca01: "p07/mca/eh2_mca01", mca02: "p07/mca/eh2_mca02", mca03: "p07/mca/eh2_mca03", mca04: "p07/mca/eh2_mca04"} - new: true - confirm: true - note: "the EH2 MCA fluorescence detectors (DET-1)" - -# =========================================================================== -# EH2B: secondary experiment hutch -# =========================================================================== - -eh2b-sample: - stage: sample - enclosure: p07-eh2b - intro: "The EH2B secondary experiment hutch: a sample / instrument motor bank for the second P07 experiment station." - note: "The exp01..64 bank carries the EH2B sample positioning, roles not labelled (GROUP-1)." - devices: - - name: SampleStage - family: LinearStage - pv: {bank: "p07/motor/exp01"} - new: true - confirm: true - note: "the EH2B sample / instrument motor bank (exp01..64 on p07/motor); per-axis roles not labelled, grouped as one stage (GROUP-1)" - -# Cross-cutting control. P07 runs Tango with Sardana, the PETRA III house style. -controls: - intro: > - P07 runs on the PETRA III control system, Tango with Sardana as the scan / motion - SCADA layer, the same floor as the other PETRA III beamlines (P07 is jointly - operated by Helmholtz-Zentrum Hereon and DESY, but the beamline controls are the - PETRA III Tango / Sardana stack). A motion axis is a Tango motor device - (p07/motor/...), the monochromator a multi-bounce dcmmotor / dcmenergy device, the - slits slt / galildmcslit devices, the diffractometer an e4cv / twothetap07 device, - the magnet a magnet17tf device, the hexapod a hexapodmotor, the Linkam a - t95tempproglinkam device; the detectors are pilatus / pedetector_old / mca. The - handles are read from P07's public OnlineXML registry and carried confirm (CTRL-1). - The high-energy diffraction / magnetism acquisition (the diffractometer / field - scan coupled to the area-detector capture) runs as a Sardana macro; that - orchestration is the seam CORA's edge would conduct over its ControlPort (CTRL-2). - motion_controllers: - - name: OMS58Controllers - family: MotionController - protocol: Tango_oms58 - new: true - confirm: true - note: "OMS MAXv-58 stepper controllers (oms58) driving the optics and sample motor banks (CTRL-1)" - - name: GalilSlitControllers - family: MotionController - protocol: Tango_galildmcslit - new: true - confirm: true - note: "Galil DMC slit controllers (galildmcslit) driving the OH2 and EH detector slits (CTRL-1)" - - name: HexapodControllers - family: MotionController - protocol: Tango_hexapod - new: true - confirm: true - note: "hexapod controllers (hexapodmotor) driving the EH2 sample hexapod (CTRL-1)" - - name: TangoMotorControllers - family: MotionController - protocol: Tango_motor_tango - new: true - confirm: true - note: "generic Tango motor controllers (motor_tango / beckhoffmotor / vmotor2) backing the DCM, the OH z-stage, and the coupled axes (CTRL-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a P07 run needs present before it - can start. All pending confirmation. LiquidHelium is the cryogen for the 17 T - superconducting magnet. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: LiquidHelium diff --git a/deployments/p08/beamline.yaml b/deployments/p08/beamline.yaml deleted file mode 100644 index 8d7ba7acc31..00000000000 --- a/deployments/p08/beamline.yaml +++ /dev/null @@ -1,232 +0,0 @@ -# P08 beamline descriptor (PETRA III, DESY), reverse-engineered from the OnlineXML -# -# P08 "High Resolution Diffraction Beamline" is the hard X-ray high-resolution -# diffraction beamline at PETRA III (DESY, Hamburg): surface / interface diffraction, -# reflectivity, and high-resolution powder / single-crystal diffraction on a -# six-circle diffractometer. It is bound to the PETRA III Site -# (deployments/petra-iii/site.yaml), the twelfth PETRA III beamline. -# -# STATUS: reverse-engineered from P08's own public OnlineXML device registry -# (gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p08, branch -# debian/jessie; the online_haspp08.xml registry). Device logical names and Tango -# control handles are real, read from that registry; vendor part numbers, crystal -# cuts, energy calibration, and physical positions are not in it and are open -# questions. Every value is carried confirm until P08 staff verify it. The extraction -# is in the xmap/research repo (private), under petra-iii/. -# -# WHAT IS NEW: no new device Family. P08 reuses existing Families end to end. Its -# six-circle Kohzu diffractometer binds the catalog Goniometer Family (not the composed -# Diffractometer Assembly, the P01 EH2 call); the DCM and multilayer monochromators -# bind Monochromator; the rich detector set (Eiger / Pilatus / Mythen / PerkinElmer / -# Vortex SDD) binds Camera / EnergyDispersiveSpectrometer. The technique (high- -# resolution diffraction / reflectivity) reuses the pending diffraction slug (TECH-1). -# -# CONTROL HANDLES: the descriptor `pv` field carries the Tango device address read -# from the OnlineXML (e.g. p08/dcmmotor/dcm_bragg). The registry exposes a large -# generically-named diffractometer / instrument motor bank (the diff* axes on -# p08/motor) whose per-axis roles are not labelled; grouped as the diffractometer / -# sample stages carrying the handles, every axis role pending (GROUP-1). The multilayer -# mono (lom) and the DCM are exposed as labelled axes, so the optics are resolved. -# -# SCOPE: this cut models the optics (the undulator, the DCM, the multilayer -# monochromator, the CRL, the absorber, the slits), the experiment endstation (the -# six-circle diffractometer, the hexapod, the sample bank), and the detection (the -# Eiger, Pilatus, Mythen, PerkinElmer, and Vortex SDD detectors). Counter / timer / -# ADC channels and the Sardana MeasurementGroup bookkeeping rows are filtered out by -# the extractor. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/p08/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "high-resolution diffraction (surface / interface, reflectivity, powder / single-crystal) on a six-circle Kohzu diffractometer with a rich detector set (Eiger / Pilatus / Mythen / PerkinElmer / Vortex); coins no new Family, reusing the pending `diffraction` Method" - name: P08 - facility: petra-iii # PETRA III Site (facility_code: petra-iii) - sector: "P08" - tier: Unit - parent: null - source: insertion-device - source_confirm: "P08 is an undulator beamline (high-resolution diffraction); the OnlineXML exposes the undulator gap (p08/attributemotor/gap) but no period or parameters, carried pending (SRC-1)" - page_layout: stages - shape: "High-resolution diffraction and reflectivity: a precise multi-circle diffractometer for surfaces, interfaces, and thin films." - source_ref: - label: "python-nxstools-extras-p08" - url: "https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p08" - -# Two enclosures inferred from the device structure (the registry exposes one Tango -# host): the optics hutch (the DCM / multilayer mono / CRL) and the experiment -# endstation (the diffractometer). DESY PSS permit signals are not in the OnlineXML -# (PSS-1). -enclosures: - - name: p08-oh - role: optics-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the P08 optics hutch; not in the OnlineXML (PSS-1)"} - - name: p08-eh - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the P08 experiment endstation; not in the OnlineXML (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the undulator and the optics -# =========================================================================== - -source: - stage: source - enclosure: p08-oh - intro: "The P08 undulator source and the optics: a double-crystal monochromator and a multilayer monochromator (selectable), a compound refractive lens, the beam absorber, and the defining slits." - note: "The DCM is dcmmotor / dcmener; the multilayer mono is lom (with its table) and a coupled lomenergy axis. The slits are vmexecutor virtual axes (sl3*)." - devices: - - name: Undulator - family: InsertionDevice - pv: {gap: "p08/attributemotor/gap"} - new: true - confirm: true - note: "P08 undulator; gap read from the registry, period not exposed (SRC-1)" - - name: Monochromator - family: Monochromator - pv: {bragg: "p08/dcmmotor/dcm_bragg", energy: "p08/dcmener/energyfmb"} - new: true - confirm: true - note: "double-crystal monochromator (dcm_bragg / energyfmb); high-resolution operation, crystal cut is OPT-1" - - name: MultilayerMonochromator - family: Monochromator - pv: {pitch1: "p08/lom/lom1pitch", lateral1: "p08/lom/lom1lat", linear1: "p08/lom/lom1lin", table_perp: "p08/lom/lom1tblperp", table_pitch: "p08/lom/lom1tblpitch", table_roll: "p08/lom/lom1tblroll", energy: "p08/lomenergy/energylom"} - new: true - confirm: true - note: "multilayer monochromator (lom*, with its table jacks and the coupled lomenergy axis): higher-flux lower-resolution branch selectable against the DCM; d-spacing is OPT-1" - - name: CompoundRefractiveLens - family: Transfocator - pv: {lens: "p08/lensctrl/lens_oh"} - new: true - confirm: true - note: "compound refractive lens control (lens_oh, lensctrl); the CRL focusing / transfocator (OPT-1)" - - name: Absorber - family: Filter - pv: {abs: "p08/absorber/abs", atten: "p08/vmexecutor/atten"} - new: true - confirm: true - note: "beam absorber / attenuator (abs + the atten virtual axis); folds into the Filter Family (OPT-1)" - - name: DefiningSlits - family: Slit - pv: {sl3_h: "p08/vmexecutor/sl3h", sl3_hc: "p08/vmexecutor/sl3hc", sl3_mv: "p08/vmexecutor/sl3mv"} - new: true - confirm: true - note: "the beam-defining slits (sl3*, vmexecutor virtual axes) (OPT-1)" - -# =========================================================================== -# SAMPLE STAGE: the experiment endstation (six-circle diffractometer) -# =========================================================================== - -experiment-sample: - stage: sample - enclosure: p08-eh - intro: "The P08 experiment endstation: a six-circle Kohzu diffractometer, a sample hexapod, and the diffractometer / sample motor bank." - note: "The diffractometer is a Kohzu six-circle (kozhue6cctrl) driving the diff* bank. The hexapod is hexapodmotor. The diff* bank carries the diffractometer circles and sample positioning, roles not labelled (GROUP-1)." - devices: - - name: Goniometer - family: Goniometer # catalog Family; the six-circle Kohzu sample-orientation circles (DIFF-1) - pv: {ctrl: "p08/motor/kozhue6cctrl", bank: "p08/motor/diff1"} - new: true - confirm: true - note: "the six-circle Kohzu diffractometer (kozhue6cctrl driving the diff1..N bank); modelled as a Goniometer Asset, not the composed Diffractometer Assembly (DIFF-1, GROUP-1)" - - name: SampleHexapod - family: Hexapod - pv: {x: "p08/hexapodmotor/hx", y: "p08/hexapodmotor/hy", z: "p08/hexapodmotor/hz", rx: "p08/hexapodmotor/hrx", ry: "p08/hexapodmotor/hry", rz: "p08/hexapodmotor/hrz"} - new: true - confirm: true - note: "the experiment sample hexapod (hx-hrz); coarse sample positioning / orientation (SAMPLE-1)" - -# =========================================================================== -# DETECTION STAGE: the rich detector set -# =========================================================================== - -detection: - stage: detection - enclosure: p08-eh - intro: "The P08 detection: the Eiger 1M and Pilatus 100k / 300k area detectors, the Mythen2 strip detector, the PerkinElmer flat-panel, and the Vortex silicon-drift fluorescence detector." - note: "Handles read from p08/eigerdectris, p08/pilatus, p08/mythen2, p08/pedetector, p08/sis3302. The detector roster per experiment is DET-1. The Lambda (petra3/lambda/01) reports on a bare petra3 host (HOST-1)." - devices: - - name: EigerDetector - family: Camera - pv: {eiger: "p08/eigerdectris/eiger1m"} - new: true - confirm: true - note: "the DECTRIS Eiger 1M area detector; high-resolution diffraction imaging (DET-1)" - - name: PilatusDetectors - family: Camera - pv: {p100k: "p08/pilatus/p100k", p300k: "p08/pilatus/p300k"} - new: true - confirm: true - note: "the DECTRIS Pilatus 100k / 300k area detectors (DET-1)" - - name: MythenDetector - family: Camera - pv: {mythen: "p08/mythen2/mythen"} - new: true - confirm: true - note: "the DECTRIS Mythen2 one-dimensional strip detector; high-resolution powder / reflectivity (DET-1)" - - name: PerkinElmerDetector - family: Camera - pv: {detector: "p08/pedetector/pe_detector"} - new: true - confirm: true - note: "the PerkinElmer flat-panel area detector (DET-1)" - - name: VortexDetector - family: EnergyDispersiveSpectrometer - pv: {vortex: "p08/sis3302/vortex"} - new: true - confirm: true - note: "the Vortex silicon-drift fluorescence detector (read by a SIS3302 digitizer); energy-dispersive fluorescence (DET-1)" - - name: LambdaDetector - family: Camera - pv: {lambda: "petra3/lambda/01"} - new: true - confirm: true - note: "a shared X-Spectrum Lambda detector; reports on the bare petra3 host (HOST-1, DET-1)" - -# Cross-cutting control. P08 runs Tango with Sardana, the PETRA III house style. -controls: - intro: > - P08 runs on the PETRA III control system, Tango with Sardana as the scan / motion - SCADA layer, the same floor as the other PETRA III beamlines. A motion axis is a - Tango motor device (p08/motor/...), the monochromators dcmmotor / dcmener and lom / - lomenergy devices, the CRL a lensctrl device, the diffractometer a Kohzu controller - (kozhue6cctrl), the hexapod a hexapodmotor, the slits / attenuator vmexecutor - virtual axes; the detectors are eigerdectris / pilatus / mythen2 / pedetector and - the sis3302-read Vortex SDD. The handles are read from P08's public OnlineXML - registry and carried confirm (CTRL-1). The high-resolution diffraction acquisition - (the diffractometer scan coupled to the area / strip detector capture) runs as a - Sardana macro; that orchestration is the seam CORA's edge would conduct over its - ControlPort (CTRL-2). - motion_controllers: - - name: OMS58Controllers - family: MotionController - protocol: Tango_oms58 - new: true - confirm: true - note: "OMS MAXv-58 stepper controllers (oms58) driving the optics and diffractometer / sample motor banks (CTRL-1)" - - name: HexapodControllers - family: MotionController - protocol: Tango_hexapod - new: true - confirm: true - note: "hexapod controllers (hexapodmotor) driving the experiment sample hexapod (CTRL-1)" - - name: TangoMotorControllers - family: MotionController - protocol: Tango_motor_tango - new: true - confirm: true - note: "generic Tango motor controllers (motor_tango) backing the monochromators, the Kohzu diffractometer, and the coupled axes (CTRL-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a P08 run needs present before it - can start. All pending confirmation. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/p09/beamline.yaml b/deployments/p09/beamline.yaml deleted file mode 100644 index 228b01986d1..00000000000 --- a/deployments/p09/beamline.yaml +++ /dev/null @@ -1,358 +0,0 @@ -# P09 beamline descriptor (PETRA III, DESY), reverse-engineered from the OnlineXML -# -# P09 "Resonant Scattering and Diffraction" is the hard X-ray resonant-scattering, -# diffraction, and magnetism beamline at PETRA III (DESY, Hamburg). It carries three -# areas: a resonant-scattering / HAXPES optics-and-experiment hutch (MONO), a -# diffraction hutch (DIF), and a high-field magnetism endstation (MAG) with a 14 T -# magnet. It is bound to the PETRA III Site (deployments/petra-iii/site.yaml), the -# seventh PETRA III beamline. -# -# STATUS: reverse-engineered from P09's own public OnlineXML device registry -# (gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p09, branch -# debian/jessie; the online_haspp09.xml / dif.xml / mag.xml registries). Device -# logical names and Tango control handles are real, read from that registry; vendor -# part numbers, crystal cuts, magnet field, energy calibration, and physical positions -# are not in it and are open questions. Every value is carried confirm until P09 staff -# verify it. The extraction is in the xmap/research repo (private), under petra-iii/. -# -# WHAT IS NEW: no new device Family. P09 reuses existing Families end to end. It binds -# the catalog PhaseRetarder Family (the polarization phase-retarder circles), the second -# consumer that graduated it out of loose alongside 4-ID (P22 is the third), the catalog -# PolarizationAnalyzer Family (the scattered-beam analyzer; graduated on the rule-of-three -# across 4-ID, i10, ID32, P09; POL-2), and the catalog Magnet Family (the 14 T -# sample-environment magnet, graduated; a consumer that reinforced the graduation, MAG-1). -# The diffractometer -# circles bind the catalog Goniometer Family (not the composed Diffractometer -# Assembly), the same call as P01 EH2. The techniques (resonant scattering, magnetic -# scattering, XMCD, HAXPES) earn no catalog Method; they are carried pending on the -# Site reusing the resonant_scattering / magnetic_scattering / xmcd slugs the 4-ID / -# i06 / i10 beamlines already share (TECH-1). -# -# CONTROL HANDLES: the descriptor `pv` field carries the Tango device address read -# from the OnlineXML (e.g. p09/dcmmotor/exp.01). The registry exposes generically- -# named motor banks (the MONO and DIF p09/motor banks) whose per-axis roles are not -# labelled; grouped as the optics / endstation stages, every axis role pending -# (GROUP-1). The SIS3302 fluorescence digitizer is exposed as many ROI sub-channels; -# these are grouped as one EnergyDispersiveSpectrometer Asset (DET-1). Two registry -# rows reference a p07/hexapodsmall device (a P07 device imported into the P09 -# registry); these are NOT P09 devices and are excluded (HOST-1). -# -# SCOPE: this cut models the MONO area (the undulator, the DCM, the mirrors, the CRL, -# the slits, the resonant-scattering instrument with its phase retarder / analyzer / -# diffractometer / PerkinElmer detector, the fluorescence detectors, the sample -# environment), the DIF diffraction hutch, and the MAG high-field magnetism endstation. -# Counter / timer / ADC channels and the Sardana MeasurementGroup bookkeeping rows are -# filtered out by the extractor. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/p09/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "resonant scattering, diffraction, and high-field magnetism (XMCD, magnetic scattering) across a resonant-scattering hutch, a diffraction hutch, and a 14 T magnetism endstation; a further consumer of the 4-ID polarization / magnetism vocabulary (the catalog `PhaseRetarder`, `PolarizationAnalyzer`, and `Magnet` Families), coins no new Family, reusing the pending `resonant_scattering` / `magnetic_scattering` / `xmcd` Methods" - name: P09 - facility: petra-iii # PETRA III Site (facility_code: petra-iii) - sector: "P09" - tier: Unit - parent: null - source: insertion-device - source_confirm: "P09 is an undulator beamline (resonant scattering / diffraction / magnetism); the OnlineXML exposes the undulator (p09/undulator) and its gap (p09/attributemotor/gap) but no period or parameters, carried pending (SRC-1)" - page_layout: stages - shape: "Resonant scattering and hard X-ray photoemission (HAXPES): a diffractometer plus a hemispherical electron analyzer." - source_ref: - label: "python-nxstools-extras-p09" - url: "https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p09" - -# Three enclosures: the resonant-scattering optics-and-experiment hutch (MONO), the -# diffraction hutch (DIF), and the high-field magnetism endstation (MAG). DESY PSS -# permit signals are not in the OnlineXML (PSS-1). -enclosures: - - name: p09-mono - role: optics-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the P09 MONO (optics + resonant scattering) hutch; not in the OnlineXML (PSS-1)"} - - name: p09-dif - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the DIF diffraction hutch; not in the OnlineXML (PSS-1)"} - - name: p09-mag - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the MAG high-field magnetism endstation; not in the OnlineXML (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the undulator and the MONO-hutch optics -# =========================================================================== - -source: - stage: source - enclosure: p09-mono - intro: "The P09 undulator source and the MONO-hutch optics: the double-crystal monochromator, the two mirrors, the compound refractive lens, the defining slit, and the absorber." - note: "Undulator on p09/undulator; DCM is dcmmotor / dcmener with a coupled mnchrmtr energy axis. The MONO p09/motor bank carries the optics positioning, roles not labelled (GROUP-1)." - devices: - - name: Undulator - family: InsertionDevice - pv: {undulator: "p09/undulator/1", gap: "p09/attributemotor/gap"} - new: true - confirm: true - note: "P09 undulator; gap read from the registry, period not exposed (SRC-1)" - - name: Monochromator - family: Monochromator - pv: {bragg: "p09/dcmmotor/DCM_BRAGG", energy: "p09/dcmener/energyfmb", energy_all: "p09/multiplemotors/mnchrmtr"} - new: true - confirm: true - note: "double-crystal monochromator (DCM_BRAGG / energyfmb, with the coupled mnchrmtr energy axis); crystal cut and energy range are OPT-1" - - name: Mirror1 - family: Mirror - pv: {pitch: "p09/spk/m1pitch", x: "p09/spk/m1x", y: "p09/spk/m1y", yaw: "p09/spk/m1yaw"} - new: true - confirm: true - note: "first mirror (m1: pitch / x / y / yaw, spk controller); coating / role OPT-1" - - name: Mirror2 - family: Mirror - pv: {bender: "p09/spk/m2bender", pitch: "p09/spk/m2pitch", x: "p09/spk/m2x", y: "p09/spk/m2y", yaw: "p09/spk/m2yaw"} - new: true - confirm: true - note: "second mirror (m2: bender / pitch / x / y / yaw, spk controller); coating / role OPT-1" - - name: CompoundRefractiveLens - family: Transfocator - pv: {crl: "p09/lensctrl/oh.01"} - new: true - confirm: true - note: "compound refractive lens control (crlbin, lensctrl); the CRL focusing / transfocator (OPT-1)" - - name: DefiningSlit - family: Slit - pv: {bottom: "p09/galildmcslit/G1Bottom", top: "p09/galildmcslit/G1Top", left: "p09/galildmcslit/G1Left", right: "p09/galildmcslit/G1Right", cx: "p09/galildmcslit/G1Cx", cy: "p09/galildmcslit/G1Cy", dx: "p09/galildmcslit/G1Dx", dy: "p09/galildmcslit/G1Dy"} - new: true - confirm: true - note: "MONO defining slit (G1, Galil DMC slit controller: blades + center / gap virtual axes)" - - name: Absorber - family: Filter - pv: {abs: "p09/absorber/01"} - new: true - confirm: true - note: "MONO beam absorber / attenuator (abs, absbox); folds into the Filter Family (the ID19 attenuator precedent) (OPT-1)" - - name: OpticsStages - family: LinearStage - pv: {bank: "p09/motor/exp.01"} - new: true - confirm: true - note: "the MONO optics / instrument motor bank (p09/motor/exp.*, ~98 modellable axes including the e6cctrl diffractometer controller); per-axis roles not labelled, grouped as one stage (GROUP-1)" - -# =========================================================================== -# MONO: resonant-scattering experiment (EH1) -# =========================================================================== - -mono-sample: - stage: sample - enclosure: p09-mono - intro: "The MONO resonant-scattering experiment: the polarization phase retarder, the scattered-beam analyzer, the six-circle diffractometer goniometer, the AttoCube sample piezos, and the sample-environment temperature controllers." - note: "The phase retarder (two circles) binds the catalog PhaseRetarder Family; the analyzer binds the catalog PolarizationAnalyzer Family. The diffractometer goniometer is e6cctrl; the hkl pseudo-axis is a sim device (DIFF-1)." - devices: - - name: PhaseRetarder - family: PhaseRetarder - pv: {circle1: "p09/phaseretarder/phaseretardercircle1", circle2: "p09/phaseretarder/phaseretardercircle2", pchi: "p09/attocubeanc300motor/pchi", pperp: "p09/attocubeanc300motor/pperp"} - new: true - confirm: true - note: "the polarization phase-retarder circles (phaseretardercircle1 / 2) plus the AttoCube pchi / pperp fine axes; binds the catalog PhaseRetarder Family (second consumer, graduated alongside 4-ID)" - - name: PolarizationAnalyzer - family: PolarizationAnalyzer - pv: {analyzer: "p09/analyzer/exp.01"} - new: true - confirm: true - note: "the scattered-beam polarization analyzer; binds the catalog PolarizationAnalyzer Family (POL-2)" - - name: Goniometer - family: Goniometer # catalog Family; the six-circle (E6C) sample-orientation circles, would compose a Diffractometer Assembly (DIFF-1) - pv: {ctrl: "p09/motor/exp.04", diffractometer: "p09/diffractometer/diffrac_eh1"} - new: true - confirm: true - note: "the MONO six-circle (E6C) diffractometer goniometer (e6cctrl + the diffrac_eh1 device); modelled as a Goniometer Asset, not the composed Diffractometer Assembly, until the full circle / detector-arm structure is confirmed (DIFF-1)" - - name: SampleTemperature - family: TemperatureController - pv: {cryocon: "p09/cryocontempctrl/exp.01", lks336: "p09/lks336tempctrl/exp.01", lks340: "p09/lks340tempctrl/exp.01", lsci: "p09/lscitempctrl/exp.01"} - new: true - confirm: true - note: "the MONO sample-environment temperature controllers (CryoCon 32, Lakeshore 336 / 340, and an LSCI controller); cryogenic sample cooling (TEMP-1)" - -mono-detector: - stage: detection - enclosure: p09-mono - intro: "The MONO detection: the PerkinElmer area detector, the Pilatus 300k, the SIS3302 fluorescence digitizer, and the MCA fluorescence detectors." - note: "The SIS3302 is exposed as many ROI sub-channels in the registry; grouped here as one EnergyDispersiveSpectrometer Asset (DET-1)." - devices: - - name: PerkinElmerDetector - family: Camera - pv: {ctrl: "p09/pectrl/exp.01", detector: "p09/pedetector/exp.01"} - new: true - confirm: true - note: "the MONO PerkinElmer flat-panel area detector (pectrl / pedetector); resonant-diffraction imaging (DET-1)" - - name: PilatusDetector - family: Camera - pv: {p300: "p09/pilatus/300k"} - new: true - confirm: true - note: "the MONO Pilatus 300k area detector (DET-1)" - - name: FluorescenceDetector - family: EnergyDispersiveSpectrometer - pv: {sis3302_1: "p09/sis3302/exp.01", sis3302_2: "p09/sis3302/exp.02", sis3302_3: "p09/sis3302/exp.03", sis3302_4: "p09/sis3302/exp.04", mca: "p09/mca/exp.01"} - new: true - confirm: true - note: "the MONO SIS3302 fluorescence digitizer (exposed as many ROI sub-channels, grouped here) plus the MCA; energy-dispersive fluorescence detection (DET-1)" - -# =========================================================================== -# DIF: diffraction hutch -# =========================================================================== - -dif-sample: - stage: sample - enclosure: p09-dif - intro: "The DIF diffraction hutch: the six-circle diffractometer goniometer and the diffraction sample / instrument motor bank." - note: "The diffractometer goniometer is e6cctrleh1 / eh2 (OMS VME58 controlled); the DIF p09/motor bank carries the sample positioning, roles not labelled (GROUP-1)." - devices: - - name: Goniometer - family: Goniometer # catalog Family; the DIF six-circle sample-orientation circles (DIFF-1) - pv: {ctrl_vme: "p09/omsvme58/difsimu.01", ctrl: "p09/motor/difsimu.01", diffractometer: "p09/diffractometer/difsimueh1.01"} - new: true - confirm: true - note: "the DIF six-circle (E6C) diffractometer goniometer (e6cctrleh1 / eh2, OMS VME58 controlled); modelled as a Goniometer Asset, not the composed Diffractometer Assembly (DIFF-1)" - - name: SampleStage - family: LinearStage - pv: {bank: "p09/motor/dif.01"} - new: true - confirm: true - note: "the DIF sample / instrument motor bank (p09/motor on the dif host, ~69 modellable axes); per-axis roles not labelled, grouped as one stage (GROUP-1)" - -# =========================================================================== -# MAG: high-field magnetism endstation -# =========================================================================== - -mag-sample: - stage: sample - enclosure: p09-mag - intro: "The MAG high-field magnetism endstation: the 14 T superconducting magnet, the six-circle diffractometer goniometer, a sample hexapod, the PI sample piezos, the polarization analyzer, and the sample-environment temperature controllers." - note: "The 14 T magnet binds the graduated catalog Magnet Family (presents Regulator). The hexapod is hexapodmotor; the piezos are PI E-710 (scan) and E-725 (sample)." - devices: - - name: Magnet - family: Magnet - pv: {magnet: "p09/magnet/exp.01"} - new: true - confirm: true - note: "the MAG 14 T superconducting sample-environment magnet (magnet14tf); binds the graduated catalog Magnet Family (presents Regulator, MAG-1)" - - name: Goniometer - family: Goniometer # catalog Family; the MAG six-circle sample-orientation circles (DIFF-1) - pv: {ctrl: "p09/diffractometer/diffrac_mag", mu: "p09/diffracmu/mu"} - new: true - confirm: true - note: "the MAG six-circle (E6C) diffractometer goniometer (diffrac_mag + the diffracmu mu circle); modelled as a Goniometer Asset, not the composed Diffractometer Assembly (DIFF-1)" - - name: SampleHexapod - family: Hexapod - pv: {u: "p09/hexapodmotor/hexa_u", v: "p09/hexapodmotor/hexa_v", w: "p09/hexapodmotor/hexa_w", x: "p09/hexapodmotor/hexa_x", y: "p09/hexapodmotor/hexa_y", z: "p09/hexapodmotor/hexa_z"} - new: true - confirm: true - note: "the MAG sample hexapod (hexa_*); coarse sample positioning within the magnet (SAMPLE-1)" - - name: SamplePiezo - family: LinearStage - pv: {scanx: "p09/piezopie710/scanx", scany: "p09/piezopie710/scany", scanz: "p09/piezopie710/scanz", piezo_x: "p09/piezopie725/piezo_x", piezo_y: "p09/piezopie725/piezo_y", piezo_z: "p09/piezopie725/piezo_z"} - new: true - confirm: true - note: "the MAG sample piezos (PI E-710 scan + E-725 sample); fine sample positioning (SAMPLE-1)" - - name: PolarizationAnalyzer - family: PolarizationAnalyzer - pv: {analyzer: "p09/analyzer/mag.01"} - new: true - confirm: true - note: "the MAG scattered-beam polarization analyzer; binds the catalog PolarizationAnalyzer Family (POL-2)" - - name: Absorber - family: Filter - pv: {abs: "p09/absorbercontroller/mag.01"} - new: true - confirm: true - note: "the MAG beam absorber / attenuator (abs, absorbercontroller); folds into the Filter Family (OPT-1)" - - name: SampleTemperature - family: TemperatureController - pv: {lks336: "p09/lks336tempctrl/mag.01", lks340: "p09/lks340tempctrl/mag.01"} - new: true - confirm: true - note: "the MAG sample-environment temperature controllers (Lakeshore 336 / 340) (TEMP-1)" - -mag-detector: - stage: detection - enclosure: p09-mag - intro: "The MAG detection: the Pilatus 100k area detector and the Andor (Lima-controlled) camera." - note: "Handles read from p09/pilatus and p09/limaccds. The detector roster per experiment is DET-1." - devices: - - name: PilatusDetector - family: Camera - pv: {p100: "p09/pilatus/p100k"} - new: true - confirm: true - note: "the MAG Pilatus 100k area detector (DET-1)" - - name: AndorCamera - family: Camera - pv: {andor: "p09/limaccds/andor.01"} - new: true - confirm: true - note: "the MAG Andor camera (Lima-controlled); imaging / diagnostics (DET-1)" - -# Cross-cutting control. P09 runs Tango with Sardana, the PETRA III house style. -controls: - intro: > - P09 runs on the PETRA III control system, Tango with Sardana as the scan / motion - SCADA layer, the same floor as the other PETRA III beamlines. A motion axis is a - Tango motor device (p09/motor/...), the monochromator a dcmmotor / dcmener device, - the mirrors spk devices, the slits Galil DMC slit controllers (galildmcslit), the - diffractometer an e6cctrl / diffractometer device, the magnet a magnet device, the - phase retarder / analyzer their own devices; the fine sample stages are AttoCube - (attocubeanc300motor) and PI (piezopie710 / piezopie725) controllers, plus a - hexapod. The detectors are PerkinElmer (pectrl / pedetector), Pilatus, Andor - (Lima), the SIS3302 fluorescence digitizer, and MCAs; instruments connect over GPIB - (gpib / Keithley). The handles are read from P09's public OnlineXML registry and - carried confirm (CTRL-1). The resonant-scattering / magnetism acquisition (the - energy / diffractometer / field scan coupled to the detector readout) runs as a - Sardana macro; that orchestration is the seam CORA's edge would conduct over its - ControlPort, the same shape as the 4-ID seam (CTRL-2). - motion_controllers: - - name: OMS58Controllers - family: MotionController - protocol: Tango_oms58 - new: true - confirm: true - note: "OMS MAXv-58 and VME58 stepper controllers (oms58 / omsvme58) driving the optics, diffractometer, and sample motor banks (CTRL-1)" - - name: GalilSlitControllers - family: MotionController - protocol: Tango_galildmcslit - new: true - confirm: true - note: "Galil DMC slit controllers (galildmcslit) driving the MONO defining slit (CTRL-1)" - - name: PiezoControllers - family: MotionController - protocol: Tango_piezo - new: true - confirm: true - note: "PI piezo controllers (piezopie710 / piezopie725) and AttoCube controllers (attocubeanc300motor) driving the fine sample / phase-retarder stages (CTRL-1)" - - name: HexapodControllers - family: MotionController - protocol: Tango_hexapod - new: true - confirm: true - note: "hexapod controllers (hexapodmotor) driving the MAG sample hexapod (CTRL-1)" - - name: TangoMotorControllers - family: MotionController - protocol: Tango_motor_tango - new: true - confirm: true - note: "generic Tango motor controllers (motor_tango / spk) backing the mono, mirrors, and coupled axes (CTRL-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a P09 run needs present before it - can start. All pending confirmation. LiquidHelium is the cryogen for the 14 T - superconducting magnet. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: LiquidHelium diff --git a/deployments/p10/beamline.yaml b/deployments/p10/beamline.yaml deleted file mode 100644 index 43d8f984672..00000000000 --- a/deployments/p10/beamline.yaml +++ /dev/null @@ -1,391 +0,0 @@ -# P10 beamline descriptor (PETRA III, DESY), reverse-engineered from the OnlineXML -# -# P10 "Coherence Applications" is the coherent hard X-ray beamline at PETRA III -# (DESY, Hamburg): X-ray photon correlation spectroscopy (XPCS), coherent diffraction -# imaging, and coherent-beam diffraction across three endstations. It is bound to the -# PETRA III Site (deployments/petra-iii/site.yaml), the sixth PETRA III beamline. -# -# STATUS: reverse-engineered from P10's own public OnlineXML device registry -# (gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p10, branch -# debian/jessie; the online_haspp10e1.xml / e2.xml / lab.xml registries). Device -# logical names and Tango control handles are real, read from that registry; vendor -# part numbers, coherence lengths, energy calibration, and physical positions are not -# in it and are open questions. Every value is carried confirm until P10 staff verify -# it. The extraction is in the xmap/research repo (private), under petra-iii/. -# -# WHAT IS NEW: no new device Family. P10 reuses existing Families end to end, and it -# is the fleet's second XPCS beamline after the APS 8-ID exercise (which graduated the -# xpcs Method). It binds a graduated XPCS Method directly (not pending), the first -# PETRA III beamline whose primary technique is already in the catalog. Coherent -# imaging reuses the pending ptychography / coherent_surface_scattering slugs (TECH-1). -# -# CONTROL HANDLES: the descriptor `pv` field carries the Tango device address read -# from the OnlineXML (e.g. p10/dcmmotor/opt.01). The registry exposes generically- -# named motor banks (OPT_MOT, E1_MOT, E2_MOT) whose per-axis roles are not labelled; -# these are grouped as the optics / endstation stages carrying the handles, every axis -# role pending (GROUP-1). Several detectors (Lambda, Lima MAX22/MAX51) report on a bare -# p10 host without an endstation token; per the cross-host mapping decision they are -# homed in the endstation that operates them with the host flagged (HOST-1). -# -# SCOPE: this cut models the optics hutch (OPT: undulator, DCM, optics stages, the -# beam shutter) and the three experiment areas (E1 coherent imaging, E2 XPCS / -# diffraction, LAB) plus the LCX piezo sub-station, with their sample stages, -# hexapods, slits, and detectors (Lambda, Eiger, Pilatus, PCO, Andor, the Lima -# cameras). Counter / timer / ADC channels and the Sardana MeasurementGroup -# bookkeeping rows are filtered out by the extractor. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/p10/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "coherent hard X-ray applications (XPCS, coherent diffraction imaging / ptychography) across an optics hutch and three experiment areas (E1 coherent imaging, E2 XPCS / diffraction, LAB); a further XPCS beamline (after APS 8-ID and NSLS-II CHX) and the first PETRA III practice to bind a graduated catalog Method (`xpcs`, earned at 8-ID) rather than a pending slug; coins no new Family, with the widest detector suite in the set" - name: P10 - facility: petra-iii # PETRA III Site (facility_code: petra-iii) - sector: "P10" - tier: Unit - parent: null - source: insertion-device - source_confirm: "P10 is an undulator beamline (coherent hard X-rays); the OnlineXML exposes the undulator (p10/undulator) and its gap (p10/attributemotor/UNDULATORGAP) but no period or parameters, carried pending (SRC-1)" - page_layout: stages - shape: "Coherence applications (XPCS, coherent imaging / ptychography) across three areas; the first PETRA III beamline whose primary technique binds a graduated catalog Method directly." - source_ref: - label: "python-nxstools-extras-p10" - url: "https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p10" - -# Five enclosures: the optics hutch, the three experiment areas (E1 coherent imaging, -# E2 XPCS / diffraction, LAB), and the LCX piezo sub-station. DESY PSS permit signals -# are not in the OnlineXML (PSS-1). -enclosures: - - name: p10-opt - role: optics-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the P10 optics hutch; not in the OnlineXML (PSS-1)"} - - name: p10-e1 - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for E1 (coherent imaging); not in the OnlineXML (PSS-1)"} - - name: p10-e2 - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for E2 (XPCS / diffraction); not in the OnlineXML (PSS-1)"} - - name: p10-lab - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the LAB area; not in the OnlineXML (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the undulator and the optics hutch -# =========================================================================== - -source: - stage: source - enclosure: p10-opt - intro: "The P10 undulator source and the optics hutch: the double-crystal monochromator, the optics stages, and the beam shutter, feeding a coherent beam to the three experiment areas." - note: "Undulator on p10/undulator with the gap as an attributemotor; the DCM is dcmmotor / dcmener with a coupled P10ENERGY axis. The OPT_MOT bank carries the optics positioning, roles not labelled (GROUP-1)." - devices: - - name: Undulator - family: InsertionDevice - pv: {undulator: "p10/undulator/1", gap: "p10/attributemotor/UNDULATORGAP"} - new: true - confirm: true - note: "P10 undulator; gap read from the registry, period not exposed (SRC-1)" - - name: Monochromator - family: Monochromator - pv: {bragg: "p10/dcmmotor/DCM_BRAGG", energy: "p10/dcmener/FMBENERGY", energy_mnchr: "p10/dcmener/MNCHRMTR", energy_all: "p10/multiplemotors/P10ENERGY"} - new: true - confirm: true - note: "double-crystal monochromator (DCM_BRAGG / FMBENERGY, with the coupled P10ENERGY axis); crystal cut and energy range are OPT-1" - - name: OpticsStages - family: LinearStage - pv: {bank: "p10/motor/OPT_MOT01"} - new: true - confirm: true - note: "the optics-hutch motor bank (OPT_MOT01..32 on p10/motor): mirror / slit / lens motions, per-axis roles not labelled, grouped as one stage (OPT-1, GROUP-1)" - - name: OpticsVirtualStages - family: PseudoAxis - pv: {bank: "p10/vmexecutor/vm_opt_01"} - new: true - confirm: true - note: "the optics-hutch virtual / coupled axes (vm_opt_* on vmexecutor): slit center / gap and coupled optics motions (GROUP-1)" - - name: BeamShutter - family: Shutter - pv: {shutter: "p10/shutter/P10SHUTTER"} - new: true - confirm: true - note: "the P10 beam shutter (P10SHUTTER); gates the coherent beam into the experiment areas (PSS-1)" - -# =========================================================================== -# E1: coherent imaging endstation -# =========================================================================== - -e1-sample: - stage: sample - enclosure: p10-e1 - intro: "The E1 coherent-imaging endstation: a six-axis hexapod, the compound refractive lens box, the Galil-controlled guard slit, and the dense E1 sample / instrument motor bank with its virtual axes." - note: "The hexapod is six hexapodmotor axes; the CRL is a lensesbox (EHCRL); the E1_MOT bank (97 axes incl. the e6cctrl diffractometer controller) carries the sample positioning, roles not labelled (GROUP-1)." - devices: - - name: Hexapod - family: Hexapod - pv: {x: "p10/hexapodmotor/HEXAX", y: "p10/hexapodmotor/HEXAY", z: "p10/hexapodmotor/HEXAZ", rx: "p10/hexapodmotor/HEXARX", ry: "p10/hexapodmotor/HEXARY", rz: "p10/hexapodmotor/HEXARZ"} - new: true - confirm: true - note: "E1 six-axis hexapod (HEXAX-HEXARZ); coarse sample orientation" - - name: CompoundRefractiveLens - family: Transfocator - pv: {crl: "p10/lensesbox/EHCRL"} - new: true - confirm: true - note: "E1 compound refractive lens box (EHCRL, lensesbox); the CRL focusing / transfocator (OPT-1)" - - name: GuardSlit - family: Slit - pv: {bottom: "p10/galildmcslit/G1BOTTOM", top: "p10/galildmcslit/G1TOP", left: "p10/galildmcslit/G1LEFT", right: "p10/galildmcslit/G1RIGHT", cx: "p10/galildmcslit/G1CX", cy: "p10/galildmcslit/G1CY", dx: "p10/galildmcslit/G1DX", dy: "p10/galildmcslit/G1DY"} - new: true - confirm: true - note: "E1 guard slit (G1, Galil DMC slit controller: blades + center / gap virtual axes); the coherence-defining slit (OPT-1)" - - name: SampleStage - family: LinearStage - pv: {bank: "p10/motor/E1_MOT01", diffractometer: "p10/motor/e6cctrl"} - new: true - confirm: true - note: "the E1 sample / instrument motor bank (E1_MOT01..97 on p10/motor, including the e6cctrl six-circle diffractometer controller); per-axis roles not labelled, grouped as one stage (GROUP-1)" - - name: SampleVirtualStages - family: PseudoAxis - pv: {bank: "p10/vmexecutor/vm_e1_01"} - new: true - confirm: true - note: "the E1 virtual / coupled axes (vm_e1_* on vmexecutor): slit and coupled sample motions (GROUP-1)" - -e1-detector: - stage: detection - enclosure: p10-e1 - intro: "The E1 detection: the Quadro area detector and the MCA fluorescence detectors." - note: "Handles read from p10/ccdpvcam and p10/mca. The detector roster per experiment is DET-1." - devices: - - name: QuadroDetector - family: Camera - pv: {quadro: "p10/ccdpvcam/QUADRO"} - new: true - confirm: true - note: "E1 Quadro area detector (ADSC / Dectris Quadro, ccdpvcam); coherent-imaging detection (DET-1)" - - name: FluorescenceDetectors - family: EnergyDispersiveSpectrometer - pv: {mca01: "p10/mca/E1_MCA01", mca02: "p10/mca/E1_MCA02", mca03: "p10/mca/E1_MCA03", mca04: "p10/mca/E1_MCA04"} - new: true - confirm: true - note: "E1 MCA fluorescence detectors (DET-1)" - -# =========================================================================== -# E2: XPCS / diffraction endstation -# =========================================================================== - -e2-sample: - stage: sample - enclosure: p10-e2 - intro: "The E2 XPCS / coherent-diffraction endstation: the two mirror stages, the SmarAct sample piezos, the two-theta arm, the Galil guard slit, and the dense E2 sample / instrument motor bank." - note: "The mirrors are spk controllers; the SmarAct piezos (SPX/SPY/SPZ) are fine sample stages; eh2tth is the two-theta detector arm. The E2_MOT bank (96 axes) carries the sample positioning, roles not labelled (GROUP-1)." - devices: - - name: Mirrors - family: Mirror - pv: {mirror1_y: "p10/spk/mirror1y", mirror1_rz: "p10/spk/mirror1rz", mirror2_y: "p10/spk/mirror2y", mirror2_rz: "p10/spk/mirror2rz", mirror_z: "p10/spk/mirrorz"} - new: true - confirm: true - note: "E2 mirror stages (mirror1 / mirror2 y / rz plus mirrorz, spk controllers); the E2 focusing / steering mirrors (OPT-1)" - - name: SamplePiezo - family: LinearStage - pv: {x: "p10/smaractmcsmotor/SPX", y: "p10/smaractmcsmotor/SPY", z: "p10/smaractmcsmotor/SPZ"} - new: true - confirm: true - note: "E2 SmarAct sample piezos (SPX / SPY / SPZ); fine sample positioning for XPCS (SAMPLE-1)" - - name: TwoThetaArm - family: RotaryStage - pv: {tth: "p10/eh2tth/eh2tthp10"} - new: true - confirm: true - note: "E2 two-theta detector arm (eh2tthp10); the scattering-angle axis for coherent diffraction (SAMPLE-1)" - - name: GuardSlit - family: Slit - pv: {bottom: "p10/galildmcslit/G2BOTTOM", top: "p10/galildmcslit/G2TOP", left: "p10/galildmcslit/G2LEFT", right: "p10/galildmcslit/G2RIGHT", cx: "p10/galildmcslit/G2CX", cy: "p10/galildmcslit/G2CY", dx: "p10/galildmcslit/G2DX", dy: "p10/galildmcslit/G2DY"} - new: true - confirm: true - note: "E2 guard slit (G2, Galil DMC slit controller); the coherence-defining slit (OPT-1)" - - name: SampleStage - family: LinearStage - pv: {bank: "p10/motor/E2_MOT01"} - new: true - confirm: true - note: "the E2 sample / instrument motor bank (E2_MOT01..96 on p10/motor); per-axis roles not labelled, grouped as one stage (GROUP-1)" - - name: SampleVirtualStages - family: PseudoAxis - pv: {bank: "p10/vmexecutor/vm_e2_02"} - new: true - confirm: true - note: "the E2 virtual / coupled axes (vm_e2_* on vmexecutor) (GROUP-1)" - -e2-detector: - stage: detection - enclosure: p10-e2 - intro: "The E2 detection: the XPCS / coherent-diffraction detector suite (Pilatus, PCO, LCX), plus the shared Lambda and Lima cameras." - note: "The Pilatus detectors (P100 / P1M / P300) and the PCO edge are the XPCS area detectors. The Lambda (p10/lambda) and Lima MAX22 / MAX51 cameras report on a bare p10 host (HOST-1). The operative roster per experiment is DET-1." - devices: - - name: PilatusDetectors - family: Camera - pv: {p100: "p10/pilatus/P100", p1m: "p10/pilatus/P1M", p300: "p10/pilatus/P300"} - new: true - confirm: true - note: "E2 Pilatus area detectors (100k / 1M / 300k); XPCS / coherent-diffraction detection (DET-1)" - - name: PCODetector - family: Camera - pv: {pco: "p10/pco/PCOEDGE"} - new: true - confirm: true - note: "E2 PCO edge sCMOS camera; fast imaging (DET-1)" - - name: LCXCamera - family: Camera - pv: {lcx: "p10/lcxcamera/LCX"} - new: true - confirm: true - note: "E2 LCX camera; beam / sample diagnostics (DET-1)" - - name: LambdaDetector - family: Camera - pv: {l01: "p10/lambda/l01", l02: "p10/lambda/l02", ldev: "p10/lambda/ldev"} - new: true - confirm: true - note: "the shared X-Spectrum Lambda detectors; report on the bare p10 host (HOST-1); the high-frame-rate XPCS detector (DET-1)" - - name: LimaCameras - family: Camera - pv: {max22ccd: "p10/limaccd/MAX22CCD", max51ccd: "p10/limaccd/MAX51CCD", max22dev: "p10/limampx/MAX22DEV", max51dev: "p10/limampx/MAX51DEV"} - new: true - confirm: true - note: "the shared Lima-controlled cameras (MAX22 / MAX51, limaccd / limampx); report on the bare p10 host (HOST-1, DET-1)" - -# =========================================================================== -# LAB: laboratory / offline endstation -# =========================================================================== - -lab-sample: - stage: sample - enclosure: p10-lab - intro: "The LAB area: a simulated six-circle diffractometer (the e6cctrl_simu and its chi / delta / gamma / mu / omega / phi simulation axes) for offline alignment and testing." - note: "The LAB axes are simulation / test devices (e6cctrl_simu and *_simu); modelled as a single offline diffractometer stage (LAB-1)." - devices: - - name: SimulatedDiffractometer - family: Goniometer - pv: {ctrl: "p10/motor/e6cctrl_simu", chi: "p10/motor/chi_simu", delta: "p10/motor/delta_simu", gamma: "p10/motor/gamma_simu", mu: "p10/motor/mu_simu", omega: "p10/motor/omega_simu"} - new: true - confirm: true - note: "LAB simulated six-circle (E6C) diffractometer (e6cctrl_simu + chi / delta / gamma / mu / omega / phi simulation axes); offline alignment / testing, bound to Goniometer (LAB-1)" - -lab-detector: - stage: detection - enclosure: p10-lab - intro: "The LAB detectors: an Eiger 4M, an Andor camera, a Mythen strip detector, and the Lima-controlled Andor CCD, for offline detector testing." - note: "Handles read from p10/eigerdectris, p10/andor, p10/mythen, p10/limaccds. The LAB detectors are offline / test units (LAB-1, DET-1)." - devices: - - name: EigerDetector - family: Camera - pv: {e4m: "p10/eigerdectris/E4M"} - new: true - confirm: true - note: "LAB DECTRIS Eiger 4M area detector (DET-1)" - - name: AndorCamera - family: Camera - pv: {andor: "p10/andor/ANDORDEV", andor_ccd: "p10/limaccds/ANDORCCD"} - new: true - confirm: true - note: "LAB Andor camera (andor / Lima-controlled andorccd) (DET-1)" - - name: MythenDetector - family: Camera - pv: {mythen: "p10/mythen/MYTHEN"} - new: true - confirm: true - note: "LAB Mythen strip detector; one-dimensional diffraction (DET-1)" - -# =========================================================================== -# LCX: piezo sub-station -# =========================================================================== - -lcx-sample: - stage: sample - enclosure: p10-e2 - intro: "The LCX piezo sub-station: AttoCube and SmarAct nano-positioning piezos, a coherent-imaging sample sub-stage within the E2 area." - note: "AttoCube (APINY / APINZ) and SmarAct (SPX / SPY / SPZ) piezos; modelled as a nano-positioning stage in the E2 enclosure (LCX-1)." - devices: - - name: NanoPositioner - family: LinearStage - pv: {attocube_y: "p10/attocubemotor/APINY", attocube_z: "p10/attocubemotor/APINZ", smaract_x: "p10/smaractmotor/SPX", smaract_y: "p10/smaractmotor/SPY", smaract_z: "p10/smaractmotor/SPZ"} - new: true - confirm: true - note: "LCX nano-positioning piezos (AttoCube APINY / APINZ + SmarAct SPX / SPY / SPZ); the coherent-imaging sample sub-stage (LCX-1, SAMPLE-1)" - -# Cross-cutting control. P10 runs Tango with Sardana, the PETRA III house style. -controls: - intro: > - P10 runs on the PETRA III control system, Tango with Sardana as the scan / motion - SCADA layer, the same floor as the other PETRA III beamlines. A motion axis is a - Tango motor device (p10/motor/...), the monochromator a dcmmotor / dcmener device, - the mirrors spk devices, the slits Galil DMC slit controllers (galildmcslit), the - fine sample stages SmarAct (smaractmcsmotor / smaractmotor) and AttoCube - (attocubemotor) controllers, the hexapod a hexapodmotor; the detectors are a wide - suite (pilatus, eigerdectris, pco, lambda, andor, mythen, ccdpvcam, lcxcamera, and - Lima-controlled limaccd / limampx). The handles are read from P10's public - OnlineXML registry and carried confirm (CTRL-1). The XPCS acquisition (the coherent - beam on the sample read by the high-frame-rate Lambda / Eiger, the correlation - computed downstream) runs as a Sardana macro; that orchestration is the seam CORA's - edge would conduct over its ControlPort, the same shape as the 8-ID XPCS seam - (CTRL-2). - motion_controllers: - - name: OMS58Controllers - family: MotionController - protocol: Tango_oms58 - new: true - confirm: true - note: "OMS MAXv-58 stepper controllers (oms58) driving the optics and sample motor banks (CTRL-1)" - - name: GalilSlitControllers - family: MotionController - protocol: Tango_galildmcslit - new: true - confirm: true - note: "Galil DMC slit controllers (galildmcslit) driving the E1 / E2 guard slits (CTRL-1)" - - name: SmarActControllers - family: MotionController - protocol: Tango_smaract - new: true - confirm: true - note: "SmarAct controllers (smaractmcsmotor / smaractmotor) driving the E2 / LCX sample piezos (CTRL-1)" - - name: AttoCubeControllers - family: MotionController - protocol: Tango_attocube - new: true - confirm: true - note: "AttoCube controllers (attocubemotor) driving the LCX nano-positioning piezos (CTRL-1)" - - name: HexapodControllers - family: MotionController - protocol: Tango_hexapod - new: true - confirm: true - note: "hexapod controllers (hexapodmotor) driving the E1 hexapod (CTRL-1)" - - name: TangoMotorControllers - family: MotionController - protocol: Tango_motor_tango - new: true - confirm: true - note: "generic Tango motor controllers (motor_tango / spk / dcm) backing the mono, mirrors, and coupled axes (CTRL-1)" - triggering: - - name: Timing - family: TimingController - new: true - confirm: true - note: "the XPCS exposure-gating timing hardware feeding the coherent detectors (the 8-ID / CHX TimingController pattern); P10 runs XPCS so the gating fabric is present, the specific device and handle are read from the Sardana seam and carried confirm (CTRL-2)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a P10 run needs present before it - can start. All pending confirmation. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/p11/beamline.yaml b/deployments/p11/beamline.yaml deleted file mode 100644 index 202addd9a52..00000000000 --- a/deployments/p11/beamline.yaml +++ /dev/null @@ -1,213 +0,0 @@ -# P11 beamline descriptor (PETRA III, DESY), reverse-engineered from the OnlineXML -# -# P11 "Bio-Imaging and Diffraction" is the macromolecular-crystallography and -# bio-imaging beamline at PETRA III (DESY, Hamburg): high-throughput rotation MX plus -# coherent / full-field bio-imaging. It is bound to the PETRA III Site -# (deployments/petra-iii/site.yaml), the fourth PETRA III beamline after P01, P04, P06, -# and the first PETRA III macromolecular-crystallography beamline. -# -# STATUS: reverse-engineered from P11's own public OnlineXML device registry -# (gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p11, branch -# debian/jessie). Device logical names and Tango control handles are real, read from -# that registry; vendor part numbers, the goniometer geometry, the detector model, and -# physical positions are not in it and are open questions. The P11 registry is sparser -# in labelling than P01 / P06: most of its devices are area-grouped motor banks -# (oh_mot*, granite_mot*, eh1/eh2/eh3_mot*, the piezomotor bank) whose per-axis roles -# are not exposed, so the Asset grouping leans on the area prefixes and is carried -# confirm (GROUP-1). Every value is carried confirm until P11 staff verify it. -# -# WHAT IS NEW: no new device Family, and no new technique vocabulary. P11 is the -# fourth macromolecular-crystallography beamline CORA models (after Diamond i03, -# NSLS-II FMX / AMX, the Australian Synchrotron MX3, Sirius MANACA, NSRRC TPS 07A / -# 05A) and PETRA III's first. It reuses the MX vocabulary: the cryostream binds the -# graduated TemperatureController, the area detector binds Camera, the fluorescence -# detector EnergyDispersiveSpectrometer, the optics and sample motions LinearStage / -# Slit. The MX technique reuses the pending i03 mx_data_collection Method, and the -# bio-imaging reuses the catalog tomography Method (TECH-1). -# -# CONTROL HANDLES: the descriptor `pv` field carries the Tango device address read -# from the OnlineXML (e.g. p11/pilatus/eh.01). The registry exposes one Tango host -# (haspp11oh) for the whole beamline; the optics-hutch (oh) and experiment-hutch -# (eh1/eh2/eh3) areas are inferred from the device-name prefixes, not from distinct -# hosts, so the enclosure split is carried confirm (ENC-1). -# -# SCOPE: this cut models the optics hutch (the oh and granite motor banks) and the -# experiment hutch (the eh1 / eh2 / eh3 / piezomotor banks, the servo, the cryostream, -# the Pilatus detector, the XIA fluorescence detector). Because the registry does not -# label the goniometer or the MX-specific instruments, they are grouped as the -# experiment-hutch positioning stages, with the MX structure carried as a question -# (MX-1). Counter / timer / ADC channels and the Sardana MeasurementGroup bookkeeping -# rows are filtered out by the extractor and not modelled. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/p11/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "high-throughput macromolecular crystallography (rotation MX) and bio-imaging on a goniometer + Pilatus detector with cryostream cooling; PETRA III's first MX beamline, a reuse-and-reinforce deployment coining no new vocabulary (reuses the i03 MX vocabulary and the pending `mx_data_collection` / `tomography` Methods); a sparse registry, so the experiment hutch is modelled as grouped stages with the goniometer carried as a question" - name: P11 - facility: petra-iii # PETRA III Site (facility_code: petra-iii) - sector: "P11" - tier: Unit - parent: null - source: insertion-device - source_confirm: "P11 is an undulator beamline for macromolecular crystallography and bio-imaging; the OnlineXML exposes no undulator device (it sits on the single haspp11oh host with the beamline motors), so the source is carried pending (SRC-1)" - page_layout: stages - shape: "Macromolecular crystallography: rotation MX on a micro-goniometer and area detector with an automated sample changer, reusing the fleet MX vocabulary." - source_ref: - label: "python-nxstools-extras-p11" - url: "https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p11" - -# Two enclosures inferred from the device-name prefixes (the registry exposes one -# Tango host, haspp11oh, for the whole beamline): the optics hutch (oh / granite) and -# the experiment hutch (eh1 / eh2 / eh3). DESY PSS permit signals are not in the -# OnlineXML (PSS-1). -enclosures: - - name: p11-oh - role: optics-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the P11 optics hutch; not in the OnlineXML (PSS-1)"} - - name: p11-eh - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the P11 experiment hutch; not in the OnlineXML (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the optics-hutch conditioning -# =========================================================================== - -source: - stage: source - enclosure: p11-oh - intro: "The P11 optics hutch: the beam-conditioning motions on the oh and granite motor banks. The monochromator, mirrors, and slits are not individually labelled in the registry, so they are grouped as the optics-hutch positioning stages." - note: "Handles read from p11/motor/oh.* and p11/motor/granite.*. The optics breakdown (monochromator, mirrors, slits) is OPT-1; the granite bank is the optics support / table stage." - devices: - - name: OpticsStages - family: LinearStage - pv: {bank: "p11/motor/oh.01"} - new: true - confirm: true - note: "the optics-hutch motor bank (oh_mot01..32 on p11/motor/oh.*): monochromator, mirror, and slit motions, per-axis roles not labelled, grouped as one stage carrying the bank prefix (OPT-1, GROUP-1)" - - name: GraniteStage - family: LinearStage - pv: {bank: "p11/motor/granite.01"} - new: true - confirm: true - note: "the granite support / table bank (granite_mot01..05 on p11/motor/granite.*); the optics or experiment granite base, role pending (GROUP-1)" - -# =========================================================================== -# SAMPLE STAGE: the experiment-hutch positioning and the MX sample environment -# =========================================================================== - -experiment-sample: - stage: sample - enclosure: p11-eh - intro: "The P11 experiment hutch: the eh1 / eh2 / eh3 motor banks and the piezomotor bank carrying the sample positioning, the goniometer, and the detector / instrument motions, plus the servo motor and the Oxford Cryostream sample cooling." - note: "The MX goniometer and the sample-changer robot are not individually labelled in the registry; the eh banks are grouped as the experiment-hutch positioning stages, with the MX structure carried as a question (MX-1)." - devices: - - name: ExperimentStage1 - family: LinearStage - pv: {bank: "p11/motor/eh.1.06"} - new: true - confirm: true - note: "the eh1 motor bank (eh1_mot06..16 on p11/motor/eh.1.*): experiment-hutch positioning, roles not labelled, grouped as one stage (GROUP-1, MX-1)" - - name: ExperimentStage2 - family: LinearStage - pv: {bank: "p11/motor/eh.2.01"} - new: true - confirm: true - note: "the eh2 motor bank (eh2_mot01..16 on p11/motor/eh.2.*): experiment-hutch positioning, roles not labelled (GROUP-1, MX-1)" - - name: ExperimentStage3 - family: LinearStage - pv: {bank: "p11/motor/eh.3.01"} - new: true - confirm: true - note: "the eh3 motor bank (eh3_mot01..16 on p11/motor/eh.3.*): experiment-hutch positioning, roles not labelled (GROUP-1, MX-1)" - - name: PiezoStage - family: LinearStage - pv: {bank: "p11/piezomotor/eh.4.01"} - new: true - confirm: true - note: "the experiment-hutch piezo bank (ehpm3_mot01..16 on p11/piezomotor/eh.4.*): fine sample / instrument positioning, roles not labelled (GROUP-1)" - - name: ServoStage - family: LinearStage - pv: {servo: "p11/servomotor/eh.1.01"} - new: true - confirm: true - note: "the eh1 servo motor (eh1_srv01); a continuous / high-speed axis, role pending (GROUP-1)" - - name: SampleTemperature - family: TemperatureController - pv: {cryo: "p11/cryo/eh.01"} - new: true - confirm: true - note: "the experiment-hutch sample cooling (eh_cryo01, Oxford Cryostream 700); the MX cryocooling, bound to the graduated TemperatureController (TEMP-1)" - -# =========================================================================== -# DETECTION STAGE: the area detector and the fluorescence detector -# =========================================================================== - -detection: - stage: detection - enclosure: p11-eh - intro: "The P11 detection: the Pilatus area detector for diffraction, and the XIA fluorescence detector." - note: "Handles read from p11/pilatus and p11/xia. The detector model (Pilatus variant) and the goniometer-to-detector geometry are DET-1." - devices: - - name: AreaDetector - family: Camera - pv: {pilatus: "p11/pilatus/eh.01"} - new: true - confirm: true - note: "the experiment-hutch Pilatus area detector (eh_pilatus01); MX diffraction imaging, the detector variant is DET-1" - - name: FluorescenceDetector - family: EnergyDispersiveSpectrometer - pv: {xia: "p11/xia/oh.1"} - new: true - confirm: true - note: "the XIA multi-channel-analyzer fluorescence detector (eh_xia01); element identification / edge scanning (DET-1)" - -# Cross-cutting control. P11 runs Tango with Sardana, the PETRA III house style. -controls: - intro: > - P11 runs on the PETRA III control system, Tango with Sardana as the scan / motion - SCADA layer, the same floor as P01, P04, and P06. The whole beamline reports on a - single Tango host (haspp11oh); a motion axis is a Tango motor device - (p11/motor/.), the piezo axes are piezomotor devices, the high-speed axis - a servomotor device, the cryostream a cryo device, and the detectors are pilatus - and xia device servers. The handles are read from P11's public OnlineXML registry - and carried confirm (CTRL-1). The rotation-MX acquisition (the goniometer - oscillation coupled to the Pilatus frame capture) runs as a Sardana macro; that - orchestration is the seam CORA's edge would conduct over its ControlPort, the same - shape as the MX cluster seams at i03 / MANACA / TPS 07A (CTRL-2). - motion_controllers: - - name: OMS58Controllers - family: MotionController - protocol: Tango_oms58 - new: true - confirm: true - note: "OMS MAXv-58 stepper controllers (oms58) driving the oh, granite, and eh motor banks (CTRL-1)" - - name: PiezoMotorControllers - family: MotionController - protocol: Tango_piezomotor - new: true - confirm: true - note: "piezomotor controllers driving the experiment-hutch fine piezo bank (CTRL-1)" - - name: TangoMotorControllers - family: MotionController - protocol: Tango_motor_tango - new: true - confirm: true - note: "generic Tango motor controllers (motor_tango / servomotor) backing the servo and coupled axes (CTRL-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a P11 run needs present before it - can start. All pending confirmation. LiquidNitrogen is the cryostream supply for - the MX sample cooling. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: LiquidNitrogen diff --git a/deployments/p13/beamline.yaml b/deployments/p13/beamline.yaml deleted file mode 100644 index 566370ad298..00000000000 --- a/deployments/p13/beamline.yaml +++ /dev/null @@ -1,250 +0,0 @@ -# P13 beamline descriptor (PETRA III, EMBL Hamburg), reverse-engineered from MXCuBE -# -# P13 is the EMBL Hamburg macromolecular-crystallography (MX) beamline on the PETRA III -# ring at DESY, Hamburg. It is operated by EMBL Hamburg, not by DESY, and it is the -# first EMBL Hamburg beamline CORA models. It is bound to the PETRA III Site -# (deployments/petra-iii/site.yaml) by facility_code, the eighteenth PETRA III beamline -# scaffold and the third PETRA III MX-family beamline after P11 (DESY) and, on the same -# EMBL endstation cluster, its sibling P14. -# -# STATUS: reverse-engineered from EMBL Hamburg's own public MXCuBE HardwareObjects -# configuration (github.com/mxcube/mxcubecore, configuration/embl_hh_p13), the device -# topology MXCuBE drives at the beamline. Device logical names and control handles are -# real, read from that config; vendor part numbers beyond the detector models, the -# goniometer geometry details, the optics layout, and physical positions are not fully -# in it and are open questions. Every value is carried confirm until EMBL Hamburg staff -# verify it. -# -# SUB-OPERATOR SEAM (the distinctive Site fact): P13 sits on the PETRA III ring but does -# NOT run DESY's Tango / Sardana / OnlineXML house style (the floor P01 / P06 / P11 bind -# to). EMBL Hamburg runs its OWN control domain: MXCuBE as the experiment-orchestration -# layer over the Exporter protocol (the microdiff / MD2-style host, e.g. -# p13md201.embl-hamburg.de:9001) and TINE channels (/P13/...) for the detector, energy, -# and beam services. So P13 is modelled as a sub-operator control-domain WITHIN the -# PETRA III Site: same ring and Facility, distinct operator and control floor. The -# PETRA III site.yaml carries an EMBL-Hamburg house-style section recording this; see -# docs/deployments/p13/equipment/controls.md (SEAM-1). -# -# WHAT IS NEW: no new device Family and no new technique vocabulary. P13 is the seventh -# MX beamline CORA models (after Diamond i03, NSLS-II FMX / AMX, the Australian -# Synchrotron MX3, Sirius MANACA, NSRRC TPS 07A / 05A, and DESY P11) and EMBL Hamburg's -# first. It reuses the MX vocabulary: the EMBLMiniDiff binds the graduated Goniometer, -# the Eiger / Pilatus area detectors bind Camera, the XRF detector -# EnergyDispersiveSpectrometer, the apertures / beamstop / objective / lights / shutters -# the matching catalog Families, and the MX technique reuses the pending i03 -# mx_data_collection Method (TECH-1). -# -# CONTROL HANDLES: the descriptor `pv` field carries the real control handle read from -# the MXCuBE config: an Exporter address (host:port) for the microdiff-hosted motions, -# or a TINE channel path (/P13/...) for the detector / energy / beam services. The -# handle protocol is itself a fact about the EMBL floor (Exporter vs TINE), recorded per -# device. -# -# SCOPE: this cut models the optics hutch (the KB mirror pitch / roll motions) and the -# experiment hutch (the EMBLMiniDiff diffractometer and its centring / kappa axes, the -# apertures / beamstop / sample lights / objective, the Eiger and Pilatus detectors, the -# flux and XRF detectors, the energy and resolution pseudo-axes, the shutters). The -# MXCuBE bookkeeping objects (session, queue, data-analysis, ISPyB, sample-changer -# logic) are filtered out by the extractor and not modelled as devices. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/p13/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "EMBL Hamburg macromolecular crystallography (rotation MX); CORA's first EMBL Hamburg beamline, MXCuBE HardwareObjects source" - name: P13 - facility: petra-iii # PETRA III Site (facility_code: petra-iii) - sector: "P13" - tier: Unit - parent: null - source: insertion-device - source_confirm: "P13 is an undulator MX beamline; the MXCuBE config exposes the photon-energy service (TINEEnergy on /P13/Energy/P13Energy) but not the undulator device itself, so the source is carried pending (SRC-1)" - page_layout: stages - shape: "EMBL macromolecular crystallography: rotation MX with an automated sample changer, its handles read from the mxCuBE configuration rather than a DESY OnlineXML registry." - source_ref: - label: "mxcube/mxcubecore (embl_hh_p13)" - url: "https://github.com/mxcube/mxcubecore/tree/develop/mxcubecore/configuration/embl_hh_p13" - -# Two enclosures inferred from the device prefixes and the EMBL MX layout: the optics -# hutch (the KB mirror pitch / roll motions on /P13/P13Kb.*) and the experiment hutch -# (the microdiff-hosted diffractometer and the TINE detector services). EMBL / DESY PSS -# permit signals are not in the MXCuBE config (PSS-1). -enclosures: - - name: p13-oh - role: optics-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY / EMBL PSS permit signal for the P13 optics hutch; not in the MXCuBE config (PSS-1)"} - - name: p13-eh - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY / EMBL PSS permit signal for the P13 experiment hutch; not in the MXCuBE config (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the optics-hutch KB mirror conditioning and the beam services -# =========================================================================== - -source: - stage: source - enclosure: p13-oh - intro: "The P13 optics conditioning: the Kirkpatrick-Baez (KB) mirror pitch / roll motions that focus the MX beam, plus the photon-energy and beam-diagnostic services. The monochromator and the KB mirror Assets themselves are not individually labelled in the MXCuBE config (which sees the motions, not the optic), so the mirror motions are grouped and the optic structure is carried as a question (OPT-1)." - note: "Handles read from the MXCuBE TINE channels (/P13/P13Kb.CDI/* for the KB target positions, /P13/Energy/* for the energy service) and the microdiff Exporter host. The KB mirror / monochromator breakdown is OPT-1." - devices: - - name: KBMirrorStage - family: LinearStage - pv: {tine: "/P13/P13Kb.CDI/HFMTgtPos"} - new: true - confirm: true - note: "the KB focusing-mirror pitch / roll motions (horizontal + vertical focusing mirror pitch on /P13/P13Kb.CDI/HFMTgtPos and /P13/P13Kb.CDI/VFMTgtPos, plus the second-crystal and VHM pitch / roll trims); per-mirror Assets not labelled in the config, grouped as the optics-hutch focusing stage (OPT-1, GROUP-1)" - - name: BeamEnergy - family: PseudoAxis - pv: {tine: "/P13/Energy/P13Energy"} - new: true - confirm: true - note: "the photon-energy virtual axis (TINEEnergy / EMBLEnergy on /P13/Energy/P13Energy, coupled to the wavelength service on /P13/collection/wavelength); the monochromator motions it drives are not individually labelled (ENERGY-1, OPT-1)" - - name: BeamDiagnostics - family: FluxMonitor - pv: {tine: "/P13/BCUIntensity/Device0"} - new: true - confirm: true - note: "the beam-conditioning-unit intensity / centring diagnostics (EMBLBeam / EMBLBeamInfo / EMBLBeamCentring; intensity read on /P13/BCUIntensity/Device0), grouped as the beam-position / flux diagnostic; the per-service split is DIAG-1" - -# =========================================================================== -# SAMPLE STAGE: the EMBLMiniDiff diffractometer and the MX sample environment -# =========================================================================== - -experiment-sample: - stage: sample - enclosure: p13-eh - intro: "The P13 experiment hutch: the EMBLMiniDiff diffractometer (the MX sample-orientation and centring instrument), its kappa goniometry and sample-centring axes, the beam-defining aperture and beamstop, the sample-viewing objective and illumination, all hosted on the microdiff Exporter server." - note: "Handles read from the microdiff Exporter host (p13md201.embl-hamburg.de:9001) for the diffractometer and its axes, and the TINE detector-distance / resolution services. The diffractometer's omega / kappa / sample-translation axes are EMBLMiniDiff roles; they are grouped under the Goniometer as the MD axis bank (MX-1)." - devices: - - name: Diffractometer - family: Goniometer - pv: {exporter: "p13md201.embl-hamburg.de:9001"} - new: true - confirm: true - note: "the EMBLMiniDiff microdiffractometer (the MX sample-orientation instrument: omega rotation, kappa / kappa-phi mini-kappa, sample x / y / z centring, and the focus / holder-length axes, all Exporter motors on the microdiff host); the goniometer geometry is carried confirm (MX-1)" - - name: MDCentringStage - family: LinearStage - pv: {tine: "/P13/MD/MD_0"} - new: true - confirm: true - note: "the diffractometer vertical centring axis (TINEMotor on /P13/MD/MD_0) and the coupled microdiff centring motions; grouped with the goniometer as the sample-centring stage (MX-1)" - - name: BeamAperture - family: Aperture - pv: {exporter: "p13md201.embl-hamburg.de:9001"} - new: true - confirm: true - note: "the beam-defining aperture on the microdiff (EMBLAperture, Exporter-hosted); the aperture-size table is carried confirm (OPT-1)" - - name: Beamstop - family: BeamStop - pv: {exporter: "p13md201.embl-hamburg.de:9001"} - new: true - confirm: true - note: "the microdiff beamstop (EMBLBeamstop, Exporter-hosted); the direct-beam stop in front of the sample" - - name: SampleObjective - family: Objective - pv: {exporter: "p13md201.embl-hamburg.de:9001"} - new: true - confirm: true - note: "the on-axis sample-viewing zoom objective (MicrodiffZoom, Exporter-hosted); the OAV magnification path (OAV-1)" - - name: SampleIllumination - family: Backlight - pv: {exporter: "p13md201.embl-hamburg.de:9001"} - new: true - confirm: true - note: "the microdiff sample illumination (MicrodiffLight back / front lights, Exporter-hosted); the on-axis viewing illumination, the Backlight affordance shared with i03 / i24 / FMX / i19 (DET-1)" - -# =========================================================================== -# DETECTION STAGE: the area detectors, the flux monitor, and the XRF detector -# =========================================================================== - -detection: - stage: detection - enclosure: p13-eh - intro: "The P13 detection: the Eiger 16M and Pilatus 6M area detectors for MX diffraction, the photodiode flux monitor, the on-axis and sample-changer cameras, and the XRF fluorescence detector for element identification." - note: "Handles read from the TINE detector channels (/P13/detector/eiger16m, /P13/detector/pilatus6m), the pin-diode flux service, and the fluorescence-scan service. The detector distance / resolution are pseudo-axes on the TINE collection service (DET-1)." - devices: - - name: EigerDetector - family: Camera - pv: {tine: "/P13/detector/eiger16m"} - new: true - confirm: true - note: "the Dectris Eiger 16M area detector (EMBLDetector, model read '16M' from the config); the primary MX diffraction detector (DET-1)" - - name: PilatusDetector - family: Camera - pv: {tine: "/P13/detector/pilatus6m"} - new: true - confirm: true - note: "the Dectris Pilatus 6M area detector (EMBLDetector, model read '6M_F' from the config); the alternative MX diffraction detector (DET-1)" - - name: DetectorDistance - family: PseudoAxis - pv: {tine: "/P13/collection/distance"} - new: true - confirm: true - note: "the detector-distance virtual axis (TINEMotor on /P13/collection/distance) and the coupled resolution axis (/P13/collection/resolution); the sample-to-detector geometry as a derived axis (DET-1)" - - name: FluxMonitor - family: FluxMonitor - pv: {tine: "/P13/PinDiode/Device0"} - new: true - confirm: true - note: "the pin-diode flux monitor (EMBLFlux on /P13/PinDiode/Device0); incident-flux normalization for MX data collection (DIAG-1)" - - name: OnAxisCamera - family: Camera - pv: {confirm: "the on-axis sample-viewing camera (VimbaVideo / QtAxisCamera); no Exporter / TINE handle in the config object, the video source is carried confirm (OAV-1)"} - new: true - confirm: true - note: "the on-axis sample-viewing video camera and the sample-changer camera (VimbaVideo / QtAxisCamera); the MX centring / loop-inspection video, control handle pending (OAV-1)" - - name: FluorescenceDetector - family: EnergyDispersiveSpectrometer - pv: {tine: "/P13/fluorescence-scan/fls-scan"} - new: true - confirm: true - note: "the energy-dispersive XRF detector (EMBLXRFSpectrum on /P13/fluorescence-scan/fls-scan); element identification / edge scanning for anomalous MX (DET-1)" - -# Cross-cutting control. P13 runs MXCuBE over EMBL Hamburg's Exporter + TINE floor, NOT -# DESY's Tango / Sardana. See the sub-operator seam note at the head of this file. -controls: - intro: > - P13 runs on EMBL Hamburg's own control domain, distinct from the DESY Tango / - Sardana floor the other PETRA III beamlines (P01 / P06 / P11) bind to. The - experiment-orchestration layer is MXCuBE (the macromolecular-crystallography - beamline-control application, shared with i03 / FMX / MANACA / TPS), and the device - floor underneath it is two protocols: the Exporter protocol on the microdiff host - (p13md201.embl-hamburg.de:9001) for the diffractometer and its motions, and TINE - channels (/P13/...) for the detector, energy, flux, and beam services. The handles - are read from EMBL's public MXCuBE HardwareObjects configuration and carried confirm - (CTRL-1). The rotation-MX acquisition (the goniometer oscillation coupled to the - Eiger frame capture) runs as an MXCuBE data-collection routine; that orchestration - is the seam CORA's edge would conduct over its ControlPort, the same shape as the MX - cluster seams at i03 / MANACA / TPS 07A, here landing on the Exporter / TINE floor - rather than Sardana (CTRL-2, SEAM-1). - motion_controllers: - - name: ExporterMotionController - family: MotionController - protocol: Exporter_microdiff - new: true - confirm: true - note: "the microdiff Exporter motion controller (p13md201.embl-hamburg.de:9001) driving the EMBLMiniDiff omega / kappa / centring axes and the aperture / beamstop / objective / light motions (CTRL-1)" - - name: TINEMotionController - family: MotionController - protocol: TINE_embl - new: true - confirm: true - note: "the TINE device floor (/P13/...) backing the KB mirror motions, the energy / wavelength service, the detector distance / resolution, and the flux / XRF services (CTRL-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a P13 run needs present before it can - start. All pending confirmation. LiquidNitrogen is the cryostream supply for the MX - sample cooling (the cryostream itself is not labelled in the MXCuBE config and is - carried as a question, CRYO-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: LiquidNitrogen diff --git a/deployments/p14/beamline.yaml b/deployments/p14/beamline.yaml deleted file mode 100644 index 1ca6d49a9ab..00000000000 --- a/deployments/p14/beamline.yaml +++ /dev/null @@ -1,334 +0,0 @@ -# P14 beamline descriptor (PETRA III, EMBL Hamburg), reverse-engineered from MXCuBE -# -# P14 is the EMBL Hamburg high-end macromolecular-crystallography (MX) beamline on the -# PETRA III ring at DESY, Hamburg. It is operated by EMBL Hamburg, not by DESY, and it -# is the sibling of P13 on the same EMBL endstation cluster. It is bound to the PETRA III -# Site (deployments/petra-iii/site.yaml) by facility_code, and it is CORA's second EMBL -# Hamburg beamline after P13. -# -# TWO ENDSTATIONS (the distinctive P14 fact): unlike P13 (one experiment hutch), P14 -# feeds TWO experiment hutches from one source / optics chain. EH1 is the main MX -# endstation (the EMBLMiniDiff microdiff on hosts p14md301 / p14md302, the Eiger -# detectors, the CRL transfocator, the beam-defining slits); EH2 is a second endstation -# (the EMBLBSD diffractometer on host pe2bsd01, a Pilatus 2M) fed by the SAME P14 energy -# and primary CRL (its energy / CRL handles point back to /P14/...). EMBL publishes EH1 -# and EH2 as two MXCuBE configs (embl_hh_p14 and embl_hh_pe2); this descriptor models -# both, with three enclosures: one optics hutch and two experiment hutches (EH-1). -# -# STATUS: reverse-engineered from EMBL Hamburg's own public MXCuBE HardwareObjects -# configuration (github.com/mxcube/mxcubecore, configuration/embl_hh_p14 for EH1 and -# configuration/embl_hh_pe2 for EH2), the device topology MXCuBE drives at the beamline. -# Device logical names and control handles are real, read from those configs; vendor part -# numbers beyond the detector models, the goniometer geometry details, the optics layout, -# and physical positions are not fully in them and are open questions. Every value is -# carried confirm until EMBL Hamburg staff verify it. NOTE: some EH2 axes are published -# as MotorMockup in the config (a simulation placeholder), so the EH2 motions are carried -# with extra caution (MOCK-1). -# -# SUB-OPERATOR SEAM (shared with P13): P14 sits on the PETRA III ring but does NOT run -# DESY's Tango / Sardana / OnlineXML house style. EMBL Hamburg runs its OWN control -# domain: MXCuBE as the experiment-orchestration layer over the Exporter protocol (the -# microdiff / MD2-style hosts p14md301 / p14md302 for EH1, the EMBLBSD host pe2bsd01 for -# EH2) and TINE channels (/P14/..., /PE2/...) for the detector, energy, and beam -# services. So P14 is modelled as a sub-operator control-domain WITHIN the PETRA III -# Site: same ring and Facility, distinct operator and control floor. The PETRA III -# site.yaml carries the EMBL-Hamburg house-style section (added with P13); see -# docs/deployments/p14/equipment/controls.md (SEAM-1). -# -# WHAT IS NEW: no new device Family and no new technique vocabulary. P14 is the eighth MX -# beamline CORA models (after Diamond i03, NSLS-II FMX / AMX, the Australian Synchrotron -# MX3, Sirius MANACA, NSRRC TPS 07A / 05A, DESY P11, and EMBL P13) and EMBL Hamburg's -# second. It reuses the MX vocabulary: the EMBLMiniDiff / EMBLBSD bind the graduated -# Goniometer, the Eiger / Pilatus area detectors bind Camera, the XRF detector -# EnergyDispersiveSpectrometer, the CRL binds Transfocator, the slits bind Slit, the -# focusing mirror binds Mirror, and the MX technique reuses the pending i03 -# mx_data_collection Method (TECH-1). -# -# CONTROL HANDLES: the descriptor `pv` field carries the real control handle read from -# the MXCuBE config: an Exporter address (host:port) for the microdiff-hosted motions, or -# a TINE channel path (/P14/..., /PE2/...) for the detector / energy / beam services. -# -# SCOPE: this cut models the optics hutch (the KB mirror pitch / roll motions, the CRL -# transfocator, the beam-defining slits), EH1 (the EMBLMiniDiff diffractometer and its -# centring / kappa axes, the aperture / beamstop / sample lights / objective, the three -# Eiger detector variants, the flux / XRF detectors, the X-ray imaging camera, the energy -# and resolution pseudo-axes), and EH2 (the EMBLBSD diffractometer, the Pilatus 2M, the -# EH2 table and beam-defining optics). The MXCuBE bookkeeping objects (session, queue, -# data-analysis, ISPyB, sample-changer logic) are filtered out by the extractor and not -# modelled as devices. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/p14/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "EMBL Hamburg high-end two-endstation macromolecular crystallography (MX), the sibling of P13" - name: P14 - facility: petra-iii # PETRA III Site (facility_code: petra-iii) - sector: "P14" - tier: Unit - parent: null - source: insertion-device - source_confirm: "P14 is an undulator MX beamline; the MXCuBE config exposes the photon-energy service (TINEEnergy on /P14/Energy/P14Energy) but not the undulator device itself, so the source is carried pending (SRC-1)" - page_layout: stages - shape: "EMBL macromolecular crystallography with a micro-focus and a versatile branch (including BioSAXS), its handles read from the mxCuBE configuration." - source_ref: - label: "mxcube/mxcubecore (embl_hh_p14)" - url: "https://github.com/mxcube/mxcubecore/tree/develop/mxcubecore/configuration/embl_hh_p14" - -# Three enclosures: one optics hutch (the KB mirror pitch / roll motions on /P14/..., -# the CRL transfocator, the beam-defining slits) feeding two experiment hutches, EH1 -# (the microdiff-hosted EMBLMiniDiff and the TINE detector services) and EH2 (the -# EMBLBSD diffractometer on pe2bsd01 and the Pilatus 2M). EMBL / DESY PSS permit signals -# are not in the MXCuBE config (PSS-1, EH-1). -enclosures: - - name: p14-oh - role: optics-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY / EMBL PSS permit signal for the P14 optics hutch; not in the MXCuBE config (PSS-1)"} - - name: p14-eh1 - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY / EMBL PSS permit signal for the P14 experiment hutch 1; not in the MXCuBE config (PSS-1)"} - - name: p14-eh2 - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY / EMBL PSS permit signal for the P14 experiment hutch 2; not in the MXCuBE config (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the shared optics-hutch conditioning feeding both endstations -# =========================================================================== - -source: - stage: source - enclosure: p14-oh - intro: "The P14 optics conditioning, shared by both experiment hutches: the Kirkpatrick-Baez (KB) mirror pitch / roll motions that focus the MX beam, the compound refractive lens (CRL) transfocator, the beam-defining slits, plus the photon-energy and beam-diagnostic services. The monochromator and the KB mirror Assets themselves are not individually labelled in the MXCuBE config, so the mirror motions are grouped and the optic structure is carried as a question (OPT-1)." - note: "Handles read from the MXCuBE TINE channels (/P14/... for the KB target positions, the CRL lens bank, and the energy service) and the microdiff Exporter host. The KB mirror / monochromator breakdown is OPT-1." - devices: - - name: KBMirrorStage - family: LinearStage - pv: {tine: "/P14/P14KB"} - new: true - confirm: true - note: "the KB focusing-mirror pitch / roll motions (the horizontal + vertical focusing mirror pitch HFMpitch / VFMpitch, the second-mirror roll, the perpendicular piezo trim, grouped under the P14KB motor group); per-mirror Assets not labelled in the config, grouped as the optics-hutch focusing stage (OPT-1, GROUP-1)" - - name: FocusingMirror - family: Mirror - pv: {tine: "/P14/collection/distance"} - new: true - confirm: true - note: "the KB beam-focusing optic (EMBLBeamFocusing) coupling the mirror motions to the focal-distance setting; the mirror coating / substrate are not in the config (OPT-1)" - - name: CompoundRefractiveLens - family: Transfocator - pv: {tine: "/P14/p14CRLs.CDI/LensOut"} - new: true - confirm: true - note: "the compound refractive lens transfocator (EMBLCRL on /P14/p14CRLs.CDI); the primary CRL focusing stack, shared with EH2; the lens count / material are not in the config (OPT-1)" - - name: BeamDefiningSlits - family: Slit - pv: {tine: "/P14/P14Atto"} - new: true - confirm: true - note: "the beam-defining slit boxes (EMBLSlitBox / BeamSlitBox on the P14Atto attocube group); the secondary-source and beam-defining slits, grouped (OPT-1, GROUP-1)" - - name: BeamEnergy - family: PseudoAxis - pv: {tine: "/P14/Energy/P14Energy"} - new: true - confirm: true - note: "the photon-energy virtual axis (TINEEnergy / EMBLEnergy on /P14/Energy/P14Energy, coupled to the wavelength service on /P14/collection/wavelength), shared by both endstations; the monochromator motions it drives are not individually labelled (ENERGY-1, OPT-1)" - - name: BeamDiagnostics - family: FluxMonitor - pv: {exporter: "p14md302.embl-hamburg.de:9001"} - new: true - confirm: true - note: "the beam intensity / centring diagnostics (EMBLBeam / EMBLBeamCentring; centring read on the microdiff host, intensity on the pin-diode), grouped as the beam-position / flux diagnostic; the per-service split is DIAG-1" - -# =========================================================================== -# SAMPLE STAGE: the two endstation diffractometers and their sample environments -# =========================================================================== - -experiment-sample: - stage: sample - enclosure: p14-eh1 - intro: "The P14 experiment hutches: EH1 carries the EMBLMiniDiff microdiffractometer (the main MX instrument, on hosts p14md301 / p14md302) with its kappa goniometry and sample-centring axes, the beam-defining aperture and beamstop, the sample-viewing objective and illumination; EH2 carries a second diffractometer (the EMBLBSD on pe2bsd01) with its own beamstop, objective, illumination, and positioning table." - note: "EH1 handles read from the microdiff Exporter hosts (p14md301 / p14md302); EH2 handles from the EMBLBSD host (pe2bsd01). The diffractometer omega / kappa / sample-translation axes are EMBLMiniDiff / EMBLBSD roles, grouped under the Goniometer (MX-1). Some EH2 axes are published as MotorMockup, carried with caution (MOCK-1)." - devices: - - name: DiffractometerEH1 - family: Goniometer - pv: {exporter: "p14md302.embl-hamburg.de:9001"} - new: true - confirm: true - note: "the EH1 EMBLMiniDiff microdiffractometer (the main MX instrument: omega rotation, kappa / kappa-phi mini-kappa, sample x / y / z centring via phix / phiy / phiz / sampx / sampy, and the focus / holder-length axes, all Exporter motors on the microdiff host); the goniometer geometry is carried confirm (MX-1)" - - name: BeamApertureEH1 - family: Aperture - pv: {exporter: "p14md302.embl-hamburg.de:9001"} - new: true - confirm: true - note: "the EH1 beam-defining aperture on the microdiff (EMBLAperture, Exporter-hosted); the aperture-size table is carried confirm (OPT-1)" - - name: BeamstopEH1 - family: BeamStop - pv: {exporter: "p14md302.embl-hamburg.de:9001"} - new: true - confirm: true - note: "the EH1 microdiff beamstop (EMBLBeamstop, Exporter-hosted); the direct-beam stop in front of the sample" - - name: SampleObjectiveEH1 - family: Objective - pv: {exporter: "p14md302.embl-hamburg.de:9001"} - new: true - confirm: true - note: "the EH1 on-axis sample-viewing zoom objective (MicrodiffZoom, Exporter-hosted); the OAV magnification path (OAV-1)" - - name: SampleIlluminationEH1 - family: Backlight - pv: {exporter: "p14md302.embl-hamburg.de:9001"} - new: true - confirm: true - note: "the EH1 microdiff sample illumination (MicrodiffLight back / front lights, Exporter-hosted); the on-axis viewing illumination, the Backlight affordance shared with i03 / i24 / FMX / i19 / P13 (DET-1)" - - name: DiffractometerEH2 - family: Goniometer - pv: {exporter: "pe2bsd01.embl-hamburg.de:9001"} - new: true - confirm: true - note: "the EH2 diffractometer (EMBLBSD on pe2bsd01); the second-endstation MX instrument with its own omega / kappa / centring axes; some axes published as MotorMockup, carried with caution (MX-1, MOCK-1)" - - name: BeamApertureEH2 - family: Aperture - pv: {exporter: "pe2bsd01.embl-hamburg.de:9001"} - new: true - confirm: true - note: "the EH2 beam-defining aperture (EMBLAperture on pe2bsd01); the aperture-size table is carried confirm (OPT-1)" - - name: BeamstopEH2 - family: BeamStop - pv: {exporter: "pe2bsd01.embl-hamburg.de:9001"} - new: true - confirm: true - note: "the EH2 beamstop (EMBLBeamstop on pe2bsd01); the direct-beam stop in front of the EH2 sample" - - name: SampleObjectiveEH2 - family: Objective - pv: {exporter: "pe2bsd01.embl-hamburg.de:9001"} - new: true - confirm: true - note: "the EH2 on-axis sample-viewing zoom objective (ExporterZoom on pe2bsd01); the EH2 OAV magnification path (OAV-1)" - - name: SampleIlluminationEH2 - family: Backlight - pv: {exporter: "pe2bsd01.embl-hamburg.de:9001"} - new: true - confirm: true - note: "the EH2 sample illumination (MicrodiffLight back / front lights on pe2bsd01); the EH2 on-axis viewing illumination, the Backlight affordance (DET-1)" - - name: ExperimentTableEH2 - family: LinearStage - pv: {confirm: "the EH2 positioning table (EMBLTableMotor table_hor / table_ver); no Exporter / TINE handle in the config object, the table motions are carried confirm (TABLE-1, MOCK-1)"} - new: true - confirm: true - note: "the EH2 experiment-table horizontal / vertical positioning (EMBLTableMotor table_hor / table_ver); the endstation table carrying the EH2 diffractometer, control handle pending (TABLE-1)" - -# =========================================================================== -# DETECTION STAGE: the EH1 Eiger detectors and the EH2 Pilatus, plus flux / XRF -# =========================================================================== - -detection: - stage: detection - enclosure: p14-eh1 - intro: "The P14 detection: EH1 carries three Dectris Eiger area detectors (a 16M silicon and two CdTe variants, 16M and 4M) for MX diffraction across energy ranges, plus the flux monitor, the on-axis and X-ray-imaging cameras, and the XRF fluorescence detector; EH2 carries a Dectris Pilatus 2M area detector." - note: "EH1 handles read from the TINE detector channels (/P14/detector/*); EH2 from /PE2/detector/pilatus2m. The detector distance / resolution are pseudo-axes on the TINE collection service (DET-1)." - devices: - - name: EigerDetector - family: Camera - pv: {tine: "/P14/detector/eiger16m"} - new: true - confirm: true - note: "the EH1 Dectris Eiger 16M silicon area detector (EMBLDetector, model read '16M' from the config); the primary MX diffraction detector (DET-1)" - - name: EigerCdTe16MDetector - family: Camera - pv: {tine: "/P14/detector/eiger16m-cdte"} - new: true - confirm: true - note: "the EH1 Dectris Eiger 16M CdTe area detector (EMBLDetector, model read '16M' from the config); the high-energy CdTe-sensor MX detector variant (DET-1)" - - name: EigerCdTe4MDetector - family: Camera - pv: {tine: "/P14/detector/eiger4m-cdte"} - new: true - confirm: true - note: "the EH1 Dectris Eiger 4M CdTe area detector (EMBLDetector, model read '4M' from the config); the smaller high-energy CdTe MX detector variant (DET-1)" - - name: PilatusDetectorEH2 - family: Camera - pv: {tine: "/PE2/detector/pilatus2m"} - new: true - confirm: true - note: "the EH2 Dectris Pilatus 2M area detector (EMBLDetector, model read '2M' from the config); the EH2 MX diffraction detector (DET-1)" - - name: DetectorDistance - family: PseudoAxis - pv: {tine: "/P14/collection/distance"} - new: true - confirm: true - note: "the EH1 detector-distance virtual axis (TINEMotor on /P14/collection/distance) and the coupled resolution axis (/P14/collection/resolution); the sample-to-detector geometry as a derived axis; EH2 carries its own /PE2/collection/* pair (DET-1)" - - name: FluxMonitor - family: FluxMonitor - pv: {tine: "/P14/PinDiode/Device0"} - new: true - confirm: true - note: "the pin-diode flux monitor (EMBLFlux on /P14/PinDiode/Device0); incident-flux normalization for MX data collection (DIAG-1)" - - name: OnAxisCamera - family: Camera - pv: {confirm: "the on-axis sample-viewing camera (VimbaVideo / QtAxisCamera); no Exporter / TINE handle in the config object, the video source is carried confirm (OAV-1)"} - new: true - confirm: true - note: "the EH1 on-axis sample-viewing video camera and the sample-changer camera (VimbaVideo / QtAxisCamera); the MX centring / loop-inspection video, control handle pending (OAV-1)" - - name: XrayImagingCamera - family: Camera - pv: {confirm: "the X-ray imaging camera (EMBLXrayImaging); no Exporter / TINE handle in the config object, the video source is carried confirm (IMG-1)"} - new: true - confirm: true - note: "the EH1 X-ray imaging camera (EMBLXrayImaging); in-situ sample / loop X-ray imaging for centring, control handle pending (IMG-1)" - - name: FluorescenceDetector - family: EnergyDispersiveSpectrometer - pv: {tine: "/P14/fluorescence-scan/fls-scan"} - new: true - confirm: true - note: "the energy-dispersive XRF detector (EMBLXRFSpectrum on /P14/fluorescence-scan/fls-scan); element identification / edge scanning for anomalous MX (DET-1)" - -# Cross-cutting control. P14 runs MXCuBE over EMBL Hamburg's Exporter + TINE floor, NOT -# DESY's Tango / Sardana. See the sub-operator seam note at the head of this file. -controls: - intro: > - P14 runs on EMBL Hamburg's own control domain, distinct from the DESY Tango / - Sardana floor the other PETRA III beamlines (P01 / P06 / P11) bind to, and shared in - style with its sibling P13. The experiment-orchestration layer is MXCuBE (the - macromolecular-crystallography beamline-control application, shared with i03 / FMX / - MANACA / TPS), and the device floor underneath it is two protocols: the Exporter - protocol on the microdiff hosts (p14md301 / p14md302 for EH1, pe2bsd01 for EH2) for - the diffractometers and their motions, and TINE channels (/P14/..., /PE2/...) for the - detector, energy, flux, and beam services. The handles are read from EMBL's public - MXCuBE HardwareObjects configuration and carried confirm (CTRL-1). Two experiment - hutches share one source / optics chain, so the energy and CRL services are common to - both endstations while each hutch carries its own diffractometer host (EH-1). The - rotation-MX acquisition (the goniometer oscillation coupled to the Eiger / Pilatus - frame capture) runs as an MXCuBE data-collection routine; that orchestration is the - seam CORA's edge would conduct over its ControlPort, the same shape as the MX cluster - seams at i03 / MANACA / TPS 07A, here landing on the Exporter / TINE floor rather - than Sardana (CTRL-2, SEAM-1). - motion_controllers: - - name: ExporterMotionController - family: MotionController - protocol: Exporter_microdiff - new: true - confirm: true - note: "the microdiff Exporter motion controllers (p14md301 / p14md302 for EH1, pe2bsd01 for EH2) driving the EMBLMiniDiff / EMBLBSD omega / kappa / centring axes and the aperture / beamstop / objective / light motions (CTRL-1)" - - name: TINEMotionController - family: MotionController - protocol: TINE_embl - new: true - confirm: true - note: "the TINE device floor (/P14/..., /PE2/...) backing the KB mirror motions, the CRL transfocator, the energy / wavelength service, the detector distance / resolution, and the flux / XRF services (CTRL-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a P14 run needs present before it can - start. All pending confirmation. LiquidNitrogen is the cryostream supply for the MX - sample cooling (the cryostream itself is not labelled in the MXCuBE config and is - carried as a question, CRYO-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: LiquidNitrogen diff --git a/deployments/p21/beamline.yaml b/deployments/p21/beamline.yaml deleted file mode 100644 index 8f3f2ab82f5..00000000000 --- a/deployments/p21/beamline.yaml +++ /dev/null @@ -1,179 +0,0 @@ -# P21 beamline descriptor (PETRA III, DESY), reverse-engineered from the OnlineXML -# -# P21 "Swedish Materials Science" is the high-energy hard X-ray materials-science -# beamline at PETRA III (DESY, Hamburg), a Swedish-collaboration beamline with two -# branches: P21.1 (high-energy diffraction / total scattering / PDF) and P21.2 (high- -# energy diffraction / imaging). It is bound to the PETRA III Site -# (deployments/petra-iii/site.yaml), the thirteenth PETRA III beamline. -# -# STATUS: reverse-engineered from P21's own public OnlineXML device registry -# (gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p21, branch -# debian/jessie; the online_hasep211eh.xml / 212oh.xml / eh3.xml / haspp21lab.xml -# registries). Device logical names and Tango control handles are real, read from that -# registry; vendor part numbers, crystal cuts, energy calibration, detectors, and -# physical positions are not in it and are open questions. The P21 registry is thin: -# most devices are area-grouped generic motor banks (oh_u*, eh3_u*, lab*) whose per- -# axis roles are not labelled, so the Asset grouping leans on the host / bank prefixes -# and is carried confirm (GROUP-1). Every value is carried confirm until P21 staff -# verify it. The extraction is in the xmap/research repo (private), under petra-iii/. -# -# WHAT IS NEW: no new device Family, and no new technique vocabulary. P21 is a thin -# high-energy materials beamline; it reuses LinearStage / Slit and the pending -# diffraction / total_scattering slugs (TECH-1). -# -# CONTROL HANDLES: the descriptor `pv` field carries the Tango device address read -# from the OnlineXML. The P21.2 optics report on the hasep212oh host, the EH3 -# endstation on hasep21eh3, and a lab station on haspp21lab; the P21.1 station -# (hasep211eh) exposed only bookkeeping devices in this slice and is noted, not -# modelled (HOST-1). The motor banks are grouped, every axis role pending (GROUP-1). -# -# SCOPE: this cut models the P21.2 optics (the oh bank), the EH3 experiment endstation -# (the eh3 bank), and the LAB station (the lab bank + the slit virtual axes). The -# detectors are not exposed as devices in this registry slice and are carried pending -# (DET-1). Counter / timer / ADC channels and the Sardana MeasurementGroup bookkeeping -# rows are filtered out by the extractor. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/p21/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "Swedish Materials Science high-energy diffraction (P21.2) and total scattering / PDF (P21.1) across an optics hutch, an EH3 endstation, and a LAB station; a thin reuse-and-reinforce scaffold (grouped motor banks, detectors carried pending), reusing the pending `diffraction` / `total_scattering` Methods" - name: P21 - facility: petra-iii # PETRA III Site (facility_code: petra-iii) - sector: "P21" - tier: Unit - parent: null - source: insertion-device - source_confirm: "P21 is an undulator beamline (Swedish Materials Science, high-energy diffraction); the OnlineXML exposes no undulator device in this slice, so the source is carried pending (SRC-1)" - page_layout: stages - shape: "High-energy X-ray diffraction (Swedish Materials Science, P21.1 / P21.2): powder and single-crystal diffraction of bulk and engineering samples across several stations." - source_ref: - label: "python-nxstools-extras-p21" - url: "https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p21" - -# Three enclosures inferred from the OnlineXML host names: the P21.2 optics, the EH3 -# experiment endstation, and the LAB station. The P21.1 station (hasep211eh) exposed -# only bookkeeping devices and is noted, not modelled (HOST-1). DESY PSS permit signals -# are not in the OnlineXML (PSS-1). -enclosures: - - name: p21-oh - role: optics-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the P21.2 optics hutch; not in the OnlineXML (PSS-1)"} - - name: p21-eh3 - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the EH3 experiment endstation; not in the OnlineXML (PSS-1)"} - - name: p21-lab - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the LAB station; not in the OnlineXML (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the P21.2 optics -# =========================================================================== - -source: - stage: source - enclosure: p21-oh - intro: "The P21.2 optics: the high-energy conditioning optics motor bank. The monochromator, mirrors, and slits are not individually labelled in this registry slice, so they are grouped as the optics-hutch positioning stages." - note: "Handles read from the oh_u* bank on the hasep212oh host. The optics breakdown (monochromator, mirrors, slits) is OPT-1." - devices: - - name: OpticsStages - family: LinearStage - pv: {bank: "p21/motor/oh_u01"} - new: true - confirm: true - note: "the P21.2 optics motor bank (oh_u* on p21/motor, hasep212oh host, ~32 axes): monochromator / mirror / slit motions, per-axis roles not labelled, grouped as one stage (OPT-1, GROUP-1)" - -# =========================================================================== -# SAMPLE STAGE: the EH3 and LAB endstations -# =========================================================================== - -eh3-sample: - stage: sample - enclosure: p21-eh3 - intro: "The EH3 experiment endstation: the sample / instrument positioning motor bank for high-energy diffraction." - note: "Handles read from the eh3_u* bank on the hasep21eh3 host. Per-axis roles not labelled (GROUP-1)." - devices: - - name: SampleStage - family: LinearStage - pv: {bank: "p21/motor/eh3_u01"} - new: true - confirm: true - note: "the EH3 sample / instrument motor bank (eh3_u* on p21/motor, hasep21eh3 host, ~16 axes); per-axis roles not labelled, grouped as one stage (GROUP-1)" - -lab-sample: - stage: sample - enclosure: p21-lab - intro: "The LAB station: a sample / instrument motor bank and the beam-defining slit virtual axes." - note: "Handles read from the lab* bank on the haspp21lab host plus the vm_s* slit virtual axes (GROUP-1)." - devices: - - name: SampleStage - family: LinearStage - pv: {bank: "p21/motor/lab01"} - new: true - confirm: true - note: "the LAB sample / instrument motor bank (lab* on p21/motor, haspp21lab host, ~7 axes); per-axis roles not labelled, grouped as one stage (GROUP-1)" - - name: DefiningSlits - family: Slit - pv: {s1_vgap: "p21/vmexecutor/vm_s1vg", s1_voffs: "p21/vmexecutor/vm_s1vo", s2_hgap: "p21/vmexecutor/vm_s2hg", s2_hoffs: "p21/vmexecutor/vm_s2ho", s2_vgap: "p21/vmexecutor/vm_s2vg", s2_voffs: "p21/vmexecutor/vm_s2vo"} - new: true - confirm: true - note: "the LAB beam-defining slits (s1 / s2, vmexecutor virtual gap / offset axes) (OPT-1)" - -# =========================================================================== -# DETECTION STAGE -# =========================================================================== - -detection: - stage: detection - enclosure: p21-eh3 - intro: "The P21 detection. The OnlineXML slice for P21 exposes no dedicated detector device beyond the motors; the high-energy diffraction detectors (area detectors, the PerkinElmer / Varex flat-panels typical of high-energy beamlines) are carried pending." - note: "High-energy diffraction area detection is not exposed as a device in this registry slice; carried pending (DET-1)." - devices: - - name: AreaDetectors - family: Camera - pv: {confirm: "the high-energy diffraction area detectors (PerkinElmer / Varex flat-panels typical of high-energy beamlines) are not exposed in this OnlineXML slice; carried pending (DET-1)"} - new: true - confirm: true - note: "the P21 high-energy diffraction area detectors; not in the registry slice, modelled as a pending Camera placeholder (DET-1)" - -# Cross-cutting control. P21 runs Tango with Sardana, the PETRA III house style. -controls: - intro: > - P21 runs on the PETRA III control system, Tango with Sardana as the scan / motion - SCADA layer, the same floor as the other PETRA III beamlines (P21 is a Swedish- - collaboration beamline, but the beamline controls are the PETRA III Tango / Sardana - stack). A motion axis is a Tango motor device (p21/motor/...), the slits vmexecutor - virtual axes; the beamline is split across the hasep212oh (optics), hasep21eh3 - (EH3), and haspp21lab (LAB) Tango hosts. The handles are read from P21's public - OnlineXML registry and carried confirm (CTRL-1). The high-energy diffraction - acquisition runs as a Sardana macro; that orchestration is the seam CORA's edge - would conduct over its ControlPort (CTRL-2). - motion_controllers: - - name: OMS58Controllers - family: MotionController - protocol: Tango_oms58 - new: true - confirm: true - note: "OMS MAXv-58 stepper controllers (oms58) driving the optics and sample motor banks (CTRL-1)" - - name: TangoMotorControllers - family: MotionController - protocol: Tango_motor_tango - new: true - confirm: true - note: "generic Tango motor controllers (motor_tango) backing the coupled / virtual axes (CTRL-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a P21 run needs present before it - can start. All pending confirmation. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/p22/beamline.yaml b/deployments/p22/beamline.yaml deleted file mode 100644 index 173c83a5c2e..00000000000 --- a/deployments/p22/beamline.yaml +++ /dev/null @@ -1,188 +0,0 @@ -# P22 beamline descriptor (PETRA III, DESY), reverse-engineered from the OnlineXML -# -# P22 "Hard X-ray Photoelectron Spectroscopy (HAXPES)" is the hard X-ray photoemission -# beamline at PETRA III (DESY, Hamburg). It shares its optics chain with P09 (the two -# beamlines are on the same straight / optics host): the undulator, the double-crystal -# monochromator, the mirror pair, and the phase retarder are P09 optics, and P22 adds -# the HAXPES experiment endstation. It is bound to the PETRA III Site -# (deployments/petra-iii/site.yaml), the fourteenth PETRA III beamline. -# -# STATUS: reverse-engineered from P22's own public OnlineXML device registry -# (gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p22, branch -# debian/jessie). Device logical names and Tango control handles are real, read from -# that registry; vendor part numbers, crystal cuts, the electron analyzer, energy -# calibration, and physical positions are not in it and are open questions. Every value -# is carried confirm until P22 staff verify it. The extraction is in -# xmap/research repo (private), under petra-iii/. -# -# WHAT IS NEW: no new device Family. P22 reuses existing Families, including the -# catalog PhaseRetarder Family (P22 is the third consumer, via the shared P09 optics, -# that graduated it out of loose alongside 4-ID and P09). The electron -# analyzer (the defining HAXPES instrument) is not exposed as a motor device in this -# registry slice and is carried pending against the catalog ElectronAnalyzer Family -# (DET-1). The technique (HAXPES) reuses the pending angle_resolved_photoemission slug -# (TECH-1). -# -# CONTROL HANDLES: the descriptor `pv` field carries the Tango device address read -# from the OnlineXML. P22's optics report on the P09 hosts (p09/ addresses, P09-MONO): -# the undulator, DCM, mirrors, phase retarder, and absorber are SHARED with P09. Per -# the cross-host mapping decision they are homed in the p22-optics enclosure with the -# shared-optics relationship flagged (HOST-1, SHARED-1). The HAXPS endstation bank is -# grouped (GROUP-1); the haxps_dmy stubs are dummy / placeholder devices (STUB-1). -# -# SCOPE: this cut models the shared P09 / P22 optics (undulator, DCM, mirrors, phase -# retarder, absorber) and the HAXPS experiment endstation (the sample / instrument -# bank). The electron analyzer is carried pending (DET-1). Counter / timer / ADC -# channels and the Sardana MeasurementGroup bookkeeping rows are filtered out by the -# extractor. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/p22/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "hard X-ray photoelectron spectroscopy (HAXPES) on a `Manipulator` sample stage + `ElectronAnalyzer`, sharing the P09 optics chain (undulator / DCM / mirrors / phase retarder); coins no new Family, reusing the pending `angle_resolved_photoemission` Method; the fleet's first shared-optics beamline pair" - name: P22 - facility: petra-iii # PETRA III Site (facility_code: petra-iii) - sector: "P22" - tier: Unit - parent: null - source: insertion-device - source_confirm: "P22 is an undulator beamline (HAXPES), sharing the undulator / optics with P09; the OnlineXML exposes the undulator (p09/undulator) but no period or parameters, carried pending (SRC-1, SHARED-1)" - page_layout: stages - shape: "Hard X-ray photoemission spectroscopy (HAXPES): a hemispherical electron analyzer probing buried interfaces at high photon energy." - source_ref: - label: "python-nxstools-extras-p22" - url: "https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p22" - -# Two enclosures: the shared P09 / P22 optics, and the HAXPS experiment endstation. The -# optics report on the P09 host (HOST-1, SHARED-1). DESY PSS permit signals are not in -# the OnlineXML (PSS-1). -enclosures: - - name: p22-optics - role: optics-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the shared P09 / P22 optics; not in the OnlineXML (PSS-1, SHARED-1)"} - - name: p22-haxps - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the HAXPS experiment endstation; not in the OnlineXML (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the shared P09 / P22 optics -# =========================================================================== - -source: - stage: source - enclosure: p22-optics - intro: "The P22 source and optics, shared with P09: the undulator, the double-crystal monochromator, the two mirrors, the polarization phase retarder, and the beam absorber. P22 is the HAXPES branch off the P09 optics chain." - note: "All these devices report on the P09 host (p09/ addresses, P09-MONO); they are shared with P09 and homed here in the p22-optics enclosure with the relationship flagged (HOST-1, SHARED-1)." - devices: - - name: Undulator - family: InsertionDevice - pv: {undulator: "p09/undulator/1", gap: "p09/attributemotor/gap"} - new: true - confirm: true - note: "the shared P09 / P22 undulator; gap read, period not exposed (SRC-1, SHARED-1)" - - name: Monochromator - family: Monochromator - pv: {energy: "p09/dcmener/mono.01", energy_all: "p09/multiplemotors/mono.01"} - new: true - confirm: true - note: "the shared double-crystal monochromator (energyfmb / mnchrmtr on the P09 host); crystal cut is OPT-1 (SHARED-1)" - - name: Mirror1 - family: Mirror - pv: {pitch: "p09/spk/exp.01", x: "p09/spk/exp.02", yaw: "p09/spk/exp.03", y: "p09/spk/exp.04"} - new: true - confirm: true - note: "the shared first mirror (m1: pitch / x / yaw / y, spk controller on the P09 host); coating / role OPT-1 (SHARED-1)" - - name: Mirror2 - family: Mirror - pv: {pitch: "p09/spk/exp.05", x: "p09/spk/exp.06", yaw: "p09/spk/exp.07", y: "p09/spk/exp.08", bender: "p09/spk/exp.09"} - new: true - confirm: true - note: "the shared second mirror (m2: pitch / x / yaw / y / bender on the P09 host); coating / role OPT-1 (SHARED-1)" - - name: PhaseRetarder - family: PhaseRetarder - pv: {circle1: "p09/phaseretarder/exp.01", circle2: "p09/phaseretarder/exp.02"} - new: true - confirm: true - note: "the shared polarization phase-retarder circles (on the P09 host); binds the catalog PhaseRetarder Family as its third consumer, alongside 4-ID and P09 (SHARED-1)" - - name: Absorber - family: Filter - pv: {abs: "p09/absorber/01"} - new: true - confirm: true - note: "the shared beam absorber / attenuator (on the P09 host); folds into the Filter Family (OPT-1, SHARED-1)" - -# =========================================================================== -# SAMPLE STAGE: the HAXPS experiment endstation -# =========================================================================== - -haxps-sample: - stage: sample - enclosure: p22-haxps - intro: "The HAXPS experiment endstation: the sample / instrument positioning motor bank for hard X-ray photoelectron spectroscopy." - note: "Handles read from the p22/motor experiment bank. The haxps_dmy stubs are dummy / placeholder devices (STUB-1). The sample bank per-axis roles are not labelled (GROUP-1)." - devices: - - name: SampleStage - family: Manipulator - pv: {bank: "p22/motor/exp01"} - new: true - confirm: true - note: "the HAXPS sample / instrument motor bank (the p22/motor experiment bank, ~64 axes); the photoemission sample manipulator, per-axis roles not labelled, grouped as one Manipulator (GROUP-1)" - -# =========================================================================== -# DETECTION STAGE: the electron analyzer -# =========================================================================== - -detection: - stage: detection - enclosure: p22-haxps - intro: "The P22 detection: the hard X-ray electron analyzer (the defining HAXPES instrument). It is not exposed as a motor device in this registry slice and is carried pending against the catalog ElectronAnalyzer Family." - note: "The HAXPES electron analyzer (a hemispherical analyzer) is the defining detector; not exposed in this registry slice, carried pending (DET-1)." - devices: - - name: ElectronAnalyzer - family: ElectronAnalyzer - pv: {confirm: "the HAXPES hemispherical electron analyzer is not exposed as a device in this OnlineXML slice; carried pending against the catalog ElectronAnalyzer Family (DET-1)"} - new: true - confirm: true - note: "the HAXPES hard X-ray electron analyzer (hemispherical); the defining detector, bound to the catalog ElectronAnalyzer Family (graduated at NSLS-II ESM), carried pending (DET-1)" - -# Cross-cutting control. P22 runs Tango with Sardana, the PETRA III house style. -controls: - intro: > - P22 runs on the PETRA III control system, Tango with Sardana as the scan / motion - SCADA layer, the same floor as the other PETRA III beamlines. P22 shares its optics - chain with P09: the undulator, DCM, mirrors, phase retarder, and absorber are P09 - devices (p09/ addresses, the P09-MONO host), and P22 adds the HAXPS endstation - (p22/ addresses). A motion axis is a Tango motor device, the mirrors spk devices, - the phase retarder a phaseretarder device. The handles are read from P22's public - OnlineXML registry and carried confirm (CTRL-1, SHARED-1). The HAXPES acquisition - (the photon-energy / analyzer sweep over the sample) runs as a Sardana macro; that - orchestration is the seam CORA's edge would conduct over its ControlPort (CTRL-2). - motion_controllers: - - name: OMS58Controllers - family: MotionController - protocol: Tango_oms58 - new: true - confirm: true - note: "OMS MAXv-58 stepper controllers (oms58) driving the HAXPS sample motor bank (CTRL-1)" - - name: TangoMotorControllers - family: MotionController - protocol: Tango_motor_tango - new: true - confirm: true - note: "generic Tango motor controllers (motor_tango / spk) backing the shared P09 optics (mono, mirrors, phase retarder) and the coupled axes (CTRL-1, SHARED-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a P22 run needs present before it - can start. All pending confirmation. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/p23/beamline.yaml b/deployments/p23/beamline.yaml deleted file mode 100644 index 971b168251f..00000000000 --- a/deployments/p23/beamline.yaml +++ /dev/null @@ -1,131 +0,0 @@ -# P23 beamline descriptor (PETRA III, DESY), reverse-engineered from the OnlineXML -# -# P23 "In-situ X-ray Diffraction and Imaging" is the hard X-ray in-situ / operando -# diffraction beamline at PETRA III (DESY, Hamburg): diffraction and imaging of samples -# under in-situ conditions (electrochemistry, thin-film growth, sample environments). -# It is bound to the PETRA III Site (deployments/petra-iii/site.yaml), the fifteenth -# PETRA III beamline. -# -# STATUS: reverse-engineered from P23's own public OnlineXML device registry -# (gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p23, branch -# debian/jessie; the online_hasep23oh.xml / hasep23dev.xml registries). Device logical -# names and Tango control handles are real, read from that registry; vendor part -# numbers, crystal cuts, energy calibration, detectors, and physical positions are not -# in it and are open questions. The P23 registry is thin: it exposes one large -# generically-named motor bank (eh_mot* on the hasep23oh host) whose per-axis roles are -# not labelled, so the Asset grouping leans on the bank prefix and is carried confirm -# (GROUP-1). Every value is carried confirm until P23 staff verify it. The extraction is -# in the xmap/research repo (private), under petra-iii/. -# -# WHAT IS NEW: no new device Family, and no new technique vocabulary. P23 is a thin -# in-situ diffraction beamline; it reuses LinearStage and the pending diffraction slug -# (TECH-1). -# -# CONTROL HANDLES: the descriptor `pv` field carries the Tango device address read from -# the OnlineXML. The eh_mot* bank reports on the hasep23oh host; a single dev stub -# reports on hasep23dev (STUB-1). The bank is grouped, every axis role pending -# (GROUP-1). -# -# SCOPE: this cut models the P23 experiment / optics motor bank (the eh_mot* bank). The -# monochromator, mirrors, diffractometer, and detectors are not individually labelled -# in this registry slice and are carried grouped / pending (OPT-1, DIFF-1, DET-1). -# Counter / timer / ADC channels and the Sardana MeasurementGroup bookkeeping rows are -# filtered out by the extractor. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/p23/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "in-situ / operando X-ray diffraction and imaging; a thin reuse-and-reinforce scaffold (one grouped motor bank, optics / diffractometer / detectors carried grouped / pending), reusing the pending `diffraction` Method" - name: P23 - facility: petra-iii # PETRA III Site (facility_code: petra-iii) - sector: "P23" - tier: Unit - parent: null - source: insertion-device - source_confirm: "P23 is an undulator beamline (in-situ diffraction); the OnlineXML exposes no undulator device in this slice, so the source is carried pending (SRC-1)" - page_layout: stages - shape: "In-situ and operando hard X-ray diffraction: a multi-circle diffractometer with sample environments for materials under working conditions." - source_ref: - label: "python-nxstools-extras-p23" - url: "https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p23" - -# One enclosure inferred from the OnlineXML host (the registry exposes the eh_mot bank -# on a single hasep23oh host): the experiment hutch carrying the optics and the -# experiment instrument. DESY PSS permit signals are not in the OnlineXML (PSS-1). -enclosures: - - name: p23-eh - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the P23 experiment hutch; not in the OnlineXML (PSS-1)"} - -# =========================================================================== -# SAMPLE STAGE: the experiment / instrument motor bank -# =========================================================================== - -experiment-sample: - stage: sample - enclosure: p23-eh - intro: "The P23 experiment / instrument motor bank: the in-situ diffraction sample positioning, diffractometer, and optics motions. The monochromator, mirrors, and diffractometer are not individually labelled in this registry slice, so they are grouped as the experiment positioning stage." - note: "Handles read from the eh_mot* bank (~79 axes) on the hasep23oh host. Per-axis roles not labelled, grouped as one stage (GROUP-1). The optics / diffractometer breakdown is OPT-1 / DIFF-1." - devices: - - name: ExperimentStage - family: LinearStage - pv: {bank: "p23/motor/eh_mot01"} - new: true - confirm: true - note: "the P23 experiment / instrument motor bank (eh_mot01..79 on p23/motor, hasep23oh host): the in-situ diffraction sample positioning, diffractometer, and optics motions, per-axis roles not labelled, grouped as one stage (GROUP-1, OPT-1, DIFF-1)" - - name: DevStage - family: LinearStage - pv: {dev: "p23/omsvme58/dev.01"} - new: true - confirm: true - note: "a single device-development / test axis on the hasep23dev host (omsvme58); a dev / commissioning stage (STUB-1)" - -# =========================================================================== -# DETECTION STAGE -# =========================================================================== - -detection: - stage: detection - enclosure: p23-eh - intro: "The P23 detection. The OnlineXML slice for P23 exposes no dedicated detector device beyond the motors; the in-situ diffraction detectors (area detectors) are carried pending." - note: "In-situ diffraction area detection is not exposed as a device in this registry slice; carried pending (DET-1)." - devices: - - name: AreaDetectors - family: Camera - pv: {confirm: "the in-situ diffraction area detectors are not exposed in this OnlineXML slice; carried pending (DET-1)"} - new: true - confirm: true - note: "the P23 in-situ diffraction area detectors; not in the registry slice, modelled as a pending Camera placeholder (DET-1)" - -# Cross-cutting control. P23 runs Tango with Sardana, the PETRA III house style. -controls: - intro: > - P23 runs on the PETRA III control system, Tango with Sardana as the scan / motion - SCADA layer, the same floor as the other PETRA III beamlines. A motion axis is a - Tango motor device (p23/motor/...), with a single dev / commissioning axis on the - omsvme58 dev host. The handles are read from P23's public OnlineXML registry and - carried confirm (CTRL-1). The in-situ diffraction acquisition runs as a Sardana - macro; that orchestration is the seam CORA's edge would conduct over its - ControlPort (CTRL-2). - motion_controllers: - - name: OMS58Controllers - family: MotionController - protocol: Tango_oms58 - new: true - confirm: true - note: "OMS MAXv-58 and VME58 stepper controllers (oms58 / omsvme58) driving the experiment motor bank (CTRL-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a P23 run needs present before it can - start. All pending confirmation. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/p24/beamline.yaml b/deployments/p24/beamline.yaml deleted file mode 100644 index 3d0d344f100..00000000000 --- a/deployments/p24/beamline.yaml +++ /dev/null @@ -1,189 +0,0 @@ -# P24 beamline descriptor (PETRA III, DESY), reverse-engineered from the OnlineXML -# -# P24 "Chemical Crystallography" is the hard X-ray single-crystal / chemical -# crystallography beamline at PETRA III (DESY, Hamburg): small-molecule and chemical -# crystallography on a diffractometer with area detection, across two experiment -# hutches (EH1, EH2). It is bound to the PETRA III Site -# (deployments/petra-iii/site.yaml), the sixteenth PETRA III beamline. -# -# STATUS: reverse-engineered from P24's own public OnlineXML device registry -# (gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p24, branch -# debian/jessie). Device logical names and Tango control handles are real, read from -# that registry; vendor part numbers, crystal cuts, the diffractometer geometry, the -# detectors, energy calibration, and physical positions are not in it and are open -# questions. The P24 registry exposes generically-named motor banks (oh_mot*, mot*) -# whose per-axis roles are not labelled, so the Asset grouping leans on the bank -# prefixes and is carried confirm (GROUP-1). Every value is carried confirm until P24 -# staff verify it. The extraction is in the xmap/research repo (private), under petra-iii/. -# -# WHAT IS NEW: no new device Family, and no new technique vocabulary. P24 is a chemical -# crystallography beamline; the diffractometer / sample positioning reuses LinearStage -# (the registry does not label a goniometer), the slits Slit, the fluorescence MCA -# EnergyDispersiveSpectrometer, and the technique reuses the pending diffraction slug -# (TECH-1). -# -# CONTROL HANDLES: the descriptor `pv` field carries the Tango device address read from -# the OnlineXML. The oh_mot* bank is the optics, the mot* bank the EH2 experiment, and -# a separate EH1 bank the second hutch. The dmy stubs are dummy / placeholder devices -# (STUB-1); the banks are grouped, every axis role pending (GROUP-1). -# -# SCOPE: this cut models the optics (the oh_mot bank, the ps1 / ps2 slits), the EH2 -# main experiment hutch (the mot bank, the MCA, the coupled axes), and the EH1 hutch -# (its bank). The diffractometer and area detector are not individually labelled in -# this registry slice and are carried grouped / pending (DIFF-1, DET-1). Counter / -# timer / ADC channels and the Sardana MeasurementGroup bookkeeping rows are filtered -# out by the extractor. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/p24/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "single-crystal / small-molecule chemical crystallography across an optics hutch and two experiment hutches (EH1 / EH2); coins no new Family (the small-molecule diffractometer reuses `LinearStage`, area detector pending), reusing the pending `diffraction` Method" - name: P24 - facility: petra-iii # PETRA III Site (facility_code: petra-iii) - sector: "P24" - tier: Unit - parent: null - source: insertion-device - source_confirm: "P24 is an undulator beamline (chemical crystallography); the OnlineXML exposes no undulator device in this slice, so the source is carried pending (SRC-1)" - page_layout: stages - shape: "Chemical crystallography: single-crystal diffraction on a precise multi-circle goniometer with area detection." - source_ref: - label: "python-nxstools-extras-p24" - url: "https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p24" - -# Three enclosures: the optics hutch (the oh_mot bank + slits) and two experiment -# hutches (EH2 main, EH1). DESY PSS permit signals are not in the OnlineXML (PSS-1). -enclosures: - - name: p24-oh - role: optics-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the P24 optics hutch; not in the OnlineXML (PSS-1)"} - - name: p24-eh2 - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the EH2 main experiment hutch; not in the OnlineXML (PSS-1)"} - - name: p24-eh1 - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the EH1 experiment hutch; not in the OnlineXML (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the optics -# =========================================================================== - -source: - stage: source - enclosure: p24-oh - intro: "The P24 optics: the conditioning optics motor bank and the primary / secondary defining slits. The monochromator and mirrors are not individually labelled in this registry slice, so they are grouped as the optics-hutch positioning stage." - note: "Handles read from the oh_mot* bank and the ps1 / ps2 slit axes. The optics breakdown (monochromator, mirrors) is OPT-1." - devices: - - name: OpticsStages - family: LinearStage - pv: {bank: "p24/motor/oh_mot01"} - new: true - confirm: true - note: "the P24 optics motor bank (oh_mot01..20 on p24/motor): monochromator / mirror motions, per-axis roles not labelled, grouped as one stage (OPT-1, GROUP-1)" - - name: DefiningSlits - family: Slit - pv: {ps1_vgap: "p24/motor/ps1vgap", ps1_vcen: "p24/motor/ps1vcen", ps2_vgap: "p24/motor/ps2vgap", ps2_vcen: "p24/motor/ps2vcen", ps2_hleft: "p24/motor/ps2hleft", ps2_hright: "p24/motor/ps2hright"} - new: true - confirm: true - note: "the primary / secondary defining slits (ps1 / ps2 gap / center / blades) (OPT-1)" - -# =========================================================================== -# EH2: main experiment hutch (diffractometer) -# =========================================================================== - -eh2-sample: - stage: sample - enclosure: p24-eh2 - intro: "The EH2 main experiment hutch: the chemical-crystallography diffractometer and sample positioning. The diffractometer geometry is not individually labelled in this registry slice, so the sample / instrument motions are grouped." - note: "Handles read from the mot* bank and the eh2 coupled axes (vmexecutor). The dmy stubs are dummy / placeholder devices (STUB-1). The diffractometer geometry is DIFF-1." - devices: - - name: SampleStage - family: LinearStage - pv: {bank: "p24/motor/mot01"} - new: true - confirm: true - note: "the EH2 diffractometer / sample motor bank (mot01..40 on p24/motor): the chemical-crystallography diffractometer and sample positioning, per-axis roles not labelled, grouped as one stage (GROUP-1, DIFF-1)" - - name: CoupledAxes - family: PseudoAxis - pv: {vm01: "p24/vmexecutor/eh2.01", vm02: "p24/vmexecutor/eh2.02", vm03: "p24/vmexecutor/eh2.03"} - new: true - confirm: true - note: "the EH2 coupled / virtual axes (eh2_vm* on vmexecutor) (GROUP-1)" - -eh2-detector: - stage: detection - enclosure: p24-eh2 - intro: "The EH2 detection: the MCA fluorescence detectors and the chemical-crystallography area detector (the latter not exposed as a device in this registry slice)." - note: "Handles read from p24/mca. The area detector (a Pilatus / Eiger-class photon-counting detector typical of chemical crystallography) is not exposed and is carried pending (DET-1)." - devices: - - name: FluorescenceDetectors - family: EnergyDispersiveSpectrometer - pv: {mca01: "p24/mca/eh2.01", mca02: "p24/mca/eh2.02", mca03: "p24/mca/eh2.03", mca04: "p24/mca/eh2.04"} - new: true - confirm: true - note: "the EH2 MCA fluorescence detectors (DET-1)" - - name: AreaDetector - family: Camera - pv: {confirm: "the chemical-crystallography area detector (a Pilatus / Eiger-class photon-counting detector) is not exposed in this OnlineXML slice; carried pending (DET-1)"} - new: true - confirm: true - note: "the EH2 area detector for single-crystal diffraction; not in the registry slice, modelled as a pending Camera placeholder (DET-1)" - -# =========================================================================== -# EH1: experiment hutch -# =========================================================================== - -eh1-sample: - stage: sample - enclosure: p24-eh1 - intro: "The EH1 experiment hutch: a sample / instrument motor bank for the second P24 experiment station." - note: "Handles read from the EH1 motor bank. Per-axis roles not labelled (GROUP-1)." - devices: - - name: SampleStage - family: LinearStage - pv: {bank: "p24/motor/eh1.01"} - new: true - confirm: true - note: "the EH1 sample / instrument motor bank (~16 axes on p24/motor); per-axis roles not labelled, grouped as one stage (GROUP-1)" - -# Cross-cutting control. P24 runs Tango with Sardana, the PETRA III house style. -controls: - intro: > - P24 runs on the PETRA III control system, Tango with Sardana as the scan / motion - SCADA layer, the same floor as the other PETRA III beamlines. A motion axis is a - Tango motor device (p24/motor/...), the coupled axes vmexecutor virtual axes; the - fluorescence detectors are mca devices. The handles are read from P24's public - OnlineXML registry and carried confirm (CTRL-1). The chemical-crystallography - acquisition (the diffractometer scan coupled to the area-detector frame capture) - runs as a Sardana macro; that orchestration is the seam CORA's edge would conduct - over its ControlPort (CTRL-2). - motion_controllers: - - name: OMS58Controllers - family: MotionController - protocol: Tango_oms58 - new: true - confirm: true - note: "OMS MAXv-58 stepper controllers (oms58) driving the optics and experiment motor banks (CTRL-1)" - - name: TangoMotorControllers - family: MotionController - protocol: Tango_motor_tango - new: true - confirm: true - note: "generic Tango motor controllers (motor_tango) backing the coupled / virtual axes and the dummy stubs (CTRL-1, STUB-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a P24 run needs present before it can - start. All pending confirmation. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/p61/beamline.yaml b/deployments/p61/beamline.yaml deleted file mode 100644 index 303ace7551a..00000000000 --- a/deployments/p61/beamline.yaml +++ /dev/null @@ -1,131 +0,0 @@ -# P61 beamline descriptor (PETRA III, DESY), reverse-engineered from the OnlineXML -# -# P61 "High Energy Wiggler Beamline" is the high-energy white-beam beamline at PETRA -# III (DESY, Hamburg), fed by a damping-wiggler source. It runs P61A (Large Volume -# Press, high-pressure / high-temperature in-situ studies) and P61B (high-energy -# white-beam / engineering diffraction). It is bound to the PETRA III Site -# (deployments/petra-iii/site.yaml), the seventeenth PETRA III beamline and the -# eighteenth (and final) PETRA III beamline with a public OnlineXML registry. -# -# STATUS: reverse-engineered from P61's own public OnlineXML device registry -# (gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p61, branch -# debian/stretch; the online_hasnp61ch1.xml registry, the only PETRA III extras -# package on the stretch branch). Device logical names and Tango control handles are -# real, read from that registry; vendor part numbers, the press, the source, energy -# calibration, detectors, and physical positions are not in it and are open questions. -# The P61 registry is thin: it exposes one large generically-named motor bank (eh_mot* -# on the hasnp61eh2 host) whose per-axis roles are not labelled, so the Asset grouping -# leans on the bank prefix and is carried confirm (GROUP-1). Every value is carried -# confirm until P61 staff verify it. The extraction is in the xmap/research repo (private), under petra-iii/. -# -# WHAT IS NEW: no new device Family, and no new technique vocabulary. P61 is a thin -# high-energy white-beam beamline; the experiment positioning reuses LinearStage, and -# the technique reuses the pending energy_dispersive_diffraction / powder_diffraction -# slugs (TECH-1). The Large Volume Press, if exposed, would reuse the catalog -# PressureCell Family (the 13-id / P02 precedent); it is not in this registry slice -# and is carried pending (PRESS-1). -# -# CONTROL HANDLES: the descriptor `pv` field carries the Tango device address read from -# the OnlineXML. The eh_mot* bank reports on the hasnp61eh2 host. The bank is grouped, -# every axis role pending (GROUP-1). Note this is the only PETRA III extras package on -# the debian/stretch branch (the others are debian/jessie), so the snapshot vintage may -# differ (CTRL-1). -# -# SCOPE: this cut models the P61 experiment / instrument motor bank. The source -# (damping wiggler), the Large Volume Press, the energy-dispersive / area detectors, -# and the optics are not exposed in this registry slice and are carried pending -# (SRC-1, PRESS-1, DET-1). Counter / timer / ADC channels and the Sardana -# MeasurementGroup bookkeeping rows are filtered out by the extractor. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/p61/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "high-energy white-beam wiggler beamline (P61A Large Volume Press + P61B energy-dispersive diffraction); a thin reuse-and-reinforce scaffold (one grouped motor bank, source / press / detectors pending), reusing the pending `energy_dispersive_diffraction` Method; the last PETRA III beamline with a public OnlineXML registry" - name: P61 - facility: petra-iii # PETRA III Site (facility_code: petra-iii) - sector: "P61" - tier: Unit - parent: null - source: superconducting-wiggler - source_confirm: "P61 is fed by a PETRA III damping wiggler (high-energy white beam); the OnlineXML exposes no source device in this slice, so the wiggler parameters are carried pending (SRC-1)" - page_layout: stages - shape: "High-energy white-beam engineering (P61A) and powder / total scattering (P61B) on a superconducting-wiggler source, for bulk and in-situ studies." - source_ref: - label: "python-nxstools-extras-p61" - url: "https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p61" - -# One enclosure inferred from the OnlineXML host (the registry exposes the eh_mot bank -# on a single hasnp61eh2 host): the experiment hutch. DESY PSS permit signals are not -# in the OnlineXML (PSS-1). -enclosures: - - name: p61-eh2 - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the P61 experiment hutch; not in the OnlineXML (PSS-1)"} - -# =========================================================================== -# SAMPLE STAGE: the experiment / instrument motor bank -# =========================================================================== - -experiment-sample: - stage: sample - enclosure: p61-eh2 - intro: "The P61 experiment / instrument motor bank: the high-energy white-beam sample positioning and diffractometer motions. The Large Volume Press, the source, and the optics are not exposed in this registry slice, so the modelled devices are the experiment positioning stage." - note: "Handles read from the eh_mot* bank (~64 axes) on the hasnp61eh2 host. Per-axis roles not labelled, grouped as one stage (GROUP-1). The Large Volume Press (P61A) is PRESS-1." - devices: - - name: ExperimentStage - family: LinearStage - pv: {bank: "p61/motor/eh_mot01"} - new: true - confirm: true - note: "the P61 experiment / instrument motor bank (eh_mot01..64 on p61/motor, hasnp61eh2 host): the high-energy white-beam sample positioning and diffractometer motions, per-axis roles not labelled, grouped as one stage (GROUP-1)" - -# =========================================================================== -# DETECTION STAGE -# =========================================================================== - -detection: - stage: detection - enclosure: p61-eh2 - intro: "The P61 detection. The OnlineXML slice exposes no dedicated detector device beyond the motors; the energy-dispersive / area detectors typical of a high-energy white-beam / LVP beamline are carried pending." - note: "Energy-dispersive (Ge solid-state) and area detectors are not exposed as devices in this registry slice; carried pending (DET-1)." - devices: - - name: EnergyDispersiveDetector - family: EnergyDispersiveSpectrometer - pv: {confirm: "the energy-dispersive (Ge solid-state) detector typical of a white-beam / LVP beamline is not exposed in this OnlineXML slice; carried pending (DET-1)"} - new: true - confirm: true - note: "the P61 energy-dispersive detector (Ge solid-state) for energy-dispersive diffraction; not in the registry slice, modelled as a pending EnergyDispersiveSpectrometer placeholder (DET-1)" - -# Cross-cutting control. P61 runs Tango with Sardana, the PETRA III house style. -controls: - intro: > - P61 runs on the PETRA III control system, Tango with Sardana as the scan / motion - SCADA layer, the same floor as the other PETRA III beamlines. A motion axis is a - Tango motor device (p61/motor/...). The handles are read from P61's public OnlineXML - registry and carried confirm (CTRL-1). Note P61 is the only PETRA III extras package - published on the debian/stretch branch (the others are debian/jessie), so its - snapshot vintage may differ. The high-energy white-beam / energy-dispersive - diffraction acquisition runs as a Sardana macro; that orchestration is the seam - CORA's edge would conduct over its ControlPort (CTRL-2). - motion_controllers: - - name: OMS58Controllers - family: MotionController - protocol: Tango_oms58 - new: true - confirm: true - note: "OMS MAXv-58 stepper controllers (oms58) driving the experiment motor bank (CTRL-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a P61 run needs present before it can - start. All pending confirmation. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/p64/beamline.yaml b/deployments/p64/beamline.yaml deleted file mode 100644 index e43add0f716..00000000000 --- a/deployments/p64/beamline.yaml +++ /dev/null @@ -1,199 +0,0 @@ -# P64 beamline descriptor (PETRA III, DESY), reverse-engineered from the OnlineXML -# -# P64 "Advanced X-ray Absorption Spectroscopy" is the EXAFS / XANES beamline at -# PETRA III (DESY, Hamburg), specialising in dilute / high-rate fluorescence-detected -# absorption spectroscopy with a large multi-element detector. It is bound to the -# PETRA III Site (deployments/petra-iii/site.yaml), the ninth PETRA III beamline. -# -# STATUS: reverse-engineered from P64's own public OnlineXML device registry -# (gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p64, branch -# debian/jessie; the online_hasnp64.xml registry). Device logical names and Tango -# control handles are real, read from that registry; vendor part numbers, crystal -# cuts, the detector element count, energy calibration, and physical positions are not -# in it and are open questions. Every value is carried confirm until P64 staff verify -# it. The extraction is in the xmap/research repo (private), under petra-iii/. -# -# WHAT IS NEW: no new device Family. P64 reuses existing Families end to end. It is the -# fleet's high-rate fluorescence EXAFS beamline; its defining feature is the large -# multi-element fluorescence detector exposed as a 104-channel SIS3302 digitizer, all -# grouped into one EnergyDispersiveSpectrometer Asset (DET-1). The technique (X-ray -# absorption spectroscopy) reuses the pending xas_spectroscopy slug the BMM / ISS / -# i20-1 / P04 beamlines already share (TECH-1). -# -# CONTROL HANDLES: the descriptor `pv` field carries the Tango device address read -# from the OnlineXML (e.g. p64/dcmener/energy). The energy axis couples the DCM and -# the undulator (coupledmonoundmove); the mono is a Tsai-geometry DCM (DcmTsai). The -# experiment motor bank carries the sample / instrument positioning, roles not -# labelled (GROUP-1). The OH mirror pair is exposed as labelled axes (Mirror1*, -# Mirror2*), so the mirrors are resolved. -# -# SCOPE: this cut models the optics (the undulator, the Tsai DCM + coupled energy, the -# OH mirror pair), the experiment endstation (the sample bank, the DAC sub-stage, the -# NewFocus picomotors, the slits), and the detection (the two Lambda 750k area -# detectors and the multi-element SIS3302 fluorescence detector). Counter / timer / -# ADC channels and the Sardana MeasurementGroup bookkeeping rows are filtered out by -# the extractor. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/p64/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "advanced X-ray absorption spectroscopy (dilute / high-rate fluorescence EXAFS / XANES) on a Tsai DCM + a multi-element fluorescence detector (104-channel SIS3302); the advanced half of the PETRA III XAS pair, coins no new Family, reusing the pending `xas_spectroscopy` Method" - name: P64 - facility: petra-iii # PETRA III Site (facility_code: petra-iii) - sector: "P64" - tier: Unit - parent: null - source: insertion-device - source_confirm: "P64 is an undulator beamline (advanced XAS); the OnlineXML exposes the undulator energy axis (p64/petra3undulator) coupled into the mono, but no period or parameters, carried pending (SRC-1)" - page_layout: stages - shape: "X-ray absorption spectroscopy: a fixed-exit monochromator sweeping across absorption edges, with ion chambers and fluorescence detectors." - source_ref: - label: "python-nxstools-extras-p64" - url: "https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p64" - -# Two enclosures: the optics hutch (the Tsai DCM + the mirror pair) and the experiment -# endstation. DESY PSS permit signals are not in the OnlineXML (PSS-1). -enclosures: - - name: p64-oh - role: optics-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the P64 optics hutch; not in the OnlineXML (PSS-1)"} - - name: p64-eh - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the P64 experiment endstation; not in the OnlineXML (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the undulator and the OH optics -# =========================================================================== - -source: - stage: source - enclosure: p64-oh - intro: "The P64 undulator source and the optics hutch: the Tsai-geometry double-crystal monochromator with its coupled undulator energy axis, and the two harmonic-rejection / focusing mirrors." - note: "The energy axis couples the DCM and the undulator (coupledmonoundmove / energy_all). The mirror pair is exposed as labelled axes (Mirror1*, Mirror2*) on p64/motor." - devices: - - name: Undulator - family: InsertionDevice - pv: {energy_und: "p64/petra3undulator/energy_und"} - new: true - confirm: true - note: "P64 undulator; the energy axis is read (coupled into the mono), period not exposed (SRC-1)" - - name: Monochromator - family: Monochromator - pv: {theta: "p64/DcmTsai/monotheta", energy: "p64/dcmener/energy", energy_all: "p64/coupledmonoundmove/energy_all"} - new: true - confirm: true - note: "Tsai-geometry double-crystal monochromator (DcmTsai monotheta + energy), with energy_all coupling the mono and undulator; crystal cut is OPT-1" - - name: Mirror1 - family: Mirror - pv: {horizontal: "p64/motor/Mirror1Hor", vertical: "p64/motor/Mirror1Ver", tilt: "p64/motor/Mirror1Tilt", yaw: "p64/motor/Mirror1Yaw"} - new: true - confirm: true - note: "first OH mirror (Mirror1: hor / ver / tilt / yaw); harmonic rejection / focusing, coating OPT-1" - - name: Mirror2 - family: Mirror - pv: {horizontal: "p64/motor/Mirror2Hor", vertical: "p64/motor/Mirror2Ver", tilt: "p64/motor/Mirror2Tilt", yaw: "p64/motor/Mirror2Yaw"} - new: true - confirm: true - note: "second OH mirror (Mirror2: hor / ver / tilt / yaw); harmonic rejection / focusing, coating OPT-1" - - name: DefiningSlits - family: Slit - pv: {s3_hgap: "p64/vmexecutor/s3hg", s3_hoff: "p64/vmexecutor/s3ho", s3_vgap: "p64/vmexecutor/s3vg", s3_voff: "p64/vmexecutor/s3vo", s4_hgap: "p64/vmexecutor/s4hg"} - new: true - confirm: true - note: "the beam-defining slits (s3 / s4, vmexecutor virtual gap / offset axes) (OPT-1)" - -# =========================================================================== -# SAMPLE STAGE: the experiment endstation -# =========================================================================== - -experiment-sample: - stage: sample - enclosure: p64-eh - intro: "The P64 experiment endstation: the sample / instrument motor bank, a diamond-anvil-cell sub-stage, and the NewFocus picomotor fine stages." - note: "The exp_mot / dac_* bank carries the sample positioning, roles not labelled (GROUP-1). The dac_* axes are a high-pressure cell sub-stage; the picomotors are NewFocus 8742 fine stages." - devices: - - name: SampleStage - family: LinearStage - pv: {bank: "p64/motor/exp_mot10", dac_phi: "p64/motor/dac_phi", dac_x: "p64/motor/dac_x", dac_y: "p64/motor/dac_y", dac_z: "p64/motor/dac_z"} - new: true - confirm: true - note: "the P64 sample / instrument motor bank (exp_mot* + dac_* on p64/motor); the dac_* axes are a high-pressure-cell sub-stage; per-axis roles not labelled, grouped as one stage (GROUP-1)" - - name: PicomotorStage - family: LinearStage - pv: {pico1: "p64/newfocuspico8742/pico_mot01", pico2: "p64/newfocuspico8742/pico_mot02", pico3: "p64/newfocuspico8742/pico_mot03", pico4: "p64/newfocuspico8742/pico_mot04"} - new: true - confirm: true - note: "the P64 NewFocus 8742 picomotor fine stages (pico_mot01..04); fine sample / optic alignment (GROUP-1)" - -# =========================================================================== -# DETECTION STAGE: the Lambda detectors and the multi-element fluorescence detector -# =========================================================================== - -detection: - stage: detection - enclosure: p64-eh - intro: "The P64 detection: two Lambda 750k area detectors and a large multi-element fluorescence detector (a 104-channel SIS3302 digitizer) for dilute high-rate EXAFS." - note: "The SIS3302 is exposed as 104 ROI / channel devices in the registry; grouped here as one EnergyDispersiveSpectrometer Asset (the multi-element fluorescence detector) (DET-1)." - devices: - - name: LambdaDetectors - family: Camera - pv: {lambda1: "p64/lambda750k/01", lambda2: "p64/lambda750k/02"} - new: true - confirm: true - note: "the two X-Spectrum Lambda 750k area detectors; transmission / total-fluorescence imaging (DET-1)" - - name: FluorescenceDetector - family: EnergyDispersiveSpectrometer - pv: {sis3302: "p64/sis3302/SIS3302_1"} - new: true - confirm: true - note: "the P64 multi-element fluorescence detector (a 104-channel SIS3302 digitizer, exposed as many ROI channels in the registry, grouped here); dilute high-rate EXAFS detection (DET-1)" - -# Cross-cutting control. P64 runs Tango with Sardana, the PETRA III house style. -controls: - intro: > - P64 runs on the PETRA III control system, Tango with Sardana as the scan / motion - SCADA layer, the same floor as the other PETRA III beamlines. A motion axis is a - Tango motor device (p64/motor/...), the monochromator a DcmTsai / dcmener device - with a coupledmonoundmove energy axis, the slits vmexecutor virtual axes, the fine - stages NewFocus 8742 picomotor devices; the detectors are lambda750k area detectors - and the SIS3302 multi-element fluorescence digitizer. The handles are read from - P64's public OnlineXML registry and carried confirm (CTRL-1). The XAS acquisition - (the coupled mono + undulator energy scan read against the transmission / multi- - element fluorescence signal) runs as a Sardana macro, often as a continuous energy - fly-scan; that orchestration is the seam CORA's edge would conduct over its - ControlPort, the same shape as the BMM / ISS XAS seams (CTRL-2). - motion_controllers: - - name: OMS58Controllers - family: MotionController - protocol: Tango_oms58 - new: true - confirm: true - note: "OMS MAXv-58 stepper controllers (oms58) driving the optics and sample motor banks (CTRL-1)" - - name: PicomotorControllers - family: MotionController - protocol: Tango_newfocuspico8742 - new: true - confirm: true - note: "NewFocus 8742 picomotor controllers driving the fine sample / optic stages (CTRL-1)" - - name: TangoMotorControllers - family: MotionController - protocol: Tango_motor_tango - new: true - confirm: true - note: "generic Tango motor controllers (motor_tango) backing the Tsai mono and the coupled energy axis (CTRL-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a P64 run needs present before it - can start. All pending confirmation. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/p65/beamline.yaml b/deployments/p65/beamline.yaml deleted file mode 100644 index 198a34c8c25..00000000000 --- a/deployments/p65/beamline.yaml +++ /dev/null @@ -1,175 +0,0 @@ -# P65 beamline descriptor (PETRA III, DESY), reverse-engineered from the OnlineXML -# -# P65 "Applied X-ray Absorption Spectroscopy" is the standard / high-throughput EXAFS -# / XANES beamline at PETRA III (DESY, Hamburg), the applied-XAS sibling of the -# advanced P64. It is bound to the PETRA III Site (deployments/petra-iii/site.yaml), -# the tenth PETRA III beamline, and is scaffolded together with P64 as the PETRA III -# XAS pair (they share the hasnp64 optics host). -# -# STATUS: reverse-engineered from P65's own public OnlineXML device registry -# (gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p65, branch -# debian/jessie; the online_hasnp65.xml registry). Device logical names and Tango -# control handles are real, read from that registry; vendor part numbers, crystal -# cuts, the detector roster, energy calibration, and physical positions are not in it -# and are open questions. Every value is carried confirm until P65 staff verify it. -# The extraction is in the xmap/research repo (private), under petra-iii/. -# -# WHAT IS NEW: no new device Family. P65 is a thin applied-XAS station: a CDCM energy -# axis, a small experiment sample bank, an experiment slit / table, and the undulator, -# reusing existing Families. The technique (X-ray absorption spectroscopy) reuses the -# pending xas_spectroscopy slug (TECH-1). -# -# CONTROL HANDLES: the descriptor `pv` field carries the Tango device address read -# from the OnlineXML. P65 shares the optics with P64: its energy / optics devices -# report on the P64-OH Tango host (hasnp64); per the cross-host mapping decision they -# are homed in the P65 optics enclosure with the host flagged (HOST-1). The a2 sample -# bank carries the experiment positioning, roles not labelled (GROUP-1); the a2_dmy -# stubs are dummy / placeholder devices (STUB-1). -# -# SCOPE: this cut models the optics (the undulator, the CDCM energy axis, the OH -# bank), the experiment endstation (the a2 sample bank, the slit / table virtual -# axes), and notes the front-end (fe) bank. Counter / timer / ADC channels and the -# Sardana MeasurementGroup bookkeeping rows are filtered out by the extractor. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/p65/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "applied / high-throughput X-ray absorption spectroscopy (transmission + fluorescence EXAFS / XANES) on a channel-cut DCM, sharing the P64 optics host; the applied half of the XAS pair, a thin reuse-and-reinforce scaffold (detection carried pending), reusing the pending `xas_spectroscopy` Method" - name: P65 - facility: petra-iii # PETRA III Site (facility_code: petra-iii) - sector: "P65" - tier: Unit - parent: null - source: insertion-device - source_confirm: "P65 is an undulator beamline (applied XAS); the OnlineXML exposes the undulator energy axis (p65/petra3undulator) but no period or parameters, carried pending (SRC-1)" - page_layout: stages - shape: "Applied X-ray absorption spectroscopy for routine EXAFS / XANES on a damping-wiggler source, with the standard ion-chamber and fluorescence detection chain." - source_ref: - label: "python-nxstools-extras-p65" - url: "https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p65" - -# Two enclosures: the optics (shared with P64, on the hasnp64 host) and the experiment -# endstation. DESY PSS permit signals are not in the OnlineXML (PSS-1). -enclosures: - - name: p65-oh - role: optics-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the P65 optics (shared with P64 on the hasnp64 host); not in the OnlineXML (PSS-1)"} - - name: p65-eh - role: experiment-hutch - facility_code: petra-iii - permit_signal: {confirm: "DESY PSS permit signal for the P65 experiment endstation; not in the OnlineXML (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the undulator and the (P64-shared) optics -# =========================================================================== - -source: - stage: source - enclosure: p65-oh - intro: "The P65 undulator source and the optics: a channel-cut double-crystal monochromator energy axis and the optics-hutch positioning bank. P65 shares the optics hutch with P64." - note: "The energy axis is a CDCM (cdcmenergy). The OH bank and the front-end (fe) bank carry the optics positioning, roles not labelled. These optics report on the P64-OH host (hasnp64) (HOST-1, GROUP-1)." - devices: - - name: Undulator - family: InsertionDevice - pv: {energy_und: "p65/petra3undulator/energy_und"} - new: true - confirm: true - note: "P65 undulator; the energy axis is read, period not exposed (SRC-1)" - - name: Monochromator - family: Monochromator - pv: {energy_dcm: "p65/cdcmenergy/energy_dcm"} - new: true - confirm: true - note: "channel-cut double-crystal monochromator energy axis (cdcmenergy); reports on the P64-OH host (HOST-1); crystal cut and energy range are OPT-1" - - name: OpticsStages - family: LinearStage - pv: {oh_bank: "p65/motor/oh_01", fe_bank: "p65/motor/fe_01"} - new: true - confirm: true - note: "the P65 optics-hutch (oh_*) and front-end (fe_*) motor banks; mirror / slit / front-end positioning, per-axis roles not labelled, grouped as one stage (OPT-1, GROUP-1, HOST-1)" - -# =========================================================================== -# SAMPLE STAGE: the experiment endstation -# =========================================================================== - -experiment-sample: - stage: sample - enclosure: p65-eh - intro: "The P65 experiment endstation: the a2 sample / instrument motor bank and the experiment slit / table virtual axes." - note: "The a2 bank carries the sample positioning, roles not labelled (GROUP-1). The a2_dmy stubs are dummy / placeholder devices (STUB-1). The slit / table are vmexecutor virtual axes." - devices: - - name: SampleStage - family: LinearStage - pv: {bank: "p65/motor/a2_mot01"} - new: true - confirm: true - note: "the P65 experiment sample / instrument motor bank (a2_mot01..20 on p65/motor); per-axis roles not labelled, grouped as one stage (GROUP-1)" - - name: ExperimentSlit - family: Slit - pv: {center_x: "p65/vmexecutor/eh_slit_cx", center_y: "p65/vmexecutor/eh_slit_cy"} - new: true - confirm: true - note: "the P65 experiment slit (eh_slit center x / y, vmexecutor virtual axes)" - - name: ExperimentTable - family: Table - pv: {height: "p65/vmexecutor/eh_table_h", vertical: "p65/vmexecutor/eh_table_v"} - new: true - confirm: true - note: "the P65 experiment table (eh_table height / vertical, vmexecutor virtual axes)" - -# =========================================================================== -# DETECTION STAGE -# =========================================================================== - -detection: - stage: detection - enclosure: p65-eh - intro: "The P65 detection. The OnlineXML slice for P65 exposes no dedicated detector device beyond the experiment motors; the XAS detection (ion chambers / fluorescence) is carried pending." - note: "Standard applied-XAS detection (ion chambers for transmission, a fluorescence detector) is not exposed as a device in this registry slice; carried pending (DET-1)." - devices: - - name: AbsorptionDetectors - family: FluxMonitor - pv: {confirm: "the XAS ion chambers (I0 / I1 / I2) and any fluorescence detector are not exposed in this OnlineXML slice; carried pending (DET-1)"} - new: true - confirm: true - note: "the P65 absorption-spectroscopy detection (ion chambers for transmission XAS, a fluorescence detector); not in the registry slice, modelled as a pending FluxMonitor placeholder (DET-1)" - -# Cross-cutting control. P65 runs Tango with Sardana, the PETRA III house style. -controls: - intro: > - P65 runs on the PETRA III control system, Tango with Sardana as the scan / motion - SCADA layer, the same floor as the other PETRA III beamlines. A motion axis is a - Tango motor device (p65/motor/...), the energy a cdcmenergy device, the slit / - table vmexecutor virtual axes; P65 shares the optics hutch with P64 (the hasnp64 - host). The handles are read from P65's public OnlineXML registry and carried - confirm (CTRL-1). The XAS acquisition (the CDCM energy scan read against the - transmission / fluorescence signal) runs as a Sardana macro; that orchestration is - the seam CORA's edge would conduct over its ControlPort (CTRL-2). - motion_controllers: - - name: OMS58Controllers - family: MotionController - protocol: Tango_oms58 - new: true - confirm: true - note: "OMS MAXv-58 stepper controllers (oms58) driving the optics and sample motor banks (CTRL-1)" - - name: TangoMotorControllers - family: MotionController - protocol: Tango_motor_tango - new: true - confirm: true - note: "generic Tango motor controllers (motor_tango / tangomotor) backing the CDCM energy axis and the a2 dummy stubs (CTRL-1, STUB-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a P65 run needs present before it - can start. All pending confirmation. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/pdf/beamline.yaml b/deployments/pdf/beamline.yaml deleted file mode 100644 index 5ba41f47cd8..00000000000 --- a/deployments/pdf/beamline.yaml +++ /dev/null @@ -1,238 +0,0 @@ -# PDF beamline descriptor (NSLS-II), reverse-engineered -# -# PDF (Pair Distribution Function) is the NSLS-II high-energy total-scattering and -# powder-diffraction beamline at sector 28-ID-1. Its defining technique is the -# rapid-acquisition pair distribution function (total scattering): a high-energy beam -# through a powder or capillary sample onto large flat-panel area detectors, with the -# sample-to-detector distance setting the accessible Q and a near / far detector pair -# merged to reach the high Q a PDF needs. It is bound to the NSLS-II Site -# (deployments/nsls2/site.yaml). -# -# TWIN GUARD. PDF (28-ID-1, XF:28ID1*) and XPD (28-ID-2, XF:28ID*; deployments/xpd) -# are the two endstations on the shared 28-ID damping wiggler: same science family -# (high-energy powder diffraction and total scattering / PDF), different branch and -# PV namespace. PDF is the dedicated total-scattering / PDF endstation; XPD is its -# already-modelled twin. This descriptor reuses XPD's modelling wholesale. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the bluesky profile collection NSLS2/pdf-profile-collection and the device -# library NSLS2/pdftools) or inferred, carried `confirm: true` pending PDF staff. -# EPICS PVs are real and verified against the startup scripts and the pdftools device -# classes; vendor part numbers, serials, and physical positions are not in them and -# are open questions. Same descriptor mode as XPD / CHX; this scaffold is descriptor -# + docs, scenarios deferred. -# -# PDF is the POWDER-DIFFRACTION / PDF reinforcement, the twin of XPD and (through it) -# of Diamond i11 (powder diffraction) and i15-1 (total scattering / PDF). It introduces -# NO new catalog family: the flat-panel and pixel area detectors reuse Camera, the -# photodiode flux monitor FluxMonitor, the cryostream / cryostat / furnace -# TemperatureController (graduated #350), the side-bounce Laue monochromator -# Monochromator, the focusing mirror Mirror, the spinner sample stage Goniometer, the -# slits Slit, the fast shutter Shutter, the beamstops BeamStop, the detector and -# sample-environment stages LinearStage, the master energy a PseudoAxis. Its one loose -# family is the StorageRing supply readback (MACHINE-1). Per the i11 / i15-1 / XPD -# precedent the powder-diffraction and total-scattering Methods are NOT coined here; -# they are the deferred owner-scope cohort (TECH-1). The two distinctive shapes vs XPD -# are carried by what is real, not coined: a side-bounce (single-bounce Laue) -# monochromator instead of XPD's bent double-Laue (a Monochromator settings -# difference), and an explicit two-detector / two-distance acquisition that merges a -# near and a far panel for the PDF Q-range (DIST-1). - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "high-energy total scattering / pair distribution function and powder diffraction (side-bounce Laue mono, two-detector two-distance merge on PerkinElmer + Pilatus panels), 28-ID-1; XPD's dedicated PDF twin on the shared 28-ID damping wiggler; modelled from public beamline config" - name: PDF - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "Sector 28" # PV namespace XF:28ID1* - tier: Unit - parent: null - source: insertion-device - source_confirm: "the source is the shared 28-ID damping wiggler (the high-flux high-energy source PDF and XPD both need); no source PV or parameters are in the profile collection, so the subtype is an inference pending staff confirmation (SRC-1)" - page_layout: stages - shape: "XPD's twin on the shared 28-ID wiggler: high-energy total scattering onto large flat-panel detectors, with an explicit two-detector, two-distance acquisition for wide-Q PDF." - source_ref: - label: "NSLS2/pdf-profile-collection" - url: "https://github.com/NSLS2/pdf-profile-collection" -enclosures: - # PV zones: 28ID1A first-optics hutch (FOE: the side-bounce mono and focusing - # mirror), 28ID1B the experiment hutch (the PDF / total-scattering endstation, with - # the spinner, the detector towers, the beamstops, and the sample environment). - - name: 28-ID-1-A - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS search-and-secure permit leaf not in source; only the fast shutter (XF:28ID1B-OP{PSh:1-Det:2}) and a photon shutter are exposed, not the front-end PPS leaves (PSS-1)"} - - name: 28-ID-1-B - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; 28-ID-1-B is the PDF / total-scattering endstation carrying the spinner, detector towers, and sample environment (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the damping-wiggler source and the machine readback -# =========================================================================== - -source: - stage: source - enclosure: 28-ID-1-A - intro: The shared 28-ID damping-wiggler source feeding the high-energy beam, and the storage-ring readback. - devices: - - name: Source - family: InsertionDevice - confirm: true - note: "28-ID insertion-device source. No source PV or parameters are in the profile collection; from facility knowledge (not the public config) it is the shared 28-ID damping wiggler, the high-flux high-energy regime PDF needs, an inference pending staff confirmation (SRC-1). The same source feeds the XPD twin." - - name: StorageRing - family: StorageRing # loose supply (MACHINE-1) - pv: "SR:OPS-BI{DCCT:1}I:Real-I" - confirm: true - note: "Storage-ring current readback (ring_current), an observe-only machine-state signal. Binds the loose StorageRing supply family (never an Asset Family, MACHINE-1)." - -# =========================================================================== -# OPTICS STAGE: the side-bounce monochromator, the focusing mirror, the slits -# =========================================================================== - -optics: - stage: source - enclosure: 28-ID-1-A - intro: "Condition the high-energy beam and set its energy: the side-bounce monochromator, the vertical focusing mirror, and the white-beam slits. PVs verified against startup/12-optics.py and pdftools/motors.py." - devices: - - name: Monochromator - family: Monochromator - pv: "XF:28ID1A-OP{Mono:SBM-Ax:" - confirm: true - note: "Side-bounce monochromator (class SideBounceMono, instance sbm): a single-bounce Laue crystal on wedge-mount X / Y, yaw / pitch / roll, and a four-corner bender (inboard / outboard, upper / lower). A high-flux high-energy mono, the PDF counterpart of XPD's bent double-Laue (a Monochromator settings difference, not a new family). The EnergyAxis below is the master energy; crystal cut and range pending (MONO-1)." - - name: VerticalFocusingMirror - family: Mirror - pv: "XF:28ID1A-OP{Mir:VFM-Ax:" - confirm: true - note: "Vertical focusing mirror (class Mirror, instance Mirror_VFM): upstream / downstream jacks and an upstream / downstream bender with encoders. Reuses the Mirror family." - - name: WhiteBeamSlit - family: Slit - pv: "XF:28ID1A-OP{Slt:0-Ax:" - confirm: true - note: "White-beam-defining slit (class Slits, instance WB_slits): top / bottom / inboard / outboard blades. A beam-defining slit (BDM_slits, Slt:1) sits on the same module. Reuses the Slit family." - - name: EnergyAxis - family: PseudoAxis - confirm: true - note: "The master energy axis set by the side-bounce monochromator. PDF runs at a fixed high energy per experiment; whether energy is ever scanned as the measurement is ENERGY-1." - -# =========================================================================== -# SAMPLE STAGE: the cleanup slit, the fast shutter, the spinner, the sample -# environment stages, and the thermal environment cluster -# =========================================================================== - -sample: - stage: sample - enclosure: 28-ID-1-B - intro: "The endstation beam conditioning and the sample side: the cleanup slit, the fast shutter, the capillary spinner, the sample-environment stage, and the thermal-environment cluster. PVs verified against startup/12-optics.py, 11-motors.py, 14-lakeshore_cryostat.py, 15-cs800crystream.py, 17-linkam.py and pdftools/sample_environment.py." - note: > - PDF positions a powder or capillary sample in the high-energy beam and records the - total-scattering pattern on the area detectors. The capillary spinner averages the - powder texture; the rich thermal-environment cluster (cryostream, cryostat, - furnace) drives in-situ variable-temperature studies. A gas-handling and humidity - rig is present in source but carried deferred (ENV-1). - devices: - - name: CleanupSlit - family: Slit - pv: "XF:28ID1B-OP{Slt:AS-Ax:" - confirm: true - note: "Endstation cleanup / guard slit (class Slits, instance cleanup_slits) trimming parasitic scatter ahead of the sample; an optics-cabin OCM slit (OCM_slits, Slt:2) sits upstream. Reuses the Slit family." - - name: FastShutter - family: Shutter - pv: "XF:28ID1B-OP{PSh:1-Det:2}" - confirm: true - note: "Fast exposure shutter (class PDFFastShutter, instance fs) gating the detector exposure; a slower photon shutter (class PDFShutter) sits alongside. Reuses the Shutter family." - - name: SpinnerGoniohead - family: Goniometer - pv: "XF:28ID1B-ES{Stg:Smpl-Ax:" - confirm: true - note: "Capillary-spinner goniohead (class SpinnerGoniohead / XYZSpinner, instance spinner_goniohead): sample X / Y / Z plus a spin axis (Ry) that rotates the capillary to average powder texture. An analyzer goniohead (analyzer_goniohead, Spn:Anlzr) sits alongside. Reuses the Goniometer family; the full axis modelling is STAGE-1." - - name: SampleEnvironmentStage - family: LinearStage - pv: "XF:28ID1B-ES{Env:1-Ax:" - confirm: true - note: "Sample-environment positioning stage (Grid_X / Grid_Y / Grid_Z) presenting the sample-environment cell to the beam; reuses the LinearStage family." - - name: SampleTemperature - family: TemperatureController - pv: "XF:28ID1-ES:1{Env:01}" - confirm: true - note: "Sample-environment thermal cluster: a cs800 cryostream controller (class CS800TemperatureController, XF:28ID1-ES:1{Env:01}, understood to be an Oxford Cryostream, inference, TEMP-1), a Lakeshore 336 cryostat (XF:28ID1-ES{LS336:1), and a Linkam T96 furnace (class LinkamFurnace_T96, XF:28ID1-ES{LINKAM:T96}:). Modelled as one thermal-environment Asset; reuses TemperatureController (graduated #350). Which units are live is TEMP-1." - -# =========================================================================== -# DETECTION STAGE: the flat-panel and pixel detectors, the two detector towers, -# the beamstops, and the flux monitor -# =========================================================================== - -detector: - stage: detection - enclosure: 28-ID-1-B - intro: "The large flat-panel and pixel area detectors for total scattering / PDF, the two detector towers that set the near and far distances, the beamstops, and the flux monitor. PVs verified against startup/80-areadetector2.py, 81-pilatus.py, 72-two-detector.py, 11-motors.py, 10-machine.py." - note: > - PDF's measurement is the total-scattering pattern on a large area detector. To - reach the high Q a pair distribution function needs, the detector sits close; a - near panel and a far panel are merged across two distances. The two detector towers - move the panels in and out, the explicit two-detector acquisition (DIST-1). All - reuse existing families. Which panels are live versus the spare set is DET-1. - devices: - - name: AreaDetector - family: Camera - pv: "XF:28ID1-ES{Det:PE1}" - confirm: true - note: "PerkinElmer flat-panel area detector (class PerkinElmerStandard, instance pe1; a second panel pe2 at Det:PE2). The primary total-scattering / powder detector; reuses Camera." - - name: PixelDetector - family: Camera - pv: "XF:28ID1-ES{Det:Pilatus}" - confirm: true - note: "Pilatus photon-counting pixel detector (class PilatusV33, instance pilatus-1) with an energy-thresholded readout, used alongside the flat panels for high-Q / low-background frames; reuses Camera. Which detector serves which distance is DET-1 / DIST-1." - - name: DetectorStage1 - family: LinearStage - pv: "XF:28ID1B-ES{Det:1-Ax:" - confirm: true - note: "First detector tower (Det_1_X / Det_1_Y / Det_1_Z): the Z axis sets the sample-to-detector distance and hence the accessible Q. In the two-detector acquisition this is the static panel. Reuses LinearStage." - - name: DetectorStage2 - family: LinearStage - pv: "XF:28ID1B-ES{Det:2-Ax:" - confirm: true - note: "Second detector tower (Det_2_X / Det_2_Y / Det_2_Z): the moving panel that steps in and out of the beam for the near / far two-distance merge (the TwoDetectors plan, 72-two-detector.py). Reuses LinearStage; the two-distance geometry is DIST-1." - - name: BeamStop - family: BeamStop - pv: "XF:28ID1B-ES{BS:1-Ax:" - confirm: true - note: "Direct-beam stop (class BeamStop, instance BStop1, X / Y); a second beamstop (BStop2, BS:2) and a table-mounted stop sit alongside, one per detector distance. Reuses the BeamStop family." - - name: FluxMonitor - family: FluxMonitor - pv: "XF:28ID1B-OP{Det:1-Det:2}Amp:bkgnd" - confirm: true - note: "Background photodiode (photodiode) reading incident-flux / background for normalization; reuses FluxMonitor (graduated #353). Channel detail pending (DIAG-1)." - -# =========================================================================== -# Cross-cutting controls -# =========================================================================== - -controls: - intro: > - PDF acquisition is software-triggered: the flat-panel detectors run in continuous - or multi-trigger mode gated by the fast exposure shutter, with no separate hardware - timing box in the profile collection, the same shape as XPD. The two-detector - two-distance merge is sequenced by a bluesky plan (the TwoDetectors helper), not a - hardware trigger. Controller box models / firmware are not in the profile - collection (DRIVE-1). - motion_controllers: - - name: EndstationMotionController - family: MotionController - confirm: true - note: "The optics and endstation motion controllers driving the monochromator, mirror, spinner, sample-environment, and detector-tower axes; box model / protocol / IP not in the profile collection (DRIVE-1)." - triggering: [] - software_iocs_not_modeled: - [PerkinElmer, Pilatus, Cryostream, Lakeshore, Linkam, Eurotherm, Prosilica] - -resources: - intro: Continuously-available resources. Facility-scope supplies live in deployments/nsls2/site.yaml. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: LiquidNitrogen # cryostream / cryostat - - kind: Power - replaceable_parts: - swappable_with_identity: ["area detectors", "capillary samples", "sample-environment cells"] diff --git a/deployments/petra-iii/site.yaml b/deployments/petra-iii/site.yaml deleted file mode 100644 index fe3a4478bc9..00000000000 --- a/deployments/petra-iii/site.yaml +++ /dev/null @@ -1,183 +0,0 @@ -# CORA Site descriptor: the PETRA III (DESY) site-level surface -# -# PETRA III is the 2.3 km hard X-ray synchrotron at DESY (Deutsches -# Elektronen-Synchrotron, Hamburg-Bahrenfeld, Germany). It is the Site CORA models -# for its DESY deployment, and the home of the P01 beamline scaffold (the first -# PETRA III deployment). 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. -# -# Status: reverse-engineered. CORA has not been connected to PETRA III and no staff -# have confirmed this model. Every value below is read from public open source (the -# gitlab.desy.de tango-ds / fsec-sardana / petra-iii-debian-packages control trees, -# the photon-science.desy.de beamline catalog) or inferred, and is carried as `pending` until staff -# confirm it. Do not invent facility specifics here; carry them as questions on each -# beamline's open-questions page. -# -# Source-of-truth boundary (same as the APS / ESRF / MAX IV / Diamond / NSLS-II / -# SLAC / NSRRC / Sirius sites): -# - the closed facility-kind / actor-kind vocabularies are validated against -# code-mirrored frozensets in scripts/site_descriptor.py. -# - the facility records the bootstrap invariants (kind=Site, display_name equals -# code); `heading` carries the human title used on the rendered page. -# -# Controls house-style (the distinctive Site fact): PETRA III runs a Tango control -# floor with Sardana as the scan / motion SCADA layer (Pool / MacroServer / -# MeasurementGroup, Spock CLI, Taurus UIs), NOT EPICS. Each beamline's device tree -# is published as an OnlineXML registry (online_*.xml: Tango device name, class, -# address, host) under petra-iii-debian-packages on gitlab.desy.de, and the device -# servers live in tango-ds/deviceclasses. This is the second Tango / Sardana house -# style CORA models (after MAX IV) and a sibling of the ESRF BLISS / Tango floor. -# DESY also runs DOOCS / TINE for the accelerator, which is out of beamline scope. -# CORA's EdgeConductor would conduct routines over the Tango floor where Sardana's -# MacroServer sits today. See docs/deployments/p01/equipment/controls.md. -# -# SUB-OPERATOR house style (EMBL Hamburg, the P13 / P14 cluster): not every PETRA III -# beamline runs the DESY house style. EMBL Hamburg operates its own beamlines on the -# ring (P12 BioSAXS, P13 / P14 macromolecular crystallography) with its OWN control -# domain: MXCuBE as the experiment-orchestration layer over the Exporter protocol (the -# microdiff / MD2-style host, e.g. p13md201.embl-hamburg.de:9001) and TINE channels -# (/P13/..., /P14/...) for the detector, energy, and beam services, NOT Tango / Sardana -# / OnlineXML. So these beamlines are modelled as a sub-operator control-domain WITHIN -# this Site: same ring and Facility, distinct operator and control floor. The device -# topology is reverse-engineered from EMBL's public MXCuBE HardwareObjects config -# (github.com/mxcube/mxcubecore, configuration/embl_hh_p13 / embl_hh_p14). The -# operator / interlock boundary (EMBL operates the beamline, DESY hosts the ring) is -# carried pending (SEAM-1, GOV-1). See docs/deployments/p13/equipment/controls.md. - -facility: - code: petra-iii - display_name: petra-iii - heading: "PETRA III" - kind: Site - institution: DESY (Deutsches Elektronen-Synchrotron, Hamburg, Germany) - control_plane: "Tango / Sardana" - beamlines_note: "Nineteen beamlines on the PETRA III ring read from a common Tango / Sardana OnlineXML registry; several share optics (P22 runs off the P09 chain)." - beamlines: [P01, P04, P06, P11, P03, P10, P09, P02, P64, P65, P07, P08, P21, P22, P23, P24, P61, P13, P14] - -# ISA-88 Site Recipes: the facility-adapted form of a catalog Method. -# -# P01 (Dynamics): nuclear resonant scattering (NRS) and inelastic / resonant -# inelastic X-ray scattering (IXS / RIXS). None of CORA's catalog Methods (all -# tomography-family today) fit, so every P01 practice is pending, naming the Method -# it would earn. RIXS reuses the resonant_inelastic_scattering slug SIX left pending -# and ESRF ID32 shares; IXS reuses the inelastic_x_ray_scattering slug NSLS-II IXS -# left pending and ESRF ID28 shares. Confirm with DESY staff (TECH-1). -practices: - - {name: P01_nuclear_resonant_scattering_practice, method: inelastic_x_ray_scattering, pending: true, note: "nuclear resonant scattering / nuclear inelastic scattering (Moessbauer-energy-resolution time- and energy-domain) on the high-resolution monochromator stack + avalanche-photodiode detection; no catalog Method fits, reuses the inelastic_x_ray_scattering slug ID28 / NSLS-II IXS share, a further consumer (TECH-1)"} - - {name: P01_rixs_practice, method: resonant_inelastic_scattering, pending: true, note: "resonant inelastic X-ray scattering on the EH3 KB-focused spectrometer endstation; reuses the resonant_inelastic_scattering slug SIX / ESRF ID32 share, a further consumer (TECH-1)"} - # P04 (Variable Polarization XUV): soft X-ray spectroscopy, 250-3000 eV. Soft X-ray - # absorption reuses the xas_spectroscopy slug 4 sites share; photoemission reuses the - # angle_resolved_photoemission slug. Both pending until DESY staff confirm (TECH-1). - - {name: P04_xas_practice, method: xas_spectroscopy, pending: true, note: "soft X-ray absorption spectroscopy (total electron yield via the drain-current electrometer) over the undulator + plane-grating-monochromator photon-energy scan; reuses the xas_spectroscopy slug, a further consumer (TECH-1)"} - - {name: P04_photoemission_practice, method: angle_resolved_photoemission, pending: true, note: "soft X-ray photoemission on the EXP endstations; reuses the angle_resolved_photoemission slug, a further consumer (TECH-1)"} - # P06 (Micro- and Nanoprobe): hard X-ray scanning fluorescence / diffraction - # microscopy + nano-tomography. Scanning XRF reuses the scanning_fluorescence_ - # microscopy slug 4 sites share; nano-tomography reuses the tomography slug. Both - # pending until DESY staff confirm (TECH-1). - - {name: P06_scanning_fluorescence_microscopy_practice, method: scanning_fluorescence_microscopy, pending: true, note: "hard X-ray scanning fluorescence / diffraction microscopy: the Aerotech raster fly-scan over the micro / nano focus reading the Maia XRF array; reuses the scanning_fluorescence_microscopy slug 2-ID / XFM / LIX / ESRF ID16B share, a further consumer (TECH-1)"} - - {name: P06_nanotomography_practice, method: tomography, pending: true, note: "hard X-ray nano-tomography on the NC1 sample rotation (Pegasus samr) + area detector; reuses the catalog tomography Method, a further consumer (TECH-1)"} - # P11 (Bio-Imaging and Diffraction): high-throughput rotation macromolecular - # crystallography + bio-imaging. MX reuses the i03 mx_data_collection slug 7 sites - # share; bio-imaging reuses the tomography slug. Both pending until DESY staff - # confirm (TECH-1). - - {name: P11_mx_data_collection_practice, method: mx_data_collection, pending: true, note: "rotation / oscillation macromolecular-crystallography data collection on the goniometer + Pilatus area detector with cryostream cooling; reuses the i03 mx_data_collection slug FMX / AMX / MX3 / MANACA / TPS share, a further consumer (TECH-1)"} - - {name: P11_bioimaging_practice, method: tomography, pending: true, note: "full-field / coherent bio-imaging on the experiment-hutch stages + Pilatus detector; reuses the catalog tomography Method, a further consumer (TECH-1)"} - # P13 (EMBL Hamburg, sub-operator): high-throughput rotation macromolecular - # crystallography on the EMBLMiniDiff + Eiger / Pilatus, run through EMBL's MXCuBE - # over Exporter + TINE, NOT the DESY Tango / Sardana floor. MX reuses the i03 - # mx_data_collection slug 7 sites share. Pending until EMBL staff confirm (TECH-1). - - {name: P13_mx_data_collection_practice, method: mx_data_collection, pending: true, note: "rotation / oscillation macromolecular-crystallography data collection on the EMBLMiniDiff microdiffractometer + Eiger 16M / Pilatus 6M area detector with cryostream cooling, orchestrated by EMBL's MXCuBE over Exporter + TINE; reuses the i03 mx_data_collection slug FMX / AMX / MX3 / MANACA / TPS / P11 share, a further consumer (TECH-1, SEAM-1)"} - # P14 (EMBL Hamburg, sub-operator): high-end rotation macromolecular crystallography - # across TWO experiment hutches (EH1 EMBLMiniDiff + Eiger variants, EH2 EMBLBSD + - # Pilatus 2M) fed by one source / optics chain, run through EMBL's MXCuBE over - # Exporter + TINE. MX reuses the i03 mx_data_collection slug. Pending (TECH-1). - - {name: P14_mx_data_collection_practice, method: mx_data_collection, pending: true, note: "rotation / oscillation macromolecular-crystallography data collection across two endstations (EH1 EMBLMiniDiff + Eiger 16M silicon / 16M / 4M CdTe, EH2 EMBLBSD + Pilatus 2M) fed by one shared source / optics chain with cryostream cooling, orchestrated by EMBL's MXCuBE over Exporter + TINE; reuses the i03 mx_data_collection slug FMX / AMX / MX3 / MANACA / TPS / P11 / P13 share, a further consumer (TECH-1, SEAM-1, EH-1)"} - # P03 (MiNaXS): micro- and nanofocus small- and wide-angle X-ray scattering, 9-23 - # keV, across a microfocus and a nanofocus GINIX endstation. SAXS reuses the - # small_angle_scattering slug, WAXS the wide_angle_scattering slug. Both pending - # until DESY staff confirm (TECH-1). - - {name: P03_small_angle_scattering_practice, method: small_angle_scattering, pending: true, note: "micro- and nanofocus small-angle X-ray scattering on the sample stage + Pilatus area detector; reuses the small_angle_scattering slug, a further consumer (TECH-1)"} - - {name: P03_wide_angle_scattering_practice, method: wide_angle_scattering, pending: true, note: "wide-angle X-ray scattering on the Pilatus 1M detector; reuses the wide_angle_scattering slug, a further consumer (TECH-1)"} - # P10 (Coherence Applications): XPCS + coherent imaging. XPCS binds the GRADUATED - # catalog xpcs Method (8-ID precedent), so this practice is NOT pending, the first - # PETRA III practice whose Method is already earned. Coherent imaging reuses the - # pending ptychography / coherent_surface_scattering slugs (TECH-1). - - {name: P10_xpcs_practice, method: xpcs, note: "X-ray photon correlation spectroscopy: the coherent beam on the sample read by the high-frame-rate Lambda / Eiger, the intensity correlation computed downstream; binds the graduated xpcs Method (8-ID), the second consumer"} - - {name: P10_ptychography_practice, method: ptychography, pending: true, note: "coherent diffraction imaging / ptychography on the E1 endstation + Quadro / Eiger detector; reuses the ptychography slug, a further consumer (TECH-1)"} - # P09 (Resonant Scattering and Diffraction): resonant scattering, magnetic - # scattering / XMCD, and diffraction across a resonant-scattering hutch, a diffraction - # hutch, and a 14 T magnetism endstation. Resonant scattering reuses the - # resonant_scattering slug; magnetic scattering / XMCD reuse the magnetic_scattering / - # xmcd slugs the 4-ID / i06 / i10 beamlines share. All pending (TECH-1). - - {name: P09_resonant_scattering_practice, method: resonant_scattering, pending: true, note: "resonant elastic X-ray scattering on the six-circle diffractometer + PerkinElmer / Pilatus detector, with polarization analysis; reuses the resonant_scattering slug 4-ID / i06 / i10 share, a further consumer (TECH-1)"} - - {name: P09_magnetic_scattering_practice, method: magnetic_scattering, pending: true, note: "magnetic scattering in the 14 T high-field magnetism endstation; reuses the magnetic_scattering slug, a further consumer (TECH-1)"} - - {name: P09_xmcd_practice, method: xmcd, pending: true, note: "X-ray magnetic circular / linear dichroism in the 14 T magnet, with the phase retarder setting polarization; reuses the 4-ID / i06 / i10 xmcd slug, a further consumer (TECH-1)"} - # P02 (Hard X-ray Diffraction): P02.1 powder diffraction / total scattering / PDF + - # P02.2 extreme conditions (diamond-anvil-cell high-pressure diffraction). Powder - # reuses the powder_diffraction slug, total scattering the total_scattering slug. - # Both pending until DESY staff confirm (TECH-1). - - {name: P02_powder_diffraction_practice, method: powder_diffraction, pending: true, note: "high-energy powder diffraction on the P02.1 endstation + Pilatus 1M; reuses the powder_diffraction slug i11 / XPD share, a further consumer (TECH-1)"} - - {name: P02_total_scattering_practice, method: total_scattering, pending: true, note: "total scattering / pair-distribution-function on the P02.1 PerkinElmer flat-panel (high-Q); reuses the total_scattering slug i15-1 / XPD share, a further consumer (TECH-1)"} - - {name: P02_high_pressure_diffraction_practice, method: powder_diffraction, pending: true, note: "diamond-anvil-cell high-pressure diffraction on the P02.2 extreme-conditions endstation; reuses the powder_diffraction slug, a further consumer (TECH-1, PRESSURE-1)"} - # P64 + P65 (X-ray absorption spectroscopy pair): advanced fluorescence EXAFS (P64) - # and applied / high-throughput EXAFS (P65), sharing the hasnp64 optics host. Both - # reuse the xas_spectroscopy slug BMM / ISS / i20-1 / P04 share. Pending (TECH-1). - - {name: P64_xas_practice, method: xas_spectroscopy, pending: true, note: "advanced X-ray absorption spectroscopy (dilute high-rate fluorescence EXAFS / XANES) on the Tsai DCM + multi-element fluorescence detector; reuses the xas_spectroscopy slug, a further consumer (TECH-1)"} - - {name: P65_xas_practice, method: xas_spectroscopy, pending: true, note: "applied / high-throughput X-ray absorption spectroscopy (transmission + fluorescence EXAFS / XANES) on the CDCM energy scan; reuses the xas_spectroscopy slug, a further consumer (TECH-1)"} - # P07 (HEMS, Hereon-operated): high-energy materials-science diffraction + high-field - # studies. Diffraction reuses the diffraction slug; the 17 T magnet work reuses the - # magnetic_scattering slug. Both pending until DESY / Hereon staff confirm (TECH-1). - - {name: P07_diffraction_practice, method: diffraction, pending: true, note: "high-energy materials-science diffraction on the four-circle diffractometer + Pilatus / PerkinElmer; reuses the diffraction slug, a further consumer (TECH-1)"} - - {name: P07_magnetic_scattering_practice, method: magnetic_scattering, pending: true, note: "high-field materials studies in the 17 T magnet; reuses the magnetic_scattering slug P09 / 4-ID share, a further consumer (TECH-1)"} - # P08 (High Resolution Diffraction): surface / interface diffraction, reflectivity, - # and high-resolution diffraction on a six-circle Kohzu diffractometer. Reuses the - # diffraction slug, pending until DESY staff confirm (TECH-1). - - {name: P08_diffraction_practice, method: diffraction, pending: true, note: "high-resolution surface / interface diffraction and reflectivity on the six-circle Kohzu diffractometer + Eiger / Pilatus / Mythen; reuses the diffraction slug, a further consumer (TECH-1)"} - # P21 (Swedish Materials Science): high-energy diffraction (P21.2) + total scattering - # / PDF (P21.1). Reuses the diffraction / total_scattering slugs, pending until DESY - # staff confirm (TECH-1). - - {name: P21_diffraction_practice, method: diffraction, pending: true, note: "high-energy materials-science diffraction on the P21.2 / EH3 endstations; reuses the diffraction slug, a further consumer (TECH-1)"} - - {name: P21_total_scattering_practice, method: total_scattering, pending: true, note: "high-energy total scattering / pair-distribution-function on the P21.1 branch; reuses the total_scattering slug i15-1 / XPD / P02 share, a further consumer (TECH-1)"} - # P22 (HAXPES): hard X-ray photoelectron spectroscopy, sharing the P09 optics chain. - # Reuses the angle_resolved_photoemission slug P04 shares, pending until DESY staff - # confirm (TECH-1). - - {name: P22_haxpes_practice, method: angle_resolved_photoemission, pending: true, note: "hard X-ray photoelectron spectroscopy on the shared P09 optics + the HAXPS electron analyzer; reuses the angle_resolved_photoemission slug P04 shares, a further consumer (TECH-1)"} - # P23 (In-situ X-ray Diffraction): in-situ / operando diffraction and imaging. Reuses - # the diffraction slug, pending until DESY staff confirm (TECH-1). - - {name: P23_diffraction_practice, method: diffraction, pending: true, note: "in-situ / operando X-ray diffraction on the experiment diffractometer; reuses the diffraction slug P07 / P08 / P21 share, a further consumer (TECH-1)"} - # P24 (Chemical Crystallography): single-crystal / small-molecule chemical - # crystallography. Reuses the diffraction slug (no chemical-crystallography Method - # exists), pending until DESY staff confirm (TECH-1). - - {name: P24_chemical_crystallography_practice, method: diffraction, pending: true, note: "single-crystal / small-molecule chemical crystallography on the EH2 diffractometer + area detector; reuses the diffraction slug (no dedicated chemical-crystallography Method exists), a further consumer (TECH-1)"} - # P61 (High Energy Wiggler Beamline): high-energy white-beam / energy-dispersive - # diffraction (P61B) + Large Volume Press high-pressure studies (P61A). Reuses the - # energy_dispersive_diffraction slug, pending until DESY staff confirm (TECH-1). - - {name: P61_energy_dispersive_diffraction_practice, method: energy_dispersive_diffraction, pending: true, note: "high-energy white-beam energy-dispersive diffraction (P61B) and Large Volume Press high-pressure / high-temperature in-situ studies (P61A); reuses the energy_dispersive_diffraction slug, a further consumer (TECH-1, PRESS-1)"} - -# Access BC Actors conceptually facility-wide at PETRA III. Pending until the DESY -# operator and review structure is confirmed. -actors: - - {name: DESY beamline staff, kind: human, pending: true, note: "beamline scientist and operator pool; structure TBD (GOV-1)"} - - {name: DESY safety review, kind: human, pending: true, note: "facility safety review body; membership TBD"} - -# Agent BC Agents seeded at this deployment. None: the CORA system agents are not -# wired for a PETRA III deployment, and this is a modelling exercise. -agents: [] - -# Supply BC: facility-wide continuously-available resources. Pending in this -# reverse-engineered model. -supplies: - - {name: PETRA III photon beam, kind: PhotonBeam, pending: true, note: "PETRA III storage-ring beam, shared across the beamlines (SRC-1)"} - - {name: Cooling water, kind: CoolingWater, pending: true} - - {name: Beamline vacuum, kind: Vacuum, pending: true} - -# Safety BC: facility-issued Clearances. DESY personnel safety (PSS / interlock) is -# carried pending; the permit-leaf signal names are not in the public OnlineXML -# (which carries beamline devices, not the PSS interlock leaves). -clearances: - - {name: DESY personnel safety system, kind: PSS, pending: true, note: "facility safety-form and permit-leaf names not in public source; confirm with DESY staff (PSS-1)"} - -# Caution BC: operator tribal knowledge. None yet for a modelling exercise; -# beamline-level cautions for P01 live on docs/deployments/p01/. -cautions: [] diff --git a/deployments/psi/site.yaml b/deployments/psi/site.yaml deleted file mode 100644 index 5c609ef422c..00000000000 --- a/deployments/psi/site.yaml +++ /dev/null @@ -1,113 +0,0 @@ -# CORA Site descriptor: the PSI site-level surface -# -# The Paul Scherrer Institut (PSI, Villigen, Switzerland) is the fourteenth Site -# CORA models. PSI hosts two photon sources: the Swiss Light Source (SLS / SLS 2.0) -# storage ring and SwissFEL. This Site, like SLAC (the lab hosting LCLS), is the -# institute; SLS and SwissFEL are sources within it, and the beamlines (I-TOMCAT on -# SLS, the Aramis stations Alvra / Bernina / Cristallina on SwissFEL) are -# experimental stations under it. 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. -# -# The Aramis stations are mined from PSI's public controls libraries -# (paulscherrerinstitute/eco for Alvra / Bernina; gitea.psi.ch slic/cristallina for -# Cristallina). The I-TOMCAT (SLS) content is a hybrid modelled from PSI's public -# TOMCAT pages and the SLS 2.0 design reports (the TomoWISE tradition), because no -# public per-beamline controls config exists for TOMCAT. -# -# Status: reverse-engineered, an off-roadmap modelling exercise (not a CORA pilot). -# CORA has not been connected to PSI and no staff have confirmed this model. Every -# value below is carried `pending` until PSI staff confirm it; do not invent facility -# specifics here, carry them as questions on the per-beamline open-questions pages. -# -# Controls house-style: SLS is an EPICS facility ("control of the beamline and -# experiment is fully implemented in EPICS"), with the BEC (Beamline and Experiment -# Control, bec-project) scan/orchestration layer over ophyd for SLS 2.0 (EPICS is the -# floor CORA drives through; BEC is the edge orchestration CORA's edge replaces, the -# I-TOMCAT SEAM-1). SwissFEL is also EPICS, with the eco / slic device libraries and -# the sf-daq per-shot event acquisition (the XFEL acquisition gaps, DAQ-1 / TIMING-1 / -# LASER-1). -# -# Source-of-truth boundary (same as the APS / MAX IV / Diamond / NSLS-II / SLAC / AS sites): -# - the closed facility-kind / actor-kind vocabularies are validated against -# code-mirrored frozensets in scripts/site_descriptor.py. -# - the facility records the bootstrap invariants (kind=Site, display_name equals -# code); `heading` carries the human title used on the rendered page. -# - a non-pending practice method must resolve to a catalog Method; I-TOMCAT runs -# the catalog's tomography-family Methods and the SwissFEL stations run none of -# them (XFEL pump-probe / diffraction), so each practice is carried pending until -# its Method is earned. -# -# Why PSI / the Aramis stations (what they test): Alvra is CORA's SECOND XFEL, after -# SLAC LCLS-MFX. Their value is reinforcement from an INDEPENDENT control stack: -# LCLS-MFX was mined from `pcdshub`, the Aramis stations from `eco` / `slic`. The same -# family-fold finding and the same architectural gaps (per-shot pulse-ID DAQ, -# beam-synchronous timing, fs pump-probe synchronization, one switched source feeding -# co-equal stations) recurring at a second XFEL built by a different team is strong -# evidence the model generalizes beyond one facility's house style, not just beyond -# storage rings. - -facility: - code: psi - display_name: psi - heading: "PSI" - kind: Site - institution: Paul Scherrer Institut (PSI), Switzerland - control_plane: "EPICS (SLS) + eco / slic (SwissFEL)" - beamlines_note: "Two sources under one institute: I-TOMCAT sits on the SLS storage ring, while Alvra, Bernina, and Cristallina are stations sharing the SwissFEL Aramis free-electron-laser source." - beamlines_note: "Two sources under one institute: I-TOMCAT is on the SLS storage ring, while Alvra, Bernina, and Cristallina are co-equal stations sharing the SwissFEL Aramis free-electron-laser source." - beamlines: [I-TOMCAT, Alvra, Bernina, Cristallina] - -# ISA-88 Site Recipes: the facility-adapted form of a catalog Method. I-TOMCAT is a -# tomographic-microscopy beamline on the SLS storage ring, so its practices adapt the -# catalog's tomography-family Methods (the 2-BM / TomoWISE precedent). The SwissFEL -# Aramis stations run none of the catalog's tomography Methods (they are XFEL pump-probe -# / diffraction stations), so every Aramis practice is pending, naming the Method it -# would earn (the pump-probe and serial-crystallography Methods reuse those SLAC -# LCLS-MFX introduced). All pending until PSI staff confirm them. -practices: - - {name: I-TOMCAT_microtomography_practice, method: tomography, pending: true, note: "absorption and propagation-based phase-contrast microtomography on the SLS undulator endstation; reuses the catalog tomography Method (TECH-1)"} - - {name: I-TOMCAT_dynamic_tomography_practice, method: streaming_tomography, pending: true, note: "fast / dynamic 4D tomography via the GigaFRoST continuous-streaming camera; reuses the catalog streaming_tomography Method (TECH-1)"} - - {name: Alvra_pump_probe_practice, method: pump_probe, pending: true, note: "femtosecond optical-laser pump / X-ray probe; needs laser-to-X-ray timing. Reuses the LCLS-MFX pump_probe Method, not yet in the catalog (TECH-1, LASER-1)"} - - {name: Alvra_spectroscopy_practice, method: xas_spectroscopy, pending: true, note: "time-resolved XAS / XES (transient absorption and emission) via the DCM and the von Hamos emission spectrometer. Reuses the LCLS-MFX spectroscopy Method (TECH-1)"} - - {name: Alvra_serial_crystallography_practice, method: serial_crystallography, pending: true, note: "time-resolved serial femtosecond crystallography on the Prime endstation; reuses the LCLS-MFX Method (TECH-1, SAMPLE-1)"} - - {name: Bernina_pump_probe_practice, method: pump_probe, pending: true, note: "femtosecond optical-laser pump / X-ray probe on the diffraction endstation; shares the Alvra / LCLS-MFX pump_probe Method (TECH-1, LASER-1)"} - - {name: Bernina_time_resolved_diffraction_practice, method: diffraction, pending: true, note: "time-resolved hard X-ray diffraction / scattering on the GPS six-circle and XRD kappa diffractometers; a new pending Method, no catalog tomography Method fits an XFEL diffraction platform (TECH-1, DIFF-1)"} - - {name: Cristallina_quantum_materials_diffraction_practice, method: diffraction, pending: true, note: "time-resolved diffraction / scattering on the Cristallina-Q dilution-fridge (DM1) and pulsed-magnet (DM2) diffractometers, in a vector superconducting-magnet sample environment; shares the Bernina diffraction Method (TECH-1, DIFF-1, MAG-1)"} - - {name: Cristallina_serial_crystallography_practice, method: serial_crystallography, pending: true, note: "serial femtosecond crystallography on the Cristallina-MX fast XY sample stage; shares the LCLS-MFX / Alvra Method (TECH-1, SAMPLE-1)"} - -# Access BC Actors conceptually facility-wide at PSI, spanning both the SLS and -# SwissFEL beamlines. Pending until the PSI operator and review structure is confirmed; -# the device libraries expose no human roster. -actors: - - {name: PSI beamline staff, kind: human, pending: true, note: "SLS and SwissFEL beamline-scientist and operator pool; structure TBD (GOV-1)"} - - {name: PSI safety review, kind: human, pending: true, note: "facility safety review body; membership TBD"} - -# Agent BC Agents seeded at this deployment. None: the CORA system agents are not -# wired for a PSI deployment, and the PSI beamlines are modelling exercises. -agents: [] - -# Supply BC: facility-wide continuously-available resources. Pending in design. The two -# sources are distinct supplies: the SLS storage-ring beam (I-TOMCAT) and the SwissFEL -# Aramis FEL beam (the pump-probe stations, shared one at a time, TOPO-1). The FEL beam's -# per-shot, pulse-ID-tagged nature is an acquisition concern recorded on the Aramis open -# questions (DAQ-1), not a supply attribute. -supplies: - - {name: SLS photon beam, kind: PhotonBeam, pending: true, note: "SLS 2.0 storage-ring beam, shared across the SLS beamlines (SRC-1)"} - - {name: SwissFEL photon beam, kind: PhotonBeam, pending: true, note: "SwissFEL Aramis free-electron-laser beam, shared across the Aramis stations (TOPO-1)"} - - {name: Cooling water, kind: CoolingWater, pending: true} - - {name: Beamline vacuum, kind: Vacuum, pending: true} - - {name: Cristallina dilution-fridge liquid helium, kind: LiquidHelium, pending: true, note: "cryogen for the Cristallina-Q dilution refrigerator and vector superconducting magnet (MAG-1)"} - -# Safety BC: facility-issued Clearances. PSI personnel safety (PSS) is carried pending -# for both sources. The SwissFEL pump-probe optical lasers and the Cristallina high-field -# magnet are modelled as Clearance hazards on the experiment, not Assets CORA drives (the -# LCLS-MFX / 32-ID / ID32 precedent, LASER-1 / MAG-1). -clearances: - - {name: PSI personnel safety system, kind: PSS, pending: true, note: "SLS and SwissFEL safety-form and permit-leaf names TBD; confirm with PSI staff (PSS-1)"} - - {name: Alvra pump-probe laser clearance, kind: Clearance, pending: true, note: "class-4 optical pump-probe laser; modelled as a hazard on the experiment, not a driven Asset (LASER-1)"} - - {name: Bernina pump-probe laser clearance, kind: Clearance, pending: true, note: "class-4 optical pump-probe laser on the diffraction endstation; modelled as a hazard, not a driven Asset (LASER-1)"} - - {name: Cristallina high-field magnet clearance, kind: Clearance, pending: true, note: "the Cristallina-Q vector superconducting magnet (to 5.2 T) and its liquid-helium cryogens; modelled as a hazard on the experiment, not a driven Asset for safety (the ID32 9 T magnet precedent, MAG-1)"} - -# Caution BC: operator tribal knowledge. None yet for a modelling exercise. -cautions: [] diff --git a/deployments/sirius/site.yaml b/deployments/sirius/site.yaml deleted file mode 100644 index 1266fe78de4..00000000000 --- a/deployments/sirius/site.yaml +++ /dev/null @@ -1,76 +0,0 @@ -# CORA Site descriptor: the Sirius site-level surface -# -# Sirius is a 3 GeV fourth-generation diffraction-limited storage ring at the -# Brazilian Synchrotron Light Laboratory (LNLS), part of CNPEM, in Campinas, -# Sao Paulo. It is the eighth Site CORA models and its first South American -# facility, home to the MOGNO micro/nanotomography beamline scaffold. -# -# STATUS: MOGNO is an off-roadmap modelling exercise (like the Diamond / NSLS-II / -# APS / SLAC / ESRF reverse-engineered beamlines), built from public Sirius -# facility pages and the published MOGNO papers (Campoi et al. 2025 software -# architecture; Archilha et al. 2022 beamline), not from a live connection or an -# open controls config. Everything below is carried `pending` until Sirius staff -# confirm it; do not invent facility specifics here, carry them as questions on -# the per-beamline open-questions pages (MOGNO, MANACA). -# -# Source-of-truth boundary (same as the other sites): -# - the closed facility-kind / actor-kind vocabularies are validated against -# code-mirrored frozensets in scripts/site_descriptor.py. -# - the facility records the bootstrap invariants (kind=Site, display_name -# equals code); `heading` carries the human title used on the rendered page. -# - a non-pending practice method must resolve to a catalog Method; MOGNO runs -# tomography (a graduated Method) and so carries one tomography practice, -# pending until the beamline enters scope. -# -# The `beamlines` list is the full operating Sirius catalog for context; MOGNO -# (tomography) and MANACA (macromolecular crystallography) are modelled today, each -# with a beamline.yaml. The docs build cross-links a site to the beamlines it -# actually hosts by globbing deployments/*/beamline.yaml, so the un-modelled -# beamlines listed here are catalog placeholders, not broken links. - -facility: - code: sirius - display_name: sirius - heading: "Sirius" - kind: Site - institution: Brazilian Synchrotron Light Laboratory (LNLS), CNPEM - control_plane: "EPICS + MXCuBE3" - beamlines_note: "MOGNO (tomography) and MANACA (MX) are independent beamlines on the Sirius 3 GeV ring; the set is a thin scaffold pending staff confirmation." - beamlines: [Carnauba, Caterete, Cedro, Ema, Imbuia, Ipe, Manaca, Mogno, Paineira, Quati, Sabia, Sapucaia] - -# ISA-88 Site Recipes: the facility-adapted form of a catalog Method. MOGNO runs -# tomography, which is already in CORA's catalog, so its practice resolves to the -# tomography Method and renders linked; it is carried pending until the beamline -# enters pilot scope. MANACA runs macromolecular crystallography, reusing the -# pending i03 MX Methods (mx_data_collection / grid_scan / sample_exchange), none -# yet in the catalog. The other operating beamlines coin no practice until they -# are modelled. -practices: - - {name: Mogno_tomography_practice, method: tomography, pending: true, note: "micro and nanotomography (phase-contrast, time-resolved 4D); reverse-engineered from the Sirius facility page and the MOGNO papers (TECH-1)"} - - {name: Manaca_mx_data_collection_practice, method: mx_data_collection, pending: true, note: "rotation / oscillation MX data collection on the goniometer + the area detector; reuses the i03 Method, not yet in the catalog (TECH-1)"} - - {name: Manaca_grid_scan_practice, method: grid_scan, pending: true, note: "fast grid scan for sample location / centring (TECH-1)"} - - {name: Manaca_sample_exchange_practice, method: sample_exchange, pending: true, note: "automated 48-pin sample-changer load / centre / collect / unmount loop; a Procedure over the spine + a Subject custody thread (ROBOT-1)"} - -# Access BC Actors conceptually facility-wide at Sirius. Pending until the LNLS -# operator and review structure is confirmed. -actors: - - {name: Sirius beamline staff, kind: human, pending: true, note: "beamline scientist and operator pool; structure TBD"} - - {name: Sirius safety review, kind: human, pending: true, note: "facility safety review body; membership TBD"} - -# Agent BC Agents seeded at this deployment. None: the CORA system agents are not -# wired for a Sirius deployment, and MOGNO is a modelling exercise. -agents: [] - -# Supply BC: facility-wide continuously-available resources. Pending in design. -supplies: - - {name: Storage-ring beam current, kind: PhotonBeam, pending: true, note: "Sirius 3 GeV storage-ring beam, shared across the beamlines"} - - {name: Cooling water, kind: CoolingWater, pending: true} - - {name: Beamline vacuum, kind: Vacuum, pending: true} - -# Safety BC: facility-issued Clearances. The Sirius personnel-safety system is -# carried pending; the permit-leaf names are not public. -clearances: - - {name: Sirius personnel safety system, kind: PSS, pending: true, note: "facility safety-form names TBD; confirm with Sirius staff (PSS-1)"} - -# Caution BC: operator tribal knowledge. None yet for a modelling exercise. -cautions: [] diff --git a/deployments/six/beamline.yaml b/deployments/six/beamline.yaml deleted file mode 100644 index ec33937f276..00000000000 --- a/deployments/six/beamline.yaml +++ /dev/null @@ -1,328 +0,0 @@ -# SIX beamline descriptor (NSLS-II), reverse-engineered -# -# SIX (Soft Inelastic X-ray scattering) is the NSLS-II resonant inelastic X-ray -# scattering (RIXS) beamline at sector 2-ID. It is bound to the NSLS-II Site -# (deployments/nsls2/site.yaml), the fourth NSLS-II beamline after FXI, HXN, and -# BMM, and CORA's FIRST soft X-ray deployment. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the bluesky profile collection NSLS2/six-profile-collection) or inferred, -# carried `new: true` + `confirm: true` pending SIX staff. EPICS PVs are real and -# verified against the profile collection startup files; vendor part numbers, -# serials, and physical positions are not in it and are open questions. Same -# descriptor mode as FXI / HXN / BMM; this scaffold is descriptor + docs, scenarios -# deferred. -# -# SIX is CORA's first SOFT X-RAY beamline, a new optics + detector + sample- -# environment regime that the all-hard-X-ray fleet has never modelled: -# - the monochromator is a plane-GRATING monochromator (PGM), not a crystal DCM: -# it disperses with an interchangeable grating (500 / 1200 / 1800 l/mm) and a -# premirror at a fixed-focus c-value (cff), and the exit slit sets resolution. -# - the signature instrument is a meters-long energy-dispersive RIXS SPECTROMETER -# arm (a bridge truss + an in-arm optics chamber + a detector chamber) that -# swings to a scattering angle and disperses the emitted soft X-rays onto a -# photon-counting camera. -# - the sample sits on a UHV cryostat MANIPULATOR (x/y/z/theta). -# None of these fit a hard X-ray catalog Family. Three have since GRADUATED into the -# catalog: GratingMonochromator (CSX, NSLS-II 23-ID, earned the soft X-ray PGM), -# Manipulator (ESM, NSLS-II 21-ID, earned the UHV sample manipulator), and -# SpectrometerArm (the dispersive arm SIX coined, earned across SIX + ESRF ID32 RIXS/XES -# + ESRF ID28), so the Monochromator, SampleManipulator, and RIXSSpectrometer below all -# bind catalog Families. Everything else reuses an existing catalog Family. -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/six/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "soft X-ray resonant inelastic scattering (RIXS), 2-ID; CORA's first soft X-ray beamline, modelled from public beamline config" - name: SIX - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "Sector 2" # PV namespace XF:02ID* - tier: Unit - parent: null - source: insertion-device - source_confirm: "2-ID elliptically-polarizing undulator (EPU) on SR:C02-ID:G1A{EPU:1}; gap + phase (polarization) axes; whether SIX shares a canted straight with a sibling beamline is TOPO-1, the EPU type/period is SRC-1" - page_layout: stages - shape: "CORA's first soft X-ray beamline: a grating monochromator, a meters-long RIXS spectrometer arm, and a UHV cryostat manipulator, three device classes new to the catalog." - source_ref: - label: "NSLS2/six-profile-collection" - url: "https://github.com/NSLS2/six-profile-collection" -# PV zones along the beamline: XF:02IDA (front-end optics), XF:02IDB (the PGM), -# XF:02IDC (refocusing optics + exit slit), XF:02IDD-ES / XF:02ID1-ES (the RIXS -# endstation). Whether these are four separate shielded hutches or beam zones -# within fewer hutches, and the PSS permit leaves, are open (ENC-1, PSS-1). -enclosures: - - name: 2-ID-A - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf not in source; front-end and photon shutters are XF:02ID-PPS{Sh:FE} and XF:02IDA-PPS{PSh} (PSS-1)"} - - name: 2-ID-B - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; photon shutter XF:02IDB-PPS{PSh} (PSS-1, ENC-1)"} - - name: 2-ID-C - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; whether A/B/C are one optics hutch or several is ENC-1"} - - name: 2-ID-D - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; the RIXS endstation hutch (ENC-1)"} - -# =========================================================================== -# SOURCE STAGE: the EPU, the front-end optics, the PGM, and the refocusing optics -# =========================================================================== - -insertion-devices: - stage: source - enclosure: 2-ID-A - intro: "The elliptically-polarizing undulator source on the SR:C02-ID straight." - note: "One InsertionDevice Asset; the EPU adds a phase (polarization) axis beyond gap, carried as a setting (SRC-1). Whether the straight is canted with a sibling beamline is TOPO-1." - devices: - - name: Undulator - family: InsertionDevice - pv: "SR:C02-ID:G1A{EPU:1}" - new: true - confirm: true - note: "elliptically-polarizing undulator (gap + phase); type and period are SRC-1, the polarization-phase DOF is carried as a setting not a separate Family" - -optics: - stage: source - enclosure: 2-ID-A - intro: "The first mirror, the front-end slit, the polarization diagnostic, and the front-end / photon shutters." - note: "M1 is the first horizontal-deflecting mirror; diagon is the soft X-ray polarization diagnostic (DIAG-1)." - devices: - - name: Mirror_1 - family: Mirror - pv: "XF:02IDA-OP{Mir:1-Ax:4" - new: true - confirm: true - note: "first mirror M1; coatings and axis roles are OPT-1" - - name: FrontEndSlit - family: Slit - pv: "XF:02IDA-OP{Mir:1-Slt:4_D_1" - new: true - confirm: true - note: "front-end baffle slit downstream of M1 (OPT-2)" - - name: PolarizationDiagnostic - family: GenericProbe - pv: "XF:02IDA-OP{Diag:1-Ax:3" - new: true - confirm: true - note: "DIAGON soft X-ray polarization diagnostic; classification a placeholder (DIAG-1)" - - name: FrontEndShutter - family: Shutter - pv: "XF:02ID-PPS{Sh:FE}" - new: true - confirm: true - note: "front-end safety shutter, PPS-gated" - - name: PhotonShutter_A - family: Shutter - pv: "XF:02IDA-PPS{PSh}" - new: true - confirm: true - note: "2-ID-A photon shutter" - -monochromator: - stage: source - enclosure: 2-ID-B - intro: "The plane-grating monochromator that selects the soft X-ray energy, and its slits." - note: > - pgm is the plane-grating monochromator (PGM): a premirror at a fixed-focus - c-value (cff) plus an interchangeable grating (500 / 1200 / 1800 l/mm) set the - energy. It binds the catalog GratingMonochromator Family (graduated across SIX + - CSX), not the Monochromator Family (which is a crystal/multilayer Bragg DCM): a - grating mono has no Bragg crystal and its resolution is set by the exit slit - (MONO-1, see model.md). - devices: - - name: Monochromator - family: GratingMonochromator # catalog Family (graduated SIX + CSX; soft X-ray PGM, not a crystal DCM) - pv: { energy: "XF:02IDB-OP{Mono:1-Ax:9_Eng}Mtr", cff: "XF:02IDB-OP{Mono:1-Ax:9_Cff}Mtr", grating_pitch: "XF:02IDB-OP{Mono:1-Ax:9_GP}Mtr", premirror_pitch: "XF:02IDB-OP{Mono:1-Ax:9_MP}Mtr", grating_translation: "XF:02IDB-OP{Mono:1-Ax:9_GT}Trans:Mtr" } - new: true - confirm: true - note: "plane-grating monochromator; three gratings 500/1200/1800 l/mm, energy range is MONO-1" - - name: MonoSlit_Upstream - family: Slit - pv: "XF:02IDB-OP{Mono:1-Slt:8_U_1" - new: true - confirm: true - note: "upstream PGM baffle slit (OPT-2)" - - name: MonoSlit_Downstream - family: Slit - pv: "XF:02IDB-OP{Mono:1-Slt:9_D_1" - new: true - confirm: true - note: "downstream PGM baffle slit (OPT-2)" - - name: PhotonShutter_B - family: Shutter - pv: "XF:02IDB-PPS{PSh}" - new: true - confirm: true - note: "2-ID-B photon shutter" - -refocusing: - stage: source - enclosure: 2-ID-C - intro: "The refocusing mirrors, their slits, and the exit slit that sets the energy resolution." - note: "M3 and M4 are hexapod-mounted refocusing mirrors; extslt is the exit slit, the PGM resolution-defining element (OPT-1, OPT-2)." - devices: - - name: Mirror_3 - family: Mirror - pv: "XF:02IDC-OP{Mir:3-Ax:13" - new: true - confirm: true - note: "hexapod-mounted refocusing mirror M3 (OPT-1)" - - name: Mirror_4 - family: Mirror - pv: "XF:02IDC-OP{Mir:4-Ax:18" - new: true - confirm: true - note: "hexapod-mounted refocusing mirror M4 (OPT-1)" - - name: MirrorSlit_3 - family: Slit - pv: "XF:02IDC-OP{Mir:3-Slt:12_U_1" - new: true - confirm: true - note: "M3 baffle slit (OPT-2)" - - name: MirrorSlit_4 - family: Slit - pv: "XF:02IDC-OP{Mir:4-Slt:18_U_1" - new: true - confirm: true - note: "M4 baffle slit (OPT-2)" - - name: ExitSlit - family: Slit - pv: "XF:02IDC-OP{Slt:1-Ax:15" - new: true - confirm: true - note: "exit slit; sets the PGM energy resolution (OPT-2)" - -# =========================================================================== -# SAMPLE STAGE: the UHV cryostat manipulator and the endstation mirrors -# =========================================================================== - -rixs-sample: - stage: sample - enclosure: 2-ID-D - intro: "The UHV cryostat sample manipulator, the sample chamber, the endstation mirrors, and the sample temperature controller." - note: > - cryo is the UHV cryostat sample manipulator (x/y/z/theta), bound to the catalog - Manipulator Family (graduated across SIX + ESM; the UHV serial-stack sample - manipulator role, SAMPLE-1). M5 and M6 are the endstation mirrors; the optics-wheel - theta sits on M5 (OPT-1). - devices: - - name: SampleManipulator - family: Manipulator # catalog Family (graduated SIX + ESM; UHV cryostat manipulator) - pv: { x: "XF:02IDD-ES{SC:1-Cryo:S1_B-Ax:X}Mtr", y: "XF:02IDD-ES{SC:1-Cryo:S1_B-Ax:Y}Mtr", z: "XF:02IDD-ES{SC:1-Cryo:S1_B-Ax:Z}Mtr", theta: "XF:02IDD-ES{SC:1-Cryo:S1_B-Ax:T}Mtr" } - new: true - confirm: true - note: "UHV cryostat sample manipulator; cryo temperature range and load-lock are SAMPLE-1" - - name: SampleChamber - family: LinearStage - pv: { x: "XF:02IDD-ES{SC:Pvt-Ax:X}Mtr", z: "XF:02IDD-ES{SC:Pvt-Ax:Z}Mtr" } - new: true - confirm: true - note: "sample chamber pivot translation; the spectrometer arm swings about it (RIXS-1)" - - name: Mirror_5 - family: Mirror - pv: "XF:02IDD-ES{Mir:5}Pos:" - new: true - confirm: true - note: "endstation mirror M5; carries the optics-wheel theta (OPT-1)" - - name: Mirror_6 - family: Mirror - pv: "XF:02IDD-ES{Mir:6-Ax:" - new: true - confirm: true - note: "endstation mirror M6 (OPT-1)" - - name: MirrorMask_5 - family: Aperture - pv: "XF:02IDD-ES{Msk:Mir5-Ax:Y}Mtr" - new: true - confirm: true - note: "single-axis mask at M5 (OPT-2)" - - name: SampleTemperature - family: TemperatureController - pv: "XF:02IDD-ES{TCtrl:1" - new: true - confirm: true - note: "Lakeshore 336 sample temperature controller (reuses the graduated Family; SAMPLE-1)" - -# =========================================================================== -# DETECTION STAGE: the RIXS spectrometer arm, its camera, and the counters -# =========================================================================== - -rixs-spectrometer: - stage: detection - enclosure: 2-ID-D - intro: "The energy-dispersive RIXS spectrometer arm, the photon-counting camera at its end, and the counting electronics." - note: > - The RIXS spectrometer is a meters-long energy-dispersive arm modelled as one - SpectrometerArm Asset, binding the catalog SpectrometerArm Family (a dispersive - positioning arm presenting the Positioner Role; the catalog - EnergyDispersiveSpectrometer presents a point Sensor Role, not this). It is three - coupled chambers: the bridge truss (br), the in-arm - optics chamber (oc) that disperses, and the detector chamber (dc). The camera is - a photon-counting / centroiding RIXSCam; whether that warrants its own Family or - binds the catalog Camera with settings is RIXS-2 (modelled as Camera here). - devices: - - name: RIXSSpectrometer - family: SpectrometerArm # catalog Family (graduated; multi-chamber energy-dispersive RIXS arm) - pv: { bridge_pitch: "XF:02IDD-ES{BT:1-Ax:Pch}Mtr", bridge_roll: "XF:02IDD-ES{BT:1-Ax:Roll}Mtr", bridge_y: "XF:02IDD-ES{BT:1-Ax:Y}Mtr", optics_two_theta: "XF:02IDD-ES{3AA:1-Ax:2T}Mtr", optics_roll: "XF:02IDD-ES{3AA:1-Ax:Roll}Mtr", detector_two_theta: "XF:02IDD-ES{DC:1-Ax:2T}Mtr", detector_z: "XF:02IDD-ES{DC:1-Ax:Z}Mtr" } - new: true - confirm: true - note: "energy-dispersive RIXS arm; bridge truss (BT:1) + optics chamber (3AA:1) + detector chamber (DC:1); full chamber geometry is RIXS-1" - - name: RIXSCamera - family: Camera - pv: "XF:02ID1-ES{RIXSCam}:" - new: true - confirm: true - note: "photon-counting RIXS camera with on-detector centroiding (XIPPlugin) and isolinear curvature correction; Camera-vs-photon-counting-Family is RIXS-2 (DET-1)" - - name: DetectorSlit - family: Slit - pv: "XF:02IDD-ES{DC:1-Slt:1" - new: true - confirm: true - note: "detector-chamber baffle slit (OPT-2)" - - name: Scaler - family: FluxMonitor - pv: "XF:02ID1-ES:1{Sclr:1}scaler1" - new: true - confirm: true - note: "counting scaler for the I0 / drain-current channels (DET-1)" - - name: Electrometer - family: FluxMonitor - pv: "XF:02ID1-ES{GPIO:1_" - new: true - confirm: true - note: "Femto transimpedance electrometer (DET-1)" - -# Cross-cutting control. SIX runs EPICS (the floor); CORA observes and, where it -# replaces bluesky-style orchestration, conducts over it. The handles above were -# read from the six-profile-collection startup files and carried confirm (CTRL-1). -controls: - intro: > - SIX runs on the NSLS-II EPICS / ophyd control stack, the same floor as FXI, - HXN, and BMM. The device handles above are bound from the beamline's bluesky - profile collection (NSLS2/six-profile-collection), carried confirm pending staff - verification (CTRL-1). The RIXS acquisition (energy moves, the alignment scans, - the spectrometer geometry moves) runs through bluesky plans and the queue server - (41-custom-plans.py, 43-alignment_scans.py, 97-standard-plans.py); that - orchestration is the seam CORA's edge replaces, driving through ophyd/EPICS, - while the RIXSCam HDF5 file-writing to the NSLS-II filestore is plumbing CORA - observes, not data it owns (see model.md). - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a SIX run needs. The PGM, the - spectrometer arm, and the sample chamber are under UHV; the cryostat manipulator - draws on cryogens (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the optics, the RIXS spectrometer arm, and the sample chamber are UHV (SUP-1)" diff --git a/deployments/slac/site.yaml b/deployments/slac/site.yaml deleted file mode 100644 index 0d7392a2907..00000000000 --- a/deployments/slac/site.yaml +++ /dev/null @@ -1,69 +0,0 @@ -# CORA Site descriptor: the SLAC site-level surface -# -# SLAC National Accelerator Laboratory (Menlo Park, USA) is the fifth Site CORA -# models, and the home of the LCLS / LCLS-II X-ray free-electron laser. This file -# is the single human-readable source for the facility's site-level instances: the -# Facility itself, the Practices it runs, and the facility principals. -# -# Status: LCLS-MFX is an off-roadmap modelling exercise (like the Diamond and FXI -# beamlines), reverse-engineered from SLAC's open `pcdshub` controls stack. It is -# the first XFEL CORA models, chosen to test whether the model generalizes beyond -# the storage-ring acquisition paradigm. Everything below is carried `pending` -# until LCLS staff confirm it; do not invent facility specifics here, carry them -# as questions on the LCLS-MFX open-questions page. -# -# Source-of-truth boundary (same as the APS site): -# - the closed facility-kind / actor-kind vocabularies are validated against -# code-mirrored frozensets in scripts/site_descriptor.py. -# - the facility records the bootstrap invariants (kind=Site, display_name -# equals code); `heading` carries the human title used on the rendered page. -# - a non-pending practice method must resolve to a catalog Method; LCLS runs -# none of the catalog's tomography methods, so each practice is carried -# pending until its Method is earned (registered in the methods-axis guard). - -facility: - code: slac - display_name: slac - heading: "SLAC" - kind: Site - institution: SLAC National Accelerator Laboratory - control_plane: "EPICS / pcdshub" - beamlines: [LCLS-MFX] - -# ISA-88 Site Recipes: the facility-adapted form of a catalog Method. None of -# CORA's catalog Methods (all tomography-family today) fit an XFEL, so every LCLS -# practice is pending, naming the Method it would earn. Confirm with LCLS staff. -practices: - - {name: MFX_serial_crystallography_practice, method: serial_crystallography, pending: true, note: "serial femtosecond crystallography (fixed-target + liquid-jet sample delivery)"} - - {name: MFX_pump_probe_practice, method: pump_probe, pending: true, note: "femtosecond optical-laser pump / X-ray probe; needs laser-to-X-ray timing"} - - {name: MFX_spectroscopy_practice, method: xas_spectroscopy, pending: true, note: "XAS / XES via the von Hamos emission spectrometer"} - -# Access BC Actors conceptually facility-wide at SLAC. Pending until the LCLS -# operator and review structure is confirmed. -actors: - - {name: LCLS beamline staff, kind: human, pending: true, note: "instrument scientist and operator pool; structure TBD"} - - {name: LCLS safety review, kind: human, pending: true, note: "facility safety review body; membership TBD"} - -# Agent BC Agents seeded at this deployment. None: the CORA system agents are not -# wired for an LCLS deployment, and LCLS-MFX is a modelling exercise. -agents: [] - -# Supply BC: facility-wide continuously-available resources. Pending in design. -# The FEL beam is carried as a PhotonBeam supply (as at MAX IV); its per-shot, -# pulse-ID-tagged nature is an acquisition concern, recorded on the LCLS-MFX -# open questions (DAQ-1), not a supply attribute. -supplies: - - {name: FEL photon beam, kind: PhotonBeam, pending: true, note: "LCLS / LCLS-II free-electron-laser beam, shared across all instruments (TOPO-1)"} - - {name: Cooling water, kind: CoolingWater, pending: true} - - {name: Beamline vacuum, kind: Vacuum, pending: true} - -# Safety BC: facility-issued Clearances. LCLS personnel safety (PPS) and the -# pump-probe optical-laser safety (BTPS-governed) are both carried pending; the -# pump-probe laser is modelled as a Clearance hazard, not an Asset CORA drives -# (the 32-ID AM-laser precedent, LASER-1). -clearances: - - {name: LCLS personnel protection system, kind: PSS, pending: true, note: "facility safety-form names TBD; confirm with LCLS staff (PSS-1)"} - - {name: MFX pump-probe laser clearance, kind: Clearance, pending: true, note: "class-4 optical laser, BTPS-governed; modelled as a hazard on the experiment, not a driven Asset (LASER-1)"} - -# Caution BC: operator tribal knowledge. None yet for a modelling exercise. -cautions: [] diff --git a/deployments/smi/beamline.yaml b/deployments/smi/beamline.yaml deleted file mode 100644 index ea994dd4bd1..00000000000 --- a/deployments/smi/beamline.yaml +++ /dev/null @@ -1,258 +0,0 @@ -# SMI beamline descriptor (NSLS-II), reverse-engineered -# -# SMI (Soft Matter Interfaces) is the NSLS-II scattering beamline at sector 12-ID. -# Its defining techniques are small- and wide-angle X-ray scattering (SAXS / WAXS), -# run simultaneously, and grazing-incidence scattering (GISAXS / GIWAXS) off films -# and interfaces, with a strong in-situ soft-matter sample environment. It is bound -# to the NSLS-II Site (deployments/nsls2/site.yaml), the tenth NSLS-II beamline after -# FXI, HXN, BMM, SRX, SIX, CHX, CSX, XPD, and ESM. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the bluesky profile collection NSLS2/smi-profile-collection) or inferred, -# carried `confirm: true` pending SMI staff. EPICS PVs are real and verified against -# the smibase/ device modules; vendor part numbers, serials, and physical positions -# are not in it and are open questions. Same descriptor mode as the other NSLS-II -# beamlines; this scaffold is descriptor + docs, scenarios deferred. -# -# SMI is the SCATTERING reinforcement: the NSLS-II twin of the Diamond i22 (SAXS / -# WAXS) beamline, the second facility for that science axis, and it adds the -# grazing-incidence geometry (GISAXS / GIWAXS) and the in-situ soft-matter cells that -# are SMI's specialty. It introduces NO new catalog family: the Pilatus area -# detectors reuse Camera, the TetrAMM flux monitor FluxMonitor (#353), the Linkam / -# LakeShore stages TemperatureController (#350), the Amptek fluorescence MCA -# EnergyDispersiveSpectrometer (#345), the beamstops BeamStop, the mirrors Mirror, -# the DCM Monochromator, and the compound-refractive-lens Transfocator (now a -# graduated CRL focusing-optic Family, bound at 4-ID / 8-ID / 9-ID / i22 / CHX too; -# the residual lens material / count fact is CRL-1). One loose family is still bound: -# the PositionMonitor (4-ID / 8-ID / 9-ID; DIAG-1). Per the -# i22 precedent the SAXS / WAXS / GISAXS Capabilities are NOT coined here; they are -# the deferred owner-scope cohort (TECH-1), simultaneous SAXS+WAXS is coordinated -# Runs not a new technique, and the in-situ cells are deferred (INSITU-1). - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "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" - name: SMI - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "Sector 12" # PV namespace XF:12ID* - tier: Unit - parent: null - source: insertion-device - source_confirm: "in-vacuum undulator (SR:C12-ID:G1{IVU:1}), verified in source (the energy pseudopositioner drives its gap); period and range not fully in the profile collection (SRC-1)" - page_layout: stages - shape: "The NSLS-II twin of Diamond I22 scattering, adding grazing-incidence geometry and in-situ soft-matter cells: two area detectors read at once, the detector distance setting Q." - source_ref: - label: "NSLS2/smi-profile-collection" - url: "https://github.com/NSLS2/smi-profile-collection" -enclosures: - # PV zones: 12IDA first-optics hutch (FOE: mirrors, white-beam slit, FOE mono - # slits), 12IDB / 12IDB1 secondary-source and diagnostics, 12IDC the experiment - # hutch (CRL + sample optics XF:12IDC-OP, end-station XF:12IDC-ES, vacuum -VA). - # Modelled as the optics hutch + the experiment hutch. - - name: 12-ID-A - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS search-and-secure permit leaf not in source; the front-end photon shutter is XF:12IDA-PPS:2{PSh} (PSS-1)"} - - name: 12-ID-C - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; 12-ID-C is the experiment hutch carrying the sample, the in-vacuum flight path, and the SAXS / WAXS detectors (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the undulator and front-end photon shutter -# =========================================================================== - -source: - stage: source - enclosure: 12-ID-A - intro: The in-vacuum undulator source and the front-end photon shutter. - devices: - - name: Source - family: InsertionDevice - pv: "SR:C12-ID:G1{IVU:1}" - confirm: true - note: "In-vacuum undulator (the ivugap motor SR:C12-ID:G1{IVU:1-Ax:Gap}-Mtr, with brake and gap-speed controls). Driven together with the monochromator by the coupled energy pseudopositioner. Period and range pending (SRC-1)." - - name: PhotonShutter - family: Shutter - pv: "XF:12IDA-PPS:2{PSh}" - confirm: true - note: "Front-end photon shutter (ph_shutter, TwoButtonShutter)." - -# =========================================================================== -# OPTICS STAGE: the monochromator, focusing mirrors, CRL, slits, attenuators -# =========================================================================== - -optics: - stage: source - enclosure: 12-ID-A - intro: "Condition the beam and set its energy: the double-crystal monochromator, the horizontal and vertical focusing mirrors, the compound-refractive-lens transfocator, the white-beam and secondary-source slits, and the attenuator banks. PVs verified against smibase/energy.py, mirrors.py, crls.py, slits.py, attenuators.py." - devices: - - name: Monochromator - family: Monochromator - pv: "XF:12ID:m65" - confirm: true - note: "Double-crystal monochromator (Bragg = m65, gap = m66, with theta m65 / height m66 / pitch m67 / roll m68 on the bare XF:12ID: motor records). The energy math uses a Si(111) crystal (D_Si111 = 3.1293 in source). Driven by the coupled energy pseudopositioner together with the undulator gap; the EnergyAxis below is the master energy. Full energy range pending (DCM-1)." - - name: HorizontalFocusingMirror - family: Mirror - pv: "XF:12IDA-OP:2{Mir:HF-Ax:" - confirm: true - note: "Horizontal focusing mirror (hfm, with a bimorph voltage controller); reuses the Mirror family. A vertical-deflecting mirror (vdm, Mir:VD) sits alongside the focusing pair." - - name: VerticalFocusingMirror - family: Mirror - pv: "XF:12IDA-OP:2{Mir:VF-Ax:" - confirm: true - note: "Vertical focusing mirror (vfm, with a bimorph voltage controller); reuses the Mirror family." - - name: Transfocator - family: Transfocator - pv: "XF:12IDC-OP:2{Lens:CRL-Ax:" - confirm: true - note: "Compound-refractive-lens transfocator (crl, twelve individually-insertable lens elements L1-L12 plus x / y / z / pitch / theta alignment) for micro-focusing versus low-divergence modes; a DSA aperture shares its controller. Reuses the graduated Transfocator catalog Family (a CRL focusing optic, bound at 4-ID / 8-ID / 9-ID / i22 / CHX too). Lens material and count pending (CRL-1)." - - name: WhiteBeamSlit - family: Slit - pv: "XF:12IDA-OP:2{Slt:WB-Ax:" - confirm: true - note: "White-beam-defining slit (wbs); FOE mono slits (hfmslit Slt:H, vfmslit Slt:V) shape the beam onto the mirrors." - - name: SecondarySourceAperture - family: Slit - pv: "XF:12IDB1-OP:2{Slt:SSA-Ax:" - confirm: true - note: "Secondary-source aperture (ssa) defining the coherence-matched source; its slit current is read for diagnostics." - - name: Attenuators - family: Filter - pv: "XF:12IDC-OP:2{Fltr:1-" - confirm: true - note: "Two attenuator banks of twelve insertable foils each (att1_1-12 at Fltr:1, att2_1-12 at Fltr:2) trimming flux; foil materials (Cu / Sn / Mo / Al, in 1x-8x thicknesses) are catalogued in beam.py. Reuses the Filter family." - - name: EnergyAxis - family: PseudoAxis - confirm: true - note: "The master energy axis: a coupled pseudopositioner moving the undulator gap, the DCM Bragg angle, and the DCM gap together (with a built-in energy-to-gap polynomial and DCM pitch / roll feedback toggled around shutter moves). Working gap range about 6200-15100. Whether energy is scanned as a measurement is ENERGY-1." - - name: BeamPositionMonitor - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1) - pv: "XF:12IDA-BI:2{EM:BPM1}" - confirm: true - note: "Beam-position monitors (xbpm1 / xbpm2 in the FOE, xbpm3 at the secondary source XF:12IDB-BI:2{EM:BPM3}, the latter feeding the DCM pitch / roll feedback). Binds the graduated PositionMonitor Family (a consumer alongside 4-ID / 8-ID / 9-ID; DIAG-1), matching the catalog note that position monitors stay loose." - -# =========================================================================== -# SAMPLE STAGE: the grazing-incidence sample stack and the in-situ environment -# =========================================================================== - -sample: - stage: sample - enclosure: 12-ID-C - intro: "The sample stack with grazing-incidence axes for GISAXS, and the sample-environment thermal control. PVs verified against smibase/manipulators.py and linkam.py." - note: > - SMI positions a film or interface in the beam at a grazing angle for GISAXS / - GIWAXS, or a bulk sample in transmission for SAXS / WAXS. The experiment-hutch - beam-defining slits condition the beam onto the sample just upstream of it. The - HUB sample stack carries the theta / phi / chi grazing-incidence axes alongside - x / y / z; a SmarAct piezo (XF:12ID2C-ES{MCS:2}) gives fine motion. The Linkam - thermal stage reuses the TemperatureController family. The in-situ soft-matter - cells (a humidity cell and a blade coater) are SMI specialties, deferred (INSITU-1). - devices: - - name: BeamDefiningSlit - family: Slit - pv: "XF:12IDC-OP:2{Slt:C-Ax:" - confirm: true - note: "Experiment-hutch beam-defining slit (cslit, the C-hutch slit) trimming the beam onto the sample; reuses the Slit family." - - name: GuardSlit - family: Slit - pv: "XF:12IDC-OP:2{Slt:E-Ax:" - confirm: true - note: "Experiment-hutch guard slit (eslit, the E slit) cleaning up parasitic scatter ahead of the sample; reuses the Slit family." - - name: SampleStage - family: LinearStage - pv: "XF:12IDC-OP:2{HUB:Stg-Ax:" - confirm: true - note: "HUB sample stack (stage; x / y / z plus theta / phi / chi for grazing incidence), with a SmarAct piezo for fine motion (XF:12ID2C-ES{MCS:2-Ax:}). Bound to LinearStage as a design-phase placeholder; whether the grazing-incidence orientation axes are modelled as a Goniometer plus an Assembly is folded into STAGE-1." - - name: SampleTemperature - family: TemperatureController - pv: "XF:12ID-ES{LINKAM}:" - confirm: true - note: "Linkam thermal stage (LThermal) with a tensile variant (LTensile); a LakeShore four-output controller (XF:12ID-ES{Env:01}) also serves. Reuses the TemperatureController family (graduated #350). Which units are live is TEMP-1." - -# =========================================================================== -# DETECTION STAGE: the SAXS and WAXS area detectors, beamstops, flux, fluorescence -# =========================================================================== - -detector: - stage: detection - enclosure: 12-ID-C - intro: "The simultaneous SAXS and WAXS Pilatus area detectors, the SAXS camera-length stage and beamstops, the flux monitor, the fluorescence detector, and the beam-viewing cameras. PVs verified against smibase/pilatus.py, beamstop.py, electrometers.py, amptek.py, prosilica.py." - note: > - SMI's measurement is the scattering pattern on two Pilatus detectors read at - once: the SAXS 2M down the in-vacuum flight path and the WAXS 900KW on a swing - arc. For GISAXS the WAXS arc is swung out; the detector stage sets the SAXS camera - length (the accessible Q). All reuse existing families. Which detectors are live - versus the retired set (a 1M, a 300KW) is a staff question (DET-1). - devices: - - name: SAXSDetector - family: Camera - pv: "XF:12ID2-ES{Pilatus:Det-2M}" - confirm: true - note: "Pilatus 2M SAXS area detector (pil2M) down the in-vacuum flight path; reuses Camera. Note the odd XF:12ID2-ES IOC namespace." - - name: WAXSDetector - family: Camera - pv: "XF:12IDC-ES:2{Det:900KW}" - confirm: true - note: "Pilatus 900KW WAXS area detector (pil900KW) on a swing arc (XF:12IDC-ES:2{WAXS:1-Ax:Arc}), read simultaneously with the SAXS detector; swung out for GISAXS, to zero for GIWAXS. Reuses Camera." - - name: SAXSDetectorStage - family: LinearStage - pv: "XF:12IDC-ES:2{Det:1M-Ax:" - confirm: true - note: "SAXS detector translation (x / y / z; the Z sets the sample-to-detector camera length and hence the accessible Q). Reuses the legacy Det:1M motor namespace from the retired 1M detector. Reuses LinearStage." - - name: SAXSBeamStop - family: BeamStop - pv: "XF:12IDC-ES:2{BS:SAXS-Ax:" - confirm: true - note: "SAXS beamstop assembly (saxs_bs; rod and pin-diode beamstops IBB / IBM / OBB / OBM) blocking the direct beam. The WAXS detector has its own beamstop motor (XF:12ID2C-ES{MCS:2-Ax:1}Mtr). Reuses BeamStop." - - name: FluxMonitor - family: FluxMonitor - pv: "XF:12ID:2{EM:Tetr1}" - confirm: true - note: "TetrAMM pin-diode flux monitor (pin_diode, QuadEM) reading incident intensity for normalization; reuses FluxMonitor (graduated #353). Channel map pending (DIAG-1)." - - name: FluorescenceSpectrometer - family: EnergyDispersiveSpectrometer - pv: "XF:12IDC-ES:2{Det-Amptek:1}" - confirm: true - note: "Amptek energy-dispersive fluorescence MCA (amptek) for element-sensitive work; reuses EnergyDispersiveSpectrometer (graduated #345)." - - name: BeamViewingCamera - family: Camera - pv: "XF:12IDC-BI{Cam:SAM}" - confirm: true - note: "On-axis sample-viewing camera (OAV, a Prosilica; a HEX top camera XF:12IDC-BI{Cam:HEX} and FOE diagnostic cameras FS / WBStop / VFM serve alignment). Reuses Camera. Live set pending (CAM-1)." - -# =========================================================================== -# Cross-cutting controls -# =========================================================================== - -controls: - intro: > - SMI acquisition is gated by the endstation fast shutter; the Pilatus detectors - run in software-triggered modes, with no separate hardware timing box in the - profile collection. Controller box models / firmware are not fully in the profile - collection (DRIVE-1). - triggering: - - name: FastShutter - family: Shutter - pv: "XF:12IDC-ES:2{PSh:ES}" - confirm: true - note: "Endstation fast shutter (fs, SMIFastShutter; a piezo open / close with a Y motor XF:12IDC:2{Sh:E-Ax:Y}) gating the detector exposure for a scattering measurement." - - name: EndstationMotionController - family: MotionController - confirm: true - note: "Endstation motion controllers driving the sample, detector, and beamstop axes (SmarAct MCS, MDrive, Thorlabs among them); box model / protocol / IP not fully in the profile collection (DRIVE-1)." - software_iocs_not_modeled: - [Pilatus, Amptek, TetrAMM, Prosilica, Linkam, LakeShore, SmarAct, BladeCoater] - -resources: - intro: Continuously-available resources. Facility-scope supplies live in deployments/nsls2/site.yaml. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum # SAXS / WAXS in-vacuum flight path and chamber - - kind: LiquidNitrogen # DCM cooling - - kind: Power - replaceable_parts: - swappable_with_identity: ["Pilatus detectors", "CRL lenses", "attenuator foils", "in-situ sample cells"] diff --git a/deployments/srx/beamline.yaml b/deployments/srx/beamline.yaml deleted file mode 100644 index f054bb91f0f..00000000000 --- a/deployments/srx/beamline.yaml +++ /dev/null @@ -1,229 +0,0 @@ -# SRX beamline descriptor (NSLS-II), reverse-engineered -# -# SRX (Submicron Resolution X-ray spectroscopy) is the NSLS-II hard X-ray -# microprobe at sector 5-ID. It is a MULTI-TECHNIQUE beamline: scanning X-ray -# fluorescence (XRF) mapping, XANES, XRF-tomography, diffraction (via pixel -# detectors), and full-field imaging, across a micro endstation and a KB-focused -# nano endstation. It is bound to the NSLS-II Site (deployments/nsls2/site.yaml), -# the fourth NSLS-II beamline after FXI, HXN, and BMM. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the bluesky profile collection NSLS2/srx-profile-collection) or inferred, -# carried `new: true` + `confirm: true` pending SRX staff. EPICS PVs are real and -# verified against the profile collection; vendor part numbers, serials, and -# physical positions are not in it and are open questions. Same descriptor mode as -# FXI / HXN / BMM; this scaffold is descriptor + docs, scenarios deferred. -# -# SRX's value is breadth: it is the first deployment that runs several techniques on -# one instrument (XRF + XANES + XRF-tomo + diffraction + imaging), so it exercises -# the multi-Capability-per-beamline shape and reuses the families the earlier NSLS-II -# beamlines and the catalog already carry. It introduces NO new family: the -# fluorescence detector reuses EnergyDispersiveSpectrometer (graduated), the pixel -# detectors Camera (the Diamond Eiger precedent), the ion chambers FluxMonitor -# (graduated #353), the sample-environment thermal stage TemperatureController -# (graduated #350). Per the design-phase discipline, no new Capability is coined; -# the XRF-mapping / scanning question stays the deferred HXN question. - -beamline: - maturity: model - evidence: controls_config - coverage: full - page_layout: stages # Inventory dissolved into flat stage siblings - summary: "submicron X-ray fluorescence microprobe (XRF mapping, XANES, XRF-tomography, diffraction), 5-ID; modelled from public beamline config" - name: SRX - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "Sector 5" # PV namespace XF:05ID* - tier: Unit - parent: null - source: insertion-device - source_confirm: "IVU21 in-vacuum undulator (SR:C5-ID:G1{IVU21:1}), verified in source; parameters not fully in the profile collection (SRC-1)" - shape: "The first beamline running several techniques on one instrument: scanning XRF, XANES, XRF-tomography, diffraction, and imaging across a micro and a KB-focused nano endstation." - source_ref: - label: "NSLS2/srx-profile-collection" - url: "https://github.com/NSLS2/srx-profile-collection" -enclosures: - # PV zones: 05IDA optics, 05IDB secondary-source / mono, 05IDD endstation. Modelled - # as optics + experiment hutches; the intermediate 05IDB boundary is a staff - # question (ENC-1). Shutters span XF:05ID-PPS / 05IDA-PPS / 05IDB-PPS. - - name: 5-ID-A - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS search-and-secure permit leaf not in source; shutters are XF:05ID-PPS{Sh:WB}, 05IDA-PPS:1{PSh:2}, 05IDB-PPS:1{PSh:4} (PSS-1)"} - - name: 5-ID-D - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; the micro (05IDB) vs nano (05IDD) endstation hutch boundary to confirm (ENC-1)"} - -# =========================================================================== -# SOURCE STAGE: the undulator, monochromator, mirror, and beam-defining slits -# =========================================================================== - -source: - stage: source - enclosure: 5-ID-A - intro: The in-vacuum undulator source and the white-beam shutter. - devices: - - name: Source - family: InsertionDevice - pv: "SR:C5-ID:G1{IVU21:1}" - confirm: true - note: "IVU21 in-vacuum undulator (instance id_fly_device); gap-driven, fly-scannable for undulator-tracked energy scans. Parameters pending (SRC-1)." - - name: WhiteBeamShutter - family: Shutter - pv: "XF:05ID-PPS{Sh:WB}" - confirm: true - note: "White-beam front-end shutter (shut_fe, SRXTwoButtonShutter); two more photon shutters gate 5-ID-A and 5-ID-B." - -optics: - stage: source - enclosure: 5-ID-A - intro: "Condition the beam and set its energy: the high-heat-load monochromator, the horizontal focusing mirror, the white/pink-beam and secondary-source slits. PVs verified against startup/11-optics.py." - devices: - - name: Monochromator - family: Monochromator - pv: "XF:05IDA-OP:1{Mono:HDCM-Ax:" - confirm: true - note: "High-heat-load double-crystal monochromator (HDCM, class SRXDCM, instance dcm). The EnergyAxis below is the master energy; crystal cut and range pending (DCM-1)." - - name: FocusingMirror - family: Mirror - pv: "XF:05IDA-OP:1{Mir:1-Ax:" - confirm: true - note: "Horizontal focusing mirror (hfm, class SRXHFM)." - - name: WhiteBeamSlit - family: Slit - pv: "XF:05IDA-OP:1{Slt:1-Ax:" - confirm: true - note: "White-beam-defining slit (slt_wb); a pink-beam slit slt_pb sits at {Slt:2}." - - name: SecondarySourceAperture - family: Slit - pv: "XF:05IDB-OP:1{Slt:SSA-Ax:" - confirm: true - note: "Secondary-source aperture (slt_ssa) defining the coherence-matched source for the nano endstation." - - name: EnergyAxis - family: PseudoAxis - confirm: true - note: "The master energy axis driving the HDCM Bragg angle (with undulator tracking). XANES sweeps it across an edge; that energy sweep is the energy_scan Capability the catalog anticipates but does not yet coin (ENERGY-1, the BMM question)." - - name: BeamPositionMonitor - family: GenericProbe - pv: "XF:05IDA-BI:1{BPM:1-Ax:" - confirm: true - note: "Beam-position monitors (bpm3_pos, bpm4_pos) in the optics and secondary-source zones; read-only." - -# =========================================================================== -# SAMPLE STAGE: the KB nanofocus optics and the nano endstation sample stack -# =========================================================================== - -sample: - stage: sample - enclosure: 5-ID-D - intro: "The KB nanofocus optics and the sample stack. SRX has a micro endstation and a KB-focused nano endstation; the nano endstation is modelled here. PVs verified against startup/16-nanoES.py and 15-microES.py." - note: > - SRX scans the sample through a KB-focused spot for XRF mapping, the same - scanning-probe acquisition HXN introduced. The KB mirror pair reuses the Mirror - family; the sample stack reuses LinearStage / RotaryStage (XRF-tomography adds a - rotation). Interferometric stage feedback (FPS, PICOSCALE) stays on the floor. - devices: - - name: NanoKBMirror - family: Mirror - pv: "XF:05IDD-ES:1{nKB:" - confirm: true - note: "Kirkpatrick-Baez nanofocusing mirror pair (nanoKB, class SRXNanoKB); reuses the Mirror family. KB slits (jjslits) define the beam onto it." - - name: SampleStage - family: LinearStage - pv: "XF:05IDD-ES:1{nKB:Smpl-Ax:" - confirm: true - note: "Nano-endstation sample stack (nano_stage, class SRXNanoStage): the fine raster axes scanned for XRF mapping. Coarse and visible-light-microscope stages alongside (nano_vlm_stage). Interferometer feedback (FPS / PICOSCALE) is floor." - - name: SampleRotary - family: RotaryStage - pv: "XF:05IDD-ES:1{nKB:Smpl-Ax:" - confirm: true - note: "Sample rotation for XRF-tomography (raster x rotation, the 63-xrftomo path). Axis and encoder pending (STAGE-1)." - - name: Attenuators - family: Filter - pv: "XF:05IDD-ES{IO:4}DO:" - confirm: true - note: "Pneumatic attenuator foils (attenuators, class SRXAttenuators), digital-output relays." - - name: SampleTemperature - family: TemperatureController - pv: "XF:05IDD-ES{LS:1-Chan:" - confirm: true - note: "Sample-environment thermal control (temp_nanoKB, Lakeshore); binds the TemperatureController family." - -# =========================================================================== -# DETECTION STAGE: the per-point and area detectors for the several techniques -# =========================================================================== - -detector: - stage: detection - enclosure: 5-ID-D - intro: "The detectors for SRX's several techniques: the fluorescence spectrometer (XRF / XANES), the pixel detectors (diffraction / ptychography), the imaging camera, and the flux counters. PVs verified against startup/31-xspress3.py, 34-merlin.py, 35-dexela.py, 36-eiger.py, 30-scaler.py." - note: > - SRX's multi-technique nature shows in its detector set: which detector is read - selects the technique (the EnergyDispersiveSpectrometer for XRF/XANES maps, a - Camera pixel detector for diffraction, the PCO for full-field imaging). All reuse - existing families. Which are live vs legacy is a staff question (CAM-1). - devices: - - name: FluorescenceSpectrometer - family: EnergyDispersiveSpectrometer - pv: "XF:05IDD-ES{Xsp:3}:" - confirm: true - note: "Xspress3 energy-dispersive fluorescence detector for XRF mapping, XANES, and XRF-tomography; presents the Sensor Role. Element count / vendor pending (DET-1)." - - name: MerlinDetector - family: Camera - pv: "XF:05IDD-ES{Merlin:1}" - confirm: true - note: "Merlin pixel detector for diffraction / ptychography; reuses Camera." - - name: DexelaDetector - family: Camera - pv: "XF:05IDD-ES{Dexela:1}" - confirm: true - note: "Dexela flat-panel detector for wide-field diffraction; reuses Camera." - - name: EigerDetector - family: Camera - pv: "XF:05IDD-ES{Det:Eig1M}" - confirm: true - note: "Eiger 1M pixel detector; reuses Camera." - - name: ImagingCamera - family: Camera - pv: "XF:05IDD-ES{Det:3-Ax:" - confirm: true - note: "PCO Edge full-field imaging camera on the downstream gantry (pcoedge); reuses Camera. A Point Grey visible-light camera (XF:05ID1-ES{PG-Cam:1}) serves on-axis viewing." - - name: FluxCounter - family: FluxMonitor - pv: "XF:05IDD-ES:1{Sclr:1}" - confirm: true - note: "Scaler-counted ion-chamber flux channels (I0 and others) for normalization; binds the FluxMonitor family. Channel map pending (DIAG-1)." - -# =========================================================================== -# Cross-cutting controls -# =========================================================================== - -controls: - intro: > - The Zebra position-capture trigger for fly XRF mapping and the motion - controllers. Controller box models / firmware are not in the profile collection - (DRIVE-1). - triggering: - - name: Zebra - family: TimingController - pv: "XF:05IDD-ES:1{Dev:Zebra1}:" - trigger_source: PSO - confirm: true - note: "Zebra FPGA position-capture box (Zebra1) gating the per-point detector triggers during a fly XRF raster; a second Zebra2 is also present (ZEBRA-1)." - - name: EndstationMotionController - family: MotionController - confirm: true - note: "Endstation motion controllers driving the nano stages and KB; box model/protocol/IP not in the profile collection (DRIVE-1)." - software_iocs_not_modeled: - [Xspress3, Merlin, Dexela, Eiger, PCO, Zebra, Struck, Qmini] - -resources: - intro: Continuously-available resources. Facility-scope supplies live in deployments/nsls2/site.yaml. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: LiquidNitrogen # HDCM cryocooler - - kind: Power - replaceable_parts: - swappable_with_identity: ["KB mirrors", "pixel detectors", "attenuator foils"] diff --git a/deployments/sst/beamline.yaml b/deployments/sst/beamline.yaml deleted file mode 100644 index 1828a413ac1..00000000000 --- a/deployments/sst/beamline.yaml +++ /dev/null @@ -1,267 +0,0 @@ -# SST beamline descriptor (NSLS-II), reverse-engineered -# -# SST (Spectroscopy Soft and Tender) is the NSLS-II soft-and-tender X-ray beamline at -# sector 7-ID. It is a DUAL-BRANCH, MULTI-ENDSTATION beamline: a soft branch (SST-1, -# an EPU60 undulator + plane-grating monochromator) feeding resonant soft X-ray -# scattering (RSoXS) and NEXAFS absorption endstations, and a tender branch (SST-2, a -# U42 undulator + double-crystal monochromator) feeding the HAXPES photoemission -# endstation. It is bound to the NSLS-II Site (deployments/nsls2/site.yaml), the -# twelfth NSLS-II beamline after FXI, HXN, BMM, SRX, SIX, CHX, CSX, XPD, ESM, SMI, IXS. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the NSLS2/sst-*-profile-collection endstation repos and the shared -# NSLS-II-SST/sst-base package) or inferred, carried `confirm: true` pending SST -# staff. EPICS PVs are real and verified against the TOML device manifests and the -# sst-base device classes; vendor part numbers, serials, and physical positions are -# not in it and are open questions. Same descriptor mode as the other NSLS-II -# beamlines; this scaffold is descriptor + docs, scenarios deferred. -# -# SST is the SOFT-AND-TENDER BREADTH deployment: one beamline carrying two source + -# monochromator branches and several endstations spanning three technique families -# (soft X-ray scattering, absorption spectroscopy, photoemission). It introduces NO -# new catalog family: the soft PGM reuses GratingMonochromator (graduated, a fourth -# sighting after SIX / CSX / ESM), the tender DCM Monochromator, the area detector -# Camera, the sample manipulators the graduated Manipulator family (ESM), the flux -# channels FluxMonitor, the thermal stage TemperatureController, the NEXAFS -# microcalorimeter EnergyDispersiveSpectrometer. The hemispherical ElectronAnalyzer -# (the HAXPES Scienta SES) GRADUATED into the catalog: SST-HAXPES is the SECOND sighting -# after ESM, earning the rule-of-three. One loose family remains: the PositionMonitor -# (DIAG-1). Per the multi- -# technique discipline no Capability or Method is coined; the soft-scattering, -# absorption, and photoemission techniques sit on deferred / pending Methods and SST -# records no Practice. The non-spectroscopy in-situ accessories (flood gun, source- -# measure unit, ADR cryostat, syringe pump) are deferred (INSITU-1). - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "soft-and-tender dual-branch, multi-endstation (RSoXS scattering, NEXAFS absorption, HAXPES photoemission), 7-ID; modelled from public beamline config" - 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 insertion-device sources, one per branch: the soft branch EPU60 (SR:C07-ID:G1A{SST1:1}) and the tender branch U42 (SR:C07-ID:G1A{SST2:1}), read from the shared sst-base energy classes. Periods and ranges not fully in the profile collection (SRC-1)" - page_layout: stages - shape: "The broadest NSLS-II beamline CORA models: two source-and-monochromator branches feeding several endstations across RSoXS, NEXAFS, and HAXPES." - source_ref: - label: "NSLS-II-SST/sst-base" - url: "https://github.com/NSLS-II-SST/sst-base" -enclosures: - # The two branches are named SST-1 (soft) and SST-2 (tender) after their undulator - # branch labels (SST1:1 EPU60, SST2:1 U42), which is grounded in source. The - # endstation PV zones do NOT map one-to-one to a branch number: the soft RSoXS / NEXAFS - # endstations sit under XF:07ID1 / 07ID2, the tender HAXPES under XF:07ID6 (DCM) and - # XF:07ID1-BI (its manipulator). The physical hutch names / numbering and the exact - # endstation-to-hutch layout are not in source (ENC-1). Modelled as the optics hutch - # plus a soft-branch and a tender-branch experiment enclosure. - - name: 7-ID-A - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS search-and-secure permit leaf not in source; the front-end shutter is XF:07ID-PPS{Sh:FE} and the photon shutters are XF:07IDA-PPS{PSh:n} (PSS-1)"} - - name: SST-1 - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; SST-1 is the soft branch (EPU60 source, PGM) carrying the RSoXS and NEXAFS endstations. Hutch name / numbering not in source (PSS-1, ENC-1)"} - - name: SST-2 - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; SST-2 is the tender branch (U42 source, DCM) carrying the HAXPES endstation. Hutch name / numbering not in source (PSS-1, ENC-1)"} - -# =========================================================================== -# SOURCE STAGE: the two insertion-device sources and the front-end shutter -# =========================================================================== - -source: - stage: source - enclosure: 7-ID-A - intro: The two branch undulators (soft EPU60, tender U42) and the front-end shutter. - devices: - - name: SoftUndulator - family: InsertionDevice - pv: "SR:C07-ID:G1A{SST1:1}" - confirm: true - note: "EPU60 elliptically-polarizing undulator feeding the soft branch (SST-1; gap SR:C07-ID:G1A{SST1:1-Ax:Gap}-Mtr, phase and polarization mode controls). Soft energy range about 71-2250 eV. From the sst-base energy/soft.py classes (SRC-1)." - - name: TenderUndulator - family: InsertionDevice - pv: "SR:C07-ID:G1A{SST2:1}" - confirm: true - note: "U42 undulator feeding the tender branch (SST-2; gap SR:C07-ID:G1A{SST2:1-Ax:Gap}-Mtr). From the sst-base energy/tender.py classes (SRC-1)." - - name: FrontEndShutter - family: Shutter - pv: "XF:07ID-PPS{Sh:FE}" - confirm: true - note: "Front-end photon shutter; downstream photon shutters gate the branches at XF:07IDA-PPS{PSh:n}." - -# =========================================================================== -# OPTICS STAGE: the soft PGM, the tender DCM, the mirrors, the slits -# =========================================================================== - -optics: - stage: source - enclosure: 7-ID-A - intro: "Condition each branch and set its energy: the soft plane-grating monochromator, the tender double-crystal monochromator, the first and per-branch mirrors, and the white-beam and exit slits. PVs verified against the sst-base energy classes and the endstation TOML device manifests." - devices: - - name: SoftMonochromator - family: GratingMonochromator - pv: "XF:07ID1-OP{Mono:PGM1-Ax:" - confirm: true - note: "Soft-branch plane-grating monochromator (PGM1; grating, mirror-2, grating-X, CFF and VLS controls, energy XF:07ID1-OP{Mono:PGM1-Ax::ENERGY_SP). Reuses GratingMonochromator (graduated across SIX / CSX / ESM); a fourth sighting. Grating set pending (DCM-1)." - - name: TenderMonochromator - family: Monochromator - pv: "XF:07ID6-OP{Mono:DCM1-Ax:" - confirm: true - note: "Tender-branch double-crystal monochromator (DCM1; Bragg, crystal-select, energy XF:07ID6-OP{Mono:DCM1-Ax::ENERGY_SP). Reuses the Monochromator (crystal Bragg) family. Crystal cut and range pending (DCM-1)." - - name: FirstMirror - family: Mirror - pv: "XF:07IDA-OP{Mir:M1" - confirm: true - note: "First mirror (M1, a hexapod-mounted plane mirror) in the front optics; reuses the Mirror family." - - name: SoftMirror - family: Mirror - pv: "XF:07ID1-OP{Mir:M3ABC" - confirm: true - note: "Soft-branch focusing / steering mirror (M3ABC; M4 / M5 mirrors sit downstream per endstation). Reuses the Mirror family." - - name: TenderMirror - family: Mirror - pv: "XF:07IDA-OP{Mir:L1" - confirm: true - note: "Tender-branch mirror (L1; an L2AB mirror with a wedge sits downstream). Reuses the Mirror family." - - name: WhiteBeamSlit - family: Slit - pv: "XF:07IDA-OP{Slt:01-Ax:" - confirm: true - note: "Front-end / FOE beam-defining slit." - - name: ExitSlit - family: Slit - pv: "XF:07ID2-BI{Slt:11-Ax:" - confirm: true - note: "Monochromator exit slit (slitsc) setting the soft-branch resolution." - - name: HAXPESSlit - family: Slit - pv: "XF:07ID2-OP{Slt:12-Ax:" - confirm: true - note: "Beam-defining slit for the tender HAXPES endstation (haxslt / eslit). Reuses the Slit family." - - name: EnergyAxis - family: PseudoAxis - confirm: true - note: "The master energy axis: a coupled pseudopositioner per branch. The soft branch co-moves the EPU60 gap / phase with the PGM (range about 71-2250 eV); the tender branch co-moves the U42 gap with the DCM. The active branch is selected by the endstation in control. Whether energy is scanned as the measurement is the NEXAFS / spectroscopy question (ENERGY-1)." - - name: BeamPositionMonitor - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1) - pv: "XF:07ID-BI{BPM:4}" - confirm: true - note: "Beam-position monitors and fluorescent-screen / diode diagnostics along the branches (BPM:4 centroid, plus FS / SlitC screen cameras). Binds the graduated PositionMonitor Family (a consumer alongside 4-ID / 8-ID / 9-ID; DIAG-1)." - -# =========================================================================== -# SAMPLE STAGE: the soft (RSoXS) and tender (HAXPES) sample manipulators -# =========================================================================== - -sample: - stage: sample - enclosure: SST-1 - intro: "The sample manipulators for the soft (RSoXS, SST-1) and tender (HAXPES, SST-2) endstations, and the sample-environment thermal control. This stage spans both branches; the enclosure tag is the soft branch, and each device note states its branch. PVs verified against the RSoXS and HAXPES TOML device manifests." - note: > - SST holds samples in UHV manipulators in each endstation: a four-axis solid-sample - stage for RSoXS soft-scattering, and a multi-axis manipulator for HAXPES - photoemission. Both reuse the Manipulator family (graduated by ESM). The Linkam / - Lakeshore thermal control reuses TemperatureController. A NEXAFS manipulator and - the in-situ accessories (a flood gun, a source-measure unit, a syringe pump, an - ADR cryostat) are deferred (INSITU-1). - devices: - - name: RSoXSManipulator - family: Manipulator - pv: "XF:07ID2-ES1{Stg-Ax:" - confirm: true - note: "RSoXS soft-scattering solid-sample manipulator (X / Y / Z / Yaw, the primary sample holder). Reuses the Manipulator family (graduated by ESM)." - - name: HAXPESManipulator - family: Manipulator - pv: "XF:07ID1-BI{HAX-Ax:" - confirm: true - note: "HAXPES photoemission sample manipulator (X / Y / Z / R) in the SST-2 tender branch (its PV sits under the XF:07ID1-BI zone label, a source naming quirk, not the tender DCM's 07ID6 zone). Reuses the Manipulator family (graduated by ESM). The NEXAFS endstation has its own manipulator (XF:07ID1-BI{NXFS-Ax:), deferred." - - name: SampleTemperature - family: TemperatureController - pv: "XF:07ID2-ES1{TCtrl:1}LS336:" - confirm: true - note: "Sample-environment thermal control (a Lakeshore 336). Reuses the TemperatureController family (graduated #350). Which units are live per endstation is TEMP-1." - -# =========================================================================== -# DETECTION STAGE: the soft scattering CCD, the electron analyzer, the calorimeter -# =========================================================================== - -detector: - stage: detection - enclosure: SST-1 - intro: "The detectors that make SST multi-technique: the soft-scattering CCD (RSoXS, SST-1), the hemispherical electron analyzer (HAXPES photoemission, SST-2), the microcalorimeter (NEXAFS fluorescence), the flux monitors, and the beamstop. This stage spans both branches; each device note states its branch. PVs verified against the RSoXS, HAXPES, and NEXAFS TOML manifests." - note: > - Which detector is read decides the technique: the Greateyes CCD for soft X-ray - scattering, the Scienta electron analyzer for photoemission, the transition-edge - microcalorimeter for energy-resolved fluorescence, or the drain-current / diode - channels for absorption. All reuse existing families. The retired or commented - detectors (the second RSoXS Greateyes SAXS arm) are not modelled (DET-1). - devices: - - name: ScatteringDetector - family: Camera - pv: "XF:07ID1-ES:1{GE:2}" - confirm: true - note: "Greateyes 4k x 4k CCD area detector (the RSoXS WAXS detector); reuses Camera. A second Greateyes SAXS arm is commented out in source (DET-1)." - - name: ElectronAnalyzer - family: ElectronAnalyzer # catalog Family (graduated ESM + SST) - pv: "XF:07ID-ES-SES" - confirm: true - note: "Scienta SES hemispherical electron analyzer (the HAXPES photoemission detector in the SST-2 tender branch; pass energy, lens mode, kinetic / excitation energy, acquisition mode, from the NSLS-II-SST/haxpes ses.py SES class). A photon-in / electron-out device that fits no photon-detector family. Binds the catalog ElectronAnalyzer family: SST-HAXPES is the SECOND sighting (n=2, the same Scienta SES type) after ESM, which GRADUATED the family into the catalog (ARPES-1)." - - name: CalorimeterSpectrometer - family: EnergyDispersiveSpectrometer - pv: "XF:07ID-ES{UCAL}:" - confirm: true - note: "Transition-edge-sensor (TES) microcalorimeter for energy-resolved fluorescence (NEXAFS); it resolves photon energy per event to give a spectrum, so it reuses EnergyDispersiveSpectrometer. Whether a cryogenic microcalorimeter is a per-Asset settings variant of that family (alongside the silicon-drift and germanium variants) or warrants its own Family is a question; carried as reuse for now. Its ADR cryostat (XF:07ID-ES{UCAL:ADR}) is deferred (INSITU-1)." - - name: FluxMonitor - family: FluxMonitor - pv: "XF:07ID-ES1{DMR:I400-1}" - confirm: true - note: "The bound PV is the RSoXS I0 photodiode (I400 electrometer). Other incident-flux channels live under separate prefixes: an Au-mesh I0 on a second I400, and the HAXPES / NEXAFS drain-current and ion-chamber channels on SR570 amplifiers into ADC buffers. Reuses FluxMonitor (graduated #353). The full channel map is pending (DIAG-1)." - - name: BeamStop - family: BeamStop - pv: "XF:07ID2-ES1{BS-Ax:1}Mtr" - confirm: true - note: "RSoXS motorized beamstop (BeamStopW) blocking the direct beam ahead of the CCD; a separate beamstop-diode current channel reads its intensity. Reuses BeamStop." - - name: SampleCamera - family: Camera - pv: "XF:07ID1-ES:1{Scr:4}" - confirm: true - note: "On-axis sample-viewing optical camera (RSoXS; side and imager cameras serve alignment). Reuses Camera." - -# =========================================================================== -# Cross-cutting controls -# =========================================================================== - -controls: - intro: > - SST acquisition is gated by the endstation fast shutter; the detectors run in - software-triggered modes, with no separate hardware timing box in the profile - collection. The endstation in control selects the active branch. Controller box - models / firmware are not fully in the profile collection (DRIVE-1). - triggering: - - name: FastShutter - family: Shutter - pv: "XF:07ID2-ES1{FSh-Ax:1}Mtr" - confirm: true - note: "RSoXS fast piezo shutter (a translate axis plus a diode-control line XF:07IDB-CT{DIODE-Local:1}) gating the detector exposure." - - name: EndstationMotionController - family: MotionController - confirm: true - note: "Endstation and optics motion controllers driving the manipulators, mirrors, and detector stages across the branches; box model / protocol / IP not fully in the profile collection (DRIVE-1)." - software_iocs_not_modeled: - [Greateyes, SES, TES, Lakeshore, SR570, I400, ADCBuffer, FloodGun, Keithley, SyringePump] - -resources: - intro: Continuously-available resources. Facility-scope supplies live in deployments/nsls2/site.yaml. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum # UHV soft / tender beam path and endstations - - kind: LiquidNitrogen # DCM cooling - - kind: Power - replaceable_parts: - swappable_with_identity: ["Greateyes CCD", "analyzer slits", "TES detector", "in-situ sample cells"] diff --git a/deployments/syrmep/beamline.yaml b/deployments/syrmep/beamline.yaml deleted file mode 100644 index 2372783d2f9..00000000000 --- a/deployments/syrmep/beamline.yaml +++ /dev/null @@ -1,286 +0,0 @@ -# SYRMEP beamline descriptor (Elettra), reverse-engineered -# -# SYRMEP (SYnchrotron Radiation for MEdical Physics) is Elettra's hard X-ray -# radiology and microtomography beamline: a bending-magnet source feeding a -# double-crystal Si(111) monochromator (or a white / pink beam), a laminar beam, -# and a heavy-payload rotation stage with an sCMOS / CCD detector on a long -# sample-to-detector propagation rail. It does absorption, propagation-based -# phase-contrast, and diffraction-enhanced imaging, plus a clinical breast-CT -# programme (SYRMA-3D). It is bound to the Elettra Site -# (deployments/elettra/site.yaml), CORA's ELEVENTH Site and its FIRST Elettra -# deployment. -# -# STATUS: reverse-engineered, design-phase. Hardware facts (source, optics, -# detectors, stages, scan modes) are read from public material (the elettra.eu -# SYRMEP beamline pages, the EPJ Plus 2024 SYRMEP review, the J. Synchrotron Rad. -# 2023 large-FOV paper) and carried -# new: true + confirm: true pending SYRMEP staff. UNLIKE the ID32 BLISS scaffold, -# SYRMEP's control handles are NOT in public source: the in-house DonkiOrchestra -# scan engine's source location is unconfirmed and the acquisition code lives in -# the private gitlab.elettra.eu syrmep_acquisition group. So device handles are -# carried as confirm-pending placeholders, NOT invented Tango device URLs -# (CTRL-1). Descriptor + docs scaffold; scenarios deferred. -# -# WHAT IS NEW: a new Site, and a new controls house-style; NO new Family. -# - A wholly NEW Site (Elettra, 11th) re-tests the Site / Federation kernel. -# - The first Tango + DonkiOrchestra controls house-style (the rest are EPICS, -# Tango / Sardana at MAX IV, or Tango / BLISS / IcePAP at the ESRF). The Tango -# floor is shared with ID32, but the orchestration seam is the in-house, -# trigger-driven DonkiOrchestra (Elettra 2.0: the abstract "Executer" Tango -# device server), not BLISS. -# - SYRMEP is a tomography beamline, so it binds the SAME catalog tomography -# Families the 2-BM / FXI / 7-BM imaging beamlines use (RotaryStage, -# LinearStage, Camera, Scintillator, Slit, Filter, Monochromator); it coins -# no Family and changes nothing in the catalog. -# -# MODELLING: SYRMEP reuses the established imaging spine. The bending-magnet source -# is a Supply (PhotonBeam), provenance only (the 2-BM precedent). The Si(111) DCM -# binds Monochromator; the white/mono mode is a per-Asset setting on it (the 2-BM -# DMM insert/retract precedent). The laminar-beam slits bind Slit, the filters bind -# Filter. The heavy-payload rotation stage binds RotaryStage; the five-axis sample -# stage binds LinearStage; the sample-to-detector propagation rail binds LinearStage -# (the 2-BM CameraZ precedent); the scintillator binds Scintillator and the sCMOS / -# CCD bind Camera. The incident energy is a PseudoAxis over the DCM (the 2-BM -# energy-curve precedent). -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/syrmep/questions.md. - -beamline: - maturity: model - evidence: narrative - coverage: full - summary: "hard X-ray radiology and microtomography (absorption + phase-contrast + breast-CT); CORA's first Elettra deployment and first DonkiOrchestra control plane" - name: SYRMEP - facility: elettra # Elettra Site (facility_code: elettra) - sector: "SYRMEP" # organizational label, not a registered asset today - tier: Unit - parent: null - source: bending-magnet - source_confirm: "first bending magnet of section 6; at 2.4 GeV critical energy 5.59 keV, field 1.45 T (SRC-1)" - page_layout: stages - shape: "Elettra's hard X-ray microtomography beamline (absorption, phase-contrast, and clinical breast CT) on a Tango + DonkiOrchestra control house-style, coining nothing new." - source_ref: - label: "elettra.eu beamline page" - url: "https://www.elettra.eu/elettra-beamlines/syrmep.html" - -# Control plane: Tango (the device floor) with the in-house DonkiOrchestra scan -# engine as the orchestration seam, NOT EPICS and NOT BLISS. Handles are NOT in -# public source (DonkiOrchestra source location unconfirmed; acquisition code in -# the private gitlab.elettra.eu syrmep_acquisition group), so every device below -# carries a confirm-pending handle rather than an invented Tango URL (CTRL-1). The -# hutch grouping and PSS permit leaves are open (ENC-1, PSS-1). -enclosures: - - name: syrmep-optics - role: optics-hutch - facility_code: elettra - permit_signal: {confirm: "Elettra PSS permit leaf not in public source; the white-beam optics zone, hutch grouping is ENC-1 (PSS-1)"} - - name: syrmep-experiment - role: experiment-hutch - facility_code: elettra - permit_signal: {confirm: "Elettra PSS permit leaf not in public source; the imaging / tomography endstation, ENC-1 (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the machine state, the bending-magnet beam, the DCM, the optics -# =========================================================================== - -machine: - stage: source - enclosure: syrmep-optics - intro: "The machine-level source state, observed not driven." - note: "The Elettra storage-ring state, the loose StorageRing pattern reused across the fleet (MACHINE-1)." - devices: - - name: StorageRing - family: StorageRing # loose Family (machine-level observe-only source state; MACHINE-1) - pv: {confirm: "Elettra storage-ring state (2.0 GeV / 300 mA and 2.4 GeV modes; current, fill); observe-only, exact Tango handles are MACHINE-1"} - new: true - confirm: true - note: "Elettra storage-ring state; observe-only (MACHINE-1)" - -source: - stage: source - enclosure: syrmep-optics - intro: "Where the bending-magnet beam enters and first gets gated." - note: > - The source devices are a flat set on the SYRMEP Unit (the 2-BM precedent): the - bending-magnet beam is a Supply (PhotonBeam), provenance only; the safety - shutter and beam-defining mask gate it. No Conditioner Assembly earns its place - at this stage. - devices: - - name: source - family: Beam # Supply(kind=PhotonBeam); accelerator-side, provenance only - new: true - note: "bending magnet (first BM of section 6), recorded as a Supply, not an Asset (SRC-1)" - - name: FrontEndShutter - family: Shutter - pv: {confirm: "the front-end / safety shutter gated by the Elettra PSS; handle not in public source (PSS-1)"} - new: true - confirm: true - note: "front-end safety shutter, gated by the personnel safety system (PSS-1)" - - name: BeamDefiningMask - family: Mask - passive: true - new: true - confirm: true - note: "the fixed white-beam-defining aperture upstream of the optics; dimensions and drawing not in public source (OPT-1)" - -conditioning-optics: - stage: source - enclosure: syrmep-optics - intro: "Pick the beam energy (or pass white beam), shape it, and filter it." - note: > - The double-crystal Si(111) monochromator binds Monochromator; the mono / white - beam choice is a per-Asset setting on it (the 2-BM DMM insert/retract - precedent). The incident energy is a PseudoAxis over the DCM. The laminar-beam - slits bind Slit and the filters bind Filter. - devices: - - name: Monochromator - family: Monochromator - pv: {confirm: "double-crystal Si(111) DCM, fixed-exit Bragg geometry (20 mm vertical offset); Bragg / offset handles not in public source (MONO-1)"} - crystal: "Si(111)" - energy_range_mono: "10-40 keV (EPJ Plus 2024 review; the elettra.eu spec still lists 9-40, MONO-1)" - beam_modes: ["monochromatic", "white"] # the white / pink beam bypasses the DCM; modeled as a per-Asset setting (MODE-1) - new: true - confirm: true - note: > - the double-crystal Si(111) monochromator (fixed-exit, 20 mm offset). The - white / pink beam mode (~16-30 keV average) bypasses the crystals; modeled - as the Monochromator Asset beam-mode setting (the 2-BM dmm_insertion - precedent). Energy range 10-40 keV mono per the 2024 review; the official - spec page still lists 9-40 keV (MONO-1). - - name: BeamEnergy - family: PseudoAxis - pv: {confirm: "incident-energy pseudo-axis over the DCM Bragg arms; partition rule and handles are MONO-1"} - new: true - confirm: true - note: "incident-energy pseudo-axis (the 2-BM energy-curve precedent); range and rule are MONO-1" - - name: BeamSlit - family: Slit - pv: {confirm: "the white-beam-defining slits shaping the laminar beam (~120-160 x 4-5 mm at 20-23 m); blade-axis map and handles are OPT-2"} - water_cooled: true - white_beam: true - new: true - confirm: true - note: "the laminar-beam-defining slits; the 7 mrad horizontal acceptance gives a ~120-160 mm wide, ~4-5 mm tall beam (OPT-2)" - - name: Filter - family: Filter - pv: {confirm: "the beam-hardening / attenuation filter set; foils and handles not in public source (FOIL-1)"} - new: true - confirm: true - note: "the absorption / beam-hardening filters; foil materials and the selector handle are FOIL-1" - -# =========================================================================== -# SAMPLE STAGE: the heavy-payload rotation stage + the five-axis sample stage -# =========================================================================== - -sample: - stage: sample - enclosure: syrmep-experiment - intro: "Hold and rotate the sample: a heavy-payload rotation stage on a five-axis sample positioner." - note: > - The rotation axis binds RotaryStage (the tomographic theta, the 2-BM - precedent); the five-axis sample positioner binds LinearStage facets. Continuous - (fly) and helical scans run as the rotation stage's trigger-driven sweep under - DonkiOrchestra (the orchestration seam, CTRL-1). - devices: - - name: Rotary - family: RotaryStage # the tomographic rotation axis (theta) - pv: {confirm: "the heavy-payload rotation stage; handle and trigger wiring not in public source (STAGE-1, CTRL-1)"} - trigger_source: {confirm: "the projection trigger for continuous / fly scans is driven by DonkiOrchestra; the hardware trigger source is CTRL-1"} - load_capacity: "up to 120 kg" # the heavy-specimen rotator (J. Synchrotron Rad. 2023) - max_speed: "1-20 deg/s" - angular_precision: "0.02 deg" - new: true - confirm: true - note: "the heavy-payload rotator (up to 120 kg, 1-20 deg/s, 0.02 deg precision per the brief); the standard sample rotation stage range / bearing / model and the wobble spec are STAGE-1" - - name: SampleStage - family: LinearStage - pv: {confirm: "the five-axis sample-positioning stage; motor vendors, micro-positioning resolution, axis set, and handles are SAMPLE-1"} - new: true - confirm: true - note: "the five-axis sample positioner; the motor vendors, the micro-positioning resolution, and the per-axis map are SAMPLE-1" - -# =========================================================================== -# DETECTION STAGE: the propagation rail, the scintillator, the sCMOS / CCD -# =========================================================================== - -detector: - stage: detection - enclosure: syrmep-experiment - intro: "Convert the transmitted beam to light and record it, on a long sample-to-detector propagation rail for phase contrast." - note: > - The sample-to-detector distance binds LinearStage (the propagation rail, the - 2-BM CameraZ precedent); the scintillator binds Scintillator and the area - detectors bind Camera. SYRMEP runs more than one camera (an sCMOS and a CCD, - plus a photon-counting detector for large-specimen CT); the default routine - camera is DET-1. - devices: - - name: PropagationRail - family: LinearStage # sample-to-detector distance (phase-contrast propagation), not a focus stage - pv: {confirm: "the sample-to-detector sliding rail (3-160 cm); handle not in public source (DET-2)"} - range: "3-160 cm" - new: true - confirm: true - note: "the phase-contrast propagation rail (sample-to-detector 3-160 cm); the two-axis detector rail handles are DET-2" - - name: Scintillator - family: Scintillator - pv: {confirm: "the scintillator screen converting X-rays to visible light (published configs cite GGG:Eu); type, thickness, and handle are DET-3"} - new: true - confirm: true - note: "the scintillator (published configs cite a GGG:Eu screen); the routine screen type and thickness are DET-3" - - name: TomographyCamera - family: Camera - pv: {confirm: "the 16-bit sCMOS detector (2048x2048 px, effective pixel 0.9-5.7 um via selectable optics; e.g. Hamamatsu Orca Flash); handle not in public source (DET-1)"} - sensor: "sCMOS, 2048x2048 px, 16-bit" - effective_pixel: "0.9-5.7 um (selectable optics)" - new: true - confirm: true - note: "the 16-bit sCMOS (2048x2048; published configs name a Hamamatsu Orca Flash); whether this or the CCD is the default routine-tomography camera, with its pixel size + FOV, is DET-1" - - name: CCDCamera - family: Camera - pv: {confirm: "the 12/16-bit CCD (4008x2672 px, 4.5 um pixel, PSF ~13 um); handle not in public source (DET-1)"} - sensor: "CCD, 4008x2672 px, 12/16-bit" - pixel_size: "4.5 um" - psf: "~13 um" - new: true - confirm: true - note: "the 12/16-bit CCD (4008x2672, 4.5 um pixel, PSF ~13 um); the alternate area detector (DET-1)" - - name: PhotonCountingCamera - family: Camera - pv: {confirm: "the XC Hydra (Direct Conversion AB) photon-counting detector for large-specimen helical CT; pixel size and handle not in public source (DET-4)"} - sensor: "XC Hydra photon-counting (Direct Conversion AB)" - new: true - confirm: true - note: "the XC Hydra photon-counting detector for large-specimen / helical CT (J. Synchrotron Rad. 2023); reuses Camera, used in the large-FOV mode; pixel size is DET-4" - -# Cross-cutting control. SYRMEP runs on Tango (the floor) with the in-house -# DonkiOrchestra scan engine (the orchestration seam); the handles above are -# confirm-pending placeholders, NOT invented, because they are not in public -# source (CTRL-1). -controls: - intro: > - SYRMEP runs on the Elettra Tango control stack (the device floor, shared with - ID32) with the in-house, trigger-driven DonkiOrchestra framework as the scan / - acquisition engine (DonkiDirector schedules DonkiPlayers over a ZeroMQ trigger - train, collecting into HDF5). The Elettra 2.0 successor names this orchestration - an abstract "Executer" Tango device server feeding the STP3 / MAPI reconstruction - and the Elettra Scientific Data Lake. That orchestration is the seam CORA's edge - replaces, conducting over Tango rather than over BLISS or EPICS. UNLIKE the public - ID32 BLISS config, SYRMEP's device handles are NOT in public source (the - DonkiOrchestra source location is unconfirmed and the acquisition code lives in - the private gitlab.elettra.eu syrmep_acquisition group), so the handles above are - carried confirm-pending placeholders, not invented Tango device URLs (CTRL-1). - The reconstruction pipeline (the SYRMEP Tomo Project: phase retrieval, ring - removal, FBP / iterative on ASTRA + TomoPy) is post-acquisition compute CORA - records as Method / Compute provenance, not data it owns (see model.md). - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources a SYRMEP run needs. The white-beam - optics path runs under vacuum and the optics are water-cooled (SUP-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the white-beam optics and beam-transport path (SUP-1)" diff --git a/deployments/tomowise/beamline.yaml b/deployments/tomowise/beamline.yaml deleted file mode 100644 index 81965f13b74..00000000000 --- a/deployments/tomowise/beamline.yaml +++ /dev/null @@ -1,477 +0,0 @@ -# CORA Beamline descriptor: TomoWISE (MAX IV), design phase -# -# TomoWISE is a planned microtomography + nanotomography beamline at MAX IV -# (Lund). It is bound to the MAX IV Site (deployments/maxiv/site.yaml). -# -# STATUS: design phase. Every value here is a TDR design SPECIFICATION, not a -# commissioned measurement, so every device carries `new: true` (not yet modelled -# in CORA) and `confirm: true` (value to be verified by MAX IV staff). Control -# handles are omitted on purpose: MAX IV runs Tango/Sardana (not EPICS) and PV -# names are TBD, so no `pv` field is invented. Devices bind to catalog Families -# only, with no `model`, because vendors/part-numbers are not yet procured; -# "(target)" models named in the TDR are carried as open questions, not bindings. -# -# Items the TDR explicitly defers are tagged inline with a (QUESTION-ID) that is -# answered on docs/deployments/tomowise/questions.md. Two TDR coordinate frames -# appear (front end: z from the CPMU14 source; optics hutch and downstream: z -# from the straight-section centre, ~505 mm apart); z_mm values are approximate -# from-source and carried as confirm (LAYOUT-1). - -beamline: - maturity: design - evidence: design_report - coverage: full - summary: "micro- and nano-tomography, Technical Design Report phase" - name: TomoWISE - facility: maxiv - tier: Unit - parent: null - source: insertion-device - source_confirm: "two switchable insertion devices: CPMU14 undulator + 3T3PW wiggler, selected per operation mode (TDR design phase)" - z_span_mm: [0, 52000] - z_span_confirm: true - page_layout: stages - shape: "A MAX IV micro- and nano-tomography beamline (two endstations on a shared source) modelled from its design report; the tomography spine on a Tango / Sardana floor." - -# Two access-gated hutches. PSS permit signals are MAX IV facility signals, not -# yet named in the TDR (PSS-1). -enclosures: - - name: TomoWISE-optics - role: optics-hutch - facility_code: maxiv - permit_signal: {confirm: "MAX IV PSS permit signal TBD (PSS-1)"} - - name: TomoWISE-experiment - role: experiment-hutch - facility_code: maxiv - permit_signal: {confirm: "MAX IV PSS permit signal TBD (PSS-1)"} - -# --- SOURCE STAGE: the beam delivery shared by both endstations --- - -insertion-devices: - stage: source - enclosure: TomoWISE-optics - intro: "Two switchable straight-section sources. The undulator drives high-flux micro- and nano-tomography; the wiggler drives wide-field large-FOV white-beam microtomography. The operation mode selects which is in use." - note: > - z is measured from the straight-section centre here (CPMU14 at -505 mm, - 3T3PW at +1734 mm). All specifications are TDR design targets. - devices: - - name: CPMU14 - family: InsertionDevice - new: true - confirm: true - device_type: cryogenic-permanent-magnet-undulator - period: 14 mm - min_gap: 3.8 mm - length: 2.0 m (cryostat 2.67 m) - max_k_eff: 1.84 - power_at_500ma: 11.1 kW - note: "primary source for high-flux micro- and nano-tomography" - - name: 3T3PW - family: InsertionDevice - new: true - confirm: true - device_type: three-pole-wiggler - field: 3 T - magnetic_length: 412 mm - min_gap: 11 mm - power_at_500ma: 1.6 kW - note: "wide-field large-FOV white-beam microtomography" - -front-end: - stage: source - enclosure: TomoWISE-optics - intro: "Fixed and movable masks plus the heat absorber that shape the beam and absorb power before the optics hutch." - note: > - z from the CPMU14 source (TDR Table 7.1). Mask is now a shared catalog - Family; the heat-absorber Family is not yet in the catalog (it renders as - plain text pending the passive beam-path tier), bound loosely by design intent. - devices: - - name: FM1 - family: Mask - z_mm: 14000 - new: true - confirm: true - aperture: 1.100 mrad X/Y - power_absorbed: ~2 kW - note: "first fixed mask" - - name: FM2 - family: Mask - z_mm: 15000 - new: true - confirm: true - aperture: 1.100 mrad X / 0.100 mrad Y - power_absorbed: up to 7 kW - note: "second fixed mask" - - name: MSM - family: Mask - z_mm: 16500 - new: true - confirm: true - aperture: 1.1 x 0.1 / 0.1 x 0.1 mrad2 - note: "movable safety mask; <100 um lateral parasitic motion (design)" - - name: HeatAbsorber - family: HeatAbsorber - z_mm: 17000 - new: true - confirm: true - power_budget: 4 kW - note: "front-end heat absorber protecting the safety shutter; a second, near-identical heat absorber sits in the optics-hutch safety unit (SU) with SS1/SS2 (TDR Table 8.1), not separately modelled here" - -optics-hutch: - stage: source - enclosure: TomoWISE-optics - intro: "The conditioning optics that filter, monochromate, and define the beam delivered to the experiment hutch. Diagnostic modules DM1/DM2 carry the bremsstrahlung collimators, white-beam stops, slits, and beam-position monitors." - note: > - z from the straight-section centre (TDR Table 8.1). Filter / BPM / - collimator / beam-stop Families are not all in the catalog yet and render - as plain text. - devices: - - name: CVD - family: Filter - z_mm: 24050 - new: true - confirm: true - material: 0.35 mm CVD diamond - transmission: 95% @ 20 keV, 50% @ 10 keV - note: "diamond filter" - - name: WhiteBeamSlit - family: Slit - z_mm: 24280 - new: true - confirm: true - note: "water-cooled white-beam slits (WBS) in DM1; DM1 also carries a separate beam-defining mask (BM, water-cooled Cu, 60 urad opening matching the MLM acceptance) and a bremsstrahlung collimator, not separately modelled here" - - name: PFU - family: Filter - z_mm: 25200 - new: true - confirm: true - mechanism: two Si wedges, 3 deg wedge angle - effective_thickness: 0.2 to 25 mm - note: "power filters unit" - - name: MLM - family: Monochromator - z_mm: 25900 - new: true - confirm: true - coating: W/SiC or W/B4C bilayers (TDR text); Table 8.3 lists W/Si; d=2.5 nm, 140 bilayers (OPT-1) - energy_range: 20 to 65 keV - bandwidth: dE/E ~ 1.8% - bragg_range: 3.84 to 12.6 mrad - max_power: 100 W - note: "multilayer monochromator; bypassed in white-beam modes" - - name: MonochromaticBeamSlit - family: Slit - z_mm: 28280 - new: true - confirm: true - note: "monochromatic beam slits (DM2)" - - name: MF - family: Filter - new: true - confirm: true - transmission: 1e-4 to 1 - note: "metal filter unit (third filter stage, Fe/Cu carriages, NanoMAX design); at the beginning of the experiment hutch" - -safety-shutters: - stage: source - enclosure: TomoWISE-optics - intro: "The safety unit (SU) gating the beam between the optics and experiment hutches." - note: "z from the straight-section centre. PSS permit signals TBD (PSS-1)." - devices: - - name: SS1 - family: Shutter - z_mm: 31830 - new: true - confirm: true - note: "safety shutter (SU)" - - name: SS2 - family: Shutter - z_mm: 31830 - new: true - confirm: true - note: "safety shutter (SU)" - -# --- SAMPLE STAGE: two endstations sharing the detector gantry --- - -microtomography-endstation: - stage: sample - enclosure: TomoWISE-experiment - intro: "The microtomography endstation, ~45 m from source: a fixed sample table carrying the rotary stage, sample positioning, laminography tilt, sample-side slits and fast shutter, and a slip ring for continuous rotation." - note: "All values TDR design targets. Stage models marked '(target)' are carried as questions, not bound." - devices: - - name: SampleTable - family: Table - z_mm: 45000 - new: true - confirm: true - degrees_of_freedom: Xt (+/-100 mm), Yt (+50/-150 mm), beta (1.2 deg) - surface_to_beam: 390 mm - note: "fixed sample table at 45 m" - - name: Rotary - family: RotaryStage - new: true - confirm: true - max_speed: 1200 rpm - resolution: 1 mdeg - encoder: TTL, 3600 pulses per rotation - model_target: Lab Motion Systems RT100AX (STAGE-1) - note: "tomographic rotation; the master clock for triggering (TRIG-1)" - - name: SamplePositioning - family: LinearStage - new: true - confirm: true - travel: +/-6 mm per axis (Xs, Zs) - resolution: 0.1 um - model_target: Lab Motion Systems XY150B-12 (STAGE-2) - note: "sample centring stage" - - name: LaminographyTilt - family: TiltStage - new: true - confirm: true - travel: 25 deg - resolution: 50 mdeg - note: "laminography tilt axis" - - name: SampleSlit - family: Slit - new: true - confirm: true - opening: 50 x 5 mm - note: "sample-side precise slits; JJ X-ray IB-C50-air reference design" - - name: FastShutter - family: Shutter - new: true - confirm: true - note: "sample-side fast shutter; Arinax Colibri (<5 ms) / Innospexion (<10 ms) reference designs" - - name: SlipRing - family: SlipRing - new: true - confirm: true - channels: 30 to 40 - note: "continuous-rotation feedthrough; up to 1000 rpm" - -nanotomography-endstation: - stage: sample - enclosure: TomoWISE-experiment - intro: "The nanotomography endstation, ~49-51 m from source: the KB mirror pair focuses the undulator beam for 200-nm-class cone-beam imaging. The sample manipulator is a six-axis stack on a granite support, conceptually similar to the microtomography endstation but about a factor of ten more precise." - note: > - Mirror Family reused for the KB pair. The TDR specifies the sample - manipulator in Table 9.5 (it is NOT deferred to procurement): the stack - reuses the same Families as the microtomography endstation (Table, - TiltStage, LinearStage, RotaryStage), with a "(target)" model per axis - carried as model_target pending procurement (NANO-1). The most critical - axis is the rotary: Abbe error from wobble and eccentricity must not - exceed 100 nm at 100 mm sample height. - devices: - - name: KB - family: Mirror - z_mm: 49000 - new: true - confirm: true - type: fixed-curvature graded-multilayer KB pair - focal_spot: 205 x 196 nm @ 30 keV; 196 x 80 nm @ 45 keV - note: "Kirkpatrick-Baez focusing mirrors for nanotomography" - - name: NanoGranite - family: Table - z_mm: 49000 - new: true - confirm: true - note: "single granite support housing the KB optics, the sample manipulator, and the detector stage" - - name: NanoTilt - family: TiltStage - new: true - confirm: true - travel: 2 deg - resolution: 5 mdeg - model_target: Huber 5202.80 (NANO-1) - note: "Tilt X; aligns the rotation axis to the beam vertical angle" - - name: NanoCoarseX - family: LinearStage - new: true - confirm: true - travel: 50 mm - model_target: Huber 5101.20 (NANO-1) - note: "Xt; centre-of-rotation alignment and flat-field acquisition" - - name: NanoCoarseY - family: LinearStage - new: true - confirm: true - travel: 50 to 100 mm - model_target: Huber 5103.A20-90 (NANO-1) - note: "Yt; sample height adjustment" - - name: NanoCoarseZ - family: LinearStage - new: true - confirm: true - travel: 250 to 300 mm - resolution: <0.5 um - model_target: Zaber X-LDQ-AE (NANO-1) - note: "Zt; brings the rotation axis into the KB focus, then translates toward the detector" - - name: NanoRotary - family: RotaryStage - new: true - confirm: true - max_speed: ">60 rpm" - resolution: 1 mdeg - eccentricity: <100 nm at sample height - encoder: TTL, 3600 pulses per rotation - model_target: Lab Motion Systems RT100AS (NANO-1) - note: "Rot y; continuous nanotomographic rotation, radial error <100 nm / axial error <50 nm" - - name: NanoSamplePositioning - family: LinearStage - new: true - confirm: true - travel: +/-6 mm (Xs, Zs) - resolution: 0.1 um - model_target: Lab Motion Systems XY150B-12 (NANO-1) - note: "Xs/Zs sample-to-CoR centring; same model as the micro endstation positioning" - -# --- DETECTION STAGE: the shared detector gantry --- - -detector: - stage: detection - enclosure: TomoWISE-experiment - intro: "One detector gantry on 7 m floor rails serves both endstations (45 m to the 52 m hutch wall), carrying interchangeable microscopes and cameras. A removable flight tube reduces air scatter." - note: > - The two microscopes are composed as Microscope Assemblies (Housing-anchored, - reusing the cross-facility catalog assembly): each has a turret, objectives, - and a selector over a scintillator. The four cameras and the gantry propagation - rail are shared across both microscopes, so the assembly's camera and - propagation_distance slots are left empty (ZeroOrOne). Camera models are design - targets (DET-1); the Optique Peter optics model is bound from the 2-BM catalog - candidate pending confirmation (DET-2). - devices: - - name: DetectorGantry - family: Table - new: true - confirm: true - axes: Xd, Yd, Zd (Zd on 7 m floor rails) - range: 45 m to 52 m - note: "shared detector gantry" - - name: MicLFOV - family: Housing - model: optique_peter_micrx080 - new: true - confirm: true - magnification: 1 to 2x - numerical_aperture: ">0.2" - cora: "Assembly(Microscope) presenting the Detector Role; Optics sub-assembly = turret + objectives + selector. The camera and propagation_distance slots are left empty (shared cameras + DetectorGantry rail)." - note: "large-field-of-view microscope; Optique Peter housing, model is the 2-BM candidate pending TomoWISE confirmation (DET-2)" - constituents: - - name: Turret - family: LinearStage - new: true - confirm: true - note: "objective changer: switches objectives without intervening in the setup (TDR p57)" - - name: Objective_1x - family: Objective - new: true - confirm: true - magnification: 1.0 - - name: Objective_2x - family: Objective - new: true - confirm: true - magnification: 2.0 - - name: ObjectiveSelector - family: PseudoAxis - new: true - confirm: true - note: "virtual objective picker over the turret" - - name: Scintillator - family: Scintillator - new: true - confirm: true - material: LSO or LuAG:Ce - thickness: 7 to 15 um - - name: MicHR - family: Housing - model: optique_peter_micrx080 - new: true - confirm: true - magnification: 4x / 10x / 20x - numerical_aperture: ">0.4" - cora: "Assembly(Microscope) presenting the Detector Role; Optics sub-assembly = turret + objectives + selector. The camera and propagation_distance slots are left empty (shared cameras + DetectorGantry rail)." - note: "high-resolution microscope; Optique Peter housing, model is the 2-BM candidate pending TomoWISE confirmation (DET-2)" - constituents: - - name: Turret - family: LinearStage - new: true - confirm: true - note: "objective changer: switches objectives without intervening in the setup (TDR p57)" - - name: Objective_4x - family: Objective - new: true - confirm: true - magnification: 4.0 - - name: Objective_10x - family: Objective - new: true - confirm: true - magnification: 10.0 - - name: Objective_20x - family: Objective - new: true - confirm: true - magnification: 20.0 - - name: ObjectiveSelector - family: PseudoAxis - new: true - confirm: true - note: "virtual objective picker over the turret" - - name: Scintillator - family: Scintillator - new: true - confirm: true - material: LuAG:Ce - thickness: 7 to 15 um - - name: CameraI - family: Camera - new: true - confirm: true - sensor: 16-25 Mpix, 16-bit sCMOS - framerate: 100-150 fps - note: "medium-speed camera; model TBD (DET-1)" - - name: CameraII - family: Camera - new: true - confirm: true - sensor: 4 Mpix, 12-bit CMOS - framerate: ">50000 fps" - note: "high-speed camera; model TBD (DET-1)" - - name: CameraIII - family: Camera - new: true - confirm: true - sensor: ~4 Mpix - framerate: ">2000 fps" - note: "streaming camera; model TBD (DET-1)" - - name: CameraIV - family: Camera - new: true - confirm: true - sensor: 150 Mpix, 54 x 40 mm, 3.76 um pixel - note: "large-sensor camera; matches the device procured for DanMAX (DET-1)" - -# Cross-cutting drive electronics and triggering. MAX IV runs Tango/Sardana; -# control handles and the trigger conditioner are TBD. -controls: - intro: > - The control stack is MAX IV Tango/Sardana with PandABox-class hardware - (per the DanMAX collaboration); PV/attribute handles are not yet assigned - (CTRL-1). - triggering: - - name: Triggering - family: TimingController - new: true - confirm: "rotary RT100AX TTL (3600 pulses/rev) is the master clock, expected to feed camera triggers directly; no FPGA conditioner specified, may evolve (TRIG-1)" - note: "trigger/sync scheme" - -# Continuously-available resources a run draws on (design phase). -resources: - intro: > - The continuously-available facility resources a run needs present before it - can start. All pending confirmation in the design phase. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum diff --git a/deployments/tps-05a/beamline.yaml b/deployments/tps-05a/beamline.yaml deleted file mode 100644 index 517cf60485d..00000000000 --- a/deployments/tps-05a/beamline.yaml +++ /dev/null @@ -1,214 +0,0 @@ -# TPS 05A beamline descriptor (NSRRC, Taiwan Photon Source), reverse-engineered -# -# TPS 05A is the NSRRC protein-microcrystallography beamline: rotation (oscillation) -# MX on an Arinax MD3 microdiffractometer goniometer reading a DECTRIS EIGER2 X 9M, -# with an ISARA robot mounting samples for unattended high-throughput collection. It -# is bound to the NSRRC Site (deployments/nsrrc/site.yaml) and is the MX-cluster -# sibling of TPS 07A (deployments/tps-07a/beamline.yaml): the same SPXF group runs the -# same Blu-Ice/DCSS stack on the same MD3 + ISARA kit, the difference being the EIGER2 -# X 9M detector (vs 07A's 16M) and the microcrystallography focus. -# -# STATUS: reverse-engineered, design-phase, REUSE-AND-REINFORCE. TPS 05A's public -# source is thinner than 07A's: the SPXF facility pages enumerate it (EIGER2 X 9M + -# ISARA), and the 2025 J. Synchrotron Rad. paper (Chou et al.) covers all three NSRRC -# MX endstations (TPS 05A, TPS 07A, TLS 15A1) as one Blu-Ice/DCSS family, but there is -# NO dedicated 05A control tree (light911/NSRRC_TPS05A_BeamMonitor is an empty stub). -# So 05A's device facts are read from the SPXF pages + the shared-cluster paper, and -# the seam / control model is inherited from the 07A reading (light911/NSRRC_TPS07A + -# TPS07A-Meshbest), confirmed to apply by the cluster paper. Carried `confirm: true` -# pending NSRRC staff. -# -# PV HONESTY: 05A has NO public PV namespace verified (unlike 07A's 07a: / 07a-ES:, -# which were read from the 07A tree). By cluster convention the 05A namespace is -# expected to be 05a: / 05a-ES:, but that is INFERRED, not read from source, so it is -# carried as a confirm note and no PV record string is asserted as a literal. This is -# the most conservative PV posture in the fleet, appropriate to the thin source. -# -# THE SEAM (inherited from 07A, the 2-BM pattern): EPICS is the control FLOOR (the MD3, -# EIGER2, optics reachable as EPICS PVs via an EPICS Device Handler Server), and the -# SCAN ORCHESTRATION on top is Blu-Ice/DCSS (the SSRL Distributed Control System -# lineage; a DCSS server per beamline, reached by a DHS bridge). CORA's EdgeConductor -# would REPLACE the DCSS scan/oscillation orchestration over the EPICS floor, the 2-BM -# TomoScan seam. Confirmed Blu-Ice/DCSS (not MXCuBE) for the whole MX cluster by Chou -# et al., J. Synchrotron Rad. 2025. See docs/deployments/tps-05a/equipment/controls.md. -# -# It introduces NO new catalog family: every device reuses an existing Family exactly -# as TPS 07A does (the graduated Goniometer for the MD3, Camera for the EIGER2 / OAV, -# Monochromator for the DCM, Filter for the attenuator, BeamStop, Shutter, LinearStage, -# MotionController, TemperatureController, plus the loose StorageRing and -# PositionMonitor). The ISARA robot is a deferred sample-exchange Procedure -# (ROBOT-1). No Capability or Method is coined; the rotation-MX techniques reuse the -# pending i03 Methods recorded as Practices on the Site. 05A is a pure reuse deployment -# whose value is reinforcing that one device-library + one seam generalizes across the -# NSRRC MX cluster. - -beamline: - maturity: model - evidence: narrative - coverage: full - summary: "protein microcrystallography (rotation MX) on the same MD3 + ISARA kit with a DECTRIS EIGER2 X 9M; the MX-cluster sibling of 07A, a reuse-and-reinforce deployment coining no new vocabulary, modelled from the SPXF pages + the 2025 cluster paper (thinner source, PV namespace inferred)" - name: TPS 05A - facility: nsrrc # NSRRC Site (facility_code: nsrrc) - sector: "05a" # EPICS PV namespace INFERRED 05a: / 05a-ES: (not read from source; 07A's was verified, 05A's is by cluster convention, PV-1) - tier: Unit - parent: null - source: insertion-device - source_confirm: "TPS 05A is fed by a TPS undulator (per the SPXF spec page); the front-end / insertion-device PV is not in any public source, so the source is carried generically and the ring-current monitor stands in as the source representation (SRC-1)" - page_layout: stages - shape: "NSRRC's protein-microcrystallography beamline, the MX-cluster sibling of TPS 07A: the same Blu-Ice / DCSS stack and MD3 + ISARA kit with a DECTRIS EIGER2 X 9M detector." - source_ref: - label: "nsrrcspxf docs" - url: "https://nsrrcspxf.github.io/nsrrcspxf/index.html" - -enclosures: - # No public source exposes the 05A hutch layout. MX beamlines run an optics hutch - # plus an experiment hutch; the hutch names and the PSS permit leaves are a staff - # question (ENC-1, PSS-1). - - name: TPS-05A-OH - role: optics-hutch - facility_code: nsrrc - permit_signal: {confirm: "PSS permit leaf not in public source; the optics hutch carries the DCM and beam-conditioning optics (PSS-1, ENC-1)"} - - name: TPS-05A-EH - role: experiment-hutch - facility_code: nsrrc - permit_signal: {confirm: "PSS permit leaf not in public source; the experiment hutch carries the MD3 microdiffractometer, the EIGER2 X 9M, and the ISARA robot (PSS-1, ENC-1)"} - -# =========================================================================== -# SOURCE STAGE: the storage ring and the front-end shutter -# =========================================================================== - -source: - stage: source - enclosure: TPS-05A-OH - intro: "The storage-ring source-current monitor and the front-end shutter. The undulator source itself is not in any public source (SRC-1)." - devices: - - name: StorageRing - family: StorageRing # loose Family (facility source representation) - confirm: true - note: "TPS storage-ring beam-current monitor (the source-side representation). The undulator is not exposed publicly (SRC-1). Reuses the loose StorageRing family; PV pending (DIAG-1)." - - name: WhiteBeamShutter - family: Shutter - confirm: true - note: "Front-end photon shutter (a PSS shutter) gating the white beam into the optics hutch. PV pending; PSS permit-leaf signal not in public source (PSS-1)." - -# =========================================================================== -# OPTICS STAGE: the monochromator, the energy axis, the attenuators -# =========================================================================== - -optics: - stage: source - enclosure: TPS-05A-OH - intro: "Set the energy and condition the beam: the double-crystal monochromator over the MX range (~5.7-20 keV per the SPXF page), the master energy axis, and the attenuator. The expected 05a: PV namespace is inferred (PV-1); per-record names are pending (OPT-1, DCM-1)." - devices: - - name: Monochromator - family: Monochromator - confirm: true - note: "Double-crystal monochromator (Si) selecting ~5.7-20 keV for MX (the SPXF page states the 05A energy range). Reuses the Monochromator family; crystal cut, range bounds, and the energy PV are pending (DCM-1)." - - name: EnergyAxis - family: PseudoAxis - confirm: true - note: "The master beamline energy setpoint the monochromator tracks. Whether energy is scanned as the measurement (anomalous / MAD MX) or set fixed per dataset is ENERGY-1." - - name: Attenuators - family: Filter - confirm: true - note: "Attenuator / transmission unit (foil set) trimming the incident flux for dose control. Reuses the Filter family; foil set and PV pending (DCM-1)." - - name: KBMirrors - family: Mirror - confirm: true - note: "Focusing mirror system delivering the microcrystallography beam (a KB pair is the standard MX micro-focus optic; the focal spot is not stated in public source for 05A). Reuses the Mirror family; mirror configuration, spot size, and PVs pending (OPT-1)." - -# =========================================================================== -# SAMPLE STAGE: the MD3 microdiffractometer goniometer, environment, robot -# =========================================================================== - -sample: - stage: sample - enclosure: TPS-05A-EH - intro: "The Arinax MD3 microdiffractometer goniometer that holds and orients the crystal, the cryostream sample cooling, and the beamstop. As at TPS 07A, the MD3 is reached as EPICS PVs through the DCSS / DHS bridge (no separate transport)." - note: > - TPS 05A holds a cryocooled crystal on the MD3 microdiffractometer and rotates it - through an oscillation while the EIGER2 X 9M reads frames, the same shape as TPS - 07A. The MD3 goniometer reuses the graduated Goniometer family (the i03 / 07A / MX3 - MX precedent). It is reached through the EPICS Device Handler Server (the 07A - pattern, applied to the cluster per the J. Synchrotron Rad. 2025 paper), so it is - on the EPICS floor; the DCSS server orchestrates the oscillation above that floor. - The ISARA sample robot is modelled as a deferred Procedure (sample exchange), not a - device, per the i03 / i24 / 07A / MX3 ROBOT-1 precedent. - devices: - - name: Goniometer - family: Goniometer - confirm: true - note: "Arinax MD3 microdiffractometer goniometer with a mini-kappa: omega rotation plus kappa / phi, sample centring, and alignment. Reuses the graduated Goniometer family. Reached as EPICS PVs via the DHS bridge (the inferred 05a-ES: endstation namespace); axis PV records pending (GONIO-1, PV-1)." - - name: SampleTemperature - family: TemperatureController - confirm: true - note: "Cryostream sample cooling keeping the crystal at cryogenic temperature through the dataset. Reuses the TemperatureController family (graduated #350); PV and vendor pending (ENV-1)." - - name: BeamStop - family: BeamStop - confirm: true - note: "Beamstop blocking the direct beam at the sample. Reuses BeamStop; PV pending (DIAG-1)." - -# =========================================================================== -# DETECTION STAGE: the EIGER2, the detector stage, the OAV camera, diagnostics -# =========================================================================== - -detector: - stage: detection - enclosure: TPS-05A-EH - intro: "The DECTRIS EIGER2 X 9M area detector and its translation stage, the on-axis viewing camera, and the beam-position diagnostics. Acquisition is commanded through the DCSS workflow, the 07A pattern with a 9M detector." - note: > - The EIGER2 X 9M reads the rotation frames. Its acquisition is commanded through the - Blu-Ice/DCSS workflow (the EPICS floor), as at TPS 07A; the frame egress and any - spot-scoring / indexing is Observe / Compute work, off the control seam. The 05A - detector model (EIGER2 X 9M) is from the SPXF page; per-device PVs and the SIMPLON - endpoint are not in public source (DET-1). - devices: - - name: EigerDetector - family: Camera - confirm: true - note: "DECTRIS EIGER2 X 9M area detector reading the rotation-MX frames (the SPXF page names the 9M for 05A, vs 07A's 16M). Reuses Camera. Driven through the DCSS / DHS workflow over the EPICS floor; detector PVs / SIMPLON endpoint pending (DET-1)." - - name: DetectorStage - family: LinearStage - confirm: true - note: "Detector translation setting the sample-to-detector distance. Reuses LinearStage; PV and any minimum-distance interlock pending (DET-1)." - - name: BeamPositionMonitor - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1) - confirm: true - note: "Diagnostic beam-position monitor (the XBPM / DBPM diagnostics class seen across TPS front ends). Binds the graduated PositionMonitor Family (DIAG-1); channel map / PV pending." - - name: OAVCamera - family: Camera - confirm: true - note: "On-axis viewing camera for sample centring on the MD3. Reuses Camera; PV pending (DIAG-1)." - -# =========================================================================== -# Cross-cutting controls -# =========================================================================== - -controls: - intro: > - The shutters that gate the exposure and the endstation motion control, plus the - seam inherited from TPS 07A: an EPICS floor with a Blu-Ice/DCSS orchestration layer - above it, bridged by an EPICS Device Handler Server. - triggering: - - name: FastShutter - family: Shutter - confirm: true - note: "Fast shutter gating the per-oscillation exposure at the sample, synchronized with the omega sweep and the EIGER2 frames. PV pending; the trigger wiring is recipe-layer (deferred at this design phase)." - motion_controllers: - - name: EndstationMotionController - family: MotionController - confirm: true - note: "The endstation, goniometer-base, and detector stages run on EPICS motor records reached through the DHS bridge; controller box firmware / IPs not in any public source (DRIVE-1)." - software_iocs_not_modeled: - [DCSS-server, EPICS-DHS, ISARA-robot, DECTRIS-SIMPLON] - -resources: - intro: Continuously-available resources. Facility-scope supplies live in deployments/nsrrc/site.yaml. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: LiquidNitrogen # cryostream - - kind: Power - replaceable_parts: - swappable_with_identity: ["sample pucks", "EIGER2 detector", "attenuator foils"] diff --git a/deployments/tps-07a/beamline.yaml b/deployments/tps-07a/beamline.yaml deleted file mode 100644 index ef84c4f4521..00000000000 --- a/deployments/tps-07a/beamline.yaml +++ /dev/null @@ -1,219 +0,0 @@ -# TPS 07A beamline descriptor (NSRRC, Taiwan Photon Source), reverse-engineered -# -# TPS 07A is the NSRRC micro-focus protein-crystallography beamline: rotation -# (oscillation) MX on an Arinax MD3 microdiffractometer goniometer reading a DECTRIS -# EIGER2 X 16M, with an ISARA robot mounting samples for unattended high-throughput -# collection. It is bound to the NSRRC Site (deployments/nsrrc/site.yaml). Its source -# is the TPS IU22 in-vacuum undulator feeding a double-crystal monochromator over the -# 6-20 keV range, focused to a ~2.9 x 1.8 micron spot. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the light911/NSRRC_TPS07A control tree + light911/TPS07A-Meshbest -# mesh-scan/data-collection app, the SPXF facility pages, and JACoW proceedings) or -# inferred, carried `confirm: true` pending NSRRC staff. -# -# PV HONESTY: unlike a curated device library, the 07A source is an operational -# working tree. The EPICS PV NAMESPACE is verified (the beamline at 07a:, the -# endstation at 07a-ES:), and the device set (MD3, EIGER2, ISARA, DCM) is real and -# read from the code, but per-device PV record strings are NOT individually verified. -# Devices therefore carry the verified prefix namespace, with the concrete record -# names pending (a deliberate contrast with the MX3 descriptor, whose literal PVs were -# file-verified against a device library). No PV string here is invented as a literal. -# -# THE DISTINCTIVE FACT (the seam, and why 07A was chosen): EPICS is the control FLOOR -# (the MD3, EIGER2, slits, attenuators, DBPMs all reachable as EPICS PVs via an EPICS -# Device Handler Server), but the SCAN ORCHESTRATION on top is Blu-Ice/DCSS (the SSRL -# Distributed Control System lineage): a DCSS server per beamline, reached by a DHS -# bridge (the EpicsDHS / DCSDHS class, dcss host 10.7.1.1 port 14242) that translates -# the DCS protocol (stoh_start_oscillation, stoh_start_motor_move, collectRuns) into -# EPICS caput/caget. This is the 2-BM TomoScan seam, not the MX3 multi-transport seam: -# one EPICS floor with an orchestration layer above it. CORA's EdgeConductor would -# REPLACE the DCSS scan/oscillation/collectRuns orchestration over the EPICS floor, -# the direct analog of replacing TomoScan's scan/alignment orchestration. This is -# confirmed live (not MXCuBE) by Chou et al., J. Synchrotron Rad. 2025, and by the -# NSRRC code (repos last pushed 2025-12-22, zero mxcubecore presence). See -# docs/deployments/tps-07a/equipment/controls.md. -# -# It introduces NO new catalog family: the MD3 goniometer reuses the graduated -# Goniometer family (the i03 / MX3 MX precedent), the EIGER2 and the OAV camera Camera, -# the DCM Monochromator, the cryostream TemperatureController, the attenuator Filter, -# the beamstop BeamStop, the shutters Shutter, the stages LinearStage / MotionController. -# Two loose families are reused (both allowlisted): StorageRing (the ring-current -# monitor) and PositionMonitor (the diagnostic BPM / XBPM). The ISARA robot is -# modelled as a deferred Procedure (sample exchange), not a device family (the i03 / -# i24 / MX3 ROBOT-1 precedent). No Capability or Method is coined; the rotation-MX -# techniques reuse the pending i03 Methods (mx_data_collection / grid_scan / -# sample_exchange) recorded as Practices on the Site. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "micro-focus protein crystallography (rotation MX) on an Arinax MD3 + DECTRIS EIGER2 X 16M with an ISARA robot; reuses the i03 / MX3 Goniometer and MX Methods, novelty is the Site and its Blu-Ice/DCSS-over-EPICS orchestration seam (the 2-BM pattern, confirmed live over MXCuBE)" - name: TPS 07A - facility: nsrrc # NSRRC Site (facility_code: nsrrc) - sector: "07a" # EPICS PV namespace 07a: (endstation at 07a-ES:) - tier: Unit - parent: null - source: insertion-device - source_confirm: "TPS 07A is fed by the TPS IU22 in-vacuum undulator (per the SPXF spec page); the front-end / insertion-device PV is not in the public control tree, so the source is carried generically and the ring-current monitor stands in as the source representation (SRC-1)" - page_layout: stages - shape: "NSRRC's Taiwan MX beamline: micro-focus macromolecular crystallography on a single EPICS floor with a Blu-Ice / DCSS orchestration layer CORA's edge would replace, the 2-BM seam rather than the MX3 seam." - source_ref: - label: "light911/NSRRC_TPS07A" - url: "https://github.com/light911/NSRRC_TPS07A" - -enclosures: - # The control tree exposes no enclosure / hutch layout. MX beamlines run an optics - # hutch plus an experiment hutch; the hutch names and the PSS permit leaves are a - # staff question (ENC-1, PSS-1). - - name: TPS-07A-OH - role: optics-hutch - facility_code: nsrrc - permit_signal: {confirm: "PSS permit leaf not in public source; the optics hutch carries the DCM and beam-conditioning optics (PSS-1, ENC-1)"} - - name: TPS-07A-EH - role: experiment-hutch - facility_code: nsrrc - permit_signal: {confirm: "PSS permit leaf not in public source; the experiment hutch carries the MD3 microdiffractometer, the EIGER2, and the ISARA robot (PSS-1, ENC-1)"} - -# =========================================================================== -# SOURCE STAGE: the storage ring and the front-end shutter -# =========================================================================== - -source: - stage: source - enclosure: TPS-07A-OH - intro: "The storage-ring source-current monitor and the front-end shutter. The IU22 undulator source itself is not in the public control tree (SRC-1)." - devices: - - name: StorageRing - family: StorageRing # loose Family (facility source representation) - confirm: true - note: "TPS storage-ring beam-current monitor (the source-side representation). The IU22 in-vacuum undulator is not exposed in the public 07A tree (SRC-1). Reuses the loose StorageRing family; PV pending (DIAG-1)." - - name: WhiteBeamShutter - family: Shutter - confirm: true - note: "Front-end photon shutter (a PSS shutter) gating the white beam into the optics hutch. PV pending; PSS permit-leaf signal not in public source (PSS-1)." - -# =========================================================================== -# OPTICS STAGE: the monochromator, the energy axis, the attenuators -# =========================================================================== - -optics: - stage: source - enclosure: TPS-07A-OH - intro: "Set the energy and condition the beam: the double-crystal monochromator over 6-20 keV, the master energy axis, and the attenuator. The 07A PV namespace is 07a:; per-record names are pending (OPT-1, DCM-1)." - devices: - - name: Monochromator - family: Monochromator - confirm: true - note: "Double-crystal monochromator (Si) selecting 6-20 keV for MX. Reuses the Monochromator family; crystal cut, range bounds, and the energy PV record are pending (DCM-1)." - - name: EnergyAxis - family: PseudoAxis - confirm: true - note: "The master beamline energy setpoint the monochromator tracks. Whether energy is scanned as the measurement (anomalous / MAD MX) or set fixed per dataset is ENERGY-1." - - name: Attenuators - family: Filter - confirm: true - note: "Attenuator / transmission unit (foil set) trimming the incident flux for dose control. Reuses the Filter family; foil set and PV pending (DCM-1)." - - name: KBMirrors - family: Mirror - confirm: true - note: "Micro-focus mirror system delivering the ~2.9 x 1.8 micron spot at the sample (a KB pair is the standard micro-focus optic; the SPXF page states the focal spot, not the optic). Reuses the Mirror family; mirror configuration and PVs pending (OPT-1)." - -# =========================================================================== -# SAMPLE STAGE: the MD3 microdiffractometer goniometer, environment, robot -# =========================================================================== - -sample: - stage: sample - enclosure: TPS-07A-EH - intro: "The Arinax MD3 microdiffractometer goniometer that holds and orients the crystal, the cryostream sample cooling, and the beamstop. The MD3 is reached as EPICS PVs through the DCSS / DHS bridge (no separate transport, unlike MX3's Exporter)." - note: > - TPS 07A holds a cryocooled crystal on the MD3 microdiffractometer and rotates it - through an oscillation while the EIGER2 reads frames. The MD3 goniometer reuses the - graduated Goniometer family (the i03 / MX3 MX precedent). Unlike MX3 (which drives - the MD3 over the MXCuBE Exporter protocol), 07A reaches the MD3 through the EPICS - Device Handler Server, so it is on the EPICS floor; the DCSS server orchestrates - the oscillation above that floor (the seam CORA replaces). The ISARA sample robot - is modelled as a deferred Procedure (sample exchange), not a device, per the i03 / - i24 / MX3 ROBOT-1 precedent. - devices: - - name: Goniometer - family: Goniometer - confirm: true - note: "Arinax MD3 microdiffractometer goniometer with a mini-kappa: omega rotation plus kappa / phi, sample centring (CentringX / Y), and alignment (AlignmentX / Y / Z). Reuses the graduated Goniometer family. Reached as EPICS PVs via the DHS bridge (07a-ES: endstation namespace); per-axis PV records pending (GONIO-1)." - - name: SampleTemperature - family: TemperatureController - confirm: true - note: "Cryostream sample cooling keeping the crystal at cryogenic temperature through the dataset. Reuses the TemperatureController family (graduated #350); PV and vendor pending (ENV-1)." - - name: BeamStop - family: BeamStop - confirm: true - note: "Beamstop blocking the direct beam at the sample. Reuses BeamStop; PV pending (DIAG-1)." - -# =========================================================================== -# DETECTION STAGE: the EIGER2, the detector stage, the OAV camera, diagnostics -# =========================================================================== - -detector: - stage: detection - enclosure: TPS-07A-EH - intro: "The DECTRIS EIGER2 X 16M area detector and its translation stage, the on-axis viewing camera, and the beam-position diagnostics. The EIGER2 streams over ZMQ (migrating to DESY ASAP::O) into the mesh-scan / Dozor analysis path; control is through the DCSS workflow." - note: > - The EIGER2 X 16M reads the rotation frames at up to 130 Hz. Its acquisition is - commanded through the DCSS / DHS workflow (the EPICS floor), and frames egress over - a ZMQ stream, with a late-2025 ASAP::O frame-ingestion path feeding Dozor spot - scoring and CHiMP crystal detection for mesh scans. CORA treats the frame egress as - a TransferPort leg and the Dozor / CHiMP scoring as ComputePort work, OFF the - control seam (it is Observe / Compute, not Actuate). The detector minimum-distance - interlock (139 mm) is a hard safety limit read from the control tree. - devices: - - name: EigerDetector - family: Camera - confirm: true - note: "DECTRIS EIGER2 X 16M area detector (~130 Hz) reading the rotation-MX frames. Frames stream over ZMQ (writers for HDF5/NeXus, CBF, TIFF; migrating to DESY ASAP::O). Reuses Camera. Driven through the DCSS / DHS workflow over the EPICS floor; SIMPLON endpoint / detector PVs pending (DET-1)." - - name: DetectorStage - family: LinearStage - confirm: true - note: "Detector translation setting the sample-to-detector distance, with a hard minimum-distance interlock at 139 mm read from the control tree. Reuses LinearStage; PV pending (DET-1)." - - name: BeamPositionMonitor - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1) - confirm: true - note: "Diagnostic beam-position monitor (the XBPM / DBPM diagnostics class seen across TPS front ends). Binds the graduated PositionMonitor Family (DIAG-1); channel map / PV pending." - - name: OAVCamera - family: Camera - confirm: true - note: "On-axis viewing camera for sample centring on the MD3. Reuses Camera; PV pending (DIAG-1)." - -# =========================================================================== -# Cross-cutting controls -# =========================================================================== - -controls: - intro: > - The shutters that gate the exposure and the endstation motion control, plus the - defining seam: an EPICS floor with a Blu-Ice/DCSS orchestration layer above it, - bridged by an EPICS Device Handler Server. - triggering: - - name: FastShutter - family: Shutter - confirm: true - note: "Fast shutter gating the per-oscillation exposure at the sample, synchronized with the omega sweep and the EIGER2 frames. PV pending; the trigger wiring is recipe-layer (deferred at this design phase)." - motion_controllers: - - name: EndstationMotionController - family: MotionController - confirm: true - note: "The endstation, goniometer-base, and detector stages run on EPICS motor records reached through the DHS bridge; controller box firmware / IPs not in the public tree (DRIVE-1)." - software_iocs_not_modeled: - [DCSS-server, EPICS-DHS, ISARA-robot, DECTRIS-SIMPLON, ASAP::O, Dozor, CHiMP] - -resources: - intro: Continuously-available resources. Facility-scope supplies live in deployments/nsrrc/site.yaml. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: LiquidNitrogen # cryostream - - kind: Power - replaceable_parts: - swappable_with_identity: ["sample pucks", "EIGER2 detector", "attenuator foils"] diff --git a/deployments/xfm/beamline.yaml b/deployments/xfm/beamline.yaml deleted file mode 100644 index be22e751284..00000000000 --- a/deployments/xfm/beamline.yaml +++ /dev/null @@ -1,180 +0,0 @@ -# XFM beamline descriptor (NSLS-II), reverse-engineered -# -# XFM (X-ray Fluorescence Microprobe) is the NSLS-II scanning-XRF microprobe at sector -# 4-BM, a BENDING-MAGNET beamline. It rasters a sample through a focused beam and reads -# element maps on a multi-element silicon-drift detector (an Xspress3), with a Maia -# continuous-mapping array for fast fly-scan mapping. It is bound to the NSLS-II Site -# (deployments/nsls2/site.yaml), the fifteenth NSLS-II beamline after FXI, HXN, BMM, -# SRX, SIX, CHX, CSX, XPD, ESM, SMI, IXS, SST, ISS, FMX. -# -# STATUS: reverse-engineered, design-phase. The public profile collection -# (NSLS2/xfm-profile-collection) is MINIMAL: it exposes only the endstation, the UTS -# raster stage, the Xspress3 fluorescence detector, and the SIS3820 scaler, plus a Maia -# detector in a bypass file. The source, monochromator, focusing optic, and shutters are -# NOT in the profile, so they are carried confirm-only with NO PV (the 2-ID thin-source -# precedent; zero fabricated PVs). The endstation PVs are real and verified against the -# startup/*.py device classes. Same descriptor mode as the other NSLS-II beamlines: -# descriptor + docs, scenarios deferred. -# -# XFM is a PURE-REUSE deployment: it coins NO new Family and graduates nothing. The SDD -# fluorescence detectors reuse EnergyDispersiveSpectrometer (the 2-ID / SRX scanning-XRF -# vocabulary), the raster stage LinearStage, the scaler I0 channels FluxMonitor, the -# bending-magnet source the loose Beam PhotonBeam supply (the 2-BM / BMM precedent), and -# the DCM / focusing optic / slits the catalog Monochromator / Mirror / Slit. The -# scanning XRF technique reuses the scanning_fluorescence_microscopy Method 2-ID left -# pending: XFM is its SECOND consumer, which strengthens but does not coin it (Methods -# have no mechanical promotion; the energy_scan deferral discipline; METHOD-1 / TECH-1). -# XANES microspectroscopy leans on the deferred energy_scan Capability (ENERGY-1). - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "scanning X-ray fluorescence microprobe (raster XRF mapping on the Xspress3 + Maia detectors, bending magnet), 4-BM; CORA's 2nd scanning-XRF after 2-ID; modelled from public beamline config" - name: XFM - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "Sector 4" # PV namespace XF:04BM* (the endstation zone is 04BMC) - tier: Unit - parent: null - source: bending-magnet - source_confirm: "4-BM bending-magnet source; not an insertion device. The profile collection exposes only the endstation (the raster stage + detectors), not the source / optics, so those are carried confirm-only (SRC-1, PROFILE-1)." - page_layout: stages - shape: "A scanning X-ray fluorescence microprobe: it rasters the sample through a focused spot and reads the fluorescence spectrum per point, with a Maia array for fast fly-scan mapping." - source_ref: - label: "NSLS2/xfm-profile-collection" - url: "https://github.com/NSLS2/xfm-profile-collection" -enclosures: - # 4-BM has an optics enclosure and the experiment endstation. The endstation PV zone is - # XF:04BMC (the UTS stage and Xspress3); the optics zone (XF:04BMA) is inferred, not in - # the profile. The hutch names / numbering and the A/B/C layout are not in source. - - name: 4-BM-A - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS search-and-secure permit leaf and shutter PVs not in the profile collection (PSS-1, PROFILE-1)"} - - name: 4-BM-C - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; 4-BM-C (PV zone XF:04BMC) is the endstation carrying the raster stage and the fluorescence detectors. Hutch layout to confirm (PSS-1, ENC-1)"} - -# =========================================================================== -# SOURCE STAGE: the bending-magnet source and the shutters -# =========================================================================== - -source: - stage: source - enclosure: 4-BM-A - intro: The bending-magnet source and the front-end / photon shutters. - devices: - - name: Source - family: Beam - new: true - confirm: true - note: "4-BM bending-magnet source, recorded as a PhotonBeam Supply, not an Asset (the 2-BM / BMM precedent). Beam-parameter machine state is on SR:C04." - - name: FrontEndShutter - family: Shutter - confirm: "front-end safety shutter; PPS-gated. PV not in the profile collection (PSS-1, PROFILE-1)" - note: "Front-end photon shutter (not exposed in the profile collection)." - - name: PhotonShutter - family: Shutter - confirm: "photon shutter into the optics; PV not in the profile collection (PSS-1, PROFILE-1)" - note: "Photon shutter gating the beam into the optics (not exposed in the profile collection)." - -# =========================================================================== -# OPTICS STAGE: the monochromator, the focusing optic, the slits (confirm-only) -# =========================================================================== - -optics: - stage: source - enclosure: 4-BM-A - intro: "Condition the beam and set its energy: the double-crystal monochromator, the microfocusing optic, and the beam-defining slits. These are not exposed in the profile collection (which carries only the endstation), so they are carried confirm-only with no fabricated PV (PROFILE-1)." - devices: - - name: Monochromator - family: Monochromator - confirm: "the 4-BM double-crystal monochromator (Si(111) is the known 4-BM crystal); the energy actuator for XRF / XANES. PV and crystal set not in the profile collection (DCM-1, PROFILE-1)" - note: "Double-crystal monochromator selecting the incident energy. Reuses the Monochromator family. Not exposed in the profile collection (DCM-1)." - - name: FocusingOptic - family: Mirror - confirm: "the microfocusing optic (KB mirror pair or capillary) that forms the microprobe spot; type and PV not in the profile collection (OPT-1, PROFILE-1)" - note: "Beam-focusing optic forming the microprobe. Reuses the Mirror family. Not exposed in the profile collection (OPT-1)." - - name: BeamDefiningSlit - family: Slit - confirm: "beam-defining slit(s) ahead of the focusing optic; PV not in the profile collection (PROFILE-1)" - note: "Beam-defining slit. Reuses the Slit family. Not exposed in the profile collection." - - name: EnergyAxis - family: PseudoAxis - confirm: "the master energy axis (the DCM energy); XANES microspectroscopy sweeps it across an edge. PV not in the profile collection (ENERGY-1, PROFILE-1)" - note: "The master energy axis driving the monochromator. XANES microspectroscopy sweeps it; that energy sweep leans on the deferred energy_scan Capability (ENERGY-1, the BMM question)." - -# =========================================================================== -# SAMPLE STAGE: the raster scanning stage -# =========================================================================== - -sample: - stage: sample - enclosure: 4-BM-C - intro: "The raster scanning stage that moves the sample through the focused spot for XRF mapping. PV verified against the xfm-profile-collection startup files." - devices: - - name: SampleStage - family: LinearStage - pv: "XF:04BMC-ES:2{UTS:1-Ax:" - confirm: true - note: "The UTS X / Y / Z raster stage (XF:04BMC-ES:2{UTS:1-Ax:X / Y / Z}Mtr) that scans the sample through the microprobe spot, point-by-point (step) or continuously (Maia fly). The signature scanning device; reuses the LinearStage family. Coarse / fine piezo split, if any, to confirm." - -# =========================================================================== -# DETECTION STAGE: the fluorescence detectors and the flux scaler -# =========================================================================== - -detector: - stage: detection - enclosure: 4-BM-C - intro: "The multi-element fluorescence detectors that make the XRF maps, and the scaler-counted flux channels. PVs verified against the xfm-profile-collection startup files." - note: > - Which detector is read sets the mapping mode: the Xspress3 silicon-drift detector - for step / fly XRF mapping, or the Maia array for fast continuous mapping. Both bind - the catalog EnergyDispersiveSpectrometer. The scaler counts the I0 flux channels for - normalization. - devices: - - name: FluorescenceDetector - family: EnergyDispersiveSpectrometer - pv: "XF:04BMC-ES{x3m:1}:" - confirm: true - note: "Four-channel silicon-drift fluorescence detector read by an Xspress3 mini (XF:04BMC-ES{x3m:1}: channels C1-C4, per-channel ROIs, an HDF5 stream). The primary XRF-mapping detector; reuses the EnergyDispersiveSpectrometer family. Element count and ROI map to confirm (DET-1)." - - name: MaiaDetector - family: EnergyDispersiveSpectrometer - pv: "XFM:MAIA" - confirm: "the Maia continuous-mapping detector array (XFM:MAIA); read from the bypass profile (rvt/bypass40-maia.py), not the active startup. Element count and live status to confirm (MAIA-1)" - note: "The Maia 384-element detector array for fast continuous (fly-scan) XRF mapping, XFM's signature mapping capability. Reuses the EnergyDispersiveSpectrometer family (a large continuous-readout array variant). Carried from the bypass profile (MAIA-1)." - - name: FluxMonitor - family: FluxMonitor - pv: "XF:04BM-ES:2{Sclr:1}" - confirm: true - note: "The SIS3820 scaler (XF:04BM-ES:2{Sclr:1}) counting the I0 / flux channels for per-pixel normalization. Reuses the FluxMonitor family. The full channel map to confirm (DIAG-1)." - -# =========================================================================== -# Cross-cutting controls -# =========================================================================== - -controls: - intro: > - XFM acquires XRF maps by rastering the UTS stage while counting the detectors against - the SIS3820 scaler: step scans (bp.grid_scan) for point mapping, and a Maia - continuous fly-scan (encoder-driven) for fast mapping. There is no separate hardware - timing box in the profile collection; the scaler does the dwell / counting and the - Maia uses its own encoder feedback. Controller box models are not in source (DRIVE-1). - motion_controllers: - - name: StageMotionController - family: MotionController - confirm: "the UTS raster-stage motion controller; box model / firmware / IP not in the profile collection (DRIVE-1)" - note: "Drives the UTS raster stage (and the optics axes). Reuses the MotionController family. Not exposed in the profile collection (DRIVE-1)." - software_iocs_not_modeled: - [Xspress3, Maia, SIS3820, nslsii] - -resources: - intro: Continuously-available resources. Facility-scope supplies live in deployments/nsls2/site.yaml. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: Power - replaceable_parts: - swappable_with_identity: ["sample mounts", "the silicon-drift detector", "the Maia detector"] diff --git a/deployments/xfp/beamline.yaml b/deployments/xfp/beamline.yaml deleted file mode 100644 index 419f89e9a50..00000000000 --- a/deployments/xfp/beamline.yaml +++ /dev/null @@ -1,298 +0,0 @@ -# XFP beamline descriptor (NSLS-II), reverse-engineered -# -# XFP (X-ray Footprinting of Biological Materials) is the NSLS-II 17-BM beamline, -# a Case Western Reserve University partner beamline. It does synchrotron X-ray -# footprinting: an intense white / pink beam irradiates a biological macromolecule -# (protein or nucleic acid) in solution, generating hydroxyl radicals that -# covalently modify the molecule at solvent-accessible sites. The structural -# readout (which sites were modified) is done OFFLINE by mass spectrometry, not on -# the beamline. It is bound to the NSLS-II Site (deployments/nsls2/site.yaml). -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the beamline's own bluesky profile collection, github.com/NSLS2/ -# xfp-profile-collection, its startup/*.py device definitions) or inferred, carried -# new: true + confirm: true pending XFP staff. EPICS PVs are real and verified -# against the profile collection; vendor part numbers, serials, dose calibrations, -# and physical positions are not in it and are open questions. The syringe pumps -# and the fraction collector are PV-bound fluidic actuators; the high-throughput -# 96-well plate is addressed in pure Python (no robot, no PV) and the science -# readout (mass spec) is entirely offline. This scaffold is descriptor + docs, -# scenarios deferred. -# -# WHAT IS GENUINELY NEW: XFP is the fleet's first DOSE-DELIVERY beamline. It is not -# a scattering, diffraction, or imaging beamline and has NO scattering / area / -# imaging detector at all. The experiment variable is the delivered radiolytic DOSE -# (exposure time x incident flux x attenuation); the run produces (a) a footprinted -# SAMPLE, an irradiated aliquot captured into a tube, and (b) a DOSE RECORD -# (exposure time, filter thickness, flux time-series, well / tube identity). The -# structural analysis is the OFFLINE-readout seam: the mass spectrometry happens -# downstream, off the instrument. So the novelty lands on the Method (radiolytic -# footprinting), the Subject (a biomolecule in solution being irradiated), and the -# offline-readout seam, NOT on device vocabulary. -# -# MODELLING: XFP coins NO new Family and changes nothing in the catalog. 17-BM is a -# bending-magnet source (the 2-BM / 7-BM / CMS pattern), observed through the loose -# StorageRing; the footprinting beam is WHITE / pink (there is NO monochromator in -# the footprinting path, the only mono is a separate XAS endstation excluded here, -# WHITE-1). The bendable front-end mirror binds Mirror; the white-beam and defining -# slits bind Slit; the eight-position Al filter wheel binds Filter (it sets the dose -# rate); the personnel and timed dose shutters bind Shutter; the delay generator -# that fires the millisecond Uniblitz fast shutter binds TimingController (it sets -# the dose opening-time); the QuadEM electrometers bind FluxMonitor (incident flux -# to compute dose); the Sydor beam-position monitor binds the graduated -# PositionMonitor Family (DIAG-1); the capillary-flow, high- -# throughput, and HTFly sample stages bind LinearStage; the syringe / sample -# delivery pumps bind the graduated catalog FlowController Family. -# -# THE REUSE WORTH NAMING: the sample-delivery pumps bind the catalog FlowController -# Family (graduated; settable flow / pump actuator, presents the Regulator Role, the -# settable-actuator sibling of TemperatureController), bound by i22, 7-BM, and LIX. -# XFP is its FOURTH consumer; FlowController graduated on this rule-of-three across -# i22 / 7-BM / LIX / XFP. The wider fluidic chain beyond the pump stays in the -# ControlPort seam (FLUID-1). The fraction collector (a PV-bound aliquot-routing actuator), -# the 96-well plate addressing (pure Python, no PV), and the offline mass-spec -# readout are the sample-custody and offline-readout seam, not devices (FC-1, HT-1, -# READOUT-1). -# -# Items left open are tagged inline with a (QUESTION-ID) answered on -# docs/deployments/xfp/questions.md. - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "X-ray footprinting of biological macromolecules in solution (white/pink-beam radiolytic dose delivery, offline mass-spec readout), 17-BM; the fleet's first dose-delivery beamline (no scattering detector); modelled from public beamline config" - name: XFP - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "17-BM" # PV zones XF:17BM (beamline) / XF:17BMA (A-branch) / FE:C17B (front-end) - tier: Unit - parent: null - source: bending-magnet - source_confirm: "17-BM is a bending-magnet source (the name and the white-beam footprinting design imply it), but the profile collection exposes no source / dipole device, only the ring-current PV SR:OPS-BI{DCCT:1}I:Real-I. Source identity is SRC-1" - page_layout: stages - shape: "A dose-delivery beamline, not a measurement one: no imaging detector; it delivers a controlled radiolytic dose to a solution sample, the structural readout done offline by mass spectrometry." - source_ref: - label: "NSLS2/xfp-profile-collection" - url: "https://github.com/NSLS2/xfp-profile-collection" -# PV zones: FE:C17B (the front-end: the white-beam slits), XF:17BM-OP / XF:17BMA-OP -# (the optics: the bendable mirror, the beamline slits), XF:17BMA-EPS / -PPS / -CT -# (the shutters), XF:17BM-BI (the flux and beam-position monitors), XF:17BMA-ES:1 / -# ES:2 (the footprinting endstations: filters, sample stages, pumps), XF:17BMA-ES:3 -# (a separate monochromatic XAS endstation, OUT OF SCOPE here, WHITE-1). Whether the -# optics and endstation are separate hutches and the PSS permit leaves are open -# (ENC-1, PSS-1). -enclosures: - - name: xfp-optics - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf not fully in the profile collection; only the front-end photon-shutter enable status (XF:17BM-PPS{Sh:FE} enabled_status) is read; the optics zone (FE:C17B, XF:17BM-OP / XF:17BMA-OP), the hutch grouping is ENC-1 (PSS-1)"} - - name: xfp-endstation - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; the footprinting endstations (XF:17BMA-ES:1, ES:2); the monochromatic XAS endstation ES:3 is out of scope (ENC-1, PSS-1, WHITE-1)"} - -# =========================================================================== -# SOURCE STAGE: the machine state, the white-beam optics, and the dose-delivery -# gating (shutters + the dose timer) -# =========================================================================== - -machine: - stage: source - enclosure: xfp-optics - intro: "The machine-level source state, observed not driven." - note: "Observe-only NSLS-II machine state, the loose StorageRing pattern reused from the NSLS-II siblings. 17-BM is a bending-magnet source, not an insertion device, so no InsertionDevice Asset (SRC-1, MACHINE-1)." - devices: - - name: StorageRing - family: StorageRing # loose Family (machine-level observe-only source state; MACHINE-1) - pv: "SR:OPS-BI{DCCT:1}I:Real-I" - new: true - confirm: true - note: "NSLS-II storage-ring current, read as a beam-present suspender input; observe-only; the rest of the ring state is MACHINE-1; the 17-BM bending-magnet source detail is SRC-1" - -optics: - stage: source - enclosure: xfp-optics - intro: "The white / pink beam optics: the bendable front-end mirror, the white-beam and beam-defining slits, and the dose-rate filter wheel. There is no monochromator in the footprinting path." - note: > - The footprinting beam is white / pink: the bendable mirror sets the cutoff and - binds Mirror; the slits bind Slit; the eight-position Al filter wheel binds Filter - (it sets the dose rate, with the pinhole apertures as a further attenuator, ATTN-1). - The only monochromator in the source is a separate XAS endstation (ES:3), out of - scope for footprinting (WHITE-1). Everything here reuses the catalog and coins nothing. - devices: - - name: FrontEndMirror - family: Mirror - pv: "XF:17BM-OP{Mir:1-Ax:P}Mtr" - new: true - confirm: true - note: "the bendable front-end mirror (horizontal / lift / pitch / yaw / roll plus a Bend focus axis and thermocouples) that takes the heat load and sets the high-energy cutoff of the white beam; coating and bend are OPT-1" - - name: WhiteBeamSlit - family: Slit - pv: "FE:C17B-OP{Slt:1-Ax:T}Mtr" - new: true - confirm: true - note: "the front-end white-beam slit (T / B / I / O blades with virtual size / center); defines the white-beam footprint (OPT-2)" - - name: DefiningSlit - family: Slit - pv: "XF:17BMA-OP{Slt:ADC-Ax:XGap}Mtr" - new: true - confirm: true - note: "the ADC beam-defining slit; its horizontal gap (adcslits.xgap) sets the exposure window for the shutterless high-throughput fly mode (the PB / PDS white-beam slit shares the same anatomy); OPT-2, HT-1" - - name: FilterWheel - family: Filter - pv: "XF:17BMA-ES:1{Fltr:1-Ax:Rot}Mtr" - new: true - confirm: true - note: "the eight-position rotary aluminium filter wheel (0 / 25 / 76 / 152 / 203 / 305 / 508 / 762 um Al) that attenuates the white beam to set the dose RATE; a beam-defining pinhole stage and a 0-9 mm Al z-attenuator are further, intermittently-connected attenuators (ATTN-1)" - -dose: - stage: source - enclosure: xfp-optics - intro: "The dose-delivery gating: the personnel and timed exposure shutters, and the delay generator that fires the millisecond fast shutter. Exposure time times flux times attenuation is the delivered dose." - note: > - Footprinting dose is delivered by gating the white beam onto the sample. The - personnel-protection and timed exposure shutters bind Shutter; the delay generator - that fires the millisecond Uniblitz fast shutter binds TimingController (its opening-time - setpoint is the dose time). Seconds-scale exposures are software-timed on the - pre-shutter; millisecond exposures use the delay-generator-fired Uniblitz, or in - the high-throughput fly mode the stage velocity through the defining slit sets the - exposure (DOSE-1, HT-1). - devices: - - name: PhotonShutter - family: Shutter - pv: "XF:17BM-PPS{Sh:FE}" - new: true - confirm: true - note: "the personnel-protection front-end photon shutter; its enabled-status leaf is interlock-gated (plans refuse to open it when disabled); the rest of the PSS search-and-secure leaves are PSS-1" - - name: DoseShutter - family: Shutter - pv: "XF:17BMA-EPS{Sh:1}" - new: true - confirm: true - note: "the equipment-protection pre-shutter, the workhorse timed-exposure shutter for seconds-scale dose (open, software-timed sleep, close); a separate inner DIODE sample shutter (XF:17BMA-CT{DIODE-Local:1}...) protects the sample (DOSE-1)" - - name: DoseTimer - family: TimingController - pv: "XF:17BMA-ES:2{DG:1}" - new: true - confirm: true - note: "the DG535 delay generator that fires the millisecond Uniblitz fast shutter: a settable opening-time (bDelaySetAO, the source's exp_time, the dose time), a trigger mode, and a single-shot fire (genSingleShotTrigBO); the Uniblitz itself has no EPICS PV and is driven downstream of this timer (DOSE-1)" - -# =========================================================================== -# SAMPLE STAGE: the capillary-flow, high-throughput, and HTFly sample stages, -# and the sample-delivery pump (the fraction collector + 96-well plate are the -# sample-custody seam, see controls) -# =========================================================================== - -sample: - stage: sample - enclosure: xfp-endstation - intro: "The capillary-flow, high-throughput plate, and shutterless HTFly sample stages, and the syringe sample-delivery pump that flows solution through the beam." - note: > - XFP runs several sample-delivery modes. The capillary-flow stage flows a solution - sample through the beam; the high-throughput stage positions a 96-well plate; the - HTFly stage sweeps a fly-cell through the beam at a set velocity so the exposure - (dose) is the slit width over the stage velocity (HT-1). All bind LinearStage. The - syringe / sample-delivery pumps bind the graduated catalog FlowController Family (the - i22 / 7-BM / LIX precedent); XFP is its fourth consumer, and FlowController graduated - on this rule-of-three (i22 / 7-BM / LIX / XFP). The - fraction collector that captures footprinted aliquots into tubes, the pure-Python - 96-well plate addressing (no robot, no PV), and the solution Subject are the - sample-custody and offline-readout seam, not devices here (FC-1, HT-1, SUBJECT-1). - devices: - - name: CapillaryFlowStage - family: LinearStage - pv: "XF:17BMA-ES:1{Stg:5-Ax:X}Mtr" - new: true - confirm: true - note: "the capillary-flow sample stage (x / y, 100 mm travel) that places a flowing solution capillary in the beam; an ES:1 three-axis table positions auxiliary sample hardware (SAMPLE-1)" - - name: HighThroughputStage - family: LinearStage - pv: "XF:17BMA-ES:2{Stg:7-Ax:X}Mtr" - new: true - confirm: true - note: "the high-throughput sample stage (x / y, 200 mm travel) that positions a 96-well plate; the well / slot addressing is pure Python plus a coordinate table, no robot and no PV, modelled as a Procedure over the spine plus a Subject custody thread (HT-1)" - - name: HtFlyStage - family: LinearStage - pv: "XF:17BMA-ES:2{HTFly:1-Ax:X}Mtr" - new: true - confirm: true - note: "the shutterless high-throughput fly stage that sweeps a fly-cell row through the beam; the exposure (dose) is the defining-slit gap over the stage velocity, not a shutter, so the dose-timing is in the Procedure not a device (HT-1, DOSE-1)" - - name: DeliveryPump - family: FlowController # catalog Family (graduated; settable flow/pump actuator, presents Regulator) - pv: "XF:17BMA-ES:1{Pmp:02}" - new: true - confirm: true - note: "the sample-delivery syringe pump (an M50 pump with velocity / volume / slew setpoints, driving the dose-response / fraction-collection mode; a second PHD2000 infusion pump at XF:17BM-ES:1{Pmp:01} drives the capillary-flow / time-resolved mode) flowing solution through the capillary or flow cell during irradiation; both bind the graduated catalog FlowController Family (presents Regulator) and are folded into this one Asset at this cut, XFP its fourth consumer, with FlowController graduated on the i22 / 7-BM / LIX / XFP rule-of-three (FLUID-1 keeps the wider fluidic chain in the ControlPort seam)" - -# =========================================================================== -# DETECTION STAGE: the flux / dose monitors. There is NO scattering / area / -# imaging detector: the footprinting readout is offline mass spectrometry. -# =========================================================================== - -detection: - stage: detection - enclosure: xfp-endstation - intro: "The incident-flux and beam-position monitors that measure the delivered dose. There is no scattering, area, or imaging detector: the footprinting structural readout is done offline by mass spectrometry." - note: > - XFP has no Detector-role imaging device. The flux it delivers is the measurement - that matters: the QuadEM electrometers bind FluxMonitor (incident flux plus a - time-series trace to compute the delivered dose, with a diode array-logger as a - further dose accumulator); the Sydor four-channel monitor binds the graduated - PositionMonitor Family (beam position plus a sum-current flux readback, - DIAG-1). The footprinting structural readout (which residues were modified) - is OFFLINE mass spectrometry, downstream of the beamline and absent from the - profile collection; what the beamline produces is a footprinted sample plus a dose - record (READOUT-1, DET-1). - devices: - - name: FluxMonitor - family: FluxMonitor - pv: "XF:17BM-BI{EM:1}EM180:" - new: true - confirm: true - note: "the primary QuadEM electrometer reading incident flux and a per-exposure time-series, the basis for the delivered dose; a DIODE PDM array-logger (XF:17BMA-CT{DIODE-PDM:1}) accumulates the dose array and a second electrometer (XF:17BM-BI{EM:2}) adds channels; the flux-to-absorbed-dose calibration lives in offline analysis (DET-1, DOSE-1, READOUT-1)" - - name: BeamPositionMonitor - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1) - pv: "XF:17BM-BI{EM:BPM1}" - new: true - confirm: true - note: "the Sydor four-channel beam-position monitor (per-quadrant currents, beam x / y, and a sum-current total-flux readback); binds the graduated PositionMonitor Family (DIAG-1); the position-vs-intensity split is DIAG-1" - -# Cross-cutting control. XFP runs EPICS plus PV-bound fluidic actuators; CORA -# observes the floor and, where it replaces bluesky-style orchestration, conducts -# over it. The handles above were read from the profile collection and carried -# confirm (CTRL-1). -controls: - intro: > - XFP runs on the NSLS-II EPICS / ophyd control stack, the same floor as the rest of - the NSLS-II fleet. The device handles above are bound from the beamline's bluesky - profile collection (github.com/NSLS2/xfp-profile-collection, its startup files), - carried confirm (CTRL-1). The dose-delivery acquisition (open a timed shutter or - fire the delay-generator Uniblitz, or sweep the HTFly stage, while a pump flows the - sample and the QuadEM records the flux trace) runs through bluesky plans publishing - to Kafka with metadata in Redis (no Tiled, no queue-server in the profile - collection); that orchestration is the seam CORA's edge replaces, driving through - ophyd / EPICS. Crucially, the science readout is OFF the beamline: a footprinting - run produces a footprinted sample plus a dose record, and the mass-spectrometry - analysis is downstream (READOUT-1). - software_iocs_not_modeled: - # The sample-custody and offline-readout seam: the fraction collector, the 96-well - # plate addressing, and the offline mass spec. Only the delivery pump is a device - # (it binds FlowController). The rest is the Subject / Supply / Procedure shape. - - "XF:17BM-ES:1{FC:1}: the fraction collector (a PV-bound aliquot-routing actuator: a collect / waste valve, a tube index, a fill pattern, home) that captures footprinted aliquots into tubes; no existing Family fits an aliquot-router cleanly, so it is carried in the sample-custody seam (the footprinted-sample hand-off to offline MS) and not coined at n=1 (FC-1, READOUT-1)" - - "the 96-well high-throughput plate: addressed alpha-numerically (8 columns x 12 rows) by pure Python (locate_slot.py) plus a coordinate table, with no robot, no sample-changer, and no PV; moving to a well is a move on the HighThroughputStage; modelled as a Procedure over the spine plus a Subject custody thread (HT-1, the i03 / MX3 / LIX custody-as-Procedure precedent, here at the no-robot end of that spectrum)" - - "the offline mass-spectrometry readout: the footprinting structural analysis (which residues were modified) is done downstream, off the beamline, and is entirely absent from the profile collection; the beamline's run produces a footprinted sample plus a dose record (exposure time, filter thickness, flux time-series, well / tube identity), the offline-readout seam (READOUT-1)" - - "the SR630 thermocouple monitor (XF:17BMA-ES:2{TCM:1}) and the Sydor bias / thermocouple controller (XF:17BM-ES{PBG:1}): read-only temperature / bias diagnostics, used as alignment-flux proxies; not core footprinting devices, deferred (TEMP-1)" - - "the data plane is Kafka (document publishing) plus Redis (metadata), with no Tiled and no queue-server in the profile collection; CORA keeps its own data-of-record, the dose record being the system-of-record for a footprinting run (CTRL-1, READOUT-1)" - -# Continuously-available resources a run draws on. -resources: - intro: > - The continuously-available facility resources an XFP run needs, plus the - footprinting consumables. The optics run under vacuum (SUP-1). A footprinting run - draws on buffers, radical scavengers, and the flow medium as Supply consumables, - distinct from the facility-wide supplies (SUP-1, SUBJECT-1). - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - note: "the white-beam optics run under vacuum (SUP-1)" diff --git a/deployments/xpd/beamline.yaml b/deployments/xpd/beamline.yaml deleted file mode 100644 index 4788081047e..00000000000 --- a/deployments/xpd/beamline.yaml +++ /dev/null @@ -1,222 +0,0 @@ -# XPD beamline descriptor (NSLS-II), reverse-engineered -# -# XPD (X-ray Powder Diffraction) is the NSLS-II high-energy powder-diffraction and -# total-scattering beamline at sector 28-ID-2. Its defining techniques are powder -# diffraction and rapid-acquisition pair distribution function (PDF / total -# scattering): a high-energy beam through a powder or capillary sample onto a large -# flat-panel area detector, with the detector distance setting the accessible Q. It -# is bound to the NSLS-II Site (deployments/nsls2/site.yaml), the eighth NSLS-II -# beamline after FXI, HXN, BMM, SRX, SIX, CHX, and CSX. -# -# STATUS: reverse-engineered, design-phase. Every value is read from public open -# source (the bluesky profile collection NSLS2/xpd-profile-collection) or inferred, -# carried `confirm: true` pending XPD staff. EPICS PVs are real and verified against -# the startup scripts; vendor part numbers, serials, and physical positions are not -# in it and are open questions. Same descriptor mode as FXI / HXN / BMM / SRX / SIX -# / CHX; this scaffold is descriptor + docs, scenarios deferred. -# -# XPD is the POWDER-DIFFRACTION / PDF reinforcement: it is the NSLS-II twin of the -# Diamond i11 (high-resolution powder diffraction) and i15-1 (total scattering / PDF) -# beamlines, the second facility for that science axis. It introduces NO new catalog -# family: the flat-panel detectors reuse Camera, the ion chamber and quad electrometer -# FluxMonitor (#353), the cryostream / furnace TemperatureController (#350, graduated -# BY i11), the bent double-Laue and high-resolution monochromators Monochromator, the -# focusing mirror Mirror. Its one loose family is the PositionMonitor, shared with -# 4-ID/8-ID/9-ID and held (DIAG-1). Per the i11 / i15-1 precedent the powder-diffraction -# and total-scattering Capabilities are NOT coined here; they are the deferred -# owner-scope cohort (TECH-1), and the autonomous sample robot is the deferred -# i03 / i15-1 autonomous-loop shape (ROBOT-1). - -beamline: - maturity: model - evidence: controls_config - coverage: full - summary: "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" - name: XPD - facility: nsls2 # NSLS-II Site (facility_code: nsls2) - sector: "Sector 28" # PV namespace XF:28ID* - tier: Unit - parent: null - source: insertion-device - source_confirm: "the source is an insertion device; no source PV or parameters are in the profile collection. It is understood from facility knowledge (not the profile collection) to be a damping wiggler, the high-flux high-energy source PDF needs; that subtype is an inference pending staff confirmation (SRC-1)" - page_layout: stages - shape: "The NSLS-II twin of Diamond I11 / I15-1: high-energy powder diffraction and total scattering onto a large area detector, the detector distance setting the accessible Q." - source_ref: - label: "NSLS2/xpd-profile-collection" - url: "https://github.com/NSLS2/xpd-profile-collection" -enclosures: - # PV zones: 28IDA first-optics hutch (FOE: the double-Laue mono and focusing - # mirror), 28IDC the main experiment hutch (the PDF / powder endstation), 28IDD a - # downstream high-resolution endstation (noted, deferred ENDSTATION-1). Modelled as - # the optics hutch + the main experiment hutch. - - name: 28-ID-A - role: optics-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS search-and-secure permit leaf not in source; only the endstation exposure shutter (XF:28IDC-ES:1{Sh:Exp}) is exposed, not the front-end PPS leaves (PSS-1)"} - - name: 28-ID-C - role: experiment-hutch - facility_code: nsls2 - permit_signal: {confirm: "PSS permit leaf unknown; 28-ID-C is the main PDF / powder endstation, with a downstream high-resolution endstation 28-ID-D deferred (ENDSTATION-1) (PSS-1)"} - -# =========================================================================== -# SOURCE STAGE: the insertion-device source -# =========================================================================== - -source: - stage: source - enclosure: 28-ID-A - intro: The insertion-device source feeding the high-energy beam. - devices: - - name: Source - family: InsertionDevice - confirm: true - note: "28-ID insertion-device source. No source PV or parameters are in the profile collection; from facility knowledge (not the public config) it is understood to be a damping wiggler, the high-flux high-energy regime PDF needs, which is an inference pending staff confirmation (SRC-1)." - -# =========================================================================== -# OPTICS STAGE: the double-Laue and high-resolution monochromators, mirror, slits -# =========================================================================== - -optics: - stage: source - enclosure: 28-ID-A - intro: "Condition the high-energy beam and set its energy: the bent double-Laue monochromator for high flux, the vertical focusing mirror, the white-beam slit, and the filters. PVs verified against startup/15-optics.py and 10-motors.py. (A separate high-resolution monochromator in the 28-ID-C hutch feeds the high-resolution endstation, deferred with it, ENDSTATION-1.)" - devices: - - name: Monochromator - family: Monochromator - pv: "XF:28IDA-OP:1{Mono:DLM-C:" - confirm: true - note: "Bent double-Laue monochromator (dlm, two crystals C:1 / C:2 with many bender axes); a transmission Laue mono giving high flux at high energy, the same bent-Laue shape Diamond i15-1 uses for PDF. The EnergyAxis below is the master energy; crystal and range pending (DCM-1)." - - name: VerticalFocusingMirror - family: Mirror - pv: "XF:28IDA-OP:1{Mir:VFM-Ax:" - confirm: true - note: "Vertical focusing mirror (vfm) with bender axes; reuses the Mirror family." - - name: WhiteBeamSlit - family: Slit - pv: "XF:28IDA-OP:2{Slt:H-Ax:" - confirm: true - note: "Horizontal beam-defining slit (class Slits)." - - name: Filters - family: Filter - pv: "XF:28IDA-OP:2{Fltr:1-Ax:Y}" - confirm: true - note: "Attenuator filter (fltr1) trimming flux; a separate filter on a different optical leg (fltr6 at OP:0) and an endstation filter bank (XF:28IDC-OP:1{Fltr}) also exist. Reuses the Filter family." - - name: EnergyAxis - family: PseudoAxis - confirm: true - note: "The master energy axis set by the double-Laue monochromator. XPD runs at a fixed high energy per experiment; whether energy is ever scanned as the measurement is ENERGY-1." - - name: BeamPositionMonitor - family: PositionMonitor # catalog Family (graduated; presents Sensor; DIAG-1) - pv: "XF:28IDA-BI:0{BPM:1-Ax:" - confirm: true - note: "Beam-position monitor (bpm1) in the optics hutch. Binds the graduated PositionMonitor Family (a consumer alongside 4-ID/8-ID/9-ID; DIAG-1), matching the catalog note that position monitors stay loose." - -# =========================================================================== -# SAMPLE STAGE: the diffractometer, sample stages, pinhole, sample environment -# =========================================================================== - -sample: - stage: sample - enclosure: 28-ID-C - intro: "The diffractometer that holds the sample and detector arm, the sample-array stage, the beam-defining pinhole, and the sample-environment thermal stages. PVs verified against startup/10-motors.py and 11-temperature-controller.py." - note: > - XPD positions a powder or capillary sample in the high-energy beam and records - the diffraction / total-scattering pattern on the area detector. The sample stack - reuses LinearStage; the rich sample-environment cluster (cryostream, furnace, - hot-air blower) reuses the TemperatureController family, the same one Diamond i11 - graduated for variable-temperature powder diffraction. - devices: - - name: SampleStage - family: LinearStage - pv: "XF:28IDC-ES:1{Dif:1-Ax:" - confirm: true - note: "Sample and detector-arm diffractometer (diff, Dif:1: Th, X, Y, two-theta inboard/outboard). Bound to LinearStage as a design-phase placeholder; the diffractometer carries goniometric axes, so whether its orientation is modelled as a Goniometer plus a Diffractometer Assembly (the 8-ID / i11 precedent) is folded into STAGE-1." - - name: SampleArrayStage - family: LinearStage - pv: "XF:28IDC-ES:1{SampArray-Ax:" - confirm: true - note: "Sample-array stage (sample_x / sample_y) presenting many samples for high-throughput acquisition, plus a secondary sample stage (Stg:Smpl2). Reuses LinearStage." - - name: Pinhole - family: Aperture - pv: "XF:28IDC-ES:1{PinHole:XRD-Ax:" - confirm: true - note: "Beam-defining pinhole (pinhole_x / pinhole_y) cleaning the beam onto the sample; reuses the Aperture family." - - name: SampleTemperature - family: TemperatureController - pv: "XF:28IDC-ES:1{CS:800}" - confirm: true - note: "Sample-environment thermal control: the cs700 (XF:28IDC-ES:1{Env:01}) and cs800 (XF:28IDC-ES:1{CS:800}) cryostream controllers, Eurotherm and hot-air blowers (Env:03 / 04 / 06), a Lakeshore cryostat (XF:28IDC-ES1:LS335:{CryoStat}), and a Linkam furnace (XF:28IDC-ES:2:{LINKAM}:). The cs700 / cs800 are understood to be Oxford Cryostreams (inference, not in source; TEMP-1). Modelled as one thermal-environment Asset; reuses TemperatureController (graduated by Diamond i11, #350). Which units are live is TEMP-1." - -# =========================================================================== -# DETECTION STAGE: the flat-panel area detectors, distance stage, flux, shutter -# =========================================================================== - -detector: - stage: detection - enclosure: 28-ID-C - intro: "The large flat-panel area detectors for powder / PDF, the detector distance stage that sets the accessible Q, the flux counters, and the exposure shutter. PVs verified against startup/80-areadetector.py, 18-ion-chamber.py, 16-electrometer.py, 10-motors.py." - note: > - XPD's measurement is the diffraction pattern on a large flat-panel detector. For - total scattering / PDF the detector sits close to reach high Q; the distance stage - moves it, the PDF two-distance shape. All reuse existing families. Which panels are - live versus the spare set is a staff question (DET-1). - devices: - - name: AreaDetector - family: Camera - pv: "XF:28IDC-ES:1{Det:PE1}" - confirm: true - note: "PerkinElmer flat-panel area detector (pe1, class XPDPerkinElmer; a second panel pe2 at Det:PE2, a third pe3 at the 28-ID-D endstation). The primary powder / PDF detector; reuses Camera." - - name: DexelaDetector - family: Camera - pv: "XF:28IDC-ES:1{Det:DEX}" - confirm: true - note: "Dexela flat-panel detector (the Det:DEX namespace is real, but the device is defined-and-currently-commented-out in source, not a live panel); reuses Camera. Live status pending (DET-1)." - - name: DetectorStage - family: LinearStage - pv: "XF:28IDC-ES:1{Det:PE1-Ax:" - confirm: true - note: "Detector translation (pe1_x, pe1_z): the Z axis sets the sample-to-detector distance and hence the accessible Q-range, the close / far distances a PDF measurement uses. Reuses LinearStage." - - name: IonChamber - family: FluxMonitor - pv: "XF:28IDC-BI{IC101}" - confirm: true - note: "Ion chamber (ion_chamber) measuring incident flux for normalization; reuses FluxMonitor (graduated #353)." - - name: QuadElectrometer - family: FluxMonitor - pv: "XF:28IDC-BI{IM:02}EM180:" - confirm: true - note: "Quad electrometer (qem1, NSLS-II QuadEM) reading I0 intensity (and a scaler em / sc); reuses FluxMonitor. Channel map pending (DIAG-1)." - - name: ExposureShutter - family: Shutter - pv: "XF:28IDC-ES:1{Sh:Exp}" - confirm: true - note: "Endstation exposure-shutter command signal (Sh:Exp, used by the area-detector multi-trigger and the beam suspender) gating the detector exposure; a separate motorized fast shutter (shctl1) sits on Sh2:Exp. Reuses the Shutter family." - -# =========================================================================== -# Cross-cutting controls -# =========================================================================== - -controls: - intro: > - XPD acquisition is software-triggered: the area detector runs in continuous or - multi-trigger mode gated by the endstation exposure shutter, with no separate - hardware timing box in the profile collection. Controller box models / firmware - are not in the profile collection (DRIVE-1). - triggering: - - name: EndstationMotionController - family: MotionController - confirm: true - note: "Endstation and optics motion controllers driving the diffractometer, sample, and detector stages; box model / protocol / IP not in the profile collection (DRIVE-1)." - software_iocs_not_modeled: - [PerkinElmer, Dexela, QuadEM, Cryostream, Lakeshore, Linkam, Robot] - -resources: - intro: Continuously-available resources. Facility-scope supplies live in deployments/nsls2/site.yaml. - supplies: - - kind: PhotonBeam - - kind: CoolingWater - - kind: Vacuum - - kind: LiquidNitrogen # cryostream - - kind: Power - replaceable_parts: - swappable_with_identity: ["flat-panel detectors", "capillary samples", "filters"] diff --git a/docs/deployments/12-id/notes.md b/docs/deployments/12-id/notes.md deleted file mode 100644 index 1abf5cb0445..00000000000 --- a/docs/deployments/12-id/notes.md +++ /dev/null @@ -1,135 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of 12-ID is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../aps/index.md) is how a facility adapts it. 12-ID is CORA's first Bonse-Hart ultra-small-angle X-ray scattering (USAXS) beamline, and it also runs pinhole SAXS and WAXS on area detectors. The lead technique, USAXS, is a new Capability for the fleet, so its Method renders unlinked and is carried pending until a technique enters scope (USAXS-1); the SAXS and WAXS Methods share the [i22](../i22/notes.md#techniques) scattering vocabulary and are pending the same owner-scope decision (TECH-1). - -### Bonse-Hart ultra-small-angle scattering - -USAXS reaches momentum transfer q far below the pinhole-SAXS regime by rocking a matched pair of channel-cut crystal stages through the Bragg condition: the collimator sits upstream of the sample, the analyzer downstream, and as the analyzer rocks against the collimator a single photodiode counts the transmitted intensity through an autoranging transimpedance amplifier across several gain decades (BONSE-1, USAXS-1). The measurement is the rocking curve, the transmitted intensity as a function of the small angular offset between the two crystals, which maps to q. This angular rocking fly-scan against a multi-decade autoranging point detector is the acquisition shape that is new for the fleet, not a new device class. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Ultra-small-angle scattering (USAXS) | `ultra_small_angle_scattering` | the Bonse-Hart rocking curve: the [analyzer crystal stage](detector.md) rocks against the [collimator crystal stage](sample.md) through the Bragg condition while the [UPD photodiode](detector.md) point-counts the transmitted flux through an autoranging amplifier; new Capability, pending (USAXS-1, BONSE-1) | -| Pinhole small-angle scattering (SAXS) | `small_angle_scattering` | low-q on the [SAXS Pilatus area detector](detector.md); shares the i22 SAXS Capability, pending (TECH-1) | -| Wide-angle scattering (WAXS) | `wide_angle_scattering` | wide-q on the [WAXS Pilatus area detector](detector.md) on its translation; shares the i22 WAXS Capability, pending (TECH-1) | - -USAXS needs the [incident beam chain](source.md) (the shared 12-ID double-crystal monochromator and the attenuator filter bank), the [sample stack](sample.md) (positioning stage, rotator, and the Linkam and PTC10 temperature stages), the [Bonse-Hart crystal stages](detector.md), and the [autoranging photodiode with its flux monitors and scaler](detector.md) for normalization. The same instrument runs pinhole SAXS and WAXS on their Pilatus area detectors, which reuse the existing scattering Capabilities and the same beam. - -### A new operating axis for the fleet - -USAXS is genuinely new for the fleet. The catalog already carries pinhole and grazing-incidence scattering on area detectors (i22, SMI) and a range of imaging, microprobe, and spectroscopy methods, but no crystal-analyzer rocking-curve technique. The new axis is the acquisition shape itself: rock one optic (the analyzer crystal) against a second, fixed-geometry optic (the collimator crystal) while a current-integrating point detector autoranges across several gain decades, rather than expose an area detector at one geometry (BONSE-1, USAXS-1). Pinhole SAXS resolves the scattering pattern by where photons land on a 2D detector; USAXS resolves much smaller angles by where the analyzer crystal passes the beam, read as one transmitted current per angular step. That is a new Capability, deferred as a question (USAXS-1). - -The new acquisition shape forces no new device families. The Bonse-Hart crystal stages bind the catalog `RotaryStage`: the operative axis is the crystal rocking rotation, and channel-cut versus multi-bounce is a per-Asset setting, not a new optic Family (BONSE-1). The autoranging photodiode binds the catalog `FluxMonitor`: it is a current-integrating point detector read through an autoranging Femto amplifier, the same anatomy as the I0 / I00 / I000 / TRD flux monitors and the counting scaler, and the multi-decade gain autorange is a device-state setting (DET-1). The SAXS and WAXS Pilatus detectors bind the catalog `Camera`. So what is new is the science Capability and the acquisition shape, not a device class; see [Model](#model) for why nothing graduates and the catalog is unchanged. - -### Not modelled yet - -The concrete acquisition recipes (the rocking-curve angular ranges, the gain-autorange behaviour and counting times for the photodiode, the pinhole-SAXS and WAXS camera geometries, and the temperature-ramp sequences) are not written yet; they join as the deployment approaches the point where CORA conducts over the floor. Whether USAXS enters CORA's catalog is an owner-scope decision and is deferred (USAXS-1); minting a cross-facility Method is not done from a modelling exercise until a technique enters a real scope, the same earn-the-abstraction discipline the SAXS and WAXS Methods follow (TECH-1). The Practices are carried pending on the [APS Site](../aps/index.md): `12ID_usaxs_practice` (`ultra_small_angle_scattering`, USAXS-1), `12ID_saxs_practice` (`small_angle_scattering`), and `12ID_waxs_practice` (`wide_angle_scattering`). See [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at 12-ID, and the trust shape that will gate it. First cut.* - -Governance at 12-ID follows the same model as the other APS beamlines: people and autonomous agents are facility principals at the [APS Site](../aps/index.md#safety-and-governance), 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). - -12-ID is not yet driven by CORA, so this shape is not yet instantiated. As a reverse-engineered scaffold, the deployment is descriptor and docs today, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized. The instrument config exposes device tables, not the human roster, so the APS operator pool and safety-review structure is carried pending at the [APS Site](../aps/index.md#safety-and-governance), shared across the beamlines (`GOV-1`). - -The safety tier is the other piece that is not yet settled. The PSS search-and-secure permit signals and the front-end and photon shutters are absent from the instrument config, so the Enclosure permit leaves and the interlock structure are carried pending and are not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [APS Site](../aps/index.md#safety-and-governance), not on the beamline, and the beamline links up to them rather than restating them. 12-ID adds the hazard classes that come with a hard X-ray USAXS endstation under vacuum and the in-situ temperature environments at the sample (the Linkam T96 and PTC10 stages, `TEMP-1`); those land with the instruments that bring them, and an experiment Clearance would carry them. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives 12-ID, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's 12-ID content lives, the first Bonse-Hart USAXS deployment that coins no new family, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at 12-ID | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes 12-ID new - -12-ID is CORA's first Bonse-Hart ultra-small-angle X-ray scattering (USAXS) beamline. The fleet already has pinhole small- and wide-angle scattering (i22, 8-ID), grazing-incidence scattering (9-ID), total scattering and powder diffraction (i15-1, i11), and coherent XPCS (8-ID, CHX), but no crystal-analyzer USAXS. The novelty is the acquisition shape: a matched pair of channel-cut crystal stages, the collimator upstream of the sample and the analyzer downstream, is rocked through the Bragg condition while a single photodiode counts the transmitted intensity through an autoranging transimpedance amplifier across several gain decades. The rocking curve resolves momentum transfer far below the pinhole-SAXS regime. That angular rocking fly-scan with a multi-decade autoranging point detector is a new Capability, deferred as a question (USAXS-1, BONSE-1). The same instrument also runs pinhole SAXS and WAXS on area detectors, which reuse the existing scattering Capabilities. The novelty forces no new device families: every device below reuses an existing catalog or loose Family. - -### No new families - -12-ID coins no new Family and changes nothing in the catalog. The two devices that could have tempted a new kind both fold into existing vocabulary: - -- **The Bonse-Hart crystal stages bind the catalog `RotaryStage`, not a new optic family.** The collimator and analyzer are channel-cut crystal stages whose operative axis is the crystal rocking rotation (plus alignment translations and a piezo fine-tilt). The rocking rotation is what `RotaryStage` already models; channel-cut versus multi-bounce is a per-Asset setting, not a new optic Family. The rocking-curve scan against the matched crystal is the USAXS measurement, an acquisition shape (USAXS-1), not a device class. - -- **The autoranging photodiode binds the catalog `FluxMonitor`, not a new detector family.** The UPD photodiode is the primary USAXS detector, but it is a current-integrating point detector read through an autoranging Femto transimpedance amplifier, the same anatomy as the I0 / I00 / I000 / TRD monitors and the counting scalers. This is the BMM precedent (a quad-electrometer-as-primary-detector). The multi-decade gain autorange is a device-state setting, not a new family (DET-1). The pinhole SAXS and WAXS Pilatus area detectors bind the catalog `Camera`. - -The Linkam T96 and the PTC10 reuse the graduated `TemperatureController` Family (presents the `Regulator` Role), the same Family three Diamond beamlines and IXS already use. The attenuator binds the `Filter` Family (the i03 / i15-1 precedent, ATTN-1). The machine source state reuses the loose `StorageRing` (MACHINE-1). - -### Deliberately not here yet - -- **The Bonse-Hart pair as an Assembly (`BONSE-1`).** Whether the matched collimator and analyzer crystal stages compose one `Assembly` (a Bonse-Hart camera presenting a single rocking-pair unit) is deferred, exactly as the diffractometer beamlines deferred materializing their Assemblies in descriptor mode. The first cut is two flat `RotaryStage` Assets with the Assembly named as the follow-on. An Assembly is earned at n=2 across independent beamlines; coining one at n=1 would be over-modelling. - -- **The channel-cut crystal identity.** Each crystal stage carries its crystal as a setting on the one `RotaryStage` Asset; promoting a crystal to a child Asset via `parent_id` is the nested-component-identity convention, itself at a rule-of-three gate (applied only for `RotaryDriveChassis` so far). The first cut carries the crystal as a setting rather than asserting a child Asset. - -- **The in-situ load frame (`LOADFRAME-1`).** A load frame exists in the instrument's device library but is not in the active instrument config, so it is not modelled here. No Family is coined for an un-instantiated device; it lands if it enters the active beamline. - -- **The USAXS Method.** Whether the Bonse-Hart rocking-curve technique enters CORA's catalog as a Capability / Method is an owner decision; the Practice renders unlinked, pending (`USAXS-1`). The pinhole SAXS / WAXS Practices share the i22 SAXS / WAXS Methods, also pending (TECH-1 at the Site level). - -- **The simulated devices and full asset-tree scenarios.** No `test_12_id_e_*.py` registers the 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). - -## Open questions - -*What CORA needs the 12-ID team to confirm before the model can be trusted.* - -12-ID was reverse-engineered from the beamline's own bluesky / BITS instrument ([BCDA-APS/usaxs-bits](https://github.com/BCDA-APS/usaxs-bits)), so the control handles on the [device pages](index.md) are the beamline's real PVs, read from the `src/usaxs/configs/*.yml` device tables and `src/usaxs/devices/*.py` classes rather than confirmed by staff. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | Is 12-ID one experiment hutch served by a shared upstream 12-ID optics zone, or do the optics live in the same hutch? | Two enclosures: a shared `12-ID-optics` zone and the `12-ID-E` experiment hutch. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The 12-ID undulator period and type (absent from the USAXS instrument config). | An insertion-device sector; the undulator gap is not exposed as a device. | The source Asset detail. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MACHINE-1 | Nice-to-have | The storage-ring state 12-ID reads (current, fill, top-up). | Observe-only machine state, a loose `StorageRing`; the exact PVs are pending. | The machine-state observation. | -| MONO-1 | Blocks-go-live | The 12-ID monochromator crystal cut / d-spacing, the incident-energy range, and the real energy PVs (the instrument wraps it as a soft device). | A double-crystal `Monochromator`; cut and range carried pending. | The monochromator Asset. | -| ATTN-1 | Nice-to-have | The attenuator foil set (`12idPyFilter:`) and whether it folds into the `Filter` Family or earns a distinct `Attenuator` kind (the fleet-wide question). | An Al/Ti filter bank bound to `Filter`, the i03 / i15-1 precedent. | The attenuator's catalog home. | -| OPT-2 | Nice-to-have | The blade-axis roles of each slit (guard, USAXS-defining) and the detector / SAXS translation stage axes. | Four-blade variable openings bound to `Slit`; translation stages bound to `LinearStage`. | The slit and stage axis detail. | - -### USAXS optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| BONSE-1 | Blocks-build | The Bonse-Hart crystal cut (channel-cut versus multi-bounce), the collimator / analyzer rocking-axis map, and the rocking-curve tolerance. | Matched channel-cut crystal stages on `RotaryStage`, each a rocking rotation plus alignment translations and a piezo fine-tilt. | The Bonse-Hart geometry; the CORA structural modelling is on [Model](#deliberately-not-here-yet). | -| USAXS-1 | Blocks-go-live | Does the Bonse-Hart rocking-curve ultra-small-angle-scattering technique enter CORA's catalog as a Capability / Method? | Deferred: carried as a pending Practice, no `cora.capability.usaxs` coined. | The USAXS Capability. | - -### Sample - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SAMPLE-1 | Blocks-go-live | The sample-stage axis set, the PI C-867 sample rotator role, and what is mounted on them. | A `LinearStage` sample stage plus a `RotaryStage` rotator; the axis set carried pending. | The sample-stage modelling. | -| TEMP-1 | Nice-to-have | The Linkam T96 temperature range and the PTC10 channel map, and whether they coexist or swap per experiment. | Two `TemperatureController` Assets presenting the `Regulator` Role; range and channels pending. | The temperature-environment modelling. | -| LOADFRAME-1 | Nice-to-have | Is the in-situ load frame (in the device library but not the active instrument config) part of the operating beamline, and what is it? | Not modelled: deferred until it appears in the active config; no Family coined for an un-instantiated device. | The load-frame modelling. | - -### Detection - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The UPD autoranging photodiode gain-decade map, the I0 / I00 / I000 / TRD flux-monitor channel assignment, the scaler channels, and the SAXS / WAXS area-detector prefixes. | The UPD photodiode + the I0 family + the scalers bound to `FluxMonitor` (gain autorange a device-state setting); the SAXS / WAXS Pilatus detectors bound to `Camera`. | The detector modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the EPICS PV handles read from the usaxs-bits instrument current and correct? | The handles in the descriptor are taken from the instrument config and carried confirm. | Verifying each Asset's control handle. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit signals and the front-end / photon shutters (absent from the instrument config). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent of the optics and flight paths. | Photon beam, cooling water, and vacuum on the optics and flight paths. | The Supply observations. | -| GOV-1 | Nice-to-have | The APS operator pool and safety-review structure (site-level, shared across the beamlines). | Carried pending on the APS Site, not instantiated per beamline. | The governance principals. | diff --git a/docs/deployments/13-id/notes.md b/docs/deployments/13-id/notes.md deleted file mode 100644 index d0783dc3757..00000000000 --- a/docs/deployments/13-id/notes.md +++ /dev/null @@ -1,176 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of 13-ID is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../aps/index.md#the-techniques-adapted-here) is how a facility adapts it. 13-ID runs monochromatic X-ray diffraction on a sample held in a diamond anvil cell under extreme pressure and double-sided laser heating: high-pressure powder diffraction and high-pressure single-crystal diffraction. Both reuse Methods that the fleet already carries (or has pending), so the slugs below render unlinked and are carried pending until one enters scope (TECH-1). Nothing here coins a new technique. The novelty at 13-ID is the sample environment, not the measurement. - -### High pressure is a sample environment, not a technique - -The diamond anvil cell squeezes the sample between two anvils and heats it from both sides, so the diffraction is measured at extreme pressure and temperature rather than at ambient conditions. That is a difference in the conditions the sample sits in, not a difference in what the beam measures or how the pattern is read. A powder ring is a powder ring whether the powder is at ambient pressure or inside a cell; a single-crystal reflection is a single-crystal reflection either way. - -So high pressure binds the same Methods as ordinary diffraction, carried as a Plan-level sample-environment difference. This follows the [4-ID precedent](../4-id/notes.md#techniques), where high-pressure diffraction is the same `diffraction` Method run with a pressure cell, a Plan setting over the same measurement and not a new slug. The cell, its heating, and its in-situ pressure and temperature metrology are modelled as equipment (the catalog [PressureCell](sample.md) family and its capabilities), and the conditions they impose are expressed in the Plan, not in the technique name. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| High-pressure powder diffraction | `powder_diffraction` | monochromatic powder rings from the cell, recorded on the [area detector](detector.md); shares the i11 powder Capability; high pressure is a Plan-level sample-environment setting, pending (TECH-1) | -| High-pressure single-crystal diffraction | `diffraction` | reciprocal-space reflections from a single crystal in the cell on the [area detector](detector.md), oriented on the [diffractometer stage](sample.md); shares the 4-ID / 8-ID / CSX / i19 diffraction Capability; high pressure is a Plan-level sample-environment setting, pending (TECH-1) | - -Both techniques need the [incident beam chain](source.md) (the shared 13-ID-A monochromator, the K-B focusing mirror, the beam-defining and clean-up apertures, and the attenuator filter bank), the [pressure cell and its diffractometer stage](sample.md), the [area detector on its 2theta arm](detector.md), and the ion-chamber and photodiode [flux monitors](detector.md) for normalization. The diffraction spine is entirely catalog reuse; see [Model](#model) for why nothing in the measurement path graduates. - -### What the cell lets the science do - -The diamond anvil cell is what makes 13-ID distinct. It lets the experiment probe matter at extreme pressure and temperature, conditions that reach toward planetary interiors and that no other deployment in the fleet has reached. The science is to watch how a material's structure responds as it is squeezed and heated: phase transitions, equations of state, and structural changes under pressure and temperature that do not appear at ambient conditions. - -Two cell capabilities do the work, and both are modelled as capabilities of the single [PressureCell](sample.md) Asset rather than as separate families: - -- **Pressure.** The cell presents the Regulator Role for its membrane gas pressure, driven through the PACE5000 membrane controller. Setting and reading the membrane pressure is the actuated handle on the squeeze (PRESSURE-1, HP-1). -- **Double-sided laser heating.** Two IPG YLR fibre lasers heat the sample from both sides, balanced, so the heated volume is hot through its thickness rather than only on one face (HEAT-1). The live heating is open-loop on commanded laser power: there is no closed-loop temperature Regulator today, the lasers are a power actuator and the temperature is inferred from the sample's own thermal emission (HEAT-1). - -These two together open the pressure-temperature space that the diffraction then samples. The cell sets the conditions; the diffraction reads the structure. - -### The in-situ metrology is part of the cell - -Knowing the pressure and temperature at the sample is itself measured in situ, and that metrology belongs to the cell as a capability, not to a technique: - -- **Temperature** is read from thermal-emission spectroradiometry: the sample's own glow, dispersed and fit to a thermal spectrum, gives the temperature on each side (HEAT-1, HP-1). The spectrometer that records it binds the catalog [Camera](detector.md) family (LightField PIMAX / PIXIS), the cell's pressure-and-temperature metrology detector. -- **Pressure** is read from ruby fluorescence, Raman, or Brillouin measurements on the cell (PRESSURE-1, HP-1). These calibrate the pressure that the membrane controller commands against an in-situ standard. - -This metrology is not a separate Method. It is how the cell knows the conditions it is imposing, the same way a temperature controller knows its setpoint. It is modelled as part of the PressureCell capability and its [metrology spectrometer](detector.md), and it does not appear in the technique table above. - -### Not modelled yet - -The concrete acquisition recipes are not written yet: the powder and single-crystal scan sequences, the laser-power ramp and balancing during heating, the ruby / Raman / Brillouin pressure-calibration steps, and how a Plan threads the pressure and temperature setpoints through a diffraction run. They join as the deployment approaches the point where CORA conducts over the floor. - -Whether `powder_diffraction` and `diffraction` enter CORA's catalog, and who owns them across the facilities that share them, is an owner-scope decision and is deferred (TECH-1); minting a cross-facility Method is not done from a modelling exercise until a technique enters a real scope. The Practices are carried pending on the [APS Site](../aps/index.md#the-techniques-adapted-here): `13ID_powder_diffraction_practice` (`powder_diffraction`) and `13ID_diffraction_practice` (`diffraction`), both pending TECH-1. - -The 2theta swing transform that would bind a `PseudoAxis` on the [detector arm](detector.md) is deferred, not invented: the arm's prefix was seen only in a controller test template, so the binding is left open (DET-1). A closed-loop temperature Regulator for the heating is likewise not modelled, because today's heating is open-loop on commanded power (HEAT-1). See [Open questions](#open-questions) for the world-facts to confirm first, and [Model](#model) for how the PressureCell family, introduced here, graduated to the catalog across 13-ID and P02 (HP-1). - -## Governance - -*Who will act at 13-ID, and the trust shape that will gate it. First cut.* - -Governance at 13-ID follows the same model as the other APS beamlines: people and autonomous agents are facility principals at the [APS Site](../aps/index.md#safety-and-governance), 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). - -13-ID is not yet driven by CORA, so this shape is not yet instantiated. As a reverse-engineered scaffold, the deployment is descriptor and docs today, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized. The GSECARS EPICS support tree exposes device templates and startup scripts, not the human roster, so the APS / GSECARS operator pool and the safety-review structure are carried pending at the [APS Site](../aps/index.md#safety-and-governance), shared across the beamlines (`GOV-1`). - -### The safety envelope - -The safety tier is the other piece that is not yet settled, and at 13-ID it carries an extra leg the other APS beamlines do not. Clearances (the safety forms that must be active to start) are issued at the [APS Site](../aps/index.md#safety-and-governance), not on the beamline, and 13-ID links up to them rather than restating them. What is specific to this station is the stack of hazard classes that an experiment Clearance would have to carry together: a hard X-ray beamline, plus the class-4 double-sided heating lasers at the sample, plus the pressurized gas membrane system that loads the diamond anvil cell. Those three land with the instruments that bring them, and the high-pressure sample environment is the novelty here (`HP-1`). - -The PSS search-and-secure permit signals and the front-end and photon shutters are absent from the EPICS-native config, so the Enclosure permit leaves and the interlock structure are carried pending and are not invented here (`PSS-1`). - -### The laser-safety permit leaf - -13-ID adds a distinct enclosure permit axis the rest of the fleet has not needed: a dedicated laser-safety permit gating laser emission, separate from the X-ray PSS leaf. A Koyo safety PLC governs whether the heating lasers may emit into the enclosure. CORA models this as an Enclosure permit concern on the laser-emission axis, not as a device. It is carried pending and its logic is not invented here (`LASER-1`, `PSS-1`); the heating capability of the cell stays open-loop on commanded power and is not a closed-loop controller (`HEAT-1`). - -### Where this lands - -The concrete Zone, Conduit, and Policy instances, the operator pool, and both safety leaves (the PSS X-ray permit and the laser-emission permit) materialize when the deployment approaches the point where CORA drives 13-ID, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's 13-ID content lives, the first extreme-conditions deployment (high-pressure diamond anvil cell), and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at 13-ID | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes 13-ID new - -13-ID is CORA's first extreme-conditions deployment. The fleet has modelled thermal sample environments (the graduated `TemperatureController`), magnetic ones (the graduated `Magnet`), and pump-probe lasers (the graduated `Laser`), but never a high-pressure one. 13-ID holds the sample in a diamond anvil cell (DAC): the anvils are squeezed by a gas membrane (a PACE5000 pneumatic controller) to the megabar regime, the sample is heated from both sides by two fibre lasers to thousands of kelvin, and the pressure and temperature are read optically in situ (thermal-emission spectroradiometry for temperature; ruby fluorescence, Raman, and Brillouin for pressure). The X-ray probe is otherwise familiar powder and single-crystal diffraction; the novelty is entirely the sample environment. - -### The PressureCell family (graduated) - -13-ID introduced one device class no existing catalog Family then covered: the high-pressure sample cell. It has since graduated to the catalog, earned across 13-ID and PETRA III P02 (the fleet's second diamond-anvil-cell environment). The name was chosen via the naming-r3 gate. - -| Catalog family | Presents | What it is | Earned across | -| --- | --- | --- | --- | -| `PressureCell` | Regulator (membrane pressure) | a high-pressure sample environment (the diamond anvil cell): membrane gas pressure loading, double-sided laser heating, and in-situ pressure / temperature metrology, as one Asset | 13-ID and PETRA III P02 (`PRESSURE-1`) | - -The name is deliberately the bare, regime-generic role-noun `PressureCell`, not `HighPressureCell` (the qualifier names the regime, the `OpticalTable` to `Table` mistake), nor `DiamondAnvilCell` (the qualifier names the implementation mechanism, which would force a near-duplicate family for the large-volume press or a clamp cell). `PressureCell` spans the DAC, the large-volume press, and clamp cells, so it did not fragment when the next high-pressure environment landed. It graduated to the catalog across 13-ID and PETRA III P02; further high-pressure environments (APS HPCAT 16-ID, the sibling 13-BM-D large-volume press in the same GSECARS source tree, the 4-ID pressure cell) now bind the graduated Family (`PRESSURE-1`). - -The cell is modelled as **one Asset** presenting the `Regulator` Role for its membrane pressure (the PACE5000 setpoint and readback, settling to a target). Its double-sided laser heating and its in-situ pressure / temperature metrology are capabilities of the same cell, not separate families. It does not swallow the metrology spectrometer (which binds the catalog `Camera`) or the X-ray detectors; those are sibling Assets. - -### The heating lasers are not the Laser family - -The two fibre lasers that heat the DAC sample do **not** bind the catalog `Laser` Family. CORA binds by Role, not mechanism: a heating laser is a power-delivery / thermal-actuation role, distinct from the pump-probe `Laser` (4-ID, LCLS-MFX, whose model-versus-hazard question heating does not touch). Binding them to `Laser` would corrupt the signal that hold protects. They are the heating capability of the `PressureCell`. Whether that capability is ever a clean `TemperatureController` is `HEAT-1`: the live heating is open-loop on commanded power (`13IDD:US_LaserPower` / `DS_LaserPower`) with temperature inferred from emission, so today it is a power actuator, not a temperature `Regulator`. The upstream and downstream beams are one device with two sides (balanced double-sided heating), not two instances. - -### No new families on the XRD spine - -The X-ray probe spine reuses the catalog throughout: the silicon DCM binds `Monochromator` (the 2-BM precedent); the K-B and carbon mirrors bind `Mirror` with their curvature as `PseudoAxis`; the slits bind `Slit`; the clean-up pinhole binds `Aperture`; the attenuator binds `Filter`; the DAC positioning stage binds `Goniometer` (the i03 Smargon precedent); the Eiger2 / Pilatus area detectors and the LightField metrology spectrometer bind `Camera`; the ion chambers and photodiode bind `FluxMonitor`; the Dante MCA binds `EnergyDispersiveSpectrometer`; the incident energy binds `PseudoAxis`; the fibre illumination binds the catalog `Backlight` (graduated across the MX / imaging fleet); the machine state binds the loose `StorageRing`. - -High-pressure diffraction is **not** a new technique: it reuses the pending `diffraction` (4-ID / 8-ID / CSX / i19) and `powder_diffraction` (i11) Methods, with high pressure a Plan-level sample-environment difference (the 4-ID high-pressure-diffraction precedent). The Practices render unlinked, pending (`TECH-1`). - -### Deliberately not here yet - -- **The PressureCell membrane / load control (`PRESSURE-1`).** The family has graduated to the catalog (earned across 13-ID and P02); the membrane / gas-loading control detail remains a staff confirmation. -- **The heating-control binding (`HEAT-1`).** Whether any heating path closes a temperature-setpoint loop (a clean `TemperatureController`) versus the open-loop power actuation modelled here is a staff confirmation. -- **The laser-safety PLC and the metrology excitation lasers (`LASER-1`).** The Koyo DL205 PLC is the laser-emission enclosure permit axis, an Enclosure concern, not a device; the Verdi / Raman excitation lasers live on a separate metrology host (`13RAMAN2`). -- **The detector 2theta-arm transform (`DET-1`).** The swing transform binds `PseudoAxis`, but its live prefix was seen only in a Galil test template, so the binding is deferred rather than invented. -- **The 13-BM stations and the large-volume press (`HP-1`).** A different multi-anvil probe spine, out of this station's scope; would bind the catalog `PressureCell` Family when exposed. -- **The diffraction Methods.** Whether high-pressure powder and single-crystal diffraction enter CORA's catalog is an owner decision; the Practices render unlinked, pending (`TECH-1`). -- **The simulated devices and full asset-tree scenarios.** No `test_13_id_d_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the GSECARS 13-ID team to confirm before the model can be trusted.* - -13-ID was reverse-engineered from the GSECARS EPICS support tree ([CARS-UChicago/GSECARS-EPICS](https://github.com/CARS-UChicago/GSECARS-EPICS)), so the control handles on the [device pages](index.md) are the beamline's real PVs, reconstructed from the `iocBoot` startup scripts, the `CARSApp/Db` device templates, and the `CARSApp/op/adl` screens rather than confirmed by staff. This is an EPICS-native source (not a dodal or BITS Python roster), so the device-to-PV reconstruction is rougher and carried at medium confidence. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | Are 13-ID-A (first optics) and 13-ID-D (endstation) separate hutches, and how does the laser-safety enclosure relate? | Two enclosures: a shared `13-ID-optics` zone and the `13-ID-D` endstation; the laser-safety PLC adds a laser-emission permit axis. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The 13-ID undulator (shared across 13-ID-C/D/E), energy-tracked with the mono. | An undulator, not surfaced as a device in the support tree read. | The source Asset detail. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MACHINE-1 | Nice-to-have | The storage-ring state 13-ID reads. | Observe-only machine state, a loose `StorageRing`; PVs pending. | The machine-state observation. | -| MONO-1 | Blocks-go-live | The 13-ID-A Si monochromator crystal cut, the energy range, and the energy partition rule. | A silicon double-crystal `Monochromator`; the energy is a `PseudoAxis` (`13IDE:En`). | The monochromator and incident-energy Assets. | -| OPT-1 | Nice-to-have | The K-B and carbon mirror coatings, the curvature / ellipticity axes. | Focusing mirrors bound to `Mirror`; curvature / ellipticity a `PseudoAxis`. | The mirror Asset detail. | -| OPT-2 | Nice-to-have | The blade-axis roles of the beam-defining and DAC table-top slits (DACV / DACH). | Slits bound to `Slit`. | The slit Asset detail. | -| APERTURE-1 | Nice-to-have | The clean-up pinhole and its X / Y / Z carriers. | The opening bound to `Aperture`, the carriers `LinearStage`. | The pinhole Asset. | -| ATTN-1 | Nice-to-have | The attenuator foil set (`13IDD:filter:`) and whether it folds into `Filter` or earns a distinct `Attenuator` kind. | The attenuator bound to `Filter` (the 2-BM precedent). | The attenuator's catalog home. | - -### The high-pressure sample environment - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| HP-1 | Blocks-build | How is the diamond anvil cell configured: the membrane pressure range, the double-sided laser-heating geometry, and the in-situ pressure / temperature metrology, and are they one cell or separate units? | One `PressureCell` Asset presenting the `Regulator` Role for the membrane pressure (PACE5000), with laser heating and metrology as its capabilities. | The DAC modelling; the CORA structural choice is on [Model](#the-pressurecell-family-graduated). | -| HEAT-1 | Blocks-go-live | Does any heating path close a loop on a temperature setpoint (a clean `TemperatureController`), or is the live laser heating open-loop on commanded power with temperature inferred from emission? | Open-loop on commanded power (`13IDD:US_LaserPower` / `DS_LaserPower`), temperature read by spectroradiometry; a power actuator, not a temperature `Regulator`. | The heating-control modelling. | -| PRESSURE-1 | Nice-to-have | The `PressureCell` membrane / gas-loading / pressure-ramp control detail, beyond the PACE5000 setpoint / readback. | The `PressureCell` Family has graduated to the catalog (earned across 13-ID and P02); the membrane / load control detail is pending. | The PressureCell control modelling. | -| LASER-1 | Blocks-go-live | The Koyo laser-safety PLC (`13IDD_laserPLC:`) enable / enclosure signals, and the metrology excitation lasers on the separate `13RAMAN2` host. | The PLC is a laser-emission enclosure permit axis (not a device); the excitation lasers are a cell metrology capability. | The laser-safety permit and the excitation lasers. | - -### Sample stage and detection - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SAMPLE-1 | Blocks-go-live | The DAC positioning stage / micro-diffractometer axes (Galil X / Z / Y / Omega and the Newport XPS-16 trajectory stage) and the single-Omega geometry. | A `Goniometer` (the i03 Smargon precedent); Galil-vs-XPS controller and single Omega are settings. | The sample-stage modelling. | -| DET-1 | Blocks-go-live | The XRD detector assignment (Eiger2 9M versus the Pilatus 1M CdTe / Si), the detector 2theta-arm transform (seen only in a Galil test template), and the flux / fluorescence channel map. | The Eiger2 / Pilatus bind `Camera`; the 2theta swing binds `PseudoAxis` (binding deferred); the ion chambers bind `FluxMonitor` and the Dante MCA `EnergyDispersiveSpectrometer`. | The detector modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the EPICS PV handles reconstructed from the GSECARS support tree current and correct? | The handles in the descriptor are reconstructed from the support tree and carried confirm at medium confidence. | Verifying each Asset's control handle. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit signals, plus the laser-safety enclosure permit. | Permit leaves to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent and the high-pressure gas supply the membrane controller uses. | Photon beam, cooling water, vacuum, and process gas. | The Supply observations. | -| GOV-1 | Nice-to-have | The APS / GSECARS operator pool and safety-review structure. | Carried pending on the APS Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Blocks-go-live | Do high-pressure powder and single-crystal diffraction enter CORA's catalog as Capabilities / Methods? | Deferred: carried as pending Practices reusing the `powder_diffraction` (i11) and `diffraction` (4-ID) Methods, with high pressure a Plan-level sample-environment difference; none coined. | The diffraction Capabilities. | diff --git a/docs/deployments/19-bm/notes.md b/docs/deployments/19-bm/notes.md deleted file mode 100644 index 702cb45671d..00000000000 --- a/docs/deployments/19-bm/notes.md +++ /dev/null @@ -1,104 +0,0 @@ -# Notes - -## Techniques - -*What 19-BM is designed to do, as intent. Design-phase.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../aps/index.md#the-techniques-adapted-here) is how a facility adapts it. 19-BM is pre-build, so the techniques below are design intent: the APS Practices that will bind them are carried pending on the [APS site page](../aps/index.md#the-techniques-adapted-here). The function view survives the eventual equipment choices, which is why it can be written before the hardware is procured. - -19-BM is a single-mode beamline: filtered white-beam tomography. There is no monochromator and no mirror, so unlike 2-BM there is no beam-mode or energy-change technique. The beam spectrum is set by selecting filters in the F3-30 unit, and the science variety is in the acquisition cadence, not the optics. - -| Technique | Catalog Method | What it is for | -| --- | --- | --- | -| Filtered white-beam tomography | `tomography` | the standard micron-resolution CT scan | -| Continuous-rotation tomography | `continuous_rotation_tomography` | high-throughput acquisition, the autonomous workhorse | -| Streaming tomography | `streaming_tomography` | live reconstruction feedback | -| Dark / flat fields | `dark_field`, `flat_field` | the reference frames every reconstruction needs | -| First light | `first_light` | commissioning the beam onto the detector | - -A few points of intent shape the model: - -- **Autonomy and throughput are the point.** 19-BM is built to run unattended at a high scan cadence with a robotic sample changer feeding it. The technique layer is ordinary tomography; what is distinctive is the autonomous operation around it (see [Governance](#governance)) and the sample-exchange loop (see [Sample](sample.md)). -- **Spectrum is set by filtering, not optics.** Selecting Si / Ge / Cu filters in the F3-30 unit hardens or softens the white-beam spectrum. This replaces the energy-selection techniques 2-BM has, which depend on its monochromator. -- **Single beam mode.** There is one set of optics and one mode, so there is no beam-mode-change technique to model. - -The concrete acquisition recipes (scan sequences, exposure, filter choices) are not written yet; they join as the beamline approaches commissioning. See [Open questions](#open-questions) for what must be confirmed first. - -## Governance - -*Who will act at 19-BM, and the trust shape that will gate it. Design-phase.* - -Governance at 19-BM follows the same model as the 2-BM pilot: people and autonomous agents are facility principals at the [APS Site](../aps/index.md#safety-and-governance), 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). - -19-BM is pre-build, so this shape is not yet instantiated. The concrete Zone, Conduit, and Policy instances, and the 19-BM operator pool, land when the beamline approaches commissioning, following the [2-BM governance](../2-bm/governance.md) shape. The APS clearances (the safety forms that must be active to start) are issued at the APS Site, not on the beamline, and the beamline links up to them. - -### Autonomy is first-class here - -19-BM is "Fast Autonomous Computed Tomography": running unattended at a high scan cadence with a robotic sample changer is the reason the beamline exists. That makes it the deployment where CORA's supervisory agents are intended to go from seeded-but-dormant to operational. The agents are already facility principals at APS, carried pending on the [APS site page](../aps/index.md#safety-and-governance): - -- The `RunSupervisor` watches a running scan and can hold it; 19-BM is where that supervision is expected to be enabled and to climb from observe-and-advise toward holding and truncating stalled runs. -- The autonomous loop also needs a way to **start** runs without an operator (queue the next sample, start its scan), which the spine does not yet expose to an agent. 19-BM is the forcing case for that capability; it is a design question, not a copy from 2-BM. - -Like every agent in CORA, these act only by issuing a command the spine already exposes, through the same authorized path a person uses. None of this is built yet; 19-BM reserves the seam. - -### The robotic sample changer gate - -The robotic sample changer requires a separate safety review before implementation (recorded in the FDR). In CORA terms that review issues a Clearance that must be Active before the changer may operate, so autonomous loading cannot start until the review is on file. The changer Asset, its Clearance gate, and the autonomous loading flow are carried as an [open question](#open-questions) (ROBOT-1) until the design and the review land. - -## Model - -*The developer's by-kind index: where each CORA aggregate's 19-BM content lives, a second BM beamline that reuses the families 2-BM established and coins none of its own, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at 19-BM | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What is deliberately not here yet - -- **Integration scenarios.** No `test_19bm_*.py` registers 19-BM Assets into the event store. Scenario code is where Assets become real, and hard-registering a design-phase, moving-target beamline would commit speculative structure. It lands when the design firms and the team approves. -- **Vendor Models.** No catalog Model is bound: the sample stages, the detector hardware, and the robotic changer are all procured after the FDR and are carried as [open questions](#open-questions), not bindings. -- **New catalog Families.** 19-BM coins none of its own. The two passive families it pushed past the rule-of-three threshold (`Window`, with two more Be windows; `Collimator`, with two more Pb collimators) have since been promoted to catalog Families under the passive beam-path tier; 19-BM's windows and collimators now bind them. -- **The autonomy build.** The `RunSupervisor` enablement and the missing run-start capability that 19-BM's autonomous operation needs are real CORA work, not documentation; see [Governance](#governance). They land as their own slices. -- **The robotic sample changer.** Deferred behind its separate safety review (ROBOT-1). -- **Operations and experiment views.** A runbook and live experiment view for an unbuilt beamline would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the 19-BM team to confirm before the model can be trusted.* - -19-BM is in the design phase, so almost every value on the [device pages](index.md) is a Final Design Report specification, not a commissioned measurement. Each row below is a fact the beamline team or the FDR owns, not a CORA modelling choice. It is a delete-on-answer queue: when an item is answered, the answer lands in the descriptor and the row is removed (with the reason in the commit). Priorities are `Blocks-build` (needed before the model is built for real), `Blocks-go-live` (needed before first users), and `Nice-to-have`. - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-build | What are the EPICS PV names for each device, and does 19-BM follow the 2-BM TomoScan / MCTOptics IOC layout? | Control handles are unassigned; CORA leaves each device handle empty (no PV) until the control system is up. | Wiring each Asset to a real control handle. | -| PSS-1 | Blocks-build | What are the PSS permit signals and access-interlock names for 19-BM-A, 19-BM-C, and 19-BM-D? | Each enclosure exists with a permit signal to be named (ICMS APS_1181415). | The Enclosure permit signals. | -| ENC-1 | Blocks-build | 19-BM-C and 19-BM-D share a downstream-wall guillotine held open during operation, so they act as one shielded volume. Do they share a single PSS search-and-secure, and should CORA model them as one Enclosure or two coupled ones? | Modelled as two Enclosures today (19-BM-C carries no Assets); the coupling is noted, not yet a structural link. | The Enclosure shape for the C and D volumes. | -| BLEPS-1 | Blocks-go-live | How should the BLEPS equipment-protection chain (beamline vacuum, and the cooling water plumbed in series across the Be window and the photon stop) map onto CORA Supplies and the beam-availability signal? | Vacuum and cooling water are beamline-scope Supplies, one each, whose faults the BLEPS also folds into beam availability, following 2-BM; no separate equipment-protection aggregate. | The BLEPS-to-Supply mapping. | - -### Sources and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| FILTER-1 | Nice-to-have | How should the F3-30 two-bank Si/Ge/Cu filter unit be modelled: one selector over the combinatorial effective thicknesses, or one selector per bank? And what fills bank 2 slot 5? | One `Filter` Asset whose selectable foils are a per-Asset setting plus a position-to-thickness calibration, as at 2-BM; the combinatorial map is a setting, not a family split. | The filter selector modelling and the bank 2 slot 5 value. | - -### Endstation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| STAGE-1 | Blocks-go-live | What are the sample rotary and linear positioning stages (the manipulator design was out of FDR scope)? | A rotary stage plus a linear positioning stage, reusing the `RotaryStage` and `LinearStage` Families, models unbound. | The sample stage Model bindings. | -| ROBOT-1 | Blocks-go-live | What is the robotic sample changer, and what is the separate safety review it requires before implementation? How should CORA gate autonomous loading on it? | The changer is one Positioner Asset that loads and unloads Subjects; its operation is gated by a Clearance that must be Active, issued after the separate safety review. Modelled when the design and review land. | The sample-changer Asset, its Clearance gate, and the autonomous loading flow. | -| TRIG-1 | Blocks-go-live | What is the high-throughput trigger and sync scheme: is the sample rotary TTL encoder the master clock, and is PSO-style fly-scan triggering used? | A single `TimingController` carries the scheme; the rotary encoder is the candidate master clock; conditioner and PSO use to be confirmed. | The trigger / sync chain. | - -### Detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | Which scintillator, microscope optics, and camera will be procured for the indirect-detection system? | A scintillator, a visible-light microscope (composed as the cross-facility `Microscope` Assembly presenting the Detector Role), and a camera; models unbound until procurement. | The detector hardware Model bindings. | diff --git a/docs/deployments/2-id/notes.md b/docs/deployments/2-id/notes.md deleted file mode 100644 index 5a1b88cf22c..00000000000 --- a/docs/deployments/2-id/notes.md +++ /dev/null @@ -1,134 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of 2-ID is designed to do, as intent. Design-phase.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../aps/index.md#the-techniques-adapted-here) is how a facility adapts it. This scaffold models 2-ID's 2-ID-D microprobe hutch, so the technique below is the scanning fluorescence one, carried as design intent. The function view survives the eventual hardware choices, which is why it can be written before the optics are confirmed. - -### Scanning fluorescence microscopy - -The microprobe focuses the monochromatic beam through a Fresnel zone plate to a small spot and rasters the sample through it, recording an X-ray fluorescence spectrum at each point with an energy-dispersive detector. Element maps are fit from the per-point spectra downstream (the EAA `XRF-Maps` lineage: scan data to fitted maps). - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Scanning XRF mapping | `scanning_fluorescence_microscopy` (pending) | 2D fly raster or 1D step scan of the sample through the focused spot; a fluorescence spectrum per point | - -This is a **new modality** for CORA. Every other deployment images by full-field projection and a rotation; this one builds an image point by point from a focused probe. There is no catalog Method for point-raster scanning fluorescence, so `scanning_fluorescence_microscopy` is named here but **not coined**: it renders unlinked, and the [APS Practice](../aps/index.md#the-techniques-adapted-here) that adapts it is carried pending (`METHOD-1`). The Method is earned into the catalog when 2-ID enters the pilot scope and a naming review accepts it, not in a design-phase scaffold. The coining decision is recorded on [Model](#deliberately-not-here-yet). - -### Energy - -2-ID-D runs monochromatic, the energy set by the upstream monochromator (assumed double-crystal, range unconfirmed, `MONO-1`). Scanning XANES (stepping the energy across an absorption edge per pixel) is a world-fact capability of the beamline but is absent from EAA's `aps_mic` code path, so it is not modelled here (see [Not modelled yet](#not-modelled-yet)). - -### Not modelled yet - -These are techniques the beamline is known to do but that this scaffold defers, because EAA does not evidence them or because they need hardware not yet modelled: - -- **Scanning fluorescence tomography.** A rotation over a sequence of XRF maps. This is a Plan setpoint over the scanning-XRF Method, not a separate Method (mirroring the 2-BM decision that laminography is a tomography Plan at a tilt setpoint), and it needs a rotation axis the endstation is not yet modelled with (`ENV-1`). It joins when the rotation axis is confirmed. -- **Micro-XANES and ptychography.** Named by world-facts about the beamline but absent from EAA's `aps_mic` code path. Ptychography in particular needs a coherent-diffraction (transmission) detector this scaffold does not model. Modelling either now would be invention. - -The concrete acquisition recipes (scan ranges, dwell times, target elements, energies) are not written yet; they join as the deployment approaches the point where CORA drives 2-ID. See [Open questions](#open-questions) for what must be confirmed first. - -## Governance - -*Who will act at 2-ID, and the trust shape that will gate it. Design-phase.* - -Governance at 2-ID follows the same model as the 2-BM pilot: people and autonomous agents are facility principals at the [APS Site](../aps/index.md#safety-and-governance), 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). - -2-ID is a design-phase scaffold in CORA, so this shape is not yet instantiated. The 2-ID operator pool and beamline-scientist assignments are not modelled ahead of confirmation; CORA does not invent a 2-ID operator roster. - -What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [APS Site](../aps/index.md#safety-and-governance), not on the beamline, and the beamline links up to them rather than restating them. - -2-ID-D adds one governance shape the tomography pilots do not have: an **autonomous alignment agent in the loop**. The EAA microprobe agent drives the zone-plate autofocus and drift-correction loop, and its own examples gate every action behind an operator confirmation, with motion and beam disabled by default. In CORA's model that maps cleanly: EAA registers as an [Agent](#how-eaa-fits) whose proposals become Decisions, and the permit and clearance adjudication is the interpose point where an agent's proposed move is allowed or denied. The default-deny posture EAA already carries is the shape CORA's Conduit and Policy would enforce, not a new invention. - -The concrete Zone, Conduit, and Policy instances, the operator pool, and the agent-authority policy land when the deployment approaches the point where CORA drives 2-ID, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's 2-ID content lives, a scanning-fluorescence microprobe whose EAA autofocus loop dissolves into a CORA-conducted Run with an agent in the loop, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at 2-ID | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### How EAA fits - -This scaffold is mined from the [Experiment Automation Agents (EAA)](https://github.com/AdvancedPhotonSource/EAA) APS-microprobe integration (`packages/eaa-imaging/.../tool/imaging/aps_mic`) and its [2-ID-D launcher](https://github.com/AdvancedPhotonSource/eaa_driver_scripts_aps_2idd). EAA is read as data about the beamline, not copied as a design. CORA does not add a "confirm the EAA tool" row anywhere; it dissolves EAA into three things it already models: - -- **Conductor replaces the orchestration.** EAA's `scan_control` runs the autofocus loop (acquire a 2D map, take a line scan, register it, step the `zp_z` focus axis, minimise the spot width) and submits the `fly2d` / `step1d` rasters over the EPICS scanRecord. That set-then-measure-until-criterion sequencing is what CORA's Conductor takes over: CORA owns the [Run lifecycle](../../architecture/modules/run/index.md) (start, hold, abort, close), the durable scan state, and the stopping governance. EAA fuses policy and sequencing in one loop; CORA draws the seam through the middle. -- **EPICS stays floor.** The EPICS scanRecord and sscan IOC, the motor PVs, the hardware-triggered raster, and the downstream `XRF-Maps` fitting are the floor and the compute edge. CORA observes and conducts over them; it never replaces them. -- **EAA registers as an Agent.** EAA's tactical decide loops (the LLM agent loop and the deterministic Bayesian-optimization parameter tuner) register as an external [Agent](../../architecture/modules/agent/index.md). Each proposed move and objective value becomes a Decision, with the LLM route recorded through the inference-recorder provenance path. EAA's own per-tool default-deny gate (operator confirmation required, motion and beam disabled by default) is exactly the interpose point CORA's permit and clearance adjudication occupies. - -The net is regime-2 for CORA's runtime model: a CORA-conducted, multi-step compute-and-move Run, with an external agent proposing inside the loop. That is the shape the edge-runtime work anticipates, surfacing here as a concrete first consumer rather than a hypothetical. - -### Deliberately not here yet - -These are the parts of 2-ID this scaffold leaves out on purpose. Each is a CORA scope or naming decision, not a fact the beamline team needs to supply, so it lives here rather than on [Open questions](#open-questions). - -- **The sister experiment hutch and the hutch roster.** The descriptor models one root Unit Asset `2-ID` with one experiment hutch (`2-ID-D`). Whether the sector adds a sister station (a 2-ID-E-class hutch) as a second hutch sub-tree, and where the shared optics sit, is held until `TOPO-1` resolves the roster. The root identity and `facility_code` binding do not migrate when it does: adding a hutch adds Component sub-trees, it does not re-home the root. This mirrors the 32-ID scaffold modelling only 32-ID-C and deferring 32-ID-B. - -- **Coining the scanning-fluorescence Method.** `scanning_fluorescence_microscopy` is a new modality (point-raster XRF, mechanistically unlike full-field projection). A design-phase scaffold coins no Method, so it is named and rendered unlinked, carried as a pending Practice (`METHOD-1`). It is earned into the catalog when a confirmed scenario uses it and a naming review accepts the name. - -- **Scanning fluorescence tomography as a Plan, not a Method.** A rotation over a sequence of XRF maps is a Plan setpoint over the scanning-XRF Method, the same way laminography is a tomography Plan at a tilt setpoint at 2-BM. It is not a separate Method, and it waits on a confirmed rotation axis (`ENV-1`). - -- **Micro-XANES and ptychography.** Named by world-facts but absent from EAA's `aps_mic` code path; ptychography also needs a coherent-diffraction detector this scaffold does not model. Modelling either now would be invention. - -- **Integration scenarios and vendor Models.** No `test_2id_*.py` registers 2-ID Assets, and no vendor Models are bound. Scenario code is where Assets become real, and hard-registering a simulation-mined, pre-confirmation beamline would commit speculative structure. Both 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). - -## Open questions - -*What CORA needs the 2-ID team to confirm before the model can be trusted.* - -2-ID is a design-phase scaffold mined from the [EAA](https://github.com/AdvancedPhotonSource/EAA) APS-microprobe integration and its [2-ID-D launcher](https://github.com/AdvancedPhotonSource/eaa_driver_scripts_aps_2idd). The launcher is a simulation and EAA does not describe the source optics, so almost every value on the [device pages](index.md) is carried as a fact still to confirm. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are recorded on [Model](#deliberately-not-here-yet) instead). It is a delete-on-answer queue: when an item is answered, the answer lands in the descriptor and the row is removed, with the reason in the commit. Priorities are `Blocks-build` (the answer changes the structure of the model, so CORA cannot finalize the shape without it), `Blocks-go-live` (a placeholder is fine for the description, but the real value is needed before CORA observes or drives the hardware), and `Nice-to-have`. - -### Topology and scope - -The one structural unknown: the Sector 2 hutch roster and where the shared optics sit. The answer decides how many experiment hutches hang off the `2-ID` root and whether the source optics are one shared train or per-hutch. - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TOPO-1 | Blocks-build | What is Sector 2's experiment-hutch roster (2-ID-D plus which sister stations), which hutch do the source optics serve, what is the upstream optics-hutch identity, and what is the post-APS-U layout of the sector? | One root Unit Asset `2-ID` with one modelled experiment hutch `2-ID-D`; the sister hutch(es) and the optics-hutch are unmodelled pending this answer. | The hutch roster, the optics-hutch Enclosure, and one-vs-many hutch sub-trees in the [descriptor](index.md). | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | What are the EPICS PV handles (and drive crates / IOC hosts) for each modelled device, and the Bluesky / scanRecord configuration for the raster? | Control handles are unassigned; CORA leaves each device handle empty. | Wiring each Asset to a real control handle. | -| PSS-1 | Blocks-go-live | What is the PSS search-and-secure permit signal for the 2-ID-D hutch (and the other hutches once `TOPO-1` resolves the roster)? | The 2-ID-D hutch exists with a permit signal to be named. | The Enclosure permit signal. | - -### Sources and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-go-live | The Sector 2 insertion-device source: device type, period, gap, and whether one source feeds more than one hutch. | One `InsertionDevice` Asset (undulator); type and period unconfirmed. | The insertion-device specs. | -| SRC-2 | Nice-to-have | The front-end and beam-defining optics between the source and the zone plate (front-end mask, window, white-beam and beam-defining slits), which EAA does not describe. | None modelled; the source stretch from front end to zone plate is carried as undescribed. | The front-end and beam-defining optics. | -| MONO-1 | Blocks-go-live | The monochromator: is it a double-crystal Si monochromator, what is its crystal and energy range, what are its axes, and which optics hutch is it in? | One `Monochromator` Asset, double-crystal, energy range unconfirmed; located upstream. | The monochromator presence, crystal, axes, and energy model. | -| OPTICS-1 | Blocks-go-live | The probe-forming Fresnel zone plate parameters (outermost-zone width, diameter, material) that set the spot size, and the order-sorting aperture that pairs with it. | One `ZonePlate` Asset (catalog Family) with a `zp_z` focus axis; the order-sorting aperture is folded in, not separately modelled. | The zone-plate spec and the order-sorting aperture. | - -### Sample-scanning endstation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| AXIS-1 | Blocks-go-live | The sample-scanning axis complement: the horizontal scan axis (EAA evidences vertical `samy` and standoff `samz` but not the horizontal raster axis), and the coarse-stage vs fine-piezo split a microprobe carries. | One coarse `SamplePositioning` stack (`LinearStage`); the horizontal scan axis and coarse/fine split unconfirmed. | The sample-stage axes and the coarse/fine model. | -| ENV-1 | Nice-to-have | The sample environment: any in-situ stage (cryo, heating), and whether the endstation carries a rotation axis (which scanning fluorescence tomography would need). | No sample environment and no rotation axis modelled. | The sample-environment Fixtures and any rotation axis. | - -### Detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The energy-dispersive fluorescence detector: model, number of elements / segmentation, and energy resolution. | One fluorescence-detector Asset bound to the catalog `EnergyDispersiveSpectrometer` Family; model and channels unconfirmed. | The detector Model binding. | -| DET-2 | Nice-to-have | The detection readout chain: the preamplifier (EAA names a `Preamp1`), the EPICS scalers, and the I0 flux monitors (ion chambers) the scan normalizes against. | A preamplifier, scalers, and flux monitors exist as the readout chain; identities unconfirmed and not separately modelled. | The readout-chain Assets and the normalization model. | - -### Supplies - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SUP-1 | Nice-to-have | What continuously-available supplies does the 2-ID-D endstation draw on (cooling water, and any sample-environment gases)? | A photon beam and cooling water; sample-environment supplies unconfirmed. | The Supply records. | diff --git a/docs/deployments/32-id/notes.md b/docs/deployments/32-id/notes.md deleted file mode 100644 index de1934780c4..00000000000 --- a/docs/deployments/32-id/notes.md +++ /dev/null @@ -1,126 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of 32-ID is designed to do, as intent. Design-phase.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../aps/index.md#the-techniques-adapted-here) is how a facility adapts it. This scaffold models 32-ID's TXM endstation, so the techniques below are the TXM ones, carried as design intent. The function view survives the eventual hardware choices, which is why it can be written before the optics are confirmed. - -### TXM nano-tomography - -The transmission X-ray microscope images the internal structure of a sample at nanometre-class resolution by magnifying the transmitted beam through a Fresnel zone plate, then rotating the sample for a tomographic reconstruction. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Nano-tomography | `tomography` | step-scan projections over a rotation, magnified by the zone-plate optics | -| Zernike phase-contrast nano-tomography | `tomography` | the phase ring is inserted for phase contrast; a Plan setting over the same Method, not a separate Method | - -Both realize `cora.capability.tomography` and need the [TXM sample stage](sample.md) and the [TXM detector](detector.md). Phase contrast is a configuration of the same tomography Method (the phase ring inserted), mirroring the 2-BM decision that laminography is a tomography Plan at a tilt setpoint rather than a new Method. - -### Energy and beam mode - -32-ID delivers white or monochromatic beam, selected by the P4-50 mode shutter. The monochromatic branch uses the Si(111) monochromator over a 7 to 40 keV range. Whether CORA models the white-to-mono switch as a new Capability or as an extension of the existing `energy_change` vocabulary is an open design decision recorded on [Model](#model); the world-fact half (the switch structure) is `MODE-1` on [Open questions](#open-questions). - -### Not modelled yet - -32-ID's other techniques run on instruments this scaffold defers (see [Model](#deliberately-not-here-yet)): white-beam high-speed imaging and ultrafast diffraction (32-ID-B), in-situ additive-manufacturing imaging (32-ID-B), and projection microscopy. Their Methods join when those instruments are modelled. - -The concrete acquisition recipes (scan sequences, energies, exposure) are not written yet; they join as the deployment approaches the point where CORA drives 32-ID. See [Open questions](#open-questions) for what must be confirmed first. - -## Governance - -*Who will act at 32-ID, and the trust shape that will gate it. Design-phase.* - -Governance at 32-ID follows the same model as the 2-BM pilot: people and autonomous agents are facility principals at the [APS Site](../aps/index.md#safety-and-governance), 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). - -32-ID is a design-phase scaffold in CORA, so this shape is not yet instantiated. The 32-ID operator pool and beamline-scientist assignments are not modelled ahead of confirmation; CORA does not invent a 32-ID operator roster. - -What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [APS Site](../aps/index.md#safety-and-governance), not on the beamline, and the beamline links up to them rather than restating them. 32-ID adds hazard classes beyond the 2-BM tomography envelope, a class-4 laser on the additive-manufacturing rig, pressurized helium and cryogens, that an experiment Clearance would carry; those land with the instruments that bring them, which are deferred (see [Model](#deliberately-not-here-yet)). - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives 32-ID, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's 32-ID content lives, a TXM nano-tomography beamline whose optic classes graduated once FXI shared them, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at 32-ID | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### Deliberately not here yet - -These are the parts of 32-ID this scaffold leaves out on purpose. Each is a CORA scope decision, not a fact the beamline team needs to supply, so it lives here rather than on [Open questions](#open-questions). - -- **The canted branch structure.** The descriptor models one root Unit Asset and one optics train. Whether 32-ID becomes two root Assets (per branch) is held until `TOPO-1` resolves the canted geometry. The root identity and `facility_code` binding do not migrate when it does: a one-to-two split adds Component sub-trees, it does not re-home the root. - -- **The white-to-mono beam-mode vocabulary.** Whether the mode switch is a new Capability or an extension of the existing `energy_change` Capability is decided when the mode is modelled, not now. The world-fact half (the switch structure and sequence) is `MODE-1`; the vocabulary half is this decision. - -- **High-speed imaging and ultrafast diffraction (32-ID-B).** White-beam high-speed imaging reuses the imaging spine, but ultrafast white-beam diffraction (HSID) produces diffraction patterns, which have no precedent in CORA's all-imaging catalog. Whether diffraction is in CORA's scope is an owner decision; until it is made, neither instrument is modelled and no diffraction Capability is coined. - -- **The additive-manufacturing laser rig (32-ID-B).** The powder-bed-fusion rig is a user-brought, actuated, non-X-ray energy source with no Family or Role precedent. The default is to model the class-4 laser as a `Clearance` hazard on an experiment, not as an Asset CORA drives. Whether CORA ever orchestrates the laser is an owner decision. - -- **The projection microscope (PM).** The source docs for the PM are still "space holder", and its most distinctive parts (a helium-atmosphere KB system, a robotic sample-exchange arm) are the least documented. Modelling it now would be invention. The robotic sample changer in particular would force a sample-changer shape CORA does not have; it waits until the PM is documented and a real device list exists. - -- **Integration scenarios and vendor Models.** No `test_32id_*.py` registers 32-ID Assets, and no vendor Models are bound. Scenario code is where Assets become real, and hard-registering a design-phase, pre-APS-U-mixed beamline would commit speculative structure. Both 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). - -## Open questions - -*What CORA needs the 32-ID team to confirm before the model can be trusted.* - -32-ID is a design-phase scaffold built from the published [32-ID docs](https://github.com/decarlof/32id-docs), which mix pre-APS-U and current values, so almost every value on the [device pages](index.md) is carried as a fact still to confirm. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are recorded on [Model](#deliberately-not-here-yet) instead). It is a delete-on-answer queue: when an item is answered, the answer lands in the descriptor and the row is removed, with the reason in the commit. Priorities are `Blocks-build` (the answer changes the structure of the model, so CORA cannot finalize the shape without it), `Blocks-go-live` (a placeholder is fine for the description, but the real value is needed before CORA observes or drives the hardware), and `Nice-to-have`. - -### Topology and scope - -The one structural unknown: how the canted source and its branches map onto CORA's Asset model. The answer decides whether 32-ID is one root Asset or two. - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TOPO-1 | Blocks-build | 32-ID is canted: two undulators feeding two branches. Do `32-ID-B` and `32-ID-C` run off separate beams (two canted branches), and does the `32-ID-A` optics set (mask, slits, monochromator, mode shutter) serve both branches or is it duplicated per branch? Which undulator feeds which branch? | One root Unit Asset `32-ID` with one optics train; the branch multiplicity is unmodelled pending this answer. | One-vs-two root Assets and one-vs-two beam walks in the [descriptor](index.md). | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | What are the EPICS PV handles (and drive crates / IOC hosts) for each modelled device? | Control handles are unassigned; CORA leaves each device handle empty. | Wiring each Asset to a real control handle. | -| PSS-1 | Blocks-go-live | What are the PSS search-and-secure permit signals for the three hutches (`32-ID-A`, `-B`, `-C`)? | Three hutches exist with permit signals to be named. | The Enclosure permit signals. | -| BLEPS-1 | Nice-to-have | Are the BLEPS (equipment-protection) fault and status signals readable as PVs for an external observer, and which map to a utility versus a specific device? CORA observes outcomes only; it never models the interlock logic. | Utility faults map to Supply status, device faults to an Asset condition; the matrix is not modelled. | The Supply and Asset condition mapping. | - -### Sources and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-go-live | The exact device types and parameters of the two canted undulators (the source table lists "Planar 1.35" downstream and "Planar 2.8" upstream; a "U33" tuning curve is published). How do these labels relate, and what are the periods and gaps? | Two `InsertionDevice` Assets, downstream and upstream, planar; periods and the U33 relationship unconfirmed. | The insertion-device specs. | -| SRC-2 | Nice-to-have | The fixed front-end mask aperture and position, and the front-end window stack (count, material, thickness). | A beam-defining `Mask` near 24 m and a `Window` (Be assumed); sizes unconfirmed. | The front-end mask and window specs. | -| MONO-1 | Blocks-go-live | The Si(111) monochromator detail: per-axis motors, energy range over the 7 to 40 keV span, and whether it drives from a saved per-energy table. | One `Monochromator` Asset, Si(111), 7 to 40 keV; axes and saved positions unconfirmed. | The monochromator axes and energy model. | -| MODE-1 | Blocks-build | The white-beam to monochromatic switch (the P4-50 mode shutter with its white-beam stop and combined mono stops). Is this a per-branch hard split (one branch always white, one always mono) or a switchable mode on one optics set, and what is the switching sequence and interlock? | A `ModeShutter` plus beam stops; switching is a coordinated, interlocked move, structure tied to TOPO-1. | The beam-mode model (and whether it is a new Capability or an `energy_change` extension, decided on [Model](#model)). | -| LAYOUT-1 | Nice-to-have | A single z-coordinate reference for the layout. The published docs give per-hutch positions but no common origin. | z values are carried as approximate from-source and flagged confirm. | Exact device z positions. | - -### TXM endstation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TXM-1 | Blocks-go-live | Is the published TXM component list current post-APS-U, or does it carry pre-APS-U hardware? Specifically the granite stages, the rotation stage (Aerotech assumed), and the sample-positioning stack (Kohzu assumed). | The published overview is taken as current; stage models and axes carried confirm. | The TXM stage Assets and models. | -| OPTICS-1 | Blocks-go-live | What is the beam-condensing optic upstream of the sample: a capillary condenser, a condenser zone plate, or KB optics? | One `Condenser` Asset bound to the catalog Family; optical type unconfirmed. | The condenser optic identity. | -| OPTICS-2 | Blocks-go-live | The objective Fresnel zone plate parameters (outermost-zone width, diameter, material) that set the TXM resolution. | One `ZonePlate` Asset bound to the catalog Family; parameters unconfirmed. | The zone-plate spec. | -| OPTICS-3 | Nice-to-have | The Zernike phase ring used for phase contrast: its parameters and whether it is inserted or retracted per scan. | One `PhaseRing` Asset bound to the catalog Family; inserted/retracted state not modelled. | The phase-ring spec and state model. | - -### Detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The TXM detector camera model, sensor, and frame rate. | One `Camera` Asset; model and sensor unconfirmed. | The camera Model binding. | -| DET-2 | Nice-to-have | The TXM indirect-detection objective magnification set and the scintillator material and thickness. | An `Objective` and a `Scintillator` Asset; details unconfirmed. | The detector optics specs. | - -### Supplies - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SUP-1 | Nice-to-have | Is the TXM flight path helium-filled or evacuated, and what gas supplies does the endstation draw on? | A flight path exists; its gas is unconfirmed (the projection microscope uses helium, the TXM is unconfirmed). | The Supply records and flight-path model. | diff --git a/docs/deployments/4-id/notes.md b/docs/deployments/4-id/notes.md deleted file mode 100644 index aecfb386bb9..00000000000 --- a/docs/deployments/4-id/notes.md +++ /dev/null @@ -1,172 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of 4-ID is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../aps/index.md#the-techniques-adapted-here) is how a facility adapts it. 4-ID's techniques are diffraction, magnetism, and polarization, none of which exist in CORA's imaging-heritage catalog yet, so the Methods below render unlinked and are carried pending until one enters the pilot scope (`TECH-1`). The function view survives the eventual hardware and catalog choices, which is why it can be written before the Methods are coined. - -### Single-crystal diffraction - -The Huber diffractometers at 4-ID-G orient a single crystal and scan reciprocal space, measuring scattered intensity as a function of momentum transfer. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| X-ray diffraction | `diffraction` | reciprocal-space scans on the Eulerian or high-pressure diffractometer; Method not yet in catalog | -| High-pressure diffraction | `diffraction` | the high-pressure diffractometer with a pressure cell; a Plan setting over the same Method | - -Both need the [diffractometers](sample.md) and the [detectors](detector.md). Whether the reciprocal-space coordination (hklpy2) is modelled as a `PseudoAxis` inside an `Assembly(Diffractometer)` is the design recorded on [Model](#deliberately-not-here-yet); the world-fact half (the circle geometry) is `DIFF-1`. - -### Magnetic and resonant scattering - -4-ID's signature: resonant scattering across an absorption edge, in an applied magnetic field and at low temperature, to probe magnetic and electronic order. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Resonant magnetic scattering | `magnetic_scattering` | scattering in field (2 T or high-field magnet) at low temperature; Method not yet in catalog | -| Resonant elastic scattering | `resonant_scattering` | energy-resonant scattering across an edge; Method not yet in catalog | - -These need the [sample environment](sample.md) (magnet plus temperature controller) and the monochromator's energy control. - -### Polarization analysis - -The phase retarders set the incident X-ray polarization, and the polarization analyzer resolves the scattered-beam polarization; together they enable dichroism and polarization-dependent scattering. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| X-ray magnetic circular dichroism | `xmcd` | circular polarization set by the phase retarders; Method not yet in catalog | -| Polarization-analyzed scattering | `magnetic_scattering` | the analyzer crystal resolves the scattered polarization; a Plan setting over the scattering Method | - -These need the [phase retarders and polarization analyzer](sample.md). - -### Not modelled yet - -The Raman station's techniques are out of this cut (`TOPO-2`). The concrete acquisition recipes (scan sequences, energies, fields, exposures) are not written yet; they join as the deployment approaches the point where CORA drives 4-ID. Whether diffraction and the polarization / magnetism Methods enter CORA's catalog at all is an owner-scope decision recorded on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at 4-ID, and the trust shape that will gate it. First cut.* - -Governance at 4-ID follows the same model as the 2-BM pilot: people and autonomous agents are facility principals at the [APS Site](../aps/index.md#safety-and-governance), 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). - -4-ID is not yet driven by CORA, so this shape is not yet instantiated. The 4-ID operator pool and beamline-scientist assignments are not modelled ahead of confirmation; CORA does not invent a 4-ID operator roster (a placeholder `4-ID Beamline Scientist` is carried pending on the [APS Site](../aps/index.md#safety-and-governance)). - -What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [APS Site](../aps/index.md#safety-and-governance), not on the beamline, and the beamline links up to them rather than restating them. 4-ID adds hazard classes beyond the imaging envelope, superconducting magnets with high stored energy and cryogens, a pump-probe laser, and pressurized high-pressure cells, that an experiment Clearance would carry; those land with the instruments that bring them as the sample environment firms (`MAG-1`, `SAMPLE-1`). - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives 4-ID, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's 4-ID content lives, the diffraction / magnetism / polarization deployment whose loose families graduated across the fleet, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at 4-ID | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### Loose-Family graduation - -4-ID introduced eight device classes CORA had not earned into the catalog. Graduation needs two or more independent CORA deployments AND a settled abstraction. The 8-ID XPCS deployment adds the second independent beamline for `TemperatureController`, `Transfocator`, and `PositionMonitor`. `TemperatureController` has since graduated to a catalog Family: the parallel Diamond i22/i03/i11 rule-of-three settled the settable-actuator abstraction, and it presents the new `Regulator` Role. `Transfocator` has likewise graduated to a catalog Family: a CRL focusing optic earned across eight deployments, so 4-ID's CRL now reuses it like any catalog Family (its lens material and lenslet count stay a per-Asset spec, `OPT-2`). `PhaseRetarder` has likewise graduated to a catalog Family: a phase-retarder optic earned across 4-ID (three diamond phase-retarder stages), PETRA III P09 (shared phase-retarder circles), and PETRA III P22 (a third consumer via the shared P09 optics), and it presents the `Positioner` Role. `PolarizationAnalyzer` has likewise graduated to a catalog Family: a polarization-analysis positioner earned across 4-ID / i10 / ID32 / P09, so 4-ID's analyzer now reuses it like any catalog Family (its analyzer-crystal spec stays a per-Asset detail, `POL-2`). `PositionMonitor` has likewise graduated to a catalog Family: its own Sensor Family earned across the wide fleet that shares it (APS 4-ID/8-ID/9-ID, the NSLS-II beamlines, and the imaging and MX beamlines), the cross-facility review resolving the fold-vs-promote question in favour of promote (distinct from the graduated `FluxMonitor` by measuring beam position and centroid, not flux; the per-Asset position-versus-intensity split stays open, `BPM-1`). The `Diffractometer` is the one that landed: as the `Assembly(Diffractometer)` blueprint (4-ID + 8-ID), which composes the catalog `Goniometer` Family, with an 8-ID Fixture scenario. `Magnet` has since graduated to a catalog Family: 4-ID was its first consumer, and the Diamond i10-1 and ESRF ID32 magnets brought it to a rule-of-three, settling the settable-field abstraction, so it presents the `Regulator` Role like `TemperatureController` (its per-Asset field range and control handles stay a per-Asset spec, `MAG-1`). `Laser` has since graduated to a catalog Family: an optical sample laser earned across 4-ID, LCLS-MFX, and the PSI SwissFEL endstations (Alvra, Bernina, Cristallina), one Family spanning pump-probe and alignment/reference lasers as a per-Asset purpose (SAMPLE-1). All names were cleared by the naming-r3 review during the catalog-graduation pass. - -| Loose Family | Presents (when graduated) | Status | -| --- | --- | --- | -| `TemperatureController` | Regulator | GRADUATED: catalog Family on the Diamond i22/i03/i11 rule-of-three; presents Regulator, requires Settable; 4-ID device details still to confirm (TEMP-1) | -| `Transfocator` | Positioner | GRADUATED: catalog Family, a CRL focusing optic earned across eight deployments; 4-ID's CRL reuses it, lens spec still to confirm (OPT-2) | -| `PositionMonitor` | Sensor | GRADUATED: catalog Family presenting Sensor, earned across the wide fleet that shares it; distinct from FluxMonitor by measuring beam position not flux; 4-ID position-vs-intensity split still to confirm (BPM-1) | -| `PhaseRetarder` | Positioner | GRADUATED: catalog Family across 4-ID / P09 / P22; presents Positioner; 4-ID phase-retarder specs still to confirm (POL-1) | -| `PolarizationAnalyzer` | Positioner | GRADUATED: catalog Family across 4-ID / i10 / ID32 / P09; presents Positioner, analyzer-crystal spec still to confirm (POL-2) | -| `Magnet` | Regulator | GRADUATED: catalog Family on the 4-ID + i10-1 + ID32 rule-of-three; presents Regulator, the field a settable process variable; 4-ID device field ranges and control PVs still to confirm (MAG-1) | -| `Laser` | (no Role) | GRADUATED: catalog Family, an optical sample laser earned across 4-ID / LCLS-MFX / Alvra / Bernina / Cristallina, one Family spanning pump-probe and alignment/reference lasers as a per-Asset purpose; the SAMPLE-1 model-versus-hazard question stays open | -| `Diffractometer` | Positioner (Assembly) | LANDED as `Assembly(Diffractometer)` in the catalog, composing `Goniometer` (4-ID + 8-ID); 8-ID Fixture scenario landed, the 4-ID Fixture is the follow-on | - -### Deliberately not here yet - -These are the parts of 4-ID this cut leaves out on purpose. Each is a CORA scope decision, not a fact the beamline team needs to supply, so it lives here rather than on [Open questions](#open-questions). - -- **The 4-ID Diffractometer Fixture.** The `Assembly(Diffractometer)` is now in the catalog (composing the `Goniometer` Family) and materialized by the 8-ID Fixture scenario (see the [8-ID model page](../8-id/notes.md#the-diffractometer-assembly-landed)). 4-ID's two Huber diffractometers (the Eulerian cradle and the high-pressure diffractometer) are still modelled here as plain devices with their circle axis maps; decomposing them into a `Goniometer` Asset (the sample circles plus centring) plus any detector-arm `RotaryStage` circles and binding a 4-ID Fixture is the follow-on, gated on the circle-role confirmation (`DIFF-1`). The Assembly is the shared blueprint; the Fixture is per-beamline. - -- **The Raman station.** `4-ID-Raman` is out of this cut because its device config did not extract (a symlink that did not resolve in the source clone). Its devices and whether it is a fifth enclosure are `TOPO-2`; it is a world-fact gap, tracked on [Open questions](#open-questions), not a scope decision. - -- **The 6-ID-B fork and the psic diffractometer.** A second instrument repo, `BCDA-APS/6idb-bits`, is a fork of `polar-bits`: its devices are almost entirely the same `4id*` PVs, with a grafted 6-ID-B endstation (a `psic` six-circle diffractometer at `6idb1:`, a CRL at `6idbSoft:TRANS:`). It is not an independent beamline, so it was used only as a second source to enrich this 4-ID descriptor (the `emag` magnet axes, the Euler diffractometer chi/phi circles), not to build a 6-ID-B deployment. The genuine 6-ID-B endstation (the `psic` diffractometer) is a future deployment, not modelled here. This fork also means the fleet recurrence report counts `polar-bits` and `6idb-bits` as two beamlines when they are one physical beamline, so 4-ID's own recurrence signal for `Magnet` / `TemperatureController` / `Diffractometer` rests on a single beamline (each of these has since graduated on a rule-of-three earned across other beamlines: `Magnet` at i10-1 and ID32). - -- **The diffraction / magnetism / polarization Methods.** Whether these techniques enter CORA's catalog (which has been all-imaging) is an owner decision. The Practices are registered pending and render unlinked; no Method is coined until the technique enters the pilot scope (`TECH-1`). - -- **Peripheral electronics.** The preamplifiers, lock-in amplifier, LabJacks, and high-pressure-cell controllers are present in the beamline config but not modelled as Assets in this cut (`SAMPLE-2`). They join if they prove to be beamline equipment CORA should track. - -- **Integration scenarios and vendor Models.** No `test_4id_*.py` registers 4-ID Assets, and no vendor Models are bound. Scenario code is where Assets become real; hard-registering a first-cut, confirm-pending beamline would commit speculative structure. Both 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). - -## Open questions - -*What CORA needs the 4-ID team to confirm before the model can be trusted.* - -4-ID was reverse-engineered from the beamline's own Bluesky instrument repo ([BCDA-APS/polar-bits](https://github.com/BCDA-APS/polar-bits)), so the control handles on the [device pages](index.md) are the beamline's real PVs, but read from a config snapshot rather than confirmed by staff. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are recorded on [Model](#deliberately-not-here-yet) instead, including which loose Families graduate and the diffractometer Assembly). It is a delete-on-answer queue: when an item is answered, the answer lands in the descriptor and the row is removed, with the reason in the commit. Priorities are `Blocks-build` (the answer changes the structure of the model), `Blocks-go-live` (a placeholder is fine for the description, but the real value is needed before CORA observes or drives the hardware), and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TOPO-1 | Blocks-build | Do the three experiment stations (`4-ID-B`, `4-ID-G`, `4-ID-H`) run off one beam in series, or are any canted / branched off separate beams? Which optics are shared versus per-station? | One root Unit Asset `4-ID` with one optics spine feeding the three stations; KB mirrors and filters are per-station. | One-vs-many beam walks and the shared-vs-per-station optics split in the [descriptor](index.md). | -| TOPO-2 | Blocks-go-live | The `4-ID-Raman` station: what instruments and devices does it carry? (Its `devices.yml` is a symlink that did not resolve in the source clone, so it did not extract.) | The Raman station exists but is out of this cut. | The Raman station devices and a fifth enclosure if warranted. | -| TOPO-3 | Nice-to-have | Two PVs gave ambiguous station hints: `4iddMZ0:` (the SGZ Vortex detector) and `4idkepco:` (a Kepco magnet supply). What station does each sit in? | The Vortex is placed at `4-ID-G` and the Kepco magnet at `4-ID-G`, both confirm. No `4-ID-D` / `4-ID-K` enclosures are declared. | The station assignment for those two devices. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the EPICS PV handles read from the polar-bits config current and correct for each device? | The handles in the descriptor are taken from the config and carried confirm. | Verifying each Asset's control handle. | -| PSS-1 | Blocks-go-live | What are the PSS search-and-secure permit signals for the four hutches (`4-ID-A/B/G/H`)? | Four hutches exist with permit signals to be named. | The Enclosure permit signals. | - -### Sources and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-go-live | The undulator pair on S04ID: device types, periods, and gaps. | One `InsertionDevice` Asset for the pair (`PolarUndulatorPair`); periods unconfirmed. | The insertion-device specs. | -| SRC-2 | Nice-to-have | Should the pair be one Asset or two (one per undulator)? | Modelled as one Asset. | One-vs-two source Assets. | -| MONO-1 | Blocks-go-live | The VDCM monochromator: energy range, crystal set behind `crystal_select`, and per-axis roles. | One `Monochromator` Asset (4idVDCM) with a crystal-select axis; range unconfirmed. | The monochromator energy model. | -| OPT-1 | Nice-to-have | The toroidal pre-focusing mirror and the HHL bendable mirror: coatings, stripes, and the bender / piezo axis roles. | Two `Mirror` Assets; the HHL axis map is taken from the config, coatings unconfirmed. | The mirror specs. | -| OPT-2 | Blocks-go-live | The transfocator (`4idPyCRL:CRL4ID:`): lens material, count, and which stations it focuses. | One `Transfocator` Asset (catalog Family); serves 4-ID-G and 4-ID-H. | The transfocator spec. | -| OPT-3 | Nice-to-have | The per-station KB mirror (`bkb`/`gkb`/`hkb`) internal axis maps. | Three `Mirror` Assets; only the 4-ID-B KB carries a partial axis map. | The KB axis maps. | - -### Polarization - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| POL-1 | Blocks-go-live | The three phase retarders (`pr1`/`pr2`/`pr3`): diamond crystal type, thickness, and how they coordinate to set a polarization state. | Three `PhaseRetarder` Assets (catalog Family), each th/x/y, energy-tracking. | The phase-retarder specs and the polarization-state model. | -| POL-2 | Blocks-go-live | The polarization analyzer (`pol`, th/y): analyzer crystal and the scattered-beam polarization it resolves. | One `PolarizationAnalyzer` Asset (catalog Family) at 4-ID-B. | The analyzer spec. | - -### Diffractometer - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DIFF-1 | Blocks-build | The Huber Eulerian and high-pressure diffractometers: the real circle set (4-circle Eulerian? 6-circle?) and which motor is which circle (omega, chi, phi, two-theta). | Two diffractometers modelled as plain devices with the config's axis maps; the circle roles are partial. | The circle geometry, which decides the `Assembly(Diffractometer)` slot shape (see [Model](#deliberately-not-here-yet)). | -| DIFF-2 | Blocks-go-live | The reciprocal-space coordination: is hklpy2 driving an (h, k, l, energy) pseudo-axis, and over what geometry? | A reciprocal-space PseudoAxis is assumed for the Assembly design; not yet a device. | The pseudo-axis model. | - -### Sample environment - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MAG-1 | Blocks-go-live | The sample magnets: the two 2 T magnets (`bmag`/`emag`) and the high-field magnet (`magnet911`) field ranges and control PVs (the 2 T magnets had no control PV in the config), and the Kepco-driven `gmag`. | Four `Magnet` Assets (catalog Family, graduated); fields and several PVs unconfirmed. | The magnet specs and handles. | -| TEMP-1 | Nice-to-have | The LakeShore 336 and 340 controllers: sensor channels and the sample stages they regulate. | Two `TemperatureController` Assets (catalog Family, presents `Regulator`) at 4-ID-G. | The temperature-controller model. | -| SAMPLE-1 | Nice-to-have | The Ventus laser at 4-ID-H: is it a pump-probe source CORA should model as a device, or only carry as a Clearance hazard? | One `Laser` Asset (catalog Family); modelling-versus-hazard is open. | The laser model or hazard treatment. | -| SAMPLE-2 | Nice-to-have | The preamplifiers, lock-in (`srs810`), and high-pressure-cell controllers (Pace `PC1`/`PC2`) are in the config but not modelled here. Which are beamline equipment versus user-brought? | Deferred as peripheral. | Whether these become Assets. | - -### Detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The Eiger area detector model, sensor, and frame rate. | One `Camera` Asset (`4idEiger:`); model unconfirmed. | The detector Model binding. | -| DET-2 | Nice-to-have | The SGZ Vortex (`4iddMZ0:`): is it a fluorescence / energy-dispersive point detector, and what Family fits? | Bound to the catalog `PositionMonitor` Family as a placeholder; classification unconfirmed (see `TOPO-3`). | The Vortex classification and Family. | - -### Beam-position monitors and supplies - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| BPM-1 | Nice-to-have | The XBPMs, Sydor electrometers, and TetrAMM: which are true beam-position monitors versus intensity (I0) normalizers? | All bound to the graduated catalog `PositionMonitor` Family presenting the Sensor Role. | The monitor classification. | -| SUP-1 | Nice-to-have | The cryogen and process-gas supplies the magnet and low-temperature environments draw on. | Liquid helium and liquid nitrogen carried pending in the descriptor. | The Supply records. | diff --git a/docs/deployments/7-bm/notes.md b/docs/deployments/7-bm/notes.md deleted file mode 100644 index b18a71722cf..00000000000 --- a/docs/deployments/7-bm/notes.md +++ /dev/null @@ -1,117 +0,0 @@ -# Notes - -## Techniques - -*What 7-BM is designed to do, as intent. Design-phase.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../aps/index.md#the-techniques-adapted-here) is how a facility adapts it. 7-BM is multi-technique, and which techniques enter the CORA pilot scope is itself an open question (TECH-1). The function view below survives the eventual equipment choices, which is why it can be written before the hardware is confirmed. - -The beam mode is selected per technique over one set of optics, not a fixed source property (BEAM-1): - -| Technique | Beam mode | Detector modality | Status in CORA | -| --- | --- | --- | --- | -| Tomography | monochromatic | 2D area camera (scintillator-coupled) | reuses the 2-BM Methods unchanged | -| High-speed imaging | white | high-speed movie camera, chopper-gated | new acquisition Method, pending | -| Radiography | focused (~8 keV) | point photodiode, digitizer-read | new acquisition Method, pending | -| Energy-dispersive diffraction | white | germanium energy-dispersive detector | new Method, pending | -| Confocal fluorescence | (docs stub) | spectroscopic detector | deferred until confirmed (the docs page is empty) | - -A few points of intent shape the model: - -- **Tomography is pure reuse.** 7-BM runs the same tomoScan engine as 2-BM (single, vertical, horizontal, mosaic scans), so its tomography binds the existing `tomography` and `mosaic_tomography` Methods and the 2-BM detector shape. No new tomography vocabulary is earned. -- **The new techniques are new acquisition Methods, not new Capabilities.** High-speed movie bursts, point-detector radiography traces, and the energy-to-q EDD measurement are new `Method` rows under the existing `acquisition` and `characterization` Capabilities. They are deployment vocabulary; the device Roles (Detector, Sensor) already exist. They are carried pending until the technique enters scope and its data unit is confirmed (HSI-1, RAD-1, DET-1). -- **Beam mode is an operation mode over one beamline.** Inserting or bypassing the monochromator, filtering the white beam, or focusing with the KB pair picks the spectrum for a technique; it is a mode over one set of optics, not separate beamlines (BEAM-1). -- **Techniques can combine.** The docs note energy-dispersive diffraction running simultaneously with tomography through shared optics; CORA models that as coordinated Runs under one Campaign, not a new combined technique (TECH-1). - -The concrete acquisition recipes (scan sequences, energies, exposure) are not written yet; they join as the techniques enter the pilot scope. See [Open questions](#open-questions) for what must be confirmed first. - -## Governance - -*Who will act at 7-BM, and the trust shape that will gate it. Design-phase.* - -Governance at 7-BM follows the same model as the 2-BM pilot: people and autonomous agents are facility principals at the [APS Site](../aps/index.md#safety-and-governance), 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). - -Because 7-BM runs at the same APS Site as 2-BM, it reuses the APS facility envelope rather than creating a new one: the APS operator pool, the experiment-safety review structure, and the seeded agents are facility-wide and are inherited unchanged. This is the opposite of the TomoWISE deployment, which had to create a new MAX IV Site. 7-BM adds only its own beamline-bound principals (the 7-BM beamline scientists and operators), carried pending on the [APS site page](../aps/index.md#safety-and-governance). - -7-BM is pre-build for CORA, so the concrete trust shape is not yet instantiated. What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the APS Site, not on the beamline, and the beamline links up to them rather than restating them. - -One governance question is sharper at 7-BM than at 2-BM: the flow and combustion hazard surface (flammable gas, fuel vapor, oxygen deficiency, a radioactive check source for detector calibration) is broader than the radiation-only hazard profile of micro-CT. CORA's current position is that this is handled by ESAF clearances plus operator Cautions plus the hutch alarms, not by a separate hazard aggregate. Whether combustion or flammable-gas work needs a review, approve, and expire workflow distinct from the standard ESAF clearance is the single question that would change that (HAZ-1). - -The concrete Zone, Conduit, and Policy instances, and the beamline operator pool, land when the beamline approaches commissioning, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's 7-BM content lives, a flow / combustion deployment whose FlowController grounds the continuous-regulation gap, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at 7-BM | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What is deliberately not here yet - -- **New catalog Families and Methods.** 7-BM does not earn new catalog kinds in this scaffold. The genuinely-new device anatomies are carried as loose families with a tracking question; the new techniques are carried as pending Methods. They are added to the catalog only when a confirmed device or technique and the naming review settle them. This follows the "pilots earn the abstractions" rule: a beamline that is not yet onboarded does not get to mint cross-facility vocabulary. -- **Integration scenarios.** No `test_7bm_*.py` registers 7-BM Assets into the event store. Scenario code is where Assets become real, and hard-registering a design-phase, partly-documented beamline would commit speculative structure. It lands when the techniques enter the pilot scope and the team approves. -- **Vendor Models.** No catalog Model is bound. The vendors named in the docs (Photron, Sierra, Kaeser, IDT, Rigaku) are recorded in the descriptor notes, not bound, because no part is procured into the catalog. -- **Operations and experiment views.** A runbook and live experiment view for an unmodelled beamline would be invention; see the note on the [index](index.md#not-yet-documented). -- **Detector assemblies.** The tomography detector is left as plain devices (scintillator plus camera). It could later compose the cross-facility `Microscope` Assembly that 2-BM and TomoWISE use, once a scenario registers it. - -- **The continuous-regulation runtime (the FlowController setpoint program).** The `FlowController` presents the earned `Regulator` Role and CORA commands its setpoint (a one-shot `SetpointStep`), but a continuous setpoint PROGRAM, a hold or ramp held during a Run while the scan acquires, has no runtime today: the Conductor walks a finite step list, and `SetpointStep` / `ControlPort.write` are one-shot. The regulation loop itself stays device/IOC-owned (the Sierra controller runs it); CORA's gap is expressing and observing the program, not hosting the loop. This is the deepest cross-facility architectural gap the audit named; 7-BM (flow/combustion) is its grounding case alongside i11 / XPD thermal. It is the continuous-regulation axis, deferred to a Stage-0 research note and a later gate-reviewed build, exactly as the event-stream axis was for XFEL/XPCS acquisition (FLOW-1). - -## Open questions - -*What CORA needs the 7-BM team to confirm before the model can be trusted.* - -7-BM is in the design phase and its operations documentation is partial, so this page is long by design: almost every value on the [device pages](index.md) is taken from the 7-BM docs or inferred, not confirmed with staff. Each row below is a fact the beamline team owns, not a CORA modelling choice. It is a delete-on-answer queue: when an item is answered, the answer lands in the descriptor and the row is removed (with the reason in the commit). Priorities are `Blocks-build` (needed before the model is built for real), `Blocks-go-live` (needed before first users), and `Nice-to-have`. - -A note on what 7-BM tests that 2-BM did not: 7-BM is multi-technique (high-speed imaging, radiography, tomography, energy-dispersive diffraction, fluorescence), runs white, monochromatic, and focused beam, and carries a flow and combustion sample environment. The questions below concentrate on the new shapes; the tomography path itself reuses the 2-BM model unchanged. - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-build | What are the EPICS PV handles for each device? | Control handles are unassigned; CORA leaves the device handle empty. | Wiring each Asset to a real control handle. | -| PSS-1 | Blocks-build | What are the PSS search-and-secure permit signals for the 7-BM-A and 7-BM-B hutches? | Both hutches exist with permit signals to be named. | The Enclosure permit signals. | -| HAZ-1 | Blocks-go-live | Do combustion, flammable-gas, or radioactive-check-source experiments need a review / approve / expire workflow distinct from the standard APS ESAF clearance? | The flow and combustion hazard surface is handled by ESAF clearances plus operator Cautions plus alarms, not a separate hazard aggregate. | Whether a Hazard lifecycle is earned beyond Clearance and Caution. | - -### Sources and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-build | What is the 7-BM source after APS-U? The docs do not state it. | A bending-magnet source, carried `confirm`, mirroring the 2-BM source representation. | The `Source` device and beamline `source` field. | -| BEAM-1 | Blocks-build | Which beam mode (white, monochromatic via the DMM, or focused via the KB mirrors) is canonical for each technique, and is the DMM split-stripe dual-energy mode used routinely? | Beam mode is a per-technique choice over one set of optics, not a fixed source property. | Binding each technique and Practice to a beam mode. | -| OPT-1 | Nice-to-have | Which optics sit in the routine pilot path: the DMM, the multilayer mirror, the KB focusing pair, the polycapillary optics, and the channel-cut calibration crystals? | The DMM, multilayer mirror, and KB pair are modelled; the polycapillary and channel-cut crystals are deferred until a confirmed technique needs them. | Which optics are Assets and which stay deferred. | -| CHOP-1 | Blocks-go-live | Is the rotary chopper permanently installed or fitted per time-resolved run, is its duty cycle a commanded setting or a manual mechanical re-index, and is the photoeye a tracked Sensor or inseparable floor wiring? | A loose `Chopper` family, pending whether it is a new catalog Family or an existing `Shutter` / `RotaryStage` plus settings. | The chopper modelling boundary. | - -### Techniques - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Blocks-go-live | Which techniques are in scope for the CORA pilot: tomography, high-speed imaging, radiography, energy-dispersive diffraction, confocal fluorescence, and which combine (the docs note EDD running simultaneously with tomography)? | Tomography reuses the 2-BM Methods; the other techniques are design intent, carried pending on the [APS site Practices](../aps/index.md#the-techniques-adapted-here). | Which Methods and Practices the pilot binds. | - -### Detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | Is the germanium energy-dispersive detector the same physical device as the fluorescence MCA, and is XRF a routine standalone technique or only an EDD energy-scale calibration step? | One `EnergyDispersiveSpectrometer` device presenting the Sensor Role, with fluorescence as a calibration step, not a separate detector. | One versus two Sensor-backed detector Assets, and whether a spectroscopy Method is earned. | -| RAD-1 | Blocks-go-live | For time-resolved radiography, what is the point-detector chain (PIN diode plus ADQ14 digitizer or oscilloscope plus DataGrabber), and is one acquisition trace one Dataset? | A `Photodiode` device presenting the Sensor Role; the digitizer / scope / DataGrabber stay on the floor; the data unit is unconfirmed. | The radiography detector Family and the Run / Dataset shape. | -| HSI-1 | Blocks-go-live | For high-speed imaging, is one chopper-gated movie burst one Run / Dataset (and the N-sequence set one Campaign), and how are top-up-blanked frames represented (invalid-marked, dropped, gap)? | One high-speed `Camera`; the acquisition unit and blanking semantics are unconfirmed. | The Run / Dataset / Acquisition shape for time-resolved capture. | - -### Sample environment - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| FLOW-1 | Nice-to-have | The command-vs-read half is settled: CORA COMMANDS the regulated flow / air setpoints (the graduated catalog `FlowController` Family presents the earned `Regulator` Role; a one-shot `SetpointStep`), not read-back-only. What remains open is the continuous-regulation runtime, a setpoint PROGRAM (a hold or ramp held during a Run, orthogonal to the scan step-list; the loop device/IOC-owned, CORA programs and observes), which no runtime expresses yet. | command-vs-read settled (commands); `FlowController` graduated (earned across i22 / 7-BM / LIX / XFP); the setpoint-program runtime is the continuous-regulation axis (see model.md + its Stage-0 research). | The continuous-regulation setpoint-program runtime primitive. | -| ENV-1 | Blocks-go-live | Is there an installed combustion, spray, or fuel-injection device at 7-BM, or is combustion an intended use served by the air, gas, and vacuum infrastructure? | No combustion rig Asset is modelled; combustion is served by the facility Supplies and bound to the specimen Subject. | Whether a combustion-rig Asset and a fuel-vapor Caution are modelled. | - -### Controls and site - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TIMING-1 | Nice-to-have | Should the DG645 delay generators, softGlue FPGA, Machine Status Link P0 reference, and top-up inhibit be one `TimingController` device, or do any of them deserve separate modelling? | One `TimingController` carries the whole scheme, mirroring the 2-BM Timing device. | The timing-subsystem Asset shape. | -| SECTOR-1 | Nice-to-have | Confirm 7-BM is in Sector 7, and whether it shares any governed resource (optics, safety system, compute) with another APS beamline. | 7-BM is a separate beamline in Sector 7 under the APS Site, sharing no governed resource with 2-BM. | The sector label and any cross-beamline shared-resource governance. | diff --git a/docs/deployments/8-3-2/notes.md b/docs/deployments/8-3-2/notes.md deleted file mode 100644 index 8be104b6bd2..00000000000 --- a/docs/deployments/8-3-2/notes.md +++ /dev/null @@ -1,128 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of 8.3.2 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../als/index.md#the-techniques-adapted-here) is how a facility adapts it. 8.3.2 is a hard X-ray micro-tomography beamline: its techniques reuse Methods CORA's catalog already carries. - -### Hard X-ray micro-tomography - -8.3.2 sets the X-ray energy with the monochromator (6,000-43,000 eV from the Superbend source), then rotates the sample on the tomographic rotary stage while the scintillator, objective, and camera record projections. It images non-destructively in 3D at ~1 micron resolution, with absorption and propagation-phase contrast (the detector stack's `camera_distance` sets the propagation distance). - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Tomography | [`tomography`](../../catalog/methods.md) | absorption and propagation-phase micro-CT, the [rotary stage](sample.md) stepped against the [scintillator + camera](detector.md); reuses the catalog tomography Method (the 2-BM pilot) | -| Continuous-rotation tomography | [`continuous_rotation_tomography`](../../catalog/methods.md) | fast fly-scan tomography, the [rotary stage](sample.md) in continuous rotation as the trigger master (`TRIG-1`); reuses the catalog continuous-rotation Method | - -Tomography needs the [incident energy](source.md) set by the [monochromator](source.md), the [rotary stage and sample positioning](sample.md), and the [scintillator + objective + camera](detector.md), with the [detector stack](detector.md) setting the sample-to-detector propagation distance. - -### A new Site on familiar vocabulary - -8.3.2 is the ALS's hard X-ray micro-CT beamline, and it ties into the tomography lineage CORA already models: the same imaging device anatomy as the 2-BM pilot, the NSLS-II FXI design, and the ALBA FAXTOR design (a bending-magnet or insertion-device source, an energy-setting optic, a rotary-stage endstation, and an indirect scintillator + camera detector). It reuses the `tomography` and `continuous_rotation_tomography` Methods directly; none forces a new device family. - -### Not modelled yet - -The concrete acquisition recipes (the fly-scan tomography sequences and their counting times, the flat / dark sequencing, the propagation-phase setups) are not written yet; they join as the deployment approaches the point where CORA drives 8.3.2. See [Open questions](#open-questions) for the world-facts to confirm first, in particular which sample-stack axis is the tomographic rotation (`ROT-1`) and the triggering scheme (`TRIG-1`). - -## Governance - -*Who will act at 8.3.2, and the trust shape that will gate it. First cut.* - -Governance at 8.3.2 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [ALS Site](../als/index.md#safety-and-governance), 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). - -8.3.2 is CORA's first ALS deployment, so ALS is a brand-new Site: the operator pool and the safety-review structure are carried pending on the [ALS Site](../als/index.md#safety-and-governance), shared across the facility's beamlines, until ALS staff confirm them (`GOV-1`). 8.3.2 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives 8.3.2, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. ALS publishes no per-beamline personnel-safety permit signals or photon / front-end shutters, so the Enclosure permit leaves and the interlock structure are carried pending and are not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [ALS Site](../als/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives 8.3.2, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's 8.3.2 content lives, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at 8.3.2 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes 8.3.2 new - -8.3.2 is two things at the Site level and nothing new at the vocabulary level. It is CORA's **first ALS Site** (the Advanced Light Source at LBNL), a re-test of the Site and Federation kernel, and the **first BCS / LabVIEW** control plane CORA models. The ALS originated BCS (the Beamline Control System), so this is the controls house-style's home facility; every prior Site is EPICS (the APS and NSLS-II beamlines), Tango / Sardana (MAX IV, ALBA), or BLISS (the ESRF). Its science is hard X-ray micro-tomography on a Superbend source. - -It also introduces the **data-record descriptor mode**: the device structure is read from the DXchange / DXfile HDF5 metadata schema (verified against the `als-computing/scicat_beamline` ingester and the `als-computing/microct` reconstruction backend), while the live BCS control handles, which are not public, are carried pending. This sits between the FXI mode (real EPICS PVs read from a public profile collection) and the FAXTOR mode (no device manifest at all). - -### No new families (the imaging spine reuses the 2-BM / FXI / FAXTOR precedent) - -8.3.2 coins no new Family. The Superbend binds the catalog `InsertionDevice` (recorded as a Supply, the 2-BM bending-magnet precedent); the energy optic binds `Monochromator`; the slits bind `Slit` and the attenuator binds `Filter`; the sample stack binds `RotaryStage` and `LinearStage`; the detector binds `Scintillator`, `Objective`, and `Camera`, with the detector motion binding `LinearStage`; the machine state binds the loose `StorageRing`. Nothing in the catalog changes. - -### The BCS control plane and the data orchestration - -8.3.2 is the fleet's first BCS / LabVIEW controls house-style. Device IO is BCS, the ALS Beamline Control System, surfaced as scan files (Time Scan, Single Motor Scan, Trajectory Scan) whose headers carry the device-state data record ([`als-computing/als.bcs`](https://github.com/als-computing/als.bcs)). An emerging acquisition layer wraps BCS scans as bluesky ophyd `fly` devices through the LabVIEW BCS API ([`als-computing/bcs-api`](https://github.com/als-computing/bcs-api)). ALS publishes no per-beamline BCS channel manifest, so CORA does not bind the BCS handles here; when bound they would be modelled as opaque edge handles over the `ControlPort`, the way the MX3 and ID32 heterogeneous-control precedents do (`CTRL-1`). The continuous-rotation tomography acquisition runs as a BCS Trajectory Scan; that orchestration is the seam CORA's edge replaces, conducting over BCS rather than replacing it. - -The downstream data movement and reconstruction is a separate, well-developed layer that CORA observes and subsumes at the debrief layer, not data it owns: [`als-computing/splash_flows`](https://github.com/als-computing/splash_flows) moves data with Prefect + Globus to NERSC and ALCF, catalogues it in SciCat, and runs tomography reconstruction (TomoPy / ASTRA / SVMBIR) via [`als-computing/microct`](https://github.com/als-computing/microct). CORA keeps its own data-of-record (the PG event store); the SciCat catalogue is a source-of-truth contest named only at the seam, not a dependency. - -### Deliberately not here yet - -- **The BCS control handles (`CTRL-1`).** No public per-beamline BCS / LabVIEW channel manifest exists; the handles are carried pending, not invented. -- **The detector model (`DET-1`).** The camera, scintillator, and objective are bound to `Camera`, `Scintillator`, and `Objective` but their models are unpublished (detector specs are per-dataset values in the data record), carried fully pending. -- **The rotation-axis identity (`ROT-1`).** The data record's `sample_motor_stack` exposes `axis1pos` / `axis2pos` / `axis5pos`; which is the tomographic rotation is pending. -- **The monochromator detail (`MONO-1`).** The mechanism (multilayer vs crystal), d-spacing, and the energy-axis wiring are carried confirm-pending. -- **The slit and filter detail (`OPT-2`, `FILT-1`).** The full slit blade-axis map and the filter materials / thicknesses are carried confirm-pending. -- **The detector-stack detail (`DET-2`).** The camera-distance / elevation / tilt axis models are named; their travels and the propagation-distance wiring are pending. -- **The hutch grouping (`ENC-1`).** Modelled as a single experiment hutch pending the optics / experiment grouping. -- **The simulated devices and full asset-tree scenarios.** No `test_8_3_2_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). -- **The ALS-U upgrade fate (`ALSU-1`).** Whether 8.3.2 goes dark, is rebuilt, or relocates in the ALS-U dark time (no sooner than October 2027) is a staff question, not modelled here. - -## Open questions - -*What CORA needs the 8.3.2 team to confirm before the model can be trusted.* - -8.3.2 was reverse-engineered from ALS's public facility pages ([als.lbl.gov/beamlines/8-3-2](https://als.lbl.gov/beamlines/8-3-2/), [microct.lbl.gov](https://microct.lbl.gov/)) and the public [als-computing](https://github.com/als-computing) GitHub org, not from a live connection. The device structure is read from the DXchange / DXfile HDF5 data record that the ALS tooling reads, but ALS runs BCS (a LabVIEW Beamline Control System, not EPICS) and publishes no per-beamline channel manifest, so the [device pages](index.md) carry a planned shape with control handles unbound. This is CORA's first ALS Site and its first BCS / LabVIEW controls house-style. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: a single experiment hutch, or a separate optics hutch feeding it? | A single `8-3-2-hutch`. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The Superbend field and critical energy. | A superconducting bending-magnet source, 6-43 keV; field pending. | The source Asset detail. | -| ALSU-1 | Nice-to-have | The ALS-U upgrade fate of 8.3.2: does it go dark, get rebuilt, or relocate, and on what schedule? | Dark time no sooner than October 2027; 8.3.2's fate carried pending. | The deployment roadmap. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MACHINE-1 | Nice-to-have | The ALS storage-ring state 8.3.2 reads (the `source_name` / `current` handles). | Observe-only machine state, a loose `StorageRing`; exact handles pending. | The machine-state observation. | -| MONO-1 | Blocks-go-live | The energy optic: the mechanism (multilayer vs crystal), d-spacing, and how the `energy`, `Z2`, `turret1` / `turret2`, and `TC2` / `TC3` channels relate. | An energy-setting `Monochromator`, 6-43 keV; `energy` the master axis. | The monochromator and energy modelling. | -| OPT-2 | Nice-to-have | The slit blade-axis map (the `hslits_*` and `vslits_*` channels) and handles. | Horizontal + vertical slits bound to `Slit`. | The slit Asset detail. | -| FILT-1 | Nice-to-have | The attenuating-filter materials and thicknesses on the `filter_y` axis. | A filter bound to `Filter`. | The filter Asset detail. | - -### Sample endstation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SAMPLE-1 | Blocks-go-live | The sample-motor stack: the rotary, the sample-centring axes (`sample_x` / `sample_y`), and the role of `axis1pos` / `axis2pos` / `axis5pos`. | A `RotaryStage` plus a `LinearStage`; axis sets and models pending. | The sample-stage modelling. | -| ROT-1 | Blocks-go-live | Which sample-stack axis is the tomographic rotation. | One of the `axisNpos` channels is the rotation; identity pending. | The rotation Asset binding. | -| TRIG-1 | Nice-to-have | The triggering / synchronization scheme for continuous-rotation tomography. | The rotary stage is the master clock feeding the camera trigger. | The trigger wiring. | - -### The detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The detector chain: the camera sensor / frame rate / model, the `scintillator_type`, and the `camera_objective` set. | A `Scintillator` + `Objective` + `Camera`; specs are per-dataset values, model carried pending. | The detector modelling. | -| DET-2 | Nice-to-have | The detector-stack axes (`camera_distance`, `camera_elevation`, `tilt_motor`): models, travels, and which is the propagation distance. | A `LinearStage` detector stack; `camera_distance` the propagation distance. | The detector-stack modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-build | The BCS / LabVIEW control handles per 8.3.2 device (absent from any public manifest). | The handles are unbound, carried pending; the control plane is ALS BCS. | Binding each Asset's control handle. | -| PSS-1 | Blocks-go-live | The ALS personnel-safety permit signals and the photon / front-end shutters (not published per beamline). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent and the cooling-water / beam / power supplies. | Photon beam, cooling water, vacuum, and power. | The Supply observations. | -| GOV-1 | Nice-to-have | The ALS operator pool and safety-review structure (site-level). | Carried pending on the ALS Site, not instantiated per beamline. | The governance principals. | diff --git a/docs/deployments/8-id/notes.md b/docs/deployments/8-id/notes.md deleted file mode 100644 index c57dbcf1019..00000000000 --- a/docs/deployments/8-id/notes.md +++ /dev/null @@ -1,149 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of 8-ID is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../aps/index.md#the-techniques-adapted-here) is how a facility adapts it. 8-ID's signature technique, **XPCS, is now a catalog Method** (`cora.capability.xpcs`): it is the second beamline after LCLS-MFX to need a DAQ-owned high-rate frame stream, which graduated XPCS out of the imaging-heritage catalog. Small-angle scattering and six-circle diffraction stay pending until they enter scope (`TECH-1`). - -### X-ray photon correlation spectroscopy - -XPCS measures the time correlations of a coherent speckle pattern to probe sample dynamics, so it records long, fast time series on an area detector under a precisely gated exposure. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| XPCS | [`xpcs`](../../catalog/methods.md) | coherent-scattering intensity time series on the Eiger / Lambda / Rigaku detectors, gated by the softGlue timing; now a catalog Method. Its acquisition is a DAQ-owned high-rate frame stream with no executing body yet, the [event-stream acquisition axis](#deliberately-not-here-yet) (Stage 1) | -| Small-angle scattering | `small_angle_scattering` | static SAXS on the same detectors; a Plan setting over the same chain | - -Both need the [XPCS sample stage](sample.md), the [coherent detectors](detector.md), and the flight path. The fast shutter and softGlue timing (`XPCS-1`, `XPCS-3`) gate the exposure. - -### Six-circle diffraction - -The 8-ID-E Huber diffractometer orients a single crystal through six circles and scans reciprocal space, sharing the diffraction Method with 4-ID. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Six-circle diffraction | `diffraction` | reciprocal-space scans on the six-circle Huber; shares the 4-ID `diffraction` Method (`TECH-1`) | - -It needs the [diffractometer](sample.md). The reciprocal-space coordination is `DIFF-2`; the reusable `Assembly(Diffractometer)` is on [Model](#deliberately-not-here-yet). - -### Not modelled yet - -The XPCS Method now exists, but the concrete acquisition primitive that executes it (a DAQ-owned high-rate frame stream, not a poll-to-Done capture) does not: that is the [event-stream acquisition axis](#deliberately-not-here-yet), now at Stage 1 (8-ID XPCS is its second beamline after LCLS-MFX). Small-angle scattering and diffraction Methods remain an owner-scope decision (`TECH-1`); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at 8-ID, and the trust shape that will gate it. First cut.* - -Governance at 8-ID follows the same model as the 2-BM pilot: people and autonomous agents are facility principals at the [APS Site](../aps/index.md#safety-and-governance), 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). - -8-ID is not yet driven by CORA, so this shape is not yet instantiated. The 8-ID operator pool and beamline-scientist assignments are not modelled ahead of confirmation (a placeholder `8-ID Beamline Scientist` is carried pending on the [APS Site](../aps/index.md#safety-and-governance)). - -What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [APS Site](../aps/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. 8-ID adds hazard classes beyond the imaging envelope, cryogens at the temperature-controlled sample environments and the user-brought rheometer and robotic sample changer, 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 8-ID, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's 8-ID content lives, the XPCS deployment that added the `xpcs` Method and landed the Diffractometer Assembly, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at 8-ID | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### Loose families held for gate-review - -8-ID adds a second independent APS beamline (after 4-ID POLAR) to three device classes that recur widely: `TemperatureController`, `Transfocator`, and `PositionMonitor`. All three have since graduated to catalog Families. `TemperatureController` graduated when the parallel Diamond i22/i03/i11 rule-of-three settled the settable-actuator abstraction (`ENV-1`), and it presents the new `Regulator` Role. `Transfocator` graduated as a CRL focusing optic Family, distinct from `Mirror` / `ZonePlate` / `Condenser`: it is bound across several beamlines (APS 4-ID/8-ID/9-id, Diamond i22, NSLS-II chx/smi/ixs, SLAC lcls-mfx), and the cross-facility review settled it as the CRL-specific home rather than a general focusing optic. `PositionMonitor` graduated as its own catalog Family presenting the `Sensor` Role, earned across the wide fleet that shares it (APS 4-ID/8-ID/9-ID, the NSLS-II beamlines, and the imaging and MX beamlines), distinct from the graduated `FluxMonitor` by what it measures: beam position and centroid, not flux or intensity. The still-loose `Diagnostic` family (arrival-time and photon-spectrum monitors) stays loose, a separate abstraction that measures timing and spectrum rather than position; only the per-Asset beam-center calibration and the position-versus-intensity channel split stay open (`DIAG-1`). - -| Loose family | Presents (when graduated) | At 4-ID | At 8-ID | -| --- | --- | --- | --- | -| `PositionMonitor` | Sensor | XBPM / Sydor / TetrAMM | Sydor (8-ID-E) + TetrAMM (8-ID-I) | - -`Transfocator` and `TemperatureController` were tracked here too and have since graduated to catalog Families. `Transfocator` is the CRL focusing optic Family the two 8-ID-D lens stacks bind (the lens material and lenslet count stay open, `OPT-3`). `TemperatureController` (#350) presents the `Regulator` Role (the LakeShore 336 at 8-ID-E and the Quantum Northwest holders at 8-ID-I bind it). Neither is held for gate-review any longer. - -`Magnet` was tracked here too on a single physical beamline (4-ID; `6idb-bits` is a 4-ID fork, see the [4-ID model page](../4-id/notes.md#deliberately-not-here-yet)); it has since graduated to a catalog Family on the 4-ID + i10-1 + ID32 rule-of-three (it presents the `Regulator` Role). `Preamplifier` stays loose on that single physical beamline. - -### The Diffractometer Assembly (landed) - -The `Assembly(Diffractometer)` designed during the catalog-graduation pass is now real, and it **composes the `Goniometer` Family** that landed for I03 MX (#340) rather than re-modelling the sample circles. It is in [`catalog/catalog.yaml`](https://github.com/xmap/cora/blob/main/catalog/catalog.yaml) as a flat assembly presenting the Positioner Role, with slots `goniometer` (Goniometer, `Exactly1`, the sample-orientation circles plus centring), `detector_arm` (RotaryStage, `ZeroOrMore`, spanning 8-ID's nu / delta and 4-ID's detector-arm-less geometries), and `reciprocal_space` (PseudoAxis, whose partition rule resolves the hklpy2 inverse kinematics). The distinction from the Goniometer Family is deliberate: the Goniometer is the integrated single-device sample orienter (the I03 Smargon); the Diffractometer is the larger composed scattering instrument that USES one. The integration scenario [`test_8id_diffractometer_setup.py`](https://github.com/xmap/cora/blob/main/apps/api/tests/integration/scenarios/test_8id_diffractometer_setup.py) materializes it end-to-end against Postgres: it installs the four 8-ID-E constituent Assets (a Goniometer for mu / eta / chi / phi, the nu / delta detector-arm circles, and the reciprocal-space axis), defines the Assembly, and registers a Fixture binding the two detector circles to the `detector_arm` slot. The circle-role confirmation remains `DIFF-1` and the reciprocal-space solver rule is `DIFF-2`; the 4-ID Fixture is the follow-on (the Assembly is shared, the Fixture is per-beamline). - -### Deliberately not here yet - -- **The UR5 robotic sample changer.** `RobocartUR5` is a user-brought robotic arm; CORA has no sample-changer shape (the same gap the 32-ID projection-microscope changer raised). It is not modelled (`SAMPLE-2`). - -- **The softGlue timing graph.** The XPCS exposure timing runs on a softGlueZynq FPGA fabric (`8idMZ1:`); it is modelled coarsely as one `TimingController`, not as its full signal graph (`XPCS-3`). - -- **The event-stream acquisition axis (the XPCS execution).** The `xpcs` Method is now in the catalog, but the acquisition primitive that runs it is not: an XPCS Run is a DAQ-owned high-rate frame stream (begin/end a per-frame burst correlated downstream into g2), which CORA's poll-to-Done acquisition bodies (`collect` / `discrete` / `continuous`) cannot execute. 8-ID is the second beamline after LCLS-MFX to hit this, which promoted the event-stream axis to Stage 1 (design-locked, gate-review next; recorded in CORA's design memory). No spine code lands in this pass. - -- **The remaining scattering Methods.** Whether small-angle scattering and six-circle diffraction enter CORA's catalog is an owner decision; their Practices render unlinked, pending (`TECH-1`). - -- **Full asset-tree scenarios and vendor Models.** Beyond the diffractometer Assembly / Fixture scenario above, no `test_8id_*.py` registers the full 8-ID asset tree (the optics spine, the XPCS endstation), 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). - -## Open questions - -*What CORA needs the 8-ID team to confirm before the model can be trusted.* - -8-ID was reverse-engineered from the beamline's own Bluesky instrument repo ([BCDA-APS/8id-bits](https://github.com/BCDA-APS/8id-bits)), so the control handles on the [device pages](index.md) are the beamline's real PVs, read from a config snapshot rather than confirmed by staff. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet), including the catalog graduation and the diffractometer Assembly). 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 | -| --- | --- | --- | --- | --- | -| TOPO-1 | Blocks-build | Are the two undulators canted feeding separate branches, and do the four stations (`8-ID-A/D/E/I`) run off one beam in series or split? | One root Unit Asset `8-ID` with one optics spine feeding the stations in series. | One-vs-many beam walks in the [descriptor](index.md). | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the EPICS PV handles read from the 8id-bits config current and correct? | The handles in the descriptor are taken from the config and carried confirm. | Verifying each Asset's control handle. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit signals for the four hutches. | Four hutches exist with permit signals to be named. | The Enclosure permit signals. | - -### Sources and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-go-live | The two undulators (downstream DSID, upstream USID): types, periods, and whether canted. | Two `InsertionDevice` Assets; periods unconfirmed. | The insertion-device specs. | -| MONO-1 | Blocks-go-live | The MN1 monochromator energy range and crystal. | One `Monochromator` Asset (8idaSoft:MN1); range unconfirmed. | The monochromator energy model. | -| MONO-2 | Nice-to-have | The in-line `idt_mono` (8idaSoft:MONO): is it a second monochromator or a different optic? | Not modelled in this cut. | Whether it becomes a second Asset. | -| OPT-1 | Nice-to-have | The two FMBO mirrors: coatings and the bender / piezo-pitch axis roles. | Two `Mirror` Assets with the config's axis maps; coatings unconfirmed. | The mirror specs. | -| OPT-2 | Nice-to-have | The slit internal axis maps (most slits carried only a base PV in the config). | `Slit` Assets with base PVs; per-blade axes partial. | The slit axis maps. | -| OPT-3 | Blocks-go-live | The two CRL transfocators (rl1, rl2): lens material and the per-lens actuator roles (ten lenses each). | Two `Transfocator` Assets; x/y/pitch/yaw mapped, the ten lens actuators summarized. | The transfocator spec. | - -### Diffractometer - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DIFF-1 | Blocks-build | The six-circle Huber geometry: confirm the circle roles (mu, eta, chi, phi, nu, delta) and which is sample versus detector arm. | A six-circle diffractometer modelled as a plain device with the config's axis map; this confirms the `Assembly(Diffractometer)` slot shape. | The circle geometry and the Assembly slots (see [Model](#deliberately-not-here-yet)). | -| DIFF-2 | Blocks-go-live | The reciprocal-space coordination: is hklpy2 driving an (h, k, l, energy) pseudo-axis over this geometry? | A `PseudoAxis` Asset (psic) is modelled for the reciprocal-space layer. | The pseudo-axis model. | - -### Sample environment - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TEMP-1 | Nice-to-have | The LakeShore 336 controllers and the Quantum Northwest holders: sensor channels and the sample stages they regulate. | `TemperatureController` Assets at 8-ID-E and 8-ID-I. | The temperature-controller model. | -| SAMPLE-1 | Nice-to-have | The rheometer shear-cell: the six axes and the shear modes it supports. | One `Rheometer` Asset (loose Family) with a six-axis map. | The rheometer model. | -| SAMPLE-2 | Nice-to-have | The UR5 robotic sample changer (RobocartUR5): is it CORA-driven, and what is its sample-exchange model? | Deferred; not modelled (CORA has no sample-changer shape). | The sample-changer model. | - -### Detector and XPCS - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The three area detectors (Eiger 4M, Lambda 2M, Rigaku 3M): models, sensors, and frame rates. | Three `Camera` Assets; models unconfirmed. | The detector Model bindings. | -| BPM-1 | Nice-to-have | The Sydor beam-position monitor and the four TetrAMM channels: which are position monitors versus intensity (I0) normalizers? | Bound to the graduated catalog `PositionMonitor` Family presenting the Sensor Role. | The monitor classification. | -| XPCS-1 | Nice-to-have | The fast shutter timing and its role in the XPCS exposure sequence. | One `Shutter` Asset (8ideSoft:fastshutter). | The fast-shutter model. | -| XPCS-2 | Nice-to-have | The flight-path geometry (length, swing) and the beam-stop relationship. | One `FlightPath` Asset (loose Family) plus a `BeamStop`. | The flight-path model. | -| XPCS-3 | Nice-to-have | The softGlue FPGA timing graph (8idMZ1): the signal routing for detector gating. | One `TimingController` Asset; the signal graph is not modelled. | The timing model. | - -### Supplies - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SUP-1 | Nice-to-have | The vacuum and process-gas supplies the flight path and sample environments draw on. | Photon beam, cooling water, and vacuum carried in the descriptor. | The Supply records. | diff --git a/docs/deployments/9-id/notes.md b/docs/deployments/9-id/notes.md deleted file mode 100644 index 3d62e1b2d23..00000000000 --- a/docs/deployments/9-id/notes.md +++ /dev/null @@ -1,145 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of 9-ID is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../aps/index.md#the-techniques-adapted-here) is how a facility adapts it. 9-ID's techniques are coherent surface scattering and grazing-incidence scattering, new to CORA's imaging-heritage catalog, so the Methods below render unlinked and are carried pending until one enters scope (`TECH-1`). - -### Coherent surface scattering - -The CSSI signature: a coherent beam strikes the sample surface at a shallow grazing angle, so the scattered intensity is sensitive to surface structure and, over time, surface dynamics. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Coherent surface scattering | `coherent_surface_scattering` | the grazing-incidence coherent measurement on the area detectors; Method not yet in catalog | -| Surface XPCS | [`xpcs`](../../catalog/methods.md) | time-correlation of the surface speckle pattern; shares the 8-ID `xpcs` catalog Method (its DAQ-owned high-rate-stream execution is the event-stream axis, Stage 1) | - -Both need the [grazing-incidence sample stack](sample.md) (the incidence rotation sets the angle) and the [coherent detectors](detector.md). - -### Grazing-incidence scattering - -GISAXS and GIWAXS read the small- and wide-angle scattering from the grazing-incidence geometry. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Grazing-incidence scattering | `grazing_incidence_scattering` | GISAXS on the Pilatus / Eiger and GIWAXS on the pedestal detector (`TECH-1`) | -| Wide-angle scattering | `wide_angle_scattering` | the GIWAXS leg; shares the i22 WAXS Method | - -It needs the same sample stack and the [WAXS detector](detector.md) on its pedestal. - -### Not modelled yet - -The concrete acquisition recipes (incidence-angle scans, correlation time series, frame rates, exposures) are not written yet; they join as the deployment approaches the point where CORA drives 9-ID. Whether these Methods enter CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at 9-ID, and the trust shape that will gate it. First cut.* - -Governance at 9-ID follows the same model as the 2-BM pilot: people and autonomous agents are facility principals at the [APS Site](../aps/index.md#safety-and-governance), 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). - -9-ID is not yet driven by CORA, so this shape is not yet instantiated. The 9-ID operator pool and beamline-scientist assignments are not modelled ahead of confirmation (a placeholder `9-ID Beamline Scientist` is carried pending on the [APS Site](../aps/index.md#safety-and-governance)). - -What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [APS Site](../aps/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. 9-ID's hazard classes are within the X-ray and vacuum envelope of the optics-and-detector beamlines; user-brought sample environments on the CSSI stack would carry their own hazards on an experiment Clearance, landing 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 9-ID, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's 9-ID content lives, the cleanest pure-reuse case in the APS fleet whose metadata and Data Management PVs are a CORA seam not Assets, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at 9-ID | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### Catalog reuse (what this deployment proves) - -9-ID is the cleanest reuse case in the APS fleet: a coherent-scattering beamline outside the imaging and diffraction cores, and yet every optic and detector binds a Family the catalog already had. `InsertionDevice`, `Monochromator`, `Mirror` (twice: the FMBO pair and the KB pair), `Aperture`, `Filter`, `Slit`, `Hexapod`, `Camera`, `BeamStop`, `LinearStage`, `RotaryStage`, `GenericProbe`, and the graduated `Transfocator` (the CRL focusing optic) all carry it with no new abstraction. That 9-ID needs no new Family is the evidence: the families earned on 2-BM, the diffraction beamlines, and the Diamond deployments cover a beamline none of them were derived from. So this cut adds nothing to `catalog.yaml`. - -### A loose family still held for gate-review - -9-ID's CRL `Transfocator` binds the graduated catalog Family (a CRL focusing optic) that 4-ID, 8-ID, and i22 also use. The cross-facility abstraction review settled the question of its catalog home: it is a CRL-specific Family, not a fold into a general focusing optic, so 9-ID's transfocator is plain catalog reuse now, like its mirrors. What graduation does not resolve is the per-Asset lens spec, the material and lenslet count of this transfocator, which stays open as `OPT-3`. - -The `PositionMonitor`, which appears at 4-ID, 8-ID, and 9-ID, has since graduated into the catalog as its own Family presenting the `Sensor` Role, earned across the wide fleet that shares it (APS 4-ID/8-ID/9-ID, the NSLS-II beamlines, and the imaging and MX beamlines). The fold-vs-promote question that once held it is resolved in favour of promote: it is distinct from the graduated `FluxMonitor` by what it measures, beam position and centroid rather than flux or intensity (`FLUX-1` graduated `FluxMonitor`). Its naming-r3 review was done during that pass. The still-loose `Diagnostic` family (arrival-time and photon-spectrum monitors) is a separate abstraction that measures timing and spectrum, not position, and stays loose; only the per-Asset beam-center calibration and the position-versus-intensity channel split stay open here (`DIAG-1`). - -| Loose family | Presents (when graduated) | At 9-ID | Also at | -| --- | --- | --- | --- | -| `PositionMonitor` | Sensor | TetrAMM + two XBPMs (9-ID-D) | 4-ID, 8-ID | - -### The metadata and Data Management seam - -The 9-ID instrument config carries a large set of metadata PVs (`experiment_name`, `sample_name`, `file_path`, `qmap_file`, `workflow_name`, `measurement_num`, and more) and a `DM_WorkflowConnector` that triggers APS Data Management workflows. These are not beamline hardware: they are where the beamline records what an experiment is and hands its data to downstream processing. That is exactly the job CORA's event-sourced system of record does. So they are modelled as a **seam, not as Assets**: CORA's Run and experiment record subsume the metadata bookkeeping, and the Data Management workflow trigger is the compute seam CORA's conduct path drives over (the same shape as the `DM_WorkflowConnector` that recurs in the APS fleet). Modelling these PVs as devices would mistake the bookkeeping CORA replaces for hardware it observes. - -### Deliberately not here yet - -- **The grazing-incidence sample Assembly.** The CSSI stack (translation, incidence rotation, hexapods, viewing microscope) is modelled as plain devices. Whether it composes into a sample Assembly, the way the 2-BM sample tower and the Diffractometer do, is deferred until a second grazing-incidence beamline gives the abstraction a rule-of-three (`CSSI-1`). - -- **The diagnostic flags and the DAMM mask.** `flag1-3` and the DAMM mask carried only their insertion-motor PVs in the config; they are folded into a descriptor note pending identification, not modelled as Assets (`DIAG-1`). - -- **The remaining scattering Methods.** 9-ID's surface-XPCS Practice now links to the catalog `xpcs` Method (shared with 8-ID; its DAQ-owned high-rate-stream execution is the event-stream axis, Stage 1). Whether coherent surface scattering and grazing-incidence scattering enter the catalog stays an owner decision; those Practices render unlinked, pending (`TECH-1`), and the WAXS Practice shares the i22 one. - -- **The simulated devices.** The instrument config carries simulated motors and detectors (`sim_motor_cssi`, `sim_det_saxs`, and so on) for offline testing; they are excluded from the model. - -- **Full asset-tree scenarios and vendor Models.** No `test_9id_*.py` registers the 9-ID 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). - -## Open questions - -*What CORA needs the 9-ID team to confirm before the model can be trusted.* - -9-ID was reverse-engineered from the beamline's own Bluesky instrument repo ([BCDA-APS/9id_bits](https://github.com/BCDA-APS/9id_bits)), so the control handles on the [device pages](index.md) are the beamline's real PVs, read from a config snapshot rather than confirmed by staff. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet), including the metadata seam and the graduated `PositionMonitor` catalog Family). 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 | -| --- | --- | --- | --- | --- | -| TOPO-1 | Blocks-build | Do the two stations (`9-ID-A`, `9-ID-D`) run off one beam in series, and is there a single undulator or a canted pair? The config showed one undulator (`S09ID:DSID:`) and `9-ID-A` / `9-ID-D` prefixes. | One root Unit Asset `9-ID` with one optics spine feeding 9-ID-D in series; one undulator. | The beam walk and station count in the [descriptor](index.md). | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the EPICS PV handles read from the 9id_bits config current and correct? | The handles in the descriptor are taken from the config and carried confirm. | Verifying each Asset's control handle. | -| CTRL-2 | Nice-to-have | The fly-scan timing: the multi-channel scaler (`9idCSSI:mcs2-01`) and any pulse routing that gates the grazing-incidence scans. | One `GenericProbe` scaler is modelled; the timing graph is not. | The fly-scan timing model. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit signals for the two hutches (`9-ID-A`, `9-ID-D`). | Two hutches exist with permit signals to be named. | The Enclosure permit signals. | - -### Sources and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-go-live | The undulator on S09ID: type, period, and whether a second device or a canted pair exists. | One `InsertionDevice` Asset; period unconfirmed. | The insertion-device spec. | -| MONO-1 | Blocks-go-live | The Kohzu monochromator (`idt_mono`, `9ida:`): energy range, crystal set, and per-axis roles. | One `Monochromator` Asset; range unconfirmed. | The monochromator energy model. | -| OPT-1 | Nice-to-have | The two FMBO mirrors: coatings and the bender / piezo-pitch axis roles. | Two `Mirror` Assets with the config's axis maps; coatings unconfirmed. | The mirror specs. | -| OPT-2 | Nice-to-have | The white-beam apertures (`SL-1`, `SL-2`) and the guard slits (`Slit3/4/5`): the internal axis maps. | `Aperture` and `Slit` Assets with base PVs; per-blade axes partial. | The aperture and slit axis maps. | -| OPT-3 | Blocks-go-live | The JJ CRL transfocator (`9idPyCRL:CRL9ID:`): lens material, count, and which stations it focuses. | One `Transfocator` Asset (the graduated catalog Family). | The transfocator spec. | -| OPT-4 | Nice-to-have | The AVS attenuator (`9idPyFilter:FL1:`): the foil / absorber set. | One `Filter` Asset. | The attenuator model. | -| OPT-5 | Nice-to-have | The KB focusing pair (`9idKB:`): the per-mirror bender axes and the focal geometry (capacitive-sensor suffixes resolved at runtime). | One `Mirror` Asset with four bender axes plus a granite support. | The KB axis map. | - -### Sample - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CSSI-1 | Blocks-build | The grazing-incidence sample geometry: which motor sets the incidence angle, and the translation-vs-rotation roles of the CSSI stack (`9idCSSI:mcs2-01`, the Aerotech fly Z, the Kohzu stage). | A `LinearStage` for translation and a `RotaryStage` for the incidence angle; the Kohzu stage folded into a note. | The sample geometry and whether it composes into an Assembly. | -| CSSI-2 | Nice-to-have | The two Aerotech hexapods (`HP1`, `HP2`): what each aligns (sample, KB, detector). | Two `Hexapod` Assets for sample/optic alignment. | The hexapod roles. | -| CSSI-3 | Nice-to-have | The viewing microscope (`uscope`, `9idCSSI:CR9D1M2`): on-axis sample viewing or a separate optic. | One `Camera` Asset for sample viewing. | The microscope role. | - -### Detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The area detectors: the Pilatus 1M (`PILATUS_1MF:`), the Eiger (prefix a guess), and the WAXS / GIWAXS detector on its pedestal: models, sensors, frame rates. | `Camera` Assets; models unconfirmed. | The detector Model bindings. | -| BPM-1 | Nice-to-have | The TetrAMM (`9idTetra:QUAD1:`) and the two XBPMs (`xpbm1`, `xpbm2`): which are position monitors versus intensity (I0) normalizers? | Bound to the graduated catalog `PositionMonitor` Family presenting the Sensor Role. | The monitor classification. | -| DIAG-1 | Nice-to-have | The diagnostic flag cameras (`flag1-3`) and the DAMM mask (`9ida:CR9A1`): what each is, and whether the flags carry cameras CORA should model. | Folded into a descriptor note; not modelled as Assets (only insertion motors extracted). | The diagnostic identification. | - -### Supplies - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SUP-1 | Nice-to-have | The vacuum and process-gas supplies the focusing optics and detector flight draw on. | Photon beam, cooling water, and vacuum carried in the descriptor. | The Supply records. | diff --git a/docs/deployments/alvra/notes.md b/docs/deployments/alvra/notes.md deleted file mode 100644 index 5944e843cee..00000000000 --- a/docs/deployments/alvra/notes.md +++ /dev/null @@ -1,135 +0,0 @@ -# Notes - -## Techniques - -*What Alvra is designed to do, as design intent. Design-phase: these are Methods CORA would earn, not Methods it has.* - -Alvra runs three technique families, none of which fits the catalog's tomography Methods, so each is carried pending on the [PSI Practices](../psi/index.md) until it is earned. They reuse the same pending Methods CORA's first XFEL, [LCLS-MFX](../lcls-mfx/notes.md#techniques), introduced; Alvra is the second deployment to need them, which is part of the point. They are listed here as design intent, with the shape each would take over the spine and the gap each leans on. - -### Femtosecond optical pump-probe - -Alvra's reason for existing. An optical laser pulse excites the sample a controlled femtoseconds before (or after) the X-ray probe pulse; scanning the delay resolves the dynamics in time. The PALM (THz-streaking) and PSEN (spectral-encoding) arrival-time monitors correct the residual laser-to-X-ray jitter shot by shot. - -- **Spine shape:** a `pump_probe` Method that scans the laser-to-X-ray delay (a `LinearStage` delay axis on the experiment laser) while acquiring per-shot, with the PSEN / PALM monitors correcting jitter. -- **Gap it leans on:** the cross-timing-domain synchronization (LASER-1). The delay axis itself is a positioner; what CORA cannot express is the femtosecond synchronization between the optical-laser and FEL timing domains (the `eco` `lxt` timing chain). This is the same gap LCLS-MFX's `lxt_ttc` SyncAxis exposed, now seen at a second XFEL. - -### Time-resolved X-ray absorption and emission (XAS / XES / HERFD) - -Alvra measures how a sample's electronic structure evolves after the pump: transient X-ray absorption through the incident energy (the double-crystal mono), and X-ray emission through the von Hamos spectrometer. In HERFD mode the incident energy is scanned at a fixed emission line. - -- **Spine shape:** an `xas_spectroscopy` Method binding the `Monochromator` for the incident-energy choreography and the `EmissionSpectrometer` for the emitted spectrum, over a per-shot acquisition. -- **Gap it leans on:** the von Hamos binds the graduated `EmissionSpectrometer` Family (Alvra is a fourth sighting; SPEC-1 now tracks only the analyzer-crystal composition), and the HERFD incident-energy scan reuses the energy-change choreography CORA already models well. The time-resolution makes the acquisition per-shot, which leans on the DAQ gap (DAQ-1). - -### Serial femtosecond crystallography (SFX) - -On the Prime endstation Alvra also runs time-resolved serial crystallography: a stream of microcrystals is delivered into the focused FEL beam; each pulse records a single-shot diffraction pattern before destroying its crystal. The dataset is many single-shot patterns, indexed and merged downstream. - -- **Spine shape:** a `serial_crystallography` Method binding the KB focusing, the sample delivery, the pulse picker, and the Jungfrau detector, over a Run that is a free-running per-shot acquisition rather than a trajectory of points. -- **Gap it leans on:** the per-shot, pulse-ID-tagged event DAQ (DAQ-1). As at LCLS-MFX, this is the technique that most exposes the acquisition-ontology gap: there is no trajectory to walk, only a shot stream to tag and reference. - -### Why none is in the catalog yet - -The catalog's Methods are all tomography-family (`tomography`, `dark_field`, `flat_field`, the alignment and energy-change methods). An XFEL pump-probe station shares none of them: there is no rotation, no flat / dark frame pairing, no storage-ring energy ramp. Coining XFEL Methods now, before the acquisition axis they depend on exists, would be inventing recipes for a spine that cannot yet run them. So each is carried pending, reusing the Method name LCLS-MFX named for it, and the deepest dependency (the event-stream acquisition axis, DAQ-1) is sketched as a design note rather than built. That the same three Methods are now needed at a second, independently-built XFEL is the strongest argument yet that they are real Methods to earn, not LCLS-specific. See [Model](#model) for the gap register. - -## Governance - -*Who would act at Alvra and the trust shape that gates their commands. Design-phase: the principals are facility-level and carried pending.* - -Alvra's principals are facility principals at the [PSI Site](../psi/index.md), not beamline-local: the SwissFEL instrument-scientist and operator pool, and the PSI safety-review body. Both are carried pending in the [site descriptor](../psi/index.md) until the PSI structure is confirmed; the `eco` device library is a controls library, not an organizational record, so it exposes no human roster (GOV-1). CORA's role kernel (the five-role authorization model) is facility-invariant, so Alvra inherits it; what Alvra adds to think about is the same two hazard gates LCLS-MFX raised, now at a second XFEL. - -### The pump-probe laser Clearance - -Alvra runs a class-4 optical laser for pump-probe. CORA carries this as a `Clearance` hazard on the experiment (a facility-issued safety permit that must be Active before laser-on work), the same posture LCLS-MFX takes for its pump-probe laser and 32-ID takes for its additive-manufacturing laser. This is distinct from whether the laser is a driven Asset: the device folds into the catalog `Laser` Family (the LCLS-MFX / 4-ID precedent), while the personnel-safety permit is a Clearance. The two coexist (LASER-1). - -### The PSS permit - -As at every beamline, beam-on work in an enclosure is gated by the facility personnel safety system (PSS). The SwissFEL PSS search-and-secure permit signals are not in the `eco` manifest and are carried pending (PSS-1). Alvra's enclosure structure (a shared Aramis optics hutch plus the Alvra experiment hutch) is itself carried `confirm` because the `eco` PV prefixes encode beamline-line zones (`SARFE10` front end, `SAROP11` optics, `SARES11` endstation), not the access-gated hutch or its safety meaning (ENC-1). The shared optics hutch is the same shared-zone question LCLS-MFX's front-end / transport zone raised, because the Aramis source feeds the Alvra, Bernina, and Cristallina stations (TOPO-1). - -### What is not modelled - -- **Trust instantiation.** No scenario instantiates Alvra trust zones or actors; this is a design-phase modelling exercise, so the governance shape is described, not seeded. It would land, following the [2-BM governance](../2-bm/governance.md) shape, if and when the deployment approaches real scope. -- **The DAQ and acquisition software as principals.** The SwissFEL `sf-daq`, `bsread`, and the `eco` / `slic` scan suite are control-system software on the floor, not CORA actors (see [Controls](controls.md)). When the per-shot acquisition axis is designed (DAQ-1), the question of which principal authorizes a DAQ run is part of that work. - -People and agents are facility principals at the [PSI Site](../psi/index.md); see [Open questions](#open-questions) for the governance items still to confirm. - -## Model - -*The developer's by-kind index: where each CORA aggregate's Alvra content lives, how the device families fold at a second XFEL, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at Alvra | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### The headline: the families fold again, at a second XFEL - -[LCLS-MFX](../lcls-mfx/notes.md#model) found that an XFEL's device families fold and its gaps are architectural. Alvra re-runs that test against an independently-built free-electron laser, mined from PSI's `eco` rather than SLAC's `pcdshub`, and reaches the same finding. Of Alvra's full `eco` device set, **none** had no CORA Family: every device reuses an existing one. The offset and KB mirrors fold into `Mirror`, the solid attenuators into `Filter`, the slits into `Slit`, the pulse picker into `Shutter` (PULSE-1), the profile monitors into `Scintillator` + `Camera`, the PBPS / PBIG monitors into `FluxMonitor` + `Diagnostic`, the double-crystal mono into `Monochromator`, the Huber sample stage into `LinearStage`, the optical table into `Table`, the sample microscope and the Jungfrau into `Camera`, and the pump-probe and reference lasers into the catalog `Laser` Family (the LCLS-MFX / 4-ID precedent). The von Hamos spectrometer binds the graduated `EmissionSpectrometer` Family, a **fourth sighting** after LCLS-MFX (which introduced it), NSLS-II ISS (which graduated it), and the MAX IV Balder near-sighting (SPEC-1). Each fold was reviewed against coining a synonym and rejected. - -So the device taxonomy generalizes from storage rings to an XFEL almost untouched, and that result is now confirmed at two independent XFELs. What does not generalize is the **acquisition ontology**, the same as at LCLS-MFX. That is the product of this exercise, recorded next. - -### Deliberately not here yet (the architectural gap register) - -These are the parts of Alvra this scaffold leaves out on purpose. Unlike the open questions (facts the PSI team owns), each is a CORA scope decision: a shape the model does not yet have, with the seam it would extend named. None is built speculatively; an XFEL is the trigger that would justify the work, and Alvra is the second sighting of each gap, strengthening the case that the work is real and not LCLS-specific. - -- **Per-shot, pulse-ID-tagged event DAQ (DAQ-1).** The load-bearing gap, re-confirmed. CORA's acquisition is a single-detector poll-to-Done loop plus a sub-Hz scalar observation logbook with no pulse-ID key. SwissFEL's `sf-daq` collects a free-running `bsread` stream of per-shot frames correlated by pulse-ID at beam rate, exactly the shape LCLS's DAQ has. The Run-as-provenance-envelope survives and the per-shot data plane lives in the SwissFEL data API (CORA references a `Dataset`, as it does for reconstructions via `ComputePort`), but representing a DAQ run as an actuation is a new event-stream axis. Its shape is sketched as a forward-looking design note in CORA's design memory (gated, not built); Alvra is the second deployment to need it. -- **Beam-synchronous event-system timing (TIMING-1).** The SwissFEL event system (EVR receivers, e.g. `SLAAR11-LTIM01-EVR0`) gates acquisition at beam rate, the analog of LCLS's EventSequencer. CORA's `TimingController` Family carries the device, but "acquire on event-code N at rate R" has no typed parameter home; today it would be opaque setpoints. -- **Femtosecond pump-probe synchronization (LASER-1).** The optical pump-probe laser and the FEL are two synchronized timing domains; the `eco` `lxt` timing chain holds them together and the PALM / PSEN arrival-time monitors correct the residual jitter. CORA's `PartitionRule` is single-domain spatial math; a cross-timing-domain synchronization is a relationship it cannot express. The laser device itself folds (catalog `Laser`); the sync is the gap, and Alvra is the second XFEL to expose it (LCLS-MFX's TimeTool is the same role as Alvra's PSEN). -- **One switched Aramis source feeding co-equal stations (TOPO-1).** One linac and Aramis undulator line serve the Alvra, Bernina, and Cristallina stations, beam routed one at a time. CORA models each beamline as a root Unit owning its source; a shared, switched source feeding co-equal Units has no home except the `Supply("PhotonBeam")` seam, and the routing state has no model. This is the same gap LCLS-MFX's shared-linac topology exposed. -- **Attenuator transmission solver (ATT-1).** The `eco` `AttenuatorAramis` driver solves a foil combination for a requested transmission, energy-dependent. CORA's `Filter` covers the discrete selection; the solve is the deferred `Attenuable` + `SolverReference` leg. With both LCLS-MFX and Alvra carrying the same energy-dependent attenuator solve, the rule-of-three for this leg is well past its trigger. - -### What is deliberately not here yet (modelling, as at the other exercises) - -- **New Capabilities / Methods and vendor Models.** Alvra earns no catalog change; the XFEL recipes are carried pending on the [PSI Practices](../psi/index.md), reusing the pending LCLS-MFX Methods. No catalog Model is bound. -- **Sample delivery and the Subject custody thread.** The fixed-target / liquid-jet delivery on the Prime sample stage is endstation-specific and deferred (SAMPLE-1); no Family is coined, mirroring how LCLS-MFX carries its liquid jet. -- **The eco cross-line references (XREF-1).** Several Alvra `eco` drivers reference `SAROP21-*` PVs (a sibling Aramis line) for an aperture and an energy readback. Whether that is correct for Alvra or a copy-paste artifact is not determinable from source; carried as an open question, not silently modelled. -- **Integration scenarios.** No `test_alvra_*.py` registers Alvra Assets. Hard-registering a design-phase, off-roadmap, XFEL beamline would commit speculative structure. - -## Open questions - -*What CORA needs the PSI team (and PSI's documentation) to confirm before the model can be trusted.* - -Alvra is modelled from PSI's open [`eco`](https://github.com/paulscherrerinstitute/eco) controls library, treated as a dry, correct DATA source: the Alvra manifest is the `aliases` dict in `eco/alvra/config.py`, and the per-device driver classes derive the motor axes from each PV prefix. That gives the device shape and the EPICS PV prefixes at high confidence; it does not give the motor units or limits, the Aramis source parameters, the PSS safety structure, or the Capability / Method binding, none of which is in the manifest. This page collects what `eco` cannot supply. It is a delete-on-answer queue: when an item is answered, the answer lands in the descriptor and the row is removed. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -As at the LCLS-MFX and Diamond exercises, the EPICS PV prefix for every device is already recorded in the descriptor, so wiring handles is not a question here. The questions concentrate on the XFEL acquisition paradigm and on the few `eco`-specific ambiguities the source itself leaves open. - -### Scope, topology, and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SCOPE-1 | Nice-to-have | Is Alvra (or any SwissFEL station) actually intended to enter CORA scope, or is this a generalization exercise against an open controls source? | A generalization exercise: Alvra is CORA's second XFEL, testing whether the XFEL findings generalize across facilities; it is not on the pilot roadmap. | Whether PSI is a real Site or a modelling fixture. | -| TOPO-1 | Blocks-build | One linac and Aramis undulator line feed the Alvra, Bernina, and Cristallina stations, beam routed to one at a time. Should each station be its own root Unit sharing an upstream source, and where does the shared switched source live? | One `Alvra` root Unit owning its source for now; the shared, switched FEL source has no model and is carried as this question. The `Supply("PhotonBeam")` seam is the candidate home. | One-vs-many root Units and where the shared source and its routing state are modelled. | -| PSS-1 | Blocks-build | What are the SwissFEL PSS search-and-secure permit signals, and the interlock for the pump-probe laser? | Both enclosures exist with permit signals to be named; `eco` does not carry them. | The Enclosure permit signals and the laser-safety interlock. | -| ENC-1 | Blocks-build | Which enclosure does each device sit in? `eco` prefixes encode beamline-line zones (`SARFE10`, `SAROP11`, `SARES11` / `SLAAR11`), not the access-gated hutch or its safety meaning. | The shared Aramis optics hutch plus the Alvra experiment hutch. | The per-device Enclosure assignment. | - -### Source, optics, and attenuation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-build | What are the Aramis undulator line parameters and the per-shot photon-energy mechanism? The `eco` manifest carries the downstream device handles, not the source. | A SASE FEL undulator; per-shot photon energy is a DAQ datum, not a standing setpoint; energy-to-gap control is deferred. | The `Undulator` parameters and the per-shot energy mechanism. | -| MACHINE-1 | Nice-to-have | SwissFEL is a linac, not a storage ring, so the loose `StorageRing` family used by the synchrotron exercises does not fit. How should machine beam be modelled? | A `PhotonBeam` Supply, not a `StorageRing` device; the per-shot pulse energy is read via the `FluxMonitor` gas / intensity monitors. | The linac machine-state modelling boundary. | -| ATT-1 | Blocks-go-live | The `AttenuatorAramis` driver selects a foil combination for a requested transmission (energy-dependent). CORA's `Filter` covers the discrete selection but not the solve. Should the deferred `Attenuable` + `SolverReference` leg graduate? | `Filter` for the discrete selection; the target-transmission solver is the deferred `Attenuable` leg. With LCLS-MFX carrying the same solve, the rule-of-three is well past its trigger. | Whether the transmission solver is built and where. | -| MONO-1 | Nice-to-have | The double-crystal mono (ODCM105) is used for monochromatic / spectroscopy modes; Alvra also runs pink / SASE beam mono-out. What are the crystal and axis details, and the pink-vs-mono mode boundary? | A `Monochromator` Asset, used in some modes; mode and crystal details are settings to supply. | The DCM internals and the pink-vs-mono mode model. | -| XREF-1 | Blocks-go-live | Several Alvra `eco` drivers reference `SAROP21-*` PVs (a sibling Aramis line): the reference laser hardcodes an aperture on `SAROP21-OLIR134`, and the joint mono+FEL energy device reads `SAROP21-ODCM098:ENERGY`. Is this correct for Alvra, or a copy-paste artifact in the library? | The Alvra-line PVs (`SAROP11-*`) are authoritative; the `SAROP21-*` references are carried `confirm`, not silently modelled. | Whether the cross-line references are real Alvra dependencies. | - -### Acquisition and timing (the architectural core) - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DAQ-1 | Blocks-build | The SwissFEL `sf-daq` records a free-running `bsread` stream of per-shot frames tagged by pulse-ID at beam rate, correlated downstream. CORA's acquisition is a single-detector poll-to-Done loop plus a sub-Hz scalar observation logbook with no pulse-ID key. How does CORA represent a DAQ run? | The Run-as-provenance-envelope is kept; the per-shot data plane lives in the SwissFEL data API, and CORA references a `Dataset`, exactly as it does for reconstructions via `ComputePort`. A per-shot event-stream actuation axis is the gap, sketched in the design note, not built. This is the same gap LCLS-MFX exposed; Alvra is the second sighting. | Whether CORA gains an event-stream acquisition axis or remains a record-keeping shell for Alvra. | -| TIMING-1 | Blocks-go-live | The SwissFEL event system (EVR receivers, e.g. `SLAAR11-LTIM01-EVR0`) gates acquisition at beam rate. CORA's `TimingController` carries the device but has no typed home for an event trigger pattern. Where does the pattern parameter live? | `TimingController` for the device; the trigger pattern is carried as opaque setpoints until a typed parameter shape is earned. | The event-system trigger-pattern parameter model. | -| LASER-1 | Blocks-go-live | The fs pump-probe needs laser-to-X-ray synchronization (the `eco` `lxt` timing chain) and PALM / PSEN jitter correction. CORA's `PartitionRule` is single-domain spatial math, with no cross-timing-domain sync; and is the laser a driven Asset or a hazard? | The laser is carried as a catalog `Laser` Family device (the LCLS-MFX / 4-ID precedent, model-vs-hazard open); the delay stage is a `LinearStage`; the fs synchronization has no CORA model. | The pump-probe synchronization model and the laser's model-vs-hazard status. | - -### Diagnostics, sample, and detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DIAG-1 | Blocks-go-live | How are the intensity-position monitors (PBPS), the gas monitor (PBIG), and the PALM / PSEN arrival-time monitors modelled? They present the Sensor Role. | The loose `FluxMonitor` and `Diagnostic` Sensor families reused from I22 / 2-BM / LCLS-MFX; per-shot intensity normalization is a DAQ-plane concern (DAQ-1). | The diagnostics modelling boundary. | -| SAMPLE-1 | Blocks-go-live | What is the sample-delivery shape on the Prime endstation (fixed target, liquid jet), and the `Subject` custody lifecycle for serial crystallography? | Sample delivery is endstation-specific and deferred; no Family is coined yet; the `Subject` thread is carried as this question. | The sample-delivery model and the `Subject` custody thread. | -| SPEC-1 | Nice-to-have | The von Hamos spectrometer is a crystal-analyzer X-ray emission spectrometer composing analyzer crystals and a 2D detector. The Family question is resolved: `EmissionSpectrometer` is in the catalog (Alvra is a fourth sighting). The residual question is whether each analyzer crystal is a child Asset or a setting on the one spectrometer Asset. | The analyzer crystals carried as settings on the one `EmissionSpectrometer` Asset for now; child-Asset-per-crystal deferred. | The analyzer-crystal composition (child-Asset vs setting). | -| DET-1 | Blocks-go-live | What is the Alvra science detector? `eco` binds a Jungfrau named `JF_4.5M` (the von Hamos 4.5M, serial `JF02T09V03` inferred via `sf_daq_broker`), and the broker lists further Alvra options (16M, 4M, 2M TXS, 0.5M variants). Which is in use, and its threshold / geometry? | The detector reuses `Camera`; per-shot frames flow through the `sf-daq` data plane (DAQ-1); the model, the active variant, and the calibration are to supply. | The detector model and how its per-shot frames are referenced. | -| PULSE-1 | Nice-to-have | The X-ray pulse picker is a fast single-pulse selector folded into `Shutter`. Is a rotary pulse-picking chopper a distinct Family (the loose `Chopper` shape)? | `Shutter` Role; the Shutter-vs-Chopper distinction is carried as this question, the same one LCLS-MFX raised. | Whether the pulse picker earns its own Family. | diff --git a/docs/deployments/amx/notes.md b/docs/deployments/amx/notes.md deleted file mode 100644 index d2182f72ec9..00000000000 --- a/docs/deployments/amx/notes.md +++ /dev/null @@ -1,112 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at AMX: macromolecular crystallography, each a [Catalog](../../catalog/methods.md) Method. AMX is CORA's third MX beamline (after Diamond i03 and NSLS-II FMX) and follows the same Method-deferral discipline.* - -AMX's science is high-throughput protein crystallography: rotate a cryo-cooled crystal in a focused microbeam and read the diffraction on the Eiger, locate crystals with fast grid scans, and exchange samples with an automated robot. These are the MX Methods i03 and FMX brought to CORA; AMX is their third consumer. The Methods below render unlinked and stay pending until a conduct-path coins them (TECH-1). - -| Technique | Beam | Detector | Status in CORA | -| --- | --- | --- | --- | -| Rotation (oscillation) data collection | monochromatic, microfocused | `AreaDetector` (Eiger, Detector Role) | the `mx_data_collection` Method, pending; 3rd consumer (TECH-1) | -| Grid scan / sample location | monochromatic, microfocused | `AreaDetector` + `SampleCamera` | the `grid_scan` Method over the Zebra-triggered goniometer raster, pending; 3rd consumer (TECH-1) | -| Autonomous sample exchange | n/a | n/a | the `sample_exchange` Method: a Procedure over the spine + a Subject custody thread, pending; 3rd consumer (ROBOT-1) | -| Anomalous element ID (fluorescence) | monochromatic, energy-swept | `FluorescenceDetector` (Mercury, Sensor) | the edge scan picks the energy for SAD / MAD; reuses the energy axis (DET-1) | - -### Why the Methods stay pending - -AMX reuses the three MX Methods i03 and FMX left pending, and is the third consumer of each. This is the moment the consumer count is strongest, so it is worth being precise about why they still do not graduate: unlike a device *Family* (which a second sighting promotes on a mechanical rule-of-three, as ISS did for the emission spectrometer), a *Method* is coined on a **conduct-path**, when a deployment actually runs it (an integration scenario or operational pilot, the way `tomography` and `xpcs` were coined). i03, FMX, and AMX are all descriptor-only scaffolds with no conduct-path, so three consumers strengthen the case but do not coin the Methods, exactly the discipline that keeps `energy_scan` deferred across its consumers. The device Roles already exist (the graduated `Goniometer` presents Positioner, the Eiger presents Detector); what is pending is the recipe. - -The genuine MX graduation, coining these Methods, is a follow-on that needs an MX conduct-path scenario (the event-sourced spine work), not another descriptor scaffold. The autonomous sample-exchange loop is the non-obvious modelling: an unattended Procedure over the spine, threaded through the `Subject` custody lifecycle and gated by a Clearance (ROBOT-1). - -## Governance - -*Who may act at AMX and the trust shape CORA applies. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority.* - -People and agents are facility principals at the [NSLS-II Site](../nsls2/index.md#safety-and-governance); on the beamline they surface through the actions they take. The human roster is not known from the profile collection (GOV-1), so the principals are the design shape, not a registered list. - -### Who acts - -CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the NSLS-II Site. An AMX beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. - -### The trust boundary - -CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may set the energy, move the goniometer, start a rotation data collection or a grid scan, drive the robot, override a caution, or commit a beam-centre calibration. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer (the LSDC Governor). The NSLS-II proposal and cycle are a fact CORA's Campaign uses for custody. - -### The autonomous loop under custody - -AMX is "highly automated": its defining governance wrinkle is the unattended EMBL-robot sample-exchange loop. CORA's Campaign, Trust, and Subject shapes are where that resolves: the robot loading a crystal is a command the trust boundary gates, and the crystal is a `Subject` whose custody (Received to mounted-on-goniometer to measured to Returned / Stored) is the record of record. The autonomous loop is gated by a `Clearance` issued after a safety review, the same pattern as i03 and FMX. An autonomous Agent driving the load-centre-collect-unmount cycle would be a facility principal scoped at the Site, governed by the same trust boundary, with each choice recorded as a [Decision](../../architecture/modules/decision/index.md). None is declared yet; the autonomous-loop lifecycle is deferred (ROBOT-1). - -## Model - -*The developer's by-kind index: where each CORA aggregate's AMX content lives. It hosts no content of its own. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC -[modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at AMX | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (EnergyAxis) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) (17-ID-A optics, 17-ID-B experiment) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Subject (the crystal custody thread) | [Governance](#the-autonomous-loop-under-custody) (deferred, ROBOT-1) | -| Procedure, Recipe, Caution, Supply, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What this deployment graduates: nothing (and that is the finding) - -AMX is a clean **pure-reuse** deployment, completing the NSLS-II MX pair as FMX's sibling. Its finding is that the MX vocabulary generalizes across a third independent beamline with no new modelling: the graduated `Goniometer` (single-omega micro-goniometer), the `Camera` (Eiger), the `Monochromator` (here vertical), the `Mirror` (tandem-deflection + KB), the `Filter` (BCU attenuator), the `BeamStop`, the `EnergyDispersiveSpectrometer` (Mercury), the `FluxMonitor` (Keithley), the `TimingController` (Zebra), and the graduated catalog `PositionMonitor` (presenting `Sensor`, distinct from `FluxMonitor` by measuring beam position rather than flux) all bind unchanged. The robot is one Positioner-presenting Asset, not a new Family (the i03 / 19-BM / FMX precedent). - -#### FMX-vs-AMX differences - -The 17-ID pair is not identical, and the differences exercise the modelling: AMX uses a **vertical** DCM (FMX horizontal), **tandem-deflection** mirrors (FMX a horizontal focusing mirror), an **EMBL** robot, and has **no CRL transfocator** and **no on-axis backlight** in source. Each is a per-Asset settings or device-presence difference, not a Family split; both beamlines bind the same Families. - -### Deliberately not here yet - -This is a design-phase scaffold (descriptor + docs), mirroring FMX and the other NSLS-II beamlines. Left out on purpose: - -- **No catalog change.** AMX graduates nothing and coins nothing. The three MX Methods (`mx_data_collection`, `grid_scan`, `sample_exchange`) stay pending: AMX is their third consumer, which strengthens but does not coin them. Methods coin on a **conduct-path** (a deployment that runs them), not on a sighting count, which is why even at n=3 they defer (the `energy_scan` discipline; TECH-1). Coining them is a follow-on that needs an **MX conduct-path scenario** (event-sourced spine work), the genuine MX-graduation path. -- **The robot is not a Family.** The EMBL sample-changing robot is one Positioner-presenting Asset, gated by a Clearance, loading a `Subject`, vendor in a bound Model; not a new SampleChanger Family (the i03 / 19-BM precedent, ROBOT-1). -- **The autonomous loop and the Subject custody thread.** The unattended exchange loop is a Procedure over the spine threaded through the `Subject` aggregate; deferred with i03 / FMX (ROBOT-1). -- **Sample cryo-cooling.** The cold-gas cryostream is not exposed in the profile collection, so it is deferred (CRYO-1); it would bind `TemperatureController` (the i03 cryostream precedent) when its PV is supplied. -- **The area detector PV.** The Eiger is not exposed in the AMX profile collection; it is carried `Camera` confirm-only (DET-1). -- **Operations and experiment views, integration scenarios, vendor Models.** A runbook and registered Assets for a beamline CORA does not yet drive would be invention; they land when the design firms and the team confirms. - -## Open questions - -*What CORA needs the AMX team to confirm. This model is reverse-engineered from public open source (the `NSLS2/amx-profile-collection` bluesky / ophyd startup files; the MX acquisition logic lives in the `lsdc` / `mxtools` libraries): the EPICS PVs are read from the `startup/*.py` device classes, but the goniometer / robot / detector vendor identities, the crystal cut, and physical positions are not. Each row is a fact the beamline team owns. It is a delete-on-answer queue.* - -Priorities: `Blocks-build`, `Blocks-go-live`, `Nice-to-have`. - -### Source and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Nice-to-have | The IVU21 undulator period, gap range, and gap-to-energy curve. The device (`SR:C17-ID:G1{IVU21:1}`) is in source; the parameters are not. | An in-vacuum undulator on the 3 GeV ring, identity-only. | The InsertionDevice settings. | -| TOPO-1 | Nice-to-have | AMX (17-ID-1) shares the IVU21 undulator and the 17-ID straight with FMX (17-ID-2, which uses IVU21:2). Is the straight canted (two beams), and is one root Unit per branch the right model? | One root Unit feeding the 17-ID-1 branch (the FMX / CSX canted precedent); FMX is the sibling branch. | The sector topology and the FMX relationship. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit-leaf PVs and the front-end / photon shutter PVs (not in the profile collection; the front end is shared with FMX). | The permit signal is a confirm note, not a guessed PV. | The Enclosure permit signals. | - -### Optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DCM-1 | Nice-to-have | The vertical DCM crystal cut, d-spacing, and energy range. The monochromator (`Mono:DCM`) and its axes are in source. | One Monochromator Asset, crystal settings blank. | The Monochromator settings. | -| KB-1 | Nice-to-have | The tandem-deflection and KB mirror coatings and calibration. The mirrors (`Mir:TDM`, `Mir:KBH/KBV`) are in source. | The mirror internals are per-Asset settings on the existing Mirror Family. | The focusing-optic settings. | - -### Sample and detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| GONIO-1 | Blocks-go-live | The goniometer axis decomposition (single omega + GX / GY / GZ centring + PY / PZ pin fine) and the centre-of-rotation calibration. The stack (`Gon:1`) is in source. | A `Goniometer` Asset (catalog Family, graduated on the i03 Smargon); per-axis decomposition to confirm. | The goniometer model. | -| ROBOT-1 | Blocks-go-live | The EMBL sample-changing robot model, the dewar / puck layout, the exchange workflow, and the Subject custody lifecycle. The robot (`EMBL`) and Governor are in source. | One Positioner-presenting `Robot` Asset (not a new Family); the autonomous loop is a Procedure + a Subject custody thread, gated by a Clearance. | The robot model and the autonomous-loop modelling. | -| DET-1 | Blocks-go-live | The Eiger model and beam centre (not exposed in the profile collection), and the Mercury fluorescence detector element count and ROI map. | An Eiger (`Camera`, PV pending) and a Mercury (`EnergyDispersiveSpectrometer`); model / ROIs to confirm. | The detector roster. | -| DIAG-1 | Nice-to-have | The beam-position channel map (the four-quadrant BPMs); the `PositionMonitor` Family is graduated (catalog, presenting `Sensor`), only the per-Asset channel map stays pending. | Read-only beam-position (graduated catalog `PositionMonitor`) probes; channel map blank. | The BeamPositionMonitor bindings. | -| CRYO-1 | Nice-to-have | The sample cryo-cooling (cold-gas cryostream), not exposed in the profile collection. | Sample cooling deferred; a `TemperatureController` when its PV is supplied. | The sample-environment Assets. | - -### Controls and technique scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DRIVE-1 | Blocks-go-live | The motion-controller box models, firmware, and IPs (the goniometer vector controller is a PowerBrick; the profile's vector PV is misconfigured to the FMX prefix). | Family bound (MotionController), specifics blank. | The MotionController Models. | -| TECH-1 | Blocks-go-live | Do the MX Methods (rotation `mx_data_collection`, `grid_scan`, `sample_exchange`) enter CORA's catalog, or stay pending? AMX is the third consumer (after i03, FMX). | The three Methods reused pending; coining awaits a conduct-path (an MX integration scenario), not the sighting count (the energy_scan discipline). | The MX Method scope. | diff --git a/docs/deployments/bernina/notes.md b/docs/deployments/bernina/notes.md deleted file mode 100644 index 254828d650f..00000000000 --- a/docs/deployments/bernina/notes.md +++ /dev/null @@ -1,148 +0,0 @@ -# Notes - -## Techniques - -*What Bernina is designed to do, as design intent. Design-phase: these are Methods CORA would earn, not Methods it has.* - -Bernina runs two technique families, neither of which fits the catalog's tomography Methods, so each is carried pending on the [PSI Practices](../psi/index.md) until it is earned. They are listed here as design intent, with the shape each would take over the spine and the gap each leans on. - -### Femtosecond optical pump-probe - -The shared SwissFEL technique, the same one [Alvra](../alvra/notes.md#techniques) and [LCLS-MFX](../lcls-mfx/notes.md#techniques) run. An optical laser pulse excites the sample a controlled femtoseconds before (or after) the X-ray probe pulse; scanning the delay resolves the dynamics in time. The PSEN spectral-encoding arrival-time monitor corrects the residual laser-to-X-ray jitter shot by shot. - -- **Spine shape:** a `pump_probe` Method that scans the laser-to-X-ray delay (a `LinearStage` delay axis on the experiment laser) while acquiring per-shot, with the PSEN monitor correcting jitter. -- **Gap it leans on:** the cross-timing-domain synchronization (LASER-1). The delay axis itself is a positioner; what CORA cannot express is the femtosecond synchronization between the optical-laser and FEL timing domains (the `eco` `lxt` timing chain). Bernina is the third deployment to reach this gap (after LCLS-MFX and Alvra). - -### Time-resolved hard X-ray diffraction and scattering - -Bernina's reason for existing, and what distinguishes it from Alvra. After the pump, the sample's structural response is read by diffraction: Bragg peaks and diffuse scattering recorded shot by shot on the area detector, as a function of pump-probe delay. The sample is oriented and the detector positioned by the GPS six-circle or XRD You-geometry diffractometer. - -- **Spine shape:** a `diffraction` Method binding the diffractometer (a `Goniometer` for the sample circles, a `RotaryStage` 2-theta detector arm, and a reciprocal-space `PseudoAxis`), composed through the graduated `Diffractometer` Assembly (DIFF-1), over a per-shot acquisition. The reciprocal-space layer resolves the hkl inverse kinematics, and for the XRD platform the kappa-to-Eulerian conversion (DIFF-2). -- **Gap it leans on:** the per-shot, pulse-ID-tagged event DAQ (DAQ-1). A time-resolved diffraction run is a free-running shot stream tagged by pulse-ID and delay, not a trajectory of points the spine walks. The diffractometer itself is fully covered by the existing Assembly; the acquisition is the gap. - -### Why neither is in the catalog yet - -The catalog's Methods are all tomography-family (`tomography`, `dark_field`, `flat_field`, the alignment and energy-change methods). An XFEL diffraction station shares none of them: there is no rotation tomography, no flat / dark frame pairing, no storage-ring energy ramp. The `diffraction` Method is genuinely new for the fleet (the synchrotron diffractometers at 4-ID and 8-ID carry their own pending Methods), and coining it now, before the per-shot acquisition axis it depends on exists (DAQ-1), would be inventing a recipe for a spine that cannot yet run it. So it is carried pending. That a diffraction technique reaches the **same** acquisition gaps a spectroscopy technique (Alvra) and a crystallography technique (LCLS-MFX) reached is the reinforcement Bernina adds: the gaps are about the XFEL acquisition paradigm, not about any one technique. See [Model](#model) for the gap register and the `Diffractometer` Assembly design. - -## Governance - -*Who would act at Bernina and the trust shape that gates their commands. Design-phase: the principals are facility-level and carried pending.* - -Bernina's principals are facility principals at the [PSI Site](../psi/index.md), not beamline-local: the SwissFEL instrument-scientist and operator pool, and the PSI safety-review body. Both are carried pending in the [site descriptor](../psi/index.md) until the PSI structure is confirmed; the `eco` device library is a controls library, not an organizational record, so it exposes no human roster (GOV-1). CORA's role kernel (the five-role authorization model) is facility-invariant, so Bernina inherits it. Bernina shares its Site, its Aramis source, and its safety posture with the sibling [Alvra](../alvra/notes.md#governance) station, so most of the governance shape is the PSI-Site shape already described there; what is worth drawing out is the shared-source boundary and the laser Clearance. - -### The shared Aramis source and the optics zone - -Bernina is one of three co-equal stations (with Alvra and Cristallina) on one Aramis source, beam routed to one at a time (TOPO-1). The `SAROP21` optics hutch conditions the beam on the way to Bernina, but the source upstream of it is shared. That makes the optics-hutch Zone a shared-access boundary, the same question Alvra's optics hutch and LCLS-MFX's front-end / transport zone raise: who holds the permit when the beam is routed to a neighbour, and how the routing state gates each station's commands. The SwissFEL PSS search-and-secure permit signals are not in the `eco` manifest and are carried pending (PSS-1). Bernina's enclosure structure (the shared `SAROP21` optics hutch plus the Bernina experiment hutch) is carried `confirm` because the `eco` PV prefixes encode beamline-line zones, not access-gated hutches (ENC-1). - -### The pump-probe laser Clearance - -Bernina runs a class-4 optical laser for pump-probe. CORA carries this as a `Clearance` hazard on the experiment (a facility-issued safety permit that must be Active before laser-on work), the same posture Alvra, LCLS-MFX, and 32-ID take. This is distinct from whether the laser is a driven Asset: the device folds into the catalog `Laser` Family, while the personnel-safety permit is a Clearance. The two coexist (LASER-1). - -### What is not modelled - -- **Trust instantiation.** No scenario instantiates Bernina trust zones or actors; this is a design-phase modelling exercise, so the governance shape is described, not seeded. It would land, following the [2-BM governance](../2-bm/governance.md) shape, if and when the deployment approaches real scope. -- **The Staeubli sample / detector robot as a principal or driven Asset.** The robot runs over PShell (HTTP), not EPICS, and its modelling is deferred (ROBOT-1); when it is modelled, whether an autonomous sample-handling Agent acts through it is part of that work. -- **The DAQ and acquisition software as principals.** The SwissFEL `sf-daq`, `bsread`, and the `eco` / `slic` scan suite are control-system software on the floor, not CORA actors (see [Controls](controls.md)). When the per-shot acquisition axis is designed (DAQ-1), the question of which principal authorizes a DAQ run is part of that work. - -People and agents are facility principals at the [PSI Site](../psi/index.md); see [Open questions](#open-questions) for the governance items still to confirm. - -## Model - -*The developer's by-kind index: where each CORA aggregate's Bernina content lives, how the diffraction platform composes as an Assembly rather than a Family, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at Bernina | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (the reciprocal-space `PseudoAxis`) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### The headline: the diffraction platform is an Assembly, not a Family - -Bernina's defining endstation is two reconfigurable diffraction platforms: GPS (`SARES22-GPS`, a six-circle station) and XRD (`SARES21-XRD`, a You-geometry station). The `eco` driver `bernina_diffractometers.py` builds, from literal PV suffixes, a base (gamma / mu plus translations and tilts), a 2-theta detector arm (delta / detector translation), a polarization-analyzer branch (pol / pthe / ptth), a kappa goniometer (with on-the-fly kappa-to-Eulerian eta / chi / phi conversion), a heavy-load goniometer table, and a PI hexapod, with an optional Staeubli robot contributing gamma / delta. - -That is far more than the catalog `Goniometer`, the integrated single-device sample orienter that [I03](../i03/notes.md#model) graduated and [MX3](../mx3/notes.md#model) reused. But it is **exactly the graduated `Diffractometer` Assembly** that 4-ID and 8-ID earned: a composed scattering instrument that - -- binds **one `Goniometer`** for the sample-orientation circles plus x / y / z centring, -- binds **zero or more `RotaryStage`** detector-arm circles (here the `delta` 2-theta arm), and -- binds **one reciprocal-space `PseudoAxis`** whose partition rule resolves the inverse kinematics (here the `SixCircleBernina` and kappa-to-You conversions). - -So Bernina coins **no new Family and adds no new Assembly**. Each platform is modelled as a `Goniometer` Asset + a `PseudoAxis` Asset (and, for XRD, a `RotaryStage` detector-arm Asset), composed through the existing `Diffractometer` Assembly. The GPS and XRD platforms are its third and fourth bindings, reinforcing the 4-ID / 8-ID graduation from a third facility and, for the first time, at an XFEL (DIFF-1). The reciprocal-space partition rule (the hkl inverse kinematics, and the kappa-to-Eulerian conversion XRD adds) is the same `PartitionRule` design the synchrotron diffractometers carry, deferred here as DIFF-2. - -### Deliberately not here yet: the externalized configuration (CONFIG-1) - -This is the boundary that makes Bernina a partial first cut, and it is a different boundary from i13-1's. At i13-1 the upstream source was simply absent from the public module. At Bernina the device **list** and the diffractometer **axis topology** are public (in `bernina.py` and `bernina_diffractometers.py`), but the **configuration state** is loaded at runtime from non-public PSI files: - -- `eco/bernina/config.py`'s entire `components` device list is commented out and `extend`-ed from `/sf/bernina/config/eco/bernina_config_eco.json` (not in the repo). -- `bernina.py` reads `/sf/bernina/config/eco/configuration/bernina_config.json` for the per-diffractometer flags that decide **which sub-assemblies are mounted** (base / arm / polana / kappa / heavy-load / hexapod / robot) and **which detectors attach to each diffractometer**. - -So CORA can model the platforms' shape but not their current instantiation: the inventory carries the recoverable devices, and the mount state and detector wiring are carried unknown, not guessed (CONFIG-1). This is the honest scope line, and it is recorded so a later cut (or a staff confirmation) can fill it without re-deriving the topology. - -### The architectural gap register (shared with the other XFELs) - -These are the same deferrals Alvra and LCLS-MFX recorded; Bernina re-confirms them on a diffraction platform rather than a spectroscopy one, which is itself the point (the gaps are about acquisition, not technique). - -- **One switched Aramis source feeding co-equal stations (TOPO-1).** Now concrete: Bernina is the second root Unit on the same source as Alvra. Two co-equal Units sharing one upstream source has no home except the `Supply("PhotonBeam")` seam, and the routing state has no model. -- **Per-shot, pulse-ID-tagged event DAQ (DAQ-1).** The `sf-daq` records a free-running `bsread` stream of per-shot frames correlated by pulse-ID; CORA's poll-to-Done acquisition has no representation for it. The Run stays the provenance envelope and the per-shot plane is a referenced `Dataset`. -- **Beam-synchronous event-system timing (TIMING-1).** The SwissFEL master timing, CTA sequencer, and EVR receivers gate acquisition at beam rate; `TimingController` carries the device but the trigger pattern has no typed home. -- **Femtosecond pump-probe synchronization (LASER-1).** The `eco` `lxt` timing chain and the PSEN arrival-time monitor hold and correct the laser-to-X-ray delay; CORA's single-domain `PartitionRule` cannot express the cross-timing-domain sync. The laser folds (catalog `Laser`); the sync is the gap. - -### What is deliberately not here yet (modelling, as at the other exercises) - -- **New Capabilities / Methods and vendor Models.** Bernina earns no catalog change; the pump-probe and diffraction recipes are carried pending on the [PSI Practices](../psi/index.md). No catalog Model is bound. -- **The Staeubli TX200 robot (ROBOT-1).** The sample / detector handling robot runs over PShell (HTTP), not EPICS, and its modelling is deferred, the same posture I03 and MX3 take for their sample-exchange arms. -- **The RIXS / tape-drive / liquid-jet sample environments (ENV-1).** `eco` defines these but their appends are commented out, so they are not in the live module; deferred, not invented. -- **The eco cross-line reference (XREF-1).** A live Bernina profile monitor (`prof_mirr_alv1`) carries an Alvra-line PV (`SAROP11-PPRM066`); whether that is a real shared device or a copy-paste residue is carried as an open question. -- **Integration scenarios.** No `test_bernina_*.py` registers Bernina Assets. Hard-registering a design-phase, off-roadmap, XFEL beamline would commit speculative structure. - -## Open questions - -*What CORA needs the PSI team (and PSI's documentation) to confirm before the model can be trusted.* - -Bernina is modelled from PSI's open [`eco`](https://github.com/paulscherrerinstitute/eco) controls library, treated as a dry, correct DATA source: the device list with PV prefixes comes from the live `eco/bernina/bernina.py`, and the diffractometer motor-axis topology from `eco/endstations/bernina_diffractometers.py`. That gives the device shape and the EPICS PV prefixes at high confidence. It does not give the configuration state, the motor units or limits, the Aramis source parameters, the PSS safety structure, or the Capability / Method binding. This page collects what `eco` cannot supply. It is a delete-on-answer queue: when an item is answered, the answer lands in the descriptor and the row is removed. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -The defining Bernina question is **CONFIG-1**: unlike Alvra, Bernina's live device list and per-diffractometer configuration are loaded from non-public PSI files, so this is a deliberately partial first cut. - -### Scope, configuration, topology, and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SCOPE-1 | Nice-to-have | Is Bernina (or any SwissFEL station) actually intended to enter CORA scope, or is this a generalization exercise against an open controls source? | A generalization exercise: Bernina extends the PSI / XFEL exercise to a second station on the shared source and to a diffraction platform; it is not on the pilot roadmap. | Whether PSI is a real Site or a modelling fixture. | -| CONFIG-1 | Blocks-build | `eco` loads Bernina's authoritative device list from `/sf/bernina/config/eco/bernina_config_eco.json` and the per-diffractometer configuration (which of base / arm / polana / kappa / heavy-load / hexapod / robot sub-assemblies are mounted, and which detector attaches to each) from `/sf/bernina/config/eco/configuration/bernina_config.json`, neither in the public repo. What is the current configuration? | The device list and diffractometer axis topology are taken from the public inline source; the mount state and detector wiring are carried unknown, not invented. | The full device list and the per-diffractometer mount + detector state. | -| TOPO-1 | Blocks-build | One linac and Aramis undulator line feed the Alvra, Bernina, and Cristallina stations, beam routed to one at a time. Should each station be its own root Unit sharing an upstream source, and where does the shared switched source live? Bernina is the second such station, so this is now concrete, not hypothetical. | One `Bernina` root Unit owning its source for now; the shared, switched FEL source has no model and is carried as this question. The `Supply("PhotonBeam")` seam is the candidate home. | One-vs-many root Units and where the shared source and its routing state are modelled. | -| PSS-1 | Blocks-build | What are the SwissFEL PSS search-and-secure permit signals, and the interlock for the pump-probe laser? | Both enclosures exist with permit signals to be named; `eco` does not carry them. | The Enclosure permit signals and the laser-safety interlock. | -| ENC-1 | Blocks-build | Which enclosure does each device sit in? `eco` prefixes encode beamline-line zones (`SARFE10`, `SAROP21`, `SARES2x` / `SLAAR21`), not the access-gated hutch or its safety meaning. | The shared `SAROP21` optics hutch plus the Bernina experiment hutch. | The per-device Enclosure assignment. | - -### Source, optics, and attenuation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-build | What are the Aramis undulator line parameters and the per-shot photon-energy mechanism? The `eco` manifest carries the downstream device handles, not the source. | A SASE FEL undulator; per-shot photon energy is a DAQ datum, not a standing setpoint; energy-to-gap control is deferred. | The `Undulator` parameters and the per-shot energy mechanism. | -| MACHINE-1 | Nice-to-have | SwissFEL is a linac, not a storage ring, so the loose `StorageRing` family does not fit. How should machine beam be modelled? | A `PhotonBeam` Supply, not a `StorageRing` device; the per-shot pulse energy is read via the `FluxMonitor` gas / intensity monitors. | The linac machine-state modelling boundary. | -| ATT-1 | Blocks-go-live | The `AttenuatorAramis` driver selects a foil combination for a requested transmission (energy-dependent). CORA's `Filter` covers the discrete selection but not the solve. Should the deferred `Attenuable` + `SolverReference` leg graduate? | `Filter` for the discrete selection; the target-transmission solver is the deferred `Attenuable` leg. With LCLS-MFX and Alvra carrying the same solve, the rule-of-three is well past its trigger. | Whether the transmission solver is built and where. | -| MONO-1 | Nice-to-have | The double-crystal mono (ODCM098) is used for monochromatic modes; Bernina also runs pink / SASE beam mono-out. What are the crystal and axis details, and the pink-vs-mono mode boundary? | A `Monochromator` Asset, used in some modes; mode and crystal details are settings to supply. | The DCM internals and the pink-vs-mono mode model. | -| XREF-1 | Blocks-go-live | A live Bernina profile monitor (`prof_mirr_alv1`) carries an Alvra-line PV (`SAROP11-PPRM066`). Is this a real shared device, or a copy-paste residue in the library? | The Bernina-line PVs (`SAROP21-*`) are authoritative; the `SAROP11-*` reference is carried `confirm`, not silently modelled. | Whether the cross-line reference is a real Bernina dependency. | - -### Endstation: the diffractometers - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DIFF-1 | Blocks-go-live | The GPS six-circle and XRD You-geometry platforms compose a goniometer, a 2-theta detector arm, a polarization-analyzer branch, a kappa goniometer, a heavy-load table, and a PI hexapod. Are they correctly modelled as the graduated `Diffractometer` Assembly (Goniometer + RotaryStage detector arm + reciprocal-space PseudoAxis), and which sub-assemblies does each carry? | Both reuse the `Diffractometer` Assembly (4-ID / 8-ID), no new Family; the mounted sub-assemblies are read from the external config (CONFIG-1). | The Assembly composition and the per-platform slot bindings. | -| DIFF-2 | Nice-to-have | The reciprocal-space layer resolves hkl inverse kinematics (`SixCircleBernina`), and the XRD platform adds a kappa-to-Eulerian conversion. What is the `PartitionRule` shape for the `PseudoAxis`? | The reciprocal-space `PseudoAxis` carries a partition rule like the synchrotron diffractometers'; the kappa-to-You conversion is part of it. | The reciprocal-space partition rule. | -| ROBOT-1 | Nice-to-have | The Staeubli TX200 robot handles samples / the detector over PShell (HTTP), not EPICS. How is it modelled? | Deferred; the robot is not modelled in this cut, the same posture I03 and MX3 take for their sample-exchange arms. | The robot's modelling and its `Subject` custody thread. | -| ENV-1 | Nice-to-have | `eco` defines RIXS, tape-drive, and liquid-jet sample environments but their appends are commented out. Are they current Bernina endstation options? | Deferred; not in the live module, so not modelled, not invented. | The sample-environment variants. | - -### Acquisition, timing, diagnostics, and detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DAQ-1 | Blocks-build | The SwissFEL `sf-daq` records a free-running `bsread` stream of per-shot frames tagged by pulse-ID at beam rate, correlated downstream. CORA's acquisition is a single-detector poll-to-Done loop with no pulse-ID key. How does CORA represent a DAQ run? | The Run-as-provenance-envelope is kept; the per-shot data plane lives in the SwissFEL data API, and CORA references a `Dataset`. A per-shot event-stream actuation axis is the gap, sketched in the design note, not built. Bernina is the third sighting (after LCLS-MFX and Alvra). | Whether CORA gains an event-stream acquisition axis. | -| TIMING-1 | Blocks-go-live | The SwissFEL event system (master timing, CTA sequencer, EVR receivers) gates acquisition at beam rate. CORA's `TimingController` carries the device but has no typed home for an event trigger pattern. Where does the pattern parameter live? | `TimingController` for the device; the trigger pattern is carried as opaque setpoints until a typed parameter shape is earned. | The event-system trigger-pattern parameter model. | -| LASER-1 | Blocks-go-live | The fs pump-probe needs laser-to-X-ray synchronization (the `eco` `lxt` timing chain) and PSEN jitter correction. CORA's `PartitionRule` is single-domain spatial math, with no cross-timing-domain sync; and is the laser a driven Asset or a hazard? | The laser is carried as a catalog `Laser` Family device (model-vs-hazard open); the delay stage is a `LinearStage`; the fs synchronization has no CORA model. | The pump-probe synchronization model and the laser's model-vs-hazard status. | -| DIAG-1 | Blocks-go-live | How are the intensity-position monitors (PBPS), the gas monitor, and the PSEN arrival-time monitor modelled? They present the Sensor Role. | The loose `FluxMonitor` and `Diagnostic` Sensor families reused from Alvra / I22 / 2-BM; per-shot intensity normalization is a DAQ-plane concern (DAQ-1). | The diagnostics modelling boundary. | -| DET-1 | Blocks-go-live | What is the Bernina science detector? `eco` wires a 1.5M Jungfrau (`JF01T03V01`) inline; `sf_daq_broker` lists a 16M (`JF07T32V02`) plus I0 / vacuum / fluorescence / RIXS 0.5M variants, and the `eco` / broker version strings differ (V01 vs V02). Which is in use per diffractometer? | The detector reuses `Camera`; per-shot frames flow through the `sf-daq` data plane (DAQ-1); the active variant and wiring are external (CONFIG-1) and to supply. | The detector model, the per-diffractometer wiring, and the version mismatch. | -| PULSE-1 | Nice-to-have | The X-ray pulse picker is a fast single-pulse selector folded into `Shutter`. Is a rotary pulse-picking chopper a distinct Family (the loose `Chopper` shape)? | `Shutter` Role; the Shutter-vs-Chopper distinction is carried as this question, the same one Alvra and LCLS-MFX raised. | Whether the pulse picker earns its own Family. | diff --git a/docs/deployments/bmm/notes.md b/docs/deployments/bmm/notes.md deleted file mode 100644 index e74ab0ab98f..00000000000 --- a/docs/deployments/bmm/notes.md +++ /dev/null @@ -1,100 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at BMM: X-ray absorption spectroscopy, bound through an NSLS-II [Practice](../nsls2/index.md#the-techniques-adapted-here). BMM raises the spectroscopy Capability question CORA has not yet had to answer.* - -BMM does transmission and fluorescence XAS / EXAFS: sweep the beam energy across an element's absorption edge, record the per-energy detector readings, and fit the absorption spectrum downstream. - -| BMM technique | CORA expression | Earn-the-abstraction call | -| --- | --- | --- | -| Transmission XAS / EXAFS | an energy sweep reading I0/It/Ir | the live question (ENERGY-1): coin `energy_scan`, or hold under `characterization`? | -| Fluorescence XAS | the same sweep reading the `EnergyDispersiveSpectrometer` | same Capability, different detector in the slot | -| Energy calibration | reference foil + `Ir` channel each scan | a Calibration, not a separate technique | -| Alignment | beam-finding and slit/mirror tuning | reuse [`alignment`](../../catalog/methods.md) | - -### The energy_scan Capability question (ENERGY-1) - -BMM is the first CORA deployment whose measurement *is* an energy scan. The catalog already anticipates this: alongside `cora.capability.energy_change` (a coordinated *setpoint* move to one energy), a note records `cora.capability.energy_scan` as **pending in code**, and describes energy_change as "distinct from a future energy_scan sweep." BMM is that future consumer. - -Per the design-phase discipline (Diamond i03/i22, 32-ID, and HXN all coined no new Capability at scaffold time), this scaffold **defers** coining `energy_scan`: an XAS scan is mapped to `characterization` plus `energy_change` for now, and the Capability is coined when a conduct-path actually sweeps the energy. The argument to coin is strong (the sweep is the measurement, exactly the in-kind case), and the catalog already reserved the name; it is held open deliberately, not because it is weak, but because a Capability is coined when a conduct-path forces it, not at scaffold time. - -EXAFS data reduction (background subtraction, normalization, the chi(k) transform) is a `ComputePort` leg, not a beamline Method, the same way tomographic and ptychographic reconstruction are. - -## Governance - -*Who may act at BMM and the trust shape CORA applies. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority.* - -People and agents are facility principals at the [NSLS-II Site](../nsls2/index.md#safety-and-governance); on the beamline they surface through the actions they take. The human roster is not known from the profile collection (GOV-1), so the principals are the design shape, not a registered list. - -### Who acts - -CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the NSLS-II Site. A BMM beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. - -### The trust boundary - -CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may start a scan, override a caution, or commit a calibration. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer. The NSLS-II proposal and cycle are a fact CORA's Campaign uses for custody. - -### Batch automation and agents - -BMM's batch XAS, a wheel of many samples scanned unattended, is a natural place for an autonomous Agent: choosing the next sample, deciding when a spectrum has enough signal-to-noise, flagging a bad scan. If such an agent were added, it would be a facility principal scoped at the Site, governed by the same trust boundary, and each decision (which sample, rescan-or-advance) would be a [Decision](../../architecture/modules/decision/index.md) recorded in the run provenance. None is declared for BMM yet; the unattended wheel loop is conducted, not agent-driven, in this scaffold. - -## Model - -*The developer's by-kind index: where each CORA aggregate's BMM content lives. It hosts no content of its own. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC -[modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at BMM | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (EnergyAxis) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [The beamline](index.md#enclosures) (6-BM-A optics, 6-BM-B endstation) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### Deliberately not here yet - -This is a design-phase scaffold (descriptor + docs), mirroring HXN and the Diamond beamlines. Left out on purpose: - -- **The `energy_scan` Capability.** BMM is the first real consumer of the energy-scan sweep the catalog already anticipates (pending in code), but a Capability is coined when a conduct-path consumes it, not at scaffold time (see [Techniques](#techniques), ENERGY-1). This is the live earn-the-abstraction question BMM surfaces. -- **No new Family.** BMM reuses existing catalog Families: the ion chambers reuse `FluxMonitor` (graduated in #353), the fluorescence detector the catalog `EnergyDispersiveSpectrometer`, plus the catalog `Screen` Family (FLAG-1) for the diagnostic screens. The sample wheel reuses `RotaryStage`; whether a sample-changer Family is earned across BMM and the Diamond robots is open (WHEEL-1). -- **Operations and experiment views, integration scenarios, vendor Models.** A runbook and registered Assets for a beamline CORA does not yet drive would be invention; they land when the design firms and the team confirms. - -## Open questions - -*What CORA needs the BMM team to confirm. This model is reverse-engineered from public open source (the [`NSLS2/bmm-profile-collection`](https://github.com/NSLS2/bmm-profile-collection) profile collection): the EPICS PVs are read from it, but vendor identities, physical positions, and the detector configuration are not. Each row is a fact the beamline team owns. It is a delete-on-answer queue.* - -Priorities: `Blocks-build` (changes the model structure), `Blocks-go-live` (needed before CORA controls or observes the hardware), `Nice-to-have`. - -### Source and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Nice-to-have | The 6-BM bending-magnet source parameters (critical energy, fan). The source is confirmed a bending magnet (`SR:C06`), not an insertion device. | A bending-magnet PhotonBeam Supply, identity-only. | The Source Supply settings. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit-leaf PVs. Only the front-end and photon shutters (`XF:06BM-PPS{Sh:FE}`, `{Sh:A}`) are in source. | The permit signal is a confirm note, not a guessed PV. | The Enclosure permit signals. | -| ENC-1 | Nice-to-have | Is the endstation a distinct hutch (6-BM-B) from the optics hutch (6-BM-A)? | Two enclosures, optics + experiment. | The Enclosure set and roles. | - -### Optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DCM-1 | Nice-to-have | The DCM crystal sets available (Si(111) confirmed; a Si(311) set?) and the energy range. | Si(111), range blank. | The Monochromator settings. | -| OPTIC-1 | Nice-to-have | The mirror coatings / stripes on M1 and M2 (harmonic rejection). | Two mirrors, coatings blank. | The Mirror settings. | - -### Sample and detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| WHEEL-1 | Blocks-go-live | The sample wheel: how many sample positions, and is batch sample-changing a CORA-modelled automation or operator-driven? Should a dedicated sample-changer Family be earned across BMM and the Diamond robots, or does the wheel stay a `RotaryStage`? | A `RotaryStage` indexing samples; sample-changer behaviour is a Method/automation concern, not a new Family. | The sample-wheel model and the sample-changer abstraction. | -| DET-1 | Blocks-go-live | The fluorescence detector configuration: which Xspress3 element count (1, 4, or 7) is the installed/default, and the vendor (Quantum Detectors?). Source carries all three configurations. | One `EnergyDispersiveSpectrometer` Asset presenting the Sensor Role; element count blank. | The detector Model and element count. | -| DIAG-1 | Blocks-go-live | The ion chambers (`I0`/`It`/`Ir`) gas fill and the per-channel PV bindings. | The quad electrometer binds the catalog `FluxMonitor` Family (graduated in #353); gas fill and per-channel detail unconfirmed. | The I0/It/Ir bindings and gas fill. | - -### Controls and techniques - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DRIVE-1 | Blocks-go-live | The motion-controller box models, firmware, serials, IPs. The endstation controller PV (`MC:09`) is in source; vendor detail is not. | A `MotionController`, specifics blank. | The MotionController Models. | -| ENERGY-1 | Blocks-build | Should CORA coin the `energy_scan` Capability (the catalog anticipates it as pending) now that BMM is its first real consumer, or keep XAS under `characterization` + `energy_change` until a conduct-path forces it? An XAS scan sweeps the energy axis and reads the detectors per point, distinct from the `beamline_energy_change` setpoint move. | XAS mapped to existing Capabilities for now; `energy_scan` deferred per the design-phase discipline. | The spectroscopy Capability decision. | diff --git a/docs/deployments/cdi/notes.md b/docs/deployments/cdi/notes.md deleted file mode 100644 index ed91ed6c3f6..00000000000 --- a/docs/deployments/cdi/notes.md +++ /dev/null @@ -1,106 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at CDI: coherent-imaging techniques, each a [Catalog](../../catalog/methods.md) Method. CDI follows the deferral the coherent and scanning beamlines set, after Diamond [i13-1](../i13-1/notes.md#techniques), which opened the pending `ptychography` Method, and APS [8-ID](../8-id/notes.md#techniques), [CHX](../chx/notes.md#techniques), and [HXN](../hxn/notes.md#techniques).* - -CDI's techniques are coherent diffractive imaging: focus a coherent beam, record the far-field diffraction pattern, and recover the real-space image offline by phase retrieval. These Methods are new to CORA's imaging- and spectroscopy-heritage catalog, so the Methods below render unlinked and are carried pending until the owner-scope decision (TECH-1) brings them into the catalog. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Ptychography | `ptychography` | a scan of overlapping coherent-diffraction frames across the sample; reuses the pending `ptychography` Method Diamond i13-1 opened; the reconstruction is a `ComputePort` leg, not a beamline Method (the HXN framing) | -| Forward CDI | `coherent_diffraction_imaging` | a single far-field coherent-diffraction frame on the Eiger2 / Merlin from an isolated object; the single-shot variant of the same deferred coherent-imaging cohort, not separately coined | -| Bragg CDI | `coherent_diffraction_imaging` | a rocking series around a Bragg peak for strain imaging of a crystalline grain, with the [goniometer](sample.md) setting the orientation; the same deferred coherent-imaging cohort | -| Alignment | [`alignment`](../../catalog/methods.md) | beam, KB, mirror, and slit tuning; reuses the existing Method | - -All three imaging techniques need the [KB nanofocus and sample stack](sample.md) and the [coherent detectors](detector.md); how the exposure is gated on the floor is the open timing question (TIMING-1). - -### Why the Methods stay deferred - -Diamond i13-1 opened the coherent-imaging Method as the pending `ptychography` Method (the fleet's first coherent diffractive imaging), carried pending until a conduct-path earns it (TECH-1). CDI reinforces that Method at a second facility and adds the single-shot forward and Bragg CDI variants, which are not separately coined; the concrete acquisition recipes (frame counts, scan grids, rocking ranges, exposures) join as the deployment approaches the point where CORA drives the beamline. This is the same earn-the-abstraction discipline the deferred `small_angle_scattering` (8-ID, CHX) techniques follow. Because the full coherent-imaging Method scope is not in the catalog, CDI records **no Practice** in the [NSLS-II Site](../nsls2/index.md), as CHX records none for its coherent-scattering Methods; the binding lands when the Method does. - -The phase retrieval itself (the iterative reconstruction that turns the diffraction frames into a real-space image, and the ptychographic engine that solves for object and probe together) is `ComputePort` work, not a beamline Method. This is the imaging analogue of CHX's correlation analysis: the beamline takes the frames, CORA's compute leg turns them into the result. - -## Governance - -*Who may act at CDI and the trust shape CORA applies. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority.* - -People and agents are facility principals at the [NSLS-II Site](../nsls2/index.md); on the beamline they surface through the actions they take. The human roster is not known from the profile collection (GOV-1), so the principals are the design shape, not a registered list. - -### Who acts - -CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the NSLS-II Site. A CDI beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. - -### The trust boundary - -CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may align the KB nanofocus, change the incident energy, arm a ptychographic scan, override a caution, or commit a calibration. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer. The NSLS-II proposal and cycle are a fact CORA's Campaign uses for custody. - -### Long unattended scans - -A ptychographic map or a Bragg-CDI rocking series can run long and unattended, which is where CORA's trust shape earns its keep: the engine holds the scan while the trust boundary bounds what may change mid-acquisition and who may intervene. If an autonomous Agent were added to steer acquisition (choose the next scan region, decide when the diffraction signal is sufficient, trigger a reconstruction to check convergence), it would be a facility principal scoped at the Site, governed by the same trust boundary, with each choice recorded as a [Decision](../../architecture/modules/decision/index.md). None is declared yet. - -## Model - -*The developer's by-kind index: where each CORA aggregate's CDI content lives. It hosts no content of its own. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC -[modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at CDI | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [the stage pages](source.md) (`EnergyAxis`) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [The beamline](index.md#enclosures) (9-ID-A optics, 9-ID-C endstation) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### Deliberately not here yet - -This is a design-phase scaffold (descriptor + docs), mirroring CHX, HXN, and the other reverse-engineered deployments. Left out on purpose: - -- **No new Family.** CDI is a reuse-and-reinforce deployment: the area detectors and diagnostic cameras bind `Camera`, the foil intensity monitor `FluxMonitor`, the pre-mirrors and the KB nanofocus pair `Mirror`, both monochromators `Monochromator`, the sample stack `Goniometer`, the white-beam / branch / conditioning slits `Slit`, the attenuator foils `Filter`, the undulator `InsertionDevice`, the master energy a `PseudoAxis`, and the endstation towers `LinearStage`. Nothing graduates and the catalog is unchanged. -- **The diagnostics and supply readback.** The `DiamondBeamMonitor` binds the graduated catalog `PositionMonitor` Family, which presents the `Sensor` Role, earned across the wide fleet that shares it, distinct from `FluxMonitor` by measuring beam position rather than flux. The `StorageRing` current readback is a loose supply observation (machine state), never an Asset Family. -- **No new Capability or Method.** Ptychography reuses the pending `ptychography` Method Diamond i13-1 opened (the fleet's first coherent diffractive imaging); forward and Bragg CDI are the single-shot variants of the same deferred coherent-imaging cohort, not separately coined (`TECH-1`). CDI reinforces the Method without coining anything and records no Practice until the scope lands. The phase retrieval and ptychographic reconstruction are `ComputePort` work, not a Method. -- **Operations and experiment views, integration scenarios, vendor Models.** A runbook and registered Assets for a beamline CORA does not yet drive would be invention; they land when the design firms and the team confirms. - -## Open questions - -*What CORA needs the CDI team to confirm. This model is reverse-engineered from public open source (the [`NSLS2/cdi-profile-collection`](https://github.com/NSLS2/cdi-profile-collection) profile collection and the [`NSLS2/cditools`](https://github.com/NSLS2/cditools) device library): the EPICS PVs are read from them, but vendor identities, physical positions, and the timing configuration are not. Each row is a fact the beamline team owns. It is a delete-on-answer queue.* - -Priorities: `Blocks-build`, `Blocks-go-live`, `Nice-to-have`. - -### Source and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Nice-to-have | IVU18 undulator period, gap range, and harmonic usage. The device (`SR:C09-ID:G1{IVU18:1}`) is confirmed. | An in-vacuum undulator, identity-only. | The InsertionDevice settings. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit-leaf PVs and the photon-shutter PVs. Neither is in source. | The permit signal is a confirm note, not a guessed PV. | The Enclosure permit signals. | -| ENC-1 | Nice-to-have | Whether the 09IDB branch zone (`Slt:DM3`, the quadrant BPM) is a distinct access-gated enclosure or part of the optics hutch. | Two enclosures (9-ID-A optics, 9-ID-C endstation); 09IDB folded into the optics zone. | The Enclosure boundaries. | -| MACHINE-1 | Nice-to-have | The storage-ring state CDI reads (current, fill, status). | Observe-only machine state, a loose `StorageRing`; the exact PVs beyond `ring_current` pending. | The machine-state observation. | -| GOV-1 | Nice-to-have | The NSLS-II operator pool and safety-review structure (site-level, shared across the beamlines). | Carried pending on the NSLS-II Site, not instantiated per beamline. | The governance principals. | - -### Optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DCM-1 | Nice-to-have | The Si DCM cryo detail and full range (the Si(111) reflection and `d = 3.1287 A` are read from the Energy model), and the DMM multilayer coating and bandpass. Both monochromators (`Mono:HDCM`, `Mono:DMM`) are in source. | Two Monochromator Assets, Si(111) recorded, other settings blank. | The Monochromator settings. | -| KB-1 | Blocks-go-live | The KB mirror focal size, coating / stripe, and working distance; whether both VKB and HKB are always installed. | A `Mirror` Asset (the KB pair); focus geometry blank. | The KB nanofocus spec. | -| ENERGY-1 | Nice-to-have | Whether incident energy is ever scanned as the measurement, and the true energy range (the `5-15 keV` bounds are marked `TODO: CHECK` in source). | Fixed-energy imaging; the range left provisional. | The energy Capability decision. | - -### Sample and detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| STAGE-1 | Blocks-go-live | Which endstation tower (`TDMS:T1` / `TDMS:T2`) carries the sample versus the detector, the sample-to-detector distance that sets the q-range, and the full `Gon:1` goniometer axis set. Some tower axes are read-only pending commissioning in source. | Two `LinearStage` towers and a `Goniometer`; roles and distance deferred. | The endstation geometry. | -| DET-1 | Blocks-go-live | Which detector (Eiger2 / Merlin) is primary for which technique, the foil materials / thicknesses, and whether a direct-beam beamstop is installed (none is in source). | Both Cameras; Eiger2 primary; no beamstop modelled. | The detector roster and beamstop. | -| CAM-1 | Nice-to-have | Which diagnostic cameras (the BCU inline camera, the sample camera, the optics-module Prosilicas) are live. | The inline and sample cameras modelled; others noted. | The diagnostic-camera set. | -| DIAG-1 | Nice-to-have | The foil-monitor channel map and the quadrant / diamond BPM channels (the diamond BPM was repurposed from ion-chamber use in source). | Read-only flux and beam-position probes; channel maps blank. | The `FluxMonitor` and `PositionMonitor` bindings. | - -### Controls and technique scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TIMING-1 | Blocks-go-live | The exposure-gating chain. The profile collection exposes no trigger box (no Zebra / PandA startup file, no shutter PVs); the Eiger2 and Merlin carry internal and external trigger modes. How is a coherent-imaging exposure gated and synchronized with the scan? | Detector-internal triggering; no floor trigger box modelled. | The triggering chain. | -| DRIVE-1 | Blocks-go-live | The motion-controller box models, firmware, IPs behind the EPICS motor records. | One `MotionController` family bound (`EndstationMotionController`), specifics blank. | The MotionController Models. | -| TECH-1 | Blocks-go-live | Do the coherent-imaging Methods (forward CDI, ptychography, Bragg CDI) enter CORA's catalog, or stay deferred? This is the same owner-scope decision 8-ID opened. | Methods deferred (rendered unlinked), no Practice recorded. | The coherent-imaging Method scope. | diff --git a/docs/deployments/chx/notes.md b/docs/deployments/chx/notes.md deleted file mode 100644 index 1dad38b97a0..00000000000 --- a/docs/deployments/chx/notes.md +++ /dev/null @@ -1,104 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at CHX: coherent-scattering techniques, each a [Catalog](../../catalog/methods.md) Method. CHX is the second coherent beamline CORA models, after APS [8-ID](../8-id/notes.md#techniques), and it follows 8-ID's deferral exactly.* - -CHX's techniques are coherent-scattering, new to CORA's imaging- and spectroscopy-heritage catalog. As at 8-ID, the Methods below render unlinked and are carried pending until the owner-scope decision (TECH-1) brings them into the catalog. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| XPCS | `xpcs` | coherent-speckle intensity time series on the Eiger, gated by the Zebra / fast shutter (TIMING-1); Method not yet in catalog | -| Small-angle scattering | `small_angle_scattering` | static SAXS/WAXS on the same detectors; a Plan setting over the same chain | -| Grazing-incidence scattering | `small_angle_scattering` | GISAXS: the same scattering Method with the beam steered onto a surface by the `GrazingIncidenceMirror` (GI-1) | -| Alignment | [`alignment`](../../catalog/methods.md) | beam, mirror, transfocator, and slit tuning; reuses the existing Method | - -All three scattering techniques need the [sample stack](sample.md) and the [coherent detectors](detector.md); the fast shutter and Zebra (TIMING-1) gate the exposure. - -### Why the Methods stay deferred - -8-ID opened the question of whether the XPCS and small-angle-scattering Methods enter CORA's catalog (TECH-1), and `main` deliberately left them pending: the concrete acquisition recipes (correlation time series, frame rates, exposures) join as the deployment approaches the point where CORA drives the beamline. CHX reinforces the case for both Methods at a second facility without coining either, the same earn-the-abstraction discipline the deferred `scanning` (HXN) and `energy_scan` (BMM) Capabilities follow. Because the defining Methods are not in the catalog, CHX records **no Practice** in the [NSLS-II Site](../nsls2/index.md#the-techniques-adapted-here), exactly as 8-ID records none at APS; the binding lands when the Method does. - -The correlation analysis itself (the g2 / multi-tau computation that turns the frame series into dynamics) is `ComputePort` work, not a beamline Method. - -## Governance - -*Who may act at CHX and the trust shape CORA applies. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority.* - -People and agents are facility principals at the [NSLS-II Site](../nsls2/index.md#safety-and-governance); on the beamline they surface through the actions they take. The human roster is not known from the profile collection (GOV-1), so the principals are the design shape, not a registered list. - -### Who acts - -CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the NSLS-II Site. A CHX beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. - -### The trust boundary - -CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may arm a long XPCS series, change the q-range, override a caution, or commit a calibration. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer. The NSLS-II proposal and cycle are a fact CORA's Campaign uses for custody. - -### Long unattended runs - -XPCS time series can run long and unattended, which is where CORA's trust shape earns its keep: the engine holds the gated exposure while the trust boundary bounds what may change mid-series and who may intervene. If an autonomous Agent were added to steer acquisition (choose the next sample temperature, decide when enough frames are collected), it would be a facility principal scoped at the Site, governed by the same trust boundary, with each choice recorded as a [Decision](../../architecture/modules/decision/index.md). None is declared yet. - -## Model - -*The developer's by-kind index: where each CORA aggregate's CHX content lives. It hosts no content of its own. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC -[modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at CHX | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (EnergyAxis) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [The beamline](index.md#enclosures) (11-ID-A optics, 11-ID-B endstation) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### Deliberately not here yet - -This is a design-phase scaffold (descriptor + docs), mirroring HXN, BMM, SRX, and the Diamond beamlines. Left out on purpose: - -- **No new Family.** CHX is a reuse-and-reinforce deployment: the area detectors bind `Camera`, the flux counter `FluxMonitor`, the thermal stage `TemperatureController`, the fluorescence detector `EnergyDispersiveSpectrometer`, the beamstop `BeamStop`, the mirrors `Mirror`, both monochromators `Monochromator`, the coherence-defining and guard slits `Slit`, and the compound-refractive-lens focusing optic the graduated `Transfocator` catalog Family (a CRL focusing optic, also bound at 4-ID, 8-ID, 9-ID, i22). The `Transfocator` graduation settled the focusing-optic abstraction, so it is a normal catalog reuse like `Mirror`; what remains open for the transfocator is only its per-Asset lens material and count, tracked as `CRL-1`. CHX also carries a **second**, distinct kind of refractive focusing optic, the endstation kinoform lenses (`k1`/`k2`): a single profiled refractive lens, not a compound-lens transfocator, so it does not bind the `Transfocator` Family. It is named but not modelled as a device; whether a kinoform earns its own Family is a separate future question if a deployment binds one, not part of `CRL-1`. -- **The graduated `PositionMonitor`.** The `PositionMonitor` (4-ID, 8-ID, 9-ID) binds the graduated catalog Family, which presents the `Sensor` Role, earned across the wide fleet that shares it, distinct from `FluxMonitor` by measuring beam position rather than flux. -- **No new Capability or Method.** XPCS and small-angle scattering sit on the deferred `xpcs` / `small_angle_scattering` Methods 8-ID left pending (`TECH-1`); CHX reinforces both without coining either, and records no Practice until they land. The correlation analysis is `ComputePort` work, not a Method. -- **Operations and experiment views, integration scenarios, vendor Models.** A runbook and registered Assets for a beamline CORA does not yet drive would be invention; they land when the design firms and the team confirms. - -## Open questions - -*What CORA needs the CHX team to confirm. This model is reverse-engineered from public open source (the [`NSLS2/chx-profile-collection`](https://github.com/NSLS2/chx-profile-collection) profile collection): the EPICS PVs are read from it, but vendor identities, physical positions, and the detector/timing configuration are not. Each row is a fact the beamline team owns. It is a delete-on-answer queue.* - -Priorities: `Blocks-build`, `Blocks-go-live`, `Nice-to-have`. - -### Source and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Nice-to-have | IVU20 undulator period, gap range, and harmonic usage. The device (`SR:C11-ID:G1{IVU20:1}`) is confirmed. | An in-vacuum undulator, identity-only. | The InsertionDevice settings. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit-leaf PVs. Only the shutters (`XF:11ID-PPS{Sh:FE}`, `XF:11IDA-PPS{PSh}`) are in source. | The permit signal is a confirm note, not a guessed PV. | The Enclosure permit signals. | - -### Optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DCM-1 | Nice-to-have | The Si DCM cryo detail and full range (the Si(111) cut and harmonic 5 are read from the production `move_E` routine), and the DMM multilayer coating and bandpass. Both monochromators (`Mono:DCM`, `Mono:DMM`) are in source. | Two Monochromator Assets, Si(111) cut recorded, other settings blank. | The Monochromator settings. | -| CRL-1 | Blocks-go-live | The FOE transfocator (`XF:11IDA-OP{Lens:`) lens material and lenslet count. Its catalog home is settled: it binds the graduated `Transfocator` CRL Family; only the per-Asset lens spec is open. (The endstation kinoform lenses `k1`/`k2`, `XF:11IDB-OP{Lens:1` / `{Lens:2`, are a distinct refractive optic, not a compound-lens transfocator; they are named but not modelled as devices, and whether they earn their own Family is a separate future question, not part of CRL-1.) | The transfocator binds the graduated `Transfocator` Family; lens material and count left blank. | The transfocator lens spec. | -| GI-1 | Nice-to-have | Is grazing-incidence scattering (GISAXS) a live routine, and does the `Mir:GI` mirror steer the beam for it? | A `Mirror` Asset; GISAXS noted as a technique. | The GISAXS geometry. | - -### Sample and detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| STAGE-1 | Blocks-go-live | The full diffractometer axis set behind the `SamplePositioner` pseudomotor, and whether the goniometric axes warrant a `Goniometer` plus a Diffractometer Assembly (the 8-ID precedent). | A `LinearStage` sample stack, rotation axes and the Assembly deferred. | The SampleStage axes and orientation modelling. | -| DET-1 | Blocks-go-live | Which Eiger (4M / 1M / 500K) is the primary XPCS detector vs the spare set, whether a separate along-beam stage sets the sample-to-detector distance (the `Det:SAXS` motor is transverse X/Y only), and the Xspress3 element count. | Eiger 4M primary; all Cameras; no distance stage modelled. | The detector roster and q-range. | -| CAM-1 | Nice-to-have | Which beam-viewing cameras (the Prosilica x-ray-eyes, the PointGrey, the OAV) are live. | The OAV modelled as a Camera; others noted. | The beam-viewing camera set. | -| DIAG-1 | Nice-to-have | The scaler flux channel map (which channel is I0) and the BPM / AH401B electrometer channels. | Read-only flux and beam-position probes; channel maps blank. | The FluxCounter and PositionMonitor bindings. | - -### Controls and technique scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TIMING-1 | Blocks-go-live | The XPCS exposure-gating chain: how the Zebra, the delay generator (`delaygen:DG0:`), and the fast shutter co-time the Eiger frame triggers, and their vendor identities. | One `TimingController` (Zebra) gating the fast shutter and frames; chain detail blank. | The triggering chain. | -| DRIVE-1 | Blocks-go-live | The motion-controller box models, firmware, IPs. | Families bound (MotionController), specifics blank. | The MotionController Models. | -| ENERGY-1 | Nice-to-have | Is CHX always fixed-energy, or does anomalous XPCS scan energy as the measurement (the `energy_scan` Capability the catalog anticipates, shared with BMM)? | Fixed-energy; energy_scan deferred (the BMM question). | The energy Capability decision. | -| TECH-1 | Blocks-go-live | Do the XPCS and small-angle-scattering Methods enter CORA's catalog, or stay deferred? This is the same owner-scope decision 8-ID opened. | Methods deferred (rendered unlinked), no Practice recorded. | The coherent-scattering Method scope. | diff --git a/docs/deployments/cms/notes.md b/docs/deployments/cms/notes.md deleted file mode 100644 index 5aa061d2bc5..00000000000 --- a/docs/deployments/cms/notes.md +++ /dev/null @@ -1,174 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of CMS is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../nsls2/index.md#the-techniques-adapted-here) is how a facility adapts it. CMS measures soft-matter and thin-film structure four ways: small-, wide-, and medium-angle scattering (SAXS / WAXS / MAXS), grazing-incidence scattering (GISAXS / GIWAXS), and specular X-ray reflectivity (XR). Three of those four are scattering the fleet already speaks; the Methods below render unlinked and are carried pending until the owner-scope decision (`TECH-1`) brings any of them into the catalog. - -CMS is the NSLS-II twin of [SMI](../smi/notes.md#techniques) (12-ID), and most of what it does reinforces vocabulary CORA already holds. Read this page for the one technique that is genuinely distinct: specular reflectivity. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Small-angle scattering (SAXS) | `small_angle_scattering` | low-Q on the [SAXS Pilatus 2M](detector.md); shares the science axis with [i22](../i22/notes.md#techniques) and [SMI](../smi/notes.md#techniques); Method not yet in catalog (`TECH-1`) | -| Wide- and medium-angle scattering (WAXS / MAXS) | `wide_angle_scattering` | wider-Q on the [Pilatus 800K heads](detector.md), one powered per configuration; shares the axis with [i22](../i22/notes.md#techniques); Method not yet in catalog (`TECH-1`) | -| Grazing-incidence scattering (GISAXS / GIWAXS) | `grazing_incidence_scattering` | the same scattering with the sample at a grazing angle on `sth`; shares the axis with APS 9-ID and its NSLS-II twin [SMI](../smi/notes.md#techniques); Method not yet in catalog (`TECH-1`) | -| Specular X-ray reflectivity (XR) | `reflectivity` | step `sth`, slide a detector region-of-interest in lockstep across the fixed [Pilatus 2M](detector.md), integrate the specular intensity; the second consumer of the reflectivity Method after [i10](../i10/notes.md#techniques) (`XR-1`, `TECH-1`) | - -All four techniques need the [incident-beam chain](source.md) (the DMM for energy, the mirrors, slits, and absorber foils), the [sample stack](sample.md) (the [Goniometer](sample.md), surface-leveling tilts, temperature stage), and the [endstation detectors](detector.md) (the Pilatus heads, beamstop, flux monitors). Scattering reads an area frame at one orientation; reflectivity reads the same area detector while the orientation is stepped. - -### The scattering is reinforcement, not novelty - -SAXS, WAXS, MAXS, and grazing-incidence scattering overlap the fleet heavily. CMS is the direct NSLS-II twin of [SMI](../smi/notes.md#techniques), and the two share their science axis with Diamond [i22](../i22/notes.md#techniques) and APS 9-ID / 12-ID: the same Camera / Goniometer / Slit / BeamStop / FluxMonitor vocabulary, zero new families, the same pending scattering Method slugs. MAXS is a detector-position variant of wide-angle scattering on a second Pilatus 800K head, not a technique of its own. GISAXS / GIWAXS is the same scattering with the sample tipped to a grazing angle on `sth`, a sample-orientation variant rather than a new Capability. - -So the scattering side of CMS earns no new abstraction. It reinforces, at a second NSLS-II beamline, the case that the small- and wide-angle scattering Capabilities belong in the catalog (`TECH-1`), the same earn-the-abstraction discipline SMI and i22 already follow. The device Roles exist (the Pilatus heads present Detector, the flux monitors present Sensor), so what stays pending is the science Capability, not a device shape. Because those Capabilities are not yet in the catalog, the matching Site Practices (`CMS_small_angle_scattering_practice`, `CMS_wide_angle_scattering_practice`, `CMS_grazing_incidence_scattering_practice`) are carried pending in the [NSLS-II Site](../nsls2/index.md#the-techniques-adapted-here); each binding lands when its Capability does. - -### Specular reflectivity, the distinct contribution - -Specular X-ray reflectivity is the one technique CMS brings that the scattering vocabulary does not cover, and CORA models it as a **Method over existing devices**, coining no hardware. - -There is no physical two-theta detector arm at CMS, and no point detector. The area detector stays fixed. The measurement steps the sample incidence angle `sth` (the same grazing-incidence angle the GISAXS Method uses) and, in lockstep, slides a software region-of-interest across the face of the fixed [Pilatus 2M](detector.md) to where the specularly reflected beam lands at each angle. The intensity inside that tracked region is integrated; the angle the region sits at is a **synthetic** two-theta computed from the geometry, not a value read off a moving arm. The result is the reflectivity curve: specular intensity versus angle, with the incident flux read on the [endstation flux monitor](detector.md) to normalize. - -| Reuses | Role in XR | -| --- | --- | -| [Goniometer](sample.md) (`sth`) | steps the specular incidence angle | -| [Pilatus 2M Camera](detector.md) | read over a tracked region-of-interest; the synthetic two-theta is where that region sits | -| [endstation FluxMonitor](detector.md) | incident flux, for normalization | - -That is the whole device list. XR coins no two-theta arm, no point detector, no new family. The reflectivity Method is the same one [i10](../i10/notes.md#techniques) brought to CORA at its soft X-ray sibling, where the geometry is realized differently; CMS is the **second consumer** of the Method (`XR-1`), realizing it in the hard X-ray regime with no new hardware. As with the scattering Capabilities, the Method is not yet in the catalog and `CMS_reflectivity_practice` is carried pending (`TECH-1`, `XR-1`). - -### Not modelled yet - -The concrete acquisition recipes are not written yet. For scattering that is the per-frame exposures, detector distances, beamstop placement, and the azimuthal integration that turns 2D frames into I(Q) curves (the integration and reduction are `ComputePort` work, not beamline Methods). For reflectivity it is the `sth` step list, the region-of-interest tracking model that maps each angle to its place on the fixed Pilatus, and the synthetic two-theta calibration. These join as the deployment approaches the point where CORA drives CMS. - -Whether any of these four techniques enters CORA's catalog is an owner-scope decision on [Model](#model): a modelling exercise reinforces the case but does not mint cross-facility Method vocabulary on its own. The scattering Capabilities are shared pending slugs the fleet already debates; what CMS adds is a second consumer of the pending `reflectivity` Method (i10 plus CMS), which strengthens the case for cataloging it but leaves that an owner decision, not an automatic one (`XR-1`, `TECH-1`). See [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at CMS, and the trust shape that will gate it. First cut.* - -Governance at CMS 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#safety-and-governance), 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). - -CMS is not yet driven by CORA, so this shape is not yet instantiated. As a modelling-exercise scaffold, the deployment is descriptor and docs today, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized. The profile collection exposes only coarse queue-server groups, not the human roster, so the NSLS-II operator pool and review structure is carried pending on the [NSLS-II Site](../nsls2/index.md#safety-and-governance), shared with the rest of the fleet (GOV-1). - -### The safety boundary - -The safety tier is the other piece that is not yet settled. The PSS search-and-secure permit signals and the front-end and photon shutters are absent from the beamline's profile collection, so the Enclosure permit leaves and the interlock structure are carried pending and are not invented here (PSS-1). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [NSLS-II Site](../nsls2/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -CMS adds the hazard classes that come with its instruments. Those land with the equipment that brings them, and an experiment Clearance would carry them. - -| Hazard class | Where it lands | Tracking | -| --- | --- | --- | -| Hard X-ray beam | the [optics](index.md) and [endstation](index.md) enclosures (XF:11BMA, XF:11BMB) (ENC-1) | (PSS-1) | -| Vacuum optics and the telescoping flight path | the [Source](source.md) walk and the detector translations | (SUP-1) | -| In-situ temperature environments | the [Sample](sample.md) thermal / tensile stage | (TEMP-1) | - -The hard X-ray beam is the interlocked hazard; its permit leaves stay pending until the PSS signals are confirmed (PSS-1). The vacuum extent and the cooling supply that the optics and flight path depend on are carried pending (SUP-1), and the in-situ temperature range that the Linkam stage brings is carried with it (TEMP-1). None of these is invented; each is recorded against its question. - -### When the shape lands - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives CMS, following the [2-BM governance](../2-bm/governance.md) shape. Because CMS shares the NSLS-II EPICS and ophyd floor with FXI, HXN, SRX, BMM, SIX, CHX, ESM, and its twin SMI, it re-tests the Site and Federation kernel rather than introducing a new trust model. The Zone groups the same optics and endstation resources the [inventory](index.md) lists; the Conduit binds the command surfaces; the Policies bind to the NSLS-II operator roles carried pending at the Site (GOV-1). - -## Model - -*The developer's by-kind index: where each CORA aggregate's CMS content lives, how it models specular reflectivity without a device, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at CMS | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (the incident-energy `PseudoAxis`) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes CMS new - -The honest answer is: not much on the scattering, and one real thing on reflectivity. CMS measures soft-matter and thin-film structure by small- and wide-angle scattering (SAXS / WAXS / MAXS), grazing-incidence scattering (GISAXS / GIWAXS), and specular X-ray reflectivity (XR). The scattering overlaps the fleet heavily: CMS is the direct NSLS-II twin of SMI (12-ID), and shares its science axis with Diamond I22 and APS 9-ID / 12-ID. That scattering reuses the existing `Camera` / `Goniometer` / `Slit` / `BeamStop` / `FluxMonitor` / `Monochromator` / `Mirror` vocabulary and contributes reinforcement, not novelty. - -CMS's two genuinely distinct contributions are: - -- **Specular X-ray reflectivity (XR), the fleet's first hard X-ray reflectometry.** It measures the specularly reflected intensity as a function of incidence angle to recover a film's depth profile. What is interesting for CORA is the mechanism: there is no physical two-theta detector arm. The area detector stays fixed, and the "two-theta" is synthetic, a software region-of-interest that slides across the fixed Pilatus face to where the reflected beam lands as the sample theta (sth) is stepped. So XR is purely a Method, realized over existing devices. -- **CMS as a further NSLS-II beamline, re-testing the Site and Federation kernel.** Its double-multilayer monochromator reuses the same `Monochromator` Family as the APS 2-BM DMM, reinforcing that reuse. - -### No new families - -CMS coins no new Family and changes nothing in the catalog. - -- **11-BM is a bending-magnet source, not an insertion device** (the 2-BM / 7-BM pattern), so there is no `InsertionDevice` Asset; the machine state is observed through the loose `StorageRing`, and the source detail is `SRC-1`. -- **The DMM binds `Monochromator`** (a multilayer Bragg optic, the 2-BM double-multilayer precedent, not the soft X-ray `GratingMonochromator`); the incident energy is a `PseudoAxis` over its Bragg angle. -- **The scattering devices all reuse:** the focusing mirrors bind `Mirror`; the slits bind `Slit`; the attenuator foils bind `Filter`; the sample-orientation circles bind `Goniometer` (sth is the grazing / specular incidence axis); the surface-leveling stage binds `TiltStage`; the SAXS / WAXS / MAXS Pilatus detectors bind `Camera`; the detector translations and the telescoping flight path bind `LinearStage`; the beamstop binds `BeamStop`; the ion chamber, electrometers, and scintillation counter bind `FluxMonitor`; the diamond-diode beam-position monitor binds the graduated catalog `PositionMonitor` (presenting `Sensor`, distinct from `FluxMonitor` by measuring beam position rather than flux; the per-Asset channel map stays `DIAG-1`); the Linkam stage binds `TemperatureController`; the support table binds `Table`. - -### How reflectivity is modelled (no device) - -Specular reflectivity (XR) is modelled as a Method (a Practice) over existing devices, not as a new device or a new detector arm: - -- the incidence angle is the `Goniometer` sample theta (sth); -- the reflected-beam intensity is read on the `Camera` (the Pilatus 2M, the same detector as SAXS) over a tracked region-of-interest; -- the incident flux for normalization is the `FluxMonitor` ion chamber. - -The "two-theta" is synthetic: the detector does not move, and the region-of-interest is slid across the fixed detector face to follow where the reflected beam lands as sth is stepped. So XR coins no device, no `Diffractometer` detector arm, and no point detector. The reflectivity Method is **shared with i10** (its soft X-ray RASOR sibling); CMS is the second consumer (`XR-1`). i10 (point-detector, soft X-ray) and CMS (area-detector region-of-interest, hard X-ray) are the rule-of-three pressure that could eventually graduate one reflectivity Method into the catalog; the soft-versus-hard and point-versus-area distinctions are Practice-level adaptations, not a Method split. - -### Deliberately not here yet - -- **The GIBar sample-exchange arm (`ROBOT-1`).** The multi-axis sample-bar loader is genuinely new automation that no catalog Family covers. Per earn-the-abstraction it is modelled by its stage axes (`LinearStage` / `RotaryStage`) at n=1, and no `SampleExchanger` Family is coined; a second fleet sample robot would earn the abstraction. The garage-indexed pick / place semantics are carried as a note, not modelled. -- **The auxiliary analog I/O and viewing cameras.** The generic analog diode box is carried as flux / diagnostic channels per its wiring, not a Family; the Prosilica sample-viewing cameras are not modelled in this cut. -- **The scattering and reflectivity Methods.** Whether SAXS, WAXS, GISAXS, and XR enter CORA's catalog as Capabilities / Methods is an owner decision; the Practices render unlinked, pending. The scattering Methods are shared with i22 / SMI / 9-ID and the reflectivity Method with i10 (`TECH-1`, `XR-1`). -- **The chamber rebinding and the sth / schi swap.** The beamline_stage configurations rebind the logical goniometer axes across physical PVs at startup, and staff have at times swapped sth and schi; CORA models the logical `Goniometer` and carries the active binding as a setting (`SAMPLE-1`), not as separate Assets. -- **The simulated devices and full asset-tree scenarios.** No `test_cms_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the CMS team to confirm before the model can be trusted.* - -CMS was reverse-engineered from the beamline's own bluesky profile collection ([NSLS2/cms-profile-collection](https://github.com/NSLS2/cms-profile-collection)), so the control handles on the [device pages](index.md) are the beamline's real PVs, read from the `startup/*.py` files rather than confirmed by staff. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | Are the PV zones XF:11BMA (first optics) and XF:11BMB (endstation) two separate hutches? | Two enclosures: a `cms-optics` zone and the `cms-endstation` hutch. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The 11-BM source: a bending magnet or a three-pole wiggler (absent from the profile collection as a device). | A bending-magnet source, observed only through the machine state. | The source Asset detail. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MACHINE-1 | Nice-to-have | The storage-ring state CMS reads (current, fill, status). | Observe-only machine state, a loose `StorageRing`; the exact PVs pending. | The machine-state observation. | -| MONO-1 | Blocks-go-live | The DMM multilayer d-spacing, the energy range (calibrations near 13.5 keV), and the energy partition rule. | A double-multilayer `Monochromator`; the energy is a `PseudoAxis` over the Bragg angle; d-spacing pending. | The monochromator and incident-energy Assets. | -| OPT-1 | Nice-to-have | The toroidal and elliptical mirror coatings and bend mechanisms. | Focusing mirrors bound to `Mirror`; coatings and bend pending. | The mirror Asset detail. | -| OPT-2 | Nice-to-have | The blade-axis roles of each slit (the FOE slit and the five endstation JJ slits, including the s4 transmission / grazing geometry presets). | Four-blade and center / gap slits bound to `Slit`. | The slit Asset detail. | -| ATTN-1 | Nice-to-have | The attenuator foil set (the eight pneumatic absorbers) and whether it folds into `Filter` or earns a distinct `Attenuator` kind (the fleet-wide question). | The foils bound to `Filter` (the i03 / i15-1 precedent). | The attenuator's catalog home. | - -### Sample - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SAMPLE-1 | Blocks-go-live | The sample-goniometer axes, the grazing / specular incidence axis (the historical sth versus schi swap), and the chamber rebinding (the beamline_stage configurations remap the logical axes across physical PVs at startup). | A `Goniometer` with sth as the incidence axis; the swap and the rebinding carried as settings. | The sample-stage modelling. | -| ROBOT-1 | Nice-to-have | The GIBar sample-exchange arm (a multi-axis sample-bar loader) and whether it earns a `SampleExchanger` Family or stays modelled as stage axes. | Modelled as `LinearStage` / `RotaryStage` axes at n=1; no `SampleExchanger` Family coined pending a second fleet sample robot. | The sample-exchange modelling; the CORA family decision is on [Model](#deliberately-not-here-yet). | -| TEMP-1 | Nice-to-have | The Linkam thermal / tensile stage temperature range and the tensile-load axis. | A `TemperatureController` Asset presenting the `Regulator` Role; range and load axis pending. | The temperature-environment modelling. | - -### Detection - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The SAXS / WAXS / MAXS Pilatus detector assignment (which 800K head is powered per configuration), the detector-distance calibrations, and the flux / beam-position channel map. | Three `Camera` Assets (Pilatus 2M SAXS, two 800K WAXS / MAXS); the monitors bind `FluxMonitor` and the diode beam-position monitor the graduated catalog `PositionMonitor`. | The detector modelling. | -| XR-1 | Blocks-go-live | The specular reflectivity (XR) realization: a fixed area detector read over a software region-of-interest tracking the reflected beam as the sample theta is stepped, with no physical two-theta arm. | XR is a Method over `Goniometer` (sth) + `Camera` (the Pilatus region) + `FluxMonitor`; no device coined; the reflectivity Method is shared with i10. | The reflectivity modelling; the CORA decision is on [Model](#deliberately-not-here-yet). | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the EPICS PV handles read from the profile collection current and correct? | The handles in the descriptor are taken from the profile collection and carried confirm. | Verifying each Asset's control handle. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit signals and the photon / front-end shutters (absent from the profile collection). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent (the optics, the sample chamber, the SAXS flight path) and the cooling supply. | Photon beam, cooling water, and vacuum on the optics and flight path. | The Supply observations. | -| GOV-1 | Nice-to-have | The NSLS-II operator pool and safety-review structure (site-level, shared across the beamlines). | Carried pending on the NSLS-II Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Blocks-go-live | Do the scattering and reflectivity techniques (SAXS, WAXS, GISAXS, XR) enter CORA's catalog as Capabilities / Methods? | Deferred: carried as pending Practices; the scattering Methods are shared with i22 / SMI / 9-ID and the reflectivity Method with i10; none coined. | The technique Capabilities. | diff --git a/docs/deployments/cristallina/notes.md b/docs/deployments/cristallina/notes.md deleted file mode 100644 index 339354b024d..00000000000 --- a/docs/deployments/cristallina/notes.md +++ /dev/null @@ -1,153 +0,0 @@ -# Notes - -## Techniques - -*What Cristallina is designed to do, as design intent. Design-phase: these are Methods CORA would earn, not Methods it has.* - -Cristallina runs two technique families, neither of which fits the catalog's tomography Methods, so each is carried pending on the [PSI Practices](../psi/index.md) until it is earned. They are listed here as design intent, with the shape each would take over the spine and the gap each leans on. - -### Time-resolved hard X-ray diffraction and scattering (quantum materials) - -Cristallina's reason for existing. The Cristallina-Q endstation studies quantum materials: their structural and electronic response is read by diffraction and scattering, shot by shot, in a controlled low-temperature, high-magnetic-field environment. The sample is oriented and the detector positioned by the DM1 dilution-fridge or DM2 pulsed-magnet diffractometer, inside the DilSc dilution refrigerator and its vector superconducting magnet. - -- **Spine shape:** a `diffraction` Method binding the diffractometer (a `Goniometer` for the sample circles, a `RotaryStage` 2-theta detector arm, and a reciprocal-space `PseudoAxis`), composed through the graduated `Diffractometer` Assembly (DIFF-1), over a per-shot acquisition, with the sample-environment state (temperature from the LakeShore 372, field from the vector magnet) as conditions. It shares the `diffraction` Method Bernina introduced. -- **Gap it leans on:** the per-shot, pulse-ID-tagged event DAQ (DAQ-1). A time-resolved diffraction run is a free-running shot stream tagged by pulse-ID, not a trajectory of points. The diffractometer is covered by the existing Assembly, and the sample environment by the `TemperatureController` Family and the graduated `Magnet` Family; the acquisition is the gap. - -The vector magnet is what distinguishes Cristallina-Q from Bernina's diffraction: the experiment sweeps not just delay and orientation but a three-axis magnetic field, in a dilution-fridge temperature regime. That sample environment is modelled (the LakeShore as `TemperatureController`, the magnet as the graduated `Magnet` Family, a further consumer, MAG-1) and gated by a Clearance hazard, but it adds no new technique-modelling shape beyond the conditions a Run already carries. - -### Serial femtosecond crystallography - -The Cristallina-MX endstation runs serial crystallography: microcrystals are delivered onto the fast XY sample stage and each X-ray pulse records a single-shot diffraction pattern. It shares the `serial_crystallography` Method LCLS-MFX and Alvra carry. - -- **Spine shape:** a `serial_crystallography` Method binding the fast sample stage, the focusing optics, and the 8M Jungfrau, over a free-running per-shot acquisition. -- **Gap it leans on:** the per-shot, pulse-ID-tagged event DAQ (DAQ-1), the same as for the other XFEL serial-crystallography exercises. The sample delivery beyond the fast stage is endstation-specific and deferred (SAMPLE-1). - -### Why neither is in the catalog yet - -The catalog's Methods are all tomography-family. An XFEL diffraction / crystallography station shares none of them, and coining XFEL Methods now, before the per-shot acquisition axis they depend on exists (DAQ-1), would be inventing recipes for a spine that cannot yet run them. So each is carried pending, reusing the Method name Bernina or LCLS-MFX named for it. That a third PSI station, on a different controls library (`slic`) and with a novel sample environment (the vector magnet), reaches the same acquisition gaps is the reinforcement Cristallina adds: the gaps are about the XFEL acquisition paradigm, not the technique or the controls house style. See [Model](#model) for the gap register, the `Diffractometer` Assembly design, and the `Magnet` rule-of-three. - -## Governance - -*Who would act at Cristallina and the trust shape that gates their commands. Design-phase: the principals are facility-level and carried pending.* - -Cristallina's principals are facility principals at the [PSI Site](../psi/index.md), not beamline-local: the SwissFEL instrument-scientist and operator pool, and the PSI safety-review body. Both are carried pending in the [site descriptor](../psi/index.md) until the PSI structure is confirmed; the `slic` device library is a controls library, not an organizational record, so it exposes no human roster (GOV-1). CORA's role kernel (the five-role authorization model) is facility-invariant, so Cristallina inherits it. Cristallina shares its Site, its Aramis source, and its safety posture with the sibling [Alvra](../alvra/notes.md#governance) and [Bernina](../bernina/notes.md#governance) stations, so most of the governance shape is the PSI-Site shape; what is worth drawing out is the shared-source boundary and the high-field-magnet hazard. - -### The shared Aramis source and the optics zone - -Cristallina is the third of three co-equal stations (with Alvra and Bernina) on one Aramis source, beam routed to one at a time (TOPO-1). The `SAROP31` optics hutch conditions the beam on the way to Cristallina, but the source upstream is shared. That makes the optics-hutch Zone a shared-access boundary, the same question Alvra and Bernina raise: who holds the permit when the beam is routed to a neighbour, and how the routing state gates each station's commands. With three stations now modelled on the one source, the routing state is a three-way selection, not a pair. The SwissFEL PSS search-and-secure permit signals are not in the `slic` manifest and are carried pending (PSS-1). Cristallina's enclosure structure (the shared `SAROP31` optics hutch plus the Cristallina experiment hutch) is carried `confirm` because the `slic` PV prefixes encode beamline-line zones, not access-gated hutches (ENC-1). - -### The high-field-magnet Clearance - -Cristallina's defining hazard is not a laser (the `slic` source has no pump-probe laser, LASER-1) but the **vector superconducting magnet** and its cryogens. The DilSc dilution refrigerator runs an Oxford Mercury iPS magnet to 5.2 Tesla on the z-axis, cooled by liquid helium. CORA carries this as a `Clearance` hazard on the experiment (a facility-issued safety permit that must be Active before high-field work), the same posture [ESRF ID32](../id32/notes.md#governance) takes for its 9 T XMCD magnet and its liquid-helium plant. This is distinct from whether the magnet is a driven Asset: the device binds the graduated `Magnet` Family (a further consumer, the per-Asset field detail pending, MAG-1), while the personnel- and quench-safety permit is a Clearance. The two coexist, the same way the laser device and the laser Clearance coexist at Alvra and Bernina. - -### What is not modelled - -- **Trust instantiation.** No scenario instantiates Cristallina trust zones or actors; this is a design-phase modelling exercise, so the governance shape is described, not seeded. It would land, following the [2-BM governance](../2-bm/governance.md) shape, if and when the deployment approaches real scope. -- **The magnet as a safety-driven Asset.** The vector magnet is modelled as a hazard via a Clearance, not as an Asset CORA drives for safety (the ID32 magnet and the Alvra / Bernina laser precedent). Its field setpoints are an experiment concern; its safety is a permit. -- **The DAQ and acquisition software as principals.** The SwissFEL `sf-daq`, `bsread`, and the `slic` scan suite are control-system software on the floor, not CORA actors (see [Controls](controls.md)). When the per-shot acquisition axis is designed (DAQ-1), the question of which principal authorizes a DAQ run is part of that work. - -People and agents are facility principals at the [PSI Site](../psi/index.md); see [Open questions](#open-questions) for the governance items still to confirm. - -## Model - -*The developer's by-kind index: where each CORA aggregate's Cristallina content lives, how the diffractometers reuse the graduated Assembly and the vector magnet binds an earned Family, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at Cristallina | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (the reciprocal-space `PseudoAxis`) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### The headline: no new Family, three things tested - -Cristallina coins **no new Family**, the same finding as Alvra and Bernina. But it tests the model against three things the prior PSI stations did not have, and the interest is in how each is absorbed by existing shapes. - -#### The diffractometers reuse the graduated Assembly (DIFF-1) - -Cristallina-Q has two diffraction platforms: DM1 (the dilution-fridge diffractometer, `SARES31-GPS`) and DM2 (the pulsed-magnet diffractometer, `SARES32-GPS`). Both are built by the `slic` `Diffractometer` driver from ECMC servo-motor axes (twotheta / theta plus base and sample translations; DM2 adds rot_x / rot_z swivels). As at [Bernina](../bernina/notes.md#model), each is the graduated [`Diffractometer` Assembly](../../catalog/assemblies.md): a composed `Goniometer` (the sample circles) plus a `RotaryStage` detector-arm circle plus a reciprocal-space `PseudoAxis`. The GPS / XRD platforms at Bernina were the Assembly's third and fourth bindings; the Cristallina DM1 / DM2 are its fifth and sixth. No new Family or Assembly is coined (DIFF-1; the reciprocal-space partition rule is DIFF-2). DM2's PV channels are commented out of the active `slic` config, so it is carried as present-hardware-not-acquired (DISABLED-1). - -#### The vector magnet is a further `Magnet` consumer (MAG-1) - -The DilSc sample environment is a dilution refrigerator with a 3-axis vector superconducting magnet (an Oxford Mercury iPS, field limits X,Y = ±0.6 T and Z = ±5.2 T). The magnet binds the **graduated `Magnet`** Family, whose rule-of-three was earned across 4-ID, i10-1, and ESRF ID32 (the 9 T XMCD magnet). Cristallina is a **further consumer**, binding the catalog Family like any other (MAG-1 now covers only the per-Asset field ranges and control handles). The `Magnet` Family presents the `Regulator` Role, the field a settable process variable, and the LakeShore 372 thermometry / heater binds the **graduated `TemperatureController`** Family (also presents the Regulator Role), the ID32 VTI precedent. The vector geometry (three independently-ramped field axes) is a richer setting than the single-axis magnets, but it is a per-Asset setting, not a Family split, the same way the diffractometer axis counts are. - -#### The absent pump-probe laser (LASER-1, reframed) - -Alvra and Bernina each carry a pump-probe `Laser` and an arrival-time monitor. Cristallina's `slic` source has neither: no `SLAAR` / `PALM` / `PSEN` devices appear, and the only laser is the X-ray alignment laser (`SAROP31-OLAS147`, a catalog `Laser`). Pump-probe timing is mediated by the CTA sequencer (`SAR-CCTA-ESC`) and the EVR, with a server-side pulse-tube synchronization service (`oscillations.psi.ch`). So this cut models no pump-probe-laser Asset. Whether Cristallina has a pump-probe laser in a different controls layer (as Alvra and Bernina do in `eco`'s `loptics`) is carried as an open question rather than invented (LASER-1). - -### The provenance boundary: slic, in-repo - -Cristallina is CORA's first deployment mined from `slic` rather than `eco`. The boundary is cleaner than Bernina's: where Bernina's `eco` config loaded its device list from a non-public JSON, Cristallina's `slic` repo keeps the device identities, axes, and PV prefixes as in-repo Python literals. What is non-public is only runtime state, not device definitions: the working directory and data paths, a PSSS motion helper script, the DilSc SECoP / Frappy magnet server (`dilsc.psi.ch:5000`, an alternative to the live EPICS driver), and the pulse-tube synchronization HTTP service (server-side). Those are recorded under `software_iocs_not_modeled` and ENV-1, not modelled. - -One provenance caution shapes the inventory: many `slic` drivers are instantiated but their PV channels are commented out of the active tuples (DM2, several SmarAct stages, the Attocube, the PuMa stack, the cameras). These are carried as present-hardware-not-acquired where carried at all (DISABLED-1), not as live Assets. - -### The architectural gap register (shared with the other XFELs) - -These are the same deferrals Alvra and Bernina recorded; Cristallina re-confirms them a third time at PSI, now in a vector-magnet diffraction context. - -- **One switched Aramis source feeding co-equal stations (TOPO-1).** Now the full triad: Cristallina is the third root Unit on the same source as Alvra and Bernina. Three co-equal Units sharing one upstream source has no home except the `Supply("PhotonBeam")` seam, and the routing state has no model. -- **Per-shot, pulse-ID-tagged event DAQ (DAQ-1).** The `sf-daq` records a free-running `bsread` stream of per-shot frames; CORA's poll-to-Done acquisition has no representation for it. The Run stays the provenance envelope and the per-shot plane is a referenced `Dataset`. -- **Beam-synchronous event timing (TIMING-1).** The CTA sequencer and EVR gate acquisition at beam rate (and here also mediate the pump-probe delay, in the absence of a laser device); `TimingController` carries the device but the trigger pattern has no typed home. - -### What is deliberately not here yet (modelling, as at the other exercises) - -- **New Capabilities / Methods and vendor Models.** Cristallina earns no catalog change; the diffraction and serial-crystallography recipes are carried pending on the [PSI Practices](../psi/index.md). No catalog Model is bound. -- **The pump-probe laser layer (LASER-1).** Absent from `slic`; not invented. -- **The vector-magnet field ranges and control handles (MAG-1).** The `Magnet` Family has graduated (Cristallina is a further consumer); only the per-Asset field detail stays pending. -- **The disabled stages (DISABLED-1).** DM2, the SmarAct / Attocube / PuMa stages, and the cameras are instantiated but commented out of the active config; carried as present-hardware, not live Assets. -- **The serial-crystallography sample delivery (SAMPLE-1).** Beyond the fast XY stage, the Cristallina-MX delivery is deferred. -- **The transmission-readback cross-reference (XREF-1).** The front-end attenuator's transmission readbacks alias to `SAROP31-OATT053`; carried `confirm`. -- **Integration scenarios.** No `test_cristallina_*.py` registers Cristallina Assets. Hard-registering a design-phase, off-roadmap, XFEL beamline would commit speculative structure. - -## Open questions - -*What CORA needs the PSI team (and PSI's documentation) to confirm before the model can be trusted.* - -Cristallina is modelled from PSI's open [`slic`](https://gitea.psi.ch/slic/cristallina) controls library (on `gitea.psi.ch`, branch `master`), treated as a dry, correct DATA source: the device list with PV prefixes comes from the in-repo `channels/pv_channels.py`, and the diffractometer and sample-environment topology from the `beamline/` and `crq_exp/` driver classes. That gives the device shape and the EPICS PV prefixes at high confidence. It does not give most motor units or limits, the Aramis source parameters, the PSS safety structure, or the Capability / Method binding. This page collects what `slic` cannot supply. It is a delete-on-answer queue: when an item is answered, the answer lands in the descriptor and the row is removed. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -Unlike Bernina, Cristallina's device facts are in-repo (not externalized), so this is a fuller cut; the residual questions concentrate on the XFEL acquisition paradigm, the novel sample environment, and a few `slic`-specific provenance cautions. - -### Scope, topology, and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SCOPE-1 | Nice-to-have | Is Cristallina (or any SwissFEL station) actually intended to enter CORA scope, or is this a generalization exercise against an open controls source? | A generalization exercise: Cristallina closes the Aramis triad and tests a `slic`-mined deployment and a vector-magnet sample environment; it is not on the pilot roadmap. | Whether PSI is a real Site or a modelling fixture. | -| TOPO-1 | Blocks-build | One linac and Aramis undulator line feed the Alvra, Bernina, and Cristallina stations, beam routed to one at a time. With three co-equal stations now modelled, should each be its own root Unit sharing an upstream source, and where does the shared switched source and its three-way routing state live? | One `Cristallina` root Unit owning its source for now; the shared, switched FEL source has no model and is carried as this question. The `Supply("PhotonBeam")` seam is the candidate home. | One-vs-many root Units and where the shared source and its routing state are modelled. | -| PSS-1 | Blocks-build | What are the SwissFEL PSS search-and-secure permit signals, and the interlock for the high-field magnet? | Both enclosures exist with permit signals to be named; `slic` does not carry them. | The Enclosure permit signals and the magnet-safety interlock. | -| ENC-1 | Blocks-build | Which enclosure does each device sit in? `slic` separates an optics hutch from an experimental hutch but does not encode the access-gated safety meaning. | The shared `SAROP31` optics hutch plus the Cristallina experiment hutch. | The per-device Enclosure assignment. | -| MAG-1 | Blocks-go-live | The DilSc vector superconducting magnet (to 5.2 T) and its liquid-helium cryogens are a personnel- and quench-safety hazard. How is the hazard gated, and what are the per-axis field ranges and control handles? | The magnet is a `Clearance` hazard (the ID32 precedent), and binds the graduated `Magnet` Family (a further consumer); the per-Asset field detail stays pending. | The magnet-hazard Clearance and the per-Asset magnet field / control detail. | - -### Source, optics, and attenuation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-build | What are the Aramis undulator gap tables and source size? `slic` carries the period (15 mm) and the K-to-energy constants but not the full source curve. | A SASE FEL undulator; per-shot photon energy (5-13 keV) is a DAQ datum, not a standing setpoint. | The `Undulator` source parameters. | -| MACHINE-1 | Nice-to-have | SwissFEL is a linac, not a storage ring. How should machine beam be modelled? | A `PhotonBeam` Supply, not a `StorageRing` device; the per-shot pulse energy is read via the gas monitor. | The linac machine-state modelling boundary. | -| ATT-1 | Blocks-go-live | The `aramis_attenuator` driver selects a foil combination for a requested transmission (energy-dependent). Should the deferred `Attenuable` + `SolverReference` leg graduate? | `Filter` for the discrete selection; the target-transmission solver is the deferred `Attenuable` leg. With Alvra, Bernina, and Cristallina all carrying it, the rule-of-three is well past its trigger. | Whether the transmission solver is built and where. | -| MONO-1 | Nice-to-have | The mono is a double-channel-cut (DCCM, `ODCC110`), distinct from Bernina's DCM. What are the crystal and axis details, and the pink-vs-mono mode boundary (the mono screen selects out / mono / pink)? | A `Monochromator` Asset, used in some modes; mode and crystal details are settings to supply. | The DCCM internals and the pink-vs-mono mode model. | -| XREF-1 | Nice-to-have | The front-end attenuator's transmission readbacks alias to `SAROP31-OATT053`. Is the front-end attenuator (`SARFE10-OATT053`) the same device read through the Cristallina-branch namespace, or two devices? | The `SARFE10-OATT053` front-end attenuator is the modelled device; the `SAROP31` alias is a readback, carried `confirm`. | Whether the attenuator readback alias is one device or two. | - -### Endstation: diffractometers and the sample environment - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DIFF-1 | Blocks-go-live | The DM1 (dilution-fridge) and DM2 (pulsed-magnet) platforms compose a goniometer, a 2-theta detector arm, and base / sample translations (DM2 adds swivels). Are they correctly modelled as the graduated `Diffractometer` Assembly, and is DM2 currently live? | Both reuse the `Diffractometer` Assembly (Bernina precedent), no new Family; DM2's PV channels are commented out in `slic`, so it is carried as present-hardware-not-acquired (DISABLED-1). | The Assembly composition and DM2's live status. | -| DIFF-2 | Nice-to-have | What is the `PartitionRule` shape for the reciprocal-space `PseudoAxis`? | The reciprocal-space `PseudoAxis` carries a partition rule like the synchrotron diffractometers'. | The reciprocal-space partition rule. | -| LASER-1 | Blocks-go-live | The `slic` source has no pump-probe laser (only the X-ray alignment laser `SAROP31-OLAS147`); pump-probe timing is mediated by the CTA sequencer and EVR. Does Cristallina have a pump-probe optical laser in another controls layer? | No pump-probe-laser Asset is modelled in this cut; the alignment laser is a catalog `Laser`. Whether a pump-probe laser exists elsewhere is carried as this question. | Whether a pump-probe laser exists and where it is controlled. | -| DISABLED-1 | Nice-to-have | Several `slic` drivers are instantiated but their PV channels are commented out of the active config (DM2, the SmarAct Juraj / mini stages, the Attocube, the PuMa stack, the cameras). Which are live hardware? | Carried as present-hardware-not-acquired; not modelled as live Assets in this cut. | Which disabled stages are current hardware. | -| ENV-1 | Nice-to-have | The DilSc magnet has an alternative SECoP / Frappy driver (`dilsc.psi.ch:5000`) and the pulsed-magnet uses a server-side pulse-tube synchronization service (`oscillations.psi.ch:8000`). Are these in the operational path? | The live EPICS magnet driver is modelled; the SECoP path and the sync service are server-side and not modelled. | The magnet control path and the pulse-tube sync. | - -### Acquisition, timing, diagnostics, and detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DAQ-1 | Blocks-build | The SwissFEL `sf-daq` records a free-running `bsread` stream of per-shot frames tagged by pulse-ID at beam rate, correlated downstream. CORA's acquisition is a single-detector poll-to-Done loop with no pulse-ID key. How does CORA represent a DAQ run? | The Run-as-provenance-envelope is kept; the per-shot data plane lives in the SwissFEL data API, and CORA references a `Dataset`. A per-shot event-stream actuation axis is the gap, sketched in the design note, not built. Cristallina is the third PSI sighting. | Whether CORA gains an event-stream acquisition axis. | -| TIMING-1 | Blocks-go-live | The CTA sequencer (`SAR-CCTA-ESC`) and EVR gate acquisition at beam rate and mediate the pump-probe delay. CORA's `TimingController` carries the device but has no typed home for an event trigger pattern. Where does the pattern parameter live? | `TimingController` for the device; the trigger pattern is carried as opaque setpoints until a typed parameter shape is earned. | The event-system trigger-pattern parameter model. | -| DIAG-1 | Blocks-go-live | How are the intensity-position monitors (PBPS), the gas monitor (PBPG), and the photon single-shot spectrometer (PSSS) modelled? They present the Sensor Role. | The loose `FluxMonitor` and `Diagnostic` Sensor families reused from Alvra / Bernina / I22; per-shot intensity normalization is a DAQ-plane concern (DAQ-1). | The diagnostics modelling boundary. | -| DET-1 | Blocks-go-live | What are the Cristallina detectors per configuration? `slic` binds a 1.5M Jungfrau (`JF16T03V02`) + a 0.5M I0 (`JF20T01V01`) for Q and an 8M (`JF17T16V01`) for MX; the human-readable labels come from a commented `sf_daq_broker` block. Which is in use, and its geometry? | The detectors reuse `Camera`; per-shot frames flow through the `sf-daq` data plane (DAQ-1); the active config and geometry are to supply. | The detector models, the per-config wiring, and the labels. | -| SAMPLE-1 | Nice-to-have | What is the Cristallina-MX sample-delivery shape beyond the fast XY stage, and the `Subject` custody lifecycle? | Sample delivery beyond the fast stage is endstation-specific and deferred; no Family is coined. | The sample-delivery model and the `Subject` custody thread. | -| PULSE-1 | Nice-to-have | The X-ray pulse picker is a fast single-pulse selector folded into `Shutter`. Is a rotary pulse-picking chopper a distinct Family? | `Shutter` Role; the Shutter-vs-Chopper distinction is carried as this question, the same one Alvra and Bernina raised. | Whether the pulse picker earns its own Family. | diff --git a/docs/deployments/csx/notes.md b/docs/deployments/csx/notes.md deleted file mode 100644 index 6a08d98887d..00000000000 --- a/docs/deployments/csx/notes.md +++ /dev/null @@ -1,120 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of CSX 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. CSX's scattering legs reuse Methods already in the catalog's pending set, so they render unlinked and are carried pending until a technique enters scope (`TECH-1`). - -### Resonant soft X-ray scattering - -CSX tunes the soft X-ray energy to an absorption edge and measures the scattered intensity through the TARDIS diffractometer, resolving electronic and magnetic order in reciprocal space. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Resonant soft X-ray scattering | `resonant_scattering` | RSXS on the TARDIS E6C; reuses the 4-ID `resonant_scattering` Method, in a soft X-ray regime (a Plan / settings difference) | -| Soft X-ray diffraction | `diffraction` | coherent soft X-ray diffraction through the TARDIS circles; reuses the 4-ID / 8-ID `diffraction` Method | - -Both need the [grating monochromator](source.md) (the incident energy), the [TARDIS diffractometer](sample.md), and the [coherent detectors](detector.md). The arm and sample circles select the momentum transfer. - -### Coherence and holography - -CSX's defining quality is beam coherence: the FastCCD records coherent-scattering and holography patterns. This is carried as a beam-quality enabler and as settings on the scattering Methods above, not coined as its own Method; whether coherent soft X-ray scattering becomes a distinct catalog Method is an owner-scope decision (`TECH-1`). - -### Not modelled yet - -The concrete acquisition recipes (energy maps, reciprocal-space scans, coherent / holography exposures) are not written yet; they join as the deployment approaches the point where CORA drives CSX. See [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at CSX, and the trust shape that will gate it. First cut.* - -Governance at CSX 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). - -CSX 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`). - -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. CSX carries the soft X-ray hazard classes (ultra-high vacuum and the cryostat's cryogens at the in-vacuum endstation) 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 CSX, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's CSX content lives, the `GratingMonochromator` graduation this deployment earns, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at CSX | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (the TARDIS hkl `PseudoAxis`) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What this deployment graduates - -CSX is the **consolidation** deployment for soft X-ray. SIX (NSLS-II 2-ID) introduced `GratingMonochromator` as a loose family at n=1; CSX's VLS-PGM (`XF:23ID1-OP{Mono`, 200-2200 eV) is the **second** independent soft X-ray plane-grating monochromator, which earns the rule-of-three. So `GratingMonochromator` **graduates into the catalog** with this deployment: it becomes a catalog Family that both SIX and CSX bind, with the grating line density and energy range carried as a per-Asset settings difference (the `InsertionDevice` / `Monochromator` precedent), not a Family split. The SIX deployment's references are swept from loose to graduated in the same change. The catalog `Monochromator` (a crystal / multilayer Bragg optic) is deliberately not stretched to cover the grating mono; they are distinct optics. Its naming-r3 review is done. - -CSX also **reinforces** an existing abstraction rather than adding one: its TARDIS endstation is an in-vacuum hkl E6C diffractometer whose circles bind the catalog `Goniometer` Family and the composed `Assembly(Diffractometer)`, a third hkl diffractometer after 4-ID and 8-ID (and the first in a soft X-ray, in-vacuum context). No new family is introduced. - -### Deliberately not here yet - -- **The fine piezo nanopositioner.** CSX carries a piezo nanopositioner for sample / lens fine-positioning; it is deferred (it would fold to `Hexapod` or stay a loose nanopositioner family, an owner call at the point it is modelled). - -- **The reciprocal-space solver.** The TARDIS hkl pseudo-axis is modelled as a `PseudoAxis` device; the inverse-kinematics partition rule is `DIFF-2`, deferred (as on 4-ID / 8-ID). - -- **The coherent / holography Method.** CSX's defining coherence (the FastCCD coherent-scattering and holography) is carried as a beam-quality enabler and settings on the existing scattering Methods, not coined as its own Method; whether coherent soft X-ray scattering enters the catalog is an owner decision (`TECH-1`). - -- **The simulated devices and full asset-tree scenarios.** No `test_csx_*.py` registers the CSX 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). - -## Open questions - -*What CORA needs the CSX team to confirm before the model can be trusted.* - -CSX was reverse-engineered from the beamline's own bluesky profile collection ([NSLS2/csx-profile-collection](https://github.com/NSLS2/csx-profile-collection)), so the control handles on the [device pages](index.md) are the beamline's real PVs, read from the `startup/csx1` files rather than confirmed by staff. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet), including the `GratingMonochromator` graduation). 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 | -| --- | --- | --- | --- | --- | -| TOPO-1 | Blocks-build | The 23-ID canted straight: do the two EPUs feed CSX (23-ID-1) plus a sibling branch, and is CSX one root Unit? | One root Unit `CSX` fed by the canted twin-EPU straight (the 32-ID precedent). | The source topology in the [descriptor](index.md). | -| ENC-1 | Blocks-go-live | Are the PV zones `XF:23IDA` / `XF:23ID1-OP` / `XF:23ID1-ES` separate shielded hutches or beam zones within fewer? | Two enclosures (front-end optics + the 23-ID-1 branch). | The Enclosure grouping. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the EPICS PV handles read from the csx-profile-collection current and correct? | The handles in the descriptor are taken from the profile collection 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 front-end shutter is `XF:23ID1-PPS{Sh:FE}`. | The Enclosure permit signals. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-go-live | The two EPUs (`EPU:1`, `EPU:2`): type, period, and the polarization (phase) model. | Two `InsertionDevice` Assets; the phase axis carried as a setting. | The insertion-device specs. | -| MONO-1 | Blocks-go-live | The VLS-PGM: the grating line densities, the c-value model, and the 200-2200 eV range. | A `GratingMonochromator` Asset (catalog Family) with energy / mirror-pitch / mirror-x / grating-pitch / grating-x axes. | The monochromator model. | -| OPT-1 | Nice-to-have | The mirrors (M1A front-end hexapod, M3A refocusing): coatings and axis roles. | `Mirror` Assets with the config's PV roots; coatings unconfirmed. | The mirror specs. | -| OPT-2 | Nice-to-have | The branch slits (`Slt:1` / `Slt:2` gap-center, `Slt:3` x/y): the internal axis maps. | `Slit` Assets with base PVs; per-blade axes partial. | The slit axis maps. | - -### TARDIS endstation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DIFF-1 | Blocks-build | The TARDIS E6C geometry: confirm the circle roles (theta, delta, gamma, mu) and which is sample versus detector. | A 6-circle hkl E6C diffractometer binding the `Goniometer` Family + the `Assembly(Diffractometer)`. | The circle geometry and the Assembly binding. | -| DIFF-2 | Blocks-go-live | The reciprocal-space coordination: the hkl E6C inverse-kinematics over this geometry. | A `PseudoAxis` Asset for the reciprocal-space layer. | The pseudo-axis model. | -| SAMPLE-1 | Nice-to-have | The sample stage, the holography stage, and the cryostat: the axes, the cryo range, and the fine nanopositioner. | A `LinearStage` (sx / say / saz + holography) and a `TemperatureController`. | The sample-environment model. | - -### Detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The coherent detectors (FastCCD, AXIS), the scaler / MCS, and the diode: models, sensors, and channels. | `Camera` Assets, a `FluxMonitor` scaler, and a `GenericProbe` diode. | The detector models and channel map. | - -### Supplies - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SUP-1 | Nice-to-have | The vacuum and cryogen supplies the UHV optics, the in-vacuum TARDIS, and the cryostat draw on. | Photon beam, cooling water, and vacuum carried in the descriptor. | The Supply records. | diff --git a/docs/deployments/esm/notes.md b/docs/deployments/esm/notes.md deleted file mode 100644 index 7b4f4c21822..00000000000 --- a/docs/deployments/esm/notes.md +++ /dev/null @@ -1,105 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of ESM 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. ESM's technique is angle-resolved photoemission, a photoemission method new to CORA's catalog, so the Method below renders unlinked and is carried pending until a technique enters scope (`TECH-1`). - -### Angle-resolved photoemission - -ARPES illuminates the sample with monochromatic soft X-rays and measures the kinetic energy and emission angle of the photoelectrons, mapping the electronic band structure. The measurement is the electron distribution recorded by the hemispherical analyzer over a pass-energy and lens-mode window, at a sample orientation set by the cryostat manipulator. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Angle-resolved photoemission | `angle_resolved_photoemission` | electron energy / angle spectra on the Scienta SES analyzer, at low temperature on the UHV manipulator; Method not yet in catalog | - -It needs the [grating monochromator](source.md) (the incident energy), the [UHV cryostat manipulator](sample.md), and the [electron analyzer](detector.md). Polarization is set by the dual EPUs. - -### Not modelled yet - -The XPEEM/LEEM photoemission-microscopy branch is deferred (a future `ElectronMicroscope` Family; see [Model](#deliberately-not-here-yet)). The concrete acquisition recipes (Fermi-surface maps, energy-distribution curves, the analyzer sweep settings) are not written yet; they join as the deployment approaches the point where CORA drives ESM. See [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at ESM, and the trust shape that will gate it. First cut.* - -Governance at ESM 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). - -ESM 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`). - -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. ESM carries the soft X-ray hazard classes (ultra-high vacuum and the cryostat's cryogens at the ARPES endstation) 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 ESM, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's ESM content lives, the `Manipulator` graduation and `ElectronAnalyzer` this deployment introduces, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at ESM | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What this deployment graduates - -ESM both earns a new abstraction and consolidates two existing ones. - -- **`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. - -### Deliberately not here yet - -- **The XPEEM/LEEM branch (`21-ID-2`).** ESM's second endstation is a low-energy electron microscope (LEEM) / photoemission electron microscope (PEEM), an electron-optics imaging instrument distinct from the analyzer. It is deferred to a follow-on as a future loose `ElectronMicroscope` Family (`PEEM-1`); this cut models the ARPES branch (the 32-ID / SRX "one endstation first" precedent). - -- **The sample-prep and load-lock transfer.** The sample-prep and analysis-chamber manipulators and the load-lock sample-transfer claw are present in the config but deferred; this cut models the main LT sample manipulator (`SAMPLE-1`). - -- **The ARPES Method.** Whether angle-resolved photoemission enters CORA's catalog is an owner decision; the Practice renders unlinked, pending (`TECH-1`). - -- **The simulated devices and full asset-tree scenarios.** No `test_esm_*.py` registers the ESM 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). - -## Open questions - -*What CORA needs the ESM team to confirm before the model can be trusted.* - -ESM was reverse-engineered from the beamline's own bluesky profile collection ([NSLS2/esm-arpes-profile-collection](https://github.com/NSLS2/esm-arpes-profile-collection)), so the control handles on the [device pages](index.md) are the beamline's real PVs, read from the `startup/*.py` files rather than confirmed by staff. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet), including the `Manipulator` graduation and the deferred XPEEM branch). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Source and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-go-live | The two EPUs (EPU57 on G1A, EPU105 on G1B): periods, the polarization (phase) model, and how the pair is coordinated. | Two `InsertionDevice` Assets; the phase axis carried as a setting. | The insertion-device specs. | -| ENC-1 | Blocks-go-live | Are the PV zones `XF:21IDA/B/C/D` separate shielded hutches or beam zones within fewer? | Four enclosures, one per zone. | The Enclosure grouping. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit signals for the hutches. | Permit leaves to be named; shutters are `XF:21ID-PPS{Sh:FE}` / `XF:21IDA-PPS{PSh}` / `XF:21IDC-PPS{PSh:1A/1B}`. | The Enclosure permit signals. | -| CTRL-1 | Blocks-go-live | Are the EPICS PV handles read from the esm-arpes-profile-collection current and correct? | The handles in the descriptor are taken from the profile collection and carried confirm. | Verifying each Asset's control handle. | - -### Optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MONO-1 | Blocks-go-live | The PGM: the grating line densities, the c-value model, and the energy range. | A `GratingMonochromator` Asset (catalog Family) with energy / focus-const / grating-pitch / mirror-pitch / grating-translation axes. | The monochromator model. | -| OPT-1 | Nice-to-have | The mirrors (M1, M3 hexapod, M4A KB pair, M4B hexapod): coatings and axis roles. | `Mirror` Assets with the config's PV roots; coatings unconfirmed. | The mirror specs. | -| OPT-2 | Nice-to-have | The PGM slits, the M3 slit, and the A/B exit slits: the internal axis maps. | `Slit` Assets with base PVs; per-blade axes partial. | The slit axis maps. | -| DIAG-1 | Nice-to-have | The ESM Diagon (`XF:21IDA-OP{Diag:1`): is it a polarization diagnostic, and what does it report? | One `GenericProbe` Asset (placeholder classification). | The diagnostic classification. | - -### ARPES endstation - -| 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. | 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. | - -### Supplies - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SUP-1 | Nice-to-have | The vacuum and cryogen supplies the UHV optics, the analyzer, and the cryostat draw on. | Photon beam, cooling water, and vacuum carried in the descriptor. | The Supply records. | diff --git a/docs/deployments/faxtor/notes.md b/docs/deployments/faxtor/notes.md deleted file mode 100644 index 16c63d7f5ec..00000000000 --- a/docs/deployments/faxtor/notes.md +++ /dev/null @@ -1,126 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of FAXTOR is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../alba/index.md#the-techniques-adapted-here) is how a facility adapts it. FAXTOR is a fast-imaging beamline: its tomography techniques reuse Methods CORA's catalog already carries, and its radiography is carried pending until it enters scope (`TECH-1`). - -### Fast tomography and radiography - -FAXTOR sets the X-ray energy with the multipole wiggler and the double multilayer monochromator (8-50 keV mono) or the filter set (30-70 keV filtered white beam), then rotates the sample on the experiment endstation while the scintillator and fast camera record projections. Continuous-rotation acquisition reaches up to 20 Hz, at 0.5-10 um pixel size, with absorption, propagation-phase, and grating-based contrast. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Tomography | [`tomography`](../../catalog/methods.md) | absorption and propagation-phase micro-CT on the [experiment endstation](sample.md), the [rotary stage](sample.md) stepped against the [scintillator + camera](detector.md); reuses the catalog tomography Method (the 2-BM pilot) | -| Continuous-rotation tomography | [`continuous_rotation_tomography`](../../catalog/methods.md) | fast fly-scan tomography up to 20 Hz, the [rotary stage](sample.md) in continuous rotation as the trigger master (`TRIG-1`); reuses the catalog continuous-rotation Method | -| Radiography | `radiography` | time-resolved single-projection radiography; reuses the 7-BM `radiography` slug, no portable Method in the catalog yet; pending (`TECH-1`) | - -Tomography needs the [incident energy](source.md) set by the [monochromator or filters](source.md), the [rotary stage and sample positioning](sample.md), and the [scintillator + fast camera](detector.md). Radiography needs the same beam and detector without the rotation sweep. - -### A new Site on familiar vocabulary - -FAXTOR is the fleet's fast-imaging beamline at ALBA, and it ties into the tomography lineage CORA already models: the same imaging device anatomy as the 2-BM pilot and the MAX IV TomoWISE design (a wiggler or undulator source, a multilayer monochromator, a rotary-stage endstation, and an indirect scintillator + camera detector). It reuses the `tomography` and `continuous_rotation_tomography` Methods directly; only radiography is carried pending, and none forces a new device family. - -### Not modelled yet - -The concrete acquisition recipes (the fly-scan tomography sequences and their counting times, the flat / dark sequencing, the phase-contrast and grating-based setups) are not written yet; they join as the deployment approaches the point where CORA drives FAXTOR. Whether radiography enters CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at FAXTOR, and the trust shape that will gate it. First cut.* - -Governance at FAXTOR follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [ALBA Site](../alba/index.md#safety-and-governance), 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). - -FAXTOR is CORA's first ALBA deployment, so ALBA is a brand-new Site: the operator pool and the safety-review structure are carried pending on the [ALBA Site](../alba/index.md#safety-and-governance), shared across the facility's beamlines, until ALBA staff confirm them (`GOV-1`). FAXTOR is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives FAXTOR, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. ALBA publishes no per-beamline personnel-safety permit signals or photon / front-end shutters, so the Enclosure permit leaves and the interlock structure are carried pending and are not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [ALBA Site](../alba/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives FAXTOR, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's FAXTOR content lives, the new ALBA Site and Tango / Sardana control house-style it introduces, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at FAXTOR | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes FAXTOR new - -FAXTOR is two things at the Site level and nothing new at the vocabulary level. It is CORA's **ninth Site** (ALBA, Barcelona), a re-test of the Site and Federation kernel, and the **second Tango / Sardana / Taurus** control plane CORA models. ALBA is the originating institution of Sardana (and of the Taurus GUI framework and the IcePAP motion controller), so this is the controls house-style's home facility; MAX IV (TomoWISE) was the first consumer CORA modelled. Its science is fast X-ray tomography and radiography on a multipole-wiggler source. - -### No new families (the imaging spine reuses the 2-BM / TomoWISE precedent) - -FAXTOR coins no new Family. The multipole wiggler binds the catalog `InsertionDevice`; the double multilayer monochromator binds `Monochromator`; the filters bind `Filter` and the slits bind `Slit`; the focusing mirrors bind `Mirror` (deferred, `OPT-1`); the experiment endstation binds `Table`, `RotaryStage`, `LinearStage`, and `Shutter`; the detector binds `Scintillator` and `Camera`; the machine state binds the loose `StorageRing`. Nothing in the catalog changes. - -### The Tango / Sardana control plane - -FAXTOR is the second Tango / Sardana / Taurus controls house-style in the fleet, after MAX IV TomoWISE. Device IO is a layer of Tango device servers (motors over IcePAP-class controllers, detectors via the Lima framework); Sardana provides the experiment-orchestration layer (a Pool of controllers / motors / measurement groups, plus a MacroServer running scan macros), and Taurus is the operator UI. ALBA publishes no per-beamline device manifest, so CORA does not bind the Tango / Sardana / IcePAP handles here; when bound they would be modelled as opaque edge strings over the `ControlPort`, the way the MX3 and ID32 heterogeneous-control precedents do (`CTRL-1`). The fast continuous-rotation tomography acquisition runs through Sardana macros; that orchestration is the seam CORA's edge replaces, conducting over Tango / IcePAP rather than replacing Sardana. The Lima detector file-writing to the ALBA data store is plumbing CORA observes, not data it owns. - -### Deliberately not here yet - -- **The control handles (`CTRL-1`).** No public per-beamline Tango / Sardana / IcePAP manifest exists; the handles are carried pending, not invented. -- **The detector model (`DET-1`).** The fast camera and scintillator are bound to `Camera` and `Scintillator` but their models are unpublished, carried fully pending. -- **The exact optics detail (`MONO-1`, `FILT-1`, `OPT-1`, `OPT-2`).** The DMM coating and energy partition, the filter set, the mirrors, and the slit blade map are carried confirm-pending. -- **The endstation stage stack (`SAMPLE-1`, `TRIG-1`).** The rotary, positioning, table, and shutter are named; their axis sets, models, and the trigger scheme are pending. -- **Radiography as a Method (`TECH-1`).** Whether it enters CORA's catalog is an owner decision; the Practice renders unlinked, pending, reusing the 7-BM `radiography` slug. Fast tomography reuses the catalog Methods directly. -- **The simulated devices and full asset-tree scenarios.** No `test_faxtor_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the FAXTOR team to confirm before the model can be trusted.* - -FAXTOR was reverse-engineered from ALBA's public facility pages ([cells.es/en/beamlines/bl31-faxtor](https://www.cells.es/en/beamlines/bl31-faxtor)) and a verified research brief, not from a live connection. ALBA publishes no per-beamline device manifest, so the [device pages](index.md) carry a planned shape with control handles unbound. This is CORA's first ALBA Site and its second Tango / Sardana / Taurus controls house-style after MAX IV. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: a shared optics hutch feeding one experiment hutch, or a different layout? | A `faxtor-optics` zone and a `faxtor-experiment` hutch. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The multipole-wiggler period, pole count, and field. | A multipole-wiggler source; period and field pending. | The source Asset detail. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MACHINE-1 | Nice-to-have | The ALBA storage-ring state FAXTOR reads. | Observe-only machine state, a loose `StorageRing`; exact handles pending. | The machine-state observation. | -| MONO-1 | Blocks-go-live | The double multilayer monochromator coating, d-spacing, and the monochromatic / filtered-white energy partition. | A DMM bound to `Monochromator`; 8-50 keV mono, 30-70 keV filtered white. | The monochromator and energy modelling. | -| FILT-1 | Nice-to-have | The filtered-white-beam filter materials and thicknesses. | A filter set bound to `Filter`. | The filter Asset detail. | -| OPT-1 | Nice-to-have | The focusing / harmonic-rejection mirrors (presence, coatings, handles). | Mirrors bound to `Mirror`; absent from public sources, deferred. | The mirror Asset detail. | -| OPT-2 | Nice-to-have | The beam-defining slit blade-axis map and handles. | Slits bound to `Slit`. | The slit Asset detail. | - -### Sample endstation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SAMPLE-1 | Blocks-go-live | The experiment-endstation stage stack: the rotary, the sample positioning, the table degrees of freedom, and the fast shutter. | A `RotaryStage`, `LinearStage`, `Table`, and `Shutter`; axis sets and models pending. | The sample-stage modelling. | -| TRIG-1 | Nice-to-have | The triggering / synchronization scheme for continuous-rotation tomography. | The rotary stage is the master clock feeding the camera trigger. | The trigger wiring. | - -### The detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The fast imaging detector: the camera sensor, frame rate, and model, and the scintillator material and thickness. | A `Scintillator` plus a `Camera` supporting up to 20 Hz tomography; model not published, carried pending. | The detector modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | The Tango / Sardana / IcePAP device handles per FAXTOR device (absent from any public manifest). | The handles are unbound, carried pending; the control plane is ALBA Tango / Sardana. | Binding each Asset's control handle. | -| PSS-1 | Blocks-go-live | The ALBA personnel-safety permit signals and the photon / front-end shutters (not published per beamline). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent and the cooling-water / beam supplies. | Photon beam, cooling water, and vacuum. | The Supply observations. | -| GOV-1 | Nice-to-have | The ALBA operator pool and safety-review structure (site-level). | Carried pending on the ALBA Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Does radiography enter CORA's catalog as a Capability / Method? | Deferred: carried as a pending Practice reusing the 7-BM `radiography` slug; fast tomography reuses the catalog tomography Methods. | The technique Capabilities. | diff --git a/docs/deployments/fmx/notes.md b/docs/deployments/fmx/notes.md deleted file mode 100644 index dddc33f5b6d..00000000000 --- a/docs/deployments/fmx/notes.md +++ /dev/null @@ -1,110 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at FMX: macromolecular crystallography, each a [Catalog](../../catalog/methods.md) Method. FMX is CORA's second MX beamline (after Diamond i03) and follows the same Method-deferral discipline.* - -FMX's science is protein crystallography: rotate a cryo-cooled crystal in a focused microbeam and read the diffraction on the Eiger, locate crystals with fast grid scans, and exchange samples with a robot. These are the MX Methods i03 brought to CORA; FMX is their second consumer. The Methods below render unlinked and stay pending until the owner-scope decision (TECH-1) brings them into the catalog. - -| Technique | Beam | Detector | Status in CORA | -| --- | --- | --- | --- | -| Rotation (oscillation) data collection | monochromatic, microfocused | `AreaDetector` (Eiger, Detector Role) | the i03 `mx_data_collection` Method binding Goniometer + Eiger + vector + Zebra, pending; 2nd consumer (TECH-1) | -| Grid scan / sample location | monochromatic, microfocused | `AreaDetector` + `SampleCamera` | the i03 `grid_scan` Method over the Zebra-triggered goniometer raster, pending; 2nd consumer (TECH-1) | -| Autonomous sample exchange | n/a | n/a | the i03 `sample_exchange` Method: a Procedure over the spine + a Subject custody thread, pending; 2nd consumer (ROBOT-1) | -| Anomalous element ID (fluorescence) | monochromatic, energy-swept | `FluorescenceDetector` (Mercury, Sensor) | the edge scan picks the energy for SAD / MAD; reuses the energy axis (DET-1) | -| Fixed-target serial (chip) | monochromatic, microfocused | `AreaDetector` | the chip-scanner raster; reuses the `serial_crystallography` Method (i24 / LCLS-MFX), deferred (SERIAL-1) | - -### Why the Methods stay pending - -FMX reuses the three MX Methods Diamond i03 left pending. Unlike a loose device *Family* (which a second sighting promotes on a mechanical rule-of-three, as ISS did for the emission spectrometer), a pending *Method* has no automatic promotion: it is coined by deliberate decision when a conduct-path needs it, the same discipline that keeps `energy_scan` deferred even across several consumers. FMX makes each of `mx_data_collection`, `grid_scan`, and `sample_exchange` a two-consumer Method (i03 + FMX), which strengthens the eventual case to coin them but does not force it in a descriptor scaffold (TECH-1). The device Roles already exist (the graduated `Goniometer` presents Positioner, the Eiger presents Detector), so what is pending is the recipe, not a device shape. - -The autonomous sample-exchange loop is the genuinely non-obvious modelling: the unattended sequence (load pin, centre, collect, unmount, next) is a Procedure over the spine, threaded through the `Subject` custody lifecycle (Received to mounted to measured to Returned) and gated by a Clearance issued after a safety review. The robot itself is just a Positioner Asset; the workflow is the modelling (ROBOT-1). The per-experiment recipes (oscillation ranges, exposure, grid parameters, the exchange sequence) are calibration the deployment must supply. - -## Governance - -*Who may act at FMX and the trust shape CORA applies. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority.* - -People and agents are facility principals at the [NSLS-II Site](../nsls2/index.md#safety-and-governance); on the beamline they surface through the actions they take. The human roster is not known from the profile collection (GOV-1), so the principals are the design shape, not a registered list. - -### Who acts - -CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the NSLS-II Site. An FMX beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. - -### The trust boundary - -CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may set the energy, move the goniometer, start a rotation data collection or a grid scan, drive the robot, override a caution, or commit a beam-centre calibration. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer (the LSDC Governor). The NSLS-II proposal and cycle are a fact CORA's Campaign uses for custody. - -### The autonomous loop under custody - -FMX's defining governance wrinkle is the unattended robot sample-exchange loop. CORA's Campaign, Trust, and Subject shapes are where that resolves: the robot loading a crystal is a command the trust boundary gates, and the crystal is a `Subject` whose custody (Received to mounted-on-goniometer to measured to Returned / Stored) is the record of record. The autonomous loop is gated by a `Clearance` issued after a safety review, exactly the i03 pattern. An autonomous Agent driving the load-centre-collect-unmount cycle would be a facility principal scoped at the Site, governed by the same trust boundary, with each choice recorded as a [Decision](../../architecture/modules/decision/index.md). None is declared yet; the autonomous-loop lifecycle is deferred (ROBOT-1). - -## Model - -*The developer's by-kind index: where each CORA aggregate's FMX content lives. It hosts no content of its own. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC -[modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at FMX | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (EnergyAxis) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [The beamline](index.md#enclosures) (17-ID-A optics, 17-ID-C experiment) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Subject (the crystal custody thread) | [Governance](#the-autonomous-loop-under-custody) (deferred, ROBOT-1) | -| Procedure, Recipe, Caution, Supply, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What this deployment graduates: nothing (and that is the finding) - -FMX is a clean **pure-reuse** deployment. As CORA's second MX beamline (after i03), its finding is that the MX vocabulary i03 earned generalizes to a second, independent facility with no new modelling: the graduated `Goniometer` (the single-omega micro-goniometer), the `Camera` (the Eiger), the graduated `Transfocator` (the CRL), the `Monochromator`, the `Mirror` (HFM + KB), the `Filter` (the BCU / RI attenuators), the `BeamStop`, the `FluxMonitor`, the catalog `Backlight` (graduated across the MX / imaging fleet), and the graduated catalog `PositionMonitor` (presenting `Sensor`, distinct from `FluxMonitor` by measuring beam position rather than flux) all bind unchanged. The robot is one Positioner-presenting Asset, not a new Family (the i03 / 19-BM precedent). The one small modelling step beyond i03 is binding the Mercury fluorescence detector to the catalog `EnergyDispersiveSpectrometer` (i03 deferred its fluorescence detector); no new Family is coined. - -### Deliberately not here yet - -This is a design-phase scaffold (descriptor + docs), mirroring i03 and the other NSLS-II beamlines. Left out on purpose: - -- **No catalog change.** FMX graduates nothing and coins nothing. The three MX Methods (`mx_data_collection`, `grid_scan`, `sample_exchange`) stay pending: FMX is their second consumer (after i03), which strengthens but does not force coining (Methods have no mechanical promotion, the `energy_scan` deferral discipline; TECH-1). The `Backlight` (i03 + i24 + FMX) has graduated to the catalog across the MX / imaging fleet (DET-1). -- **The robot is not a Family.** The sample-changing robot is one Positioner-presenting Asset, gated by a Clearance, loading a `Subject`, vendor in a bound Model; not a new SampleChanger Family (the i03 / 19-BM precedent, adversarially verified there; ROBOT-1). -- **The autonomous loop and the Subject custody thread.** The unattended exchange loop is a Procedure over the spine threaded through the `Subject` aggregate; it is the genuinely non-obvious MX modelling, deferred with i03 (ROBOT-1). -- **Sample cryo-cooling.** The cold-gas cryostream is not exposed in the profile collection (an annealer / thaw-air actuator is), so it is deferred (CRYO-1); it would bind `TemperatureController` (the i03 cryostream precedent) when its PV is supplied. -- **The fixed-target serial mode.** The chip-scanner serial-crystallography raster is named but not modelled; it would reuse the `serial_crystallography` Method (i24 / LCLS-MFX), deferred (SERIAL-1). -- **Operations and experiment views, integration scenarios, vendor Models.** A runbook and registered Assets for a beamline CORA does not yet drive would be invention; they land when the design firms and the team confirms. - -## Open questions - -*What CORA needs the FMX team to confirm. This model is reverse-engineered from public open source (the `NSLS2/fmx-profile-collection` bluesky / ophyd startup files; the MX acquisition logic lives in the `lsdc` / `mxtools` libraries): the EPICS PVs are read from the `startup/*.py` device classes, but the goniometer / robot / detector vendor identities, the crystal cut, and physical positions are not. Each row is a fact the beamline team owns. It is a delete-on-answer queue.* - -Priorities: `Blocks-build`, `Blocks-go-live`, `Nice-to-have`. - -### Source and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Nice-to-have | The IVU21 undulator period, gap range, and gap-to-energy curve. The device (`SR:C17-ID:G1{IVU21:2}`) is in source; the parameters are not. | An in-vacuum undulator on the 3 GeV ring, identity-only. | The InsertionDevice settings. | -| TOPO-1 | Nice-to-have | FMX (17-ID-2) shares the IVU21 undulator and the 17-ID straight with AMX (17-ID-1). Is the straight canted (two beams), and is one root Unit per branch the right model? | One root Unit feeding the 17-ID-2 branch (the CSX / 32-ID canted precedent); AMX is the sibling branch. | The sector topology and the AMX relationship. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit-leaf PVs. Only the shutters (`XF:17ID-PPS:FAMX{Sh:FE}`, `XF:17IDA-PPS:FMX{PSh}`) are in source. | The permit signal is a confirm note, not a guessed PV. | The Enclosure permit signals. | - -### Optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DCM-1 | Nice-to-have | The HDCM crystal cut, d-spacing, and energy range. The monochromator (`Mono:DCM`) and its axes are in source. | One Monochromator Asset, crystal settings blank. | The Monochromator settings. | -| KB-1 | Nice-to-have | The HFM and KB mirror coatings, the bimorph calibration, and the CRL transfocator lens count and focal configuration. The mirrors (`Mir:HFM`, `Mir:KBH/KBV`) and the CRL (`CRL:`) are in source. | The mirror / CRL internals are per-Asset settings on the existing Mirror / Transfocator Families. | The focusing-optic settings. | - -### Sample and detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| GONIO-1 | Blocks-go-live | The goniometer axis decomposition (single omega + GX / GY / GZ centring + PY / PZ pin + PI fine) and the centre-of-rotation calibration. The stack (`Gon:1`) is in source. | A `Goniometer` Asset (catalog Family, graduated on the i03 Smargon); per-axis decomposition to confirm. | The goniometer model. | -| ROBOT-1 | Blocks-go-live | The sample-changing robot model, the dewar / puck layout, the exchange workflow, and the Subject custody lifecycle. The Governor state machine (`Gov:Robot`) and the dewar interlock (`DewarSwitch`) are in source. | One Positioner-presenting `Robot` Asset (not a new Family); the autonomous loop is a Procedure + a Subject custody thread, gated by a Clearance. | The robot model and the autonomous-loop modelling. | -| DET-1 | Blocks-go-live | The Eiger model and beam centre, and the Mercury fluorescence detector element count and ROI map. The Eiger (`Det:Eig16M`) and the Mercury (`Det:Mer`) are in source. | An Eiger 16M (`Camera`) and a Mercury (`EnergyDispersiveSpectrometer`); model / ROIs to confirm. | The detector roster. | -| DIAG-1 | Nice-to-have | The beam-position channel map (the Prosilica BPM cameras, the sector XBPM); the `PositionMonitor` Family is graduated (catalog, presenting `Sensor`), only the per-Asset channel map stays pending. | Read-only beam-position (graduated catalog `PositionMonitor`) probes; channel map blank. | The PositionMonitor bindings. | -| CRYO-1 | Nice-to-have | The sample cryo-cooling (cold-gas cryostream) and the annealer / thaw-air actuator. The annealer (`Wago:`) is in source; the cryostream IOC is not. | Sample cooling deferred; the annealer named, the cryostream a `TemperatureController` when its PV is supplied. | The sample-environment Assets. | - -### Controls and technique scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DRIVE-1 | Blocks-go-live | The motion-controller box models, firmware, and IPs (the PowerBrick / PPMAC vector controller `Gon:1-Vec` / `MC17:Sender`, the Zebra `Zeb:3`, and the EPICS motor records). | Families bound (MotionController, TimingController), specifics blank. | The MotionController Models. | -| TECH-1 | Blocks-go-live | Do the MX Methods (rotation `mx_data_collection`, `grid_scan`, `sample_exchange`) enter CORA's catalog, or stay pending? FMX is the second consumer after i03. | The three Methods reused pending (no mechanical promotion for Methods; the energy_scan deferral discipline); no new Method coined. | The MX Method scope. | -| SERIAL-1 | Nice-to-have | The fixed-target chip-scanner serial-crystallography mode (the Oxford chip raster, a PPMAC on-the-fly motion). Is it modelled, and does it reuse the `serial_crystallography` Method (i24 / LCLS-MFX)? | Deferred; FMX's primary mode is rotation MX, the chip-scanner mode is named here. | The serial-mode Assets and Method. | diff --git a/docs/deployments/fxi/notes.md b/docs/deployments/fxi/notes.md deleted file mode 100644 index 0b83ce3d9e1..00000000000 --- a/docs/deployments/fxi/notes.md +++ /dev/null @@ -1,129 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at FXI: the Capabilities and portable [Catalog](../../catalog/methods.md) Methods CORA brings, bound through an NSLS-II [Practice](../nsls2/index.md#the-techniques-adapted-here). The function view survives equipment swaps.* - -FXI is a full-field transmission X-ray microscope that does fly and step tomography, mosaic tomography, radiography, and XANES / spectro-tomography. These are the same techniques the 2-BM pilot exercised, so CORA expresses each as a Catalog Method it already carries: a second tomography deployment proves the Methods are portable across facilities. (The "demonstrated by" column names the floor plan that shows FXI runs the technique today; CORA replaces that orchestration with its Conductor, see [Controls](controls.md).) - -### Imaging - -| CORA does | Catalog Method | Demonstrated by (floor) | -| --- | --- | --- | -| Continuous-rotation fly tomography | [`continuous_rotation_tomography`](../../catalog/methods.md) | position-triggered fly scan | -| Step tomography | [`tomography`](../../catalog/methods.md) | stop-and-shoot projections | -| Mosaic tomography | [`mosaic_tomography`](../../catalog/methods.md) | tiled fields for large samples | -| Radiography | [`tomography`](../../catalog/methods.md) | single-angle projection series (carried under the tomography family pending a dedicated Method) | -| Flat / dark acquisition | [`flat_field`](../../catalog/methods.md), [`dark_field`](../../catalog/methods.md) | reference-frame capture per scan | - -### Spectroscopy - -| CORA does | Catalog Method | Demonstrated by (floor) | -| --- | --- | --- | -| XANES imaging / spectro-tomography | [`tomography`](../../catalog/methods.md) + [`beamline_energy_change`](../../catalog/methods.md) | energy-resolved imaging across an edge | -| Energy change | [`beamline_energy_change`](../../catalog/methods.md) | the coupled energy move that co-moves the zone plate, condenser, and detector to hold magnification constant | - -### Supporting operations - -| CORA does | Catalog Method | Demonstrated by (floor) | -| --- | --- | --- | -| Rotation-center finding | [`center_alignment`](../../catalog/methods.md) | center search during reconstruction | -| Calibration-position recording | [`focus_alignment`](../../catalog/methods.md) | building the energy lookup table | - -Reconstruction (the tomographic recon, ring removal, rotation-center search) is CORA's compute leg, conducted over the ComputePort rather than as a beamline Method; see [Controls](controls.md). - -## Governance - -*Who may act at FXI and the trust shape CORA applies. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority.* - -People and agents are facility principals at the [NSLS-II Site](../nsls2/index.md#safety-and-governance); on the beamline they surface through the actions they take. The human roster is not yet known (GOV-1), so the principals below are the design shape, not a registered list. - -### Who acts - -CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the NSLS-II Site. An FXI beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. The concrete people and their role assignments are pending staff confirmation (GOV-1). - -### The trust boundary - -CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may start a run, override a caution, or commit a calibration. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer. - -Two facts from the facility flow into this design: - -- Proposal custody. An NSLS-II beamtime is scoped to a proposal and cycle. CORA uses that proposal/cycle as the Campaign and the custody key for who is entitled to act during a beamtime; it confirms entitlement against the facility's proposal identity but applies its own per-Actor authority on top. -- The floor already has a coarse, group-level command-authority layer at the controls level. CORA does not adopt it: CORA's per-Actor Trust model supersedes it with finer, auditable authority. - -No autonomous or adaptive agent Actor is declared for FXI yet. If one were added (an alignment or experiment-steering agent), it would be a facility principal scoped at the Site, governed by the same Trust boundary, and each proposed move would be a [Decision](../../architecture/modules/decision/index.md) (the inference-recorder path for any LLM-backed agent). - -## Model - -*The developer's by-kind index: where each CORA aggregate's FXI content lives. It hosts no content of its own. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC -[modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at FXI | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (XEng) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) (18-IDA optics, 18-IDB endstation) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### Deliberately not here yet - -This is a design-phase scaffold (descriptor + docs), reverse-engineered from the profile collection. Left out on purpose: - -- **Operations and experiment views, integration scenarios, vendor Models.** A runbook and registered Assets for a beamline CORA does not yet drive would be invention; they land when the design firms and the team confirms. -- **`BertrandLens` catalog graduation.** A loose family at its only sighting (OPTIC-3); graduates at a second deployment. - -## Open questions - -*What CORA needs the FXI team to confirm before the model can be trusted.* - -This model is reverse-engineered from public NSLS-II open source (the bluesky profile collection [`NSLS2/fxi-profile-collection`](https://github.com/NSLS2/fxi-profile-collection) and the shared `NSLS2/nslsii` package), so this page is long by design: the EPICS PVs are read straight from the profile collection, but vendor identities, controller boxes, physical positions, and the safety layer are not in it. Each row is a fact the beamline team or an IOC `st.cmd` file owns, not a CORA modelling choice. It is a delete-on-answer queue: when an item is answered, the answer lands in the descriptor and the row is removed (with the reason in the commit). Priorities are `Blocks-build` (needed before the model is built for real), `Blocks-go-live` (needed before CORA controls or observes the hardware), and `Nice-to-have`. - -### Source and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-go-live | What is the 18-ID insertion device (undulator vs damping wiggler), and its period, gap, and power? Not in the profile collection. | An insertion-device source, identity-only; recorded as a PhotonBeam Supply. | The Source Asset and the InsertionDevice settings. | -| PSS-1 | Blocks-go-live | What are the PSS search-and-secure permit-leaf PVs for hutches 18-IDA and 18-IDB? Only the PPS photon-shutter status `XF:18IDA-PPS{PSh}Pos-Sts` is in source. | Both hutches exist; the permit signal is a confirm note, not a guessed PV. | The Enclosure permit signals. | -| ENC-1 | Nice-to-have | Is the `XF:18ID1-ES` namespace (where the Kinetix camera lives) a distinct endstation area, or part of 18-IDB? | Two enclosures (18-IDA optics, 18-IDB experiment); 18ID1-ES folded into 18-IDB. | The Enclosure set and roles. | -| LAYOUT-1 | Nice-to-have | What are the device z positions along the beam? The profile collection carries no layout or z reference. | No z values are recorded; the device order is the source/sample/detection grouping only. | Device z positions. | - -### Optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DCM-1 | Blocks-go-live | What is the DCM crystal cut (Si 111?) and the energy range? | A double-crystal monochromator; cut and range carried blank. | The Monochromator settings. | -| OPTIC-1 | Nice-to-have | Are the two mirrors collimating (`cm`) and toroidal (`tm`) respectively? Both are the same ophyd class with no role string in source; the labels are inferred from the instance names. | The role labels are carried `confirm`, not asserted. | The Mirror role labels. | -| OPTIC-2 | Nice-to-have | What are the slit blade-axis PV suffixes, and the PV prefix for the secondary-source slit (`TXM_SSA`)? | The white-beam slit `XF:18IDA-OP{PBSL:1` is bound; the secondary-source slit is identity-only. | The Slit axes. | -| OPTIC-3 | Nice-to-have | Should BetrandLens become a catalog Family? Condenser, ZonePlate, and PhaseRing graduated once FXI joined 32-ID as a second deployment; BetrandLens is FXI-only, so it stays a loose family tag pending a second sighting. | Loose family name that renders as text; not yet graduated. | Catalog Family graduation (Federation-scoped). | -| OPTIC-4 | Nice-to-have | Confirm the zone-plate values: NanoTools, 244 um diameter, 30 nm outer zone width. These are code constants, not staff-verified. | The code-constant values, carried `confirm`. | The ZonePlate settings. | -| FILT-1 | Nice-to-have | What are the materials and thicknesses of the eight pneumatic filter foils (relays on a Moxa ioLogik E1211)? | Eight foils, materials unknown. | The Filter foil settings. | - -### Sample and detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| STAGE-1 | Nice-to-have | What is the sample translation stage (`TXMSampleStage`, sx/sy/sz) vendor and travel? | A LinearStage stack, identity-only. | The SampleStage settings. | -| STAGE-2 | Blocks-go-live | What is the tomography rotary (`pi_r`, `XF:18IDB-OP{TXM:2-Ax:R}`) hardware (air-bearing vs piezo), encoder resolution, and max speed? The "PI / Physik Instrumente" reading is a naming inference. | A RotaryStage, PSO-triggered, specs blank. | The SampleRotary settings (critical for the tomography Capability). | -| DET-1 | Nice-to-have | What are the scintillator material and thickness? | A scintillator-relay lens stage, material unknown. | The Scintillator settings. | -| DET-2 | Nice-to-have | What is the detector-support (`DetSupport`, DetU/DetD) PV prefix? `DetU.z` is the propagation distance in the magnification calculation. | The support is recorded, PV prefix blank. | The DetectorSupport binding. | -| CAM-1 | Blocks-go-live | Which cameras are physically installed and active? Source has Andor Neo2, Andor Marana, and Photometrics Kinetix; the U/D pairs share identical PVs (KinetixD is a placeholder reusing KinetixU's PVs). Is there a second detector position? | One detector position, bound to the live Kinetix; the rest are a roster note. | The Camera Assets and the detector Fixture. | -| CAM-2 | Nice-to-have | What are the camera vendor part numbers? Vendor names are inferred from ophyd class names; only `MARANA-4BV6X` / `SONA-4BV6X` / `KINETIX` / `KINETIX22` are literal in the readout config. | Vendor classes, no part numbers. | The Camera Models. | -| DIAG-1 | Nice-to-have | What are the ion-chamber channel PV suffixes (`ic1..ic4`, i404 quad electrometer)? | Read-only intensity probes, suffixes blank. | The IonChamber bindings. | -| ENV-1 | Nice-to-have | Is the Lakeshore 336 sample-environment temperature controller installed? It is disabled in source (`motor_lakeshore = []`). | Not modeled as a live device. | The sample-environment controller. | - -### Controls and data - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DRIVE-1 | Blocks-go-live | What are the motion-controller boxes behind the EpicsMotors (model, protocol, axis count, serial, firmware, IP), and which IOC drives each device group? Confirmed not in public open source: FXI has no IOC-config repo, and its per-beamline IOC inventory (Ansible `nsls2.ioc_deploy` device roles + a `-epics-containers` repo) is ops-private. Needs FXI staff or inventory access. | Families only; box identities unknown. | The MotionController Models and the Drive identities. | -| ZEBRA-1 | Nice-to-have | Are there two position-trigger boxes? One is instantiated; a second is referenced in the public config. What is each wired to? | One trigger box, reading the rotary as the master encoder. | The TimingController set. | - -### Governance - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| GOV-1 | Blocks-go-live | Who is the FXI operator and beamline-scientist pool, and the role assignments? The public config exposes only a coarse group-level controls authority, not the human roster CORA's Access model needs. | A pending facility actor pool; CORA applies its own per-Actor authority. | The Access Actors and Trust policies. | diff --git a/docs/deployments/hex/notes.md b/docs/deployments/hex/notes.md deleted file mode 100644 index 270560b819c..00000000000 --- a/docs/deployments/hex/notes.md +++ /dev/null @@ -1,191 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of HEX is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../nsls2/index.md#the-techniques-adapted-here) is how a facility adapts it. HEX measures engineering-materials and energy-storage samples three ways, all in the single operational endstation and all at high X-ray energy: X-ray imaging and tomography, energy-dispersive X-ray diffraction (EDXD), and angle-dispersive / powder diffraction (ADXD). One of those, tomography, is a Method CORA already holds; the rest render unlinked and are carried pending until the owner-scope decision (`TECH-1`) brings them into the catalog. - -HEX is mostly reinforcement of imaging and high-energy diffraction the fleet already speaks. Read this page for the one thing that is structurally distinct: all three techniques run in the same experiment, with detectors and optics moved into the beam remotely. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| X-ray tomography and CT | `tomography` | high-energy white-beam and monochromatic tomography (continuous fly-rotation, `tomo_flyscan`) on the [Kinetix sCMOS cameras](detector.md); reuses the graduated Method (shared with [2-BM](../2-bm/techniques.md) and [FXI](../fxi/notes.md#techniques)) | -| Time-resolved radiography | `radiography` | 2D high-speed / in-situ radiography on the [Phantom Veo](detector.md); shares the Method APS [7-BM](../7-bm/notes.md#techniques) left pending (`TECH-1`) | -| Energy-dispersive diffraction (EDXD) | `energy_dispersive_diffraction` | spatially-resolved EDXD on the [GeRM germanium strip detector](detector.md); shares the Method 7-BM left pending, HEX the second consumer (`TECH-1`) | -| Angle-dispersive / powder diffraction (ADXD) | `powder_diffraction` | monochromatic area-detector diffraction on the [PerkinElmer flat panel](detector.md); shares the Method Diamond [i11](../i11/notes.md#techniques) left pending, HEX the second consumer (`TECH-1`) | - -All four techniques need the [incident-beam chain](source.md) (the superconducting wiggler, the low-energy filters, and the monochromator for the monochromatic modes), the [sample stack](sample.md) (the 500 kg sample tower, the tomographic rotation and translations), and the [endstation detectors](detector.md). The white beam serves high-speed imaging and EDXD; the monochromatic beam serves tomography at a chosen energy and angle-dispersive diffraction. - -### The imaging and diffraction is reinforcement, not novelty - -Tomography, radiography, and high-energy diffraction overlap the fleet. Tomography is the operational pilot's defining technique ([2-BM](../2-bm/techniques.md)) and is graduated in the catalog; the [FXI](../fxi/notes.md#techniques) full-field microscope is a second tomography sibling. Energy-dispersive diffraction is the pending APS [7-BM](../7-bm/notes.md#techniques) white-beam Method, and angle-dispersive / powder diffraction is the pending Diamond [i11](../i11/notes.md#techniques) Method. HEX reuses the same `Camera` / `Scintillator` / `RotaryStage` / `LinearStage` / `EnergyDispersiveSpectrometer` vocabulary, coins no new Family, and adds a second consumer to each pending diffraction Method. - -So the technique side of HEX earns no new abstraction. It reinforces, at a high-energy beamline, the case that energy-dispersive and powder diffraction belong in the catalog (`TECH-1`), the same earn-the-abstraction discipline 7-BM and i11 already follow. The device Roles exist (the cameras and the flat panel present Detector, the GeRM strip detector presents Sensor), so what stays pending is the science Capability, not a device shape. Because those Capabilities are not yet in the catalog, the matching Site Practices (`HEX_radiography_practice`, `HEX_energy_dispersive_diffraction_practice`, `HEX_powder_diffraction_practice`) are carried pending in the [NSLS-II Site](../nsls2/index.md#the-techniques-adapted-here); each binding lands when its Capability does. `HEX_tomography_practice` names the graduated `tomography` Method and renders linked. - -### Multi-technique in one experiment, the distinct contribution - -The structurally distinct thing about HEX is not any one technique; it is that imaging / tomography, EDXD, and ADXD are all available in the single F-hutch endstation during the same experiment, with detectors and optics moved into place remotely per technique. A high-energy beamline lets a user follow a working battery or a loaded engineering component and switch, within one mounting, between a tomographic view of the microstructure, an energy-dispersive map of internal strain and phase, and an angle-dispersive powder pattern. - -CORA models this as **multiple Methods over one endstation**, not a new Capability. The switch itself is a positioning action: a [detector / optics stage](detector.md) moves the chosen detector into the beam. That positioning binds the catalog `LinearStage` and is conducted over the `ControlPort` (see [Controls](controls.md)); it is a Practice-level sequence, not a new technique. The one-technique-per-acquisition assumption is what this stresses, and the resolution is that a Run selects its technique by positioning, then acquires (`TECH-1`). - -| Technique in the experiment | Detector | Family | -| --- | --- | --- | -| imaging / tomography | [Kinetix sCMOS](detector.md) + scintillator-lens | `Camera` + `Scintillator` | -| time-resolved radiography | [Phantom Veo](detector.md) | `Camera` | -| energy-dispersive diffraction (EDXD) | [GeRM strip detector](detector.md) | `EnergyDispersiveSpectrometer` | -| angle-dispersive diffraction (ADXD) | [PerkinElmer flat panel](detector.md) | `Camera` | - -### Not modelled yet - -The concrete acquisition recipes are not written yet. For tomography that is the fly-rotation step model, the dark / flat sequence (`tomo_dark_flat`), and the vertical stitch (`tomo_y_scan_loop`); the reconstruction (flat-field correction, ring / stripe removal) is `ComputePort` work, not a beamline Method. For diffraction it is the EDXD gauge-volume definition and the angle-dispersive integration that turns 2D frames into one-dimensional patterns. These join as the deployment approaches the point where CORA drives HEX. - -Whether any of these techniques enters CORA's catalog is an owner-scope decision on [Model](#model): a modelling exercise reinforces the case but does not mint cross-facility Method vocabulary on its own. HEX adds a second consumer to the pending `energy_dispersive_diffraction`, `radiography`, and `powder_diffraction` Methods, which strengthens the case for cataloging them but leaves that an owner decision (`TECH-1`). See [Open questions](#open-questions) for the world-facts to confirm first, including whether pair-distribution-function (PDF) or three-dimensional X-ray diffraction (3DXRD) are offered, which public sources do not list for HEX (`TECH-1`). - -## Governance - -*Who will act at HEX, and the trust shape that will gate it. First cut.* - -Governance at HEX 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#safety-and-governance), 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). - -HEX is not yet driven by CORA, so this shape is not yet instantiated. As a modelling-exercise scaffold, the deployment is descriptor and docs today, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized. The profile collection exposes only coarse queue-server groups, not the human roster, so the NSLS-II operator pool and review structure is carried pending on the [NSLS-II Site](../nsls2/index.md#safety-and-governance), shared with the rest of the fleet (`GOV-1`). - -### A distinct allocation policy - -HEX has one governance fact the other NSLS-II beamlines do not: a share of its beamtime is reserved for proposals aligned with New York clean-energy and energy-storage goals. Public sources describe a portion of beamtime set aside for such proposals, evaluated by a dedicated proposal-evaluation committee on weighted criteria (technical merit, New York commercial relevance, economic development, and personnel), with the remainder allocated through the standard NSLS-II proposal review and all proposals administered through the facility proposal system. This is a real, distinct trust-shape input: an allocation Policy that gates which experiments run, layered on top of the facility-wide safety and access tiers. - -CORA records this as a Policy-level fact, not a new bounded context or descriptor. The exact reservation fraction and the committee's scoring split are carried as a world-fact (`GOV-1`) and are modelled when CORA drives the beamline, not instantiated now. The allocation Policy binds to the NSLS-II operator and review roles carried pending at the Site. - -### The safety boundary - -The safety tier is the other piece that is not yet settled. The PSS search-and-secure permit signals and the front-end and photon shutters are absent from the beamline's profile collection, so the Enclosure permit leaves and the interlock structure are carried pending and are not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [NSLS-II Site](../nsls2/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -HEX adds the hazard classes that come with its instruments. Those land with the equipment that brings them, and an experiment Clearance would carry them. - -| Hazard class | Where it lands | Tracking | -| --- | --- | --- | -| High-energy hard X-ray beam (white to 250 keV, monochromatic to 200 keV) | the [optics](index.md) and [endstation](index.md) enclosures (`hex-foe`, `hex-endstation`) | (`PSS-1`, `SCW-1`) | -| The superconducting wiggler source | the [Source](source.md) walk (cryogen-free, no liquid-helium hazard) | (`SCW-1`) | -| Heavy-sample handling (up to 500 kg) | the [Sample](sample.md) tower | (`STAGE-1`) | -| User-brought in-situ / operando environments | the [Sample](sample.md) endstation | (`INSITU-1`) | - -The high-energy beam is the interlocked hazard, and at these photon energies the shielding burden is heavier than the fleet's lower-energy beamlines; its permit leaves stay pending until the PSS signals are confirmed (`PSS-1`). The superconducting wiggler is cryogen-free, so no liquid-helium supply hazard is carried (`SCW-1`). The heavy-sample handling and the user-brought in-situ environments are operational hazards carried with the equipment that brings them (`STAGE-1`, `INSITU-1`); none is invented, each is recorded against its question. - -### When the shape lands - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives HEX, following the [2-BM governance](../2-bm/governance.md) shape. Because HEX shares the NSLS-II EPICS and ophyd floor with its siblings, it re-tests the Site and Federation kernel rather than introducing a new trust model. The Zone groups the same optics and endstation resources the [inventory](index.md) lists; the Conduit binds the command surfaces; the Policies bind to the NSLS-II operator roles carried pending at the Site, with the NYSERDA-aligned allocation Policy layered on top (`GOV-1`). - -## Model - -*The developer's by-kind index: where each CORA aggregate's HEX content lives, how it models the multi-technique endstation and the heavy sample tower, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at HEX | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (the incident-energy `PseudoAxis`) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes HEX new - -The honest answer is: not much on any single technique, and three real things on structure. HEX measures engineering-materials and energy-storage samples by high-energy imaging / tomography, energy-dispersive diffraction (EDXD), and angle-dispersive / powder diffraction (ADXD). The imaging overlaps the fleet heavily (the 2-BM pilot, the NSLS-II FXI), and the diffraction reuses the pending energy-dispersive (7-BM) and powder (i11) Methods. That side reuses the existing `Camera` / `Scintillator` / `RotaryStage` / `LinearStage` / `EnergyDispersiveSpectrometer` / `InsertionDevice` / `Monochromator` / `Filter` vocabulary and contributes reinforcement, not novelty. - -HEX's three genuinely distinct contributions are: - -- **Multi-technique in one experiment.** All three techniques run in the single F-hutch endstation during one experiment, with detectors and optics moved into the beam remotely. CORA models this as multiple Methods over one endstation, the technique switch a positioning leg over the `ControlPort`, not a new Capability (`TECH-1`). -- **Very large and heavy engineering samples.** The 500 kg removable sample tower is a heavy reconfigurable fixture, not a precision goniometer. It reuses `Table` + `RotaryStage` + `LinearStage` with capacity and the configuration set as settings (`STAGE-1`). -- **A high-energy hard X-ray source.** The superconducting wiggler (4.3 T, 70 mm period) reaching 200 keV monochromatic is a first for the fleet. It binds the existing `InsertionDevice` Family, with the field and energy reach as source specs (`SCW-1`). - -### No new families - -HEX coins no new Family and changes nothing in the catalog. - -- **The superconducting wiggler binds `InsertionDevice`** (the undulator precedent at the NSLS-II siblings). The beam mode (white 30 to 250 keV versus monochromatic 30 to 200 keV) is selected by inserting or retracting the monochromator first crystal, so it is a setting on the optic, not a second source (`MONO-2`). -- **The optics reuse:** the low-energy filters bind `Filter`; the bent-Laue monochromator binds `Monochromator` (a Bragg optic, not the soft X-ray `GratingMonochromator`); the incident energy is a `PseudoAxis` over it; the front-end slits bind `Slit`. -- **The sample side reuses:** the tomographic rotation binds `RotaryStage`; the sample translations bind `LinearStage`; the 500 kg removable tower binds `Table`. -- **The detection side reuses:** the Kinetix sCMOS and Phantom Veo cameras and the PerkinElmer flat panel bind `Camera`; the imaging scintillator-lens table binds `Scintillator`; the detector / optics positioning binds `LinearStage`; the GeRM germanium strip detector binds the existing `EnergyDispersiveSpectrometer` Family (below). - -### The GeRM strip detector reuses an earned family - -The one place HEX looks like it might force a new abstraction is its energy-dispersive detector, the GeRM germanium strip detector that produces a per-channel energy spectrum rather than a 2D frame. That shape is already in the catalog: the `EnergyDispersiveSpectrometer` Family was earned by the APS 2-ID fluorescence detector and the 7-BM germanium energy-dispersive-diffraction detector, and its definition presents the `Sensor` Role (a scalar or short-vector Reading per point) and explicitly spans the silicon-drift and germanium variants. HEX's GeRM detector is the **third consumer** of that Family, with channel count and energy resolution per-Asset settings. So EDXD on HEX is a reuse, not a graduation, and no catalog or loose-family change is forced (`DET-2`). - -### How the multi-technique switch is modelled (no new capability) - -The F-hutch offers imaging / tomography, EDXD, and ADXD in one experiment. CORA models the switch between them as a **positioning action over existing devices**, not a new Capability or device: - -- each technique has its detector already on the [detection](detector.md) side (the Kinetix cameras, the PerkinElmer flat panel, the GeRM strip detector); -- a `LinearStage` (`DetectorStage`) moves the chosen detector or optic into the beam; -- CORA conducts that positioning over the `ControlPort`, then runs the technique's Method. - -So the "multi-technique endstation" is a Practice-level sequence, not a fused mega-instrument. The stress it puts on the model, that a single endstation hosts several one-technique acquisitions selected by positioning, is resolved by treating technique selection as a conducted positioning leg ahead of acquisition (`TECH-1`). No new family is coined for the switch. - -### Deliberately not here yet - -- **The B / C / D / E hutch contents (`ENC-1`, `LAYOUT-1`).** HEX is designed for six enclosures (A = FOE, B, C, D, E, F). All six are declared in the descriptor, forward-looking, but only the operational FOE (`hex-foe`) and F-hutch (`hex-endstation`) carry devices; B (not erected) and C / D / E (future-upgrade shells) are declared as device-free enclosures and carry no Assets in this cut. The descriptor validates that every device's enclosure ref is declared but allows an unreferenced enclosure, so the shells are honest forward-looking placeholders, not invented contents. The satellite-building identity and the per-hutch positions are carried as world-facts (`SAT-1`, `LAYOUT-1`). -- **The monochromatic focusing optic (`FOCUS-1`).** The beamline page lists focusing for the monochromatic beam as "being commissioned." It is not yet modelled as a device; what optic it is and its target spot are carried as a world-fact. -- **In-situ sample environments (`INSITU-1`).** HEX's science is operando battery and engineering-materials work, but no specific rig (load frame, furnace, cryostat, battery cycler) is source-confirmed as installed; the endstation is "capable of housing" user-brought environments. Per earn-the-abstraction, no in-situ rig is modelled as an Asset in this cut. If a specific rig is confirmed installed and a second fleet beamline brings one, that is the trigger to consider a sample-environment Family. -- **The heavy-sample stage as a distinct family (`STAGE-1`).** The 500 kg removable tower stresses the assumption that a sample-orientation Asset is small and goniometer-like. CORA holds the line: capacity and the configuration set (configs A to D) are settings on a reused `Table` + `RotaryStage` + `LinearStage`, not a new `HeavyStage` Family. A second fleet beamline with a heavy removable tower would be the rule-of-three trigger. -- **The diffraction Methods.** Whether energy-dispersive diffraction, radiography, and powder diffraction enter CORA's catalog as Capabilities / Methods is an owner decision; the Practices render unlinked, pending. EDXD and radiography are shared with 7-BM and powder diffraction with i11 (`TECH-1`). -- **Pair-distribution-function and 3DXRD.** Public sources do not list PDF (that is NSLS-II 28-ID / [XPD](../xpd/index.md)) or three-dimensional X-ray diffraction for HEX, so neither is modelled or assumed (`TECH-1`). -- **The simulated devices and full asset-tree scenarios.** No `test_hex_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the HEX team to confirm before the model can be trusted.* - -HEX was reverse-engineered from public sources (the BNL beamline page, the [beamline 27-ID wiki](https://wiki-nsls2.bnl.gov/beamline27ID), and the beamline's bluesky profile collection [NSLS2/hex-profile-collection](https://github.com/NSLS2/hex-profile-collection) and [NSLS2/hextools](https://github.com/NSLS2/hextools)), so the control handles on the [device pages](index.md) are read from public config rather than confirmed by staff. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | Are the six designed enclosures A (FOE), B, C, D, E, F, with only A and F presently relevant to operations (B not erected; C / D / E future-upgrade shells)? | All six declared; `hex-foe` and `hex-endstation` carry devices, B to E are device-free forward-looking shells. | The Enclosure grouping and the future-hutch contents. | -| SAT-1 | Nice-to-have | Is the satellite building housing the F-hutch the same as Bldg. 742 or a separate numbered structure adjacent to it? | The F-hutch is a distinct enclosure adjacent to Bldg. 742, bound to the NSLS-II Site. | The endstation Enclosure detail. | -| LAYOUT-1 | Nice-to-have | The source-to-F-hutch distance (about 100 m) and whether an exact per-hutch z-position table exists. | About 100 m source to endstation; no per-hutch z table carried. | The beam-path geometry. | -| BRANCH-1 | Nice-to-have | Do the inboard and outboard front-end branches carry any installed optics, or are they bare provisions for the future hutches? | Provisions only; only the center branch carries devices. | The front-end slit modelling. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MACHINE-1 | Nice-to-have | The storage-ring state HEX reads (current, fill, status). | Observe-only machine state, a loose `StorageRing`; the exact PVs pending. | The machine-state observation. | -| SCW-1 | Nice-to-have | The superconducting wiggler pole count and critical photon energy (only the 4.3 T field, 70 mm period, 1.2 m length, cell-27 straight are published). | An `InsertionDevice` Asset; field, period, and length carried as specs; pole count and critical energy pending. | The source Asset detail. | -| MONO-1 | Blocks-go-live | The monochromator crystal material and geometry (is it Si(111) bent Laue?), the crystal count, and the d-spacing. | A single bent-Laue first crystal on a vertical translation, binding `Monochromator`; the incident energy a `PseudoAxis` over it. | The monochromator and incident-energy Assets. | -| MONO-2 | Blocks-build | The upper monochromatic energy: 150 keV (the wiki) or 200 keV (peer-reviewed, "first NSLS-II beamline to reach 200 keV mono")? | 30 to 200 keV monochromatic, 30 to 250 keV white. | The energy-axis range bound. | -| FILT-1 | Nice-to-have | The FOE low-energy filter materials and thicknesses per branch (center SiC 3 / 6 / 9 / 12 mm; outboard / inboard Cu plus SiC) and the 35 mm pitch. | Beam-hardening filters bound to `Filter`; materials and thicknesses as listed on the commissioning wiki. | The filter Asset detail. | -| FOCUS-1 | Nice-to-have | What focusing optic is being commissioned for the monochromatic beam, and the target focused spot. | Focusing not yet a device; carried deferred. | The focusing-optic Asset. | - -### Sample - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| STAGE-1 | Blocks-go-live | The modular sample-tower configurations (A to D), the 500 kg capacity, and which axes are motorized (the tomographic rotation and the translations). | One reconfigurable tower (`Table`, 500 kg, configs A to D) plus a `RotaryStage` rotation and `LinearStage` translations; capacity and config set as settings. | The sample-stage modelling. | -| INSITU-1 | Blocks-go-live | Which in-situ rigs are actually installed or available at the endstation (load frames, furnaces, cryostats, battery cyclers)? | None installed; the endstation is "capable of housing" user-brought environments, so no in-situ rig is modelled. | The sample-environment modelling; the CORA family decision is on [Model](#deliberately-not-here-yet). | - -### Detection - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The PerkinElmer area-detector model (XRD1621?), its pixel count, and that it is the angle-dispersive / powder-diffraction (ADXD) detector. | A PerkinElmer XRD1621 flat panel binding `Camera`, inferred to be the ADXD detector. | The area-detector modelling. | -| DET-2 | Blocks-go-live | The GeRM germanium strip detector channel count, energy resolution, and the EDXD gauge-volume dimensions. | A GeRM strip detector binding the existing `EnergyDispersiveSpectrometer` Family; specs pending. | The energy-dispersive-detector modelling. | -| DET-3 | Nice-to-have | Which Kinetix camera is the tomography default, and the scintillator / lens magnification options behind the "2 & 4 mm", "20 & 40 mm", and "Dual cam" imaging-table positions. | `kinetix1` is the default; the scintillator-lens table binds `Scintillator`; the Phantom Veo is the high-speed camera. | The imaging-camera and scintillator modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the EPICS PV handles read from the profile collection current and correct, and what are the FOE-optics PVs (absent from it)? | The endstation detector handles are from the profile collection and carried confirm; the FOE-optics PVs are pending. | Verifying each Asset's control handle. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit signals and the photon / front-end shutters (absent from the profile collection). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent (the FOE optics) and the cooling supply. | Photon beam, cooling water, and vacuum on the FOE optics; the cryogen-free wiggler draws no liquid helium. | The Supply observations. | -| GOV-1 | Nice-to-have | The NSLS-II operator pool and safety-review structure (site-level), and the NYSERDA-aligned beamtime-reservation fraction and the proposal-evaluation committee's scoring split. | Carried pending on the NSLS-II Site; the NYSERDA allocation Policy layered on top, fraction and scoring pending. | The governance principals and allocation Policy. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Blocks-go-live | Is the operational technique set exactly imaging / tomography, radiography, EDXD, and powder / ADXD, with all three diffraction-and-imaging modes available in the one endstation, and are PDF and 3DXRD not offered? | Those techniques only; multi-technique in one endstation via detector / optics positioning; no PDF, no 3DXRD. | The technique Capabilities and the multi-technique modelling. | diff --git a/docs/deployments/hxn/notes.md b/docs/deployments/hxn/notes.md deleted file mode 100644 index b94f4ebab6e..00000000000 --- a/docs/deployments/hxn/notes.md +++ /dev/null @@ -1,101 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at HXN: the Capabilities and portable [Catalog](../../catalog/methods.md) Methods, bound through an NSLS-II [Practice](../nsls2/index.md#the-techniques-adapted-here).* - -HXN does scanning nano-XRF mapping, ptychography, nano-tomography, and spectro-tomography, all variants of one act: raster the sample through the focus and read the per-point detectors. The big modeling question HXN raises is whether scanning and ptychography are new Capabilities or fit existing ones; this scaffold **defers** coining them, following the Diamond i03/i22 and 32-ID precedent (no new Capability coined for a design-phase reverse-engineered deployment until a real conduct-path consumes it). - -| HXN technique | CORA expression | Earn-the-abstraction call | -| --- | --- | --- | -| Scanning XRF mapping | Method under `acquisition` (a raster of per-point spectra) | **Defer** coining a `scanning` Capability; trigger = first raster conduct-path, or a 2nd scanning beamline | -| Ptychography | the same raster with a `Camera` in the detector slot + offline reconstruction | **Defer**; ptychography is not its own Capability. The reconstruction is a `ComputePort` leg, not a beamline Method | -| Nano-tomography | [`tomography`](../../catalog/methods.md) | reuse; raster x rotation, the same family as 2-BM/FXI tomography | -| Spectro-tomography | compose `tomography` + energy change | reuse; do not coin `spectro_tomography` | -| XANES / energy change | [`beamline_energy_change`](../../catalog/methods.md) | reuse; but the HXN energy change co-moves the zone-plate refocus per element (ENERGY-1), a richer move than FXI's mono-only change | -| Alignment | [`alignment`](../../catalog/methods.md) | reuse (line-center, knife-edge, center-of-mass) | - -The central new shape, **scanning-probe acquisition with multi-modal per-point detection**, is the strongest in-kind argument the catalog has seen for a `scanning` Capability (the raster *is* the measurement, not a frame at a fixed pose). It is held open deliberately, not because it is weak, but because the discipline is to coin a Capability when a conduct-path forces it, not at scaffold time. See [Controls](controls.md) for how CORA's conducting engine would run the raster over the ControlPort and the ptychographic reconstruction over the ComputePort. - -## Governance - -*Who may act at HXN and the trust shape CORA applies. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority.* - -People and agents are facility principals at the [NSLS-II Site](../nsls2/index.md#safety-and-governance); on the beamline they surface through the actions they take. The human roster is not known from the profile collection (GOV-1), so the principals are the design shape, not a registered list. - -### Who acts - -CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the NSLS-II Site. An HXN beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. - -### The trust boundary - -CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may start a run, override a caution, or commit a calibration. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer. The NSLS-II proposal and cycle are a fact CORA's Campaign uses for custody; CORA confirms entitlement against the facility's proposal identity but applies its own per-Actor authority on top. - -### Agents and the scanning loop - -HXN's scanning workflows (auto-alignment, adaptive mapping) are where an autonomous or adaptive Agent would naturally act: proposing the next scan region or correction inside the conduct loop. If such an agent were added, it would be a facility principal scoped at the Site, governed by the same trust boundary, and each proposed move would be a [Decision](../../architecture/modules/decision/index.md) (the inference-recorder path for any LLM-backed agent). None is declared for HXN yet. - -## Model - -*The developer's by-kind index: where each CORA aggregate's HXN content lives. It hosts no content of its own. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC -[modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at HXN | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (EnergyAxis) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) (3-ID-A optics, 3-ID-C endstation) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### Deliberately not here yet - -This is a design-phase scaffold (descriptor + docs), mirroring 32-ID and 7-BM. Left out on purpose: - -- **The scanning / ptychography Capabilities.** Coined when a real conduct-path consumes a raster, not at scaffold time (see [Techniques](#techniques)). HXN is the first scanning-probe deployment, so this is the live earn-the-abstraction question, deferred deliberately. -- **`MultilayerLaueLens` catalog graduation.** A loose family at its first sighting (OPTIC-3); graduates at a second MLL beamline. -- **Operations and experiment views, integration scenarios, vendor Models.** A runbook and registered Assets for a beamline CORA does not yet drive would be invention; they land when the design firms and the team confirms. - -## Open questions - -*What CORA needs the HXN team to confirm. This model is reverse-engineered from public open source (the [`NSLS2/hxn-profile-collection`](https://github.com/NSLS2/hxn-profile-collection) profile collection): the EPICS PVs are read from it, but vendor identities, physical positions, and the detector roster are not. Each row is a fact the beamline team owns. It is a delete-on-answer queue.* - -Priorities: `Blocks-build` (changes the model structure), `Blocks-go-live` (needed before CORA controls or observes the hardware), `Nice-to-have`. - -### Source and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Nice-to-have | IVU20 undulator period, gap range, and harmonic usage. The device (`SR:C3-ID:G1{IVU20:1}`) is confirmed; parameters are not in source. | An in-vacuum undulator, identity-only. | The InsertionDevice settings. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit-leaf PVs per hutch. Only the photon shutter `XF:03IDB-PPS{PSh}` is in source. | The permit signal is a confirm note, not a guessed PV. | The Enclosure permit signals. | -| ENC-1 | Nice-to-have | Is the `XF:03IDB` intermediate zone (secondary-source aperture, slow shutter) a distinct enclosure, or part of the endstation? HXN spans three PV zones (3-ID-A/B/C). | Two enclosures (3-ID-A optics, 3-ID-C experiment); 3-ID-B folded. | The Enclosure set and roles. | - -### Optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DCM-1 | Nice-to-have | DCM crystal cut and energy range. | A double-crystal monochromator; cut/range blank. | The Monochromator settings. | -| OPTIC-1 | Blocks-go-live | Are the zone plate and the multilayer Laue lens both permanently installed and operator-selected, or is one decommissioned? Both appear in source. | Both modelled, switchable. | The focusing-optic roster. | -| OPTIC-2 | Nice-to-have | Zone-plate parameters (outer-zone width, diameter, material). | A ZonePlate Asset, parameters blank. | The ZonePlate settings. | -| OPTIC-3 | Nice-to-have | Should `MultilayerLaueLens` become a catalog Family? HXN is its only sighting (a 1D crossed-pair lens, distinct from the circular ZonePlate). | A loose family name that renders as text; not yet graduated. | Catalog Family graduation (Federation-scoped). | - -### Sample and detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| STAGE-1 | Blocks-go-live | The tomographic rotary (`sth`, on an ANC350) hardware, encoder resolution, and max speed. | A RotaryStage, specs blank. | The SampleRotary settings. | -| STAGE-2 | Nice-to-have | Does the SmarAct Smarpod 6-DOF pod fit the `Hexapod` Family (single coordinated parallel-kinematics move)? | Modelled as a Hexapod. | The SamplePod Family fit. | -| DET-1 | Blocks-go-live | The Xspress3 fluorescence detector: vendor (Quantum Detectors?), element count, energy resolution. Source shows 4 channels (C1-C4) plus a second unit. | One `EnergyDispersiveSpectrometer` Asset presenting the Sensor Role; specs blank. | The detector Model and element count. | -| CAM-1 | Blocks-go-live | Which pixel detectors are physically installed and active? Source has Merlin (x2), Eiger 1M, and Dexela; some classes are duplicated (`USE_RASMI`-gated). | Merlin1, Eiger1, Dexela1 modelled as Cameras; dormant duplicates excluded. | The detector roster and the per-scan detector slot. | -| DIAG-1 | Nice-to-have | The scaler / ion-chamber flux channel map (which channel is I0 for ptycho normalization). | Read-only flux counters, channel map blank. | The FluxCounter bindings. | - -### Controls and techniques - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DRIVE-1 | Blocks-go-live | The motion-controller box models, firmware, serials, and IPs. HXN exposes the controller PVs (Power PMAC `Ppmac:1` + `MC:2-8`; Attocube `ANC350:1-8`), which FXI did not, but vendor/firmware detail is still not in source. | Families bound (MotionController), models named where evident (PMAC, Attocube), specifics blank. | The MotionController Models and Drive identities. | -| ZEBRA-1 | Nice-to-have | Is `nanoZebra` (`Zeb:3`) the live trigger master, and is the PandABox (`67-nano-panda`, currently partly commented) the go-forward box? | One live Zebra; PandA deferred. | The TimingController set. | -| ENERGY-1 | Nice-to-have | Does an energy change co-move the zone-plate refocus per element edge, and is that table operator-data or a CORA Calibration? | Energy axis drives the monochromator; the optic co-move is noted, not modelled. | The energy-change Method shape. | diff --git a/docs/deployments/i-tomcat/notes.md b/docs/deployments/i-tomcat/notes.md deleted file mode 100644 index 2e7e54daa3d..00000000000 --- a/docs/deployments/i-tomcat/notes.md +++ /dev/null @@ -1,114 +0,0 @@ -# Notes - -## Techniques - -*What I-TOMCAT is designed to do, as intent. Modelling exercise.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../psi/index.md#the-techniques-adapted-here) is how a facility adapts it. The PSI Practices that bind these are carried pending on the [PSI site page](../psi/index.md#the-techniques-adapted-here) until PSI staff confirm them. The function view survives the eventual equipment choices, which is why it can be written from the public pages before the controls are wired. - -I-TOMCAT is a hard X-ray tomographic-microscopy beamline. Its techniques are the tomography-family Methods the catalog already carries, the same ones the APS [2-BM](../2-bm/index.md) pilot earned: - -| Technique | Catalog Method | What it is for | -| --- | --- | --- | -| Standard microtomography | [`tomography`](../../catalog/methods.md) | absorption-contrast 3D imaging on the U15 undulator, monochromatic 8-30 keV | -| Propagation-based phase contrast | [`tomography`](../../catalog/methods.md) | edge-enhanced imaging of weakly-absorbing samples (a propagation distance, not a separate fixture) | -| Fast / dynamic 4D tomography | [`streaming_tomography`](../../catalog/methods.md) | continuous high-speed acquisition via the GigaFRoST streaming camera, for in-situ dynamics | - -A few points of intent shape the model: - -- **The GigaFRoST camera is the dynamic-tomography enabler.** The PSI in-house continuous-streaming camera (up to 1255 fps full-frame, ~8 GB/s, up to ~33,875 Hz on a reduced ROI) is what distinguishes I-TOMCAT's fast and dynamic 4D tomography from a standard CT beamline. It maps to the catalog `streaming_tomography` Method, not a new one. -- **Phase contrast is a propagation distance, not a separate station.** Propagation-based phase-contrast imaging runs on the same endstation by moving the detector back from the sample; it is an acquisition mode over one set of optics, modelled under `tomography`, mirroring the 2-BM decision. -- **Grating interferometry is out of scope.** The legacy TOMCAT offered it only occasionally; it is not modelled here and is not one of the SLS Practices until staff confirm it is offered on the rebuilt beamline (TECH-1). - -The concrete acquisition recipes (scan sequences, energies, exposure) are not written yet; they join if the deployment firms toward a real connection. See [Open questions](#open-questions) for what must be confirmed first. - -## Governance - -*Who would act at I-TOMCAT, and the trust shape that would gate it. Modelling exercise.* - -Governance at I-TOMCAT follows the same model as the 2-BM pilot: people and autonomous agents are facility principals at the [PSI Site](../psi/index.md#safety-and-governance), 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). - -I-TOMCAT is a modelling exercise, so this shape is not yet instantiated. The PSI operator and safety-review structure is not public and is carried pending on the [PSI site page](../psi/index.md#safety-and-governance); CORA does not invent a PSI operator pool or review chain ahead of confirmation. - -What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the PSI Site, not on the beamline, and the beamline links up to them rather than restating them. The PSI personnel-safety-system form and interlock names are an open question (PSS-1 on [Open questions](#open-questions)). - -The concrete Zone, Conduit, and Policy instances, and the operator pool, would land if the deployment firms toward a real connection, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's I-TOMCAT content lives, the SLS 2.0 control-stack seam this exercise draws, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at I-TOMCAT | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### The seam: what CORA would replace vs drive through - -I-TOMCAT is the fleet's view of an SLS 2.0 beamline, so the control-stack boundary matters more than usual. SLS is an EPICS facility with the BEC (Beamline and Experiment Control) scan layer over ophyd introduced for SLS 2.0. - -| Layer | SLS tool | CORA seam | -| --- | --- | --- | -| Control (floor) | EPICS IOCs | **drive through** (never replaced; the floor CORA actuates and observes) | -| Scan / orchestration (edge) | BEC over ophyd | **replace** (CORA's edge replaces BEC's scan/experiment steering; the BEC-shares-ophyd nuance keeps a drive-through reading open, SEAM-1) | -| Detector / capture | the camera streaming + HDF5 writer chain | **drive through / observe** (specialized capture CORA observes) | -| Data-of-record | SciCat + the Ra/SLURM Fiji reconstruction pipeline | **replace / invert source-of-truth** (CORA owns its own Dataset; SciCat is a fact a future integration reads, not CORA's record) | - -This is the standard CORA lens (EPICS is the floor, the facility's scan/data software is named only to draw the boundary). The single most consequential call, BEC replace vs drive-through, is carried as SEAM-1 on [Open questions](#open-questions) because BEC adopts the same ophyd device model CORA's edge would. - -### What is deliberately not here yet - -- **Integration scenarios.** No `test_i_tomcat_*.py` registers I-TOMCAT Assets into the event store. Scenario code is where Assets become real, and hard-registering a modelling-exercise beamline with unconfirmed facts would commit speculative structure. It lands if the deployment firms toward a real connection. -- **Vendor Models.** No catalog Model is bound. The "(target)" models in the descriptor are [open questions](#open-questions), not bindings, because they are read from public pages and not staff-confirmed. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA has not connected to would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the I-TOMCAT team to confirm before the model can be trusted.* - -I-TOMCAT is a modelling exercise modelled from PSI's public pages and the SLS 2.0 design reports, so this page is long by design: almost every value on the [device pages](index.md) is read from a public page, not a staff-confirmed fact, and some are legacy TOMCAT specs whose validity for the rebuilt beamline is itself uncertain. Each row below is a fact the beamline team or a design report owns, not a CORA modelling choice. It is a delete-on-answer queue: when an item is answered, the answer lands in the descriptor and the row is removed (with the reason in the commit). Priorities are `Blocks-build` (needed before the model is built for real), `Blocks-go-live` (needed before first users), and `Nice-to-have`. - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-build | What are the EPICS PV prefix scheme and the BEC ophyd device handles for each I-TOMCAT device? | The PV scheme is not public and the BEC plugin is internal; CORA leaves each device handle empty. | Wiring each Asset to a real control handle. | -| SEAM-1 | Blocks-build | Does CORA's edge replace BEC's scan/experiment orchestration, or drive through it at the ophyd/`bec_messages` boundary? | CORA's edge replaces BEC's scan steering, conducting over EPICS; the shared ophyd device model keeps a drive-through reading open. | The control-stack seam boundary. | -| PSS-1 | Blocks-build | What are the PSS permit signals and access-interlock names for the optics and experiment hutches? | Both hutches exist with permit signals to be named. | The Enclosure permit signals. | -| ENC-1 | Blocks-go-live | Is `X02SA` genuinely the rebuilt I-TOMCAT, and what is the optics/experiment hutch grouping? | `X02SA` is I-TOMCAT (corroborated by the `/sls/x02sa/` raw-data path); two hutches, optics shared with S-TOMCAT. | The enclosure model and sector binding. | - -### Sources and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-go-live | What are the U15 undulator period and gap range, and when does the HTSU10 source upgrade land? | A U15 undulator now, HTSU10 in 2027; period/gap to be named. | The InsertionDevice settings. | -| MACHINE-1 | Nice-to-have | What are the SLS 2.0 storage-ring state handles (current, fill) CORA observes? | Observe-only ring state, handles to be named. | The StorageRing observation handles. | -| MONO-1 | Blocks-go-live | Do the legacy DCMM optics (multilayer stripes, Si(111), energy range) still describe the rebuilt beamline? | The legacy fixed-exit DCMM, 8-50 keV (8-30 recommended), carried until confirmed. | The Monochromator / Window / Filter specs. | -| OPT-1 | Nice-to-have | What are the focusing / harmonic-rejection mirror coatings and handles? They are not on the public pages. | A focusing mirror exists but is deferred (not invented) until named. | The Mirror model. | -| OPT-2 | Nice-to-have | What is the beam-defining slit blade-axis map and the handles? | Beam-defining slits ahead of the endstation; axis map to be named. | The Slit model. | - -### Endstation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| STAGE-1 | Blocks-go-live | Is the rotation stage the Aerotech ABRX150, and are its specs (~1500 deg/s) final? | The "(target)" ABRX150, used as the trigger master clock. | The rotary stage Model binding. | -| SAMPLE-1 | Blocks-go-live | What are the sample positioning axis set, the slip-ring channel count, and the fast-shutter model? | A centring stage, a continuous-rotation slip ring, and a dose-limiting fast shutter; details to be named. | The sample-stage models. | -| TRIG-1 | Blocks-go-live | Does the air-bearing rotary TTL feed the camera triggers directly, or is a conditioner needed? | Direct rotary-master triggering; may evolve once camera trigger requirements firm. | The trigger / sync chain. | - -### Detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | Which camera models are installed (the pco.edge family, pco.dimax, and the PSI GigaFRoST)? | Three cameras at the stated design-target sensors/speeds; models unbound. | The camera Model bindings. | -| DET-2 | Blocks-go-live | What is the microscope optics model, and does it compose the cross-facility `Microscope` Assembly the way 2-BM does? | A `Housing` with `Objective` + `Scintillator` constituents, 1x-40x; Assembly composition deferred. | The microscope Model and Assembly composition. | - -### Techniques - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Which tomography Practices does the rebuilt beamline offer (e.g. is grating interferometry offered)? | Standard + phase-contrast + dynamic 4D tomography; grating interferometry out of scope. | The SLS Practices that bind the catalog Methods. | diff --git a/docs/deployments/i03/notes.md b/docs/deployments/i03/notes.md deleted file mode 100644 index 9e61588cc9d..00000000000 --- a/docs/deployments/i03/notes.md +++ /dev/null @@ -1,118 +0,0 @@ -# Notes - -## Techniques - -*What I03 is designed to do, as intent. Design-phase.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../diamond/index.md) is how a facility adapts it. I03 is the first macromolecular-crystallography (MX) beamline CORA has looked at, so its techniques are new Methods over the spine. Which enter scope is an open question (TECH-1); the function view below survives the eventual vocabulary choices. - -| Technique | Beam | Detector | Status in CORA | -| --- | --- | --- | --- | -| Rotation (oscillation) data collection | monochromatic, focused | `Eiger` (Detector Role) | new Method binding Goniometer + Eiger + SampleShutter, pending (TECH-1) | -| Grid scan / sample location | monochromatic, focused | `Eiger` + `OAV` | new Method over the Zebra/PandA fast grid scan, pending (TRIG-1, TECH-1) | -| Autonomous sample exchange | n/a | n/a | a Procedure over the spine + a Subject custody thread, pending (ROBOT-1) | -| Fluorescence / anomalous element ID | monochromatic | `FluorescenceDetector` (Sensor) | deferred until the detector is modelled (DET-1) | - -A few points of intent shape the model: - -- **MX data collection is a new Method, not a new Capability shape.** A rotation data collection sweeps the goniometer omega while the Eiger captures frames, gated by the fast sample shutter. The device Roles already exist (the graduated Goniometer presents Positioner, the Eiger presents Detector); what is new is the recipe binding them. The catalog tomography Methods do not fit (they bind RotaryStage + Camera + Scintillator, not Goniometer + Eiger), so MX earns its own Methods (TECH-1). -- **The autonomous loop is a Procedure plus Subject custody, not a device.** The unattended exchange (load pin, thaw, centre, collect, unmount, next) is the genuinely new and non-obvious part of MX automation. CORA expresses it as an orchestrated Procedure over the spine, threaded through the `Subject` aggregate (custody Received to mounted-on-goniometer to measured to Returned / Stored) and gated by a Clearance issued after a safety review. The robot itself is just a Positioner; the workflow is the modelling (ROBOT-1). -- **Energy change is a Method, not the dodal composite.** dodal couples the undulator and DCM through the `UndulatorDCM` composite, which owns no motors and is being retired upstream. CORA dissolves it into an `energy_change` Method binding the undulator gap and the DCM energy with the lookup-table perp/offset compensation (ENERGY-1). -- **Grid scan is a Method, not a device.** dodal exposes the fast grid scan only as devices (`ZebraFastGridScan`, `PandAFastGridScan`); CORA models the scan as a Method over the goniometer + detector driven by the timing hardware, not as an Asset (TRIG-1). - -The concrete recipes (oscillation ranges, exposure, grid parameters, the exchange sequence) are calibration the deployment must supply. See [Open questions](#open-questions) for what must be confirmed first. - -## Governance - -*Who would act at I03, and the trust shape that would gate it. Design-phase.* - -Governance at I03 follows the same model as the CORA pilots: people and autonomous agents are facility principals at the [Diamond Site](../diamond/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). - -I03 is the second beamline at the Diamond Site (after I22), so it reuses the Diamond facility envelope rather than creating a new one: the Diamond operator pool, the safety review structure, and the safety forms are facility-wide and inherited. I03 adds only its own beamline-bound principals, carried pending on the [Diamond Site page](../diamond/index.md). This is the same reuse pattern 7-BM follows at APS, the opposite of the new-Site work I22 did. - -Because I03 is a modelling exercise, the concrete trust shape is not instantiated. What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the Diamond Site, not on the beamline, and the beamline links up to them. The Diamond PSS clearance is carried pending because its form names are not confirmed (PSS-1). - -One governance shape is sharper at I03 than at the other deployments: **autonomous sample handling**. The sample-changing robot would run unattended, so its operation must be gated. Following the 19-BM precedent (ROBOT-1), CORA models this as a Clearance that must be Active before the robot may load, issued after a separate safety review of the changer. The robot is one Positioner-presenting Asset; the autonomy is governed by the Clearance, and the sample it carries is tracked as a `Subject` through a custody lifecycle, not as part of the device. None of that is built yet; the seam is reserved, not invented (ROBOT-1). - -The off-roadmap question SCOPE-1 applies here as at I22: whether Diamond becomes a real CORA Site is unanswered. The concrete Zone, Conduit, and Policy instances, the operator pool, and the robot Clearance would land if the beamline approaches real scope, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's I03 content lives, the one catalog Family it graduates (`Goniometer`), and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at I03 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### The one catalog change: graduating Goniometer - -I03 is the first Diamond deployment to earn a new catalog Family. The catalog had carried `Goniometer` as pending (documented, not yet defined). I03's `Smargon` is CORA's first canonical six-axis MX goniometer (omega / chi / phi rotation plus x / y / z sample-centring, with centre-of-rotation control), so it is the deployment that graduates Goniometer from pending to a defined Family. The Family stays a bare role-noun; chi-vs-kappa and axis-count variants are per-Asset settings or a bound Model, not Family splits. The per-axis decomposition and centre-of-rotation calibration are carried pending (GONIO-1). - -### What is deliberately not here yet - -- **New Capabilities / Methods and vendor Models.** I03 graduates Goniometer (an already-pending Family with a canonical instance) but earns no new Capabilities or Methods in this scaffold; the MX recipes are carried pending. No catalog Model is bound. -- **The robot as a Family.** An adversarial new-kind review refuted a `SampleChanger` Family: the robot is one Positioner-presenting Asset (the 19-BM / 32-ID position), with the sample a `Subject` and autonomy a Clearance. The robot's shape is deferred to ROBOT-1, not minted. -- **Integration scenarios.** No `test_i03_*.py` registers I03 Assets. Hard-registering a design-phase, off-roadmap beamline would commit speculative structure. -- **The endstation Assembly.** The goniometer + aperture-scatterguard + backlight + cryostream are carried flat; an MX-endstation Assembly (the 2-BM SampleTower analogue) is promoted only when a feature must act on the whole (ASSEMBLY-1). -- **Operations and experiment views.** A runbook for an unmodelled beamline would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the I03 team (and Diamond's documentation) to confirm before the model can be trusted.* - -I03 is modelled from Diamond's open [`dodal`](https://github.com/DiamondLightSource/dodal) controls library, treated as a dry, correct DATA source. dodal gives the device shape and the EPICS PV handles at high confidence; it does not give the calibrated numbers, the hutch / PSS safety structure, the passive beam-path tier, or the Capability / Method binding. This page collects what dodal cannot supply. Each row is a fact the beamline team (or a Diamond drawing / the published I03 beamline paper) owns, not a CORA modelling choice. It is a delete-on-answer queue: when an item is answered, the answer lands in the descriptor and the row is removed. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -As at I22, the EPICS PV prefix for every device is already recorded in the descriptor (the dodal dry fact), so wiring handles is not a question here. The questions are the layers above that, concentrated on the two new MX shapes: the goniometer and the autonomous sample-exchange robot. - -### Scope and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SCOPE-1 | Nice-to-have | Is I03 (or any Diamond beamline) actually intended to enter CORA scope, or is this a generalization exercise against an open controls source? | A generalization exercise: I03 graduates the Goniometer Family and stresses autonomous sample handling; it is not on the pilot roadmap. | Whether Diamond is a real Site or a modelling fixture. | -| PSS-1 | Blocks-build | What are the Diamond PSS search-and-secure permit signals for the optics and experiment hutches? | Both hutches exist with permit signals to be named; dodal does not carry them. | The Enclosure permit signals. | -| ENC-1 | Blocks-build | Which hutch does each device sit in? dodal PV prefixes encode functional zones (OP, MO, EA, DI), not the access-gated hutch or its safety meaning. | The standard Diamond MX optics + experiment hutch split. | The per-device Enclosure assignment. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-build | What are the undulator energy range, period, minimum gap, harmonic, and gap-to-energy curve? dodal carries only the lookup-table path and harmonic ~3. | An undulator source with the dodal harmonic; energy range and curve are calibration to supply. | The `Undulator` parameters and the beamline energy range. | -| ENERGY-1 | Nice-to-have | dodal couples the undulator and DCM (the UndulatorDCM composite, itself being retired upstream). Should CORA model energy change as one Method binding the undulator gap + DCM energy + perp/offset compensation? | Yes: an `energy_change` Method over the two real Assets, not a device; the composite dissolves. | The energy-change seam shape. | -| OPT-1 | Nice-to-have | What are the mirror coating stripes and bimorph (22-channel) calibration, and the DCM crystal cut, d-spacing, and thermal model? dodal exposes the axes, the Si crystal, and the channel/temperature counts, not the calibrated settings. | The optic internals are per-Asset settings or a bound Model on the existing `Mirror` / `Monochromator` Families. | Which optic internals are modelled and where. | -| MACHINE-1 | Nice-to-have | How should the machine-level storage-ring state be modelled: a loose `StorageRing` source, an observe-only `GenericProbe`, or a facility-shared read model? | A loose `StorageRing` family bound observe-only, reused from I22. | The machine-state modelling boundary. | - -### Diagnostics and feedback - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DIAG-1 | Blocks-go-live | The beam-position (QBPM) and flux (Flux, IPin) monitors bind the graduated Sensor Families; what beam-center calibration do they need? | The existing Sensor Role: beam position via the graduated `PositionMonitor` catalog Family (distinct from `FluxMonitor` by measuring position rather than flux), flux via the graduated `FluxMonitor` catalog Family (rule-of-three i22/i03/i15-1); beam-center is calibration to supply. | The beam-center calibration for the diagnostics. | -| FEEDBACK-1 | Nice-to-have | Is the XBPM feedback loop a modelled CORA construct, or floor (an EPICS control loop CORA observes but does not own)? | Floor: the feedback loop is not a CORA Asset; carried with its modelling deferred. | Whether the feedback loop is modelled or stays on the floor. | - -### Sample and the autonomous loop - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| GONIO-1 | Blocks-go-live | What are the Smargon axis details (omega / chi / phi + x / y / z, centre-of-rotation control, wrapped omega), and is the chi axis a mini-kappa? The Goniometer Family is graduated; the per-axis decomposition and CoR calibration are pending. | One `Goniometer` Asset with per-axis children; chi-vs-kappa and axis-count are settings, not Family splits; CoR is a calibration. | The goniometer per-axis Assets and CoR calibration. | -| ROBOT-1 | Blocks-go-live | What is the sample-changing robot, how is autonomous loading gated, and what is the Subject custody lifecycle (dewar / puck / pin queue)? | One Positioner-presenting Asset loading / unloading a `Subject`, gated by a Clearance that must be Active, vendor in a bound Model (the 19-BM ROBOT-1 shape); not a new Family. | The robot Asset, its Clearance gate, the Subject custody thread, and the autonomous loop. | -| ENV-1 | Blocks-go-live | Must CORA command the sample-environment setpoints (the cryostream temperature, the thawer), or only read them back? | The settable-actuator shape is now settled: both bind the graduated `TemperatureController` Family (presents `Regulator`, requires `Settable`). What is open is whether CORA commands the setpoints. | The command-vs-read decision. | -| ASSEMBLY-1 | Nice-to-have | Should the goniometer + aperture-scatterguard + backlight + cryostream compose an MX-endstation Assembly (the analogue of 2-BM's SampleTower), and is the cryostream inside it or co-located? | Carried flat in this scaffold; an Assembly is promoted only when a feature must act on the whole. | The endstation `parent_id` grouping. | - -### Detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | What are the Eiger threshold energy and beam-center, the detector-translation axis ranges, and how is the retractable fluorescence detector (and the sample backlight) modelled? | The Eiger reuses `Camera`; the fluorescence detector presents Sensor (loose); the backlight binds the catalog `Backlight` Family; calibration to supply. | The detector calibration and the loose fluorescence modelling. | - -### Techniques, triggering, identity - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Blocks-go-live | Which MX Capabilities and Methods are in scope (rotation data collection binding Goniometer + Eiger + Shutter; grid scan; OAV pin-tip centring), and are they new Capabilities or Methods under existing ones? | New Methods over the spine, carried pending on the [Diamond Practices](../diamond/index.md); the catalog tomography Methods do not fit MX as-is. | Which Capabilities and Methods the catalog earns. | -| TRIG-1 | Nice-to-have | How do the Zebra and PandABox bind to the goniometer, detector, and shutter, and is the fast grid scan a Method (not a device)? dodal exposes grid scan only as devices. | One or two `TimingController` devices carry the scheme; the fast grid scan is a Method / Plan, not a device. | The triggering binding and the grid-scan modelling. | -| ID-1 | Nice-to-have | What are the hardware identities (serial numbers, asset tags) for the devices? dodal carries none. | Assets carry no part / serial identity until supplied. | The Asset hardware-identity fields. | diff --git a/docs/deployments/i06/notes.md b/docs/deployments/i06/notes.md deleted file mode 100644 index f4bf5fdf04d..00000000000 --- a/docs/deployments/i06/notes.md +++ /dev/null @@ -1,210 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of i06 is designed to do, as intent. Scaffold.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../diamond/index.md#the-techniques-adapted-here) is how a facility adapts it. i06's techniques all sit in one family: polarization-driven dichroism. Every one of them turns the X-ray polarization at an absorption edge and reads the change in contrast, whether that contrast is an absorption spectrum, an electron image, or a diffraction peak. So i06's modelling story is not a new recipe over the spine; it is a new acquisition axis (the polarization) that the existing soft X-ray Methods now drive. - -i06 is CORA's first APPLE-II source, so it is the first beamline that can set that axis at all. It is also CORA's first PEEM (photoemission electron microscopy) endstation, an electron-imaging technique whose defining instrument (the electron-optical column and its image detector) is not yet a CORA device (PEEM-1). The function view below survives both: it describes what each technique does, while the catalog vocabulary and the deferred instruments are carried as questions. - -### The polarization-driven dichroism family - -i06 carries four techniques, all pending in CORA's catalog. Two share Methods already pending from the 4-ID soft X-ray deployment; two are new pending slugs. - -| Technique | CORA Method | Contrast it reads | Status in CORA | -| --- | --- | --- | --- | -| X-ray magnetic circular dichroism (XMCD) | `xmcd` | absorption difference between circular-positive and circular-negative polarization at a magnetic edge | shares the 4-ID `xmcd` Method, pending (TECH-1) | -| X-ray magnetic linear dichroism (XMLD) | `xmld` | absorption difference between two linear-polarization angles at a magnetic edge | new pending slug `xmld` (TECH-1) | -| Photoemission electron microscopy (PEEM) | `photoemission_microscopy` | magnified electron image of the photoemitting surface, with polarization-driven magnetic / electronic contrast | new pending slug, the imaging detector deferred (PEEM-1) | -| Resonant soft X-ray diffraction / dichroism | `resonant_scattering` | a diffraction peak whose intensity tracks order (magnetic / charge / orbital) as the polarization and energy are tuned through resonance | shares the 4-ID `resonant_scattering` Method, pending (TECH-1) | - -Each technique adapts to i06 as a Site Practice on the [Diamond Site](../diamond/index.md#the-techniques-adapted-here): `I06_xmcd_practice`, `I06_xmld_practice`, `I06_peem_practice`, and `I06_resonant_diffraction_practice`, all pending. The Practices render unlinked until the owner decides whether each Method enters the catalog (TECH-1, PEEM-1). - -A few points of intent shape the family: - -- **The four techniques differ in what reads the contrast, not in how the contrast is made.** XMCD and XMLD read it as an absorption spectrum on the i06-1 stages; PEEM reads it as a magnified electron image at the i06-2 endstation; resonant diffraction reads it as the intensity of a Bragg peak on the i06-1 diffractometer. The shared move underneath all four is the same: set or turn the polarization at an absorption edge and observe the difference. That shared move is the new primitive (see below), and it is why XMCD and resonant scattering can reuse the Methods 4-ID already carries rather than coin i06-specific ones. - -- **Two techniques reuse 4-ID Methods; two are new.** XMCD and resonant soft X-ray diffraction are the same Methods CORA already carries pending from the 4-ID deployment, so i06 is a second consumer rather than a coiner: the second consumer is the graduation watch-item for both. XMLD and photoemission microscopy have no existing Method that fits, so they are new pending slugs (`xmld`, `photoemission_microscopy`). Whether any of the four enters CORA's catalog as a Capability is an owner decision (TECH-1, PEEM-1). - -- **PEEM is an imaging technique, and its instrument is not modelled yet.** PEEM is distinct from the electron-energy analysis of ARPES (the ESM endstation): ARPES analyses the energy and angle of photoelectrons, while PEEM forms a magnified spatial image of where they came from. The instrument that forms that image, the electron-optical column and its magnified electron-image detector, is absent from dodal and is deferred (PEEM-1). CORA models the PEEM sample manipulators now (they reuse the graduated `Manipulator` Family), and the column and image detector land once their PV handles are sourced. The `photoemission_microscopy` Method is the technique view of the same deferral: the recipe is named, the imaging instrument it would bind is not yet coined. - -- **Resonant diffraction and XAS reuse the i06-1 geometry, and the detectors are deferred.** The i06-1 diffractometer (sample circles plus the detector arm) and the absorption stage are modelled now (DIFF-1, STAGE-1), but the i06-1 scattering detector and any incident-flux or drain-current electron-yield monitor are absent from dodal and are not invented (DET-1). So the techniques that read a diffraction peak or an absorption spectrum carry their detector as pending: the geometry that aims the beam is in the model, the device that records the signal is bound later. - -### Polarization as a new operating axis for the fleet - -The genuinely new thing i06 brings is not a Method; it is an axis. An APPLE-II undulator can drive its magnetic phase rows to choose the X-ray polarization, not just set a gap, so for the first time in the fleet a run can ask for a polarization the way it asks for an energy. - -i06 models this as a [`PseudoAxis`](../../catalog/families.md), a sibling of the incident-energy pseudo-axis over the same source (the 2-BM beam-energy precedent, extended to a second driven source quantity). The shape is: - -- **Set the polarization on the APPLE-II.** The axis's value domain is the polarization set the source can produce: linear horizontal (LH), linear vertical (LV), linear at an arbitrary angle (LA), circular positive (PC), circular negative (NC), plus third-harmonic variants (POL-1). The run names a value; CORA writes it; the source's phase rows move to produce it. - -- **Flip or rotate it at an absorption edge to make the contrast.** XMCD flips between PC and NC at a magnetic edge and reads the absorption difference. XMLD rotates between two linear angles. Resonant diffraction tunes the polarization and the incident energy together through a resonance. In every case the contrast is the change the polarization causes, so turning the polarization at the edge is the acquisition primitive the whole dichroism family is built on. - -- **The conversion stays on the live controller.** The polarization-to-phase kinematics (how a requested polarization becomes a phase-row position) is the axis's partition rule, and it is carried rule-less by default: the live i06 controller owns the conversion, so CORA names the axis and records the move without duplicating a second source of truth for the source geometry (POL-1). Pinning the conversion as a CORA-owned Calibration is deferred until a run needs to scan polarization without that controller in the loop. The same asymmetry the source-axis wiring carries (only the upstream IDU exposes the driven polarization handle in dodal) is an open question (POL-2). - -This is the new acquisition primitive expressed entirely by reuse. The polarization axis is a `PseudoAxis` and the source is an `InsertionDevice`; no new device Family appears. What is new is that a run now carries a polarization alongside its energy, and the dichroism Methods drive both. - -### Not modelled yet - -The intent above is the function view. The concrete recipes that turn it into runnable acquisition are deliberately not written, because writing them for a beamline CORA does not yet drive would be invention rather than record: - -- **The concrete dichroism recipes.** The per-edge energy and polarization sequences, the dwell and averaging, the field and temperature setpoints for an in-situ measurement, and the PEEM imaging sequence are calibration the deployment must supply. None of it is invented here. - -- **Whether each Method enters the catalog.** Minting a Method is owner-scope. XMCD and resonant scattering reuse 4-ID Methods, and XMLD and photoemission microscopy are new slugs, but all four render pending until the owner decides (TECH-1, PEEM-1). The decision is recorded on the [Model](#model) page, not made here. - -- **The PEEM imaging instrument.** The PEEM electron-optical column and its magnified electron-image detector are deferred (PEEM-1): they are the `ElectronMicroscope` anatomy, distinct from the photon `Camera` and from the energy-analyzing catalog `ElectronAnalyzer`, and they are not coined here because they have no PV in dodal. - -- **The i06-1 detectors and flux monitor.** The diffraction scattering detector and the incident-flux / drain-current monitor are absent from dodal and are bound later from outside it, with no detector Family invented in the meantime (DET-1). - -For the source and optics that feed these techniques, see the generated source-walk on [the beamline page](source.md). For what the i06 team must confirm before the model can be trusted, see [Open questions](#open-questions). The CORA-owned scope decisions (the polarization Calibration, the deferred Methods, the diffractometer Assembly) are recorded on the [Model](#deliberately-not-here-yet) page. - -## Governance - -*Who would act at i06, and the trust shape that would gate it. Scaffold.* - -Governance at i06 follows the same model as the other Diamond beamlines: people and autonomous agents are facility principals at the [Diamond Site](../diamond/index.md#safety-and-governance), 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). - -i06 is a further beamline at the Diamond Site, so it reuses the Diamond facility envelope rather than creating a new one: the operator pool, the safety review structure, and the safety forms are facility-wide and inherited, shared with the soft X-ray and MX siblings (I22, I03, I15-1, I11, I24). i06 adds only its own beamline-bound principals. The Diamond operator pool and review structure are site-level and shared across the beamlines, so they are not yet instantiated per beamline; they are carried pending on the [Diamond Site page](../diamond/index.md#safety-and-governance) (GOV-1). None of this is in dodal, which is a controls library, not an organizational record. - -Because i06 is a reverse-engineered scaffold rather than a pilot, the concrete trust shape is not instantiated. What is already settled is the boundary, the same as for every deployment: clearances (the safety forms that must be active to start) are issued at the Diamond Site, not on the beamline, and the beamline links up to them rather than restating them. The Diamond personnel safety system (PSS) clearance is carried pending because its form names are not confirmed. - -### The Enclosures i06 gates - -The beamline spans three enclosures, the grouping CORA's Zone would follow (ENC-1): - -| Enclosure | PV zone | What it holds | -| --- | --- | --- | -| i06-optics | BL06I (optics spine), SR06I (the APPLE-II servo crates) | the PGM, the twin APPLE-II controllers, and the i06-branch PEEM sample stage | -| i06-1 | BL06J | the diffraction-dichroism endstation | -| i06-2 | BL06K | the PEEM endstation | - -How the two endstations share the source, and whether the three PV zones are three separate hutches, is the beamline team's to confirm (ENC-1). The Zone grouping is named here, not built. - -### The safety tier behind the beam - -The safety tier behind the beam is the personnel safety system. On a soft X-ray beamline the leaves that must be satisfied before the beam can enter an enclosure are the PSS search-and-secure permit signals, and the photon and front-end shutters are what those leaves gate. Both the permit signals and the shutters are absent from dodal, so CORA does not name them and does not invent them: the Enclosure permit signals and the shutters are carried pending (PSS-1). When staff confirm the signal and shutter handles, they bind to the Enclosure as the permit leaves the way the Diamond siblings carry theirs. No interlock, PSS, or equipment-protection tier is invented in the meantime. - -The hazard classes i06 brings to that envelope are those of a soft X-ray UHV beamline: - -- **An intense, variable-polarization beam.** i06 is the fleet's first APPLE-II source, so the beam's polarization is a driven experiment axis (LH / LV / PC / NC / LA plus third-harmonic variants over 70-2200 eV), not a fixed property. The radiation hazard is the standard photon-shutter concern the PSS gates (PSS-1); the polarization axis adds optics state, not a new safety tier. -- **Ultra-high vacuum on the optics and both endstations.** The soft X-ray optics and the two endstations run under UHV (SUP-1). The hazard is the vacuum envelope itself, the same class the PEEM and diffraction-dichroism endstations carry. -- **In-situ temperature environments.** The i06-1 endstation carries two Lakeshore 336 controllers for sample cooling and heating (TEMP-1). The sample environment spans a temperature range whose limits are pending; the hazard is the cryogen and heater envelope at the sample. - -Where these become Clearance-gated operation (for example any unattended or hazardous run) is the shape the Diamond siblings reserve, not instantiated here. - -### What is deliberately not modelled - -- **The PSS permit signals and shutters (PSS-1).** Absent from dodal, carried pending, not invented. -- **The Diamond operator pool and review structure (GOV-1).** Site-level and shared across the beamlines, carried pending on the Diamond Site, not instantiated per beamline. -- **The concrete Zone, Conduit, and Policy instances.** Named as the trust shape, not built; they would land if and when the beamline approaches real scope, following the [2-BM governance](../2-bm/governance.md) shape. - -The deferred detectors (the i06-1 scattering detector and the PEEM electron-image column, DET-1 and PEEM-1) are equipment, not governance, decisions; they live on [Model](#deliberately-not-here-yet). The full delete-on-answer queue is on [Open questions](#open-questions). - -## Model - -*The developer's by-kind index: where each CORA aggregate's i06 content lives, why this first APPLE-II deployment coins no new family and models polarization as an axis, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at i06 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (the polarization PseudoAxis) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes i06 new - -i06 is CORA's first APPLE-II (variable-polarization) source. The fleet's other insertion devices set a gap; an APPLE-II additionally drives its magnetic phase rows to choose the X-ray polarization, so i06 is the first beamline whose run sets the polarization as an experiment axis: linear horizontal or vertical, linear at an arbitrary angle, circular positive or negative, and third-harmonic variants. That is what magnetic dichroism needs (the X-ray magnetic circular and linear dichroism contrast comes from flipping or rotating the polarization at an absorption edge). i06 is also CORA's first PEEM (photoemission electron microscopy) endstation, an electron-imaging technique distinct from the electron-energy analysis of ARPES. - -The novelty forces no new device families. It is carried by two reuse decisions and two deferrals (below). The genuinely new modelling primitive, polarization as a driven axis, is expressed by reusing the existing `PseudoAxis` Family, the same way incident energy is already a pseudo-axis. - -### No new families - -i06 coins no new Family and changes nothing in the catalog. The four devices that could have tempted a new kind all fold into existing vocabulary: - -- **The two APPLE-II undulators bind the catalog `InsertionDevice`, not a new source family.** An APPLE-II is the same source-undulator anatomy as the EPUs already bound by SIX, CSX, and ESM. The catalog `InsertionDevice` Family already "spans the undulator and the wiggler; the device type and its gap / field parameters are a per-Asset settings difference." The APPLE-II variable-polarization phase rows, the EPICS energy-to-gap polynomial lookup, and the coordinating controller are per-Asset settings and the bound Model (they are how the gap and phase are driven), not a new device class. This resolves the long-standing `SRC-1` question toward reuse: a second concordant variable-polarization source confirms the existing Family stretches, rather than earning a split. - -- **Polarization is a `PseudoAxis`, not a new primitive.** The thing an i06 run sets, the polarization, is modelled as a `PseudoAxis` Asset, a sibling of the incident-energy pseudo-axis over the same source. The polarization value domain (LH / LV / PC / NC / LA plus third-harmonic variants) is the axis's value set, and the controller's polarization-to-phase conversion is its partition rule. This is exactly the 2-BM beam-energy-as-pseudo-axis precedent, extended to a second driven source quantity. CORA names the axis, writes the value, and records the move; by default the live i06 controller owns the polarization-to-phase kinematics (the partition rule is carried rule-less, `POL-1`), so CORA does not duplicate a second source of truth for the optics geometry. - -- **The PEEM sample manipulators bind the graduated `Manipulator`.** The PEEM endstation's UHV sample manipulators (x / y / phi plus the energy-slit translation) reuse the `Manipulator` Family graduated on SIX and ESM; the energy-slit axis and axis count are per-Asset settings. - -- **The PGM binds `GratingMonochromator`, the diffractometer binds `Goniometer`, the Lakeshores bind `TemperatureController`.** All three reuse families the soft X-ray and diffraction siblings already earned. - -### Deliberately not here yet - -- **The PEEM electron-imaging column and detector (`PEEM-1`).** The PEEM technique's defining instrument, the electron-optical column that forms a magnified electron image of the photoemitting surface, is not a dodal device (dodal binds the PEEM sample manipulator and its energy slit, not the column or the image detector). It is the `ElectronMicroscope` anatomy: an electron-imaging column, distinct from the photon `Camera` (which produces a Frame from photons) and from the energy-analyzing catalog `ElectronAnalyzer` (the ESM / ARPES electron-energy analyzer). It is deferred as `PEEM-1`, not coined: binding a family with no PV would create an orphan, so the column and detector land once their handles are sourced. i06's PEEM branch is then a candidate first sighting for an `ElectronMicroscope` family. - -- **The i06-1 diffraction detector and the flux monitors (`DET-1`).** The i06-1 scattering detector and any incident-flux or drain-current (electron-yield) monitor are absent from dodal (only the detector-arm motors are present). The geometry is modelled now; the detectors are bound later from outside dodal, and no detector Family is invented in the meantime. - -- **The diffractometer Assembly (`DIFF-1`).** Whether the i06-1 sample circles plus the detector arm compose an `Assembly(Diffractometer)` is deferred, exactly as 4-ID, 8-ID, and CSX deferred materializing their soft X-ray diffractometer Assemblies in descriptor mode. The first cut is a flat `Goniometer` Asset plus a reciprocal-space `PseudoAxis`, with the Assembly named as the follow-on. - -- **The XMCD / XMLD / PEEM Methods.** Whether magnetic dichroism, photoemission microscopy, and resonant soft X-ray diffraction enter CORA's catalog as Capabilities / Methods is an owner decision; the Practices render unlinked, pending. XMCD and resonant scattering share the 4-ID Methods; XMLD and photoemission microscopy are new pending slugs (`TECH-1`, `PEEM-1`). - -- **The polarization Calibration (`POL-1`).** Pinning the polarization-to-phase conversion as a CORA-owned LookupTable Calibration revision (rather than letting the live i06 controller own it) is deferred; it is only needed if CORA must scan polarization without the i06 controller in the loop. - -- **The simulated devices and full asset-tree scenarios.** No `test_i06_*.py` registers the 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). - -## Open questions - -*What CORA needs the i06 team to confirm before the model can be trusted.* - -i06 was reverse-engineered from the beamline's own bluesky device layer ([DiamondLightSource/dodal](https://github.com/DiamondLightSource/dodal): the `src/dodal/beamlines/i06*.py` factories and the `src/dodal/devices/` classes), so the control handles on the [device pages](index.md) are the beamline's real PVs, read from dodal rather than confirmed by staff. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | Are the PV zones BL06I (optics spine), BL06J (i06-1), and BL06K (i06-2) three separate hutches, and how do the two endstations share the source? | Three enclosures: a shared `i06-optics` zone and the `i06-1` and `i06-2` experiment hutches. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The two APPLE-II undulator periods, the gap range, and how the downstream (IDD) and upstream (IDU) devices coordinate to feed the branches. | Two `InsertionDevice` Assets; period and coordination carried pending. | The source Asset detail. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MACHINE-1 | Nice-to-have | The storage-ring state i06 reads (current, fill, machine mode). | Observe-only machine state on `SR-DI-DCCT-01` / `CS-CS-MSTAT-01` / `SR-CS-FILL-01`, a loose `StorageRing`. | The machine-state observation. | -| MONO-1 | Blocks-go-live | The plane-grating monochromator gratings (line densities), the cff fixed-focus constant, and the incident-energy range and partition rule. | A soft X-ray PGM bound to `GratingMonochromator`, 70-2200 eV, gratings 150 / 400 / 1200 l/mm; the energy pseudo-axis decomposes to the PGM and the APPLE-II gap. | The monochromator and incident-energy Assets. | -| POL-2 | Blocks-go-live | The IDD / IDU asymmetry: only the upstream IDU exposes the driven energy / polarization handles in dodal, while the downstream IDD stops at its controller. Should CORA expose a symmetric IDD handle? | The energy and polarization pseudo-axes are over the upstream IDU; the IDD is a sibling `InsertionDevice` Asset. | The source-axis wiring. | - -### Beam axes: polarization - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| POL-1 | Blocks-go-live | The polarization value domain (LH / LV / PC / NC / LA plus third-harmonic variants) and the polarization-to-phase conversion: should CORA pin the conversion as a LookupTable Calibration, or run the polarization pseudo-axis rule-less and let the live i06 controller own the kinematics? | A `PseudoAxis` over the APPLE-II phase rows, value domain as listed, carried rule-less by default (the controller owns the conversion). | The polarization-axis modelling. | - -### Diffraction-dichroism endstation (i06-1) - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DIFF-1 | Blocks-go-live | The i06-1 diffraction-dichroism circle roles (sample theta incidence, chi / phi orientation, the DET:2THETA / DET:Y detector arm) and whether they compose an Assembly. | A `Goniometer` for the sample circles plus a detector arm; the `Assembly(Diffractometer)` is named, not built. | The diffractometer geometry; the CORA structural modelling is on [Model](#deliberately-not-here-yet). | -| DIFF-2 | Nice-to-have | The reciprocal-space coordination over the diffraction-dichroism circles (the inverse-kinematics rule). | A reciprocal-space `PseudoAxis` over the circles, the rule deferred as on 4-ID / 8-ID / CSX. | The reciprocal-space Asset. | -| STAGE-1 | Nice-to-have | Whether the absorption-stage theta (and the diffractometer chi / phi) warrant a `Goniometer` plus Assembly rather than the `LinearStage` placeholder. | The absorption stage bound to `LinearStage` as a design-phase placeholder. | The absorption-stage Family. | -| TEMP-1 | Nice-to-have | The Lakeshore 336 cooling and heating ranges and channel assignment. | Two `TemperatureController` Assets presenting the `Regulator` Role; cooling-vs-heating a per-Asset setting; ranges pending. | The temperature-control modelling. | -| DET-1 | Blocks-go-live | The i06-1 diffraction scattering detector and any incident-flux / drain-current (electron-yield) monitor: both are absent from dodal. | Not modelled as devices: the geometry is modelled now and the detector(s) bound later from outside dodal; no detector Family invented. | The detector modelling. | - -### PEEM endstation (i06-2) - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MANIP-1 | Blocks-go-live | The PEEM sample-manipulator axis sets (the i06-2 `peem` x / y / phi plus the es energy-slit translation, and the i06-branch sample stage). | Two `Manipulator` Assets reusing the graduated Family; axis sets carried pending. | The manipulator modelling. | -| PEEM-1 | Blocks-go-live | The PEEM electron-optical column and its magnified electron-image detector: both are absent from dodal. | Not modelled: the electron-imaging column is the `ElectronMicroscope` anatomy, deferred until its PVs are sourced; not coined here. | The PEEM imaging-detector modelling; the CORA family decision is on [Model](#deliberately-not-here-yet). | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the EPICS PV handles read from dodal current and correct? | The handles in the descriptor are taken from dodal and carried confirm. | Verifying each Asset's control handle. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit signals and the photon / front-end shutters (absent from dodal). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent (the soft X-ray optics and the UHV endstations) and the cooling supply. | Photon beam, cooling water, and ultra-high vacuum on the optics and endstations. | The Supply observations. | -| GOV-1 | Nice-to-have | The Diamond operator pool and safety-review structure (site-level, shared across the beamlines). | Carried pending on the Diamond Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Blocks-go-live | Do the soft X-ray dichroism and resonant-scattering techniques (XMCD, XMLD, resonant diffraction) enter CORA's catalog as Capabilities / Methods? | Deferred: carried as pending Practices; XMCD and resonant scattering share the 4-ID Methods, XMLD is a new pending slug; none coined. | The dichroism / resonant Capabilities. | diff --git a/docs/deployments/i10/notes.md b/docs/deployments/i10/notes.md deleted file mode 100644 index fcdd0c7fef0..00000000000 --- a/docs/deployments/i10/notes.md +++ /dev/null @@ -1,225 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of i10 is designed to do, as intent. Scaffold.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../diamond/index.md#the-techniques-adapted-here) is how a facility adapts it. i10 (BLADE) is i06's soft X-ray twin: the fleet's second APPLE-II source, sharing the twin-APPLE-II and PGM spine, feeding two endstations that study magnetic materials. Its techniques sit in the same family i06 already named, polarization-driven contrast, but i10 reads that contrast two ways i06 does not: it resolves the polarization of the scattered beam (the RASOR analyzer arm), and it makes the contrast under an applied magnetic field at low temperature (the i10-1 magnets). - -So i10's modelling story is mostly reuse. The polarization acquisition axis already exists from i06, and three of i10's four Methods are already pending in CORA's catalog. What i10 adds on top is two affordances, polarization analysis and applied-field dichroism, expressed against families CORA already carries rather than new recipes over the spine. The function view below describes what each technique does, while the catalog vocabulary and the deferred decisions are carried as questions. - -### The four techniques - -i10 carries four techniques, all pending in CORA's catalog. Three reuse Methods already pending from earlier soft X-ray deployments; one is a new pending slug. - -| Technique | CORA Method | Contrast it reads | Status in CORA | -| --- | --- | --- | --- | -| Resonant soft X-ray scattering | `resonant_scattering` | a diffraction peak whose intensity tracks magnetic / charge / orbital order as the polarization and energy are tuned through resonance | shares the 4-ID `resonant_scattering` Method, pending (TECH-1) | -| Soft X-ray reflectivity | `reflectivity` | the specularly reflected intensity versus angle and energy, sensitive to depth structure and magnetic profile (the R in RASOR) | new pending slug `reflectivity` (TECH-1) | -| X-ray magnetic circular dichroism (XMCD) | `xmcd` | absorption difference between circular-positive and circular-negative polarization at a magnetic edge, here in an applied field | shares the 4-ID `xmcd` Method, pending (TECH-1) | -| X-ray magnetic linear dichroism (XMLD) | `xmld` | absorption difference between two linear-polarization angles at a magnetic edge, here in an applied field | shares the i06 `xmld` slug, pending (TECH-1) | - -Each technique adapts to i10 as a Site Practice on the [Diamond Site](../diamond/index.md#the-techniques-adapted-here): `I10_resonant_scattering_practice`, `I10_reflectivity_practice`, `I10_xmcd_practice`, and `I10_xmld_practice`, all pending. The Practices render unlinked until the owner decides whether each Method enters the catalog (TECH-1). - -A few points of intent shape the four: - -- **The four split across two endstations by what reads the contrast.** Resonant scattering and reflectivity read it at the RASOR endstation: the contrast is the intensity of a scattered or reflected beam on the diffractometer, observed through point and current-integrating detection (DET-1). XMCD and XMLD read it at the i10-1 / I10J magnet endstation: the contrast is an absorption difference observed as total-electron-yield, fluorescence, or diode signal while a magnetic field is applied to the sample (DET-1, MAG-1). Underneath all four is the same shared move that i06 named: set or turn the polarization at an absorption edge and observe the difference. - -- **Three techniques reuse existing Methods; one is new.** Resonant scattering and XMCD are the same Methods CORA already carries pending from the 4-ID deployment, and XMLD reuses the i06 slug, so for those three i10 is a second (or third) consumer rather than a coiner: the second consumer is the graduation watch-item. Reflectivity has no existing Method that fits, so it is a new pending slug. Whether any of the four enters CORA's catalog as a Capability is an owner decision (TECH-1), recorded on the [Model](#model) page, not made here. - -- **Resonant scattering and reflectivity reuse the RASOR geometry, and the science detector is a flux monitor.** The RASOR diffractometer (the two-theta scattering arm with sample theta, chi, chamber X, and alpha) is modelled now as a `Goniometer` (DIFF-1), with a reciprocal-space `PseudoAxis` over it (DIFF-2). There is no area detector at RASOR, so the scattered-beam point detector, the incident-flux monitor, the fluorescence channel, and the drain-current / total-electron-yield channel all bind the catalog `FluxMonitor` family through their current amplifiers (DET-1). The geometry that aims and reads the beam is in the model; the recipe that sequences a scan or a reflectivity curve is calibration the deployment supplies later. - -- **XMCD and XMLD here are field-and-temperature techniques.** At i10-1 the contrast is made not just by turning the polarization but by applying a magnetic field with the sample held cold. The magnets are modelled (MAG-1), the cryostat stage and its temperature controller are modelled (TEMP-1), and the i10-1 point detection is again a `FluxMonitor` (DET-1). The applied-field affordance is what distinguishes i10's XMCD / XMLD from i06's, and it is the second of the two things i10 adds (see below). - -### The polarization axis, reused from i06 - -The polarization acquisition axis is not new with i10. i06 brought it to the fleet first: an APPLE-II undulator drives its magnetic phase rows to choose the X-ray polarization, not just set a gap, so a run can ask for a polarization the way it asks for an energy. i10 is the fleet's second APPLE-II source and reuses that axis unchanged. - -i10 models it as a [`PseudoAxis`](../../catalog/families.md) over the twin-APPLE-II phase rows, a sibling of the incident-energy pseudo-axis over the same source. The shape is: - -- **Set the polarization on the APPLE-II.** The axis's value domain is the polarization set the source can produce: linear horizontal (LH), linear vertical (LV), circular positive (PC), circular negative (NC), and linear at an arbitrary angle (LA), plus third-harmonic variants (POL-1). The continuous linear-arbitrary-angle is the continuous realization of the LA value within this same axis, not a second axis and not a new family. The run names a value; CORA writes it; the source's phase rows move to produce it. - -- **Turn it at an absorption edge to make the contrast.** XMCD flips between PC and NC at a magnetic edge and reads the absorption difference. XMLD rotates between two linear angles. Resonant scattering tunes the polarization and the incident energy together through a resonance. In every case the contrast is the change the polarization causes, so turning the polarization at the edge is the acquisition primitive the whole family is built on. - -- **The conversion stays on the live controller.** The polarization-to-phase kinematics is carried rule-less by default: the live i10 controller owns the conversion, so CORA names the axis and records the move without duplicating a second source of truth for the source geometry (POL-1). Both undulators are driven sources, and whether the polarization handle is wired over one axis or two is an open question (ENERGY-1). - -So far this is i06's primitive expressed by reuse: the polarization axis is a `PseudoAxis`, the source is an `InsertionDevice`, and no new device Family appears. i10 then adds two things i06 does not carry. - -#### What i10 adds: polarization analysis of the scattered beam - -RASOR does not only set the incident polarization; it can resolve the polarization of the scattered beam. The motorized analyzer arm (the PaStage / POLAN arm, with its analyzer two-theta and theta, py and pz, and eta motors) selects a scattered-polarization channel, which is what lets resonant scattering separate the magnetic and charge contributions to a peak rather than read only its total intensity. This is the analysis half of polarization: i06 turns it, i10 also reads it back. - -CORA models that arm as the catalog `PolarizationAnalyzer` Family. This is a deliberate modelling choice: dodal exposes only the arm's motors, and the analyzer crystal is implicit hardware, but RASOR's defining polarization-analysis role lives on that real motorized arm, so CORA models the arm rather than hiding the role. The analyzer crystal specifics are not invented (POL-2). The Family has graduated across 4-ID / i10 / ID32 / P09, presenting Positioner; the analyzer-crystal spec stays a per-Asset detail to confirm (POL-2). - -#### What i10 adds: applied-field dichroism - -The i10-1 / I10J endstation makes the dichroic contrast under an applied magnetic field, with the sample held at low temperature. Two magnet devices serve it: a set-and-read electromagnet and a superconducting magnet whose field can be swept (a Flyable affordance). CORA models both as the single graduated `Magnet` family: they are one family, and the field sweep is a per-Asset affordance, not a split (MAG-1). i10-1 was the `Magnet` family's second sighting after 4-ID, and with the later ESRF ID32 magnet it reached a rule-of-three and graduated into the catalog (MAG-1). The field values and the sweep specifics are not invented (MAG-1). - -The applied field is what makes i10's XMCD / XMLD different from i06's: i06 reads dichroism from the polarization alone, while i10 reads it with a field applied and the sample cold. The cryostat low-temperature stage folds into the catalog `LinearStage`, and the magnet temperature is held by a catalog `TemperatureController` (TEMP-1). As with the polarization axis, no new device Family is coined for either addition: the analyzer binds the graduated catalog `PolarizationAnalyzer`, and the magnets are the graduated `Magnet` family, whose rule-of-three i10-1 helped complete. - -### Not modelled yet - -The intent above is the function view. The concrete recipes that turn it into runnable acquisition are deliberately not written, because writing them for a beamline CORA does not yet drive would be invention rather than record: - -- **The concrete recipes.** The per-edge energy and polarization sequences, the reflectivity angle and energy scans, the polarization-analysis channel selections, the field and temperature setpoints for an in-situ measurement, and the dwell and averaging are all calibration the deployment must supply. None of it is invented here. No energies, angles, fields, or resolutions are stated. - -- **Whether each Method enters the catalog.** Minting a Method is owner-scope. Resonant scattering and XMCD reuse 4-ID Methods, XMLD reuses the i06 slug, and reflectivity is a new slug, but all four render pending until the owner decides (TECH-1). The decision is recorded on the [Model](#model) page, not made here. - -- **The graduated analyzer and magnet families.** `PolarizationAnalyzer` has graduated to a catalog Family across 4-ID / i10 / ID32 / P09 (POL-2), so i10's analyzer arm binds the catalog Family; the analyzer-crystal spec stays uninvented as a per-Asset detail. The `Magnet` family has also graduated (i10-1 was one of its three consumers with 4-ID and ID32), so i10's magnets bind the catalog Family; only the per-Asset magnet field values stay uninvented (MAG-1). - -- **The science detectors.** Neither endstation has an area detector. The RASOR and i10-1 point and current-integrating channels bind the catalog `FluxMonitor` through their current amplifiers (DET-1); no detector Family is invented in the meantime. - -For the source and optics that feed these techniques, see the generated source-walk on [the beamline page](source.md). For what the i10 team must confirm before the model can be trusted, see [Open questions](#open-questions). The CORA-owned scope decisions (the deferred Methods, the held families, the diffractometer Assembly) are recorded on the [Model](#deliberately-not-here-yet) page. - -## Governance - -*Who would act at i10, and the trust shape that would gate it. Scaffold.* - -Governance at i10 follows the same model as the other Diamond beamlines: people and autonomous agents are facility principals at the [Diamond Site](../diamond/index.md#safety-and-governance), 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). - -i10 is a further beamline at the Diamond Site, so it reuses the Diamond facility envelope rather than creating a new one: the operator pool, the safety review structure, and the safety forms are facility-wide and inherited, shared with the soft X-ray and MX siblings (I22, I03, I15-1, I11, I24, I06). i10 adds only its own beamline-bound principals. The Diamond operator pool and review structure are site-level and shared across the beamlines, so they are not yet instantiated per beamline; they are carried pending on the [Diamond Site page](../diamond/index.md#safety-and-governance) (GOV-1). None of this is in dodal, which is a controls library, not an organizational record. - -Because i10 is a reverse-engineered scaffold rather than a pilot, the concrete trust shape is not instantiated. What is already settled is the boundary, the same as for every deployment: clearances (the safety forms that must be active to start) are issued at the Diamond Site, not on the beamline, and the beamline links up to them rather than restating them. The Diamond personnel safety system (PSS) clearance is carried pending because its form names are not confirmed. - -i10 is i06's soft X-ray twin: the two beamlines share a twin-APPLE-II and PGM spine and feed branch endstations. The governance shape is the same on both, and i10 inherits it the same way, so this page reads as the i06 page does, with the hazard classes that are particular to i10 called out below. - -### The Enclosures i10 gates - -The beamline spans three enclosures, the grouping CORA's Zone would follow (ENC-1): - -| Enclosure | PV zone | What it holds | -| --- | --- | --- | -| i10-optics | BL10I (optics spine), SR10I (the APPLE-II servo crates) | the PGM, the twin APPLE-II controllers, and the collimating and switching mirrors | -| i10-rasor | ME01D | the RASOR resonant-scattering and reflectivity endstation, with its branch focusing mirror | -| i10-1 / I10J | BL10J | the magnet endstation, with its electromagnet and superconducting magnet | - -How the two endstations share the source, and whether the three PV zones are three separate hutches, is the beamline team's to confirm (ENC-1). The Zone grouping is named here, not built. - -### The safety tier behind the beam - -The safety tier behind the beam is the personnel safety system. On a soft X-ray beamline the leaves that must be satisfied before the beam can enter an enclosure are the PSS search-and-secure permit signals, and the photon and front-end shutters are what those leaves gate. Both the permit signals and the shutters are absent from dodal, so CORA does not name them and does not invent them: the Enclosure permit signals and the shutters are carried pending (PSS-1). When staff confirm the signal and shutter handles, they bind to the Enclosure as the permit leaves the way the Diamond siblings carry theirs. No interlock, PSS, or equipment-protection tier is invented in the meantime. - -The hazard classes i10 brings to that envelope are those of a soft X-ray UHV beamline, plus the magnet endstation's own: - -- **An intense, variable-polarization beam.** i10 is the fleet's second APPLE-II source, after i06, so the beam's polarization is a driven experiment axis (LH / LV / PC / NC / LA plus third-harmonic variants, with the continuous linear-arbitrary-angle the realization of the LA value within the same axis) rather than a fixed property (POL-1). The radiation hazard is the standard photon-shutter concern the PSS gates (PSS-1); the polarization axis adds optics state, not a new safety tier. -- **Ultra-high vacuum on the optics and the endstations.** The soft X-ray optics run under UHV (SUP-1). The hazard is the vacuum envelope itself, the same class the Diamond soft X-ray siblings carry. -- **High magnetic fields at i10-1.** The i10-1 / I10J endstation carries an electromagnet (BL10J-EA-MAGC-01) and a superconducting magnet whose field can be swept (BL10J-EA-SMC-01), both modelled on the graduated catalog Magnet family (MAG-1). A superconducting magnet is a high-field environment, a class of hazard the optics and the RASOR endstation do not carry. CORA does not invent field values or sweep specifics (MAG-1); what it records is that this endstation adds a hazard class the rest of the beamline does not have. -- **Cryogenics at the sample.** The RASOR sample sits on a cryostat stage (ME01D-MO-CRYO-01) read by a Lakeshore 340 (ME01D-EA-TCTRL-01), and the i10-1 magnet endstation folds a cryostat low-temperature environment into its stages, read by a Lakeshore 336 (BL10J-EA-TCTRL-41) (TEMP-1). The hazard is the cryogen and low-temperature envelope at the sample, the same class the soft X-ray siblings carry, here paired with the magnet field at i10-1. - -Where these become Clearance-gated operation (for example any unattended or hazardous run, or a superconducting-magnet field sweep) is the shape the Diamond siblings reserve, not instantiated here. - -### What is deliberately not modelled - -- **The PSS permit signals and shutters (PSS-1).** Absent from dodal, carried pending, not invented. -- **The Diamond operator pool and review structure (GOV-1).** Site-level and shared across the beamlines, carried pending on the Diamond Site, not instantiated per beamline. -- **The concrete Zone, Conduit, and Policy instances.** Named as the trust shape, not built; they would land if and when the beamline approaches real scope, following the [2-BM governance](../2-bm/governance.md) shape. - -The RASOR analyzer arm binds the catalog `PolarizationAnalyzer` (graduated, POL-2); the analyzer-crystal spec is an equipment, not governance, detail. The graduated `Magnet` family (the magnet devices, MAG-1) is likewise equipment modelling; they live on [Model](#model). The full delete-on-answer queue is on [Open questions](#open-questions). - -## Model - -*The developer's by-kind index: where each CORA aggregate's i10 content lives, why this second APPLE-II deployment coins no new family and decides two loose families' second sighting, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at i10 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (the polarization PseudoAxis) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes i10 new - -i10 is the fleet's second APPLE-II (variable-polarization) source, after i06, and it is i06's soft X-ray twin: the same shared spine of twin APPLE-II undulators feeding a plane-grating monochromator and two branch endstations. What i10 adds is the science those endstations do with the polarization: resonant soft X-ray scattering and reflectivity on the RASOR diffractometer (with a polarization-analysis arm that resolves the polarization of the scattered beam), and X-ray magnetic dichroism with the sample in an applied magnetic field at the i10-1 endstation. - -For the modelling, i10's significance is that it brings two device families that were loose at a single beamline (4-ID) to a second sighting: the polarization analyzer and the sample-environment magnet. That second independent deployment was a step toward the rule-of-three; both families have since completed it and graduated into the catalog (PolarizationAnalyzer across 4-ID / i10 / ID32 / P09, Magnet across 4-ID / i10-1 / ID32), so i10's analyzer arm and magnets bind their catalog Families. i10 coins no new family. - -### No new families - -i10 coins no new Family and changes nothing in the catalog. - -- **The polarization decisions follow the merged i06 precedent.** The two APPLE-II undulators bind the catalog `InsertionDevice` (the phase rows, the energy-to-gap polynomial, and the controller are per-Asset settings and the bound Model). The polarization is a `PseudoAxis` Asset, a sibling of the incident-energy axis over the same source; the Pol value domain (LH / LV / PC / NC / LA plus third-harmonic variants) is the axis's value set, and the controller's polarization-to-phase conversion is its partition rule, carried rule-less (`POL-1`). i10's one addition over i06 is the continuous linear-arbitrary-angle: it is the continuous realization of the LA value within the same polarization axis, not a second axis, since the angle is meaningful only as a refinement of LA. -- **The RASOR sample circles bind `Goniometer`, with a reciprocal-space `PseudoAxis`** (the 4-ID / 8-ID / i06-1 diffractometer pattern; the Assembly is named, not built, `DIFF-1`). -- **The rest reuse existing families:** the PGM binds `GratingMonochromator`; the collimating, switching, and focusing mirrors bind `Mirror`; the slits bind `Slit`; the pinhole binds `Aperture`; the sample and magnet stages bind `LinearStage`; the Lakeshore controllers bind `TemperatureController`; and the counting chains bind `FluxMonitor`. The machine state reuses the loose `StorageRing`. - -### Loose families at a second sighting - -Two families that were used only at 4-ID reach a further sighting at i10, and both have since graduated. The promotion guard (`PROMOTION_THRESHOLD = 2`) makes a loose family used by two or more deployments require a recorded hold-or-graduate decision: the signal is mechanical, the decision stays human. `Magnet` has graduated: i10-1 was one of the three consumers (with 4-ID and ESRF ID32) whose rule-of-three earned it into the catalog, so i10's magnets now bind the graduated catalog `Magnet` Family (it presents the `Regulator` Role, the field a settable process variable). `PolarizationAnalyzer` has also graduated to a catalog Family (earned across 4-ID / i10 / ID32 / P09, presenting Positioner), so i10's RASOR arm now binds the catalog Family. - -| Loose family | Sightings | i10 binding | Decision | -| --- | --- | --- | --- | -| `PolarizationAnalyzer` | 4-ID, i10, ID32, P09 | the RASOR polarization-analysis arm (the POLAN stage) | **graduated** (`POL-2`): catalog Family across 4-ID / i10 / ID32 / P09, presents Positioner; dodal exposes the analyzer arm's motors only (the analyzer crystal is implicit hardware), so CORA models the role on the real motorized arm and binds the catalog Family | -| `Magnet` | 4-ID, i10 (i10-1), ID32 | the i10-1 electromagnet and the superconducting field-sweep magnet | **graduated** (`MAG-1`): i10-1 was one of the three consumers (4-ID + i10-1 + ID32) whose rule-of-three earned it; both magnet devices are one Family, the field-sweep capability is a per-Asset bound-Model affordance, not a split (the `InsertionDevice` / `TemperatureController` precedent); presents the `Regulator` Role (`MAG-1` now covers only the per-Asset field detail) | - -The decision to bind the RASOR PaStage to the catalog `PolarizationAnalyzer` Family (rather than to a plain detector-arm `RotaryStage` with the analyzer as a setting) is a deliberate one: RASOR's defining role is polarization analysis (the PV root is `POLAN`), and CORA models that role on the real arm rather than hiding it in a note. The absence of an analyzer-crystal signal in dodal is an absence in the data, not proof the role is absent; the analyzer-crystal spec stays a per-Asset detail to confirm (`POL-2`). - -### Deliberately not here yet - -- **No area detector; the science detector is a point counter (`DET-1`).** Neither endstation has an area detector in dodal. Detection is point and current-integrating: the scattered-beam point detector, the incident-flux monitor, and the fluorescence and drain-current / total-electron-yield channels are current-amplifier-plus-scaler chains, which bind `FluxMonitor`. Whether scattered-beam point-counting eventually earns its own Sensor Family is `DET-1`; if a future i10 area detector appears, the science detector migrates. -- **The diffractometer Assembly (`DIFF-1`) and the reciprocal-space rule (`DIFF-2`).** Named, not built, exactly as 4-ID, 8-ID, and i06-1 deferred theirs. -- **The polarization Calibration (`POL-1`).** Pinning the polarization-to-phase and the linear-arbitrary-angle conversion as a CORA-owned Calibration is deferred; it is only needed if CORA must scan polarization without the i10 controller in the loop. -- **The resonant-scattering / reflectivity / XMCD / XMLD Methods.** Whether they enter CORA's catalog is an owner decision; the Practices render unlinked, pending. Resonant scattering and XMCD share the 4-ID Methods, XMLD shares the i06 slug, and reflectivity is a new pending slug (`TECH-1`). -- **The upstream diagnostics and simulated devices.** The diagnostic screens (d1-d7 fluorescent screens and webcams) and the simulated devices are not modelled in this cut; no `test_i10_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the i10 team to confirm before the model can be trusted.* - -i10 was reverse-engineered from the beamline's own bluesky device layer ([DiamondLightSource/dodal](https://github.com/DiamondLightSource/dodal): the `src/dodal/beamlines/i10*.py` factories and the `src/dodal/devices/` classes), so the control handles on the [device pages](index.md) are the beamline's real PVs, read from dodal rather than confirmed by staff. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | Are the PV zones BL10I (optics spine), ME01D (RASOR), and BL10J (i10-1) three separate hutches, and how do the two endstations share the source? | Three enclosures: a shared `i10-optics` zone and the `i10-rasor` and `i10-1` experiment hutches. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The two APPLE-II undulator periods, the gap range, and how the downstream (IDD) and upstream (IDU) devices feed the branches. | Two `InsertionDevice` Assets; period carried pending. | The source Asset detail. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MACHINE-1 | Nice-to-have | The storage-ring state i10 reads (current, energy, fill). | Observe-only machine state, a loose `StorageRing`; the exact PVs pending. | The machine-state observation. | -| MONO-1 | Blocks-go-live | The plane-grating monochromator gratings, the cff constant, and the incident-energy range and partition rule. | A soft X-ray PGM bound to `GratingMonochromator`; gratings and range pending. | The monochromator and incident-energy Assets. | - -### Beam axes: energy and polarization - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENERGY-1 | Nice-to-have | Both APPLE-IIs are driven sources (energy_dd over IDD, energy_ud over IDU); should CORA carry one incident-energy axis or two, and how do they map to the branches? | One `BeamEnergy` `PseudoAxis` over the PGM and the APPLE-II gap; the two-source wiring pending. | The incident-energy Asset wiring. | -| POL-1 | Blocks-go-live | The polarization value domain (LH / LV / PC / NC / LA plus third-harmonic variants and the continuous linear-arbitrary-angle) and the polarization-to-phase conversion: pin it as a CORA Calibration, or run the axis rule-less and let the live controller own it? | A `PseudoAxis` over the APPLE-II phase rows; the linear-arbitrary-angle is the continuous realization of LA in the same axis; rule-less by default. | The polarization-axis modelling. | - -### RASOR endstation (i10-rasor) - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DIFF-1 | Blocks-go-live | The RASOR diffractometer circle roles (two-theta scattering arm, sample theta / chi, chamber X, alpha) and whether they compose an Assembly. | A `Goniometer` for the sample circles; the `Assembly(Diffractometer)` is named, not built. | The diffractometer geometry; the CORA structural modelling is on [Model](#deliberately-not-here-yet). | -| DIFF-2 | Nice-to-have | The reciprocal-space coordination over the RASOR circles (the inverse-kinematics rule). | A reciprocal-space `PseudoAxis` over the circles, the rule deferred as on 4-ID / 8-ID / i06-1. | The reciprocal-space Asset. | -| POL-2 | Blocks-go-live | Does RASOR run genuine polarization analysis on the PaStage (the POLAN arm), confirming the analyzer-crystal spec on the catalog `PolarizationAnalyzer` Family? | The PaStage binds the catalog `PolarizationAnalyzer` (graduated across 4-ID / i10 / ID32 / P09); dodal exposes the motors only, the analyzer crystal is implicit, so the crystal spec stays a per-Asset detail to confirm. | The analyzer-crystal spec; the graduation is recorded on [Model](#loose-families-at-a-second-sighting). | -| STAGE-1 | Nice-to-have | Whether the cryostat sample stage warrants a `Manipulator` rather than `LinearStage`, and whether the pinhole is an `Aperture` or a plain stage. | The sample stage bound to `LinearStage` (plain in-air translation); the pinhole bound to `Aperture`. | The sample-stage and pinhole Families. | -| TEMP-1 | Nice-to-have | The Lakeshore 340 (RASOR) and Lakeshore 336 (i10-1) temperature ranges and channel assignment. | Two `TemperatureController` Assets presenting the `Regulator` Role; ranges pending. | The temperature-control modelling. | -| DET-1 | Blocks-go-live | The RASOR and i10-1 detection: no area detector exists in dodal, only the current-amplifier / scaler point-counting chains (monitor, scattered-beam point detector, fluorescence, drain-current / total-electron-yield). Is the point detector best a `FluxMonitor`, or does scattered-beam point-counting earn its own Sensor Family? | The scattered-beam point detector and the monitor / fluorescence / yield channels bind `FluxMonitor`; no detector Family invented. | The detector modelling. | - -### i10-1 magnet endstation (i10-1) - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MAG-1 | Blocks-go-live | The i10-1 electromagnet and superconducting field-sweep magnet (field ranges, the sweep mode), and the low-temperature environment. | The two magnets bind the graduated catalog `Magnet` Family (one Family, the sweep is a per-Asset affordance); i10-1 was one of its three consumers with 4-ID and ID32; the cryostat folds into the stage. | The per-Asset magnet field / control detail; the family graduation is settled (see [Model](#loose-families-at-a-second-sighting)). | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the EPICS PV handles read from dodal current and correct? | The handles in the descriptor are taken from dodal and carried confirm. | Verifying each Asset's control handle. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit signals and the photon / front-end shutters (absent from dodal). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent (the soft X-ray optics and the UHV endstations) and the cooling supply. | Photon beam, cooling water, and ultra-high vacuum on the optics and endstations. | The Supply observations. | -| GOV-1 | Nice-to-have | The Diamond operator pool and safety-review structure (site-level, shared across the beamlines). | Carried pending on the Diamond Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Blocks-go-live | Do the resonant-scattering, reflectivity, and magnetic-dichroism techniques (RSXS, soft X-ray reflectivity, XMCD, XMLD) enter CORA's catalog as Capabilities / Methods? | Deferred: carried as pending Practices; resonant scattering and XMCD share the 4-ID Methods, XMLD shares the i06 slug, reflectivity is a new pending slug; none coined. | The technique Capabilities. | diff --git a/docs/deployments/i11/notes.md b/docs/deployments/i11/notes.md deleted file mode 100644 index 93dd1e8641c..00000000000 --- a/docs/deployments/i11/notes.md +++ /dev/null @@ -1,105 +0,0 @@ -# Notes - -## Techniques - -*What I11 is designed to do, as intent. Design-phase.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../diamond/index.md) is how a facility adapts it. I11 does high-resolution powder diffraction, a new science domain for CORA. Which Methods enter scope is an open question (TECH-1). - -| Technique | Beam | Detector | Status in CORA | -| --- | --- | --- | --- | -| High-resolution powder diffraction | monochromatic (DCM) | `Mythen3` strip detector on the two-theta arm, capillary `Spinner` for averaging | new Capability, pending (TECH-1) | -| Variable-temperature powder diffraction | monochromatic | same, over a temperature ramp on the thermal actuators | the variable-temperature axis that earns TemperatureController (TEMP-1) | -| Autonomous sample exchange | n/a | n/a | a Procedure over the spine + a Subject custody thread, pending (ROBOT-1) | - -A few points of intent shape the model: - -- **Powder diffraction is a new Capability, not a new device shape.** A measurement spins a capillary sample for powder averaging and sweeps the detector arm while the Mythen3 strip captures the diffraction pattern. The device Roles already exist (the diffractometer and spinner present Positioner, the Mythen3 presents Detector); what is new is the science Capability binding them (TECH-1). -- **Variable temperature is the genuinely new operating axis, and it earns an abstraction.** Powder diffraction at I11 routinely runs over a temperature ramp using the Cyberstar/Eurotherm blowers and the cryostreams. These are continuous-setpoint actuators (`set(value)`/`ramprate`), the first such cluster CORA has at rule-of-three. That earned the `TemperatureController` Family graduation and the `Regulator` Role, which landed via gate-review (TEMP-1). -- **The diffractometer is not goniometry.** Unlike I03's MX goniometer (a sample-orientation cradle, the graduated Goniometer Family), I11's theta/two_theta/delta are a sample rotation plus detector-arm angles, modelled as per-axis RotaryStage (GONIO-1). - -The concrete recipes (two-theta ranges, exposure, temperature ramps) are calibration the deployment must supply. See [Open questions](#open-questions). - -## Governance - -*Who would act at I11, and the trust shape that would gate it. Design-phase.* - -Governance at I11 follows the same model as the CORA pilots: people and autonomous agents are facility principals at the [Diamond Site](../diamond/index.md), and on the beamline they surface through the actions they take, gated by a trust shape (a Zone grouping the beamline's resources, a Conduit binding the command surfaces, and Policies). - -I11 is the fourth beamline at the Diamond Site (after I22, I03, and I15-1), so it reuses the Diamond facility envelope: the operator pool, the safety review structure, and the safety forms are facility-wide and inherited. I11 adds only its own beamline-bound principals, carried pending on the [Diamond Site page](../diamond/index.md). - -Two governance notes at I11: - -- **Autonomous sample loading is gated by a Clearance.** Like I03, the sample-changing robot + carousel would run unattended, so its operation is gated by a Clearance that must be Active, issued after a safety review; the robot is one Positioner Asset and the sample it carries is a `Subject` (ROBOT-1). -- **The TemperatureController earn touched governed vocabulary.** I11 was the rule-of-three that earned graduating the `TemperatureController` Family and a new settable-actuator Role. Because a new Role is a code change to a core BC aggregate (`SEED_ROLES`), that change was routed through the gate-review panel (3 baseline + specialist reviewers) rather than slipped into this scaffold (TEMP-1), and has since landed: `TemperatureController` is a catalog Family presenting the `Regulator` Role. The scaffold cadence stayed clean; the core-vocabulary change got its proper governance. - -Because I11 is a modelling exercise, the concrete Zone, Conduit, and Policy instances are not instantiated; the off-roadmap question SCOPE-1 applies as at the other Diamond beamlines. They would land if the beamline approaches real scope, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's I11 content lives, the settable-continuous-setpoint actuator Role it earns, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at I11 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### The earn, and why it is not in this PR - -I11 is the deployment that genuinely earns an abstraction CORA has deferred since 7-BM: a **settable-continuous-setpoint actuator**. Its four thermal actuators (two Cyberstar/Eurotherm blowers, two Oxford cryostreams) are `Locatable[float]` with `set(value)`/`setpoint`/`ramprate`/PID. After the loose `TemperatureController` family was carried at I22 and I03, I11 is the rule-of-three. - -That earns two things: - -1. **Graduating the `TemperatureController` Family** (catalog `families:` add, like I03's Goniometer). -2. **A new settable-continuous-setpoint actuator Role** (CORA had none at the time: Positioner is spatial, Controller supervises, GenericProbe is read-only). - -The Role was a **code change** to `cora.equipment.aggregates.role.SEED_ROLES`, which is drift-guarded by an exact-match test (`test_roles_match_seed_roles`), and is core cross-facility vocabulary. Per the gate-review discipline, that did not belong in a families-only scaffold PR; it was routed to a **separate, gate-reviewed change** (TEMP-1). Graduating the Family is coupled to the Role (a `TemperatureController` Family presenting a non-existent Role would be hollow), so both landed together in that change: `TemperatureController` is now a catalog Family presenting the new `Regulator` Role. This scaffold carried the actuators loose, as I22 and I03 did, and recorded the trigger. - -### What is deliberately not here yet - -- **The TemperatureController graduation + `Regulator` Role**: not part of this families-only scaffold; landed via the gate-reviewed follow-up (TEMP-1). -- **New Capabilities / Methods and vendor Models.** The powder-diffraction Method is carried pending; no Model is bound. -- **The robot as a Family.** It presents the existing Positioner Role; shape deferred (ROBOT-1). -- **Integration scenarios.** No `test_i11_*.py` registers I11 Assets. -- **Operations and experiment views.** See the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the I11 team (and Diamond's documentation) to confirm before the model can be trusted.* - -I11 is modelled from Diamond's open [`dodal`](https://github.com/DiamondLightSource/dodal) controls library, treated as a dry, correct DATA source. dodal gives the device shape and the EPICS PV handles; it does not give the calibrated numbers, the hutch / PSS safety meaning, or the Capability / Method binding. This is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Scope and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SCOPE-1 | Nice-to-have | Is I11 (or any Diamond beamline) actually intended to enter CORA scope, or is this a generalization exercise? | A generalization exercise; not on the pilot roadmap. | Whether Diamond is a real Site or a modelling fixture. | -| PSS-1 | Blocks-build | What are the Diamond PSS search-and-secure permit signals for the two hutches? | Both hutches exist; permit signals to be named. | The Enclosure permit signals. | -| ENC-1 | Blocks-build | Which hutch does each device sit in? dodal PV prefixes encode functional zones, not the access-gated hutch. | The standard optics + experiment hutch split. | The per-device Enclosure assignment. | - -*(TEMP-1, the thermal earn, is resolved: i11's four continuous-setpoint actuators triggered graduating the `TemperatureController` catalog Family and adding the `Regulator` Role with the `Settable` affordance, landed via a gate-reviewed change.)* - -### Source, optics, diffractometer - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-build | What is the I11 source and its energy range? dodal does not pin it (the Synchrotron device is facility-wide, observe-only). | A source carried `confirm`; energy range is calibration to supply. | The source and beamline energy range. | -| OPT-1 | Nice-to-have | What are the DCM crystal d-spacing and thermal model? dodal exposes the axes and the Si(111) default, not the calibrated values. | Settings / a bound Model on the existing Monochromator Family. | The mono calibration. | -| MACHINE-1 | Nice-to-have | How should the storage-ring state be modelled: loose `StorageRing`, observe-only `GenericProbe`, or a facility-shared read model? | A loose `StorageRing` family bound observe-only, reused from I22. | The machine-state modelling boundary. | -| GONIO-1 | Nice-to-have | Is the diffractometer (theta / two_theta / delta) correctly modelled as per-axis `RotaryStage` (not the I03-graduated `Goniometer`)? | Yes: theta is a sample rotation and two_theta / delta are detector-arm angles, not an MX orientation cradle. | That the diffractometer stays RotaryStage, not Goniometer. | -| DIFF-1 | Blocks-go-live | What are the diffractometer axis PVs and ranges (the dodal class was not read axis-by-axis), and the detector-arm geometry? | Per-axis RotaryStage under a DiffractometerStage Assembly; axes to confirm. | The diffractometer per-axis Assets and geometry. | -| SPIN-1 | Nice-to-have | Is the capillary spinner correctly a `RotaryStage` (a sample-rotation device for powder averaging), and what speed range? | Yes, a RotaryStage; speed is calibration. | The spinner modelling and speed range. | - -### Detector, robot, technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MYTHEN-1 | Blocks-go-live | How is the Mythen3 (a 1D position-sensitive strip detector) modelled: reuse `Camera` (Detector Role), or does a strip / PSD warrant a distinct shape? And what are its threshold / deadtime values? It is skip-flagged in dodal (issue I11-916). | Reuse `Camera` / Detector Role, with the strip-vs-2D nuance noted; calibration to supply. | The strip-detector Role choice and calibration. | -| ROBOT-1 | Blocks-go-live | What is the sample-changing robot + carousel, how is autonomous loading gated, and what is the sample custody lifecycle? | One Positioner-presenting Asset loading / unloading a `Subject`, gated by a Clearance, vendor in a bound Model (the I03 / 19-BM shape); not a new Family. | The robot Asset, its Clearance gate, and the Subject custody thread. | -| TECH-1 | Blocks-go-live | What is the powder-diffraction Capability and its Methods (binding the diffractometer + Mythen3 + spinner, often over a temperature ramp)? | A new powder-diffraction Capability not yet in the catalog, carried pending on the [Diamond Practices](../diamond/index.md). | Which Capabilities and Methods the catalog earns. | -| ID-1 | Nice-to-have | What are the hardware identities (serial numbers, asset tags)? dodal carries none. | Assets carry no part / serial identity until supplied. | The Asset hardware-identity fields. | diff --git a/docs/deployments/i13-1/notes.md b/docs/deployments/i13-1/notes.md deleted file mode 100644 index 4e898036daa..00000000000 --- a/docs/deployments/i13-1/notes.md +++ /dev/null @@ -1,157 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at I13-1: hard X-ray ptychography and coherent diffraction imaging, a [Catalog](../../catalog/methods.md) Method bound through a [Diamond Practice](../diamond/index.md#the-techniques-adapted-here). It is the fleet's first coherent lensless imaging, and its Capability is new and deferred, the more so because only the coherence-branch endstation is in source.* - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Ptychography / coherent diffraction imaging (CDI) | `ptychography` | a coherent beam is raster-scanned across overlapping points on the sample and the far-field coherent-diffraction pattern is captured at each point; the real-space image is reconstructed downstream. The fleet's first coherent lensless imaging. New Capability, pending (TECH-1) | - -The technique is recorded as a pending [Practice](../diamond/index.md#the-techniques-adapted-here) on the Diamond Site, `I13-1_ptychography_practice` (TECH-1). - -### The acquisition shape - -Ptychography is not a new kind of device, it is a way of acquiring. A coherent beam is rastered across the sample in overlapping points, the [sample stage](sample.md) moving point to point (SAMPLE-1); at each point the Merlin (the Medipix3 photon-counting detector) records the far-field coherent-diffraction pattern; and the stack of diffraction patterns, together with the known scan positions, is enough to reconstruct a real-space image of the sample. The overlap between adjacent points is what makes the reconstruction tractable. - -CDI is the same lensless-imaging idea read from far-field coherent diffraction; CORA carries the pair under the one `ptychography` Method (TECH-1). - -So the parts in source are a raster `LinearStage` (the PI piezo sample-scanning stage, SAMPLE-1) and two `Camera`s: the Merlin as the science detector that records each diffraction frame, and the Aravis / GenICam side camera for sample alignment (DET-1). The novelty lives in how they are driven and in what happens afterward, not in a new device class. - -### Why the Capability is new, and deferred - -Ptychography is a genuinely new science Capability for CORA to model as a beamline's purpose. HXN already rasters a coherent nanobeam and reconstructs from the diffraction stack, but as one of several scanning-probe modes; I13-1 is the first beamline CORA models around coherent lensless imaging as its reason for being. CORA carries the `ptychography` Method as pending rather than coining it outright, the same earn-the-abstraction discipline every new-domain technique follows (TECH-1). - -It would be tempting to read the novelty as a new device family, a "coherent imaging" class. That is the wrong axis. The coherence is a property of the beam and the acquisition, and the devices that realise it are a raster `LinearStage` and `Camera`s already in the Catalog. The new thing is a Method, an acquisition shape plus a reconstruction, and it adds no Family ([Model](#model)). - -The image reconstruction, turning the stack of far-field diffraction patterns into a real-space image, is `ComputePort` work, not a beamline Method. It runs downstream of the acquisition, not on a device on the floor. - -### Not modelled yet - -This is a deliberately partial first cut, the same posture as the sibling i20-1 scaffold. The public dodal module exposes only the coherence-branch endstation, the sample stage, the side camera, and the Merlin detector. What sits upstream is absent from source and deferred, not invented: - -- The shared I13 source and the optics that condition the coherent beam (the undulator, monochromator, mirrors, and slits) are upstream of the endstation and not in the module. They are carried as open questions, not fabricated (SRC-1, OPT-1). -- The machine state is observe-only against a loose `StorageRing`; the shared source is deferred with it (MACHINE-1, SRC-1). -- The PSS search-and-secure permit signals and the photon / front-end shutters are absent from the dodal module and carried pending, not invented (PSS-1). -- Beam-conditioning and shutter conduct paths, and the supporting infrastructure around the endstation, follow once their devices are in source (CTRL-1, SUP-1). - -Each of these is named on the [Open questions](#open-questions) page rather than guessed at. The source walk that grounds what is and is not present is the generated [beamline](source.md) view. - -## Governance - -*Who may act at I13-1 and the trust shape CORA applies. This is CORA's governance design landing on the coherence-branch endstation, not a description of the beamline's current controls authority. Scaffold, not yet instantiated.* - -People and autonomous agents are facility principals at the [Diamond Site](../diamond/index.md#safety-and-governance); on the beamline they surface through the actions they take. The human roster is not in the `i13_1` dodal module (GOV-1), so the principals are the design shape, not a registered list. This page follows the same model as the other Diamond beamlines, and the same partial-first-cut posture as the I13-1 scaffold overall: only the coherence-branch endstation is in this cut, and the shared I13 source and optics are deferred (SRC-1, OPT-1). - -### Who acts - -CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the Diamond Site. An I13-1 beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. The Diamond operator pool and review structure are site-level and shared across the beamlines, so they are not instantiated per beamline; they are carried pending on the [Diamond Site page](../diamond/index.md#safety-and-governance) (GOV-1). None of this is in dodal, which is a controls library, not an organizational record. - -### The trust boundary - -CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may drive the [sample stage](sample.md) through a ptychography raster, arm the [Merlin detector](sample.md) to record the far-field coherent-diffraction pattern, view the sample on the side camera, override a caution, or commit an alignment. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer. The Diamond proposal and cycle are a fact CORA's Campaign uses for custody. - -Because I13-1 is a reverse-engineered scaffold rather than a pilot, the concrete trust shape (the Zone grouping the coherence-branch resources, the Conduit binding the surfaces that may issue commands, and the Policies that say who may do what) is named here, not built. It would land, following the [2-BM governance](../2-bm/governance.md) shape, if and when the deployment approaches real scope. - -### The Enclosure I13-1 gates - -This cut covers a single enclosure, the grouping CORA's Zone would follow (ENC-1): - -| Enclosure | PV zone | What it holds | -| --- | --- | --- | -| `i13-1` | `BL13J` | the coherence-branch experiment hutch: the PI piezo sample-scanning stage, the Aravis / GenICam side camera, and the Merlin / Medipix3 detector | - -The shared I13 source and the I13-2 imaging branch are out of this cut and not part of the Zone here (SRC-1, OPT-1). - -### The safety tier behind the beam - -The safety tier behind the beam is the personnel safety system. The leaves that must be satisfied before the beam can enter an enclosure are the PSS search-and-secure permit signals, and the photon and front-end shutters are what those leaves gate. Both the permit signals and the shutters are absent from the `i13_1` dodal module, so CORA does not name them and does not invent them: the Enclosure permit signals and the shutters are carried pending (PSS-1). When staff confirm the signal and shutter handles, they bind to the Enclosure as the permit leaves the way the Diamond siblings carry theirs. No interlock, PSS, or equipment-protection tier is invented in the meantime. - -Clearances (the safety forms that must be active to start) are issued at the Diamond Site, not on the beamline, and the beamline links up to them rather than restating them (GOV-1). The Diamond PSS clearance is carried pending because its form names are not confirmed (PSS-1). - -### Coherent imaging under custody - -I13-1's reason for existing is coherent lensless imaging: a ptychography or coherent-diffraction-imaging acquisition raster-scans the coherent beam across the sample and records the far-field diffraction, and a real-space image is reconstructed from that diffraction stack. In CORA's model this novelty is an acquisition shape and a reconstruction, a Method, not a new device class (TECH-1); the devices it gates are a raster LinearStage and Cameras (SAMPLE-1, DET-1), and the reconstruction is ComputePort work, not a beamline device. That makes the repeated raster acquisition the place CORA's custody and trust shapes would earn their keep: the trust boundary bounds who may drive the raster and arm the Merlin detector, and the Campaign and Subject shapes carry the sample's custody and the diffraction record. - -If an autonomous Agent were added (for example to step the raster or decide when a diffraction stack is complete enough to reconstruct), it would be a facility principal scoped at the Site, governed by the same trust boundary, with each choice recorded as a [Decision](../../architecture/modules/decision/index.md). None is declared yet; with the shared source and optics deferred and the ptychography Method carried pending (SRC-1, OPT-1, TECH-1), this stays design intent. - -### What is deliberately not modelled - -- **The PSS permit signals and shutters (PSS-1).** Absent from the `i13_1` dodal module, carried pending, not invented. -- **The Diamond operator pool and review structure (GOV-1).** Site-level and shared across the beamlines, carried pending on the Diamond Site, not instantiated per beamline. -- **The shared I13 source and optics (SRC-1, OPT-1).** Upstream and absent from the module; deferred, not invented. No monochromator, mirror, slit, or undulator Asset is coined. -- **The concrete Zone, Conduit, and Policy instances.** Named as the trust shape, not built; they would land if and when the deployment approaches real scope, following the [2-BM governance](../2-bm/governance.md) shape. - -The full delete-on-answer queue is on [Open questions](#open-questions); where each device and Method lands is on [Model](#model). - -## Model - -*The developer's by-kind index: where each CORA aggregate's I13-1 content lives, why coherent imaging coins no new family, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at I13-1 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes I13-1 new - -I13-1 is CORA's first coherent lensless-imaging beamline. The fleet has tomography, XRF microprobe, and a hard X-ray nanoprobe (HXN), but no ptychography or coherent diffraction imaging (CDI). Ptychography raster-scans a coherent illumination across overlapping points on the sample and records a far-field coherent-diffraction pattern at each point; the real-space image is reconstructed downstream from the diffraction stack. That is the novelty, and it is an **acquisition shape plus a reconstruction**, a new Capability deferred as a pending Method (`TECH-1`), not a new device class. - -### No new families - -The scout that surfaced I13-1 anticipated a new "coherent imaging" device family. That is the wrong axis: coherent imaging is a Method, not a device. The devices the technique needs are a sample-scanning stage and an area detector, both of which the catalog already covers, so I13-1 coins no new Family and changes nothing in the catalog: - -- **The piezo sample-scanning stage binds the catalog `LinearStage`.** The ptychography raster is its operative motion; the fixed-angle lab-frame variant (`BL13J-MO-PI-02:FIXANG:`) is a setting on the same stage, not a separate device class (`SAMPLE-1`). -- **The Merlin photon-counting detector and the side viewing camera bind the catalog `Camera`.** The Merlin records the far-field coherent-diffraction pattern (the science detector); the side camera is for alignment (`DET-1`). -- **The machine state binds the loose `StorageRing`** (`MACHINE-1`). - -The coherent imaging itself is the `ptychography` Method, the fleet's first, carried pending (`TECH-1`). - -### Deliberately not here yet - -- **The shared I13 source and optics (`SRC-1`, `OPT-1`).** The dodal `i13_1` module exposes only the coherence-branch endstation; the undulator, monochromator, mirrors, and slits are upstream and not in the module, so they are deferred, not invented. This is the same partial-first-cut posture as I20-1. -- **The ptychography Method and the reconstruction.** Whether ptychography / CDI enters CORA's catalog as a Capability / Method is an owner decision; the Practice renders unlinked, pending (`TECH-1`). The image reconstruction from the diffraction stack is `ComputePort` work, not a beamline device. -- **The simulated devices and full asset-tree scenarios.** No `test_i13_1_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the I13-1 team to confirm before the model can be trusted.* - -I13-1 was reverse-engineered from the beamline's own bluesky device layer ([DiamondLightSource/dodal](https://github.com/DiamondLightSource/dodal), `src/dodal/beamlines/i13_1.py`), so the control handles on the [device pages](index.md) are the beamline's real PVs, read from dodal rather than confirmed by staff. This is a **deliberately partial** first cut: dodal currently exposes only the coherence-branch endstation, so the shared I13 source and optics are deferred, not invented. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | Is I13-1 its own experiment hutch, and how does it relate to the I13-2 imaging branch and the shared I13 source? | One `i13-1` experiment hutch on the `BL13J` prefix. | The Enclosure grouping. | -| SRC-1 | Blocks-go-live | The shared I13 undulator source, absent from the i13_1 dodal module. | An undulator upstream, not modelled in this partial cut. | The source Asset. | -| OPT-1 | Blocks-go-live | The shared I13 optics (monochromator, mirrors, slits), absent from the i13_1 dodal module. | Shared optics upstream, not modelled in this partial cut. | The optics Assets. | - -### Endstation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SAMPLE-1 | Blocks-go-live | The piezo sample-scanning stage axes, and the fixed-angle lab-frame variant (`BL13J-MO-PI-02:FIXANG:`): one stage with two reference frames or two stages? | One `LinearStage` (the ptychography raster); the fixed-angle frame a setting on the same stage. | The sample-stage modelling. | -| DET-1 | Blocks-go-live | The Merlin (Medipix3) detector configuration and the side viewing camera role. | The Merlin and the side camera bind `Camera`; the Merlin is the coherent-diffraction science detector. | The detector modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the EPICS PV handles read from dodal current and correct? | The handles in the descriptor are taken from dodal and carried confirm. | Verifying each Asset's control handle. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit signals and the photon / front-end shutters (absent from the i13_1 dodal module). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| MACHINE-1 | Nice-to-have | The storage-ring state I13-1 reads. | Observe-only machine state, a loose `StorageRing`; the exact PVs pending. | The machine-state observation. | -| SUP-1 | Nice-to-have | The vacuum extent of the coherent-beam path. | Photon beam, cooling water, and vacuum on the flight path. | The Supply observations. | -| GOV-1 | Nice-to-have | The Diamond operator pool and safety-review structure (site-level, shared across the beamlines). | Carried pending on the Diamond Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Blocks-go-live | Does ptychography / coherent diffraction imaging enter CORA's catalog as a Capability / Method? | Deferred: carried as a pending Practice; the fleet's first coherent diffractive imaging, no `cora.capability.ptychography` coined. | The ptychography Capability. | diff --git a/docs/deployments/i15-1/notes.md b/docs/deployments/i15-1/notes.md deleted file mode 100644 index 691de278828..00000000000 --- a/docs/deployments/i15-1/notes.md +++ /dev/null @@ -1,103 +0,0 @@ -# Notes - -## Techniques - -*What I15-1 is designed to do, as intent. Design-phase.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../diamond/index.md) is how a facility adapts it. I15-1 does total scattering / pair distribution function (PDF), a new science domain for CORA. Which Methods enter scope is an open question (TECH-1). - -| Technique | Beam | Detector | Status in CORA | -| --- | --- | --- | --- | -| Total scattering / PDF | fixed-energy, bent-Laue mono | `Eiger` (Detector Role), wide-Q on the two-theta arm | new Capability, pending (TECH-1) | -| Autonomous powder/capillary exchange | n/a | n/a | a Procedure over the spine + a Subject custody thread, pending (ROBOT-1) | - -A few points of intent shape the model: - -- **Total scattering is a new Capability, not a new device shape.** A PDF measurement captures wide-Q scattering on the Eiger across the two-theta arm at a fixed high energy. The device Roles already exist (Camera presents Detector, the mono and arm present Positioner); what is new is the science Capability binding them. Carried pending on the [Diamond Practices](../diamond/index.md) (TECH-1). -- **Energy scanning is explicitly NOT in scope here.** I15-1's bent-Laue monochromator selects a fixed energy: dodal exposes `energy_kev` as a read-only readback derived from the crystal y position via a lookup table, not a commanded or swept axis. So the pending `energy_scan` Capability is **not** earnable from I15-1's source; it must wait for a tunable XAS/EXAFS beamline whose scanning monochromator is actually instantiated in dodal (ENERGY-1). -- **The autonomous loop reuses the I03 shape.** The powder/capillary robot exchange is a Procedure over the spine threaded through the `Subject` aggregate and gated by a Clearance, the same shape as the I03 MX loop, with a powder/capillary twist instead of MX pins (ROBOT-1). - -The concrete recipes (q-ranges, exposure, the exchange sequence) are calibration the deployment must supply. See [Open questions](#open-questions) for what must be confirmed first. - -## Governance - -*Who would act at I15-1, and the trust shape that would gate it. Design-phase.* - -Governance at I15-1 follows the same model as the CORA pilots: people and autonomous agents are facility principals at the [Diamond Site](../diamond/index.md), and on the beamline they surface through the actions they take, gated by a trust shape (a Zone grouping the beamline's resources, a Conduit binding the command surfaces, and Policies). - -I15-1 is the third beamline at the Diamond Site (after I22 and I03), so it reuses the Diamond facility envelope: the operator pool, the safety review structure, and the safety forms are facility-wide and inherited. I15-1 adds only its own beamline-bound principals, carried pending on the [Diamond Site page](../diamond/index.md). - -Two governance points are worth noting at I15-1: - -- **The interlocks are governance data, not equipment.** dodal exposes a PSS hutch interlock and a goniometer interlock. CORA does not model these as Assets: an interlock is the read-only permit behind the **Enclosure** aggregate (the shipped Enclosure BC), so it is carried as the Enclosure `permit_signal`, mutated by the safety system, not by CORA (INTERLOCK-1). dodal even gives real interlock PVs here (unlike I22 / I03), carried as the permit-signal candidates pending confirmation (PSS-1). -- **Autonomous sample loading is gated by a Clearance.** Like I03, the powder/capillary robot would run unattended, so its operation is gated by a Clearance that must be Active, issued after a safety review; the robot is one Positioner Asset and the sample it carries is a `Subject` (ROBOT-1). - -Because I15-1 is a modelling exercise, the concrete Zone, Conduit, and Policy instances are not instantiated; the off-roadmap question SCOPE-1 applies as at I22 / I03. They would land if the beamline approaches real scope, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's I15-1 content lives, why it adds no catalog kinds and reinforces the existing model, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at I15-1 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### Why I15-1 adds no catalog kinds - -I15-1 was picked partly expecting it to graduate the open settable-actuator affordance from its `SafeOrBeamPositioner` sample-environment devices. A source-level adversarial eval **refuted that**, and the refutation is the modelling content of this deployment: - -- **`SafeOrBeamPositioner` folds into Positioner.** It is a `Movable` that drives a motor to two named positions (SAFE / BEAM), which is the existing Positioner Role with Indexable named positions, not a new affordance. It is also **not** a `TemperatureController`: the dodal classes are named for temperature controllers (blower / cobra / cryostream) but model only the in/out-of-beam move, so calling them `TemperatureController` would mirror the class name rather than the behaviour (intentional-modelling-not-mirroring). Modelled as `LinearStage` + Positioner / Indexable (SAFEBEAM-1). -- **The `rail` folds into Table** (the TomoWISE DetectorGantry precedent), not a new `Rail` Family (RAIL-1). -- **The interlocks fold into the Enclosure permit**, not an equipment Family (INTERLOCK-1). - -So I15-1 is a reuse + reinforce deployment: it provides the third `FluxMonitor` deployment that completed its rule-of-three graduation into the catalog, and adds a third robot-as-Positioner instance, while coining no new vocabulary of its own. That is a result, not a gap: the value is confirming the existing model absorbs a new technique cleanly. - -### What is deliberately not here yet - -- **New Capabilities / Methods and vendor Models.** The total-scattering Method is carried pending; no Model is bound. -- **The robot as a Family.** It presents the existing Positioner Role; shape deferred (ROBOT-1). -- **Integration scenarios.** No `test_i15_1_*.py` registers I15-1 Assets. -- **Operations and experiment views.** A runbook for an unmodelled beamline would be invention; see the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the I15-1 team (and Diamond's documentation) to confirm before the model can be trusted.* - -I15-1 is modelled from Diamond's open [`dodal`](https://github.com/DiamondLightSource/dodal) controls library, treated as a dry, correct DATA source. dodal gives the device shape and the EPICS PV handles; it does not give the calibrated numbers, the hutch / PSS safety meaning, or the Capability / Method binding. This is a delete-on-answer queue: when an item is answered, the answer lands in the descriptor and the row is removed. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Scope, safety, and the modelling decisions - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SCOPE-1 | Nice-to-have | Is I15-1 (or any Diamond beamline) actually intended to enter CORA scope, or is this a generalization exercise? | A generalization exercise; not on the pilot roadmap. | Whether Diamond is a real Site or a modelling fixture. | -| PSS-1 | Blocks-build | What are the Diamond PSS search-and-secure permit signals for the two hutches? dodal records interlock readbacks (BL15I-PS-IOC-02:M11:LOP, BL15I-VA-OMRON-01:INT3:ILK) but not confirmed permits. | Both hutches exist; the dodal interlock readbacks are permit-signal candidates. | The Enclosure permit signals. | -| ENC-1 | Blocks-build | Which hutch does each device sit in? dodal PV prefixes encode functional zones, not the access-gated hutch. | The standard optics + experiment hutch split. | The per-device Enclosure assignment. | -| INTERLOCK-1 | Nice-to-have | Are the PSS / gonio interlocks correctly modelled as the Enclosure `permit_signal` (not as equipment devices)? | Yes: an interlock is the read-only permit behind the Enclosure aggregate, not an Asset. | That interlocks stay on the Enclosure, not the device walk. | -| SAFEBEAM-1 | Blocks-go-live | Are the blower / cobra / cryostream correctly modelled as Positioner + Indexable SAFE/BEAM (not TemperatureController), and is the cobra/cryostream rail-interchange a Fixture-style swap or an Assembly? | Positioner with two named positions; the interchange is a Fixture-style swap (they share the ENV:X rail motor). | The sample-environment actuator shape and the exchange modelling. | -| RAIL-1 | Nice-to-have | Is the rail correctly the existing Table Family, and what are its exchange semantics? | The existing Table Family (the TomoWISE DetectorGantry precedent), not a new Rail kind. | The rail Family and exchange shape. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-build | What is the I15-1 source (it is a branch line) and its energy range? dodal does not pin it. | A source carried `confirm`; energy range is calibration to supply. | The source and beamline energy range. | -| ENERGY-1 | Blocks-go-live | Is the bent-Laue energy ever a goto-command (driving y to hit a target energy via inverse lookup), or only the fixed-selection read-only readback dodal exposes? | A read-only y-to-energy lookup readback; the pending energy_scan Capability is NOT earnable here. | Whether energy is a commandable axis and whether energy_scan applies. | -| OPT-1 | Nice-to-have | What are the bent-Laue crystal lookup table, the multilayer mirror coating, and the attenuator transmission-vs-foil table? dodal exposes the axes, not the calibrated values. | The optic internals are settings / a bound Model / a Calibration on the existing Families. | The optic calibration. | -| MACHINE-1 | Nice-to-have | How should the storage-ring state be modelled: loose `StorageRing`, observe-only `GenericProbe`, or a facility-shared read model? | A loose `StorageRing` family bound observe-only, reused from I22. | The machine-state modelling boundary. | -| ATTN-1 | Nice-to-have | Are the ATTN-01 three-stick stage and the ATTN-02 transmission selector two physically distinct attenuator stations, or two control surfaces of one unit? | Two distinct stations (separate EPICS roots), the selector folding into Filter via Indexable named positions. | The attenuator station topology. | - -### Sample, detector, technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| FLUX-1 | Blocks-go-live | How is the incident-flux monitor (the JBPM TetrAMM i0) modelled, and what beam-center calibration does it need? | The existing Sensor Role, via the `FluxMonitor` catalog Family (graduated on the i22/i03/i15-1 rule-of-three this deployment completes). | The flux-monitor modelling and beam-center. | -| ROBOT-1 | Blocks-go-live | What is the powder/capillary sample-changing robot, how is autonomous loading gated, and what is the puck custody lifecycle? | One Positioner-presenting Asset loading / unloading a `Subject`, gated by a Clearance, vendor in a bound Model (the I03 / 19-BM shape); not a new Family. | The robot Asset, its Clearance gate, and the Subject custody thread. | -| DET-1 | Blocks-go-live | What are the Eiger threshold energy and beam-center, the two-theta arm geometry, and the second detector translation ranges? | The Eiger reuses `Camera`; calibration to supply. | The detector calibration and arm geometry. | -| TECH-1 | Blocks-go-live | What are the total-scattering / PDF Capability and Methods (binding the mono + Eiger + two-theta arm + the powder robot exchange)? | A new total-scattering Capability not yet in the catalog, carried pending on the [Diamond Practices](../diamond/index.md). | Which Capabilities and Methods the catalog earns. | -| ID-1 | Nice-to-have | What are the hardware identities (serial numbers, asset tags)? dodal carries none. | Assets carry no part / serial identity until supplied. | The Asset hardware-identity fields. | diff --git a/docs/deployments/i19/notes.md b/docs/deployments/i19/notes.md deleted file mode 100644 index 4b4514aa0ba..00000000000 --- a/docs/deployments/i19/notes.md +++ /dev/null @@ -1,188 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of i19 is designed to do, as intent. Design-phase.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../diamond/index.md#the-techniques-adapted-here) is how a facility adapts it. i19 is CORA's first *chemical* crystallography beamline: small-molecule single-crystal structure solution, distinct from the macromolecular MX (I03, I24, FMX, MX3) the rest of the fleet carries. The function view below is written before the Method is coined, because it survives the eventual catalog vocabulary choice. - -### Single-crystal diffraction - -The Newport kappa four-circle goniometer orients a single crystal in the monochromatic or variable-wavelength beam, sweeps reciprocal space, and the Eiger records the scattered intensity as a function of momentum transfer. This is the same diffraction function the magnetic single-crystal stations already do; what differs at i19 is the science the data feed, not the recipe. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Single-crystal diffraction | `diffraction` | reciprocal-space scans on the kappa four-circle with the Eiger; shares the 4-ID / 8-ID / CSX `diffraction` Method, pending (TECH-1) | -| Variable-wavelength diffraction | `diffraction` | the same Method over a coordinated energy move; a Plan / settings difference, not a new Method (TECH-1) | - -This needs the [diffractometer](sample.md) (the kappa four-circle, plus the 2-theta detector arm and det_z), the [Eiger detector](sample.md), and the shared-optics energy control. A few points of intent shape how the Method binds here: - -- **Single-crystal diffraction reuses the pending `diffraction` Method.** The prior consumers are the magnetic single-crystal stations (4-ID, 8-ID, CSX); i19 is a fourth consumer of the same recipe. The Method binds a Goniometer that orients the crystal and a Camera that captures the diffracted frames. Chemical crystallography (small-molecule structure solution) versus the magnetic single-crystal science at 4-ID is a **Practice-level** difference, not a Method-level one: the I19_diffraction_practice (pending) is where the chemical adaptation lives, over the portable diffraction Method (TECH-1). -- **The kappa four-circle is plain Goniometer reuse.** kappa is a setting per the catalog Goniometer note, so the four-circle does not earn a new Family. The larger four-circle (phi / omega / kappa, the 2-theta arm, det_z, sample-centring) is the named-not-built `Assembly(Diffractometer)` composed over that Goniometer (DIFF-1). The reciprocal-space coordination binds `PseudoAxis` (DIFF-2). - -### Serial / microfocus fixed-target delivery - -i19 carries a serial / microfocus fixed-target arm: a second sample stage (x / y / z / phi) that presents many crystals to a microfocused beam on a fixed target. This is a **delivery sub-mode** of single-crystal diffraction, not a separate technique. It binds the same `diffraction` Method, with the second stage modelled as a second Goniometer (SERIAL-1). - -| Delivery | Catalog method | Notes | -| --- | --- | --- | -| Fixed-target serial collection | `diffraction` | many crystals on the serial stage; the same Method, a delivery sub-mode (SERIAL-1) | - -The one part that reaches past the present catalog is the **raster**: stepping the fixed target through a grid of positions and collecting at each would touch a grid-scan-style Method the catalog does not yet carry. Until that Method exists, the raster is carried as a note on the serial sub-mode, not modelled as its own recipe (SERIAL-1). The microfocused beam is shaped by the [MAPT pinhole and collimator](sample.md), whose aperture sizes are a Capability settings schema (the i03 MAPT precedent) (APERTURE-1). - -### Not modelled yet - -The concrete acquisition recipes are deferred: oscillation and scan ranges, exposures, the variable-wavelength sequence, and the serial raster pattern are calibration the deployment must supply, and writing them now for an unmodelled beamline would be invention, not record. They join as the deployment approaches the point where CORA drives i19. - -Whether the `diffraction` Method (and the grid-scan-style Method the raster would need) enters CORA's catalog at all is an owner-scope decision, recorded on [Model](#model); the raster's catalog gap is SERIAL-1 and the Method-coin question is TECH-1. See [Open questions](#open-questions) for the world-facts to confirm first, including which hutch holds the four-circle (ENC-1). - -## Governance - -*Who would act at i19 and the trust shape that would gate it. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority. Not yet instantiated (scaffold).* - -Governance at i19 follows the same model as the other Diamond beamlines: people and autonomous agents are facility principals at the [Diamond Site](../diamond/index.md#safety-and-governance), 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. The human roster is not in the dodal module (GOV-1), so the principals below are the design shape, not a registered list. - -Because i19 is a scaffold, the concrete trust shape is not instantiated. What is already settled is the boundary: clearances (the safety state that must be active to start) are issued at the Diamond Site, not on the beamline, and the beamline links up to them. - -### Who acts - -The Diamond operator pool runs an i19 beamtime, with a beamline scientist and a safety reviewer in the facility-wide review chain. These are the Diamond facility principals, carried pending at the [Diamond Site page](../diamond/index.md#safety-and-governance); i19 inherits them rather than coining its own (GOV-1). The Diamond proposal and cycle are a fact CORA's Campaign uses for custody. - -### The trust boundary - -i19's boundary is shaped by the Trust BC aggregates (Zone, Conduit, Policy); the [Trust module](../../architecture/modules/trust/index.md) defines what each one is. This page records only the intended i19 instances, all pending until the beamline approaches real scope. - -| Zone | Conduit | Endpoints | -| --- | --- | --- | -| `i19 Zone` | `i19 Local Conduit` | `i19 Zone` -> `i19 Zone` | - -A Policy governs who may issue which command across a Conduit. - -| Policy | Permitted principals | Permitted commands | -| --- | --- | --- | -| `i19 Operations Policy` | Diamond operator pool (GOV-1) | Operator-driven commands (Equipment, Recipe, Operation, Run, Subject, Dataset, Caution, Clearance, Supply, Campaign) | -| `i19 Agent Policy` | Diamond agent principals (GOV-1) | Decision family: `RegisterDecision`, `RateDecision`, `AppendInferences` | - -### The safety envelope - -i19 inherits the Diamond [safety envelope](../diamond/index.md#safety-and-governance). The one safety signal CORA can name today is the dodal interlocked optics shutter (`OpticsShutter`, BL19I-PS-SHTR-01), which is PSS-interlocked and bound to the Shutter family. Beyond that, the PSS search-and-secure permit signals per hutch are pending and are not invented (PSS-1). Clearances are issued at the Diamond Site and the beamline links up to them. - -### The active-hutch permit (ACCESS-1) - -i19 has two experiment hutches in series, EH1 (`i19-1`) and EH2 (`i19-2`), that share one optics line (`i19-optics`, the shared BL19I optics). This is the i19-specific governance element, and it is the genuine novelty of the deployment: only the **active** hutch may drive the shared optics. A non-active hutch may still observe the shared optics state, but it may not move them. - -dodal expresses this with a central arbiter, the i19-blueapi optics service. A hutch reads the shared-optics state directly over EPICS, but its writes (change the energy, operate the experiment shutter, move the attenuator, set a mirror piezo) are posted to the arbiter. The arbiter compares the requesting hutch against the active-hutch readback (BL19I-OP-STAT-01:EHStatus) and runs or rejects. - -CORA models this as an **Enclosure-permit plus Trust-gate** over the shared-optics Assets, not as a device family (ACCESS-1): - -- The Enclosure-permit is the active-hutch state itself: of the two Enclosures `i19-1` and `i19-2`, the one currently holding the permit is the only one whose commands against the shared `i19-optics` Assets may proceed (ENC-1). -- The Trust-gate is the Policy condition layered on the shared-optics commands: a command to change energy (`BeamEnergy`, the coordinated DCM plus undulator plus mirror-stripe move, MONO-1), operate the optics shutter (PSS-1), move the attenuator (`Attenuator`, the i03 precedent, ATTN-1), or set a focusing-mirror piezo (`HorizontalFocusingMirror` / `VerticalFocusingMirror`, with its hutch-keyed coating stripe Si 5-10 / Rh 10-20 / Pt 20-30 keV, OPT-1) is admitted only from the hutch that holds the permit. -- The i19-blueapi arbiter is the **actuate-floor seam** partner, the same "EPICS is the floor" pattern the rest of the Diamond fleet follows, here a blueapi-arbiter floor. CORA's gate decides whether the command is authorized; the arbiter remains the floor that compares the requesting hutch against the active-hutch readback and runs or rejects against EPICS. - -The shared-optics devices are single Assets, access-gated rather than duplicated per hutch: the monochromator (DCM, MONO-1), the two focusing mirrors (OPT-1), the attenuator (ATTN-1), the coordinated `BeamEnergy` pseudo-axis (MONO-1), and the optics shutter (PSS-1) all live in `i19-optics` and are reached through the permit. The undulator (`Undulator`, SR19I-MO-SERVC-01) is coordinated with the DCM on an energy move (SRC-1); the storage ring is observe-only machine state (MACHINE-1). - -None of this is instantiated yet. The Zone, Conduit, and Policy instances, the Diamond operator pool, and the active-hutch permit gate would land if the beamline approaches real scope, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's i19 content lives, why the four-circle is not the novelty and the dual-hutch access-control seam is, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at i19 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (the incident-energy PseudoAxis) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes i19 new (and what does not) - -i19 is CORA's first chemical (small-molecule) single-crystal crystallography beamline. The fleet's other diffraction-imaging crystallography is all macromolecular MX (I03, I24, FMX, MX3); i19 solves small-molecule structures on a Newport kappa four-circle goniometer with an Eiger detector, plus a serial / microfocus fixed-target arm. - -The honest framing: the instrument is **not** the novelty. The kappa four-circle is plain catalog `Goniometer` reuse: - -- The catalog `Goniometer` note states that **chi-versus-kappa and axis-count are a per-Asset setting, not a Family split**. So the phi / omega / kappa sample circles bind the catalog `Goniometer`, exactly as the i03 Smargon and the MX3 mini-kappa do. -- The larger four-circle (the goniometer plus the 2theta detector arm plus a reciprocal-space axis) composes the catalog `Assembly(Diffractometer)`, the 8-ID / 4-ID / i06-1 pattern, named-not-built in descriptor mode (`DIFF-1`, `DIFF-2`). -- The single-crystal diffraction technique reuses the pending `diffraction` Method that 4-ID, 8-ID, and CSX already share; chemical-versus-magnetic single crystal is a Practice-level science difference, not a new Method (`TECH-1`). - -What **is** genuinely new is the governance seam, below. i19 coins no new Family and changes nothing in the catalog. - -### The dual-hutch access-control seam - -i19 has two experiment hutches in series (EH1 and EH2) that share one optics line, and only the active hutch may drive the shared optics. dodal expresses this through a central arbiter (the i19-blueapi optics service): a hutch reads the shared-optics state directly over EPICS, but its writes (change energy, operate the experiment shutter, move the attenuator, set a mirror piezo) are posted to the arbiter, which compares the requesting hutch against the active-hutch readback (`BL19I-OP-STAT-01:EHStatus`) and runs or rejects the operation. - -CORA models this without a new device family: - -- **The shared-optics devices are single Assets** in the `i19-optics` enclosure (the `Monochromator`, `Undulator`, the two `Mirror`s, the `Filter` attenuator, the `Shutter`). A non-active hutch reading them read-only is the same Asset surfaced through a permit, not a second Asset. -- **The active-hutch permit is an Enclosure-permit + Trust-gate.** EH1 and EH2 are two `Enclosure`s; which one may drive the shared optics now is a permit axis on the Enclosure, governed by Trust authorization. The `BL19I-OP-STAT-01:EHStatus` readback is the read-model of that permit (`ACCESS-1`). -- **The i19-blueapi arbiter is an actuate-floor seam partner.** It is the same shape as the "EPICS is the floor" seam, here a blueapi-arbiter floor: today it performs the active-hutch arbitration; CORA's edge would conduct the run over its `ControlPort`, either driving through the arbiter or replacing its plan-orchestration per routine, a seam decision not pre-empted here. - -This is the design-interesting content of i19: an Enclosure-permit-gated actuate seam, the first dual-hutch shared-optics arbitration in the fleet. The concrete Enclosure-permit, Trust, and seam instances are named, not built, in this scaffold. - -### No new families - -Beyond the four-circle (Goniometer) and the MAPT aperture (below), the rest reuse the catalog directly: the DCM binds `Monochromator`; the focusing mirrors bind `Mirror` (the coating stripe is a hutch-keyed setting); the attenuator binds `Filter` (the i03 precedent); the undulator binds `InsertionDevice`; the Eiger and the OAV viewing cameras bind `Camera`; the Zebra and PandA hardware triggers bind `TimingController`; the serial / microfocus arm binds a second `Goniometer`; the beamstops bind `BeamStop`; the shutter binds `Shutter`; the incident energy is a `PseudoAxis`. The machine state reuses the loose `StorageRing`. - -- **The MAPT pinhole and collimator bind the catalog `Aperture` (`APERTURE-1`).** This follows the i03 ApertureScatterguard-at-MAPT precedent: the consumer-facing beam-defining Asset binds `Aperture`, composing the pinhole and collimator XY stages, with the configuration aperture sizes as a Capability settings schema. The discriminator tension (the catalog `Aperture` describes a fixed code pattern, while the MAPT is a driven, size-selectable opening) is carried as `APERTURE-1`; the i03 sibling, the same controls stack and the same MAPT, already binds `Aperture`, so i19 follows it. - -- **The sample backlight binds the catalog `Backlight` Family.** i03, i24, and fmx already bind it; i19 is a further consumer of the illumination affordance now graduated across the MX / imaging fleet (`DET-1`). i19 adds a consumer, not a new Family. - -### Deliberately not here yet - -- **The Assembly(Diffractometer) and the reciprocal-space rule (`DIFF-1`, `DIFF-2`).** Named, not built, exactly as 4-ID, 8-ID, and i06-1 deferred theirs. The 2theta detector arm is a `RotaryStage` slot of the Assembly; det_z folds as a per-Asset axis on the arm (the i06-1 precedent). -- **The serial / microfocus raster (`SERIAL-1`).** The fixed-target arm binds a second `Goniometer`; the raster sub-mode (which would touch a grid-scan-style Method that the catalog does not yet carry) is carried as a note, not modelled. -- **The Enclosure-permit + Trust-gate + actuate seam instances (`ACCESS-1`).** The dual-hutch access-control is described above and is the governance novelty, but the concrete Zone / Conduit / Policy and the arbiter-seam drive-through-versus-replace decision are named, not built, in this scaffold. -- **The diffraction Method.** Whether single-crystal diffraction enters CORA's catalog as a Capability / Method is an owner decision; the Practice renders unlinked, pending, reusing the slug 4-ID / 8-ID / CSX share (`TECH-1`). -- **The centring image-recognition behaviour and the simulated devices.** The OAV pin-tip recognition is a Method behaviour on the Camera, not a device; no `test_i19_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the i19 team to confirm before the model can be trusted.* - -i19 was reverse-engineered from the beamline's own bluesky device layer ([DiamondLightSource/dodal](https://github.com/DiamondLightSource/dodal): the `src/dodal/beamlines/i19*.py` factories and the `src/dodal/devices/` classes), so the control handles on the [device pages](index.md) are the beamline's real PVs, read from dodal rather than confirmed by staff. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology, scope, and the dual-hutch seam - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The EH1 / EH2 grouping: which experiment hutch holds the four-circle and the Eiger, and which holds the on-axis viewing, and how the two hutches sit relative to the shared optics. | A shared `i19-optics` zone feeding two experiment hutches `i19-1` (EH1) and `i19-2` (EH2); the four-circle in EH2. | The Enclosure grouping. | -| ACCESS-1 | Blocks-go-live | The dual-hutch shared-optics access-control: only the active hutch may drive the shared optics, enforced by the i19-blueapi optics arbiter against the active-hutch readback (`BL19I-OP-STAT-01:EHStatus`). How should CORA represent the active-hutch permit and the arbiter? | An Enclosure-permit + Trust-gate over the shared-optics Assets, with the arbiter as an actuate-floor seam partner (the "EPICS is the floor" pattern). | The governance seam; the CORA modelling is on [Model](#the-dual-hutch-access-control-seam). | -| SRC-1 | Nice-to-have | The undulator period and type (`SR19I-MO-SERVC-01`). | An undulator coordinated with the DCM on an energy move; period pending. | The source Asset detail. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MACHINE-1 | Nice-to-have | The storage-ring state i19 reads (current, fill). | Observe-only machine state, a loose `StorageRing`; the exact PVs pending. | The machine-state observation. | -| MONO-1 | Blocks-go-live | The DCM crystal cut, the energy / wavelength range, and the energy partition rule (the variable-wavelength capability). | A double-crystal `Monochromator`; the energy is a `PseudoAxis` over the DCM and undulator; range pending. | The monochromator and incident-energy Assets. | -| OPT-1 | Nice-to-have | The focusing-mirror coatings and the stripe energy bands (Si / Rh / Pt), and whether the stripe is hutch-keyed. | Focusing mirrors bound to `Mirror`; coating stripe a hutch-keyed setting (Si 5-10, Rh 10-20, Pt 20-30 keV). | The mirror Asset detail. | -| ATTN-1 | Nice-to-have | The absorber-wedge attenuator and whether it folds into `Filter` or earns a distinct `Attenuator` kind (the fleet-wide question). | The wedge absorber bound to `Filter` (the i03 precedent). | The attenuator's catalog home. | - -### Endstations - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DIFF-1 | Blocks-go-live | The Newport kappa four-circle circle roles (phi / omega / kappa sample circles, the 2theta detector arm, det_z, the sample centring) and whether they compose an Assembly. | A `Goniometer` (kappa a setting) plus a 2theta detector arm; the `Assembly(Diffractometer)` is named, not built. | The diffractometer geometry; the CORA structural modelling is on [Model](#deliberately-not-here-yet). | -| DIFF-2 | Nice-to-have | The reciprocal-space coordination over the four-circle (the kappa-to-eulerian / hkl rule). | A reciprocal-space `PseudoAxis` over the circles, the rule deferred as on 4-ID / 8-ID / i06-1. | The reciprocal-space Asset. | -| SERIAL-1 | Nice-to-have | The serial / microfocus fixed-target arm (`BL19I-MO-SRL-01`, x / y / z / phi) and its raster sub-mode. | A second `Goniometer` for the serial / microfocus delivery; the fixed-target raster carried as a note. | The serial-arm modelling. | -| APERTURE-1 | Nice-to-have | The MAPT pinhole + collimator microfocus aperture and whether it binds `Aperture` (the i03 MAPT precedent) despite being a driven, size-selectable opening. | The pinhole + collimator bound to `Aperture`, the configuration sizes a Capability settings schema. | The aperture Family. | -| DET-1 | Blocks-go-live | The Eiger detector model, the OAV viewing-camera roles, the beamstops, and the backlight. | The Eiger and OAVs bind `Camera`; the beamstops bind `BeamStop`; the backlight binds the catalog `Backlight`. | The detector and viewing modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the EPICS PV handles read from dodal current and correct, and is the i19-blueapi arbiter the live optics-control path? | The handles in the descriptor are taken from dodal and carried confirm; the arbiter is the actuate seam (ACCESS-1). | Verifying each Asset's control handle. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit signals and the photon / front-end shutters (absent from dodal beyond the interlocked optics shutter). | Permit leaves to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent of the shared optics. | Photon beam, cooling water, and vacuum on the optics. | The Supply observations. | -| GOV-1 | Nice-to-have | The Diamond operator pool and safety-review structure (site-level, shared across the beamlines). | Carried pending on the Diamond Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Blocks-go-live | Does single-crystal diffraction (chemical crystallography) enter CORA's catalog as a Capability / Method? | Deferred: carried as a pending Practice reusing the `diffraction` Method that 4-ID / 8-ID / CSX share; none coined. | The diffraction Capability. | diff --git a/docs/deployments/i20-1/notes.md b/docs/deployments/i20-1/notes.md deleted file mode 100644 index 4a7db133ce5..00000000000 --- a/docs/deployments/i20-1/notes.md +++ /dev/null @@ -1,95 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at I20-1: energy-dispersive EXAFS, a [Catalog](../../catalog/methods.md) Method bound through a [Diamond Practice](../diamond/index.md). It is the dispersive complement to the scanning-XAS axis, and its Capability is deferred, the more so because the dispersive devices are not yet in source.* - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Energy-dispersive EXAFS (EDE) | `energy_dispersive_exafs` | the whole absorption spectrum read in one shot off a polychromatic fan on a strip detector; time-resolved. New Capability, pending (TECH-1); the dispersive polychromator + strip detector are not yet in source (POLY-1 / STRIP-1) | -| Fluorescence-yield EXAFS | `energy_dispersive_exafs` | the same dispersive acquisition read in fluorescence on the Xspress3, a secondary mode (DET-1) | - -The technique is recorded as a pending [Practice](../diamond/index.md) on the Diamond Site. - -### Why the Capability is deferred (and the heart is an open question) - -EDE is a new science Capability for CORA: scanning XAS (NSLS-II BMM) steps a monochromator through an edge and the per-energy readings are the data, while EDE reads every energy at once off a dispersed fan. CORA carries the EDE Method as pending, the dispersive complement to the energy-scan question BMM opened (TECH-1 / the ENERGY-1 cohort), rather than coining it, the same earn-the-abstraction discipline every new-domain technique follows. - -The sharper point at I20-1 is that the two devices the Capability turns on, the bent-crystal polychromator and the position-sensitive strip detector, are not in the public dodal commissioning module. So this is a partial first cut: the technique is named and its periphery modelled (the energy-selecting turbo slit, the fly-scan PMAC and PandA timing, the fluorescence Xspress3), but the dispersive optic and detector are explicit open questions (POLY-1, STRIP-1). The polychromator in particular would be a genuinely new optic class, an energy-fanning bent crystal distinct from a `Monochromator`, that CORA would weigh as a Family once it is PV-bound; coining it now, with no source PV, would be invention. - -The spectrum extraction (turning the dispersed strip frame into an absorption spectrum) is `ComputePort` work, not a beamline Method. - -## Governance - -*Who may act at I20-1 and the trust shape CORA applies. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority.* - -People and agents are facility principals at the [Diamond Site](../diamond/index.md); on the beamline they surface through the actions they take. The human roster is not in the dodal module (GOV-1), so the principals are the design shape, not a registered list. - -### Who acts - -CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the Diamond Site. An I20-1 beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. - -### The trust boundary - -CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may arm the detector, drive the turbo-slit fly-scan, change the energy selection, override a caution, or commit a calibration. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer. The Diamond proposal and cycle are a fact CORA's Campaign uses for custody. - -### Time-resolved collection - -EDE's reason for existing is speed: a full absorption spectrum in sub-second time, so a reaction can be followed as it runs. That makes the unattended, repeated, fast acquisition the place CORA's custody and trust shapes earn their keep, the engine holds the fly-scan and the detector arming while the trust boundary bounds what may change mid-series. If an autonomous Agent were added to trigger collections on a sample-environment cue or decide when a kinetic series is complete, it would be a facility principal scoped at the Site, governed by the same trust boundary, with each choice recorded as a [Decision](../../architecture/modules/decision/index.md). None is declared yet; with the dispersive detector still an open question (STRIP-1), this stays design intent. - -## Model - -*The developer's by-kind index: where each CORA aggregate's I20-1 content lives. It hosts no content of its own. Design-phase scaffold, deliberately partial.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC -[modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at I20-1 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (EnergyAxis) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [The beamline](index.md#enclosures) (I20-1-OH optics, I20-1-EH experiment) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### Deliberately not here yet - -This is a design-phase scaffold (descriptor + docs), and a deliberately partial one: the dodal commissioning module is thin. Left out on purpose: - -- **The dispersive heart of EDE.** The bent-crystal polychromator (POLY-1) and the position-sensitive strip detector (STRIP-1), the two devices that make the technique energy-dispersive, are not in the public source, so they are named open questions, not modelled. The polychromator would be a genuinely new optic class (an energy-fanning bent crystal, distinct from `Monochromator` / `GratingMonochromator`); CORA would weigh a `Polychromator` Family once it is PV-bound, not before. Coining it from no source PV would be invention. -- **No new Family, no loose family.** What is modelled reuses existing families only: the turbo slit binds `Slit`, the PMAC `MotionController`, the PandA `TimingController`, the sample stage the graduated `Manipulator`, the Xspress3 the graduated `EnergyDispersiveSpectrometer`. -- **The mock / skip honesty.** The sample stage is a dodal `mock` (real PVs, motors being reconnected, STAGE-1); the Xspress3 is a dodal `skip` (defined, not loaded by default, DET-1). Both are carried `confirm` and flagged, not asserted live. -- **The absent source / optics / diagnostics chain.** No source, front-end, primary mirror, attenuator, ion chamber, flux monitor, or beam-position monitor is in the commissioning module; the source is carried PV-less (SRC-1) and the rest are open questions. -- **No new Capability or Method.** Energy-dispersive EXAFS is a pending Practice on the Site (the dispersive complement to the BMM energy-scan question, TECH-1); MX3-style, the technique is reinforced-and-deferred, not coined. -- **Operations and experiment views, integration scenarios, vendor Models.** A runbook and registered Assets for a beamline CORA does not yet drive, and whose primary detector is not even in source, would be invention; they land when the dispersive devices are PV-bound and the team confirms. - -## Open questions - -*What CORA needs the I20-1 team to confirm. This model is reverse-engineered from the public dodal controls library (`src/dodal/beamlines/p51.py`, the i20-1 commissioning module): the EPICS PVs are read from it, but it is a thin commissioning roster and the dispersive heart of EDE is not in it. Each row is a fact the beamline team owns. It is a delete-on-answer queue.* - -Priorities: `Blocks-build`, `Blocks-go-live`, `Nice-to-have`. - -### The dispersive heart (absent from source) - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| POLY-1 | Blocks-build | The bent-crystal polychromator that fans the energy band across the sample, the defining EDE optic. It is not in the dodal module (only the turbo slit at the polychromator enclosure `BL51P-OP-PCHRO-01` is). What are its PVs and axes (crystal bend, Bragg, position)? It is a genuinely new optic class (an energy-dispersing bent crystal, distinct from a Monochromator); CORA would weigh a new `Polychromator` Family once it is PV-bound. | Not modelled; named here, no Family coined without a source PV. | The polychromator Asset and a possible new Family. | -| STRIP-1 | Blocks-build | The position-sensitive strip detector that reads the dispersed absorption spectrum in one shot, the EDE primary detector (e.g. an XH / germanium microstrip). It is not in the dodal module. What is its PV, and does it fit `Camera` (a 1D frame) or warrant a new detector class? | Not modelled; named here, no device coined without a source PV. | The strip-detector Asset and its family. | - -### Source and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-go-live | The insertion-device source, front-end, and primary mirror: none is in the commissioning module. The PV root `BL51P` would carry them. | An insertion-device source, identity-only, no PV. | The Source and front-optics Assets. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit-leaf PVs (not in the dodal module). | The permit signal is a confirm note, not a guessed PV. | The Enclosure permit signals. | -| ENC-1 | Nice-to-have | The hutch layout and names (the dodal module exposes no enclosure structure). | An optics hutch plus an experiment hutch. | The Enclosure set and roles. | - -### Sample, detector, controls - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| STAGE-1 | Blocks-go-live | The sample alignment stage axis set and reconnection: the dodal module constructs `alignment_x` / `alignment_y` (`BL51P-MO-STAGE-01:X` / `Y`) as a mock, noting the motors are being reconnected on the beamline. | A `Manipulator` Asset (X / Y); the PVs are real but not yet connected. | The SampleStage axes and live PVs. | -| DET-1 | Nice-to-have | The Xspress3 fluorescence detector (`BL51P-EA-DET-03:`, 16-channel) is defined but constructed with `skip=True` in dodal (not loaded by default). Is it live, and what is the I0 / It / ion-chamber flux chain (none is in the module)? | One `EnergyDispersiveSpectrometer` Asset; flux chain blank. | The detector roster and flux monitors. | -| DRIVE-1 | Blocks-go-live | The PMAC trajectory controller (`BL51P-MO-STEP-06:`) and PandA box (`BL51P-EA-PANDA-01/02:`) firmware / IPs. | Families bound (MotionController, TimingController), specifics blank. | The controller Models. | -| TECH-1 | Blocks-go-live | Does the energy-dispersive-EXAFS Capability enter CORA's catalog, or stay deferred? It is the dispersive complement to the scanning-XAS / energy-scan question (the BMM ENERGY-1 cohort). | The EDE Method is a pending Practice, not yet in the catalog. | The EDE Capability scope. | diff --git a/docs/deployments/i22/notes.md b/docs/deployments/i22/notes.md deleted file mode 100644 index 2b81389a7f3..00000000000 --- a/docs/deployments/i22/notes.md +++ /dev/null @@ -1,111 +0,0 @@ -# Notes - -## Techniques - -*What I22 is designed to do, as intent. Design-phase.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../diamond/index.md) is how a facility adapts it. I22 is the first scattering beamline CORA has looked at, so its techniques are the first that do not reduce to the existing tomography and acquisition Capabilities. Which scattering Capabilities and Methods the catalog earns is itself an open question (TECH-1); the function view below survives the eventual vocabulary choices, which is why it can be written before the catalog is extended. - -| Technique | Beam | Detector | Status in CORA | -| --- | --- | --- | --- | -| Small-angle scattering (SAXS) | monochromatic, KB-focused | `SaxsDetector` (Pilatus3 2M, long camera length) | new Capability, pending (TECH-1) | -| Wide-angle scattering (WAXS) | monochromatic, KB-focused | `WaxsDetector` (Pilatus3 2M, short camera length) | new Capability, pending (TECH-1) | -| Simultaneous SAXS+WAXS | monochromatic, KB-focused | both detectors at once | coordinated Runs, the routine mode, pending (TECH-1) | -| Time-resolved SAXS/WAXS | monochromatic | both detectors, PandA-gated | new acquisition Method, deferred until confirmed | - -A few points of intent shape the model: - -- **The Capabilities are genuinely new.** Tomography reduces to the `tomography` and `acquisition` Capabilities the catalog already carries; SAXS and WAXS do not. They are the cleanest test of whether CORA's Capability layer generalizes past imaging. They are carried as pending Practices on the [Diamond Site](../diamond/index.md), not minted into the catalog, until the technique enters a real scope (TECH-1). A beamline that is a modelling exercise does not get to mint cross-facility vocabulary. -- **Simultaneous acquisition is coordinated Runs, not a combined technique.** The routine I22 mode reads the SAXS and WAXS detectors at once. CORA models that as coordinated Runs under one Campaign over a shared trigger, the same way 7-BM models energy-dispersive diffraction running alongside tomography, not as a third combined technique. -- **The detector Roles already exist.** Both detectors present the existing Detector Role; the flux monitors present the existing Sensor Role. No new Role is needed for scattering, only new science Capabilities. The device anatomy generalized cleanly; the technique vocabulary is what is new. -- **Beam mode is one focused, monochromatic path.** The undulator feeds the double-crystal monochromator and the KB mirror pair; SAXS and WAXS share that one conditioned beam, distinguished by detector position, not beam mode. - -The concrete acquisition recipes (q-ranges, camera lengths, exposure, time-resolved sequences) are not written: they are calibration the deployment must supply. See [Open questions](#open-questions) for what must be confirmed first. - -## Governance - -*Who would act at I22, and the trust shape that would gate it. Design-phase.* - -Governance at I22 follows the same model as the CORA pilots: people and autonomous agents are facility principals at the [Diamond Site](../diamond/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). - -I22 introduces the third Site CORA models, after APS and MAX IV. Unlike 7-BM (which reused the existing APS envelope) and like TomoWISE (which created MAX IV), I22 requires a new Diamond Site: the facility, its operator pool, its safety review structure, and its safety forms are all Diamond-specific and carried pending on the [Diamond Site page](../diamond/index.md) until staff confirm them. None of this is in dodal, which is a controls library, not an organizational record. - -Because I22 is a modelling exercise rather than a pilot, the concrete trust shape is not instantiated. What is already settled is the boundary, the same as for every deployment: clearances (the safety forms that must be active to start) are issued at the Diamond Site, not on the beamline, and the beamline links up to them rather than restating them. The Diamond personnel safety system (PSS) clearance is carried pending because its form names are not confirmed (PSS-1). - -One governance note is specific to the off-roadmap nature of this exercise: whether Diamond becomes a real CORA Site at all is itself an open question (SCOPE-1). Until it is answered, the Diamond Site exists as a design-phase fixture that exercises the second-Site machinery (a new Facility, new principals, new clearances) without committing CORA to operate there. - -The concrete Zone, Conduit, and Policy instances, and the Diamond operator pool, would land if and when the beamline approaches real scope, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's I22 content lives, why it earns no catalog kinds and carries real EPICS handles, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at I22 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What is deliberately not here yet - -- **New catalog Families, Capabilities, and Methods.** I22 does not earn new catalog kinds in this scaffold. An adversarial new-kind review refuted all five proposed device anatomies as catalog Families on the strength of I22 alone; four (`TemperatureController`, `FluxMonitor`, `Transfocator`, `FlowController`) have since graduated to the catalog once a rule-of-three across deployments settled them, and the remaining one (`StorageRing`) is still carried as a loose family with a tracking question. The new scattering Capabilities are carried as pending Practices. A kind is added to the catalog only when a confirmed device or technique and the naming review settle it. This follows the "pilots earn the abstractions" rule, and I22 is explicitly not a pilot (SCOPE-1). -- **Integration scenarios.** No `test_i22_*.py` registers I22 Assets into the event store. Hard-registering a design-phase, off-roadmap beamline would commit speculative structure. -- **Vendor Models.** No catalog Model is bound. The hardware dodal names (Dectris, AVT, Watson-Marlow, Linkam) is recorded in the descriptor notes, not bound. -- **Operations and experiment views.** A runbook and live experiment view for an unmodelled beamline would be invention; see the note on the [index](index.md#not-yet-documented). -- **Detector assemblies.** The two detectors are left as plain `Camera` devices. Whether the SAXS detector composes an Assembly with its beamstops and base is deferred (GROUP-1). - -What is genuinely new here versus the other scaffolds: the descriptor carries real EPICS control handles (from dodal), and the open questions are about the layers dodal cannot reach (calibration, safety, technique), not about the PVs. - -## Open questions - -*What CORA needs the I22 team (and Diamond's documentation) to confirm before the model can be trusted.* - -I22 is modelled from Diamond's open [`dodal`](https://github.com/DiamondLightSource/dodal) controls library, treated as a dry, correct DATA source. dodal gives the device shape and the EPICS PV handles at high confidence; it does not give the calibrated numbers, the hutch/safety structure, the passive beam-path tier, or the technique binding. This page collects what dodal cannot supply. Each row is a fact the beamline team (or a Diamond drawing / the published I22 beamline paper) owns, not a CORA modelling choice. It is a delete-on-answer queue: when an item is answered, the answer lands in the descriptor and the row is removed (with the reason in the commit). Priorities are `Blocks-build` (needed before the model is built for real), `Blocks-go-live` (needed before first users), and `Nice-to-have`. - -Note on what dodal already settled, so it is **not** a question here: the EPICS PV prefix for every device is recorded in the descriptor (this is the one thing I22 has that the TomoWISE scaffold did not), and the device-to-Family mapping is high-confidence. The questions below are the layers above that. - -A note on what I22 tests that the tomography pilots did not: I22 is a SAXS/WAXS scattering beamline, so its science Capabilities are new, it runs two detectors simultaneously, and it carries quantitative flux monitors and sample-environment actuators. The questions concentrate on those new shapes. - -### Scope and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SCOPE-1 | Nice-to-have | Is I22 (or any Diamond beamline) actually intended to enter CORA scope, or is this purely a generalization exercise against an open controls source? | A generalization exercise: I22 proves the dodal-seed to intentional-model pipeline and stresses the non-tomography axis; it is not on the pilot roadmap. | Whether Diamond becomes a real Site or stays a modelling fixture. | -| PSS-1 | Blocks-build | What are the Diamond PSS search-and-secure permit signals for the optics and experiment hutches? | Both hutches exist with permit signals to be named; dodal does not carry them. | The Enclosure permit signals. | -| ENC-1 | Blocks-build | Which hutch does each device sit in? dodal PV prefixes encode functional zones (OP, MO, EA, DI), not the access-gated hutch or its safety meaning. | The standard Diamond optics + experiment hutch split, with conditioning optics upstream and sample + detectors downstream. | The per-device Enclosure assignment. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-build | What are the undulator energy range, period, minimum gap, and gap-to-energy curve? dodal carries only 80 poles and 2.0 m length, plus a lookup-table path on the Diamond filesystem. | An undulator source with the dodal poles/length; the energy range and curve are calibration to supply. | The `Undulator` parameters and the beamline energy range. | -| MACHINE-1 | Nice-to-have | How should the machine-level storage-ring state (ring current, fill mode, top-up countdown) be modelled: a loose `StorageRing` source, an observe-only `GenericProbe`, or a facility-shared read model? | A loose `StorageRing` family bound observe-only, mirroring the loose beam-source representation the APS deployments use. | The machine-state modelling boundary. | -| OPT-1 | Nice-to-have | What are the mirror coatings/stripes, the DCM crystal d-spacing and thermal model, and the bimorph channel calibration? dodal exposes the axes and the Si(111) crystal and channel counts, but not the calibrated optic settings. | The optic internals are per-Asset settings or a bound Model on the existing `Mirror` / `Monochromator` Families, not new Families. | Which optic internals are modelled and where they live. | - -### Detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | Are the SAXS and WAXS camera lengths fixed mounts or settable axes (a movable detector / flight tube)? dodal carries a single distance snapshot for each. | The two detectors are one `Camera` Family at two positions; whether distance is a settable axis (warranting a detector-translation `LinearStage` Asset) is open. | Whether a detector-translation Asset is modelled. | -| DET-2 | Blocks-go-live | What are the Pilatus threshold energy and the per-detector beam-center? Both are `None` in dodal and are required for SAXS/WAXS data reduction. | Not modelled until supplied; these are calibrated, beam-energy-dependent values. | The detector calibration the data reduction needs. | -| OAV-1 | Blocks-go-live | What are the on-axis-view camera working distance and effective pixel size? dodal carries a sentinel distance (-1.0 m) and a pixel size flagged "double check". | Not modelled; both depend on viewing optics dodal does not model. | The OAV geometry. | - -### Sample environment - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| FLUX-1 | Blocks-go-live | How are the incident and transmitted ion chambers (I0 / It) modelled: a new `FluxMonitor` Family, or the existing Sensor Role with a deployment-local device? And is the incident-vs-transmitted distinction a placement setting? | The existing Sensor Role (whose docstring names ion chambers), now via the graduated `FluxMonitor` catalog Family (rule-of-three i22/i03/i15-1); incident vs transmitted is placement, not a Family split. | The flux-monitor modelling boundary. | -| ENV-1 | Blocks-go-live | Must CORA command the sample-environment setpoints (the Linkam temperature controller, the peristaltic pump), or only read them back? | The settable-actuator shape is now settled: the Linkam binds the graduated `TemperatureController` Family (presents `Regulator`, requires `Settable`); the pump binds the graduated `FlowController` Family (presents `Regulator`, the `TemperatureController` sibling, earned across i22 / 7-BM / LIX / XFP). What is open is whether CORA commands the setpoints. | The command-vs-read decision (shared with 7-BM FLOW-1). | - -### Techniques and identity - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Blocks-go-live | Which scattering Capabilities and Methods are in scope (small-angle, wide-angle, simultaneous SAXS+WAXS, time-resolved), and how is a simultaneous SAXS+WAXS acquisition represented? | SAXS and WAXS are new Capabilities not yet in the catalog; simultaneous acquisition is coordinated Runs, carried pending on the [Diamond Practices](../diamond/index.md). | Which Capabilities and Methods the catalog earns. | -| TRIG-1 | Nice-to-have | How do the PandABox FPGA boxes bind to the detectors and flux monitors (trigger fan-out, gating, the master clock)? | One or two `TimingController` devices carry the scheme, mirroring the 2-BM Timing device; the detector/flux binding is a Method concern. | The triggering-subsystem binding. | -| GROUP-1 | Nice-to-have | Does the SAXS detector share an Assembly with its beamstops and base stage, or are they independent devices? dodal models them separately. | Independent devices in this scaffold; an Assembly is earned only when a feature must act on the whole. | The `parent_id` / Assembly grouping. | -| ID-1 | Nice-to-have | What are the hardware identities (serial numbers, asset tags) for the devices? dodal carries none. | Assets carry no part/serial identity until supplied. | The Asset hardware-identity fields. | diff --git a/docs/deployments/i24/notes.md b/docs/deployments/i24/notes.md deleted file mode 100644 index 7de7baae9de..00000000000 --- a/docs/deployments/i24/notes.md +++ /dev/null @@ -1,133 +0,0 @@ -# Notes - -## Techniques - -*What i24 is designed to do, as intent. Design-phase.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../diamond/index.md) is how a facility adapts it. i24 is the first serial / fixed-target macromolecular-crystallography beamline CORA has looked at, so its technique is a new acquisition shape over the spine, not a recipe over Methods that already exist. Whether it enters the catalog as a Capability is an open question (SSX-1); the function view below survives the eventual vocabulary choice. - -| Technique | Beam | Detector | Status in CORA | -| --- | --- | --- | --- | -| Fixed-target serial crystallography | monochromatic, focused | `Eiger` (Detector Role) | a new `serial_crystallography` Capability binding the chip stage + Eiger + sample shutter + Zebra, deferred (SSX-1) | -| Chip raster fly-collection | monochromatic, focused | `Eiger` + `OnAxisViewer` | the acquisition primitive of the technique above: window-addressed, Zebra-gated, no rotation (SSX-1, CHIP-1) | -| Pump-probe excitation | monochromatic, focused | `Eiger` | PMAC-fired lasers on encoder edges; modelled as a trigger setting or a hazard, deferred (LASER-1) | -| Jungfrau commissioning collection | monochromatic, focused | `Jungfrau` (Detector Role) | the same shape on the commissioning detector; carried pending (DET-1) | - -A few points of intent shape the model: - -- **Serial collection is a new acquisition shape, not a new device.** Rotation MX at I03 sweeps the goniometer omega while the Eiger captures frames through a continuous oscillation: one crystal, one trajectory of angles. i24 does the opposite. The chip stage rasters a fixed-target chip of thousands of static crystals across the beam, and the detector takes one diffraction snapshot per addressable window, with no goniometer rotation at all. The dataset is many single-orientation patterns, indexed and merged downstream, rather than one rotation sweep. The device Roles already exist (the chip stage presents Positioner, the Eiger presents Detector, the Zebra presents the timing surface); what is new is the recipe that binds them as a window-by-window fly-collection. - -- **The catalog has no Method that fits, so i24 earns a Capability.** The tomography Methods bind RotaryStage + Camera + Scintillator over a rotation trajectory, and the I03 rotation MX Methods are a continuous omega sweep over a single crystal; neither matches a triggered raster over a grid of static samples. So serial crystallography is a new `serial_crystallography` Capability rather than a Method under an existing one. Whether it enters CORA's catalog is an owner decision, so the Practice renders pending (SSX-1). i24 is the first synchrotron consumer; the SLAC LCLS-MFX XFEL deployment already carries the same Method pending, so the second consumer is the graduation watch-item. - -- **The chip raster is hardware-sequenced, and that sequencing is the seam CORA's edge replaces.** The serial trajectory (set a window, gate the exposure, step to the next) runs on the PMAC motion controller, with the Zebra FPGA TTL-gating the detector and the fast sample shutter per window off encoder position-compare. CORA does not model the PMAC motion program or the Zebra trigger graph as devices; it drives them through EPICS as the orchestration the edge conducts. The detailed raster pattern, the per-window dwell, and the trigger timing are calibration the deployment must supply (SSX-1). - -- **The fixed-target chip is a Fixture and a Subject grid, not a PV.** The chip itself is the addressable holder the stage rasters one window at a time, and the crystals it carries are Subjects. The chip stage is a `LinearStage` Asset, but the grid geometry and the well / aperture map live in beamline software, not on a PV, so the chip-as-Fixture and the Subject grid are deferred as a CORA modelling decision (CHIP-1). Whether the chip windows are Subjects in a custody grid is the load-bearing question for the serial Subject thread. - -- **There is no sample-exchange loop to model.** Rotation MX at I03 leans on an autonomous robot that loads pins one crystal at a time, which becomes a Procedure plus a Subject custody thread. i24 has no robot and no per-crystal exchange: one chip carries thousands of crystals, loaded once and rastered as a unit. The custody thread is over the chip and its grid, not over a stream of mounted pins. - -The concrete recipe (the raster pattern, the per-window dwell, the laser and Zebra trigger timing, the chip grid map) is calibration the deployment must supply. See [Open questions](#open-questions) for what must be confirmed first. - -## Governance - -*Who would act at i24, and the trust shape that would gate it. Design-phase.* - -Governance at i24 follows the same model as the CORA pilots: people and autonomous agents are facility principals at the [Diamond Site](../diamond/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). - -i24 is a further beamline at the Diamond Site, so it reuses the Diamond facility envelope rather than creating a new one: the Diamond operator pool, the safety review structure, and the safety forms are facility-wide and inherited. i24 adds only its own beamline-bound principals, carried pending on the [Diamond Site page](../diamond/index.md). The operator pool and safety-review structure are site-level and shared across the beamlines, so they are not yet instantiated per beamline (GOV-1). This is the same reuse pattern 7-BM follows at APS, the opposite of the new-Site work I22 did. - -Because i24 is a modelling exercise, the concrete trust shape is not instantiated. What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the Diamond Site, not on the beamline, and the beamline links up to them. The Diamond PSS clearance is carried pending because its form names are not confirmed. - -The safety tier behind the beam is the personnel safety system. The hutch photon shutter is dodal's interlocked hutch shutter, which sits behind a PSS interlock; the search-and-secure permit signals are the leaves that must be satisfied before the beam can enter the enclosure. CORA reads the shutter as a `Shutter` Asset, but the PSS permit leaves are not named in the descriptor and are not invented here, so the Enclosure permit signals are carried pending (PSS-1). - -One hazard is sharper at i24 than at the rotation-MX siblings. The fixed-target serial collection rasters an addressable chip of thousands of static crystals across the chip stage, and the PMAC motion controller fires lasers on encoder edges during the raster. Whether those lasers are an excitation source CORA should model as a device or only a trigger setting with a Clearance hazard is deferred (LASER-1). If they are a hazard, the laser interlock would be gated by a Clearance issued after a separate safety review, the same shape the other deployments reserve for unattended or hazardous operation. None of that is built yet; the seam is reserved, not invented. Unlike the rotation-MX siblings, i24 has no sample-changing robot, so there is no autonomous-loading Clearance to model here. - -The off-roadmap question of whether Diamond becomes a real CORA Site is unanswered. The concrete Zone, Conduit, and Policy instances, the operator pool, and any laser Clearance would land if the beamline approaches real scope, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's i24 content lives, why this first serial-crystallography deployment coins no new vocabulary, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at i24 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes i24 new - -i24 is CORA's first serial / fixed-target crystallography. Unlike I03 rotation MX (one crystal, a continuous omega sweep), i24 raster-scans a fixed-target chip holding thousands of static crystals, taking one diffraction snapshot per addressable window, hardware-sequenced on the PMAC motion controller with Zebra TTL gating and no goniometer rotation. The novelty is the acquisition shape, a triggered chip-raster fly-collection over a sample grid, which is a new Capability deferred as a question (SSX-1). It forces no new device Family. - -### No new families - -i24 introduces no new device class. Every device reuses an existing catalog or loose Family, which is the strongest possible outcome for the families-only descriptor mode: - -- The vertical pin goniometer reuses the catalog `Goniometer`, the Family I03 graduated. -- The fixed-target chip stage (dodal's PMAC, an XYZ stage) reuses `LinearStage`. The serial raster trajectory, the encoder position-compare, and the laser triggers run on the PMAC controller; they are the orchestration seam CORA's edge replaces, not a device Family. -- The Eiger and Jungfrau detectors reuse `Camera` (Detector Role); the on-axis viewer reuses `Camera`; the Zebra reuses `TimingController`; the DCM reuses `Monochromator`; the focusing mirrors reuse `Mirror`; the attenuator reuses `Filter` (the I03 / i15-1 precedent, not a new Attenuator kind); the aperture, beamstop, and detector / chip stages reuse `Aperture` / `BeamStop` / `LinearStage`; the shutters reuse `Shutter`. -- The dual backlight binds the catalog `Backlight` Family (graduated across the MX / imaging fleet); the machine source state reuses the loose `StorageRing`. No new loose family either. - -### Deliberately not here yet - -- **The fixed-target chip as a Fixture / Subject grid (`CHIP-1`).** The chip is a holder of thousands of static crystals that the stage rasters one window at a time. The chip stage is a `LinearStage` Asset; the chip itself (the addressable grid, the well / aperture map) is a Fixture, and the crystals are Subjects, a CORA modelling decision. The grid map lives in beamline software, not a PV, so it is carried as the open `CHIP-1` rather than modelled now. Whether the chip windows are Subjects in a custody grid is the load-bearing question for the serial Subject thread. - -- **The serial-crystallography Capability (`SSX-1`).** The chip-raster fly-collection (set a window, gate the exposure, step to the next) is a new acquisition Capability. Whether it enters CORA's catalog as a Method is an owner decision; the Practice renders unlinked, pending. i24 is the first synchrotron consumer; the SLAC LCLS-MFX XFEL deployment carries the same Method pending, so the second consumer is the graduation watch-item. - -- **The PMAC laser triggers (`LASER-1`).** The PMAC fires lasers via M-variables on rising / falling encoder edges. Whether these are a pump-probe excitation source CORA should model as a device, or only a trigger setting and a Clearance hazard, is deferred. - -- **The collection-Assembly question.** Whether the goniometer, chip stage, and detector compose an Assembly is deferred, as the other Diamond deployments deferred their Assemblies in descriptor mode; the first cut is flat Assets. - -- **The simulated devices and full asset-tree scenarios.** No `test_i24_*.py` registers the i24 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). - -## Open questions - -*What CORA needs the i24 team to confirm before the model can be trusted.* - -i24 was reverse-engineered from Diamond's open controls library ([dodal](https://github.com/DiamondLightSource/dodal), `src/dodal/beamlines/i24.py` and its device classes), so the control handles on the [device pages](index.md) are the beamline's real PVs, read from the source rather than confirmed by staff. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#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 | Nice-to-have | The i24 insertion-device source (gap, type), which dodal does not expose as a device here. | An undulator source; only the Synchrotron machine state is read. | The source Asset detail. | -| ENC-1 | Blocks-go-live | Is i24 one optics hutch plus one experiment hutch, or a different enclosure split? | Two enclosures: i24-optics and i24-experiment. | The Enclosure grouping. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MACHINE-1 | Nice-to-have | The machine source state i24 reads (ring current, top-up, mode) and its PVs. | Observe-only via dodal's Synchrotron device, a loose `StorageRing`. | The machine-state observation. | -| MONO-1 | Blocks-go-live | The DCM crystal cut, d-spacing, and incident-energy range. | A double-crystal monochromator on `BL24I-MO-DCM-01:`; values pending. | The monochromator Asset. | -| OPT-1 | Nice-to-have | The focusing-mirror coatings and the selectable focus modes. | Focusing mirrors bound to `Mirror` (dodal FocusMirrorsMode); modes pending. | The mirror Asset detail. | -| ATTN-1 | Nice-to-have | The attenuator filter set and transmission levels. | A filter-based attenuator bound to `Filter`, not a new kind (the I03 / i15-1 precedent). | The attenuator Asset. | -| OPT-2 | Nice-to-have | The aperture, beamstop, and detector-stage axis roles. | Beam-defining aperture / positioned beamstop / detector translation; axes pending. | The optic Asset detail. | - -### Sample and serial collection - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| GONIO-1 | Blocks-go-live | The vertical goniometer circle and pin-translation axes. | A vertical pin goniometer bound to the catalog `Goniometer`; axes pending. | The goniometer Asset. | -| CHIP-1 | Blocks-build | How is the fixed-target chip addressed: the grid geometry, the well / aperture layout, and how a collection window maps to a stage position? | An addressable chip on the XYZ chip stage; the grid map lives in beamline software, not a PV. | The chip addressing; the CORA Fixture / Subject-grid modelling is on [Model](#deliberately-not-here-yet). | -| SSX-1 | Blocks-go-live | The serial-collection sequence: the raster pattern, the per-window dwell, and the laser / Zebra trigger timing. Does serial crystallography enter CORA's catalog as a Capability? | A triggered chip-raster fly-collection; the Capability is deferred, the Practice rendered pending. | The serial-collection shape; the CORA Capability is on [Model](#deliberately-not-here-yet). | -| LASER-1 | Nice-to-have | The PMAC-controlled lasers: are they a pump-probe excitation source CORA should model, or only a trigger setting and a hazard? | Carried as a trigger setting on the chip-collection seam, not a device; modelling deferred. | The laser model or hazard treatment. | -| BACKLIGHT-1 | Nice-to-have | The dual backlight PV root and its positions. | Binds the catalog `Backlight` Family; the root `BL24I` and positions pending. | The backlight Asset. | - -### Detection - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The detector configuration: the Eiger as the production detector, the Jungfrau as commissioning, and the beam-centre. | Eiger is the primary `Camera` (Detector Role); Jungfrau carried as commissioning. | The detector modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the EPICS PV handles read from dodal current and correct? | The handles in the descriptor are taken from dodal and carried confirm. | Verifying each Asset's control handle. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit signals behind the interlocked hutch shutter. | The hutch shutter is dodal's InterlockedHutchShutter; the permit leaves are to be named, not invented here. | The Enclosure permit signals. | -| SUP-1 | Nice-to-have | The vacuum extent and the facility supplies a run draws on. | Photon beam, cooling water, and vacuum on the optics path. | The Supply observations. | -| GOV-1 | Nice-to-have | The Diamond operator pool and safety-review structure (site-level, shared across the beamlines). | Carried pending on the Diamond Site, not instantiated per beamline. | The governance principals. | diff --git a/docs/deployments/id16b/notes.md b/docs/deployments/id16b/notes.md deleted file mode 100644 index 3c6982e21d0..00000000000 --- a/docs/deployments/id16b/notes.md +++ /dev/null @@ -1,175 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at ID16B: KB-focused hard X-ray nano-tomography and nano-XRF (fluorescence) mapping, two [Catalog](../../catalog/methods.md) Methods bound through [ESRF Practices](../esrf/index.md#the-techniques-adapted-here). Both are reused, not new; ID16B's novelty is the nanoprobe-on-BLISS combination, not the techniques.* - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| KB-focused nano-tomography | `tomography` | the sample is spun through the nanofocused beam while an area detector records a projection stack; a real-space volume is reconstructed downstream. The existing Method ID19 / 2-BM / TomoWise carry; ID16B is a further consumer (TECH-1) | -| Nano-XRF mapping (incl. fluorescence-tomography) | `scanning_fluorescence_microscopy` | the sample is rastered through the nanoprobe on a piezo scanner while an energy-dispersive detector reads a fluorescence spectrum per point, building an element map; fluorescence-tomography adds a rotation axis. The pending Method 2-ID / XFM / LIX carry; ID16B is a further consumer (METHOD-1) | - -The techniques are recorded as pending [Practices](../esrf/index.md#the-techniques-adapted-here) on the ESRF Site: `ID16B_nanotomography_practice` and `ID16B_scanning_fluorescence_microscopy_practice` (TECH-1, METHOD-1). - -### The two acquisition shapes - -Both are acquisition shapes CORA already models; ID16B runs them through one KB nanofocus. - -- **Nano-tomography.** The [rotation stage](sample.md) spins the sample through the nanofocused beam; the [area detector](detector.md) records a projection at each angle; the projection stack reconstructs to a volume. Same shape as ID19, at nanoscale resolution. -- **Nano-XRF mapping.** The [piezo raster scanner](sample.md) steps the sample through the nanoprobe point by point; at each point the [fluorescence detector](detector.md) reads an energy-dispersive spectrum, and the element maps are fit downstream. Adding the rotation axis turns this into fluorescence-tomography (a 3D element map). - -The parts are a `RotaryStage` (the tomo spin / fluo-tomo rotation), `LinearStage`s (coarse positioning and the PI piezo raster scanner), `Mirror`s (the KB nanofocus), an `EnergyDispersiveSpectrometer` (the FalconX XRF detector), and a `Camera` (the area detector). None is new. The reconstructions, both the tomographic volume and the XRF map fitting, are `ComputePort` work, not beamline devices. - -### Why the techniques are not the novelty - -CORA already models tomography (ID19, 2-BM) and scanning fluorescence microscopy (2-ID, XFM, LIX). ID16B is a further consumer of both, so the Practices are carried pending only because ID16B is not yet driven by CORA, not because the Methods are new. - -The novelty at ID16B is the combination and the floor: it is the fleet's first KB nanoprobe with an energy-dispersive fluorescence detector, and a further beamline on the BLISS / Tango control floor. Both are device-and-control concerns ([Model](#model), [Controls](controls.md)), not technique concerns. Holding the Methods constant is the point: it isolates what is genuinely new. - -### Not modelled yet - -This cut models the source, optics, KB nanofocus, sample stack, and detection. The sample environments present in the config are noted, not modelled: - -- The cryostream, furnace, and xeol sample environments (`EH/cryo`, `EH/furnace`, `EH/xeol`) and their Eurotherm / nanodac regulation. A `Cryostat` Family is not yet in the catalog, so the sample environment is deferred to keep this cut vocabulary-neutral (ENV-1). -- The `mapping` / `oda` / `taurus` / `webui` software layers (not beamline devices). - -Each is named on the [Open questions](#open-questions) page rather than modelled speculatively. The source walk that grounds what is and is not present is the generated [beamline](source.md) view. - -## Governance - -*Who may act at ID16B and the trust shape CORA applies. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority. Scaffold, not yet instantiated.* - -People and autonomous agents are facility principals at the [ESRF Site](../esrf/index.md#safety-and-governance); on the beamline they surface through the actions they take. The human roster is not in the BLISS config (GOV-1), so the principals are the design shape, not a registered list. This page follows the same model as ID19 and the other beamlines. - -### Who acts - -CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the ESRF Site. An ID16B beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. The ESRF operator pool and review structure are site-level and shared across the beamlines (ID19 and ID16B both inherit them), so they are not instantiated per beamline; they are carried pending on the [ESRF Site page](../esrf/index.md#safety-and-governance) (GOV-1). - -### The trust boundary - -CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may drive the [sample rotation](sample.md) through a tomographic scan, raster the [piezo scanner](sample.md) for an XRF map, arm the [FalconX detector](detector.md) or an area detector, move the KB nanofocus or the monochromator, override a caution, or commit an alignment. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer. The ESRF proposal and cycle are a fact CORA's Campaign uses for custody. - -Because ID16B is a reverse-engineered scaffold rather than a pilot, the concrete trust shape (the Zones grouping the optics and endstation resources, the Conduit binding the surfaces that may issue commands, and the Policies that say who may do what) is named here, not built. It would land, following the [2-BM governance](../2-bm/governance.md) shape, if and when the deployment approaches real scope. - -### The Enclosures ID16B gates - -This cut covers two enclosures, the grouping CORA's Zones would follow (ENC-1): - -| Enclosure | Role | What it holds | -| --- | --- | --- | -| `id16b-optics` | optics hutch | the U205 undulator source, the Kohzu DCM, the primary / secondary slits, the beam monitors, and the shutters | -| `id16b-experiment` | experiment hutch | the KB nanofocus mirrors, the sample-side slits, the sample rotation / coarse / piezo-scanner stack, the FalconX XRF detector, the optical spectrometer, and the area detectors | - -### The safety tier behind the beam - -The safety tier behind the beam is the personnel safety system. The leaves that must be satisfied before the beam can enter an enclosure are the PSS search-and-secure permit signals, and the shutters are what those leaves gate. The shutter handles are known from the config (the front-end and `fshut` fast shutter), but the PSS permit signals behind them are not in the config, so CORA does not name them and does not invent them: the Enclosure permit signals are carried pending (PSS-1). When staff confirm the permit signal handles, they bind to the Enclosure as the permit leaves. No interlock or PSS tier is invented in the meantime. - -Clearances (the safety forms that must be active to start) are issued at the ESRF Site, not on the beamline, and the beamline links up to them rather than restating them (GOV-1). The ESRF PSS clearance is carried pending because its form names are not confirmed (PSS-1). - -### Nano-analysis under custody - -ID16B's reason for existing is nano-analysis: KB-focused nano-tomography and nano-XRF mapping. In CORA's model these are the existing `tomography` and `scanning_fluorescence_microscopy` Methods, not new techniques (TECH-1, METHOD-1); the devices they gate are `RotaryStage`, `LinearStage`, `Mirror`, `EnergyDispersiveSpectrometer`, and `Camera` Assets (SAMPLE-1, DET-1), and the reconstructions (the tomographic volume and the XRF map fitting) are `ComputePort` work, not beamline devices. That makes the repeated nano-acquisition the place CORA's custody and trust shapes would earn their keep: the trust boundary bounds who may drive the nanofocus and arm the detectors, and the Campaign and Subject shapes carry the sample's custody and the data record. - -The governance shape is the same CORA brings to every beamline; what is different at ID16B is the control floor (BLISS / Tango, not EPICS, see [Controls](controls.md)) and the nanoprobe device set. The trust boundary is control-floor-agnostic and device-agnostic: it gates commands by Actor and state regardless. - -If an autonomous Agent were added (for example to centre the sample on the nanoprobe or decide when an XRF map is complete), it would be a facility principal scoped at the Site, governed by the same trust boundary, with each choice recorded as a [Decision](../../architecture/modules/decision/index.md). None is declared yet; this stays design intent. - -### What is deliberately not modelled - -- **The PSS permit signals (PSS-1).** The shutter handles are known; the permit signals behind them are not in the config, carried pending, not invented. -- **The ESRF operator pool and review structure (GOV-1).** Site-level and shared across the beamlines, carried pending on the ESRF Site. -- **The sample environments (ENV-1).** The cryostream, furnace, and xeol environments are noted, not modelled in this cut. -- **The concrete Zone, Conduit, and Policy instances.** Named as the trust shape, not built; they would land if and when the deployment approaches real scope, following the [2-BM governance](../2-bm/governance.md) shape. - -The full delete-on-answer queue is on [Open questions](#open-questions); where each device and Method lands is on [Model](#model). - -## Model - -*The developer's by-kind index: where each CORA aggregate's ID16B content lives, why this nanoprobe deployment coins no new family, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at ID16B | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes ID16B new - -ID16B is CORA's **third non-EPICS deployment** (after ID32 and ID19) and the fleet's **first KB nanoprobe with XRF**. The novelty sits on two axes, both below the technique layer: - -- **A second BLISS / Tango floor.** ID16B confirms the ID19 seam pattern is repeatable: motion stages are BLISS axes (IcePAP racks, PI piezo scanners, etel Tango motors), the fluorescence detector is a MOSCA / FalconX Tango device, the area detectors are Lima device servers, and CORA's edge conducts over the `ControlPort` against that floor (CTRL-1, see [Controls](controls.md)). -- **The first KB nanoprobe with XRF.** The Kirkpatrick-Baez mirror pair focuses the beam to a nanoprobe, and an energy-dispersive fluorescence detector reads a spectrum per raster point. This device combination is new to the fleet, but every part binds an existing Family. - -### No new families, two reused methods - -ID16B holds the vocabulary constant; that is deliberate, so the new axes (floor, nanoprobe device set) are isolated. - -- **The KB mirrors bind the catalog `Mirror`.** The Kirkpatrick-Baez focusing pair is the nanoprobe; a focusing mirror is what `Mirror` is (OPT-1). -- **The fluorescence detector binds the catalog `EnergyDispersiveSpectrometer`.** ID16B's FalconX silicon-drift detector reads a per-point energy spectrum, a Sensor not a 2D Frame, the same shape as the XFM Xspress3 and the 2-ID / SRX detectors (DET-1). The optical spectrometer (QEPro / Hamamatsu) reuses the same Family (DET-2). -- **The area detectors bind the catalog `Camera`, which presents the Detector Role.** The PCO and Zyla indirect-detection cameras for nano-tomography are thin `Camera` instances (DET-1). -- **The stages bind `RotaryStage` and `LinearStage`.** Sample rotation (the tomo / fluo-tomo master motion), coarse positioning, and the PI piezo raster scanner (the nano-XRF mapping motion) (SAMPLE-1). -- **The optics bind existing Families.** `Monochromator` (the Kohzu DCM), `Slit` (primary / secondary / sample-side), `FluxMonitor` (the EBV beam monitors), `Shutter` (the fast shutter), `InsertionDevice` (the U205 undulator). -- **The Methods are reused.** Nano-tomography is the existing `tomography` Method; nano-XRF mapping is the pending `scanning_fluorescence_microscopy` Method (2-ID / XFM / LIX). ID16B is a further consumer of each (TECH-1, METHOD-1). - -ID16B coins no new Family, nothing graduates, and the catalog is unchanged. - -### Deliberately not here yet - -- **The sample environments (`ENV-1`).** The config carries a cryostream, a furnace, and a xeol environment with Eurotherm / nanodac regulation. A `Cryostat` Family is not yet in the catalog; the sample environment is deferred to keep this cut vocabulary-neutral. It is the natural first candidate for a future cut (and a rule-of-three watch for a sample-environment Family across ID16B, the 4-ID magnet / temperature stack, and others). -- **The PSS permit signals (`PSS-1`).** The shutter handles are known; the permit signals behind them are not in the config; carried pending, not invented. -- **Vendor models, serials, focal-spot sizes, and physical positions.** Not in the config; carried confirm. -- **The simulated devices and full asset-tree scenarios.** No `test_id16b_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the ID16B team to confirm before the model can be trusted.* - -ID16B was reverse-engineered from the beamline's own public BLISS Beacon device database ([`gitlab.esrf.fr/id16b/beamline_configuration`](https://gitlab.esrf.fr/id16b/beamline_configuration)), so the control handles on the [device pages](index.md) are the beamline's real BLISS object and Tango device names, read from the config rather than confirmed by staff. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Control and the BLISS / Tango floor - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the BLISS object and Tango device handles read from the public config current and correct against the live system? | The handles in the descriptor are taken from the config and carried confirm. | Verifying each Asset's control handle. | -| CTRL-2 | Nice-to-have | Which BLISS scan procedures ID16B uses per mode (daiquiri_tomo vs daiquiri_fluo / fluo3d), and which the CORA edge drives through versus replaces. | A continuous-rotation tomo scan and a piezo raster fluo scan; the conduct-versus-replace split is per routine. | The orchestration seam over the `ControlPort`. | - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: one optics hutch and one experiment hutch holding the nanofocus and sample? | One `id16b-optics` and one `id16b-experiment` enclosure. | The Enclosure grouping. | -| ENV-1 | Nice-to-have | The sample environments (cryostream, furnace, xeol) in the config: do they enter a later cut, and as which Family? | Noted, not modelled in this cut; no `Cryostat` Family yet. | The sample-environment roster. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-go-live | The U205 undulator energy reach and gap mapping. | An undulator source feeding the DCM; energy reach to confirm. | The source Asset. | -| OPT-1 | Blocks-go-live | The Kohzu crystal-pair selection per energy, and the KB focal spot / working distance. | Kohzu Si111 / Si333 / Si311; KB mirrors as the nanofocus. | The optics and nanofocus modelling. | - -### Sample and detection - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SAMPLE-1 | Blocks-go-live | The operative rotation / coarse / piezo-scanner axis set per mode (tomo vs fluo). | Rotation (srot) + coarse (sx/sy/sz) + PI piezo scanner (sampy/sampz); rotation is the tomo master motion, the piezo scanner the fluo raster. | The sample-stage modelling. | -| DET-1 | Blocks-go-live | The operative XRF detector and area detector per mode, and the detector-stage axes. | FalconX silicon-drift for nano-XRF (EnergyDispersiveSpectrometer); PCO / Zyla for nano-tomography (Camera). | The detector modelling. | -| DET-2 | Nice-to-have | The role of the optical spectrometer (QEPro / Hamamatsu): xeol, beam diagnostics, or a science channel? | An optical-emission spectrometer reusing EnergyDispersiveSpectrometer. | The optical-spectrometer modelling. | - -### Safety and resources - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| PSS-1 | Blocks-go-live | The ESRF PSS permit signals behind the front-end / fast shutters (not in the config). | Permit leaves to be named; the shutter handles are known, the permit signals are not. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent of the beam path and the cooling-water / beam supplies a run draws on. | Photon beam, cooling water, and vacuum, carried pending. | The Supply observations. | -| GOV-1 | Nice-to-have | The ESRF operator pool and safety-review structure (site-level, shared across beamlines). | Carried pending on the ESRF Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Blocks-go-live | Do nano-tomography and nano-XRF map cleanly onto the existing `tomography` and `scanning_fluorescence_microscopy` Methods? | Both reused as pending Practices; ID16B is a further consumer of each. | The two Practices. | diff --git a/docs/deployments/id19/notes.md b/docs/deployments/id19/notes.md deleted file mode 100644 index eaa18ec6046..00000000000 --- a/docs/deployments/id19/notes.md +++ /dev/null @@ -1,178 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at ID19: hard X-ray parallel-beam microtomography, radiography, and propagation phase-contrast imaging, a [Catalog](../../catalog/methods.md) Method bound through an [ESRF Practice](../esrf/index.md#the-techniques-adapted-here). The technique is plain tomography reuse; the genuine novelty at ID19 is the control floor, not the science.* - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Parallel-beam microtomography / radiography / phase-contrast imaging | `tomography` | the sample is spun through the beam while an area detector records a stack of projection radiographs; a real-space volume is reconstructed downstream. The existing Method the 2-BM pilot and MAX IV TomoWise carry; ID19 is a further consumer (TECH-1) | - -The technique is recorded as a pending [Practice](../esrf/index.md#the-techniques-adapted-here) on the ESRF Site, `ID19_microtomography_practice` (TECH-1). - -### The acquisition shape - -Microtomography is an acquisition shape CORA already models. The [rotation stage](sample.md) spins the sample through the beam; the [detector](detector.md) records a projection radiograph at each angle; and the stack of projections, together with the known rotation angles, is enough to reconstruct a real-space volume of the sample. ID19's long source-to-sample distance gives the beam high spatial coherence, so a settable sample-to-detector distance turns the same acquisition into propagation phase-contrast imaging (DET-1). The reconstruction, turning the projection stack into a volume, is `ComputePort` work, not a beamline device, the same reconstruction leg the other imaging beamlines carry. - -ID19 runs this acquisition at two endstations sharing one source and optics: the micro-resolution (MR) station for large-field, high-throughput tomography, and the high-resolution (HR) station for small-field, high-resolution tomography. Both are the same Method; the difference is the stage stack and the magnification optic, a Practice-and-settings difference, not a new technique. - -So the parts are a `RotaryStage` (the tomographic spin, the master motion, SAMPLE-1), a `LinearStage` for sample centring (SAMPLE-1), a `Camera` as the area detector (interchangeable Frelon / PCO / Basler Lima cameras, DET-1), and a `LinearStage` setting the detector propagation distance (DET-1). None is new; ID19 reuses the existing tomography device shapes exactly. - -### Why the technique is not the novelty - -ID19 is a microtomography beamline, and CORA already models microtomography at the 2-BM operational pilot and the MAX IV TomoWise design scaffold. The `tomography` Method, its Capability, and the device families it binds are all in place. ID19 is a further consumer of that Method, not a new technique, so the Practice is carried pending only because ID19 is not yet driven by CORA, not because the Method is new (TECH-1). - -The genuine novelty at ID19 is one layer down, in the control plane: ESRF runs BLISS (a Tango-based control system), not EPICS, and ID19 is the first to bring that BLISS floor to tomographic imaging (its ESRF sibling ID32 opened it for soft X-ray RIXS). That is a [Controls](controls.md) and seam concern, not a technique concern. Holding the technique constant is the point: it isolates the control-plane axis so the BLISS / Tango floor is the only thing that is new (see [Model](#model)). - -### Not modelled yet - -This cut models the source, the optics, and the two main tomography endstations (MR and HR). The further endstations present in the ID19 config are noted but not modelled: - -- The MH and MED tomography endstations, their own BLISS sessions with their own stage stacks (ENDSTATION-1). -- The LATOMO laminography endstation, which runs a MicosAnka controller over TCP plus a tilt-transformation pusher, a distinct acquisition geometry (ENDSTATION-1). -- The RADIO (radiography) and PCOTOMO (PCO high-speed tomography) sessions (ENDSTATION-1). -- The SmarAct multi-tower sample stack and the FalconX / Mercury fluorescence MCAs (ENDSTATION-1). - -Each is named on the [Open questions](#open-questions) page rather than modelled speculatively. The source walk that grounds what is and is not present is the generated [beamline](source.md) view. - -## Governance - -*Who may act at ID19 and the trust shape CORA applies. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority. Scaffold, not yet instantiated.* - -People and autonomous agents are facility principals at the [ESRF Site](../esrf/index.md#safety-and-governance); on the beamline they surface through the actions they take. The human roster is not in the BLISS config (GOV-1), so the principals are the design shape, not a registered list. This page follows the same model as the other beamlines. - -### Who acts - -CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the ESRF Site. An ID19 beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. The ESRF operator pool and review structure are site-level and shared across the beamlines, so they are not instantiated per beamline; they are carried pending on the [ESRF Site page](../esrf/index.md#safety-and-governance) (GOV-1). None of this is in the BLISS config, which is a controls device database, not an organizational record. - -### The trust boundary - -CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may drive a [rotation stage](sample.md) through a tomographic scan, arm a [detector](detector.md) to record the projection stack, move the monochromator or open a shutter, override a caution, or commit an alignment. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer. The ESRF proposal and cycle are a fact CORA's Campaign uses for custody. - -Because ID19 is a reverse-engineered scaffold rather than a pilot, the concrete trust shape (the Zones grouping the optics and endstation resources, the Conduit binding the surfaces that may issue commands, and the Policies that say who may do what) is named here, not built. It would land, following the [2-BM governance](../2-bm/governance.md) shape, if and when the deployment approaches real scope. - -### The Enclosures ID19 gates - -This cut covers two enclosures, the grouping CORA's Zones would follow (ENC-1): - -| Enclosure | Role | What it holds | -| --- | --- | --- | -| `id19-optics` | optics hutch | the insertion-device source, the TripleMono, the primary / secondary slits, the transfocator, the attenuators, and the front-end / beam shutters | -| `id19-experiment` | experiment hutch | the MR and HR tomographic rotation stages, their sample positioning stacks, the Lima area detectors, and the detector propagation stages | - -A shared optics hutch feeding two tomography endstations in one experiment hutch is the governance shape: which endstation is taking beam, and who may drive the shared optics, is the kind of question the Zone and Policy answer. - -### The safety tier behind the beam - -The safety tier behind the beam is the personnel safety system. The leaves that must be satisfied before the beam can enter an enclosure are the PSS search-and-secure permit signals, and the shutters are what those leaves gate. The shutter handles are known from the config (`frontend`, `id19/bsh/1`, `id19/bsh/2`, all TangoShutters), but the PSS permit signals behind them are not in the config, so CORA does not name them and does not invent them: the Enclosure permit signals are carried pending (PSS-1). When staff confirm the permit signal handles, they bind to the Enclosure as the permit leaves the way the operating siblings carry theirs. No interlock or PSS tier is invented in the meantime. - -Clearances (the safety forms that must be active to start) are issued at the ESRF Site, not on the beamline, and the beamline links up to them rather than restating them (GOV-1). The ESRF PSS clearance is carried pending because its form names are not confirmed (PSS-1). - -### Microtomography under custody - -ID19's reason for existing is microtomography: a tomographic acquisition spins the sample through the beam and records a stack of projection radiographs, and a real-space volume is reconstructed from that stack. In CORA's model this is the existing `tomography` Method, not a new technique (TECH-1); the devices it gates are `RotaryStage`, `LinearStage`, and `Camera` Assets (SAMPLE-1, DET-1), and the reconstruction is `ComputePort` work, not a beamline device. That makes the repeated tomographic acquisition the place CORA's custody and trust shapes would earn their keep: the trust boundary bounds who may drive the rotation and arm the detector, and the Campaign and Subject shapes carry the sample's custody and the projection record. - -The governance shape is the same CORA brings to every beamline; what is different at ID19 is one layer down, in the control floor (BLISS / Tango, not EPICS, see [Controls](controls.md)). The trust boundary is control-floor-agnostic: it gates commands by Actor and state regardless of whether the floor underneath is EPICS or BLISS. - -If an autonomous Agent were added (for example to centre the sample or decide when a scan is complete), it would be a facility principal scoped at the Site, governed by the same trust boundary, with each choice recorded as a [Decision](../../architecture/modules/decision/index.md). None is declared yet; this stays design intent. - -### What is deliberately not modelled - -- **The PSS permit signals (PSS-1).** The shutter handles are known; the permit signals behind them are not in the config, carried pending, not invented. -- **The ESRF operator pool and review structure (GOV-1).** Site-level and shared across the beamlines, carried pending on the ESRF Site, not instantiated per beamline. -- **The further endstations (ENDSTATION-1).** MH, MED, laminography, radiography, and PCO are noted, not modelled in this cut. -- **The concrete Zone, Conduit, and Policy instances.** Named as the trust shape, not built; they would land if and when the deployment approaches real scope, following the [2-BM governance](../2-bm/governance.md) shape. - -The full delete-on-answer queue is on [Open questions](#open-questions); where each device and Method lands is on [Model](#model). - -## Model - -*The developer's by-kind index: where each CORA aggregate's ID19 content lives, why this BLISS-floor imaging deployment coins no new family, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at ID19 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes ID19 new - -ID19 is CORA's first imaging beamline on a **non-EPICS control floor**. Most of the fleet is EPICS (APS, Diamond, NSLS-II, SLAC, all ophyd / bluesky / dodal / pcdshub). ESRF runs BLISS, a Tango-based control system; its soft X-ray sibling ID32 opened the BLISS floor for CORA, and ID19 is the first to bring it to tomographic imaging. That is the novelty, and it is a **control-plane** concern, not a device or technique concern. - -The seam model that today reads "EPICS is the floor" generalizes at ID19 to "BLISS / Tango is the floor". CORA's edge conducts the tomographic scan over its `ControlPort` against BLISS scan procedures and Lima detector servers, rather than EPICS IOCs. The test ID19 poses is that the `ControlPort` and the conduct-versus-drive-through seam are genuinely control-system-agnostic, not secretly EPICS-shaped (see [Controls](controls.md), CTRL-1). - -### No new families, no new methods - -ID19 is a microtomography beamline, and CORA already models microtomography. So holding the device families and the technique constant is deliberate: it isolates the control-plane axis as the only new thing. - -- **The rotation stages bind the catalog `RotaryStage`.** `mrsrot` (MR) and `hrsrot` (HR) are the tomographic spins, the master motions of each scan, expected to clock the detector triggering (SAMPLE-1). -- **The sample and detector positioning stages bind the catalog `LinearStage`.** Sample centring (with the `XYOnRotation` pseudo-axis keeping the sample on the rotation axis) and the detector propagation distance are plain linear motion (SAMPLE-1, DET-1). -- **The detectors bind the catalog `Camera`, which presents the Detector Role.** ID19's indirect-detection area detectors (interchangeable Frelon CCD, PCO 4k, PCO Dimax high-speed, and Basler Lima cameras) are thin `Camera` instances (DET-1). -- **The optics bind existing Families.** `Monochromator` (the TripleMono), `Slit` (primary / secondary), `Transfocator` (the white-beam Be-lens transfocator), `Filter` (the attenuator banks, folding in per the i03 precedent rather than a new `Attenuator` Family), `Shutter` (front-end and beam shutters), and `InsertionDevice` (the undulator / wiggler set). -- **The technique is the existing `tomography` Method.** ID19 is a further consumer of the Method the 2-BM pilot and TomoWise carry; the Practice `ID19_microtomography_practice` is carried pending only because ID19 is not yet driven by CORA (TECH-1). - -ID19 coins no new Family, nothing graduates, and the catalog is unchanged. - -### Two endstations - -MR (micro-resolution) and HR (high-resolution) are distinct BLISS sessions (`MRTOMO`, `HRTOMO`) sharing the source and optics. CORA models each as its own sample and detection group under the shared experiment hutch: same Families, same `tomography` Method, different stage stack and magnification optic. This is a Practice-and-settings difference, not new vocabulary. - -### Deliberately not here yet - -- **The further endstations (`ENDSTATION-1`).** The config carries MH, MED, laminography (LATOMO, a MicosAnka-over-TCP controller with a tilt-transformation pusher), RADIO, PCOTOMO, the SmarAct multi-tower stack, and the FalconX / Mercury fluorescence MCAs. This cut models MR and HR, the two main tomography stations; the rest are noted, not modelled. -- **The PSS permit signals (`PSS-1`).** The TangoShutter handles (`frontend`, `id19/bsh/1`, `id19/bsh/2`) are known, but the personnel-safety permit signals behind them are not in the config; carried pending, not invented. -- **Vendor models, serials, and physical positions.** Not in the config; carried confirm. -- **The simulated devices and full asset-tree scenarios.** No `test_id19_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the ID19 team to confirm before the model can be trusted.* - -ID19 was reverse-engineered from the beamline's own public BLISS Beacon device database ([`gitlab.esrf.fr/id19/beamline_configuration`](https://gitlab.esrf.fr/id19/beamline_configuration)), so the control handles on the [device pages](index.md) are the beamline's real BLISS object and Tango device names, read from the config rather than confirmed by staff. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Control and the BLISS / Tango floor - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the BLISS object and Tango device handles read from the public config current and correct against the live system? | The handles in the descriptor are taken from the config and carried confirm. | Verifying each Asset's control handle on the BLISS floor. | -| CTRL-2 | Nice-to-have | Which BLISS scan procedure(s) ID19 uses per endstation (continuous / fly versus step), and which the CORA edge drives through versus replaces. | A continuous-rotation scan clocked by the rotation stage; the conduct-versus-replace split is per routine. | The orchestration seam over the `ControlPort`. | - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: one optics hutch and one experiment hutch holding both endstations, or a finer split? | One `id19-optics` and one `id19-experiment` enclosure. | The Enclosure grouping. | -| ENDSTATION-1 | Nice-to-have | The further endstations in the config (MH, MED, laminography LATOMO, RADIO, PCOTOMO, the SmarAct towers, the fluorescence MCAs): are they distinct endstations CORA should model? | Noted, not modelled in this cut; MR and HR are the two main tomography stations. | The remaining endstation roster. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-go-live | Which insertion device(s) feed which endstation / mode, and the energy reach. | The undulators (u13a/u32a/u17-6c/u32c) and the w150b wiggler, selected per mode; the wiggler drives white-beam tomography. | The source Asset and mode mapping. | -| OPT-1 | Blocks-go-live | The TripleMono crystal-pair / Laue / multilayer mode mapping, the transfocator lens recipe per energy, and the attenuator foil set. | TripleMono Bragg 17-99 keV plus Laue / multilayer; 8 Be transfocator lenses; Cu/Al attenuator banks folding into Filter. | The optics modelling. | - -### Endstations - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SAMPLE-1 | Blocks-go-live | The operative rotation and sample-positioning axis set per endstation (the config carries spare / commented axes). | MR: mrsrot + mrsx/mrsy/mrxc/mryc; HR: hrsrot + hrsx/hrsy/hrsz/hrz0; XYOnRotation centring on each. | The sample-stage modelling. | -| DET-1 | Blocks-go-live | The operative Lima detector(s) and the indirect-detection optics per endstation, and the propagation-stage axes. | Interchangeable Frelon / PCO / Basler Lima cameras bound to `Camera`; the propagation stage binds `LinearStage`. | The detector modelling. | - -### Safety and resources - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| PSS-1 | Blocks-go-live | The ESRF PSS search-and-secure permit signals behind the frontend / bsh shutters (not in the config). | Permit leaves to be named; the TangoShutter handles are known, the permit signals are not. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent of the beam path and the cooling-water / beam supplies a run draws on. | Photon beam, cooling water, and vacuum, carried pending. | The Supply observations. | -| GOV-1 | Nice-to-have | The ESRF operator pool and safety-review structure (site-level, shared across beamlines). | Carried pending on the ESRF Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Blocks-go-live | Does ID19 microtomography map cleanly onto the existing `tomography` Method, or does parallel-beam / phase-contrast imaging want a distinct Method? | The existing `tomography` Method, a further consumer; carried as a pending Practice. | The microtomography Practice. | diff --git a/docs/deployments/id28/notes.md b/docs/deployments/id28/notes.md deleted file mode 100644 index cd63ce88420..00000000000 --- a/docs/deployments/id28/notes.md +++ /dev/null @@ -1,129 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of ID28 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../esrf/index.md#the-techniques-adapted-here) is how a facility adapts it. ID28 runs momentum-resolved hard X-ray inelastic scattering, a Method not yet in CORA's catalog, so the Method below renders unlinked and is carried pending until a technique enters scope (`TECH-1`). - -### Momentum-resolved inelastic X-ray scattering - -ID28 sets a meV-resolution incident energy with the high-resolution backscattering monochromator (scanned by tuning the crystal temperature, not a Bragg angle), places the multi-analyzer spectrometer arm at a scattering angle that selects the momentum transfer, and scans the incident energy against the fixed-angle analyzer crystals, counting the energy-analyzed scattered photons. The measurement is the intensity surface I(Q, energy-loss): how much energy the sample exchanges with the photon at a chosen momentum transfer, the signature of phonons and collective excitations. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Momentum-resolved inelastic X-ray scattering | `inelastic_x_ray_scattering` | the momentum transfer Q is set by the [spectrometer-arm two-theta](detector.md); the meV incident energy is scanned on the [backscattering monochromator](source.md) against the fixed-angle [multi-analyzer crystals](detector.md); the energy-analyzed signal is counted per analyzer; reuses the NSLS-II IXS Method, the second consumer; Method not yet in catalog | - -It needs the [incident-energy chain](source.md) (the backscattering mono for the meV resolution), the [sample stage and its temperature environment](sample.md), and the [multi-analyzer spectrometer arm and its detectors](detector.md). The arm scattering angle sets the magnitude of the momentum transfer; the analyzer crystals fix the analyzed energy so the incident-energy scan reads out the energy loss. - -### The same inelastic axis, in the hard X-ray regime - -ID28 is the fleet's hard X-ray IXS instrument. The catalog already anticipates inelastic scattering (the SIX soft RIXS arm, the NSLS-II IXS beamline, the ID32 soft RIXS / XES arms), and ID28 reuses the `inelastic_x_ray_scattering` Method the NSLS-II IXS beamline left pending as the second consumer, deepening the case for that Capability without coining anything. The device that ties the inelastic beamlines together is the dispersive spectrometer arm: ID28's multi-analyzer crystal arm is a further consumer of the `SpectrometerArm` family, the sighting that reinforced the graduation earned at ID32, now landed as a catalog Family (see [Model](#a-further-spectrometerarm-consumer-held)). - -### Not modelled yet - -The concrete acquisition recipes (the per-Q energy scans, the analyzer alignment, the counting times, the analyzer-crystal array calibration) are not written yet; they join as the deployment approaches the point where CORA drives ID28. Whether momentum-resolved IXS enters CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at ID28, and the trust shape that will gate it. First cut.* - -Governance at ID28 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [ESRF Site](../esrf/index.md#safety-and-governance), 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). - -ID28 is CORA's second ESRF beamline, so the ESRF Site already exists (established with ID32): the operator pool and the safety-review structure are carried pending on the [ESRF Site](../esrf/index.md#safety-and-governance), shared across the facility's beamlines, until ESRF staff confirm them (`GOV-1`). ID28 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives ID28, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. The ESRF personnel-safety permit signals and the photon and front-end shutters are absent from the BLISS Beacon config, so the Enclosure permit leaves and the interlock structure are carried pending and are not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [ESRF Site](../esrf/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -ID28 adds the hazard classes that come with its endstation: a cryogenic sample environment (the 10 K displex cryostat and the cryogens it draws on) and a hard X-ray beam. Those land with the instruments that bring them, and an experiment Clearance would carry them. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives ID28, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's ID28 content lives, why it coins no new family and adds a further SpectrometerArm consumer, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at ID28 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (the incident-energy PseudoAxis, realized over the F700 temperature controller) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes ID28 new - -ID28 is CORA's second ESRF beamline (after ID32), and it deepens the fleet's inelastic-scattering coverage with a distinct flavor: **momentum-resolved hard X-ray inelastic scattering (IXS)**. A high-resolution backscattering monochromator sets a meV-resolution incident energy, the sample scatters, and a multi-analyzer crystal spectrometer on a two-theta arm energy-analyzes the scattered beam in backscattering, mapping phonon and collective-excitation dispersions across momentum transfer. The fleet already has soft RIXS (SIX, ID32) and the NSLS-II IXS beamline; ID28 is the ESRF hard X-ray IXS instrument, reusing the pending `inelastic_x_ray_scattering` Method as the second consumer (`TECH-1`). - -The second value is the Site re-test: ID28 exercises the ESRF Site and the BLISS / Tango / IcePAP control plane a second time, confirming the ID32 house-style modelling generalizes within the facility. - -A modelling note worth surfacing: ID28's incident energy is **not** scanned by a Bragg angle. The high-resolution backscattering monochromator selects energy by the silicon crystal's lattice spacing, which is tuned by **temperature** (the ASL F700 controller carries a paired `monot` setpoint / `deltae` energy axis). CORA still models the incident energy as a `PseudoAxis`, but it is realized over the F700 temperature controller rather than a goniometer, so the `Monochromator` Asset and the `BeamEnergy` `PseudoAxis` are decoupled in a way an angle-scanned beamline's are not. This is the kind of mechanism the descriptor records (read from the config) so the model is intentional, not a mirror of an angular-mono assumption. - -### A further SpectrometerArm consumer, held - -ID28's IXS spectrometer is a `TwoThetaMultilayer` two-theta arm carrying an array of inclined analyzer crystals (`a2_inca` / `a3_inca` / `a4_inca`, each with chi / th), which binds the `SpectrometerArm` Family. This is a **further consumer** of the family that SIX coined and ID32 brought to a rule-of-three (SIX RIXS arm + ID32 RIXS arm + ID32 XES arm). ID28 is a further sighting that reinforced it, and the family has since **graduated** into the catalog (`RIXS-1`); ID28's arm binds it like any catalog Family, so this scaffold makes no catalog change of its own. - -`SpectrometerArm` is the right home: it is an arm that **positions** an energy-dispersing element (here a crystal array, at SIX / ID32 a grating) and **carries** a detector, presenting the `Positioner` Role, which is why it never fit the point-Sensor families. - -### No new families - -Beyond the graduated `SpectrometerArm`, ID28 reuses the catalog throughout: the backscattering monochromator binds `Monochromator` (the meV backscattering reflection is a per-Asset setting); the HFM / VFM benders bind `Mirror`; the beam-defining slits bind `Slit`; the two in-vacuum undulators bind `InsertionDevice`; the incident energy is a `PseudoAxis` realized over the ASL F700 backscattering-crystal temperature controller (`monot` / `deltae`), not over a Bragg angle; the Basler / PCO detectors bind `Camera`; the sample-temperature environments (the 10 K displex LakeShore 340, the Oxford 700, the nanodac gas blower) bind `TemperatureController`; the oh2 Elettra beam-position monitor binds the graduated catalog `PositionMonitor` (presenting the `Sensor` Role, distinct from `FluxMonitor` by measuring beam position rather than flux); the front-end shutter binds `Shutter`; and the machine state binds the loose `StorageRing` via the BLISS MachInfo. - -### Deliberately not here yet - -- **The analyzer-crystal array identity (`IXS-1`).** The multi-analyzer arm carries an array of inclined analyzer crystals, each with its own chi / th and cylinder slit. The config provisions nine analyzer-slit positions (`a1h..a9h` / `a1v..a9v`) and `inca` controllers for `a2` / `a3` / `a4`; how many crystals are populated is `IXS-1`. The first cut carries the array as a per-Asset setting on the one `SpectrometerArm` Asset; promoting each crystal to a child Asset via `parent_id` is the nested-component-identity convention, itself at a rule-of-three gate (the IXS 10-ID diced-crystal `XTAL-1` question is the sibling), so ID28 flags it rather than asserting it. -- **The SpectrometerArm graduation (`RIXS-1`).** Landed; the family graduated into the catalog (SIX + ID32 RIXS/XES + ID28), so ID28's arm binds it directly. Only the per-Asset arm geometry stays pending. -- **The exact sample-stage and per-analyzer-detector handles (`SAMPLE-1`, `DET-1`).** Carried confirm-pending; the spectrometer arm, mono, mirrors, and sample cryostats carry their real BLISS handles. -- **The IXS Method.** Whether momentum-resolved IXS enters CORA's catalog is an owner decision; the Practice renders unlinked, pending, reusing the NSLS-II IXS slug (`TECH-1`). -- **The simulated devices and full asset-tree scenarios.** No `test_id28_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the ID28 team to confirm before the model can be trusted.* - -ID28 was reverse-engineered from the ESRF's open BLISS Beacon device database ([gitlab.esrf.fr/id28/beamline_configuration](https://gitlab.esrf.fr/id28/beamline_configuration), a git mirror of the live config), so the control handles on the [device pages](index.md) are the beamline's real BLISS / Tango / IcePAP addresses, read from the config rather than confirmed by staff (the ID32 house-style precedent). Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: an optics zone (oh1 / oh2 / oh3) feeding the eh1 spectrometer endstation, or a different layout? | A shared `id28-optics` zone and the `id28-eh1` experiment hutch. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The period and segment count of the two in-vacuum undulators (`u22gap` IVU22a, `u133gap` IVU13-3c). | Two in-vacuum undulators on the ESRF_Undulator device server; the names imply 22 mm and 13 mm periods, segment detail pending. | The source Asset detail. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MACHINE-1 | Nice-to-have | The ESRF-EBS storage-ring state ID28 reads. | Observe-only machine state, a loose `StorageRing`; exact handles pending. | The machine-state observation. | -| MONO-1 | Blocks-go-live | The backscattering crystal / reflection, the meV energy resolution, the energy-scan partition rule, and the premono (OH1) / postmono (OH2) roles ahead of the main mono (OH3). | A `Monochromator` on the PI E518 piezo (`pimth` / `pimchi`); the meV energy is scanned by the ASL F700 crystal-temperature axis (`monot` / `deltae`), not a Bragg angle; energy is a `PseudoAxis` over the F700. | The monochromator and incident-energy Assets. | -| OPT-1 | Nice-to-have | The HFM / VFM mirror coatings and bender mechanics. | Two-bender focusing mirrors bound to `Mirror`. | The mirror Asset detail. | -| OPT-2 | Nice-to-have | The blade-axis map of the primary, mono, and sample slits. | Beam-defining `Slit` Assets (BLISS `slits_ph` / `slits_pv` / `slits_mx` / `slits_sh` / `slits_sv`); each with horizontal / vertical gap and offset. | The slit Asset detail. | -| DIAG-1 | Nice-to-have | The oh2 Elettra beam-position monitor channel map: it binds the graduated catalog `PositionMonitor` (position-measuring), distinct from `FluxMonitor`; the per-Asset position-vs-flux channel detail is the residual. | The graduated catalog `PositionMonitor` (presenting `Sensor`); channel map pending. | The beam-position channel map. | - -### The IXS spectrometer endstation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| RIXS-1 | Blocks-go-live | The multi-analyzer spectrometer arm (the `TwoThetaMultilayer` two-theta arm carrying the inclined analyzer crystals): the per-Asset arm geometry and axis map. | The arm binds the catalog `SpectrometerArm` Family (graduated across SIX + ID32 RIXS/XES + ID28); the per-Asset geometry stays pending. | The spectrometer-arm geometry; the family graduation is settled (see [Model](#a-further-spectrometerarm-consumer-held)). | -| IXS-1 | Blocks-go-live | The analyzer-crystal array: the config shows analyzer slits a1..a9 and inclined-analyzer (`inca`) controllers for a2 / a3 / a4 (each with chi / th); how many crystals are populated, and whether they are one arm Asset or identity-bearing child Assets. | One `SpectrometerArm` Asset carrying the crystal array as a per-Asset setting, not child Assets. | The analyzer-array modelling; the CORA structural choice is on [Model](#deliberately-not-here-yet). | -| SAMPLE-1 | Blocks-go-live | The IXS sample-positioning stage axes: which of the scattering-geometry axes (`sax` / `say` / `saz`, `th` / `sphi` / `chi`), the eh1_ss `iceid285` (`phi` / `omega` / `sz`), and the SmarAct fine stage make up the modelled stage. | A `LinearStage`; axis set pending. | The sample-stage modelling. | -| TEMP-1 | Nice-to-have | The sample-temperature environments (the 10 K displex LakeShore 340, the Oxford 700 cryostream, the nanodac gas blower) and which is the default. | `TemperatureController` Assets presenting the `Regulator` Role. | The temperature-control modelling. | -| DET-1 | Blocks-go-live | The per-analyzer IXS photon detectors and the Basler / PCO imaging cameras: how the `deta1..deta9` P201 counters and the `izero` / `ione` monitors map to the analyzer crystals. | The Basler and PCO bind `Camera`; the per-analyzer `deta1..deta9` counters and the `izero` / `ione` beam monitors are read from the config, the crystal map pending. | The detector modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the BLISS / Tango / IcePAP handles read from the public Beacon config current and correct? | The handles in the descriptor are taken from the BLISS config and carried confirm. | Verifying each Asset's control handle. | -| PSS-1 | Blocks-go-live | The ESRF personnel-safety permit signals behind the shutters. The config exposes the front-end shutter (`fe`) and the vacuum beam shutters (`bsh1` / `bsh2` / `bsh3` on `id28/v-bsh/0..2`), but not the PSS permit leaves. | The shutters are modelled (`FrontEndShutter`, the `bsh*` leaves carried on the enclosures); the permit signals behind them are to be named, not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent and the displex cryostat cryogen supply. | Photon beam, cooling water, and vacuum on the optics and flight path. | The Supply observations. | -| GOV-1 | Nice-to-have | The ESRF operator pool and safety-review structure (site-level). | Carried pending on the ESRF Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Blocks-go-live | Does momentum-resolved IXS enter CORA's catalog as a Capability / Method? | Deferred: carried as a pending Practice reusing the `inelastic_x_ray_scattering` Method NSLS-II IXS left pending, the second consumer; none coined. | The IXS Capability. | diff --git a/docs/deployments/id32/notes.md b/docs/deployments/id32/notes.md deleted file mode 100644 index 30fc71ba3e5..00000000000 --- a/docs/deployments/id32/notes.md +++ /dev/null @@ -1,143 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of ID32 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../esrf/index.md#the-techniques-adapted-here) is how a facility adapts it. ID32 runs three soft X-ray techniques, all new to CORA's catalog, so the Methods below render unlinked and are carried pending until a technique enters scope (`TECH-1`). - -### Resonant inelastic X-ray scattering, magnetic dichroism, emission - -ID32 sets the X-ray energy and polarization with the twin APPLE-II undulators and the plane-grating monochromator, then either disperses the inelastically scattered beam on a long spectrometer arm (RIXS), or measures the absorption asymmetry between polarizations in a high magnetic field (XMCD), or disperses the emitted beam (XES). - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Resonant inelastic X-ray scattering | `resonant_inelastic_scattering` | the roughly 5 m dispersive [spectrometer arm](detector.md) on the RIXS endstation, scanned in energy against the [incident-energy axis](source.md); reuses the SIX RIXS Method, the second consumer; Method not yet in the catalog | -| X-ray magnetic dichroism | `xmcd` | absorption asymmetry in the 9 T [XMCD magnet](sample.md) between circular / linear polarizations set on the [APPLE-II](source.md); reuses the 4-ID / i06 / i10 dichroism Method; pending | -| X-ray emission spectroscopy | `xas_spectroscopy` | the [XES Rowland arm](detector.md) at the XMCD endstation; reuses the `xas_spectroscopy` Method that ISS / LCLS-MFX left pending for XES; pending | - -RIXS needs the [incident-energy and polarization axes](source.md), the [RIXS diffractometer](sample.md) to set the scattering geometry, and the [dispersive spectrometer arm and its CCD](detector.md). XMCD needs the polarization axis, the [9 T magnet and its VTI](sample.md), and a detection channel. XES needs the [emission spectrometer arm](detector.md). - -### A new operating axis for the fleet, on familiar vocabulary - -RIXS at ID32 is the fleet's second soft X-ray RIXS after SIX, and the dispersive spectrometer arm is the device that ties them together: the same `SpectrometerArmsController` anatomy that SIX coined loose, sighted three times across two sites (the ID32 RIXS arm, the ID32 XES arm, and SIX). That rule-of-three earned the graduation of the `SpectrometerArm` Family, which has since landed as a catalog Family (SIX + ID32 RIXS/XES + ID28; see [Model](#loose-families-brought-to-a-rule-of-three-all-since-graduated)). XMCD and XES likewise reuse the dichroism and emission Methods the fleet already carries pending; none forces a new device family. - -### Not modelled yet - -The concrete acquisition recipes (the RIXS energy maps and arm alignment, the XMCD field-and-polarization sequences, the XES scans, and the counting times) are not written yet; they join as the deployment approaches the point where CORA drives ID32. Whether RIXS, XMCD, and XES enter CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at ID32, and the trust shape that will gate it. First cut.* - -Governance at ID32 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [ESRF Site](../esrf/index.md#safety-and-governance), 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). - -ID32 is CORA's first ESRF deployment, so the ESRF is a brand-new Site: the operator pool and the safety-review structure are carried pending on the [ESRF Site](../esrf/index.md#safety-and-governance), shared across the facility's beamlines, until ESRF staff confirm them (`GOV-1`). ID32 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives ID32, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. The ESRF personnel-safety permit signals and the photon and front-end shutters are absent from the BLISS Beacon config, so the Enclosure permit leaves and the interlock structure are carried pending and are not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [ESRF Site](../esrf/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -ID32 adds the hazard classes that come with its endstations: a 9 Tesla superconducting magnet and its liquid-helium cryogen plant at the XMCD endstation, and an intense polarized soft X-ray beam. Those land with the instruments that bring them, and an experiment Clearance would carry them; the magnet and its cryogens are modelled as hazards on the experiment, not as Assets CORA drives for safety (the LASER-1 / sample-environment precedent). - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives ID32, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's ID32 content lives, the graduations it earns, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at ID32 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (the polarization PseudoAxis) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes ID32 new - -ID32 is two things the fleet has not had: a new Site and a new controls house-style. It is CORA's **seventh Site** (the ESRF, Grenoble), the biggest re-test of the Site and Federation kernel a single deployment can be, and the **first BLISS / Beacon / Tango / IcePAP** control plane CORA models (the rest are EPICS, or Tango / Sardana at MAX IV). Its science is soft X-ray resonant inelastic scattering (RIXS) with a ~5 m dispersive spectrometer arm, and X-ray magnetic dichroism (XMCD) plus X-ray emission spectroscopy (XES) at a 9 Tesla high-field-magnet endstation, all fed by twin APPLE-II undulators through a soft X-ray plane-grating monochromator. - -ID32 coins no new Family. The twin APPLE-II undulators bind the catalog `InsertionDevice`, and the polarization is a `PseudoAxis` over the undulator phase, exactly as i06 and i10 modelled their APPLE-II sources; the PGM binds `GratingMonochromator`; the 4-circle diffractometer binds `Goniometer` with a reciprocal-space `PseudoAxis` (the Assembly named, not built, DIFF-1 / DIFF-2); the Andor CCDs bind `Camera`; the LakeShore VTI and coil-diagnostic controllers bind `TemperatureController`; the XMCD sample stage binds `LinearStage`; the machine state binds the loose `StorageRing`. - -### Loose families brought to a rule-of-three (all since graduated) - -ID32 pushed three loose families to a genuine rule-of-three. Per the owner decision (2026-06-27) each graduation is a dedicated, gated catalog PR rather than bundled into this scaffold; all three have since **graduated**. - -| Loose family | Sightings with ID32 | ID32 binding | Status | -| --- | --- | --- | --- | -| `SpectrometerArm` | SIX + ID32 RIXS arm + ID32 XES arm + ID28 | the two dispersive spectrometer arms (the same `SpectrometerArmsController` class instantiated twice) | **graduated**: earned across SIX + ID32 RIXS/XES + ID28; presents the `Positioner` Role | -| `Magnet` | 4-ID + i10-1 + ID32 | the 9 T / 4 T XMCD split-coil magnet | **graduated**: earned across 4-ID + i10-1 + ID32; presents the `Regulator` Role, the field a settable process variable (`MAG-1` now covers only the per-Asset field detail) | -| `PolarizationAnalyzer` | 4-ID + i10 + ID32 + P09 | the RIXS scattered-beam polarimeter | **graduated** (`POL-2`): catalog Family across 4-ID / i10 / ID32 / P09, presents Positioner | - -Keeping each graduation as its own PR keeps the scaffold clean and lets each get its own naming-r3 and gate-review. `SpectrometerArm` was the clearest: it presents the `Positioner` Role (an arm that positions a grating and carries a `Camera` at its focus), which is exactly why it never fit the point-Sensor families (`FluxMonitor` / `EnergyDispersiveSpectrometer`) and was coined loose at SIX. - -### The BLISS / Tango control plane - -ID32 is the first non-EPICS, non-Sardana controls house-style in the fleet: BLISS / Beacon (a YAML device database) over Tango and IcePAP. CORA models the control handles as opaque edge strings regardless of transport, the way the MX3 heterogeneous-control precedent does: a Tango device URL (`id32/limaccds/andor_1`), an IcePAP host+address (`iceid324`), or a BLISS axis name is the handle, carried confirm (`CTRL-1`). The RIXS / XMCD / XES acquisition runs through BLISS sequences; that orchestration is the seam CORA's edge replaces, conducting over Tango / IcePAP rather than replacing BLISS. - -### Deliberately not here yet - -- **The graduations (`RIXS-1`, `MAG-1`, `POL-2`).** All three families ID32 brought to a rule-of-three, `SpectrometerArm`, `Magnet`, and `PolarizationAnalyzer`, have since graduated into the catalog via their dedicated gated PRs. -- **The exact optics handles (`MONO-1`, `OPT-1`, `OPT-2`, `DIFF-1`, `SAMPLE-1`).** The PGM, mirrors, slits, diffractometer axes, and XMCD sample stage are carried confirm-pending; the decision-critical devices (the arms, the magnet, the LakeShores, the CCDs, the undulator) carry their real BLISS addresses. -- **The Assembly(Diffractometer) and the reciprocal-space rule (`DIFF-1`, `DIFF-2`).** Named, not built, as the other diffractometer beamlines deferred theirs. -- **The RIXS / XMCD / XES Methods.** Whether they enter CORA's catalog is an owner decision; the Practices render unlinked, pending, reusing the SIX RIXS, the 4-ID / i06 / i10 XMCD, and the xas_spectroscopy XES slugs (`TECH-1`). -- **The simulated devices and full asset-tree scenarios.** No `test_id32_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the ID32 team to confirm before the model can be trusted.* - -ID32 was reverse-engineered from the ESRF's open BLISS Beacon device database ([gitlab.esrf.fr/id32/beamline_configuration](https://gitlab.esrf.fr/id32/beamline_configuration), a git mirror of the live Beacon config), so the control handles on the [device pages](index.md) are the beamline's real Tango / IcePAP / BLISS addresses, read from the config rather than confirmed by staff. This is CORA's first ESRF Site and first BLISS / Tango / IcePAP controls house-style. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: a shared optics zone feeding the RIXS and XMCD endstations, or a different layout? | A shared `id32-optics` zone and the `id32-rixs` and `id32-xmcd` experiment hutches. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The APPLE-II undulator period and segment count. | An APPLE-II undulator source on the `id/master/id32` device server; period pending. | The source Asset detail. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MACHINE-1 | Nice-to-have | The ESRF-EBS storage-ring state ID32 reads. | Observe-only machine state, a loose `StorageRing`; exact handles pending. | The machine-state observation. | -| POL-1 | Blocks-go-live | The polarization value domain (linear / circular) and the phase conversion: pin it as a Calibration or run it rule-less on the live controller? | A `PseudoAxis` over the APPLE-II phase; rule-less by default (the i06 / i10 precedent). | The polarization-axis modelling. | -| MONO-1 | Blocks-go-live | The PGM grating line densities, the cff, the incident-energy range, and the exact handles. | A soft X-ray PGM bound to `GratingMonochromator`; energy a `PseudoAxis`. | The monochromator and incident-energy Assets. | -| OPT-1 | Nice-to-have | The focusing-mirror coatings and the exact handles. | Soft X-ray focusing mirrors bound to `Mirror`. | The mirror Asset detail. | -| OPT-2 | Nice-to-have | The beam-defining slit blade-axis map and handles. | Slits bound to `Slit`. | The slit Asset detail. | - -### RIXS endstation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DIFF-1 | Blocks-go-live | The 4-circle diffractometer (BLISS `DiffE4CH`, E4CH) circle roles and axes. | A `Goniometer`; the `Assembly(Diffractometer)` is named, not built. | The diffractometer geometry; the CORA structural modelling is on [Model](#deliberately-not-here-yet). | -| DIFF-2 | Nice-to-have | The reciprocal-space (hkl) coordination over the diffractometer. | A reciprocal-space `PseudoAxis`, the rule deferred. | The reciprocal-space Asset. | -| RIXS-1 | Blocks-go-live | The RIXS and XES dispersive spectrometer arms (the `SpectrometerArmsController` geometry, the Rowland radii, the grating modes). | Both bind the catalog `SpectrometerArm` Family (graduated across SIX + ID32 RIXS/XES + ID28); the per-Asset arm geometry stays pending. | The spectrometer-arm geometry; the family graduation is settled (see [Model](#loose-families-brought-to-a-rule-of-three-all-since-graduated)). | -| POL-2 | Nice-to-have | The RIXS scattered-beam polarimeter (the `thpol` / `chipol` / `tthpol` block). | Binds the catalog `PolarizationAnalyzer`, graduated across 4-ID / i10 / ID32 / P09. | The polarimeter modelling. | -| DET-1 | Blocks-go-live | The Andor CCD configurations (RIXS `andor_1`, XES `andor_2`). | Both bind `Camera`. | The detector modelling. | - -### XMCD endstation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MAG-1 | Blocks-go-live | The 9 T / 4 T XMCD split-coil magnet (field range, ramp, the two coils) and its cryogen plant. | Binds the catalog `Magnet` Family (graduated across 4-ID + i10-1 + ID32); the field is a settable axis (Regulator), the per-Asset field detail pending. | The per-Asset magnet field / control detail; the family graduation is settled (see [Model](#loose-families-brought-to-a-rule-of-three-all-since-graduated)). | -| TEMP-1 | Nice-to-have | The LakeShore 336 (VTI sample) and 340 (coil / shield diagnostics) sensor and loop maps, and the He needle valve. | Two `TemperatureController` Assets presenting the `Regulator` Role; the needle valve folds into the VTI. | The temperature-control modelling. | -| SAMPLE-1 | Blocks-go-live | The XMCD sample-positioning stage axes inside the magnet bore. | A `LinearStage`; axis set pending. | The sample-stage modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the Tango / IcePAP / BLISS handles read from the public Beacon config current and correct? | The handles in the descriptor are taken from the BLISS config and carried confirm. | Verifying each Asset's control handle. | -| PSS-1 | Blocks-go-live | The ESRF personnel-safety permit signals and the photon / front-end shutters (absent from the BLISS config). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent and the liquid-helium supply for the magnet. | Photon beam, cooling water, vacuum, and liquid helium. | The Supply observations. | -| GOV-1 | Nice-to-have | The ESRF operator pool and safety-review structure (site-level). | Carried pending on the ESRF Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Blocks-go-live | Do RIXS, XMCD, and XES enter CORA's catalog as Capabilities / Methods? | Deferred: carried as pending Practices reusing the SIX RIXS, the 4-ID / i06 / i10 XMCD, and the xas_spectroscopy XES slugs; none coined. | The technique Capabilities. | diff --git a/docs/deployments/index.md b/docs/deployments/index.md index 4493c3e8782..91e0f8a7652 100644 --- a/docs/deployments/index.md +++ b/docs/deployments/index.md @@ -4,195 +4,24 @@ A deployment is a beamline pilot: one instrument where the recipe ladder, BCs, and trust boundaries meet real users. Vertical before horizontal. CORA's domain model only contains what at least one real deployment forced into it; until a beamline demands a shape, the shape stays out. -A beamline is never standalone: it sits inside a Site, a Federation `Facility` that owns the clearances, principals, practices, and facility-scope supplies the beamline inherits but does not own. The deployments below are grouped by that Site, in the order CORA took the Site on; each beamline page links up to its Site rather than restating it. - -Each Site is introduced by a short card that answers the same three questions: what the facility is, why CORA took it on (the operational pilot, the second-customer validation, or an off-roadmap exercise that stresses a new region, source, or control plane), and the control-plane house-style CORA's edge would land on. Beamline-level detail lives on the beamline pages, not here. +A beamline is never standalone: it sits inside a Site, a Federation `Facility` that owns the clearances, principals, practices, and facility-scope supplies the beamline inherits but does not own. 2-BM's Site is APS; each beamline page links up to it rather than restating it. Each beamline carries three independent badges, so the one word "status" no longer has to mean three things at once: -- **Maturity** is CORA's relationship to the beamline. `Pilot` means CORA drives it live (only 2-BM today). `Design` means it is on the roadmap, modelled ahead of construction or recommissioning. `Model` means an off-roadmap exercise on an operating beamline, taken to test that the domain model generalizes. -- **Evidence** is where the facts came from, strongest first. `Live` is verified against the running instrument. `Design report` is a staff-authored technical or final design report. `Controls config` is public machine-readable controls with real per-device handles (dodal, bluesky profiles, DESY OnlineXML, ESRF BLISS Beacon, MXCuBE, eco / slic, pcdshub). `Narrative` is facility pages or papers only, with device families inferred and no handles. +- **Maturity** is CORA's relationship to the beamline. `Pilot` means CORA drives it live. +- **Evidence** is where the facts came from, strongest first. `Live` is verified against the running instrument. - **Coverage** is whether the modelled slice is the whole operational core (`Full`) or a deliberately partial cut (`Partial`). -The badges are read from each beamline's descriptor, so the table cannot drift from the model. Wherever the evidence is not `Live`, every value on the beamline's pages stays `confirm` until the beamline team verifies it. +The badges are read from the descriptor, so the table cannot drift from the model. + +CORA has also modeled further beamlines at APS and at other facilities worldwide, from public source, to test that the domain model generalizes: those are not deployments (CORA has no operational relationship with them), so they are not presented here. That corpus lives in the private `xmap/descriptors` repo. ## [APS](aps/index.md) -The Advanced Photon Source (Argonne National Laboratory, near Chicago) is CORA's operational pilot Site and its first multi-beamline one: 2-BM runs live while its sibling beamlines are modelled alongside, all sharing one facility envelope. Control plane: EPICS / ophyd. +The Advanced Photon Source (Argonne National Laboratory, near Chicago) is CORA's operational pilot Site. Control plane: EPICS / ophyd. | Beamline | Maturity | Evidence | Coverage | What it is | | --- | --- | --- | --- | --- | | [2-BM](2-bm/index.md) | Pilot | Live | Full | bending-magnet micro-CT, the operational pilot | -| [2-ID](2-id/index.md) | Design | Narrative | Full | scanning fluorescence microprobe (2-ID-D hutch), mined from the EAA toolkit | -| [7-BM](7-bm/index.md) | Design | Narrative | Full | multi-technique flow and combustion imaging, recommissioned for APS-U | -| [19-BM](19-bm/index.md) | Design | Design report | Full | bending-magnet autonomous high-throughput tomography (formerly branded FACT) | -| [32-ID](32-id/index.md) | Design | Narrative | Partial | canted multi-instrument: optics spine and transmission X-ray microscope | -| [12-ID](12-id/index.md) | Model | Controls config | Full | Bonse-Hart ultra-small-angle X-ray scattering (USAXS) plus pinhole SAXS / WAXS, Sector 12; CORA's first USAXS deployment | -| [13-ID](13-id/index.md) | Model | Controls config | Full | GSECARS high-pressure X-ray diffraction on a diamond anvil cell, Sector 13; the fleet's first extreme-conditions sample environment | -| [4-ID](4-id/index.md) | Model | Controls config | Full | polarization and magnetic scattering across four stations (formerly branded POLAR); introduces the POLAR polarization / magnetism vocabulary (the graduated `PhaseRetarder`, `PolarizationAnalyzer`, and `Magnet` catalog Families) | -| [8-ID](8-id/index.md) | Model | Controls config | Full | X-ray photon correlation spectroscopy (XPCS) across four stations; the fleet's first coherent XPCS beamline, earns the xpcs Method | -| [9-ID](9-id/index.md) | Model | Controls config | Full | the Coherent Surface Scattering Instrument (CSSI) across two stations | - -## [MAX IV](maxiv/index.md) - -MAX IV (Lund, Sweden) is CORA's second-customer Site: the first test that the platform ports off APS without per-facility rework, taken on while its beamline is still in design. Control plane: Tango / Sardana, the first non-EPICS house-style CORA plans to drive. - -| Beamline | Maturity | Evidence | Coverage | What it is | -| --- | --- | --- | --- | --- | -| [TomoWise](tomowise/index.md) | Design | Design report | Full | micro- and nano-tomography, Technical Design Report phase | - -## [Diamond Light Source](diamond/index.md) - -Diamond Light Source (Harwell Campus, UK) is an off-roadmap generalization Site: CORA lands here to test that its intentional model, earned on APS tomography, generalizes to Diamond's operating beamlines across MX, scattering, and spectroscopy. Control plane: EPICS / dodal. - -| Beamline | Maturity | Evidence | Coverage | What it is | -| --- | --- | --- | --- | --- | -| [I22](i22/index.md) | Model | Controls config | Full | small- and wide-angle X-ray scattering (SAXS/WAXS), reverse-engineered from dodal | -| [I03](i03/index.md) | Model | Controls config | Full | macromolecular crystallography (MX); graduates the Goniometer Family and exercises autonomous sample handling | -| [I15-1](i15-1/index.md) | Model | Controls config | Full | X-ray total scattering / pair distribution function (XPDF); a reuse + reinforce deployment (no new vocabulary) | -| [I11](i11/index.md) | Model | Controls config | Full | high-resolution powder diffraction; the rule-of-three that earned the TemperatureController graduation + the Regulator Role (landed via gate-review) | -| [I24](i24/index.md) | Model | Controls config | Full | serial / fixed-target macromolecular crystallography (chip-coordinate single-shot); reuses the Goniometer, first synchrotron serial MX | -| [I06](i06/index.md) | Model | Controls config | Full | APPLE-II variable-polarization soft X-ray (XMCD/XMLD, PEEM, resonant diffraction); polarization as a controllable axis | -| [I10](i10/index.md) | Model | Controls config | Full | BLADE twin APPLE-II soft X-ray: RASOR resonant scattering / reflectivity + i10-1 magnet dichroism | -| [I20-1](i20-1/index.md) | Model | Controls config | Partial | energy-dispersive / time-resolved EXAFS (EDE); a deliberately partial first cut, the dispersive polychromator + strip detector deferred (POLY-1 / STRIP-1) | -| [I13-1](i13-1/index.md) | Model | Controls config | Partial | hard X-ray ptychography and coherent diffraction imaging (CDI) on the I13 coherence branch; the fleet's first coherent lensless imaging | -| [I19](i19/index.md) | Model | Controls config | Full | small-molecule single-crystal diffraction; the fleet's first chemical crystallography beamline | - -## [NSLS-II](nsls2/index.md) - -NSLS-II (Brookhaven National Laboratory, New York) is an off-roadmap generalization Site, and the fleet's broadest: CORA lands here to stretch the model across two dozen operating beamlines spanning nearly every hard- and soft-X-ray technique. Control plane: EPICS / bluesky. - -| Beamline | Maturity | Evidence | Coverage | What it is | -| --- | --- | --- | --- | --- | -| [FXI](fxi/index.md) | Model | Controls config | Full | full-field transmission X-ray microscopy and tomography, 18-ID; modelled from public beamline config | -| [HXN](hxn/index.md) | Model | Controls config | Full | scanning hard X-ray nanoprobe (nano-XRF, ptychography, nano-tomography), 3-ID; modelled from public beamline config | -| [BMM](bmm/index.md) | Model | Controls config | Full | X-ray absorption spectroscopy (transmission + fluorescence XAS/EXAFS), 6-BM; modelled from public beamline config | -| [SRX](srx/index.md) | Model | Controls config | Full | submicron X-ray fluorescence microprobe (XRF mapping, XANES, XRF-tomography, diffraction), 5-ID; modelled from public beamline config | -| [SIX](six/index.md) | Model | Controls config | Full | soft X-ray resonant inelastic scattering (RIXS), 2-ID; CORA's first soft X-ray beamline, modelled from public beamline config | -| [CHX](chx/index.md) | Model | Controls config | Full | coherent hard X-ray scattering (XPCS, SAXS/WAXS, GISAXS), 11-ID; the second coherent beamline after APS 8-ID, modelled from public beamline config | -| [CSX](csx/index.md) | Model | Controls config | Full | coherent soft X-ray scattering and RSXS (TARDIS diffractometer), 23-ID; graduates the GratingMonochromator Family, modelled from public beamline config | -| [IOS](ios/index.md) | Model | Controls config | Full | in situ / operando soft X-ray spectroscopy (ambient-pressure XPS / AP-PES, NEXAFS / XAS), 23-ID-2; the twin of CSX on the canted 23-ID straight; modelled from public beamline config | -| [XPD](xpd/index.md) | Model | Controls config | Full | 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) | Model | Controls config | Full | electron spectro-microscopy (ARPES), 21-ID; CORA's first photoemission beamline, graduates the Manipulator Family, modelled from public beamline config | -| [SMI](smi/index.md) | Model | Controls config | Full | 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 | -| [IXS](ixs/index.md) | Model | Controls config | Full | momentum-resolved hard inelastic X-ray scattering, 10-ID; modelled from public beamline config | -| [SST](sst/index.md) | Model | Controls config | Full | soft-and-tender dual-branch, multi-endstation (RSoXS scattering, NEXAFS absorption, HAXPES photoemission), 7-ID; modelled from public beamline config | -| [ISS](iss/index.md) | Model | Controls config | Full | inner-shell spectroscopy (EXAFS by trajectory energy fly-scan, plus XES / HERFD on the Johann + von Hamos crystal emission spectrometers), 8-ID; modelled from public beamline config | -| [FMX](fmx/index.md) | Model | Controls config | Full | frontier microfocusing macromolecular crystallography (rotation MX on a single-omega goniometer + Eiger, autonomous robot sample exchange), 17-ID-2; CORA's 2nd MX after i03; modelled from public beamline config | -| [CMS](cms/index.md) | Model | Controls config | Full | complex-materials scattering (SAXS/WAXS/MAXS, GISAXS/GIWAXS) and the fleet's first hard X-ray reflectivity (XR), 11-BM; the NSLS-II twin of SMI; modelled from public beamline config | -| [XFM](xfm/index.md) | Model | Controls config | Full | scanning X-ray fluorescence microprobe (raster XRF mapping on the Xspress3 + Maia detectors, bending magnet), 4-BM; CORA's 2nd scanning-XRF after 2-ID; modelled from public beamline config | -| [LIX](lix/index.md) | Model | Controls config | Full | life-science solution scattering (bio-SAXS/WAXS, in-line SEC-SAXS) and scanning-microbeam mapping, 16-ID; the fleet's first solution beamline and fluidic sample-delivery chain; modelled from public beamline config | -| [HEX](hex/index.md) | Model | Controls config | Full | high-energy engineering X-ray scattering (imaging/tomography + energy-dispersive and powder diffraction on a superconducting wiggler, white 30-250 keV / mono 30-200 keV), 27-ID; the fleet's first true high-energy hard X-ray beamline; modelled from public beamline config | -| [AMX](amx/index.md) | Model | Controls config | Full | highly automated macromolecular crystallography (rotation MX on a single-omega goniometer + Eiger, EMBL robot sample exchange), 17-ID-1; FMX's sibling, CORA's 3rd MX; modelled from public beamline config | -| [XFP](xfp/index.md) | Model | Controls config | Full | X-ray footprinting of biological macromolecules in solution (white/pink-beam radiolytic dose delivery, offline mass-spec readout), 17-BM; the fleet's first dose-delivery beamline (no scattering detector); modelled from public beamline config | -| [ISR](isr/index.md) | Model | Controls config | Partial | in-situ and resonant hard X-ray scattering / surface diffraction, 4-ID; a deliberately partial first cut, the multi-circle diffractometer + in-situ environment + resonant energy axis deferred (DIFF-1 / INSITU-1 / RESONANT-1); modelled from public beamline config | -| [CDI](cdi/index.md) | Model | Controls config | Full | coherent diffractive imaging (forward CDI, ptychography, Bragg CDI) with a KB nanofocus and Eiger2 / Merlin photon-counting detectors, 9-ID; NSLS-II's coherent-imaging beamline after Diamond i13-1, distinct from APS 9-ID; modelled from public beamline config | -| [PDF](pdf/index.md) | Model | Controls config | Full | high-energy total scattering / pair distribution function and powder diffraction (side-bounce Laue mono, two-detector two-distance merge on PerkinElmer + Pilatus panels), 28-ID-1; XPD's dedicated PDF twin on the shared 28-ID damping wiggler; modelled from public beamline config | - -## [SLAC](slac/index.md) - -SLAC (SLAC National Accelerator Laboratory, California) is an off-roadmap generalization Site and CORA's first X-ray free-electron laser: it tests whether the model reaches past the storage-ring acquisition paradigm to an XFEL's per-shot regime. Control plane: EPICS / pcdshub. - -| Beamline | Maturity | Evidence | Coverage | What it is | -| --- | --- | --- | --- | --- | -| [LCLS-MFX](lcls-mfx/index.md) | Model | Controls config | Full | macromolecular femtosecond crystallography at the LCLS free-electron laser; the first XFEL, where the device families fold but the per-shot acquisition paradigm does not | - -## [Australian Synchrotron](as/index.md) - -The Australian Synchrotron (operated by ANSTO, Melbourne) is an off-roadmap generalization Site and CORA's first in Australia: it re-tests the Site and Federation kernel in a new region and stresses the seam against a heterogeneous, multi-protocol floor. Control plane: EPICS + MXCuBE Exporter + SIMPLON REST. - -| Beamline | Maturity | Evidence | Coverage | What it is | -| --- | --- | --- | --- | --- | -| [MX3](mx3/index.md) | Model | Controls config | Full | macromolecular crystallography (rotation MX) on an MD3 microdiffractometer + DECTRIS Eiger with an ISARA robot; reuses the i03 Goniometer and MX Methods, novelty is the Site and its heterogeneous control plane | - -## [ESRF](esrf/index.md) - -The ESRF (European Synchrotron Radiation Facility, Grenoble) is an off-roadmap generalization Site: CORA lands here to port the Site and Federation kernel onto a fourth-generation source and its BLISS control ecosystem, the first non-EPICS, non-Sardana house-style in the fleet. Control plane: BLISS / Beacon / Tango / IcePAP. - -| Beamline | Maturity | Evidence | Coverage | What it is | -| --- | --- | --- | --- | --- | -| [ID32](id32/index.md) | Model | Controls config | Full | soft X-ray resonant inelastic scattering (RIXS) and X-ray magnetic dichroism (XMCD) on a ~5 m spectrometer arm + 9 T magnet; CORA's first ESRF deployment and first BLISS control plane | -| [ID19](id19/index.md) | Model | Controls config | Full | parallel-beam hard X-ray microtomography, radiography, and phase-contrast imaging on the long imaging beamline | -| [ID16B](id16b/index.md) | Model | Controls config | Full | KB-focused hard X-ray nano-tomography and nano-XRF on the ESRF nanoprobe | -| [ID28](id28/index.md) | Model | Controls config | Full | momentum-resolved hard X-ray inelastic scattering (IXS) on a multi-analyzer crystal spectrometer arm; CORA's second ESRF deployment | - -## [Sirius](sirius/index.md) - -Sirius (Brazilian Synchrotron Light Laboratory, LNLS at CNPEM, Campinas) is an off-roadmap generalization Site and CORA's first in South America: it re-tests the Site and Federation kernel in a new region on a fourth-generation source. Control plane: EPICS + MXCuBE3. - -| Beamline | Maturity | Evidence | Coverage | What it is | -| --- | --- | --- | --- | --- | -| [MOGNO](mogno/index.md) | Model | Narrative | Partial | cone-beam X-ray micro and nanotomography (phase-contrast, time-resolved 4D) across two stations; reuses the 2-BM / FXI tomography vocabulary, novelty is the Site and the fleet's first custom-Python (non-Bluesky) orchestration layer | -| [MANACA](manaca/index.md) | Model | Narrative | Full | macromolecular crystallography (rotation MX, serial and room-temperature) on a goniometer + area detector with a 48-pin sample changer; Sirius's first MX beamline, reuses the i03 / FMX / AMX / MX3 Goniometer and MX Methods on the EPICS floor + MXCuBE3, no new Family | - -## [ALBA](alba/index.md) - -ALBA (CELLS, Barcelona, Spain) is an off-roadmap generalization Site: CORA lands here to reuse its tomography vocabulary on a new facility and control plane. ALBA is the home of Sardana, so its floor is the reference form of that house-style. Control plane: Tango / Sardana / Taurus. - -| Beamline | Maturity | Evidence | Coverage | What it is | -| --- | --- | --- | --- | --- | -| [FAXTOR](faxtor/index.md) | Model | Narrative | Full | BL31 fast X-ray micro-CT and radiography (continuous-rotation tomography up to 20 Hz) on a multipole wiggler; reuses the tomography Families and Methods, novelty is the Site and its Tango / Sardana control plane | - -## [ALS](als/index.md) - -The Advanced Light Source (Lawrence Berkeley National Laboratory, California) is an off-roadmap generalization Site: CORA lands here to reuse its tomography vocabulary on a facility whose floor is unlike any other in the fleet. Control plane: BCS (LabVIEW), the fleet's only LabVIEW house-style. - -| Beamline | Maturity | Evidence | Coverage | What it is | -| --- | --- | --- | --- | --- | -| [8.3.2](8-3-2/index.md) | Model | Narrative | Full | hard X-ray micro-tomography (micro-CT) on a Superbend source, 6-43 keV, ~1 micron; reuses the 2-BM / FXI / FAXTOR tomography Families and Methods, novelty is the Site and its BCS / LabVIEW control plane | - -## [Elettra Sincrotrone Trieste](elettra/index.md) - -Elettra Sincrotrone Trieste (Trieste, Italy) is an off-roadmap generalization Site: CORA lands here to reuse its tomography vocabulary against an in-house, trigger-driven orchestration floor unlike the fleet's other house-styles. Control plane: Tango + DonkiOrchestra. - -| Beamline | Maturity | Evidence | Coverage | What it is | -| --- | --- | --- | --- | --- | -| [SYRMEP](syrmep/index.md) | Model | Narrative | Full | hard X-ray radiology and microtomography (absorption + phase-contrast + breast-CT); CORA's first Elettra deployment and first DonkiOrchestra control plane | - -## [NSRRC](nsrrc/index.md) - -The NSRRC (National Synchrotron Radiation Research Center, Hsinchu, Taiwan) is an off-roadmap generalization Site and CORA's first in Taiwan: it re-tests the Site and Federation kernel in a new region, with an MX cluster whose orchestration seam is the pilot's TomoScan pattern seen at a crystallography beamline. Control plane: EPICS (Blu-Ice / DCSS). - -| Beamline | Maturity | Evidence | Coverage | What it is | -| --- | --- | --- | --- | --- | -| [TPS 07A](tps-07a/index.md) | Model | Controls config | Full | micro-focus protein crystallography (rotation MX) on an Arinax MD3 + DECTRIS EIGER2 X 16M with an ISARA robot; reuses the i03 / MX3 Goniometer and MX Methods, novelty is the Site and its Blu-Ice/DCSS-over-EPICS orchestration seam (the 2-BM pattern, confirmed live over MXCuBE) | -| [TPS 05A](tps-05a/index.md) | Model | Narrative | Full | protein microcrystallography (rotation MX) on the same MD3 + ISARA kit with a DECTRIS EIGER2 X 9M; the MX-cluster sibling of 07A, a reuse-and-reinforce deployment coining no new vocabulary, modelled from the SPXF pages + the 2025 cluster paper (thinner source, PV namespace inferred) | - -## [PETRA III](petra-iii/index.md) - -PETRA III (DESY, Hamburg, Germany) is an off-roadmap generalization Site, and the fleet's deepest single-facility set: CORA lands across its beamlines to widen the technique surface and re-test the kernel at scale on one Site. Control plane: Tango / Sardana. - -| Beamline | Maturity | Evidence | Coverage | What it is | -| --- | --- | --- | --- | --- | -| [P01](p01/index.md) | Model | Controls config | Full | nuclear resonant scattering and inelastic / resonant-inelastic scattering (2.5-80 keV) across two optics hutches and three experiment hutches (EH1 NRS high-resolution-monochromator stack, EH2 diffraction, EH3 RIXS / KB pair); reuses the optics / motion Families, novelty is the Site, its Tango / Sardana control plane read from the OnlineXML, and the NRS / RIXS technique branch (reusing the pending IXS / RIXS Methods) | -| [P04](p04/index.md) | Model | Controls config | Full | variable-polarization soft X-ray spectroscopy (250-3000 eV: XAS, photoemission) across a soft X-ray optics section and two experiment endstations; CORA's first `GratingMonochromator` deployment (the plane-grating mono), reuses the optics / motion Families otherwise, reusing the pending `xas_spectroscopy` / `angle_resolved_photoemission` Methods | -| [P06](p06/index.md) | Model | Controls config | Full | hard X-ray scanning micro / nano fluorescence and diffraction microscopy + nano-tomography across an optics hutch and two scanning-probe endstations (MC01 micro, NC1 nano); the fleet's fullest scanning-probe instrument (the Maia XRF array as `EnergyDispersiveSpectrometer`, hexapods, Aerotech fly-scan stages), coins no new Family, reusing the pending `scanning_fluorescence_microscopy` / `tomography` Methods | -| [P11](p11/index.md) | Model | Controls config | Full | high-throughput macromolecular crystallography (rotation MX) and bio-imaging on a goniometer + Pilatus detector with cryostream cooling; PETRA III's first MX beamline, a reuse-and-reinforce deployment coining no new vocabulary (reuses the i03 MX vocabulary and the pending `mx_data_collection` / `tomography` Methods); a sparse registry, so the experiment hutch is modelled as grouped stages with the goniometer carried as a question | -| [P03](p03/index.md) | Model | Controls config | Full | micro- and nanofocus small- and wide-angle X-ray scattering (SAXS / WAXS, 9-23 keV) across shared P02 / P03 optics and two endstations (a microfocus endstation and the nanofocus GINIX waveguide endstation); PETRA III's first SAXS / WAXS beamline, coins no new Family, brings Galil DMC and SmarPod controllers, reusing the pending `small_angle_scattering` / `wide_angle_scattering` Methods | -| [P10](p10/index.md) | Model | Controls config | Full | coherent hard X-ray applications (XPCS, coherent diffraction imaging / ptychography) across an optics hutch and three experiment areas (E1 coherent imaging, E2 XPCS / diffraction, LAB); a further XPCS beamline (after APS 8-ID and NSLS-II CHX) and the first PETRA III practice to bind a graduated catalog Method (`xpcs`, earned at 8-ID) rather than a pending slug; coins no new Family, with the widest detector suite in the set | -| [P09](p09/index.md) | Model | Controls config | Full | resonant scattering, diffraction, and high-field magnetism (XMCD, magnetic scattering) across a resonant-scattering hutch, a diffraction hutch, and a 14 T magnetism endstation; a further consumer of the 4-ID polarization / magnetism vocabulary (the catalog `PhaseRetarder`, `PolarizationAnalyzer`, and `Magnet` Families), coins no new Family, reusing the pending `resonant_scattering` / `magnetic_scattering` / `xmcd` Methods | -| [P02](p02/index.md) | Model | Controls config | Full | high-energy hard X-ray diffraction: P02.1 powder diffraction / total scattering / PDF (~60 keV) + P02.2 extreme conditions (diamond-anvil-cell high-pressure diffraction); the fleet's second diamond-anvil-cell deployment (binds the catalog `PressureCell`, graduated across 13-ID and P02), bendable HFM / VFM mirrors, coins no new Family, reusing the pending `powder_diffraction` / `total_scattering` Methods | -| [P64](p64/index.md) | Model | Controls config | Full | advanced X-ray absorption spectroscopy (dilute / high-rate fluorescence EXAFS / XANES) on a Tsai DCM + a multi-element fluorescence detector (104-channel SIS3302); the advanced half of the PETRA III XAS pair, coins no new Family, reusing the pending `xas_spectroscopy` Method | -| [P65](p65/index.md) | Model | Controls config | Full | applied / high-throughput X-ray absorption spectroscopy (transmission + fluorescence EXAFS / XANES) on a channel-cut DCM, sharing the P64 optics host; the applied half of the XAS pair, a thin reuse-and-reinforce scaffold (detection carried pending), reusing the pending `xas_spectroscopy` Method | -| [P07](p07/index.md) | Model | Controls config | Full | high-energy materials-science diffraction (HEMS) on a multi-bounce DCM + four-circle diffractometer, with a 17 T high-field magnet endstation; jointly operated by Helmholtz-Zentrum Hereon + DESY, coins no new Family (a further consumer of the graduated `Magnet` Family), reusing the pending `diffraction` / `magnetic_scattering` Methods | -| [P08](p08/index.md) | Model | Controls config | Full | high-resolution diffraction (surface / interface, reflectivity, powder / single-crystal) on a six-circle Kohzu diffractometer with a rich detector set (Eiger / Pilatus / Mythen / PerkinElmer / Vortex); coins no new Family, reusing the pending `diffraction` Method | -| [P21](p21/index.md) | Model | Controls config | Full | Swedish Materials Science high-energy diffraction (P21.2) and total scattering / PDF (P21.1) across an optics hutch, an EH3 endstation, and a LAB station; a thin reuse-and-reinforce scaffold (grouped motor banks, detectors carried pending), reusing the pending `diffraction` / `total_scattering` Methods | -| [P22](p22/index.md) | Model | Controls config | Full | hard X-ray photoelectron spectroscopy (HAXPES) on a `Manipulator` sample stage + `ElectronAnalyzer`, sharing the P09 optics chain (undulator / DCM / mirrors / phase retarder); coins no new Family, reusing the pending `angle_resolved_photoemission` Method; the fleet's first shared-optics beamline pair | -| [P23](p23/index.md) | Model | Controls config | Full | in-situ / operando X-ray diffraction and imaging; a thin reuse-and-reinforce scaffold (one grouped motor bank, optics / diffractometer / detectors carried grouped / pending), reusing the pending `diffraction` Method | -| [P24](p24/index.md) | Model | Controls config | Full | single-crystal / small-molecule chemical crystallography across an optics hutch and two experiment hutches (EH1 / EH2); coins no new Family (the small-molecule diffractometer reuses `LinearStage`, area detector pending), reusing the pending `diffraction` Method | -| [P61](p61/index.md) | Model | Controls config | Full | high-energy white-beam wiggler beamline (P61A Large Volume Press + P61B energy-dispersive diffraction); a thin reuse-and-reinforce scaffold (one grouped motor bank, source / press / detectors pending), reusing the pending `energy_dispersive_diffraction` Method; the last PETRA III beamline with a public OnlineXML registry | -| [P13](p13/index.md) | Model | Controls config | Full | EMBL Hamburg macromolecular crystallography (rotation MX); CORA's first EMBL Hamburg beamline, MXCuBE HardwareObjects source | -| [P14](p14/index.md) | Model | Controls config | Full | EMBL Hamburg high-end two-endstation macromolecular crystallography (MX), the sibling of P13 | - -## [PSI](psi/index.md) - -The Paul Scherrer Institut (Villigen, Switzerland) is an off-roadmap generalization Site and, like SLAC, an institute rather than a single ring: it hosts the SLS storage ring and the SwissFEL free-electron laser. CORA lands here to re-test its XFEL findings against an independently-built FEL and its micro-CT model against a second undulator source. Control plane: EPICS (SLS) + eco / slic (SwissFEL). - -| Beamline | Maturity | Evidence | Coverage | What it is | -| --- | --- | --- | --- | --- | -| [I-TOMCAT](i-tomcat/index.md) | Model | Design report | Full | insertion-device tomographic microscopy (absorption + propagation phase contrast + dynamic 4D CT on the PSI GigaFRoST camera), X02SA; the SLS 2.0 undulator half of the rebuilt TOMCAT, CORA's micro-CT analog of APS 2-BM | -| [Alvra](alvra/index.md) | Model | Controls config | Full | hard X-ray femtosecond pump-probe (time-resolved XAS / XES / HERFD and serial crystallography) on the SwissFEL Aramis branch; CORA's second XFEL, reinforcing the LCLS-MFX family-fold and acquisition-gap findings from an independent control stack (`eco`) | -| [Bernina](bernina/index.md) | Model | Controls config | Partial | hard X-ray femtosecond pump-probe diffraction / scattering on two reconfigurable diffractometers (GPS six-circle, XRD You-geometry); the second co-equal station on the shared Aramis source, makes the shared-switched-source seam concrete, reuses the graduated Diffractometer Assembly; a deliberately partial first cut (`eco`), the live device config is externalized | -| [Cristallina](cristallina/index.md) | Model | Controls config | Full | hard X-ray time-resolved diffraction / scattering on quantum materials (DM1 / DM2 diffractometers in a dilution-fridge vector superconducting magnet) plus serial crystallography; the third Aramis station, closes the shared-source triad, CORA's first deployment mined from `slic`, a further consumer of the graduated `Magnet` Family, no new Family | Cross-facility vocabulary (Capabilities, Methods) lives in the [Catalog](../catalog/index.md), since it is not bound to any single Site. diff --git a/docs/deployments/ios/notes.md b/docs/deployments/ios/notes.md deleted file mode 100644 index d1b23067135..00000000000 --- a/docs/deployments/ios/notes.md +++ /dev/null @@ -1,167 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at IOS: ambient-pressure photoemission and soft X-ray absorption, each a [Catalog](../../catalog/methods.md) Method. IOS follows the deferral discipline of the soft X-ray beamlines that brought each technique family to CORA. First cut.* - -IOS's techniques are soft X-ray surface science under working conditions: ambient-pressure photoemission and soft NEXAFS / XAS. The Methods below render unlinked and are carried pending until the owner-scope decision (`TECH-1`) brings them into the catalog. Following [SST](../sst/notes.md#techniques), IOS records **no Practice** at the [NSLS-II Site](../nsls2/index.md#the-techniques-adapted-here) yet, because each technique sits on a pending or deferred Method; each binding lands when its Capability does. - -| Technique | Mode | Notes | -| --- | --- | --- | -| Ambient-pressure photoemission (AP-XPS / AP-PES) | fixed energy, gas atmosphere | photoelectron spectra on the SPECS hemispherical analyzer under a working gas pressure; the ESM / SST photoemission family, new Capability pending (`TECH-1`) | -| Soft NEXAFS / XAS | energy sweep | absorption by total / partial electron yield (drain current through the scaler) and partial fluorescence yield (the Vortex / Xspress3), over a PGM energy scan; the BMM energy-scan question (`ENERGY-1`, `TECH-1`) | - -Both need the [grating monochromator](source.md) (the incident energy), the [AP-PES manipulator](sample.md) (the sample in the analyzer focus), and the [analyzer and yield chain](detector.md). The detection mode (TEY drain current, PEY kinetic-energy-selected electrons through the analyzer, PFY region-of-interest fluorescence) is a setting, not a separate technique. - -### Why the Capabilities stay deferred - -Each of IOS's techniques sits on a Capability the catalog does not yet carry, and the discipline is the same one the originating beamlines applied: - -- **Ambient-pressure photoemission** follows NSLS-II [ESM](../esm/index.md). The only photoemission Method slug the catalog anticipates is `angle_resolved_photoemission`, coined for ESM's ARPES; IOS's AP-XPS is chemical-state photoemission under a gas atmosphere, not angle-resolved, so reusing that slug would name a shape it was not coined for. The device Role already exists (the analyzer presents Detector); what is new is the science Capability, and the ambient-pressure context on top of it. -- **Soft NEXAFS / XAS** follows [BMM](../bmm/index.md): the measurement is the energy sweep itself, the deferred `energy_scan` Capability (`ENERGY-1`). It is a different shape from the crystal-emission-spectrometer `xas_spectroscopy` that LCLS-MFX and ISS left pending (which disperses emitted photons through an analyzer crystal); IOS's NEXAFS reads absorption by electron and fluorescence yield. - -So IOS reinforces both technique families at one more instrument without coining either, and records no Practice; each binding lands when its Capability does (`TECH-1`, `ENERGY-1`). - -### The ambient-pressure context - -What distinguishes IOS from the fleet's other photoemission and absorption beamlines is that it runs under a working gas atmosphere (in situ / operando), not in vacuum. That context is the heart of the science, but the hardware that delivers it (the reaction cell, the gas dosing and mixing, the pressure control, the sample heating) is not in the profile collection and is carried as the headline open question (`INSITU-1`), not modelled. When a Method for ambient-pressure spectroscopy is eventually authored, the ambient-pressure context would be a Practice-level adaptation (the gas, pressure, and temperature settings) on the photoemission and absorption Methods, not a separate technique. - -### Not modelled yet - -The concrete acquisition recipes (the energy scans with their coupled EPU edge-table switching, the spectrum acquisitions, the yield reads) are not written yet; they join as the deployment approaches the point where CORA drives IOS. The per-technique reduction (photoemission spectra, NEXAFS spectra) is `ComputePort` work, not beamline Methods. See [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at IOS, and the trust shape that will gate it. First cut.* - -Governance at IOS 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). - -IOS 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`). - -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. The PSS search-and-secure permit signals and the photon shutters are absent from the profile collection, so the Enclosure permit leaves and the interlock structure are carried pending and not invented here (`PSS-1`). - -IOS carries the hazard classes that come with its instruments, which an experiment Clearance would carry; those land with the instruments that bring them: - -- the soft X-ray beam in the optics and endstation enclosures; -- the ultra-high vacuum of the PGM, the KB system, and the analyzer endstation; -- and, distinctively, the **ambient-pressure / operando sample environment**: a working gas atmosphere, the gas dosing and handling, and the sample heating that the reaction cell brings. That hardware is not in the profile collection, so its hazards (gas handling, pressure, temperature) are carried pending with the cell itself, not invented (`INSITU-1`). - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives IOS, following the [2-BM governance](../2-bm/governance.md) shape. It re-tests the Site and Federation kernel rather than introducing a new trust model. - -## Model - -*The developer's by-kind index: where each CORA aggregate's IOS content lives, how the ambient-pressure environment is carried as a deferral, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at IOS | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes IOS new - -The honest answer is: little on the hardware, one real thing on the science. IOS measures surface and interface chemistry under working conditions by ambient-pressure X-ray photoemission (AP-XPS / AP-PES) and soft NEXAFS / XAS. Every device it carries is a fleet shape ported once more: - -- the SPECS hemispherical analyzer binds the catalog `ElectronAnalyzer`, the third sighting after ESM and SST; -- the VLS-PGM binds `GratingMonochromator`, a further consumer after SIX / CSX / ESM / SST; -- the Vortex and Xspress3 silicon-drift detectors bind `EnergyDispersiveSpectrometer`; -- the AP-PES four-axis stage binds `Manipulator`; -- the two canted EPUs are the same `SR:C23-ID` twin-EPU straight CSX reads, with IOS on the 23-ID-2 branch. - -IOS's one genuinely distinct contribution is **in-situ / operando ambient-pressure spectroscopy**: measuring chemistry under a working gas atmosphere rather than in vacuum. That is the heart of the beamline, but the hardware that makes it (the reaction cell, the gas dosing and mixing manifold, the pressure control, the sample heating) is not in the profile collection, so CORA carries it as the headline open question (`INSITU-1`) and does not invent it. IOS also re-tests the NSLS-II Site and Federation kernel once more; the value there is confidence that the kernel holds, not a new abstraction. - -### No new families - -IOS coins no new Family and changes nothing in the catalog. - -- **The SPECS analyzer binds `ElectronAnalyzer`** (a photon-in / electron-out hemispherical analyzer, the ESM / SST precedent), the third sighting and the first non-Scienta and first ambient-pressure one; the analyzer make, the lens-mode set, and the pass-energy range are a per-Asset settings or bound-Model difference, not a Family split (`DET-1`). -- **The VLS-PGM binds `GratingMonochromator`** (the soft X-ray plane-grating optic, the SIX / CSX precedent); the energy is its master axis with the EPU edge-table switching coupled in (`MONO-1`). -- **The fluorescence detectors all reuse:** the Vortex (silicon-drift detector + MCA) and the Xspress3 (four-channel silicon-drift) bind `EnergyDispersiveSpectrometer`; the AP-PES stage binds `Manipulator`; the XAS-endstation translation binds `LinearStage`; the front-end and branch mirrors and the KB pair bind `Mirror`; the branch slits bind `Slit`; the front-end and branch shutters bind `Shutter`; the scaler and the Au-mesh I0 reference bind `FluxMonitor`; the surface-prep ion gun binds `GenericProbe`; the exit-slit diagnostic camera binds `Camera`; the two EPUs bind `InsertionDevice`. - -### How the ambient-pressure environment is carried (no device) - -The ambient-pressure / operando sample environment is what makes IOS IOS, and it is carried as a deferral, not a device: - -- the sample positioning that **is** in the profile (the APPES four-axis manipulator) is modelled as `Manipulator`; -- the gas dosing and mixing, the pressure control, and the sample heating that the reaction cell needs are **not** in the profile collection (no gas, pressure, or temperature PVs), so they are carried as the headline open question (`INSITU-1`), not modelled. - -This is the same discipline the fleet's other in-situ accessories follow (SMI defers its humidity cell and blade coater, SST defers its ADR cryostat and syringe pump, ISS defers its broader sample environment): the device Roles that exist are modelled, and the sample-environment hardware that is not in the public source is deferred to an open question rather than invented. Whether a `ReactionCell` or near-ambient-pressure-cell Family is ever earned is a future owner decision, pending a second ambient-pressure deployment and the real PVs (`INSITU-1`). - -### Why no Practice is recorded - -IOS records **no Practice** at the [NSLS-II Site](../nsls2/index.md#the-techniques-adapted-here), following [SST](../sst/notes.md#techniques), the closest sibling (the soft / tender NSLS-II photoemission-and-absorption beamline that also recorded none): - -- IOS's ambient-pressure photoemission is photoemission, but the only photoemission Method slug the catalog anticipates is `angle_resolved_photoemission`, coined for ESM's ARPES; AP-XPS is chemical-state, not angle-resolved, so reusing that slug would name a shape it was not coined for; -- IOS's soft NEXAFS / XAS is absorption by electron and fluorescence yield over an energy sweep, which leans on the deferred `energy_scan` Capability (the BMM question, `ENERGY-1`) and is a different shape from the crystal-emission-spectrometer `xas_spectroscopy` that MFX and ISS left pending. - -So no Practice is bound until a Method lands; IOS is bound to the Site through the beamline list, and each binding lands when its Capability does (`TECH-1`, `ENERGY-1`). - -### Deliberately not here yet - -- **The ambient-pressure reaction cell (`INSITU-1`).** The gas dosing / mixing manifold, the pressure control, and the sample heating are absent from the profile collection (no gas / pressure / temperature PVs) and are not invented; the sample positioning that is in the profile is modelled as `Manipulator`. A second ambient-pressure deployment and the real PVs would earn the abstraction. -- **The sample transfer / load-lock.** A load-lock gate valve (`IOXAS-GV:4`) is in the profile but no sample-transfer motor PVs are, so the transfer mechanism is deferred (`SAMPLE-1`). -- **The gate valves and the storage-ring readback.** The vacuum gate valves (`XF:23ID2-VA`) and the storage-ring current (`XF:23ID-SR`) are vacuum plumbing and facility observation, carried as notes, not Assets. -- **The photoemission and NEXAFS Methods.** Whether ambient-pressure photoemission and soft NEXAFS enter CORA's catalog as Capabilities / Methods is an owner decision; the techniques render unlinked, and no Practice is recorded (`TECH-1`, `ENERGY-1`). -- **The simulated devices and full asset-tree scenarios.** No `test_ios_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the IOS team to confirm before the model can be trusted.* - -IOS was reverse-engineered from the beamline's own bluesky profile collection ([NSLS2/ios-profile-collection](https://github.com/NSLS2/ios-profile-collection)), so the control handles on the [device pages](index.md) are the beamline's real PVs, read from the `startup/*.py` files rather than confirmed by staff. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#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 | -| --- | --- | --- | --- | --- | -| TOPO-1 | Blocks-build | The 23-ID canted straight: do the two EPUs feed both CSX (23-ID-1) and IOS (23-ID-2), and is IOS one root Unit? | One root Unit `IOS` fed by the canted twin-EPU straight (the 32-ID / CSX precedent). | The source topology in the [descriptor](index.md). | -| ENC-1 | Blocks-go-live | Are the PV zones `XF:23IDA` / `XF:23ID2-OP` / `XF:23ID2-ES` separate shielded hutches or beam zones within fewer? | Two enclosures (front-end optics + the 23-ID-2 branch). | The Enclosure grouping. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the EPICS PV handles read from the ios-profile-collection current and correct, and is a queue server in use? | The handles in the descriptor are taken from the profile collection and carried confirm; queue-server use unknown. | 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 front-end shutter is `XF:23ID-PPS{Sh:FE}` and the branch shutter `XF:23ID2-PPS{PSh}`. | The Enclosure permit signals. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-go-live | The two EPUs (`EPU:1`, `EPU:2`): type, period, the polarization (phase) model, and the energy-edge lookup tables. | Two `InsertionDevice` Assets; the phase axis and the edge table carried as settings. | The insertion-device specs. | -| MONO-1 | Blocks-go-live | The VLS-PGM: the grating line densities, the c-value model, and the 200-2200 eV range. | A `GratingMonochromator` Asset with energy / mirror-pitch / mirror-x / grating-pitch / grating-x axes and an energy fly-scan. | The monochromator model. | -| OPT-1 | Nice-to-have | The mirrors (M1A front-end, M1B1 / M1B2 deflecting, M3B branch, DM1, the KB pair): coatings and axis roles. | `Mirror` Assets with the config's PV roots; coatings unconfirmed. | The mirror specs. | -| OPT-2 | Nice-to-have | The branch slits (`Slt:1` gap-center, `Slt:2` vertical): the internal axis maps. | `Slit` Assets with base PVs; per-blade axes partial. | The slit axis maps. | - -### Sample and ambient-pressure environment - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SAMPLE-1 | Blocks-build | The APPES manipulator (x / y / z / rotation) and the IOXAS stage: the axis roles, and the sample-transfer / load-lock mechanism (the `IOXAS-GV:4` valve is present, no transfer-motor PVs are). | A `Manipulator` and a `LinearStage`; the transfer mechanism deferred. | The sample-positioning model. | -| SAMPLE-2 | Nice-to-have | The SPECS surface-prep sputter / ion gun: control and role. | A `GenericProbe` auxiliary, not the analyzer. | The surface-prep model. | -| INSITU-1 | Blocks-build | The ambient-pressure reaction cell, the gas dosing / mixing manifold, the pressure control, and the sample heating: there are no gas / pressure / temperature PVs in the profile collection. | The ambient-pressure sample environment is out of the profile collection and not modelled until the hardware and PVs are provided. | The operando sample environment, IOS's defining feature. | - -### Detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The SPECS hemispherical analyzer: model (Phoibos NAP?), pass-energy range, lens-mode set, and angular acceptance. | An `ElectronAnalyzer` Asset; analyzer make and ranges are settings. | The analyzer model. | -| DET-2 | Blocks-go-live | The Vortex and Xspress3 silicon-drift detectors: models, channels, and the ROI map (and why one of four Xspress3 channels is active). | `EnergyDispersiveSpectrometer` Assets; ROI / channel maps partial. | The fluorescence-detector models. | -| DET-3 | Nice-to-have | The scaler, the `CurrAmp:1/2/3` current amplifiers, and the Au mesh: the electron-yield (TEY / PEY) channel wiring and the I0 reference. | `FluxMonitor` Assets; the yield-chain wiring partial. | The yield-chain map. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENERGY-1 | Nice-to-have | Is the NEXAFS / XAS measurement a continuous PGM energy fly-scan (with coupled EPU edge-table switching) or a stepped scan? | The PGM energy fly-scan is available; the sweep-as-measurement is carried as intent. | The energy-scan mode. | - -### Supplies - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SUP-1 | Nice-to-have | The vacuum and cooling supplies the UHV optics, the KB system, and the analyzer endstation draw on. | Photon beam, cooling water, and vacuum carried in the descriptor. | The Supply records. | diff --git a/docs/deployments/isr/notes.md b/docs/deployments/isr/notes.md deleted file mode 100644 index dfe89283ab3..00000000000 --- a/docs/deployments/isr/notes.md +++ /dev/null @@ -1,150 +0,0 @@ -# Notes - -## Techniques - -*What ISR is designed to do, as intent. A deliberately partial first cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../nsls2/index.md#the-techniques-adapted-here) is how a facility adapts it. ISR's mission is hard X-ray resonant scattering and surface / interface diffraction, with in-situ sample environments. The Methods below render unlinked and are **doubly deferred**: the Methods themselves are pending, and the multi-circle diffractometer they run on is absent from the source (`TECH-1`, `DIFF-1`). - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Resonant scattering | `resonant_scattering` | resonant elastic scattering near an absorption edge; reuses the Method APS [4-ID](../4-id/notes.md#techniques) (POLAR) and [CSX](../csx/notes.md#techniques) left pending; needs a tunable energy axis and a diffractometer, both absent from source (`TECH-1`, `RESONANT-1`, `DIFF-1`) | -| Surface / interface diffraction | `diffraction` | crystal truncation rods and surface structure; reuses the `diffraction` Method 4-ID / [8-ID](../8-id/notes.md#techniques) left pending; needs the multi-circle diffractometer, absent from source (`TECH-1`, `DIFF-1`) | - -Both techniques would need the [incident-beam chain](source.md) (the undulator, the DCM for energy, the focusing mirrors, the attenuator), a multi-circle [sample diffractometer](sample.md), and the [Eiger area detector](detector.md). The first two of those are partly modelled; the diffractometer is not. - -### Reuse, not new vocabulary - -ISR coins **no new Method**. Its resonant scattering reuses the `resonant_scattering` Method that APS 4-ID brought and CSX shares; its surface / CTR diffraction reuses the `diffraction` Method that 4-ID / 8-ID share. So ISR adds, when it lands, further consumers of two pending Methods, strengthening the case for cataloging them, but it does not mint vocabulary. The matching Site Practices (`ISR_resonant_scattering_practice`, `ISR_surface_diffraction_practice`) are carried pending in the [NSLS-II Site](../nsls2/index.md#the-techniques-adapted-here). - -### Why these are doubly deferred - -For every other beamline the technique Methods are deferred because the Capability is not yet in the catalog (the owner-scope decision). At ISR there is a second, harder deferral: the **devices** the techniques run on are not in the public source. Resonant scattering needs a tunable energy axis (a non-functional stub here, `RESONANT-1`) and surface diffraction needs a multi-circle diffractometer (only two axes bound, `DIFF-1`). So these Practices are intent recorded against a partial scaffold, not a capability CORA could drive today. They firm up as the diffractometer and the energy axis enter the source. - -### Not modelled yet - -The concrete acquisition recipes are not written yet, and cannot be until the diffractometer lands: the reciprocal-space (hkl) scans, the rocking-curve and CTR trajectories, the energy scans across an edge for resonant work, and the in-situ environment programs. The integration and reduction (azimuthal / CTR rod integration) are `ComputePort` work, not beamline Methods. These join as ISR's profile collection grows past its current optics-first state. - -See [Open questions](#open-questions) for the world-facts to confirm first, especially the diffractometer (`DIFF-1`) and the in-situ environment (`INSITU-1`). - -## Governance - -*Who will act at ISR, and the trust shape that will gate it. A deliberately partial first cut.* - -Governance at ISR 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#safety-and-governance), 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). - -ISR is not yet driven by CORA, so this shape is not yet instantiated. As a partial modelling-exercise scaffold, the deployment is descriptor and docs today, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized. The NSLS-II operator pool and review structure is carried pending on the [NSLS-II Site](../nsls2/index.md#safety-and-governance), shared with the rest of the fleet (`GOV-1`). - -### The safety boundary - -The safety tier is the other piece that is not yet settled, and the source is especially thin here: **no PSS search-and-secure permit signal, photon shutter, or hutch-interlock device is in the profile collection** (the only two-button-shutter use is the filter-bank actuation, not a beam shutter). So the Enclosure permit leaves and the interlock structure are carried pending and not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [NSLS-II Site](../nsls2/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -ISR adds the hazard classes that come with its instruments. Those land with the equipment that brings them, and an experiment Clearance would carry them. - -| Hazard class | Where it lands | Tracking | -| --- | --- | --- | -| Hard X-ray beam | the [optics](index.md) and [endstation](index.md) enclosures (XF:04ID) (`ENC-1`) | (`PSS-1`) | -| Vacuum optics | the [Source](source.md) walk | (`SUP-1`) | -| In-situ sample environments (when present) | the [Sample](sample.md) side | (`INSITU-1`) | - -The hard X-ray beam is the interlocked hazard; its permit leaves stay pending until the PSS signals are confirmed (`PSS-1`). The in-situ sample environments that ISR's name implies (electrochemistry, gas, temperature, cryostat) would each bring their own hazards, but none is in the source yet, so they are carried against the in-situ question, not invented (`INSITU-1`). - -### When the shape lands - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when ISR's profile collection firms up past its current optics-first state and the deployment approaches the point where CORA drives ISR, following the [2-BM governance](../2-bm/governance.md) shape. Because ISR shares the NSLS-II EPICS and ophyd floor with the rest of the fleet, it re-tests the Site and Federation kernel rather than introducing a new trust model. The Zone groups the same optics and endstation resources the [inventory](index.md) lists; the Policies bind to the NSLS-II operator roles carried pending at the Site (`GOV-1`). - -## Model - -*The developer's by-kind index: where each CORA aggregate's ISR content lives, why this deployment is deliberately partial, and the record of what is deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at ISR | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### Why ISR is partial - -ISR's name, In Situ and Resonant, promises a multi-circle diffractometer, a tunable resonant energy axis, in-situ sample environments, and often polarization analysis. The public profile collection does not yet contain them. It is an optics-and-detectors-first scaffold: the front-end slit, the undulator gap (read-only), the DCM, the focusing and harmonic-rejection mirrors, the attenuator bank, the Eiger 1M, the diagnostic screen cameras, and only two bound sample axes (`th`, `zeta`). The flux-monitor electrometers are commented out, the energy axis is a non-functional stub, and the databroker catalog has a placeholder name, all commissioning signals. - -CORA models what is PV-bound and routes the four mission-critical gaps to open questions rather than inventing them. This is the same discipline the [i20-1](../i20-1/notes.md#model) (EDE) partial uses: where the source is thin, model the real handles and name the absences, never fabricate the headline device. - -### No new families - -ISR coins no new Family and changes nothing in the catalog. - -- **4-ID is an undulator beamline** (read-only gap in source); machine state is observed through the loose `StorageRing`, and the undulator detail is `SRC-1`. -- **The optics reuse the catalog:** the DCM binds `Monochromator`; the bendable focusing pair and the harmonic-rejection mirror bind `Mirror`; the front-end slit binds `Slit`; the attenuator bank binds `Filter`. -- **The one bound sample rotation binds `RotaryStage`, not `Goniometer`.** With only `th` + `zeta` bound and no detector arm or reciprocal-space engine, there is no basis for a multi-circle `Goniometer`; it is one `RotaryStage` Asset with the full diffractometer deferred (`DIFF-1`). -- **The Eiger 1M and the screen cameras bind `Camera`; the motorized BPM stage binds the graduated catalog `PositionMonitor`** (presents `Sensor`, distinct from `FluxMonitor` by measuring beam position rather than flux; the per-Asset channel map stays open, `DIAG-1`). The flux-monitor electrometers are commented out, so no `FluxMonitor` Asset is modelled (`DET-1`). - -### No new Methods - -ISR's science reuses two pending Methods rather than coining: `resonant_scattering` (APS 4-ID, CSX) and `diffraction` (4-ID, 8-ID). Both are doubly deferred here because the diffractometer they run on is absent from source (`TECH-1`, `DIFF-1`). When ISR's diffractometer lands and the techniques are driven, ISR becomes a further consumer of each, strengthening the case for cataloging them, an owner decision, not an automatic one. - -### Deliberately not here yet - -- **The multi-circle diffractometer (`DIFF-1`).** Only `th` + `zeta` are bound under the `Dif:ISD` IOC; the orientation circles, the detector two-theta arm, and the reciprocal-space / hkl engine are absent from source and not invented. When they land, the sample side would be a `Goniometer` plus reciprocal-space `PseudoAxis` (the IXS six-circle / CSX TARDIS precedent), with a detector-arm `RotaryStage` / `LinearStage`. -- **The in-situ sample environment (`INSITU-1`).** No temperature / electrochemistry / gas / cryostat device is PV-bound. When it lands it reuses `TemperatureController` / the graduated `FlowController` and the Subject / Supply / Procedure seam, not a new family. -- **The resonant energy axis and polarization analysis (`RESONANT-1`).** The energy axis is a non-functional stub; no polarization analyzer or phase retarder is bound. When wired, the energy axis is a `PseudoAxis` over the DCM and polarization hardware reuses the catalog `PhaseRetarder` and `PolarizationAnalyzer` (4-ID). -- **The flux monitors (`DET-1`).** The QuadEM electrometers and the secondary-source slit are defined but commented out in source; not modelled until live. -- **The Methods.** Whether `resonant_scattering` and `diffraction` enter CORA's catalog is an owner decision; the Practices render unlinked, pending (`TECH-1`). -- **The simulated devices and full asset-tree scenarios.** No `test_isr_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive, and whose primary instrument is not even in source, would be invention; they land when the diffractometer is bound and the team confirms. - -## Open questions - -*What CORA needs the ISR team to confirm before the model can be trusted.* - -ISR was reverse-engineered from the beamline's own bluesky profile collection ([NSLS2/isr-profile-collection](https://github.com/NSLS2/isr-profile-collection)), which is an early / commissioning, optics-first scaffold. The control handles on the [device pages](index.md) are the beamline's real PVs, read from the `startup/` files rather than confirmed by staff, and the devices ISR's mission implies are largely absent from the source. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### The mission gaps (the headline) - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DIFF-1 | Blocks-go-live | The multi-circle diffractometer: only two axes (`th`, `zeta`) are bound under the `Dif:ISD` IOC. What are the full sample-orientation circles, the detector two-theta arm, and the reciprocal-space / hkl engine that resonant and surface (CTR) diffraction need? | One `RotaryStage` for the two bound axes; the full diffractometer is absent and not modelled. | The sample-orientation and detection-geometry modelling. | -| INSITU-1 | Blocks-go-live | The in-situ sample environment: despite In Situ being the beamline's name, no temperature controller, electrochemistry / potentiostat, gas / flow, or cryostat is PV-bound. Which in-situ environments exist and what are their PVs? | No in-situ device modelled; carried as a named gap. | The in-situ sample-environment modelling. | -| RESONANT-1 | Blocks-go-live | The resonant energy axis and polarization analysis: the DCM Bragg is the physical energy axis but a wired energy pseudo-axis is only a non-functional stub, and no polarization analyzer or phase retarder is bound. How is energy scanned for resonant work, and is polarization analyzed? | Energy via the DCM Bragg; no energy pseudo-axis or polarization device modelled. | The resonant-scattering modelling. | - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | Are the optics zones (FE:C04A, XF:04IDA-OP, XF:04IDB-OP) and the zone-D endstation (XF:04IDD-ES) separate hutches? | Two enclosures: an `isr-optics` zone and the `isr-endstation` hutch. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The in-vacuum undulator model and energy range (only a read-only gap encoder is bound; no gap-drive setpoint). | An `InsertionDevice` undulator, observed gap; parameters pending. | The source Asset detail. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MACHINE-1 | Nice-to-have | The storage-ring state ISR reads (only the ring current is bound). | Observe-only machine state, a loose `StorageRing`; the rest pending. | The machine-state observation. | -| MONO-1 | Blocks-go-live | The DCM crystal cut (Si(111) / Si(311)) and the energy range. | A double-crystal `Monochromator`; the crystal cut and range pending. | The monochromator Asset. | -| OPT-1 | Nice-to-have | The focusing-mirror pair (HFM / VFM) and harmonic-rejection mirror (DHRM) coatings and bend mechanisms. | Bendable focusing + harmonic-rejection mirrors bound to `Mirror`; coatings pending. | The mirror Asset detail. | -| OPT-2 | Nice-to-have | The front-end slit blade-axis map, and the secondary-source (SSA) slit (defined but commented out in source). | A front-end `Slit`; the SSA carried as a deferred gap. | The slit Asset detail. | -| ATTN-1 | Nice-to-have | The four-foil attenuator bank (bit-encoded transmission level) and its calibration. | The foils bound to `Filter`. | The attenuator Asset. | - -### Detection - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The Eiger 1M model and the write path (a commissioning `testing/` path in source), and the flux monitors (the QuadEM electrometers are defined but commented out; there is no point / scaler detector for diffraction counting). | One `Camera` Asset (Eiger 1M); no `FluxMonitor` Asset modelled until the electrometers are live. | The detector and flux-monitor modelling. | -| DIAG-1 | Nice-to-have | The diagnostic screen cameras and the motorized beam-position monitor (only its stage motors are bound; the electrometers are commented out), and the position-versus-intensity split (the fleet-wide question). | `Camera` for the screens; the graduated catalog `PositionMonitor` for the BPM stage (presents Sensor, distinct from `FluxMonitor` by measuring beam position). | The diagnostic modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the EPICS PV handles read from the profile collection current and correct, and is the profile representative of production (the databroker catalog is a placeholder name and several devices are commented out, both commissioning signals)? | The handles in the descriptor are taken from the profile collection and carried confirm; the data plane (bluesky-queueserver + Tiled) is the seam CORA's edge replaces. | Verifying each Asset's control handle and the data plane. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit signals and the photon / front-end shutters (no PSS / shutter / hutch-interlock device is in the profile collection). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent (the optics) and the cooling supply. | Photon beam, cooling water, and vacuum on the optics. | The Supply observations. | -| GOV-1 | Nice-to-have | The NSLS-II operator pool and safety-review structure (site-level, shared across the beamlines). | Carried pending on the NSLS-II Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Blocks-go-live | Do resonant scattering and surface (CTR) diffraction enter CORA's catalog as Capabilities / Methods? | Deferred: carried as pending Practices reusing the 4-ID / CSX `resonant_scattering` and 4-ID / 8-ID `diffraction` Methods; doubly deferred because the diffractometer is absent from source (DIFF-1). | The technique Capabilities. | diff --git a/docs/deployments/iss/notes.md b/docs/deployments/iss/notes.md deleted file mode 100644 index dbe0651cb61..00000000000 --- a/docs/deployments/iss/notes.md +++ /dev/null @@ -1,106 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at ISS: X-ray absorption and X-ray emission spectroscopy, each a [Catalog](../../catalog/methods.md) Method. ISS follows the deferral discipline of the beamlines that brought spectroscopy to CORA.* - -ISS's measurement is energy spectroscopy: it sweeps the incident energy across an absorption edge (EXAFS) and, with the crystal emission spectrometers, resolves the emitted spectrum (XES) or selects an emission line during the incident-energy sweep (HERFD). The Methods below render unlinked and are carried pending until the owner-scope decision (TECH-1) brings them into the catalog. - -| Technique | Mode | Notes | -| --- | --- | --- | -| X-ray absorption (EXAFS) | transmission / fluorescence, energy fly-scan | I0 / It / Ir ion chambers or the Xspress3 SDD over a trajectory energy sweep; the BMM energy-scan question (ENERGY-1, TECH-1) | -| X-ray emission (XES) | emission spectrometer, fixed incident energy | the Johann or von Hamos crystal spectrometer disperses the emitted spectrum onto the area detector (SPEC-1, TECH-1) | -| HERFD | emission spectrometer, incident-energy fly-scan | high-energy-resolution fluorescence detection: scan the incident energy, read one emission line through the analyzer (ENERGY-1, SPEC-1) | - -All three need the [sample stage](sample.md) and a [detector](detector.md); the trajectory fly-scan sweeps the energy and the analog pizza box reads the detectors synchronously. - -### Why the Method scope stays pending - -ISS's absorption and emission both lean on energy spectroscopy CORA carries pending. EXAFS is the energy-sweep-as-the-measurement case BMM raised: the `energy_scan` Capability is anticipated in the catalog but deferred until a conduct-path forces it (ENERGY-1), and a descriptor scaffold does not force it; ISS is a further consumer that strengthens the case without coining it. The emission techniques (XES, HERFD) are the same shape LCLS-MFX left pending as the `xas_spectroscopy` Method (XAS / XES via the emission spectrometer), so ISS **reuses** that Method as the second consumer rather than coining a new one (TECH-1), and records that one pending Practice on the [NSLS-II Site](../nsls2/index.md). The device Roles already exist (the ion chambers present Sensor, the SDD the energy-dispersive Sensor, the emission spectrometers the Detector Role); what is new is the science Method, not a device shape. - -The per-technique reduction (EXAFS normalization and fitting, XES / HERFD spectra) is `ComputePort` work, not beamline Methods. - -## Governance - -*Who may act at ISS and the trust shape CORA applies. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority.* - -People and agents are facility principals at the [NSLS-II Site](../nsls2/index.md#safety-and-governance); on the beamline they surface through the actions they take. The human roster is not known from the profile collection (GOV-1), so the principals are the design shape, not a registered list. - -### Who acts - -CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the NSLS-II Site. An ISS beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. - -### The trust boundary - -CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may load an energy trajectory, sweep the energy, start an acquisition, move the emission-spectrometer crystals, run an in-situ program, override a caution, or commit an energy calibration. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer. The NSLS-II proposal and cycle are a fact CORA's Campaign uses for custody. - -### The energy-scan under custody - -ISS's defining operation is the trajectory energy fly-scan, which couples the monochromator, the encoder, and the streaming detectors as one timed sweep. CORA's Campaign and Trust shapes are where that resolves: loading and starting a trajectory is a command the trust boundary gates, and the per-scan energy calibration (the reference foil read on the reference ion chamber) is a committed fact under custody, not an ad-hoc adjustment. If an autonomous Agent were added to drive the EXAFS / HERFD program (a common pattern at high-throughput XAS beamlines), it would be a facility principal scoped at the Site, governed by the same trust boundary, with each choice recorded as a [Decision](../../architecture/modules/decision/index.md). None is declared yet. - -## Model - -*The developer's by-kind index: where each CORA aggregate's ISS content lives. It hosts no content of its own. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC -[modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at ISS | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (EnergyAxis) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [The beamline](index.md#enclosures) (8-ID-A optics, 8-ID-B experiment) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What this deployment graduates - -ISS earns one catalog change: the **`EmissionSpectrometer`** Family GRADUATED. LCLS-MFX introduced it for its von Hamos six-crystal XES spectrometer and carried it loose at n=1 (SPEC-1, with MAX IV Balder noted as a near-sighting). ISS's Johann and von Hamos crystal emission spectrometers are the **second** sighting, earning the rule-of-three the way `GratingMonochromator` (CSX), `Manipulator` (ESM), and `ElectronAnalyzer` (SST) graduated at their second sighting. The abstraction is settled (a crystal-analyzer emission spectrometer composing analyzer crystals and a 2D detector along a Rowland-circle or wavelength-dispersive geometry is a distinct, recurring device, not a point Sensor and not a beam-conditioning Monochromator), so it GRADUATED into the catalog (SPEC-1); LCLS-MFX's references were swept loose to graduated alongside. It stays distinct from the still-loose `EnergyAnalyzer` (the IXS diced-crystal energy-selecting analyzer, ANALYZER-1), which graduates nothing until its own rule-of-three, and from the catalog `SpectrometerArm` (the SIX soft X-ray grating dispersive RIXS arm, since graduated across SIX + ID32 + ID28, RIXS-1). - -### Deliberately not here yet - -This is a design-phase scaffold (descriptor + docs), mirroring the other NSLS-II and Diamond beamlines. Left out on purpose: - -- **No new loose Family.** ISS is otherwise a reuse deployment: the trajectory and high-resolution monochromators bind `Monochromator`, the mirrors `Mirror`, the filter box `Filter`, the slits `Slit`, the shutters `Shutter`, the energy axis `PseudoAxis`, the sample stage `LinearStage`, the goniometer `Goniometer`, the reference foil wheel `RotaryStage`, the thermal stage `TemperatureController`, the ion chambers `FluxMonitor`, the Xspress3 SDD `EnergyDispersiveSpectrometer`, the Pilatus `Camera`, the trajectory controller `MotionController`, the analog pizza box `TimingController`. -- **The graduated `PositionMonitor`.** The beam-position diagnostics bind the graduated catalog `PositionMonitor` Family that the wide fleet shares; it presents the `Sensor` Role, earned across that fleet, distinct from `FluxMonitor` by measuring beam position rather than flux. The per-Asset beam-position channel map is the residual (`DIAG-1`). -- **No new Capability or Method.** EXAFS leans on the deferred `energy_scan` Capability (ENERGY-1, the BMM question; ISS strengthens it as a further consumer without forcing it); XES / HERFD reuse the `xas_spectroscopy` Method LCLS-MFX left pending, the second consumer (TECH-1). ISS records that one pending Practice and coins nothing. The per-technique reduction is `ComputePort` work. -- **The deferred in-situ environment.** The ion-chamber fill-gas mass-flow controllers (He / N2) would bind the graduated `FlowController` Family, but they and the broader in-situ sample environment are named in a question (`ENV-1`) rather than modelled at this design phase. ISS models the main transmission / fluorescence / emission legs as the representative configuration. -- **Operations and experiment views, integration scenarios, vendor Models.** A runbook and registered Assets for a beamline CORA does not yet drive would be invention; they land when the design firms and the team confirms. - -## Open questions - -*What CORA needs the ISS team to confirm. This model is reverse-engineered from public open source (the `NSLS2/iss-profile-collection` bluesky / ophyd startup files): the EPICS PVs are read from the `startup/*.py` device classes, but undulator parameters, crystal cuts, vendor identities, and physical positions are not. Each row is a fact the beamline team owns. It is a delete-on-answer queue.* - -Priorities: `Blocks-build`, `Blocks-go-live`, `Nice-to-have`. - -### Source and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Nice-to-have | The 8-ID insertion-device identity, period, and gap range. The profile collection drives photon energy through the HHM trajectory and does not expose the undulator gap PVs; only the ring current (`SR:OPS-BI{DCCT:1}`) is read. | An in-vacuum undulator on the 3 GeV ring, identity-only. | The InsertionDevice settings. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit-leaf PVs. Only the shutters (`XF:08ID-PPS{Sh:FE}`, `XF:08IDA-PPS{PSh}`) are in source. | The permit signal is a confirm note, not a guessed PV. | The Enclosure permit signals. | - -### Optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DCM-1 | Nice-to-have | The HHM and HRM crystal cuts, reflections, and energy ranges. Both monochromators (`Mono:HHM`, `Mono:HRM`) and the HHM trajectory controller (`MC:06`) are in source. | One trajectory DCM and one high-resolution mono Asset, crystal settings blank. | The Monochromator settings. | -| ENERGY-1 | Nice-to-have | ISS's measurement sweeps the energy axis (EXAFS) as a trajectory fly-scan, the textbook case for the energy-scan Capability the catalog anticipates. Does CORA coin `energy_scan` now, or keep it deferred until a conduct-path forces it? | Energy-scan deferred (the BMM question); ISS is a further consumer that strengthens the case. | The energy-scan Capability decision. | - -### Sample and detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SPEC-1 | Blocks-go-live | The Johann and von Hamos crystal emission spectrometer geometry: the analyzer crystal cut, the Rowland-circle radius, and whether each of the (Johann: main + four auxiliary) analyzer crystals is a child Asset or a setting on the one spectrometer Asset. | Two `EmissionSpectrometer` Assets (catalog Family, graduated at this 2nd sighting after LCLS-MFX); crystals as settings for now. | The emission-spectrometer model and analyzer-crystal composition. | -| DET-1 | Blocks-go-live | The detector roster: the ion-chamber channel map (I0 / It / Ir / If through the ICAmplifier / Keithley-428 amps and the analog pizza box), the Xspress3 element count and ROI map, and which Pilatus serves which spectrometer. | The ion chambers, the 4-channel Xspress3, and one Pilatus modelled; channel maps blank. | The detector roster and channel maps. | -| TEMP-1 | Nice-to-have | Which sample-environment thermal units are live (the Lakeshore 331 is in source; cryostat / furnace not). | One `TemperatureController` Asset; the others noted. | The sample-environment Assets. | -| ENV-1 | Nice-to-have | The ion-chamber fill-gas flow (He / N2 mass-flow controllers `XF:08IDB-OP{IC}FLW:`) and the broader in-situ sample environment. The mass-flow controllers would bind the graduated FlowController Family; the broader environment is deferred at this design phase. | Deferred; fill gas and in-situ environment named here, not modelled. | The fill-gas and in-situ Assets. | -| DIAG-1 | Nice-to-have | The beam-position channel map (the Prosilica BPM cameras and the sample-positioner cameras); the `PositionMonitor` Family is settled (graduated catalog Family presenting `Sensor`, distinct from `FluxMonitor` by measuring beam position rather than flux). | Read-only beam-position (graduated catalog `PositionMonitor`) probes; channel map blank. | The PositionMonitor bindings. | - -### Controls and technique scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DRIVE-1 | Blocks-go-live | The motion-controller box models, firmware, and IPs (the Delta-Tau HHM trajectory controller `MC:06`, the von Hamos `MC:3-Ax:` axes, and the EPICS motor records). | Families bound (MotionController), specifics blank. | The MotionController Models. | -| TECH-1 | Blocks-go-live | Do the X-ray absorption (EXAFS) and X-ray emission (XES / HERFD) techniques enter CORA's catalog as Methods, or stay pending? ISS reuses the `xas_spectroscopy` Method LCLS-MFX left pending, the second consumer. | The `xas_spectroscopy` Method reused pending; no new Method coined (the BMM / SST deferral discipline). | The technique Method scope. | diff --git a/docs/deployments/ixs/notes.md b/docs/deployments/ixs/notes.md deleted file mode 100644 index ae6693c275d..00000000000 --- a/docs/deployments/ixs/notes.md +++ /dev/null @@ -1,142 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of IXS 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. IXS's technique is momentum-resolved hard X-ray inelastic scattering, the fleet's first energy-loss method, so the Method below renders unlinked and is carried pending until a technique enters scope (`TECH-1`). - -### Momentum-resolved inelastic X-ray scattering - -IXS sets the momentum transfer Q with the six-circle reciprocal-space arm, then scans the incident energy against a fixed crystal analyzer and counts the energy-analyzed scattered photons, so the measurement is the intensity surface I(Q, energy-loss): how much energy the sample exchanges with the photon at a chosen momentum transfer. The energy loss is read as the difference between the scanned incident energy and the fixed final energy the analyzer passes. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Momentum-resolved inelastic X-ray scattering | `inelastic_scattering` | Q is set on the [six-circle spectrometer arm](detector.md) via the H/K/L reciprocal-space pseudo-axis; the incident energy is scanned on the [double-crystal and high-resolution monochromators](source.md) against the fixed [crystal energy analyzer](detector.md); the energy-analyzed signal is point-counted on the electrometers; Method not yet in catalog | - -It needs the [incident-energy chain](source.md) (the DCM for the coarse energy and the high-resolution monochromator for the meV steps), the [sample stage](sample.md), and the [six-circle arm, crystal energy analyzer, and counting detectors](detector.md). The arm scattering angle sets the magnitude of the momentum transfer; the analyzer fixes the final energy so the incident-energy scan reads out the energy loss. - -### A new operating axis for the fleet - -Energy loss is genuinely new for the fleet. The catalog already covers elastic scattering (SAXS/WAXS, XPDF, powder, XPCS, MX), XRF microprobe, hard X-ray absorption (BMM), and soft resonant inelastic scattering (SIX), but no hard inelastic scattering. The new axis is the acquisition shape itself: scan one optic (the incident energy) against a second, fixed energy-selecting optic (the crystal analyzer) while a point detector counts, rather than expose an area detector at one energy. That is a new Capability, deferred as a question (`TECH-1`); it forces no new device families beyond the loose [`EnergyAnalyzer`](#new-loose-families). - -### Not modelled yet - -The concrete acquisition recipes (the incident-energy maps, the per-Q energy scans, the analyzer alignment, and the counting times) are not written yet; they join as the deployment approaches the point where CORA drives IXS. Whether the technique enters CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); hard inelastic scattering is a new regime for the fleet (see [Open questions](#open-questions) for the world-facts to confirm first). - -## Governance - -*Who will act at IXS, and the trust shape that will gate it. First cut.* - -Governance at IXS 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). - -IXS is not yet driven by CORA, so this shape is not yet instantiated. As a modelling-exercise scaffold, the deployment is descriptor and docs today, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized. 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), shared with the rest of the fleet (`GOV-1`). - -The safety tier is the other piece that is not yet settled. The PSS search-and-secure permit signals and the front-end and photon shutters are absent from the beamline's profile collection, so the Enclosure permit leaves and the interlock structure are carried pending and are not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [NSLS-II Site](../nsls2/index.md), not on the beamline, and the beamline links up to them. IXS adds the hazard classes that come with a hard X-ray endstation under vacuum and a temperature-stabilized crystal analyzer; those land with the instruments that bring them, and an experiment Clearance would carry them. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives IXS, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's IXS content lives, the one new loose family this first hard inelastic-scattering deployment introduces, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at IXS | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (the reciprocal-space `PseudoAxis`) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes IXS new - -IXS is CORA's first photon-in / photon-out energy-LOSS technique. The fleet already has elastic scattering (SAXS/WAXS, XPDF, powder, XPCS, MX), XRF microprobe, hard X-ray absorption (BMM), and soft resonant inelastic scattering (SIX), but no hard inelastic scattering. The novelty is the acquisition shape: set the momentum transfer Q with a six-circle reciprocal-space pseudo-axis, then scan the incident energy (the DCM, and the high-resolution monochromator for meV steps) against a fixed crystal analyzer, point-detecting the energy-analyzed scattered beam to build I(Q, energy-loss). That is a new Capability, deferred as a question (TECH-1); it forces no new device families beyond the analyzer below. - -### New loose families - -IXS introduces one device class no existing catalog Family covers: the crystal energy analyzer. Per earn-the-abstraction, it is held **loose at n=1** and graduates nothing: a second independent hard crystal-analyzer beamline must earn the abstraction before any catalog change. The name was cleared by the naming-r3 gate. - -| Loose family | Presents (when graduated) | What it is | Earns when | -| --- | --- | --- | --- | -| `EnergyAnalyzer` | Positioner (Sensor-vs-Positioner a confirm) | a diced multi-crystal Bragg analyzer that selects the final photon energy of the scattered beam, focusing energy-selected photons onto the point detectors | a 2nd hard crystal-analyzer / IXS beamline (`ANALYZER-1`) | - -`EnergyAnalyzer` is deliberately not stretched onto an existing Family. It is not the catalog `EnergyDispersiveSpectrometer` (a per-event point Sensor that reads energy, where the analyzer positions crystals and the reading happens downstream at the electrometers), nor the catalog `Monochromator` (an upstream incident-beam optic), nor the catalog `SpectrometerArm` (the energy-dispersive arm SIX coined, since graduated; IXS uses a driven scanning crystal analyzer, not a dispersive one). naming-r3 chose `EnergyAnalyzer` over `Analyzer` and `CrystalAnalyzer`: it is the `Analyzer` sibling of the catalog `PolarizationAnalyzer` (the qualifier names the analyzed quantity), and it avoids the `CrystalAnalyzer` / `AnalyzerCrystal` read-aloud homograph. Whether `EnergyAnalyzer` and `PolarizationAnalyzer` later merge into one `Analyzer` Family differentiated by a setting is the open `ANALYZER-1`, a gate decision at the second sighting, not this PR's. - -### Deliberately not here yet - -- **The six-circle arm binds the catalog `Goniometer`, not a new family.** The spectrometer arm (tth / th / chi / phi driven by the H/K/L reciprocal-space pseudo-axis) is the 8-ID / 4-ID six-circle diffractometer anatomy. In descriptor mode it binds the catalog `Goniometer` directly (the 8-ID / 4-ID scaffold pattern), and SIX's dispersive `SpectrometerArm` is the wrong anatomy for a driven scanning arm. The reciprocal-space layer binds the catalog `PseudoAxis`. - -- **The analyzer-Assembly question (`ANALYZER-1`).** Whether the crystal analyzer plus the six-circle arm compose an `Assembly(Diffractometer)`-style Fixture is deferred, exactly as 8-ID and 4-ID deferred materializing their diffractometer Assemblies in descriptor mode. The first cut is a flat loose `EnergyAnalyzer` Asset plus a `Goniometer` arm Asset, with the Assembly named as the follow-on. An Assembly is earned at n=2 across independent beamlines; coining one at n=1 would be over-modelling. - -- **The diced-crystal identity (`XTAL-1`).** The six diced crystals each carry their own theta / phi and PID temperature, so each is identity-bearing. The lower-risk first cut carries them as settings on the one `EnergyAnalyzer` Asset; promoting each to a child Asset via `parent_id` is exactly the nested-component-identity convention, which is itself at a rule-of-three gate (applied only for `RotaryDriveChassis` so far), so IXS flags `XTAL-1` as a candidate trigger rather than asserting it. The six crystal-temperature PID loops are carried as one `TemperatureController` Asset for the same reason (`TEMP-1`). - -- **The high-resolution-mono beamstop (`HRM-1`).** The high-resolution monochromator carries an in-line beamstop; whether it is a distinct child `BeamStop` Asset is gated under the same nested-component rule-of-three. - -- **The IXS Method.** Whether momentum-resolved inelastic scattering enters CORA's catalog as a Capability / Method is an owner decision; the Practice renders unlinked, pending (`TECH-1`). - -- **The simulated devices and full asset-tree scenarios.** No `test_ixs_*.py` registers the IXS 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). - -## Open questions - -*What CORA needs the IXS team to confirm before the model can be trusted.* - -IXS was reverse-engineered from the beamline's own bluesky profile collection ([NSLS2/ixs-profile-collection](https://github.com/NSLS2/ixs-profile-collection)), so the control handles on the [device pages](index.md) are the beamline's real PVs, read from the `startup/*.py` files rather than confirmed by staff. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet), including the new loose `EnergyAnalyzer` family). 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 | -| --- | --- | --- | --- | --- | -| TOPO-1 | Blocks-build | Does 10-ID share a canted straight with a sibling beamline, or run off its own undulator in series? | One root Unit Asset `IXS` on its own straight. | The source topology in the [descriptor](index.md). | -| ENC-1 | Blocks-go-live | Are the PV zones `XF:10IDA/B/C/D` four separate shielded hutches or beam zones within fewer hutches? | Four enclosures, one per zone. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The IVU22 undulator period and type. | An in-vacuum undulator on `SR:C10-ID:G1{IVU22:1}`, period carried pending. | The source Asset detail. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MACHINE-1 | Nice-to-have | The storage-ring state IXS reads (current, fill, top-up). | Observe-only machine state on `SR:OPS-BI{DCCT:1}`, a loose `StorageRing`. | The machine-state observation. | -| FEEDBACK-1 | Nice-to-have | How should the source-orbit feedback (`SR:UOFB`) be modelled, if at all? | Carried family-less, modelling deferred (the i03 `XBPMFeedback` precedent). | The feedback Asset. | -| MONO-1 | Blocks-go-live | The DCM crystal cut / d-spacing, the incident-energy range, and the energy pseudo-axis partition rule. | Si(111) DCM, range 7.835-17.7 keV, energy via the DCM Bragg angle coupled to the undulator gap. | The monochromator and incident-energy Assets. | -| HRM-1 | Blocks-go-live | The high-resolution monochromator crystals, its meV resolution, and whether its in-line beamstop is a distinct identity-bearing Asset. | A second crystal `Monochromator` Asset; the beamstop carried as a note, not yet a child Asset. | The high-resolution mono Asset. | -| OPT-1 | Nice-to-have | The mirror coatings, bend mechanisms, and axis roles (VFM / HFM). | Grazing-incidence focusing mirrors bound to `Mirror`; coatings pending. | The mirror Asset detail. | -| OPT-2 | Nice-to-have | The blade-axis roles of each slit (front-end, DCM, SSA, transport, endstation, analyzer). | Four-blade variable openings bound to `Slit`. | The slit Asset detail. | -| PH-1 | Nice-to-have | Is the focusing pinhole a positioned beam-shaping aperture (`Aperture`) or a plain fixed opening (`Mask`)? | Bound to `Aperture` on the round-opening precedent; the catalog wording leans `Mask`. | The pinhole Family. | -| MCM-1 | Nice-to-have | Is the MCM optics manipulator six coupled parallel-kinematics axes (a `Hexapod`) or independent serial rotations? | A coupled six-DOF `Hexapod`. | The manipulator Family. | - -### Sample and spectrometer - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SAMPLE-1 | Blocks-go-live | Are the sample table (`Spec:1`) and the sample-environment translations (`Env:1`) one fused stage or two siblings, and what is mounted on them? | Two sibling `LinearStage` Assets on their separate PV roots. | The sample-stage modelling. | -| ANALYZER-1 | Blocks-build | How is the crystal energy analyzer configured: the diced-crystal Bragg geometry, the analyzed final energy, and whether it shares mechanics with the six-circle arm? | A diced multi-crystal Bragg analyzer on the spectrometer arm, selecting a fixed final energy. | The analyzer geometry; the CORA structural modelling is on [Model](#deliberately-not-here-yet). | -| XTAL-1 | Blocks-go-live | Are the six diced analyzer crystals individually addressed (each its own theta / phi and temperature loop), and do they act as one analyzer? | Six crystals, each with theta / phi and a PID temperature, acting as one analyzer. | The diced-crystal addressing; the child-Asset modelling is on [Model](#deliberately-not-here-yet). | -| TEMP-1 | Nice-to-have | Are the six crystal-temperature PID loops one Asset or six, and do they parent to the analyzer or to per-crystal child Assets? | One `TemperatureController` Asset noting six PID channels. | The thermal-control modelling. | - -### Detection - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The electrometer / scaler channel map: which channels are the analyzed-signal detector, which is I0, and whether the analyzer-focus photodiode is a separate Asset or a channel. | Quad electrometers + the scaler I0 bound to `FluxMonitor`; the focus diode is a channel, not a standalone Asset. | The detector modelling. | -| ENERGY-1 | Nice-to-have | The read-only derived diffractometer angles (`HKLDerived`) present the Sensor read-back facet, not a driven axis. | A read-back facet of the reciprocal-space `PseudoAxis`. | The pseudo-axis read modelling. | -| DIAG-1 | Blocks-go-live | The beam-position monitors bind the graduated catalog `PositionMonitor` Family; what beam-center calibration and diagnostic-foil channel detail do they need? | The graduated catalog `PositionMonitor` (presents `Sensor`, distinct from `FluxMonitor` by measuring beam position rather than flux), the NSLS-II sibling choice; beam-center and foil channels to supply. | The beam-position-monitor calibration and channel detail. | -| BPM-1 | Nice-to-have | Which monitors are true beam-position monitors versus intensity (I0) normalizers? | Treated as beam-position monitors; the intensity ones would be `FluxMonitor`. | The position-vs-intensity split. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the EPICS PV handles read from the ixs-profile-collection current and correct? | The handles in the descriptor are taken from the profile collection and carried confirm. | Verifying each Asset's control handle. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit signals and the front-end / photon shutters (absent from the profile collection). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| GOV-1 | Nice-to-have | The NSLS-II operator pool and safety-review structure (site-level, shared across the beamlines). | Carried pending on the NSLS-II Site, not instantiated per beamline. | The governance principals. | -| SUP-1 | Nice-to-have | The vacuum extent and the analyzer thermal-stabilization supply. | Photon beam, cooling water, and vacuum on the optics and spectrometer path. | The Supply observations. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Blocks-go-live | Does the momentum-resolved inelastic-scattering technique enter CORA's catalog as a Capability / Method? | Deferred: carried as a pending Practice, no `cora.capability.ixs` coined. | The IXS Capability. | diff --git a/docs/deployments/lcls-mfx/notes.md b/docs/deployments/lcls-mfx/notes.md deleted file mode 100644 index f158cb7f0aa..00000000000 --- a/docs/deployments/lcls-mfx/notes.md +++ /dev/null @@ -1,136 +0,0 @@ -# Notes - -## Techniques - -*What MFX is designed to do, as design intent. Design-phase: these are Methods CORA would earn, not Methods it has.* - -MFX runs three technique families, none of which fits the catalog's tomography Methods, so each is carried pending on the [SLAC Practices](../slac/index.md) until it is earned. They are listed here as design intent, with the shape each would take over the spine and the gap each leans on. - -### Serial femtosecond crystallography (SFX) - -A stream of microcrystals is delivered into the focused FEL beam (liquid jet or fixed target); each X-ray pulse destroys its crystal but records a diffraction pattern first ("diffraction before destruction"). The dataset is millions of single-shot patterns, indexed and merged downstream. - -- **Spine shape:** a `serial_crystallography` Method binding the focusing lenses, the sample delivery, the pulse picker, and the area detector, over a Run that is a free-running per-shot acquisition rather than a trajectory of points. -- **Gap it leans on:** the per-shot, pulse-ID-tagged event DAQ (DAQ-1). This is the technique that most exposes the acquisition-ontology gap: there is no trajectory to walk, only a shot stream to tag and reference. - -### Femtosecond optical pump-probe - -An optical laser pulse excites the sample a controlled femtoseconds before (or after) the X-ray probe pulse; scanning the delay resolves dynamics in time. - -- **Spine shape:** a `pump_probe` Method that scans the laser-to-X-ray delay (a `LinearStage` delay axis) while acquiring per-shot, with the timetool correcting residual jitter shot by shot. -- **Gap it leans on:** the cross-timing-domain synchronization (LASER-1). The delay axis itself is a positioner; what CORA cannot express is the femtosecond synchronization between the optical-laser and FEL timing domains (the `lxt_ttc` SyncAxis). - -### X-ray emission spectroscopy (XES / HERFD) - -The von Hamos 6-crystal spectrometer disperses the X-ray fluorescence emitted by the sample onto a 2D detector, resolving emission energy; in HERFD mode the incident energy is scanned at a fixed emission line. - -- **Spine shape:** an `xas_spectroscopy` Method binding the emission spectrometer and, for HERFD, the incident-energy choreography (the DCCM), over a per-shot acquisition. -- **Gap it leans on:** the emission spectrometer binds the `EmissionSpectrometer` family it introduced, since graduated once ISS earned the 2nd sighting (SPEC-1 now tracks only the analyzer-crystal composition), and HERFD's incident-energy scan reuses the energy-change choreography CORA already models well. - -### Why none is in the catalog yet - -The catalog's Methods are all tomography-family (`tomography`, `dark_field`, `flat_field`, the alignment and energy-change methods). An XFEL shares none of them: there is no rotation, no flat / dark frame pairing, no storage-ring energy ramp. Coining XFEL Methods now, before the acquisition axis they depend on exists, would be inventing recipes for a spine that cannot yet run them. So each is carried pending, naming the Method it would earn, and the deepest dependency (the event-stream acquisition axis, DAQ-1) is sketched as a design note rather than built. See [Model](#model) for the gap register. - -## Governance - -*Who would act at MFX and the trust shape that gates their commands. Design-phase: the principals are facility-level and carried pending.* - -MFX's principals are facility principals at the [SLAC Site](../slac/index.md), not beamline-local: the LCLS instrument-scientist and operator pool, and the LCLS safety-review body. Both are carried pending in the [site descriptor](../slac/index.md) until the LCLS structure is confirmed. CORA's role kernel (the five-role authorization model) is facility-invariant, so MFX inherits it; what MFX adds to think about is two hazard gates the storage-ring exercises do not have. - -### The pump-probe laser Clearance - -MFX runs a class-4 optical laser for pump-probe, governed at LCLS by the Beam Transport Protection System (BTPS). CORA carries this as a `Clearance` hazard on the experiment (a facility-issued safety permit that must be Active before laser-on work), the same posture 32-ID takes for its additive-manufacturing laser. This is distinct from whether the laser is a driven Asset: the device folds into the catalog `Laser` Family (the 4-ID precedent), while the personnel-safety permit is a Clearance. The two coexist (LASER-1). - -### The PPS permit - -As at every beamline, beam-on work in an enclosure is gated by the facility personnel protection system (PPS). The LCLS PPS search-and-secure permit signals are not in `pcdshub` and are carried pending (PSS-1). MFX's enclosure structure (a shared front-end / transport zone plus the MFX experiment hutch) is itself carried `confirm` because the `pcdshub` PV prefixes encode beamline-line zones, not access-gated hutches (ENC-1). - -### What is not modelled - -- **Trust instantiation.** No scenario instantiates MFX trust zones or actors; this is a design-phase modelling exercise, so the governance shape is described, not seeded. -- **The DAQ and analysis software as principals.** The LCLS DAQ, `psana`, and the bluesky-based scan suite are control-system software on the floor, not CORA actors (see [Controls](controls.md)). When the per-shot acquisition axis is designed (DAQ-1), the question of which principal authorizes a DAQ run is part of that work. - -People and agents are facility principals at the [SLAC Site](../slac/index.md); see [Open questions](#open-questions) for the governance items still to confirm. - -## Model - -*The developer's by-kind index: where each CORA aggregate's LCLS-MFX content lives, how the device families fold while the gaps stay architectural, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at LCLS-MFX | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### The headline: the families fold, the gaps are architectural - -I03 graduated a device Family (Goniometer). MFX coined exactly one new family and reused everything else, and that is the finding. Of MFX's full device set, one type had no CORA Family, the von Hamos emission spectrometer; it introduced `EmissionSpectrometer`, which has since GRADUATED into the catalog once NSLS-II ISS (8-ID) earned the second sighting (SPEC-1). Everything else reuses an existing Family: the offset mirrors fold into `Mirror`, the solid-Si attenuators into `Filter`, the JAWS into `Slit`, the pulse picker into `Shutter` (PULSE-1), the profile imagers into `Scintillator` + `Camera`, the intensity-position monitors into `FluxMonitor` + `Diagnostic`, the channel-cut into `Monochromator`, the lens stacks into the graduated `Transfocator` catalog Family, the EventSequencer into `TimingController`, the pump-probe laser into the catalog `Laser` Family (the 4-ID precedent), and the area detector into `Camera`. Each fold was reviewed against coining a synonym and rejected. - -So the device taxonomy generalizes from storage rings to an XFEL almost untouched. What does not generalize is the **acquisition ontology**. That is the product of this exercise, recorded next. - -### Deliberately not here yet (the architectural gap register) - -These are the parts of MFX this scaffold leaves out on purpose. Unlike the open questions (facts the LCLS team owns), each of these is a CORA scope decision: a shape the model does not yet have, with the seam it would extend named. None is built speculatively; an XFEL is the trigger that would justify the work. - -- **Per-shot, pulse-ID-tagged event DAQ (DAQ-1).** The load-bearing gap. CORA's acquisition is a single-detector poll-to-Done loop (`apps/api/src/cora/operation/acquisitions.py`) plus a sub-Hz scalar observation logbook with no pulse-ID key (`apps/api/src/cora/run/aggregates/run/entries.py`). An XFEL collects a free-running stream of per-shot frames correlated by fiducial at beam rate. The Run-as-provenance-envelope survives and the per-shot data plane lives in `psana` (CORA references a `Dataset`, as it does for reconstructions via `ComputePort`), but representing a DAQ run as an actuation is a new event-stream axis. Its shape is sketched as a forward-looking design note in CORA's design memory (gated, not built). -- **Beam-synchronous event-code timing (TIMING-1).** The EventSequencer plays a sequence of `[beam_code, delta_beam, delta_fiducial, burst_count]` lines that gate acquisition at beam rate. CORA's `TimingController` Family carries the device, but "acquire on event-code N at rate R, burst B" has no typed parameter home; today it would be opaque setpoints. -- **Femtosecond pump-probe synchronization (LASER-1).** The optical laser and the FEL are two synchronized timing domains (the `lxt_ttc` SyncAxis holds a ~50 fs deadband; the timetool corrects residual jitter). CORA's `PartitionRule` is single-domain spatial math; a cross-timing-domain synchronization is a relationship it cannot express. The laser device itself folds (catalog `Laser`, 4-ID precedent); the sync is the gap. -- **One switched FEL source feeding co-equal instruments (TOPO-1).** One linac and undulator line serve many instruments, beam routed one at a time by the transport mirrors. CORA models each beamline as a root Unit owning its source; a shared, switched source feeding co-equal Units has no home except the `Supply("PhotonBeam")` seam, and the routing state ("which instrument has beam now") is new. -- **Attenuator transmission solver (ATT-1).** The solid-Si attenuators solve a foil combination for a requested transmission, energy-dependent (the `AttBase` solver). CORA's `Filter` covers the discrete selection; the solve is the deferred `Attenuable` + `SolverReference` leg (`apps/api/src/cora/operation/_partition_rule_eval.py` defers SolverReference evaluation). MFX, with the same focus solver on the `Transfocator` lens stacks, is the rule-of-three trigger. -- **Computed device-state to path-transmission lightpath (LIGHTPATH-1).** `pcdshub`'s `lightpath` walks the z-ordered beam path and computes path-level transmission and the first blocking device from each device's inserted / removed state. CORA already has the static z-ordered walk and the location-not-identity discipline; only the dynamic computed half is deferred (the passive-beam-path tier). `lightpath/path.py` is a ready precedent. - -### What is deliberately not here yet (modelling, as at the other exercises) - -- **New Capabilities / Methods and vendor Models.** MFX earns no catalog change; the XFEL recipes are carried pending on the [SLAC Practices](../slac/index.md). No catalog Model is bound. -- **The von Hamos as a graduated Family.** `EmissionSpectrometer` GRADUATED into the catalog once NSLS-II ISS (8-ID) earned the second sighting (its Johann + von Hamos XES / HERFD spectrometers); MAX IV Balder (SCANIA-2D) is a third near-sighting. The residual open question is whether each analyzer crystal is a child Asset (SPEC-1). -- **Sample delivery and the Subject custody thread.** The liquid jet / fixed target is endstation-specific and deferred (SAMPLE-1); no Family is coined. -- **Integration scenarios.** No `test_lcls_mfx_*.py` registers MFX Assets. Hard-registering a design-phase, off-roadmap, XFEL beamline would commit speculative structure. - -## Open questions - -*What CORA needs the LCLS team (and SLAC's documentation) to confirm before the model can be trusted.* - -MFX is modelled from SLAC's open [`pcdshub`](https://github.com/pcdshub) stack, treated as a dry, correct DATA source: the `happi` device database ([`device_config/db.json`](https://github.com/pcdshub/device_config)), the worked hutch config ([`mfx/beamline.py`](https://github.com/pcdshub/mfx)), the [`lightpath`](https://github.com/pcdshub/lightpath) beam-walk engine, and `pcdsdevices`. That gives the device shape and the EPICS PV prefixes at high confidence; it does not give the calibrated numbers, the PPS safety structure, the undulator specifics, or the Capability / Method binding. This page collects what `pcdshub` cannot supply. It is a delete-on-answer queue: when an item is answered, the answer lands in the descriptor and the row is removed. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -As at the Diamond exercises, the EPICS PV prefix for every device is already recorded in the descriptor, so wiring handles is not a question here. The questions concentrate on the one thing the storage-ring exercises never reached: the XFEL acquisition paradigm. - -### Scope, topology, and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SCOPE-1 | Nice-to-have | Is MFX (or any LCLS instrument) actually intended to enter CORA scope, or is this a generalization exercise against an open controls source? | A generalization exercise: MFX tests the XFEL acquisition paradigm; it is not on the pilot roadmap. | Whether SLAC is a real Site or a modelling fixture. | -| TOPO-1 | Blocks-build | One linac and undulator line feed many co-equal instruments (CXI/XPP/XCS/MEC/MFX, plus the LCLS-II soft-X-ray instruments), beam routed to one at a time. Should each instrument be its own root Unit sharing an upstream source, and where does the shared switched source live? | One `LCLS-MFX` root Unit owning its source for now; the shared, switched FEL source has no model and is carried as this question. The `Supply("PhotonBeam")` seam is the candidate home. | One-vs-many root Units and where the shared source and its routing state are modelled. | -| PSS-1 | Blocks-build | What are the LCLS PPS search-and-secure permit signals, and the BTPS interlock for the pump-probe laser? | Both enclosures exist with permit signals to be named; `pcdshub` does not carry them. | The Enclosure permit signals and the laser-safety interlock. | -| ENC-1 | Blocks-build | Which enclosure does each device sit in? `pcdshub` prefixes encode beamline-line zones (FEE, XRT, HFX, MFX:DG1/DG2/DIA), not the access-gated hutch or its safety meaning. | The shared front-end / transport zone plus the MFX experiment hutch. | The per-device Enclosure assignment. | - -### Source, optics, and attenuation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-build | What are the HXR undulator line parameters and the per-shot photon-energy mechanism (vernier vs undulator), and is the beam SASE or self-seeded? `pcdshub` carries the device handles, not the source curve. | A SASE FEL undulator; per-shot photon energy is a DAQ datum, not a standing setpoint; energy-to-gap control is deferred. | The `Undulator` parameters and the per-shot energy mechanism. | -| MACHINE-1 | Nice-to-have | LCLS is a linac, not a storage ring, so the loose `StorageRing` family used by the synchrotron exercises does not fit. How should machine beam be modelled? | A `PhotonBeam` Supply, not a `StorageRing` device; the per-shot pulse energy is read via a `FluxMonitor` gas detector. | The linac machine-state modelling boundary. | -| ATT-1 | Blocks-go-live | The solid-Si attenuators select a foil combination for a requested transmission (energy-dependent, the `AttBase` solver). CORA's `Filter` covers the discrete selection but not the solve. Should the deferred `Attenuable` + `SolverReference` leg graduate? | `Filter` for the discrete selection; the target-transmission solver is the deferred `Attenuable` leg, and MFX is its rule-of-three trigger. | Whether the transmission solver is built and where. | -| MONO-1 | Nice-to-have | The diamond double-channel-cut mono (DCCM) is used for some modes; MFX also runs pink / SASE beam mono-out. What are the crystal and axis details, and the pink-vs-mono mode boundary? | A `Monochromator` Asset, used in some modes; mode and crystal details are settings to supply. | The DCCM internals and the pink-vs-mono mode model. | - -### Acquisition and timing (the architectural core) - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DAQ-1 | Blocks-build | The LCLS DAQ records a free-running stream of per-shot frames tagged by pulse-ID / fiducial at beam rate (120 Hz to ~1 MHz), correlated downstream by pulse-ID. CORA's acquisition is a single-detector poll-to-Done loop plus a sub-Hz scalar observation logbook with no pulse-ID key. How does CORA represent a DAQ run? | The Run-as-provenance-envelope is kept; the per-shot data plane lives in `psana`, and CORA references a `Dataset`, exactly as it does for reconstructions via `ComputePort`. A per-shot event-stream actuation axis is the gap, sketched in the design note, not built. | Whether CORA gains an event-stream acquisition axis or remains a record-keeping shell for MFX. | -| TIMING-1 | Blocks-go-live | The EventSequencer plays a beam-synchronous sequence (each line `[beam_code, delta_beam, delta_fiducial, burst_count]`) to gate acquisition. CORA's `TimingController` carries the device but has no typed home for an event-code sequence. Where does the sequence parameter live? | `TimingController` for the device; the event-code sequence is carried as opaque setpoints until a typed parameter shape is earned. | The event-code-sequence parameter model. | -| LASER-1 | Blocks-go-live | The fs pump-probe needs laser-to-X-ray synchronization (the `lxt_ttc` SyncAxis, ~50 fs deadband) and timetool jitter correction. CORA's `PartitionRule` is single-domain spatial math, with no cross-timing-domain sync; and is the laser a driven Asset or a hazard? | The laser is carried as a catalog `Laser` Family device (the 4-ID precedent, model-vs-hazard open); the delay stage is a `LinearStage`; the fs synchronization has no CORA model. | The pump-probe synchronization model and the laser's model-vs-hazard status. | -| LIGHTPATH-1 | Nice-to-have | `lightpath` computes path-level transmission and the first blocking device from each device's inserted / removed state along the z-walk. CORA has the static z-ordered walk and location-not-identity, but not the dynamic device-state-to-path-transmission computation (the passive-beam-path tier defers the beam effect). Should it graduate? | The static walk is modelled; the dynamic computed transmission is deferred under the passive-beam-path tier; `lightpath/path.py` is the precedent. | Whether the computed lightpath beam-effect is built. | - -### Diagnostics, sample, and detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DIAG-1 | Blocks-go-live | How are the intensity-position monitors (IPM), the gas detector, the Wave8, and the timetool modelled? They present the Sensor Role; the gas detector is a `BeamStats` PV, not a happi device. | The loose `FluxMonitor` and `Diagnostic` Sensor families reused from I22 / 2-BM; per-shot intensity normalization is a DAQ-plane concern (DAQ-1). | The diagnostics modelling boundary. | -| SAMPLE-1 | Blocks-go-live | What is the sample-delivery shape (liquid jet, fixed target), and the `Subject` custody lifecycle for serial crystallography? | Sample delivery is endstation-specific and deferred; no Family is coined yet; the `Subject` thread is carried as this question. | The sample-delivery model and the `Subject` custody thread. | -| SPEC-1 | Nice-to-have | The von Hamos 6-crystal spectrometer is a crystal-analyzer X-ray emission spectrometer composing analyzer crystals and a 2D detector along a dispersive geometry. The Family question is resolved: `EmissionSpectrometer` GRADUATED into the catalog once NSLS-II ISS (8-ID) earned the second sighting. The residual question is whether each of the six analyzer crystals is a child Asset or a setting on the one spectrometer Asset. | The six analyzer crystals carried as settings on the one `EmissionSpectrometer` Asset for now; child-Asset-per-crystal deferred. | The analyzer-crystal composition (child-Asset vs setting). | -| DET-1 | Blocks-go-live | What is the MFX area detector (Rayonix MX340-XFEL, ePix10k, Jungfrau), and its threshold / geometry? `pcdshub` manages it through the DAQ, not as a polled happi device. | The detector reuses `Camera`; per-shot frames flow through the DAQ data plane (DAQ-1); the model and calibration are to supply. | The detector model and how its per-shot frames are referenced. | -| PULSE-1 | Nice-to-have | The pulse picker is a fast single-pulse selector folded into `Shutter`. Is a rotary pulse-picking chopper a distinct Family (the loose `Chopper` shape)? | `Shutter` Role; the Shutter-vs-Chopper distinction is carried as this question. | Whether the pulse picker earns its own Family. | diff --git a/docs/deployments/lix/notes.md b/docs/deployments/lix/notes.md deleted file mode 100644 index e9be0004dce..00000000000 --- a/docs/deployments/lix/notes.md +++ /dev/null @@ -1,180 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of LIX is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../nsls2/index.md#the-techniques-adapted-here) is how a facility adapts it. LIX measures biological structure three ways: biological solution scattering (bio-SAXS / WAXS), in-line size-exclusion-chromatography-coupled scattering (SEC-SAXS), and scanning-microbeam mapping of cells and tissue. The Methods below render unlinked and are carried pending until the owner-scope decision (`TECH-1`) brings any of them into the catalog. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Biological solution scattering (bio-SAXS / WAXS) | `solution_scattering` | small- and wide-angle scattering from a protein in solution in the [flow cell](sample.md), read on the [SAXS Pilatus 1M](detector.md); the fleet's first solution-scattering Method, new to the catalog (`TECH-1`) | -| In-line SEC-SAXS | `solution_scattering` | the [HPLC delivery pump](sample.md) flows an eluting size-exclusion peak through the cell while the SAXS detector reads; the same `solution_scattering` Method with the chromatographic elution as the acquisition axis (`TECH-1`, `FLUID-1`) | -| Scanning-microbeam mapping | `scanning_fluorescence_microscopy` | raster the microbeam across a cell or tissue section on the [scanning goniometer](sample.md), reading scattering and fluorescence per point; reuses the existing pending Method (`TECH-1`) | - -All three techniques need the [incident-beam chain](source.md) (the undulator and DCM for energy, the mirrors and transfocator for focus, the slits), the [sample side](sample.md) (the positioning stack or scanning goniometer, and for the solution modes the fluidic delivery chain), and the [endstation detectors](detector.md) (the Pilatus heads, beamstop, flux monitors). - -### Where the novelty is: the Subject, not the Method - -LIX's measurement, small- and wide-angle X-ray scattering, is a science axis the fleet already speaks. The materials-scattering beamlines [SMI](../smi/notes.md#techniques), [CMS](../cms/notes.md#techniques), Diamond [I22](../i22/notes.md#techniques), and APS [9-ID](../9-id/notes.md#techniques) / [12-ID](../12-id/notes.md#techniques) all run small- and wide-angle scattering on the same `Camera` / `FluxMonitor` / `BeamStop` vocabulary. So the scattering hardware and detection are reinforcement, not novelty. - -What LIX adds is a new **Subject** and a new **sample-delivery** shape, not a new detector. The specimen is a protein in solution rather than a solid mount, and for SEC-SAXS it is an eluting chromatographic peak whose elution profile is the acquisition axis. That is why `solution_scattering` is proposed as a Method distinct from the materials `small_angle_scattering`: not because the optics differ, but because the Subject and the acquisition (a flowing, time-resolved liquid correlated to chromatography) differ. Whether the catalog ultimately holds one scattering Capability with solution-versus-solid as a Practice adaptation, or a distinct `solution_scattering` Capability, is the owner-scope decision (`TECH-1`); LIX records the case, it does not mint the vocabulary. - -The matching Site Practices (`LIX_solution_scattering_practice`, `LIX_sec_saxs_practice`, `LIX_microbeam_scanning_practice`) are carried pending in the [NSLS-II Site](../nsls2/index.md#the-techniques-adapted-here); each binding lands when its Capability does. - -### SEC-SAXS is a Procedure over the fluidic seam - -In-line SEC-SAXS is the technique that most exercises the fluidic delivery chain, and CORA models it as a **Procedure**, not a new device. The run equilibrates the size-exclusion column, injects the sample, and reads SAXS frames continuously while the peak elutes through the [flow cell](sample.md). The actuators it drives, the [HPLC delivery pump](sample.md) (the graduated `FlowController`) and the selector valves (the seam), are conducted over the `ControlPort`; the [column and buffers](sample.md) are Supply; the eluting peak is a Subject; the frames correlated to the elution are the Dataset. The technique's identity in CORA's record lives in the Subject, Supply, and Procedure, not in a device or a new detector (`FLUID-1`, `SEC-1`, `SUBJECT-1`). - -### Not modelled yet - -The concrete acquisition recipes are not written yet. For solution scattering that is the per-frame exposures, the buffer-subtraction sequence, and the azimuthal integration that turns 2D frames into I(Q) curves (the integration and reduction are `ComputePort` work, not beamline Methods). For SEC-SAXS it is the column-equilibration and injection steps, the flow program, and the peak-fraction model that maps frames to elution. For the scanning mode it is the raster trajectory and the per-point reduction. These join as the deployment approaches the point where CORA drives LIX. - -Whether any of these techniques enters CORA's catalog is an owner-scope decision on [Model](#model): a modelling exercise reinforces the case but does not mint cross-facility Method vocabulary on its own. See [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at LIX, and the trust shape that will gate it. First cut.* - -Governance at LIX 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#safety-and-governance), 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). - -LIX is not yet driven by CORA, so this shape is not yet instantiated. As a modelling-exercise scaffold, the deployment is descriptor and docs today, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized. The profile collection's access model is a POSIX-ACL `login` keyed to a proposal id, not a facility role roster, so the NSLS-II operator pool and review structure is carried pending on the [NSLS-II Site](../nsls2/index.md#safety-and-governance), shared with the rest of the fleet (`GOV-1`). - -### The safety boundary - -The safety tier is the other piece that is not yet settled. The PSS search-and-secure permit signals and the front-end and photon shutters are largely absent from the beamline's profile collection (only the photon-shutter enable status is present), so the Enclosure permit leaves and the interlock structure are carried pending and are not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [NSLS-II Site](../nsls2/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -LIX adds the hazard classes that come with its instruments, and one that is distinctive: a wet, biological sample environment. Those land with the equipment and the samples that bring them, and an experiment Clearance would carry them. - -| Hazard class | Where it lands | Tracking | -| --- | --- | --- | -| Hard X-ray beam | the [optics](index.md) and [endstation](index.md) enclosures (XF:16IDA / B / C) (`ENC-1`) | (`PSS-1`) | -| Vacuum optics and the SAXS flight path | the [Source](source.md) walk and the detector translations | (`SUP-1`) | -| Biological samples, buffers, and pressurized fluidics | the [Sample](sample.md) delivery chain (the HPLC pump, the buffers, the flow cell) | (`FLUID-1`, `SEC-1`) | - -The hard X-ray beam is the interlocked hazard; its permit leaves stay pending until the PSS signals are confirmed (`PSS-1`). The vacuum extent and the cooling supply that the optics and flight path depend on are carried pending (`SUP-1`). The biological-sample and pressurized-fluidics hazards are distinctive to a life-science solution beamline and travel with the delivery chain and the Subject; they are carried pending against the fluidic questions, not invented (`FLUID-1`, `SEC-1`). - -### When the shape lands - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives LIX, following the [2-BM governance](../2-bm/governance.md) shape. Because LIX shares the NSLS-II EPICS and ophyd floor with the rest of the fleet, it re-tests the Site and Federation kernel rather than introducing a new trust model. The one new wrinkle is the fluidic delivery chain: a Conduit would have to bind the HPLC cart's heterogeneous surfaces (the soft-IOC, the Moxa sockets) as command surfaces alongside EPICS, the same multi-transport Conduit shape the [MX3](../mx3/notes.md#governance) deployment first surfaced. The Zone groups the same optics and endstation resources the [inventory](index.md) lists; the Policies bind to the NSLS-II operator roles carried pending at the Site (`GOV-1`). - -## Model - -*The developer's by-kind index: where each CORA aggregate's LIX content lives, how it models a solution beamline's fluidic delivery without inventing device vocabulary, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at LIX | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (the incident-energy `PseudoAxis`) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes LIX new - -The honest answer is: not the detector, and one real thing on the sample side. LIX measures biological structure by small- and wide-angle X-ray scattering (bio-SAXS / WAXS), in-line size-exclusion-chromatography-coupled scattering (SEC-SAXS), and scanning-microbeam mapping. The scattering hardware overlaps the fleet heavily: LIX shares its science axis and its `Camera` / `FluxMonitor` / `BeamStop` vocabulary with the materials-scattering beamlines SMI, CMS, I22, and 9-ID, and contributes reinforcement there, not novelty. - -LIX's genuinely distinct contributions are above the detector and beside the sample: - -- **The solution Subject.** The fleet's first life-science solution-scattering beamline measures a buffer-borne macromolecule, often an eluting chromatographic peak, rather than a solid mount. That is a new Subject shape, with its own provenance, not a new device (`SUBJECT-1`). -- **The fluidic sample-delivery chain.** An HPLC delivery pump, selector valves, a size-exclusion column, buffers, and a flow cell move the sample into the beam in lockstep with the exposure. It is the fleet's first fluidic delivery plane, and it is heterogeneous (a Moxa terminal server, the Agilent OpenLAB .NET SDK, a pcaspy soft-IOC), the MX3 non-EPICS shape extended to fluidics (`FLUID-1`). -- **The SEC-SAXS Procedure.** The run is a flow program correlated to the chromatographic elution, a Procedure over the seam plus a Subject / Supply shape, not a device (`FLUID-1`, `SEC-1`). - -### No new families - -LIX coins no new Family and changes nothing in the catalog. - -- **16-ID is an undulator beamline** (unlike the bending-magnet CMS), so it carries an `InsertionDevice` on the spine; the machine state is also observed through the loose `StorageRing`, and the undulator detail is `SRC-1`. -- **The DCM binds `Monochromator`** (a silicon double-crystal optic, the energy law implies Si(111)); the incident energy is a `PseudoAxis` over its Bragg angle and the undulator gap. -- **The optics and detectors all reuse:** the white-beam and KB mirrors bind `Mirror`; the slits bind `Slit`; the compound refractive lens binds the graduated `Transfocator`; the shutters bind `Shutter`; the solution positioning stack binds the graduated `Manipulator`; the scanning goniometer binds `Goniometer`; the Pilatus detectors bind `Camera`; the Xspress3 binds the graduated `EnergyDispersiveSpectrometer`; the detector translations bind `LinearStage`; the beamstop binds `BeamStop`; the TetrAMM electrometers bind `FluxMonitor`; the diamond-diode / Best beam-position monitor binds the graduated catalog `PositionMonitor` (presenting `Sensor`, earned across the wide fleet that shares it, distinct from `FluxMonitor` by measuring beam position rather than flux, `DIAG-1`); the Zebra binds `TimingController`. - -### The graduated FlowController Family - -The one reuse worth spelling out is the HPLC delivery pump. Its CORA-facing anatomy is a settable flow / pump actuator presenting `Regulator`: a flowrate setpoint and readback, a pressure readback, and run / stop. That is exactly the graduated catalog `FlowController` Family, the continuous-setpoint flow / pump actuator that presents `Regulator` and is the settable-actuator sibling of `TemperatureController`. So the pump **reuses** the graduated `FlowController`; it coins nothing. - -`FlowController` graduated into the catalog on the rule-of-three across Diamond i22, APS 7-BM, NSLS-II LIX, and NSLS-II XFP, the same way `TemperatureController`, `FluxMonitor`, and `EmissionSpectrometer` did: presenting the existing `Regulator` Role, so a YAML-and-docs change with no new Role or affordance. LIX is one of the four consumers that earned the graduation, and it now simply **binds the catalog `FlowController` Family (graduated; presents `Regulator`)**. The wider fluidic chain stays deferred (`FLUID-1`, `FLOW-1`). - -### How the fluidic chain is modelled (mostly not a device) - -The fluidic delivery chain is the novel axis, and only one piece of it is a device: - -- the **delivery pump** is the `DeliveryPump`, binding the graduated `FlowController` (above); -- the **selector valves** (VICI column / purge / detector, the Aurora buffer valve) are the ControlPort **seam**: discrete N-position routers over Moxa TCP sockets, with no existing Family, conducted over the seam and not coined at n=1 (`FLUID-1`); -- the **SEC column and buffers** are **Supply** consumables (`SEC-1`); -- the **flow cell** is sample environment, living in an external library (lixtools), not a catalog device here (`SEC-1`, `FLUID-1`); -- the **sample robot and autosampler** are a **Procedure** over the spine plus a **Subject** custody thread, the i03 / MX3 robot precedent, not a device Family (`ROBOT-1`); -- the **solution sample / eluting peak** is a **Subject** (`SUBJECT-1`). - -This is the CORA-lens decision for a solution beamline: the experiment's identity lives in the Subject (which protein, which peak), the Supply (which column, which buffers), and the Procedure (the flow program), with the pump and valves as actuators conducted over the seam. Coining `Pump` and `Valve` device Families at n=1 would mint federation vocabulary one deployment cannot earn alone; the pump reuses the graduated `FlowController` Family instead, and the valves stay in the seam pending a second fluidic beamline (`FLUID-1`). - -### Deliberately not here yet - -- **The selector-valve Family (`FLUID-1`).** The VICI and Aurora valves are discrete-position routers with no existing Family. Per earn-the-abstraction they are carried in the seam at n=1, no `Valve` / `SelectorValve` Family coined; a second fluidic beamline would earn the abstraction. -- **The disabled attenuator and the deferred temperature controllers.** The `Fltr:Attn` attenuator and its lookup tables are commented out in the profile collection, so no attenuator is modelled, not invented (`ATTN-1`). The sample-cell temperature controllers (the FTC100D and the SMC chiller) have their module-level instances commented out, though a solution mode instantiates an FTC100D, so this is a scope deferral; the autosampler tray temperature (`SAMPLER:TEMP`) is folded into the same deferral (`TEMP-1`). -- **The Methods.** Whether `solution_scattering` and the scanning Method enter CORA's catalog is an owner decision; the Practices render unlinked, pending. `solution_scattering` is new and `scanning_fluorescence_microscopy` is reused pending (`TECH-1`). -- **The multi-mode endstation rebinding.** The solution, scanning, and vacuum-scan modes rebind the logical sample axes across physical PVs and controllers (EPICS, XPS trajectory, SmarAct) at startup; CORA models the logical stacks and carries the active binding as a setting (`SAMPLE-1`, `SCAN-1`), not as separate Assets. -- **The third Pilatus, the Kinetix, and the viewing cameras.** The 300K WAXS1 head is disabled, the Xspress3 is optional, and the Kinetix and Prosilica cameras are not modelled in this cut (`DET-1`). -- **The simulated devices and full asset-tree scenarios.** No `test_lix_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the LIX team to confirm before the model can be trusted.* - -LIX was reverse-engineered from the beamline's own bluesky profile collection ([NSLS2/lix-profile-collection](https://github.com/NSLS2/lix-profile-collection)), so the control handles on the [device pages](index.md) are the beamline's real PVs, read from the `startup/` files rather than confirmed by staff. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | Are the PV zones XF:16IDA (optics), XF:16IDB (transport), and XF:16IDC (endstation) three separate hutches? | Two enclosures: a `lix-optics` zone (folding A and B) and the `lix-endstation` hutch. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The in-vacuum undulator model, period, and length (the profile collection fits an empirical Keff(gap) curve, a 23 mm period implied, but names no device). | An `InsertionDevice` undulator, observed gap; parameters pending. | The source Asset detail. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MACHINE-1 | Nice-to-have | The storage-ring state LIX reads (current, fill, status); only the ring current PV is read for beam suspenders. | Observe-only machine state, a loose `StorageRing`; the exact PVs pending. | The machine-state observation. | -| MONO-1 | Blocks-go-live | The DCM crystal cut (the energy law implies Si(111)), the energy range, and the energy-partition rule coupling the Bragg angle to the undulator gap. | A double-crystal `Monochromator`; the energy is a `PseudoAxis` over the Bragg angle and the gap; the crystal cut pending. | The monochromator and incident-energy Assets. | -| OPT-1 | Nice-to-have | The white-beam and KB mirror coatings, whether the KB pair is bimorph, and the bend mechanisms. | Focusing mirrors bound to `Mirror`; coatings and bend pending. | The mirror Asset detail. | -| OPT-2 | Nice-to-have | The blade-axis roles of each slit (the mono slit, the secondary-source aperture, the endstation guard slit). | Four-blade and center / gap slits bound to `Slit`. | The slit Asset detail. | -| CRL-1 | Nice-to-have | The compound refractive lens lens-group configuration (nine selectable groups, in / out per group) and the focal-length map. | A `Transfocator` reusing the graduated Family; the lens-group set carried as settings. | The transfocator Asset detail. | -| ATTN-1 | Nice-to-have | Is an attenuator live (the `Fltr:Attn` motors and the `Attenuator` class are commented out in the profile collection)? | No attenuator modelled; not invented. | Whether an attenuator Asset exists. | - -### Sample and delivery - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SAMPLE-1 | Blocks-go-live | The solution-mode positioning stack axes (the coarse x and z pusher are EPICS; the scan x / y are Newport-XPS trajectory axes), and how the flow cell mounts on it. | A `Manipulator` for the positioning stack; the flow cell is the fluidic seam. | The solution-stage modelling. | -| SCAN-1 | Blocks-go-live | The scanning-microbeam goniometer axes (the SmarAct stack), the fast raster axes (the XPS scan.X / scan.Y trajectory), and the tomo rotation (the XPS rot.rY). | A `Goniometer` for the SmarAct stack; the XPS trajectory axes carried as the motion-controller seam. | The scanning-stage modelling. | -| FLUID-1 | Blocks-go-live | The fluidic sample-delivery chain: the HPLC delivery pump (an Agilent quaternary pump over the .NET SDK plus a regeneration pump over a Moxa socket, fronted by the `XF:16IDC-ES{HPLC}` soft-IOC), the VICI and Aurora selector valves (Moxa TCP sockets, no EPICS), and whether the valve actuators earn a Family. | The pump binds the graduated catalog `FlowController` (presents Regulator; earned across i22 / 7-BM / LIX / XFP); the valves stay in the seam; no Valve Family coined. | The fluidic-delivery modelling; the CORA decisions are on [Model](#deliberately-not-here-yet). | -| SEC-1 | Nice-to-have | The size-exclusion column types, the buffers, the needle wash, and the X-ray flow cell (the flow cell lives in an external library, lixtools). | The column and buffers are Supply consumables; the flow cell is sample environment, not a device. | The consumable / flow-cell modelling. | -| ROBOT-1 | Nice-to-have | The sample-handling robot (the `SW:` method soft-IOC, task-verb-driven) and the Agilent autosampler, and whether they earn a Family. | Modelled as a Procedure over the spine and a Subject custody thread, the i03 / MX3 robot precedent; no `SampleExchanger` Family coined. | The sample-handling modelling. | -| SUBJECT-1 | Nice-to-have | The solution Subject: a buffer-borne macromolecule or an eluting SEC peak, with its own provenance, distinct from a solid mount. | A liquid Subject; the chromatographic peak as the acquisition axis for SEC-SAXS. | The Subject modelling. | -| TEMP-1 | Nice-to-have | The sample-cell temperature control (the FTC100D and SMC chiller module-level instances are commented out, though a solution mode instantiates an FTC100D; plus the autosampler tray temperature SAMPLER:TEMP). | No temperature-controller device modelled in this cut; the in-situ environment pending. | The temperature-environment modelling. | - -### Detection - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The SAXS / WAXS Pilatus detector models and sizes (a 1M SAXS, a 900K WAXS; a 300K WAXS1 is disabled), the Xspress3 per-run availability (initialized in a try / except), the detector-distance calibrations, and the flux / beam-position channel map. | Two `Camera` Assets (Pilatus 1M SAXS, 900K WAXS); the Xspress3 binds `EnergyDispersiveSpectrometer`; the monitors bind `FluxMonitor` and the graduated catalog `PositionMonitor`. | The detector modelling. | -| DIAG-1 | Nice-to-have | The beam-position monitor: the Best aggregator deriving x / y from the TetrAMM quadrant currents, and the position-versus-intensity channel split. The Family is settled (graduated catalog Family presenting `Sensor`, distinct from `FluxMonitor` by measuring beam position rather than flux). | The graduated catalog `PositionMonitor`, earned across the wide fleet that shares it; the per-Asset channel split is the residual. | The beam-position channel split. | -| TRIG-1 | Blocks-go-live | The exposure triggering: the Zebra soft-input pulse and position capture, gated from the Newport XPS, and the fast-shutter TTL. | A `TimingController` (the Zebra); the fast shutter a `Shutter` on the timing seam. | The triggering modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the EPICS PV handles read from the profile collection current and correct, and is the data plane Kafka plus Redis plus a custom packing queue (no Tiled, no queueserver in the profile collection)? | The handles in the descriptor are taken from the profile collection and carried confirm; the data plane is the seam CORA's edge replaces. | Verifying each Asset's control handle and the data plane. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit signals, the front-end and photon shutters (only the photon-shutter enable status is in the profile collection; the security model there is a POSIX-ACL login). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent (the optics, the SAXS flight path) and the cooling supply. | Photon beam, cooling water, and vacuum on the optics and flight path. | The Supply observations. | -| GOV-1 | Nice-to-have | The NSLS-II operator pool and safety-review structure (site-level, shared across the beamlines). | Carried pending on the NSLS-II Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Blocks-go-live | Do the solution-scattering and scanning techniques (bio-SAXS / WAXS, SEC-SAXS, microbeam mapping) enter CORA's catalog as Capabilities / Methods? | Deferred: carried as pending Practices; `solution_scattering` is new and `scanning_fluorescence_microscopy` is reused pending; none coined. | The technique Capabilities. | diff --git a/docs/deployments/manaca/notes.md b/docs/deployments/manaca/notes.md deleted file mode 100644 index 006149706e6..00000000000 --- a/docs/deployments/manaca/notes.md +++ /dev/null @@ -1,133 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of MANACA is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../sirius/index.md#the-techniques-adapted-here) is how a facility adapts it. MANACA runs macromolecular crystallography, reusing the same cross-facility MX Methods Diamond i03 introduced, so the Methods below render unlinked and are carried pending until a technique enters scope (`TECH-1`, `ROBOT-1`). - -### Macromolecular crystallography - -MANACA sets the X-ray energy (5-20 keV) with the undulator and the monochromator, mounts a crystal on the goniometer (from the automated 48-pin sample changer), and rotates it through an oscillation while the area detector reads frames. It supports serial and room-temperature MX in addition to standard cryocooled rotation collection. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Rotation MX data collection | `mx_data_collection` | oscillation collection on the [goniometer](sample.md) reading the [area detector](detector.md); reuses the i03 Method (also at FMX / AMX / MX3), not yet in the catalog (`TECH-1`) | -| Grid scan | `grid_scan` | fast grid scan for sample location and centring on the [goniometer](sample.md); reuses the i03 Method; pending (`TECH-1`) | -| Sample exchange | `sample_exchange` | the automated 48-pin changer load / centre / collect / unmount loop, modelled as a Procedure over the spine; reuses the i03 / MX3 Method; pending (`ROBOT-1`) | - -Rotation MX needs the [incident energy](source.md) set by the [monochromator](source.md), the [goniometer and cryostream](sample.md), and the [area detector](detector.md). Serial and room-temperature MX reuse the same chain with the sample-delivery and environment varied. - -### A new beamline on familiar vocabulary - -MANACA is a further macromolecular-crystallography beamline after Diamond i03, NSLS-II FMX / AMX, and the Australian Synchrotron MX3, and Sirius's first MX beamline (its [MOGNO](../mogno/index.md) sibling is tomography). It ties into the MX lineage CORA already models: the same goniometer / detector / cryostream anatomy, driven here through the Sirius EPICS floor and MXCuBE3. It reuses the `mx_data_collection`, `grid_scan`, and `sample_exchange` Methods directly (all carried pending across the MX fleet); none forces a new device family, and the 48-pin sample changer is a Procedure, not a new device. - -### Not modelled yet - -The concrete acquisition recipes (the oscillation sequences and their exposures, the grid-scan centring, the sample-changer custody loop, the serial / room-temperature delivery) are not written yet; they join as the deployment approaches the point where CORA drives MANACA. Whether the MX Methods enter CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at MANACA, and the trust shape that will gate it. First cut.* - -Governance at MANACA follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [Sirius Site](../sirius/index.md#safety-and-governance), 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). - -MANACA is Sirius's first MX beamline but not CORA's first Sirius deployment (the [MOGNO](../mogno/index.md) tomography scaffold precedes it): the operator pool and the safety-review structure are carried pending on the [Sirius Site](../sirius/index.md#safety-and-governance), shared across the facility's beamlines, until LNLS staff confirm them (`GOV-1`). MANACA is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives MANACA, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. LNLS publishes no per-beamline personnel-safety permit signals or photon / front-end shutters, so the Enclosure permit leaves and the interlock structure are carried pending and are not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [Sirius Site](../sirius/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -MANACA also carries the hazard classes that come with an MX endstation: a cryostream and its liquid-nitrogen supply, and an automated sample changer moving in the experiment hutch. Those land with the instruments that bring them; the sample-changer custody loop is modelled as a Procedure with a Subject thread (`ROBOT-1`), not as an Asset CORA drives for safety. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives MANACA, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's MANACA content lives, its place as Sirius's first MX beamline, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at MANACA | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (the incident-energy `PseudoAxis`) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes MANACA new - -MANACA is a new beamline at an existing Site, and nothing new at the vocabulary level. It is **Sirius's first macromolecular-crystallography beamline**, CORA's second modelled Sirius beamline after the [MOGNO](../mogno/index.md) tomography scaffold. Its science is macromolecular crystallography (serial and room-temperature) at 5-20 keV: rotation MX on a goniometer reading an area detector, with an automated 48-pin sample changer. The control plane is the Sirius EPICS device floor with MXCuBE3 / MXCuBE Web as the MX experiment UI; Bluesky / Ophyd (the LNLS sophys family) is named as a facility orchestration direction, the same migration question MOGNO records (`ORCH-1`). - -### No new families (the MX spine reuses the i03 / FMX / AMX / MX3 precedent) - -MANACA coins no new Family. The goniometer binds the graduated `Goniometer`; the monochromator binds `Monochromator` and the energy is a `PseudoAxis`; the attenuators bind `Filter`; the cryostream binds the graduated `TemperatureController`; the beamstop binds `BeamStop`; the area detector and the on-axis camera bind `Camera`, the detector stage `LinearStage`, the flux monitor the graduated `FluxMonitor`; the shutters bind `Shutter`; the machine state binds the supply-loose `StorageRing`, and the sample backlight the catalog `Backlight` (graduated across the MX / imaging fleet, `DET-1`). Nothing in the catalog changes. The automated 48-pin sample changer is a deferred sample-exchange Procedure, not a device family (the i03 / i24 / MX3 `ROBOT-1` precedent). - -### The control plane - -MANACA sits on the Sirius EPICS device floor with MXCuBE3 / MXCuBE Web as the MX experiment UI driving the goniometer, the detector, and the sample changer. Sirius has named Bluesky / Ophyd (the LNLS sophys family: a RunEngine fronted by bluesky-queueserver and bluesky-httpserver) as a facility orchestration direction, and the MOGNO scaffold records the same migration question (`ORCH-1`); whether MANACA runs it today is not public. LNLS publishes its control software openly but no per-beamline PV manifest, so CORA does not bind the EPICS / MXCuBE handles here; when bound they would be modelled as opaque edge strings over the `ControlPort` (`CTRL-1`). The rotation-MX acquisition runs through MXCuBE and the beamline orchestration layer; that orchestration is the seam CORA's edge replaces or drives through, conducting over the EPICS floor rather than owning it. The detector file-writing to the Sirius data store is plumbing CORA observes, not data it owns. - -### Deliberately not here yet - -- **The control handles (`CTRL-1`).** No public per-beamline EPICS / MXCuBE manifest exists; the handles are carried pending, not invented. -- **The detector model (`DET-1`).** The area detector is bound to `Camera` but its model (a Pilatus / Eiger-class photon-counting detector) is unpublished, carried pending. -- **The sample-exchange Procedure (`ROBOT-1`).** The automated 48-pin changer is named as a deferred Procedure, not built, following the established MX robot precedent. -- **The exact optics and goniometer detail (`MONO-1`, `ENERGY-1`, `FILT-1`, `OPT-1`, `GONIO-1`).** The monochromator crystal, the energy axis, the attenuators, the mirrors / slits, and the goniometer axes are carried confirm-pending. -- **The MX Methods (`TECH-1`, `ROBOT-1`).** Whether rotation MX, grid scan, and sample exchange enter CORA's catalog is an owner decision; the Practices render unlinked, pending, reusing the i03 slugs. -- **The simulated devices and full asset-tree scenarios.** No `test_manaca_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the MANACA team to confirm before the model can be trusted.* - -MANACA was reverse-engineered from Sirius's public facility pages ([lnls.cnpem.br/facilities/manaca](https://lnls.cnpem.br/facilities/manaca/)) and a verified research brief, not from a live connection. LNLS publishes its control software (the Bluesky-based sophys family) openly, but no per-beamline EPICS PV manifest, so the [device pages](index.md) carry a planned shape with control handles unbound. MANACA is Sirius's first macromolecular-crystallography beamline, CORA's second modelled Sirius beamline after the [MOGNO](../mogno/index.md) tomography scaffold. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: a shared optics hutch feeding one experiment hutch, or a different layout? | A `manaca-optics` zone and a `manaca-experiment` hutch. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The undulator period and parameters. | An undulator source, 5-20 keV; period pending. | The source Asset detail. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MACHINE-1 | Nice-to-have | The Sirius storage-ring state MANACA reads. | Observe-only machine state, a loose `StorageRing`; exact handles pending. | The machine-state observation. | -| MONO-1 | Blocks-go-live | The monochromator crystal / multilayer type and handles. | A monochromator bound to `Monochromator`; 5-20 keV. | The monochromator modelling. | -| ENERGY-1 | Nice-to-have | Whether energy is scanned as the measurement (anomalous MX). | A master energy `PseudoAxis` the monochromator tracks. | The energy-axis modelling. | -| FILT-1 | Nice-to-have | The attenuator / transmission foil set. | An attenuator unit bound to `Filter`. | The attenuator Asset detail. | -| OPT-1 | Nice-to-have | The focusing mirrors and beam-defining slits (presence, handles). | No standalone mirror / slit device published; deferred. | The optics Asset detail. | - -### Sample endstation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| GONIO-1 | Blocks-go-live | The goniometer geometry: the rotation, centring, and alignment axes. | A `Goniometer` (the graduated i03 family); axis set pending. | The goniometer modelling. | -| TEMP-1 | Nice-to-have | The cryostream sample-cooling sensor and setpoint handles. | A `TemperatureController` (the graduated family). | The temperature-control modelling. | -| SAMPLE-1 | Nice-to-have | The beamstop axes and the sample-environment detail. | A `BeamStop` at the sample; axis set pending. | The sample-stage modelling. | -| ROBOT-1 | Blocks-go-live | The automated 48-pin sample changer (load / centre / collect / unmount loop). | A deferred sample-exchange Procedure over the spine + a Subject custody thread, not a device family. | The sample-exchange modelling. | - -### The detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The area-detector model (a Pilatus / Eiger-class photon-counting detector), its translation stage, and the on-axis camera. | A `Camera` plus a `LinearStage` and an on-axis `Camera`; model not published, carried pending. | The detector modelling. | -| DIAG-1 | Nice-to-have | The incident-flux monitor handles. | A `FluxMonitor` (the graduated family). | The flux-monitor modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | The EPICS PV and MXCuBE device handles per MANACA device (absent from any public per-beamline manifest). | The handles are unbound, carried pending; the control plane is the Sirius EPICS floor + MXCuBE3. | Binding each Asset's control handle. | -| ORCH-1 | Nice-to-have | Does MANACA run the Bluesky / Ophyd (sophys) orchestration layer, or another scan engine under MXCuBE? | Bluesky / sophys is a named facility direction (as MOGNO records); the MANACA status is unconfirmed. | The orchestration-layer modelling. | -| PSS-1 | Blocks-go-live | The Sirius personnel-safety permit signals and the photon / front-end shutters (not published per beamline). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent and the cryostream liquid-nitrogen / beam supplies. | Photon beam, cooling water, vacuum, and liquid nitrogen. | The Supply observations. | -| GOV-1 | Nice-to-have | The Sirius operator pool and safety-review structure (site-level). | Carried pending on the Sirius Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Do rotation MX and grid scan enter CORA's catalog as Capabilities / Methods? | Deferred: carried as pending Practices reusing the i03 `mx_data_collection` and `grid_scan` slugs; none coined. | The technique Capabilities. | diff --git a/docs/deployments/mogno/notes.md b/docs/deployments/mogno/notes.md deleted file mode 100644 index da3b047870d..00000000000 --- a/docs/deployments/mogno/notes.md +++ /dev/null @@ -1,137 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of MOGNO is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../sirius/index.md#the-techniques-adapted-here) is how a facility adapts it. MOGNO runs cone-beam X-ray tomography, which is already in CORA's catalog, so the Method below renders linked and the practice is carried pending until the technique enters scope (`TECH-1`). - -### Cone-beam micro and nanotomography - -MOGNO illuminates the sample with a quasi-monochromatic divergent (cone) beam and records projections as the sample rotates. Because the geometry is cone-beam, moving the sample along the cone between the secondary source and the detector changes the magnification, so a single instrument spans nanotomography (at the elliptical-mirror nanofocus) and microtomography (large field of view) by sample position. Phase contrast comes from propagation over the sample-to-detector distance, and time-resolved (4D) tomography from fast continuous rotation. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Cone-beam X-ray tomography | `tomography` | projections over a rotation on the [nanotomography](sample.md) and [microtomography](sample.md) stations, hardware-triggered by the [TATU timing unit](controls.md); reuses the graduated `tomography` Method the APS 2-BM pilot and NSLS-II FXI share; practice pending (`TECH-1`) | - -Tomography at MOGNO needs the [rotation axis](sample.md) as the master clock, the [TATU trigger](controls.md) to hardware-sync projection acquisition, the [detector chain](detector.md) to record the projections plus flat and dark fields, and the [cone-beam magnification axis](detector.md) to set the resolution-and-field-of-view working point. - -### A familiar technique on a third facility - -MOGNO is the tomography spine reaching a third facility after the APS 2-BM bending-magnet micro-CT pilot and the NSLS-II FXI transmission microscope. It coins no new Method: the same `tomography` Method covers micro and nano variants, exactly as 2-BM uses it for both. What MOGNO reinforces is not the technique but the surrounding model, the cone-beam magnification as a `PseudoAxis`, the FPGA trigger as a `TimingController`, and the seam against a custom (non-Bluesky) orchestration layer. - -The streaming and continuous-rotation tomography variants the catalog already carries (`streaming_tomography`, `continuous_rotation_tomography`) are plausible for MOGNO's 4D time-resolved work, but are not asserted here without a source; they would be added as practices once staff confirm the acquisition modes. - -### Not modelled yet - -The concrete acquisition recipes (the rotation ranges and speeds, the projection counts, the flat and dark field cadence, the per-energy and per-station alignment routines, and the reconstruction parameters) are not written yet; they join as the deployment approaches the point where CORA drives MOGNO. The reconstruction step (`ssc-raft` on the HPC cluster) is named on [Model](#the-compute-axis-reconstruction-named-not-built) as the compute axis, not modelled here. See [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at MOGNO, and the trust shape that will gate it. First cut.* - -Governance at MOGNO follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [Sirius Site](../sirius/index.md#safety-and-governance), 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). - -MOGNO is CORA's first Sirius deployment, so Sirius is a brand-new Site: the operator pool and the safety-review structure are carried pending on the [Sirius Site](../sirius/index.md#safety-and-governance), shared across the facility's beamlines, until LNLS staff confirm them (`GOV-1`). MOGNO is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives MOGNO, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. The Sirius personnel-safety permit signals and the photon and front-end shutters are not in any public source, so the Enclosure permit leaves and the interlock structure are carried pending and are not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [Sirius Site](../sirius/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -MOGNO carries the hazard classes that come with a tomography beamline: an intense X-ray beam (a quasi-monochromatic dipole source running up to ~68 keV), and the radiation-enclosure interlocks of the two experiment stations. Those land at the Site safety envelope; an experiment Clearance would carry the per-experiment authorization. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives MOGNO, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's MOGNO content lives, the new Sirius Site and the compute axis named for reconstruction, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at MOGNO | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (the cone-beam magnification `PseudoAxis`) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes MOGNO new - -MOGNO is CORA's **eighth Site** (Sirius, the Brazilian Synchrotron Light Laboratory at CNPEM) and the fleet's **first South American facility**, the biggest re-test of the Site and Federation kernel a single deployment can be. Its science is cone-beam X-ray micro and nanotomography across two endstations, fed by a quasi-monochromatic dipole source at three working energies. - -It is also the thinnest reverse-engineered scaffold to date, by necessity. The NSLS-II and Diamond beamlines were built from public open-source controls libraries (bluesky profile collections, `dodal`), so their descriptors carry real EPICS PVs or device handles. MOGNO has no public controls configuration: its facts come from two papers and a facility page. So every device binds a catalog Family but carries no handle and no vendor Model; the handles are open questions, not read-from-config evidence. - -### No new families, no new method (reuse and reinforce) - -MOGNO coins nothing. It is the tomography spine landing on a third facility after the APS 2-BM pilot and NSLS-II FXI, and it reuses their vocabulary wholesale: - -- the rotation axes bind `RotaryStage` (the master clock for triggered acquisition); -- the sample positioners (including the fine piezo "tripod") bind `LinearStage`, the axis set a per-Asset setting; -- the focusing optics bind `Mirror`, the beam-defining slits bind `Slit`; -- the detectors bind `Camera` and `Scintillator` (the indirect chain); -- the cone-beam magnification binds `PseudoAxis` (the FXI Magnification precedent); -- the TATU FPGA trigger binds `TimingController` (the 2-BM softGlueZynq / FXI Zebra precedent); -- the machine state binds the loose `StorageRing`; -- the `tomography` Method is reused, the practice carried pending (`TECH-1`). - -### The control seam: a custom EPICS application layer - -MOGNO is the fleet's first orchestration layer that is neither Bluesky nor BLISS nor Sardana. Its floor is EPICS IOCs plus a TATU FPGA trigger/timer (shared Sirius infrastructure, exposing EPICS PVs via the LNLS Nheengatu layer). Above that floor sits a beamline-owned custom PyEpics application stack: `mgn-devices` (device abstraction over PyEpics), `mgn-routines` (the alignment and tomogram acquisition routines), and `mgn-control-guis` (the PyQt/PyDM launchers). A tomogram is launched from a GUI dialog that runs the relevant `mgn-routines` script as a subprocess, driving the rotation stage, detector, and TATU trigger over EPICS. - -That custom routine layer is the orchestration CORA's edge would conduct over the EPICS floor, exactly as the 2-BM seam designates: CORA's EdgeConductor replaces the scan/alignment orchestration the `mgn-routines` perform today, conducting over the EPICS + TATU floor rather than replacing it. The beamline has named Bluesky/sophys (Ophyd devices, Bluesky plans) as a future migration target; whether it has migrated is an open question (`ORCH-1`). Modelling the seam against a custom stack, not Bluesky, is the point: it confirms the seam model does not assume a particular orchestration framework. - -### The compute axis: reconstruction named, not built - -MOGNO reconstructs on an HPC cluster. The beamline's reconstruction library is `ssc-raft` (CUDA, from the Sirius Scientific Computing group), submitted to the cluster over SSH from a FastAPI reconstruction service with a PyQt job-queue GUI; it has been the production reconstruction path since early 2024. This is a clean instance of CORA's compute axis (a `ComputePort` over a Method, no new BC): named here as reinforcement of the compute-modelling synthesis, not modelled as Assets in this cut. The cluster name, scheduler, and storage path are not confirmed from public sources (`COMPUTE-1`). - -### Deliberately not here yet - -- **The exact device handles and vendor models (`CTRL-1`, `STAGE-1`, `STAGE-2`, `STAGE-3`, `CAM-1`, `CAM-2`, `OPT-1`, `OPT-2`).** No public controls config exists; the PVs, controller boxes, and part numbers must come from staff. They carry no value here rather than a guessed one. -- **The reconstruction Assets and the compute leg (`COMPUTE-1`).** The `ssc-raft` HPC path is named above, not modelled. -- **The orchestration migration status (`ORCH-1`).** Whether MOGNO still runs the custom `mgn-*` stack or has moved to Bluesky/sophys is an open question. -- **The PSS permit signals and shutters (`PSS-1`).** Absent from public sources, carried pending, not invented. -- **The simulated devices and full asset-tree scenarios.** No `test_mogno_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the MOGNO team to confirm before the model can be trusted.* - -MOGNO was reverse-engineered from two published papers (Campoi et al. 2025, the software architecture; Archilha et al. 2022, the beamline) and the public [Sirius MOGNO facility page](https://lnls.cnpem.br/facilities/mogno/). Unlike the NSLS-II and Diamond scaffolds, there is no public controls configuration to read, so MOGNO carries no real control handles at all: the device families are inferred from the papers, and every handle, model, and PV namespace is an open question. This is CORA's first Sirius Site and first South American facility. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-go-live | The source type (permanent-magnet dipole vs superbend), field, and the energy-selection mechanism. | A 3.2 T dipole / superbend bound to `InsertionDevice`, recorded as a Supply (PhotonBeam) at the Site. | The source Asset detail. | -| SRC-2 | Nice-to-have | The working energy set: the hardware paper gives 21.5 / 39.0 / 67.7 keV, the facility page 22 / 39 / 67.5 keV. | The three quasi-monochromatic working energies; exact values pending. | The energy working points. | -| MACHINE-1 | Nice-to-have | The Sirius storage-ring state MOGNO reads. | Observe-only machine state, a loose `StorageRing`; exact read pending. | The machine-state observation. | -| OPT-1 | Blocks-go-live | The focusing-mirror count, geometry (elliptical set vs KB pair), coatings, and handles. | Elliptical / KB-style focusing mirrors bound to `Mirror`, demagnifying to ~100-120 nm. | The mirror Assets. | -| OPT-2 | Nice-to-have | The beam-defining slit blade-axis map and handles. | Slits bound to `Slit`. | The slit Asset detail. | - -### Sample stations - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| STAGE-1 | Blocks-go-live | The nanotomography rotation stage (model, encoder, max speed, handle). | A `RotaryStage`, the master clock for hardware-triggered acquisition. | The nano rotation Asset. | -| STAGE-2 | Blocks-go-live | The nanotomography fine sample positioner (the piezo "tripod" axes and model). | A `LinearStage`; axis set a per-Asset setting. | The nano sample-positioner Asset. | -| STAGE-3 | Blocks-go-live | The microtomography station stages (rotation and positioner models, axes, handles). | A `RotaryStage` and a `LinearStage`, mirroring the nano station at coarser resolution. | The micro-station Assets. | - -### Detector and data - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CAM-1 | Blocks-go-live | The detector roster and per-station pairing: which of Pimega (Si photon-counting), the sCMOS indirect chain, and the CdTe Medipix/Mobipix are installed and active at each station. | One detector position bound to `Camera` until staff confirm; the FXI multi-camera precedent. | The detector Assets. | -| CAM-2 | Nice-to-have | The scintillator material and thickness and the Optique Peter microscope objective set for the indirect chain. | A `Scintillator` (e.g. LuAG:Ce) coupled via a microscope. | The indirect-chain detail. | -| MAG-1 | Nice-to-have | The cone-beam magnification rule (how sample-along-cone position maps to magnification). | A `PseudoAxis` over the sample and detector distances; rule deferred. The FXI Magnification precedent. | The magnification Asset. | -| DATA-1 | Blocks-go-live | The acquisition file format and layout: HDF5 / NeXus / DXchange `exchange/data` + flat + dark, and the metadata schema injected into the file. | A single main data file carrying projections, flat, dark, and metadata; format pending. | The data-of-record interface. | - -### Control, compute, and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-build | The EPICS PV namespaces, the TATU trigger handles, and the motion-controller boxes. None are in public sources. | EPICS IOCs + a TATU FPGA trigger as the floor, with the handles carried confirm. | Verifying each Asset's control handle. | -| ORCH-1 | Blocks-go-live | Does MOGNO still run the custom `mgn-*` PyEpics stack, or has it migrated to Bluesky/sophys? | The custom `mgn-devices` / `mgn-routines` / `mgn-control-guis` stack today, with Bluesky a future target. | The orchestration seam CORA conducts over. | -| COMPUTE-1 | Nice-to-have | The reconstruction HPC cluster name, scheduler (SLURM?), GPU resources, and shared storage path. | `ssc-raft` (CUDA) submitted to an HPC cluster over SSH; cluster specifics pending. | The compute leg. | -| PSS-1 | Blocks-go-live | The Sirius personnel-safety permit signals and the photon / front-end shutters. | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| GOV-1 | Nice-to-have | The Sirius operator pool and safety-review structure (site-level). | Carried pending on the Sirius Site, not instantiated per beamline. | The governance principals. | diff --git a/docs/deployments/mx3/notes.md b/docs/deployments/mx3/notes.md deleted file mode 100644 index a0dc89cd4b2..00000000000 --- a/docs/deployments/mx3/notes.md +++ /dev/null @@ -1,108 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at MX3: rotation macromolecular crystallography, each technique a [Catalog](../../catalog/methods.md) Method bound through an [Australian Synchrotron Practice](../as/index.md#the-techniques-adapted-here). MX3 reuses the MX Methods Diamond [I03](../i03/notes.md#techniques) introduced, so it coins nothing new.* - -MX3's technique, rotation MX, is the macromolecular-crystallography shape CORA already saw at i03 (and, in its serial form, at i24 and LCLS-MFX). The Methods render unlinked and are carried pending until the owner-scope decision (TECH-1) brings them into the catalog, exactly as at i03. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Rotation MX data collection | `mx_data_collection` | oscillation collection on the MD3 goniometer + the Eiger; the i03 Method, pending (TECH-1) | -| Grid scan | `grid_scan` | fast grid scan for sample location / centring on the MD3 (TECH-1) | -| Autonomous sample exchange | `sample_exchange` | the ISARA robot load / centre / collect / unmount loop, a Procedure over the spine (ROBOT-1) | - -All three are recorded as pending [Practices](../as/index.md#the-techniques-adapted-here) on the Australian Synchrotron Site, reusing the same Method names Diamond i03 carries. - -### Why the Methods are reused, not coined - -MX3 brings a new Site, not a new technique. Rotation MX, grid-scan centring, and robot sample exchange are the i03 shapes, so MX3 binds the same pending Methods (`mx_data_collection`, `grid_scan`, `sample_exchange`) rather than coining anything; whether those Methods enter the catalog is the cross-facility owner-scope decision i03 opened (TECH-1), and MX3 reinforces the case at a further facility (after Diamond i03 and NSLS-II FMX / AMX). The device Roles already exist (the MD3 presents Positioner via the graduated `Goniometer`, the Eiger presents Detector via `Camera`), so nothing new is needed in the device model either. - -The autonomous sample exchange reuses the i03 / i24 autonomous-loop shape: a Procedure over the spine threaded through `Subject` custody, not a new device family (ROBOT-1). Indexing and integration of the diffraction frames are `ComputePort` work, not beamline Methods. - -The genuinely new thing MX3 contributes is below the technique layer: a sixth Site and a heterogeneous control plane (see [Controls](controls.md)), which the technique vocabulary rides over unchanged. - -## Governance - -*Who may act at MX3 and the trust shape CORA applies. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority.* - -People and agents are facility principals at the [Australian Synchrotron Site](../as/index.md#safety-and-governance); on the beamline they surface through the actions they take. The human roster is not in the device library (GOV-1), so the principals are the design shape, not a registered list. - -### Who acts - -CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the Australian Synchrotron Site. An MX3 beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. This is the same role kernel CORA seeds at every Site; MX3 being a new Site is exactly the test that the Federation / Access kernel ports unchanged. - -### The trust boundary - -CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may start a collection, move the robot, change the energy, override a caution, or commit a calibration. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer, and it holds the same across all four control planes (a command to the Eiger over REST or the robot over TCP is gated exactly as an EPICS motor move is). The facility proposal and cycle are a fact CORA's Campaign uses for custody. - -### Unattended autonomous collection - -MX3's throughput model is unattended: the ISARA robot mounts a crystal, the MD3 centres it, the Eiger collects, the robot unmounts, repeat. That loop is where CORA's custody and trust shapes earn their keep, each crystal threaded through the `Subject` aggregate so its identity and provenance is tracked, the exchange a Procedure gated by a Clearance (ROBOT-1). If an autonomous Agent were added to choose which crystal to collect or when a dataset is good enough, it would be a facility principal scoped at the Site, governed by the same trust boundary, with each choice recorded as a [Decision](../../architecture/modules/decision/index.md). None is declared yet. - -## Model - -*The developer's by-kind index: where each CORA aggregate's MX3 content lives. It hosts no content of its own. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC -[modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at MX3 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (EnergyAxis) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [The beamline](index.md#enclosures) (MX3-OH optics, MX3-EH experiment) | -| Facility (Federation); Zone, Conduit, Policy (Trust); Actor (Access) | [Australian Synchrotron Site](../as/index.md), [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### Deliberately not here yet - -This is a design-phase scaffold (descriptor + docs), mirroring the other reverse-engineered beamlines. Left out on purpose: - -- **No new Family.** MX3's novelty is the Site and its control plane, not its devices: the MD3 goniometer binds the graduated `Goniometer` (the i03 MX precedent), the detectors `Camera`, the DMM `Monochromator`, the cryojet `TemperatureController`, the attenuator `Filter`, the flux monitor `FluxMonitor`, the beamstop `BeamStop`, the shutters `Shutter`, the stages `LinearStage` / `MotionController`. -- **The reused loose family.** `StorageRing` (the ring-current monitor) is bound loose, already allowlisted from earlier deployments; MX3 coins no new loose family. The MD3 backlight binds the catalog `Backlight` Family (graduated across the MX / imaging fleet). The beam-position monitor binds the graduated catalog `BeamPositionMonitor`, which presents `Sensor`, earned across the wide fleet that shares it, distinct from `FluxMonitor` by measuring beam position rather than flux. -- **The heterogeneous control plane.** MX3 drives EPICS, the MXCuBE Exporter protocol (MD3), the SIMPLON REST API (Eiger), and a TCP robot client (ISARA). This is modelled as `ControlPort` adapters, not new aggregates; the three non-EPICS devices carry no PV and route their host / endpoint to deployment config (GONIO-1, DET-1, ROBOT-1). See [Controls](controls.md). -- **The ISARA robot as a Procedure.** Autonomous sample exchange is a deferred Procedure over the spine threaded through `Subject` custody (ROBOT-1), reusing the i03 / i24 shape, not a new device family. -- **The beam-steering controller.** The closed-loop PID steering paired with the BPM (`MX3DAQIOC04:`) fits no existing family cleanly; the BPM half binds `PositionMonitor` and the steering controller is a deferred new-device question (STEER-1). -- **No new Capability or Method.** Rotation MX reuses the pending i03 Methods (`mx_data_collection` / `grid_scan` / `sample_exchange`), recorded as Practices on the Site; MX3 reinforces the case without coining any (TECH-1). -- **Operations and experiment views, integration scenarios, vendor Models.** A runbook and registered Assets for a beamline CORA does not yet drive would be invention; they land when the design firms and the team confirms. - -## Open questions - -*What CORA needs the Australian Synchrotron / MX3 team to confirm. This model is reverse-engineered from public open source (the [`AustralianSynchrotron/mx3-beamline-library`](https://github.com/AustralianSynchrotron/mx3-beamline-library) device library): the EPICS PVs are read from it, but vendor identities, physical positions, the source, and the non-EPICS subsystem endpoints are not. Each row is a fact the beamline team owns. It is a delete-on-answer queue.* - -Priorities: `Blocks-build`, `Blocks-go-live`, `Nice-to-have`. - -### Source and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-go-live | The insertion-device / front-end source: MX3 is an undulator beamline, but no source PV is in the library, only the storage-ring current monitor (`SR11BCM01:CURRENT_MONITOR`). | An insertion-device source, identity-only, no PV; the ring-current monitor stands in as the source representation. | The Source Asset and its PV. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit-leaf PVs. Only the photon-shutter enable / status PVs (`MX3FE01SHT01`, `MX3BLSH01SHT01`) are in source. | The permit signal is a confirm note, not a guessed PV. | The Enclosure permit signals. | -| ENC-1 | Nice-to-have | The hutch layout and names: which devices sit in the optics hutch versus the experiment hutch? The library exposes no enclosure structure. | An optics hutch plus an experiment hutch (the MD3 / Eiger / robot). | The Enclosure set and roles. | - -### Optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DCM-1 | Nice-to-have | The double-multilayer monochromator coating stripes and range, and the attenuator foil set. Both (`MX3MONO01`, `MX3FLT05`) are in source. | One Monochromator and one Filter Asset, settings blank. | The Monochromator / Filter settings. | -| OPT-1 | Nice-to-have | The beam-conditioning optics not in the library: mirrors and any standalone slits (the `devices/optics.py` stub is empty). | None modelled; the `MX3FLT05` unit carries the beam-size readback. | The mirror / slit Assets. | -| ENERGY-1 | Nice-to-have | Does MX3 scan energy as the measurement (anomalous / MAD MX), or run fixed-energy per dataset? | Fixed-energy; the master energy axis is a setpoint. | The energy Capability decision. | - -### Sample, detector, robot - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| GONIO-1 | Blocks-go-live | The MD3 microdiffractometer host / port (it is driven over the MXCuBE Exporter protocol at `MD3_ADDRESS:MD3_PORT`, an env-config default in the library, not a baked PV), and the full axis set behind the Exporter property names. | A `Goniometer` Asset (omega / kappa / phi + centring / alignment) over the Exporter seam; the host is deployment config. | The Goniometer interface and axes. | -| DET-1 | Blocks-go-live | The DECTRIS Eiger model (16M / 4M) and its SIMPLON REST endpoint (`SIMPLON_API`, an env-config default in the library). | An Eiger `Camera` over the SIMPLON REST seam; the endpoint is deployment config. | The detector Model and interface. | -| ROBOT-1 | Nice-to-have | The ISARA sample-mounting robot (a TCP client at `ROBOT_HOST`, mount / unmount trajectories gated on the MD3 state). CORA would model autonomous sample exchange as a Procedure over the spine threaded through the `Subject` aggregate and gated by a Clearance, the same shape as the i03 / i24 loops. | The robot is deferred autonomous-loop machinery, not a beam-path Asset. | The sample-exchange Procedure and Subject custody thread. | -| DIAG-1 | Nice-to-have | The flux and beam-position channel maps; the `PositionMonitor` Family is settled (graduated catalog Family presenting `Sensor`, distinct from `FluxMonitor` by measuring beam position rather than flux). | Read-only flux (`FluxMonitor`) and beam-position (graduated catalog `PositionMonitor`) probes; channel maps blank. | The FluxMonitor / PositionMonitor bindings. | -| STEER-1 | Nice-to-have | The closed-loop beam-steering controller (`MX3DAQIOC04:` PID + DAC paired with the BPM): is it a device Family of its own, or a settings-only feedback variant? It fits no existing family cleanly. | The BPM half binds the graduated catalog `PositionMonitor`; the PID steering controller is named but not modelled. | The beam-steering device boundary. | - -### Controls and technique scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DRIVE-1 | Blocks-go-live | The motion-controller box firmware / IPs (the Australian Synchrotron Power Brick PMAC behind the `MX3STG..MOT..` axes). | Families bound (MotionController), specifics blank. | The MotionController Models. | -| TECH-1 | Blocks-go-live | Do the MX Capabilities (rotation data collection, grid scan) enter CORA's catalog, or stay deferred? This is the same owner-scope decision Diamond i03 opened; MX3 reuses the pending `mx_data_collection` / `grid_scan` / `sample_exchange` Methods. | Methods deferred (pending Practices on the Site), no catalog Method coined. | The MX Capability scope. | diff --git a/docs/deployments/p01/notes.md b/docs/deployments/p01/notes.md deleted file mode 100644 index 95105103b2e..00000000000 --- a/docs/deployments/p01/notes.md +++ /dev/null @@ -1,143 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of P01 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../petra-iii/index.md#the-techniques-adapted-here) is how a facility adapts it. P01 runs hard X-ray dynamics techniques (nuclear resonant scattering and resonant inelastic scattering) that earn no catalog Method today, so the Methods below render unlinked and are carried pending until a technique enters scope (`TECH-1`). - -### Nuclear resonant scattering (EH1) - -P01 sets the X-ray energy onto a Moessbauer isotope's nuclear resonance with the [double-crystal monochromator](source.md), then carves a meV / Moessbauer-energy bandwidth with the [high-resolution monochromator stack](sample.md) (the four nested / channel-cut HRMs). Scanning the high-resolution-monochromator energy axis while reading the time- and energy-resolved detector signal produces the nuclear inelastic / resonant spectrum. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Nuclear resonant scattering / nuclear inelastic scattering | `inelastic_x_ray_scattering` | the high-resolution-monochromator energy scan reading the avalanche-photodiode signal; no catalog Method fits, reuses the IXS slug ESRF ID28 / NSLS-II IXS share, a further consumer (`TECH-1`) | - -### Resonant inelastic X-ray scattering (EH3) - -P01's EH3 endstation focuses the beam with the [KB mirror pair](sample.md) onto the sample and analyzes the inelastically scattered photons on the spectrometer arm, scanning the incident energy against the analyzed energy to map the excitation spectrum. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Resonant inelastic X-ray scattering | `resonant_inelastic_scattering` | KB-focused incident beam analyzed on the EH3 spectrometer; reuses the RIXS slug SIX / ESRF ID32 share, a further consumer (`TECH-1`) | - -### Diffraction (EH2) - -P01's EH2 endstation carries a theta / two-theta [goniometer](sample.md) reading a detector on a positioning stage, for hard X-ray diffraction. The catalog carries no general diffraction Method today; the technique is noted, not bound, pending confirmation of the endstation's routine use (`TECH-1`, `DIFF-1`). - -### A new technique branch on familiar vocabulary - -P01 is the fleet's NRS / RIXS dynamics beamline. Its techniques are new to CORA's catalog (which is tomography- and MX-centric today), but they reuse the inelastic- and resonant-inelastic-scattering slugs already carried pending across the fleet (ESRF ID28 IXS, ESRF ID32 / SIX RIXS, NSLS-II IXS), so none forces a new Method to be coined now. The instrument anatomy reuses existing Families end to end: the monochromators bind `Monochromator`, the KB mirrors `Mirror`, the lens `Transfocator`, the stages `LinearStage` / `RotaryStage` / `Table`, the sample circle `Goniometer`. - -### Not modelled yet - -The concrete acquisition recipes (the high-resolution-monochromator energy-scan sequences and their exposures, the RIXS incident-energy scans, the diffraction scans) are not written yet; they join as the deployment approaches the point where CORA drives P01. Whether the NRS / RIXS Methods enter CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at P01, and the trust shape that will gate it. First cut.* - -Governance at P01 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), 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). - -P01 is CORA's first PETRA III beamline, so the DESY operator pool and the safety-review structure are carried pending on the [PETRA III Site](../petra-iii/index.md#safety-and-governance), shared across the facility's beamlines, until DESY staff confirm them (`GOV-1`). P01 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives P01, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. The OnlineXML carries beamline devices, not the personnel-safety interlock leaves, so the Enclosure permit signals (across the two optics and three experiment hutches) and the interlock structure are carried pending and are not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -P01 also carries the hazard classes that come with its endstations: the high-resolution-monochromator stack and the KB optics are precision instruments inside interlocked hutches, and the five-hutch layout means several enclosures gate the beam in series. Those land with the instruments that bring them when the deployment firms up. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives P01, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's P01 content lives, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at P01 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (coupled mono energy) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes P01 new - -P01 is a new Site's first beamline, and two things genuinely new at the modelling level. It is **CORA's first PETRA III beamline** and a further **Tango / Sardana control floor** (after MAX IV and ALBA). Its science is hard X-ray dynamics: nuclear resonant scattering in EH1, diffraction in EH2, and RIXS in EH3, across 2.5-80 keV. - -- **The control plane (`CTRL-1`).** PETRA III runs Tango with Sardana as the scan layer. P01 is the first deployment whose device handles were read from a DESY OnlineXML registry, the Tango analog of the ESRF BLISS Beacon config and the APS Guarneri `devices.yml`. The OnlineXML extractor that produced the candidate is `reverse_engineer/` in the (private) `xmap/research` repo (the `--source onlinexml` path). -- **The technique branch (`TECH-1`).** NRS and RIXS are new to CORA's catalog but reuse the IXS / RIXS slugs already carried pending across the fleet, so no Method is coined now. - -### No new families (the optics / motion spine reuses the fleet precedent) - -P01 coins no new Family. The monochromators bind `Monochromator` and the coupled energy is a `PseudoAxis`; the mirrors (deflection and KB) bind `Mirror`; the slits bind `Slit`; the CRL binds `Transfocator`; the undulator binds `InsertionDevice`; the stages bind `LinearStage` / `RotaryStage` / `Table`; the EH2 sample circle binds `Goniometer`; the BPM / ion chamber / diamond monitor bind `FluxMonitor`. Nothing in the catalog changes. - -The one binding worth calling out: the EH2 sample circle is modelled as a **`Goniometer`** Asset (the catalog Family), not the composed **`Diffractometer`** Assembly. The OnlineXML exposes only theta / two-theta; the `Diffractometer` Assembly requires a goniometer plus a detector arm plus a reciprocal-space layer, none of which the registry confirms. This follows the catalog's own guidance (the TARDIS E6C precedent) and is carried `DIFF-1`. - -### The control plane - -P01 sits on the PETRA III Tango device floor with Sardana as the scan / motion SCADA layer (Pool / MacroServer / MeasurementGroup, Spock CLI, Taurus UIs). A motion axis is a Tango motor device (`p01/motor/.`), a coupled axis is a virtual-motor executor (`p01/vmexecutor/`), and a scan is a Sardana macro. The handles are read from P01's public OnlineXML registry and carried confirm; the device servers live in `tango-ds/deviceclasses`, the Sardana fork in `fsec-sardana` (`CTRL-1`). The NRS / RIXS acquisition runs as a Sardana macro; that orchestration is the seam CORA's edge replaces or drives through over its `ControlPort`, conducting over the Tango floor rather than owning it. The NeXus file-writing (the `nexdatas` chain) is plumbing CORA observes, not data it owns. - -### Deliberately not here yet - -- **The detector devices (`DET-1`).** The OnlineXML carries detector positioning stages, not the detector device servers; the APD / RIXS / diffraction detectors are named, not bound. -- **The physical optics detail (`MONO-1`, `NRS-1`, `OPT-1`).** The DCM crystal cut, which HRM is in beam per isotope, the mirror coatings, the KB bend radii, and the CRL recipe are carried confirm-pending. -- **The goniometer geometry (`DIFF-1`).** The EH2 circle count beyond theta / two-theta, and whether it composes a Diffractometer Assembly, is pending. -- **The handle freshness (`CTRL-1`).** The OnlineXML branch is `debian/jessie`; some handles may lag the live Tango database. -- **The NRS / RIXS Methods (`TECH-1`).** Whether these enter CORA's catalog is an owner decision; the Practices render unlinked, pending, reusing the IXS / RIXS slugs. -- **The PSS permit signals (`PSS-1`).** Not in the OnlineXML; carried pending, not invented. -- **The simulated devices and full asset-tree scenarios.** No `test_p01_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the P01 team to confirm before the model can be trusted.* - -P01 was reverse-engineered from P01's own public OnlineXML device registry ([gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p01](https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p01), branch `debian/jessie`) and a verified research brief, not from a live connection. The registry carries real Tango device names and control handles, but no physical detail (crystal cuts, energy ranges, bend radii, detector models). P01 is CORA's first PETRA III beamline and a further Tango / Sardana control floor (after MAX IV and ALBA). Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: two optics hutches (OH1, OH2) feeding three experiment hutches (EH1, EH2, EH3), or a different layout? | Two `p01-oh*` optics hutches and three `p01-eh*` experiment hutches, read from the OnlineXML host names. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The undulator period and parameters, and whether gap_a/gap_b/taper_a/taper_b mean two sections or a canted arrangement. | An undulator source, 2.5-80 keV; gap / taper virtual axes only. | The source Asset detail. | -| GROUP-1 | Nice-to-have | The Asset grouping of the registry's per-axis device list into instruments (one monochromator, one mirror, one sample stage). | The groupings on the [device pages](index.md), inferred from the axis name prefixes. | The Asset boundaries. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MONO-1 | Blocks-go-live | The double-crystal monochromator crystal cut (Si 111 / 311) and energy range. | A DCM bound to `Monochromator`; Bragg / energy virtual axes read from the registry. | The monochromator modelling. | -| OPT-1 | Nice-to-have | The deflection-mirror coatings / stripes and incidence angles, the KB bend radii and focal sizes, the CRL lens count / material, and the diamond-monitor / RIXS-pre-optic roles. | Two OH1 mirrors and the EH3 KB pair bound to `Mirror`; the CRL bound to `Transfocator`; the diamond monitor bound to `FluxMonitor`; handles read, physical detail pending. | The optics Asset detail. | - -### Sample endstations - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| NRS-1 | Blocks-go-live | The four EH1 high-resolution monochromators (400 / 1064 / 3D / 3W): which is in beam per Moessbauer isotope and resolution, and how the `hrm_ener` virtual axis couples them. | Four `Monochromator` Assets plus a `HighResMonoEnergy` `PseudoAxis`; selection per isotope pending. | The NRS instrument modelling. | -| DIFF-1 | Blocks-go-live | The EH2 diffractometer geometry: the full circle count beyond theta / two-theta, and whether it composes a Diffractometer Assembly with a detector arm. | A `Goniometer` Asset (theta / two-theta), not the composed Diffractometer Assembly, until a detector arm is confirmed. | The diffractometer modelling. | -| SAMPLE-1 | Nice-to-have | The EH3 RIXS sample-stage axes and sample-environment detail. | A `LinearStage` (x / y / b / rot / tilt) read from the registry. | The sample-stage modelling. | - -### The detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The detector models per endstation (the EH1 NRS avalanche photodiode, the EH2 diffraction detector, the EH3 RIXS spectrometer detector), which the OnlineXML does not carry as motor rows. | Detector positioning stages bound to `LinearStage`; the detector devices named, not bound. | The detector modelling. | -| DIAG-1 | Nice-to-have | The beam-position-monitor, ion-chamber, and diamond-monitor handles and roles. | `FluxMonitor` positioning stages read from the registry. | The diagnostics modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | The Tango device handles per P01 device, and whether the OnlineXML `debian/jessie` branch matches the live Tango database. | The handles read from the public OnlineXML, carried pending; the floor is Tango + Sardana. | Binding each Asset's control handle. | -| PSS-1 | Blocks-go-live | The DESY personnel-safety permit signals and the photon / front-end shutters (absent from the OnlineXML). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent and the cooling / beam supplies. | Photon beam, cooling water, vacuum. | The Supply observations. | -| GOV-1 | Nice-to-have | The DESY operator pool and safety-review structure (site-level). | Carried pending on the PETRA III Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Do nuclear resonant scattering and RIXS enter CORA's catalog as Capabilities / Methods? | Deferred: carried as pending Practices reusing the `inelastic_x_ray_scattering` and `resonant_inelastic_scattering` slugs; none coined. | The technique Capabilities. | diff --git a/docs/deployments/p02/notes.md b/docs/deployments/p02/notes.md deleted file mode 100644 index db92feae5d6..00000000000 --- a/docs/deployments/p02/notes.md +++ /dev/null @@ -1,144 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of P02 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../petra-iii/index.md#the-techniques-adapted-here) is how a facility adapts it. P02's diffraction techniques reuse Methods the fleet already carries pending, so the Methods below render unlinked until a technique enters scope (`TECH-1`). - -### Powder diffraction (P02.1) - -P02.1 illuminates a powder / polycrystalline sample with a high-energy (~60 keV) monochromatic beam and reads the Debye-Scherrer rings on the [Pilatus 1M area detector](detector.md), with in-situ temperature control for parametric studies. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| High-energy powder diffraction | `powder_diffraction` | the powder sample read by the Pilatus 1M; reuses the `powder_diffraction` slug i11 / XPD share, a further consumer (`TECH-1`) | - -### Total scattering / PDF (P02.1) - -P02.1 also collects total scattering to high momentum transfer (the high-energy beam plus the [PerkinElmer flat-panel](detector.md)) for pair-distribution-function analysis of local / disordered structure. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Total scattering / pair-distribution-function | `total_scattering` | high-Q total scattering on the PerkinElmer flat-panel; reuses the `total_scattering` slug i15-1 / XPD share, a further consumer (`TECH-1`) | - -### High-pressure diffraction (P02.2) - -P02.2 puts the sample in a [diamond-anvil cell](sample.md) and collects diffraction under high pressure (and variable temperature), for extreme-conditions studies. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Diamond-anvil-cell high-pressure diffraction | `powder_diffraction` | high-pressure diffraction in the DAC; reuses the `powder_diffraction` slug, a further consumer (`TECH-1`, `PRESSURE-1`) | - -### A high-energy diffraction beamline on familiar vocabulary - -P02 is the fleet's high-energy powder / total-scattering beamline and its first diamond-anvil-cell extreme-conditions endstation. Its techniques reuse the `powder_diffraction` and `total_scattering` slugs already carried pending across the fleet (Diamond i11 / i15-1, NSLS-II XPD), so none forces a new Method now. The instrument anatomy reuses existing Families end to end: the monochromator binds `Monochromator`, the bendable mirrors `Mirror`, the detectors `Camera`, the sample environment `TemperatureController`, and the high-pressure cell the catalog `PressureCell` (graduated across 13-id and P02, with P02 the second consumer that earned it). - -### Not modelled yet - -The concrete acquisition recipes (the powder-ring integration sequences, the high-Q PDF collection, the pressure-ramp diffraction loops) are not written yet; they join as the deployment approaches the point where CORA drives P02. Whether the diffraction Methods or the PressureCell Family enter CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at P02, and the trust shape that will gate it. First cut.* - -Governance at P02 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), 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). - -P02 is CORA's eighth PETRA III beamline: the DESY operator pool and the safety-review structure are carried pending on the [PETRA III Site](../petra-iii/index.md#safety-and-governance), shared across the facility's beamlines, until DESY staff confirm them (`GOV-1`). P02 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives P02, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. The OnlineXML carries beamline devices, not the personnel-safety interlock leaves, so the Enclosure permit signals (across the OH1 optics and the two endstations) and the interlock structure are carried pending and are not invented here (`PSS-1`). A P02-specific note: P02 owns the OH1 high-heatload optics hutch shared with P03, so the optics enclosure's access state couples to the neighbouring beamline, part of the `PSS-1` question. - -P02 also carries the hazard classes that come with its endstations: a high-energy (~60 keV) beam, in-situ furnaces (the Anton-Paar) at P02.1, and the diamond-anvil-cell high-pressure environment at P02.2. Those land with the instruments that bring them when the deployment firms up; the pressure cell is modelled as a sample-environment `PressureCell` Asset, not a beam-steering device CORA drives. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives P02, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's P02 content lives, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at P02 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes P02 new - -P02 is an eighth beamline at an existing Site, and the fleet's high-energy diffraction beamline with two branches: P02.1 (powder / total scattering / PDF, ~60 keV) and P02.2 (extreme conditions, diamond-anvil cell). At the modelling level it brings the fleet's **second diamond-anvil-cell** endstation, binding the catalog `PressureCell` Family (graduated across 13-id and P02, with P02 the second consumer that earned it). - -### No new families (the DAC reuses the 13-id PressureCell) - -P02 coins no new Family. The monochromator binds `Monochromator`; the bendable HFM / VFM mirrors bind `Mirror`; the slits bind `Slit`; the sample stages bind `LinearStage`; the sample environment binds `TemperatureController`; the detectors bind `Camera` / `EnergyDispersiveSpectrometer`; the beam monitor binds `FluxMonitor`; and the diamond-anvil cell binds the catalog `PressureCell`. - -Adding P02 as `PressureCell`'s second consumer crossed the rule-of-three promotion threshold, so the Family graduated to the catalog (earned across 13-id and P02, `PRESSURE-1`), following the path the POLAR-family `PhaseRetarder`, `PolarizationAnalyzer`, and `Magnet` siblings took to catalog Families. This is the graduation guard working as designed. - -### The control plane - -P02 sits on the PETRA III Tango device floor with Sardana as the scan layer, the same as the other PETRA III beamlines. Its distinctive devices are the bendable HFM / VFM mirrors (curvature / ellipticity attribute motors), the Pilatus 1M + PerkinElmer high-energy detectors, and the Anton-Paar / Lakeshore sample environment. The handles are read from P02's public OnlineXML registry and carried confirm (`CTRL-1`). P02 owns the OH1 high-heatload optics hutch shared with P03. The powder / total-scattering / high-pressure acquisition runs as a Sardana macro; that orchestration is the seam CORA's edge replaces or drives through over its `ControlPort`. - -### Deliberately not here yet - -- **The undulator parameters (`SRC-1`).** The OnlineXML exposes the gap, not the period; carried pending. -- **The optics detail (`OPT-1`).** The DCM crystal cut and the bendable-mirror coatings / focusing recipes are carried confirm-pending. -- **The motor-bank axis roles (`GROUP-1`).** The eh1a/b and eh2a/b banks carry no per-axis role; grouped as stage Assets. -- **The pressure-cell control (`PRESSURE-1`).** The diamond-anvil-cell membrane / gas-loading / pressure control is not in the registry; the `PressureCell` Family is the catalog one (graduated across 13-id and P02), with the membrane / load control detail pending. -- **The detector roster (`DET-1`).** The detector models, the powder-vs-PDF detector roles, and the P02.2 diffraction area detector are named, not fully bound. -- **The CH dummy stubs (`STUB-1`).** The CH1 / CH2 `tangomotor` dummies are test / placeholder devices, noted not modelled. -- **The handle freshness (`CTRL-1`).** The OnlineXML branch is `debian/jessie`; some handles may lag the live Tango database. -- **The diffraction Methods (`TECH-1`).** Whether powder diffraction / total scattering enter CORA's catalog is an owner decision; the Practices render unlinked, pending, reusing the existing slugs. -- **The PSS permit signals (`PSS-1`).** Not in the OnlineXML; carried pending, not invented. -- **The simulated devices and full asset-tree scenarios.** No `test_p02_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the P02 team to confirm before the model can be trusted.* - -P02 was reverse-engineered from P02's own public OnlineXML device registry ([gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p02](https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p02), branch `debian/jessie`) and a verified research brief, not from a live connection. The registry carries real Tango device names and control handles, but no crystal cuts, pressure-cell detail, or energy calibration. P02 is CORA's eighth PETRA III beamline and the fleet's second diamond-anvil-cell deployment. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: a shared OH1 optics hutch feeding a P02.1 powder endstation and a P02.2 extreme-conditions endstation? | A `p02-oh1` optics hutch and `p02-1-powder` / `p02-2-extreme` endstations, read from the device-name prefixes. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The undulator period and parameters. | An undulator; gap read, period pending. | The source Asset detail. | -| GROUP-1 | Nice-to-have | The per-axis roles of the motor banks (`eh1a/b`, `eh2a/b`, the OH1 bank). | Grouped as stage Assets carrying the bank prefix; per-axis roles pending. | The Asset boundaries. | -| STUB-1 | Nice-to-have | The CH1 / CH2 `tangomotor` dummy stubs: test / placeholder devices, or real channels? | Noted as dummy stubs, not modelled. | The CH stub status. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| OPT-1 | Blocks-go-live | The DCM crystal cut, the bendable HFM / VFM mirror coatings and focusing recipes, and the slit / CRL detail. | A DCM `Monochromator`, two bendable `Mirror`s, and `Slit`s; physical detail pending. | The optics modelling. | - -### Sample endstations - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| PRESSURE-1 | Blocks-go-live | The P02.2 diamond-anvil-cell control: the membrane / gas-loading / pressure-ramp interface, and the cell's positioning stages. | A `PressureCell` Asset (the catalog Family, graduated across 13-id and P02); membrane / load control pending. | The pressure-cell modelling. | -| TEMP-1 | Nice-to-have | The P02.1 sample-environment sensor / setpoint handles (Anton-Paar, Eurotherm, Lakeshore). | `TemperatureController` controllers; in-situ furnace / cryo. | The sample-environment modelling. | - -### The detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The detector roster per branch, the powder-vs-PDF detector roles (Pilatus 1M vs PerkinElmer), and the P02.2 high-pressure diffraction area detector. | `Camera` area detectors plus `EnergyDispersiveSpectrometer` fluorescence; roles pending. | The detector modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | The Tango device handles per P02 device, the shared OH1 optics with P03, and whether the OnlineXML `debian/jessie` branch matches the live Tango database. | The handles read from the public OnlineXML, carried pending; the floor is Tango + Sardana; OH1 shared with P03. | Binding each Asset's control handle. | -| PSS-1 | Blocks-go-live | The DESY personnel-safety permit signals, the shared-optics access coupling with P03, and the photon / front-end shutters (absent from the OnlineXML). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent and the cooling / beam supplies. | Photon beam, cooling water, vacuum. | The Supply observations. | -| GOV-1 | Nice-to-have | The DESY operator pool and safety-review structure (site-level). | Carried pending on the PETRA III Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Do powder diffraction and total scattering / PDF enter CORA's catalog as Capabilities / Methods? | Deferred: carried as pending Practices reusing the `powder_diffraction` / `total_scattering` slugs i11 / i15-1 / XPD share; none coined. | The technique Capabilities. | diff --git a/docs/deployments/p03/notes.md b/docs/deployments/p03/notes.md deleted file mode 100644 index c6a28b12173..00000000000 --- a/docs/deployments/p03/notes.md +++ /dev/null @@ -1,134 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of P03 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../petra-iii/index.md#the-techniques-adapted-here) is how a facility adapts it. P03 runs small- and wide-angle X-ray scattering, which earns no catalog Method today, so the Methods below render unlinked until a technique enters scope (`TECH-1`). - -### Small-angle X-ray scattering - -P03 focuses the beam (the multilayer monochromator feeding the CRL or the GINIX waveguide) to a micro or nano spot, illuminates the sample, and reads the small-angle scattering on the [Pilatus area detector](detector.md) at a distance. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Small-angle X-ray scattering (SAXS) | `small_angle_scattering` | the focused beam on the sample read by the Pilatus at a SAXS distance; reuses the `small_angle_scattering` slug, a further consumer (`TECH-1`) | - -### Wide-angle X-ray scattering - -The microfocus endstation's Pilatus 1M reads the wide-angle scattering simultaneously with the SAXS signal. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Wide-angle X-ray scattering (WAXS) | `wide_angle_scattering` | the Pilatus 1M reading the wide-angle signal; reuses the `wide_angle_scattering` slug, a further consumer (`TECH-1`) | - -### A new technique family on familiar vocabulary - -P03 is PETRA III's first SAXS / WAXS beamline. Its techniques reuse the `small_angle_scattering` and `wide_angle_scattering` slugs already in the catalog's method vocabulary (the same slugs the NSLS-II SMI / CMS and Diamond i22 scattering beamlines carry), so neither forces a new Method to be coined now. The instrument anatomy reuses existing Families: the monochromator binds `Monochromator`, the mirrors `Mirror`, the CRL and GINIX hexapods `Hexapod`, the slits `Slit`, the detectors `Camera`. The GINIX nanofocus adds a waveguide (modelled as a `Hexapod` carrier plus `LinearStage` waveguide stages) and a sample rotation (`RotaryStage`) that suits scanning / nano-imaging, but no new Family. - -### Not modelled yet - -The concrete acquisition recipes (the SAXS / WAXS exposure sequences, the GINIX scanning / waveguide alignment, the grazing-incidence variants) are not written yet; they join as the deployment approaches the point where CORA drives P03. Whether the scattering Methods enter CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at P03, and the trust shape that will gate it. First cut.* - -Governance at P03 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), 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). - -P03 is CORA's fifth PETRA III beamline: the DESY operator pool and the safety-review structure are carried pending on the [PETRA III Site](../petra-iii/index.md#safety-and-governance), shared across the facility's beamlines (with P01, P04, P06, P11), until DESY staff confirm them (`GOV-1`). P03 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives P03, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. The OnlineXML carries beamline devices, not the personnel-safety interlock leaves, so the Enclosure permit signals (across the shared optics and the two endstations) and the interlock structure are carried pending and are not invented here (`PSS-1`). The nanofocus GINIX experiment shutter is read from the registry but its safety role is not (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -A P03-specific governance note: P03 shares its high-heatload optics with P02, so the optics enclosure's safety and access state is coupled to the neighbouring beamline; how the shared-optics permit is modelled is part of the `HOST-1` / `PSS-1` questions. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives P03, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's P03 content lives, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at P03 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes P03 new - -P03 is a fifth beamline at an existing Site, and the fleet's entry into small-angle / wide-angle scattering. It is the MiNaXS beamline: micro- and nanofocus SAXS / WAXS at 9-23 keV across two endstations (the microfocus endstation and the nanofocus GINIX endstation with its waveguide nano-focusing). It brings a two-endstation-sharing-one-optics-chain layout, the shared P02 / P03 high-heatload optics, and two new Tango motion-controller protocols (Galil DMC slit controllers, SmarPod controllers), but no new Family or Method. - -### No new families (the scattering instrument reuses existing vocabulary) - -P03 coins no new Family. The multilayer monochromator binds `Monochromator`; the mirrors bind `Mirror`; the CRL and GINIX hexapods bind `Hexapod`; the waveguide stages bind `LinearStage`; the slits bind `Slit`; the sample rotation binds `RotaryStage`; the sample environment binds `TemperatureController`; the detectors bind `Camera` / `EnergyDispersiveSpectrometer`; the shutter binds `Shutter`. Nothing in the catalog changes. - -### The control plane - -P03 sits on the PETRA III Tango device floor with Sardana as the scan layer, the same as the other PETRA III beamlines, and adds two controller protocols new to the set: Galil DMC slit controllers and SmarPod controllers (the GINIX waveguide). The handles are read from P03's public OnlineXML registry and carried confirm (`CTRL-1`); the shared P02 / P03 optics mean the first defining slit reports on the P02 host (`HOST-1`). The SAXS / WAXS acquisition (the sample scan coupled to the Pilatus, the GINIX waveguide-scanning nano-imaging) runs as a Sardana macro; that orchestration is the seam CORA's edge replaces or drives through over its `ControlPort`. - -### Deliberately not here yet - -- **The undulator parameters (`SRC-1`).** The OnlineXML exposes the gap, not the period; carried pending. -- **The optics physical detail (`OPT-1`).** The multilayer d-spacing, the mirror coatings, and the CRL / waveguide focal sizes are carried confirm-pending. -- **The motor-bank axis roles (`GROUP-1`).** The `expmi_mot` and `mot` banks carry no per-axis role in the registry; grouped as sample-stage Assets, roles pending. -- **The GINIX geometry (`SAMPLE-1`).** The waveguide-to-sample geometry and the sample-hexapod / rotation detail are pending. -- **The detector roster (`DET-1`).** The SAXS-vs-WAXS detector assignment, the sample-to-detector distance, and the detector models are named, not fully bound. -- **The host mapping (`HOST-1`).** The shared P02 / P03 optics host and the bare-host Lambda are flagged; whether shared Tango DB or registry artifact is pending. -- **The handle freshness (`CTRL-1`).** The OnlineXML branch is `debian/jessie`; some handles may lag the live Tango database. -- **The scattering Methods (`TECH-1`).** Whether SAXS / WAXS enter CORA's catalog is an owner decision; the Practices render unlinked, pending, reusing the existing slugs. -- **The PSS permit signals (`PSS-1`).** Not in the OnlineXML; carried pending, not invented. -- **The simulated devices and full asset-tree scenarios.** No `test_p03_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the P03 team to confirm before the model can be trusted.* - -P03 was reverse-engineered from P03's own public OnlineXML device registry ([gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p03](https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p03), branch `debian/jessie`) and a verified research brief, not from a live connection. The registry carries real Tango device names and control handles, but no focal sizes, multilayer d-spacing, or energy calibration. P03 is CORA's fifth PETRA III beamline and its first SAXS / WAXS beamline. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: shared optics feeding a microfocus endstation and a nanofocus GINIX endstation? | A `p03-optics` section (shared with P02) and two `p03-microfocus` / `p03-nanofocus` endstations. | The Enclosure grouping. | -| HOST-1 | Nice-to-have | The first defining slit reports on the P02 optics host (`haspp02oh1`) and a Lambda on the bare `petra3` host. Shared Tango DB hosts, or registry artifacts? | The shared P02 / P03 optics are homed in `p03-optics`; the hosts are flagged. | The device-to-host mapping. | -| GROUP-1 | Nice-to-have | The per-axis roles of the motor banks (`expmi_mot01..64` microfocus, `mot01..40` nanofocus). | Grouped as sample-stage Assets carrying the bank prefix; per-axis roles pending. | The sample-stage Asset boundaries. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Nice-to-have | The undulator period and parameters. | An undulator; gap read, period pending. | The source Asset detail. | -| OPT-1 | Blocks-go-live | The multilayer monochromator d-spacing, the mirror coatings, and the CRL / GINIX-waveguide focal sizes. | A multilayer `Monochromator`, two `Mirror`s, a CRL `Hexapod`, and the GINIX waveguide; handles read, physical detail pending. | The optics modelling. | - -### Sample endstations - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SAMPLE-1 | Nice-to-have | The GINIX waveguide-to-sample geometry and the sample-hexapod / rotation detail. | A `Hexapod` sample stage and a `RotaryStage` rotation; geometry pending. | The GINIX sample modelling. | -| TEMP-1 | Nice-to-have | The Eurotherm 2604 sample-environment sensor / setpoint handles. | A `TemperatureController` sample environment. | The temperature-control modelling. | - -### The detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The detector roster per experiment, the SAXS-vs-WAXS assignment (Pilatus 300k / 1M), the sample-to-detector distance, and the fluorescence-detector channel count. | `Camera` Pilatus detectors plus `EnergyDispersiveSpectrometer` MCA / XIA detectors; assignment pending. | The detector modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | The Tango device handles per P03 device, and whether the OnlineXML `debian/jessie` branch matches the live Tango database. | The handles read from the public OnlineXML, carried pending; the floor is Tango + Sardana. | Binding each Asset's control handle. | -| PSS-1 | Blocks-go-live | The DESY personnel-safety permit signals, the photon / front-end shutters, and the role of the GINIX experiment shutter (absent / partial in the OnlineXML). | Permit leaves and shutters to be named; the GINIX shutter bound to `Shutter`, safety role pending. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent and the cooling / beam supplies. | Photon beam, cooling water, vacuum. | The Supply observations. | -| GOV-1 | Nice-to-have | The DESY operator pool and safety-review structure (site-level), and the shared-optics permit coupling with P02. | Carried pending on the PETRA III Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Do small-angle and wide-angle X-ray scattering enter CORA's catalog as Capabilities / Methods? | Deferred: carried as pending Practices reusing the `small_angle_scattering` and `wide_angle_scattering` slugs; none coined. | The technique Capabilities. | diff --git a/docs/deployments/p04/notes.md b/docs/deployments/p04/notes.md deleted file mode 100644 index 3aad8856957..00000000000 --- a/docs/deployments/p04/notes.md +++ /dev/null @@ -1,128 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of P04 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../petra-iii/index.md#the-techniques-adapted-here) is how a facility adapts it. P04 runs soft X-ray spectroscopy, which earns no catalog Method today, so the Methods below render unlinked and are carried pending until a technique enters scope (`TECH-1`). - -### Soft X-ray absorption spectroscopy - -P04 sets the photon energy (250-3000 eV) by coupling the [variable-polarization undulator](source.md) and the [plane-grating monochromator](source.md), then scans it across an absorption edge while reading the sample drain current on the [electrometer](detector.md) (total electron yield). - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Soft X-ray absorption (XAS / NEXAFS) | `xas_spectroscopy` | the undulator + PGM photon-energy scan reading the Keithley electrometer; reuses the `xas_spectroscopy` slug four sites share, a further consumer (`TECH-1`) | - -### Photoemission - -P04's variable polarization and soft X-ray energy range suit photoemission on the EXP endstations (the analyzer is an endstation instrument not exposed as a motor in the registry). - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Soft X-ray photoemission | `angle_resolved_photoemission` | photoemission on the EXP endstations; reuses the `angle_resolved_photoemission` slug, a further consumer (`TECH-1`) | - -### A new technique regime on mostly familiar vocabulary - -P04 is the fleet's soft X-ray spectroscopy beamline. Its energy regime is new (250-3000 eV, below the hard X-ray beamlines), and it forces the one genuinely new device binding, the `GratingMonochromator` (the soft X-ray analog of the crystal `Monochromator`). The techniques themselves reuse the `xas_spectroscopy` and `angle_resolved_photoemission` slugs already carried pending across the fleet, so neither forces a new Method to be coined now. The rest of the instrument anatomy reuses existing Families: the undulator binds `InsertionDevice`, the mirrors `Mirror`, the slits `Slit`, the manipulators `Manipulator`, the diagnostics `Camera` / `FluxMonitor` / `Screen`. - -### Not modelled yet - -The concrete acquisition recipes (the photon-energy-scan sequences and their dwell times, the polarization switching, the photoemission analyzer sweeps) are not written yet; they join as the deployment approaches the point where CORA drives P04. Whether the soft X-ray Methods enter CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at P04, and the trust shape that will gate it. First cut.* - -Governance at P04 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), 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). - -P04 is CORA's second PETRA III beamline, not its first: the DESY operator pool and the safety-review structure are carried pending on the [PETRA III Site](../petra-iii/index.md#safety-and-governance), shared across the facility's beamlines (with P01), until DESY staff confirm them (`GOV-1`). P04 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives P04, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. The OnlineXML carries beamline devices, not the personnel-safety interlock leaves, so the Enclosure permit signals (across the optics section and the two experiment endstations) and the interlock structure are carried pending and are not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives P04, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's P04 content lives, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at P04 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (incident-energy axis) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes P04 new - -P04 is a second beamline at an existing Site, and PETRA III's entry into the soft X-ray regime (the fleet's soft X-ray line was opened by NSLS-II SIX). It **binds the catalog `GratingMonochromator` Family** (introduced at SIX, graduated at CSX): its monochromator is a plane-grating monochromator (the soft X-ray analog of the crystal `Monochromator`), not the Bragg crystal mono the hard X-ray beamlines use. Its science is soft X-ray spectroscopy at 250-3000 eV (XAS via total electron yield, and photoemission), fed by a variable-polarization APPLE-II-type undulator. - -### No new families (the one new binding is already in the catalog) - -P04 coins no new Family. The plane-grating monochromator binds the catalog `GratingMonochromator` (its first deployment, but the Family exists); the undulator binds `InsertionDevice`; the mirrors bind `Mirror`; the slits bind `Slit`; the sample manipulators bind `Manipulator`; the diagnostic cameras bind `Camera`; the electrometers bind `FluxMonitor`; the virtual axes bind `PseudoAxis`; and the motorized phosphor screens bind the catalog `Screen` Family (the 2-BM `FLAG-1` precedent). Nothing in the catalog changes. - -### The control plane - -P04 sits on the PETRA III Tango device floor with Sardana as the scan layer, the same as P01. The soft X-ray specifics are the device classes (the `MonoP04` plane-grating monochromator, the `UndulatorP04` variable-polarization undulator, the SmarPod-style `spk` mirror controllers, the `Keithley6517A` electrometers, the `TangoVimba` diagnostic cameras). The handles are read from P04's public OnlineXML registry and carried confirm (`CTRL-1`); some optics report on the `haspp04exp2` host but are the optics section (`HOST-1`). The soft X-ray absorption acquisition (the undulator + PGM photon-energy scan read against the electrometer) runs as a Sardana macro; that orchestration is the seam CORA's edge replaces or drives through over its `ControlPort`. - -### Deliberately not here yet - -- **The undulator polarization control (`SRC-1`).** The OnlineXML exposes the gap, not the APPLE-II row-phase / polarization axes; carried pending. -- **The optics physical detail (`OPT-1`).** The grating line densities, the included-angle / c-value mode, the mirror coatings, and the exit-slit calibration are carried confirm-pending. -- **The manipulator axis roles (`GROUP-1`).** The `exp1_mot01..16` and `ps2.01..14` banks carry no per-axis role in the registry; grouped as `Manipulator` Assets, roles pending. -- **The EXSU2 sub-roles (`EXSU-1`).** The exit-shutter unit's slit / bpm / baffle breakdown is pending. -- **The detection channels (`DET-1`).** The electrometer measured channels and the photoemission analyzer (not a motor row) are named, not bound. -- **The host mapping (`HOST-1`).** The optics report on the experiment host; whether this is a shared Tango DB or a registry artifact is pending. -- **The handle freshness (`CTRL-1`).** The OnlineXML branch is `debian/jessie`; some handles may lag the live Tango database. -- **The soft X-ray Methods (`TECH-1`).** Whether XAS and photoemission enter CORA's catalog is an owner decision; the Practices render unlinked, pending, reusing the existing slugs. -- **The PSS permit signals (`PSS-1`).** Not in the OnlineXML; carried pending, not invented. -- **The simulated devices and full asset-tree scenarios.** No `test_p04_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the P04 team to confirm before the model can be trusted.* - -P04 was reverse-engineered from P04's own public OnlineXML device registry ([gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p04](https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p04), branch `debian/jessie`) and a verified research brief, not from a live connection. The registry carries real Tango device names and control handles, but no grating line densities, polarization modes, or energy calibration. P04 is CORA's second PETRA III beamline and PETRA III's first soft X-ray / grating-monochromator deployment. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: a soft X-ray optics section feeding two experiment endstations (EXP1, EXP2)? | A `p04-optics` section and two `p04-exp*` endstations, read from the OnlineXML host names. | The Enclosure grouping. | -| HOST-1 | Nice-to-have | The optics (undulator, PGM, mirrors, exit slits) report on the `haspp04exp2` Tango host. Is that a shared Tango DB host for the optics, or a registry artifact? | The optics are the optics section (`p04-optics`); the host is flagged. | The optics-to-host mapping. | -| GROUP-1 | Nice-to-have | The per-axis roles of the manipulator banks (`exp1_mot01..16`, `ps2.01..14`, `exp2_mot06/08`). | Grouped as `Manipulator` Assets carrying the handles; per-axis roles pending. | The sample-stage Asset boundaries. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-go-live | The variable-polarization undulator: the polarization modes (H / V / circular) and the row-phase axes that set them. | An APPLE-II-type undulator, 250-3000 eV; gap read, row-phase axes pending. | The source Asset detail. | -| OPT-1 | Blocks-go-live | The plane-grating monochromator grating line densities and mode (included angle / c-value), the three mirror coatings and roles, and the exit-slit calibration. | A `GratingMonochromator`, three `Mirror`s, and exit `Slit`s; handles read, physical detail pending. | The optics modelling. | - -### Sample and detection - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| EXSU-1 | Nice-to-have | The EXP2 exit-shutter unit (EXSU2) sub-roles: slit (Spalt), translation, beam-position monitor, baffle. | Modelled as a beam-defining `Slit`; the bpm / baffle roles pending. | The EXSU2 modelling. | -| DET-1 | Blocks-go-live | The electrometer measured channels (drain current vs I0) and the photoemission analyzer (the endstation spectrometer, not a motor row). | `FluxMonitor` electrometers; the analyzer named, not bound. | The detection modelling. | -| DIAG-1 | Nice-to-have | The EXP2 diagnostic-screen positions and the camera-to-screen mapping. | Motorized `Screen`s imaged by `Camera`s; positions pending. | The diagnostics modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | The Tango device handles per P04 device, and whether the OnlineXML `debian/jessie` branch matches the live Tango database. | The handles read from the public OnlineXML, carried pending; the floor is Tango + Sardana. | Binding each Asset's control handle. | -| PSS-1 | Blocks-go-live | The DESY personnel-safety permit signals and the photon / front-end shutters (absent from the OnlineXML). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent and the cooling / beam supplies. | Photon beam, cooling water, vacuum. | The Supply observations. | -| GOV-1 | Nice-to-have | The DESY operator pool and safety-review structure (site-level). | Carried pending on the PETRA III Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Do soft X-ray absorption and photoemission enter CORA's catalog as Capabilities / Methods? | Deferred: carried as pending Practices reusing the `xas_spectroscopy` and `angle_resolved_photoemission` slugs; none coined. | The technique Capabilities. | diff --git a/docs/deployments/p06/notes.md b/docs/deployments/p06/notes.md deleted file mode 100644 index b377f1b5bf7..00000000000 --- a/docs/deployments/p06/notes.md +++ /dev/null @@ -1,135 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of P06 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../petra-iii/index.md#the-techniques-adapted-here) is how a facility adapts it. P06 runs hard X-ray scanning-probe microscopy and nano-tomography, reusing Methods the fleet already carries pending, so the Methods below render unlinked until a technique enters scope (`TECH-1`). - -### Scanning fluorescence / diffraction microscopy - -P06 focuses the beam (the multilayer or crystal monochromator feeding the KB optics) to a micro or nano spot, then rasters the sample across it with the [Aerotech scan stage](sample.md) while the [Maia XRF array](detector.md) reads the fluorescence at each point (and the area detectors read scattering / diffraction). - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Scanning X-ray fluorescence / diffraction microscopy | `scanning_fluorescence_microscopy` | the Aerotech raster fly-scan over the micro / nano focus reading the Maia array; reuses the slug 2-ID / XFM / LIX / ESRF ID16B share, a further consumer (`TECH-1`) | - -### Nano-tomography - -The NC1 nano-probe carries a Pegasus sample rotation (`samr`); rotating the sample in the nano-focused beam while reading the area detector gives nano-tomography. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Hard X-ray nano-tomography | `tomography` | the NC1 sample rotation + area detector; reuses the catalog `tomography` Method (the 2-BM / FXI / ID19 lineage), a further consumer (`TECH-1`) | - -### A dense instrument on familiar vocabulary - -P06 is the fleet's fullest scanning-probe beamline, but it coins no new vocabulary. Its techniques reuse the `scanning_fluorescence_microscopy` and `tomography` slugs already carried across the fleet, and its instrument anatomy reuses existing Families: the monochromators bind `Monochromator`, the hexapods `Hexapod`, the scan stages `LinearStage`, the Maia array `EnergyDispersiveSpectrometer`, the area detectors `Camera`. The novelty is in the density and diversity of the device tree (six controller families, two endstations, the Maia array), not in any new Family or Method. - -### Not modelled yet - -The concrete acquisition recipes (the raster fly-scan trajectories and dwell times, the Maia mapping readout, the nano-tomography rotation sequences) are not written yet; they join as the deployment approaches the point where CORA drives P06. Whether the scanning / nano-tomography Methods enter CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at P06, and the trust shape that will gate it. First cut.* - -Governance at P06 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), 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). - -P06 is CORA's third PETRA III beamline: the DESY operator pool and the safety-review structure are carried pending on the [PETRA III Site](../petra-iii/index.md#safety-and-governance), shared across the facility's beamlines (with P01 and P04), until DESY staff confirm them (`GOV-1`). P06 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives P06, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. The OnlineXML carries beamline devices, not the personnel-safety interlock leaves, so the Enclosure permit signals (across the mono hutch and the two probe endstations) and the interlock structure are carried pending and are not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -P06 also carries the hazard classes that come with a dense nano-probe endstation: hexapods, KB-lens stacks, and piezo scanners moving in close quarters inside interlocked hutches. Those land with the instruments that bring them when the deployment firms up. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives P06, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's P06 content lives, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at P06 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (KB lens fine axes) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes P06 new - -P06 is a third beamline at an existing Site, and the fleet's fullest scanning-probe instrument. It is a hard X-ray micro- and nano-probe: a focused beam rastered across a sample while a high-rate Maia XRF array and area detectors read each point, plus nano-tomography on the NC1 sample rotation. Its novelty is the density and diversity of the device tree (six motion-controller families, two endstations, the Maia array), not any new Family or Method. - -### No new families (the fullest catalog reuse yet) - -P06 coins no new Family. The Maia XRF array binds `EnergyDispersiveSpectrometer` (one Asset carrying its six sub-device handles); the hexapods (MC01 plus the two NC1 KB-lens carriers) bind `Hexapod`; the KB lens fine stages bind `PseudoAxis`; the scan, sample, pin, and nano stages bind `LinearStage`; the sample rotation binds `RotaryStage`; the monochromators bind `Monochromator`; the slits bind `Slit`; the undulator binds `InsertionDevice`; the BPMs bind `FluxMonitor`; and the area / view cameras bind `Camera`. Nothing in the catalog changes. - -### The control plane - -P06 sits on the PETRA III Tango device floor with Sardana as the scan layer, the same as P01 / P04, but with the most controller diversity yet: OMS steppers, Aerotech fly-scan controllers, SmarAct piezo / hexapod controllers, a hexapod controller, PI and SMC-Hydra fine-stage controllers, and a Pegasus rotation controller, reading the Maia array and the Eiger / Lambda / Pilatus / PCO detectors. The handles are read from P06's public OnlineXML registry and carried confirm (`CTRL-1`); several detectors report on a bare `p06` / `petra3` host (`HOST-1`). The scanning fluorescence acquisition is a continuous-motion Aerotech fly-scan coupled to the Maia readout; CORA's edge conducts that over its `ControlPort` and is barred from the deterministic real-time fly-scan loop by construction. - -### Deliberately not here yet - -- **The undulator parameters (`SRC-1`).** The OnlineXML exposes the gap / harmonic / taper, not the period; carried pending. -- **The optics physical detail (`OPT-1`).** The DCM crystal cut, the multilayer d-spacing, and the KB focal sizes are carried confirm-pending. -- **The motor-bank axis roles (`GROUP-1`).** The `mono_mot`, `mi_mot`, and `nat_mot` banks carry no per-axis role in the registry; grouped as stage Assets, roles pending. -- **The fly-scan parameters (`SCAN-1`).** The Aerotech raster trajectories and the motion-detector triggering coupling are not in the registry. -- **The detector roster (`DET-1`).** The operative detectors per experiment, the Maia element count, and the area-detector models are named, not fully bound; the Maia sub-device split is a modelling question. -- **The host mapping (`HOST-1`).** Several detectors report on a bare host; whether that is a shared Tango DB or a registry artifact is pending. -- **The handle freshness (`CTRL-1`).** The OnlineXML branch is `debian/jessie`; some handles may lag the live Tango database. -- **The scanning / nano-tomography Methods (`TECH-1`).** Whether these enter CORA's catalog is an owner decision; the Practices render unlinked, pending, reusing the existing slugs. -- **The PSS permit signals (`PSS-1`).** Not in the OnlineXML; carried pending, not invented. -- **The simulated devices and full asset-tree scenarios.** No `test_p06_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the P06 team to confirm before the model can be trusted.* - -P06 was reverse-engineered from P06's own public OnlineXML device registry ([gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p06](https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p06), branch `debian/jessie`) and a verified research brief, not from a live connection. The registry carries real Tango device names and control handles, but no focal sizes, detector models, or energy calibration. P06 is CORA's third PETRA III beamline and its fullest scanning-probe deployment. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: an optics / mono hutch feeding two scanning-probe endstations (MC01 micro, NC1 nano)? | A `p06-mono` hutch and two `p06-mc01` / `p06-nc1` endstations, read from the OnlineXML host names. | The Enclosure grouping. | -| HOST-1 | Nice-to-have | Several detectors (Lambda, the detector pool) report on a bare `p06` / `petra3` Tango host. Is that a shared detector host, or a registry artifact? | The detectors are homed in the endstation that operates them; the host is flagged. | The detector-to-host mapping. | -| GROUP-1 | Nice-to-have | The per-axis roles of the motor banks (`mono_mot`, `mi_mot01..84`, `nat_mot01..32`). | Grouped as stage Assets carrying the bank prefix; per-axis roles pending. | The sample / instrument-stage Asset boundaries. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Nice-to-have | The undulator period and parameters. | An undulator; gap / harmonic / taper read, period pending. | The source Asset detail. | -| OPT-1 | Blocks-go-live | The DCM crystal cut, the multilayer monochromator d-spacing, and the KB-lens focal sizes (horizontal and vertical). | A DCM + a multilayer `Monochromator`, two KB `Hexapod` carriers; handles read, physical detail pending. | The optics modelling. | - -### Sample endstations - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SCAN-1 | Blocks-go-live | The Aerotech fly-scan raster trajectories and the motion-detector triggering coupling (MC01 and NC1). | `LinearStage` scan stages with a continuous fly-scan role; parameters pending. | The scanning-acquisition modelling. | -| SAMPLE-1 | Nice-to-have | The NC1 SmarAct sample-piezo axes and the Pegasus sample-rotation detail (the nano-tomography axis). | A `LinearStage` piezo stack and a `RotaryStage` rotation; axis set pending. | The sample-stage modelling. | - -### The detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The detector roster per experiment, the Maia element count, and the area-detector models (Eiger / Lambda / Pilatus / PCO variants). | A Maia `EnergyDispersiveSpectrometer` (one Asset, six sub-devices), XIA fluorescence, and `Camera` area detectors; models pending. | The detector modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | The Tango device handles per P06 device, and whether the OnlineXML `debian/jessie` branch matches the live Tango database. | The handles read from the public OnlineXML, carried pending; the floor is Tango + Sardana. | Binding each Asset's control handle. | -| PSS-1 | Blocks-go-live | The DESY personnel-safety permit signals and the photon / front-end shutters (absent from the OnlineXML). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent and the cooling / beam supplies. | Photon beam, cooling water, vacuum. | The Supply observations. | -| GOV-1 | Nice-to-have | The DESY operator pool and safety-review structure (site-level). | Carried pending on the PETRA III Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Do scanning fluorescence / diffraction microscopy and nano-tomography enter CORA's catalog as Capabilities / Methods? | Deferred: carried as pending Practices reusing the `scanning_fluorescence_microscopy` and `tomography` slugs; none coined. | The technique Capabilities. | diff --git a/docs/deployments/p07/notes.md b/docs/deployments/p07/notes.md deleted file mode 100644 index a74030264a3..00000000000 --- a/docs/deployments/p07/notes.md +++ /dev/null @@ -1,138 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of P07 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../petra-iii/index.md#the-techniques-adapted-here) is how a facility adapts it. P07's diffraction and high-field techniques earn no catalog Method today, so the Methods below render unlinked and are carried pending until a technique enters scope (`TECH-1`). - -### High-energy materials-science diffraction - -P07 uses a high-energy monochromatic beam to study engineering materials (bulk diffraction, residual stress, texture, in-situ deformation), reading the diffraction on the [four-circle diffractometer](sample.md) and the [Pilatus / PerkinElmer detectors](detector.md). - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| High-energy diffraction | `diffraction` | bulk / engineering diffraction on the four-circle diffractometer + area detectors; reuses the `diffraction` slug, a further consumer (`TECH-1`) | - -### High-field materials science - -P07's EH2 endstation carries a 17 T high-field magnet for studies under applied magnetic field. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| High-field magnetic scattering | `magnetic_scattering` | scattering / diffraction in the 17 T magnet; reuses the `magnetic_scattering` slug P09 / 4-ID share, a further consumer (`TECH-1`) | - -### A high-energy materials beamline on familiar vocabulary - -P07 is the fleet's high-energy materials-science beamline. Its techniques reuse the `diffraction` and `magnetic_scattering` slugs already carried across the fleet, so none forces a new Method now. The instrument anatomy reuses existing Families: the multi-bounce mono binds `Monochromator`, the four-circle diffractometer `Goniometer`, the 17 T magnet the graduated catalog `Magnet` Family, the Linkam stage `TemperatureController`, the detectors `Camera`. The in-situ sample environment (the Linkam heating / cooling, the magnet) suits operando materials studies but coins no new Family. - -### Not modelled yet - -The concrete acquisition recipes (the diffraction / stress-mapping scans, the in-situ deformation / temperature ramps, the high-field scans) are not written yet; they join as the deployment approaches the point where CORA drives P07. Whether the diffraction Methods enter CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at P07, and the trust shape that will gate it. First cut.* - -Governance at P07 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), 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). - -P07 carries a governance wrinkle the other PETRA III beamlines do not: it is **jointly operated by Helmholtz-Zentrum Hereon (2/3) and DESY (1/3)** (`OPERATOR-1`). How that joint operation maps to CORA's Federation / Trust model (a single Site with a shared operator pool, or two Federation participants sharing a beamline) is a facility-governance question carried pending. For this first cut, P07 is modelled as a beamline on the PETRA III Site, with the Hereon stake noted on the [index](index.md) and as a question; the DESY / Hereon operator pool and safety-review structure are carried pending on the [PETRA III Site](../petra-iii/index.md#safety-and-governance) (`GOV-1`). - -P07 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives P07, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. The OnlineXML carries beamline devices, not the personnel-safety interlock leaves, so the Enclosure permit signals (across the optics and the two experiment hutches) and the interlock structure are carried pending and are not invented here (`PSS-1`). P07 also carries the hazard classes that come with its endstations: a high-energy beam, the 17 T superconducting magnet and its liquid-helium cryogen, and the Linkam furnace; those land with the instruments that bring them when the deployment firms up. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives P07, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's P07 content lives, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at P07 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes P07 new - -P07 is an eleventh beamline at an existing Site, and the facility's high-energy materials-science beamline, jointly operated by Helmholtz-Zentrum Hereon (2/3) and DESY (1/3). Its distinguishing capabilities are high-energy diffraction for engineering materials and a 17 T high-field magnet endstation. At the modelling level it is a reuse-and-reinforce deployment, plus a governance note (the joint operation). - -### No new families - -P07 coins no new Family. The multi-bounce mono binds `Monochromator`; the four-circle diffractometer `Goniometer`; the hexapod `Hexapod`; the 17 T magnet the graduated catalog `Magnet` Family (a further consumer, after 4-ID / i10-1 / ID32 / P09); the Linkam stage `TemperatureController`; the slits `Slit`; the stages `LinearStage`; the detectors `Camera` / `EnergyDispersiveSpectrometer`. Nothing in the catalog changes. - -### The control plane - -P07 sits on the PETRA III Tango device floor with Sardana as the scan layer, the same as the other PETRA III beamlines, despite the Hereon / DESY joint operation (the beamline controls are the PETRA III stack). Its distinctive devices are the multi-bounce DCM (resolved axes), the 17 T magnet, and the Linkam stage. The handles are read from P07's public OnlineXML registry and carried confirm (`CTRL-1`); only the EH2 registry slice is public. The high-energy diffraction / high-field acquisition runs as a Sardana macro; that orchestration is the seam CORA's edge replaces or drives through over its `ControlPort`. - -### Deliberately not here yet - -- **The joint-operation governance (`OPERATOR-1`).** The Hereon (2/3) + DESY (1/3) operation is a facility-governance fact carried as a question; how it maps to CORA's Federation / Trust model is pending. -- **The undulator parameters (`SRC-1`).** The gap / taper are read; the period is not exposed. -- **The optics detail (`OPT-1`).** The multi-bounce DCM crystal cut and the OH optics are carried confirm-pending. -- **The diffractometer structure (`DIFF-1`).** The four-circle count and the detector arm are pending; modelled as a `Goniometer` Asset. -- **The motor-bank axis roles (`GROUP-1`).** The `exp*` / `oh*` banks carry no per-axis role; grouped as stage Assets. -- **The magnet detail (`MAG-1`).** The 17 T field and control are pending; the Family is the graduated catalog `Magnet` (a further consumer, its per-Asset field detail pending). -- **The detector roster (`DET-1`).** The models and the EH2B detection are named, not fully bound. -- **The other hutches (`HOST-1`).** Only the EH2 slice is public; EH1 / EH3 / EH4 are noted, not modelled. -- **The handle freshness (`CTRL-1`).** The OnlineXML branch is `debian/jessie`; some handles may lag the live Tango database. -- **The diffraction Methods (`TECH-1`).** Whether they enter CORA's catalog is an owner decision; the Practices render unlinked, pending. -- **The PSS permit signals (`PSS-1`).** Not in the OnlineXML; carried pending, not invented. -- **The simulated devices and full asset-tree scenarios.** No `test_p07_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the P07 team to confirm before the model can be trusted.* - -P07 was reverse-engineered from P07's own public OnlineXML device registry ([gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p07](https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p07), branch `debian/jessie`) and a verified research brief, not from a live connection. The registry carries real Tango device names and control handles, but no crystal cuts, magnet field, or energy calibration. P07 is CORA's eleventh PETRA III beamline, jointly operated by Helmholtz-Zentrum Hereon and DESY. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: an optics hutch feeding an EH2 main and an EH2B secondary hutch, plus other hutches (EH1 / EH3 / EH4)? | A `p07-oh2` optics hutch and `p07-eh2` / `p07-eh2b` endstations, from the registry slice. | The Enclosure grouping. | -| OPERATOR-1 | Blocks-go-live | The Hereon (2/3) + DESY (1/3) joint operation: how does it map to CORA's Federation / Trust model? | A beamline on the PETRA III Site with a shared operator pool; the Hereon stake noted. | The operator / governance model. | -| HOST-1 | Nice-to-have | The other P07 hutches (EH1 / EH3 / EH4) are not in the public EH2 registry slice. Where are they? | Only EH2 / EH2B modelled; the others noted, not modelled. | The full hutch roster. | -| GROUP-1 | Nice-to-have | The per-axis roles of the motor banks (`exp*`, `oh*`). | Grouped as stage Assets carrying the bank prefix; per-axis roles pending. | The Asset boundaries. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Nice-to-have | The undulator period and parameters. | An undulator; gap / taper read, period pending. | The source Asset detail. | -| OPT-1 | Blocks-go-live | The multi-bounce DCM crystal cut and energy range, and the OH optics. | A multi-bounce `Monochromator`; physical detail pending. | The optics modelling. | - -### Sample endstations - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DIFF-1 | Blocks-build | The four-circle Eulerian diffractometer geometry and whether it composes a Diffractometer Assembly with a detector arm. | A `Goniometer` Asset (e4cv + two-theta), not the composed Diffractometer Assembly. | The diffractometer modelling. | -| MAG-1 | Blocks-go-live | The 17 T magnet field, cryogen, and control / ramp interface. | A 17 T superconducting `Magnet` (the graduated catalog Family, a further consumer); field and control pending. | The per-Asset magnet field / control detail. | -| SAMPLE-1 | Nice-to-have | The EH2 sample-hexapod geometry and the Linkam stage handles. | A `Hexapod` + a `TemperatureController`; geometry pending. | The sample modelling. | - -### The detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The detector roster per hutch, the Pilatus / PerkinElmer models (the `_old` controller suffix), and the EH2B detection. | `Camera` area detectors plus `EnergyDispersiveSpectrometer` MCAs; models pending. | The detector modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | The Tango device handles per P07 device, and whether the OnlineXML `debian/jessie` branch matches the live Tango database. | The handles read from the public OnlineXML, carried pending; the floor is Tango + Sardana. | Binding each Asset's control handle. | -| PSS-1 | Blocks-go-live | The DESY / Hereon personnel-safety permit signals and the photon / front-end shutters (absent from the OnlineXML). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent, the cooling / beam supplies, and the magnet liquid-helium supply. | Photon beam, cooling water, vacuum, and liquid helium. | The Supply observations. | -| GOV-1 | Nice-to-have | The DESY / Hereon operator pool and safety-review structure (site-level). | Carried pending on the PETRA III Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Do high-energy diffraction and high-field materials science enter CORA's catalog as Capabilities / Methods? | Deferred: carried as pending Practices reusing the `diffraction` / `magnetic_scattering` slugs; none coined. | The technique Capabilities. | diff --git a/docs/deployments/p08/notes.md b/docs/deployments/p08/notes.md deleted file mode 100644 index d5b09a20628..00000000000 --- a/docs/deployments/p08/notes.md +++ /dev/null @@ -1,124 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of P08 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../petra-iii/index.md#the-techniques-adapted-here) is how a facility adapts it. P08's diffraction technique earns no catalog Method today, so the Method below renders unlinked and is carried pending until a technique enters scope (`TECH-1`). - -### High-resolution diffraction - -P08 uses a high-resolution monochromatic beam on a six-circle [diffractometer](sample.md) to measure surface / interface diffraction, reflectivity (XRR), and high-resolution powder / single-crystal diffraction, reading the [Eiger / Pilatus / Mythen detectors](detector.md). - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| High-resolution diffraction / reflectivity | `diffraction` | surface / interface diffraction and reflectivity on the six-circle Kohzu diffractometer + area / strip detectors; reuses the `diffraction` slug P07 share, a further consumer (`TECH-1`) | - -### A diffraction beamline on familiar vocabulary - -P08 is the fleet's high-resolution diffraction beamline. Its technique reuses the `diffraction` slug already carried pending across the fleet, so it forces no new Method now. The instrument anatomy reuses existing Families: the monochromators bind `Monochromator`, the six-circle diffractometer `Goniometer`, the CRL `Transfocator`, the hexapod `Hexapod`, the detectors `Camera` / `EnergyDispersiveSpectrometer`. The rich detector set (Eiger / Pilatus / Mythen / PerkinElmer / Vortex) suits the breadth of diffraction modes but coins no new Family. - -### Not modelled yet - -The concrete acquisition recipes (the reflectivity / rocking-curve scans, the reciprocal-space mapping, the high-resolution powder collection) are not written yet; they join as the deployment approaches the point where CORA drives P08. Whether the diffraction Method enters CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at P08, and the trust shape that will gate it. First cut.* - -Governance at P08 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), 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). - -P08 is CORA's twelfth PETRA III beamline: the DESY operator pool and the safety-review structure are carried pending on the [PETRA III Site](../petra-iii/index.md#safety-and-governance), shared across the facility's beamlines, until DESY staff confirm them (`GOV-1`). P08 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives P08, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. The OnlineXML carries beamline devices, not the personnel-safety interlock leaves, so the Enclosure permit signals (across the optics and the experiment endstation) and the interlock structure are carried pending and are not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives P08, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's P08 content lives, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at P08 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes P08 new - -P08 is a twelfth beamline at an existing Site, the facility's high-resolution diffraction beamline (surface / interface diffraction, reflectivity, high-resolution powder / single-crystal). At the modelling level it is a reuse-and-reinforce deployment: nothing new at the vocabulary level, distinguished mainly by its rich detector set. - -### No new families - -P08 coins no new Family. The DCM and multilayer mono bind `Monochromator`; the CRL `Transfocator`; the absorber `Filter`; the six-circle Kohzu diffractometer `Goniometer`; the hexapod `Hexapod`; the slits `Slit`; the detectors `Camera` / `EnergyDispersiveSpectrometer`. Nothing in the catalog changes. The Mythen2 strip detector is modelled as a `Camera` for now (a fold-vs-promote question for the catalog owner, the P10 precedent). - -### The control plane - -P08 sits on the PETRA III Tango device floor with Sardana as the scan layer, the same as the other PETRA III beamlines. Its distinctive devices are the Kohzu six-circle diffractometer controller and the breadth of detectors (Eiger / Pilatus / Mythen / PerkinElmer / Vortex). The handles are read from P08's public OnlineXML registry and carried confirm (`CTRL-1`). The high-resolution diffraction acquisition runs as a Sardana macro; that orchestration is the seam CORA's edge replaces or drives through over its `ControlPort`. - -### Deliberately not here yet - -- **The undulator parameters (`SRC-1`).** The gap is read; the period is not exposed. -- **The optics detail (`OPT-1`).** The DCM / multilayer crystal cut and the CRL detail are carried confirm-pending. -- **The diffractometer structure (`DIFF-1`, `GROUP-1`).** The six-circle Kohzu geometry and the per-axis `diff*` bank roles are pending; modelled as a `Goniometer` Asset. -- **The sample hexapod geometry (`SAMPLE-1`).** Carried confirm-pending. -- **The detector roster (`DET-1`).** The models, the operative roster, and the Mythen fold-vs-promote are named, not fully bound. -- **The shared Lambda host (`HOST-1`).** A Lambda reports on the bare `petra3` host. -- **The handle freshness (`CTRL-1`).** The OnlineXML branch is `debian/jessie`; some handles may lag the live Tango database. -- **The diffraction Method (`TECH-1`).** Whether it enters CORA's catalog is an owner decision; the Practice renders unlinked, pending. -- **The PSS permit signals (`PSS-1`).** Not in the OnlineXML; carried pending, not invented. -- **The simulated devices and full asset-tree scenarios.** No `test_p08_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the P08 team to confirm before the model can be trusted.* - -P08 was reverse-engineered from P08's own public OnlineXML device registry ([gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p08](https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p08), branch `debian/jessie`) and a verified research brief, not from a live connection. The registry carries real Tango device names and control handles, but no crystal cuts or energy calibration. P08 is CORA's twelfth PETRA III beamline, the high-resolution diffraction beamline. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: an optics hutch feeding the diffractometer experiment endstation? | A `p08-oh` optics hutch and a `p08-eh` endstation. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The undulator period and parameters. | An undulator; gap read, period pending. | The source Asset detail. | -| GROUP-1 | Nice-to-have | The per-axis roles of the `diff*` Kohzu diffractometer / sample bank. | Grouped as the `Goniometer` Asset carrying the bank prefix; per-axis roles pending. | The diffractometer Asset boundaries. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| OPT-1 | Blocks-go-live | The DCM and multilayer monochromator crystal cuts / d-spacing, and the CRL detail. | A DCM + a multilayer `Monochromator` and a `Transfocator` CRL; physical detail pending. | The optics modelling. | - -### Sample endstation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DIFF-1 | Blocks-build | The six-circle Kohzu diffractometer geometry and whether it composes a Diffractometer Assembly with a detector arm. | A `Goniometer` Asset (kozhue6cctrl + diff*), not the composed Diffractometer Assembly. | The diffractometer modelling. | -| SAMPLE-1 | Nice-to-have | The sample hexapod geometry. | A `Hexapod`; geometry pending. | The sample modelling. | - -### The detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The detector roster per experiment, the models (Eiger 1M / Pilatus / Mythen2 / PerkinElmer / Vortex), and whether the Mythen strip detector warrants a distinct Family. | A `Camera` suite plus a `EnergyDispersiveSpectrometer` Vortex; the Mythen modelled as a `Camera` for now. | The detector modelling. | -| HOST-1 | Nice-to-have | A shared Lambda detector reports on the bare `petra3` host. Shared host, or registry artifact? | The Lambda is noted; the host is flagged. | The detector-to-host mapping. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | The Tango device handles per P08 device, and whether the OnlineXML `debian/jessie` branch matches the live Tango database. | The handles read from the public OnlineXML, carried pending; the floor is Tango + Sardana. | Binding each Asset's control handle. | -| PSS-1 | Blocks-go-live | The DESY personnel-safety permit signals and the photon / front-end shutters (absent from the OnlineXML). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent and the cooling / beam supplies. | Photon beam, cooling water, vacuum. | The Supply observations. | -| GOV-1 | Nice-to-have | The DESY operator pool and safety-review structure (site-level). | Carried pending on the PETRA III Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Does high-resolution diffraction enter CORA's catalog as a Capability / Method? | Deferred: carried as a pending Practice reusing the `diffraction` slug; none coined. | The technique Capability. | diff --git a/docs/deployments/p09/notes.md b/docs/deployments/p09/notes.md deleted file mode 100644 index a4c311b73ee..00000000000 --- a/docs/deployments/p09/notes.md +++ /dev/null @@ -1,139 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of P09 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../petra-iii/index.md#the-techniques-adapted-here) is how a facility adapts it. P09's resonant-scattering, magnetic-scattering, and dichroism techniques earn no catalog Method today, so the Methods below render unlinked and are carried pending until a technique enters scope (`TECH-1`). - -### Resonant elastic X-ray scattering - -P09 tunes the incident energy onto an absorption edge (the DCM) and measures the elastically scattered intensity on the six-circle [goniometer](sample.md), with the [phase retarder](sample.md) setting incident polarization and the [analyzer](sample.md) resolving the scattered polarization. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Resonant elastic X-ray scattering | `resonant_scattering` | edge-tuned elastic scattering on the six-circle diffractometer + PerkinElmer / Pilatus, with polarization analysis; reuses the `resonant_scattering` slug 4-ID / i06 / i10 share, a further consumer (`TECH-1`) | - -### Magnetic scattering and dichroism - -P09's MAG endstation applies a 14 T field to the sample and measures the magnetic scattering / dichroism, with the phase retarder switching incident polarization for XMCD. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Magnetic scattering | `magnetic_scattering` | scattering in the 14 T high-field magnet; reuses the `magnetic_scattering` slug, a further consumer (`TECH-1`) | -| X-ray magnetic circular / linear dichroism | `xmcd` | dichroism in the 14 T magnet with the phase retarder setting polarization; reuses the `xmcd` slug 4-ID / i06 / i10 share, a further consumer (`TECH-1`) | - -### A polarization / magnetism beamline on the 4-ID vocabulary - -P09 is the fleet's resonant-scattering and high-field-magnetism beamline. Its techniques are new to CORA's catalog (no resonant / magnetic Method is earned yet), but they reuse the slugs the APS 4-ID deployment and the Diamond i06 / i10 beamlines already carry pending, so none forces a new Method now. Crucially, the instrument anatomy reuses the polarization / magnetism Families 4-ID introduced: the phase retarder binds the catalog `PhaseRetarder` and the analyzer the catalog `PolarizationAnalyzer` (graduated across 4-ID / i10 / ID32 / P09, presenting Positioner), while the 14 T magnet binds the graduated catalog `Magnet` (earned across 4-ID + i10-1 + ID32), a further consumer. For `PhaseRetarder`, P09 was the rule-of-three signal (with P22) that earned it into the catalog. All recorded on [Model](#model). - -### Not modelled yet - -The concrete acquisition recipes (the energy / diffractometer / field scan sequences, the polarization-switching dichroism loops) are not written yet; they join as the deployment approaches the point where CORA drives P09. Whether the resonant / magnetic Methods enter CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at P09, and the trust shape that will gate it. First cut.* - -Governance at P09 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), 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). - -P09 is CORA's seventh PETRA III beamline: the DESY operator pool and the safety-review structure are carried pending on the [PETRA III Site](../petra-iii/index.md#safety-and-governance), shared across the facility's beamlines, until DESY staff confirm them (`GOV-1`). P09 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives P09, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. The OnlineXML carries beamline devices, not the personnel-safety interlock leaves, so the Enclosure permit signals (across the three areas) and the interlock structure are carried pending and are not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -P09 also carries the hazard classes that come with a high-field magnetism endstation: a 14 T superconducting magnet and its liquid-helium cryogen, a stored-energy and field hazard that gates access to the MAG endstation. Those land with the instruments that bring them when the deployment firms up; the magnet is modelled as a sample-environment `Magnet` Asset, not a beam-steering device CORA drives. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives P09, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's P09 content lives, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at P09 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes P09 new - -P09 is a seventh beamline at an existing Site, and the richest of the PETRA III set in technique breadth: resonant elastic X-ray scattering and HAXPES (MONO), diffraction (DIF), and high-field magnetism / XMCD (MAG, a 14 T magnet). At the modelling level it is the **second consumer of the polarization / magnetism vocabulary** the APS 4-ID deployment introduced: the phase retarder, the polarization analyzer, and the high-field magnet. - -### No new families (the 4-ID vocabulary ports cleanly) - -P09 coins no new Family. It binds the catalog `PhaseRetarder` Family (P09 was the second consumer, the rule-of-three signal with P22 that earned it into the catalog) and the graduated catalog `PolarizationAnalyzer` Family (earned across 4-ID / i10 / ID32 / P09, presenting Positioner) for its analyzer. Its 14 T magnet binds the graduated catalog `Magnet` Family (earned across 4-ID + i10-1 + ID32; presents `Regulator`), a further consumer. The diffractometers bind the catalog `Goniometer` Family (not the composed `Diffractometer` Assembly, the same call as P01 EH2); the optics bind `Monochromator` / `Mirror` / `Transfocator` / `Slit` / `Filter`; the sample environment binds `TemperatureController` / `Hexapod` / `LinearStage`; the detectors bind `Camera` / `EnergyDispersiveSpectrometer`. Nothing in the catalog changes. - -### The control plane - -P09 sits on the PETRA III Tango device floor with Sardana as the scan layer, the same as the other PETRA III beamlines. Its instrument diversity is high (OMS / VME58 steppers, Galil slits, PI + AttoCube piezos, a hexapod; PerkinElmer / Pilatus / Andor detectors, the SIS3302 digitizer, GPIB instruments). The handles are read from P09's public OnlineXML registry and carried confirm (`CTRL-1`). The resonant-scattering / magnetism acquisition (the energy / diffractometer / field scan with polarization switching) runs as a Sardana macro; that orchestration is the seam CORA's edge replaces or drives through over its `ControlPort`, the same shape as the 4-ID seam. - -### Deliberately not here yet - -- **The undulator parameters (`SRC-1`).** The OnlineXML exposes the gap, not the period; carried pending. -- **The optics detail (`OPT-1`).** The DCM crystal cut, the mirror coatings, and the CRL detail are carried confirm-pending. -- **The diffractometer structure (`DIFF-1`).** The MONO / DIF / MAG six-circle counts and detector arms are pending; modelled as `Goniometer` Assets, not `Diffractometer` Assemblies. -- **The motor-bank axis roles (`GROUP-1`).** The MONO / DIF `p09/motor` banks carry no per-axis role; grouped as stage Assets. -- **The polarization / magnet detail (`POL-1`, `MAG-1`).** The phase-retarder / analyzer geometry and the 14 T magnet field / control are pending; the polarization Families are the graduated catalog `PhaseRetarder` / `PolarizationAnalyzer`, and the magnet binds the graduated catalog `Magnet` Family (its per-Asset field / control detail pending). -- **The detector roster (`DET-1`).** The detector models and the SIS3302 channel count (collapsed from the registry's ROI explosion) are named, not fully bound. -- **The host mapping (`HOST-1`).** A shared Lambda reports on the bare `petra3` host; a stray `p07/hexapodsmall` row (a P07 device) is excluded from P09. -- **The handle freshness (`CTRL-1`).** The OnlineXML branch is `debian/jessie`; some handles may lag the live Tango database. -- **The resonant / magnetic Methods (`TECH-1`).** Whether they enter CORA's catalog is an owner decision; the Practices render unlinked, pending, reusing the existing slugs. -- **The PSS permit signals (`PSS-1`).** Not in the OnlineXML; carried pending, not invented. -- **The simulated devices and full asset-tree scenarios.** No `test_p09_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the P09 team to confirm before the model can be trusted.* - -P09 was reverse-engineered from P09's own public OnlineXML device registry ([gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p09](https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p09), branch `debian/jessie`) and a verified research brief, not from a live connection. The registry carries real Tango device names and control handles, but no crystal cuts, magnet field, or energy calibration. P09 is CORA's seventh PETRA III beamline and the second consumer of the 4-ID polarization / magnetism vocabulary. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: a MONO optics-and-resonant-scattering hutch, a DIF diffraction hutch, and a MAG magnetism endstation? | A `p09-mono` hutch and `p09-dif` / `p09-mag` endstations, read from the OnlineXML host names. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The undulator period and parameters. | An undulator; gap read, period pending. | The source Asset detail. | -| GROUP-1 | Nice-to-have | The per-axis roles of the MONO / DIF motor banks (`p09/motor/exp`, `p09/motor/dif`). | Grouped as stage Assets carrying the bank prefix; per-axis roles pending. | The Asset boundaries. | -| HOST-1 | Nice-to-have | A shared Lambda detector reports on the bare `petra3` host, and the registry includes a `p07/hexapodsmall` row. Shared host / cross-beamline import? | The Lambda is noted unbound; the P07 device is excluded from P09. | The device-to-host mapping. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| OPT-1 | Blocks-go-live | The DCM crystal cut, the mirror coatings, the CRL detail, and the absorber configuration. | A DCM `Monochromator`, two `Mirror`s, a `Transfocator` CRL, and `Filter` absorbers; physical detail pending. | The optics modelling. | - -### Sample endstations - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DIFF-1 | Blocks-build | The diffractometer circle counts (MONO / DIF / MAG) and whether each composes a Diffractometer Assembly with a detector arm. | A `Goniometer` Asset per area (six-circle E6C), not the composed Diffractometer Assembly, until detector arms are confirmed. | The diffractometer modelling. | -| POL-1 | Nice-to-have | The phase-retarder geometry (circles + AttoCube fine axes) and the polarization-analyzer detail. | The catalog `PhaseRetarder` Family and the catalog `PolarizationAnalyzer` Family (graduated across 4-ID / i10 / ID32 / P09); detail pending. | The polarization-instrument modelling. | -| MAG-1 | Blocks-go-live | The MAG magnet field (14 T assumed), its cryogen, and its control / ramp interface. | A 14 T superconducting `Magnet` (the graduated catalog Family, a further consumer); field and control pending. | The per-Asset magnet field / control detail. | -| SAMPLE-1 | Nice-to-have | The MAG sample-hexapod and PI-piezo geometry. | A `Hexapod` + `LinearStage` piezos; geometry pending. | The MAG sample modelling. | -| TEMP-1 | Nice-to-have | The CryoCon / Lakeshore / LSCI sensor / setpoint handles. | `TemperatureController` controllers; cryogenic cooling. | The temperature-control modelling. | - -### The detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The detector roster per area, the PerkinElmer / Pilatus / Andor models, and the SIS3302 fluorescence channel count (collapsed from the registry's ROI explosion). | `Camera` area detectors plus an `EnergyDispersiveSpectrometer` SIS3302 / MCA; models pending. | The detector modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | The Tango device handles per P09 device, and whether the OnlineXML `debian/jessie` branch matches the live Tango database. | The handles read from the public OnlineXML, carried pending; the floor is Tango + Sardana. | Binding each Asset's control handle. | -| PSS-1 | Blocks-go-live | The DESY personnel-safety permit signals and the photon / front-end shutters (absent from the OnlineXML). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent, the cooling / beam supplies, and the magnet liquid-helium supply. | Photon beam, cooling water, vacuum, and liquid helium. | The Supply observations. | -| GOV-1 | Nice-to-have | The DESY operator pool and safety-review structure (site-level). | Carried pending on the PETRA III Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Do resonant scattering, magnetic scattering, and XMCD enter CORA's catalog as Capabilities / Methods? | Deferred: carried as pending Practices reusing the `resonant_scattering` / `magnetic_scattering` / `xmcd` slugs 4-ID / i06 / i10 share; none coined. | The technique Capabilities. | diff --git a/docs/deployments/p10/notes.md b/docs/deployments/p10/notes.md deleted file mode 100644 index 1bca388a691..00000000000 --- a/docs/deployments/p10/notes.md +++ /dev/null @@ -1,135 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of P10 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../petra-iii/index.md#the-techniques-adapted-here) is how a facility adapts it. P10's primary technique, XPCS, is a graduated catalog Method (earned at the APS 8-ID), so its practice binds it directly; the coherent-imaging techniques reuse pending slugs (`TECH-1`). - -### X-ray photon correlation spectroscopy - -P10 illuminates the sample with a coherent beam and reads the speckle pattern on a high-frame-rate area detector (Lambda / Eiger); the intensity autocorrelation over time measures the sample dynamics. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| X-ray photon correlation spectroscopy (XPCS) | [`xpcs`](../../catalog/methods.md) | the coherent beam on the sample read by the high-frame-rate Lambda / Eiger, the correlation computed downstream; binds the graduated `xpcs` Method (earned at APS 8-ID), the second consumer | - -### Coherent diffraction imaging - -P10's E1 endstation focuses the coherent beam (the CRL) and records coherent diffraction patterns (the Quadro / Eiger) for ptychographic / coherent-diffraction reconstruction. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Coherent diffraction imaging / ptychography | `ptychography` | the focused coherent beam scanned across the sample, the diffraction recorded for phase retrieval; reuses the pending `ptychography` slug, a further consumer (`TECH-1`) | - -### A graduated Method meets a new facility - -P10 is a further XPCS beamline (after APS 8-ID and NSLS-II CHX). Unlike the other PETRA III beamlines (whose techniques are not yet earned and carry pending practices), P10's XPCS practice binds the graduated `xpcs` Method directly, reusing the abstraction the APS 8-ID deployment forced into the catalog. This is the reuse-earns-the-abstraction principle working as intended: a technique graduated at one facility carries cleanly to another on a different control plane. The coherent-imaging side reuses the pending `ptychography` slug; the instrument anatomy reuses existing Families (the CRL `Transfocator`, the hexapod `Hexapod`, the detector suite `Camera`). - -### Not modelled yet - -The concrete acquisition recipes (the XPCS multi-tau / correlation sequences, the ptychographic scan trajectories, the coherent-diffraction exposures) are not written yet; they join as the deployment approaches the point where CORA drives P10. Whether `ptychography` enters CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at P10, and the trust shape that will gate it. First cut.* - -Governance at P10 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), 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). - -P10 is CORA's sixth PETRA III beamline: the DESY operator pool and the safety-review structure are carried pending on the [PETRA III Site](../petra-iii/index.md#safety-and-governance), shared across the facility's beamlines, until DESY staff confirm them (`GOV-1`). P10 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives P10, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. The OnlineXML carries beamline devices, including the P10 beam shutter, but not the personnel-safety interlock leaves, so the Enclosure permit signals (across the optics and the three experiment areas) and the interlock structure are carried pending and are not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives P10, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's P10 content lives, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at P10 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (coupled axes) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes P10 new - -P10 is a sixth beamline at an existing Site, and a further XPCS beamline after the APS 8-ID and NSLS-II CHX exercises. Its science is coherent hard X-ray applications: XPCS, coherent diffraction imaging / ptychography, and coherent-beam diffraction, across three experiment areas. Its modelling first is the practice binding: P10's XPCS practice binds the **graduated** catalog `xpcs` Method directly, the first PETRA III practice whose Method is already earned (the others all carry pending practices). This is the reuse-earns-the-abstraction principle in action: a technique graduated at one facility (8-ID, EPICS) carries cleanly to another (PETRA III, Tango) without re-coining. - -### No new families - -P10 coins no new Family. The undulator binds `InsertionDevice`; the mono `Monochromator`; the CRL `Transfocator`; the hexapod `Hexapod`; the slits `Slit`; the mirrors `Mirror`; the two-theta arm `RotaryStage`; the sample / optics / nano stages `LinearStage`; the coupled axes `PseudoAxis`; the beam shutter `Shutter`; the wide detector suite `Camera`; the fluorescence detectors `EnergyDispersiveSpectrometer`; the LAB simulated diffractometer `Goniometer`. Nothing in the catalog changes. The Mythen strip detector is modelled as a `Camera` for now (a fold-vs-promote question deferred to the catalog owner, `DET-1`). - -### The control plane - -P10 sits on the PETRA III Tango device floor with Sardana as the scan layer, the same as the other PETRA III beamlines, with the widest controller and detector diversity in the set (OMS, Galil DMC, SmarAct, AttoCube, hexapod, spk; Pilatus / Eiger / Lambda / PCO / Andor / Mythen / Quadro / Lima). The handles are read from P10's public OnlineXML registry and carried confirm (`CTRL-1`); the Lambda and Lima cameras report on a bare `p10` host (`HOST-1`). The XPCS acquisition (the coherent beam read by the high-frame-rate detector, the correlation computed downstream) runs as a Sardana macro; that orchestration is the seam CORA's edge replaces or drives through over its `ControlPort`, and the correlation compute is `ComputePort` work, the same shape as the 8-ID XPCS seam. - -### Deliberately not here yet - -- **The undulator parameters (`SRC-1`).** The OnlineXML exposes the gap, not the period; carried pending. -- **The optics detail (`OPT-1`).** The DCM crystal cut, the optics-bank breakdown, the CRL focal sizes, and the mirror coatings are carried confirm-pending. -- **The motor-bank axis roles (`GROUP-1`).** The `OPT_MOT`, `E1_MOT`, `E2_MOT` banks carry no per-axis role; grouped as stage Assets. -- **The E2 / LCX sample detail (`SAMPLE-1`, `LCX-1`).** The sample-piezo / two-theta geometry and the LCX sub-station role are pending. -- **The LAB status (`LAB-1`).** The LAB devices are simulation / test units; whether they are modelled as a live offline endstation or excluded is pending. -- **The detector roster (`DET-1`).** The XPCS-detector assignment (Lambda vs Eiger), the detector models, and the Mythen fold-vs-promote are named, not fully bound. -- **The host mapping (`HOST-1`).** The Lambda / Lima cameras report on a bare host; whether shared Tango DB or registry artifact is pending. -- **The handle freshness (`CTRL-1`).** The OnlineXML branch is `debian/jessie`; some handles may lag the live Tango database. -- **`ptychography` Method (`TECH-1`).** Whether coherent imaging enters CORA's catalog is an owner decision; the practice renders unlinked, pending. (XPCS already binds the graduated Method.) -- **The PSS permit signals (`PSS-1`).** The beam shutter is read but the permit leaves are not; carried pending, not invented. -- **The simulated devices and full asset-tree scenarios.** No `test_p10_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the P10 team to confirm before the model can be trusted.* - -P10 was reverse-engineered from P10's own public OnlineXML device registry ([gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p10](https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p10), branch `debian/jessie`) and a verified research brief, not from a live connection. The registry carries real Tango device names and control handles, but no coherence lengths, energy calibration, or physical positions. P10 is CORA's sixth PETRA III beamline and a further XPCS beamline (after APS 8-ID and NSLS-II CHX). Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: an optics hutch feeding three experiment areas (E1 coherent imaging, E2 XPCS / diffraction, LAB)? | A `p10-opt` hutch and three `p10-e1` / `p10-e2` / `p10-lab` areas. | The Enclosure grouping. | -| LCX-1 | Nice-to-have | The LCX piezo sub-station: is it a distinct enclosure or a sample sub-stage within E2? | Modelled as a nano-positioning stage within the E2 enclosure. | The LCX placement. | -| LAB-1 | Nice-to-have | The LAB area: is the simulated diffractometer a live offline endstation, or test-only (to exclude)? | Modelled as an offline `Goniometer` + detectors. | The LAB scope. | -| GROUP-1 | Nice-to-have | The per-axis roles of the motor banks (`OPT_MOT`, `E1_MOT01..97`, `E2_MOT01..96`). | Grouped as stage Assets carrying the bank prefix; per-axis roles pending. | The Asset boundaries. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Nice-to-have | The undulator period and parameters. | An undulator; gap read, period pending. | The source Asset detail. | -| OPT-1 | Blocks-go-live | The DCM crystal cut, the optics-bank breakdown (mirrors / slits / lenses), and the CRL focal sizes. | A DCM `Monochromator`, grouped optics stages, and an E1 CRL `Transfocator`; physical detail pending. | The optics modelling. | - -### Sample endstations - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SAMPLE-1 | Nice-to-have | The E2 sample-piezo / two-theta geometry and the LCX nano-positioner detail. | SmarAct / AttoCube `LinearStage` piezos and a `RotaryStage` two-theta arm; geometry pending. | The E2 / LCX sample modelling. | - -### The detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The detector roster per experiment, the high-frame-rate XPCS-detector assignment (Lambda vs Eiger), the detector models, and whether the Mythen strip detector warrants a distinct Family. | A wide `Camera` suite plus `EnergyDispersiveSpectrometer` MCAs; the Mythen modelled as a `Camera` for now. | The detector modelling. | -| HOST-1 | Nice-to-have | The Lambda and Lima cameras report on the bare `p10` host. Shared detector host, or registry artifact? | The cameras are homed in E2 (the XPCS detection stage); the host is flagged. | The detector-to-host mapping. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | The Tango device handles per P10 device, and whether the OnlineXML `debian/jessie` branch matches the live Tango database. | The handles read from the public OnlineXML, carried pending; the floor is Tango + Sardana. | Binding each Asset's control handle. | -| PSS-1 | Blocks-go-live | The DESY personnel-safety permit signals, and the role of the P10 beam shutter (read from the registry, safety role not). | Permit leaves to be named; the beam shutter bound to `Shutter`, safety role pending. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent and the cooling / beam supplies. | Photon beam, cooling water, vacuum. | The Supply observations. | -| GOV-1 | Nice-to-have | The DESY operator pool and safety-review structure (site-level). | Carried pending on the PETRA III Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Does coherent diffraction imaging / ptychography enter CORA's catalog as a Method? (XPCS already binds the graduated `xpcs` Method.) | Deferred: the coherent-imaging practice reuses the pending `ptychography` slug; XPCS is already earned. | The ptychography Capability. | diff --git a/docs/deployments/p11/notes.md b/docs/deployments/p11/notes.md deleted file mode 100644 index f229775a940..00000000000 --- a/docs/deployments/p11/notes.md +++ /dev/null @@ -1,138 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of P11 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../petra-iii/index.md#the-techniques-adapted-here) is how a facility adapts it. P11 runs macromolecular crystallography and bio-imaging, reusing Methods the fleet already carries pending, so the Methods below render unlinked until a technique enters scope (`TECH-1`). - -### Macromolecular crystallography - -P11 mounts a crystal on the goniometer (with cryostream cooling), rotates it through an oscillation, and reads frames on the [Pilatus area detector](detector.md). It is a high-throughput rotation-MX beamline. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Rotation MX data collection | `mx_data_collection` | oscillation collection on the goniometer reading the Pilatus, with cryostream cooling; reuses the i03 Method (also at FMX / AMX / MX3 / MANACA / TPS), a further consumer (`TECH-1`) | - -### Bio-imaging - -P11 also runs coherent / full-field bio-imaging on the experiment-hutch stages reading the area detector. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Bio-imaging | `tomography` | full-field / coherent imaging on the experiment-hutch stages + Pilatus; reuses the catalog `tomography` Method (the 2-BM / FXI lineage), a further consumer (`TECH-1`) | - -### A familiar beamline on familiar vocabulary - -P11 is the fleet's fourth-plus macromolecular-crystallography beamline and PETRA III's first. It ties into the MX lineage CORA already models: the same goniometer / detector / cryostream anatomy, driven here through the PETRA III Tango / Sardana floor. It reuses the `mx_data_collection` Method directly (carried pending across the MX fleet), and the bio-imaging reuses `tomography`; neither forces a new device Family. The automated sample changer, if present, would be a Procedure, not a new device (the i03 / MX3 / MANACA `ROBOT-1` precedent). - -### Not modelled yet - -The concrete acquisition recipes (the oscillation sequences and their exposures, the bio-imaging scans, the sample-changer custody loop) are not written yet; they join as the deployment approaches the point where CORA drives P11. Whether the MX Methods enter CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at P11, and the trust shape that will gate it. First cut.* - -Governance at P11 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), 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). - -P11 is CORA's fourth PETRA III beamline: the DESY operator pool and the safety-review structure are carried pending on the [PETRA III Site](../petra-iii/index.md#safety-and-governance), shared across the facility's beamlines (with P01, P04, P06), until DESY staff confirm them (`GOV-1`). P11 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives P11, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. The OnlineXML carries beamline devices, not the personnel-safety interlock leaves, so the Enclosure permit signals and the interlock structure are carried pending and are not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -P11 also carries the hazard classes that come with an MX endstation: a cryostream and its liquid-nitrogen supply, and (if present) an automated sample changer moving in the experiment hutch. Those land with the instruments that bring them; the sample-changer custody loop, if modelled, would be a Procedure with a Subject thread (`ROBOT-1`), not an Asset CORA drives for safety. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives P11, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's P11 content lives, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at P11 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes P11 new - -P11 is a fourth beamline at an existing Site, and PETRA III's first macromolecular-crystallography beamline. Its science is high-throughput rotation MX (a crystal on a goniometer, cryostream-cooled, read by a Pilatus) plus coherent / full-field bio-imaging. At the modelling level it is a reuse-and-reinforce deployment: nothing new at the vocabulary level. - -### No new families (the MX spine reuses the i03 precedent) - -P11 coins no new Family. The cryostream binds the graduated `TemperatureController`; the area detector binds `Camera`; the fluorescence detector binds `EnergyDispersiveSpectrometer`; the optics and experiment-hutch motions bind `LinearStage`. Nothing in the catalog changes. The MX technique reuses the pending i03 `mx_data_collection` Method (as MANACA and TPS 07A do), and the bio-imaging reuses `tomography`. - -### The honest limitation: a sparse registry - -Unlike P01 (named monochromators, KB mirrors) and P06 (named hexapods, Maia), the P11 OnlineXML does not label its goniometer or MX instruments: most of its devices are area-grouped motor banks (`oh_mot*`, `eh1/eh2/eh3_mot*`, the piezo bank). So this cut models the experiment hutch as grouped positioning stages with the MX instrument structure carried as a question (`MX-1`), rather than inventing a goniometer the registry does not name. This is the same posture the thinner reverse-engineered scaffolds take (FAXTOR's no-manifest, TPS 05A's inferred namespace): model what the source supports, flag the rest. - -### The control plane - -P11 sits on the PETRA III Tango device floor with Sardana as the scan layer, the same as the other PETRA III beamlines, with the whole beamline on one Tango host (`haspp11oh`). The handles are read from P11's public OnlineXML registry and carried confirm (`CTRL-1`). The rotation-MX acquisition (the goniometer oscillation coupled to the Pilatus) runs as a Sardana macro; that orchestration is the seam CORA's edge replaces or drives through over its `ControlPort`, the same shape as the MX cluster seams at i03 / MANACA / TPS 07A. - -### Deliberately not here yet - -- **The source (`SRC-1`).** The OnlineXML exposes no undulator device; the source is carried pending. -- **The optics breakdown (`OPT-1`).** The monochromator, mirrors, and slits are not individually labelled; the oh bank is grouped. -- **The goniometer / MX structure (`MX-1`).** The registry does not name the goniometer; the eh banks are grouped, the MX instrument carried as a question. -- **The motor-bank axis roles (`GROUP-1`).** The banks carry no per-axis role; grouped as stage Assets. -- **The sample changer (`ROBOT-1`).** Not in the registry; would be a deferred sample-exchange Procedure, not a device. -- **The detector model (`DET-1`).** The Pilatus variant and the geometry are named, not bound. -- **The handle freshness (`CTRL-1`).** The OnlineXML branch is `debian/jessie`; some handles may lag the live Tango database. -- **The MX Methods (`TECH-1`).** Whether MX and bio-imaging enter CORA's catalog is an owner decision; the Practices render unlinked, pending, reusing the existing slugs. -- **The PSS permit signals (`PSS-1`).** Not in the OnlineXML; carried pending, not invented. -- **The simulated devices and full asset-tree scenarios.** No `test_p11_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the P11 team to confirm before the model can be trusted.* - -P11 was reverse-engineered from P11's own public OnlineXML device registry ([gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p11](https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p11), branch `debian/jessie`) and a verified research brief, not from a live connection. The P11 registry is sparser in labelling than the other PETRA III beamlines: most devices are area-grouped motor banks whose per-axis roles are not exposed, so the goniometer and MX instruments are not individually resolvable. P11 is CORA's fourth PETRA III beamline and its first macromolecular-crystallography beamline. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: an optics hutch and an experiment hutch? The registry exposes one Tango host (`haspp11oh`), so the split is inferred from device-name prefixes. | A `p11-oh` optics hutch and a `p11-eh` experiment hutch. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The undulator source (the OnlineXML exposes no undulator device). | An undulator beamline; the source carried pending. | The source Asset. | -| GROUP-1 | Nice-to-have | The per-axis roles of the motor banks (`oh_mot*`, `granite_mot*`, `eh1/eh2/eh3_mot*`, the piezo bank). | Grouped as area positioning stages carrying the bank prefix; per-axis roles pending. | The Asset boundaries. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| OPT-1 | Blocks-go-live | The optics breakdown: the monochromator, mirrors, and slits within the oh / granite banks. | Grouped `LinearStage` optics stages; the breakdown pending. | The optics modelling. | - -### Sample endstation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MX-1 | Blocks-build | The goniometer geometry and the MX instrument structure within the eh1 / eh2 / eh3 banks (the registry does not label them). | Grouped `LinearStage` experiment-hutch stages; the goniometer carried as a question. | The MX instrument modelling. | -| TEMP-1 | Nice-to-have | The cryostream sensor / setpoint handles. | An Oxford Cryostream 700 bound to `TemperatureController`. | The temperature-control modelling. | -| ROBOT-1 | Blocks-go-live | The automated sample changer (load / centre / collect / unmount loop), if present. | A deferred sample-exchange Procedure over the spine + a Subject custody thread, not a device family; not in the registry. | The sample-exchange modelling. | - -### The detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The Pilatus detector variant (300k / 1M / 2M / 6M), the sample-to-detector geometry, and the XIA fluorescence detector channel count. | A `Camera` Pilatus plus an `EnergyDispersiveSpectrometer` XIA detector; model pending. | The detector modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | The Tango device handles per P11 device, and whether the OnlineXML `debian/jessie` branch matches the live Tango database. | The handles read from the public OnlineXML, carried pending; the floor is Tango + Sardana. | Binding each Asset's control handle. | -| PSS-1 | Blocks-go-live | The DESY personnel-safety permit signals and the photon / front-end shutters (absent from the OnlineXML). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent and the cryostream liquid-nitrogen / beam supplies. | Photon beam, cooling water, vacuum, and liquid nitrogen. | The Supply observations. | -| GOV-1 | Nice-to-have | The DESY operator pool and safety-review structure (site-level). | Carried pending on the PETRA III Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Do rotation MX and bio-imaging enter CORA's catalog as Capabilities / Methods? | Deferred: carried as pending Practices reusing the i03 `mx_data_collection` and the `tomography` slugs; none coined. | The technique Capabilities. | diff --git a/docs/deployments/p13/notes.md b/docs/deployments/p13/notes.md deleted file mode 100644 index 666fb80b52c..00000000000 --- a/docs/deployments/p13/notes.md +++ /dev/null @@ -1,140 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of P13 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../petra-iii/index.md#the-techniques-adapted-here) is how a facility adapts it. P13 runs macromolecular crystallography, reusing a Method the fleet already carries pending, so the Method below renders unlinked until a technique enters scope (`TECH-1`). - -### Macromolecular crystallography - -P13 mounts a crystal on the EMBLMiniDiff microdiffractometer (with cryostream cooling), rotates it through an oscillation, and reads frames on the [Eiger or Pilatus area detector](detector.md). It is a high-throughput rotation-MX beamline, with an XRF detector for anomalous-edge identification. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Rotation MX data collection | `mx_data_collection` | oscillation collection on the EMBLMiniDiff reading the Eiger / Pilatus, with cryostream cooling; reuses the i03 Method (also at FMX / AMX / MX3 / MANACA / TPS / P11), a further consumer (`TECH-1`) | - -### A familiar beamline on an unfamiliar floor - -P13 is the fleet's seventh macromolecular-crystallography beamline and CORA's first at EMBL Hamburg. It ties into the MX lineage CORA already models: the same goniometer / detector / cryostream anatomy. What is new is not the technique but the floor it runs on: where P11 drives MX through the DESY Tango / Sardana stack, P13 drives it through EMBL's MXCuBE over Exporter + TINE (`SEAM-1`). It reuses the `mx_data_collection` Method directly (carried pending across the MX fleet); it forces no new device Family. The automated sample changer is a Procedure, not a new device (the i03 / MX3 / MANACA `ROBOT-1` precedent). - -### Not modelled yet - -The concrete acquisition recipes (the oscillation sequences and their exposures, the anomalous-edge scans, the sample-changer custody loop) are not written yet; they join as the deployment approaches the point where CORA drives P13. Whether the MX Method enters CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at P13, and the trust shape that will gate it. First cut.* - -Governance at P13 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), 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). - -P13 is CORA's first EMBL Hamburg beamline, and the first **sub-operator** on the PETRA III Site: the beamline shares the ring and Facility with the DESY beamlines but is operated by EMBL Hamburg, with its own staff and its own MXCuBE control domain. The EMBL Hamburg operator pool and safety-review structure are carried pending on the [PETRA III Site](../petra-iii/index.md#safety-and-governance), distinct from the DESY pool that P01 / P06 / P11 share, until EMBL staff confirm them (`GOV-1`). P13 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives P13, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. The MXCuBE config carries beamline devices, not the personnel-safety interlock leaves, so the Enclosure permit signals and the interlock structure are carried pending and are not invented here (`PSS-1`). The interlock at P13 is operated by DESY (the ring host) even where EMBL operates the beamline, so the boundary between the DESY-issued site clearance and the EMBL-operated experiment is itself a question (`GOV-1`). What is already settled is the shape: clearances (the safety forms that must be active to start) are issued at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -P13 also carries the hazard classes that come with an MX endstation: a cryostream and its liquid-nitrogen supply, and an automated sample changer moving in the experiment hutch. Those land with the instruments that bring them; the sample-changer custody loop, if modelled, would be a Procedure with a Subject thread (`ROBOT-1`), not an Asset CORA drives for safety. - -The concrete Zone, Conduit, and Policy instances, and the EMBL operator pool, land when the deployment approaches the point where CORA drives P13, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's P13 content lives, the sub-operator seam it exercises, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at P13 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes P13 new - -P13 is CORA's first EMBL Hamburg beamline, and the first **sub-operator** at an existing Site: it sits on the PETRA III ring but is operated by EMBL Hamburg, not DESY, with its own control domain. Its science is rotation MX (a crystal on the EMBLMiniDiff, cryo-cooled, read by an Eiger or Pilatus). At the vocabulary level it is a reuse-and-reinforce deployment; the new thing it exercises is the **sub-operator seam**, not a new device or technique. - -### The sub-operator seam (the new modelling exercise) - -The PETRA III Site already carries the DESY house style (Tango / Sardana / OnlineXML). P13 adds a distinct control-domain *within* the same Site and Facility: EMBL Hamburg runs MXCuBE over the Exporter protocol (the microdiff host) and TINE channels. This is recorded as an EMBL-Hamburg house-style section on the [PETRA III Site](../petra-iii/index.md) descriptor, so the Site now documents two operators with two control floors on one ring (`SEAM-1`). It is the first time CORA models operator and control-floor heterogeneity below the Site boundary; the [seam model](../../architecture/index.md) treats the floor (EPICS / Tango / MXCuBE+Exporter+TINE) as the wall CORA's edge conducts over, never owns. - -### No new families (the MX spine reuses the i03 precedent) - -P13 coins no new Family. The EMBLMiniDiff binds the graduated `Goniometer`; the area detectors bind `Camera`; the XRF detector binds `EnergyDispersiveSpectrometer`; the aperture / beamstop / objective bind `Aperture` / `BeamStop` / `Objective`; the sample illumination binds the catalog `Backlight` (graduated across the MX / imaging fleet); the optics motions bind `LinearStage`, the energy and detector distance `PseudoAxis`. Nothing in the catalog changes. The MX technique reuses the pending i03 `mx_data_collection` Method (as MANACA, TPS 07A, and P11 do). - -### The gain over P11: a config that names the instrument - -Unlike P11's OnlineXML (area-grouped motor banks, no named goniometer), EMBL's MXCuBE config names the EMBLMiniDiff and its omega / kappa / sample-centring axes, the aperture, the beamstop, the detectors by model. So P13's experiment hutch resolves into a real `Goniometer` instrument rather than grouped stages. This is the same "model what the source supports" posture P11 takes, but the richer source supports more: the limitation moves from "what is the instrument" to "what are its exact geometry and ranges" (`MX-1`). - -### The control plane - -P13 sits on EMBL Hamburg's MXCuBE + Exporter + TINE domain, distinct from the DESY Tango / Sardana floor, with the diffractometer motions Exporter-hosted (`p13md201.embl-hamburg.de:9001`) and the detector / energy / beam services on TINE (`/P13/...`). The handles are read from EMBL's public MXCuBE config and carried confirm (`CTRL-1`). The rotation-MX acquisition (the goniometer oscillation coupled to the Eiger) runs as an MXCuBE data-collection routine; that orchestration is the seam CORA's edge replaces or drives through over its `ControlPort`, the same shape as the MX cluster seams at i03 / MANACA / TPS 07A. - -### Deliberately not here yet - -- **The source (`SRC-1`).** The MXCuBE config exposes the energy service, not the undulator device; the source is carried pending. -- **The optics breakdown (`OPT-1`, `ENERGY-1`).** The monochromator and KB mirror Assets are not individually labelled; the motions are grouped, the energy carried as a pseudo-axis. -- **The goniometer geometry (`MX-1`).** The EMBLMiniDiff is named and bound to `Goniometer`, but its kappa range and axis offsets are not in the config. -- **The cryostream (`CRYO-1`).** Not a labelled device in the config; carried as a question, with the liquid nitrogen a Supply. -- **The sample changer (`ROBOT-1`).** MXCuBE bookkeeping, not a device; a deferred sample-exchange Procedure. -- **The detector model detail (`DET-1`).** The Eiger 16M and Pilatus 6M are named; the ROI modes and geometry are pending. -- **The on-axis camera handle (`OAV-1`).** The viewing cameras carry no control handle in the config object. -- **The handle freshness (`CTRL-1`).** The config is the upstream `develop` branch; some handles may lag the live beamline. -- **The operator / safety boundary (`GOV-1`).** The EMBL-operated beamline on the DESY-hosted ring splits operator from interlock host; the boundary is pending. -- **The MX Method (`TECH-1`).** Whether MX enters CORA's catalog is an owner decision; the Practice renders unlinked, pending, reusing the existing slug. -- **The PSS permit signals (`PSS-1`).** Not in the config; carried pending, not invented. -- **The simulated devices and full asset-tree scenarios.** No `test_p13_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the P13 team to confirm before the model can be trusted.* - -P13 was reverse-engineered from EMBL Hamburg's own public MXCuBE HardwareObjects configuration ([github.com/mxcube/mxcubecore](https://github.com/mxcube/mxcubecore/tree/develop/mxcubecore/configuration/embl_hh_p13), `configuration/embl_hh_p13`), not from a live connection. EMBL publishes a richer config than the DESY OnlineXML, so the diffractometer and its axes are named (the experiment hutch resolves into a real `Goniometer`), but the exact geometry, the optics breakdown, and the safety / operator boundary are not in it. P13 is CORA's first EMBL Hamburg beamline and the first sub-operator on the PETRA III Site. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: an optics hutch and an experiment hutch? The split is inferred from the device prefixes and the MX layout. | A `p13-oh` optics hutch and a `p13-eh` experiment hutch. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The undulator source (the MXCuBE config exposes the energy service, not the undulator device). | An undulator beamline; the source carried pending. | The source Asset. | -| GROUP-1 | Nice-to-have | The per-axis roles of the KB mirror motions (`/P13/P13Kb.CDI/*`). | Grouped as the optics-hutch focusing stage; per-mirror Assets pending. | The Asset boundaries. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| OPT-1 | Blocks-go-live | The optics breakdown: the monochromator and the KB mirrors within the focusing motions, and the aperture-size table. | Grouped `LinearStage` optics motions plus a beam-defining `Aperture`; the breakdown pending. | The optics modelling. | -| ENERGY-1 | Nice-to-have | The energy / monochromator coupling behind the `TINEEnergy` service (`/P13/Energy/P13Energy`). | A `PseudoAxis` energy service; the mono motions it drives pending. | The energy modelling. | - -### Sample endstation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MX-1 | Blocks-build | The EMBLMiniDiff goniometer geometry (kappa range, axis offsets, the omega / kappa / centring axis assignment). | The EMBLMiniDiff bound to the graduated `Goniometer` with its named axes; the geometry carried as a question. | The MX instrument modelling. | -| OAV-1 | Nice-to-have | The on-axis viewing objective (MicrodiffZoom) magnification and the on-axis / sample-changer camera handles. | An `Objective` zoom plus `Camera` viewing; the camera handle pending. | The OAV modelling. | -| CRYO-1 | Nice-to-have | The cryostream (cooler model, sensor / setpoint handles); it is not a labelled device in the MXCuBE config. | Carried as a question; the liquid nitrogen a Supply observation, not a device. | The temperature-control modelling. | -| ROBOT-1 | Blocks-go-live | The automated sample changer (load / centre / collect / unmount loop). | A deferred sample-exchange Procedure over the spine + a Subject custody thread, not a device family; MXCuBE bookkeeping, not a device. | The sample-exchange modelling. | - -### The detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The detector models (Eiger 16M, Pilatus 6M read from the config), their ROI modes, and the sample-to-detector geometry. | Two `Camera` area detectors plus a derived `PseudoAxis` distance; the geometry pending. | The detector modelling. | -| DIAG-1 | Nice-to-have | The beam-diagnostic service split (the BCU intensity / centring services and the pin-diode flux). | Grouped `FluxMonitor` diagnostics; the per-service split pending. | The diagnostic modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | The Exporter / TINE control handles per P13 device, and whether the upstream MXCuBE `develop` config matches the live beamline. | The handles read from the public MXCuBE config, carried pending; the floor is MXCuBE over Exporter + TINE. | Binding each Asset's control handle. | -| SEAM-1 | Blocks-go-live | The EMBL Hamburg control domain: MXCuBE over Exporter (microdiff) + TINE, distinct from the DESY Tango / Sardana floor. | A sub-operator control-domain within the PETRA III Site; EMBL's house style recorded on the Site. | The seam and Site modelling. | -| GOV-1 | Blocks-go-live | The EMBL Hamburg operator pool, the safety-review structure, and the boundary between the DESY-hosted ring interlock and the EMBL-operated beamline. | Carried pending on the PETRA III Site, distinct from the DESY pool; the operator / interlock boundary a question. | The governance principals. | -| PSS-1 | Blocks-go-live | The personnel-safety permit signals and the photon / front-end shutters (absent from the MXCuBE config). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent and the cryostream liquid-nitrogen / beam supplies. | Photon beam, cooling water, vacuum, and liquid nitrogen. | The Supply observations. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Does rotation MX enter CORA's catalog as a Capability / Method? | Deferred: carried as a pending Practice reusing the i03 `mx_data_collection` slug; none coined. | The technique Capability. | diff --git a/docs/deployments/p14/notes.md b/docs/deployments/p14/notes.md deleted file mode 100644 index a9faade6810..00000000000 --- a/docs/deployments/p14/notes.md +++ /dev/null @@ -1,148 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of P14 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../petra-iii/index.md#the-techniques-adapted-here) is how a facility adapts it. P14 runs macromolecular crystallography across two endstations, reusing a Method the fleet already carries pending, so the Method below renders unlinked until a technique enters scope (`TECH-1`). - -### Macromolecular crystallography - -P14 mounts a crystal on a diffractometer (with cryostream cooling), rotates it through an oscillation, and reads frames on an area detector, across two experiment hutches: EH1 on the [EMBLMiniDiff + Eiger detectors](detector.md), EH2 on the [EMBLBSD + Pilatus 2M](detector.md). The EH1 CdTe Eiger variants extend the technique to high-energy data collection, and the X-ray imaging camera supports in-situ centring. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Rotation MX data collection | `mx_data_collection` | oscillation collection on the EMBLMiniDiff (EH1) / EMBLBSD (EH2) reading the Eiger / Pilatus, with cryostream cooling; reuses the i03 Method (also at FMX / AMX / MX3 / MANACA / TPS / P11 / P13), a further consumer (`TECH-1`) | - -### A familiar technique across two hutches - -P14 is the fleet's eighth macromolecular-crystallography beamline and CORA's second at EMBL Hamburg. It ties into the MX lineage CORA already models: the same goniometer / detector / cryostream anatomy, here run through EMBL's MXCuBE over Exporter + TINE (`SEAM-1`). What is distinctive is the two-endstation layout, one source feeding two hutches each running rotation MX, and the high-energy CdTe detector variants in EH1. It reuses the `mx_data_collection` Method directly (carried pending across the MX fleet); it forces no new device Family. The automated sample changer is a Procedure, not a new device (the i03 / MX3 / MANACA `ROBOT-1` precedent). - -### Not modelled yet - -The concrete acquisition recipes (the oscillation sequences and their exposures, the high-energy CdTe collection, the anomalous-edge scans, the X-ray imaging centring, the sample-changer custody loop) are not written yet; they join as the deployment approaches the point where CORA drives P14. Whether the MX Method enters CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at P14, and the trust shape that will gate it. First cut.* - -Governance at P14 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), 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). - -P14 is CORA's second EMBL Hamburg beamline, the sibling of [P13](../p13/notes.md#governance) and, like it, a **sub-operator** on the PETRA III Site: the beamline shares the ring and Facility with the DESY beamlines but is operated by EMBL Hamburg, with its own staff and its own MXCuBE control domain. The EMBL Hamburg operator pool and safety-review structure are carried pending on the [PETRA III Site](../petra-iii/index.md#safety-and-governance), distinct from the DESY pool and shared with P13, until EMBL staff confirm them (`GOV-1`). P14 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives P14, following the [2-BM governance](../2-bm/governance.md) shape. - -The two-hutch layout adds a governance nuance: EH1 and EH2 are separate experiment hutches under one beamline, so the trust shape would scope per hutch (each hutch its own Zone of resources and its own access state) while sharing the source / optics chain. That per-hutch scoping is carried as part of the enclosure question (`EH-1`). - -The safety tier is the other piece that is not yet settled. The MXCuBE configs carry beamline devices, not the personnel-safety interlock leaves, so the Enclosure permit signals and the interlock structure are carried pending and are not invented here (`PSS-1`). The interlock is operated by DESY (the ring host) even where EMBL operates the beamline, so the boundary between the DESY-issued site clearance and the EMBL-operated experiment is itself a question (`GOV-1`). What is already settled is the shape: clearances (the safety forms that must be active to start) are issued at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -P14 also carries the hazard classes that come with an MX endstation: a cryostream and its liquid-nitrogen supply, and an automated sample changer moving in the experiment hutches. Those land with the instruments that bring them; the sample-changer custody loop, if modelled, would be a Procedure with a Subject thread (`ROBOT-1`), not an Asset CORA drives for safety. - -The concrete Zone, Conduit, and Policy instances, and the EMBL operator pool, land when the deployment approaches the point where CORA drives P14, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's P14 content lives, the multi-endstation topology it exercises, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at P14 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes P14 new - -P14 is CORA's second EMBL Hamburg beamline (the sibling of P13) and the **first two-endstation MX beamline** CORA models: one source / optics chain feeding two experiment hutches, EH1 (the EMBLMiniDiff + Eiger detectors) and EH2 (the EMBLBSD + Pilatus 2M). At the vocabulary level it is a reuse-and-reinforce deployment; the new thing it exercises is the **multi-endstation topology under one beamline**, plus the high-energy CdTe detector variants and the X-ray imaging camera. - -### Two endstations, one source (the new modelling exercise) - -P13 established the EMBL sub-operator control-domain; P14 reuses it and adds the multi-hutch shape. The optics chain (KB mirrors, CRL transfocator, beam-defining slits, shared photon energy) feeds two experiment hutches, each with its own diffractometer host. CORA models this as three enclosures (`p14-oh`, `p14-eh1`, `p14-eh2`) under one root Asset, with the energy and CRL services shared and each hutch carrying its own goniometer, detector, and sample optics (`EH-1`). The trust shape would scope per hutch while sharing the source, a governance nuance carried with the enclosure question. - -### No new families (the MX spine reuses the i03 precedent) - -P14 coins no new Family. Both diffractometers bind the graduated `Goniometer`; the area detectors bind `Camera`; the XRF detector binds `EnergyDispersiveSpectrometer`; the CRL binds `Transfocator`; the slits bind `Slit`; the focusing optic binds `Mirror`; the sample illumination binds the catalog `Backlight` (graduated across the MX / imaging fleet); the optics motions bind `LinearStage`, the energy and detector distance `PseudoAxis`. Nothing in the catalog changes. The MX technique reuses the pending i03 `mx_data_collection` Method (as P13 and the wider MX fleet do). - -### The honest limitation: published mockups - -The EH2 config (`embl_hh_pe2`) publishes some axes as `MotorMockup`, a simulation placeholder rather than a live device handle. Rather than present these as real, the EH2 diffractometer and table are carried with a caution marker (`MOCK-1`): the instrument is named and bound, but whether each axis is live on the floor or a config stub is a confirm. This is the same "model what the source supports, flag the rest" posture P11 and P13 take, applied to a source that mixes live and simulated entries. - -### The control plane - -P14 sits on EMBL Hamburg's MXCuBE + Exporter + TINE domain, distinct from the DESY Tango / Sardana floor, with the diffractometer motions Exporter-hosted (`p14md301` / `p14md302` for EH1, `pe2bsd01` for EH2) and the detector / energy / beam services on TINE (`/P14/...`, `/PE2/...`). The handles are read from EMBL's public MXCuBE configs and carried confirm (`CTRL-1`). The rotation-MX acquisition runs as an MXCuBE data-collection routine; that orchestration is the seam CORA's edge replaces or drives through over its `ControlPort`, the same shape as the MX cluster seams at i03 / MANACA / TPS 07A and its sibling P13. - -### Deliberately not here yet - -- **The source (`SRC-1`).** The MXCuBE config exposes the energy service, not the undulator device; the source is carried pending. -- **The optics breakdown (`OPT-1`, `ENERGY-1`).** The monochromator and KB mirror Assets are not individually labelled; the motions are grouped, the energy carried as a pseudo-axis, the CRL and slits bound but uncharacterized. -- **The goniometer geometries (`MX-1`).** Both diffractometers are named and bound to `Goniometer`, but their kappa ranges and axis offsets are not in the configs. -- **The EH2 mockups (`MOCK-1`).** Some EH2 axes are `MotorMockup`; whether each is live or simulated is a confirm. -- **The EH2 table handle (`TABLE-1`).** The EH2 positioning table carries no control handle in the config object. -- **The cryostream (`CRYO-1`).** Not a labelled device in the configs; carried as a question, with the liquid nitrogen a Supply. -- **The sample changer (`ROBOT-1`).** MXCuBE bookkeeping, not a device; a deferred sample-exchange Procedure. -- **The detector model detail (`DET-1`).** The Eiger variants and Pilatus 2M are named; the ROI modes and geometry are pending. -- **The imaging / on-axis camera handles (`OAV-1`, `IMG-1`).** The viewing and X-ray imaging cameras carry no control handle in the config objects. -- **The handle freshness (`CTRL-1`).** The configs are the upstream `develop` branch; some handles may lag the live beamline. -- **The operator / safety boundary (`GOV-1`).** The EMBL-operated beamline on the DESY-hosted ring splits operator from interlock host; the boundary is pending. -- **The MX Method (`TECH-1`).** Whether MX enters CORA's catalog is an owner decision; the Practice renders unlinked, pending, reusing the existing slug. -- **The PSS permit signals (`PSS-1`).** Not in the configs; carried pending, not invented. -- **The simulated devices and full asset-tree scenarios.** No `test_p14_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the P14 team to confirm before the model can be trusted.* - -P14 was reverse-engineered from EMBL Hamburg's own public MXCuBE HardwareObjects configuration ([github.com/mxcube/mxcubecore](https://github.com/mxcube/mxcubecore/tree/develop/mxcubecore/configuration/embl_hh_p14), `configuration/embl_hh_p14` for EH1 and `configuration/embl_hh_pe2` for EH2), not from a live connection. EMBL publishes both endstation configs, so the two diffractometers and their axes are named (each experiment hutch resolves into a real `Goniometer`), but the exact geometry, the optics breakdown, the live-vs-mockup status of the EH2 axes, and the safety / operator boundary are not in them. P14 is CORA's second EMBL Hamburg beamline (the sibling of P13) and the first two-endstation MX beamline. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: one optics hutch and two experiment hutches? The split is inferred from the device prefixes and the MX layout. | A `p14-oh` optics hutch feeding `p14-eh1` and `p14-eh2` experiment hutches. | The Enclosure grouping. | -| EH-1 | Blocks-go-live | The two-endstation layout: do EH1 and EH2 share one source / optics chain (energy + CRL), each with its own diffractometer host? | One shared optics chain feeding two hutches; per-hutch diffractometer and detector. | The multi-endstation topology and per-hutch trust scoping. | -| SRC-1 | Nice-to-have | The undulator source (the MXCuBE config exposes the energy service, not the undulator device). | An undulator beamline; the source carried pending. | The source Asset. | -| GROUP-1 | Nice-to-have | The per-axis roles of the KB mirror and slit motions (the P14KB / P14Atto motor groups). | Grouped as the optics-hutch focusing and slit stages; per-axis roles pending. | The Asset boundaries. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| OPT-1 | Blocks-go-live | The optics breakdown: the monochromator and KB mirrors, the CRL lens count / material, and the aperture / slit-size tables. | Grouped `LinearStage` motions, a `Mirror` focusing optic, a `Transfocator` CRL, and `Slit` beam-defining boxes; the breakdown pending. | The optics modelling. | -| ENERGY-1 | Nice-to-have | The energy / monochromator coupling behind the `TINEEnergy` service (`/P14/Energy/P14Energy`), shared by both hutches. | A `PseudoAxis` energy service; the mono motions it drives pending. | The energy modelling. | - -### Sample endstations - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MX-1 | Blocks-build | The goniometer geometries of both endstations (the EH1 EMBLMiniDiff and the EH2 EMBLBSD): kappa range, axis offsets, the omega / kappa / centring axis assignment. | Both bound to the graduated `Goniometer` with named axes; the geometries carried as questions. | The MX instrument modelling. | -| MOCK-1 | Blocks-build | The EH2 axes published as `MotorMockup`: which are live on the floor and which are simulation placeholders in the config? | The EH2 diffractometer and table named and bound, but carried with a caution marker. | Whether the EH2 instrument is modelled live. | -| TABLE-1 | Nice-to-have | The EH2 experiment-table control handles (the EMBLTableMotor table_hor / table_ver carry no handle in the config object). | A `LinearStage` EH2 table; the handle pending. | The EH2 table modelling. | -| OAV-1 | Nice-to-have | The on-axis viewing objectives (MicrodiffZoom / ExporterZoom) magnification and the on-axis / sample-changer camera handles, both hutches. | `Objective` zooms plus `Camera` viewing; the camera handles pending. | The OAV modelling. | -| IMG-1 | Nice-to-have | The EH1 X-ray imaging camera (EMBLXrayImaging) control handle and role. | A `Camera` X-ray imaging device for centring; the handle pending. | The imaging modelling. | -| CRYO-1 | Nice-to-have | The cryostream (cooler model, sensor / setpoint handles); it is not a labelled device in the MXCuBE configs. | Carried as a question; the liquid nitrogen a Supply observation, not a device. | The temperature-control modelling. | -| ROBOT-1 | Blocks-go-live | The automated sample changer (load / centre / collect / unmount loop), per hutch. | A deferred sample-exchange Procedure over the spine + a Subject custody thread, not a device family; MXCuBE bookkeeping, not a device. | The sample-exchange modelling. | - -### The detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The detector models (Eiger 16M silicon, Eiger 16M / 4M CdTe in EH1, Pilatus 2M in EH2, read from the configs), their ROI modes, and the sample-to-detector geometries. | `Camera` area detectors plus derived `PseudoAxis` distances; the geometries pending. | The detector modelling. | -| DIAG-1 | Nice-to-have | The beam-diagnostic service split (the beam intensity / centring services and the pin-diode flux). | Grouped `FluxMonitor` diagnostics; the per-service split pending. | The diagnostic modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | The Exporter / TINE control handles per P14 device across the three diffractometer hosts, and whether the upstream MXCuBE `develop` configs match the live beamline. | The handles read from the public MXCuBE configs, carried pending; the floor is MXCuBE over Exporter + TINE. | Binding each Asset's control handle. | -| SEAM-1 | Blocks-go-live | The EMBL Hamburg control domain: MXCuBE over Exporter (microdiff) + TINE, distinct from the DESY Tango / Sardana floor (shared with P13). | A sub-operator control-domain within the PETRA III Site; EMBL's house style recorded on the Site. | The seam and Site modelling. | -| GOV-1 | Blocks-go-live | The EMBL Hamburg operator pool, the safety-review structure, and the boundary between the DESY-hosted ring interlock and the EMBL-operated beamline. | Carried pending on the PETRA III Site, shared with P13; the operator / interlock boundary a question. | The governance principals. | -| PSS-1 | Blocks-go-live | The personnel-safety permit signals and the photon / front-end shutters (absent from the MXCuBE configs), per hutch. | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent and the cryostream liquid-nitrogen / beam supplies. | Photon beam, cooling water, vacuum, and liquid nitrogen. | The Supply observations. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Does rotation MX enter CORA's catalog as a Capability / Method? | Deferred: carried as a pending Practice reusing the i03 `mx_data_collection` slug; none coined. | The technique Capability. | diff --git a/docs/deployments/p21/notes.md b/docs/deployments/p21/notes.md deleted file mode 100644 index 7395ca74b08..00000000000 --- a/docs/deployments/p21/notes.md +++ /dev/null @@ -1,124 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of P21 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../petra-iii/index.md#the-techniques-adapted-here) is how a facility adapts it. P21's diffraction techniques earn no catalog Method today, so the Methods below render unlinked and are carried pending until a technique enters scope (`TECH-1`). - -### High-energy diffraction - -P21's P21.2 / EH3 branches use a high-energy monochromatic beam for bulk / engineering diffraction, residual stress, and texture studies on the [sample stages](sample.md), reading area detectors. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| High-energy diffraction | `diffraction` | bulk / engineering diffraction on the high-energy branches; reuses the `diffraction` slug P07 / P08 share, a further consumer (`TECH-1`) | - -### Total scattering / PDF - -P21's P21.1 branch collects total scattering to high momentum transfer for pair-distribution-function analysis. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Total scattering / pair-distribution-function | `total_scattering` | high-Q total scattering on the P21.1 branch; reuses the `total_scattering` slug i15-1 / XPD / P02 share, a further consumer (`TECH-1`) | - -### A thin high-energy materials beamline - -P21 is a Swedish-collaboration high-energy materials beamline. Its techniques reuse the `diffraction` and `total_scattering` slugs already carried across the fleet, so none forces a new Method. The instrument anatomy reuses existing Families (`LinearStage`, `Slit`); the sparse registry slice means the model is deliberately thin, with the detectors carried pending. - -### Not modelled yet - -The concrete acquisition recipes (the diffraction / stress-mapping scans, the high-Q PDF collection) are not written yet; they join as the deployment approaches the point where CORA drives P21. Whether the diffraction Methods enter CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at P21, and the trust shape that will gate it. First cut.* - -Governance at P21 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), 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). - -P21 is CORA's thirteenth PETRA III beamline, a Swedish-collaboration beamline; the DESY operator pool and the safety-review structure are carried pending on the [PETRA III Site](../petra-iii/index.md#safety-and-governance), shared across the facility's beamlines, until DESY staff confirm them (`GOV-1`). How the Swedish collaboration maps to operator / access governance is part of that question. P21 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives P21, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. The OnlineXML carries beamline devices, not the personnel-safety interlock leaves, so the Enclosure permit signals (across the optics and the experiment stations) and the interlock structure are carried pending and are not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives P21, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's P21 content lives, a deliberately thin Swedish-collaboration materials model, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at P21 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes P21 new - -P21 is a thirteenth beamline at an existing Site, a Swedish-collaboration high-energy materials beamline (P21.1 powder / total scattering, P21.2 diffraction / imaging). At the modelling level it is a reuse-and-reinforce deployment, and a deliberately thin one given its sparse registry slice. - -### No new families (a thin, honest model) - -P21 coins no new Family. The motor banks bind `LinearStage`; the slits bind `Slit`; the detectors are a pending `Camera` placeholder. Nothing in the catalog changes. The P21 registry slice exposes little beyond grouped motor banks, so the detectors are carried pending rather than invented (`DET-1`), the same model-what-the-source-supports posture as P11 / P65. - -### The control plane - -P21 sits on the PETRA III Tango device floor with Sardana as the scan layer, the same as the other PETRA III beamlines, split across three Tango hosts (`hasep212oh`, `hasep21eh3`, `haspp21lab`). The handles are read from P21's public OnlineXML registry and carried confirm (`CTRL-1`). The high-energy diffraction acquisition runs as a Sardana macro; that orchestration is the seam CORA's edge replaces or drives through over its `ControlPort`. - -### Deliberately not here yet - -- **The source (`SRC-1`).** The OnlineXML slice exposes no undulator device; the source is carried pending. -- **The optics breakdown (`OPT-1`).** The monochromator, mirrors, and slits within the optics bank are not labelled; grouped. -- **The motor-bank axis roles (`GROUP-1`).** The `oh_u*`, `eh3_u*`, `lab*` banks carry no per-axis role; grouped as stage Assets. -- **The detectors (`DET-1`).** Not in the registry slice; carried as a pending `Camera` placeholder. -- **The P21.1 station (`HOST-1`).** The `hasep211eh` host exposed only bookkeeping devices; noted, not modelled. -- **The handle freshness (`CTRL-1`).** The OnlineXML branch is `debian/jessie`; some handles may lag the live Tango database. -- **The diffraction Methods (`TECH-1`).** Whether they enter CORA's catalog is an owner decision; the Practices render unlinked, pending. -- **The PSS permit signals (`PSS-1`).** Not in the OnlineXML; carried pending, not invented. -- **The simulated devices and full asset-tree scenarios.** No `test_p21_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the P21 team to confirm before the model can be trusted.* - -P21 was reverse-engineered from P21's own public OnlineXML device registry ([gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p21](https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p21), branch `debian/jessie`) and a verified research brief, not from a live connection. The P21 registry is thin: area-grouped generic motor banks, no detectors exposed. P21 is CORA's thirteenth PETRA III beamline, the Swedish Materials Science beamline. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: a P21.2 optics hutch, an EH3 endstation, and a LAB station (plus the P21.1 branch)? | A `p21-oh` / `p21-eh3` / `p21-lab` grouping, from the OnlineXML host names. | The Enclosure grouping. | -| HOST-1 | Blocks-go-live | The P21.1 station (`hasep211eh`) exposed only bookkeeping devices in this slice. Where is its device tree, and how do P21.1 / P21.2 relate? | Only P21.2 optics / EH3 / LAB modelled; P21.1 noted, not modelled. | The full beamline roster. | -| SRC-1 | Nice-to-have | The undulator source (absent from this slice). | An undulator beamline; the source carried pending. | The source Asset. | -| GROUP-1 | Nice-to-have | The per-axis roles of the motor banks (`oh_u*`, `eh3_u*`, `lab*`). | Grouped as stage Assets carrying the bank prefix; per-axis roles pending. | The Asset boundaries. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| OPT-1 | Blocks-go-live | The optics breakdown: the monochromator, mirrors, and slits within the P21.2 optics bank. | Grouped `LinearStage` optics stages; the breakdown pending. | The optics modelling. | - -### The detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The high-energy diffraction detectors (area detectors, the PerkinElmer / Varex flat-panels typical of high-energy beamlines), absent from this registry slice. | A pending `Camera` placeholder; the detectors not invented. | The detector modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | The Tango device handles per P21 device, the three-host split, and whether the OnlineXML `debian/jessie` branch matches the live Tango database. | The handles read from the public OnlineXML, carried pending; the floor is Tango + Sardana. | Binding each Asset's control handle. | -| PSS-1 | Blocks-go-live | The DESY personnel-safety permit signals and the photon / front-end shutters (absent from the OnlineXML). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent and the cooling / beam supplies. | Photon beam, cooling water, vacuum. | The Supply observations. | -| GOV-1 | Nice-to-have | The DESY operator pool, the Swedish collaboration's role, and the safety-review structure (site-level). | Carried pending on the PETRA III Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Do high-energy diffraction and total scattering enter CORA's catalog as Capabilities / Methods? | Deferred: carried as pending Practices reusing the `diffraction` / `total_scattering` slugs; none coined. | The technique Capabilities. | diff --git a/docs/deployments/p22/notes.md b/docs/deployments/p22/notes.md deleted file mode 100644 index 4438da9812f..00000000000 --- a/docs/deployments/p22/notes.md +++ /dev/null @@ -1,119 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of P22 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../petra-iii/index.md#the-techniques-adapted-here) is how a facility adapts it. P22's HAXPES technique earns no catalog Method today, so the Method below renders unlinked and is carried pending until a technique enters scope (`TECH-1`). - -### Hard X-ray photoelectron spectroscopy - -P22 illuminates the sample with a monochromatic hard X-ray beam (the shared P09 optics, with the phase retarder setting polarization) and measures the kinetic-energy spectrum of the emitted photoelectrons on the [electron analyzer](detector.md), probing bulk / buried electronic structure (the hard X-ray depth advantage over soft X-ray photoemission). - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Hard X-ray photoelectron spectroscopy (HAXPES) | `angle_resolved_photoemission` | photoemission on the HAXPS electron analyzer over the shared P09 optics; reuses the `angle_resolved_photoemission` slug P04 shares, a further consumer (`TECH-1`) | - -### A photoemission beamline on familiar vocabulary - -P22 is the fleet's hard X-ray photoemission beamline. Its technique reuses the `angle_resolved_photoemission` slug already carried pending (P04, NSLS-II ESM), so it forces no new Method. The instrument anatomy reuses existing Families: the shared optics bind `Monochromator` / `Mirror` / the catalog `PhaseRetarder`, the sample stage `Manipulator`, and the electron analyzer the catalog `ElectronAnalyzer` (graduated at NSLS-II ESM, carried pending here since not exposed in the registry). The HAXPES depth sensitivity is a physics consequence of the hard X-ray energy, not a new device. - -### Not modelled yet - -The concrete acquisition recipes (the analyzer energy sweeps, the depth-profiling / standing-wave HAXPES, the polarization-dependent measurements) are not written yet; they join as the deployment approaches the point where CORA drives P22. Whether `angle_resolved_photoemission` enters CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at P22, and the trust shape that will gate it. First cut.* - -Governance at P22 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), 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). - -P22 is CORA's fourteenth PETRA III beamline: the DESY operator pool and the safety-review structure are carried pending on the [PETRA III Site](../petra-iii/index.md#safety-and-governance), shared across the facility's beamlines, until DESY staff confirm them (`GOV-1`). P22 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives P22, following the [2-BM governance](../2-bm/governance.md) shape. - -A P22-specific governance wrinkle: P22 **shares its optics chain with P09** (`SHARED-1`). The undulator, monochromator, mirrors, and phase retarder are P09 devices, so the optics-enclosure access state and the source-conditioning commands couple the two beamlines. How CORA's Federation / Trust model carries that coupling (a shared Zone, or a coordination Conduit between the two beamlines) is part of the open question; for this first cut the shared optics are homed in the P22 optics enclosure with the relationship flagged. - -The safety tier is the other piece that is not yet settled. The OnlineXML carries beamline devices, not the personnel-safety interlock leaves, so the Enclosure permit signals and the interlock structure are carried pending and are not invented here (`PSS-1`). The shared optics mean the optics-enclosure permit is coupled with P09. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives P22, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's P22 content lives, the shared-optics relationship with P09, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at P22 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes P22 new - -P22 is a fourteenth beamline at an existing Site, the facility's hard X-ray photoemission (HAXPES) beamline. Its distinguishing structural fact is that it **shares its optics chain with P09**: the undulator, DCM, mirrors, phase retarder, and absorber are P09 devices, and P22 is the HAXPES branch off that chain. At the modelling level it is a reuse-and-reinforce deployment, plus a shared-optics relationship the Federation / Trust model would carry. - -### No new families - -P22 coins no new Family. The shared optics bind `Monochromator` / `Mirror` / `Filter` and the catalog `PhaseRetarder` (P22 is the third consumer, the one that completed the 4-ID/P09/P22 rule-of-three); the HAXPS sample stage binds `Manipulator` (the NSLS-II ESM Family); the electron analyzer binds the catalog `ElectronAnalyzer` (also ESM, carried pending here). Nothing in the catalog changes. - -### The control plane - -P22 sits on the PETRA III Tango device floor with Sardana as the scan layer. Its defining control fact is the shared P09 optics (the `p09/` addresses), so P22's source-conditioning state is coupled to P09 (`SHARED-1`). The handles are read from P22's public OnlineXML registry and carried confirm (`CTRL-1`); the electron analyzer is a self-contained instrument not in the registry slice (`DET-1`). The HAXPES acquisition runs as a Sardana macro coordinated with the analyzer; that orchestration is the seam CORA's edge replaces or drives through over its `ControlPort`. - -### Deliberately not here yet - -- **The shared-optics relationship (`SHARED-1`).** P22 and P09 share the undulator / DCM / mirrors / phase retarder; how that maps to CORA's Federation / Trust coordination (two beamlines, one optics chain) is pending. -- **The undulator parameters (`SRC-1`).** The gap is read; the period is not exposed. -- **The optics detail (`OPT-1`).** The DCM crystal cut, the mirror coatings, and the phase-retarder geometry are carried confirm-pending. -- **The manipulator axis roles (`GROUP-1`).** The `p22/motor` bank carries no per-axis role; grouped as one `Manipulator`. -- **The electron analyzer (`DET-1`).** The defining HAXPES detector is named (bound to `ElectronAnalyzer`) but its model / control interface is not in the registry; carried pending. -- **The dummy stubs (`STUB-1`).** The `haxps_dmy*` placeholder devices are noted, not modelled. -- **The handle freshness (`CTRL-1`).** The OnlineXML branch is `debian/jessie`; some handles may lag the live Tango database. -- **The HAXPES Method (`TECH-1`).** Whether it enters CORA's catalog is an owner decision; the Practice renders unlinked, pending. -- **The PSS permit signals (`PSS-1`).** Not in the OnlineXML; carried pending, not invented. -- **The simulated devices and full asset-tree scenarios.** No `test_p22_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the P22 team to confirm before the model can be trusted.* - -P22 was reverse-engineered from P22's own public OnlineXML device registry ([gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p22](https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p22), branch `debian/jessie`) and a verified research brief, not from a live connection. The registry shows P22 sharing the P09 optics chain, with the HAXPS endstation as a grouped bank and the electron analyzer not exposed. P22 is CORA's fourteenth PETRA III beamline, the HAXPES beamline. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: shared P09 optics feeding the HAXPS experiment endstation? | A `p22-optics` (shared with P09) and a `p22-haxps` endstation. | The Enclosure grouping. | -| SHARED-1 | Blocks-go-live | The P22 / P09 shared optics: the undulator, DCM, mirrors, and phase retarder are P09 devices. How are the two beamlines coordinated (shared straight, switched source, simultaneous operation)? | The optics are shared, homed in `p22-optics` with the relationship flagged. | The shared-optics coordination model. | -| SRC-1 | Nice-to-have | The undulator period and parameters. | A shared P09 undulator; gap read, period pending. | The source Asset detail. | -| GROUP-1 | Nice-to-have | The per-axis roles of the HAXPS manipulator bank (the polar / azimuthal / translation axes). | Grouped as one `Manipulator` Asset; per-axis roles pending. | The manipulator Asset boundaries. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| OPT-1 | Blocks-go-live | The shared DCM crystal cut, the mirror coatings, and the phase-retarder geometry. | A DCM `Monochromator`, two `Mirror`s, and a catalog `PhaseRetarder`; physical detail pending. | The optics modelling. | - -### The detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The HAXPES electron analyzer model (a hemispherical analyzer, e.g. SPECS / Scienta), its lens modes, and its control interface (absent from this registry slice). | An `ElectronAnalyzer` Asset (the NSLS-II ESM Family); model and control pending. | The detector modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | The Tango device handles per P22 device, the shared P09 optics handles, and whether the OnlineXML `debian/jessie` branch matches the live Tango database. | The handles read from the public OnlineXML, carried pending; the floor is Tango + Sardana; optics shared with P09. | Binding each Asset's control handle. | -| PSS-1 | Blocks-go-live | The DESY personnel-safety permit signals, the shared-optics permit coupling with P09, and the photon / front-end shutters (absent from the OnlineXML). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent (HAXPES needs UHV at the analyzer) and the cooling / beam supplies. | Photon beam, cooling water, vacuum. | The Supply observations. | -| GOV-1 | Nice-to-have | The DESY operator pool and safety-review structure (site-level). | Carried pending on the PETRA III Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Does hard X-ray photoelectron spectroscopy enter CORA's catalog as a Capability / Method? | Deferred: carried as a pending Practice reusing the `angle_resolved_photoemission` slug P04 shares; none coined. | The technique Capability. | diff --git a/docs/deployments/p23/notes.md b/docs/deployments/p23/notes.md deleted file mode 100644 index 8a88487d3da..00000000000 --- a/docs/deployments/p23/notes.md +++ /dev/null @@ -1,117 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of P23 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../petra-iii/index.md#the-techniques-adapted-here) is how a facility adapts it. P23's diffraction technique earns no catalog Method today, so the Method below renders unlinked and is carried pending until a technique enters scope (`TECH-1`). - -### In-situ X-ray diffraction - -P23 measures diffraction (and imaging) of samples under in-situ / operando conditions, electrochemistry, thin-film growth, and controlled sample environments, on the [experiment diffractometer](sample.md). - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| In-situ / operando X-ray diffraction | `diffraction` | diffraction of samples under in-situ conditions; reuses the `diffraction` slug P07 / P08 / P21 share, a further consumer (`TECH-1`) | - -### A thin in-situ diffraction beamline - -P23 is a thin in-situ diffraction beamline. Its technique reuses the `diffraction` slug already carried across the fleet, so it forces no new Method. The instrument anatomy reuses existing Families (`LinearStage`); the sparse registry slice means the model is deliberately thin, with the optics / diffractometer grouped and the detectors carried pending. The in-situ sample environments (the operando cells), if present, would be sample-environment Assets bound when the registry exposes them. - -### Not modelled yet - -The concrete acquisition recipes (the diffraction scans, the in-situ / operando time series, the environment-coupled measurements) are not written yet; they join as the deployment approaches the point where CORA drives P23. Whether the diffraction Method enters CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at P23, and the trust shape that will gate it. First cut.* - -Governance at P23 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), 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). - -P23 is CORA's fifteenth PETRA III beamline: the DESY operator pool and the safety-review structure are carried pending on the [PETRA III Site](../petra-iii/index.md#safety-and-governance), shared across the facility's beamlines, until DESY staff confirm them (`GOV-1`). P23 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives P23, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. The OnlineXML carries beamline devices, not the personnel-safety interlock leaves, so the Enclosure permit signals and the interlock structure are carried pending and are not invented here (`PSS-1`). P23's in-situ / operando sample environments (electrochemical cells, growth chambers) may carry their own hazards; those land with the instruments that bring them when the deployment firms up. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives P23, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's P23 content lives, a deliberately thin in-situ / operando diffraction model, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at P23 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes P23 new - -P23 is a fifteenth beamline at an existing Site, the facility's in-situ / operando diffraction beamline. At the modelling level it is a reuse-and-reinforce deployment, and a deliberately thin one given its sparse registry slice (one generic motor bank). - -### No new families (a thin, honest model) - -P23 coins no new Family. The motor bank binds `LinearStage`; the detectors are a pending `Camera` placeholder. Nothing in the catalog changes. The P23 registry slice exposes little beyond the grouped motor bank, so the optics / diffractometer breakdown and the detectors are carried grouped / pending rather than invented (`OPT-1`, `DIFF-1`, `DET-1`), the same model-what-the-source-supports posture as P11 / P21 / P65. - -### The control plane - -P23 sits on the PETRA III Tango device floor with Sardana as the scan layer, the same as the other PETRA III beamlines. The handles are read from P23's public OnlineXML registry and carried confirm (`CTRL-1`). The in-situ diffraction acquisition runs as a Sardana macro; that orchestration is the seam CORA's edge replaces or drives through over its `ControlPort`. - -### Deliberately not here yet - -- **The source (`SRC-1`).** The OnlineXML slice exposes no undulator device; the source is carried pending. -- **The optics / diffractometer breakdown (`OPT-1`, `DIFF-1`).** The mono, mirrors, and diffractometer within the bank are not labelled; grouped. -- **The motor-bank axis roles (`GROUP-1`).** The `eh_mot*` bank carries no per-axis role; grouped as one stage. -- **The dev stub (`STUB-1`).** The single `hasep23dev` axis is a dev / commissioning device, noted. -- **The detectors (`DET-1`).** Not in the registry slice; carried as a pending `Camera` placeholder. -- **The handle freshness (`CTRL-1`).** The OnlineXML branch is `debian/jessie`; some handles may lag the live Tango database. -- **The diffraction Method (`TECH-1`).** Whether it enters CORA's catalog is an owner decision; the Practice renders unlinked, pending. -- **The PSS permit signals (`PSS-1`).** Not in the OnlineXML; carried pending, not invented. -- **The simulated devices and full asset-tree scenarios.** No `test_p23_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the P23 team to confirm before the model can be trusted.* - -P23 was reverse-engineered from P23's own public OnlineXML device registry ([gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p23](https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p23), branch `debian/jessie`) and a verified research brief, not from a live connection. The P23 registry is thin: one area-grouped generic motor bank, no detectors exposed. P23 is CORA's fifteenth PETRA III beamline, the in-situ diffraction beamline. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: a single experiment hutch (the registry exposes one host)? Is there a separate optics hutch? | A `p23-eh` experiment hutch, from the OnlineXML `hasep23oh` host. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The undulator source (absent from this slice). | An undulator beamline; the source carried pending. | The source Asset. | -| GROUP-1 | Nice-to-have | The per-axis roles of the `eh_mot*` motor bank. | Grouped as one `LinearStage` stage carrying the bank prefix; per-axis roles pending. | The Asset boundaries. | -| STUB-1 | Nice-to-have | The single `hasep23dev` axis: a dev / commissioning device, or a real channel? | Noted as a dev / commissioning stage. | The dev-stub status. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| OPT-1 | Blocks-go-live | The optics breakdown: the monochromator and mirrors within the bank. | Grouped into the experiment stage; the breakdown pending. | The optics modelling. | -| DIFF-1 | Blocks-build | The diffractometer geometry within the bank. | Grouped into the experiment stage; the diffractometer pending. | The diffractometer modelling. | - -### The detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The in-situ diffraction detectors (area detectors, any fluorescence detectors), absent from this registry slice. | A pending `Camera` placeholder; the detectors not invented. | The detector modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | The Tango device handles per P23 device, and whether the OnlineXML `debian/jessie` branch matches the live Tango database. | The handles read from the public OnlineXML, carried pending; the floor is Tango + Sardana. | Binding each Asset's control handle. | -| PSS-1 | Blocks-go-live | The DESY personnel-safety permit signals and the photon / front-end shutters (absent from the OnlineXML). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent, the cooling / beam supplies, and the in-situ sample-environment supplies. | Photon beam, cooling water, vacuum. | The Supply observations. | -| GOV-1 | Nice-to-have | The DESY operator pool and safety-review structure (site-level). | Carried pending on the PETRA III Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Does in-situ X-ray diffraction enter CORA's catalog as a Capability / Method? | Deferred: carried as a pending Practice reusing the `diffraction` slug; none coined. | The technique Capability. | diff --git a/docs/deployments/p24/notes.md b/docs/deployments/p24/notes.md deleted file mode 100644 index e5dda38d187..00000000000 --- a/docs/deployments/p24/notes.md +++ /dev/null @@ -1,123 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of P24 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../petra-iii/index.md#the-techniques-adapted-here) is how a facility adapts it. P24's chemical crystallography earns no dedicated catalog Method today, so the Method below renders unlinked and is carried pending until a technique enters scope (`TECH-1`). - -### Chemical crystallography - -P24 mounts a single crystal on the [diffractometer](sample.md) and collects single-crystal diffraction on the area detector to solve small-molecule / chemical structures (including at non-ambient conditions). - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Single-crystal / chemical crystallography | `diffraction` | single-crystal diffraction on the EH2 diffractometer + area detector; reuses the `diffraction` slug (no dedicated chemical-crystallography Method exists), a further consumer (`TECH-1`) | - -### A chemical crystallography beamline on familiar vocabulary - -P24 is PETRA III's chemical (small-molecule) crystallography beamline, the fleet's second after Diamond [I19](../i19/index.md). It is distinct from the macromolecular-crystallography beamlines (P11, i03, FMX / AMX, MANACA, TPS): those bind the `Goniometer` Family and the `mx_data_collection` Method, while P24 does small-molecule chemical crystallography, which CORA models as `diffraction` for now (no dedicated chemical-crystallography Method exists, and the registry does not expose a labelled goniometer). The instrument anatomy reuses existing Families (`LinearStage`, `Slit`, `EnergyDispersiveSpectrometer`); the area detector is carried pending. - -### Not modelled yet - -The concrete acquisition recipes (the single-crystal data-collection strategies, the multi-temperature / variable-condition collection) are not written yet; they join as the deployment approaches the point where CORA drives P24. Whether a dedicated chemical-crystallography Method (vs reusing `diffraction`) enters CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at P24, and the trust shape that will gate it. First cut.* - -Governance at P24 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), 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). - -P24 is CORA's sixteenth PETRA III beamline: the DESY operator pool and the safety-review structure are carried pending on the [PETRA III Site](../petra-iii/index.md#safety-and-governance), shared across the facility's beamlines, until DESY staff confirm them (`GOV-1`). P24 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives P24, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. The OnlineXML carries beamline devices, not the personnel-safety interlock leaves, so the Enclosure permit signals (across the optics and the two experiment hutches) and the interlock structure are carried pending and are not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives P24, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's P24 content lives, its single-crystal chemical crystallography distinct from the MX beamlines, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at P24 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes P24 new - -P24 is a sixteenth beamline at an existing Site, the facility's single-crystal / small-molecule chemical crystallography beamline. It is distinct from the macromolecular-crystallography beamlines (P11, i03, FMX / AMX, MANACA, TPS), which bind `Goniometer` and `mx_data_collection`: P24 does small-molecule chemical crystallography, modelled as `diffraction` for now. At the modelling level it is a reuse-and-reinforce deployment. - -### No new families - -P24 coins no new Family. The optics / sample banks bind `LinearStage`; the slits `Slit`; the coupled axes `PseudoAxis`; the MCA `EnergyDispersiveSpectrometer`; the area detector `Camera` (carried pending). Nothing in the catalog changes. Whether the diffractometer, once labelled, warrants a `Goniometer` / `Diffractometer` binding is carried `DIFF-1`. - -### The control plane - -P24 sits on the PETRA III Tango device floor with Sardana as the scan layer, the same as the other PETRA III beamlines. The handles are read from P24's public OnlineXML registry and carried confirm (`CTRL-1`); the area detector is not exposed in this slice (`DET-1`). The chemical-crystallography acquisition runs as a Sardana macro; that orchestration is the seam CORA's edge replaces or drives through over its `ControlPort`. - -### Deliberately not here yet - -- **The source (`SRC-1`).** The OnlineXML slice exposes no undulator device; the source is carried pending. -- **The optics breakdown (`OPT-1`).** The monochromator and mirrors within the optics bank are not labelled; grouped. -- **The diffractometer geometry (`DIFF-1`).** Not labelled in the registry; grouped into the sample stage, the goniometer-vs-diffractometer binding pending. -- **The motor-bank axis roles (`GROUP-1`).** The `oh_mot*` / `mot*` banks carry no per-axis role; grouped as stage Assets. -- **The area detector (`DET-1`).** The single-crystal area detector is not in the registry slice; carried as a pending `Camera` placeholder. -- **The dummy stubs (`STUB-1`).** The `eh2_dmy*` placeholder devices are noted, not modelled. -- **The handle freshness (`CTRL-1`).** The OnlineXML branch is `debian/jessie`; some handles may lag the live Tango database. -- **The chemical-crystallography Method (`TECH-1`).** Whether a dedicated Method (vs reusing `diffraction`) enters CORA's catalog is an owner decision; the Practice renders unlinked, pending. -- **The PSS permit signals (`PSS-1`).** Not in the OnlineXML; carried pending, not invented. -- **The simulated devices and full asset-tree scenarios.** No `test_p24_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the P24 team to confirm before the model can be trusted.* - -P24 was reverse-engineered from P24's own public OnlineXML device registry ([gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p24](https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p24), branch `debian/jessie`) and a verified research brief, not from a live connection. The registry exposes generic motor banks and the MCAs, but not the diffractometer geometry or the area detector. P24 is CORA's sixteenth PETRA III beamline, the chemical crystallography beamline. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: an optics hutch feeding an EH2 main and an EH1 experiment hutch? | A `p24-oh` optics hutch and `p24-eh2` / `p24-eh1` endstations. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The undulator source (absent from this slice). | An undulator beamline; the source carried pending. | The source Asset. | -| GROUP-1 | Nice-to-have | The per-axis roles of the motor banks (`oh_mot*`, `mot*`). | Grouped as stage Assets carrying the bank prefix; per-axis roles pending. | The Asset boundaries. | -| STUB-1 | Nice-to-have | The `eh2_dmy*` dummy stubs: test / placeholder devices, or real channels? | Noted as dummy stubs, not modelled. | The stub status. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| OPT-1 | Blocks-go-live | The optics breakdown: the monochromator and mirrors within the optics bank. | Grouped `LinearStage` optics stages; the breakdown pending. | The optics modelling. | - -### Sample endstation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DIFF-1 | Blocks-build | The chemical-crystallography diffractometer geometry (and whether it warrants a `Goniometer` / `Diffractometer` binding once labelled). | A grouped `LinearStage` sample stage; the diffractometer binding pending. | The diffractometer modelling. | - -### The detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The single-crystal area detector (a Pilatus / Eiger-class photon-counting detector), absent from this registry slice. | A pending `Camera` placeholder plus the `EnergyDispersiveSpectrometer` MCAs. | The detector modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | The Tango device handles per P24 device, and whether the OnlineXML `debian/jessie` branch matches the live Tango database. | The handles read from the public OnlineXML, carried pending; the floor is Tango + Sardana. | Binding each Asset's control handle. | -| PSS-1 | Blocks-go-live | The DESY personnel-safety permit signals and the photon / front-end shutters (absent from the OnlineXML). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent and the cooling / beam supplies. | Photon beam, cooling water, vacuum. | The Supply observations. | -| GOV-1 | Nice-to-have | The DESY operator pool and safety-review structure (site-level). | Carried pending on the PETRA III Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Does chemical crystallography enter CORA's catalog as a dedicated Capability / Method (vs reusing `diffraction`)? | Deferred: carried as a pending Practice reusing the `diffraction` slug; none coined. | The technique Capability. | diff --git a/docs/deployments/p61/notes.md b/docs/deployments/p61/notes.md deleted file mode 100644 index 1876348d008..00000000000 --- a/docs/deployments/p61/notes.md +++ /dev/null @@ -1,119 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of P61 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../petra-iii/index.md#the-techniques-adapted-here) is how a facility adapts it. P61's diffraction technique earns no catalog Method today, so the Method below renders unlinked and is carried pending until a technique enters scope (`TECH-1`). - -### High-energy white-beam / energy-dispersive diffraction - -P61 uses the high-energy white beam from the damping wiggler for energy-dispersive diffraction (P61B engineering / materials studies) and Large Volume Press high-pressure / high-temperature in-situ studies (P61A), reading the [energy-dispersive detector](detector.md). - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Energy-dispersive diffraction (white beam) | `energy_dispersive_diffraction` | high-energy white-beam energy-dispersive diffraction (P61B) and Large Volume Press in-situ studies (P61A); reuses the `energy_dispersive_diffraction` slug, a further consumer (`TECH-1`, `PRESS-1`) | - -### A thin high-energy white-beam beamline - -P61 is the fleet's high-energy white-beam wiggler beamline. Its technique reuses the `energy_dispersive_diffraction` slug already carried across the fleet, so it forces no new Method. The instrument anatomy reuses existing Families (`LinearStage`); the sparse registry slice means the model is deliberately thin, with the source, the Large Volume Press, and the detectors carried pending. The Large Volume Press (P61A), when exposed, would reuse the catalog `PressureCell` Family (graduated across 13-id and P02). - -### Not modelled yet - -The concrete acquisition recipes (the energy-dispersive diffraction scans, the LVP pressure / temperature ramps, the white-beam engineering measurements) are not written yet; they join as the deployment approaches the point where CORA drives P61. Whether the diffraction Method enters CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at P61, and the trust shape that will gate it. First cut.* - -Governance at P61 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), 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). - -P61 is CORA's seventeenth PETRA III beamline: the DESY operator pool and the safety-review structure are carried pending on the [PETRA III Site](../petra-iii/index.md#safety-and-governance), shared across the facility's beamlines, until DESY staff confirm them (`GOV-1`). P61 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives P61, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. The OnlineXML carries beamline devices, not the personnel-safety interlock leaves, so the Enclosure permit signals and the interlock structure are carried pending and are not invented here (`PSS-1`). P61 carries hazard classes specific to a high-energy white-beam / Large Volume Press beamline: the unmonochromated white beam (a stringent shielding / interlock case) and the LVP's high-pressure / high-temperature environment. Those land with the instruments that bring them when the deployment firms up; the press is modelled as a sample-environment `PressureCell` Asset when exposed, not a beam-steering device CORA drives. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives P61, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's P61 content lives, its place as the last OnlineXML-modelled PETRA III beamline, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at P61 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes P61 new - -P61 is a seventeenth beamline at an existing Site, the facility's high-energy white-beam wiggler beamline (P61A Large Volume Press + P61B energy-dispersive diffraction). It is the **last PETRA III beamline with a public OnlineXML registry**, completing CORA's OnlineXML-driven coverage of the facility. At the modelling level it is a reuse-and-reinforce deployment, and a deliberately thin one given its sparse registry slice (one generic motor bank). - -### No new families (a thin, honest model) - -P61 coins no new Family. The motor bank binds `LinearStage`; the energy-dispersive detector is a pending `EnergyDispersiveSpectrometer` placeholder. Nothing in the catalog changes. The Large Volume Press (P61A), when exposed, would reuse the catalog `PressureCell` Family (graduated across 13-id and P02); it is carried pending (`PRESS-1`). The P61 registry slice exposes little beyond the grouped motor bank, so the source, the press, and the detectors are carried pending rather than invented, the model-what-the-source-supports posture as P11 / P21 / P23. - -### The control plane - -P61 sits on the PETRA III Tango device floor with Sardana as the scan layer, the same as the other PETRA III beamlines, with one quirk: P61 is the only PETRA III extras package on the `debian/stretch` branch (the others are `debian/jessie`), so its snapshot vintage may differ. The handles are read from P61's public OnlineXML registry and carried confirm (`CTRL-1`). The energy-dispersive diffraction acquisition runs as a Sardana macro; that orchestration is the seam CORA's edge replaces or drives through over its `ControlPort`. - -### Deliberately not here yet - -- **The source (`SRC-1`).** P61 is a damping-wiggler beamline (`source: superconducting-wiggler`); the wiggler parameters are not exposed in this registry slice. -- **The Large Volume Press (`PRESS-1`).** P61A's press is not in the registry slice; would reuse the catalog `PressureCell` Family when exposed. -- **The motor-bank axis roles (`GROUP-1`).** The `eh_mot*` bank carries no per-axis role; grouped as one stage. -- **The detectors (`DET-1`).** The Ge energy-dispersive detector and any area detector are not in the registry slice; carried as a pending placeholder. -- **The handle freshness (`CTRL-1`).** The OnlineXML branch is `debian/stretch` (unusual for the set); some handles may lag the live Tango database. -- **The diffraction Method (`TECH-1`).** Whether it enters CORA's catalog is an owner decision; the Practice renders unlinked, pending. -- **The PSS permit signals (`PSS-1`).** Not in the OnlineXML; carried pending, not invented. -- **The simulated devices and full asset-tree scenarios.** No `test_p61_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the P61 team to confirm before the model can be trusted.* - -P61 was reverse-engineered from P61's own public OnlineXML device registry ([gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p61](https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p61), branch `debian/stretch`) and a verified research brief, not from a live connection. The P61 registry is thin: one generic motor bank, no source / press / detectors exposed. P61 is CORA's seventeenth PETRA III beamline, the high-energy white-beam wiggler beamline. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: a single experiment hutch (the registry exposes one host), and the P61A / P61B branch split? | A `p61-eh2` experiment hutch, from the OnlineXML `hasnp61eh2` host. | The Enclosure grouping. | -| GROUP-1 | Nice-to-have | The per-axis roles of the `eh_mot*` motor bank. | Grouped as one `LinearStage` stage carrying the bank prefix; per-axis roles pending. | The Asset boundaries. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-go-live | The damping-wiggler source parameters (period, field), and whether the beam is white or monochromated per branch. | A damping wiggler delivering high-energy white beam; parameters pending. | The source Asset detail. | - -### Sample endstation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| PRESS-1 | Blocks-build | The Large Volume Press (P61A): its press / anvil control, and whether it should bind the catalog `PressureCell` Family. | A pending press; would reuse the catalog `PressureCell` (graduated across 13-id and P02) when exposed. | The press modelling. | - -### The detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The energy-dispersive (Ge solid-state) detector, and any area detectors, absent from this registry slice. | A pending `EnergyDispersiveSpectrometer` placeholder; the chain not invented. | The detector modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | The Tango device handles per P61 device, and whether the OnlineXML `debian/stretch` branch (unusual for the set) matches the live Tango database. | The handles read from the public OnlineXML, carried pending; the floor is Tango + Sardana. | Binding each Asset's control handle. | -| PSS-1 | Blocks-go-live | The DESY personnel-safety permit signals, the white-beam shielding / interlock, and the photon / front-end shutters (absent from the OnlineXML). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent and the cooling / beam supplies. | Photon beam, cooling water, vacuum. | The Supply observations. | -| GOV-1 | Nice-to-have | The DESY operator pool and safety-review structure (site-level). | Carried pending on the PETRA III Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Does energy-dispersive diffraction enter CORA's catalog as a Capability / Method? | Deferred: carried as a pending Practice reusing the `energy_dispersive_diffraction` slug; none coined. | The technique Capability. | diff --git a/docs/deployments/p64/notes.md b/docs/deployments/p64/notes.md deleted file mode 100644 index 9c9393f635c..00000000000 --- a/docs/deployments/p64/notes.md +++ /dev/null @@ -1,114 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of P64 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../petra-iii/index.md#the-techniques-adapted-here) is how a facility adapts it. P64's XAS technique earns no catalog Method today, so the Method below renders unlinked and is carried pending until a technique enters scope (`TECH-1`). - -### Advanced X-ray absorption spectroscopy - -P64 scans the incident energy across an absorption edge (the Tsai DCM coupled to the undulator) and reads the absorption in transmission (the Lambda detectors) and, for dilute samples, in fluorescence on the large [multi-element detector](detector.md), measuring EXAFS / XANES. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| X-ray absorption spectroscopy (EXAFS / XANES) | `xas_spectroscopy` | the coupled mono + undulator energy scan read against transmission / multi-element fluorescence; reuses the `xas_spectroscopy` slug BMM / ISS / i20-1 / P04 share, a further consumer (`TECH-1`) | - -### A high-rate fluorescence EXAFS beamline on familiar vocabulary - -P64 is the advanced half of the PETRA III XAS pair (with the applied [P65](../p65/index.md)). Its distinguishing capability is dilute, high-rate fluorescence detection via the large multi-element SIS3302 detector, but it coins no new vocabulary: it reuses the `xas_spectroscopy` slug already carried pending across the fleet, and its instrument anatomy reuses existing Families (the `Monochromator`, the `Mirror` pair, the `Camera` Lambda detectors, the `EnergyDispersiveSpectrometer` fluorescence detector). The continuous energy fly-scan is a control-plane detail, not a new Method. - -### Not modelled yet - -The concrete acquisition recipes (the QEXAFS / step-scan energy sequences, the multi-element detector deadtime handling, the DAC high-pressure XAS) are not written yet; they join as the deployment approaches the point where CORA drives P64. Whether `xas_spectroscopy` enters CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at P64, and the trust shape that will gate it. First cut.* - -Governance at P64 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), 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). - -P64 is CORA's ninth PETRA III beamline: the DESY operator pool and the safety-review structure are carried pending on the [PETRA III Site](../petra-iii/index.md#safety-and-governance), shared across the facility's beamlines, until DESY staff confirm them (`GOV-1`). P64 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives P64, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. The OnlineXML carries beamline devices, not the personnel-safety interlock leaves, so the Enclosure permit signals and the interlock structure are carried pending and are not invented here (`PSS-1`). P64 shares its optics hutch with the applied-XAS sibling [P65](../p65/index.md), so the optics-enclosure access state couples to the neighbouring beamline, part of the `PSS-1` question. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives P64, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's P64 content lives, its dilute high-rate fluorescence EXAFS via a large multi-element detector, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at P64 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes P64 new - -P64 is a ninth beamline at an existing Site, and the advanced half of the PETRA III XAS pair (with the applied [P65](../p65/index.md), sharing the optics host). Its distinguishing capability is dilute, high-rate fluorescence EXAFS via a large multi-element detector. At the modelling level it is a reuse-and-reinforce deployment: nothing new at the vocabulary level. - -### No new families - -P64 coins no new Family. The undulator binds `InsertionDevice`; the Tsai mono `Monochromator`; the mirrors `Mirror`; the slits `Slit`; the sample / picomotor stages `LinearStage`; the Lambda detectors `Camera`; the multi-element fluorescence detector `EnergyDispersiveSpectrometer`. Nothing in the catalog changes. The 104-channel SIS3302 is grouped into one `EnergyDispersiveSpectrometer` Asset, not 104 Assets. - -### The control plane - -P64 sits on the PETRA III Tango device floor with Sardana as the scan layer, the same as the other PETRA III beamlines. Its distinctive devices are the Tsai-geometry DCM with its coupled undulator energy axis, the NewFocus picomotors, and the multi-element SIS3302 fluorescence detector. The handles are read from P64's public OnlineXML registry and carried confirm (`CTRL-1`); the optics host is shared with P65. The XAS acquisition (the continuous energy fly-scan read against the multi-element fluorescence) runs as a Sardana macro; that orchestration is the seam CORA's edge replaces or drives through over its `ControlPort`, the same shape as the BMM / ISS XAS seams. - -### Deliberately not here yet - -- **The undulator parameters (`SRC-1`).** The energy axis is read; the period is not exposed. -- **The optics detail (`OPT-1`).** The Tsai DCM crystal cut and the mirror coatings are carried confirm-pending. -- **The sample-bank axis roles (`GROUP-1`).** The `exp_mot` / `dac_*` bank carries no per-axis role; grouped, with the DAC sub-stage noted. -- **The detector detail (`DET-1`).** The multi-element element count, the deadtime / ROI handling, and the transmission ion chambers are named, not fully bound. -- **The handle freshness (`CTRL-1`).** The OnlineXML branch is `debian/jessie`; some handles may lag the live Tango database. -- **`xas_spectroscopy` Method (`TECH-1`).** Whether XAS enters CORA's catalog is an owner decision; the Practice renders unlinked, pending. -- **The PSS permit signals (`PSS-1`).** Not in the OnlineXML; carried pending, not invented. -- **The simulated devices and full asset-tree scenarios.** No `test_p64_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the P64 team to confirm before the model can be trusted.* - -P64 was reverse-engineered from P64's own public OnlineXML device registry ([gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p64](https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p64), branch `debian/jessie`) and a verified research brief, not from a live connection. The registry carries real Tango device names and control handles, but no crystal cuts, detector element count, or energy calibration. P64 is CORA's ninth PETRA III beamline and the advanced half of the PETRA III XAS pair. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: an optics hutch feeding the experiment endstation, sharing the optics with P65? | A `p64-oh` optics hutch and a `p64-eh` endstation. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The undulator period and parameters. | An undulator; energy axis read, period pending. | The source Asset detail. | -| GROUP-1 | Nice-to-have | The per-axis roles of the sample bank (`exp_mot*`, `dac_*`) and the picomotor assignments. | Grouped as `LinearStage` Assets carrying the bank prefix; per-axis roles pending. | The sample-stage Asset boundaries. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| OPT-1 | Blocks-go-live | The Tsai DCM crystal cut and energy range, and the two mirror coatings / roles. | A Tsai `Monochromator` and two `Mirror`s; physical detail pending. | The optics modelling. | - -### The detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The multi-element fluorescence detector element count (the 104-channel SIS3302), the deadtime / ROI handling, the two Lambda 750k roles, and the transmission ion chambers. | A grouped `EnergyDispersiveSpectrometer` + two `Camera` Lambdas; element count and ion chambers pending. | The detector modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | The Tango device handles per P64 device, the shared P64 / P65 optics host, and whether the OnlineXML `debian/jessie` branch matches the live Tango database. | The handles read from the public OnlineXML, carried pending; the floor is Tango + Sardana; optics shared with P65. | Binding each Asset's control handle. | -| PSS-1 | Blocks-go-live | The DESY personnel-safety permit signals, the shared-optics coupling with P65, and the photon / front-end shutters (absent from the OnlineXML). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent and the cooling / beam supplies. | Photon beam, cooling water, vacuum. | The Supply observations. | -| GOV-1 | Nice-to-have | The DESY operator pool and safety-review structure (site-level). | Carried pending on the PETRA III Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Does X-ray absorption spectroscopy enter CORA's catalog as a Capability / Method? | Deferred: carried as a pending Practice reusing the `xas_spectroscopy` slug BMM / ISS / i20-1 / P04 share; none coined. | The technique Capability. | diff --git a/docs/deployments/p65/notes.md b/docs/deployments/p65/notes.md deleted file mode 100644 index cee2f522c4f..00000000000 --- a/docs/deployments/p65/notes.md +++ /dev/null @@ -1,118 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of P65 is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../petra-iii/index.md#the-techniques-adapted-here) is how a facility adapts it. P65's XAS technique earns no catalog Method today, so the Method below renders unlinked and is carried pending until a technique enters scope (`TECH-1`). - -### Applied X-ray absorption spectroscopy - -P65 scans the incident energy across an absorption edge (the channel-cut DCM) and reads the absorption in transmission (ion chambers) and fluorescence, for routine applied EXAFS / XANES (catalysis, batteries, environmental science). - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| X-ray absorption spectroscopy (EXAFS / XANES) | `xas_spectroscopy` | the CDCM energy scan read against transmission / fluorescence; reuses the `xas_spectroscopy` slug BMM / ISS / i20-1 / P04 / P64 share, a further consumer (`TECH-1`) | - -### The applied half of the XAS pair - -P65 is the applied / high-throughput half of the PETRA III XAS pair, the sibling of the advanced [P64](../p64/index.md). Where P64 specialises in dilute high-rate fluorescence with a large multi-element detector, P65 serves routine transmission + fluorescence EXAFS. Both reuse the `xas_spectroscopy` slug; neither coins a new Family or Method. P65's instrument anatomy is deliberately thin (a `Monochromator` energy axis, `LinearStage` sample bank, `Slit`, `Table`), matching what the registry exposes. - -### Not modelled yet - -The concrete acquisition recipes (the step / continuous energy scans, the ion-chamber / fluorescence detection chain, the sample-changer throughput loop) are not written yet; they join as the deployment approaches the point where CORA drives P65. Whether `xas_spectroscopy` enters CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at P65, and the trust shape that will gate it. First cut.* - -Governance at P65 follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [PETRA III Site](../petra-iii/index.md#safety-and-governance), 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). - -P65 is CORA's tenth PETRA III beamline: the DESY operator pool and the safety-review structure are carried pending on the [PETRA III Site](../petra-iii/index.md#safety-and-governance), shared across the facility's beamlines, until DESY staff confirm them (`GOV-1`). P65 is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives P65, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. The OnlineXML carries beamline devices, not the personnel-safety interlock leaves, so the Enclosure permit signals and the interlock structure are carried pending and are not invented here (`PSS-1`). P65 shares its optics hutch with the advanced-XAS sibling [P64](../p64/index.md), so the optics-enclosure access state couples to the neighbouring beamline, part of the `PSS-1` question. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives P65, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's P65 content lives, a deliberately thin applied / high-throughput XAS model, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at P65 | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes P65 new - -P65 is a tenth beamline at an existing Site, and the applied / high-throughput half of the PETRA III XAS pair (with the advanced [P64](../p64/index.md), sharing the optics host). Its science is routine transmission + fluorescence EXAFS / XANES. At the modelling level it is a reuse-and-reinforce deployment: nothing new at the vocabulary level, and a deliberately thin model matching its sparse registry slice. - -### No new families (a thin, honest model) - -P65 coins no new Family. The undulator binds `InsertionDevice`; the CDCM energy axis `Monochromator`; the stages `LinearStage`; the slit `Slit`; the table `Table`; the detection placeholder `FluxMonitor`. Nothing in the catalog changes. The P65 registry slice exposes little beyond the energy axis and the sample bank, so the detection chain is carried as a pending placeholder rather than invented (`DET-1`), the same model-what-the-source-supports posture as P11 and the thinner reverse-engineered scaffolds. - -### The control plane - -P65 sits on the PETRA III Tango device floor with Sardana as the scan layer, the same as the other PETRA III beamlines, sharing the optics host (`hasnp64`) with P64. The handles are read from P65's public OnlineXML registry and carried confirm (`CTRL-1`). The XAS acquisition (the CDCM energy scan read against transmission / fluorescence) runs as a Sardana macro; that orchestration is the seam CORA's edge replaces or drives through over its `ControlPort`, the same shape as the BMM / ISS XAS seams. - -### Deliberately not here yet - -- **The undulator parameters (`SRC-1`).** The energy axis is read; the period is not exposed. -- **The optics detail (`OPT-1`).** The CDCM crystal cut and the optics-bank breakdown are carried confirm-pending. -- **The bank axis roles (`GROUP-1`).** The `oh_*`, `fe_*`, and `a2_*` banks carry no per-axis role; grouped as stage Assets. -- **The detection chain (`DET-1`).** The ion chambers and fluorescence detector are not in the registry slice; carried as a pending `FluxMonitor` placeholder. -- **The host mapping (`HOST-1`).** The energy / optics report on the shared P64 host; modelled in the P65 optics enclosure with the host flagged. -- **The dummy stubs (`STUB-1`).** The `a2_dmy*` placeholder devices are noted, not modelled. -- **The handle freshness (`CTRL-1`).** The OnlineXML branch is `debian/jessie`; some handles may lag the live Tango database. -- **`xas_spectroscopy` Method (`TECH-1`).** Whether XAS enters CORA's catalog is an owner decision; the Practice renders unlinked, pending. -- **The PSS permit signals (`PSS-1`).** Not in the OnlineXML; carried pending, not invented. -- **The simulated devices and full asset-tree scenarios.** No `test_p65_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the P65 team to confirm before the model can be trusted.* - -P65 was reverse-engineered from P65's own public OnlineXML device registry ([gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p65](https://gitlab.desy.de/petra-iii-debian-packages/python-nxstools-extras-p65), branch `debian/jessie`) and a verified research brief, not from a live connection. The P65 registry slice is thin: an energy axis, a sample bank, a slit / table, the undulator. The XAS detection is not exposed. P65 is CORA's tenth PETRA III beamline and the applied half of the PETRA III XAS pair. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: an optics hutch (shared with P64) feeding the experiment endstation? | A `p65-oh` optics hutch and a `p65-eh` endstation. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The undulator period and parameters. | An undulator; energy axis read, period pending. | The source Asset detail. | -| GROUP-1 | Nice-to-have | The per-axis roles of the banks (`oh_*`, `fe_*`, `a2_*`). | Grouped as stage Assets carrying the bank prefix; per-axis roles pending. | The Asset boundaries. | -| STUB-1 | Nice-to-have | The `a2_dmy*` dummy stubs: test / placeholder devices, or real channels? | Noted as dummy stubs, not modelled. | The stub status. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| OPT-1 | Blocks-go-live | The CDCM crystal cut and energy range, and the optics-bank breakdown. | A channel-cut `Monochromator` energy axis and grouped optics stages; physical detail pending. | The optics modelling. | -| HOST-1 | Nice-to-have | The CDCM energy / optics report on the shared P64 host (`hasnp64`). How is the shared optics split between P64 and P65? | The P65 optics are homed in `p65-oh`; the host is flagged. | The shared-optics mapping. | - -### The detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The XAS detection chain: the transmission ion chambers (I0 / I1 / I2), the fluorescence detector model, and the digitizer (absent from this registry slice). | A pending `FluxMonitor` placeholder; the chain not invented. | The detector modelling. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | The Tango device handles per P65 device, the shared P64 / P65 optics host, and whether the OnlineXML `debian/jessie` branch matches the live Tango database. | The handles read from the public OnlineXML, carried pending; the floor is Tango + Sardana; optics shared with P64. | Binding each Asset's control handle. | -| PSS-1 | Blocks-go-live | The DESY personnel-safety permit signals, the shared-optics coupling with P64, and the photon / front-end shutters (absent from the OnlineXML). | Permit leaves and shutters to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent and the cooling / beam supplies. | Photon beam, cooling water, vacuum. | The Supply observations. | -| GOV-1 | Nice-to-have | The DESY operator pool and safety-review structure (site-level). | Carried pending on the PETRA III Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | Does X-ray absorption spectroscopy enter CORA's catalog as a Capability / Method? | Deferred: carried as a pending Practice reusing the `xas_spectroscopy` slug; none coined. | The technique Capability. | diff --git a/docs/deployments/pdf/notes.md b/docs/deployments/pdf/notes.md deleted file mode 100644 index 54fb4a341b2..00000000000 --- a/docs/deployments/pdf/notes.md +++ /dev/null @@ -1,110 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at PDF: high-energy total-scattering and powder-diffraction techniques, each a [Catalog](../../catalog/methods.md) Method. PDF is the twin of [XPD](../xpd/notes.md#techniques) and follows its deferral exactly, after Diamond [i11](../i11/notes.md#techniques) and [i15-1](../i15-1/notes.md#techniques).* - -PDF's techniques are high-energy total scattering and powder diffraction: a high-energy beam through a powder or capillary sample onto a large area detector, with the sample-to-detector distance setting the accessible Q. These Methods are new to CORA's imaging- and spectroscopy-heritage catalog. As at XPD, the Methods below render unlinked and are carried pending until the owner-scope decision (TECH-1) brings them into the catalog. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Total scattering / PDF | `total_scattering` | rapid-acquisition pair distribution function: a near and a far detector distance merged to high Q (DIST-1); Method not yet in catalog, shared with i15-1 and XPD | -| Powder diffraction | `powder_diffraction` | the same high-energy beam and detector for Rietveld-quality powder patterns; Method not yet in catalog, shared with i11 and XPD | -| Alignment | [`alignment`](../../catalog/methods.md) | beam, monochromator, mirror, and slit tuning; reuses the existing Method | - -Both techniques need the [sample spinner and environment](sample.md) and the [area detectors](detector.md); the exposure is gated by the fast shutter, with the two-distance merge sequenced in software (DIST-1). - -### Why the Methods stay deferred - -Diamond i11 (powder diffraction) and i15-1 (total scattering / PDF) opened the question of whether these Methods enter CORA's catalog (TECH-1), and `main` deliberately left them pending: the concrete acquisition recipes (energies, distances, exposures, the near / far merge) join as the deployment approaches the point where CORA drives the beamline. PDF reinforces both Methods at a second NSLS-II endstation without coining either, the same earn-the-abstraction discipline XPD follows. Because the defining Methods are not in the catalog, PDF records **no Practice** in the [NSLS-II Site](../nsls2/index.md), exactly as XPD records none; the binding lands when the Method does. - -The PDF reduction itself (the azimuthal integration of the detector frames and the Fourier transform of the structure function into the pair distribution function G(r)) is `ComputePort` work, not a beamline Method: the beamline takes the frames, CORA's compute leg turns them into the result. - -## Governance - -*Who may act at PDF and the trust shape CORA applies. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority.* - -People and agents are facility principals at the [NSLS-II Site](../nsls2/index.md); on the beamline they surface through the actions they take. The human roster is not known from the profile collection (GOV-1), so the principals are the design shape, not a registered list. - -### Who acts - -CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the NSLS-II Site. A PDF beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. - -### The trust boundary - -CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may change the incident energy, move a detector tower to a new distance, set a sample-environment temperature ramp, override a caution, or commit a calibration. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer. The NSLS-II proposal and cycle are a fact CORA's Campaign uses for custody. - -### In-situ and high-throughput runs - -A variable-temperature total-scattering series or a high-throughput sample queue can run long and unattended, which is where CORA's trust shape earns its keep: the engine holds the temperature ramp and the acquisition while the trust boundary bounds what may change mid-series and who may intervene. If an autonomous Agent were added to steer acquisition (choose the next temperature point, decide when the pattern statistics are sufficient, trigger a PDF reduction to check the result), it would be a facility principal scoped at the Site, governed by the same trust boundary, with each choice recorded as a [Decision](../../architecture/modules/decision/index.md). None is declared yet. - -## Model - -*The developer's by-kind index: where each CORA aggregate's PDF content lives. It hosts no content of its own. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC -[modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at PDF | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [the stage pages](source.md) (`EnergyAxis`) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [The beamline](index.md#enclosures) (28-ID-1-A optics, 28-ID-1-B endstation) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### Deliberately not here yet - -This is a design-phase scaffold (descriptor + docs), mirroring its twin [XPD](../xpd/notes.md#model) and the other reverse-engineered deployments. Left out on purpose: - -- **No new Family.** PDF is a reuse-and-reinforce deployment: the flat-panel and pixel detectors bind `Camera`, the photodiode `FluxMonitor`, the thermal cluster `TemperatureController`, the side-bounce mono `Monochromator`, the focusing mirror `Mirror`, the spinner `Goniometer`, the slits `Slit`, the fast shutter `Shutter`, the beamstops `BeamStop`, the detector and sample-environment stages `LinearStage`, the master energy a `PseudoAxis`. Nothing graduates and the catalog is unchanged. -- **The held loose family.** The `StorageRing` current readback is a loose supply observation (machine state), never an Asset Family. -- **No new Capability or Method.** Total scattering / PDF and powder diffraction sit on the deferred `total_scattering` / `powder_diffraction` Methods Diamond i11 and i15-1 left pending (`TECH-1`); PDF reinforces them at a second NSLS-II endstation without coining either, and records no Practice until they land. The PDF reduction (azimuthal integration and the Fourier transform to G(r)) is `ComputePort` work, not a Method. -- **The gas-handling and humidity rig.** Present in the profile collection but carried deferred (`ENV-1`): a design-phase scaffold models the thermal environment that is settled (`TemperatureController`) and defers the in-situ gas / humidity actuators until they earn modelling, the same discipline the other deployments follow. -- **Operations and experiment views, integration scenarios, vendor Models.** A runbook and registered Assets for a beamline CORA does not yet drive would be invention; they land when the design firms and the team confirms. - -## Open questions - -*What CORA needs the PDF team to confirm. This model is reverse-engineered from public open source (the [`NSLS2/pdf-profile-collection`](https://github.com/NSLS2/pdf-profile-collection) profile collection and the [`NSLS2/pdftools`](https://github.com/NSLS2/pdftools) device library): the EPICS PVs are read from them, but vendor identities, physical positions, and the detector geometry are not. Each row is a fact the beamline team owns. It is a delete-on-answer queue.* - -Priorities: `Blocks-build`, `Blocks-go-live`, `Nice-to-have`. - -### Source and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Nice-to-have | The 28-ID source identity and parameters. No source PV is in the profile collection; CORA infers the shared 28-ID damping wiggler from facility knowledge. | An insertion device, the shared damping wiggler, identity-only. | The InsertionDevice settings. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit-leaf PVs. Only the fast and photon shutters are in source. | The permit signal is a confirm note, not a guessed PV. | The Enclosure permit signals. | -| MACHINE-1 | Nice-to-have | The storage-ring state PDF reads (current, fill, status). | Observe-only machine state, a loose `StorageRing`; the exact PVs beyond `ring_current` pending. | The machine-state observation. | -| GOV-1 | Nice-to-have | The NSLS-II operator pool and safety-review structure (site-level, shared across the beamlines). | Carried pending on the NSLS-II Site, not instantiated per beamline. | The governance principals. | - -### Optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MONO-1 | Nice-to-have | The side-bounce monochromator crystal cut, reflection, and energy range. The device (`Mono:SBM`) is confirmed. | A single high-energy Laue `Monochromator` Asset; cut and range blank. | The Monochromator settings. | -| ENERGY-1 | Nice-to-have | Is PDF always fixed-energy per experiment, or does any routine scan energy as the measurement? | Fixed-energy; energy scan deferred. | The energy Capability decision. | - -### Sample and environment - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| STAGE-1 | Blocks-go-live | The full spinner and analyzer goniohead axis set, and whether the sample orientation warrants a `Goniometer` plus an Assembly (the i11 precedent). | A `Goniometer` spinner; the analyzer noted, the Assembly deferred. | The sample-stage modelling. | -| TEMP-1 | Nice-to-have | Which thermal units are live (the cs800 cryostream make, the Lakeshore cryostat, the Linkam furnace) and their ranges. | One thermal-environment `TemperatureController` Asset; units blank. | The sample-environment roster. | -| ENV-1 | Nice-to-have | The gas-handling and humidity rig (flow valves, residual-gas analyzer, humidity) is present in source but not modelled. Does it warrant a settable actuator Asset (the loose `FlowController` family)? | Deferred; the thermal cluster is modelled, the gas / humidity rig noted. | The in-situ environment modelling. | - -### Detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | Which detectors are live (the two PerkinElmer panels, the Pilatus) and which serves which role. | Both Cameras; PerkinElmer primary; Pilatus alongside. | The detector roster. | -| DIST-1 | Blocks-go-live | The two-detector / two-distance geometry: the near and far distances, which tower is static vs moving, and how the panels merge for the PDF Q-range (the `TwoDetectors` plan). | Two `LinearStage` towers; the merge deferred. | The detector geometry and Q-range. | -| DIAG-1 | Nice-to-have | The background-photodiode / flux channel detail. | A read-only `FluxMonitor` probe; channel map blank. | The FluxMonitor binding. | - -### Controls and technique scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DRIVE-1 | Blocks-go-live | The motion-controller box models, firmware, IPs behind the EPICS motor records. | One `MotionController` family bound (`EndstationMotionController`), specifics blank. | The MotionController Models. | -| TECH-1 | Blocks-go-live | Do the total-scattering and powder-diffraction Methods enter CORA's catalog, or stay deferred? This is the same owner-scope decision Diamond i11 / i15-1 and XPD opened. | Methods deferred (rendered unlinked), no Practice recorded. | The powder / PDF Method scope. | diff --git a/docs/deployments/six/notes.md b/docs/deployments/six/notes.md deleted file mode 100644 index af4d0710c84..00000000000 --- a/docs/deployments/six/notes.md +++ /dev/null @@ -1,118 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of SIX 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. SIX's technique is resonant inelastic X-ray scattering, a soft X-ray scattering method new to CORA's imaging-heritage catalog, so the Method below renders unlinked and is carried pending until a technique enters scope (`TECH-1`). - -### Resonant inelastic X-ray scattering - -RIXS tunes the incident soft X-ray energy to an absorption edge and measures the energy and momentum the sample exchanges with the scattered photon, so the measurement is a spectrum of the emitted light dispersed by the spectrometer arm onto the photon-counting camera. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Resonant inelastic X-ray scattering | `resonant_inelastic_scattering` | the incident energy is set on the [grating monochromator](source.md); the emitted spectrum is dispersed by the [spectrometer arm](detector.md) and recorded on the photon-counting camera; Method not yet in catalog | - -It needs the [grating monochromator](source.md) (the incident-energy and resolution chain, exit slit included), the [UHV cryostat sample](sample.md), and the [RIXS spectrometer arm and camera](detector.md). The arm scattering angle selects the momentum transfer. - -### Not modelled yet - -The concrete acquisition recipes (energy maps, emission-spectrum exposures, the arm-angle and resolution settings) are not written yet; they join as the deployment approaches the point where CORA drives SIX. Whether RIXS enters CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); soft X-ray is a new regime for the fleet (see [Open questions](#open-questions) for the world-facts to confirm first). - -## Governance - -*Who will act at SIX, and the trust shape that will gate it. First cut.* - -Governance at SIX 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). - -SIX 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`). - -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. SIX adds hazard classes the hard X-ray fleet does not carry: ultra-high vacuum and the cryostat's cryogens at the sample environment, which 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 SIX, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's SIX content lives, the loose families this first soft X-ray deployment introduced and has since graduated, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at SIX | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### New loose families - -SIX is CORA's first soft X-ray beamline, a new optics, detector, and sample-environment regime. It introduced three device classes no hard X-ray catalog Family covered. All three have since **graduated**: `GratingMonochromator` became a catalog Family once CSX (NSLS-II 23-ID) earned the soft X-ray PGM, `Manipulator` once ESM (NSLS-II 21-ID) earned the UHV sample manipulator, and `SpectrometerArm` once ESRF ID32 (the RIXS and XES arms) and ID28 (the multi-analyzer arm) earned the dispersive spectrometer arm SIX coined (the Monochromator, SampleManipulator, and RIXSSpectrometer here bind them). - -| Family | Presents | What it is | Status | -| --- | --- | --- | --- | -| `GratingMonochromator` | Positioner | the soft X-ray plane-grating monochromator (PGM): premirror at a fixed-focus c-value plus an interchangeable grating, no Bragg crystal | graduated (SIX + CSX, `MONO-1`) | -| `SpectrometerArm` | Positioner | the meters-long energy-dispersive RIXS arm (bridge truss + optics chamber + detector chamber) | graduated (SIX + ID32 RIXS/XES + ID28) | -| `Manipulator` | Positioner | the UHV cryostat sample manipulator (x/y/z/theta) | graduated (SIX + ESM, `SAMPLE-1`) | - -The catalog `Monochromator` is deliberately not stretched to cover the PGM: its note describes a crystal / multilayer Bragg monochromator, and a plane-grating mono has no Bragg crystal, selects energy by grating pitch and translation, and takes its resolution from the exit slit, so `GratingMonochromator` is a distinct Family rather than a settings variant. Likewise `SpectrometerArm` is distinct from the catalog `EnergyDispersiveSpectrometer` (a point Sensor, not a multi-chamber dispersive arm); it presents the `Positioner` Role (an arm that positions a dispersing grating and carries a `Camera` at its focus). - -### Deliberately not here yet - -- **The RIXS-camera Family question.** The RIXS camera does on-detector single-photon centroiding and isolinear curvature correction, a photon-counting regime distinct from an integrating-frame area detector. It is modelled here as the catalog `Camera` with that behavior carried as a note; whether the photon-counting pipeline warrants its own Family is `RIXS-2`, deferred (a `Camera`-with-settings is the lower-risk first cut). - -- **The EPU polarization DOF.** The elliptically-polarizing undulator adds a phase (polarization) axis beyond gap. It binds the catalog `InsertionDevice` with the polarization carried as a setting; whether the EPU phase warrants a distinct family is deferred until a second EPU beamline (`SRC-1`). - -- **The legacy end-station PGM.** The profile collection carries a discarded second monochromator instance (`Mono:2` / `espgm`) and a dead `PGMjoe` class; only the live `Mono:1` PGM is modelled. - -- **The RIXS Method.** Whether RIXS enters CORA's catalog is an owner decision; the Practice renders unlinked, pending (`TECH-1`). - -- **The simulated devices and full asset-tree scenarios.** No `test_six_*.py` registers the SIX 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). - -## Open questions - -*What CORA needs the SIX team to confirm before the model can be trusted.* - -SIX was reverse-engineered from the beamline's own bluesky profile collection ([NSLS2/six-profile-collection](https://github.com/NSLS2/six-profile-collection)), so the control handles on the [device pages](index.md) are the beamline's real PVs, read from the `startup/*.py` files rather than confirmed by staff. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet), including the new loose families). 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 | -| --- | --- | --- | --- | --- | -| TOPO-1 | Blocks-build | Does SIX share a canted straight with a sibling beamline, or run off its own undulator in series? | One root Unit Asset `SIX` on its own EPU straight. | The source topology in the [descriptor](index.md). | -| ENC-1 | Blocks-go-live | Are the PV zones `XF:02IDA/B/C/D` four separate shielded hutches or beam zones within fewer hutches? | Four enclosures, one per zone. | The Enclosure grouping. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the EPICS PV handles read from the six-profile-collection current and correct? | The handles in the descriptor are taken from the profile collection 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 photon shutters are `XF:02ID-PPS{Sh:FE}` / `XF:02IDA-PPS{PSh}` / `XF:02IDB-PPS{PSh}`. | The Enclosure permit signals. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-go-live | The EPU (`SR:C02-ID:G1A{EPU:1}`): type, period, and the polarization (phase) model. | One `InsertionDevice` Asset; the phase axis carried as a setting. | The insertion-device spec. | -| MONO-1 | Blocks-build | The plane-grating monochromator: energy range, the three grating line densities (500 / 1200 / 1800 l/mm), and the c-value (cff) model. | A `GratingMonochromator` Asset (catalog Family) with energy / cff / grating-pitch / premirror-pitch / grating-translation axes. | The monochromator energy and grating model. | -| OPT-1 | Nice-to-have | The mirrors (M1, M3, M4, M5, M6): coatings, stripes, and the hexapod / bender axis roles. | `Mirror` Assets with the config's PV roots; coatings unconfirmed. | The mirror specs. | -| OPT-2 | Nice-to-have | The baffle slits, the exit slit, and the M5 mask: the internal axis maps. | `Slit` / `Aperture` Assets with base PVs; per-blade axes partial. | The slit and aperture axis maps. | - -### RIXS endstation - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| RIXS-1 | Blocks-build | The spectrometer-arm geometry: the bridge truss (`BT:1`), the in-arm optics chamber (`3AA:1`), and the detector chamber (`DC:1`): which axis is the arm scattering angle, the dispersion, and the detector distance, and how the arm pivots about the sample chamber. | One `SpectrometerArm` Asset (catalog Family, graduated) with the three chambers' axes; the sample chamber as the pivot. | The spectrometer geometry and whether it composes into an Assembly. | -| RIXS-2 | Nice-to-have | The RIXS camera (`XF:02ID1-ES{RIXSCam}`): the sensor, the photon-counting / centroiding pipeline, and the curvature correction. | One `Camera` Asset; the centroiding behavior carried as a note. | The detector model and Family decision. | -| DET-1 | Nice-to-have | The counting scaler, the Femto electrometer, and the camera readout: which channels are I0 versus signal. | `FluxMonitor` Assets plus the `Camera`. | The detector channel map. | -| DIAG-1 | Nice-to-have | The DIAGON diagnostic (`XF:02IDA-OP{Diag:1`): is it a polarization diagnostic, and what does it report? | One `GenericProbe` Asset (placeholder classification). | The diagnostic classification and Family. | - -### Sample environment and supplies - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SAMPLE-1 | Blocks-go-live | The UHV cryostat manipulator (`SC:1-Cryo:S1_B`) and the Lakeshore controller: the cryo temperature range, the base pressure, and any load-lock / sample-transfer mechanism. | A `Manipulator` Asset (catalog Family, x/y/z/theta) plus a `TemperatureController`. | The sample-environment model. | -| SUP-1 | Nice-to-have | The vacuum and cryogen supplies the UHV optics, the spectrometer arm, and the cryostat draw on. | Photon beam, cooling water, and vacuum carried in the descriptor. | The Supply records. | diff --git a/docs/deployments/smi/notes.md b/docs/deployments/smi/notes.md deleted file mode 100644 index 38e7cd7a615..00000000000 --- a/docs/deployments/smi/notes.md +++ /dev/null @@ -1,109 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at SMI: scattering techniques, each a [Catalog](../../catalog/methods.md) Method. SMI is the NSLS-II twin of the Diamond [I22](../i22/notes.md#techniques) (SAXS / WAXS) beamline, and it follows i22's deferral exactly, adding the grazing-incidence variants.* - -SMI's techniques are small- and wide-angle scattering, the science domain Diamond i22 brought to CORA. As there, the Methods below render unlinked and are carried pending until the owner-scope decision (TECH-1) brings them into the catalog. - -| Technique | Mode | Notes | -| --- | --- | --- | -| Small-angle scattering (SAXS) | monochromatic, long camera | low-Q on the SAXS Pilatus 2M; the i22 Capability, new Capability pending (TECH-1) | -| Wide-angle scattering (WAXS) | monochromatic, swing arc | wide-Q on the WAXS Pilatus 900KW; the i22 Capability, new Capability pending (TECH-1) | -| Simultaneous SAXS+WAXS | both detectors at once | coordinated Runs under one Campaign, the routine mode, not a third technique (TECH-1) | -| Grazing-incidence (GISAXS / GIWAXS) | shallow incidence, reflected geometry | the same scattering Methods with the sample at a grazing angle and the WAXS arc swung; a sample-orientation variant (TECH-1) | - -All the scattering techniques need the [grazing-incidence sample stack](sample.md) and the [SAXS / WAXS detectors](detector.md); the fast shutter gates the exposure. - -### Why the Capabilities stay deferred - -Diamond i22 opened the question of whether the SAXS and WAXS Capabilities enter CORA's catalog (TECH-1), and `main` deliberately left them pending: SAXS and WAXS do not reduce to the imaging-heritage `tomography` / `acquisition` Capabilities, and a modelling exercise does not mint cross-facility vocabulary until a technique enters a real scope. The device Roles already exist (the Pilatus detectors present the Detector Role, the flux monitor presents Sensor), so what is new is the science Capability, not a device shape. SMI reinforces the case for both at a second facility without coining either, the same earn-the-abstraction discipline the deferred `scanning` (HXN), `energy_scan` (BMM), and powder / total-scattering (XPD) Capabilities follow. - -Grazing incidence (GISAXS / GIWAXS) is the genuinely new wrinkle SMI adds over i22, but it is a sample-orientation variant of the same scattering Capability (the sample sits at a shallow angle, the WAXS arc swings), not a new Capability of its own. Simultaneous SAXS+WAXS is coordinated Runs under one Campaign over a shared trigger, the same way 7-BM and i22 model parallel detector reads, not a combined technique. Because the defining Capabilities are not in the catalog, SMI records **no Practice** in the [NSLS-II Site](../nsls2/index.md#the-techniques-adapted-here); the binding lands when the Capability does. - -The azimuthal integration and reduction (turning the 2D scattering frames into I(Q) curves and GISAXS maps) are `ComputePort` work, not beamline Methods. - -## Governance - -*Who may act at SMI and the trust shape CORA applies. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority.* - -People and agents are facility principals at the [NSLS-II Site](../nsls2/index.md#safety-and-governance); on the beamline they surface through the actions they take. The human roster is not known from the profile collection (GOV-1), so the principals are the design shape, not a registered list. - -### Who acts - -CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the NSLS-II Site. An SMI beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. - -### The trust boundary - -CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may start an acquisition, change the camera length or grazing angle, run an in-situ environment program, override a caution, or commit a calibration. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer. The NSLS-II proposal and cycle are a fact CORA's Campaign uses for custody. - -### In-situ studies and time series - -SMI's soft-matter science often follows a sample as it changes: a film drying under a blade coater, a polymer responding to humidity or a temperature ramp. Those are time series under an in-situ environment program, where CORA's custody and trust shapes earn their keep, holding the gated acquisition while the trust boundary bounds what may change mid-series and who may intervene. If an autonomous Agent were added to steer such a study (adjust the environment, decide when enough frames are collected), it would be a facility principal scoped at the Site, governed by the same trust boundary, with each choice recorded as a [Decision](../../architecture/modules/decision/index.md). None is declared yet. - -## Model - -*The developer's by-kind index: where each CORA aggregate's SMI content lives. It hosts no content of its own. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC -[modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at SMI | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (EnergyAxis) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [The beamline](index.md#enclosures) (12-ID-A optics, 12-ID-C experiment) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### Deliberately not here yet - -This is a design-phase scaffold (descriptor + docs), mirroring the other NSLS-II and Diamond beamlines. Left out on purpose: - -- **No new Family.** SMI is a reuse-and-reinforce deployment, the NSLS-II twin of Diamond i22 (SAXS / WAXS): the Pilatus detectors bind `Camera`, the flux monitor `FluxMonitor`, the sample environment `TemperatureController`, the fluorescence MCA `EnergyDispersiveSpectrometer`, the beamstops `BeamStop`, the mirrors `Mirror`, the monochromator `Monochromator`, the slits `Slit`, the attenuators `Filter`, and the compound-refractive-lens `Transfocator`, which reuses the graduated `Transfocator` catalog Family (a CRL focusing optic, distinct from `Mirror` / `ZonePlate` / `Condenser`, bound at 4-ID, 8-ID, 9-ID, i22, and CHX too); the residual open item is the per-Asset lens material and count (`CRL-1`), which graduation does not resolve. -- **The graduated `PositionMonitor`.** One device binds the graduated catalog `PositionMonitor` Family that other deployments also share (4-ID, 8-ID, 9-ID): it presents the `Sensor` Role, earned across the wide fleet that shares it, distinct from `FluxMonitor` by measuring beam position rather than flux. The per-Asset residual that stays open is the beam-position channel map (`DIAG-1`), recorded in the promotion-review register. -- **No new Capability or Method.** SAXS, WAXS, and GISAXS sit on the deferred scattering Capabilities Diamond i22 left pending (`TECH-1`); SMI reinforces them without coining any, and records no Practice. Grazing incidence is a sample-orientation variant, not a new Capability; simultaneous SAXS+WAXS is coordinated Runs, not a combined technique. The integration and reduction are `ComputePort` work. -- **The in-situ soft-matter cells.** The humidity cell (driven via Moxa analog IO, relative humidity computed in software) and the blade coater (a SmarAct stage plus a syringe pump) are SMI's specialty; they would each need their own family or Procedure decision, so they are deferred to a named question (`INSITU-1`) rather than modelled. -- **The in-vacuum WAXS / SAXS chamber.** The active sample chamber (pressure gauges, gate valves, turbo pump, pump / vent automation) is carried as the facility `Vacuum` Supply, the i22 precedent; whether the active chamber enters CORA as its own device is the named question `VAC-1`. -- **Operations and experiment views, integration scenarios, vendor Models.** A runbook and registered Assets for a beamline CORA does not yet drive would be invention; they land when the design firms and the team confirms. - -## Open questions - -*What CORA needs the SMI team to confirm. This model is reverse-engineered from public open source (the [`NSLS2/smi-profile-collection`](https://github.com/NSLS2/smi-profile-collection) profile collection): the EPICS PVs are read from it, but vendor identities, physical positions, and the detector and in-situ-cell configuration are not. Each row is a fact the beamline team owns. It is a delete-on-answer queue.* - -Priorities: `Blocks-build`, `Blocks-go-live`, `Nice-to-have`. - -### Source and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Nice-to-have | The in-vacuum undulator period, gap range, and harmonic usage. The device (`SR:C12-ID:G1{IVU:1}`) is confirmed; working gap range is about 6200-15100. | An in-vacuum undulator, identity-only. | The InsertionDevice settings. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit-leaf PVs. Only the front-end photon shutter (`XF:12IDA-PPS:2{PSh}`) is in source. | The permit signal is a confirm note, not a guessed PV. | The Enclosure permit signals. | - -### Optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DCM-1 | Nice-to-have | The double-crystal monochromator energy range (the crystal is Si(111) per the source energy math, on bare motor records `XF:12ID:m65`-`m68`, driven by the coupled energy pseudopositioner). | One Monochromator Asset, Si(111) recorded, range blank. | The Monochromator settings. | -| CRL-1 | Blocks-go-live | The transfocator (`XF:12IDC-OP:2{Lens:CRL}`) lens material and count (twelve elements). The cross-deployment abstraction is resolved: the compound refractive lens reuses the graduated `Transfocator` catalog Family (a CRL focusing optic), bound at 4-ID, 8-ID, 9-ID, i22, and CHX too; only the per-Asset lens spec is still open. | The graduated `Transfocator` Family is bound; lens material and count blank. | The transfocator lens specification. | -| ENERGY-1 | Nice-to-have | Does SMI ever scan energy as the measurement, or is it always fixed-energy per experiment? | Fixed-energy; energy_scan not modelled. | The energy Capability decision. | - -### Sample and detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| STAGE-1 | Blocks-go-live | The full HUB sample-stack axis set (x / y / z / theta / phi / chi) and the SmarAct piezo, and whether the grazing-incidence orientation axes warrant a `Goniometer` plus an Assembly. | A `LinearStage` sample stack, orientation axes and the Assembly deferred. | The SampleStage axes and orientation modelling. | -| DET-1 | Blocks-go-live | Which Pilatus detectors are live (the SAXS 2M, the WAXS 900KW) versus the retired set (a 1M, a 300KW), and the SAXS camera-length range. | 2M (SAXS) and 900KW (WAXS) live; all Cameras; camera-length range blank. | The detector roster and Q-range. | -| TEMP-1 | Nice-to-have | Which sample-environment thermal units are live (the Linkam thermal / tensile stages, the LakeShore controller)? | One `TemperatureController` Asset (the Linkam); the others noted. | The sample-environment Assets. | -| INSITU-1 | Nice-to-have | The in-situ soft-matter cells: the humidity cell (driven via Moxa analog IO, no dedicated PV) and the blade coater (a SmarAct stage plus a syringe pump). How does CORA model these in-situ environments? | Deferred; they would need their own family / Procedure decisions when they land. | The in-situ cell Assets and Procedures. | -| VAC-1 | Nice-to-have | The WAXS / SAXS in-vacuum sample chamber (`Sample_Chamber`: pressure gauges, gate valves, a turbo pump, and pump / vent automation, used to set the in-vacuum vs in-air measurement mode). Does the active chamber enter CORA as a device, or stay a facility Supply? | Vacuum carried as a facility Supply (the i22 precedent); the active chamber deferred. | The vacuum-chamber Asset boundary. | -| DIAG-1 | Nice-to-have | The flux-monitor and beam-position channel maps; the `PositionMonitor` Family is settled (graduated catalog Family presenting `Sensor`), so only the per-Asset channel map stays open. | Read-only flux (`FluxMonitor`) and beam-position (graduated catalog `PositionMonitor`) probes; channel maps blank. | The FluxMonitor and PositionMonitor channel-map bindings. | - -### Controls and technique scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CAM-1 | Nice-to-have | Which beam-viewing cameras (the SAM / HEX sample cameras, the FOE FS / WBStop / VFM cameras) are live. | The on-axis SAM camera modelled; others noted. | The beam-viewing camera set. | -| DRIVE-1 | Blocks-go-live | The motion-controller box models, firmware, IPs (SmarAct MCS, MDrive, Thorlabs are named). | Families bound (MotionController), specifics blank. | The MotionController Models. | -| TECH-1 | Blocks-go-live | Do the SAXS / WAXS / GISAXS Capabilities enter CORA's catalog, or stay deferred? This is the same owner-scope decision Diamond i22 opened. Simultaneous SAXS+WAXS would be coordinated Runs, not a new technique. | Capabilities deferred (rendered unlinked), no Practice recorded. | The scattering Capability scope. | diff --git a/docs/deployments/srx/notes.md b/docs/deployments/srx/notes.md deleted file mode 100644 index 177235d089b..00000000000 --- a/docs/deployments/srx/notes.md +++ /dev/null @@ -1,96 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at SRX, several techniques on one beamline, each a [Catalog](../../catalog/methods.md) Method bound through an NSLS-II [Practice](../nsls2/index.md#the-techniques-adapted-here). SRX exercises the multi-Capability-per-beamline shape.* - -SRX is a microprobe that does much: it maps elements, scans absorption edges, reconstructs 3D element distributions, takes diffraction, and images. The point for CORA is that all of this reuses Capabilities and Families the fleet already has, the techniques compose from existing parts rather than forcing new vocabulary. - -| SRX technique | CORA expression | Reuse note | -| --- | --- | --- | -| Scanning XRF mapping | a raster reading the `EnergyDispersiveSpectrometer` | the HXN scanning shape; `scanning` Capability deferred (ENERGY-1 cohort) | -| XANES | an energy sweep over the `EnergyAxis` | the BMM energy-scan question; `energy_scan` deferred | -| XRF-tomography | [`tomography`](../../catalog/methods.md), raster x rotation | reuse; XRF maps at each angle | -| Diffraction | a raster/exposure reading a `Camera` pixel detector | reuse; the technique is the detector choice | -| Full-field imaging | the PCO `Camera` | reuse; the FXI/2-BM imaging shape | -| Alignment | beam, KB, and slit tuning | reuse [`alignment`](../../catalog/methods.md) | - -### The multi-Capability-per-beamline shape - -SRX is the first deployment where one beamline carries several distinct techniques at once. In CORA terms, one Unit Asset presents the equipment for multiple Capabilities (imaging, scanning XRF, energy-scan spectroscopy, tomography, diffraction), and a measurement selects the Capability plus the detector(s) it needs from the shared set. Nothing here is new vocabulary: it reinforces that the Capability/Method layer composes, the same `tomography` Method that serves 2-BM serves SRX's XRF-tomography (with a different detector in the slot), and the `EnergyDispersiveSpectrometer` that BMM uses for transmission-reference fluorescence serves SRX's XRF mapping. - -Two Capabilities stay deferred, exactly as their originating beamlines left them: `scanning` (HXN) and `energy_scan` (BMM). SRX reinforces the case for both without coining either, per the design-phase discipline. The reconstruction/fitting legs (XRF fitting, tomographic reconstruction) are `ComputePort` work, not beamline Methods. - -## Governance - -*Who may act at SRX and the trust shape CORA applies. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority.* - -People and agents are facility principals at the [NSLS-II Site](../nsls2/index.md#safety-and-governance); on the beamline they surface through the actions they take. The human roster is not known from the profile collection (GOV-1), so the principals are the design shape, not a registered list. - -### Who acts - -CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the NSLS-II Site. An SRX beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. - -### The trust boundary - -CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may start a scan, switch technique, override a caution, or commit a calibration. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer. The NSLS-II proposal and cycle are a fact CORA's Campaign uses for custody. - -### Multi-technique and agents - -SRX's breadth (a user may map, then scan an edge, then take a tomogram in one beamtime) is a place where an autonomous Agent could choose the next technique or region. If such an agent were added, it would be a facility principal scoped at the Site, governed by the same trust boundary, and each choice would be a [Decision](../../architecture/modules/decision/index.md). SRX also carries an auto-alignment routine in source; conducted by CORA, that is the engine's, with any agent-proposed corrections recorded as Decisions. None is declared yet. - -## Model - -*The developer's by-kind index: where each CORA aggregate's SRX content lives. It hosts no content of its own. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC -[modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at SRX | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (EnergyAxis) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) (5-ID-A optics, 5-ID-D nano endstation) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### Deliberately not here yet - -This is a design-phase scaffold (descriptor + docs), mirroring HXN, BMM, and the Diamond beamlines. Left out on purpose: - -- **No new Family or Capability.** SRX is the reuse-and-reinforce deployment: every device binds an existing catalog Family (`EnergyDispersiveSpectrometer`, `FluxMonitor`, `TemperatureController` among the recently-graduated ones), and the techniques compose from existing Capabilities. The deferred `scanning` (HXN) and `energy_scan` (BMM) Capabilities are reinforced, not coined, here. -- **The micro endstation.** SRX has a micro endstation (05IDB) alongside the nano (KB) endstation modelled here; it is noted and deferred (ENDSTATION-1), the way 32-ID modelled one of several instruments. -- **Operations and experiment views, integration scenarios, vendor Models.** A runbook and registered Assets for a beamline CORA does not yet drive would be invention; they land when the design firms and the team confirms. - -## Open questions - -*What CORA needs the SRX team to confirm. This model is reverse-engineered from public open source (the [`NSLS2/srx-profile-collection`](https://github.com/NSLS2/srx-profile-collection) profile collection): the EPICS PVs are read from it, but vendor identities, physical positions, and the detector/endstation configuration are not. Each row is a fact the beamline team owns. It is a delete-on-answer queue.* - -Priorities: `Blocks-build`, `Blocks-go-live`, `Nice-to-have`. - -### Source and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Nice-to-have | IVU21 undulator period, gap range, and harmonic usage. The device (`SR:C5-ID:G1{IVU21:1}`) is confirmed. | An in-vacuum undulator, identity-only. | The InsertionDevice settings. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit-leaf PVs. Only the shutters (`XF:05ID-PPS{Sh:WB}`, `05IDA-PPS:1{PSh:2}`, `05IDB-PPS:1{PSh:4}`) are in source. | The permit signal is a confirm note, not a guessed PV. | The Enclosure permit signals. | -| ENC-1 | Nice-to-have | The hutch layout: which PV zones (05IDA optics, 05IDB micro endstation, 05IDD nano endstation) are distinct enclosures? | Two enclosures, optics + experiment (nano). | The Enclosure set and roles. | - -### Optics and sample - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DCM-1 | Nice-to-have | The HDCM crystal cut and energy range. | High-heat-load DCM, range blank. | The Monochromator settings. | -| STAGE-1 | Blocks-go-live | The XRF-tomography sample rotation hardware, encoder resolution, and max speed. | A RotaryStage, specs blank. | The SampleRotary settings. | -| ENDSTATION-1 | Nice-to-have | The micro endstation (05IDB): is it a distinct sample stack from the nano endstation modelled here, and how are the two selected? | The nano (KB) endstation is modelled; the micro endstation is noted, deferred. | The micro-endstation Assets. | - -### Detectors and controls - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The Xspress3 fluorescence detector element count and vendor. | One `EnergyDispersiveSpectrometer` Asset presenting the Sensor Role; specs blank. | The detector Model and element count. | -| CAM-1 | Blocks-go-live | Which pixel/area detectors are live vs legacy? Source has Merlin, Dexela, Eiger 1M, a PCO imaging camera, and legacy detectors. | Merlin/Dexela/Eiger/PCO modelled as Cameras; legacy excluded. | The detector roster and per-technique detector slot. | -| DIAG-1 | Nice-to-have | The scaler / ion-chamber flux channel map (which channel is I0). | Read-only flux counters (`FluxMonitor`), channel map blank. | The FluxCounter bindings. | -| DRIVE-1 | Blocks-go-live | The motion-controller box models, firmware, IPs. | Families bound (MotionController), specifics blank. | The MotionController Models. | -| ENERGY-1 | Nice-to-have | Does SRX's XANES sweep warrant the `energy_scan` Capability the catalog anticipates (shared with BMM), or stay under `characterization`? | XANES mapped to existing Capabilities; energy_scan deferred (the BMM question). | The spectroscopy Capability decision. | diff --git a/docs/deployments/sst/notes.md b/docs/deployments/sst/notes.md deleted file mode 100644 index 257f04ee97c..00000000000 --- a/docs/deployments/sst/notes.md +++ /dev/null @@ -1,104 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at SST: soft-scattering, absorption, and photoemission techniques, each a [Catalog](../../catalog/methods.md) Method. SST spans three technique families on two branches, and follows the deferral discipline of the beamlines that brought each to CORA.* - -SST's techniques are new-domain science (soft-X-ray scattering, absorption, photoemission), the families Diamond and the earlier NSLS-II soft-X-ray beamlines brought to CORA. The Methods below render unlinked and are carried pending until the owner-scope decision (TECH-1) brings them into the catalog. - -| Technique | Branch / mode | Notes | -| --- | --- | --- | -| Resonant soft X-ray scattering (RSoXS) | soft, monochromatic | scattering pattern on the Greateyes CCD; the i22 / CSX scattering family, new Capability pending (TECH-1) | -| NEXAFS absorption | soft, energy sweep | drain current / partial electron yield / microcalorimeter fluorescence over an energy scan; the BMM energy-scan question (ENERGY-1, TECH-1) | -| HAXPES photoemission | tender, fixed energy | photoelectron spectra on the hemispherical analyzer; the ESM photoemission family, new Capability pending (TECH-1) | - -All three need the per-endstation [sample manipulator](sample.md) and [detector](detector.md); the fast shutter gates the exposure, and the endstation in control selects the branch. - -### Why the Capabilities stay deferred - -Each of SST's three technique families sits on a Capability the catalog does not yet carry, and the discipline is the same one the originating beamlines applied: soft-X-ray scattering follows Diamond i22 and NSLS-II CSX (the scattering Capabilities are pending, TECH-1); NEXAFS absorption follows BMM (energy-scan-as-the-measurement, deferred at ENERGY-1); photoemission follows NSLS-II ESM (the `angle_resolved_photoemission` Method ESM coined is pending, and HAXPES is the hard / tender photoemission companion). The device Roles already exist (the CCD presents Detector, the manipulators present Positioner, the analyzer and microcalorimeter are the energy-resolving detectors); what is new is the science Capability, not a device shape. SST reinforces all three at one more, larger instrument without coining any, so it records **no Practice** in the [NSLS-II Site](../nsls2/index.md#the-techniques-adapted-here); each binding lands when its Capability does. - -The per-technique reduction (scattering reduction, photoemission spectra, NEXAFS spectra) is `ComputePort` work, not beamline Methods. - -## Governance - -*Who may act at SST and the trust shape CORA applies. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority.* - -People and agents are facility principals at the [NSLS-II Site](../nsls2/index.md#safety-and-governance); on the beamline they surface through the actions they take. The human roster is not known from the profile collection (GOV-1), so the principals are the design shape, not a registered list. - -### Who acts - -CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the NSLS-II Site. An SST beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. - -### The trust boundary - -CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may select the active branch and endstation, start an acquisition, sweep energy, run an in-situ program, override a caution, or commit a calibration. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer. The NSLS-II proposal and cycle are a fact CORA's Campaign uses for custody. - -### Two branches under one custody - -SST's defining governance wrinkle is that two branches and several endstations share one sector and one beamtime allocation. CORA's Campaign and Trust shapes are where that resolves: the endstation in control is a beamline-state fact the trust boundary reads, so a command valid for the soft RSoXS endstation is not automatically valid when the tender HAXPES endstation is live. If an autonomous Agent were added to drive an endstation, it would be a facility principal scoped at the Site, governed by the same trust boundary, with each choice recorded as a [Decision](../../architecture/modules/decision/index.md). None is declared yet. - -## Model - -*The developer's by-kind index: where each CORA aggregate's SST content lives. It hosts no content of its own. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC -[modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at SST | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (EnergyAxis) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [The beamline](index.md#enclosures) (7-ID-A optics, SST-1 soft, SST-2 tender) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### Deliberately not here yet - -This is a design-phase scaffold (descriptor + docs), mirroring the other NSLS-II and Diamond beamlines. Left out on purpose: - -- **No new Family.** SST is a reuse-and-reinforce deployment at Site scale: the soft PGM binds `GratingMonochromator` (graduated across SIX / CSX / ESM, a fourth sighting), the tender DCM `Monochromator`, the sample manipulators `Manipulator` (graduated by ESM, bound twice more here), the soft-scattering CCD and viewing cameras `Camera`, the microcalorimeter `EnergyDispersiveSpectrometer`, the flux channels `FluxMonitor`, the thermal stage `TemperatureController`, the mirrors `Mirror`, the slits `Slit`, the shutters `Shutter`, the beamstop `BeamStop`. -- **The `ElectronAnalyzer` graduation.** The HAXPES Scienta SES hemispherical analyzer binds the `ElectronAnalyzer` family NSLS-II ESM introduced. SST-HAXPES is the **second** sighting (the same Scienta SES type), so it earned the rule-of-three, the way `GratingMonochromator` (CSX) and `Manipulator` (ESM) graduated at their second sighting. The abstraction is settled (a hemispherical electron analyzer is a distinct, recurring photon-in / electron-out device, not a photon detector), so it GRADUATED into the catalog (`ARPES-1`); ESM's references were swept loose to graduated alongside. -- **The graduated `PositionMonitor`.** The beam-position diagnostics bind the graduated catalog `PositionMonitor` Family that several deployments share: it presents the `Sensor` Role, earned across the wide fleet that shares it, distinct from `FluxMonitor` by measuring beam position rather than flux. The per-Asset beam-position channel map stays open (`DIAG-1`). -- **No new Capability or Method.** Soft-scattering, absorption, and photoemission sit on deferred / pending Capabilities (TECH-1, ENERGY-1, the ESM `angle_resolved_photoemission`); SST reinforces all three without coining any, and records no Practice. The per-technique reduction is `ComputePort` work. -- **The deferred endstations and in-situ accessories.** The NEXAFS endstation detail (drain-current / partial-electron-yield channels), the UCAL microcalorimeter ADR cryostat, the VPPEM microscope, the HAXPES flood gun and source-measure unit, and the RSoXS syringe pump are named in a question (`INSITU-1`); none fits an existing family cleanly, so they are deferred rather than modelled. SST models the RSoXS, HAXPES, and NEXAFS-microcalorimeter legs as the representative endstations, the way SRX modelled one of its endstations and 32-ID one of several instruments. -- **Operations and experiment views, integration scenarios, vendor Models.** A runbook and registered Assets for a beamline CORA does not yet drive would be invention; they land when the design firms and the team confirms. - -## Open questions - -*What CORA needs the SST team to confirm. This model is reverse-engineered from public open source (the `NSLS2/sst-*-profile-collection` endstation repos and the shared `NSLS-II-SST/sst-base` package): the EPICS PVs are read from the TOML device manifests and the sst-base device classes, but vendor identities, physical positions, and the per-endstation configuration are not. Each row is a fact the beamline team owns. It is a delete-on-answer queue.* - -Priorities: `Blocks-build`, `Blocks-go-live`, `Nice-to-have`. - -### Source and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Nice-to-have | The two undulator periods and gap / phase ranges (soft EPU60, tender U42). The devices (`SR:C07-ID:G1A{SST1:1}`, `{SST2:1}`) are confirmed from the sst-base energy classes; soft range about 71-2250 eV. | Two insertion devices, identity-only. | The InsertionDevice settings. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit-leaf PVs. Only the shutters (`XF:07ID-PPS{Sh:FE}`, `XF:07IDA-PPS{PSh:n}`) are in source. | The permit signal is a confirm note, not a guessed PV. | The Enclosure permit signals. | -| ENC-1 | Nice-to-have | The branch-to-hutch mapping and the physical hutch names / numbering (not in source): which endstations (RSoXS, NEXAFS on the soft SST-1 branch; HAXPES on the tender SST-2 branch; plus UCAL, VPPEM) sit in which enclosures? The PV zone numbers (07ID1 / 07ID2 / 07ID6) do not map one-to-one to a branch. | An optics hutch plus a soft (SST-1) and a tender (SST-2) experiment enclosure. | The Enclosure set and roles. | - -### Optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DCM-1 | Nice-to-have | The soft PGM grating set and the tender DCM crystal cut and ranges. Both monochromators (`Mono:PGM1`, `Mono:DCM1`) are in source. | One GratingMonochromator and one Monochromator Asset, settings blank. | The Monochromator settings. | -| ENERGY-1 | Nice-to-have | Is energy scanned as the measurement (NEXAFS absorption sweeps the soft PGM across an edge), warranting the energy-scan Capability the catalog anticipates? | NEXAFS mapped to deferred Capabilities; energy-scan deferred (the BMM question). | The spectroscopy Capability decision. | - -### Sample and detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ARPES-1 | Blocks-go-live | The HAXPES Scienta SES hemispherical analyzer model, lens modes, and pass-energy / kinetic-energy controls. | An `ElectronAnalyzer` Asset (catalog Family, graduated at this 2nd sighting after ESM) presenting the Detector Role. | The analyzer model. | -| DET-1 | Blocks-go-live | Which detectors are live per endstation: the RSoXS Greateyes WAXS CCD (a second SAXS-arm CCD is commented out), the HAXPES analyzer, the NEXAFS microcalorimeter and drain-current / partial-electron-yield channels. | The WAXS CCD, the analyzer, and the microcalorimeter modelled; the SAXS arm excluded. | The detector roster per endstation. | -| TEMP-1 | Nice-to-have | Which sample-environment thermal units are live per endstation (the Lakeshore controllers). | One `TemperatureController` Asset; the others noted. | The sample-environment Assets. | -| DIAG-1 | Nice-to-have | The flux-channel map (the I0 mesh / diode, the drain-current and ion-chamber SR570 channels); the `PositionMonitor` Family is settled (graduated catalog Family presenting `Sensor`), so only the per-Asset channel map stays open. | Read-only flux (`FluxMonitor`) and beam-position (graduated catalog `PositionMonitor`) probes; channel maps blank. | The FluxMonitor and PositionMonitor channel-map bindings. | -| INSITU-1 | Nice-to-have | The endstations and in-situ accessories deferred at this design phase: the NEXAFS endstation detail (drain-current / partial-electron-yield channels), the UCAL microcalorimeter ADR cryostat, the VPPEM microscope, the HAXPES flood gun and source-measure unit, and the RSoXS syringe pump. None fits an existing family cleanly. How does CORA model these? | Deferred; the main RSoXS / HAXPES / NEXAFS-TES legs are modelled; the rest are named here. | The deferred endstation and in-situ Assets. | - -### Controls and technique scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DRIVE-1 | Blocks-go-live | The motion-controller box models, firmware, IPs across the branches. | Families bound (MotionController), specifics blank. | The MotionController Models. | -| TECH-1 | Blocks-go-live | Do the soft-scattering (RSoXS), absorption (NEXAFS), and photoemission (HAXPES) Capabilities enter CORA's catalog, or stay deferred? This is the same owner-scope decision the other scattering / spectroscopy / photoemission beamlines opened. | Capabilities deferred (rendered unlinked), no Practice recorded. | The technique Capability scope. | diff --git a/docs/deployments/syrmep/notes.md b/docs/deployments/syrmep/notes.md deleted file mode 100644 index 9d5bee90a6c..00000000000 --- a/docs/deployments/syrmep/notes.md +++ /dev/null @@ -1,155 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of SYRMEP is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../elettra/index.md) is how a facility adapts it. SYRMEP is a hard X-ray microtomography beamline, so its core imaging techniques reuse the catalog Methods the fleet's imaging beamlines already share; the helical, white-beam, and phase-retrieval Methods are new to CORA's catalog and render unlinked, carried pending until a technique enters scope (`TECH-1`). - -### Microtomography: absorption and phase contrast - -SYRMEP sets the X-ray energy with the Si(111) monochromator (or passes white / pink beam), then rotates the specimen while the detector records projections. It does absorption tomography, propagation-based phase-contrast tomography (the long sample-to-detector rail), and diffraction-enhanced imaging. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Microtomography | [`tomography`](../../catalog/methods.md) | the canonical imaging routine on the [rotation stage](sample.md) and [camera](detector.md); reuses the 2-BM tomography Method directly | -| Continuous (fly) tomography | [`continuous_rotation_tomography`](../../catalog/methods.md) | trigger-driven continuous rotation under DonkiOrchestra; reuses the catalog Method | -| Wide / laminar-beam tomography | [`mosaic_tomography`](../../catalog/methods.md) | tiled tomography for samples beyond the field of view; reuses the catalog Method | -| Dark / flat field | [`dark_field`](../../catalog/methods.md), [`flat_field`](../../catalog/methods.md) | the reconstruction baseline frames; reuse the catalog acquisition Methods | -| Rotation-axis centring | [`center_alignment`](../../catalog/methods.md) | the alignment step; reuses the catalog Method | -| Helical CT | `helical_tomography` | the large-specimen continuous-pitch mode (the XC Hydra photon-counting setup); Method not yet in the catalog, renders unlinked | -| White / pink-beam tomography | `white_beam_tomography` | fast tomography with the DCM bypassed; Method not yet in the catalog | -| Phase retrieval | `phase_retrieval` | single-distance TIE-HOM / Paganin retrieval (the SYRMEP Tomo Project pipeline); a compute Method not yet in the catalog (`COMPUTE-1`) | - -### A clean re-test of the imaging spine - -SYRMEP's significance for the catalog is that it forces nothing new at the Family level: every device binds an existing imaging Family (`RotaryStage`, `LinearStage`, `Camera`, `Scintillator`, `Slit`, `Filter`, `Monochromator`), and the core tomography Practices bind real catalog Methods. It is the cleanest re-test the fleet has of whether the imaging spine ports to a brand-new Site and control house-style. The clinical breast-CT programme (SYRMA-3D) and the large-specimen helical work are extensions that would earn new Methods if the deployment enters pilot scope. - -### Not modelled yet - -The concrete acquisition recipes (the exposure, projection counts, angle ranges, propagation distances, and the phase-retrieval and ring-removal parameters) are not written yet; they join as the deployment approaches the point where CORA drives SYRMEP. Whether helical CT, white-beam tomography, and phase retrieval enter CORA's catalog is an owner-scope decision on [Model](#deliberately-not-here-yet); see [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at SYRMEP, and the trust shape that will gate it. First cut.* - -Governance at SYRMEP follows the same model as the rest of the fleet: people and autonomous agents are facility principals at the [Elettra Site](../elettra/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). - -SYRMEP is CORA's first Elettra deployment, so Elettra is a brand-new Site: the operator pool and the safety-review structure are carried pending on the [Elettra Site](../elettra/index.md), shared across the facility's beamlines, until Elettra staff confirm them (`GOV-1`). SYRMEP is a reverse-engineered scaffold rather than a pilot, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized; they land when the deployment approaches the point where CORA drives SYRMEP, following the [2-BM governance](../2-bm/governance.md) shape. - -The safety tier is the other piece that is not yet settled. The Elettra personnel-safety permit signals and the front-end / safety shutters are not in public source, so the Enclosure permit leaves and the interlock structure are carried pending and are not invented here (`PSS-1`). The Elettra 2.0 GeCo PLC interlock stack (Siemens S7-1500 over PROFINET) is the safety floor CORA never drives; it sits below the seam. What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [Elettra Site](../elettra/index.md), not on the beamline, and the beamline links up to them. - -SYRMEP carries the hazard classes that come with hard X-ray imaging: an intense white / monochromatic beam, and, for the clinical breast-CT programme (SYRMA-3D), human-subject considerations that an experiment Clearance would carry. Those land with the work that brings them, modelled as hazards on the experiment rather than as Assets CORA drives for safety. - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives SYRMEP, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's SYRMEP content lives, the new Elettra Site and Tango / DonkiOrchestra control house-style it introduces, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at SYRMEP | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (the incident-energy `PseudoAxis`) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes SYRMEP new - -SYRMEP is two things at the facility level and nothing new at the catalog level. It is CORA's **eleventh Site** (Elettra Sincrotrone Trieste, Trieste), another re-test of the Site and Federation kernel, and the **first Tango + DonkiOrchestra** control house-style. The Tango device floor is shared with the ESRF's ID32, but the orchestration seam is the in-house, trigger-driven DonkiOrchestra framework (Elettra 2.0: the abstract "Executer" Tango device server), not BLISS and not EPICS. Its science is hard X-ray microtomography (absorption, propagation-based phase contrast, diffraction-enhanced imaging) plus the SYRMA-3D clinical breast-CT programme. - -### No new families: the imaging spine ports wholesale - -SYRMEP coins no new Family and changes nothing in the catalog. It is the cleanest re-test the fleet has of the imaging spine on a new Site: - -- the bending-magnet source is a Supply (`PhotonBeam`), provenance only (the 2-BM precedent); -- the double-crystal Si(111) DCM binds `Monochromator`, with the mono / white (pink) beam choice as a per-Asset setting (the 2-BM `dmm_insertion` insert/retract precedent); -- the incident energy is a `PseudoAxis` over the DCM (the 2-BM energy-curve precedent); -- the laminar-beam slits bind `Slit`, the filters bind `Filter`, the upstream mask binds `Mask`; -- the heavy-payload rotation stage binds `RotaryStage` (the tomographic theta); -- the five-axis sample positioner binds `LinearStage`; -- the sample-to-detector propagation rail binds `LinearStage` (the 2-BM `CameraZ` precedent); -- the scintillator binds `Scintillator` and the sCMOS / CCD / photon-counting cameras bind `Camera`; -- the machine state binds the loose `StorageRing`. - -Unlike ID32 (which bound no catalog Method), SYRMEP's core Practices bind the real catalog `tomography`, `continuous_rotation_tomography`, `mosaic_tomography`, `dark_field`, `flat_field`, and `center_alignment` Methods. The three new technique slugs (`helical_tomography`, `white_beam_tomography`, `phase_retrieval`) are registered pending in `tests/unit/deployments/test_site_descriptor.py` until they enter pilot scope. - -### The Tango / DonkiOrchestra control plane - -SYRMEP is the first Tango + DonkiOrchestra controls house-style in the fleet. CORA models the control handles as opaque edge strings over the `ControlPort`, the way the MX3 / ID32 heterogeneous-control precedent does. The crucial difference from ID32: **SYRMEP's handles are not in public source**. The DonkiOrchestra scan engine's source location is unconfirmed and the acquisition code is in the private `gitlab.elettra.eu` `syrmep_acquisition` group, so the handles are confirm-pending placeholders rather than read addresses (`CTRL-1`). The DonkiOrchestra orchestration (Elettra 2.0: the "Executer" device server) is the seam CORA's edge replaces, conducting over Tango rather than over BLISS or EPICS. - -### Deliberately not here yet - -| Deferred | Why | Tracking | -| --- | --- | --- | -| Every concrete control handle | not in public source (private gitlab group, unconfirmed DonkiOrchestra source) | `CTRL-1` | -| PSS permit signals and shutters | not in public source, not invented | `PSS-1` | -| The default routine camera, pixel size, FOV | sources name multiple detectors without pinning the routine one | `DET-1` | -| Helical CT, white-beam tomography, phase retrieval as catalog Methods | a CORA-scope decision pending pilot scope | `TECH-1` | -| The reconstruction pipeline as Compute provenance | post-acquisition compute; modelled when the deployment firms up | `COMPUTE-1` | -| Scenarios, operations runbook, live experiment view | SYRMEP is not yet driven by CORA | follows the [2-BM](../2-bm/index.md) shape | - -## Open questions - -*What CORA needs the SYRMEP team to confirm before the model can be trusted.* - -SYRMEP was reverse-engineered from public material (the [elettra.eu SYRMEP pages](https://www.elettra.eu/elettra-beamlines/syrmep.html), the EPJ Plus 2024 SYRMEP review, and the J. Synchrotron Rad. 2023 large-FOV paper). The hardware facts are read from those sources, but **the control handles are not in public source**: the in-house DonkiOrchestra scan engine's source location is unconfirmed and the acquisition code lives in the private `gitlab.elettra.eu` `syrmep_acquisition` group. So unlike the ID32 BLISS scaffold, the device handles on the [device pages](index.md) are confirm-pending placeholders rather than read addresses. This is CORA's first Elettra Site and first Tango / DonkiOrchestra controls house-style. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | The hutch grouping: a white-beam optics zone feeding one imaging / tomography endstation, or a different layout? | A shared `syrmep-optics` zone and the `syrmep-experiment` endstation. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The bending-magnet source detail (critical energy, field across the 2.0 / 2.4 GeV modes). | A bending-magnet source (section 6); 5.59 keV critical energy and 1.45 T field at 2.4 GeV. | The source Asset detail. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MACHINE-1 | Nice-to-have | The Elettra storage-ring state SYRMEP reads (the 2.0 GeV / 300 mA and 2.4 GeV modes; current, fill). | Observe-only machine state, a loose `StorageRing`; exact Tango handles pending. | The machine-state observation. | -| MONO-1 | Blocks-go-live | The Si(111) DCM energy range and the authoritative bound: the EPJ Plus 2024 review states mono 10-40 keV, the elettra.eu spec still lists 9-40 keV. The Bragg / offset handles. | A `Monochromator` (Si(111), fixed-exit, 20 mm offset); energy a `PseudoAxis`; range 10-40 keV mono. | The monochromator and incident-energy Assets. | -| MODE-1 | Blocks-go-live | The mono / white (pink) beam switch: how the beam bypasses the DCM, and the white-beam energy (~16-30 keV average). | The beam mode is a per-Asset setting on the `Monochromator` (the 2-BM DMM insert/retract precedent). | The beam-mode modelling. | -| OPT-1 | Nice-to-have | The white-beam-defining mask dimensions and drawing. | A fixed `Mask` upstream of the optics. | The mask Asset detail. | -| OPT-2 | Blocks-go-live | The laminar-beam slit blade-axis map and handles, and the beam dimensions (sources cite ~120 x 4 mm at 20 m and ~160 x 5 mm at 23 m). | Slits bound to `Slit`; a ~120-160 mm wide, ~4-5 mm tall laminar beam at 7 mrad acceptance. | The slit Asset detail and beam geometry. | -| FOIL-1 | Nice-to-have | The absorption / beam-hardening filter foils and the selector handle. | Filters bound to `Filter`; foils pending. | The filter Asset detail. | - -### Sample - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| STAGE-1 | Blocks-go-live | The rotation stages: the heavy-payload rotator (up to 120 kg, 1-20 deg/s, 0.02 deg) is documented, but the standard sample rotation stage range / bearing / model and the rotator wobble spec are not. | A `RotaryStage` for the tomographic theta; a standard-stage variant and the wobble spec pending. | The rotation-stage modelling. | -| SAMPLE-1 | Blocks-go-live | The five-axis sample-positioning stage: motor vendors, micro-positioning resolution, axes, and handles. | A `LinearStage` facet set; vendors / resolution / axis map pending. | The sample-stage modelling. | - -### Detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The default routine-tomography camera and its pixel size and field of view: the sCMOS (2048x2048, 0.9-5.7 um) or the CCD (4008x2672, 4.5 um)? | Both bind `Camera`; the routine camera is pending. | The detector modelling. | -| DET-2 | Nice-to-have | The sample-to-detector propagation rail and the two-axis detector rail handles. | A `LinearStage` (range 3-160 cm). | The propagation-rail Asset. | -| DET-3 | Nice-to-have | The routine scintillator screen type and thickness (published configs cite GGG:Eu). | A `Scintillator`; type and thickness pending. | The scintillator Asset. | -| DET-4 | Nice-to-have | The XC Hydra photon-counting detector pixel size and configuration, and when it is used. | A `Camera` for the large-specimen / helical CT mode; pixel size pending. | The photon-counting detector modelling. | - -### Controls and acquisition - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-build | The Tango device namespaces and the DonkiOrchestra (Elettra 2.0: "Executer") scan-engine handles: SYRMEP's control source is not public. | A Tango device floor with the in-house DonkiOrchestra scan engine; handles are confirm-pending placeholders. | The whole control plane (every device handle in the Inventory). | -| PSS-1 | Blocks-go-live | The Elettra personnel-safety permit signals and the front-end / safety shutters. | Enclosure permit leaves and a `Shutter`, carried pending, not invented. | The safety / interlock structure. | - -### Techniques and compute - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Nice-to-have | The technique scope: core tomography reuses catalog Methods, but helical CT, white-beam tomography, and phase retrieval are not yet catalog Methods. | The core tomography Practices reuse catalog Methods; the rest are pending and render unlinked. | Whether the new techniques enter the catalog (a CORA-scope call on [Model](#deliberately-not-here-yet)). | -| COMPUTE-1 | Nice-to-have | The reconstruction pipeline (the SYRMEP Tomo Project: phase retrieval, ring removal, FBP / iterative on ASTRA + TomoPy) and whether CORA records its invocation as Method / Compute provenance. | Post-acquisition compute CORA records as provenance, not data it owns. | The compute-provenance modelling. | -| SUP-1 | Nice-to-have | The facility supplies a run draws on (cooling water for the optics, the vacuum extent of the white-beam path). | `PhotonBeam`, `CoolingWater`, `Vacuum`. | The Supply detail. | - -### Governance - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| GOV-1 | Nice-to-have | The Elettra operator pool and safety-review structure (site-level). | Carried pending on the Elettra Site, not instantiated per beamline. | The governance principals. | diff --git a/docs/deployments/tomowise/notes.md b/docs/deployments/tomowise/notes.md deleted file mode 100644 index d42d560cf5d..00000000000 --- a/docs/deployments/tomowise/notes.md +++ /dev/null @@ -1,94 +0,0 @@ -# Notes - -## Techniques - -*What TomoWISE is designed to do, as intent. Design-phase.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../maxiv/index.md#the-techniques-adapted-here) is how a facility adapts it. TomoWISE is pre-build, so the techniques below are design intent: the MAX IV Practices that will bind them are carried pending on the [MAX IV site page](../maxiv/index.md#the-techniques-adapted-here). The function view survives the eventual equipment choices, which is why it can be written before the hardware is procured. - -The beamline's five operation modes (TDR) select the source, filtering, monochromator, and KB optics for a given technique: - -| Technique | Source | Monochromator | KB | What it is for | -| --- | --- | --- | --- | --- | -| Standard microtomography | CPMU14 | MLM | no | high-throughput monochromatic CT | -| High-speed microtomography (small FOV) | CPMU14 | MLM or none | no | sub-micron pixel, fast dynamics | -| Large-FOV / white-beam microtomography | 3T3PW | none | no | large or highly attenuating samples | -| Nanotomography | CPMU14 | MLM | yes | 200-nm-class cone-beam imaging | -| Laminography | CPMU14 | MLM | no | flat, extended samples (tilt axis, not a separate fixture) | - -A few points of intent shape the model: - -- **Source switching is first-class.** Two insertion devices (one `InsertionDevice` Family, two Assets) are selected per mode, unlike the single bending-magnet source at 2-BM. The mode determines which is in the beam. -- **Laminography is a tilt setpoint, not a separate station.** It runs on the microtomography endstation's tilt axis, mirroring the 2-BM laminography decision: the same installed stack, a different Method, not a new Fixture. -- **Monochromatic and white-beam are the same beamline.** Inserting or bypassing the MLM (and the filter chain) picks the spectrum; it is an operation mode over one set of optics, not two beamlines. - -The concrete acquisition recipes (scan sequences, energies, exposure) are not written yet; they join as the beamline approaches commissioning. See [Open questions](#open-questions) for what must be confirmed first. - -## Governance - -*Who will act at TomoWISE, and the trust shape that will gate it. Design-phase.* - -Governance at TomoWISE follows the same model as the 2-BM pilot: people and autonomous agents are facility principals at the [MAX IV Site](../maxiv/index.md#safety-and-governance), 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). - -TomoWISE is pre-build, so this shape is not yet instantiated. The MAX IV operator and safety-review structure is still being defined and is carried pending on the [MAX IV site page](../maxiv/index.md#safety-and-governance); CORA does not invent a MAX IV operator pool or review chain ahead of confirmation. - -What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the MAX IV Site, not on the beamline, and the beamline links up to them rather than restating them. The MAX IV safety-form names themselves are an open question (PSS-1 on [Open questions](#open-questions)). - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the beamline approaches commissioning, following the [2-BM governance](../2-bm/governance.md) shape. - -## Model - -*The developer's by-kind index: where each CORA aggregate's TomoWISE content lives, the cross-facility `Microscope` / `Optics` Assemblies it reuses with 2-BM, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at TomoWISE | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What is deliberately not here yet - -- **Integration scenarios.** No `test_tomowise_*.py` registers TomoWISE Assets into the event store. Scenario code is where Assets become real, and hard-registering a design-phase, moving-target beamline would commit speculative structure. It lands when the design firms and the team approves. -- **Vendor Models.** Only one catalog Model is bound: `optique_peter_micrx080` on the microscope Housings (reused from 2-BM, pending confirmation, DET-2). The remaining "(target)" models in the TDR are [open questions](#open-questions), not bindings, because part numbers are not yet procured. -- **Operations and experiment views.** A runbook and live experiment view for an unbuilt beamline would be invention; see the note on the [index](index.md#not-yet-documented). -- **Detector assemblies (done).** The two microscopes now compose the cross-facility `Microscope` / `Optics` Assemblies that 2-BM uses (Housing-anchored: turret + objectives + selector over a scintillator), rather than a loose family. The catalog assembly was generalized (`camera` and `propagation_distance` made `ZeroOrOne`) so TomoWISE can share its four cameras and the one gantry propagation rail across both microscopes. This also removed the prior name collision between the loose `Microscope` family and the catalog `Microscope` Assembly. What remains deferred is the integration scenario that registers the Fixture (slot -> Asset bindings) and a standalone fixture page; both wait until the design firms. - -## Open questions - -*What CORA needs the TomoWISE team to confirm before the model can be trusted.* - -TomoWISE is in the design phase, so this page is long by design: almost every value on the [device pages](index.md) is a TDR design specification, not a commissioned measurement. Each row below is a fact the beamline team or the TDR owns, not a CORA modelling choice. It is a delete-on-answer queue: when an item is answered, the answer lands in the descriptor and the row is removed (with the reason in the commit). Priorities are `Blocks-build` (needed before the model is built for real), `Blocks-go-live` (needed before first users), and `Nice-to-have`. - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-build | What are the Tango/Sardana device and attribute names for each device? | Control handles are unassigned; CORA leaves the device handle empty (no EPICS PV). | Wiring each Asset to a real control handle. | -| PSS-1 | Blocks-build | What are the PSS permit signals and access-interlock names for the optics and experiment hutches? | Both hutches exist with permit signals to be named. | The Enclosure permit signals. | - -### Sources and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| OPT-1 | Nice-to-have | Which MLM coating is selected? The TDR text lists W/SiC or W/B4C; Table 8.3 lists W/Si. | The MLM is one Monochromator Asset; coating is a setting. | The MLM coating setting. | -| LAYOUT-1 | Nice-to-have | What is the single z-coordinate reference for the layout? The TDR mixes "from the CPMU14 source" (front end) and "from the straight-section centre" (optics and downstream), about 505 mm apart. | z values are carried as approximate from-source and flagged confirm. | Exact device z positions. | - -### Endstations - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| NANO-1 | Blocks-go-live | Are the nanotomography sample-manipulator model bindings final? The TDR specifies the six-axis stack in Table 9.5 (tilt, coarse X/Y/Z, continuous rotary, fine Xs/Zs); only the per-axis model procurement remains. | The TDR-specified stack, reusing the micro-endstation Families, with a "(target)" model per axis carried unbound. | The nanotomography stage Model bindings. | -| STAGE-1 | Blocks-go-live | Is the rotary stage the Lab Motion Systems RT100AX, and are its specs final? | The "(target)" RT100AX, used as the trigger master clock. | The rotary stage Model binding. | -| STAGE-2 | Nice-to-have | Is the sample positioning stage the Lab Motion Systems XY150B-12? | The "(target)" XY150B-12. | The sample positioning Model binding. | - -### Detector - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | Which camera models will be procured for cameras I to IV? (Chosen in project year 2.) | Four cameras at the stated design-target sensors/speeds; models unbound. | The camera Model bindings. | -| DET-2 | Blocks-go-live | Confirm the microscope optics model. Each Housing binds the 2-BM candidate `optique_peter_micrx080`; the TDR names only the vendor (Optique Peter), so confirm this model or name the procured alternative (project year 2). | Two microscopes (MicLFOV, MicHR) composed as `Microscope` Assemblies, Housing model bound to `optique_peter_micrx080` pending confirmation. | The microscope Model confirmation. | -| TRIG-1 | Blocks-go-live | Will the rotary TTL (3600 pulses/rev) feed the camera triggers directly, or is an FPGA conditioner needed? | Direct TTL, no conditioner; may evolve once camera trigger requirements are firm. | The trigger/sync chain. | diff --git a/docs/deployments/tps-05a/notes.md b/docs/deployments/tps-05a/notes.md deleted file mode 100644 index eed0d0b3b9d..00000000000 --- a/docs/deployments/tps-05a/notes.md +++ /dev/null @@ -1,118 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at TPS 05A: rotation macromolecular crystallography, each technique a [Catalog](../../catalog/methods.md) Method bound through an [NSRRC Practice](../nsrrc/index.md#the-techniques-adapted-here). TPS 05A reuses the same MX Methods as [TPS 07A](../tps-07a/notes.md#techniques) and Diamond [I03](../i03/notes.md#techniques), so it coins nothing new.* - -TPS 05A's technique, rotation MX (in its microcrystallography form), is the macromolecular-crystallography shape CORA already saw at i03, TPS 07A, and MX3. The Methods render unlinked and are carried pending until the owner-scope decision (TECH-1) brings them into the catalog. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Rotation MX data collection | `mx_data_collection` | oscillation collection on the MD3 goniometer + the EIGER2 X 9M, orchestrated through Blu-Ice/DCSS; the i03 Method, pending (TECH-1) | -| Mesh / grid scan | `grid_scan` | mesh scan for crystal location / centring on the MD3; the i03 Method (TECH-1) | -| Autonomous sample exchange | `sample_exchange` | the ISARA robot load / centre / collect / unmount loop, a Procedure over the spine (ROBOT-1) | - -All three are recorded as pending [Practices](../nsrrc/index.md#the-techniques-adapted-here) on the NSRRC Site (the `TPS05A_*` practices), reusing the same Method names TPS 07A and Diamond i03 carry. - -### Why the Methods are reused, not coined - -TPS 05A brings nothing new at the technique layer: it is the MX-cluster sibling of TPS 07A. Rotation MX, mesh-scan centring, and robot sample exchange are the i03 shapes, so 05A binds the same pending Methods (`mx_data_collection`, `grid_scan`, `sample_exchange`) rather than coining anything; whether those Methods enter the catalog is the cross-facility owner-scope decision i03 opened (TECH-1), and 05A reinforces the case at a **further MX deployment** (after i03, NSLS-II FMX / AMX, MX3, Sirius MANACA, and TPS 07A). The device Roles already exist (the MD3 presents Positioner via the graduated `Goniometer`, the EIGER2 presents Detector via `Camera`), so nothing new is needed in the device model either. - -The autonomous sample exchange reuses the i03 / i24 / 07A / MX3 autonomous-loop shape: a Procedure over the spine threaded through `Subject` custody, not a new device family (ROBOT-1). - -TPS 05A contributes no new vocabulary anywhere; its value is reinforcing that the NSRRC Site, the Blu-Ice/DCSS-over-EPICS seam, and the MX Methods cover the cluster, not just 07A. - -## Governance - -*Who may act at TPS 05A and the trust shape CORA applies. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority.* - -People and agents are facility principals at the [NSRRC Site](../nsrrc/index.md#safety-and-governance); on the beamline they surface through the actions they take. TPS 05A's governance is **identical to [TPS 07A](../tps-07a/notes.md#governance)'s**, because both beamlines share the one NSRRC Site: the same principals, the same LDAP-backed staff (`ldap://10.7.1.1`), and the same mandatory radiation-safety-training portal (`safetytraining.nsrrc.org.tw`). The human roster is not in public source (GOV-1), so the principals are the design shape, not a registered list. - -### Who acts - -CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the NSRRC Site. A TPS 05A beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. This is the same role kernel CORA seeds at every Site, and at 05A it is literally reused from 07A, both share the NSRRC Site, so the second beamline registers no new facility principals. That reuse is the point: the Access kernel scopes at the Site, not per-beamline. - -The NSRRC mandatory training portal maps to CORA's **worldwide-invariant training axis**: a fact carried on the Access principals, not a separate Clearance kind (GOV-1). - -### The trust boundary - -CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may start a collection, move the robot, change the energy, override a caution, or commit a calibration. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer or its LDAP groups. It holds across the seam: a command CORA's EdgeConductor issues in place of DCSS (start an oscillation, drive a motor, arm the detector) is gated exactly as any spine command is. The facility proposal and cycle are a fact CORA's Campaign uses for custody. - -### Unattended autonomous collection - -TPS 05A's throughput model is unattended, the same as 07A: the ISARA robot mounts a crystal, the MD3 centres it (mesh scan), the EIGER2 collects, the robot unmounts, repeat. That loop is where CORA's custody and trust shapes earn their keep, each crystal threaded through the `Subject` aggregate so its identity and provenance is tracked, the exchange a Procedure gated by a Clearance (ROBOT-1). If an autonomous Agent were added to choose which crystal to collect or when a dataset is good enough, it would be a facility principal scoped at the Site, governed by the same trust boundary, with each choice recorded as a [Decision](../../architecture/modules/decision/index.md). None is declared yet. - -The PSS search-and-secure permit leaves that gate the hutch are not in public source (PSS-1) and are carried as a confirm. - -## Model - -*The developer's by-kind index: where each CORA aggregate's TPS 05A content lives. It hosts no content of its own. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC -[modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at TPS 05A | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (EnergyAxis) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [The beamline](index.md#enclosures) (TPS-05A-OH optics, TPS-05A-EH experiment) | -| Facility (Federation); Zone, Conduit, Policy (Trust); Actor (Access) | [NSRRC Site](../nsrrc/index.md), [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### Deliberately not here yet - -This is a design-phase scaffold (descriptor + docs), mirroring the other reverse-engineered beamlines and especially its sibling [TPS 07A](../tps-07a/notes.md#model). Left out on purpose: - -- **No new Family.** TPS 05A reuses every Family TPS 07A binds: the graduated `Goniometer` for the MD3, `Camera` for the EIGER2 / OAV, `Monochromator`, `Filter`, `BeamStop`, `Shutter`, `Mirror`, `TemperatureController`, `LinearStage` / `MotionController`, plus the loose `StorageRing` and `PositionMonitor`. The only device-level difference from 07A is the EIGER2 size (9M vs 16M), a per-Asset fact. -- **No new Site, principals, or seam.** The NSRRC Site, its Access principals, and the Blu-Ice/DCSS-over-EPICS seam were all created by 07A; 05A reuses them unchanged. This is the deployment's whole point: demonstrating that the Site, the device-library, and the seam generalize across the MX cluster. -- **The ISARA robot as a Procedure.** Autonomous sample exchange is a deferred Procedure over the spine threaded through `Subject` custody (ROBOT-1), reusing the i03 / i24 / 07A / MX3 shape. -- **The frame egress and any mesh-scan compute.** The EIGER2 frame stream is a `TransferPort` leg into the Dataset of record; spot-scoring / indexing is `ComputePort` work, an Observe / Compute leg off the control seam (DET-1). -- **No new Capability or Method.** Rotation MX reuses the pending i03 Methods, recorded as the `TPS05A_*` Practices on the Site; 05A reinforces the case at a further MX deployment without coining any (TECH-1). -- **A verified PV namespace.** Unlike 07A (whose `07a:` / `07a-ES:` namespace was read from its control tree), 05A has no dedicated public tree, so its `05a:` / `05a-ES:` namespace is inferred by cluster convention and carried pending (PV-1), the fleet's most conservative PV posture. -- **Operations and experiment views, integration scenarios, vendor Models.** A runbook and registered Assets for a beamline CORA does not yet drive would be invention; they land when the design firms and the team confirms. - -## Open questions - -*What CORA needs the NSRRC / TPS 05A team to confirm. This model is reverse-engineered from public open source, but TPS 05A's source is thinner than [TPS 07A](../tps-07a/notes.md#open-questions)'s: there is no dedicated 05A control tree (the public `NSRRC_TPS05A_BeamMonitor` repo is an empty stub), so the device kit is read from the [SPXF facility pages](https://nsrrcspxf.github.io/nsrrcspxf/index.html) and the 2025 J. Synchrotron Rad. cluster paper, and the seam / PV model is inherited from the 07A reading. Each row is a fact the beamline team owns. It is a delete-on-answer queue.* - -Priorities: `Blocks-build`, `Blocks-go-live`, `Nice-to-have`. - -### Provenance (05A-specific) - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| PV-1 | Blocks-go-live | The EPICS PV namespace. 07A's `07a:` / `07a-ES:` was read from its control tree; 05A has no public tree, so its namespace is **inferred** as `05a:` / `05a-ES:` by cluster convention. Is that correct? | The 05A beamline namespace is `05a:` and the endstation `05a-ES:`, inferred, not verified. | The PV namespace for every Asset. | - -### Source and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-go-live | The insertion-device / front-end source: TPS 05A is fed by a TPS undulator (per the SPXF page), but no source PV is in public source. | An insertion-device source, identity-only, no PV; the ring-current monitor stands in as the source representation. | The Source Asset and its PV. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit-leaf PVs. No PSS permit signals are in public source. | The permit signal is a confirm note, not a guessed PV. | The Enclosure permit signals. | -| ENC-1 | Nice-to-have | The hutch layout and names: which devices sit in the optics hutch versus the experiment hutch? Public source exposes no enclosure structure. | An optics hutch (DCM, mirrors) plus an experiment hutch (the MD3 / EIGER2 / robot). | The Enclosure set and roles. | - -### Optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DCM-1 | Nice-to-have | The double-crystal monochromator crystal cut and exact range, and the attenuator foil set. | A Si DCM over ~5.7-20 keV and one Filter Asset, settings blank. | The Monochromator / Filter settings. | -| OPT-1 | Nice-to-have | The focusing optic and the microcrystallography spot size (not stated in public source for 05A). | A KB focusing mirror system (`KBMirrors`, Mirror family), configuration and spot blank. | The mirror Assets, spot size, and PVs. | -| ENERGY-1 | Nice-to-have | Does TPS 05A scan energy as the measurement (anomalous / MAD MX), or run fixed-energy per dataset? | Fixed-energy; the master energy axis is a setpoint. | The energy Capability decision. | - -### Sample, detector, robot - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| GONIO-1 | Blocks-go-live | The MD3 microdiffractometer axis PV records, the full axis set, and the settling confirmation that 05A's live scan orchestration is Blu-Ice/DCSS and not a live MXCuBE deployment (the 2025 cluster paper says Blu-Ice/DCS for all three MX endstations; high confidence, but per-beamline confirmation is owed). | A `Goniometer` Asset on the EPICS floor; the DCSS-over-EPICS seam (the 07A / 2-BM pattern), not MXCuBE; PV records deployment config. | The Goniometer interface, axes, and the seam confirmation. | -| DET-1 | Blocks-go-live | The EIGER2 X 9M detector PV records, its SIMPLON REST endpoint, and any detector minimum-distance interlock (07A has one at 139 mm; 05A's is unknown). | An EIGER2 X 9M `Camera` commanded through the DCSS workflow; endpoint and interlock deployment config. | The detector interface and safety limit. | -| ENV-1 | Nice-to-have | The cryostream sample-cooling vendor and PV. | A `TemperatureController` Asset, settings blank. | The cryostream Model and PV. | -| ROBOT-1 | Nice-to-have | The ISARA sample-mounting robot (the same model as 07A). CORA would model autonomous sample exchange as a Procedure over the spine threaded through the `Subject` aggregate and gated by a Clearance, the i03 / i24 / 07A / MX3 shape. | The robot is deferred autonomous-loop machinery, not a beam-path Asset. | The sample-exchange Procedure and Subject custody thread. | -| DIAG-1 | Nice-to-have | The beam-position / XBPM and OAV-camera channel maps and PVs. | Read-only beam-position (graduated catalog `PositionMonitor`) and OAV (`Camera`) probes; channel maps blank. | The diagnostic bindings. | - -### Controls and technique scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DRIVE-1 | Blocks-go-live | The motion-controller box firmware / IPs behind the endstation, goniometer-base, and detector stages. | Families bound (MotionController), specifics blank. | The MotionController Models. | -| TECH-1 | Blocks-go-live | Do the MX Capabilities enter CORA's catalog, or stay deferred? The same owner-scope decision i03 opened; 05A reuses the pending `mx_data_collection` / `grid_scan` / `sample_exchange` Methods. | Methods deferred (pending Practices on the Site), no catalog Method coined. | The MX Capability scope. | diff --git a/docs/deployments/tps-07a/notes.md b/docs/deployments/tps-07a/notes.md deleted file mode 100644 index c42426edfca..00000000000 --- a/docs/deployments/tps-07a/notes.md +++ /dev/null @@ -1,115 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at TPS 07A: rotation macromolecular crystallography, each technique a [Catalog](../../catalog/methods.md) Method bound through an [NSRRC Practice](../nsrrc/index.md#the-techniques-adapted-here). TPS 07A reuses the MX Methods Diamond [I03](../i03/notes.md#techniques) introduced, so it coins nothing new.* - -TPS 07A's technique, rotation MX, is the macromolecular-crystallography shape CORA already saw at i03 (and at the Australian Synchrotron [MX3](../mx3/notes.md#techniques), and in its serial form at i24 and LCLS-MFX). The Methods render unlinked and are carried pending until the owner-scope decision (TECH-1) brings them into the catalog, exactly as at i03 and MX3. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| Rotation MX data collection | `mx_data_collection` | oscillation collection on the MD3 goniometer + the EIGER2 X 16M, orchestrated through Blu-Ice/DCSS; the i03 Method, pending (TECH-1) | -| Mesh / grid scan | `grid_scan` | mesh scan for crystal location / centring on the MD3, with Dozor spot-scoring (the Meshbest path); the i03 Method (TECH-1) | -| Autonomous sample exchange | `sample_exchange` | the ISARA robot load / centre / collect / unmount loop, a Procedure over the spine (ROBOT-1) | - -All three are recorded as pending [Practices](../nsrrc/index.md#the-techniques-adapted-here) on the NSRRC Site, reusing the same Method names Diamond i03 carries. - -### Why the Methods are reused, not coined - -TPS 07A brings a new Site and a new seam, not a new technique. Rotation MX, mesh-scan centring, and robot sample exchange are the i03 shapes, so TPS 07A binds the same pending Methods (`mx_data_collection`, `grid_scan`, `sample_exchange`) rather than coining anything; whether those Methods enter the catalog is the cross-facility owner-scope decision i03 opened (TECH-1), and TPS 07A reinforces the case at a further MX facility (after i03, NSLS-II FMX / AMX, MX3, and Sirius MANACA). The device Roles already exist (the MD3 presents Positioner via the graduated `Goniometer`, the EIGER2 presents Detector via `Camera`), so nothing new is needed in the device model either. - -The autonomous sample exchange reuses the i03 / i24 / MX3 autonomous-loop shape: a Procedure over the spine threaded through `Subject` custody, not a new device family (ROBOT-1). The mesh-scan Dozor spot-scoring and CHiMP crystal detection are `ComputePort` work (an Observe / Compute leg), not beamline Methods. - -The genuinely new things TPS 07A contributes are below the technique layer: a new Site (NSRRC) and the Blu-Ice/DCSS-over-EPICS orchestration seam at an MX beamline (see [Controls](controls.md)), which the technique vocabulary rides over unchanged. - -## Governance - -*Who may act at TPS 07A and the trust shape CORA applies. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority.* - -People and agents are facility principals at the [NSRRC Site](../nsrrc/index.md#safety-and-governance); on the beamline they surface through the actions they take. The human roster is not in the public control trees (GOV-1), so the principals are the design shape, not a registered list. The trees do expose two governance facts CORA maps onto its own model: LDAP-backed authentication (`ldap://10.7.1.1`) and a mandatory radiation-safety-training portal (`safetytraining.nsrrc.org.tw`). - -### Who acts - -CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the NSRRC Site. A TPS 07A beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. This is the same role kernel CORA seeds at every Site; NSRRC being a new Site is exactly the test that the Federation / Access kernel ports unchanged. - -The NSRRC mandatory training portal maps to CORA's **worldwide-invariant training axis**: a fact carried on the Access principals (has-this-person-completed-the-required-training), not a separate Clearance kind. CORA records it as a property of the principal rather than coining a new facility form (GOV-1). - -### The trust boundary - -CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may start a collection, move the robot, change the energy, override a caution, or commit a calibration. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer or its LDAP groups. It holds across the seam: a command CORA's EdgeConductor issues in place of DCSS (start an oscillation, drive a motor, arm the detector) is gated exactly as any spine command is. The facility proposal and cycle are a fact CORA's Campaign uses for custody. - -### Unattended autonomous collection - -TPS 07A's throughput model is unattended: the ISARA robot mounts a crystal, the MD3 centres it (mesh scan + Dozor scoring), the EIGER2 collects, the robot unmounts, repeat. That loop is where CORA's custody and trust shapes earn their keep, each crystal threaded through the `Subject` aggregate so its identity and provenance is tracked, the exchange a Procedure gated by a Clearance (ROBOT-1). If an autonomous Agent were added to choose which crystal to collect or when a dataset is good enough (the CHiMP crystal-detection output is the natural input), it would be a facility principal scoped at the Site, governed by the same trust boundary, with each choice recorded as a [Decision](../../architecture/modules/decision/index.md). None is declared yet. - -### The detector safety interlock - -The control tree exposes a hard detector minimum-distance interlock (139 mm): the detector stage may not approach the sample closer than that. This is a floor-level hardware safety limit, not a CORA-owned gate; CORA's conduct path respects it as a constraint on the detector-distance command, the same way it respects an EPICS soft limit. The PSS search-and-secure permit leaves that gate the hutch are not in the public source (PSS-1) and are carried as a confirm. - -## Model - -*The developer's by-kind index: where each CORA aggregate's TPS 07A content lives. It hosts no content of its own. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC -[modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at TPS 07A | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (EnergyAxis) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [The beamline](index.md#enclosures) (TPS-07A-OH optics, TPS-07A-EH experiment) | -| Facility (Federation); Zone, Conduit, Policy (Trust); Actor (Access) | [NSRRC Site](../nsrrc/index.md), [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### Deliberately not here yet - -This is a design-phase scaffold (descriptor + docs), mirroring the other reverse-engineered beamlines. Left out on purpose: - -- **No new Family.** TPS 07A's novelty is the Site and the seam, not its devices: the MD3 goniometer binds the graduated `Goniometer` (the i03 / MX3 MX precedent), the detectors `Camera`, the DCM `Monochromator`, the cryostream `TemperatureController`, the attenuator `Filter`, the beamstop `BeamStop`, the shutters `Shutter`, the mirrors `Mirror`, the stages `LinearStage` / `MotionController`. -- **The reused loose families.** `StorageRing` (the ring-current monitor) and `BeamPositionMonitor` (the beam-position diagnostic) are bound loose, each already allowlisted from earlier deployments; TPS 07A coins no new loose family. -- **The DCSS-over-EPICS seam.** TPS 07A drives a single EPICS floor with a Blu-Ice/DCSS orchestration layer above it, reached through an EPICS Device Handler Server. This is modelled as `ControlPort` actuation over EPICS plus a CORA EdgeConductor that replaces the DCSS orchestration, not new aggregates; it is the 2-BM TomoScan seam, not the MX3 multi-transport seam. See [Controls](controls.md). The MD3 axis PV records and the DCSS-vs-MXCuBE confirmation are GONIO-1. -- **The ISARA robot as a Procedure.** Autonomous sample exchange is a deferred Procedure over the spine threaded through `Subject` custody (ROBOT-1), reusing the i03 / i24 / MX3 shape, not a new device family. -- **The frame egress and mesh-scan compute.** The EIGER2 ZMQ / ASAP::O frame stream is a `TransferPort` leg into the Dataset of record; the Dozor spot-scoring and CHiMP crystal-detection are `ComputePort` work, an Observe / Compute leg off the control seam, not beamline Methods or Assets (DET-1). -- **No new Capability or Method.** Rotation MX reuses the pending i03 Methods (`mx_data_collection` / `grid_scan` / `sample_exchange`), recorded as Practices on the Site; TPS 07A reinforces the case at a further MX facility without coining any (TECH-1). -- **Operations and experiment views, integration scenarios, vendor Models.** A runbook and registered Assets for a beamline CORA does not yet drive would be invention; they land when the design firms and the team confirms. - -## Open questions - -*What CORA needs the NSRRC / TPS 07A team to confirm. This model is reverse-engineered from public open source (the [`light911/NSRRC_TPS07A`](https://github.com/light911/NSRRC_TPS07A) control tree and [`light911/TPS07A-Meshbest`](https://github.com/light911/TPS07A-Meshbest) app): the EPICS PV namespace (`07a:` / `07a-ES:`) is read from it, but per-device PV records, vendor identities, physical positions, the source, and the PSS signals are not. Each row is a fact the beamline team owns. It is a delete-on-answer queue.* - -Priorities: `Blocks-build`, `Blocks-go-live`, `Nice-to-have`. - -### Source and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-go-live | The insertion-device / front-end source: TPS 07A is fed by the IU22 in-vacuum undulator (per the SPXF spec page), but no source PV is in the public tree. | An insertion-device source, identity-only, no PV; the ring-current monitor stands in as the source representation. | The Source Asset and its PV. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit-leaf PVs. No PSS permit signals are in the public source. | The permit signal is a confirm note, not a guessed PV. | The Enclosure permit signals. | -| ENC-1 | Nice-to-have | The hutch layout and names: which devices sit in the optics hutch versus the experiment hutch? The trees expose no enclosure structure. | An optics hutch (DCM, mirrors) plus an experiment hutch (the MD3 / EIGER2 / robot). | The Enclosure set and roles. | - -### Optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DCM-1 | Nice-to-have | The double-crystal monochromator crystal cut and exact range, and the attenuator foil set. | A Si DCM over 6-20 keV and one Filter Asset, settings blank. | The Monochromator / Filter settings. | -| OPT-1 | Nice-to-have | The micro-focus optic delivering the ~2.9 x 1.8 micron spot: is it a KB mirror pair, and what are its PVs? The SPXF page states the focal spot, not the optic. | A KB micro-focus mirror system (`KBMirrors`, Mirror family), configuration blank. | The mirror Assets and PVs. | -| ENERGY-1 | Nice-to-have | Does TPS 07A scan energy as the measurement (anomalous / MAD MX), or run fixed-energy per dataset? | Fixed-energy; the master energy axis is a setpoint. | The energy Capability decision. | - -### Sample, detector, robot - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| GONIO-1 | Blocks-go-live | The MD3 microdiffractometer axis PV records (`07a-ES:` namespace, reached through the EPICS DHS), the full axis set, and the settling confirmation that the live scan orchestration is Blu-Ice/DCSS and not a live MXCuBE `mxcubecore` HardwareObjects deployment. (Public evidence is high-confidence DCSS; a live MXCuBE config for 07A would flip the seam to mixed.) | A `Goniometer` Asset (omega / kappa / phi + centring / alignment) on the EPICS floor; the DCSS-over-EPICS seam (the 2-BM pattern), not MXCuBE; PV records deployment config. | The Goniometer interface, axes, and the seam confirmation. | -| DET-1 | Blocks-go-live | The EIGER2 X 16M detector PV records and its SIMPLON REST endpoint, and whether the ZMQ frame egress has migrated to DESY ASAP::O in production. | An EIGER2 `Camera` commanded through the DCSS workflow; frames over ZMQ migrating to ASAP::O; endpoint deployment config. | The detector Model, interface, and frame-egress path. | -| ENV-1 | Nice-to-have | The cryostream sample-cooling vendor and PV. | A `TemperatureController` Asset, settings blank. | The cryostream Model and PV. | -| ROBOT-1 | Nice-to-have | The ISARA sample-mounting robot (mount / unmount trajectories gated on the MD3 state). CORA would model autonomous sample exchange as a Procedure over the spine threaded through the `Subject` aggregate and gated by a Clearance, the same shape as the i03 / i24 / MX3 loops. | The robot is deferred autonomous-loop machinery, not a beam-path Asset. | The sample-exchange Procedure and Subject custody thread. | -| DIAG-1 | Nice-to-have | The beam-position / XBPM and OAV-camera channel maps and PVs. | Read-only beam-position (graduated catalog `PositionMonitor`) and OAV (`Camera`) probes; channel maps blank. | The diagnostic bindings. | - -### Controls and technique scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DRIVE-1 | Blocks-go-live | The motion-controller box firmware / IPs behind the endstation, goniometer-base, and detector stages (EPICS motor records reached through the DHS). | Families bound (MotionController), specifics blank. | The MotionController Models. | -| TECH-1 | Blocks-go-live | Do the MX Capabilities (rotation data collection, mesh / grid scan) enter CORA's catalog, or stay deferred? This is the same owner-scope decision Diamond i03 opened; TPS 07A reuses the pending `mx_data_collection` / `grid_scan` / `sample_exchange` Methods. | Methods deferred (pending Practices on the Site), no catalog Method coined. | The MX Capability scope. | -| GOV-1 | Nice-to-have | The operator / beamline-scientist roster and review structure (the trees show LDAP auth at `ldap://10.7.1.1` and a mandatory training portal at `safetytraining.nsrrc.org.tw`, but no roster). | CORA's role kernel scoped at the Site; the training portal maps to the worldwide-invariant training axis on the principal. | The Actor roster and training-axis binding. | diff --git a/docs/deployments/xfm/notes.md b/docs/deployments/xfm/notes.md deleted file mode 100644 index e128b223420..00000000000 --- a/docs/deployments/xfm/notes.md +++ /dev/null @@ -1,106 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at XFM: scanning X-ray fluorescence microscopy, a [Catalog](../../catalog/methods.md) Method bound through an NSLS-II [Practice](../nsls2/index.md). XFM is the second scanning-XRF beamline (after 2-ID) and follows the same Method-deferral discipline.* - -XFM's science is element mapping: raster the sample through a focused beam and read the fluorescence spectrum at each point, in a step grid or a Maia continuous fly-scan. The Method below renders unlinked and stays pending until the owner-scope decision (METHOD-1) brings it into the catalog. - -| Technique | Mode | Detector | Status in CORA | -| --- | --- | --- | --- | -| Scanning XRF mapping | raster (step grid or Maia fly) | `EnergyDispersiveSpectrometer` (Xspress3 / Maia) | the 2-ID `scanning_fluorescence_microscopy` Method, pending; XFM is the 2nd consumer (METHOD-1) | -| XANES microspectroscopy | energy sweep over the `EnergyAxis` | `EnergyDispersiveSpectrometer` | the BMM energy-scan question; `energy_scan` deferred (ENERGY-1), no practice | -| XRF-tomography | raster x rotation | `EnergyDispersiveSpectrometer` | out of scope: no rotation axis in the profile (TECH-1) | - -### Why the Method stays pending - -XFM reuses the `scanning_fluorescence_microscopy` Method that 2-ID left pending. Unlike a loose device *Family* (which a second sighting promotes on a mechanical rule-of-three), a pending *Method* has no automatic promotion: it is coined by deliberate decision when a conduct-path needs it, the same discipline that keeps `energy_scan` deferred even across several consumers. XFM makes `scanning_fluorescence_microscopy` a two-consumer Method (2-ID + XFM), which strengthens the eventual case to coin it but does not force it in a descriptor scaffold (METHOD-1). The device Roles already exist (the SDD presents the energy-dispersive Sensor, the raster stage presents Positioner), so what is pending is the recipe, not a device shape. - -The XANES microspectroscopy leg sweeps the monochromator energy across an absorption edge, which leans on the deferred `energy_scan` Capability (the BMM ENERGY-1 question); no XANES practice is recorded until that Capability lands, the SRX / BMM discipline. The XRF fitting and any tomographic reconstruction are `ComputePort` work, not beamline Methods. - -## Governance - -*Who may act at XFM and the trust shape CORA applies. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority.* - -People and agents are facility principals at the [NSLS-II Site](../nsls2/index.md#safety-and-governance); on the beamline they surface through the actions they take. The human roster is not known from the profile collection (GOV-1), so the principals are the design shape, not a registered list. - -### Who acts - -CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the NSLS-II Site. An XFM beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. - -### The trust boundary - -CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may set the energy, start a raster map, run the Maia fly-scan, change the focusing optic, override a caution, or commit an energy calibration. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer. The NSLS-II proposal and cycle are a fact CORA's Campaign uses for custody. - -### The scanning map under custody - -XFM's defining operation is the raster XRF map: the UTS stage sweeps the sample through the focused spot while the detectors count per pixel. CORA's Campaign and Trust shapes are where that resolves: starting a map (step or Maia fly) is a command the trust boundary gates, and the per-map energy and flux normalization are facts under custody. If an autonomous Agent were added to drive a mapping survey (a common pattern at high-throughput microprobes), it would be a facility principal scoped at the Site, governed by the same trust boundary, with each choice recorded as a [Decision](../../architecture/modules/decision/index.md). None is declared yet. - -## Model - -*The developer's by-kind index: where each CORA aggregate's XFM content lives. It hosts no content of its own. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC -[modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at XFM | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (EnergyAxis) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [The beamline](index.md#enclosures) (4-BM-A optics, 4-BM-C endstation) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What this deployment graduates: nothing - -XFM is a clean **pure-reuse** scanning-XRF deployment, the second after 2-ID. It coins no Family and graduates nothing: the multi-element silicon-drift fluorescence detectors (the Xspress3 and the Maia) reuse `EnergyDispersiveSpectrometer` (graduated when 2-ID and 7-BM shared it), the raster stage reuses `LinearStage`, the scaler I0 channels reuse `FluxMonitor` (graduated in #353), the bending-magnet source binds the loose `Beam` PhotonBeam supply (the 2-BM / BMM precedent), and the monochromator / focusing optic / slits bind the catalog `Monochromator` / `Mirror` / `Slit`. The scanning XRF technique reuses the `scanning_fluorescence_microscopy` Method 2-ID left pending: XFM is its second consumer, which strengthens but does not coin it. - -### Deliberately not here yet - -This is a design-phase scaffold (descriptor + docs), mirroring 2-ID / SRX and the other NSLS-II beamlines. Left out on purpose: - -- **No catalog change.** XFM graduates nothing and coins nothing. `scanning_fluorescence_microscopy` stays pending (2-ID + XFM = 2 consumers; Methods have no mechanical promotion, the `energy_scan` deferral discipline; METHOD-1). XANES microspectroscopy leans on the deferred `energy_scan` Capability (ENERGY-1), no practice recorded. -- **The endstation-only profile.** The public profile collection exposes only the raster stage, the Xspress3, the scaler, and the Maia (in a bypass file). The bending-magnet source, the monochromator, the focusing optic, and the shutters are not in the profile, so they are carried confirm-only with no PV (no fabricated PVs; PROFILE-1). The model is honest about being thin: it asserts the device classes a BM XRF / XANES microprobe must have, with their handles pending the team. -- **The Maia detector.** XFM's signature fast continuous-mapping array (`XFM:MAIA`) is read from the bypass profile (`rvt/bypass40-maia.py`), not the active startup; it is modelled as a second `EnergyDispersiveSpectrometer` Asset and flagged (MAIA-1). -- **XRF-tomography.** Out of scope: the profile exposes an X/Y/Z raster stage but no rotation axis, so the raster-x-rotation XRF-tomography (the SRX shape) is not modelled (TECH-1). -- **Operations and experiment views, integration scenarios, vendor Models.** A runbook and registered Assets for a beamline CORA does not yet drive would be invention; they land when the design firms and the team confirms. - -## Open questions - -*What CORA needs the XFM team to confirm. This model is reverse-engineered from public open source (the `NSLS2/xfm-profile-collection` bluesky / ophyd startup files), which is endstation-only: the raster stage and detectors are read from the `startup/*.py` device classes, but the bending-magnet source, the optics, and the shutters are not in the profile and are carried confirm-only. Each row is a fact the beamline team owns. It is a delete-on-answer queue.* - -Priorities: `Blocks-build`, `Blocks-go-live`, `Nice-to-have`. - -### Source and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Nice-to-have | The 4-BM bending-magnet source parameters (critical energy, fan, the front-end acceptance). 4-BM is a bending magnet, not an insertion device. | A bending-magnet source, recorded as a PhotonBeam Supply (the 2-BM / BMM precedent). | The source modelling. | -| PROFILE-1 | Blocks-build | The public profile collection exposes only the endstation (the raster stage + detectors). What are the source, monochromator, focusing-optic, and shutter device handles? They are carried confirm-only with no PV here. | The optics exist physically (a BM XRF / XANES microprobe needs a DCM + focusing optic + shutters); their PVs await the team. | The optics device handles. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit-leaf PVs and the front-end / photon shutter PVs (not in the profile collection). | The permit and shutter signals are confirm notes, not guessed PVs. | The Enclosure permit + shutter signals. | -| ENC-1 | Nice-to-have | The hutch names / numbering and the A / B / C layout. The endstation PV zone is `XF:04BMC`; the optics zone is inferred. | An optics hutch (4-BM-A) plus the endstation (4-BM-C). | The Enclosure set. | - -### Optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DCM-1 | Nice-to-have | The monochromator crystal cut (Si(111) is the known 4-BM crystal), d-spacing, and energy range. Not in the profile collection. | One `Monochromator` Asset, crystal settings blank. | The Monochromator settings. | -| OPT-1 | Nice-to-have | The microfocusing optic type (a KB mirror pair or a capillary) and its parameters. Not in the profile collection. | One `Mirror` Asset (the focusing optic), type to confirm. | The focusing-optic modelling. | -| ENERGY-1 | Nice-to-have | Is energy scanned as the measurement (XANES microspectroscopy sweeps the DCM across an edge), warranting the energy-scan Capability the catalog anticipates? | XANES mapped to the deferred energy_scan Capability (the BMM question). | The spectroscopy Capability decision. | - -### Sample and detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The Xspress3 element count and ROI map (the profile configures four channels). | A four-channel `EnergyDispersiveSpectrometer` Asset; ROIs to confirm. | The fluorescence-detector modelling. | -| MAIA-1 | Nice-to-have | The Maia continuous-mapping detector: its element count, live status, and whether it is the primary mapping detector. It is in a bypass profile file (`rvt/bypass40-maia.py`), not the active startup. | A second `EnergyDispersiveSpectrometer` Asset (the Maia array) for fast continuous mapping. | The Maia detector modelling. | -| DIAG-1 | Nice-to-have | The SIS3820 scaler flux-channel map (which channels are I0, transmitted, the Maia deadtime). | Read-only flux (`FluxMonitor`) channels; the map blank. | The FluxMonitor bindings. | - -### Controls and technique scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DRIVE-1 | Blocks-go-live | The raster-stage and optics motion-controller box models, firmware, IPs. | Family bound (MotionController), specifics blank. | The MotionController Models. | -| METHOD-1 | Blocks-go-live | Does the scanning XRF microprobe technique (`scanning_fluorescence_microscopy`) enter CORA's catalog as a Method, or stay pending? XFM is the second consumer after 2-ID. | The Method reused pending (no mechanical promotion for Methods; the energy_scan deferral discipline). | The scanning-XRF Method scope. | -| TECH-1 | Nice-to-have | Beyond XRF mapping, does XFM run XANES microspectroscopy and XRF-tomography in CORA scope? XANES leans on the deferred energy_scan; XRF-tomography would need a rotation axis (not in the profile). | XRF mapping modelled; XANES deferred (energy_scan); XRF-tomography out of scope. | The technique scope. | diff --git a/docs/deployments/xfp/notes.md b/docs/deployments/xfp/notes.md deleted file mode 100644 index ba80f8ba7b8..00000000000 --- a/docs/deployments/xfp/notes.md +++ /dev/null @@ -1,181 +0,0 @@ -# Notes - -## Techniques - -*What the modelled part of XFP is designed to do, as intent. First cut.* - -A technique is a portable [Catalog](../../catalog/methods.md) Method; a [Practice](../nsls2/index.md#the-techniques-adapted-here) is how a facility adapts it. XFP does one technique, **X-ray footprinting**, in two delivery modes: static / capillary-flow, and shutterless high-throughput. The Method below renders unlinked and is carried pending until the owner-scope decision (`TECH-1`) brings it into the catalog. - -| Technique | Catalog method | Notes | -| --- | --- | --- | -| X-ray footprinting (capillary-flow / static) | `x_ray_footprinting` | gate a timed white-beam dose onto a flowing solution capillary or flow-cell sample, recording exposure time x flux x attenuation as the delivered dose; the fleet's first dose-delivery Method, new to the catalog; readout is offline mass spec (`TECH-1`, `READOUT-1`) | -| High-throughput footprinting (HTFly) | `x_ray_footprinting` | sweep a fly-cell row through the defining slit at a set stage velocity so the exposure (dose) is the slit gap over the velocity, across a 96-well plate; the same `x_ray_footprinting` Method with the HTFly stage as the dose-timing (`TECH-1`, `HT-1`) | - -Both modes need the [white-beam chain](source.md) (the mirror, the slits, the Al filter wheel for dose rate), the [dose gating](source.md) (the timed shutters or the delay-generator-fired Uniblitz, or the HTFly velocity), the [sample side](sample.md) (a stage and the delivery pump), and the [flux monitors](detector.md) (to record the delivered dose). They differ only in how the exposure is timed and how many samples are handled. - -### The technique is dose delivery, and the readout is offline - -This is the heart of what makes XFP a new shape for CORA. X-ray footprinting is not a measurement technique in the sense the rest of the fleet uses: the beamline does not record a structural signal. It **delivers a controlled radiolytic dose** to a biological macromolecule in solution, generating hydroxyl radicals that covalently modify the molecule at solvent-accessible sites. The modified sample is then analysed **offline by mass spectrometry**, which reveals which residues were exposed and thus maps the molecule's surface and conformational changes. - -So the Method `x_ray_footprinting` is a **dose-delivery** Method: - -- its controlled variable is the delivered dose (exposure time times flux times attenuation), not a detector setting; -- its product is a footprinted sample plus a dose record, not a measurement frame; -- its structural readout is the offline-readout seam (mass spec, downstream and off the beamline, `READOUT-1`). - -That is why `x_ray_footprinting` is proposed as a Method distinct from anything in the catalog: not because the optics are unusual (a white beam, a filter, a shutter), but because the experiment shape, dose-in, sample-out, structure-read-elsewhere, is genuinely new. Whether the catalog ultimately holds a `x_ray_footprinting` Capability, or a broader "controlled-dose / irradiation" Capability with footprinting as a Practice adaptation, is the owner-scope decision (`TECH-1`); XFP records the case, it does not mint the vocabulary. The matching Site Practices (`XFP_footprinting_practice`, `XFP_high_throughput_footprinting_practice`) are carried pending in the [NSLS-II Site](../nsls2/index.md#the-techniques-adapted-here); each binding lands when its Capability does. - -### A time-resolved mode, deferred - -The profile collection also contains a time-resolved capillary-flow mode (a stopped-flow style mixing experiment before irradiation), but it is flagged unfinished in the source, so no Practice is recorded for it here; it is a later mode that would reuse the same `x_ray_footprinting` Method with a mixing step in the Procedure (`TECH-1`). - -### Not modelled yet - -The concrete acquisition recipes are not written yet. For footprinting that is the dose series (the set of exposure times or filter thicknesses that build a dose-response curve), the flow program that presents fresh sample, the aliquot-collection pattern, and the flux-to-absorbed-dose calibration that converts the measured flux to the dose the sample received (a seam constant that lives in offline analysis, `DOSE-1`). The downstream linkage to the offline mass-spec result is the offline-readout seam, not a beamline recipe (`READOUT-1`). These join as the deployment approaches the point where CORA drives XFP. - -Whether `x_ray_footprinting` enters CORA's catalog is an owner-scope decision on [Model](#model): a modelling exercise reinforces the case but does not mint cross-facility Method vocabulary on its own. See [Open questions](#open-questions) for the world-facts to confirm first. - -## Governance - -*Who will act at XFP, and the trust shape that will gate it. First cut.* - -Governance at XFP follows the same model as the other NSLS-II beamlines: people and autonomous agents are facility principals at the [NSLS-II Site](../nsls2/index.md#safety-and-governance), and on the beamline they surface through the actions they take. Their commands are gated by a trust shape (a Zone grouping the beamline's resources, a Conduit binding the surfaces that may issue commands, and Policies that say who may do what). - -XFP is not yet driven by CORA, so this shape is not yet instantiated. As a modelling-exercise scaffold, the deployment is descriptor and docs today, so the concrete Zone, Conduit, and Policy instances are deliberately not materialized. XFP is a Case Western Reserve University partner beamline operated within NSLS-II, so its operator and review structure is carried pending on the [NSLS-II Site](../nsls2/index.md#safety-and-governance), with the partner-beamline operating model itself an open question (`GOV-1`). - -### The safety boundary - -The safety tier is the other piece that is not yet settled. Only the front-end photon-shutter enable status is in the beamline's profile collection (interlock-derived; plans refuse to open the shutter when it is disabled), so the Enclosure permit leaves and the rest of the search-and-secure structure are carried pending and not invented here (`PSS-1`). What is already settled is the boundary: clearances (the safety forms that must be active to start) are issued at the [NSLS-II Site](../nsls2/index.md#safety-and-governance), not on the beamline, and the beamline links up to them. - -XFP brings two distinctive hazards: a high-flux white beam, and the dose it delivers. They land with the equipment and the experiment that bring them, and an experiment Clearance would carry them. - -| Hazard class | Where it lands | Tracking | -| --- | --- | --- | -| High-flux white / pink X-ray beam | the [optics](index.md) and [endstation](index.md) enclosures (FE:C17B, XF:17BM / XF:17BMA) (`ENC-1`) | (`PSS-1`, `WHITE-1`) | -| Delivered radiolytic dose to biological samples | the [dose-delivery gating](source.md) and the [Sample](sample.md) side | (`DOSE-1`, `SUBJECT-1`) | -| Vacuum white-beam optics | the [Source](source.md) walk | (`SUP-1`) | -| Biological samples, buffers, and fluidics | the [Sample](sample.md) delivery chain | (`FLOW-1`, `SUBJECT-1`) | - -The high-flux white beam is the interlocked hazard; its permit leaves stay pending until the PSS signals are confirmed (`PSS-1`). The delivered dose is itself a controlled hazard at a footprinting beamline, distinctive to its dose-delivery character, and travels with the dose-gating chain and the Subject (`DOSE-1`, `SUBJECT-1`). The biological-sample and fluidics hazards travel with the delivery chain (`FLOW-1`). None of these is invented; each is carried against its question. - -### When the shape lands - -The concrete Zone, Conduit, and Policy instances, and the operator pool, land when the deployment approaches the point where CORA drives XFP, following the [2-BM governance](../2-bm/governance.md) shape. Because XFP shares the NSLS-II EPICS and ophyd floor with the rest of the fleet, it re-tests the Site and Federation kernel rather than introducing a new trust model. The distinctive wrinkles are the partner-beamline operating model (`GOV-1`) and the offline-readout seam: a Conduit would bound the dose-delivery command surfaces, while the downstream mass-spec analysis sits outside the beamline's trust boundary entirely (`READOUT-1`). The Zone groups the same optics and endstation resources the [inventory](index.md) lists; the Policies bind to the NSLS-II operator roles carried pending at the Site (`GOV-1`). - -## Model - -*The developer's by-kind index: where each CORA aggregate's XFP content lives, how it models a beamline with no detector and an offline readout, and the record of what is deliberately deferred. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC [modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at XFP | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [the index](index.md#enclosures) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### What makes XFP new - -XFP is the most structurally distinct deployment in the fleet. Every other beamline CORA models is a measurement beamline: condition a beam, place a sample, record a detector signal. XFP is a **dose-delivery** beamline with **no detector**. Its contributions: - -- **Dose as the experiment variable.** The controlled quantity is the delivered radiolytic dose (exposure time times incident flux times attenuation), not a detector setting. The whole apparatus, the timed shutters, the delay-generator-fired millisecond fast shutter, the Al filter wheel, and the flux monitors, exists to set and measure that dose. -- **A sample-and-record output, not frames.** A footprinting run produces a footprinted sample (an irradiated aliquot) plus a dose record (exposure time, filter thickness, flux time-series, well / tube identity). There are no measurement frames. -- **The offline-readout seam.** The structural readout (which residues were modified) is offline mass spectrometry, downstream and off the beamline. CORA is the system of record for the dose and the sample provenance; the MS analysis is a separate, later step. -- **A solution Subject.** Like LIX, the specimen is a biological macromolecule in a buffer, delivered fluidically. - -### No new families - -XFP coins no new Family and changes nothing in the catalog. The whole device tree reuses existing vocabulary; the novelty is in the Method, the Subject, and the seam, not in device classes. - -- **17-BM is a bending-magnet, white / pink beam source** (no insertion device, no monochromator in the footprinting path); machine state is observed through the loose `StorageRing`, and the white-versus-mono scope is `SRC-1` / `WHITE-1`. -- **The dose chain reuses the catalog:** the bendable mirror binds `Mirror`; the slits bind `Slit`; the Al filter wheel binds `Filter` (it sets the dose rate); the timed shutters bind `Shutter`; the delay generator that fires the millisecond Uniblitz fast shutter binds `TimingController` (its opening-time setpoint is the dose time); the QuadEM electrometers bind `FluxMonitor`; the Sydor beam-position monitor binds the graduated catalog `PositionMonitor` (presenting `Sensor`, distinct from `FluxMonitor` by measuring beam position rather than flux; per-Asset channel map open, `DIAG-1`); the sample stages bind `LinearStage`. - -### How a beamline with no detector is modelled - -XFP has no Detector-role imaging device, and CORA models that honestly rather than inventing one: - -- the detection side holds **flux / dose monitors** (`FluxMonitor`, the graduated catalog `PositionMonitor`), which measure the delivered dose, not a sample signal; -- the dose-delivery role is expressed by the **Source gating** (Shutter + `TimingController` + `Filter`) plus those flux monitors, not by a detector; -- the structural readout is the **offline-readout seam**: the run's product is a footprinted sample plus a dose record, and the mass-spec analysis happens downstream, off the beamline (`READOUT-1`). - -This is the deliberate inversion: where a measurement beamline's run is anchored on a Dataset of detector frames, an XFP run is anchored on a dose record and a Subject (the footprinted aliquot), with the structural Dataset produced elsewhere and linked back later. - -### The FlowController rule-of-three - -The one device reuse worth naming is the sample-delivery pump. Its anatomy is a settable flow / pump actuator (rate / volume setpoints, a run command), exactly the catalog `FlowController` Family that i22, 7-BM, and LIX already use. So the pump **reuses** `FlowController`; it coins nothing. XFP is its **fourth** consumer (i22, 7-BM, LIX, XFP), and `FlowController` has now **graduated** into the catalog on this rule-of-three: it presents the existing `Regulator` Role (the settable-actuator sibling of `TemperatureController`), earned across i22 / 7-BM / LIX / XFP, like `EmissionSpectrometer` and `TemperatureController` before it. The wider fluidic chain beyond the pump (selector valves, SEC columns, flow cells, fraction collectors) stays in the `ControlPort` seam pending its own rule-of-three (`FLUID-1`). - -### Deliberately not here yet - -- **The fraction collector Family (`FC-1`).** The fraction collector is a PV-bound aliquot-routing actuator with no clean existing Family. At n=1 CORA does not coin a `FractionCollector` Family; it is carried in the sample-custody seam (the footprinted-sample hand-off to offline MS). -- **The 96-well plate handler (`HT-1`).** The plate is addressed in pure Python (8 columns x 12 rows, a coordinate table, no robot and no PV); it is a Procedure over the spine plus a Subject custody thread, the i03 / MX3 / LIX custody-as-Procedure precedent (XFP at the no-robot end of that spectrum), not a device Family. -- **The offline mass-spec readout (`READOUT-1`).** The structural analysis is downstream, off the beamline, and absent from the profile collection. A future integration could link the offline MS result back to the dose record; it is not modelled here. -- **The Method.** Whether `x_ray_footprinting` (or a broader controlled-dose / irradiation Capability) enters CORA's catalog is an owner decision; the Practices render unlinked, pending (`TECH-1`). -- **The intermittently-connected and out-of-scope hardware.** The 0-9 mm Al z-attenuator, the beam-defining pinhole stages, the greenfield Galil stages, and the temperature / bias diagnostics are intermittently connected or read-only and not modelled as core devices (`ATTN-1`, `TEMP-1`); the monochromatic XAS endstation (ES:3) is a separate endstation, out of scope for footprinting (`WHITE-1`). -- **The time-resolved mixing mode.** The stopped-flow time-resolved footprinting mode is flagged unfinished in the source; no Practice is recorded for it (`TECH-1`). -- **The simulated devices and full asset-tree scenarios.** No `test_xfp_*.py` registers the asset tree, and no vendor Models are bound. -- **Operations and experiment views.** A runbook and live experiment view for a beamline CORA does not yet drive would be invention; see the note on the [index](index.md#not-yet-documented). - -## Open questions - -*What CORA needs the XFP team to confirm before the model can be trusted.* - -XFP was reverse-engineered from the beamline's own bluesky profile collection ([NSLS2/xfp-profile-collection](https://github.com/NSLS2/xfp-profile-collection)), so the control handles on the [device pages](index.md) are the beamline's real PVs, read from the `startup/` files rather than confirmed by staff. Each row below is a fact the beamline team owns, not a CORA modelling choice (those are on [Model](#deliberately-not-here-yet)). It is a delete-on-answer queue. Priorities are `Blocks-build`, `Blocks-go-live`, and `Nice-to-have`. - -### Topology and scope - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| ENC-1 | Blocks-go-live | Are the optics (FE:C17B, XF:17BM-OP / XF:17BMA-OP) and the endstations (XF:17BMA-ES:1, ES:2) separate hutches? | Two enclosures: a `xfp-optics` zone and the `xfp-endstation` hutch. | The Enclosure grouping. | -| SRC-1 | Nice-to-have | The 17-BM source (a bending magnet is implied by the name and the white-beam design; the profile collection exposes no source device, only ring current). | A bending-magnet source, observed only through the machine state. | The source Asset detail. | -| WHITE-1 | Blocks-go-live | Is routine footprinting white beam or pink beam (filtered by the mirror cutoff and the Al filters), and is there any monochromator in the footprinting path? (A DCM exists only on a separate XAS endstation, ES:3, excluded here.) | White / pink beam, no monochromator in the footprinting path; ES:3 out of scope. | The beam-conditioning model. | - -### Source and optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| MACHINE-1 | Nice-to-have | The storage-ring state XFP reads (only the ring current is read for a beam-present suspender). | Observe-only machine state, a loose `StorageRing`; the rest pending. | The machine-state observation. | -| OPT-1 | Nice-to-have | The front-end mirror coating and bend mechanism (a bendable mirror with a Bend focus axis and thermocouples). | A bendable focusing `Mirror`; coating and bend pending. | The mirror Asset detail. | -| OPT-2 | Nice-to-have | The blade-axis roles of the white-beam, PB / PDS, and ADC defining slits (the ADC horizontal gap sets the HTFly exposure window). | Four-blade / center-gap slits bound to `Slit`. | The slit Asset detail. | -| ATTN-1 | Blocks-go-live | The attenuation chain that sets the dose RATE: the eight-position Al filter wheel, plus the intermittently-connected 0-9 mm Al z-attenuator and the beam-defining pinhole apertures. | The filter wheel binds `Filter`; the pinhole / z-attenuator are further attenuators carried pending. | The dose-rate attenuator modelling. | - -### Dose delivery - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DOSE-1 | Blocks-go-live | The dose-delivery chain: the timed shutters (the EPS pre-shutter, the PPS photon shutter, the inner DIODE sample shutter), the DG535 delay generator that fires the millisecond Uniblitz fast shutter (its opening-time setpoint is the dose time), and the flux-to-absorbed-dose calibration (which lives in offline analysis). | Seconds-scale dose is software-timed on the pre-shutter (`Shutter`); millisecond dose is the delay-generator-fired Uniblitz (`TimingController`); the dose calibration is offline. | The dose-delivery modelling. | - -### Sample and delivery - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SAMPLE-1 | Blocks-go-live | The capillary-flow sample stage axes and how a flowing solution capillary mounts in the beam. | A `LinearStage` for the capillary-flow stage; the flow is the fluidic seam. | The sample-stage modelling. | -| HT-1 | Blocks-go-live | The high-throughput modes: the 96-well plate stage and addressing (8 columns x 12 rows, addressed in pure Python with a coordinate table, no robot and no PV), and the shutterless HTFly stage (exposure = defining-slit gap over stage velocity). | `LinearStage` stages; the well addressing and the HTFly dose-timing are Procedures over the spine plus a Subject custody thread. | The high-throughput modelling. | -| FLOW-1 | Nice-to-have | The sample-delivery pumps (an M50 pump and a PHD2000 infusion pump, both with rate / volume setpoints), which units are live, and the per-Asset pump detail. | The pump binds the graduated catalog `FlowController` (presents Regulator; earned on the i22 / 7-BM / LIX / XFP rule-of-three); the wider fluidic chain stays in the seam (`FLUID-1`). | The pump modelling; the CORA decision is on [Model](#deliberately-not-here-yet). | -| FC-1 | Nice-to-have | The fraction collector (a PV-bound aliquot-routing actuator: a collect / waste valve, a tube index, a fill pattern) that captures footprinted aliquots, and whether it earns a Family. | Carried in the sample-custody seam (the footprinted-sample hand-off to offline MS); no `FractionCollector` Family coined at n=1. | The fraction-collector modelling. | -| SUBJECT-1 | Nice-to-have | The solution Subject: a biological macromolecule (protein / nucleic acid) in a buffer, irradiated, with its own provenance. | A liquid Subject; the footprinted aliquot is the run's output, carried to offline MS. | The Subject modelling. | -| TEMP-1 | Nice-to-have | The temperature / bias diagnostics (the SR630 thermocouple monitor and the Sydor bias / thermocouple controller), used as alignment-flux proxies. | Read-only diagnostics, not core footprinting devices; deferred. | The temperature-diagnostic modelling. | - -### Detection and readout - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DET-1 | Blocks-go-live | The flux / dose monitors: the QuadEM electrometers (incident flux plus a per-exposure time-series), the DIODE PDM array-logger, and which channels measure the delivered dose. | `FluxMonitor` Assets; the channel map and the dose computation carried pending. | The flux / dose-monitor modelling. | -| DIAG-1 | Nice-to-have | The Sydor beam-position monitor (per-quadrant currents, beam x / y, a sum-current total flux) and the per-Asset position-versus-intensity split. The `PositionMonitor` Family itself is settled (graduated catalog Family presenting `Sensor`). | A graduated catalog `PositionMonitor` (earned across the wide fleet that shares it); only the per-Asset channel map is pending. | The beam-position-monitor channel map. | -| READOUT-1 | Blocks-go-live | The offline mass-spectrometry readout: what artifact the beamline hands off (a footprinted aliquot in a fraction-collector tube? a capillary?), whether a sample-ID barcode is recorded, and where the dose record is the system of record. | The beamline produces a footprinted sample plus a dose record; the MS structural analysis is downstream, off the beamline. | The offline-readout seam. | - -### Control and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| CTRL-1 | Blocks-go-live | Are the EPICS PV handles read from the profile collection current and correct, and is the data plane Kafka plus Redis (no Tiled, no queue-server)? | The handles in the descriptor are taken from the profile collection and carried confirm; the data plane is the seam CORA's edge replaces. | Verifying each Asset's control handle and the data plane. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit signals and the front-end / photon shutters (only the front-end photon-shutter enable status is in the profile collection). | Permit leaves to be named; not invented here. | The Enclosure permit signals and the safety tier. | -| SUP-1 | Nice-to-have | The vacuum extent (the white-beam optics) and the cooling supply, plus the footprinting consumables (buffers, radical scavengers, the flow medium). | Photon beam, cooling water, and vacuum on the optics; the consumables as Supply. | The Supply observations. | -| GOV-1 | Nice-to-have | The NSLS-II operator pool and safety-review structure, and XFP's partner-beamline (Case Western) operating model. | Carried pending on the NSLS-II Site, not instantiated per beamline. | The governance principals. | - -### Technique - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| TECH-1 | Blocks-go-live | Does X-ray footprinting (the dose-delivery technique, with offline MS readout) enter CORA's catalog as a Capability / Method? | Deferred: carried as pending Practices; `x_ray_footprinting` is new, the fleet's first dose-delivery Method; not coined. | The technique Capability. | diff --git a/docs/deployments/xpd/notes.md b/docs/deployments/xpd/notes.md deleted file mode 100644 index d351174554e..00000000000 --- a/docs/deployments/xpd/notes.md +++ /dev/null @@ -1,109 +0,0 @@ -# Notes - -## Techniques - -*What CORA would run at XPD: powder-diffraction and total-scattering techniques, each a [Catalog](../../catalog/methods.md) Method. XPD is the NSLS-II twin of the Diamond [I11](../i11/notes.md#techniques) (powder diffraction) and [I15-1](../i15-1/notes.md#techniques) (total scattering / PDF) beamlines, and it follows their deferral exactly.* - -XPD's techniques are powder diffraction and total scattering, a science domain Diamond's i11 and i15-1 brought to CORA as new Capabilities. As there, the Methods below render unlinked and are carried pending until the owner-scope decision (TECH-1) brings them into the catalog. - -| Technique | Mode | Notes | -| --- | --- | --- | -| Powder diffraction | monochromatic, flat panel | Debye-Scherrer rings on the flat panel at a chosen energy; the i11 Capability, new Capability pending (TECH-1) | -| Total scattering / PDF | fixed high energy, close detector | wide-Q on the flat panel at a close detector distance; the i15-1 Capability, new Capability pending (TECH-1) | -| Variable-temperature diffraction | over a temperature ramp | the same, over a ramp on the sample-environment stages (TEMP-1) | -| Autonomous sample exchange | n/a | a Procedure over the spine, threaded through `Subject` custody and gated by a Clearance (ROBOT-1) | - -All the scattering techniques need the [diffractometer and sample stages](sample.md), the [flat-panel detectors](detector.md), and the detector distance; the exposure shutter gates the frames. - -### Why the Capabilities stay deferred - -Diamond i11 and i15-1 opened the question of whether the powder-diffraction and total-scattering Capabilities enter CORA's catalog (TECH-1), and `main` deliberately left them pending: a powder or PDF measurement is a new science Capability binding device Roles that already exist (the flat panel presents Detector, the diffractometer and mono present Positioner), so what is new is the Capability, not a device shape. XPD reinforces the case for both at a second facility without coining either, the same earn-the-abstraction discipline the deferred `xpcs` (CHX), `scanning` (HXN), and `energy_scan` (BMM) Capabilities follow. Because the defining Capabilities are not in the catalog, XPD records **no Practice** in the [NSLS-II Site](../nsls2/index.md#the-techniques-adapted-here); the binding lands when the Capability does. - -The azimuthal integration and pair-distribution-function reduction (the Fourier transform of the total-scattering structure function into a real-space PDF) are `ComputePort` work, not beamline Methods. The autonomous sample exchange reuses the i03 / i15-1 autonomous-loop shape: a Procedure over the spine, not a new device family (ROBOT-1). - -## Governance - -*Who may act at XPD and the trust shape CORA applies. This is CORA's governance design landing on the beamline, not a description of the beamline's current controls authority.* - -People and agents are facility principals at the [NSLS-II Site](../nsls2/index.md#safety-and-governance); on the beamline they surface through the actions they take. The human roster is not known from the profile collection (GOV-1), so the principals are the design shape, not a registered list. - -### Who acts - -CORA brings its own Access model: a small set of facility roles (operator, beamline scientist, safety reviewer, and the autonomous-agent and service principals) scoped at the NSLS-II Site. An XPD beamtime is run by an operator or beamline scientist Actor; a safety reviewer holds the clearance authority. - -### The trust boundary - -CORA's Trust BC (Zone, Conduit, Policy) gates every command by who is acting and what the beamline state allows: who may start an acquisition, change the detector distance, run a temperature program, override a caution, or commit a calibration. This authority is CORA's own, expressed per Actor, not inherited from the beamline's controls layer. The NSLS-II proposal and cycle are a fact CORA's Campaign uses for custody. - -### High-throughput and the sample robot - -XPD's strength is throughput: a sample-array stage and a sample-changing robot let it run many powders unattended, often across temperature ramps. That is where CORA's custody and trust shapes earn their keep. CORA would model the autonomous exchange as a Procedure over the spine, threaded through the `Subject` aggregate so each sample's identity and provenance is tracked, and gated by a Clearance, the same shape as the I03 macromolecular-crystallography loop and the I15-1 powder exchange (ROBOT-1). If an autonomous Agent were added to choose the next sample or decide when a pattern is good enough, it would be a facility principal scoped at the Site, governed by the same trust boundary, with each choice recorded as a [Decision](../../architecture/modules/decision/index.md). None is declared yet. - -## Model - -*The developer's by-kind index: where each CORA aggregate's XPD content lives. It hosts no content of its own. Design-phase scaffold.* - -For the aggregate shapes see the [architecture model](../../architecture/model.md) and the per-BC -[modules](../../architecture/modules/index.md). - -| Aggregate (BC) | Where at XPD | -| --- | --- | -| Asset (Equipment) | the stage pages: [Source](source.md), [Sample](sample.md), [Detector](detector.md) | -| Computed / virtual axes (Equipment) | [Source](source.md) (EnergyAxis) | -| Capability, Method (Recipe) | [Techniques](#techniques) | -| Enclosure (Enclosure) | [The beamline](index.md#enclosures) (28-ID-A optics, 28-ID-C experiment) | -| Zone, Conduit, Policy (Trust); Actor (Access) | [Governance](#governance) | -| Procedure, Recipe, Caution, Supply, Subject, Run, Campaign, Dataset, Decision | deferred (design-phase; see below) | - -### Deliberately not here yet - -This is a design-phase scaffold (descriptor + docs), mirroring the other NSLS-II and Diamond beamlines. Left out on purpose: - -- **No new Family.** XPD is a reuse-and-reinforce deployment, the NSLS-II twin of Diamond i11 (powder diffraction) and i15-1 (total scattering / PDF): the flat panels bind `Camera`, the flux counters `FluxMonitor`, the sample environment `TemperatureController` (which i11 graduated, reinforced here at a second facility), the double-Laue monochromator `Monochromator`, the mirror `Mirror`, the pinhole `Aperture`, the exposure shutter `Shutter`. -- **The graduated `PositionMonitor`.** The optics-hutch beam-position monitor binds the graduated catalog `PositionMonitor` Family that several APS and NSLS-II deployments share: it presents the `Sensor` Role, earned across the wide fleet that shares it, distinct from `FluxMonitor` by measuring beam position rather than flux. The per-Asset ion-chamber / quad-electrometer channel map stays open (DIAG-1), recorded in the promotion-review register. -- **No new Capability or Method.** Powder diffraction and total scattering sit on the deferred `powder_diffraction` / `total_scattering` Capabilities Diamond i11 and i15-1 left pending (TECH-1); XPD reinforces both without coining either and records no Practice. The azimuthal integration and PDF reduction are `ComputePort` work. -- **The autonomous sample robot.** Modelled as a deferred Procedure over the spine threaded through `Subject` custody (ROBOT-1), reusing the i03 / i15-1 autonomous-loop shape, not a new device family. -- **The high-resolution channel** alongside the modelled main PDF channel: the high-resolution monochromator (`Mono:HRM`, in the 28-ID-C hutch) and the downstream high-resolution endstation (28-ID-D) are noted and deferred together (ENDSTATION-1), the way SRX deferred its micro endstation and 32-ID modelled one of several instruments. -- **The calibration diffractometer (`Dif:2`)** and its Ecal wavelength-calibration routine (scanning against a standard to fit the beam wavelength) are a routine powder/PDF operation, deferred to a named question (CALIB-1) rather than modelled at this design phase. The dormant multi-analyzer stage (`MAD:DMS`) and the mono beam-defining slits (`Slt:MB1` / `Slt:MB2`) are deferred alongside it. -- **The in-situ / operando accessories**: a QEPro UV-Vis spectrometer read in parallel with the diffraction pattern (a distinct optical-spectroscopy modality, not a `Camera`), the gas switcher, and the flash-sintering / electrochemistry power system, deferred to a named question (OPERANDO-1); the UV-Vis channel would need its own family decision when it lands. -- **Operations and experiment views, integration scenarios, vendor Models.** A runbook and registered Assets for a beamline CORA does not yet drive would be invention; they land when the design firms and the team confirms. - -## Open questions - -*What CORA needs the XPD team to confirm. This model is reverse-engineered from public open source (the [`NSLS2/xpd-profile-collection`](https://github.com/NSLS2/xpd-profile-collection) profile collection): the EPICS PVs are read from it, but vendor identities, physical positions, and the source and endstation configuration are not. Each row is a fact the beamline team owns. It is a delete-on-answer queue.* - -Priorities: `Blocks-build`, `Blocks-go-live`, `Nice-to-have`. - -### Source and safety - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| SRC-1 | Blocks-go-live | The source: 28-ID is a damping-wiggler beamline, but no source PV or parameters are in the profile collection. | An insertion-device (damping wiggler), identity-only, no PV. | The Source Asset PV and settings. | -| PSS-1 | Blocks-go-live | The PSS search-and-secure permit-leaf PVs. Only the endstation exposure shutter (`XF:28IDC-ES:1{Sh:Exp}`) is in source, not the front-end PPS leaves. | The permit signal is a confirm note, not a guessed PV. | The Enclosure permit signals. | -| ENDSTATION-1 | Nice-to-have | The high-resolution channel: the high-resolution monochromator (`Mono:HRM`, in the 28-ID-C hutch) and the downstream high-resolution endstation (28-ID-D) with its own sample stack (the `Stg:Stack` fine axes) and a third flat panel (`Det:PE3`). | The main PDF channel (DLM mono + 28-ID-C endstation) is modelled; the high-resolution channel is noted, deferred. | The HRM and 28-ID-D Assets. | - -### Optics - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DCM-1 | Nice-to-have | The double-Laue monochromator crystal and energy range, and the high-resolution monochromator crystal. Both (`Mono:DLM`, `Mono:HRM`) are in source. | Two Monochromator Assets, settings blank. | The Monochromator settings. | -| ENERGY-1 | Nice-to-have | Does XPD ever scan energy as the measurement, or is it always fixed-energy per experiment? | Fixed-energy; energy_scan not modelled. | The energy Capability decision. | - -### Sample and detectors - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| STAGE-1 | Blocks-go-live | The full diffractometer axis set behind `Dif:1`, and whether the goniometric axes warrant a `Goniometer` plus a Diffractometer Assembly (the 8-ID / i11 precedent). | A `LinearStage` sample stack, rotation axes and the Assembly deferred. | The SampleStage axes and orientation modelling. | -| DET-1 | Blocks-go-live | Which flat panels are live (PerkinElmer pe1 / pe2, Dexela, the 28-ID-D pe3) vs the spare set, and the detector distance range. | pe1 primary, Dexela secondary; all Cameras; distance range blank. | The detector roster and Q-range. | -| TEMP-1 | Nice-to-have | Which sample-environment units are live (Cryostream cs700 / cs800, Eurotherm, hot-air blower, Lakeshore cryostat, Linkam furnace)? | One `TemperatureController` Asset (the Cryostream); the others noted. | The sample-environment Assets. | -| DIAG-1 | Nice-to-have | The ion-chamber and quad-electrometer channel map (which channel is I0); the `PositionMonitor` Family is settled (graduated catalog Family presenting `Sensor`), so only this per-Asset channel map stays open. | Read-only flux counters (`FluxMonitor`), the graduated catalog `PositionMonitor`; channel map blank. | The IonChamber / QuadElectrometer bindings. | -| CALIB-1 | Nice-to-have | The energy / wavelength calibration: the calibration diffractometer (`Dif:2`: `th_cal`, `tth_cal`, `ecal_x`, `ecal_y`) and the Ecal routine that scans a standard to fit the beam wavelength, plus the dormant multi-analyzer stage (`MAD:DMS`) and the mono beam-defining slits (`Slt:MB1` / `Slt:MB2`). | A Procedure over the spine; these support devices deferred at this design phase. | The calibration Procedure and its devices. | -| OPERANDO-1 | Nice-to-have | The in-situ / operando accessories: the QEPro UV-Vis spectrometer read in parallel with the diffraction pattern (a distinct optical-spectroscopy modality, not a `Camera`), the gas switcher (`Env:02`), and the flash-sintering / electrochemistry power system. | Deferred; the UV-Vis channel needs its own family decision when it lands. | The operando detector and sample-environment Assets. | -| ROBOT-1 | Nice-to-have | The sample-changing robot (`XF:28IDC-ES:1{SM}`): CORA would model autonomous powder / capillary exchange as a Procedure over the spine threaded through the `Subject` aggregate and gated by a Clearance, the same shape as the I03 MX loop and the I15-1 powder exchange. | The robot is deferred autonomous-loop machinery, not a beam-path Asset. | The sample-handling Procedure and Subject custody thread. | - -### Controls - -| ID | Priority | Question | CORA assumes | Resolves | -| --- | --- | --- | --- | --- | -| DRIVE-1 | Blocks-go-live | The motion-controller box models, firmware, IPs. | Families bound (MotionController), specifics blank. | The MotionController Models. | -| TECH-1 | Blocks-go-live | Do the powder-diffraction and total-scattering / PDF Capabilities enter CORA's catalog, or stay deferred? This is the same owner-scope decision Diamond i11 and i15-1 opened. | Capabilities deferred (rendered unlinked), no Practice recorded. | The powder / PDF Capability scope. | diff --git a/mkdocs.yml b/mkdocs.yml index f2e4d0c8138..9ffa1f1c6a4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -115,19 +115,6 @@ nav: - LLM debrief comparison: deployments/2-bm/llm_debrief.md - Model: deployments/2-bm/model.md - Open questions: deployments/2-bm/questions.md - - MAX IV: deployments/maxiv/index.md - - Diamond: deployments/diamond/index.md - - NSLS-II: deployments/nsls2/index.md - - SLAC: deployments/slac/index.md - - Australian Synchrotron: deployments/as/index.md - - ESRF: deployments/esrf/index.md - - PSI: deployments/psi/index.md - - Sirius: deployments/sirius/index.md - - Elettra: deployments/elettra/index.md - - ALBA: deployments/alba/index.md - - NSRRC: deployments/nsrrc/index.md - - PETRA III: deployments/petra-iii/index.md - - ALS: deployments/als/index.md - Catalog: - catalog/index.md - Capabilities: catalog/capabilities.md @@ -230,9 +217,6 @@ strict: false validation: nav: - # Most deployment pages (all but the 2-BM pilot) are reachable from their - # Site's roster and their own index.md "More" links, not force-listed in - # nav, so a built-but-unlisted page is expected here, not a mistake. - omitted_files: ignore + omitted_files: warn links: anchors: warn From f5040ed247ab91bf7b27747db05f23cc4bb0174f Mon Sep 17 00:00:00 2001 From: xmap <16776958+xmap@users.noreply.github.com> Date: Wed, 9 Sep 2026 10:20:44 -0500 Subject: [PATCH 2/2] Fix the BLEPS descriptor-scan floor for the 2-file deployments/ tree test_the_descriptor_scan_reads_files pinned "> 50" as a non-vacuity guard against a past bug (a wrong parents[N] index made the scan read zero files and pass trivially). With the 93 non-pilot descriptors moved to xmap/descriptors, deployments/ now holds exactly 2 files (2-bm/ beamline.yaml, aps/site.yaml), so the floor legitimately fails. This test is not one of the fleet-wide mechanisms retired in the parent commit: it is a safety posture guard (CORA never binds a BLEPS interlock write PV) that must keep scanning whatever cora's own deployments/ tree actually carries, 2-BM's real descriptor included. Lowered the floor to >= 2 rather than removing the guard. Caught by CI (tests/architecture is part of the "fast" lane alongside tests/unit, which is what I ran locally before pushing; missed because I scoped my local re-run to tests/unit only). Re-ran `pytest tests/unit tests/architecture` locally after the fix: 52319 passed, 649 skipped, matching CI's fast lane exactly. --- .../tests/architecture/test_bleps_binding_is_read_only.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/apps/api/tests/architecture/test_bleps_binding_is_read_only.py b/apps/api/tests/architecture/test_bleps_binding_is_read_only.py index 00ba58a5233..5bb0ac96d90 100644 --- a/apps/api/tests/architecture/test_bleps_binding_is_read_only.py +++ b/apps/api/tests/architecture/test_bleps_binding_is_read_only.py @@ -118,9 +118,14 @@ def test_the_descriptor_scan_reads_files() -> None: This is the check that was missing when `_descriptor_files()` pointed at a directory that does not exist. Asserting on the roster alone said nothing about whether anything was ever opened. + + deployments/ carries just 2-bm/beamline.yaml and aps/site.yaml today + (the further 93 descriptors moved to the private xmap/descriptors repo, + a presentation and vocabulary-testing move unrelated to this safety + posture check, which must keep scanning whatever cora actually carries). """ found = _descriptor_files() - assert len(found) > 50, f"expected the deployments tree, found {len(found)} files" + assert len(found) >= 2, f"expected at least 2-bm + aps, found {len(found)} files" assert any(p.parent.name == "2-bm" for p in found)