tikz-palattice_documentation.
Transcription
tikz-palattice_documentation.
tikz-palattice - draw particle accelerator lattices with TikZ Jan Schmidt <[email protected]> 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