This repository includes SLAC-specific python code to be utilized with creating and running virtual accelerators of SLAC beamlines via the LUME framework (see https://github.com/slaclab/lume-base, https://github.com/lume-science).

Installation

First, clone this repo to a local location and enter the directory. Also install Conda if you don't already have it. (we recommended using Conda from Miniforge)

Then create a new conda environment using mamba, containing bmad and pytao:

mamba create -n va-env -c conda-forge python=3.12 bmad pytao

(you can also use an existing environment, although it could lead to dependency conflicts)

Now activate the newly created environment:

conda activate va-env

and then install the remaining required packages with pip by running:

pip install .

the -e flag can be added if you plan to edit the virtual accelerator code.

Lastly, install backend-specific extras depending on which simulation types you need:

pip install .[bmad]
pip install .[cheetah]
pip install .[impact]
pip install .[pva]
pip install .[surrogate]
pip install .[all]

Optional Dependency Keys by Model:

Model / Factory Function	Optional dependency key(s)	Notes
get_cu_hxr_bmad_model	bmad	Requires BMAD/PyTAO backend.
get_facet_bmad_model	bmad	FACET-II BMAD model; requires FACET2_LATTICE.
get_cu_hxr_injector_surrogate_model	surrogate	Uses torch surrogate + cheetah particles.
get_facet_staged_model	surrogate, bmad	FACET-II staged model (injector surrogate + FACET-II BMAD).
get_cu_hxr_staged_model	surrogate, bmad	Stages InjectorSurrogate + CU HXR BMAD model.
virtual_accelerator.models.runners CLI	pva (+ model backend key)	Runner requires pva; selected model backend must also be installed.

The package now lazily imports backend-specific dependencies. If you call a model whose optional dependency is not installed, you will get an actionable error with the matching extra to install.

Creating model instances also requires the $LCLS_LATTICE environment variable for LCLS-based models and $FACET2_LATTICE for FACET-II models; each should point to a location containing the contents of the lcls-lattice repo https://github.com/slaclab/lcls-lattice or the facet2-lattice repo https://github.com/slaclab/facet2-lattice.

Running the models

You can use the runner script to start the model. The script allows you to specify the model backend, number of particles, and end element to run with.

For example:

python virtual_accelerator/models/runners.py cu_hxr_bmad --end-element OTR4

For more info, run:

python virtual_accelerator/models/runners.py -h

Note

The Cu Injector model is present in subtrees/lcls_cu_injector_ml_model. To pull latest changes from the Cu Inj repo

pip install git+https://github.com/slaclab/lcls_cu_injector_ml_model.git