makethin.tex

%%\title{MAKETHIN}
%  Changed by: Helmut Burkhardt,  7-April-2005 
%  Changed by: Helmut Burkhardt, Ghislain Roy -  6-Mai-2014 
 
\chapter{Slicing a sequence into thin lenses}
\label{chap:makethin}

This module takes a sequence with thick elements and creates another one 
with similar functionality but composed of
thin (zero length) element slices or simplified thick slices as required
by \madx tracking or conversion to \texttt{SIXTRACK} input format.

DISCLAIMER: Several \madx commands such as {\texttt{ELIGN}}, {\texttt{EFCOMP}} won't directly work on sequences produced by {\texttt{MAKETHIN}}. In order to use such commands on a thin sequence, it is advisable to save the sequence on a file, and then re-load it.

\section{MAKETHIN}
\label{sec:makethin}

The slicing is performed by the command: 
\madbox{
MAKETHIN, SEQUENCE=seqname, STYLE=string, MAKEDIPEDGE=logical;
}

The parameters are defined as: 
\begin{madlist}
   \ttitem{SEQUENCE} seqname is the name of the sequence to be
   processed to thin slices. The sequence must be active, i.e. it should
   have been previously loaded with a \hyperref[sec:use]{\texttt{USE}} command.  
   The sequence must use the default positioning of elements
   ({\texttt{REFER=centre}}). 

   \ttitem{STYLE} the slicing style to be used for all active elements (excluding corrector magnets).
   The corrector magnets and the inactive elements are instead sliced so there is a slice in the 
   beginning and in end of the location of the thick element.  \\
   Available slicing styles are: 

   \begin{madlist}
   	\ttitem{TEAPOT} is the default slicing algorithm for all elements 
   	except collimators and is described in \cite{burkhardt2013}. 
   	\texttt{TEAPOT} is a clear improvement over the \texttt{SIMPLE} algorithm.
   	
   	\ttitem{SIMPLE} produces slices of equal strength and length at equidistant
   	positions.
   	
   	\ttitem{COLLIM} is the default slicing algorithm for collimators. 
   	If only one slice is chosen it is placed in the middle of the old
   	element. If two slices are chosen they are placed at either
   	end. Three slices or more are treated as one slice. 
   	
   	\ttitem{HYBRID} is the previous default algorithm 
   	that was active up to version 5.02.05 when the \texttt{STYLE} 
   	attribute was not given; the standard slicing for all
   	elements, except collimators, is \texttt{TEAPOT} if the number
   	of slices is less or equal to four, and \texttt{SIMPLE} otherwise.
   
   \end{madlist}
   
   \ttitem{MAKEDIPEDGE} is a logical flag to control the generation of
   \texttt{DIPEDGE} elements at the start and/or end of bending magnets,
   to conserve edge focusing from pole face angles \texttt{E1, E2}
   or extra fields described by \texttt{FINT, FINTX}, in the
   process of slicing bending magnets to thin multipole slices.   
   Selection with \texttt{THICK=true} will translate a complex thick 
   \texttt{RBEND} or \texttt{SBEND}, including edge effects, to a simple
   thick \texttt{SBEND} with edge focusing transferred to extra 
   \texttt{DIPEDGE} elements. \\ 
   (Default:~true)
\end{madlist}

Example:
\madxmp{
! keep translated rbend as thick sbend \\
SELECT, FLAG=makethin, CLASS=rbend, THICK=true;
}

\section{Controlling the number of slices}
\label{sec:numberofslices}

The number of slices can be set individually for elements or groups of
elements using the \texttt{SELECT} command
\madxmp{
SELECT, \=FLAG=makethin, \\
        \>RANGE=range, CLASS=class, PATTERN=pattern[,FULL][,CLEAR], \\
        \>THICK=logical, SLICE=integer;
}
where the argument to the attribute \texttt{SLICE} stands for the number of
slices for the selected elements. The default is one slice and
\texttt{THICK=false} for all elements, i.e. conversion of all thick
elements to a single thin slice positioned at the centre of the original
thick element.

Note that \texttt{THICK=true} only applies to dipole, quadrupole or solenoid magnetic
elements and is ignored otherwise.

\texttt{MAKETHIN} allows for thick quadrupole slicing with insertion of
thin \texttt{MULTIPOLE} elements between thick slices. 
Positioning is done with markers between
slices, here however with thick slice quadrupole piece filling the whole
length.

\textbf{Examples:}
\madxmp{
! slice quadrupoles in three thick slices, insert 2 markers per quadrupole \\
SELECT, FLAG=makethin, CLASS=quadrupole, THICK=true, SLICE=3; \\ 
\\
! thick slicing for quadrupoles named mqxa, insert one marker in the middle \\
SELECT, FLAG=makethin, PATTERN=mqxa$\backslash$., THICK=true, SLICE=2; 
}

Slicing can be turned off for certain elements or classes by specifying
a number of slices $< 1$. Examples: 
\madxmp{
! turn off slicing for sextupoles \\
SELECT, FLAG=makethin, CLASS=sextupole, SLICE=0;  \\
\\
! keep elements unchanged with names starting by mbxw \\
SELECT, FLAG=makethin, PATTERN=mbxw$\backslash$., SLICE=0; 
}
This option allows to introduce slicing step by step and monitor the 
resulting changes in optics parameters.

Keep in mind however that subsequent tracking generally requires full
slicing, with possible exception of dipole and quadrupole magnetic elements. 

\section{Choice of options for dipoles}

There are several options that affect the slicing of a sequence. 
Depending whether dipole magnets (\hyperref[sec:bend]{\texttt{RBEND} 
or \texttt{SBEND}}) are kept as thick elements 
(See \hyperref[sec:select]{\texttt{SELECT, FLAG=makethin}}) and 
whether the \hyperref[sec:makethin]{\texttt{MAKEDIPEDGE}} option 
of \texttt{MAKETHIN} is used to generate 
\hyperref[sec:dipedge]{\texttt{DIPEDGE}} elements around these bending magnets, 
the resulting sequence is more adapted to optics calculation or tracking. 
The following table gives an indication of the best choice of options for 
dipole elements 

\begin{table}[ht]
  \caption{Best choice of options in \texttt{MAKETHIN}}
  \vspace{1ex}
  \centering
  \begin{tabular}{|l|l|l|}
    \hline
    & \texttt{THICK=false} & \texttt{THICK=true}\\
    \hline
    \texttt{MAKEDIPEDGE=false} & backward compatibility & thick optics calculations \\
    \hline
    \texttt{MAKEDIPEDGE=true} & thin tracking & thick tracking \\
    \hline
  \end{tabular}
\end{table}

The combination of \hyperref[sec:numberofslices]{\texttt{THICK=false}} 
(dipoles converted to thin lenses) 
and \hyperref[sec:makethin]{\texttt{MAKEDIPEDGE=false}} 
(no \hyperref[sec:dipedge]{\texttt{DIPEDGE}} 
thin elements inserted around the dipoles) results in a lattice with 
Twiss parameters that can differ significantly from those of 
the original sequence. 
This is most obvious with the tune or phase advance parameters 
that are generally differing by a significant amount (see first 
hint below). This combination is however useful for backward compatibility 
with previous versions of \texttt{MAKETHIN} before 
\hyperref[sec:dipedge]{\texttt{DIPEDGE}} elements were
implemented. 

The combination of \hyperref[sec:numberofslices]{\texttt{THICK=true}} 
(dipoles are kept as thick elements and not converted to thin lenses) 
and \hyperref[sec:makethin]{\texttt{MAKEDIPEDGE=false}} 
(\hyperref[sec:dipedge]{\texttt{DIPEDGE}} thin elements 
are not inserted around the thick dipoles to replace the edge effects 
that stay with the bends themselves) 
results in a lattice with \hyperref[chap:twiss]{\texttt{TWISS}} parameters 
very comparable to those of the original sequence. The dipoles are still 
thick elements, eventually sliced, with proper edge effects up to second 
order, although non-symplectic.
This is the best combination for optics studies without particle tracking, 
e.g. with \hyperref[chap:twiss]{\texttt{TWISS}}. 

The combination of \hyperref[sec:numberofslices]{\texttt{THICK=false}}
for dipoles and \hyperref[sec:makethin]{\texttt{MAKEDIPEDGE=true}} 
transforms the original dipoles into one or several thin slices without 
any edge effect, surrounded by a pair of
\hyperref[sec:dipedge]{\texttt{DIPEDGE}}  
elements at the original location of dipole entrance and exit. 
Note however that these \hyperref[sec:dipedge]{\texttt{DIPEDGE}}
elements only contain first order effects for the purpose of tracking. 

The combination of \hyperref[sec:numberofslices]{\texttt{THICK=true}}
for dipoles and \hyperref[sec:makethin]{\texttt{MAKEDIPEDGE=true}} 
conserves the dipoles as thick element dipole bodies only while their
associated edge effects are transferred to
\hyperref[sec:dipedge]{\texttt{DIPEDGE}} elements that are taken into
account at first order only for symplectic tracking. 

\section{Additional information}

The generated thin lens sequence has the following properties: 
\begin{itemize}
\item The new sequence has the same name as the original. 
  The original sequence is replaced by the new one in memory. 
  If the original sequence is needed for further processing in \madx, 
  it should be reloaded.
\item The algorithm also processes any sub-sequence inserted in the main
  sequence. These sub-sequences are also given the same names as the
  original ones. 
\item Any element transformed into a single thin lens element has the
  same name as the original. 
\item If an element is sliced into more than one \textbf{thin} slices, the individual
  slices have the same basename as the original element plus a suffix 
  \texttt{..1}, \texttt{..2}, etc. and a marker with the name of the
  original element is placed at the location of the center of the
  original element. 
\item If an element is sliced into more than one \textbf{thick} slices, the individual
  slices have the same basename as the original element plus a suffix \texttt{\_EN} the first one, a suffix \texttt{\_EX} the last one, and a suffix \texttt{\_BO} the ones in between.
\end{itemize}


\textbf{Hints}
\begin{enumerate}
\item Compare the main optics parameters like tunes before and after slicing
  with \texttt{MAKETHIN}. Rematch tunes and chromaticity as necessary after
  \texttt{MAKETHIN}. 

\item In tests, turn off slicing for some of the main element classes to
  identify the main sources of changes. 

\item For sextupoles and octupoles, a single slice should always be sufficient.

\item Increase the number of slices for critical elements like mini-beta
  quadrupoles. Even there, more than four slices should rarely be
  required. 

\item In case of problems or doubts, consider to
  \texttt{FLATTEN} the sequence before slicing.  

\item See the
  \href{http://madx.web.cern.ch/madx/madX/examples/makethin/}{examples}
  for makethin. \\ 
  See also the presentations on the upgrade of the makethin module:\\
  \href{http://ab-dep-abp.web.cern.ch/ab-dep-abp/LCU/LCU_meetings/2012/20120918/LCU_makethin_2012_09_18.pdf}{LCU\_makethin\_2012\_09\_18.pdf}, and \\
  \href{http://ab-dep-abp.web.cern.ch/ab-dep-abp/LCU/LCU_meetings/2013/20130419/LCU_makethin_2013_04_19.pdf}{LCU\_makethin\_2013\_04\_19.pdf}. \\ 
  TEAPOT is documented in \href{http://accelconf.web.cern.ch/AccelConf/IPAC2013/papers/mopwo027.pdf}{IPAC'13 MOPWO027}

\end{enumerate}

%%%%%%%%