Collider Ring Design Tutorial using Bmad

July 30, 2024

Georg Hoffstaetter de Torquat

Daria Kuzovkova
David Sagan
Matt Signorelli
Jonathan Unger
Ningdong Wang
Contents

0 Introduction and Overview 6

1 FODO Cells 7
1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.2 Example: Forward Arc FODO Cell . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.2.1 Tao.init File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.2.2 Plotting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.2.3 Optimization Data Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.2.4 Optimization Variable Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.2.5 Running an Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.3 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

2 Dispersion Suppressor 18
2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.2 Example: Forward Dispersion Suppressor Creation . . . . . . . . . . . . . . . . 18
2.3 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

3 Dispersion Suppressor to Straight Section Twiss Parameter Matching 23

3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.2 Example: Forward Matching Section Creation . . . . . . . . . . . . . . . . . . . 23
3.3 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

4 Machine Coordinates 26
4.1 Coordinate Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4.2 Element Geometry Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.3 Local Coordinate System Construction . . . . . . . . . . . . . . . . . . . . . . . 28
4.4 Laboratory Coordinates Relative to Global Coordinates . . . . . . . . . . . . . . 29
4.5 Element Misalignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.6 Patch Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.7 Example: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.8 Exercises: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Collider Ring Design Tutorial using Bmad 2

 5 Constructing the Ring 34
5.1 Ring Construction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.2 Example: Forward Straight Section to Arc . . . . . . . . . . . . . . . . . . . . . 35
5.3 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

6 Low-Beta Interaction Region Insertion 38

6.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
6.2 Example: Constructing the Upstream and Downstream IR Lines . . . . . . . . . 39
6.3 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

7 Tune Cell 42
7.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
7.2 Example: tao.init for the Tune Cell . . . . . . . . . . . . . . . . . . . . . . . . . . 42
7.3 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

8 Particle Phase Space Coordinates 44

8.1 Phase Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
8.2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
8.3 Exercises: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

9 RF Cavities 48
9.1 Reference Energy and the Lcavity and RFcavity Elements . . . . . . . . . . . . 48
9.2 Example: Cavity Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
9.3 Adding RF Cavities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
9.4 Example: Consturcting the FODO cell with RF cavities . . . . . . . . . . . . . . 50
9.5 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

10 Introduction to Long Term Tracking 52

10.1 Initializing a Beam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
10.2 Initializing long term tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
10.3 Particle Track Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
10.4 Averages Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
10.5 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Collider Ring Design Tutorial using Bmad 3

 11 Control Elements 57
11.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
11.2 Example Lattice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
11.3 Control Element Organization in the Lattice . . . . . . . . . . . . . . . . . . . . . 58
11.4 Overlay Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
11.5 Group Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
11.6 Example: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
11.7 Exercises: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

12 Dynamic Aperture 63
12.1 Calculating Dynamic Aperture . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
12.2 Example: Adding Sextupoles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
12.3 Example: Chromaticity Correction . . . . . . . . . . . . . . . . . . . . . . . . . . 66
12.4 Advanced Dynamic Aperture Correction . . . . . . . . . . . . . . . . . . . . . . 67
12.4.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
12.5 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

13 Model, Design and Base Lattices in Tao 71

13.1 Changing Model Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
13.2 Using the Base Lattice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
13.3 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

14 Orbit Correction 75
14.1 Example: Adding Corrector Coils and BPMs . . . . . . . . . . . . . . . . . . . . 75
14.2 Example: Radiation-induced Sawtooth Orbit Correction . . . . . . . . . . . . . . 76
14.3 Example: Orbit Correction with Quadrupole Misalignments . . . . . . . . . . . . 79
14.4 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

A Python/PyTao Interface 81
A.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
A.2 Basic Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
A.2.1 Initializing Tao . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
A.2.2 Send a Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
A.2.3 Jupyter magic %%tao . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Collider Ring Design Tutorial using Bmad 4

 A.2.4 Interface Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

B Answers to Selected Exercises 83

B.1 Chapter 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
B.2 Chapter 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
B.3 Chapter 9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
B.4 Chapter 11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
B.5 Chapter 13 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Collider Ring Design Tutorial using Bmad 5

 0 Introduction and Overview

This ring design tutorial serves as an introductory guide to the Bmad ecosystem for relativistic
charged–particle and X-Ray simulations. At the heart of this ecosystem is the open source Bmad
toolkit (software library) which can be used to construct simulation programs in less time and with
fewer bugs than can be done from scratch. But Bmad is more than just a toolkit, and the Bmad
ecosystem contains many programs that use the toolkit as the engine for doing simulations. A
few of these programs will be introduced in this tutorial. Principal among these is Tao which is
a general purpose design and simulation program. The other programs introduced are the Long
Term Tracking program for particle tracking including spin and radiation, the Dynamic Aperture
program used for calculating dynamic apertures, and the SODOM-2 program for calculating the
invariant spin field. Not covered is the advanced topic of programming using the Bmad toolkit.
For a discussion on Bmad programming, the reader is referred to the Bmad manual.
The EIC will probe the In this tutorial you will design, your own collider ring based on the 18 GeV Electron Storage
properties of matter via Ring (ESR) of the Electron-Ion Collider (EIC) currently in design at the Brookhaven National
deep inelastic scatter-
ing while colliding spin- Laboratory on Long Island. By the end, you’ll gain both an understanding of many important
polarized electrons with concepts involved in building a real collider ring, as well as experience using Bmad.
protons and nuclei.
The ring design sections of the tutorial includes a short introduction to what is to be done, fol-
lowed by an example. The example lattice files include instructions at the top describing how to
create the lattice file step-by-step, numbered (1), (2), etc. Each number is also located at the
place in the lattice file where that step is performed.
Needed is the Bmad manual along with the manuals of programs used for this tutorial. All of this
is available at the Bmad web site:
www.classe.cornell.edu/bmad/

Also to be found on the site are the input files for the programs. The input files are in a directory
tree whose root directory is /RingDesign/lattices.

Collider Ring Design Tutorial using Bmad 6

1 FODO Cells

QD

B
QF

SD
B

SF
(a) Forward arc FODO cell.

QD
B

B
SD
QF
SF

(b) Reverse arc FODO cell.

Figure 1: QF, QD: Focusing and defocusing quadrupoles respectively. SF, SD: Sextupoles near
focusing and defocusing quadrupoles respectively.

0 100 200 300 400 500

0 0

4 Straight Dispersion
FoDo cells “creator”
20 Arc FoDo cells
Match to
-100 -100
dispersion
“generator”
X

-200 -200
Dispersion suppressor

Match to straight section

4 Straight FoDo cells

-300 -300
0 100 200 Z 300 400 500

Figure 2: A sextant of the ring.

1.1 Introduction

In the arc FODO cells of the Electron Storage Ring (ESR), a sextupole, a bend, and a cor-
rector coil all need to fit in between each quadrupole. To accommodate the sextupoles, the

Collider Ring Design Tutorial using Bmad 7

 quadrupoles cannot be centered between the bends. As a result, there are two types of FODO
cells in the ESR: one which has the sextupoles placed before the quadrupoles and one which
has the sextupoles placed after the quadrupoles. We’ll call these the “forward” and “reverse”
cells respectively and are shown in Figs. 1a and 1b. This tutorial will use the convention that all
FODO cells start with a full-length horizontally-focusing (K1 > 0) quadrupole.
The ring is made up 6 sextants as discussed in chapter §5. There are two types of sextants:
forward sextants with forward FODO cells and reverse sextants with reverse FODO cells. The
two types of sextants have mirror symmetry with respect to one another. Each sextant consists
of two half-length straight sections with an arc section in between as shown in Fig. 2.
The first straight section, in which the dispersion is zero, is followed by a dispersion “creator” to
match to the periodic dispersion in the arc. After the arc, there is a dispersion “suppressor” to
match the dispersion free second straight section.

1.2 Example: Forward Arc FODO Cell

The phase advance per FODO cell for the lattice to be designed is chosen to be 90◦ to achieve
Later in the tutorial the emittance requirements. Construction of the forward arc FODO cell without sextupoles will
the sextupoles and be demonstrated below. Left as an exercise will be the construction of the reverse arc FODO
corrector coils will cell without sextupoles along with the forward and reverse straight section FODO cells. Example
be added in.
files can be found in the /lattices/1_FoDoA/a_Arc/ directory.

0.5m 0.5m
Lchord = 6.86m Lchord = 6.86m

0.609m 1.241m 0.609m 1.241m

B

B
QD
QF

Figure 3: Forward arc FODO cell with lengths specified.

See the Bmad man- Figure 3 shows the lengths of each element in the forward arc FODO cell. The ESR uses
ual for details on the rectangular bends (rbends) in the arcs. Note: In Bmad, following the MAD convention, the length
different types of el- L of an rbend in the lattice file specifies the chord length, whereas for sector bends (sbends) it
ements.
specifies the arc length. See the Bends: Rbend and Sbend section in the Bmad manual for more
details. When rbends are read in, Bmad will convert them to sbends, will set L_chord equal to
the input L, and will set L equal to the true arc length.
Our collider ring with have 132 arc FODO cells, and so each bend must precess the orbit by an
angle 2π/(2 ∗ 132). Choosing initially arbitrary quadrupole strengths K1, the Bmad file for this
lattice is:
! L a t t i c e f i l e : fodoAF0 . bmad
parameter [ p0c ] = 1.7846262612447E10 ! Reference momentum i n eV
parameter [ p a r t i c l e ] = E l e c t r o n
parameter [ geometry ] = c l o s e d ! C a l c u l a t e s t h e p e r i o d i c Twiss parameters

QF: Quadrupole , L = 0 . 5 , K1 = 0.4

Collider Ring Design Tutorial using Bmad 8

 QD: Quadrupole , L = 0 . 5 , K1 = −0.4
B : Rbend , L = 6 . 8 6 , angle = p i /132
D1 : D r i f t , L = 0.609
D2 : D r i f t , L = 1.241

FODOAF: l i n e = (QF, D1 , B , D2 , QD, D1 , B , D2 )

use , FODOAF

Make sure you are in the directory /lattices/1_FoDoA. On the command line, the lattice can be
opened in Tao using the command
t a o − l a t fodoAF0 . bmad

where the “-lat” flag is short for -lattice and the argument following this flag needs to be the name
of the Bmad lattice file being analyzed. Specifying a lattice on the command line will override
any default lattice specified in the tao.init file. In this case, the tao.init file does not specify a
lattice so the -lat flag is needed on the command line.
When Tao is started, a plot window will open showing the beta functions, dispersion, orbit, and
lattice layout. If the plot window is too large for the screen, the -geom flag followed by a width and
height in the format <width>x<height> can be used to adjust the window size. For example:
t a o − l a t fodoAF0 . bmad −geom 400x400

To view a summary of all the flags, use the command:

tao −help

After opening the above lattice in Tao, the show lattice command can be used to view the lattice:
Tao> sho lat ! A b b r e v i a t i o n s are a c c e p t a b l e so " sho l a t " works .
# Values shown are f o r t h e E x i t End o f each Element :
# Index name key s l beta phi_a ...
Bmad always includes # a [2 pi ] ...
a BEGINNING ele- 0 BEGINNING Beginning_Ele 0.000 −−− 43.90 0.000 ...
ment at the beginning. 1 QF Quadrupole 0.500 0.500 43.90 0.002 ...
2 D1 Drift 1.109 0.609 38.69 0.004 ...
3 B Sbend 7.969 6.860 3.97 0.098 ...
4 D2 Drift 9.210 1.241 2.39 0.164 ...
5 QD Quadrupole 9.710 0.500 2.39 0.198 ...
6 D1 Drift 10.319 0.609 2.98 0.234 ...
By default, Bmad 7 B Sbend 17.179 6.860 33.65 0.354 ...
puts an END marker 8 D2 Drift 18.420 1.241 43.90 0.359 ...
element at the end 9 END Marker 18.420 0.000 43.90 0.359 ...

By default, Tao, will print values evaluated at the downstream end of elements (the end where
particles exit the element). To print information evaluated at the middle or beginning of each
element, include the -middle or -beginning flags in the show lat command respectively.
To see the phase advance at the end of the lattice, use theshow element end command:
“show ele 9” also
Tao> show element end
works.
Element # 9
Element Name : END
Key : Marker
S_start , S: 18.420324 , 18.420324

Collider Ring Design Tutorial using Bmad 9

 R e f _ t i m e _ s t a r t , Ref_time : 6.144359E−08 , 6.144359E−08

A t t r i b u t e v a l u e s [ Only non−zero v a l u e s shown ] :

1 L = 0.0000000E+00 m
...
Twiss a t end o f element :
A B ...
Beta (m) 43.89736699 2.38487039 | 0.00000000 0.00000000 ...
Alpha −4.42108656 0.34433533 | 0.00000000 0.00000000 ...
Gamma ( 1 /m) 0.46804644 0.46902625 | Gamma_c = 1.00000000 ...
Phi is the betatron
Phi ( rad ) 0.00000000 0.00000000 X Y
phase.
Eta (m) 0.38412123 0.00000000 0.38412123 0.00000000 ...
Etap 0.03789803 0.00000000 0.03789803 0.00000000 ...
dEta / ds 0.03789803 0.00000000 0.03789803 0.00000000 ...
Sigma 0.00066663 0.00000011 0.00000000 0.00000000

Orbit : Electron State : Alive

P o s i t i o n [mm] Momentum [ mrad ] Spin | ...
X: 0.00000000 0.00000000 | ...
Y: 0.00000000 0.00000000 | ...
Z: 0.00000000 0.00000000 | ...

Tao calculates the Twiss parameters of the eigenmodes of the 1-turn matrix. For an uncoupled
ring, the A mode corresponds to what other programs label the horizontal (x) Twiss, and the B
mode corresponds to the vertical (y) Twiss.

1.2.1 Tao.init File

Given our arbitrary choice of quadrupole strengths, the phase advance at the end of our FODO
Additionally, Tao has
an interface with
cell is not 90◦ . In order to determine what strengths will produce the desired phase advance, the
Python allowing use optimizers built into Tao can be used. To perform an optimization, data and variables must be
of Python based defined in a tao.init file. A tao.init file is also useful if you’d like Tao to run with special settings,
optimizers. e.g. a 400x400 plot page size (so the -geom flag does not need to be included when running
Tao), or even custom plots. In order to determine the correct quadrupoles strengths, for a 90◦
phase advance, the tao.init file might look like:
! tao . i n i t f i l e
&t a o _ p l o t _ p a g e
p l o t _ p a g e%s i z e = 400 , 400 ! Sets t h e p l o t page s i z e
p l o t _ p a g e%t e x t _ h e i g h t = 8 ! Makes t h e p l o t page t e x t s i z e s m a l l e r
p l o t _ p a g e%n_curve_pts = 5000 ! Adds more sampled p o i n t s t o t h e p l o t s
/

&tao_d2_data
d2_data%name = " phase "
n_d1_data = 1
/

&tao_d1_data
ix_d1_data = 1
datum ( 1 ) = " phase . a " " " " " " end " " t a r g e t " 1.570796326794897 10.0
datum ( 2 ) = " phase . b " " " " " " end " " t a r g e t " 1.570796326794897 10.0
/

Collider Ring Design Tutorial using Bmad 10

 &t a o _ v a r
v1_var%name = " quads "
v a r (1:2)% ele_name = "QF" , "QD"
d e f a u l t _ s t e p = 1e−6
d e f a u l t _ a t t r i b u t e = " k1 "
/

There’s a lot going on here, so let’s decompose each “namelist” in this file.

1.2.2 Plotting

The first namelist, tao_plot_page, tells Tao to open with a plot window with a size of 400x400,
a text height of 8pt, and include 5,000 points for each plot. The last setting will be useful when
looking at the betas for the entire ring, as aliasing may be present with the default settings
causing plotting artifacts.

1.2.3 Optimization Data Setup

d2_data d2_data
[EG: “orbit”]

d1_data
[EG: “x”]
d1_data
[EG: “y”]
d1_data ...
datum
[Index: 36]
datum
[Index: 37]
datum ...
Figure 4: Tao’s tree structure for datums. A d2_data structure holds an array of d1_data
structures and a d1_data structure holds an array of datums.

Data: The next two namelists, tao_d2_data and tao_d1_data, define the data of the optimiza-
tion. “Data" are the conditions that we wish to satisfy via optimization. In this case, wanted is to
make the horizontal and vertical phase advances 90◦ from start to end. A quick look at the “Tao
Data Types" section in the “Data" chapter of the Tao manual shows that the desired data types
are called phase.a and phase.b.
Fig. 4 shows how data is organized in a three level tree-structure which serves as an aid to the
user in keeping the data organized. At the top level, d2_data structures are defined. A d2_data
structure is defined with a tao_d2_data namelist. In this case, there is a single d2_data struc-
ture named “phase”. Every d2 structure has an array of d1_data structures under it. In this
example there is only one (n_d1_data = 1) and this d1 structure is defined in the tao_d1_data
namelist below the tao_d2_data namelist. Every d1_data structure has an array of data struc-
tures with each data structure representing a single datum. In this example there are two datums,
the first for phase.a and the second for phase.b.

Collider Ring Design Tutorial using Bmad 11

 While this example used a single d2_data and a single d1_data structure, a differing organiza-
tion could have been used and each datum could have been assigned its own separate d2_data
and a single d1_data structures. Ultimately, the tree organization has no impact on the outcome
of the optimization.
The datums for the optimization are defined on the lines
datum ( 1 ) = " phase . a " " " " " " end " " t a r g e t " 1.570796326794897 10.0
datum ( 2 ) = " phase . b " " " " " " end " " t a r g e t " 1.570796326794897 10.0

The syntax for setting datums is discussed in the “Data and Constraint Initialization" section of
the “Initialization" chapter of the Tao manual. Basically, the datums will be assigned “model”
values which are the horizontal and vertical mode phase advances at the END element of the
FODO cell, and the optimizer will adjust variable settings to try to get these model values equal
to what is called the “measured” values which are set to π/2 as shown above.
Optimization involves minimization of a merit function M which is evaluated using the formula
X  2 X  2
M≡ wi δDi + wj δVj (1)
i j

where the first sum is a sum over the data and the second sum is a sum over the variables.
The wi and wj are weights specified by the user and the δDi and δVj are functions of the data
and variables. The merit function is discussed in depth in the “Optimization" chapter in the Tao
manual.
The datums defined above both have weights of 10.0. Datum weights can have a large effect
on optimizations. Often times, the best way to choose the correct weight is trial and error (is the
optimization converging well or not?).
The datums defined above both use a merit_type that is set to "target". In this case, δD in
Eq. (1) is evaluated using the equation
δD = model − meas

where model is the value as calculated from the lattice and meas is the “measured” value as set
on the datum line. In this case, the meas value is π/2 for both datums.
Datum names are in the form
<d2−data −name>. <d1−data −name> [ datum− i n d e x ]

In this case, the d2_data structure has the name (set by d2_data%name in the file) of "phase".
The name of the d1_data structure is not specified in the file and so gets the default name of “1"
(if there were other d1_data structs associated with this d2_data structure, the default names
would be “2", “3", etc.). The datums have names
phase . a datum : phase . 1 [ 1 ] ! Can be shortened t o phase [ 1 ]
phase . b datum : phase . 1 [ 2 ] ! Can be shortened t o phase [ 2 ]

Since there is only one d1_datum here the “.1” specifier can be omitted. The show data com-
mand will display a list of defined d2_data:

Collider Ring Design Tutorial using Bmad 12

 Tao> show data
Name Using f o r O p t i m i z a t i o n
phase [ 1 : 2 ] Using : 1 : 2

To see information on a particular d2_data structure, use the command show data <d2> where
<d2> is the name of the structure. In this case:
Tao> show data phase
Data name : phase . 1
| Useit
. . . Ele Meas Model Design | Opt P l o t
1 phase . a < t a r g e t > . . . END 1.57079E+0 2.25845E+0 2.25845E+0 T F
2 phase . b < t a r g e t > . . . END 1.57079E+0 2.260399+0 2.26039E+0 T F

The design value is the value of the “design" lattice which is a lattice Tao creates representing the
lattice that was read in (discussed in depth in chapter §13). The parameters in the design lattice
are fixed and cannot change. This is in contrast to the “model" lattice where the parameters are
changeable and it is the quadrupole strengths of the model lattice which will be varied in the
optimization. In this case, the merit function is calculated using the difference model - meas (see
above), the design lattice does not influence the present optimization.
To see information on a particular datum, use the show data <datum> where <datum> is the
name of the datum. For example:
Tao> show data phase [ 1 ]

%ele_name = "END"
. . . etc . . .
%d a t a _ t y p e = " phase . a "
. . . etc . . .
%model = 2.25845820E+00
%design = 2.25845820E+00
. . . etc . . .
%w e i g h t = 1.00000000E+01
%e x i s t s = T
%good_model = T
%good_design = T
%good_base = T
%good_meas = T
. . . etc . . .
%u s e i t _ p l o t = F
%u s e i t _ o p t = T

The useit_opt logical indicates whether the datum will be used when the merit function is evalu-
ated. For example, if the meas value has not been set, Tao will set good_meas to False and this
will cause Tao to set useit_opt to False.

1.2.4 Optimization Variable Setup

The last namelist, tao_var, in the above tao.init file defines the variables of the optimization
&t a o _ v a r
v1_var%name = " quads "

Collider Ring Design Tutorial using Bmad 13

 v a r (1:2)% ele_name = "QF" , "QD"
d e f a u l t _ s t e p = 1e−6
d e f a u l t _ a t t r i b u t e = " k1 "
/

variables are the things to vary in the optimization to satisfy the conditions defined by
the data. Variables are grouped in a tree structure just like data except for variables there are
only two layers instead of the three for data. The top layer is a set of v1_var structures. In this
case there is a single v1_var structure called "quads". Every v1_var structure has an array of
variables. In this case, the quads v1_var structure has a two variable array with the variables
controlling the k1 attribute of the QF, and QD quadrupoles respectively. To calculate derivatives
for the optimization, Tao uses finite differences and so a step size must be specified. The step
size can be different for different variables but here a default value of 1e-6 is used that will be
applied to all the variables. Variables can have weights which affects the merit function. Weights
for variables are useful when there are “degeneracies" or near-degeneracies where, without
variable weights, the optimizer can find solutions with small merit function values with variables
having unphysically large values. The weights can constrain variables to have reasonable values.
In this case there are no degeneracies and variable weights are not needed.
To refer to an individual variable use the syntax:
v1−var −name [ var − i n d e x ]

where var-index is the index of the variable. For example, the first variable in the quad structure
is quad[1], etc.
When running Tao, the show variable command can be used to view a list of the v1_vars defined
Tao> show v a r
Name Using f o r O p t i m i z a t i o n
quads [ 1 : 2 ] 1:2

The show variable <v1> can be used to show information on a particular v1_var named <v1>
Tao> show v a r quads
Variable Slave Parameters Meas Model Design U s e i t _ o p t
quads [ 1 ] QF[ K1 ] 0.0000E+00 4.0000E−01 4.0000E−01 T
quads [ 2 ] QD[ K1 ] 0.0000E+00 −4.0000E−01 −4.0000E−01 T

And the show variable <var> can be used to show information on a particular variable named
<var>
Tao> show v a r quads [ 2 ]
%ele_name = "QD"
%a t t r i b _ n a m e = " K1 "
. . . etc . . .
%model = −4.00000000E−01
. . . etc . . .
%e x i s t s = T
%good_var = T
%good_user = T
%good_opt = T
%u s e i t _ o p t = T

Collider Ring Design Tutorial using Bmad 14

1.2.5 Running an Optimization

To see what data and what variables are being used in the optimization, use the show data
and show variables commands as discussed above. To see optimizer parameters, use the show
optimizer command:
Tao> show o p t i
Data Used :
phase [ 1 : 2 ] Using : 1 : 2
V a r i a b l e s Used :
quads [ 1 : 2 ] Using : 1 : 2

optimizer : " lm "

G l o b a l o p t i m i z a t i o n parameters ( use " s e t g l o b a l " t o change ) :
%d e _ l m _ s t e p _ r a t i o = 1.00000000E+00
%d e _ v a r _ t o _ p o p u l a t i o n _ f a c t o r = 5.00000000E+00
%l m _ o p t _ d e r i v _ r e i n i t = −1.00000000E+00
...

There are many parameters associated with optimization and it is important to carefully consider
what values these parameters have in order to be able to have a successful optimization.
To see how the merit function is being evaluated, use the show constraints command:
Tao> show cons

Constraints ... Ele / S Meas−or −Lim Model Merit

phase [ 1 ] phase . a < t a r g e t > ... END 1.5708E+00 2.2585E+00 4.729E+00
phase [ 2 ] phase . b < t a r g e t > ... END 1.5708E+00 2.2604E+00 4.756E+00
quads [ 1 ] QF[ K1 ] ... 0.50 −1.0000E+30 4.0000E−01 0.000E+00
quads [ 2 ] QD[ K1 ] ... 9.71 −1.0000E+30 −4.0000E−01 0.000E+00

f i g u r e o f m e r i t : 9.484309E+00

! Top 10
Constraints ... Ele / S Meas−or −Lim Model Merit
phase [ 2 ] phase . b < t a r g e t > ... END 1.5708E+00 2.2604E+00 4.756E+00
phase [ 1 ] phase . a < t a r g e t > ... END 1.5708E+00 2.2585E+00 4.729E+00
quads [ 2 ] QD[ K1 ] ... 9.71 −1.0000E+30 −4.0000E−01 0.000E+00
quads [ 1 ] QF[ K1 ] ... 0.50 −1.0000E+30 4.0000E−01 0.000E+00

This shows, among other things, that the value of the merit function is 9.48 and that the largest
contributor to the merit function by a hair is phase[2] which has a contribution of 4.756 which is
about 50% of the total merit function. In this optimization, the variables do not contribute to the
merit function.
There are several optimizers that can be used as detailed in the Tao manual. For global opti-
mization use the de (Differential Evolution) optimizer. All other optimizers will only converge to
the local optimum but will converge faster than de. In this case, the optimum is local so the lm
(Levenburg-Marquardt) optimizer will be used which is the default:
Tao> run
O p t i m i z i n g w i t h : lm
Type ‘ ‘ . ’ ’ t o s t o p t h e o p t i m i z e r b e f o r e i t ’ s f i n i s h e d .
[ INFO ] tao_dmodel_dvar_calc :

Collider Ring Design Tutorial using Bmad 15

 Remaking dModel_dVar d e r i v a t i v e m a t r i x .
T h i s may t a k e a w h i l e . . .

Cycle Merit A_lambda

1 4.3831E−01 1.00E−04
2 5.7875E−02 1.00E−05
3 8.5664E−03 1.00E−06
. . . etc . . .
20 1.7768E−16 1.00E−23
W r i t t e n : var1 . o u t
21 1.7768E−16 0.00E+00

The Merit value is now about 10−16 showing good convergence which can be seen by examining
the data:
Tao> show data phase
Data name : phase . 1
| Useit
. . . Ele Meas Model Design | Opt P l o t
1 phase . a < t a r g e t > . . . END 1.570796E+0 1.570796E+0 2.258458E+0 T F
2 phase . b < t a r g e t > . . . END 1.570796E+0 1.570796E+0 2.260399E+0 T F

And the model lattice has the correct phase advance.

Use write bmad fodoAF.bmad after optimizing to create a new lattice file with name fodoAF.bmad
having the optimized quadrupole strengths. Note that fodoAF.bmad will contain the beginning
periodic Twiss, dispersion, and orbit (only non-zero values are put in the file so the orbit does not
explicitly appear in this instance). This is very useful if the geometry is switched from closed to
open as will be discussed in the following chapter.

1.3 Exercises

1. Reverse arc FODO: Construct the reverse arc FODO cell without sextupoles, and determine
the quadrupole strengths for a 90◦ phase advance. Let the optimized lattice file name be
fodoAR.bmad.
2. Forward straight section FODO: Replace the dipoles in the forward cell by a drift (empty
space) of length 5.855m and name the drifts DB. This length is chosen to produce the same
straight section length as in the RHIC tunnel. Additionally, rename the horizontally-focusing
and defocusing quadrupoles QFSS and QDSS respectively. Which quadrupole strengths lead
to 90 degrees phase advance in both planes? Use the name fodoSSF.bmad for the optimized
lattice file. Note: files are in 1_FODO/b_SS/F
3. Reverse straight section FODO: Replace the dipoles in the reverse cell by a drift of length
5.855m and name the drifts DB. Rename the horizontally-focusing and defocusing quadrupoles
QFSS and QDSS respectively. Which quadrupole strengths lead to 90 degrees phase ad-
vance in both planes? Use the name fodoSSR.bmad for the optimized lattice file. These
quadrupole strengths should be exactly the same as in fodoSSF.bmad
4. Analytical FODO cell: Using a FODO model with the same total length as constructed above
but with zero length quadrupoles, and no bends. Calculate by hand the appropriate quad

Collider Ring Design Tutorial using Bmad 16

 strengths that lead to a 90 degrees phase advance in x and y. What are the beta functions at
the thin quads? How do the quad strengths and beta functions compare to above?

5. Forward and Reversed Cells: Check that your forward and reverse arc FODO cells that
both start with focusing quads have different periodic beta and alpha functions. Check also
that both cells, for the same phase advance of 90 degrees have exactly the same quadrupole
strength. Explain why this is so
6. L, L_arc, and L_chord: For rbend elements, to be consistent with the MAD program, the
input “l" length in the lattice file is used as the chord length. On input, the rbends are converted
to sbends and after the conversion l will be set to the true arc length. For the rbends in the
above lattice, what is the difference of the values between these two lengths? [Hint: Use the
“show ele" command.]
7. show lattice command: The show lattice command is very powerful (and has a lot of op-
tions). Can you figure out what the following command shows?
Tao> show l a t − a t t r i b k1 quadrupole : : *

8. show data <datum> command: An individual datum is a complicated beast and the output
of the show data <datum> command reflects this. Look at the full (not abridged output
above) output and by reading the Tao manual see if you can make sense of the individual
components.
9. The good_user logical: One component of a datum or variable is good_user which is set by
the user and controls whether the datum or variable will be used in the optimization. Com-
mands to control good_user are use, veto and restore. Play around with these commands to
see how changing this affects the optimization.

Collider Ring Design Tutorial using Bmad 17

2 Dispersion Suppressor

2.1 Introduction

To connect an arc to the following straight section in a sextant, the dispersion in the straight
section must be suppressed to zero while minimally changing the betas. For a 90◦ lattice, this
can be approximately achieved by using two equivalent arc FODO cells with the bends at half-
strength. To get the dispersion and dispersion derivative at the end of the dispersion suppressor
exactly zero, the last two quadrupoles can be minimally varied.
0.6
η
η
X
Dispersion [model]
Y

0.4
η , η [m]
Y
X

0.2

0
0 4 8 12 16 s [m] 20 24 28 32 36
half-strength half-strength half-strength half-strength
Arc FODO Straight
cells section

QDF1
QFF1
QD

BH
BH

BH

BH
QF

Vary QFF1 and QDF1 to

make ηx = η’x = 0 at end

Figure 5: Dispersion suppressor.

2.2 Example: Forward Dispersion Suppressor Creation

The procedure for creating the forward dispersion suppressor is outlined below. The reverse
dispersion suppressor construction is left as an exercise. The example files can be found in the
/lattices/2_DispSuppress/F/ directory.
To create the forward dispersion suppressor:

1. Create a copy of the fodoAF.bmad file, which contains the optimized quadrupole strengths
for the 90◦ phase advance FODO cell.
2. In this new copy, set parameter[geometry] equal to open. This tells Bmad to not calculate the
periodic betas, instead propagating the initial betas specified in the lattice file (which in this
case, are the beginning periodic betas in the arc cells) through the lattice.
parameter [ geometry ] = open ! ( 2 ) : Set geometry t o open

Collider Ring Design Tutorial using Bmad 18

 3. Define a new half-strength bend element and the two special quadrupoles to vary to make
ηx = ηx′ = 0. The strengths will be calculated via optimization. Because these special
quadrupoles are in the forward sextant (F), and are the first “special” quadrupoles (1), use the
names QFF1 and QDF1 (that is, add an F1 suffix to the original quadrupole names).
! ( 3 ) : D e f i n e h a l f bend and quads f o r d i s p e r s i o n s u p p r e s s i o n
BH: rbend , L = 6 . 8 6 , angle= p i / 1 3 2 / 2
QFF1 : Quadrupole , L = 0 . 5 , K1 = 0 . 3
QDF1 : Quadrupole , L = 0 . 5 , K1 = −0.3

4. Define and use the new line as in Fig. 5 containing the half bends and special quads. Since
this is the forward dispersion suppressor, use the name DISPSUPF for the line.
! ( 4 ) : D e f i n e t h e new l i n e f o r h a l f bends
DISPSUPF : l i n e = (QF, D1 , BH, D2 , QD, D1 , BH, D2 ,
QFF1 , D1 , BH, D2 , QDF1, D1 , BH, D2 )
use , DISPSUPF

The completed initial lattice file containing these changes is provided in the example file
named dispsupF0.bmad.
5. A tao.init file is needed to define the optimization parameters. This might look like:
&t a o _ p l o t _ p a g e
p l o t _ p a g e%s i z e = 400 , 400
p l o t _ p a g e%t e x t _ h e i g h t = 8
p l o t _ p a g e%n_curve_pts = 5000
/

! Set t h e number o f c y c l e s t o 1000 t o a v o i d having t o t y p e " run " l e s s

&tao_params
g l o b a l%n _ o p t i _ c y c l e s = 100
g l o b a l%n _ o p t i _ l o o p s = 100
/

Use the "show &tao_d2_data

opt" to see opt d2_data%name = " d i s p "
params. n_d1_data = 1
/

&tao_d1_data
ix_d1_data = 1
datum ( 1 ) = " e t a . x " " " " " " end " " t a r g e t " 0 10
datum ( 2 ) = " deta_ds . x " " " " " " end " " t a r g e t " 0 10
/

&t a o _ v a r
v1_var%name = " quads "
v a r (1:2)% ele_name = "QFF1 " , "QDF1"
d e f a u l t _ s t e p = 1e−6
d e f a u l t _ a t t r i b u t e = " k1 "
/

This tao.init file has a namelist tao_params in which n_opti_cycles, the number of opti-
mization cycles, is set equal to 100 (the default is 20). When the optimizer goes through
n_opti_cycles, this is called a loop. Before each loop, the derivatives of how much the data

Collider Ring Design Tutorial using Bmad 19

 changes with change in variable is computed. Periodic recomputation is needed since lattices
are never linear and so the derivatives change as variables are varied. Also in the tao_params
namelist the number of loops, which is set by n_opti_loops, is set to 100 (the default is one).
These are two of many parameters that can be set to customize the Tao experience. See the
Tao manual for more options.
The tao.init file has two datums, one for the horizontal dispersion eta.x and one for its slope
deta_ds.x. Both are desired to be exactly zero at the end of the lattice and they have equal
weight. Additionally, the variables are the k1 strength of the two special quadrupoles QFF1
and QDF1.
6. Starting Tao with the new tao.init file, the show constraints command can be used to verify
that the optimization is set up correctly:
Tao> show cons

Constraints ... Ele / S Meas−or −Lim Model Merit

disp [ 1 ] eta . x < target > ... END 0.0000E+00 5.1814E−02 2.685E−02
disp [ 2 ] deta_ds . x < t a r g e t > ... END 0.0000E+00 3.9512E−03 1.561E−04
quads [ 1 ] QFF1 [ K1 ] ... 18.92 −1.0000E+30 3.0000E−01 0.000E+00
quads [ 2 ] QDF1 [ K1 ] ... 28.13 −1.0000E+30 −3.0000E−01 0.000E+00
Constraints ... Ele / S Meas−or −Lim Model Merit

f i g u r e o f m e r i t : 2.700305E−02

! Top 10

Constraints ... Ele / S Meas−or −Lim Model Merit

disp [ 1 ] eta . x < target > ... END 0.0000E+00 5.1814E−02 2.685E−02
disp [ 2 ] deta_ds . x < t a r g e t > ... END 0.0000E+00 3.9512E−03 1.561E−04
quads [ 2 ] QDF1 [ K1 ] ... 28.13 −1.0000E+30 −3.0000E−01 0.000E+00
quads [ 1 ] QFF1 [ K1 ] ... 18.92 −1.0000E+30 3.0000E−01 0.000E+00
Constraints ... Ele / S Meas−or −Lim Model Merit

f i g u r e o f m e r i t : 2.700305E−02

7. The optimizer can now be run:

Tao> run
O p t i m i z i n g w i t h : lm
Type ‘ ‘ . ’ ’ t o s t o p t h e o p t i m i z e r b e f o r e i t ’ s f i n i s h e d .
[ INFO ] tao_dmodel_dvar_calc :
Remaking dModel_dVar d e r i v a t i v e m a t r i x .
T h i s may t a k e a w h i l e . . .

Cycle Merit A_lambda

1 7.0232E−05 1.00E−04
2 4.0222E−05 1.00E−05
3 1.2014E−05 1.00E−06
. . . etc . . .
156 1.9259E−33 1.36E+10
O p t i m i z e r a t minimum o r d e r i v a t i v e s need t o be r e c a l c u l a t e d .
W r i t t e n : var1 . o u t
157 1.9259E−33 0.00E+00

8. The show data and show var commands can be used to inspect the data and variables:

Collider Ring Design Tutorial using Bmad 20

 Tao> show data d i s p
Data name : d i s p . 1
| Useit
. . . Ele Meas Model Design | Opt P l o t
1 eta . x < target > . . . END 0.0000E+00 1.3877E−17 5.1814E−02 T F
2 deta_ds . x < t a r g e t > . . . END 0.0000E+00 0.0000E+00 3.9511E−03 T F

Tao> show v a r quads

Variable Slave Parameters Meas Model Design Useit_opt
quads [ 1 ] QFF1 [ K1 ] 0.0000E+00 3.1279E−01 3.0000E−01 T
quads [ 2 ] QDF1 [ K1 ] 0.0000E+00 −3.1244E−01 −3.0000E−01 T

The dispersion and its slope are 0 or negligibly small so the optimization has been sucessful.
9. Use write bmad dispsupF.bmad to create a new lattice file named dispsupF.bmad with the
optimized quadrupole strengths. This will be the dispersion suppressor for the forward sex-
tants.

2.3 Exercises
1. Reverse dispersion suppressor: Construct the reverse dispersion suppressor, optimizing
the last two quadrupole strengths for ηx = ηx′ = 0 exactly at the end for a 90◦ phase ad-
vance. How do the two quadrupole values for the reverse dispersion suppressor compare
to those obtained in class for the forward suppressor? Name the optimized lattice file name
dispsupR.bmad.

2. Forward and Reversed Cells: Check that your forward and reverse cells that both start with
focusing quads have different periodic beta and alpha functions. Check also that both cell, for
the same phase advance of 90 degrees have exactly the same quadrupole strength. Explain
how this can be the correct solution.
3. Dispersion derivative: Tao calculates a “dispersion derivative" and a “momentum disper-
sion" which for the x plane are deta_ds.x and etap.x respectively. What is the difference
between the two? Show that with the lattice being designed they are the same. Hint: See the
Bmad manual.
4. Normal mode dispersion: What is the difference between the horizontal ηx and vertical
ηy dispersions and the normal mode dispersions ηa and ηb in the lattice being constructed?
Verify your answer by checking the difference for one lattice element (Use the “show ele"
command).
5. Setting optimization parameters: The tao.init file for this chapter sets the global param-
eter global%n_opti_cycles to 100 and this setting happens when Tao is started. Besides
being able to set this parameter in the initialization file, this, and all other parameters, may be
set from Tao’s command line. What is the command to set global%n_opti_cycles from the
command line?
6. Strength of bends: [Warning! This is a difficult problem!] To a good approximation, a disper-
sion suppressor between from an arc FODO line to a straight FODO line (where the straight

Collider Ring Design Tutorial using Bmad 21

 FODO cells have the same layout as the arc FODO cells except that the bends are replaced
by drifts) can be constructed using two arc FODO cells with the first cell having the bend
strengths reduced by a factor α and the second cell with the bend strengths reduced by a
factor 1 − α. In the case of 90◦ FODO cells, α is 0.5. Note: The approximation is only valid
in the case of weak bends. Problem: Prove that this is the case and show that for 60◦ FODO
cells the value of α is zero.

Collider Ring Design Tutorial using Bmad 22

3 Dispersion Suppressor to Straight Section Twiss Parameter
Matching

3.1 Introduction

The periodic betas in the arcs are different from the periodic betas in the straight sections. After
suppressing the dispersion to zero, four quadrupoles after the dispersion suppressor are needed
to match αa , αb , βa , and βb to the periodic betas in the following straight section.

Beta Function [model]

30 β
A
β
B

20
β , β [m]
B
A

10

0
0 10 20 30 s [m] 40 50 60 70
Dispersion suppressor Matching to SS line

Arc FODO Straight

cells section FODO
QDF1

QDF2

QDF3
QFF1

QFF2

QFF3
QD
QF

Figure 6: Dispersion suppressor match section.

3.2 Example: Forward Matching Section Creation

The procedure for creating the forward matching section is shown below. Matching the re-
verse matching section is left as an exercise. The example files can be found in the /lat-
tices/3_MatchToSS/F/ directory.
To create the forward matching section:

1. Create a copy of the dispsupF.bmad file, which contains the optimized dispersion suppressor.
2. In this new copy, add the straight section drift DB, which was defined previously in Exercises
2 and 3 of section 1.3.
! ( 2 ) : Add s t r a i g h t s e c t i o n (SS) d r i f t DB
DB: D r i f t , L = 5.855

Collider Ring Design Tutorial using Bmad 23

 3. Define four quads for matching to the straight section. Because this is the forward matching
section (F), and these are the 2nd and 3rd special QF and QDs, use the names QFF2, QDF2,
QFF3, and QDF3.
! ( 3 ) : D e f i n e quads f o r matching t o SS ( two per plane ,
! use SS s t r e n g t h s as s t a r t i n g p o i n t )
QFF2 : Quadrupole , L = 0 . 5 , K1 = 0.351957452649287
QDF2 : Quadrupole , L = 0 . 5 , K1 = −0.351957452649287
QFF3 : Quadrupole , L = 0 . 5 , K1 = 0.351957452649287
QDF3 : Quadrupole , L = 0 . 5 , K1 = −0.351957452649287

4. Define the matching to the straight section (SS) line in Fig. 6 containing the matching quads.
Because this is the forward matching to SS, Use the name MSSF.
! ( 4 ) : D e f i n e t h e matching t o SS l i n e (MSSF)
MSSF: l i n e = ( QFF2 , D1 , DB, D2 , QDF2, D1 , DB, D2 ,
QFF3 , D1 , DB, D2 , QDF3, D1 , DB, D2 )

“F” stands for 5. Use the name ARC_TO_SSF as the line containing the combined dispersion suppression
Forward. and matching to SS line:
! ( 5 ) : D e f i n e t h e d i s p e r s i o n s u p p r e s s i o n and
! matching t o SS l i n e (ARC_TO_SSF)
ARC_TO_SSF : l i n e = ( DISPSUPF , MSSF)

use , ARC_TO_SSF

The completed initial lattice file containing these changes is provided in the example files,
named mSSF0.bmad.

6. The last four quads need to be optimized so that at the end of the ARC_TO_SSF line the
betas are equal to the periodic betas in the straight section FODO cells. Four datums, one
for each of αa , αb , βa , and βb at the end of the line, need to be defined in the tao.init file.
The “measure” (target) values of these datums can be found from the solution lattice fo-
doSSF.bmad obtained in Exercise 2 of Section 1.3. The variables will be the quadrupole
strengths of QFF2, QDF2, QFF3, and QDF3. The completed tao.init file is provided in the
example files.
7. Run the optimizer in Tao a couple times until the merit is extremely small. The merit will be of
order 10−28 . The data should look like:
Tao> show data betas
Data name : betas . 1
| Useit
... Ele Meas Model Design | Opt P l o t
1 beta . a < t a r g e t > . . . END 2.7205E+01 2.7205E+01 3.0610E+01 T F
2 alpha . a < t a r g e t > . . . END −2.4024E+00 −2.4024E+00 −2.4011E+00 T F
3 beta . b < t a r g e t > . . . END 4.9609E+00 4.9609E+00 5.5667E+00 T F
4 alpha . b < t a r g e t > . . . END 4.8460E−01 4.8460E−01 4.7804E−01 T F

You can also verify the Twiss parameters are indeed what you need them to be at the END
element using command show element END.

Collider Ring Design Tutorial using Bmad 24

 Tao> show e l e END
Element # 33
Element Name : END
......
Twiss a t end o f element :
A B
Beta (m) 27.20598820 4.96091411 ...
Alpha −2.40249037 0.48460556 ...
Gamma ( 1 /m) 0.24891432 0.24891432 ...
......

8. Save the optimized quadrupoles strength by writing a new lattice file mSSF.bmad. This will
be the matching section in the forward sextants.

3.3 Exercises
1. Reversed matching section: Construct the reverse matching section, following the same
steps as shown in the example but for the reverse cells. How do your quad values compare
to those obtained in class for the forward matching cells? Let the optimized lattice file name
be mSSR.bmad.

2. Merit Weight: Optimization success or failure can depend heavily on the relative weights
used for the data and the variables. As an example of this, start again with the unoptimized
lattice and this time set the weight for the datum beta[1] to 1E10. This can be done in the
lattice file or on the Tao command line with:
s e t data betas [ 1 ] | w e i g h t = 1e10

With this, how well does the optimization do?

Collider Ring Design Tutorial using Bmad 25

4 Machine Coordinates

4.1 Coordinate Systems

As explained in the Coordinates chapter of the Bmad manual, bmad uses three coordinate sys-
tems to describe the positioning of lattice elements as shown in Figure 7:

Global Coordinates
The (X, Y, Z) global (also called floor) coordinate system (notice that capital letters are
used for the coordinate axes) is independent of the accelerator machine and is "attached"
to the building the accelerator is in. Typically, the Y-axis is taken to be pointing vertically up
and (X, Z) defines the horizontal plane.
Local Coordinates
The global coordinate system is not convenient for describing where particles are as they
move through the lattice. For this, shown in red, there is the local (also called labora-
tory, also called reference) curvilinear coordinate system. Laboratory coordinates are also
used to describe the nominal (that is, without any “misalignments”) position of the lattice
elements. The laboratory coordinates start with a curved line often called the “reference
trajectory”. The distance along the reference trajectory is denoted by s. At each point
along the reference trajectory, there is a Cartesian (x, y, z) coordinate system with the ori-
gin at the reference trajectory point. The z-axis is always tangent to, and the x and y-axes
always transverse to the reference trajectory.
Element Body Coordinates
Elements can be shifted ("misaligned") from their nominal position. To describe things
like electric and magnetic fields or apertures (which can depend upon an element’s actual
position), element body coordinates are used. The element body coordinates are the
coordinates attached to the physical element. Without any "misalignments", the element
coordinates correspond to the laboratory coordinates.

z
x x

x Nominal element z
position

X Actu Element body

a s
posi l elemen z coordinates
tion t
Local coordinate system
Z a.k.a. The laboratory coords
a.k.a. The reference orbit
Global (”floor”) coordinates

Figure 7: The three coordinate systems used to describe lattice element positioning: Global,
reference, and element body coordinates.

Collider Ring Design Tutorial using Bmad 26

 A) Straight B) Bend C) Patch & Floor_Shift
y y
z y
z z
x x
x
Exit Exit
Exit

ance nce ce
Entr tra ran
En Ent
Figure 8: Lattice element geometry types: Straight, bend, and patch. All elements have an
entrance coordinate system and an exit coordinate system.

4.2 Element Geometry Types

All lattice elements have an “entrance” end and an “exit” end. Normally a particle will enter the
element at the entrance end and exit at the exit end but it is possible to simulate particles going
backwards or have lattice elements that are reversed longitudinally.
Lattice elements in Bmad have one of four geometry types. Three of them will be discussed here
and are shown in Figure 8. [The fourth geometry type, used for X-ray simulations, is used with
mirror, multilayer_mirror, and crystal elements.] These three types are called straight, bend
and patch based upon how the (x, y, z) laboratory coordinates transform as a function of the
longitudinal s position from the entrance end of the element to the exit end.

Straight Geometry
The straight geometry, shown in Figure 8A, is used with elements like drifts and quadrupoles.
Within any one given element, the orientation of the (x, y, z) coordinates is independent of
s and the reference trajectory is a straight line so that the z-axis at the exit end is co-linear
with the entrance z-axis.
Bend Geometry
The bend geometry shown in Figure 8B is used with sbend and rbend dipole elements.
With this geometry, the reference trajectory is a semi-circle. The (x, y, z) coordinates rotate
about an axis which is perpendicular to the z-axis. The default is to have the rotation axis
parallel to the y-axis which keeps the orientation of the y-axis independent of s.
Patch Geometry
The patch geometry shown in Figure 8C is used with patch and floor_shift elements. With
the patch geometry, the exit coordinates can be arbitrarily positioned with respect to the
entrance coordinates. See section §4.6. The reference trajectory within the patch region is
undefined since there is no good way to define it.

Collider Ring Design Tutorial using Bmad 27

 s
y
Down
strea
z m
x C
B
A
Upstream

Figure 9: The local coordinate system is constructed by taking the ordered list of lattice elements
and connecting the exit frame of one element to the entrance frame of the next.

4.3 Local Coordinate System Construction

The local coordinate system is constructed by taking the ordered list of lattice elements and
connecting the (x, y, z) exit frame of one element to the (x, y, z) entrance frame of the next (just
like LEGO blocks). Given a line constructed as:
l a t : l i n e = ( A , B , C)

The result could look as shown in Figure 9. The reference trajectory is shown in red.

Collider Ring Design Tutorial using Bmad 28

 Y
y

z s
x Reference
Orbit
X

ψ Projection of the
z-axis on the X-Z plane

φ Global Frame Z

Figure 10: The global coordinate system.

4.4 Laboratory Coordinates Relative to Global Coordinates

For any given s-position on the reference orbit, the local coordinate system is described with
respect to the global coordinate system by 6 parameters as shown in Figure 10:

• (X, Y, Z) global position

• θ azimuth angle in the (X, Z) plane.

• ϕ elevation angle
• ψ roll angle.

Notes:

• The default is for the beginning of the lattice (s = 0) is to have the local (x, y, z) coordinate
system aligned with the global (X, Y, Z) coordinate system with θ, ϕ and ψ all being zero.

• For a machine that lies in the horizontal plane, the ϕ(s) and ψ(s) angles are zero for all s.

Collider Ring Design Tutorial using Bmad 29

 x
x_pitch y
tilt

x_offset
x
z

(a) Effect of x_offset and x_pitch on a straight line element (b) Effect of a tilt on a straight line
element.

Figure 11

4.5 Element Misalignments

Once the reference coordinate system is established, the position of any physical element can
be shifted (“misaligned”). [Note: Patch and floor_shift elements cannot be misaligned.] For
straight elements, the element attributes that determine any misalignment are:

x_offset, y_offset, z_offset

The x_offset, y_offset, and z_offset attributes offset the element in the x, y, and z direc-
tions respectively. See Figure 11a.

x_pitch, y_pitch
The x_pitch and y_pitch attributes rotate the element. A x_pitch of π/2 would rotate
the element around the +y-axis so that the body +z-axis is aligned with the local +x-axis.
Similarly, a y_pitch of π/2 would rotate the element around the -x-axis so that the body
+z-axis is aligned with the local +y-axis. See Figure 11a.

tilt
A tilt rotates the element around the +z-axis as shown in Figure 11b

Note: The above only applies to straight elements. Patch like elements are explained below. For
a discussion of misalignments for bend type elements see the Bmad manual.
! L a t t i c e F i l e : m i s a l i g n . bmad
b e g i n n i n g [ beta_a ] = 1 0 . ! m a−mode beta f u n c t i o n
b e g i n n i n g [ beta_b ] = 1 0 . ! m b−mode beta f u n c t i o n
b e g i n n i n g [ e _ t o t ] = 10e6 ! eV
parameter [ geometry ] = open ! o r c l o s e d
q : quadrupole , L = 1 , x _ o f f s e t = 0 . 1 , x _ p i t c h = 0.04
lat : line = (q) ! L i s t o f l a t t i c e elements
use , l a t ! L i n e used t o c o n s t r u c t t h e l a t t i c e

Collider Ring Design Tutorial using Bmad 30

 Start Tao with the lattice file misalign.bmad. The misalignment can be viewed using the -floor
option with the show element command:
Tao> show e l e q − f l o o r

Element # 1
Element Name : Q
. . . etc . . .

A t t r i b u t e v a l u e s [ Only non−zero / non− d e f a u l t v a l u e s shown ] :

1 L = 1.0000E+00 m
13 SPIN_FRINGE_ON = T ( 1 )
31 L_HARD_EDGE = 1.0000E+00 m
34 X_PITCH = 4.0000E−02 55 X_PITCH_TOT = 4.0000E−02
36 X_OFFSET = 1.0000E−01 m 57 X_OFFSET_TOT = 1.0000E−01 m
. . . etc . . .

G l o b a l F l o o r Coords a t End o f Element :

X Y Z Theta
Reference 0.00000 0.00000 1.00000 0.00000 . . . ! Without misalignments
Actual 0.11999 0.00000 0.99960 0.04000 . . . ! With m i s a l i g n m e n t s
. . . etc . . .

In the “Global Floor Coords” section, the Reference row shows the nominal position of the exit
end of the element without misalignments. [Due to space constraints the phi and psi columns
are not shown. They are zero in this case.] The Actual row shows the position of the physical
element at the exit end.
Associated with each misalignment attribute there is a corresponding attribute with a “_tot” suf-
fix. The difference is that an attribute like x_offset is the misalignment with respect to any girder
that may be supporting it while the corresponding x_offset_tot is the total misalignment of the
lattice element with respect to the element’s nominal position. Another difference is that mis-
alignments attributes are set by the user while the corresponding _tot attributes are calculated
by Bmad. If there is no girder support, the _tot attributes will be the same as the misalignment
attributes as it is in this case so x_pitch is equal to x_pitch_tot, etc.

4.6 Patch Elements

Patch elements are used to shift the reference orbit. As a consequence, the nominal placements
of all elements downstream of the patch are affected. This is useful in simulating things like
injection or extraction lines where the patch is used to reorient the reference orbit so that it
follows the injection or extraction line.
For patch elements the same six parameters that are used to misalign straight line elements
are, for a patch, used to set the placement of the exit frame relative to the entrance frame. The
transformation from entrance coordinates to exit coordinate is:

1. Initially the exit coordinates coincide with the entrance coordinates.

2. The origin of the exit coordinates is translated by (x_offset, y_offset, z_offset)

Collider Ring Design Tutorial using Bmad 31

 x z

Exit x_pitch
x

z
(x_offset, y_offset, z_offset)
Entrance

(b) Lattice with a patch element. The patch ele-

ment is the coordinates patch element in a lattice.
(a) The body coordinates at the exit end of a patch
[Note: The default is not to draw patch elements in
is set by the element attributes x_offset, y_offset,
a floor_plan plot.]
z_offset, x_pitch, y_pitch, and tilt.

Figure 12

3. The x_pitch and y_pitch rotations (in radians) are applied. The x_pitch rotation rotates
the +z axis towards the +x axis (rotation around the +y axis). The y_pitch rotation rotates
the +z axis towards the +y axis (rotation around the -x axis).
4. The tilt rotation (in radians) rotates the exit coordinates around the exit coordinate’s +z
axis.

This transformation is illustrated in Figure 12a. The transformation from patch entrance to exit
coordinates is the same transformation from laboratory coordinates at the center of a straight
element to the element body coordinates at the center of the misaligned element.

4.7 Example:
! L a t t i c e F i l e : patch . bmad
b e g i n n i n g [ beta_a ] = 1 0 . ! m a−mode beta f u n c t i o n
b e g i n n i n g [ beta_b ] = 1 0 . ! m b−mode beta f u n c t i o n
b e g i n n i n g [ e _ t o t ] = 10e6 ! eV
parameter [ geometry ] = open ! or closed

b : sbend , L = 0 . 5 , g = 1 ! g = 1 / bending_radius
p : patch , z _ o f f s e t = 1 , x _ p i t c h = p i / 4
q : quadrupole , L = 0 . 6 , k1 = 0.23

lat : line = (b, p, q) ! L i s t o f l a t t i c e elements

use , l a t ! L i n e used t o c o n s t r u c t t h e l a t t i c e

Collider Ring Design Tutorial using Bmad 32

 Start Tao with the lattice file patch.bmad. Create a floor_plan with the command place r11 floor.
The result is shown in Figure 12b except that, by default, Tao does not draw a patch element
so, in the figure, the patch has been drawn in by hand. The global coordinates of the nominal
positions of the elements can be seen by using the show lat -floor command:
Tao> show l a t − f l o o r

Values a t End o f Element :

Ix name key s X Y Z Theta ...
0 BEGINNING Beginning_Ele 0.000 0.0000 0.0000 0.0000 0.0000 ...
1 B Sbend 0.500 −0.1224 0.0000 0.4794 −0.5000 ...
2 P Patch 1.207 −0.6018 0.0000 1.3570 0.2854 ...
3 Q Quadrupole 1.807 −0.4329 0.0000 1.9327 0.2854 ...
4 END Marker 1.807 −0.4329 0.0000 1.9327 0.2854 ...

A patch represents a field free space so a particle traveling through a patch propagate as in
a drift. The difference is that in a patch there is a coordinate transformation from entrance
coordinates to exit coordinates.
4.8 Exercises:
1. Modify the lattice file simple.bmad to include a girder element supporting elements B and Q.
Misalign the girder and verify that a supported element will have _tot attributes different from
the misalignment attributes.
2. The show ele -floor command will show the global coordinates of both the nominal (non-
misaligned) position as well as the misaligned (actual) position of an element. For example
show e l e Q − f l o o r

On the Tao command line, misalign any element using the set ele command and observe what
the differences are between the nominal and misaligned positions. Can you predict what the
difference will be between the nominal and misaligned positions when you change the tilt of
Q?
3. Using lattice simple.bmad, calculate by hand the floor coordinates at the exit end of element
Q and compare this with the coordinates as calculated by Bmad.

Collider Ring Design Tutorial using Bmad 33

5 Constructing the Ring

5.1 Ring Construction

Figure 13: Mirror symmetry about the centers of each straight.

In the previous chapters, forward and reverse arc lines, forward and reverse straight section
lines, and forward and reverse lines to connect the arcs to the straight sections (with dispersion
suppression and matching the betas) were constructed. In this chapter, the entire ring is created
based on Fig. 13. All that’s left is a section to match the straight section to the arc, including
dispersion "creation" and betas matching, as shown in Fig. 14.
Does this mean a dispersion "creator" for both the forward and reverse sextants needs to be
created? Fortunately, no! Considering the mirror symmetry shown in Fig. 13, the quadrupole
settings for the forward sextant dispersion suppression and matching are equal to the quadrupole
settings for the reverse dispersion creation and matching. Likewise, the reverse dispersion sup-
pression and matching quadrupole settings are equal to the forward dispersion creation and
matching section quadrupoles. Therefore, no optimization is necessary here. All that is needed
is to connect the lines together.

Collider Ring Design Tutorial using Bmad 34

 0 100 200 300 400 500

0 0

4 Straight Dispersion
FoDo cells “creator”
20 Arc FoDo cells
Match to
-100 -100
dispersion
“generator”
X

-200 -200
Dispersion suppressor

Match to straight section

4 Straight FoDo cells

-300 -300
0 100 200 Z 300 400 500

Figure 14: A sextant of the ring.

5.2 Example: Forward Straight Section to Arc

As an example, the forward line to connect the straight section to the arc, SS_TO_ARCF, will
be constructed. The example lattice file can be found in /lattices/5_Ring/. Construction of
SS_TO_ARCR and the entire ring will be left as an exercise.
Following Fig. 14, both the matching to dispersion creator line (which we’ll call MDCF), and
the dispersion creator line itself (which we’ll call DISPCREF) need to be construted. Using
the mirror symmetry as shown in Fig. 13, it is seen that SS_TO_ARCF will use the same
quadrupole settings as in ARC_TO_SSR. Keeping with our convention of starting each line
with a full horizontally-focusing quadrupole, this is
! Match f o r w a r d s t r a i g h t s e c t i o n t o d i s p e r s i o n " c r e a t o r " ( use QFR)
MDCF: l i n e = (QFSS, D1 , DB, D2 , QDR3, D1 , DB, D2 ,
QFR3, D1 , DB, D2 , QDR2, D1 , DB, D2 )

! Forward d i s p e r s i o n " c r e a t o r " ( use QFR)

DISPCREF : l i n e = (QFR2, D1 , BH, D2 , QDR1, D1 , BH, D2 ,
QFR1, D1 , BH, D2 , QD, D1 , BH, D2 )

SS_TO_ARCF : l i n e = (MDCF, DISPCREF )

After matching the straight sections to the arc, it is now time to contruct the full ring.

Collider Ring Design Tutorial using Bmad 35

5.3 Exercises
1. Construct the reverse straight section to arc lines: Construct SS_TO_ARCR using the
example shown above and Figs. 13 and 14.
2. Construct the ring

2.1. Gather all elements from each optimized file

2.2. Gather the arc and SS FODO cells
! ( 2 ) : Gather a r c and SS FoDo c e l l s

! S t r a i g h t s e c t i o n f o r w a r d FoDo :
FODOSSF: l i n e = ( QFSS, D1 , DB, D2 , QDSS, D1 , DB, D2 )

! Arc f o r w a r d FoDo :
FODOAF: l i n e = (QF, D1 , B , D2 , QD, D1 , B , D2 )

! Arc r e v e r s e FoDo :
FODOAR: l i n e = (QF, D2 , B , D1 , QD, D2 , B , D1 )

! S t r a i g h t s e c t i o n r e v e r s e FoDo :
FODOSSR: l i n e = ( QFSS, D2 , DB, D1 , QDSS, D2 , DB, D1 )

2.3. Gather dispersion suppression and matching to SS lines (ARC_TO_SSF, ARC_TO_-

SSR)
! ( 3 ) : Gather d i s p e r s i o n s u p p r e s s i o n
! and matching t o SS l i n e s (ARC_TO_SSF, ARC_TO_SSR)

! Forward d i s p e r s i o n suppressor :
DISPSUPF : l i n e = (QF, D1 , BH, D2 , QD, D1 , BH, D2 ,
QFF1 , D1 , BH, D2 , QDF1, D1 , BH, D2 )

! Match f o r w a r d d i s p e r s i o n suppressor t o SS :
MSSF: l i n e = ( QFF2 , D1 , DB, D2 , QDF2, D1 , DB, D2 ,
QFF3 , D1 , DB, D2 , QDF3, D1 , DB, D2 )

ARC_TO_SSF : l i n e = ( DISPSUPF , MSSF)

! Reverse d i s p e r s i o n suppressor :
DISPSUPR : l i n e = ( QF, D2 , BH, D1 , QD, D2 , BH, D1 ,
QFR1, D2 , BH, D1 , QDR1, D2 , BH, D1 )

! Match r e v e r s e d i s p e r s i o n suppressor t o SS :
MSSR: l i n e = ( QFR2, D2 , DB, D1 , QDR2, D2 , DB, D1 ,
QFR3, D2 , DB, D1 , QDR3, D2 , DB, D1 )

ARC_TO_SSR : l i n e = ( DISPSUPR, MSSR)

2.4. Gather matching to dispersion creation and dispersion creation lines (SS_TO_ARCF,
SS_TO_ARCR) from the Example and first exercise in this section
2.5. Build the ring!

Collider Ring Design Tutorial using Bmad 36

 ! ( 5 ) : Build the r i n g !

SEXTANT1 : line = ( 4 * FODOSSF, SS_TO_ARCF, 20 *FODOAF, ARC_TO_SSF, 4 *FODOSSF)

SEXTANT3 : line = ( 4 * FODOSSR, SS_TO_ARCR, 20 *FODOAR, ARC_TO_SSR, 4 *FODOSSR)
SEXTANT5 : line = ( 4 * FODOSSF, SS_TO_ARCF, 20 *FODOAF, ARC_TO_SSF, 4 *FODOSSF)
SEXTANT7 : line = ( 4 * FODOSSR, SS_TO_ARCR, 20 *FODOAR, ARC_TO_SSR, 4 *FODOSSR)
SEXTANT9 : line = ( 4 * FODOSSF, SS_TO_ARCF, 20 *FODOAF, ARC_TO_SSF, 4 *FODOSSF)
SEXTANT11 : line = ( 4 * FODOSSR, SS_TO_ARCR, 20 *FODOAR, ARC_TO_SSR, 4 *FODOSSR)

RING : l i n e = (SEXTANT1, SEXTANT3, SEXTANT5, SEXTANT7, SEXTANT9, SEXTANT11 )

use , RING

3. Check that the ring closes geometrically using either show element end -floor or show
element end -all. What is the circumference of the ring?

4. Use Tao’s place command to display a floor_plan drawing (Figs 13 and 14 are floor_plan
drawings). First, use place r11 floor_plan to place the floor template in the plot region (use
show plot to display the region). Then, try to adjust the drawing boundaries using scale, scale
all, and x_scale all commands.

Collider Ring Design Tutorial using Bmad 37

 6 Low-Beta Interaction Region Insertion

6.1 Introduction
For IR simulations In this chapter an Interaction Region (IR) with a low beta Interaction Point (IP) will be constructed
Bmad has a Beam-
Beam lattice element
by modifying the 6 o’clock straight section quadrupoles as shown in Figs. 15A and 15B.
for simulating the fully- The IR is divided into two parts which are constructed separately as shown in Fig. 16. IPF is
nonlinear weak-strong
beam-beam effect.
the upstream “forward” section before the IP (labeled IP6) and IPR is the downstream “reverse”
Bmad also has a section after IP6. At the IP, the betas are to be optimized to the values βa∗ = 0.6 and βb∗ = 0.06,
crab_cavity element and, as standard for many IPs, the alpha values αa∗ , and αb∗ will be optimized to zero. The
to simulate crabbing surrounding quadrupoles will be adjusted to match these IP parameters while still matching to
with a non-zero cross-
ing angle. Discussion the periodic solution at the ends of the sections furthest from the IP. Because this region is
of this is beyond the particularly sensitive, this match is achieved with the following steps:
scope of this tutorial.
1. Match the forward line from SS to IP
2. Match backwards the reverse line from SS to IP
3. Connect the two and match the full line to the periodic solution once more to ensure a perfect
match

A)
QDSS

QDSS

QDSS

QDSS

QDSS

QDSS

QDSS

QDSS
QFSS

QFSS

QFSS

QFSS

QFSS

QFSS
QFSS

QFSS
QDF3

B)

QDSS
QDSS

QER4
QER3

QER2

QER1

QFSS
QFSS
QDF3

QEF3
QEF4
QEF1

QEF2

IP6

Beta Function [model]

C) 600
β
A
β , β [m]

β
B
400
B
A

200

0
1840 1860 1880 1900 s [m] 1920 1940 1960 1980

Figure 15: A) Layout before modification. B) Layout with IR constructed. C) IR Beta functions.

Collider Ring Design Tutorial using Bmad 38

 3.76m
20.46m 5.8m

IPF:
QEF1

QEF3

QEF4
QEF2

DEF1

DEF2

DEF3

IP6
0.5m
5.3m 23.82m

IPR:

QER2

QER1
DER3

DER1
QER4
QER3
DER2
I P6

Figure 16: Interaction region dimensions. Red circles mark drifts with non-standard lengths. IPF:
Forward section before the IP. IPR: Reverse section after the IP.

6.2 Example: Constructing the Upstream and Downstream IR Lines

The example lattice file can be found in /lattices/6_IP/a_IP0/.

Construct the upstream and downstream IR lines, shown on the top and bottom of Fig. 16 respec-
tively, and leave the upstream, downstream, and full IR matching described in the introduction
as exercises.
To construct the IR lines:

1. Start with fodoSSF.bmad, the optimized forward straight-section lattice file

2. Set geometry to open
parameter [ geometry ] = open ! ( 2 ) : Set geometry t o open

3. Define forward (upstream) interaction region drifts and quads (strengths TBD, start with SS
quadrupole strengths)
! ( 3 ) : D e f i n e f o r w a r d ( upstream ) i n t e r a c t i o n r e g i o n d r i f t s and
! quads ( s t r e n g t h s TBD, s t a r t w i t h SS)
QEF1 : Quadrupole , L = 0 . 5 , K1 = 0.351957452649287
QEF2 : Quadrupole , L = 0 . 5 , K1 = −0.351957452649287
DEF1 : D r i f t , L = 20.46
QEF3 : Quadrupole , L = 1 . 6 , K1 = 0.351957452649287
DEF2 : D r i f t , L = 3.76
QEF4 : Quadrupole , L = 1 . 2 , K1 = −0.351957452649287
DEF3 : D r i f t , L = 5 . 8

4. Define the interaction point element. Use a Marker element for this. Markers have zero length
and have no impact on the orbit or spin transport.
! ( 4 ) : D e f i n e IP
IP6 : marker

Collider Ring Design Tutorial using Bmad 39

 5. Define reverse (downstream) interaction region drifts and quads (strengths TBD, start with SS
quadrupole strengths)
! ( 5 ) : D e f i n e r e v e r s e ( downstream ) i n t e r a c t i o n r e g i o n d r i f t s and
! quads ( s t r e n g t h s TBD, s t a r t w i t h SS)
DER3 : D r i f t , L = 5 . 3
QER4: Quadrupole , L = 1 . 8 , K1= −0.351957452649287
DER2 : D r i f t , L = 0 . 5
QER3: Quadrupole , L = 1 . 4 , K1=0.351957452649287
DER1 : D r i f t , L = 23.82
QER2: Quadrupole , L = 0 . 5 , K1 = 0.351957452649287
QER1: Quadrupole , L = 0 . 5 , K1 = −0.351957452649287

6. Define the upstream and downstream lines

! ( 6 ) : D e f i n e t h e upstream and downstream l i n e s
IPF : l i n e = ( QEF1, D1 , DB, D2 , QEF2, D1 , DB,
D2 , DEF1 , QEF3, DEF2 , QEF4, DEF3 , IP6 )
IPR : l i n e = ( IP6 , DER3, QER4, DER2, QER3, DER1,
QER2, D2 , DB, D1 , QER1, D2 , DB, D1 )

After defining the two IP lines, the exercises will focus on region matching and optimization of
our updated ring.

6.3 Exercises
1. Forward (upstream) interaction region matching: Using the IPF line defined above, vary
QEF1, QEF2, QEF3, and QEF4 so that at IP6 βa = 0.6, βb = 0.06, αa = αb = 0. After
optimizing, instead of write-ing the lattice, make a copy of the var1.out file and rename it to
something like IPF.out. This output file is a Bmad lattice file that sets the quadrupoles to their
correct strengths.
2. Reverse (downstream) interaction region matching: Match backwards the downstream
interaction region line IPR defined above, starting from the end of the line and ending at
the interaction point, varying QER1, QER2, QER3, and QER4 that βa = 0.6, βb = 0.06,
αa = αb = 0 at IP6. Once again, save a copy of the final var1.out file containing the optimized
quadrupole strengths and rename it to something like IPR.out. Hint: the line can be reflected
using a negative sign:
I P R _ r e f l e c t e d : l i n e = ( − IPR )

3. Call command: The optimized quadrupole settings in the .out files obtained above can be
called directly in the lattice file using the call command at the end of the lattice file. Bmad will
read in the entire lattice file, and then set the quadrupole strengths accordingly. E.g., at the
end of the lattice file:
! D e f i n e and use IP l i n e
IP : l i n e = ( IPF , IPR )
use , IP

Collider Ring Design Tutorial using Bmad 40

 ! C a l l t h e quadrupole s e t t i n g s i n IPF . o u t and IPR . o u t
c a l l , f i l e = " IPF . o u t "
c a l l , f i l e = " IPR . o u t "

This should give a very good match, however to ensure a perfect solution, the full line to the
periodic solution is matched once more. Using the full IR line ((IPF, IPR)) now, vary the
downstream quadrupoles QER1, QER2, QER3, and QER4 to match perfectly to the periodic
betas in the straight section at the end of the line. Now you can use write bmad IP.bmad with
the fully optimized IR quadrupole settings
4. Add the IR into the ring: Copy the optimized lattice elements from IP.bmad into the ring
lattice file, copy the IPF and IPR lines into the ring lattice file, and finally add the IP into the
ring by modifying SEXTANT5 and SEXTANT7:
SEXTANT5 : l i n e = ( 4 * FODOSSF, SS_TO_ARCF, 20 *FODOAF, ARC_TO_SSF, FODOSSF, IPF )
SEXTANT7 : l i n e = ( IPR , FODOSSR, SS_TO_ARCR, 20 *FODOAR, ARC_TO_SSR, 4 *FODOSSR)

5. Alpha and Beta Functions: How should you change the initial betas and alphas for a proper
match using the reflected line? Hint: the betas and alphas are the same as calculated in
earlier chapters.
6. Importance of variable step size: In Exercise 1, you optimized the match the IP Twiss using
a step size for varying the quadrupole k1 values of 10−6 . How is this step size used with
the Levenberg-Marquardt optimization? Verify that if, instead, a step size of 10−4 is used the
optimization does not converge to a usable solution. Why is this?

Collider Ring Design Tutorial using Bmad 41

7 Tune Cell

7.1 Introduction

In order to adjust the tune of the ring, the phase advance per FODO cell in one of the straight
sections can be adjusted, while ensuring it is still matching to the periodic solution in each of
the surrounding arcs. We’ll put this “tune cell” in the 2 o’clock straight section, and modify the
lines/lattice elements by simply appending a _2 to the names.
Required for the optimization is:

1. Setting the phase advances in the FODOSSF/FODOSSR straight section for desired tunes
Qx = 54.08 and Qy = 54.14 (2 constraints)

2. Matching from the dispersion suppressor to the new periodic betas and alphas in the center
FODOSSF/FODOSSR section (4 constraints)
3. Matching the center FODOSSF/FODOSSR section to the dispersion creator (would be 4 con-
straints but these are defined already by the mirror symmetry)

These 6 constraints can be satisfied using the four quadrupoles in the forward matching to SS
(QFF2_2, QDF2_2, QFF3_2, and QDF3_2), and the two quadrupoles in the straight section
(QFSS_2 and QDSS_2).

DISPSUPF_2 MSSF_2 4 FODOSSF_2 4 FODOSSR_2 MSSR_2 DISPCRER_2

QDSS_2

QDSS_2

QDSS_2

QDSS_2

QDSS_2

QDSS_2

QDSS_2

QDSS_2
QFSS_2

QFSS_2

QFSS_2

QFSS_2

QFSS_2

QFSS_2

QFSS_2

QFSS_2
QD F 2_2

QD F 3_2
QF SS_2

QDF3_2

QDF2_2

QDF1_2
QF F 2_2

QF F 3_2

QFF3_2

QFF2_2

QFF1_2
QDF1
QFF1
QD

QD
QF

QF
{
2 knobs
4 knobs 4 knobs defined by
mirror symmetry

Figure 17: Enter Caption

7.2 Example: tao.init for the Tune Cell

The example file can be found at /lattices/7_TuneCell/tao.init.

To define datums that constrain the solution to have periodic betas in the straight section, ex-
pression datums are used. Expressions are an extremely powerful tool that allows for complex
lattice optimizations and matching techniques.

Collider Ring Design Tutorial using Bmad 42

 In this case, required is that the betas at one focusing quadrupole in the center FODO cells are
equal to the betas at the next focusing quadrupole. Equivalently, required is that the difference
of those two are equal to zero. The appropriate datums are
! Require p e r i o d i c betas i n c e n t e r FoDo c e l l s o f 2 o ’ c l o c k tune c e l l
datum ( 1 ) = ’ e x p r e s s i o n : l a t : : beta . a [ QFSS_2##4] − l a t : : beta . a [ QFSS_2# # 5 ] ’
’ ’ ’ 0 ’ ’ end ’ ’ t a r g e t ’ 0 10
datum ( 2 ) = ’ e x p r e s s i o n : l a t : : beta . b [ QFSS_2##4] − l a t : : beta . b [ QFSS_2# # 5 ] ’
’ ’ ’ 0 ’ ’ end ’ ’ t a r g e t ’ 0 10
datum ( 3 ) = ’ e x p r e s s i o n : l a t : : alpha . a [ QFSS_2##4] − l a t : : alpha . a [ QFSS_2# # 5 ] ’
’ ’ ’ 0 ’ ’ end ’ ’ t a r g e t ’ 0 10
datum ( 4 ) = ’ e x p r e s s i o n : l a t : : alpha . b [ QFSS_2##4] − l a t : : alpha . b [ QFSS_2# # 5 ] ’
’ ’ ’ 0 ’ ’ end ’ ’ t a r g e t ’ 0 10

The syntax lat::beta.a[QFSS_2##4] evaluates to the value of the a-mode beta function at the
fourth lattice element named QFSS_2. The above datums have a measured (target) value of
zero so that the contribution to the merit function will be zero when the differences of the betas
at the fourth QFSS_2 and at the fifth QFSS_2 are zero. Thais in, when they are equal. This
ensures periodicity in the optics in the straight section.
Besides the above datums, other datums are need to make sure that the outgoing Twiss from
the modified straight section correctly match the Twiss at the start of the dispersion creator
DISPCRER_2 (see Fig. 17. The needed datums are:
! Match betas t o d i s p e r s i o n c r e a t o r a f t e r tune c e l l
datum ( 5 ) = ’ beta . a ’ ’ ’ ’ ’ ’ QFF2_2##2 ’ ’ t a r g e t ’ 30.6104309489717465 10
datum ( 6 ) = ’ beta . b ’ ’ ’ ’ ’ ’ QFF2_2##2 ’ ’ t a r g e t ’ 5.56679467017438689 10
datum ( 7 ) = ’ alpha . a ’ ’ ’ ’ ’ ’ QFF2_2##2 ’ ’ t a r g e t ’ 2.40115683012980607 100
datum ( 8 ) = ’ alpha . b ’ ’ ’ ’ ’ ’ QFF2_2##2 ’ ’ t a r g e t ’ −.47804044385806721 100

Finally, datums are needed to set the optimized tune to the desired values:
! Set phase advance t o n e a r e s t d e s i r e d f r a c t i o n a l tunes ( 5 4 . 0 8 , 5 4 . 1 4 )
datum ( 9 ) = ’ phase . a ’ ’ ’ ’ ’ ’ end ’ ’ t a r g e t ’ 339.79466141227203 10
datum ( 1 0 ) = ’ phase . b ’ ’ ’ ’ ’ ’ end ’ ’ t a r g e t ’ 340.17165253070283 10

7.3 Exercises
1. Implement the tune cell: Add the new special quadrupoles shown in Fig. 17, and optimize
them using the tao.init file created in the example so the lattice has the correct tunes Qx =
54.08 and Qy = 54.14.

Collider Ring Design Tutorial using Bmad 43

8 Particle Phase Space Coordinates

8.1 Phase Space

Figure 18a shows the reference orbit (laboratory coordinate system) which was discussed in
chapter 4. The reference coordinates (x, y, z) associated with a given point a distance s along
the reference point has the coordinate origin at the given point and the z-axis tangent to the
reference orbit.
A particle being simulated has its own trajectory as shown in the figure. Given a particle at some
point on its trajectory (blue dot in Figure 18a), there is a point at position s on the reference orbit
such that the z coordinate of the particle is zero in the (x, y, z) coordinate frame associated with
the reference orbit point.
With this, the particle’s position and momentum P can be described using the coordinates:
( x ( s ) , y ( s ) , Px ( s ) , Py ( s ) , Pz ( s ) , t ( s ) )

where t(s) is the time that the particle is at the given point. From now on, to simplify the notation,
the s dependence will be dropped.
For tracking purposes, canonical phase space coordinates are used with the convention that
upper case P denotes (unnormalized) momentum (Figure 18b) and lower case p denotes phase
space momentum. The phase space coordinates are denoted
( x , px , y , py , z , pz )

where
px = Px / P0
py = Py / P0
pz = (P − P0 ) / P0

Actual
Orbit
p
p
s y
Reference y px
y Orbit
Particle
z

x
|g| = 1/ρ

Reference
Reference
Particle Trajectory
Center of

s=0
Curvature
s

(a) Particle coordinate positions are relative to the (b) Particle phase space.
reference orbit.

Figure 18

Collider Ring Design Tutorial using Bmad 44

 B Q B Q
(a) Initial orbit. (b) Orbit after adjusting the starting px phase space
coordinate.

Figure 19

z = c * β * ( t_ref − t )

with
• P0 is the reference momentum. See section §9.1.
• c * β is the velocity of the particle,
• t_ref(s) is the time the reference particle reaches the point s. The reference particle is a
fictitious particle that can be imagined to be traveling on the reference orbit. Frequently,
this reference particle is thought of as describing the center of a bunch of particles.

Notes:
• Do not confuse the canonical z coordinate with the z coordinate of the particle in the (x, y, z)
coordinate frame. By construction, the latter is always zero.
• For a bunch of particles at a given s position, in general, the particles will have differing
time t.
• If the reference particle has the same β value as a particle, canonical z will be the longitu-
dinal distance the particle is with respect to the reference particle. Positive z indicates that
the particle is in front of the reference particle and vice versa.

8.2 Example

Example lattice:
! L a t t i c e F i l e : o r b i t . bmad
b e g i n n i n g [ beta_a ] = 1 0 . ! m a−mode beta f u n c t i o n
b e g i n n i n g [ beta_b ] = 1 0 . ! m b−mode beta f u n c t i o n
b e g i n n i n g [ e _ t o t ] = 10e6 ! eV
parameter [ geometry ] = open ! or closed

Collider Ring Design Tutorial using Bmad 45

 bmad_com [ s p i n _ t r a c k i n g _ o n ] = T

particle_start [ y ] = 0.01
particle_start [ px ] = 0.06
particle_start [ pz ] = −0.2
particle_start [ spin_x ] = 1

b : sbend , L = 0 . 5 , g = 1 ! g = 1 / bending_radius
q : quadrupole , L = 0 . 6 , k1 = 10

lat : line = (b, q) ! L i s t o f l a t t i c e elements

use , l a t ! L i n e used t o c o n s t r u c t t h e l a t t i c e

Start Tao with the lattice file orbit.bmad. Spin tracking is on (bmad_com[spin_tracking_on] set
to True) and a non-zero initial orbit is set using particle_start parameters. The resulting orbit is
shown in Figure 19a.
The initial phase space coordinates can now be varied using the change or set commands. For
example:
Tao> change p a r t i c l e _ s t a r t px 0.04
Old New Old −Design New−Design Delta
0.060000 0.100000 0.000000 0.040000 0.040000

The result is shown in Figure 19b.

View Orbits with show lattice command
Tao> show l a t − s p i n − o r b i t
Values a t End o f Element :
Index name key ... orbit ... spin
... x ... x
0 BEGINNING Beginning_Ele . . . 0.000000E+00 ... 0.000000E+00
1 B Sbend ... 5.027722E−03 . . . −1.414516E−01
2 Q Quadrupole ... −1.599068E−02 . . . −7.350543E−02
3 END Marker ... −1.599068E−02 . . . −7.350543E−02

or the show element command

Tao> show e l e 1
Element # 1
Element Name : B
. . . etc . . .

Orbit : Positron State : Alive

P o s i t i o n [mm] Momentum [ mrad ] Spin |
X: 5.02772161 −44.34051580 −0.14145163 | P a r t i c l e [ sec ] : ...
Y: 9.52710654 −1.27804602 −0.00171549 | Part −Ref [ sec ] : ...
Z: −4.78648430 −200.00000000 0.98994368 | ( Ref − P a r t ) * Vel [m] : ...

8.3 Exercises:
1. Phase Space: Construct a lattice with a single drift of 2 meters length. Set the particle
species to be protons with a reference energy of 101 2 eV (so the approximation that the

Collider Ring Design Tutorial using Bmad 46

 particle velocity is speed of light can be made), and Set the initial particle position to have
px = 0.2, pz = 1 with all other coordinates zero. Calculate from first principles what the phase
space coordinates will be at the end of the lattice and check that your answer agrees with
Bmad.

Collider Ring Design Tutorial using Bmad 47

9 RF Cavities

9.1 Reference Energy and the Lcavity and RFcavity Elements

Reference Energy
Every lattice element has a reference particle, a reference energy called E_tot, and a reference
momentum named p0c (in eV). The three are interrelated so knowing the reference particle
and either the reference momentum or energy, the third quantity can be calculated. The refer-
ence momentum is used for normalization of the phase space momentum as well as normalized
strength parameters.
For example, for a quadrupole element, the b1_gradient parameter (units: Tesla/m) can be used
to specify the linear field gradient and the k1 parameter (units: 1/m2 ) is the normalized field gra-
dient normalized using the value of the reference momentum as discussed in the “Magnetostatic
Multipole Fields” section of the “Electromagnetic Fields” chapter of the Bmad manual.
Lcavity
Lcavity elements are exceptions for lattices with an open geometry, where the reference energy/-
momentum at the beginning of the lattice is what is set in the lattice file. Usually, the reference
energy/momentum for a downsteam element inherits the reference energy/momentum of the
element just upstream.
Lcavity elements represent an RF cavity where the reference energy/momentum at the exit end
of the lcavity is set so that a particle entering the cavity with zero phase space coordinates leaves
with zero phase space coordinates. In particular, its phase space pz will be zero at the exit end.
Lcavity elements also have p0c_start and E_tot_start parameters that are set to the reference
energy of the upstream element.
Rfcavity
Rfcavity elements also represent an RF cavity, but their reference energy/momentum is the same
as the upstream element.

9.2 Example: Cavity Element

! L a t t i c e F i l e : c a v i t y . bmad
b e g i n n i n g [ beta_a ] = 1 0 . ! m a−mode beta f u n c t i o n
b e g i n n i n g [ beta_b ] = 1 0 . ! m b−mode beta f u n c t i o n
b e g i n n i n g [ p0c ] = 1e8 ! eV

parameter [ geometry ] = open ! or closed

parameter [ p a r t i c l e ] = He+

q1 : quad , l = 0 . 1 , k1 = 0.14
q2 : quad , l = 0 . 1 , b 1 _ g r a d i e n t = parameter [ p0c ] * q1 [ k1 ] / c _ l i g h t
lc : lcavity , l = 1 , v o l t a g e = 10e8 , r f _ f r e q u e n c y = 1e9
rf : rfcavity , l = 1 , v o l t a g e = 10e8 , p h i 0 = 0.25

l a t : l i n e = ( q1 , q2 , l c , q1 , q2 , r f )
use , l a t

Collider Ring Design Tutorial using Bmad 48

 Notes:
• For a lcavity phi0 = 0 corresponds to peak acceleration.

• For an rfcavity phi0 = 0.25 corresponds to peak acceleration.

Start Tao as explained in with the lattice file cavity.bmad. Examining the lcavity element shows:
> t a o − l a t c a v i t y . bmad

Tao> show e l e 3
Element # 3
Element Name : LC
Key : L c a v i t y
. . . etc . . .
51 P0C_START = 1.000000E+08 eV BETA_START = 0.02681151
52 E_TOT_START = 3.729740E+09 eV DELTA_E = 1.000000E+09 eV
53 P0C = 2.910237E+09 eV BETA = 0.61530588
54 E_TOT = 4.729740E+09 eV GAMMA = 1.268571E+00
. . . etc . . .
O r b i t : He+ State : Alive
P o s i t i o n [mm] Momentum [ mrad ] Spin |
X: 0.00000000 0.00000000 | P a r t i c l e [ sec ] : ...
Y: 0.00000000 0.00000000 | Part −Ref [ sec ] : ...
Z: −0.00000000 0.00000000 | ( Ref − P a r t ) * Vel [m] : ...

The reference energy at the start of the element, E_tot_start, is not the same as the reference
energy at the end of the element E_tot. The particle orbit, which started out with zero phase
space coordinates (there were no particle_start statements to give a non-zero starting orbit),
still has zero phase space coordinates at the end of the lcavity element.
Compare this to the rfcavity element:
Tao> show e l e 6
Element # 6
Element Name : RF
Key : R F c a v i t y
. . . etc . . .
53 P0C = 2.9102374E+09 eV BETA = 0.615305883
54 E_TOT = 4.7297409E+09 eV GAMMA = 1.2685712E+00
. . . etc . . .
O r b i t : He+ State : Alive
P o s i t i o n [mm] Momentum [ mrad ] Spin |
X: 0.00000000 0.00000000 | P a r t i c l e [ sec ] : ...
Y: 0.00000000 0.00000000 | Part −Ref [ sec ] : ...
Z: 140.37425587 494.97867675 | ( Ref − P a r t ) * Vel [m] : ...

Here there is no E_tot_start parameter since the ending reference energy is always equal to
the starting one. Here, the pz coordinate at the end of the element is nonzero.

9.3 Adding RF Cavities

The example files for this section can be found at /lattices/9_RF/AddingRF/

Collider Ring Design Tutorial using Bmad 49

 In a real machine, electrons emit synchrotron radiation as they bend around the ring, so we need
to replenish the energy with an RF system. Let’s put RF cavities in the 10 o’clock straight section
of our ring. We will design a special FODO cellwith RF cavities FODORF and replace 4 FODO
cells in the 10 o’clock straight section.
In the ESR, there are two RF cavities of length 4.017m between each quadrupole with equal drift
spaces between each element. We will follow these dimensions as shown in Fig. 20.

QDSS
Q FSS

RF0

RF0

RF0

RF0
Figure 20: FODO cell with RF cavities.

9.4 Example: Consturcting the FODO cell with RF cavities

1. Define RF cavities and drift elements. The appropriate drift length is calculated using an
expression.
RF0 : RFCavity , L = 4 . 0 1 7 , harmon = 7560 ,
v o l t a g e = 6 8 . 0 / 1 8 . 0 * 1e6 ! S t a r t w i t h ESR v o l t a g e
DRF: D r i f t , L = ( ( 1 . 2 4 1 + 5 . 8 5 5 + 0 . 6 0 9 ) − 2 * 4 . 0 1 7 ) / 3

2. Define the FODORF cell.

FODORF: l i n e = (QFSS, DRF, RF0 , DRF, RF0 , DRF, QDSS, DRF, RF0 , DRF, RF0 , DRF)

3. Replace 4 FODO cells in the 10 o’clock section with FODORF by modifying SEXTANT9 and
SEXTANT9:
SEXTANT9 : l i n e = ( 4 * FODOSSF, SS_TO_ARCF, 20 *FODOAF,
ARC_TO_SSF, 2 *FODOSSF, 2 *FODORF)
SEXTANT11 : l i n e = ( 2 * FODORF, 2 *FODOSSR, SS_TO_ARCR,
20 *FODOAR, ARC_TO_SSR, 4 *FODOSSR)

9.5 Exercises
1. Set the synchrotron tune: The synchrotron tune can be set by using the set z_tune com-
mand in Tao, which varies the RF cavity voltages. Set the synchrotron tune to 0.05 and write
down the new RF voltage. Add it to the end of the lattice file as
RF0 [ v o l t a g e ] = y o u r _ v o l t a g e

Collider Ring Design Tutorial using Bmad 50

 2. Modify the lcavity in the cavity.bmad to have a small length (so the transit time is small), and
set the beginning momentum small enough so the relativistic beta is significantly than one.
Starting the particle with a finite z, calculate the ending z after the cavity and verity that the
change in z is consistent with what Bmad calculates.
3. Lcavity elements have an attribute phi0_err which varies the RF phase that a particle sees
but does not change the reference energy. Add a finite phi0_err to the cavity element and
verify that the reference energy does not change but that the phase space pz of the particle
does change. With the cavity.bmad lattice, there is a range of values for phi0_err where the
cavity will decellerate the particle enough so that the particle will turn around and not make it
through the cavity. Approximately what is this range?

Collider Ring Design Tutorial using Bmad 51

10 Introduction to Long Term Tracking

Up to this point, only the Tao program in the Bmad ecosystem has been used and tracking has
implicitly been limited to tracking a single particle once through the lattice (which is needed for
computation of the Twiss functions and closed orbit §14.). Bmad also supports multi-particle
(beam) tracking and a Bmad based program, if appropriately configured, can track beams over
an arbitrary number of turns. Tao is equipped to do beam tracking but Tao is not designed for
tracking beams over many turns in a ring. Rather, the Bmad based program Long Term Tracking
is designed for this. The Long Term Tracking program can simulate such things as misalignments,
wake fields, higher order mode cavity resonances, spin polarization, energy ramping, etc. The
Long Term Tracking program is also capable of simulating beam injection into and extraction out
of a storage ring including tracking the beam through the transfer lines.

10.1 Initializing a Beam

Bmad has two ways to define an initial beam distribution. One is providing a file containing
individual particle positions. The other is using a beam_init_struct structure which holds pa-
rameters to initialize a beam. This is discused in detail in the Bmad manual.
Bmad accepts two file formats for beam initialization: ASCII and HDF5. HDF5 is a widely
used binary format which is useful when storing beams with a large number of particles. In
this tutorial The ASCII format is used. The ASCII beam format describes a single bunch using
a header section followed by a table section. Multiple bunches can be defined using multiple
header/table pairs. The header lines start with a “#” sign and contains global parameters and
custom parameters. Any line in the header that does not contain a valid parameter is ignored.
The last line in the header starts with “#!” and defines the table columns. The table section
follows the header section. Each row gives the parameters for one particle in the bunch.
Here is a simple beam initialization file beam.bmad. It defines 7 electrons with various z and pz
values.
# T h i s i s t h e header s e c t i o n
# You can d e f i n e parameters f o r a l l p a r t i c l e s i n t h e bunch
# species = e l e c t r o n
# charge = 1 . 6 e−19
# state = alive
# Or custom parameters n o t used by Bmad l i k e
# version = 1.0.0

#! x px y py z pz
0 0 0 0 0 0
0 0 0 0 0.1 0
0 0 0 0 0.15 0
0 0 0 0 0 −0.01
0 0 0 0 0 0.015
0 0 0 0 0 0.02
0 0 0 0 0 0.03

Collider Ring Design Tutorial using Bmad 52

 0.03
0.02
0.01
0.00
dp/p

0.01
0.02
0.03
0.4 0.2 0.0 0.2 0.4
z [m]
Figure 21: The trajectory of 7 particles in the z-pz plane over 30 turns.

10.2 Initializing long term tracking

Long Term Tracking takes an input file that defines parameters in a namelist, similar to how Tao
is initialized with a tao.init file. A full list of parameters and their descriptions can be found in the
Long Term Tracking manual. A simple long_term_tracking.init file:
&params
l t t %l a t _ f i l e = " r i n g . bmad "
l t t %simulation_mode = "BEAM"
l t t %t r a c k i n g _ m e t h o d = "BMAD"
l t t %n _ t u r n s = 30
l t t %p a r t i c l e _ o u t p u t _ e v e r y _ n _ t u r n s = 1
l t t %p h a s e _ s p a c e _ o u t p u t _ f i l e = " t u r n "

b e a m _ i n i t%c e n t e r = 0 , 0 , 0 , 0 , 0 , 0
b e a m _ i n i t%p o s i t i o n _ f i l e = " beam . bmad "
/

The long_term_tracking.init file specifies the lattice file name, tracking method, initial beam
positions, and program outputs. In this case, Long Term Tracking will track the initial beam for 30
turns and output the particle positions at the end of each turn.
You can run Long Term Tracking with this initialization file by the command long_term_tracking
<ini_file> where <ini_file> is the name of the master initialization file (as opposed to other in-
put files like the lattice file). If the ini_file is not specified, the default file name is long_term_tracking.init.

Collider Ring Design Tutorial using Bmad 53

 The output to the terminal will look like:
> long_term_tracking
I n i t i a l i z a t i o n f i l e : long_term_tracking . i n i t
n_particle : 7
Cumulative number dead a t end o f t u r n 6 : 1
Cumulative number dead a t end o f t u r n 1 9 : 2
Cumulative number dead a t end o f t u r n 2 4 : 3
# t r a c k i n g _ t i m e = 0.02552

10.3 Particle Track Output

The settings init the init file:

l t t %p h a s e _ s p a c e _ o u t p u t _ f i l e = " t u r n "
l t t %p a r t i c l e _ o u t p u t _ e v e r y _ n _ t u r n s = 1

results in files named turn## where ## is the turn number being generated every turn. In these
files, particle positions will be recorded with a similar format as the beam initialization file. The
files contain a header section with global parameters of the simulation and a table section. The
key of each column in the table section is given by the last line of the header section which starts
with "##". Each row gives the coordinates and state of one particle.
With some parsing of these files, particle trajectories can be visualized. Python and gnuplot
scripts are provided in the /lattices/10_LongTermTracking/ParticleTrack directory. Fig. 21
shows the results.

10.4 Averages Output

Besides particle output files, the Long Term Tracking program can generate several other types
of output. One useful type of output are the averages files. To illustrate these files, run the Long
Term Tracking program with the input files in the /lattices/10_LongTermTracking/AveragesOutput
directory. In this case, the master input file is named averages.init:
&params
l t t %l a t _ f i l e = " s i m p l e _ r i n g . bmad " ! Lattice f i l e

l t t %a v e r a g e s _ o u t p u t _ f i l e = " # . d a t "
l t t %a v e r a g e s _ o u t p u t _ e v e r y _ n _ t u r n s = 100

l t t %simulation_mode = "BEAM"
l t t %t r a c k i n g _ m e t h o d = "MAP" !
l t t %n _ t u r n s = 20000 ! Number o f t u r n s t o t r a c k
l t t %map_order = 3

bmad_com%s p i n _ t r a c k i n g _ o n = T ! See Bmad manual f o r bmad_com parameters .

bmad_com%r a d i a t i o n _ d a m p i n g _ o n = T
bmad_com%r a d i a t i o n _ f l u c t u a t i o n s _ o n = T

b e a m _ i n i t%n _ p a r t i c l e = 100
b e a m _ i n i t%s p i n = 1 , 1 , 0 ! See Bmad manual f o r b e a m _ i n i t _ s t r u c t parameters .

Collider Ring Design Tutorial using Bmad 54

 b e a m _ i n i t%a_emit = 1e−9
b e a m _ i n i t%b_emit = 1e−12
b e a m _ i n i t%s i g _ z = 1e−4
b e a m _ i n i t%s i g _ p z = 1e−4
/

The ltt%tracking_method is set to "MAP" which means that tracking is done using a one-turn
map. Using a map makes tracking fast but the construction of the map at the beginning can take
some time. In this case, a very simple lattice is used to speed up the process. If radiation effects
are turned on as they are here, the radiation effects are included in the map. The map is partially
inverted to make, in the limit of no radiation, the application of the map symplectic.
The setting of ltt%averages_output_file to "#.dat" means that the averages output files will
be produced. There are three averages output files which in this case will be named emit.dat,
ave.dat, and sigma.dat. Every 100 turns (set by ltt%averages_output_every_n_turns), a line
is written to each file recording varias averaged quantities like the beam sigma matrix, emittance,
spin polarization, etc.
In the init file, the beam is specified by the beam_init settings rather than an beam file and the
beam is started with transverse emittances that are smaller than the equilibrium ones. This is
illustrated by the the graph in Fig. 22, which shows the approach to equilibrium of the a-mode
emittance as a function of turn number. Since the averages files are structured to be easily
plotted using gnuplot, fig. 22 was drawn with the command
gnuplot > p l o t " emit . dat " using 1:4

7x10-8

6x10-8
a-mode emittance (m-rad)

5x10-8

4x10-8

3x10-8

2x10-8

1x10-8

0
0 5000 10000 Turn # 15000 20000

Figure 22: The a-mode emittance as a function of turn number.

Collider Ring Design Tutorial using Bmad 55

10.5 Exercises
1. Initial parameters: Experiment with different initial particle parameters and plot their trajec-
tories. How much can you change pz without losing the particle? Track particles and plot
their longitudinal phase space. Find stable and unstable fixed points, and invariant ellipses in
longitudinal phase space.
2. Core Emittance: In the emit.dat file there are columns for the “50% Core” emittance. What
is this? Hint: Consult the Long Term Tracking manual.

Collider Ring Design Tutorial using Bmad 56

11 Control Elements

11.1 Overview

Control elements are elements that control the parameters of other elements. There are four
types of control elements: groups, overlays, ramper and girders. Groups and overlays are con-
venient to do such things as simulate control room "knobs". For example a power supply that
powers a chain of magnets. Girder elements are used for simulating lattice element support
structures. For example, a bend element followed by a quadrupole followed by a sextupole that
are all resting on a common table can be simulated with the three elements supported by a
girder element. Ramper elements are used for simulating machines where parameters can vary
turn-by-turn. For example, ramper elements can simulate such things as energy ramping, beta
squeeze to achieve colliding beam conditions, or third order resonance slow extraction from a
ring to an extraction line.
Discussion of girder and ramper elements is outside the scope of this tutorial and here group
and overlay elements will be studied. Note: Group, overlay, ramper, and girder elements are
known as “minor lords” since they only control a subset of an element’s attributes. The other
type of lord elements, multipass lords and superposition lords are called “major lords”. See the
Bmad manual for details.

11.2 Example Lattice

The lattice used to illustrate control elements is named control.bmad which is situated in the
directory /lattices/11_ControlElements/:
! L a t t i c e F i l e : c o n t r o l . bmad
b e g i n n i n g [ beta_a ] = 10
b e g i n n i n g [ beta_b ] = 10

parameter [ p a r t i c l e ] = muon
parameter [ p0c ] = 1e9
parameter [ geometry ] = open

q : quadrupole , l = 1
b : sbend , l = 1
l l : line = (q, b)
use , l l

ov1 : o v e r l a y = { q [ k1 ] : a+b ^2 , b [ g ] : 0 . 1 * a+ t a n ( b ) } , v a r = { a , b } , a = 0.02

ov2 : o v e r l a y = { q [ k1 ] : 0 . 7 , q [ x _ o f f s e t ] : 0 . 1 * hh } , v a r = { hh } , hh = 0.01
gr1 : group = { b [ k1 ] : 0 . 4 * s q r t ( z ) } , v a r = { z }

Explanation:

• The overlay ov1 controls two parameters: The k1 attribute of element q (denoted q[k1]) and
the g attribute of element b (denoted b[g]).
• Overlay ov1 has two variables called a and b that are used to control the two attributes.

Collider Ring Design Tutorial using Bmad 57

 • The formulas that overlay ov1 uses to calculate the values of the two controlled attributes are
a+b2 for q[k1] and 0.1*a+tan(b) for b[g].

• Since overlay ov2 also controls q[k1], the value of q[k1] is the sum of the contributions of ov1
and ov2.
• The given "formula" for the control of q[k1] by ov2 is just a constant: 0.7. This is a shorthand
notation and the actual formula used is 0.7*hh. Note: When this shorthand notation is used,
only one control variable (in this case hh) may be used by the overlay.

• The initial values for control variables may be set when defining the control element. For
example, hh of ov2 is set to 0.2. Control variables default to a value of zero.

11.3 Control Element Organization in the Lattice

Start Tao with the lattice file control.bmad. To see the elements in the lattice use the show lattice
command:
Tao> show l a t

Values a t End o f Element :

Index name key s l beta phi ...
a a ...
0 BEGINNING Beginning_Ele 0.000 −−− 10.00 0.000 ...
1 Q Quadrupole 1.000 1.000 9.83 0.101 ...
2 B Sbend 2.000 1.000 9.60 0.204 ...
3 END Marker 2.000 0.000 9.60 0.204 ...
Lord Elements :
4 OV1 Overlay 2.000 −−− 9.60 0.204 ...
5 OV2 Overlay 1.000 −−− 9.83 0.101 ...
6 GR1 Group 2.000 −−− 9.60 0.204 ...
Index name key s l beta phi ...
a a ...
Values a t End o f Element :

The list of lattice elements is divided up into two sections:

• The "tracking" part of the lattice are the elements to be tracked through. Here the tracking
part of the lattice contains elements with index 1 through 3 (the beginning element with index
0 is not tracked through and is present to hold Initial parameters like the Twiss parameters).
• The "lord" section of the lattice are where the lord elements reside. Here the lord section
contains elements with index 4 through 6.

• Group and overlay elements get assigned a longitudinal s-position based upon the s-position
of the last slave element. This does not affect any calculations and is done since it can be
useful information when using the show lat and other show commands (oftentimes a control
element will only control the parameters of one slave element).

Collider Ring Design Tutorial using Bmad 58

11.4 Overlay Control

To see how things are controlled, the show element command may be used. Examining the lord
ov1 element shows:
Tao> show e l e 4 ! Or : show e l e ov1

Element # 4
Element Name : OV1
Key : Overlay
. . . etc . . .
S l a v e _ s t a t u s : Free
L o r d _ s t a t u s : Overlay_Lord
Control Variables :
1 A = 2.0000000E−02
2 B = 0.0000000E+00
Slaves : [ A t t r i b _ V a l = Expression_Val summed over a l l c o n t r o l l i n g o v e r l a y s . ]
Index Ele_Name A t t r i b u t e A t t r i b _ V a l u e Expression_Val Expression
1 Q K1 2.7000E−02 2.0000E−02 a+b^2
2 B G 2.0000E−03 2.0000E−03 0 . 1 * a+ t a n ( b )
. . . etc . . .

• All lattice elements have a slave_status which shows what type of slave the element is and
a lord_status which shows what type of lord the element is. overlay elements automatically
have a lord_status of overlay_lord. In this case, ov1 has a slave_status of free since there
are no other lord elements that control parameters of ov1. In general, overlay and group lords
may control parameters of other lords as well as non-lords.
• When an element parameter is controlled by one or more overlays, the value of that element
parameter is the sum of the values for each overlay. Thus in the above example, the contri-
bution to q[k1] due to overlay ov1 is 0.02 (= a + b2 ) as shown in the “Expression_Val” column
above. There is also a contribution of 0.007 (= 0.7 · hh) due to overlay ov2 making the value of
q[k1] equal to 0.027 as shown in the “Attrib_Value” column above.

Examining the q slave element shows that indeed the k1 attribute has a value of 0.027:
Tao> show e l e q
Element # 1
Element Name : Q
. . . etc . . .
1 L = 1.0000000E+00 m
4 K1 = 2.7000000E−02 1 /m^2
. . . etc . . .
S l a v e _ s t a t u s : Minor_Slave
C o n t r o l l e r Lord ( s ) :
Index Name Attribute Lord_Type Expression
4 OV1 K1 Overlay a+b^2
5 OV2 K1 Overlay 0 . 7 * hh
5 OV2 X_OFFSET Overlay 0 . 1 * hh

L o r d _ s t a t u s : Not_a_Lord
. . . etc . . .

Collider Ring Design Tutorial using Bmad 59

 The slave_status of element q is set to minor_slave to show that it is controlled by one or
more minor lords. The lord_status of q is not_a_lord indicating that it does not control any-
thing (“tracking elements”, that is elements in the tracking part of the lattice, never control other
elements).
Since the value of an attribute that is controlled by overlays depends directly on the overlay
variable values, the attribute may not be directly changed. For example, trying to change q[k1]
directly will result in an error:
Tao> s e t e l e q k1 = 0.02
[ERROR | 2017−AUG−26 1 3 : 2 9 : 2 6 ] a t t r i b u t e _ f r e e :
THE ATTRIBUTE : K1
OF THE ELEMENT: Q
IS NOT FREE TO VARY SINCE :
I T IS CONTROLLED BY THE OVERLAY: OV1

11.5 Group Control

Overlay elements use what is called “absolute” control since the value of a controlled parameter
is determined directly by the settings of the overlay variables that the controlled parameter is
slaved to. On the other hand, group elements use what is called “relative” control which is
different from absolute control in two respects:

• Only changes in group variable values affect controlled parameters.

• With group control, a controlled parameter may be varied directly.

Looking at an example will make this clear. Starting from the control.bmad lattice, consider the
effect of changing the z variable of the group gr1 to 0.01.
Tao> s e t e l e gr1 z = 0.01

Tao> show e l e gr1

Element # 6
Element Name : GR1
Key : Group

. . . etc . . .

S l a v e _ s t a t u s : Free
L o r d _ s t a t u s : Group_Lord
Control Variables :
1 Z = 1.0000000E−02 OLD_Z = 1.0000000E−02
Slaves :
Index Ele_Name A t t r i b u t e Attrib_Value Expression_Val Expression
2 B K1 4.0000E−02 4.0000E−02 0.4* sqrt ( z )

For group elements, Bmad keeps track of what is called the “old” value of a variable. The name
of the old value is the variable name with a “old_” prefix. In this case the old value of z is given
the name “old_z”. Before the set ele gr1 command was executed, the value of z and old_z is
zero. When the above set ele gr1 command is executed, the value of z becomes 0.01. Bmad
detects that z and old_z are different and updates b[k1] using the following procedure:

Collider Ring Design Tutorial using Bmad 60

 1. Evaluates the formula for b[k1] using z and old_z and takes the difference. In this case the
difference is 0.4*sqrt(z) - 0.4*sqrt(old_z) = 0.04
2. Changes the value of b[k1] by the difference (0.04). Since the old value of b[k1] was zero.
The new value of b[k1] is 0.04.
3. Sets the value of old_z equal to z indicating that the change was made.

A consequence of the last step in the above procedure, the show ele command will always show
that old_z and z are equal.
Now consider the effect of the following commands:
Tao> r e i n i t tao
Tao> s e t e l e gr1 z = 0.01
Tao> s e t e l e b k1 = 0.02
Tao> s e t e l e gr1 z = 0.04

The result is:

Tao> show e l e gr1
. . . etc . . .
Control Variables :
1 Z = 4.0000000E−02 OLD_Z = 4.0000000E−02
Slaves :
Index Ele_Name A t t r i b u t e Attrib_Value Expression_Val Expression
2 B K1 6.0000E−02 8.0000E−02 0.4* sqrt ( z )

1. The “reinit tao” command resets Tao to its initial state.

2. The “set ele gr1 z = 0.01” command acts as explained above.
3. The “set ele b” command sets the value of b[k1] to 0.02. This is independent of the state
of element gr1.
4. The “set ele gr1 z = 0.04” command sets the value of gr1[z] to 0.04 which causes the
value of b[k1] to increase by 0.04 (= 0.08 - 0.04) from 0.02 to a value of 0.06.

11.6 Example:

Consider the situation where you want to control the chromaticity (change in tune with particle
energy) of a ring by varying sextupole strengths. To change the chromaticity by 1 unit you want
to change the sextupole strengths by amounts that you compute. Here you don’t care about
the value of the sextupole strengths per se, you only want to vary the sextupole strengths by a
certain delta. So the sextupole “knob” can be simulated using a group controller which may look
like:
xqune_1 : group ={SEX_08W: −.6415E−03 * k2 , . . . } , v a r = { k2 }

Note: In this case, since the parameter to be controlled for the sex_08w element was not speci-
fied, the parameter is taken to be the same as the variable of the controller. k2 in this case.
Notes:

Collider Ring Design Tutorial using Bmad 61

 • Group and overlay elements can control other group and overlay elements.
• A given element parameter may only be controlled by a set of group elements or a set of overlay
elements but may not be controlled by both group and overlay elements since this would create
an ambiguous situation as to how to evaluate the parameter.

11.7 Exercises:
1. The function that a controller uses to control a slave attribute may be specified using an
arithmetical expression as in the above examples, or may be specified by a list of “knot” points
with spline interpolation used to evaluate the function in between points. As an exercise, setup
a controller in control.bmad that uses knot points that mimics the action of ov2 at least over
some limited interval. Hint: Look at the documentation for overlay or group elements in the
elements chapter of the Bmad manual.
2. Group controllers are good for varying the longitudinal position of elements. Starting with
the file simple.bmad add a group controller that varies the s-position of the upstream edge of
element B while keeping the length of the entire lattice constant (hint: The lengths of both
B and D must change in tandem). This situation occurs frequently enough that there is a
shortcut attribute called start_edge that can be used instead of directly varying the lengths of
elements. See the documentation on group elements in the Elements chapter of the Bmad
manual for more details.
3. Modify the lattice file simple.bmad to include a girder element supporting elements B and Q.
Use the show ele command to verify that indeed the girder is supporting these two elements.

Collider Ring Design Tutorial using Bmad 62

12 Dynamic Aperture

Dynamic aperture (DA) is measure of the stable phase space in an accelerator over a specified
number of turns. Particles outside of the DA will be driven to large amplitudes where they will
be lost. In the following sections, strategies for increasing a ring’s DA will be shown in a sample
ring.

θ
O x

Figure 23: The calculation of a dynamic aperture curve in the x-y plane at a given initial pz value
involves calculating aperture curve points (blue dots) along a set of “rays” (dashed lines). The
line segments between points is simply for visualization purposes and does not appear in graphs
of real data.

12.1 Calculating Dynamic Aperture

The DA calculation can be done in Tao or the standalone dynamic_aperture program. The
calculation is done using the same Bmad based routines in both programs. Example files for
both programs are provided. Points along rays are tested to determine the DA perimeter as
shown in Fig. 23. The rays have a common origin point (O) which is taken to be the reference
orbit. The calculation of an aperture curve point along a given ray involves iteratively tracking
particles with different starting (x, y) position values to find the boundary between stable (green
dots) and unstable (red dots) motion.
Files for this example can be found at
/ l a t t i c e s / 1 2 _DynamicAperture / 1 2 . 1 _ C a l c u l a t i n g D A

Using the init file tao_DA.init, Tao will calculate the DA of out lattice. The DA calculation is
defined in the block:
&tao_dynamic_aperture
ix_universe = 1
e l l i p s e _ s c a l e = 10

Collider Ring Design Tutorial using Bmad 63

 Dynamic Aperture
0.6 10 sigma beam ellipse ⊙
⊙ δ: 0.00%
⊙ δ: 0.20% ⊙
⊙ δ: 0.40%
⊙ δ: 0.60% ⊙
⊙ δ: 0.80 % ⊙ ⊙
0.4 ⊙ δ: 1.00% ⊙
⊙ ⊙
⊙
y (mm)
⊙ ⊙ ⊙⊙
⊙
0.2

⊙
⊙
0 ⊙⊙⊙ ⊙ ⊙⊙ ⊙⊙ ⊙⊙ ⊙⊙
-3 -2 -1 0 1 2 3
x (mm)

Figure 24: Dynamic aperture results.

pz = 0 . 0 0 , 0 . 0 0 2 , 0 . 0 0 4 , 0 . 0 0 6 , 0 . 0 0 8 , 0.010
da_param%n_angle = 5
da_param%n _ t u r n = 1000
da_param%abs_accuracy = 1e−4
da_param%min_angle = 0
da_param%max_angle = 3.14159
a_emit = 2E−08
b_emit = 1E−08
/

The pz list gives each momentum offset the aperture will be calculated for. The da_param struct
contains the parameters used for a calculation. In this case it is set up to give 5 points along rays
arranged from 0 to π. Particle stability is checked over 1000 turns. Run Tao with the command
t a o − i n i t tao_DA . i n i t

After the calculation is finished, the results can be plotted using the command
p l a c e r11 dynamic_aperture

The results are shown in Fig. 24

For the standalone program, the file DA.init is provided. The parameters are similar to those in
the Tao program:
&params
d a t _ f i l e = " ring_DA . d a t "
l t t %l a t _ f i l e = " r i n g . bmad "
l t t %r f c a v i t y _ o n = T
dpz = 0 . 0 0 0 , 0 . 0 0 2 , 0 . 0 0 4 , 0 . 0 0 6 , 0 . 0 0 8 , 0.010
da_param%n_angle = 5
da_param%n _ t u r n = 1000
da_param%abs_accuracy = 1e−5
da_param%min_angle = 0
da_param%max_angle = 3.14159
/

Collider Ring Design Tutorial using Bmad 64

 The main additions are the output file and lattice file being declared. Using this file, the stan-
dalone program can be run by the command:
dynamic_aperture DA. i n i t

After running, the results will be in the dat_file used. The results can the be plotted in gnuplot
using the command outputted at the end of the DA run or using the plotting software of your
choice.
You can run the program using the ring lattice to check the DA. DA calculations can be slow,
so it is sometimes advisable to reduce the accuracy, number of turns, or number of angles to
get faster results between optimizations, and then come back with a more accurate run to verify.
These example parameters are set to take fewer than 5 minutes with the tutorial ring.

12.2 Example: Adding Sextupoles

Files for this example can be found at:

/ l a t t i c e s / 1 2 _DynamicAperture / 1 2 . 2 _AddingSextupoles

A common element used for DA optimization are sextupoles. “Harmonic” sextupoles, that is, sex-
tupoles that minimize resonance driving modes, can be used to increase the transverse aperture.
Sextupoles can be added to the lattice by following the steps below.

1. Start by defining the chromatic sextupoles (sextupoles that will control the chromaticity and
therefore have to be placed in dispersive regions). Two families per plane in each arc will be
used. A typical sextupole here looks like:
SF1_1 : Sextupole , L = 0 . 5 8 4 , k2 = 2

The sextupole strength will be optimized later. The ring.bmad file defines a ring with sex-
tupoles.
2. Harmonic sextupoles should also be defined for the straight sections. We will use one family
in each plane
SFSS : Sextupole , L = 0 . 5 8 4 , k2 = 0 .
SDSS: Sextupole , L = 0 . 5 8 4 , k2 = −0.

3. We need to make room for the sextupoles, so we will split the drift D2 into two smaller drifts
D2S1 : D r i f t , L = 0.501
D2S2 : D r i f t , L = 0.156

4. The FODO cells must be altered to include the new sextupoles and drifts. In the straight
sections this is simply done:
! S t r a i g h t s e c t i o n f o r w a r d FoDo :
FODOSSF: l i n e = (QFSS, D1 , DB, D2S1 , SDSS, D2S2 ,
QDSS, D1 , DB, D2S1 , SFSS, D2S2 )

Collider Ring Design Tutorial using Bmad 65

 This also must be done for the reverse line. The arc FODOs are more complicated as we
want to families per plane. In order to do this, we will define two FODO cells. For arc 1 this
will look like:
! 1 o ’ c l o c k a r c f o r w a r d 2 * FoDo :
FODOAF_1 : l i n e = (QF, D1 , B , D2S1 , SD1_1 , D2S2 ,
QD, D1 , B , D2S1 , SF1_1 , D2S2 ,
QF, D1 , B , D2S1 , SD2_1 , D2S2 ,
QD, D1 , B , D2S1 , SF2_1 , D2S2 )

The sample file contains similar FODO declarations for all arcs.
5. Finally the lines that define the ring must be to include the altered FODO cells
SEXTANT1 : l i n e = ( 4 * FODOSSF, SS_TO_ARCF,
10 *FODOAF_1, ARC_TO_SSF_2, 4 * FODOSSF_2)
SEXTANT3 : l i n e = ( 4 * FODOSSR_2, SS_TO_ARCR_2,
10 *FODOAR_3, ARC_TO_SSR, 4 *FODOSSR)
SEXTANT5 : l i n e = ( 4 * FODOSSF, SS_TO_ARCF,
10 *FODOAF_5, ARC_TO_SSF, 1 *FODOSSF, IPF )
SEXTANT7 : l i n e = ( IPR , 1 *FODOSSR, SS_TO_ARCR,
10 *FODOAR_7, ARC_TO_SSR, 4 *FODOSSR)
SEXTANT9 : l i n e = ( 4 * FODOSSF, SS_TO_ARCF,
10 *FODOAF_9, ARC_TO_SSF, 2 *FODOSSF, 2 *FODORF)
SEXTANT11 : l i n e = ( 2 * FODORF, 2 *FODOSSR, SS_TO_ARCR,
10 *FODOAR_11, ARC_TO_SSR, 4 *FODOSSR)

12.3 Example: Chromaticity Correction

Files for this example can be found at:

/ l a t t i c e s / 1 2 _DynamicAperture / 1 2 . 3 _ C h r o m a t i c i t y C o r r e c t i o n

The first step in chromatic correction is to use the newly placed chromatic sextupoles to correct
the linear chromaticity. As there is a chromaticity associated with each plane, we have two things
to correct. For optimization, sextupoles can be combined using an Overlay element. This allows
all sextupoles in the same plane to be optimized together. With one overlay for each plane, this
gives two variables for the correction. This optimization can be done with the following steps:

1. First the overlays must be defined

OSF: o v e r l a y = { SF%_ * [ k2 ] : x } , v a r = { x }
OSD: o v e r l a y = {SD%_ * [ k2 ] : x } , v a r = { x }

The overlays define an attribute x that controls the k2 attribute of every sextupole that fits a
name of the form in each overlay.
2. In the tao.init file, a variable block can be used to control the overlays in an optimization
&t a o _ v a r
v1_var%name = ’OS’
v a r (1:2)% ele_name = "OSF" , "OSD"
d e f a u l t _ s t e p = 1e−6
default_attribute = ’x ’
/

Collider Ring Design Tutorial using Bmad 66

 3. We must also define the data for chromaticity in the tao.init file. Instead of correcting setting
the chromaticity to zero, it is usually set to a small positive number when above transition or a
small negative number when below. This is done to avoid the head-tail instability. In our case
we can set it to 1 in both planes.
&tao_d2_data
d2_data%name = ’ chrom ’
n_d1_data = 1
/

&tao_d1_data
ix_d1_data = 1
datum ( 1 ) = ’ chrom . a ’ ’’ ’’ ’’ ’ t a r g e t ’ 1 100
datum ( 2 ) = ’ chrom . b ’ ’’ ’’ ’’ ’ t a r g e t ’ 1 100
/

4. The optimization can be done using the command run lmdif. After the optimizer is finished,
the results will be in a output file named var1.out by default.

5. After optimizing, make a copy of the var1.out file and rename it to something like correc-
tion.out. Then, call the output file for the sextupole values in your lattice using call, file =
correction.out.
6. You can then rerun a DA calculation to see how this correction has altered the results.

12.4 Advanced Dynamic Aperture Correction

In addition to linear chromaticity, several other optimizations to improve DA are also available in
Bmad. One of these is the W-function:
p
W = A2 + B 2 (2)

where

∂α α ∂β 1 ∂β
A= − , B= (3)
∂pz β ∂pz β ∂pz

This is a chromatic function that is the amplitude of the linear energy dependent β-beat. similar to
the linear chromaticity, this can be corrected with the use of sextupoles. This correction is more
complex than before as the phase advance between sextupoles and the quadrupoles creating the
W-function is important. Since β-beating goes as twice the betatron phase advance, sextupoles
that are 90◦ apart will work against each other. The solution is to split the sextupoles in each
arc into two families per plane. This way we can correct the chromaticity while making sure the
sextupoles do not entirely cancel each other for the W-function correction.

Collider Ring Design Tutorial using Bmad 67

12.4.1 Example

Files for this example can be found at:

/lattices/12_DynamicAperture/12.4_AdvancedDA
The sextupole families can again be set up using an overlay, although this time we will center
the sextupole strengths around the value for chromaticity correction. This will ensure each arc
corrects an equal amount of the total chromaticity.

1. We will begin by altering the overlays. Assume the sextupole setting you found in the last
example are SX and SY, then an overlay for sextupoles centered at these values will be
OF_1 : o v e r l a y = { SF1_1 [ k2 ] : SX + x , SF2_1 [ k2 ] : SX − x } , v a r = { x }
OD_1 : o v e r l a y = { SD1_1 [ k2 ] : SY + x , SD2_1 [ k2 ] : SY − x } , v a r = { x }

This must be done for all arcs.

2. With these overlays, the W-function can be optimized, however, without proper phasing be-
tween arcs, sextupoles may not be efficient in the correction. In order to fix phases between
sextupoles for the optimization, it is often useful to use a phase trombone. Phase trombones
are artificial elements that are used to set a phase advance without altering optics. We will
need three phase trombones, two surrounding the IP and one to fix the tune. We will fix the
tune in the 2 o’clock tune cell.
TR_F : match , dphi_a = 0 , dphi_b = 0 , m a t r i x = phase_trombone
TR_R : match , dphi_a = 0 , dphi_b = 0 , m a t r i x = phase_trombone
TR_M: match , dphi_a = 0 , dphi_b = 0 , m a t r i x = phase_trombone

3. In order to make sure the tune remains fixed, we can use an overlay to control the trombones
TROMBONES: o v e r l a y = { TR_F [ dphi_a ] : x1 ,
TR_R [ dphi_a ] : x2 , TR_2 [ dphi_a ] : −x1−x2 ,
TR_F [ dphi_b ] : y1 , TR_R [ dphi_b ] : y2 , TR_2 [ dphi_b ] : −y1−y2 } ,
v a r = { x1 , x2 , y1 , y2 }

4. W-function optimization is often done by setting it to zero in specific location in the ring. We
will set it to zero at the IP and at the end of arc 7. We will add a marker for the use in the
optimization
END_7 : marker

5. The trombones and marker can now be placed in the ring

SEXTANT1 : l i n e = (TR_M, 4 *FODOSSF, SS_TO_ARCF,
10 *FODOAF_1, ARC_TO_SSF_2, 4 * FODOSSF_2)
SEXTANT3 : l i n e = ( 4 * FODOSSR_2, SS_TO_ARCR_2,
10 *FODOAR_3, ARC_TO_SSR, 4 *FODOSSR)
SEXTANT5 : l i n e = ( 4 * FODOSSF, SS_TO_ARCF,
10 *FODOAF_5, ARC_TO_SSF, 1 *FODOSSF, TR_F , IPF )
SEXTANT7 : l i n e = ( IPR , TR_R, 1 *FODOSSR, SS_TO_ARCR,
10 *FODOAR_7, END_7 ,ARC_TO_SSR, 4 *FODOSSR)
SEXTANT9 : l i n e = ( 4 * FODOSSF, SS_TO_ARCF,
10 *FODOAF_9, ARC_TO_SSF, 2 *FODOSSF, 2 *FODORF)
SEXTANT11 : l i n e = ( 2 * FODORF, 2 *FODOSSR, SS_TO_ARCR,
10 *FODOAR_11, ARC_TO_SSR, 4 *FODOSSR)

Collider Ring Design Tutorial using Bmad 68

 6. We must now set up the init file. Define the W-function to be zero at the IP6 and END_7
markers
&tao_d2_data
d2_data%name = ’w ’
n_d1_data = 1
/
&tao_d1_data
ix_d1_data = 1
datum ( 1 ) = ’ chrom . w . a ’ ’ ’ ’ ’ ’END_7 ’ ’ t a r g e t ’ 0 100
datum ( 2 ) = ’ chrom . w . b ’ ’ ’ ’ ’ ’END_7 ’ ’ t a r g e t ’ 0 100
datum ( 3 ) = ’ chrom . w . a ’ ’ ’ ’ ’ ’ IP6 ##1 ’ ’ t a r g e t ’ 0 100
datum ( 4 ) = ’ chrom . w . b ’ ’ ’ ’ ’ ’ IP6 ##1 ’ ’ t a r g e t ’ 0 100
/

7. The variables can be set up to control the sextupoles in arcs 5 and 7 and the phase trombones
&t a o _ v a r
v1_var%name = ’ s e x t u p o l e s ’
v a r (1:4)% ele_name = " OF_5 " , "OD_5" , " OF_7 " , "OD_7"
d e f a u l t _ s t e p = 1e−6
default_attribute = ’x ’
/

&t a o _ v a r
v1_var%name = ’ phases ’
v a r (1:4)% ele_name ="TROMBONES" , "TROMBONES" , "TROMBONES" , "TROMBONES"
d e f a u l t _ s t e p = 1e−6
v a r (1:4)% a t t r i b u t e = ’ x1 ’ , ’ x2 ’ , ’ y1 ’ , ’ y2 ’
/

8. Run the optimizer in Tao to find the correct sextupole and phase trombone settings.
9. Make a copy of the var1.out file and call it in your lattice to use the updated values.

After these steps, you should have a W-function like in Figure 25.

12.5 Exercises
1. IP and 2 o’clock phase trombones: This can be split into three parts, the phase on both
sides of the IP and the phase in the 2 o’clock phase trombone. These parts can be inserted
separately into the init file
(a) The 2 o’clock phase trombone is the easiest to add the init file, simply copy the data and
variables from the previous use of the tune cell.
(b) The upstream phase trombone can be implemented by fixing αx,y and βx,y at the IP.
Add a marker at the beginning of arc 5 named END_5. Set a datum for phase_frac.a
and phase_frac.b from the marker to the IP. Set the target to get the correct phase. For
variables, use the upstream IR quads and the last three quads in the matching section
from the dispersion suppressor.

Collider Ring Design Tutorial using Bmad 69

 Figure 25: The W-function receives a large contribution form the IP which is corrected over one
arc.

(c) The downstream phase can be matched using the same process as the upstream side.
Variables can be chosen to be the downstream IR quads and last three quads in the
matching section to the dispersion suppressor. We again must fix αx,y and βx,y , but this
time we will fix it at the marker END_7. The phase condition is now set from the IP to
END_7.
After setting up the data and variables, you can run the optimizer. If the lattice may become
unstable during the optimization, if this happens, try using the cut command (toggles lattice
geometry between open and close). Notice that the W-function correction is slightly disrupted
by this change. This sometimes requires an iterative process.

Collider Ring Design Tutorial using Bmad 70

13 Model, Design and Base Lattices in Tao

When Tao runs, Tao creates three lattices (Technically, Tao instantiates three lattices per uni-
verse. See the discussion on universes in the Tao manual.):

Design Lattice
The design lattice corresponds to the lattice read in from the lattice description file(s). Pa-
rameters in this lattice are never varied.
Model Lattice
Initially, when Tao is started, The model lattice is the same as the design lattice. Parameters
in the model lattice are allowed to vary. That is, all commands to vary lattice parameters
vary parameters of the model lattice.
Base Lattice
The base lattice is a reference lattice used so that changes in the Model lattice may be
easily viewed. The Design lattice can also be used as a reference lattice but since the
parameters of the design lattice are fixed, this is not always desirable. The parameters of
the base lattice are set by setting the parameters of the base lattice equal to the present
state of the model lattice.

13.1 Changing Model Parameters

To see the difference between the model and design lattices, start Tao with the lattice file lat-
tices/13_LatticeTypes/simple.bmad.
Now issue the following commands:
Tao> p l a c e r23 o r b i t
Tao> p l a c e r13 o r b i t
Tao> s e t p l o t r33 component = design ! Bottom p l o t
Tao> s e t p l o t r13 component = model − design ! Plot difference o r bi t
Tao> scale

The “set plot <plot_name> component = ...” command sets where the data to be plotted
comes from. The result is shown in Figure 26a. The bottom plot shows the design lattice orbit, the
middle plot shows the model lattice orbit and the top plot shows the difference in orbits between
model and design. Since the two lattices are the same when Tao is started, the difference orbit
is zero.
Now change the model lattice using the following commands:
Tao> change element b v k i c k −0.0005 ! Changes by a g i v e n d e l t a
Tao> s e t element q h k i c k = 0.001 ! Another way o f changing a parameter .
Tao> s c a l e

The change command changes real numbers by a given delta. The set command sets a param-
eter to a specific value. Unlike the change command, the set command can also be used with

Collider Ring Design Tutorial using Bmad 71

 D B Q D B Q

(a) Initially, the model lattice and the design lattices (b) The set and change commands will modify
are the same. model lattice parameters.

Figure 26

integer, string and logical parameters. The result is shown in Figure 26b. Since now the model
lattice is not the same as the design lattice, the difference orbit is non-zero.

13.2 Using the Base Lattice

The base lattice is used to view changes when the desired reference lattice does not correspond
to the design lattice.
Continuing from the previous section, issue the following commands:
Tao> s e t l a t t i c e base = model ! Set t h e Base l a t t i c e = Model l a t t i c e .
Tao> s e t p l o t r33 component = model − base
Tao> s e t e l e q v k i c k = 5e−4
Tao> scale

The set lattice command sets the base lattice equal to the model lattice. The third command
varies the model lattice. The result is shown in Figure 27. The bottom plot of the orbit difference
between model and base is not the same as the orbit difference between model and design.

Collider Ring Design Tutorial using Bmad 72

 Figure 27: The base lattice is used to view changes when the reference lattice configuration does
not correspond to the design lattice.

13.3 Exercises
1. Orbit plots: Modify the middle graph in Fig. 27 so that the vertical orbit curve becomes the
horizontal orbit of the design lattice.

2. Alias command: To save on typing, alias commands may be defined. Define an alias com-
mand called setit so that typing “setit 1e-6” is equivalent to “set ele q vkick = 1e-6”. Hint:
Look in the manual or type “help alias” to get more information on setting and using alias
commands. Note: Do not confuse Tao alias commands with the alias string component of a
lattice element.

3. Adjust the tune using set tune: The tune of the lattice can also be set by using the set
tune command in Tao, which scales together all focusing quadrupoles and all defocusing
quadrupoles to set the horizontal and vertical tunes. Using a lattice with the ring you have
constrcted, use set tune -mask *, QF, QD 0.08 0.14 to set the tune of the ring. Plot the

Collider Ring Design Tutorial using Bmad 73

 difference between the model and design lattices to see how much “beta-beating” there is
around the ring.

Collider Ring Design Tutorial using Bmad 74

14 Orbit Correction

While operating accelerators, the beam’s orbit is measured with Beam Position Monitors (BPMs).
The accelerator is designed with ideal BPM readings in mind, which are often 0. After extended
operational experience, operators learn good readings for all BPMs that are referred to as golden
orbits. It then becomes important to change the beam’s trajectory to obtain the desired BPM
readings.

14.1 Example: Adding Corrector Coils and BPMs

QDSS
QF SS
CH

CV
Figure 28: FODO cell with corrector coils.

1. Start with the ring0.bmad lattice. Place corrector coils in the middle of D1 drifts 6.4 cm away
from quadrupoles. This is downstream from the quadrupoles in the forward arcs and upstream
in the reverse arcs. Define horizontal and vertical corrector coils and appropriate drift spaces
as follows:
! ( 1 ) : D e f i n e h o r i z o n t a l / v e r t i c a l c o r r e c t o r c o i l s and
s p l i t D1 i n t o D1C1 and D1C2 t o f i t c o i l s
D1C1 : D r i f t , L = 0.064
D1C2 : D r i f t , L = 0.345 ! 0 . 6 0 9 − 0.064 − 0 . 2
CH: h k i c k e r , L = 0 . 2
CV: v k i c k e r , L = 0 . 2

2. Add corrector coils near quadrupoles. Then, add horizontal kickers near focusing quadrupoles
and vertical kickers near defocusing quadrupoles.
After adding the kicker, correctors in the D1 drift have to be added. This means placing the
correctors after quadrupoles in the forward geometry and before quadrupoles in the reverse
geometry.
Because we have used D1 drifts repeatedly throughout the ring, adding correctors manually
is a tedious task. The easiest approach is to use regular expressions in Find and Replace.
The recipe is the following:
1 . I n t h e f o r w a r d a r c s f o r d r i f t s a f t e r f o c u s i n g quadrupoles :
Replace (QF [ ^ , \ n ] * , [ ^ , \ n ] * ) D1 w i t h \ 1D1C1 , CH, D1C2 f o r
2 . I n t h e f o r w a r d a r c s f o r d r i f t s a f t e r d e f o c u s i n g quadrupoles :
Replace (QD[ ^ , \ n ] * , [ ^ , \ n ] * ) D1 w i t h \ 1D1C1 , CV, D1C2
3 . I n t h e r e v e r s e a r c s f o r d r i f t s b e f o r e f o c u s i n g quadrupoles :
Replace ( D1 ) ( [ ^ , \ n ] * , [ ^ , \ n ] * QF) , w i t h D1C2 , CH, D1C1\ 2
4 . I n t h e r e v e r s e a r c s f o r d r i f t s b e f o r e d e f o c u s i n g quadrupoles :
Replace ( D1 ) ( [ ^ , \ n ] * , [ ^ , \ n ] * QD) , w i t h D1C2 , CV, D1C1\ 2

Collider Ring Design Tutorial using Bmad 75

 5 . I n t h e r e v e r s e a r c s f o r d r i f t s a t t h e end o f a c e l l :
Replace D1 ) w i t h D1C2 , CH, D1C1 )

In some text editors, you may need to use $1 and $2 instead of \1 and \2.
3. Define and add BPMs after dipoles (B, HB, and DB in the straight section). Here we use a
0-length marker to represent the BPMs.
! ( 3 ) D e f i n e and add BPMs
BPM: marker

Then insert the BPMs after dipoles by searching and replacing B, with B, BPM, (including
the commas) and repeat for HB and DB.

14.2 Example: Radiation-induced Sawtooth Orbit Correction

Horizontal Orbit(mm) [model]

0.6
A) ⊙⊙⊙ ⊙
⊙⊙⊙
⊙⊙⊙
⊙⊙⊙
0.3 ⊙ ⊙ ⊙⊙
⊙⊙⊙
⊙
⊙
⊙ ⊙
⊙⊙⊙⊙⊙ ⊙⊙⊙ ⊙
⊙⊙ ⊙⊙⊙⊙
⊙⊙
⊙⊙⊙ ⊙
⊙⊙⊙⊙
⊙⊙
⊙⊙
⊙⊙
⊙
⊙⊙
⊙⊙⊙
⊙⊙
⊙⊙⊙ ⊙
⊙⊙
⊙⊙
⊙⊙⊙
⊙
⊙⊙
⊙⊙
⊙ ⊙⊙
⊙⊙
⊙⊙⊙ ⊙
⊙⊙
⊙ ⊙
⊙⊙
⊙ ⊙
⊙⊙
⊙
⊙⊙
⊙⊙
⊙⊙
⊙
⊙⊙⊙
⊙ ⊙
⊙ ⊙ ⊙
0⊙ ⊙⊙
⊙⊙ ⊙
⊙⊙
⊙⊙
⊙⊙
⊙⊙
⊙ ⊙
⊙ ⊙⊙⊙
⊙⊙⊙
⊙⊙
⊙⊙
⊙⊙
⊙⊙
⊙⊙⊙
⊙⊙⊙
⊙⊙⊙⊙ ⊙⊙
⊙⊙
⊙⊙
⊙ ⊙
⊙⊙⊙
⊙
⊙⊙
⊙⊙⊙ ⊙⊙
⊙⊙
⊙⊙
⊙ ⊙
⊙
⊙⊙
⊙⊙⊙
⊙
⊙ ⊙⊙
X

⊙ ⊙ ⊙ ⊙ ⊙ ⊙ ⊙⊙ ⊙
⊙ ⊙
⊙
⊙⊙⊙⊙
⊙⊙
⊙⊙⊙⊙
⊙⊙ ⊙ ⊙
⊙ ⊙⊙ ⊙ ⊙
⊙
⊙
⊙⊙⊙
⊙⊙ ⊙ ⊙
⊙⊙
⊙⊙
⊙⊙
⊙ ⊙ ⊙ ⊙
⊙ ⊙ ⊙ ⊙ ⊙ ⊙
⊙⊙⊙ ⊙
⊙⊙⊙
⊙⊙
⊙ ⊙
⊙
⊙⊙
⊙ ⊙⊙
-0.3
⊙ ⊙⊙
⊙⊙
⊙⊙
⊙⊙
⊙⊙
⊙⊙⊙ ⊙
⊙
⊙⊙
⊙
⊙
⊙
⊙⊙
⊙⊙⊙
⊙⊙
⊙⊙
⊙
⊙⊙
⊙⊙
⊙
⊙ ⊙
⊙⊙
⊙⊙
⊙⊙⊙
⊙⊙⊙⊙
⊙
⊙⊙
⊙⊙
⊙
⊙
-0.6
0 40 80 120 160 200 240 280 320 360 400 440
index
HorizontalOrbit(mm) [model]
⊙
B) 0.06 ⊙
⊙⊙⊙⊙ ⊙⊙⊙⊙
⊙⊙⊙⊙ ⊙ ⊙ ⊙⊙⊙
0.03 ⊙ ⊙ ⊙⊙⊙⊙⊙⊙⊙ ⊙ ⊙
⊙ ⊙⊙ ⊙ ⊙
⊙⊙⊙⊙⊙⊙⊙⊙⊙ ⊙ ⊙ ⊙⊙ ⊙⊙⊙⊙⊙⊙⊙⊙⊙⊙⊙ ⊙
⊙ ⊙
⊙⊙⊙
⊙⊙
⊙⊙
⊙⊙
⊙⊙
⊙⊙⊙⊙ ⊙
⊙⊙
⊙⊙
⊙⊙⊙⊙⊙⊙⊙⊙
⊙ ⊙⊙ ⊙ ⊙
⊙ ⊙ ⊙⊙
⊙⊙⊙⊙⊙⊙⊙⊙⊙⊙
⊙
⊙ ⊙⊙ ⊙ ⊙⊙⊙⊙⊙⊙⊙⊙⊙⊙⊙ ⊙⊙ ⊙⊙⊙⊙ ⊙ ⊙⊙ ⊙⊙⊙⊙⊙⊙
⊙⊙
⊙
⊙
0⊙ ⊙⊙⊙ ⊙ ⊙⊙⊙
⊙⊙ ⊙⊙⊙⊙⊙⊙⊙⊙⊙
⊙ ⊙ ⊙⊙⊙
⊙⊙
⊙⊙
⊙⊙⊙⊙⊙⊙⊙⊙⊙⊙⊙⊙⊙⊙⊙
⊙ ⊙⊙⊙ ⊙⊙⊙⊙⊙⊙⊙⊙⊙⊙⊙
⊙ ⊙⊙⊙
X

⊙ ⊙
⊙⊙⊙⊙⊙⊙ ⊙⊙⊙
⊙⊙
⊙⊙
⊙⊙
⊙
⊙ ⊙⊙⊙⊙⊙
⊙ ⊙ ⊙
⊙⊙⊙⊙
⊙
⊙⊙⊙⊙
⊙⊙⊙⊙⊙⊙⊙⊙⊙⊙⊙ ⊙
⊙ ⊙ ⊙
⊙
⊙⊙
⊙⊙
⊙⊙⊙ ⊙⊙
⊙
⊙⊙ ⊙
⊙ ⊙
⊙⊙⊙
⊙⊙ ⊙ ⊙
⊙⊙⊙⊙⊙⊙⊙⊙ ⊙ ⊙⊙⊙ ⊙⊙ ⊙ ⊙⊙⊙ ⊙ ⊙ ⊙⊙ ⊙ ⊙ ⊙⊙⊙ ⊙⊙⊙ ⊙
⊙⊙ ⊙ ⊙⊙ ⊙
⊙ ⊙ ⊙⊙⊙⊙ ⊙ ⊙⊙⊙ ⊙
⊙ ⊙ ⊙ ⊙ ⊙⊙⊙⊙
⊙
⊙⊙
⊙
-0.03 ⊙ ⊙⊙⊙⊙⊙ ⊙
⊙⊙⊙⊙⊙⊙⊙⊙
⊙⊙⊙⊙
⊙⊙⊙⊙
⊙⊙⊙⊙⊙⊙⊙ ⊙⊙⊙⊙ ⊙ ⊙
⊙⊙
⊙⊙⊙⊙⊙
-0.06
0 40 80 120 160 200 240 280 320 360 400 440
index

Figure 29: A) The sawtooth orbit due to synchrotron radiation. B) The orbit after correction using
kickers and BPMs.

1. Sawtooth orbits are caused by synchrotron radiation energy loss in the ring. This energy loss
leads to the particle energy variation along the ring, which causes the horizontal closed orbit
to have a sawtooth shape. To produce this shape in Tao, turn on radiation damping with
bmad_com [ r a d i a t i o n _ d a m p i n g _ o n ] = T

Collider Ring Design Tutorial using Bmad 76

 in the ring0.bmad file, or equivalently run
s e t bmad_com r a d i a t i o n _ d a m p i n g _ o n = T

in Tao. It turns on the deterministic average synchrotron radiation energy loss in the ring.
Let’s explore two methods to correct the sawtooth orbit.

2. The taper command adjusts magnet strengths to eliminate the transverse orbital and Twiss
changes due to the radiation damping induced sawtooth effect. The taper scales mag-
net strengths based on local closed orbit momentum deviation and identical elements are
changed independently. Tapering is not applied to strengths controlled by an overlay ele-
ment.
Now run taper in Tao and check the resulting orbit.

3. Alternatively, we can use kickers to fix the sawtooth orbit. Let’s define the orbit readings as
data and kicker strengths as variables in tao.init.
&tao_d2_data
d2_data%name = ’ o r b i t ’
n_d1_data = 2
default_merit_type = ’ target ’
default_meas = 0
default_weight = 1
/

&tao_d1_data
ix_d1_data = 1
d1_data%name = ’ x ’
s e a r c h _ f o r _ l a t _ e l e s = ’BPM * ’
/

&tao_d1_data
ix_d1_data = 2
d1_data%name = ’ y ’
s e a r c h _ f o r _ l a t _ e l e s = ’BPM * ’
/

&t a o _ v a r
v1_var%name = ’ h k i c k e r ’
search_for_lat_eles = ’ hkicker : : * ’
d e f a u l t _ s t e p = 1e−6
d e f a u l t _ a t t r i b u t e = ’ kick ’
/

&t a o _ v a r
v1_var%name = ’ v k i c k e r ’
search_for_lat_eles = ’ vkicker : : * ’
d e f a u l t _ s t e p = 1e−6
d e f a u l t _ a t t r i b u t e = ’ kick ’
/

4. Right now all the kickers and BPMs are assumed to be the same, but we want to address
them individually. Tao has the option to add a unique suffix after duplicate elements. Simply
add to your tao.init:

Collider Ring Design Tutorial using Bmad 77

 &tao_ desi gn_la ttice
unique_name_suffix = " h k i c k e r : : _? v k i c k e r : : _? marker : : _ ?"
/

5. While Tao has a native template for orbit plots, here we provide two custom templates to plot
orbit data from BPMs. You can add them to your tao.init and show them by running place r13
bpm_orbit_x and place r23 bpm_orbit_y.
&t a o _ t e m p l a t e _ p l o t
p l o t%name = ’ bpm_orbit_x ’
d e f a u l t _ g r a p h%x%m a j o r _ d i v _ n o m i n a l = 10
d e f a u l t _ g r a p h%x%l a b e l = ’ ’
p l o t%x _ a x i s _ t y p e = ’ index ’
p l o t%n_graph = 1
/

&t a o _ t e m p l a t e _ g r a p h
graph%name = ’ x ’
graph_index = 1
graph%box = 1 , 1 , 1 , 1
graph%t i t l e = ’ H o r i z o n t a l O r b i t (mm) ’
graph%y%l a b e l = ’ X ’
graph%y%m a j o r _ d i v = 4
curve (1)% data_source = ’ data ’
curve (1)% d a t a _ t y p e = ’ orbit .x ’
curve (1)% y _ a x i s _ s c a l e _ f a c t o r = 1000
curve (1)% symbol%c o l o r = " red "
/

&t a o _ t e m p l a t e _ p l o t
p l o t%name = ’ bpm_orbit_y ’
d e f a u l t _ g r a p h%x%m a j o r _ d i v _ n o m i n a l = 10
d e f a u l t _ g r a p h%x%l a b e l = ’ ’
p l o t%x _ a x i s _ t y p e = ’ index ’
p l o t%n_graph = 1
/

&t a o _ t e m p l a t e _ g r a p h
graph%name = ’ y ’
graph_index = 1
graph%box = 1 , 1 , 1 , 1
graph%t i t l e = ’ V e r t i c a l O r b i t (mm) ’
graph%y%l a b e l = ’ Y ’
graph%y%m a j o r _ d i v = 4
curve (1)% data_source = ’ data ’
curve (1)% d a t a _ t y p e = ’ orbit .y ’
curve (1)% y _ a x i s _ s c a l e _ f a c t o r = 1000
/

6. Before we run the optimization, we can choose which variables to change and which data
to optimize with run and veto commands. For example, the sawtooth orbit is entirely in the
x-direction, so we can ignore vkickers and orbit.y for this orbit correction with:
veto var v k i c k e r
v e t o data o r b i t . y

Collider Ring Design Tutorial using Bmad 78

 Run the optimizer and check if the orbit is fixed. Write the lattice with optimized kicker
strengths into a new file ring.bmad.

14.3 Example: Orbit Correction with Quadrupole Misalignments

1. Let’s start from ring.bmad that we created in chapter §14.2. Add random offsets to all
quadrupoles in the lattice. We can first assume that x-offsets of quadrupoles follow a Gaus-
sian distribution of σ = 10 µm with a 3σ cutoff. You can do this with Tao command "set ele
quadrupole::* x_offset = 1e-5*ran_gauss(3)". The ran_gauss(sig_cut) command returns
an array of Gaussian distributed random variables with unit RMS truncated at sig_cut.
2. Correct the orbit using the same optimization process. You can reuse the tao.init we wrote
for example §14.2.

3. If the misalignment amplitude is large, the orbit could become unstable and the optimizer will
have a hard time finding a solution. Try larger misalignments of σ = 100 µm with "set ele
quadrupole::* x_offset = 1e-5*ran_gauss(3) and correct the orbit. This will likely fail and
you’ll see many error messages.
4. One approach to avoid unstable orbits is correcting the orbit with an open lattice first. Reini-
tialize Tao to start fresh from the beginning. Use command cut to change the lattice geometry
from closed to open. Tao now uses the single-turn orbit instead, so it won’t complain even if
the closed orbit is unstable.
5. We can now run the optimizer and correct the single-turn orbit as close to 0 as possible. After
the single-turn orbit is corrected, use command cut again to change the lattice geometry back
to closed and Tao will calculate the periodic orbit. Since the orbit excursions are now much
smaller, the periodic orbit should be far away from the unstable region. Run the optimizer
again to correct the periodic orbit to 0.
6. unstable.lattice is a special datum that can be used in an optimization to avoid unstable
solutions. For lattices with a closed geometry, it is 0 if the ring is stable. If the closed orbit is
unstable, its value will be positive. This helps the optimizer find a solution in the stable region.
You can declare it in tao.init as follows:
&tao_d2_data
d2_data%name = ’ u n s t a b l e ’
n_d1_data = 1
/

&tao_d1_data
ix_d1_data = 1
d1_data%name = ’ l a t ’
datum ( 1 ) = " u n s t a b l e . l a t t i c e " " " " " " " " t a r g e t " 0 100
/

Collider Ring Design Tutorial using Bmad 79

14.4 Exercises
1. Zero orbit at IP: Use 4 horizontal/vertical kickers around the IP (CH/V_104 to CH/V_107, 8
total kickers) to make the orbit exactly 0 at the IP without affecting the rest of the ring.

Collider Ring Design Tutorial using Bmad 80

A Python/PyTao Interface

PyTao is a Python wrapper on top of Tao that allows users to access the Tao library via ctypes
and pexpect. More information can be found at https://bmad-sim.github.io/pytao/.

A.1 Installation

The Bmad Distribution must be installed before installing PyTao. If Bmad is installed via a release
tarball, the Bmad Distribution must be compiled with the ACC_ENABLE_SHARED="Y" flag
set in the bmad_dist/util/dist_prefs file.
PyTao can be installed in three different ways:
1) Using setuptools
python setup . py i n s t a l l

2) Using pip
# From PyPI d i s t r i b u t i o n
p i p i n s t a l l pytao

# o r from t h e source f o l d e r
pip i n s t a l l .

3) Using conda
conda i n s t a l l −c conda− f o r g e pytao

A.2 Basic Examples

A.2.1 Initializing Tao

While running Python, To run Tao while running Python, first import the Pytao package:
>>> from pytao i m p o r t Tao

Tao is the basic object in PyTao. Anything used to initialize Tao on the command line can be
used to initialize a Tao object in Python. For example, a Tao object is created with -init to use a
specific tao.init file or with -lat to use a specific lattice file:
>>> t a o = Tao ( " − i n i t l a t t i c e s / 1 _FoDoA / a_Arc / t a o . i n i t − n o p l o t " )

A.2.2 Send a Command

Anything that you would normally type at a Tao> prompt on the command line can be sent as a
string using the tao.cmd command. The return is a list of output strings. To send a command:

Collider Ring Design Tutorial using Bmad 81

 >>> t a o . cmd ( " show l a t 1 : 1 0 " )

User can also send a list of commands using tao.cmds. This returns the corresponding list of
outputs:
>>> t a o . cmds ( [ " s e t l a t t i c e model= design " , " s e t e l e Q00W x _ o f f s e t = 1e − 6 " ] )

A.2.3 Jupyter magic %%tao

There is an alternative way to send commands to Tao directly in a Jupyter notebook, using the
%%tao command. Multiple lines can be executed in one code block:
%%t a o
show l a t 1:10
show e l e 4

A.2.4 Interface Commands

Output from the show command is designed to be human-readable. To get data suitable for
parsing in Python, Tao has a set of special commands under python. See the python section in
the Tao manual for more details, or use help:
%%t a o
h e l p python

Some commands have array_out options. For example, this will return nothing:
t a o . cmd ( " python l a t _ l i s t − a r r a y _ o u t 1@0>>Q * | model o r b i t . f l o o r . x " )

But calling tao.cmd_real on the same command will return the data as an array from an internal
pointer:
t a o . cmd_real ( " python l a t _ l i s t − a r r a y _ o u t 1@0>>Q * | model o r b i t . f l o o r . x " )

For convenience, all of these commands are also available as methods of the Tao class, and the
outputs are automatically parsed.
For example, to get the orbit at an s position:
tao . o r b i t _ a t _ s ( s _ o f f s e t =1.2)

To evaluate and return data values:

t a o . e v a l u a t e ( " data : : cbar . 1 1 [ 1 : 1 0 ] | model " )

One very useful method to extract array data is tao.lat_list. For example, to get the locations
and orbits for all elements:
s = tao . l a t _ l i s t ( " * " , " ele . s " )
x = t a o . l a t _ l i s t ( " * " , " o r b i t . vec . 1 " )
y = t a o . l a t _ l i s t ( " * " , " o r b i t . vec . 3 " )

Collider Ring Design Tutorial using Bmad 82

 A detailed list of parameters that can be extracted using tao.lat_list can be obtained via:
?tao . l a t _ l i s t

To see all the available method commands:

from pytao i m p o r t interface_commands

all_cmds = [ name f o r name i n d i r ( Tao ) i f n o t name . s t a r t s w i t h ( " _ " ) ]

f o r cmd i n all_cmds :
p r i n t ( cmd )

Each has documentation and an example associated with it:

? t a o . data_d2

Unfortunately there can only be one Tao instance per process, because the internal structures
are held in memory and accessed via ctypes. So this will replace the current Tao session in
memory.

B Answers to Selected Exercises

B.1 Chapter 2
Exercise 5:
The set command:
s e t g l o b a l n _ o p t i _ c y c l e s = 100

B.2 Chapter 8
Exercise 1:
The phase space momenta px , py and pz do not change through a drift and therefore have the
same values at the end of the lattice as the beginning. Since py is zero, y will be zero at the
end. The horizontal momentum Px (not to be confused with the phase space momentum)

Px = (1 + pz ) px P0 = 0.4 P0 (4)

where P0 is the reference momentum. The longitudinal momentum Ps is

»
Ps = (1 + pz ) 1 − p2x − p2y P0 = 3.97994974842648 P 0 (5)

Given the initial starting position of x0 = 0, the x position at the end is

Px
x = x0 + L = 0.20100756305184242 meters (6)
Ps
where L is the length of the drift.

Collider Ring Design Tutorial using Bmad 83

 To calculate z at the end, the particle time t and reference particle time tref at the end must be
computed. The reference time is
L 2
tref = tref0 + = (7)
βref c c

where tref0 is the beginning reference time which is zero and the reference beta βref is approxi-
mated to be unity. The particle time is
p
L 1 + (Px /Ps )2 + (Py /Ps )2 2.010075630518424
t = t0 + = (8)
βc c

where t0 is the beginning particle time which is zero and the particle beta is approximated to
be unity. the z position at the end, given that the initial position z0 is zero, is then

z = z0 + β c (tref − t) = −0.010075630518424195 meters (9)

Comparing the computed z here with what Bmad calculates shows a tiny difference due to the
approximation made that β = βref = 1.

B.3 Chapter 9
Exercise 2:
In the cavity.bmad lattice file replace the appropriate lines with
b e g i n n i n g [ p0c ] = 2 * mass_of ( He )
l c : l c a v i t y , l = 1e −6 , v o l t a g e = mass_of ( He ) , r f _ f r e q u e n c y = 1e9
p a r t i c l e _ s t a r t [ z ] = 1e−3

The command show ele lc will show that the beginning beta is 0.740 and the ending beta is
0.916 The ratio of the betas is the same ratio as the ratio of the beginning z (1.00 mm) to
ending z (1.24 mm).
Exercise 3:
Approximately, for phi0_err values above about 0.2502 or below -0.2502 the particle will not
make it through the lcavity.

B.4 Chapter 11
Exercise 1:
A knot based overlay to replace ov2 would be:
k2 : o v e r l a y = { q [ k1 ] : { 0 , 0 . 7 } , q [ x _ o f f s e t ] : { 0 , 0 . 1 } } ,
v a r = { hh } , hh = 0 . 0 1 , x_knot = { 0 , 1 }

Exercise 2:
A group element to vary the entrance edge of element B:

Collider Ring Design Tutorial using Bmad 84

 gedge : group = { B [ s t a r t _ e d g e ] : ds } , v a r = { ds }

Exercise 3:
In the simple.bmad lattice file add:
gg : g i r d e r = { b , q }

B.5 Chapter 13
Exercise 1:
The show curve r23 command will show that the curves are named r23.g.x and r23.g.y. [Note:
using the alternative name that begins with “orbit” will not work here since there are multiple
orbit plots.] To use the r23.g.y curve to draw the design horizontal orbit use the commands:
s e t curve r23 . g . y d a t a _ t y p e = o r b i t . x
s e t curve r23 . g . y l e g e n d _ t e x t = "X"
s e t curve r23 . g . y component = design

Note: By default, orbit plots have a non-blank legend_text which is why the legend_text needs
to be changed. What happens if, instead of setting to “X”, the legend_text is set to a blank
string?
Exercise 2:
Define a setit command by:
a l i a s s e t i t set ele q vkick = [ [ 1 ] ]

Collider Ring Design Tutorial using Bmad 85