leds

An event viewer for the LEGEND experiment: a Panel dashboard with event display, waveforms, spectra, dataset-metadata and validation views over a legend-dataflow production cycle.

Running

pip install legend-leds   # or: uv pip install .

leds app /path/to/production_cycle          # local single-user browser tab
leds app --desktop /path/to/cycle           # native window (needs leds[desktop])
leds serve /path/to/cycle --port 5006       # hosted multi-user server

The production-cycle path (a directory containing dataflow-config.yaml, or a directory of such cycles) can also come from $LEDS_BASE_PATH; several paths may be listed separated by :.

Deployment (NERSC Spin)

The Dockerfile builds a slim two-stage image by cloning this repository:

docker build -t registry.nersc.gov/<project>/leds:latest \
  --build-arg LEDS_REPO=https://github.com/legend-exp/leds.git \
  --build-arg LEDS_REF=main .
docker push registry.nersc.gov/<project>/leds:latest

(Point LEDS_REPO at a fork while changes are not upstream yet.) The container listens on port 5006 and runs under an arbitrary non-root UID, as Spin requires.

Service environment

Sessions in one worker share the read-only data they have in common — channelmaps, detector statuses, directory scans, per-run reductions — so a second user on the same cycle starts nearly instantly and does not duplicate that memory. All the bounds above are per worker process, so multiply by NUM_PROCS when sizing the Spin memory limit.

Because that sharing includes the parsed metadata, an updated metadata checkout is picked up within LEDS_CACHE_TTL rather than immediately. Lower it if the deployment updates metadata often; restarting the service always picks it up at once.

Threads

NUM_THREADS (passed by the image to leds serve --num-threads, like NUM_PROCS to --num-procs) runs callbacks on a thread pool instead of the worker's single event loop. Without it, one session's slow operation — a first visit to the Validation tab, a raw read stalling on CFS — freezes the UI of every other session in that worker until it finishes. With it those sessions keep responding, and work that is not HDF5 (parsing a channelmap, evaluating cuts, building Bokeh models) runs in parallel.

What it does not buy: h5py serialises every HDF5 call behind one process-wide lock, so two sessions' raw reads still take turns within a worker. NUM_PROCS is the lever for that; the two combine.

Per-session state — the viewer's caches and open HDF5 handles, the spectrum accumulator, the tab bookkeeping — is guarded by one lock per session, so a session's own callbacks never overlap even though they run on the pool. Open HDF5 handles are per session and never shared across sessions or forked workers. A playback tick that arrives while the previous frame is still rendering is dropped rather than queued.

Login (Spin secrets)

Without any of the variables below the server is open. In all authenticated setups set a fixed LEDS_COOKIE_SECRET — with an ephemeral one, logins break on every restart and across the NUM_PROCS workers.

Option A — shared password / user list: set LEDS_BASIC_AUTH to either a single shared password or a path to a mounted JSON file of {"username": "password"}.

Option B — LDAP (takes precedence over LEDS_BASIC_AUTH): users sign in with their directory credentials. Fill the values in from the LEGEND LDAP administrators:

Configure either LEDS_LDAP_USER_DN_TEMPLATE (direct bind) or the three search-bind variables; if both are present, direct bind wins. Server certificates are always verified. Bad credentials, unknown users and non-members all get the same generic login error; infrastructure failures are reported as "authentication service unavailable" with details in the container log only.

To try the LDAP flow locally against a throwaway directory:

docker run --rm -d -p 1389:1389 -e LDAP_ADMIN_PASSWORD=adminpw \
  -e LDAP_USERS=alice -e LDAP_PASSWORDS=alicepw bitnamilegacy/openldap

LEDS_LDAP_SERVER=ldap://localhost:1389 \
LEDS_LDAP_USER_DN_TEMPLATE="cn={username},ou=users,dc=example,dc=org" \
LEDS_COOKIE_SECRET=devsecret leds serve /path/to/cycle