SimCodes

Note

In case of any issues arising during installation or running SIMBA, contact Alex Brynes.

SIMBA has been tested with the most recent versions of the codes mentioned below [2025], and may not be compatible with earlier versions.

SimCodes is a container for the particle accelerator tracking codes used by SIMBA.

While most of the accelerator code executables are open-source, we prefer not to provide these as an installable package. The user can install the following codes from the links below:

Note that the following python-based simulation packages are optional dependencies of SIMBA, installable via the simcodes extra (pip install simba-accelerator[simcodes]). They run in-process and are unaffected by container_runtime (see below), so they must be installed locally regardless of whether a container runtime is used for the other codes:

SIMBA does, however, require these codes to be accessible. This functionality is provided in various ways.

Creating a SimCodes Directory

One can create a top-level directory containing sub-folders for each tracking code, and instantiate SIMBA with a simcodes argument:

import simba.Framework as fw
directory = "/path/to/working_directory"
simcodes_location = "/path/to/simcodes/folder"

fw = Framework(
    directory=directory,
    simcodes=simcodes_location,
)

Alternatively, one can set up SIMBA without this argument and set up the SimCodes location afterwards:

import simba.Framework as fw
directory = "/path/to/working_directory"
simcodes_location = "/path/to/simcodes/folder"

fw = Framework(directory=directory)

fw.setSimCodesLocation(simcodes_location)

These executables are then accessible to the run() function of the frameworkLattice object.

In simba/Executables.yaml the required structure is provided for this schema to work for different hardware architectures, either by the OS type or the computer name.

Using a Container Runtime

Note

Running SIMBA via Apptainer or Docker is only possible with an OS that supports it.

Apptainer has no native Windows build at all. On Windows, use WSL (see below).

Rather than installing the tracking codes locally, SIMBA can run them from a prebuilt container image, using either Docker or Apptainer. This is enabled by passing the container_runtime argument to SIMBA on instantiation:

import simba.Framework as fw
directory = "/path/to/working_directory"

fw = Framework(
    directory=directory,
    container_runtime="apptainer",  # or "docker"
)

When container_runtime="apptainer" is used, SIMBA looks for a .sif image file at <simcodes>/Apptainer/simcodes-apptainer_master.sif, where <simcodes> is the directory passed via the simcodes argument (see above):

import simba.Framework as fw
directory = "/path/to/working_directory"
simcodes_location = "/path/to/simcodes/folder"

fw = Framework(
    directory=directory,
    simcodes=simcodes_location,
    container_runtime="apptainer",
)

If simcodes is not provided, the .sif file defaults to a per-OS cache location (e.g. ~/.local/share/apptainer/ on Linux and ~/Library/Application Support/apptainer/ on macOS).

If the .sif file is not already present at that location, SIMBA creates the containing directory (if necessary) and pulls the image from the registry defined in simba/Executables.yaml (ghcr.io/astec-stfc/simcodes-apptainer:master by default) the first time SIMBA is instantiated with container_runtime="apptainer". This image is several GB, so the initial pull can take some time; subsequent instantiations detect the existing .sif file and skip the pull.

container_runtime="docker" works analogously, pulling the ghcr.io/astec-stfc/simcodes-docker:master image via the local Docker daemon instead of writing a .sif file to the simcodes directory.

Note

container_runtime covers ASTRA, Elegant, CSRTrack, OPAL, and Genesis. GPT is not included, as it is proprietary and requires a license; it must be installed locally (see define_gpt_command()) and run with GPTLICENSE set.

The python-based codes (Ocelot, Xsuite, Cheetah, Wake-T) run in-process and are unaffected by container_runtime - install them locally via the simcodes extra regardless.

Running on Windows

The container images hold Linux binaries, so on Windows the supported route for running in containers is WSL2:

wsl --install -d Ubuntu

Then, inside the WSL shell, install Docker (or Apptainer) and SIMBA as on any Linux machine, and work from a path under the WSL filesystem (/home/...) rather than under /mnt/c; bind-mounting a /mnt/c working directory into a container is slow and the tracking codes write a lot of intermediate files.

Native Windows supports the codes that ship a Windows build - ASTRA, Elegant, CSRTrack and GPT - via the nt section of simba/Executables.yaml or the location argument (see below).

OPAL and Genesis are Linux-only. There is no Windows binary to point Executables.yaml at, so requesting either from a Windows Python process raises a RuntimeError telling you to use WSL or a container runtime, rather than failing later with a missing output file.

container_runtime on native Windows is untested.

Editing the Executables.yaml file

If the user already has these executables installed, they can point directly to them in simba/Executables.yaml

Pointing to a specific location

An instance of SIMBA has access to these executables via the executables attribute, and these can be modified once SIMBA is instantiated.

For example, in order to point to a local install of the ELEGANT code, the user can run the following code:

import simba.Framework as fw
directory = "/path/to/working_directory"
elegant_location = "/path/to/elegant/binary"

fw = Framework(directory=directory)

fw.executables.define_elegant_command(location=elegant_location)

This will then allow SIMBA to call the correct version of ELEGANT.

Citing the codes used

Please consider citing the code(s) used if any work performed with SIMBA leads to a publication. The citations above resolve against the reference list.