GEECS Plugin Suite¶

A Python-native toolkit for the BELLA beamline at LBNL.

The GEECS Plugin Suite extends LBNL's GEECS (Generalized Equipment and Experiment Control System) acquisition platform with Python-native tools for scanning, image analysis, scan post-processing, and result browsing. Each subdirectory is an independent Python package; together they cover the experimental data lifecycle from acquisition through analysis to delivery.

Where to start¶

The suite splits cleanly into the two halves of the experimental data lifecycle — acquisition and analysis. The first two cards below follow that split; the bottom row is for navigation and troubleshooting.

Data Acquisition

Run scans on the beamline from a browser with the GEECS Scanner: pick a preset or compose a scan, submit it to the Bluesky queueserver, watch it live, move a device — or submit the same presets headlessly from your own scripts.

GEECS Scanner · Running scans
Data Analysis

Process per-shot images, configure analysis pipelines, and run per-scan analysis from the data portal. Edit configs in its config editor; run them headlessly or interactively via the Image/Scan Analysis APIs.

Analysis tutorial · All tutorials
Browse by package

Overviews, examples, and API reference for each package in the suite. Pick this if you already know which piece you're working with.

GEECS Scanner · Image Analysis · Scan Analysis · Data Utils · GEECS-Core
Troubleshooting & internals

Common scan failure modes, the /triage skill for diagnosing recurring issues, and the architecture deep-dives.

Troubleshooting · Skills

How the packages fit together¶

flowchart LR
    Scanner[GEECS Scanner<br/>web scanner console]
    Engine[GeecsBluesky<br/>RunEngine scan core]
    Core[GEECS-Core<br/>transport + DB + GeecsDevice]
    GW[CA/PVA Gateways<br/>GEECS as EPICS PVs]
    SA[Scan Analysis<br/>per-scan workflows]
    IA[Image Analysis<br/>per-image pipelines]
    DU[Data Utils<br/>paths + s-files]

    Scanner --> Engine
    Engine -->|CA service| GW
    GW --> Core
    Engine --> DU
    SA --> IA
    SA --> DU
    IA -.->|optional, via Array2DScanAnalyzer| SA

A typical workflow: the GEECS Scanner runs a scan that writes a folder to the data server (and a structured run to the Tiled catalog). Scan Analysis (live or offline) reads that folder, runs configured Image Analysis analyzers across the shots, renders summary figures, and appends derived scalars back to the s-file. A separate notebook can then load the s-file via Data Utils for ad-hoc exploration.

Packages at a glance¶

GEECS Scanner — the operator front end for collecting data, in a browser: pick or compose a scan, submit it to the Bluesky queueserver, watch it live, move devices and run action plans. The engine underneath (GeecsBluesky) is equally usable headlessly.

Image Analysis — per-image processing and analysis. Pipelines are described in YAML (background, masking, filtering, geometric transforms, thresholding) with specialised analyzers for beam profile, FROG, magspec, HASO wavefront, and 1D traces.

Scan Analysis — orchestrates analysis across a complete scan: shot binning, per-bin processing, summary figure rendering, s-file appending. Runs explicitly through the data portal or Python.

GEECS-Core — the GEECS access library: device communication (UDP/TCP transport and the entry-level GeecsDevice client), the experiment database, and the PV naming contract. The shared config.ini it reads is documented in the Getting Started tutorial.

GEECS Data Utils — path resolution and data loading for scan folders. Resolves (experiment, date, scan_number) to an on-disk path, loads s-files, and defines the common types used across the suite. Typically a dependency rather than a direct import.

How the docs are organised¶

Within each package, content is split into four kinds — different modes for different questions:

Tutorials teach by guided walkthrough — start here if you're new.
How-To guides are task recipes — "add a save element," "diagnose a failed scan," "configure background subtraction."
Reference is for lookup once you know what you want — API docs, config schema, CLI flags.
Explanation covers the why behind the how — architecture, design rationale, what each package is for.

If you're looking for something specific and you already know roughly where it lives, the left-hand navigation will get you there fastest. If you're new, the Tutorials tab is the right entry point.