sodd.tex

%%\title{SODD}
%  Changed by: E. T. d'Amico, 8-Sep-2004 
%\href{http://xwho.web.cern.ch/xwho/people/show/6175}{damico}, September 10, 2004 

\chapter{SODD: Second Order Detuning and Distortion}

The \texttt{SODD} command calculates the Second Order Detuning and
Distortion, as described in \cite{bengtsson1990}, on the beam line
defined by the last \texttt{USE} command followed by a \texttt{TWISS}
command. 

The \texttt{SODD} command is based on the stand-alone program\cite{SODD}
with the same name, with analytical computation extended to the second
order distortion\cite{schmidt1999}. 

\madbox{
SODD, \=DETUNE=logical, DISTORT1=logical, DISTORT2=logical, \\
      \>START\_STOP = start,stop, \\
      \>MULTIPOLE\_ORDER\_RANGE = first,last, \\
      \>NOPRINT=logical, PRINT\_ALL=logical, PRINT\_AT\_END=logical, \\
      \>NOSIXTRACK=logical;
}

The attributes of the \texttt{SODD} command are:
\begin{madlist}
  \ttitem{DETUNE} flag to trigger calculation of the detuning function
  terms in first and second order in the strength of the
  multipoles. (Default:~false) 

  \ttitem{DISTORT1} flag to trigger the calculation of the distortion
  function and the Hamiltonian terms in first order in the strength of
  the multipoles. (Default:~false)  

  \ttitem{DISTORT2} flag to trigger the calculation of the distortion
  function and Hamiltonian terms in second order in the strength of the
  multipoles. (Default:~false) 

  \ttitem{START\_STOP} positions (reals in meters) along the beamline
  defining a longitudinal interval. (Default:~0.0,0.0)

  \ttitem{MULTIPOLE\_ORDER\_RANGE} lowest and highest multipole
  order to be taken in account, given as integers. (Default:~1,2)  

  \ttitem{NOPRINT} flag to the effect that no file or internal
  table is created to hold the results. If true, the
  attributes \texttt{PRINT\_ALL} or \texttt{PRINT\_AT\_END} have no
  effect. (Default:~false) 

  \ttitem{PRINT\_ALL} flag to generate files and internal tables with
  results for each mutipole. (Default:~false)

  \ttitem{PRINT\_AT\_END} flag to generate files and internal tables with
  results at the end of the longitudinal interval. (Default:~false)

  \ttitem{NOSIXTRACK} flag to signal that fc.34 shall not be generated
  internally by invoking the conversion routine of sixtrack. The user
  should provide this file before the execution of the \texttt{SODD}
  command. (Default:~false)  

\end{madlist}

Note that the first row of every file generated by \texttt{SODD} is a
header containing the names of the columns. This row is absent in the
internal tables.

A more detailed description can be found in \cite{damico2004}.
 
\section{DETUNE} 

The attribute \texttt{DETUNE} triggers the calculation of the detuning
function terms in first and second order in the strength of the
multipoles.  

If the logical attribute \texttt{PRINT\_AT\_END} is set to true,
the following two files, and corresponding tables, are created: 

\begin{itemize}
\item "detune\_1\_end" contains five columns :
multipole order, 
horizontal or vertical plane coded as 1 or 2,
horizontal or vertical detuning, 
order of horizontal invariant and 
order of vertical invariant. 

\item "detune\_2\_end" contains five columns : 
first multipole order, 
second multipole order,  
horizontal detuning, 
order of horizontal invariant and 
order of vertical invariant.  
\end{itemize}

If the logical attribute \texttt{PRINT\_ALL} is set to true, the
following two files, and corresponding tables, are created :   

\begin{itemize}
\item "detune\_1\_all" contains five columns :  
multipole order, 
horizontal or vertical plane coded as 1 or 2,  
horizontal or vertical detuning, 
order of horizontal invariant and 
order of vertical invariant. 

\item "detune\_2\_all" contains five columns :  
first multipole order, 
second multipole order,  
horizontal detuning, 
order of horizontal invariant and 
order of vertical invariant. 
\end{itemize}

\section{DISTORT1}

The attribute \texttt{DISTORT1} triggers the calculation of the
distortion function and the Hamiltonian terms in first order in the
strength of the multipoles.

If the logical attribute \texttt{PRINT\_AT\_END} is set to true,
the following two files, and corresponding tables are created:  

\begin{itemize}
\item "distort\_1\_F\_end" contains eight columns : 
multipole order, 
cosine and sine part of distortion, 
amplitude of distortion, 
j, k, l, m. 

\item "distort\_1\_H\_end"  contains eight columns : 
multipole order, 
cosine and sine part of Hamiltonian, 
amplitude of Hamiltonian, 
j, k, l, m.  
\end{itemize}

If the logical attribute \texttt{PRINT\_ALL} is set to true, the
following two files, and corresponding tables, are created :   

\begin{itemize}
\item "distort\_1\_F\_all" contains eleven columns :  
multipole order, 
appearance number in position range, 
number of resonance, 
position, 
cosine and sine part of distortion, 
amplitude of distortion, 
j, k, l, m. 

\item "distort\_1\_H\_all"  contains eleven columns : 
multipole order, 
appearance number in position range, 
number of resonance, 
position, 
cosine and sine part of Hamiltonian, 
amplitude of Hamiltonian, 
j, k, l, m. 
\end{itemize}

\section{DISTORT2}
The attribute \texttt{DISTORT2} triggers the calculation of the
distortion function and Hamiltonian terms in second order in the
strength of the multipoles.  

If the attribute \texttt{PRINT\_AT\_END} is set to true, the
following two files, and corresponding tables, are created:  

\begin{itemize}
\item "distort\_2\_F\_end" contains nine columns : 
first multipole order,
second multipole order,  
cosine and sine part of distortion, 
amplitude of distortion, 
j, k, l, m. 

\item "distort\_2\_H\_end"  contains nine columns :  
first multipole order, 
second multipole order, 
cosine and sine part of Hamiltonian, 
amplitude of Hamiltonian, 
j, k, l, m.  
\end{itemize}

%% EOF