Agentic Accelerator Design

An Agentic AI Framework for Accelerator Lattice Design.

It utilizes the Academy package to deploy agents across distributed and federated resources.

Getting Started

Prerequisites

• uv — used for Python version and dependency management
• Python 3.14 (installed automatically by uv below)

Setup

# 1. Clone the repo
git clone <repo-url>
cd agentic-accelerator-design

# 2. Install Python 3.14
uv python install 3.14

# 3. Install all dependencies (including dev tools)
uv sync --dev

# 4. Copy the environment file and fill in your LLM credentials
cp .env.example .env

Open .env and set at minimum:

AAD_MODEL=<model-id>        # e.g. claude-sonnet-4-6
AAD_PROVIDER=<provider>     # e.g. anthropic or argo
AAD_API_KEY=<your-key>
AAD_API_BASE=<api-url>      # leave blank for default Anthropic endpoint

For ARGO (Argonne's LLM gateway), use AAD_PROVIDER=argo, set AAD_MODEL to the ARGO model ID, and set AAD_API_KEY=$USER.

Running the web dashboard

uv run aad serve --port 8080

Then open http://localhost:8080 in your browser.

Running the CLI pipeline directly

uv run aad run

Running tests and linting

uv run pytest
uv run black --check .
uv run isort --check-only .

---

Long-Term Vision

The end goal of this project is for the framework to answer the questions a working accelerator physicist would actually ask when designing a lattice, not just tune quadrupole strengths inside a fixed template.

In the long run, a "design" is treated as a higher-level question decomposed into a sequence of smaller optimization stages, each tuning one element (or a small group) to a minor sub-goal before moving to the next. This mirrors how physicists actually design lattices by hand (e.g. tune quadrupoles for β first, then sextupoles for chromaticity, then fine-tune for emittance). The agent orchestrates those stages, judges each stage's output, and decides whether to move on, repeat, or try a different topology. The composition of the minor sub-goals is what produces the overall design objective; individual optimization runs are building blocks, the orchestration is the framework. The pipeline must also support designs without an incoming beam (periodic / ring cells), free-text goals and constraints, an explicit available_elements list, and indefinite HPC runs with dev / test / prod mode caps.

Concrete real-world tasks the framework targets include emittance-exchange beamlines, storage-ring cells (e.g. 7-bend achromat), linac and transport-line designs, and dynamic-aperture optimization. The near-term, lowest-hanging deliverable is an optimization-only fast path: the user uploads an existing simulation file or script, the pipeline skips design entirely, builds the evaluator from the script, emits an Xopt VOCS, and runs the optimizer. Higher-order effects (space charge, image charges) and frontend polish are deferred until the multi-stage backend is solid.

See plan/LongTermDesign.md for the full end-goal direction, schema-relaxation plan, and priority order.

Concrete Execution Plan

The first executable milestone is tracked in plan/v1-demo.md.

Local Environment

Copy .env.example to .env and fill in the LLM settings before running the live reporter path:

cp .env.example .env

The CLI loads .env automatically for aad run. Reporter-specific variables are optional and fall back to the global AAD_* values. For ARGO, set AAD_PROVIDER=argo, keep the model as the ARGO model ID, and use AAD_API_KEY=$USER.

Conceptual Workflow

Optimization Only

1. User prompts the optimization problem, with a defined lattice template
2. Agent generates a VOCS file and select the optimizer package accordingly
3. Agent initiates the job on cluster / federated computing resource, through academy & globus compute
4. Agent retrieves the result, report, and iterate if necessary.

Full / Iterative Design

1. User prompt
2. LLM parses the input, convert that into a Json/Yaml optimization config with
3. LLM proposes a lattice structure with
4. LLM agent generates a simulation template with the basic lattice configuration
   1. Extension
5. LLM generates a VOCS config for the inner loop optimization
6. Agent initiates the job on cluster / federated computing resource, through academy & globus compute
7. Retrieves the result, in JSON + raw data format, store locally or in a database
8. Analyze the existing result, start new configurations

Conceptual Structure and Interfaces for Implementation

Architecture (High level)

flowchart TD
    A[User Design Prompt] --> B[Requirement Parser<br/>LLM → DesignRequest]
    B --> C[Design Planner<br/>LLM → LatticeCandidate]
    C --> D[Deterministic Validator<br/>Schema + physics checks]
    D --> E[Simulation Builder<br/>Cheetah → SimulationConfig]
    E --> F[Optimization Builder<br/>Xopt VOCS + evaluator]
    F --> G[Academy Execution Backend<br/>local / Globus / federated]
    G --> H[Result Analyzer<br/>metrics + plots + next step]
    H --> I[Experiment Store<br/>JSONL / SQLite / artifacts]

    D -->|invalid| C
    H -->|iterate| C

Loading

Execution (long-term planned)

flowchart LR
    A[User prompt] --> B[Parse design intent]
    B --> C[Validated DesignRequest]

    C --> D{Workflow mode}

    D -->|Optimization only| E[Select fixed lattice template]
    D -->|Agentic design| F[Design planner agent]

    F --> G[Propose candidate lattices]
    G --> H[Validate lattice candidates]
    H -->|invalid| F
    H -->|valid| I[Build simulation config]

    E --> I

    I --> J[Generate Xopt VOCS]
    J --> K[Validate optimization config]

    K --> L[Create RunSpec]

    L --> M[Academy execution backend]

    M --> N{Academy execution mode}

    N -->|Local| O[Local worker / local agent]
    N -->|Globus Compute| P[Remote endpoint worker]
    N -->|Federated resources| Q[Distributed agent workers]

    O --> R[Cheetah simulation + Xopt optimization]
    P --> R
    Q --> R

    R --> S[Optimization history and raw artifacts]
    S --> T[ResultRecord]
    T --> U[Run / artifact store]

    T --> V[Result analyzer agent]
    V --> W[Generate report]
    V --> X{Continue iteration?}

    X -->|yes| F
    X -->|no| Y[Recommended lattice / optimized settings]

Loading

Minimal Usage Implementation

1. Unified LLM Agent inference interfaces with LangChain, LiteLLM
2. Stateful agent & orechestration with Academy
3. Generate simulation templates, validate (For demo, use simulation models built in Cheetah), move on to PALS standard later
4. Generate optimization template according to Xopt VOCS, validate