Loading in a Lattice File

Getting started demonstrated how to create a LAURA lattice in python. This page will describe how to generate a SIMBA instance based on pre-existing LAURA element and lattice definitions.

Setting up a Simulation From Files

Given a LAURA MachineModel, which contains:

All of the elements in an accelerator lattice;
The various sections that compose that lattice;
A list of layouts composed of lattice sections;

SIMBA can be used to interact with this structure.

The simulation of the lattice is defined in a separate YAML file, for example CLARA.def for the CLARA [9] [10] accelerator:

generator:
    default: clara_400_3ps
files:
  injector400:
    code: astra
    charge:
      cathode: True
      space_charge_mode: 2D
      mirror_charge: True
    input:
      particle_definition: 'initial_distribution'
    output:
      zstart: 0
      end_element: CLA-S02-SIM-APER-01
  Linac:
    code: elegant
    output:
      start_element: CLA-S02-SIM-APER-01
      end_element: CLA-FEA-SIM-START-01
  FEBE:
    code: ocelot
    charge:
      cathode: False
      space_charge_mode: 3D
    input: {}
    output:
      start_element: CLA-FEA-SIM-START-01
      end_element: CLA-FED-SIM-DUMP-01-START
groups:
  bunch_compressor:
    type: chicane
    elements: [CLA-VBC-MAG-DIP-01, CLA-VBC-MAG-DIP-02, CLA-VBC-MAG-DIP-03, CLA-VBC-MAG-DIP-04]
layout: /path/to/laura-lattices/CLARA/layouts.yaml
section: /path/to/laura-lattices/CLARA/sections.yaml
element_list: /path/to/laura-lattices/CLARA/YAML/

This lattice definition would produce several output files (called injector400.in, Linac.lte, and FEBE.py) for running in the ASTRA, Elegant and Ocelot beam tracking codes.

The elements are loaded from the directory /path/to/laura-lattices/CLARA/YAML/ defined above.

As this simulation starts from the cathode, the input definition is required for the first injector400 file block. An alternative method for starting is to specify input/particle_definition to point to an existing beam file.

For follow-on lattice runs, it is sufficient to define the output: start_element, which should match the output: end_element definition from the previous file block.

Running SIMBA

The following example assumes that LAURA has already been installed (see Installation) and that the SimCodes directory has been prepared.

import simba.Framework as fw


# Define a new framework instance, in directory 'example'.
#       "clean" will empty (delete everything!) in the directory if true
#       "verbose" will print a progressbar if true
simcodes_location = "/path/to/simcodes/directory"
framework = fw.Framework(
    master_lattice="/path/to/laura-lattices/CLARA",
    directory="./example",
    generator_defaults="clara.yaml",
    simcodes_location=simcodes_location,
    clean=True,
    verbose=True,
    )
# Load a lattice definition file. These can be found in Masterlattice/Lattices by default.
framework.loadSettings("Lattices/CLARA.def")
# Change all lattice codes to ASTRA/Elegant/GPT with exclusions (injector cannot be done in Elegant)
framework.change_Lattice_Code("All", "ASTRA", exclude=["Linac"])
# Again, but put the VBC in Elegant for CSR
framework.change_Lattice_Code("FEBE", "Elegant")
# This is the code that generates the laser distribution (ASTRA or GPT)
framework.change_generator("ASTRA")
# Load a starting laser distribution setting
framework.generator.load_defaults("clara_400_2ps_Gaussian")
# Set the thermal emittance for the generator
framework.generator.thermal_emittance = 0.0005
# This is a scaling parameter
# This defines the number of particles to create at the gun (this is "ASTRA generator" which creates distributions)
framework.generator.number_of_particles = 512
# Track the lattice
framework.track()