Using lattice files in Sirepo

When simulating an existing accelerator in Sirepo, it’s useful to have a lattice file to start from. But what is a lattice file, and where do you get one for your accelerator?

In this article, we’ll explain what lattices are, how to import and export them, and give a few examples.

What lattice files are

A lattice file is named for the composition of guiding elements, traditionally comprised of magnets, in a particle accelerator.

Essentially, it’s an ordered list of the elements that make up the beamline.

It comes as a separate text file providing the specification for those individual elements, plus any metadata needed to properly interpret it (e.g. apertures, beam properties, diagnostic locations, etc.). Lattice files are essential resources for accelerator scientists and experimentalists alike, as they succinctly describe many of the relevant parameters for a beamline.

Obtaining a lattice file

These files are unique to each machine configuration. In many instances, lattice files may be publicly available, either through laboratory websites or via public open-source code repositories.

For example, a number of sample lattice files for SLAC National Accelerator Laboratory’s LCLS and FACET beamlines are publicly available in a number of formats. Similarly, example lattices for CERN’s LHC, and its tunnel predecessor, the LEP, are available via the standard Methodical Accelerator Design (MAD) format at the MAD code repository (LHC, LEP).

Uploading a lattice to Sirepo

Sirepo gives you the option of uploading a lattice file rather than building a model of an accelerator from scratch.

To upload a lattice, navigate to your Sirepo workspace for the code you’re using. On the homepage, you’ll find this import icon.

Click on that and a popup appears, as below in the Sirepo/elegant app.

From there, simply click Choose File and select the desired file from your computer. (Acceptable formats are .ele, .lte, .madx, or a zipped Sirepo export.) Once selected, click Import File.

Exporting lattice files from Sirepo

Once you’ve built your simulation, you can also export lattice files from Sirepo.

For example, the "bunchComp" example in Sirepo/elegant produces the following lattice in MAD-X format.

---

title, "bunchComp - fourDipoleCSR";

Q: DRIFT; B1: SBEND,angle=0.146607657167524,e1=0.07,e2=0.07,fint=0.5,l=0.200718260855179; B2: SBEND,angle=-0.146607657167524,e1=-0.146607657167524,e2=0,fint=0.5,l=0.200718260855179; B3: SBEND,angle=-0.146607657167524,e1=0,e2=-0.146607657167524,fint=0.5,l=0.200718260855179; B4: SBEND,angle=0.146607657167524,e1=0.146607657167524,e2=0,fint=0.5,l=0.200718260855179; L1: DRIFT,l=0.758132998376353; L2: DRIFT,l=0.5; L3: DRIFT,l=1.0; PF: DRIFT; LINA10: RFCAVITY,freq=2856e6,l=0.3,volt=4800000; LINB10: RFCAVITY,freq=2856e6,l=0.3,volt=4800000; ZWAKE: DRIFT; W1: MONITOR; W2: MONITOR; W3: MONITOR; W4: MONITOR; W5: MONITOR; LINACA: LINE=(LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE); LINACB: LINE=(LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE); BL: LINE=(Q,LINACA,W1,B1,L1,W2,B2,L2,W3,B3,L1,W4,B4,W5,L3,LINACB,PF);

beam; use, sequence=bl; twiss, file=twiss.tfs;

---

Note: When you download the .zip file for an elegant simulation, the lattice file may not be kept separately. It will, however, be included in the Python run file.

Below is the same bunchComp simulation. When you open it, you’ll see a similar description for the beamline, with some differences in how the elements are defined, owing to the different APIs used by elegant and MAD-X.

---

# bunchComp - fourDipoleCSR execution_mode = 'parallel'

lattice_file = """

"Q": CHARGE,total=1e-9 "B1": CSRCSBEND,angle=0.146607657167524,bins=500,e1=0.07,e2=0.07,l=0.200718260855179,n_kicks=100,output_file="B1.output_file.sdds",output_interval=10,sg_halfwidth=1 "B2": CSRCSBEND,angle=-0.146607657167524,bins=500,e1=-0.146607657167524,e2=0,l=0.200718260855179,n_kicks=100,output_file="B2.output_file.sdds",output_interval=10,sg_halfwidth=1 "B3": CSRCSBEND,angle=-0.146607657167524,bins=500,e1=0,e2=-0.146607657167524,l=0.200718260855179,n_kicks=100,output_file="B3.output_file.sdds",output_interval=4,sg_halfwidth=1 "B4": CSRCSBEND,angle=0.146607657167524,bins=500,e1=0.146607657167524,e2=0,l=0.200718260855179,n_kicks=100,output_file="B4.output_file.sdds",output_interval=4,sg_halfwidth=1 "L1": CSRDRIFT,dz=0.01,l=0.758132998376353,use_stupakov=1 "L2": CSRDRIFT,dz=0.01,l=0.5,use_stupakov=1 "L3": CSRDRIFT,dz=0.01,l=1.0,use_stupakov=1 "PF": PFILTER,deltalimit=0.005 "LINA10": RFCA,change_p0=1,freq=2856e6,l=0.3,phase=62,volt=4800000 "LINB10": RFCA,change_p0=1,freq=2856e6,l=0.3,phase=96,volt=4800000 "ZWAKE": WAKE,factor=8.6,inputfile="WAKE-inputfile.knsl45.liwake.sdds",interpolate=1,n_bins=1024,tcolumn="t",wcolumn="W" "W1": WATCH,filename="w1.filename.sdds" "W2": WATCH,filename="w2.filename.sdds" "W3": WATCH,filename="w3.filename.sdds" "W4": WATCH,filename="w4.filename.sdds" "W5": WATCH,filename="w5.filename.sdds" "LINACA": LINE=(LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE,LINA10,ZWAKE) "LINACB": LINE=(LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE,LINB10,ZWAKE) "BL": LINE=(Q,LINACA,W1,B1,L1,W2,B2,L2,W3,B3,L1,W4,B4,W5,L3,LINACB,PF)

"""

elegant_file = """

&global_settings mpi_io_write_buffer_size = 1048576, &end

&run_setup semaphore_file = run_setup.semaphore, centroid = "run_setup.centroid.sdds", concat_order = 2, lattice = "elegant.lte", output = "run_setup.output.sdds", p_central_mev = 54.9835, parameters = "run_setup.parameters.sdds", print_statistics = 1, sigma = "run_setup.sigma.sdds", use_beamline = "bl", &end

&run_control &end

&twiss_output alpha_x = 1, alpha_y = 1, beta_x = 10, beta_y = 10, filename = "twiss_output.filename.sdds", matched = 0, output_at_each_step = 1, statistics = 1, &end

&bunched_beam alpha_x = 1, alpha_y = 1, alpha_z = 0, beta_x = 10, beta_y = 10, beta_z = 0, distribution_cutoff[0] = 3, 3, 3, emit_x = 4.6e-08, emit_y = 4.6e-08, emit_z = 0, enforce_rms_values[0] = 1, 1, 1, n_particles_per_bunch = 50000, one_random_bunch = 0, sigma_dp = 0.001, sigma_s = 0.00065, symmetrize = 1, &end

&track &end

"""

with open('elegant.lte', 'w') as f: f.write(lattice_file)

with open('elegant.ele', 'w') as f: f.write(elegant_file)

import os os.system('elegant elegant.ele')