diff options
author | Karl Berry <karl@freefriends.org> | 2015-02-24 23:12:22 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2015-02-24 23:12:22 +0000 |
commit | 6393e0fa1c1b3ab125e43ddbeecbdca740f7d6ac (patch) | |
tree | 90fba8c6dfe27fdf2da8a732c92a9bfc1202f60f /Master/texmf-dist/doc/latex/tikz-palattice/tikz-palattice_documentation.tex | |
parent | 1c213966cd11f3051008400dd35517dc22c1e600 (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.tex | 581 |
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 |