summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/tikz-palattice/tikz-palattice_documentation.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2015-02-24 23:12:22 +0000
committerKarl Berry <karl@freefriends.org>2015-02-24 23:12:22 +0000
commit6393e0fa1c1b3ab125e43ddbeecbdca740f7d6ac (patch)
tree90fba8c6dfe27fdf2da8a732c92a9bfc1202f60f /Master/texmf-dist/doc/latex/tikz-palattice/tikz-palattice_documentation.tex
parent1c213966cd11f3051008400dd35517dc22c1e600 (diff)
tikz-palattice (24feb15)
git-svn-id: svn://tug.org/texlive/trunk@36373 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/tikz-palattice/tikz-palattice_documentation.tex')
-rw-r--r--Master/texmf-dist/doc/latex/tikz-palattice/tikz-palattice_documentation.tex581
1 files changed, 581 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/tikz-palattice/tikz-palattice_documentation.tex b/Master/texmf-dist/doc/latex/tikz-palattice/tikz-palattice_documentation.tex
new file mode 100644
index 00000000000..a88c4f61161
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/tikz-palattice/tikz-palattice_documentation.tex
@@ -0,0 +1,581 @@
+%% 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{fixltx2e}
+\usepackage{graphicx}
+\usepackage{subcaption}
+\usepackage[normalem]{ulem}
+\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.1 (February 23, 2015)}
+\title{tikz-palattice - draw particle accelerator lattices with \tikzlabel}
+\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 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}[h]
+ \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.
+
+
+\clearpage
+\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)
+
+\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. East and center are available. East is always downstream.
+
+\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}
+\centering
+\begin{subfigure}[b]{.45\textwidth}
+\centering
+ \begin{lattice}
+ \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}[1][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}
+ \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}
+
+
+\clearpage
+\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 Legend entry alignment is buggy for some legend scales that differ significantly
+ from~1
+\item Please report bugs!
+\end{itemize}
+
+\end{document} \ No newline at end of file