summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/tikz-palattice/tikz-palattice_documentation.tex
blob: 201c4e44d7c58cb4c4fc57b641e43db29273a306 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
%% tikz-palattice_documentation.tex
%% Copyright 2015 J. Schmidt
%% tikz-palattice LaTeX package
% 
% This work may be distributed and/or modified 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
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
% 
% This work has the LPPL maintenance status `maintained'.
% 
% The Current Maintainer of this work is J. Schmidt.
% 
% This work consists of the files tikz-palattice.sty and tikz-palattice_documentation.tex
% and the 5 example files example1_linear.tex, example2_circular.tex,
% example3_coordinates.tex, example4_labels.tex and elsa.tex

\documentclass[a4paper]{scrartcl}
\usepackage[english]{babel}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage{fixltx2e}
\usepackage{graphicx}
\usepackage{subcaption}
\usepackage{amsmath}
\usepackage{textcomp}
\usepackage{marvosym}
\usepackage{amssymb}
\usepackage[colorlinks]{hyperref}
\usepackage{siunitx}
\usepackage{listings}
\usepackage{xcolor}
\usepackage{tikz-palattice}

\newcommand{\option}[1]{{\color{blue}$\langle$\textit{#1}$\rangle$}}
\newcommand{\optiondef}[2]{{\color{green!50!black}$\langle$\textit{#1=#2}$\rangle$}}
\newcommand{\tikzlabel}{Ti\textit{k}Z}

\author{Jan Schmidt <schmidt@physik.uni-bonn.de>}
\date{v2.2 (March 01, 2015)}
\title{tikz-palattice - draw particle accelerator lattices with \tikzlabel}

\hypersetup{
  pdftitle={tikz-palattice - draw particle accelerator lattices with \tikzlabel},
  pdfauthor={Jan Schmidt}
}

\begin{document}

\definecolor{keycolor}{RGB}{172, 42, 42}
\lstset{
basicstyle=\small\sffamily,
backgroundcolor=\color{gray!20},
%numbers=left,
numberstyle=\tiny,
breaklines=true,
%frame=l,
xleftmargin=\parindent,
columns=fullflexible,
showstringspaces=false,
keywordstyle=\bfseries\color{keycolor},
commentstyle=\color{black!50},
identifierstyle=,%\color{blue},
stringstyle=,
escapeinside={(*}{*)}
}

\maketitle

\begin{abstract}
  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.
\end{abstract}


\begin{figure}[h]
  \centering
  \includegraphics[width=\textwidth]{elsa.pdf}
  \caption{The Electron Stretcher Facility ELSA at Bonn University, drawn with
    tikz-palattice}
\label{fig:elsa}
\end{figure}


\clearpage
\parindent=0pt
Copyright 2015 Jan Schmidt

\medskip
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

\tableofcontents

\section{Installation}
\label{sec-1}
\subsection{Copy tikz-palattice.sty}
\label{sec-1-1}
You just need to copy the lattice.sty file to a place where your \LaTeX{} installation can recognize it.
This can be
\begin{itemize}
\item the same folder as your .tex document or
\item in the \LaTeX{} system or user tree.
\end{itemize}
E.g. to add it to the system tree for texlive under ubuntu:
\begin{lstlisting}
sudo mkdir -p /usr/local/share/texmf/tex/latex/lattice/
sudo cp lattice.sty /usr/local/share/texmf/tex/latex/lattice/
sudo mktexlsr
\end{lstlisting}
For this path there is also a Makefile prepared, so just enter
\begin{lstlisting}
sudo make install
\end{lstlisting}
Otherwise read the documentation of your \LaTeX{} distribution.

\subsection{Required packages}
\label{sec-1-2}
\begin{itemize}
\item tikz
\item siunitx
\item ifthen
\item xargs
\item etoolbox
\end{itemize}

\lstset{language=[LaTeX]TeX}

\section{Basic Usage}
\label{sec:remarks}

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 \lstinline+drift+
and one other element alternately:

\begin{minipage}[c]{0.5\textwidth}
\begin{lstlisting}
  \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}
\end{lstlisting}
\end{minipage}
%
\begin{minipage}[c]{0.5\textwidth}
  \begin{center}
    \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}
  \end{center}
\end{minipage}


Descriptions of the commands are given in section \ref{sec-5}. 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.

\paragraph{Some general remarks:}
\begin{itemize}
\item it is recommended to draw lattices using \lstinline+\documentclass{standalone}+
  especially for larger beamlines.
\item lengths are set in meter, so you write \{1.32\} for \SI{1.32}{\m}.
\item beamline with angle \SI{0}{\degree} goes to the right, positive angles bend counter clockwise.
\item some commands use the \tikzlabel{} \textit{north/east/south/west} terms. \textit{east}
  of an element is always where the beam leaves the element (downstream) and \textit{west} is where the
  beam enters the element (upstream).
\item settings (colors, font, rotatelabel,\ldots{}) changed within a \verb+scope+ environment are set back to the previous values outside of \verb+scope+
\item picture scale: for lattice scale=1 an element of 1m length is plotted with \SI{2}{\cm} length
\end{itemize}

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



\section{The lattice Environment}
\label{sec-4}

To draw a lattice just add
\begin{lstlisting}
\usepackage{lattice}
\end{lstlisting}
to your preambel and use the lattice environment with
\begin{lstlisting}
  \begin{lattice}[(*\optiondef{scale}{1}*)][(*\optiondef{tikz options}{}*)]
    ...
  \end{lattice}
\end{lstlisting}
The \lstinline+lattice+ environment contains a \lstinline+tikzpicture+ environment in
which the lattice is drawn using usual tikz commands. The \lstinline+lattice+ environment
has 2 optional arguments:
\begin{enumerate}
\item \optiondef{scale}{1} scales whole picture (default is 1).
\item \optiondef{tikz options}{} gives any options for the \lstinline+tikzpicture+ (e.g.
  overlay, default is none).
\end{enumerate}


\section{Within lattice Environment}
\label{sec-5}

\subsection{Elements}
\label{sec-5-1}

 Here is a list of all implemented element types. The element names are self-explanatory:
\begin{lstlisting}
  \drift{(*\option{length/m}*)}[(*\optiondef{name}{}*)]
  \dipole{(*\option{name}*)}{(*\option{arc length/m}*)}{(*\option{bending angle/deg}*)}[(*\optiondef{type}{s}*)][(*\optiondef{thickness/m}{0.6}*)]
  \quadrupole{(*\option{name}*)}{(*\option{length/m}*)}[(*\optiondef{thickness/m}{0.5}*)]
  \sextupole{(*\option{name}*)}{(*\option{length/m}*)}[(*\optiondef{thickness/m}{0.3}*)]
  \corrector{(*\option{name}*)}{(*\option{length/m}*)}[(*\optiondef{thickness/m}{0.25}*)]
  \kicker{(*\option{name}*)}{(*\option{length/m}*)}[(*\optiondef{thickness/m}{0.25}*)]
  \cavity{(*\option{name}*)}{(*\option{length/m}*)}[(*\optiondef{thickness/m}{0.45}*)]
  \solenoid{(*\option{name}*)}{(*\option{length/m}*)}[(*\optiondef{thickness/m}{0.2}*)]
  \beamdump{(*\option{name}*)}{(*\option{length/m}*)}[(*\optiondef{thickness/m}{0.5}*)]
  \source{(*\option{name}*)}{(*\option{length/m}*)}[(*\optiondef{thickness/m}{0.5}*)]
  \screen{(*\option{name}*)}[(*\optiondef{length/m}{0.2}*)]
  \valve{(*\option{name}*)}
  \marker{(*\option{name}*)}[(*\optiondef{length/m}{0.35}*)] % a line perpendicular to the beamline, see Fig. (*\ref{fig:example1}*)
\end{lstlisting}

The \lstinline+dipole+ option \optiondef{type}{s} allows to select different dipole
shapes. It is shown in example~2. Possible values are:
\begin{itemize}
\item s for a sector magnet (entrance/exit surface 90 degree to beampipe)
\item br for a bend rectangle magnet (parallel entrance/exit surfaces)
\item r for a rectangle magnet
\end{itemize}
If you use any other letters, also the default (s) is used.


\begin{figure}[ht]
  \centering
  \includegraphics[width=10cm]{example1_linear}
  \caption{Example 1}
  \label{fig:example1}
\end{figure}


\subsection{Orientation of the lattice}
\label{sec-5-2}

\begin{lstlisting}
  \start{(*\option{coordinate/m}*)}
\end{lstlisting}
sets starting point of the lattice. Use it before the first element. \option{coordinate/m}
is of form (x,y) or any tikz label, e.g. (mylabel.east) You can use this with
\lstinline+\savecoordinate+ (section \ref{sec:coords}) to connect lattices, but it is
recommended to do this via \lstinline+\goto+ (see below). Both are shown in example 3.

\begin{lstlisting}
  \rotate{(*\option{angle/deg}*)}
\end{lstlisting}
bends the beamline by the given angle.

\begin{lstlisting}
  \setangle{(*\option{angle/deg}*)}
\end{lstlisting}
sets the beamline angle to the given angle. The next element is drawn with beam axis in
this direction.

\begin{lstlisting}
  \goto{(*\option{coordinate name}*)}
\end{lstlisting}
sets current position and angle to values saved
with \lstinline+\savecoordinate+ (section \ref{sec:coords}).
Use this to connect lattices and draw injection, extraction or even a complete accelerator
facility. This is shown in example 3.



\subsection{Rule and Legend}
\label{sec:rule-legend}

\begin{lstlisting}
  \drawrule{(*\option{position/m}*)}[(*\optiondef{tick distance/m}{1}*)][(*\optiondef{scale}{1}*)][(*\optiondef{height/m}{0.1}*)]
\end{lstlisting}
draws a rule to visualize the size of the lattice. Coordinate is of form (x,y) or any tikz
label, e.g. (mylabel.east)

\begin{lstlisting}
  \legend{(*\option{position/m}*)}[(*\optiondef{scale}{1}*)]
\end{lstlisting}
draws a legend with all element types that occur in the lattice before this command.
The given \option{position/m} 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.

\begin{lstlisting}
  \completelegend{(*\option{position/m}*)}[(*\optiondef{scale}{1}*)]
\end{lstlisting}
is similar to \lstinline+\legend+, but shows all element types.


\begin{figure}[h]
  \centering
  % this is the ring from example 2, but plotted smaller (30%).
  % the element sizes (in meter) are the same - as the rule indicates.
  \begin{lattice}[0.3]
    \setlabelfont{\tiny}
    \begin{labeldistance}{0.3}
      \drift{1}
      \dipole{M1}{2}{45}
      \drift{1}
      \turnlabels
      \dipole{M2}{2}{45}
      \turnlabels
      \drift{1}
      \dipole{M3}{2}{45}
      \drift{1}
      \savecoordinate{myCoord1}[center]
      \dipole{M4}{2}{45}
      \drift{1}
      \dipole{M5}{2}{45}
      \drift{1}
      \dipole{M6}{2}{45}
      \drift{1}
      \savecoordinate{myCoord2}[center]
      \dipole{M7}{2}{45}
      \drift{1}
      \dipole{M8}{2}{45}
      \drawrule{(-2.5,-1)}[2]
    \end{labeldistance}
    % custom drawing using saved coordinates (to center of drifts)
    \draw[->, thick] (myCoord2) -- (myCoord1) node[midway,fill=white,rotate=20] {signal};
  \end{lattice}
\caption{From example 3}
\label{fig:fromexample3}
\end{figure}


\subsection{Labels}
\label{sec: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
\ref{sec:colors}) to your background color.

\begin{lstlisting}
  \turnlabels
\end{lstlisting}
moves labels to other side of elements (swap with marker labels), while
\begin{lstlisting}
  \northlabels
  \southlabels
\end{lstlisting}
explicitly sets the labels to north or south (see section \ref{sec:remarks}) of the
elements. It is recommended to use these and not \lstinline+\turnlabels+, because
otherwise the label position at a certain element is determined by the number of
\lstinline+\turnlabels+ commands before this element.

\begin{lstlisting}
  \rotatelabels{(*\option{angle/deg}*)}[(*\optiondef{anchor}{}*)]
\end{lstlisting}
allows rotation of element labels.
The \optiondef{anchor}{} sets the center of rotation (north, center, south west,
\ldots{}). West corresponds to the labels first character. By default the anchor is set
automatically depending on the current angle of the beamline.

\begin{lstlisting}
  \begin{labeldistance}{(*\option{distance/m}*)}
    ...
  \end{labeldistance}
\end{lstlisting}
sets the distance of text labels to the element center for all elements within this
environment. Default is 0.35.

\begin{lstlisting}
  \setlabeldistance{(*\option{distance/m}*)}
  \resetlabeldistance
\end{lstlisting}
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.

\begin{lstlisting}
  \setlabelfont{(*\option{fontsize}*)}
\end{lstlisting}
sets the text label font size. Default is \lstinline+\normalsize+.



\subsubsection{Colors}
\label{sec: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 \lstinline+scope+
environment to change a color for a section of a lattice.

\begin{lstlisting}
  \setlinecolor{(*\option{type}*)}{(*\option{color}*)}
  \resetlinecolor{(*\option{type}*)}
\end{lstlisting}
for \option{type} drift and marker.

\begin{lstlisting}
  \setelementcolor{(*\option{type}*)}{(*\option{color}*)}[(*\optiondef{gradient color}{white}*)]
  \resetelementcolor{(*\option{type}*)}
\end{lstlisting}
for all element types. Set \optiondef{gradient color}{white} equal to \option{color} to
"disable" the gradient.

\begin{lstlisting}
  \setlabelcolor{(*\option{color}*)}
\end{lstlisting}
for textlabels. Set to background color to hide text labels.


\begin{lstlisting}
  \begin{fade}[(*\optiondef{opacity}{0.25}*)]
    ...
  \end{fade}
\end{lstlisting}
 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 \optiondef{opacity}{0.25} to zero.




\subsection{Access lattice Coordinates}
\label{sec:coords}
You can use element coordinates to draw anything you want using pgf/tikz. 

\begin{lstlisting}
  \savecoordinate{(*\option{name}*)}[(*\optiondef{position}{east}*)]
\end{lstlisting}
saves the coordinate of the previous element to access it later. Position specifies the
exact place of the element. \textit{east} and \textit{center} are available (see section
\ref{sec:remarks}).

\begin{itemize}
\item you can use all tikz/pgf commands within the lattice environment to draw anything.
\item You can use this to connect multiple beamlines \textbf{within a lattice environment} with
  \lstinline+\goto{name}+ (recommended, Figure \ref{fig:twoways} (b)).
\item You can use this to connect \textbf{multiple lattice environments} with
  \lstinline+\start{name}+. Use the tikz overlay option. (Figure \ref{fig:twoways} (a))
\end{itemize}




\begin{figure}[h]
\centering
\begin{subfigure}[b]{.45\textwidth}
\centering
 \begin{lattice}[0.8]
    \rotate{90}
    \turnlabels %labels to the left
    \drift{0.5}
    \quadrupole{QF1}{0.3}
    \drift{0.2}
    \kicker{}{0.1}
    \drift{0.07}
    \quadrupole{QD2}{0.3}
    \drift{0.4}
    \setelementcolor{kicker}{cyan}
    \kicker{Septum}{0.5}
    \resetelementcolor{kicker}
    \savecoordinate{Septum}[center] %save to connect other beamline
    \drift{0.8}
    \kicker{}{0.1}
    \drift{0.37}
    \quadrupole{QD3}{0.2}
    \drift{0.17}
    \kicker{}{0.1}
    \drift{0.1}
    \sextupole{SF1}{0.2}
    \drift{0.27}
    \dipole{MB1}{0.2}{30}[s][0.4]
    \drift{0.2}
  \end{lattice}
  % 
  %now draw second lattice and connect them using the saved coordinate
  \begin{lattice}[0.8][overlay]
    \start{(Septum)}
    \rotate{70}
    \drift{0.6}
    \kicker{SS1}{0.2}
    \drift{0.2}
    \kicker{SSH1}{0.2}
    \drift{0.3}
    \dipole{M1}{0.2}{-30}[r][0.4]
    \begin{fade} %fade out this part
      \drift{0.2}
      \dipole{M2}{0.2}{50}[r][0.4]
      \drift{0.2}
      \dipole{M3}{0.2}{-20}[r][0.4]
      \drift{0.7}
    \end{fade}
    \legend{(-1,6.5)}
  \end{lattice}
 \caption{two lattice environments and start}
\end{subfigure}
%
\begin{subfigure}[b]{.45\textwidth}
  \centering
  \begin{lattice}[0.8]
    \rotate{90}
    \turnlabels %labels to the left
    \drift{0.5}
    \quadrupole{QF1}{0.3}
    \drift{0.2}
    \kicker{}{0.1}
    \drift{0.07}
    \quadrupole{QD2}{0.3}
    \drift{0.4}
    \setelementcolor{kicker}{cyan}
    \kicker{Septum}{0.5}
    \resetelementcolor{kicker}
    \savecoordinate{Septum}[center] %save to connect other beamline
    \drift{0.8}
    \kicker{}{0.1}
    \drift{0.37}
    \quadrupole{QD3}{0.2}
    \drift{0.17}
    \kicker{}{0.1}
    \drift{0.1}
    \sextupole{SF1}{0.2}
    \drift{0.27}
    \dipole{MB1}{0.2}{30}[s][0.4]
    \drift{0.2}

    % now go back to saved coordinate and continue with another beamline
    \goto{Septum}
    \rotate{-20}
    \turnlabels %labels to the right
    \drift{0.6}
    \kicker{SS1}{0.2}
    \drift{0.2}
    \kicker{SSH1}{0.2}
    \drift{0.3}
    \dipole{M1}{0.2}{-30}[r][0.4]
    \begin{fade} %fade out this part
      \drift{0.2}
      \dipole{M2}{0.2}{50}[r][0.4]
      \drift{0.2}
      \dipole{M3}{0.2}{-20}[r][0.4]
      \drift{0.7}
    \end{fade}
    \legend{(0,6.5)}
  \end{lattice}
  \caption{one lattice environment and goto}
\end{subfigure}
\caption{From example 3: Two ways to connect lattices}
\label{fig:twoways}
\end{figure}



\section{Changelog}
\label{sec:changelog}
v2.1 from 2015/02/23 is the first published version.

\paragraph{v2.2 from 2015/03/01}
\begin{itemize}
\item added \lstinline+\northlabels+ and \lstinline+\southlabels+
\item minor legend improvements (label position is now independent of current lattice settings)
\item minor documentation improvements
\end{itemize}


\section{TODO}
\label{sec:todo}

\paragraph{What is missing?}
\begin{itemize}
\item manually adding and editing legend entries
\item The look of the elements can be improved
\item More element types can be added
\item \ldots{}
\end{itemize}

I am not an \TeX{} programmer. I basically used the \tikzlabel{} commands and wrote a
bunch of macros. So there is:
\begin{itemize}
\item no error handling implemented
\item no dedicated scoping of internal macros (use of lattice with documentclass standalone recommended)
\end{itemize}

\paragraph{Known issues:}
\begin{itemize}
\item Please report bugs!
\end{itemize}

\end{document}