%================================================= %================================================= % % WARNING: NOT USED IN opal_user_guide.tex % %================================================= %================================================= \input{header} \chapter{\textit{OPAL-map}} \label{sec:SplitOperatorMethods} \section{\textit{OPAL-map} Conventions} \label{chp:definitions} \index{Conventions|(} \index{Global!Reference} \index{Reference!Global} The accelerator and/or beam line to be studied with \textit{OPAL-map} is described as a sequence of beam elements placed sequentially along a reference or design orbit. The global reference orbit, also known as the design orbit see~Figure~\ref{global} is the path of a charged particle having the central design momentum of the accelerator through idealised magnets with no fringe fields. In case of \textit{OPAL-t} and \textit{OPAL-cycl} with time as the independent variable no such explicit design orbit exists. The rest of this chapter is only relevant to \textit{OPAL-map} except Section~\ref{units} on the physical units. \section{Design or Reference Orbit} \index{Design!Orbit} \index{Orbit!Design} \index{Reference!Orbit} \index{Orbit!Reference} The reference orbit consists of a series of straight line segments and circular arcs. It is defined under the assumption that all elements are perfectly aligned along the design orbit. The accompanying tripod of the reference orbit spans a local curvilinear right handed coordinate system $(x,y,s)$. The local $s$-axis is the tangent to the reference orbit. The other two axes are perpendicular to the reference orbit and are labelled~$x$ (in the bend plane) and~$y$ (perpendicular to the bend plane). \section{Closed Orbit} \index{Closed!Orbit} \index{Orbit!Closed} \index{Misalignment} \index{Field!Error} \index{Error!Field} \index{Error!Misalignment} \index{Fringe Field} \index{Field!Fringe} Due to various errors like misalignment errors, field errors, fringe fields etc., the closed orbit does not coincide with the design orbit. It also changes with the momentum error. The closed orbit is described with respect to the reference orbit, using the local reference system see~Figure~\ref{local}. It is evaluated including any nonlinear effects. \begin{figure}[ht] \begin{center} \setlength{\unitlength}{1pt} \begin{picture}(400,250) % axes \thicklines \put(180,100){\vector(0,1){90}} \put(180,0){\line(0,1){33.3}} \put(187,185){\makebox(0,0){$y$}} \put(280,0){\vector(-1,1){160}} \put(120,150){\makebox(0,0){$x$}} \thinlines \put(180,100){\circle*{4}} % coordinates \put(150,130){\line(0,1){60}} \put(155,125){\line(0,1){60}} \put(160,120){\line(0,1){60}} \put(165,115){\line(0,1){60}} \put(170,110){\line(0,1){60}} \put(175,105){\line(0,1){60}} \put(180,160){\line(-1,1){30}} \put(180,150){\line(-1,1){30}} \put(180,140){\line(-1,1){30}} \put(180,130){\line(-1,1){30}} \put(180,120){\line(-1,1){30}} \put(180,110){\line(-1,1){30}} % radius of curvature and centre \put(280,0){\vector(-3,1){172}} \put(160,30){\makebox(0,0){$\rho$}} \put(280,0){\vector(0,1){142}} \put(290,60){\makebox(0,0){$\rho$}} \put(280,0){\circle*{4}} \put(295,15){\vector(-1,-1){12}} \put(295,15){\makebox(0,0)[bl]{\shortstack{centre of \\curvature}}} \path(270,3.3)(280,9) \path(260,6.7)(280,18) \path(250,10)(280,27) \path(240,13.3)(280,36) \path(230,16.7)(280,45) \path(220,20)(280,54) \path(210,23.3)(280,63) \path(200,26.7)(280,72) \path(190,30)(280,81) \path(180,33.3)(280,90) \path(170,36.7)(280,99) \path(160,40)(280,108) \path(150,43.3)(280,117) \path(140,46.7)(280,126) \path(130,50)(280,135) \path(120,53.3)(278,142) \path(110,56.7)(218,117.9) % actual orbit \thicklines \bezier{150}(0,100)(75,165)(150,190) \bezier{150}(150,190)(240,220)(320,220) \put(320,220){\vector(1,0){4}} \put(80,180){\vector(1,-1){12}} \put(80,180){\makebox(0,0)[br]{\shortstack{actual \\orbit}}} % reference orbit \bezier{150}(40,0)(100,60)(180,100) \bezier{150}(180,100)(260,140)(340,160) \put(340,160){\vector(4,1){4}} \put(330,165){\makebox{$s$}} \put(320,135){\vector(-1,1){12}} \put(320,135){\makebox(0,0)[tl]{\shortstack{reference \\orbit}}} \end{picture} \caption{Local Reference System} \label{fig:local} \end{center} \end{figure} \index{Betatron Motion} \index{Synchrotron Motion} \textit{OPAL-map} computes the betatron and synchrotron oscillations with respect to the closed orbit. Results are given in the local $(x, y, s)$-system defined by the reference orbit. \section{Global Reference System} \index{Global!Reference} \index{Reference!Global} The global reference orbit see~Figure~\ref{global} of the accelerator is uniquely defined by the sequence of physical elements. The local reference system $(x, y, s)$ may thus be related to a global Cartesian coordinate system $(X, Y, Z)$. The positions between beam elements are numbered $0, \ldots , i, \ldots n$. The local reference system $(x_i, y_i, s_i)$ at position $i$, i.e.\ the displacement and direction of the reference orbit with respect to the system $(X, Y, Z)$ are defined by three displacements $(X_i, Y_i, Z_i)$ and three angles $(\Theta_i, \Phi_i, \Psi_i)$. \begin{figure}[ht]% 1.2 \begin{center} \setlength{\unitlength}{1pt} \begin{picture}(400,270) % global axes \thicklines \put(20,150){\line(2,-1){40}} \dashline{3}(60,130)(100,110) \put(100,110){\line(2,-1){60}} \put(193,63){\vector(2,-1){90}} \put(300,20){\makebox(0,0){$Z$}} \put(20,100){\line(3,1){30}} \dashline{3}(50,110)(248,176) \put(248,176){\vector(3,1){132}} \put(373,210){\makebox(0,0){$X$}} \put(80,0){\vector(0,1){270}} \put(70,265){\makebox(0,0){$Y$}} %local axes \put(133.3,0){\vector(1,3){90}} \put(215,270){\makebox(0,0){$x$}} \put(300,150){\vector(-2,1){160}} \put(140,220){\makebox(0,0){$y$}} \put(0,100){\vector(2,1){270}} \put(260,240){\makebox(0,0){$s$}} % projection of s onto ZX \thinlines \put(100,110){\circle*{4}} \put(200,200){\circle*{4}} \path(0,110)(170,110) \dashline{3}(170,110)(240,110) \path(240,110)(290,110) \put(280,90){\makebox(0,0)[t]{\shortstack{projection of $s$ \\ onto $(Z,X)$-plane}}} \put(280,95){\vector(0,1){13}} \put(20,110){\circle*{4}} \put(50,110){\circle*{4}} % hashing of xy plane \path(210,195)(160,45) \path(220,190)(169.7,39.7) \path(230,185)(187.5,57.5) \path(240,180)(205,75) \path(250,175)(222.5,92.5) \path(260,170)(240,110) \path(270,165)(257.5,127.5) \path(280,160)(275,145) \path(196.7,190)(278.9,148.9) \path(193.3,180)(271.1,141.1) \path(190,170)(263.3,133.3) \path(186.7,160)(255.5,125.5) \path(183.3,150)(247.7,117.7) \path(180,140)(239.9,109.9) \path(176.7,130)(232.1,101.1) \path(173.3,120)(224.3,94.3) \path(170,110)(216.5,86.5) \path(166.7,100)(208.7,78.7) \path(163.3,90)(200.9,70.9) \path(160,80)(193.1,63.1) \path(156.7,70)(185.3,55.3) \path(153.3,60)(177.5,47.5) \path(150,50)(169.7,39.7) % hashing of projection plane \put(70,110){\line(0,1){25}} \put(80,110){\line(0,1){30}} \put(90,110){\line(0,1){35}} \put(100,110){\line(0,1){40}} \put(110,110){\line(0,1){45}} \put(120,110){\line(0,1){50}} \put(130,110){\line(0,1){55}} \put(140,110){\line(0,1){60}} \put(150,110){\line(0,1){65}} \put(160,110){\line(0,1){70}} \put(170,110){\line(0,1){75}} \put(180,140){\line(0,1){50}} \put(190,170){\line(0,1){25}} % intersection of xy and ZX \put(130,0){\line(1,1){230}} \put(135,5){\circle*{4}} \put(193.3,63.3){\circle*{4}} \put(240,110){\circle*{4}} \put(286.7,156.7){\circle*{4}} \put(335,205){\circle*{4}} \thicklines \put(200,25){\vector(-1,1){20}} \put(200,20){\makebox(0,0)[t]{\shortstack{intersection of \\ $(x,y)$ and $(Z,X)$ planes}}} % reference orbit \bezier{80}(140,150)(170,185)(200,200) \bezier{80}(200,200)(230,215)(260,220) \put(260,220){\makebox(0,0)[l]{\shortstack{reference \\orbit}}} % roll angle \bezier{30}(160,30)(160,40)(150,50) \put(152,48){\vector(-1,1){2}} \put(150,30){\makebox(0,0){$\psi$}} \put(140,30){\makebox(0,0)[br]{roll angle}} % pitch angle \bezier{20}(60,110)(60,120)(55,125) \put(57,123){\vector(-1,2){2}} \put(50,118){\makebox(0,0){$\phi$}} \put(40,125){\makebox(0,0)[br]{pitch angle}} % azimuth \bezier{20}(130,95)(140,100)(140,110) \put(140,105){\vector(0,1){5}} \put(130,105){\makebox(0,0){$\theta$}} \put(115,95){\makebox(0,0)[t]{azimuth}} \end{picture} \caption{Global Reference System} \label{fig:global} \end{center} \end{figure} \index{Displacement} The above quantities are defined more precisely as follows: \begin{description} \item[X] \index{Horizontal Displacement} Displacement of the local origin in $X$-direction. \item[Y] \index{Vertical Displacement} Displacement of the local origin in $Y$-direction. \item[Z] \index{Longitudinal Displacement} Displacement of the local origin in $Z$-direction. \index{Angle} \item[THETA] \index{Azimuth Angle} Angle of rotation (azimuth) about the global $Y$-axis, between the global $Z$-axis and the projection of the reference orbit onto the $(Z, X)$-plane. A positive angle \texttt{THETA} forms a right-hand screw with the $Y$-axis. \item[PHI] \index{Pitch Angle} Pitch angle, i.e. the angle between the reference orbit and its projection onto the $(Z, X)$-plane. A positive angle \texttt{PHI} correspond to $Y$ increasing with $s$. If only horizontal bends are present, the reference orbit remains in the ($Z$, $X$)-plane. In this case \texttt{PHI} is always zero. \item[PSI] \index{Roll Angle} Roll angle about the local $s$-axis, i.e. the angle between the intersection $(x, y)$- and $(Z, X)$-planes and the local $x$-axis. A positive angle \texttt{PSI} forms a right-hand screw with the $s$-axis. \end{description} The angles \texttt{(THETA, PHI, PSI)} are \textbf{not} the Euler angles. The reference orbit starts at the origin and points by default in the direction of the positive $Z$-axis. The initial local axes $(x, y, s)$ coincide with the global axes $(X, Y, Z)$ in this order. The six quantities $(X_0, Y_0, Z_0, \Theta_0, \Phi_0, \Psi_0)$ thus all have zero initial values by default. The program user may however specify different initial conditions. Internally the displacement is described by a vector $V$ and the orientation by a unitary matrix $W$. The column vectors of $W$ are the unit vectors spanning the local coordinate axes in the order $(x, y, s)$. $V$ and $W$ have the values: \[ V=\left(\begin{array}{c} X \\ Y \\ Z \end{array}\right), \qquad W=\Theta\Phi\Psi \] where \[ \Theta=\left(\begin{array}{ccc} \cos\theta & 0 & \sin\theta \\ 0 & 1 & 0 \\ -\sin\theta & 0 & \cos\theta \end{array}\right), \quad \Phi=\left(\begin{array}{ccc} 1 & 0 & 0 \\ 0 & \cos\phi & \sin\phi \\ 0 & -\sin\phi & \cos\phi \end{array}\right), \quad \] \[ \Psi=\left(\begin{array}{ccc} \cos\psi & -\sin\psi & 0 \\ \sin\psi & \cos\psi & 0 \\ 0 & 0 & 1 \end{array}\right). \] The reference orbit should be closed and it should not be twisted. This means that the displacement of the local reference system must be periodic with the revolution frequency of the accelerator, while the position angles must be periodic $\pmod{2\pi}$ with the revolution frequency. If \texttt{PSI} is not periodic $\pmod{2\pi}$, coupling effects are introduced. When advancing through a beam element, \textit{OPAL-map} computes $V_i$ and $W_i$ by the recurrence relations \[ V_i = W_{i-1}R_i + V_{i-1}, \qquad W_i = w_{i-1}S_i. \] The vector $R_i$ is the displacement and the matrix $S_i$ is the rotation of the local reference system at the exit of the element $i$ with respect to the entrance of the same element. The values of $R_i$ and $S_i$ are listed below for each physical element type. \section{Local Reference Systems} \index{Local!Reference} \index{Reference!Local} \subsection{Reference System for Straight Beam Elements} \label{sec:straight} In straight elements the local reference system see~Figure~\ref{straight} is simply translated by the length of the element along the local $s$-axis. This is true for \begin{itemize} \item Drift spaces see~Section~\ref{drift} \item Quadrupoles see~Section~\ref{quadrupole} \item Sextupoles see~Section~\ref{sextupole} \item Octupoles see~Section~\ref{octupole} \item Multipoles see~Section~\ref{octupole} \item Solenoids see~Section~\ref{solenoid} \item RF cavities see~Section~\ref{cavity} \item Electrostatic separators see~Section~\ref{separator} \item Closed orbit correctors see~Section~\ref{corrector} \item Beam position monitors see~Section~\ref{monitors} \end{itemize} The corresponding $R$, $S$ are \[ R=\left(\begin{array}{c} 0 \\ 0 \\ L \end{array}\right), \qquad S=\left(\begin{array}{ccc} 1 & 0 & 0 \\ 0 & 1 & 0 \\ 0 & 0 & 1 \\ \end{array}\right). \] A rotation of the element about the $S$-axis has no effect on $R$ and $S$, since the rotations of the reference system before and after the element cancel. \begin{figure}[ht] \begin{center} \setlength{\unitlength}{1pt} \begin{picture}(400,100) \thinlines % axes \put(150,50){\circle{8}}\put(150,50){\circle*{2}} \put(140,40){\makebox(0,0){$y_1$}} \put(250,50){\circle{8}}\put(250,50){\circle*{2}} \put(260,40){\makebox(0,0){$y_2$}} \put(100,50){\line(1,0){46}} \put(154,50){\line(1,0){92}} \put(254,50){\vector(1,0){46}} \put(290,40){\makebox(0,0){$s$}} \put(150,0){\line(0,1){46}} \put(150,54){\vector(0,1){46}} \put(140,90){\makebox(0,0){$x_1$}} \put(250,0){\line(0,1){46}} \put(250,54){\vector(0,1){46}} \put(260,90){\makebox(0,0){$x_2$}} % magnet outline \thicklines \put(150,54){\line(0,1){26}} \put(150,46){\line(0,-1){26}} \put(250,54){\line(0,1){26}} \put(250,46){\line(0,-1){26}} \put(150,20){\line(1,0){100}} \put(150,80){\line(1,0){100}} \put(200,2){\vector(1,0){50}} \put(200,2){\vector(-1,0){50}} \put(200,10){\makebox(0,0){L}} \end{picture} \caption{Reference System for Straight Beam Elements} \label{fig:straight} \end{center} \end{figure} \subsection{Reference System for Bending Magnets} \label{rbend} Both rectangular see~Figure~\ref{rbend} and sector see~Figure~\ref{sbend} bending magnets have a curved reference orbit. For both types of magnets \[ R=\left(\begin{array}{c} \rho(\cos\alpha-1) \\ 0 \\ \rho\sin\alpha \end{array}\right), \qquad S=\left(\begin{array}{ccc} \cos\alpha & 0 & -\sin\alpha \\ 0 & 1 & 0 \\ \sin\alpha & 0 & \cos\alpha \end{array}\right), \] where $\alpha$ is the bend angle. A positive bend angle represents a bend to the right, i.e. towards negative $x$ values. For sector bending magnets, the bend radius is given by $\rho$, and for rectangular bending magnets it has the value \[ \rho = L / 2 n(\alpha/2). \] If the magnet is rotated about the $s$-axis by an angle psi, $R$ and $S$ are transformed by \[ R^{*} = T R, \qquad S^{*} = T S T^{-1}. \] where $T$ is the orthogonal rotation matrix \[ T= \begin{pmatrix} \cos\psi & -\sin\psi & 0 \\ \sin\psi & \cos\psi & 0 \\ 0 & 0 & 1 \end{pmatrix}. \] The special value $\psi = \pi/2$ represents a bend down. \begin{figure}[ht] \begin{center} \setlength{\unitlength}{1pt} \begin{picture}(400,215) % axes \thinlines \put(150,150){\circle{8}}\put(150,150){\circle*{2}} \put(160,140){\makebox(0,0){$y_1$}} \put(250,150){\circle{8}}\put(250,150){\circle*{2}} \put(240,140){\makebox(0,0){$y_2$}} \put(74,124.7){\vector(3,1){72}} \put(84,135){\makebox(0,0){$s_1$}} \put(254,148.7){\vector(3,-1){72}} \put(316,135){\makebox(0,0){$s_2$}} \put(200,0){\vector(-1,3){48.7}} \put(165,75){\makebox(0,0){$\rho$}} \put(148.7,154){\vector(-1,3){18}} \put(118,206){\makebox(0,0){$x_1$}} \put(200,0){\vector(1,3){48.7}} \put(235,75){\makebox(0,0){$\rho$}} \put(251.3,154){\vector(1,3){18}} \put(282,206){\makebox(0,0){$x_2$}} \bezier{20}(190.5,28.5)(200,31.7)(209.5,28.5) \put(200,20){\makebox(0,0){$\alpha$}} \put(154,150){\line(1,0){92}} \put(200,150){\circle*{4}} \put(200,150){\vector(0,1){60}} \put(210,200){\makebox(0,0){$x$}} \put(150,154){\line(0,1){44}} \put(150,146){\line(0,-1){46}} \put(151,154){\line(1,4){11}} \put(250,154){\line(0,1){44}} \put(250,146){\line(0,-1){46}} \put(249,154){\line(-1,4){11}} % magnet outline \thicklines \put(200,102){\vector(-1,0){50}} \put(200,102){\vector(1,0){50}} \put(200,110){\makebox(0,0){L}} \put(151,154){\line(1,4){6}} \put(149,146){\line(-1,-4){6}} \put(249,154){\line(-1,4){6}} \put(251,146){\line(1,-4){6}} \put(157,178){\line(1,0){86}} \put(143,122){\line(1,0){114}} \bezier{10}(150,195)(155.5,195)(160.9,193.7) \put(155.5,195){\vector(3,-1){5.4}} \put(150,205){\makebox(0,0)[l]{$e_1$}} \bezier{10}(250,195)(244.5,195)(239.1,193.7) \put(244.5,195){\vector(-3,-1){5.4}} \put(250,205){\makebox(0,0)[r]{$e_2$}} \end{picture} \caption[Reference System for a Rectangular Bending Magnet]% {Reference System for a Rectangular Bending Magnet; the signs of pole-face rotations are positive as shown.} \label{fig:rbend} \end{center} \end{figure} \begin{figure}[ht] \begin{center} \setlength{\unitlength}{1pt} \begin{picture}(400,215) % axes \thinlines \put(150,150){\circle{8}}\put(150,150){\circle*{2}} \put(160,140){\makebox(0,0){$y_1$}} \put(250,150){\circle{8}}\put(250,150){\circle*{2}} \put(240,140){\makebox(0,0){$y_2$}} \put(74,124.7){\vector(3,1){72}} \put(84,135){\makebox(0,0){$s_1$}} \put(254,148.7){\vector(3,-1){72}} \put(316,135){\makebox(0,0){$s_2$}} \put(200,0){\vector(-1,3){48.7}} \put(165,75){\makebox(0,0){$\rho$}} \put(148.7,154){\vector(-1,3){18}} \put(118,206){\makebox(0,0){$x_1$}} \put(200,0){\vector(1,3){48.7}} \put(235,75){\makebox(0,0){$\rho$}} \put(251.3,154){\vector(1,3){18}} \put(282,206){\makebox(0,0){$x_2$}} \bezier{20}(190.5,28.5)(200,31.7)(209.5,28.5) \put(200,20){\makebox(0,0){$\alpha$}} \put(200,158.8){\circle*{4}} \put(200,158.8){\vector(0,1){50}} \put(210,200){\makebox(0,0){$r$}} \put(151,154){\line(1,4){10}} \put(249,154){\line(-1,4){10}} % magnet outline \thicklines \bezier{100}(154,151.3)(200,166.7)(246,151.3) \put(162,154){\vector(-3,-1){8}} \put(238,154){\vector(3,-1){8}} \put(210,168){\makebox(0,0){L}} \put(151,154){\line(1,4){6}} \put(149,146){\line(-1,-4){6}} \put(249,154){\line(-1,4){6}} \put(251,146){\line(1,-4){6}} \bezier{90}(157,178)(200,188.4)(243,178) \bezier{110}(143,122)(200,148.6)(257,122) \bezier{20}(137.4,187.9)(149.1,191.5)(159.7,188.8) \put(153.7,190.8){\vector(3,-1){6}} \put(150,180){\makebox(0,0){$e_1$}} \bezier{20}(262.6,187.9)(250.9,191.5)(240.3,188.8) \put(246.3,190.8){\vector(-3,-1){6}} \put(250,180){\makebox(0,0){$e_2$}} \end{picture} \caption[Reference System for a Sector Bending Magnet]% {Reference System for a Sector Bending Magnet; the signs of pole-face rotations are positive as shown.} \label{fig:sbend} \end{center} \end{figure} \subsection{Rotation of the Reference System} \label{sec:refrot} For a rotation of the reference system by an angle $\psi$ about the beam ($s$) axis see~Figure~\ref{srot}: \[ S=\left(\begin{array}{ccc} \cos\psi & -\sin\psi & 0 \\ \sin\psi & \cos\psi & 0 \\ 0 & 0 & 1 \\ \end{array}\right), \] while for a rotation of the reference system by an angle $\theta$ about the vertical ($y$) axis see~Figure~\ref{yrot}: \[ S=\left(\begin{array}{ccc} \cos\theta & 0 & -\sin\theta \\ 0 & 1 & 0 \\ \sin\theta & 0 & \cos\theta \end{array}\right). \] In both cases the displacement $R$ is zero. \begin{figure}[ht]% \begin{center} \setlength{\unitlength}{1pt} \begin{picture}(400,200) \thinlines \put(200,100){\circle{8}}\put(200,100){\circle*{2}} \put(190,90){\makebox(0,0){$s$}} \put(100,100){\line(1,0){96}} \put(204,100){\vector(1,0){96}} \put(290,90){\makebox(0,0){$x_1$}} \put(200,0){\line(0,1){96}} \put(200,104){\vector(0,1){96}} \put(190,210){\makebox(0,0){$y_1$}} \put(103,75.75){\line(4,1){93}} \put(204,101){\vector(4,1){93}} \put(287,134){\makebox(0,0){$x_2$}} \put(224.25,3){\line(-1,4){23.25}} \put(199,104){\vector(-1,4){23.25}} \put(166,187){\makebox(0,0){$y_2$}} \bezier{20}(260,100)(260,107.5)(258,114.5) \put(260,106.5){\vector(-1,4){2}} \put(250,106.25){\makebox(0,0){$\psi$}} \put(220,150){\circle{8}}\put(220,150){\circle*{2}} \put(220,140){\makebox(0,0){beam}} \end{picture} \caption{Reference System for a Rotation Around the s-Axis} \label{fig:srot} \end{center} \end{figure} \begin{figure}[ht]% \begin{center} \setlength{\unitlength}{1pt} \begin{picture}(400,200) \thinlines \put(200,100){\circle{8}}\put(200,100){\circle*{2}} \put(190,90){\makebox(0,0){$y$}} \put(100,100){\line(1,0){96}} \put(204,100){\vector(1,0){96}} \put(290,110){\makebox(0,0){$s_1$}} \put(200,0){\line(0,1){96}} \put(200,104){\vector(0,1){96}} \put(190,190){\makebox(0,0){$x_1$}} \put(103,124.25){\line(4,-1){93}} \put(204,99){\vector(4,-1){93}} \put(287,66){\makebox(0,0){$s_2$}} \put(175.75,3){\line(1,4){23.25}} \put(201,104){\vector(1,4){23.25}} \put(234,187){\makebox(0,0){$x_2$}} \bezier{20}(260,100)(260,92.5)(258,85.5) \put(260,93.5){\vector(-1,-4){2}} \put(250,93.75){\makebox(0,0){$\theta$}} \thicklines \put(100,130){\vector(1,0){200}} \put(290,140){\makebox(0,0){beam}} \end{picture} \caption{Reference System for a Rotation Around the y-Axis} \label{fig:yrot} \end{center} \end{figure} \subsection{Elements which do not Change the Local Reference} The following elements do not affect the reference orbit and are ignored for geometry calculations: \begin{itemize} \item Beam-beam interactions %Beam-beam interactions see~Section~\ref{sec:beambeam} \item Marker see~Section~\ref{marker} \end{itemize} \section{Sign Conventions for Magnetic Fields} \label{sec:sign} \index{Sign Conventions For Fields} \index{Field!Signs} The \textit{OPAL-map} program uses the following Taylor expansion for the normal and skewed field components respectively in the mid-plane $y$=0, described in \bibref{SLAC-75}{matrix}: \[ B_x(x,0)=\sum_{k=0}^{\infty}\frac{B_{kn}x^k}{k!}, \qquad B_x(x,0)=\sum_{k=0}^{\infty}\frac{B_{ks}x^k}{k!}. \] Note the factorial in the denominator. The field coefficients have the following meaning: \begin{description} \item[$B_{0n}$] Normal dipole field component. The component is positive if the field points in the positive $y$ direction. A positive field bends a positively charged particle travelling in positive $s$-direction to the right. \item[$B_{0s}$] Skew dipole field component. The component is positive if the field points in the negative $y$ direction. A positive field bends a positively charged particle travelling in positive $s$-direction down. \item[$B_{1n}$] Normal quadrupole field component $B_{1n}=\uglyparder{B_y}{x}$. The component is positive if $B_y$ is positive on the positive $x$-axis. A positive value corresponds to horizontal focussing of a positively charged particle. \item[$B_{1s}$] Skew quadrupole field component $B_{1s}=\uglyparder{B_x}{x}$. The component is positive if $B_x$ is negative on the positive $x$-axis. \item[$B_{2n}$] Normal sextupole field component $B_{2n}=\uglyparder[2]{B_y}{x}$. The component is positive if $B_y$ is positive on the $x$-axis. \item[$B_{2s}$] Skew sextupole field component $B_{2s}=\uglyparder[2]{B_x}{x}$. The component is negative if $B_x$ is positive on the $x$-axis. \item[$B_{3n}$] Normal octupole field component $B_{3n}=\uglyparder[3]{B_y}{x}$. The component is positive if $B_y$ is positive on the positive $x$-axis. \item[$B_{3s}$] Skew octupole field component $B_{3s}=\uglyparder[3]{B_x}{x}$. The component is negative if $B_x$ is positive on the $x$-axis. \end{description} All derivatives are taken on the $x$-axis. Using this expansion and the curvature $h$ of the reference orbit, the longitudinal component of the vector potential for a magnet with mid-plane symmetry is to order~4: \index{Field!Vector Potential} \index{Vector Potential} \begin{align*} A_s \quad = \quad & B_{0n}\left(x-\frac{hx^2}{2(1+hx)}\right) \\ &+B_{1n}\left(\frac{1}{2}(x^2-y^2)-\frac{h}{6}x^{3} +\frac{h^2}{24}(4x^{4}-y^{4})+\ldots\right) \\ &+B_{2n}\left(\frac{1}{6}(x^{3}-3xy^2)-\frac{h}{24}(x^{4}-y^{4}) +\ldots\right) \\ &+B_{3n}\left(\frac{1}{24}(x^{4}-6x^2y^2+y^{4})+\ldots\right) + \ldots \end{align*} Taking $\mathrm{curl} A$ in curvilinear coordinates, the field components can be computed as \index{Field!Components} \begin{align*} B_x(x,y) \quad = \quad & B_{1n}\left(y+\frac{h^2}{6}y^{3}+\ldots\right) +B_{2n}\left(xy-\frac{h^{3}}{6}y^{3}+\ldots\right) \\ &+B_{3n}\left(\frac{1}{6}(3x^2y-y^{3})+\ldots\right) + \ldots \\ B_y(x,y) \quad = \quad & B_{0n} +B_{1n}\left(x-\frac{h}{2}y^2+\frac{h^2}{2}xy^2+\ldots\right) \\ &+B_{2n}\left(\frac{1}{2}(x^2-y^2)-\frac{h}{2}xy^2+\ldots\right) \\ &+B_{3n}\left(\frac{1}{6}(x^{3}-3xy^2)+\ldots\right) + \ldots \end{align*} One can easily verify that both $\mathrm{curl} B$ and $\mathrm{div} B$ are zero to the order of the $B_3$ term. Introducing the magnetic rigidity $B \rho$, the multipole coefficients are computed as \[ K_{kn}=eB_{kn}/p_0=B_{kn}/B\rho,\qquad K_{ks}=eB_{ks}/p_0=B_{ks}/B\rho. \] Note that the $K_k$ have the \textbf{same sign} as the corresponding field components $B_k$. The signs will be changed due to the sign of particle charges and the direction of travel of the beam. \section{Variables in \textit{OPAL-map}} \label{sec:variables} \index{Variables} For each variable the physical units are listed in square brackets. \subsection{Canonical Variables Describing Orbits} \label{sec:canon} \index{Canonical Variables} \index{Variables!Canonical} \textit{OPAL-map} uses the following canonical variables to describe the motion of particles: \begin{description} \item[X] Horizontal position $x$ of the (closed) orbit, referred to the ideal orbit [m]. \item[PX] Horizontal canonical momentum of the (closed) orbit referred to the ideal orbit, divided by the reference momentum: $\mathtt{PX} = p_x / p_0$. \item[Y] Vertical position $y$ of the (closed) orbit, referred to the ideal orbit [m]. \item[PY] Vertical canonical momentum of the (closed) orbit referred to the ideal orbit, divided by the reference momentum: $\mathtt{PY} = p_y / p_0$. \item[T] The negative time difference, multiplied by the instantaneous velocity of the particle [m]: $\mathtt{T} = - v \delta(t)$. A positive \texttt{T} means that the particle arrives ahead of the \textbf{reference particle}. \texttt{T} describes the deviation of the particle from the orbit of a fictitious reference particle having the constant \textbf{reference momentum} $p_s$ and the \textbf{reference velocity} $v_s$. $v_s$ defines the revolution frequency. The velocities have the values \[ v = c p / \sqrt{p^2 + m^2 c^2}, \qquad v_s = c p_s / \sqrt{p_s^2 + m^2 c^2}, \] where $c$ is the velocity of light, $m$ is the particle rest mass, and $p$ is the instantaneous momentum of the particle. \item[PT] Momentum error, divided by the reference momentum: $\mathtt{PT} = \delta p / p_s$. This value is only non-zero when synchrotron motion is present. It describes the deviation of the particle from the orbit of a particle with the reference momentum $p_s$. \end{description} The independent variable is: \begin{description} \item[S] Arc length $s$ along the reference orbit [m]. \end{description} The longitudinal variables is in the limit of fully relativistic particles ($\gamma \gg 1, v = c, p c = E$), the variables \texttt{T, PT} used here agree with the longitudinal variables used in \bibref{TRANSPORT}{transport}. This means that \texttt{T} becomes the negative path length difference, while \texttt{PT} is the fractional momentum error. The reference momentum must be constant in order to keep the system canonical. \subsection{Normalised Variables and other Derived Quantities} \label{sec:normal} \index{Normalised Variables} \index{Variables!Normalised} \begin{description} \item[XN] The normalised horizontal displacement [$\mathrm{m}^{1/2}$]: $\mathtt{XN} = x_n = \Re(\transpose{E_1} S Z)$. \item[PXN] The normalised horizontal transverse momentum [$\mathrm{m}^{1/2}$]: $\mathtt{PXN} = p_{xn} = \Im(\transpose{E_1} S Z$). \item[WX] The horizontal Courant-Snyder invariant [m]: $\mathtt{WX} = \sqrt{x_n^2 + p_{xn}^2}$. \item[PHIX] The horizontal phase: $\mathtt{PHIX} = - \arctan(p_{xn} / x_n) / 2 \pi$. \item[YN] The normalised vertical displacement [$\mathrm{m}^{1/2}$]: $\mathtt{YN} = y_n = \Re(\transpose{E_2} S Z)$. \item[PYN] The normalised vertical transverse momentum [$\mathrm{m}^{1/2}$]: $\mathtt{PYN} = p_{yn} = \Im(\transpose{E_2} S Z)$. \item[WY] The vertical Courant-Snyder invariant [m]: $\mathtt{WY} = \sqrt{y_n^2 + p_{yn}^2}$. \item[PHIY] The vertical phase: $\mathtt{PHIY} = - \arctan(p_{yn} / y_n) / 2 \pi$. \item[TN] The normalised longitudinal displacement [$\mathrm{m}^{1/2}$]: $\mathtt{TN} = t_n = \Re(\transpose{E_3} S Z)$. \item[PTN] The normalised longitudinal transverse momentum [$\mathrm{m}^{1/2}$]: $\mathtt{PTN} = p_{tn} = Im(\transpose{E_3} S Z)$. \item[WT] The longitudinal invariant [m]: $\mathtt{WT} = \sqrt{t_n^2 + p_{tn}^2}$. \item[PHIT] The longitudinal phase: $\mathtt{PHIT} = + \arctan(p_{tn} / t_n) / 2 \pi$. \end{description} in the above formulas $Z$ is the phase space vector $Z = \transpose{(x, p_x, y, p_y, t, p_t)}$. The matrix $S$ is the ``symplectic unit matrix'' \[ S = \begin{pmatrix} 0 & 1 & 0 & 0 & 0 & 0 \\ -1 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 1 & 0 & 0 \\ 0 & 0 &-1 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 1 \\ 0 & 0 & 0 & 0 &-1 & 0 \end{pmatrix}, \] and the vectors $E_i$ are the three complex eigenvectors. The superscript $T$ denotes the transpose of a vector or matrix. \section{Physical Units} \label{sec:units} \index{Units} \index{Physical Units} Throughout the computations \textit{OPAL} uses international units see~Table~\ref{units}, as defined by SI (Syst\`eme International). \begin{table}[ht] \footnotesize \begin{center} \caption{Physical Units} \label{tab:units} \begin{tabular}{|l|l|} \hline quantity & dimension \\ \hline Length & m (metres) \\ Angle & rad (radians) \\ Quadrupole coefficient & $\mathrm{m}^{-2}$ \\ Multipole coefficient, 2n poles & $\mathrm{m}^{-n}$ \\ Electric voltage & MV (Megavolts) \\ Electric field strength & MV/m \\ Frequency & MHz (Megahertz) \\ Phase angles & $2\pi$ \\ Particle energy & GeV \\ Particle mass & GeV/$c^2$ \\ Particle momentum & GeV/c \\ Beam current & A (Amperes) \\ Particle charge & e (elementary charges) \\ Impedances & M$\Omega$ (Megohms) \\ Emittances & $\pi$ m mrad \\ Emittances \textit{OPAL-t} & m rad \footnote{(normalized and un-normalized)}\\ RF power & MW (Megawatts) \\ Higher mode loss factor & V/pc \\ \hline \end{tabular} \end{center} \end{table} \index{Conventions|)} Typically, the total Hamiltonian can be written as the sum of two parts, $H = H_{1} + H_{2}$, which correspond to the external and space charge contributions respectively. Such a situation is ideally suited to multi-map symplectic Split-Operator methods~\ref{forestall}, also known as fractional step methods \ref{SanzSerna}. A second-order accurate algorithm for a single step is given by \begin{equation} \label{eq:splitOper1} {\cal M}(\tau)={\cal M}_1(\tau/2)~{\cal M}_2(\tau)~{\cal M}_1(\tau/2) + \mathcal{O}(\tau^3) \end{equation} where $\tau$ denotes the step size, ${\cal M}_1$ is the map corresponding %Equation~\ref{mad9pham} to $H_{1}$ and ${\cal M}_2$ is the map corresponding to $H_{2}$. If desired this approach can be easily generalized to higher order accuracy using Yoshida's scheme. % ~\ref{yoshida}. This is the simplest 2nd order symplectic\footnote{Products of symplectic operators are symplectic as well.} Split-Operator integration method, which first applies all external forces for the first half of one integration step, then adds the complete influence of the internal forces for one entire integration step, and then applies another half of an integration step worth of external forces. Details following when \textit{OPAL-map} is implemented. Each \texttt{member} may be one of the following: \begin{itemize} \item A {SEQUENCE} see~Section~\ref{sequence} label, \end{itemize} Beam lines can be nested to any level. The {TWISS} command see~Section~\ref{twiss} tells \textit{OPAL} to perform lattice calculations on the sequence \begin{verbatim} A,B,C,D,A,D \end{verbatim} \subsection{Reflection and Repetition} \label{sec:refrep} An unsigned repetition count and an asterisk indicate repetition of a beam line member. An optional minus sign (\texttt{-}) prefix causes reflection, i.e. all elements in the subsequence are taken in reverse order. Sub-lines of reflected lines are also reflected, but on physical elements the reflection flag is ignored. The minus sign must precede any repetition count. Repetitions are expanded immediately when a line is read, so are reflections of anonymous beam lines. The result is a flat line referring to a sequence of named elements and/or beam lines. Please note this is not yet supported for \texttt{DOPAL-t} and \texttt{DOPAL-cycl}. When the line is output, it has the form resulting from this expansion. Example: \begin{verbatim} R:LINE=(G,H); S:LINE=(C,R,D); T:LINE=(2*S,2*(E,F),-S,-(A,B)); TWISS,LINE=T; \end{verbatim} The three lines are stored as follows: \begin{verbatim} R:LINE=(G,H); S:LINE=(C,R,D); T:LINE=(S,S,E,F,E,F,-S,B,A); \end{verbatim} When \texttt{T} is expanded, substitution is recursive: \begin{enumerate} \item Replace sub-line \texttt{S}: \begin{verbatim} (C,R,D,C,R,D,E,F,E,F,D,-R,C,B,A) \end{verbatim} \item Replace sub-line \texttt{R}: \begin{verbatim} (C,G,H,D,C,G,H,D,E,F,E,F,D,H,G,C,B,A) \end{verbatim} \end{enumerate} Note that the inner sub-line R is reflected together with the outer sub-line S. \index{Line|)} \section{Beam Line Sequences} \label{sec:sequence} \index{SEQUENCE} \index{Sequence|(} A sequence of elements can easily be generated from a data base using a command looking like \begin{verbatim} label:SEQUENCE,REFER=keyword,L=expression,REFPOS=name; object-definition; ...; object-definition; ENDSEQUENCE; \end{verbatim} It reads a sequence of element definitions, compiles an object which resembles a beam line definition, and gives it the name "label". The resulting sequence can be used like a beam line. Please note this is not yet supported for \texttt{DOPAL-t} and \texttt{DOPAL-cycl}. The attributes of the sequence are: \begin{description} \item[REFER] \index{REFER} The reference points for the elements are specified by the \texttt{REFER} attribute: \begin{description} \item[REFER=CENTRE] \index{CENTRE} The reference points are at the element centres (default). \item[REFER=ENTRY] \index{ENTRY} The reference points are at element entrances. \item[REFER=EXIT] \index{EXIT} The reference points are at element exits. \end{description} \item[L] \index{L} The length of the \texttt{SEQUENCE} can be given on the \texttt{SEQUENCE} command, or it may be entered with the \texttt{ENDSEQUENCE} command. \item[REFPOS] \index{REFPOS} Normally, the reference position for a nested sequence is defined by the \texttt{REFER} attribute of the enclosing sequence, but, if \texttt{REFPOS} is given, it specifies a \textbf{unique} element in the sequence whose \texttt{AT} attribute becomes the reference point for the sequence. \end{description} For each non-drift element in the sequence one element definition appears following the \texttt{SEQUENCE} command and preceding the \texttt{ENDSEQUENCE} command. These look similar to ordinary element definitions see~Chapter~\ref{element}, but they may contain an optional specification to place the element: \begin{verbatim} class-name,AT=expression; class-name,AT=expression,FROM=name; class-name,DRIFT=expression; object-name,class-name, AT=expression,attribute,...,attribute; object-name,class-name, AT=expression,FROM=name,attribute,...,attribute; object-name,class-name, DRIFT=expression,attribute,...,attribute; \end{verbatim} The meaning of the \texttt{AT} specifications is: \begin{description} \item[AT=expression] \index{AT} Place the element's entrance, centre, or exit at the specifiet position. \item[FROM=name] \index{FROM} Interpret the \texttt{AT} specification as relative to the \textbf{unique} element \texttt{name}. \item[FROM=\#S] \index{\#S} Like omitting the \texttt{FROM} specification, \texttt{AT} is relative to the beginning of the sequence. \item[FROM=\#E] \index{\#E} The \texttt{AT} specification is relative to the end of the sequence. \item[FROM=PREVIOUS] \index{PREVIOUS} The \texttt{AT} specification is relative to the previous element. \item[FROM=NEXT] \index{NEXT} The \texttt{AT} specification is relative to the following element. \item[DRIFT=expression] \index{DRIFT} The element is preceded by a drift of the given length. \end{description} One should consider the following: \begin{enumerate} \item The name \texttt{class-name} must be an element class name see~Section~\ref{elm-class}, it may optionally be preceded by a minus sign (\texttt{-}). This inverts the order of the elements in the inserted object. This makes sense only for a beam line or sequence. \item If the name \texttt{object-name} is not given, \textit{OPAL} inserts the element specified by \texttt{class-name}. In this case no further attributes are allowed. \item If there is a non-blank \texttt{object-name}, this name should not be defined earlier in the data. \textit{OPAL} then first makes a copy of \texttt{class-name} and gives it the new name \texttt{object-name}. Any further attributes override the attributes inherited from \texttt{class-name}.b \item The elements must be entered in order of increasing position, and they must not overlap. Their positions are evaluated while reading the \texttt{SEQUENCE} definition, and become \textbf{constant} values. \item A {LINE} see~Section~\ref{line} or {SEQUENCE} see~Section~\ref{sequence} can be nested in another \texttt{SEQUENCE} or \texttt{LINE}. \end{enumerate} Within the \texttt{SEQUENCE}, \textit{OPAL} generates the drift spaces for proper positioning. Example: \begin{verbatim} // Define element classes for a simple cell: B: SBEND,L=35.09,ANGLE = 0.011306116; QF: QUADRUPOLE,L=1.6,K1=-0.02268553; QD: QUADRUPOLE,L=1.6,K1=0.022683642; SF: SEXTUPOLE,L=0.4,K2=-0.13129; SD: SEXTUPOLE,L=0.76,K2=0.26328; // Define the cell as a sequence: CELL:SEQUENCE,L=79.0; B1: B, AT=19.115; SF1:SF,AT=37.42; QF1:QF,AT=38.70; B2: B, AT=58.255,ANGLE=-B1->ANGLE; SD1:SD,AT=76.74; QD1:QD,AT=78.20; ENDSEQUENCE; \end{verbatim} In this example all members of the sequence have a new name, and \textit{OPAL} generates copies of the corresponding classes. The bending magnet \texttt{B1} is wrapped to change sign, but its definition is still equal to \texttt{B}. Thus \texttt{B2}, which has the negative field of \texttt{B1}, has the same effect as the wrapped element \texttt{B1}. \index{Sequence|)} \section{Lines and Sequences with arguments} \index{Line!Argument} \index{Sequence!Argument} \index{Argument!Line} \index{Argument!Sequence} A line or sequence definition can also have parameters like a {MACRO} see~Section~\ref{macro}. Such a line or sequence can be nested (and instantiated) in another line or sequence, but it \textbf{must have a unique name} when instantiated in a sequence. \par Examples: \begin{verbatim} CELL(X,Y):SEQUENCE,L=79; QF&X: QF,AT=...; Y&X: Y,L=1,AT=...; QD&X: QD,AT=...; ENDSEQUENCE; \end{verbatim} When used as \begin{verbatim} CELL12: CELL(12,SF); \end{verbatim} this expands to \begin{verbatim} CELL12:SEQUENCE,L=79; QF12: QF,AT=...; SF12: SF,L=1,AT=...; QD12: QD,AT=...; ENDSEQUENCE; \end{verbatim} A second example: \begin{verbatim} CELL(X,Y):LINE=(D1,QF&X,D2,Y&X,D3,QD&X,D4); \end{verbatim} If the proper drifts are used, this example is equivalent to the sequence example above. \section{Shared Lines} \label{sec:seq-class} \index{Line!Shared} \index{Share Lines} \index{Sequence!Shared} \index{Shared Sequences} Please note this is not yet supported for \texttt{DOPAL-t} and \texttt{DOPAL-cycl}. Normally, when a beam line or sequence is referred to in another line, each reference refers to a \textbf{distinct} copy of the line. \begin{verbatim} L:LINE=(A,B,C); S:SEQUENCE,L=real; ... ENDSEQUENCE; \end{verbatim} Such a line or sequence is cloned when it is inserted in another line or sequence, thus permitting assignment of errors to its elements without affecting other occurrences of the same line. A beam line or sequence can be shared by using the keyword \texttt{SHARED}, \index{SHARED} then the line or sequence is unique, and all references in other lines refer to the \textbf{same} instance. Example: \begin{verbatim} // Define the interaction region common to both rings: SHARED IR2:SEQUENCE,L=...; ... ENDSEQUENCE; RING1:LINE=(...,IR2,...); RING2:LINE=(...,IR2,...); // Now assign imperfections to IR2 wich // will be seen by both rings: EALIGN,LINE=IR2,DX=...,DY=...; \end{verbatim} Counterexample: \begin{verbatim} // Define one superperiod of the machine: SUPER:SEQUENCE,L=...; ... ENDSEQUENCE; // Each occurrence of SUPER is distinct: RING:LINE=(8*SUPER); // Assign different imperfections to each SUPER: EALIGN,LINE=RING,DX=...,DY=...; \end{verbatim} \section{Sequence Editor} \label{sec:editor} \index{Edit!Sequence} \index{Sequence Editor|(} \index{SEQEDIT} \index{ENDEDIT} Please note this is not yet supported for \texttt{DOPAL-t} and \texttt{DOPAL-cycl}. During editing of a sequence, all element positions are evaluated immediately when defined and stored as \textbf{constant} values. To modify a sequence it must be selected for editing by the command \begin{verbatim} SEQEDIT,SEQUENCE=old-name; \end{verbatim} \textit{OPAL} enters editing mode during which it only recognises the sequence editor commands see~Table~\ref{edit}, and makes the sequence \texttt{old-name} the current sequence being edited. Editing mode is switched off by the command \begin{verbatim} ENDEDIT,NAME=new-name; \end{verbatim} If \texttt{new-name} is non-blank, it becomes the name of the edited sequence, otherwise the modified sequence is stored under its old name. \begin{table}[ht] \footnotesize \begin{center} \caption{Commands accepted in editor mode} \label{tab:edit} \begin{tabular}{|p{0.3\textwidth}|p{0.6\textwidth}|} \hline \tabhead{Command & Purpose} \hline \tabline{SELECT}{Select elements to be affected} \tabline{CYCLE}{Change starting point (cyclic interchange)} \tabline{FLATTEN}{Flatten the sequence} \tabline{INSTALL}{Install new elements} \tabline{MOVE}{Move elements} \tabline{REFLECT}{Reflect the sequence} \tabline{REMOVE}{Remove elements} \tabline{REPLACE}{Replace elements} \tabline{ENDEDIT}{Leave sequence edit mode} \hline \end{tabular} \end{center} \end{table} \subsection{Selecting Element(s)} \label{sec:editselect} \index{SELECT} Elements are selected by a command \begin{verbatim} SELECT, RANGE=range, CLASS=name, PATTERN=regex, FULL=logical, CLEAR=logical; \end{verbatim} When the clause \texttt{SELECTED} is used in an editor command, that command acts on all elements currently selected. A selection remains active until it is explicitly turned off by \begin{verbatim} SELECT, CLEAR=TRUE; \end{verbatim} \index{CLEAR} or by an \texttt{ENDEDIT} command \begin{verbatim} ENDEDIT; \end{verbatim} See also details on element selection see~Section~\ref{select}. \subsection{Change Start Point} \label{sec:editcycle} \index{CYCLE} The command \begin{verbatim} CYCLE, START=place; \end{verbatim} \index{START} makes a cyclic interchange of all elements in the current edit sequence so as to start at the specified place see~Section~\ref{aplace}. This element should preferrably be a zero-length element like a \texttt{MARKER}. All further edit commands refer to the \textbf{new} positions. \subsection{Flatten the Sequence being Edited} \label{sec:editflat} The sequence loaded into the editor can be flattened by the command \begin{verbatim} FLATTEN; \end{verbatim} This creates a copy of the sequence with all sub-lines and sub-sequences expanded, thus allowing changes also to elements within those nested parts. \subsection{Install an Element} \label{sec:editinstall} \index{INSTALL} New element(s) can be installed in the edited sequence by the commands \begin{verbatim} object-name: class-name, AT=at-expression, SELECTED, attributes; object-name: class-name, AT=at-expression, FROM=place, attributes; object-name: class-name, AT=at-expression, attributes; class-name, AT=at-expression, SELECTED; class-name, AT=at-expression, FROM=place; class-name, AT=at-expression; \end{verbatim} It has the following attributes: \begin{description} \item[object\_name] The name of the element to be installed. If the object name is given, attributes may also be specified to override the attributes of the class. \item[class\_name] The name of the class from which the element is to be defined. \item[AT] \index{AT} The position where to install the element. \item[FROM] \index{FROM} Three cases are possible: \begin{description} \item[SELECTED] \index{SELECTED} New elements are inserted at \texttt{AT=at-expression} from each currently selected element. \item[FROM=place] A new element is installed at position \texttt{AT=at-expression} relative to the (unique) element at {place} see~Section~\ref{aplace}. \item[FROM omitted or blank] A new element is installed at the absolute position \texttt{AT=at-expression}. \end{description} Relative positions may be negative. \end{description} The two names \texttt{object-name} and \texttt{class-name} interact in the same way as for a sequence definition see~Section~\ref{sequence}. The reference points for elements is defined by the REFER attribute of the \texttt{SEQUENCE}. \subsection{Move an Element} \label{sec:editmove} \index{MOVE} The commands \begin{verbatim} MOVE, SELECTED, BY=by-expression; MOVE, ELEMENT=place, BY=by-expression; MOVE, ELEMENT=place, TO=to-expression; MOVE, ELEMENT=place, TO=to-expression, FROM=from-name; \end{verbatim} move element(s) to new location(s). Three cases are possible: \begin{description} \item[SELECTED,BY=by-expression] \index{SELECTED} All currently selected elements are moved by \texttt{by-expression}. \item[ELEMENT=place,BY=by-expression] \index{ELEMENT} \index{BY} The (unique) element at \texttt{place} is moved by \texttt{by-expression}. \item[ELEMENT=place,TO=to-expression] \index{TO} The (unique) element at \texttt{place} is moved to the absolute position \texttt{to-expression}. \item[ELEMENT=place,TO=to-expression,FROM=from-name] \index{FROM} The (unique) element at {place} see~Section~\ref{aplace} is moved to position \texttt{to-expression} relative to element \texttt{from-name}. A relative position may be negative. \end{description} Except in the first case, it is an error to move more than one element with one \texttt{MOVE} command. The \texttt{MOVE} command must not attempt to change the order of elements in the sequence; elements can not ``hop'' over each other. \subsection{Reflect a Sequence} \label{sec:editreflect} \index{REFLECT} The command \begin{verbatim} REFLECT; \end{verbatim} reverses the order of all elements in the sequence currently being edited. All further editing commands must refer to the \textbf{new} positions. The sequence members are \textbf{not} reflected. \subsection{Remove an Element} \label{sec:editremove} \index{REMOVE} One or more element(s) can be removed by the commands \begin{verbatim} REMOVE, SELECTED; REMOVE, ELEMENT=place; \end{verbatim} Two cases are possible: \begin{description} \item[SELECTED] \index{SELECTED} Removes all currently selected elements, \item[ELEMENT=place] \index{ELEMENT} Removes the single element at {place} see~Section~\ref{aplace}. It is an error of \texttt{name} occurs more than once in the sequence. \end{description} \subsection{Replace an Element} \label{sec:editreplace} \index{REPLACE} The commands \begin{verbatim} REPLACE, SELECTED, BY=new-name; REPLACE, ELEMENT=place, BY=new-name; \end{verbatim} replace one or more element(s) in the sequence. Two cases are possible: \begin{description} \item[SELECTED] \index{SELECTED} All currently selected elements are replaced by an occurrence of the element \texttt{new-name}. \item[ELEMENT=old-name] \index{ELEMENT} The (unique) element at {place} see~Section~\ref{aplace} is replaced by \texttt{new-name}. It is an error if \texttt{old-name} is not unique. \end{description} Example: \begin{verbatim} REPLACE, ELEMENT=QF15, BY=QF17; // replace one element \end{verbatim} \index{Sequence Editor|)} \subsection{Example for the Sequence Editor} \label{sec:editxmpl} \index{Editor Examples} \begin{verbatim} SEQ: SEQUENCE, L=79.00; B1: B, AT=19.115; SF1: SF, AT=37.42; QF1: QF, AT=38.70; B2: B, AT=58.255; SD1: SD, AT=76.74; QD1: QD, AT=78.20; END; B2W:B2,ANGLE=0.1*B2->ANGLE; EDIT, SEQUENCE=SEQ; MOVE, ELEMENT=SF1, TO=-1.27, FROM=QF1; MOVE, ELEMENT=SD1, BY=0.01; REPLACE, ELEMENT=B2, BY=BS2; END, NAME=NEWSEQ; \end{verbatim} This example moves the two sextupoles and replaces the element \texttt{B2} by the element \texttt{B2W}. The effect of the above \texttt{REPLACE} command is equivalent to \begin{verbatim} INSTALL, ELEMENT=B2W, AT=0, FROM=B2; REMOVE, CLASS=B2; \end{verbatim} In this example a new element \texttt{B2W} is installed at the position of \texttt{B2} and the the latter is removed. This works, since all positions are e \clearpage \subsection{CERN SPS Lattice} \label{sec:sps} \index{SPS} The CERN SPS lattice may be represented using the following beam elements: \begin{verbatim} QF:QUADRUPOLE,...; // focusing quadrupole QD:QUADRUPOLE,...; // defocusing quadrupole B1:RBEND,...; // bending magnet of type 1 B2:RBEND,...; // bending magnet of type 2 DS:DRIFT,...; // short drift space DM:DRIFT,...; // drift space replacing two bends DL:DRIFT,...; // long drift space \end{verbatim} The SPS machine is represented by the lines \begin{verbatim} SPS: LINE=(6*SUPER); SUPER: LINE=(7*P44,INSERT,7*P44); INSERT:LINE=(P24,2*P00,P42); P00: LINE=(QF,DL,QD,DL); P24: LINE=(QF,DM,2*B2,DS,PD); P42: LINE=(PF,QD,2*B2,DM,DS); P44: LINE=(PF,PD); PD: LINE=(QD,2*B2,2*B1,DS); PF: LINE=(QF,2*B1,2*B2,DS); \end{verbatim} In order not to overload the example, small gaps between magnetic elements have been omitted. \subsection{LEP Lattice} \label{sec:lep} \index{LEP} A preliminary description of LEP has been given in the \bibref{LEP pink book}{LEP}. Translation of those element sequences to the \textit{OPAL} input format gives: \begin{verbatim} LEP: LINE=(4*SUP); SUP: LINE=(OCT, -OCT); OCT: LINE=(LOBS, RFS, DISS, ARC, DISL, RFL, LOBL); LOBS:LINE=(L1, QS1, L2, QS2, L3, QS3, L4, QS4); RFS: LINE=(L5, QS5, L5, QS6, L5, 2*(QS7, L5, QS8, L5)); DISS:LINE=(QS11, L25, BW, L22, QS12, L25, B4, L22, QS13, L25, B4, L22, QS14, L25, B4, L31, QS15, L25, B4, L32, SF, L23, QS16); ARC: LINE=(L21, B6, L22, SD, L23, QD, 7*(CELL(SF1, SD1), CELL(SF, SD)), CELL(SF1, SD1), L24, B6, L41, QF, L21, B6, L22, SD4, L23, QD, 7*(CELL(SF4, SD3), CELL(SF3, SD4)), CELL(SF4, SD3), L24, B6, L22, SF3, L23); DISL:LINE=(QL16, L34, B4, L22, QL15, L33, B4, L22, QL14, L25, B4, L22, QL13, L25, B4, L22, QL12, L25, BW, L22, QL11); RFL: LINE=(2*(L5, QL8, L5, QL7), L5, QL6, L5, QL5, L5); LOBL:LINE=(QL4, L14, QL3, L13, QL2, L12, QL1, L11); BW: LINE=(W, L26, W); B4: LINE=(B, L26, B); B6: LINE=(B, L26, B, L26,B); CELL(SF,SD):LINE=(L24, B6, L22, SF, L23, QF, L21, B6, L22, SD, L23, QD); \end{verbatim} Here the element definitions have been left out to save space. \section{Global Reference Momentum} \label{sec:P0} \index{P0} Before any physics computations are attempted the following command should be entered: \begin{verbatim} P0=real; \end{verbatim} This command sets the global reference momentum in GeV/c, which is used to compute the magnetic fields from the normalized multipole coefficients. The {BEAM}~command see~Chapter~\ref{beam} then renomalizes the multipole coefficients. This mechanism allows sending a beam with a momentum different from the design momentum through a beam line. \section{BEAM command options} By default the particle momentum is P0 see~Section~\ref{P0}. A different value can be defined by one of the following: \begin{description} \item[ENERGY] \index{ENERGY} \index{Particle!Energy}\index{Energy} \index{Total Energy} The total energy per particle in GeV. If given, it must be greater then the particle mass. \item[PC] \index{PC} \index{Momentum} \index{Particle!Momentum} The momentum per particle in GeV/c. If given, it must be greater than zero. \item[GAMMA] \index{GAMMA} The ratio between total energy and rest energy of the particles $\gamma = E / m_0$. If given, it must be greater than one. If the mass is changed a new value for the energy should be entered. Otherwise the energy remains unchanged, and the momentum and $\gamma$ are recalculated. \end{description} The emittances are defined by: \begin{description} \item[EX] \index{EX} \index{Emittance!Horizontal} The horizontal emittance $E_x=\sigma_x^2/\beta_x$ (default:~1~m). \item[EY] \index{EY} \index{Emittance!Vertical} The vertical emittance $E_y=\sigma_y^2/\beta_y$ (default:~1~m). \item[ET] \index{ET} \index{Emittance!Longitudinal} The longitudinal emittance $E_t=\sigma_e/(p_0c) \cdot c\sigma_t$ (default:~1~m). The emittances can be replaced by the normalised emittances and the energy spread: \item[EXN] \index{EXN} \index{Normalised Emittance}\index{emittance!normalised} The normalised horizontal emittance [m]: $E_{xn}=4\beta\gamma E_x$ (ignored if $E_x$ is given). \item[EYN] \index{EYN} The normalised vertical emittance [m]: $E_{yn}=4\beta \gamma E_y$ (ignored if $E_y$ is given). \item[SIGT] \index{SIGT} \index{Bunch!Length} The bunch length $c\sigma_t$ [m]. \item[SIGE] \index{SIGE} \index{Energy!Spread} The {\em relative} energy spread $\sigma_e/p_0 c$ [1]. \end{description} For the time being, only the particle definition (\texttt{PARTICLE,MASS,CHARGE,PC, ENERGY,GAMMA}) is used. The other parameters will be implemented as needed when new commands become available. %Certain commands compute the synchrotron tune $Q_s$ %from the RF cavities. %If $Q_s\neq 0$, %the relative energy spread $\sigma_e/p_0c$ %and the bunch length $c\sigma_t$ are %\[ %\frac{\sigma_e}{p_0c}=\sqrt{\frac{2\pi Q_s E_t}{\eta C}}, %\qquad %c\sigma_t=\sqrt{\frac{\eta C E_t}{2\pi Q_s}}, %\] %where $C$ is the machine circumference, and %$\eta = (1/\gamma^2) - (1/\gamma_{tr}^2)$. %Finally, the \texttt{BEAM} command accepts %\begin{description} %\item[KBUNCH] % \index{Bunch!Number} % The number of particle bunches in the machine (default:~1). %\item[NPART] % \index{Bunch} % The number of particles per bunch (default:~0). %\item[BCURRENT] % \index{Beam!Current}\index{Bunch!Current} % \index{Current} % The bunch current (default:~0~A). %\item[BUNCHED] % \index{Bunch} % A logical flag. % If set, the beam is treated as bunched whenever this makes sense. %\item[RADIATE] % \index{Radiation} % \index{Synchrotron!Radiation} % A logical flag. % If set, synchrotron radiation is considered in all bipolar magnets. %\end{description} \section{Tracking} \section{Define Initial Conditions} \label{sec:trackstart} \index{START} The \texttt{START} command is not used in \texttt{DOPAL-t} and \texttt{DOPAL-cycl}. In \textit{OPAL-t} and \textit{OPAL-cycl} initial conditions are defined by generating a particle distribution using the \texttt{DISTRIBUTION} command see~Chapter~\ref{distribution} or run \textit{OPAL} in the restart mode see~Section~\ref{Restart}. The \texttt{START} command defines the initial coordinates of the particles to be tracked. There may be many \texttt{START} statements, one for each particle. Particles are always started with coordinates relative to the computed closed orbit for the defined energy error. The command format is: \begin{verbatim} START, X=real, PX=real, Y=real, PY=real, T=real, DELTAP=real; START, FX=real, PHIX=real, FY=real, PHIY=real, FT=real, PHIT=real; \end{verbatim} \texttt{START} statements must be entered after the {TRACK} command see~Section~\ref{trackmode}, but before the {RUN} command see~Section~\ref{trackrun}. \subsection{Absolute Particle Positions} The first form of the {START} command see~Section~\ref{trackstart} defines absolute particle positions see~Section~\ref{variables}: \begin{description} \item[X] \index{X} Horizontal position $x$, referred to the ideal orbit [m]. \item[PX] \index{PX} Horizontal canonical momentum, divided by the reference momentum [1]. \item[Y] \index{Y} Vertical position $y$, referred to the ideal orbit [m]. \item[PY] \index{PY} Vertical canonical momentum, divided by the reference momentum [1]. \item[T] \index{T} The negative time difference, multiplied by the instantaneous velocity of the particle [m]. \item[PT] \index{PT} Momentum error, divided by the reference momentum [1]. \end{description} \subsection{Normalised Particle Positions} The second form of the \texttt{START} command defines normalised particle positions see~Section~\ref{normal}: \begin{description} \item[FX] \index{FX} The normalised amplitude for mode 1 [1]: \item[PHIX] \index{PHIX} The phase for mode 1 [1]: $\phi_x = - \arctan(p_{xn}/x_n) / 2 \pi$, \item[FY] \index{FY} The normalised amplitude for mode 2 [1]: \item[PHIY] \index{PHIY} The phase for mode 2 [1]: $\phi_y = - \arctan(p_{yn}/y_n) / 2 \pi$, \item[FT] \index{FT} The normalised amplitude for mode 3 [1]: \item[PHIT] \index{PHIT} The phase for mode 3 [1]: $\phi_t = + \arctan(p_{tn}/t_n) / 2 \pi$, \end{description} \subsection{Initial Conditions} Mixing absolute and normalised positions is possible, in this case the results are added. Initial conditions $Z$ in unnormalised phase space are related to the closed orbit and the absolute and normalised coordinates as follows: \[ \begin{array}{rcl} Z = Z_{co}&+& \sqrt{E_x} \hbox{\tt FX} (\Re V_k \cos \hbox{\tt PHIX} + \Im V_k \sin \hbox{\tt PHIX}) \\ &+& \sqrt{E_y} \hbox{\tt FY} (\Re V_k \cos \hbox{\tt PHIY} + \Im V_k \sin \hbox{\tt PHIY}) \\ &+& \sqrt{E_t} \hbox{\tt FT} (\Re V_k \cos \hbox{\tt PHIT} + \Im V_k \sin \hbox{\tt PHIT}) \end{array} \] where $Z_{co}$ is the closed orbit vector, and $Z$ is the vector \[ Z = \transpose{(\texttt{X,PX,Y,PY,T,PT})}, \] and $\Re V_k$ and $\Im V_k$ are the real and imaginary parts of the $k^{th}$ eigenvector, which are computed in the {TRACK} command see~Section~\ref{trackmode}. %\section{Define Power Supply Ripple} %\label{sec:tracknoise} %\index{NOISE} %One may define noise to be applied to magnet excitations %with the statement %\begin{verbatim} %NOISE,VARIABLE=variable,AMPLITUDE=real_vector, % FREQUENCY=real_vector,PHASE=real_vector; %\end{verbatim} %The NOISE statement must be entered after the %{TRACK} command see~Section~\ref{trackmode}, %but before the {RUN} command see~Section~\ref{trackrun}. %It has the effect to apply several sinusoidal variations to the %specified parameter. %The command has four attributes. %\begin{description} %\item[VARIABLE] % Reference to the {variable} see~Section~\ref{avariable} to be affected. %\item[AMPLITUDE] % A {vector} see~Section~\ref{avector} of \texttt{real} see~Section~\ref{areal} % noise amplitudes $A_i$. %\item[FREQUENCY] % A {vector} see~Section~\ref{avector} of \texttt{real} see~Section~\ref{areal} % noise frequencies $f_i$. %\item[PHASE] % A {vector} see~Section~\ref{avector} of \texttt{real} see~Section~\ref{areal} % noise phases $phi_i$. %\end{description} %Example: %\begin{verbatim} %NOISE,VARIABLE=QF[K1],AMPLITUDE={1.e-3,2.e-4}, % FREQUENCY=table(2,50*(#+1)),PHASE=table(2,0); %\end{verbatim} %Before each turn is tracked, the noise is re-evaluated as %\[ %\Delta A = \sum_{i=1}^N A_i \cos ( 2\pi (f_i t + \phi_i)). %\] %where $t$ is the real time. \section{Save Particle Positions} \label{sec:tracksave} \index{TSAVE} The \texttt{TSAVE} command is not used in \texttt{DOPAL-t} and \texttt{DOPAL-cycl}. The command \begin{verbatim} TSAVE, FILE=string; \end{verbatim} saves the most recent particle bunch positions on the file named by \texttt{string}. \index{FILE} These will normally be the positions of surviving particles after the most recent {RUN} command see~Section~\ref{trackrun}. If no \texttt{RUN} command has been seen yet, the positions are the result of any {START} commands see~Section~\ref{trackstart} seen. The positions are written as \texttt{START} commands, and the file may be read by a subsequent tracking run. \index{Tracking|)} \section{Element Classes} \label{sec:elm-class} \index{Element!Class} \index{Class!Of Elements} The concept of element classes solves the problem of addressing instances of elements in the accelerator in a convenient manner. It also helps defining portions of the machine which are shared physically between two or more beam lines. This concept will first be illustrated by an example. All the quadrupoles in the accelerator form a class \texttt{QUADRUPOLE}. Let us define three subclasses for the focussing quadrupoles, the defocussing quadrupoles, and the skewed quadrupoles: \begin{verbatim} MQF:QUADRUPOLE, L=LQM, K1=KQF; // Focusing quadrupoles MQD:QUADRUPOLE, L=LQM, K1=KQD; // Defocusing quadrupoles MQT:QUADRUPOLE, L=LQT; // Skewed quadrupoles \end{verbatim} These classes can be thought of as new keywords which define elements with specified default attributes. We now use them to define the real quadrupoles: \begin{verbatim} QD1:MQD; // Defocusing quadrupoles QD2:MQD; QD3:MQD; ... QF1:MQF; // Focusing quadrupoles QF2:MQF; QF3:MQF; ... QT1:MQT, K1S=KQT1; // Skewed quadrupoles QT2:MQT, K1S=KQT2; ... \end{verbatim} These quadrupoles inherit all unspecified attributes from their class. This allows to build up a hierarchy of objects with a rather economic input structure. The full power of the class concept is revealed when object classes are used to select see~Section~\ref{select} instances of elements for printing. \noindent Example: \begin{verbatim} SELECT, CLASS=QUADRUPOLE; // Select all quadrupoles PRINT, CLASS=MQT; // Select skewed quadrupoles \end{verbatim} More formally, for each element keyword \textit{OPAL} maintains a class of elements with the same name. A defined element becomes itself a class which can be used to define new objects, which will become members of this class. A new object inherits all attributes from its class; but its definition may override some of those values by new ones. All class and object names can be used in range selections, providing a powerful mechanism to specify positions for matching constraints and printing. When an object is used in a beam line, \textit{OPAL} automatically makes a copy of that element, unless the object is defined as \texttt{SHARED}. The user can later attach imperfections to all copies individually. Example: \begin{verbatim} QF:QUADRUPOLE,...; // Define the class QF L:LINE=(...,QF,...,QF,...) // Each QF is distinct QF1:QF,...; // QF1 is derived from QF \end{verbatim} On the contrary, if an object is defined as shared using the keyword \texttt{SHARED}, \index{Shared Element} \index{Element!Shared} \index{SHARED} its use in more than one beam line implies the same object occurs in all those beam lines. Example: \begin{verbatim} SHARED QF:QUADRUPOLE,...; // Define shared quadrupole // QF L1:LINE=(...,QF,...,QF,...) // All the QF's are the same // ... L2:LINE=(...,QF,...) // ... also in this line. \end{verbatim} This is a restricted feature: \texttt{DOPAL-t}, \texttt{DOPAL-cycl}. \subsection{BEND \textit{OPAL-map} Mode} \label{sec:opalmap:bend} The two types of bending magnets are defined by the commands: \begin{verbatim} SBEND,TYPE=string, APERTURE=real-vector, L=real, ANGLE=real, K0=real, K1=real, K2=real, K3=real, K0S=real, K1S=real, K2S=real, K3S=real, E1=real, E2=real, H1=real, H2=real, HGAP=real,FINT=real; RBEND,TYPE=string, APERTURE=real-vector, L=real, ANGLE=real, K0=real, K1=real, K2=real, K3=real, K0S=real, K1S=real, K2S=real, K3S=real, E1=real, E2=real, H1=real, H2=real, HGAP=real, FINT=real; \end{verbatim} For both types, the following attributes are permitted: \begin{description} \item[L] \index{L} The length of the magnet (default: 0~m). For a rectangular magnet the length is measured along a straight line, while for a sector magnet it is the arc length of the reference orbit. A thin dipole see~Section~\ref{thin} is described with length zero. In this case all fields are the integrated fields. \\ \item[ANGLE] \index{ANGLE} The \textbf{geometric} bend angle (default: 0 rad). It is this attribute only which determines the geometry of the magnet. A positive bend angle bends the reference axis to the right, i.e. towards negative $x$~values. \\ \item[K0] \index{K0} The normal dipole component $K_0=\frac{1}{B \rho}B_y$. If this value is not given, it is taken as \texttt{ANGLE/L}. A positive value bends positive particles to the right (towards negative $x$).\\ \item[K0S] \index{K0S} The skew dipole component $K_{0S}=\frac{1}{B \rho}B_x$. The default is $0 \mathrm{m}^{-2}$. The component is positive for a bend up.\\ \item[K1] \index{K1} The normal quadrupole component $K_1=\frac{1}{B \rho}\diffp{B_y}{x}$. The default is $0 \mathrm{m}^{-2}$. The component is positive, if $B_y$ is positive on the positive $x$-axis. This implies horizontal focusing of positively charged particles which travel in positive $s$ direction.\\ \item[K1S] \index{K1S} The skew quadrupole component $K_{1s}=\frac{1}{B \rho}\diffp{B_x}{x}$. The default is $0 \mathrm{m}^{-2}$. The component is negative, if $B_x$ is positive on the positive $x$-axis.\\ \item[K2] \index{K2} The normal sextupole component $K_2=\frac{1}{B \rho}\diffp[2]{B_y}{x}$. The default is $0 \mathrm{m}^{-3}$. The component is positive, if $B_y$ is positive on the positive $x$-axis.\\ \item[K2S] \index{K2S} The skew sextupole component $K_{2s}=\frac{1}{B \rho}\diffp[2]{B_x}{x}$. The default is $0 \mathrm{m}^{-3}$. The component is negative, if $B_x$ is positive on the positive $x$-axis.\\ \item[K3] \index{K3} The normal sextupole component $K_3=\frac{1}{B \rho}\diffp[3]{B_y}{x}$. The default is $0 \mathrm{m}^{-4}$. The component is positive, if $B_y$ is positive on the positive $x$-axis.\\ \item[K3S] \index{K3S} The skew sextupole component $K_{3s}=\frac{1}{B \rho}\diffp[3]{B_x}{x}$. The default is $0 \mathrm{m}^{-4}$. The component is negative, if $B_x$ is positive on the positive $x$-axis.\\ \item[E1] \index{E1} The rotation angle for the entrance pole face (default: 0 rad). \item[E2] \index{E2} The rotation angle for the exit pole face (default: 0 rad). \item[H1] \index{H1} The curvature of the entrance pole face (default: $0 \mathrm{m}^{-1}$).\\ \item[H2] \index{H2} The curvature of the exit pole face (default: $0~\mathrm{m}^{-1}$). A positive pole face curvature induces a negative sextupole component; i.e. for positive \texttt{H1} and \texttt{H2} the centres of curvature of the pole faces are placed inside the magnet.\\ \end{description} \section{Thin Lenses} \label{sec:thin} \index{Thin Lens} All multipole-like elements (\texttt{RBEND, SBEND, QUADUPOLE, SEXTUPOLE, OCTUPOLE, MULTIPOLE}) can have a finite or a zero length. This does not apply to \textit{OPAL-t} and \textit{OPAL-cycl} where the elements have to have a finite length and elements with zero length are ignored. For finite length the multipole coefficients are the coefficients per unit length; for zero length they are interpreted as the integrated strength. The {SAVE} command see~Section~\ref{save} converts thin elements to thin multipoles. \section{Markers} \label{sec:marker} \index{MARKER} \begin{verbatim} label: MARKER, TYPE=string, APERTURE=vector; \end{verbatim} The simplest element which can occur in a beam line is the \texttt{MARKER}. It has no effect on the beam, but it allows one to identify a position in the beam line, for example to apply a matching constraint. A marker has no attributes: \noindent Example: \begin{verbatim} M27:MARKER; \end{verbatim} This is a restricted feature: \texttt{DOPAL-t}, \texttt{DOPAL-cycl}. \section{Orbit Correctors} \label{sec:corrector} \index{Orbit Corrector} \index{KICKER} \index{HKICKER} \index{VKICKER} Three types of closed orbit correctors are available: \begin{description} \item[HKICKER] \index{HKICKER} \label{sec:hkicker} A corrector for the horizontal plane, \item[VKICKER] \index{VKICKER} \label{sec:vkicker} A corrector for the vertical plane, \item[KICKER] \index{KICKER} \label{sec:kicker} A corrector for both planes. \end{description} \begin{verbatim} label:HKICKER, TYPE=string, APERTURE=real-vector, L=real, KICK=real; label:VKICKER, TYPE=string, APERTURE=real-vector, L=real, KICK=real; label:KICKER, TYPE=string, APERTURE=real-vector, L=real, HKICK=real, VKICK=real; \end{verbatim} They have the following attributes: \begin{description} \item[L] \index{L} The length of the closed orbit corrector (default: 0~m). \item[KICK] \index{KICK} The kick angle for either horizontal or vertical correctors. (default: 0~rad). \item[HKICK] \index{HKICK} The horizontal kick angle for a corrector in both planes (default: 0~rad). \item[VKICK] \index{VKICK} The vertical kick angle for a corrector in both planes (default: 0 rad). \end{description} A positive kick increases $p_{x}$ or $p_{y}$ respectively. \noindent Examples: \begin{verbatim} HK1:HKICKER, KICK=0.001; VK3:VKICKER, KICK=0.0005; KHV:KICKER, HKICK=0.001, VKICK=0.0005; \end{verbatim} The first kicker is rotated about the longitudinal axis by 10 degrees. The reference system for an orbit corrector is a Cartesian coordinate system see~Figure~\ref{straight}. \subsection{RFCavities \textit{OPAL-map} mode} The following attributes are supported only by the \textit{OPAL-map} mode \begin{description} \item[HARMON] \index{HARMON} The harmonic number $h$ (no default). Note that the RF frequency is computed from the harmonic number and the revolution frequency $f_0$. \textbf{The frequency attribute \texttt{FREQ} must no longer be used.} \item[BETRF] \index{BETRF} RF coupling factor (default: 0). \item[PG] \index{PG} The RF power per cavity (default: 0~mW). \item[SHUNT] \index{SHUNT} The relative shunt impedance (default: $0 M\Omega/\mathrm{m}$). \item[TFILL] \index{TFILL} The filling time of the cavity $T_\mathrm{fill}$ (default: $0 \mu\mathrm{s}$). \end{description} Use of a cavity requires the particle momentum \texttt{P} and the particle charge \texttt{CHARGE} to be set on the relevant optics command before any calculations is performed. \noindent Example: \begin{verbatim} CAVITY:RFCAVITY, L=10.0, VOLT=150.0, LAG=0.0, HARMON=31320; STATIC, P=50.0, PARTICLE=ELECTRON; \end{verbatim} The reference system for a cavity is a Cartesian coordinate system see~Figure~\ref{straight}. \section{Electrostatic Separators} \label{sec:separator} \index{ELSEPARATOR} \index{Separator} An \texttt{ELSEPARATOR} (electrostatic separator) has three real attributes: \begin{verbatim} label:ELSEPARATOR, TYPE=string, APERTURE=real-vector, L=real, EX=real, EY=real; \end{verbatim} \begin{description} \item[L] \index{L} The length of the separator (default: 0~m). \item[EX] \index{EX} The horizontal electric field strength (default: 0~MV/m). A positive field increases $p_x$ for positive particles. \item[EY] \index{EY} The vertical electric field strength (default: 0~MV/m). A positive field increases $p_y$ for positive particles. \end{description} A \texttt{ELSEPARATOR} requires the particle momentum \texttt{P} and its charge \texttt{CHARGE} to be set in the relevant {BEAM} command see~Chapter~\ref{beam} before any calculations are performed. \noindent Example: \begin{verbatim} BEAM, PARTICLE=POSITRON, PC=46.0; SEP:ELSEPARATOR, L=5.0, E=0.5; \end{verbatim} The reference system for a separator is a Cartesian coordinate system see~Figure~\ref{straight}. \subsection{\textit{OPAL-t} mode} \subsection{\textit{OPAL-cycl} mode} This is a restricted feature: \texttt{DOPAL-t}, \texttt{DOPAL-cycl}. \section{Beam Position Monitors} \label{sec:monitors} \index{MONITOR} \index{HMONITOR} \index{VMONITOR} A beam monitor acts on the beam like a drift space. In addition it records the beam position for closed orbit corrections. Four different types of beam position monitors are recognised: \begin{description} \item[HMONITOR] \label{sec:hmonitor} Monitor for the horizontal beam position, \item[VMONITOR] \label{sec:vmonitor} Monitor for the vertical beam position, \item[MONITOR] \label{sec:monitor} Monitor for both horizontal and vertical beam position. \item[INSTRUMENT] \label{sec:instrument} A place holder for any other type of beam instrumentation. Optically it behaves like a drift space; it returns \textbf{no beam observation}. It represents a class of elements which is completely independent from drifts and monitors. \end{description} \begin{verbatim} label:HMONITOR, TYPE=string, APERTURE=real-vecto, L=real; label:VMONITOR, TYPE=string, APERTURE=real-vecto, L=real; label:MONITOR, TYPE=string, APERTURE=real-vecto, L=real; label:INSTRUMENT, TYPE=string, APERTURE=real-vector, L=real; \end{verbatim} A beam position monitor has one real attribute: \begin{description} \item[L] \index{L} The length of the monitor (default: 0~m). If the length is different from zero, the beam position is recorded in the centre of the monitor (except for the \texttt{INSTRUMENT} element). \end{description} \noindent Examples: \begin{verbatim} MH:HMONITOR, L=1; MV:VMONITOR; \end{verbatim} The reference system for a monitor is a Cartesian coordinate system see~Figure~\ref{straight}. \section{Coordinate Transformations} \label{sec:rotation} \subsection{Rotations About the Vertical Axis} \label{sec:yrot} \index{Rotation} \index{Coordinate!Change} \index{YROT} \begin{verbatim} label:YROT, TYPE=string, APERTURE=real-vector, ANGLE=real; \end{verbatim} The element \texttt{YROT} rotates reference system about the vertical ($y$) axis see~Figure~\ref{yrot}. \texttt{YROT} has no effect on the beam, but it causes the beam to be referred to the new coordinate system \[\begin{array}{lcl} x_2&=&x_1\cos\theta-s_1\sin\theta, \\ y_2&=&x_1\sin\theta+s_1\cos\theta, \end{array}\] It has one real attribute: \begin{description} \item[ANGLE] \index{ANGLE} The rotation angle theta (default: 0 rad). It must be a \textbf{small} angle, i.e. an angle comparable to the transverse angles of the orbit. \end{description} A positive angle means that the new reference system is rotated clockwise about the local $y$-axis with respect to the old system. \noindent Example: \begin{verbatim} KINK:YROT, ANGLE=0.0001; \end{verbatim} \subsection{Rotations Around the Longitudinal Axis} \label{sec:srot} \index{Rotation} \index{Coordinate!Change} \index{SROT} \begin{verbatim} label:SROT, TYPE=string, APERTURE=real-vector, ANGLE=real; \end{verbatim} The element \texttt{SROT} rotates the reference system about the longitudinal ($s$) axis see~Figure~\ref{srot}. \texttt{SROT} has no effect on the beam, but it causes the beam to be referred to the new coordinate system \[\begin{array}{lcl} x_2&=&x_1\cos\psi-y_1\sin\psi, \\ y_2&=&x_1\sin\psi+y_1\cos\psi, \end{array}\] It has one real attribute: \begin{description} \item[ANGLE] \index{ANGLE} The rotation angle psi (default: 0~rad) \end{description} A positive angle means that the new reference system is rotated clockwise about the $s$-axis with respect to the old system. \noindent Example: \begin{verbatim} ROLL1:SROT, ANGLE=PI/2.; ROLL2:SROT, ANGLE=-PI/2.; HBEND:SBEND, L=6.0, ANGLE=0.01; VBEND:LINE=(ROLL1, HBEND, ROLL2); \end{verbatim} The above is a way to represent a bend down in the vertical plane, it could be defined more simply by \begin{verbatim} VBEND:SBEND, L=6.0, K0S=-0.01/6.0; \end{verbatim} \subsection{General Change of Reference} \label{sec:patch} \index{Reference!Change} \index{Coordinate!Change} \index{PATCH} \begin{verbatim} label:PATCH, TYPE=string, APERTURE=real-vector, DX=real, DY=real, DZ=real, DTHETA=real, DPHI=real, DPSI=real; \end{verbatim} The element \texttt{PATCH} applies a general change to the reference system. \texttt{PATCH} has no effect on the beam, but it causes the beam to be referred to the new coordinate system. It has six real attributes: \begin{description} \item[DX] \index{DX} The displacement in $x$-direction of the new system with respect to the old one. \item[DY] \index{DY} The displacement in $y$-direction of the new system with respect to the old one. \item[DS] \index{DS} The displacement in $s$-direction of the new system with respect to the old one. \item[VX] \index{VX} The rotation around the $x$-axis of the new system with respect to the old one. \item[VY] \index{VY} The rotation around the $y$-axis of the new system with respect to the old one. \item[VZ] \index{VZ} The rotation around the $s$-axis of the new system with respect to the old one. \end{description} \noindent As an example consider a simplified model of the separation of the two beams see~Figure~\ref{patch} near the interaction region of LHC: \begin{verbatim} ALPHA=...; // The bend angle in the separator magnets. DISTANCE=...; // The longitudinal distance between // the separator magnets. D1:HKICKER, L=0, KICK=ALPHA; D2:HKICKER, L=0, KICK=-ALPHA; DIST:DRIFT, L=DISTANCE; PATCH1:PATCH, DX=DISTANCE*TAN(ALPHA); PATCH2:PATCH, DX=-DISTANCE*TAN(ALPHA); SHARED SEPARATION:LINE=(D1, DIST, D2); RING1:SEQUENCE,...; // beam goes clockwise. ... SEPARATION; PATCH1; // change reference to ... ENDSEQUENCE; RING2:SEQUENCE,...; // beam goes anticlockwise. ... SEPARATION; PATCH2; ... ENDSEQUENCE; \end{verbatim} The direction of travel of each beam determines the signs of the deflections, the patches change the reference. Note that the common reference between the two separator magnets allows a correct handling of long-distance beam-beam interactions in that area. \begin{figure}[ht] \begin{center} \begin{picture}(400,90) \thinlines \drawline(0,40)(100,40) \drawline(100,40)(200,60)(300,60) \put(240,65){\vector(1,0){20}} \put(305,60){\makebox(0,0)[l]{reference beam 1}} \dashline[30]{8}(100,40)(200,40) \put(205,40){\makebox(0,0)[l]{common reference}} \drawline(100,40)(200,20)(300,20) \put(260,15){\vector(-1,0){20}} \put(305,20){\makebox(0,0)[l]{reference beam 2}} \drawline(100,10)(100,70) \put(100,75){\makebox(0,0)[b]{\texttt{D1}}} \drawline(200,10)(200,70) \put(200,75){\makebox(0,0)[b]{\texttt{D2}+patches}} \end{picture} \caption{Separation of two beams} \label{fig:patch} \end{center} \end{figure} This is a restricted feature: \texttt{DOPAL-t}, \texttt{DOPAL-cycl}. \section{Editing Element Definitions} \label{sec:elm-edit} \index{Element!Editing} \index{Edit!Element} An element definition can be changed in two ways: \begin{description} \item[Entering a new definition] The element definition will be replaced. A beam element, {LINE} see~Section~\ref{line}, or {SEQUENCE} see~Section~\ref{sequence} can be replaced by another beam element, beam line, or sequence; if the replaced item occurs in another beam line or sequence, all references in that line or sequence are replaced. \item[Entering the element name together with new attributes] The element will be updated in place, and the new attribute values will replace the old ones. When the type of the element should not change, replacement of an attribute is the more efficient way. \end{description} Element definitions can be changed freely. The changes do not affect already defined objects which belong to its class see~Section~\ref{elm-class}. This example shows two ways to change the strength of a quadrupole: \begin{verbatim} QF:QUADRUPOLE, L=1, K1=0.01; // Original definition of QF QF:QUADRUPOLE, L=1, K1=0.02; // Replace whole definition // of QF QF, K1=0.02; // Replace value of K1 \end{verbatim} \subsection{\textit{OPAL-t} mode} \subsection{\textit{OPAL-cycl} mode} This is a restricted feature: \texttt{DOPAL-t}, \texttt{DOPAL-cycl}. % %\section{Beam-Beam Interactions} %\label{sec:beambeam} %\index{BEAMBEAM} %\index{Interaction!Beam-Beam} %The command \texttt{BEAMBEAM} may be inserted in a beam line %to simulate a beam-beam interaction point: %\begin{verbatim} %label:BEAMBEAM,TYPE=string,APERTURE=real-vector, % SIGX=real,SIGY=real,XMA=real,YMA=real,CHARGE=real; %\end{verbatim} %The code for this element has been contributed by J.M. Veuillen (1987), %and has been adapted to C++ in 1997. %It has six real attributes: %\begin{description} %\item[SIGX] % \index{SIGX} % The horizontal extent (standard deviation) of the opposite beam % (default: 0~m). %\item[SIGY] % \index{SIGY} % The vertical extent (standard deviation) of the opposite beam % (default: 0~m). %\item[XMA] % \index{XMA} % The horizontal displacement of the opposite beam with respect to % the ideal orbit (default: 0~m). %\item[YMA] % \index{YMA} % The vertical displacement of the opposite beam with respect to % the ideal orbit (default: 0~m). %\item[CHARGE] % \index{CHARGE} % The charge of particles in the opposite beam in proton charges % (default: 0). %\item[NPART] % \index{NPART} % The number of particles in the opposite beam. % (default: 0). %\end{description} %A beam-beam element requires the particle momentum \texttt{P} %and its charge \texttt{CHARGE} to be defined on the relevant optics command %before any calculations are performed. %\noindent Example: %\begin{verbatim} %BEAM,MOMENTUM=46.0,MASS=PMASS,CHARGE=1.0; %BB:BEAMBEAM,SIGX=1.E-3,SIGY=5.E-4,CHARGE=1.0,NPART=1.0E12; %\end{verbatim} %A three-dimensional representation of a beam-beam interaction is %available with the command %\index{BEAMINT} %\index{Interaction!Beam-Beam} %\begin{verbatim} %label:BEAMINT,TYPE=string,APERTURE=real-vector, % PHI=real,NSLI=integer,FAST=bool,XIYN=real,DX=real,DY=real,DZ=real, % BETXS=real,BETYS=real,ALFXS=real,ALFYS=real, % DXS=real,DPXS=real,DYS=real,DPYS=real, % EXS=real,EYS=real,SIGTS=real,SIGES=real; %\end{verbatim} %Its parameters are: %\begin{description} %\item[PHI] % \index{PHI} % Horizontal crossing angle. %\item[NSLI] % \index{NSLI} % Number of slices to be taken in strong beam. %\item[FAST] % \index{FAST} % If true, use tables for computing the error function. %\item[XIYN] % \index{XIYN} % Beam-beam parameter. %\item[DX] % \index{DX} % Horizontal displacement of the interaction point in [m]. %\item[DY] % \index{DY} % Vertical displacement of the interaction point in [m]. %\item[DZ] % \index{DZ} % Longitudinal displacement of the interaction point in [m]. %\end{description} %The following parameters describe the strong beam: %\begin{description} %\item[BETXS] % \index{BETXS} % Horizontal $\beta*$ in [m]. %\item[BETYS] % \index{BETYS} % Vertical $\beta*$ in [m]. %\item[ALFXS] % \index{ALFXS} % Horizontal $\alpha*$* in [1]. %\item[ALFYS] % \index{ALFYS} % Vertical $\alpha*$ in [1]. %\item[DXS] % \index{DXS} % Horizontal dispersion in [m]. %\item[DPXS] % \index{DPXS} % Horizontal dispersion slope in [m]. %\item[DYS] % \index{DYS} % Vertical dispersion in [m]. %\item[DPYS] % \index{DPYS} % Vertical dispersion slope in [m]. %\item[EXS] % \index{EXS} % Horizontal emittance in [m rad]. %\item[EYS] % \index{EYS} % Vertical emittance in [m rad]. %\item[SIGTS] % \index{SIGTS} % Bunch length in [m]. %\item[SIGES] % \index{SIGES} % Energy spread in [1]. %\end{description} \section{Tracking Example} \label{sec:trackxmpl} \begin{verbatim} L: LINE=(OCT,-OCT); // Misalignments and closed orbit correction may be done here. P0=60.0; B:BEAM, ENERGY=60.0; TRACK, LINE=L,BEAM=B; START, X=0.001, Y=0.001, PT=0.001; RUN, TURNS=1024; ENDTRACK; \end{verbatim} \input{footer}