Resonance

Resonance is a Python package for the ALS-RSOXS Beamline Control System. It provides a high-level API for motor control, analog inputs, NEXAFS scans, and an MCP server for beamline access.

Install

Requires uv and Python 3.13+.

uv sync --all-groups

To include the optional BCS group (beamline control dependencies):

uv sync --all-groups --group bcs

Usage

Run the MCP beamline server:

uv run mcp-beamline

Or after installing:

mcp-beamline

Use the API from Python:

from resonance.api import RsoxsServer, nexafs_scan
from resonance.api.types import AI, Motor

Development

make install
make verify
make test

• make verify runs lint, format-check, and type-check.
• make fix auto-fixes Ruff lint and format.
• make test-cov runs tests with coverage.

Install pre-commit hooks (prek or pre-commit):

pre-commit install

See CHANGELOG.md for release history. Architecture decisions are in docs/adr/.

Project status

Basic I/O operations

• Read AIs
• Read motor positions
• Move motor positions
• Motor scan scheduling

Scheduling and run management

• Build default NEXAFS scans
• Get feedback logic
• Build auto alignment

QOL

• Install BLS API into venv to avoid sys.path.append
• Type motors and AIs
• Formatting and type hinting (Ruff, ty)