Feature: YellowPages (standardized-name mapping & discovery)

[gupichon]

Description, motivation and use case

The User Interface Specification states that configuration must not enforce a common facility naming convention, and instead should rely on a standard list of names that users map to their own Elements/ElementArrays:

• Chapter 4 – Configuration, Section 4.1 “Overview”:
  The document explicitly requires “a standard list of names that the user can map to the Element/ElementArrays they have defined”, with the example that a family of horizontal steerers does not have to be called identically across facilities, but higher-level applications can rely on a standardized name (e.g. “HorizontalOrbitCorrectors”).

This implies a user-facing mechanism is needed to:

1. Resolve standardized names → facility-defined elements/arrays, and
2. Discover what standardized names are available in a given configuration.

Additionally, HLAs rely on selecting/using “some objects” representing BPMs / tune devices, etc.:

• Chapter 6 – Running measurements, Section 6.2 “Function-based High-Level Applications (HLA)”:
  The examples use inputs like sel_bpm_mlvs / sel_tune_mlvs, described as objects from which relevant data can be obtained via a control system.
  A standardized discovery + resolution layer is a natural way to provide these selections in a facility-independent manner.

Finally, the configuration describes that devices/arrays are specified once and instantiated per control mode:

• Chapter 4 – Configuration, Section 4.4.9 “Virtual Accelerator”:
  Devices and arrays are specified only once (e.g. in sr.yaml) but instantiated per control mode.
  A standardized mapping service should therefore be consistent across control modes.

---

Proposed solution

Add a YellowPages service at the Accelerator level that implements the standardized-name mapping described in:

• Chapter 4, Section 4.1 “Overview”

YellowPages responsibilities (UI-level behavior):

1. Resolution: provide a stable API to resolve standardized names to the configured target (Elements or ElementArrays).
2. Discovery: provide a global view of what standardized names are available in the current configuration (and across control modes).

This is consistent with the separation principles stated in Chapter 4, Section 4.1 (configuration separated from code, no naming convention requirements, standardized names used by HLAs).

---

Describe alternatives you've considered

1. Let each HLA define its own selection objects (e.g., sel_bpm_mlvs) manually
   This does not provide the standardized-name mapping requirement and reduces reusability, which is precisely the topic introduced in Chapter 6, Section 6.2.

---

Example

Resolution API (concept)

yp = sr.yellow_pages

# Standardized names (facility-independent)
bpms = yp.get("BPM")              # returns configured BPM ElementArray / IDs
hcorr = yp.get("HCORR")           # returns configured horizontal correctors
vcorr = yp.get("VCORR")           # returns configured vertical correctors

Global discovery / printing

print(sr.yellow_pages)

Expected output example:

Accelerators:
    live
    design
    errors[0-20]
    model
    .

Tools:
    DEFAULT_ORBIT_CORRECTION (pyaml.tuning_tools.orbit)
    DEFAULT_TUNE_CORRECTION (pyaml.tuning_tools.tune)
    DEFAULT_ORBIT_RESPONSE_MATRIX (pyaml.tuning_tools.orbit_response_matrix)
    LOCO_ORBIT_RESPONSE_MATRIX (pyaml.tuning_tools.orbit_response_matrix)
    .

Diagnostics:
    DEFAULT_BETATRON_TUNE_MONITOR (pyaml.diagnostics.tune_monitor)
    SPARE_BETATRON_TUNE_MONITOR (pyaml.diagnostics.tune_monitor)
    Bunch_current_monitor (pyaml.diagnostics.current)
    .

Arrays:
    BPM (pyaml.arrays.bpm_array)                     size=224
    HCORR (pyaml.arrays.magnet_array)                size=96
    VCORR (pyaml.arrays.magnet_array)                size=96
    HCORR_LOCO (pyaml.arrays.magnet_array)           size=48
    VCORR_LOCO (pyaml.arrays.magnet_array)           size=48
    .

The size=N part is important for a UI-level discovery feature: it helps validate that the configured mapping produces the expected scope for HLAs (e.g., orbit/dispersion/chromaticity measurements described in Chapter 6).

---

Additional context

YellowPages is a direct implementation of the “standard list of names mapped by the user” requirement:

• Chapter 4, Section 4.1 “Overview”

And should remain consistent with the idea that arrays/devices are defined once and used across control modes:

• Chapter 4, Section 4.4.9 “Virtual Accelerator”

---

Checklist

• I've assigned this issue to a project
• I've @-mentioned relevant people