Skip to main content

Lightfall

PyPI version Python versions CI Docs License: BSD-3-Clause

A modern, unified control system for synchrotron lightsource facilities that provides facility-wide consistency with beamline-specific customization.

Overview

Lightfall is designed for the Advanced Light Source (ALS) facility, providing:

  • Unified Interface: Consistent look-and-feel across beamlines with skinnable themes
  • API-First Architecture: Modular, extensible design enabling automation and integration
  • LLM/AI Integration: Claude-powered chatbot for natural language control and assistance
  • FAIR-Compliant Data Management: Integration with Tiled for data cataloging and access
  • Secure Remote Operations: Full remote operation capability with fine-grained access control

Features

User Interface

  • Progressive disclosure: user panels with expert panels behind authorization
  • Scripting panel with Jupyter-lab style interface
  • LLM panel for controlling panels via natural language
  • GUI Builder for drag-and-drop interface creation
  • Persistent user preferences saved across sessions

Device Management

  • Centralized device catalog with lifecycle tracking
  • Real-time monitoring via EPICS Channel Access
  • Version-controlled device configurations
  • Rich high-level controls integrated into workflows

Data Acquisition

  • Bluesky-based acquisition engine
  • Flexible signal/stream selection with real-time visualization
  • Interactive, pausable, restartable acquisition
  • Automatic data persistence to Tiled catalog

Data Browser

  • Browse and search data stored in Tiled server
  • Filter by date range, plan type, exit status
  • Pagination for large datasets
  • Click/double-click signals for integration with analysis tools

Installation

pip install lightfall

Development Installation

# Clone the repository
git clone https://github.com/als-controls/lightfall.git
cd lightfall

# Create and activate virtual environment
python -m venv .venv
.venv\Scripts\activate  # Windows
# or
source .venv/bin/activate  # Unix

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Lightfall depends on lightfall-utils (installed from PyPI like any other dependency). To co-develop both packages, install a sibling checkout in editable mode on top:

git clone https://github.com/als-controls/lightfall-utils.git ../lightfall-utils
pip install -e ../lightfall-utils

Running the Application

lightfall

Configuration

Lightfall uses a layered configuration system:

  1. System defaults - Built-in defaults
  2. Site configuration - Facility-wide settings
  3. User preferences - Personal customizations

Configuration files are stored in:

  • Windows: %APPDATA%\lightfall\
  • Linux/Mac: ~/.config/lightfall/

Architecture

Lightfall is built on:

  • PySide6 - Qt for Python GUI framework
  • Bluesky - Data acquisition framework
  • Ophyd - Device abstraction layer
  • Tiled - Data catalog and access
  • EPICS - Control system communication

Plugin System

Lightfall supports plugins for:

  • Panels - Custom UI panels
  • Settings - Preference pages
  • Status Bar - Status indicators
  • Engines - Acquisition backends
  • Plans - Scan procedures

Development

Running Tests

pytest

Code Quality

# Linting
ruff check src tests

# Type checking
mypy src

Project Structure

lightfall/
├── src/lightfall/
│   ├── acquire/        # Data acquisition engine (Bluesky RunEngine, plans)
│   ├── auth/           # Authentication & authorization
│   ├── claude/         # Embedded Claude agent integration
│   ├── config/         # Configuration management
│   ├── core/           # Core application classes
│   ├── devices/        # Device catalog & backends
│   ├── epics/          # EPICS (caproto) widgets & helpers
│   ├── exporter/       # Data exporter CLI
│   ├── ipc/            # Inter-process communication (NATS)
│   ├── logbook/        # Logbook client
│   ├── pipelines/      # Pipeline client
│   ├── plugins/        # Plugin system
│   ├── services/       # Application services (Tiled, CA tunnel, etc.)
│   ├── settings/       # User-portable settings client
│   ├── ui/             # User interface
│   │   ├── panels/     # Panel implementations
│   │   ├── widgets/    # Reusable widgets
│   │   ├── preferences/  # Settings UI
│   │   └── theme/      # Theming system
│   ├── utils/          # Utilities
│   └── visualization/  # Plotting & live visualization
└── tests/              # Test suite

Metadata

Release files for lightfall 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lightfall 0.3.0
File Size Uploaded Provenance Actions
lightfall-0.3.0.tar.gz 3.3 MB With provenance Details for lightfall-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for lightfall 0.3.0
File Interpreter ABI Platform Actions
lightfall-0.3.0-py3-none-any.whl Python 3 none any Details for lightfall-0.3.0-py3-none-any.whl

Total release size: 6.8 MB

Release files / lightfall-0.3.0.tar.gz

Download URL lightfall-0.3.0.tar.gz
Size 3.3 MB
Tags Source
SHA-256 checksum
How to use checksums
8f768968d7bec68a4734212823df1caee5f8952e1f7923fe58cf66edddf4ab1b
BLAKE2b-256 checksum
How to use checksums
dbaa0aeface1ff388d69d76ad7b68695ac57d9240166dbffd3e74dde59546fa1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.

Transparency log

Release files / lightfall-0.3.0-py3-none-any.whl

Download URL lightfall-0.3.0-py3-none-any.whl
Size 3.5 MB
Tags Python 3
SHA-256 checksum
How to use checksums
f4dd444f82ae96b1f4625e2b4c32d783105d1a65a55221e3cb375572ea5fd987
BLAKE2b-256 checksum
How to use checksums
a219c254397293fe60381c9e8ad11567271b9c8c156739f1587069513b6a6d34
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.

Transparency log

Security for lightfall 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for lightfall-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page