Accumulator (Accelerator Universal Emulator)

Accumulator is a digital twin (emulator) of a charged particle accelerator based on the Elegant physics engine and the EPICS Channel Access protocol.

The project is developed as part of the scaut ecosystem and allows debugging control systems, optimization algorithms, and user interfaces without access to real hardware.

Features

• Automatic PV Generation: PVs (Process Variables) are generated automatically based on the accelerator lattice file (*.lte).
• Real Physics: Every parameter change (via EPICS) triggers a simulation in Elegant, calculating the real beam response.
• Scalability: Ability to run multiple independent accelerator instances (e.g., for testing interaction between multiple rings).
• Value Mapping: Built-in support for unit scaling (e.g., converting orbit from meters to millimeters or magnet current to K1).
• Docker-native: Easy execution in an isolated container.

Quick Start

Requirements

• Docker
• Docker Compose

Run Base Services

docker compose -f docker-compose.accumulator.yml up --build

This will start the base accelerator emulator ACC1: on ports 5064 (RPC), 5065 (stream), 8501 (UI).

Run Jupyter Notebook

docker compose -f docker-compose.jupyter.yml up --build

This starts Jupyter Notebook on port 8888 with installed dependencies from requirements.txt.

Generate Additional Accelerators

To run multiple accelerator instances, generate all services:

python scripts/generate_compose.py --count 10

This creates docker-compose.accumulator.yml with 10 accelerators (ACC1: through ACC10:) on UI ports 8501-8510.

Run All Services

docker compose -f docker-compose.accumulator.yml -f docker-compose.jupyter.yml up --build

Connection

You can use caget/caput (from the pyepics package or command line) to interact.

Example (for ACC1):

# Read beam position
caget ACC1:BI-LA1:PK3:Cx

# Change magnet strength
caput ACC1:MG-LA1:QLF1:K1 -9.5

Configuration

All configuration is centralized in the elegant/ folder:

• config.py: Element handlers, energy settings, PV/device mappings, and scale factors.
• config.lte: Magnetic structure description.
• config.ele: Simulation commands.

Element Configuration

Element handlers are defined as dictionaries in elegant/config.py:

ELEMENT_HANDLERS = {
    'QUAD': {
        'K1': {'pv_suffix': 'K1', 'param_name': 'K1', ...},
        'DX': {'pv_suffix': 'DX', 'param_name': 'DX', 'scale': PK_MONITOR_SCALE_FACTOR},
        ...
    },
    ...
}

Each element type maps to a dictionary of parameters with properties like:

• pv_suffix: Suffix for PV name generation
• param_name: Elegant parameter name
• is_read_only: Whether the parameter is read-only
• scale: Value scaling factor
• precision: Number of decimal places
• default_val: Default value

Value Mapping

• PV_MAPPING: Maps elegant element names to EPICS PV names
• SCALE_MAPPING: Defines scaling factors for specific parameters
• DEVICE_MAPPING: Maps element names to device prefixes

Energy Settings

Beam energies are defined for each linac section:

ENERGY_LA1 = 38e-3   # [GeV/c]
ENERGY_LA2 = 76e-3
...

Environment Variables

See .env_example for a complete list of configuration options.

• ACCUMULATOR_PREFIX: Prefix for all PVs (default ACC1: for base service).
• LOG_LEVEL: Logging level (default INFO).
• LOG_DIR: Directory for log files (default logs).
• ELEGANT_SIMULATION_DIR: Path to elegant configuration directory
• ELEGANT_SIMULATION_CONFIG_FILE: Path to elegant config file
• ELEGANT_SIMULATION_LATTICES_FILE: Path to elegant lattice file

Project Structure

• accumulator/: Python package source code.
  • core/: Core configuration and utilities.
    • config.py: Application configuration.
    • logger.py: Logging configuration.
  • elegant/: Elegant simulation integration.
    • lattice.py: Lattice parser and PV configuration.
    • mapping.py: PV name and simulation name resolution.
    • ioc.py: EPICS request handling and Elegant simulation logic.
  • main.py: Entry point.
• elegant/: Physics engine and accelerator configuration.
  • config.py: Element handlers, energy settings, PV mappings, and scale factors.
  • config.lte: Magnetic structure description.
  • config.ele: Elegant simulation commands.
• scripts/: Utility scripts (e.g., generate_compose.py for Docker Compose generation).
• notebooks/: Jupyter notebooks for analysis and experimentation.