tikz-palattice_documentation.

tikz-palattice - draw particle accelerator
lattices with TikZ
Jan Schmidt <schmidt@physik.uni-bonn.de>
v2.21 (March 18, 2015)
The tikz-palattice package allows for drawing a map of a particle accelerator just by giving a list of elements - similar to lattice files for simulation 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 accelerator. 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.
KV22
QF22
M21
KV21
QD21
M22
QF24
MB1
QN2
KV
SD 19
19
QD
19
KV24
QN1
hadron physics
experiments
M20
M24
MB3
Dipole
Quadrupole
Sextupole
Corrector
Kicker
Cavity
Solenoid
Source
KV
20
QF2
0
19
QD23
MSE23
M23
MB2
SF
QF2
QD1
QD2
SSV2
SSH2
SSV3
SSH3
Tagger
SSH1
SSV1
QF1
photon camera
BGO-OD
M18
SSH3
QD25
QF2
KV18
QF18
SX17
LQ17
SSV3
M25
QD2
Tagger
PETRA2
KV25
Crystal Barrel
KV17
QD17
TJQD16
QF26
M5
PETRA1
M26
LQ16
SX16
QF16
KV15
KV26
SD26
QD27
ComptonPolarimeter
photon camera
M15
QD15
M27
KV14
M3
B1
B2 S1
KV27
SF27
QF28
M4
VC1
K1
QF14
S2
KV13
M28
KV28
QD29
S3
INJSEPT
irradiation
area
M12
M2
QT2
QT1
M1
KV1
QA
KV2
BoosterSynchrotron
0.5 - 1.2 GeV
M1
Q8
M29
M13
QD13
KV12
M6
KV29
M12
KV3
QB
QF30
VC2
QF12
B3
SF11
KV11
QC
KV30
M7
M11
QD31
Q6Q7
VC3
K2
M31
QD11
SD10
KV10
KV31
Q5
Q4
ELSA Stretcherring
0.5 - 3.2 GeV
M5
M2
KD
Q3
M11
M8
QF32
SX32
LQ32
KV32
SQ32
LINAC 1
EKS
Q7
M10
K3
Q2
Q1
M10
DORIS
M9
20 MeV
TJQ32
QD1
KV01
QF10
synchrotron light
diagnostic area
KV09
SQ1
Q6
M9
LQ1
SX1
QF2
QD9
KV02
Q5
M2
Q4
Q3 Q2 Q1
M8
QD3
SD3
KV03
Source of pol. e−
M90
QF4
SF
KV 4
04
QD5
KV05
QD7
M4
M5
QF6
KV06
3
MSE2
LINAC 2
QD1
MB
QF1
M6
26 MeV
0m
QD2
QF2
KV08
QF8
M7
5m
area for
detector tests
(under construction)
10 m
15 m
Figure 1: The Electron Stretcher Facility ELSA at Bonn University, drawn with tikzpalattice
1
Copyright 2015 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
1.1 Copy tikz-palattice.sty . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 Required packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2
2
3
2 Basic Usage
3
3 The lattice Environment
4
4 Within lattice Environment
4.1 Elements . . . . . . . . .
4.2 Orientation of the lattice .
4.3 Rule and Legend . . . . .
4.4 Labels . . . . . . . . . . .
4.5 Colors . . . . . . . . . . .
4.6 Fade Out . . . . . . . . .
4.7 Access lattice Coordinates
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4
4
5
5
6
7
7
8
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
For this path there is also a Makefile prepared, so just enter
2
sudo make install
Otherwise read the documentation of your LATEX distribution.
1.2 Required packages
• tikz
• siunitx
• ifthen
• xargs
• etoolbox
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}
\drift{0.29}
\kicker{VC1}{0.1}
\drift{0.2}
\end{lattice}
VC1
Gun
Q1
M1
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.
• 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).
3
• 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]
\valve{hnamei}
\marker{hnamei}[hlength/m=0.35 i] % a line perpendicular to the beamline, see Fig. 2
The dipole option htype=si allows to select different dipole shapes. It is shown in example 2. Possible values are:
4
• s for a sector magnet (entrance/exit surface 90 degree to beampipe)
• br for a bend rectangle magnet (parallel entrance/exit surfaces)
• r for a rectangle magnet
If you use any other letters, also the default (s) is used.
marker 1
marker 2
Q42
M1
MySource Q1 VC1
S1
Q2
Space left!
Acceleration?
Figure 2: Example 1
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.
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]
5
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.
M5
M4
al
sign
M6
M3
M2
M7
M8
0m
M1
2m
4m
6m
Figure 3: From example 3
4.4 Labels
Every element has a text label showing the given element name. The position and orientation 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 recommended 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.
6
\begin{labeldistance}{hdistance/mi}
...
\end{labeldistance}
sets the distance of text labels to the element center for all elements within this environment. 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.
\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 gradient.
\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:
7
\begin{lattice}
\tikzset{mynode/.style={
anchor=west,xshift=7mm,font=\bf,red}}
\setangle{−90}
\drift{0.2}
\sextupole{S1}{0.2}
\drift{0.267}
\begin{fade}[0.4]
\quadrupole{Q1}{0.4}
\savecoordinate{Q1}[center]
\node[mynode,faded] at (Q1) {a quadrupole!};
\drift{0.29}
\end{fade}
\kicker{VC1}{0.1}
\savecoordinate{kick}[center]
\node[mynode,faded] at (kick) {a kicker!};
\drift{0.2}
\dipole{M1}{0.8}{30}
\drift{0.29}
\end{lattice}
S1
Q1
VC1
a quadrupole!
a kicker!
M1
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 anything.
• You can use this to connect multiple beamlines within a lattice environment
with \goto{name} (recommended, Figure 4 (b)).
• You can use this to connect multiple lattice environments with \start{name}.
Use the tikz overlay option. (Figure 4 (a))
8
Dipole
Quadrupole
Sextupole
Kicker
Dipole
Kicker
MB1
MB1
SF1
M3
SF1
M3
QD3
M2
M1
QD3
M2
M1
SSH1
SSH1
SS1
SS1
Septum
Septum
QD2
QD2
QF1
QF1
(a) two lattice environments and start
(b) one lattice environment and goto
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
6 TODO
What is missing?
• manually adding and editing legend entries
• 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 standalone 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