tikz-palattice - draw particle accelerator

lattices with TikZ

Jan Schmidt <[email protected]>

v2.3 (March 9, 2017)

The tikz-palattice package allows for drawing a map of a particle accel-

erator just by giving a list of elements - similar to lattice files for simula-
tion software. The package includes 12 common element types like dipoles,
quadrupoles, cavities or screens, as well as automatic labels with element
names, a legend, a rule and an environment to fade out parts of the accel-
erator. The coordinate of any element can be saved and used for custom
tikz drawings or annotations. Thereby, lattices can be connected to draw
injection/extraction or even a complete accelerator facility.

photon camera
M21
QF22
SSV1

MSE22
KV22
SSH1

KV21

M22
QD21
QF1

BGO-OD (E2) Tagger

QD23 M20
Dipole
SSV3

QD1

MSE23
SSH3

SSH2
SSV2

QD2
20
KV

QF2 M23
0

Quadrupole
QF2

MB2
19
SF

QF24
MB1
QN1
KV24
Sextupole
SD 19
19
KV

19

QN2
QD

hadron physics
MB3 M24 M18
SSH3

QD25 KV18
Corrector
QF2
QF18
Kicker
experiments QD2
SSV3
M25
SX17
LQ17

KV17 Cavity
Tagger PETRA2
KV25

QF26
QD17 Solenoid
M5 TJQD16

PETRA1
Source
M26

Crystal Barrel (E1) LQ16

SX16
Screen
QF16
KV15
KV26
SD26
Combined Function
QD27

photon camera Compton- M15

Polarimeter M27
QD15

KV14

KV27
SF27
B2 S1
M3 M4 QF28

VC1
K1 S2 QF14
B1
M28 KV13

M2 M5

S3
KV28
QD29
ELSA Stretcherring M13

QD13

0.5 - 3.2 GeV

KV1 KV12
QA
KV2 M29
M1

Booster- M6

KV3
QB
KV29
IJK29
M12

QF30

Synchrotron
VC2
INJSEPT QF12
B3
SF11
KV11

irradiation QC

0.5 - 1.2 GeV

KV30

M12 M7 MSI30

area M2
Q8 QD31 M11

QT2
QT1
Q6Q7 VC3 M31
M1 QD11
K2
SD10
Q5 KV31 KV10
Q4 KD MSI31
QF32
Q3 M11 M8 SX32
LQ32
KV32 M10
EKS SQ32

LINAC 1
Q7 K3
Q2
Q1 M10 M9 TJQ32 QF10
DORIS QD1

20 MeV KV01
KV09 synchrotron light
SQ1

Q6
LQ1 M9 diagnostic area
SX1
QF2
IJK2 QD9
KV02
Q5
SSV3
SSH3

Q4 M2 M8

Source of pol. e−
IR CS4
CS3
3
QD

SSV2
03

SSH2
KV 3

CS2
SD

M90 KV08
QF3 QD4
Q3 Q2 Q1
QF8 QD2
Area for
K3

MB
IJ

CS1
QF

M7
04
KV 4
SF

LINAC 2 QD7
MSE7
QF1
Detector Tests (E3)
KV05

SSV1
QD5

M4
SSH1
KV06
MSE6
QF6

M6
M5

26 MeV

0m 5m 10 m 15 m

Figure 1: The Electron Stretcher Facility ELSA at Bonn University, drawn with tikz-
palattice

1
Copyright 2017 Jan Schmidt
Permission is granted to distribute and/or modify both the documentation and the code
under the conditions of the LaTeX Project Public License, either version 1.3 of this
license or (at your option) any later version. The latest version of this license is in
http://www.latex-project.org/lppl.txt

Contents
1 Installation 2
1.1 Copy tikz-palattice.sty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2 Required packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Basic Usage 3

3 The lattice Environment 4

4 Within lattice Environment 4

4.1 Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4.1.1 Dipole Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
4.2 Orientation of the lattice . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
4.3 Rule and Legend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
4.4 Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.5 Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.6 Fade Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.7 Access lattice Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

5 Changelog 10

6 TODO 10

1 Installation
1.1 Copy tikz-palattice.sty
You just need to copy the lattice.sty file to a place where your LATEX installation can
recognize it. This can be

• the same folder as your .tex document or

• in the LATEX system or user tree.

E.g. to add it to the system tree for texlive under ubuntu:

sudo mkdir −p /usr/local/share/texmf/tex/latex/lattice/
sudo cp lattice.sty /usr/local/share/texmf/tex/latex/lattice/
sudo mktexlsr

2
For this path there is also a Makefile prepared, so just enter
sudo make install
Otherwise read the documentation of your LATEX distribution.

1.2 Required packages

• tikz

• siunitx

• ifthen

• xargs

• etoolbox

• iflang

2 Basic Usage
Basically, an accelerator lattice is drawn by writing element commands one after the
other. White spaces and newlines are ignored. Usually you will use one drift and one
other element alternately:
\begin{lattice}
\source{Gun}{0.4}
\drift{0.267}
\quadrupole{Q1}{0.4}
\drift{0.29}
\dipole{M1}{0.8}{30} VC1
\drift{0.29} M1
\kicker{VC1}{0.1} Gun Q1
\drift{0.2}
\end{lattice}
Descriptions of the commands are given in section 4. There are 5 examples coming with
this package. Some of the drawings are shown in this document. Please look at the
separate tex-files for the source code.

Some general remarks:

• it is recommended to draw lattices using \documentclass{standalone} especially for

larger beamlines.

• lengths are set in meter, so you write {1.32} for 1.32 m.

• beamline with angle 0° goes to the right, positive angles bend counter clockwise.

3
 • some commands use the TikZ north/east/south/west terms. east of an element is
always where the beam leaves the element (downstream) and west is where the
beam enters the element (upstream).

• settings (colors, font, rotatelabel,. . . ) changed within a scope environment are set
back to the previous values outside of scope

• picture scale: for lattice scale=1 an element of 1m length is plotted with 2 cm

length

Below, the arguments of commands are given in angle brackets. The values after an
equal sign are default values of optional arguments. E.g. hscale=1 i indicates that the
default value of "scale" is 1.

3 The lattice Environment

To draw a lattice just add
\usepackage{tikz−palattice}
to your preambel and use the lattice environment with
\begin{lattice}[hscale=1 i][htikz options=i]
...
\end{lattice}
The lattice environment contains a tikzpicture environment in which the lattice is drawn
using usual tikz commands. The lattice environment has 2 optional arguments:

1. hscale=1 i scales whole picture (default is 1).

2. htikz options=i gives any options for the tikzpicture (e.g. overlay, default is none).

4 Within lattice Environment

4.1 Elements
Here is a list of all implemented element types. The element names are self-explanatory:
\drift{hlength/mi}[hname=i]
\dipole{hnamei}{harc length/mi}{hbending angle/degi}[htype=si][hthickness/m=0.6 i]
\quadrupole{hnamei}{hlength/mi}[hthickness/m=0.5 i]
\sextupole{hnamei}{hlength/mi}[hthickness/m=0.3 i]
\corrector{hnamei}{hlength/mi}[hthickness/m=0.25 i]
\kicker{hnamei}{hlength/mi}[hthickness/m=0.25 i]
\cavity{hnamei}{hlength/mi}[hthickness/m=0.45 i]
\solenoid{hnamei}{hlength/mi}[hthickness/m=0.2 i]
\beamdump{hnamei}{hlength/mi}[hthickness/m=0.5 i]
\source{hnamei}{hlength/mi}[hthickness/m=0.5 i]
\screen{hnamei}[hlength/m=0.2 i]

4
 marker 1 marker 2

Q42

M1
MySource Q1 VC1 S1 Q2 Space left! Acceleration?

Figure 2: Example 1

\valve{hnamei}
\marker{hnamei}[hlength/m=0.35 i] % a line perpendicular to the beamline, see Fig. 2

4.1.1 Dipole Types

The dipole option htype=si allows to select different dipole shapes. It is shown in exam-
ple 2. Possible values are:

s: sector magnet r: rectangle magnet br: bend rectangle magnet

If you use any other letters, also the default (s) is used.

4.2 Orientation of the lattice

\start{hcoordinate/mi}
sets starting point of the lattice. Use it before the first element. hcoordinate/mi is of
form (x,y) or any tikz label, e.g. (mylabel.east) You can use this with \savecoordinate
(section 4.7) to connect lattices, but it is recommended to do this via \goto (see below).
Both are shown in example 3.
\rotate{hangle/degi}
bends the beamline by the given angle.
\setangle{hangle/degi}
sets the beamline angle to the given angle. The next element is drawn with beam axis
in this direction.
\goto{hcoordinate namei}
sets current position and angle to values saved with \savecoordinate (section 4.7). Use this
to connect lattices and draw injection, extraction or even a complete accelerator facility.
This is shown in example 3.

5
 M5 M4

M6 al M3
sign

M2
M7

M8 M1

0m 2m 4m 6m

Figure 3: From example 3

4.3 Rule and Legend

\drawrule{hposition/mi}[htick distance/m=1 i][hscale=1 i][hheight/m=0.1 i]

draws a rule to visualize the size of the lattice. Coordinate is of form (x,y) or any tikz
label, e.g. (mylabel.east)
\legend{hposition/mi}[hscale=1 i]
draws a legend with all element types that occur in the lattice before this command. The
given hposition/mi is north west (upper left corner) of the legend box. The scale option
scales the whole box including the text, which has the usual label textsize if scale=1.
\completelegend{hposition/mi}[hscale=1 i]
is similar to \legend, but shows all element types.
The legend can be customized with the following two commands. Here is an example
for legend customizations:
\begin{lattice}
\drift{0.2}
\quadrupole{Q1}{0.4}
\drift{0.1}
\kicker{C1}{0.1} Q1 C1 S1
\drift{0.5}
\screen{S1}
\drift{0.2} I am focusing
\setlegendtext{quadrupole}{I am focusing} Kicker
\addlegendentry{What’s that?}{cyan, fill= Screen
violet}
What’s that?
\legend{(0.2,−1)}
\end{lattice}

\setlegendtext{htypei}{htexti}

6
allows to change the text shown in the legend for element type htypei. The legend is
automatically translated to German if ngerman is set with the babel package.
\addlegendentry{htexti}{hstylei}
adds a custom entry to the legend. The style of the legend image can set with hstylei.
All style options for a tikz node are allowed. All custom legend entries appear below the
normal entries.
4.4 Labels
Every element has a text label showing the given element name. The position and ori-
entation of the label is set automatically according to the current angle of the beamline.
Several commands to modify the labels manually are described below. If you want to
disable labels, leave the element names blank or set the label color (section 4.5) to your
background color.
\turnlabels
moves labels to other side of elements (swap with marker labels), while
\northlabels
\southlabels
explicitly sets the labels to north or south (see section 2) of the elements. It is recom-
mended to use these and not \turnlabels, because otherwise the label position at a certain
element is determined by the number of \turnlabels commands before this element.
\rotatelabels{hangle/degi}[hanchor=i]
allows rotation of element labels. The hanchor=i sets the center of rotation (north,
center, south west, . . . ). West corresponds to the labels first character. By default the
anchor is set automatically depending on the current angle of the beamline.
\begin{labeldistance}{hdistance/mi}
...
\end{labeldistance}
sets the distance of text labels to the element center for all elements within this envi-
ronment. Default is 0.35.
\setlabeldistance{hdistance/mi}
\resetlabeldistance
sets the distance of text labels to the element center for all following elements. the reset
command sets the default value. Default is 0.35.
\setlabelfont{hfontsizei}
sets the text label font size. Default is \normalsize.

4.5 Colors
The colors can be changed at any point of the lattice. A setting is valid until the
next color command. The reset commands set the according default color. Use a scope
environment to change a color for a section of a lattice.

7
 \setlinecolor{htypei}{hcolor i}
\resetlinecolor{htypei}
for htypei drift and marker.
\setelementcolor{htypei}{hcolor i}[hgradient color=whitei]
\resetelementcolor{htypei}
for all element types. Set hgradient color=whitei equal to hcolori to "disable" the gradi-
ent.
\setlabelcolor{hcolor i}
for textlabels. Set to background color to hide text labels.

4.6 Fade Out

\begin{fade}[hopacity=0.25 i]
...
\end{fade}
reduces the opacity of all elements within the environment and sets all colors to gray.
So you can fade out regions of the lattice - e.g. for presentations. This can also be used
to completely hide regions by setting hopacity=0.25 i to zero.
Custom drawings and annotations (see section 4.7) can also be faded out automatically.
The tikz style faded provides the appropriate settings: Add faded to the style of any tikz
drawing or node within the lattice environment. If it is drawn within a fade environment,
it is faded out. Else its style is not changed:
\begin{lattice}
\tikzset{mynode/.style={
anchor=west,xshift=7mm,font=\bf,red}}
\setangle{−90}
\drift{0.2}
S1
\sextupole{S1}{0.2}
\drift{0.267}
\begin{fade}[0.4] Q1 a quadrupole!
\quadrupole{Q1}{0.4}
\savecoordinate{Q1}[center]
\node[mynode,faded] at (Q1) {a quadrupole!}; VC1 a kicker!
\drift{0.29}
\end{fade}
\kicker{VC1}{0.1} M1
\savecoordinate{kick}[center]
\node[mynode,faded] at (kick) {a kicker!};
\drift{0.2}
\dipole{M1}{0.8}{30}
\drift{0.29}
\end{lattice}

8
4.7 Access lattice Coordinates
You can use element coordinates to draw anything you want using pgf/tikz.
\savecoordinate{hnamei}[hposition=easti]
saves the coordinate of the previous element to access it later. Position specifies the
exact place of the element. east and center are available (see section 2).

• you can use all tikz/pgf commands within the lattice environment to draw any-
thing.

• You can use this to connect multiple beamlines within a lattice environment
with \goto{name} (recommended, Figure 4 (a)).

• You can use this to connect multiple lattice environments with \start{name}.
Use the tikz overlay option. (Figure 4 (b))

Dipole Dipole
Quadrupole Kicker
Sextupole
Kicker

MB1 MB1
SF1 M3 SF1 M3
QD3 M2 QD3 M2
M1 M1
SSH1 SSH1
SS1 SS1

Septum Septum

QD2 QD2

QF1 QF1

(a) one lattice environment and goto (b) two lattice environments and start

Figure 4: From example 3: Two ways to connect lattices

9
5 Changelog
v2.1 from 2015/02/23 is the first published version.

v2.2 from 2015/03/01

• added \northlabels and \southlabels
• minor legend improvements (label position is now independent of current lattice
settings)
• minor documentation improvements

v2.21 from 2015/03/18

• added faded style (apply fade out to custom annotations)
• fixed sector dipole drawing
• documentation fixes

v2.3 from 2017/03/09

• added \setlegendtext and \addlegendentry
• German legend translation via babel (ngerman)
• legend fixes

6 TODO
What is missing?
• The look of the elements can be improved
• More element types can be added
• ...
I am not an TEX programmer. I basically used the TikZ commands and wrote a bunch
of macros. So there is:
• no error handling implemented
• no dedicated scoping of internal macros (use of lattice with documentclass stan-
dalone recommended)

Known issues:
• A circular lattice can have a significant offset (no closed circle), if the dipole bending
angles are not integer. Probably, this is due to rounding or calculation accuracy.
• Please report bugs!

10