control.tex

%%%\title{Range Selection}
%  Changed by: Chris ISELIN, 27-Jan-1997 
%  Changed by: Hans Grote, 15-Jan-2003 


%\input{control/control}
%\input{control/foot}
%\include{control/general}
%\include{control/special}


\chapter{General Control Statements} 

\madx consists of a core program, and modules for specific tasks such as
\hyperref[chap:twiss]{twiss parameter calculation},
\hyperref[chap:match]{matching}, \hyperref[chap:thintrack]{thin lens
  tracking}, \textsl{etc.}   
 
The statements listed here are those executed by the program core.
They deal with the I/O, element and sequence declaration, sequence
manipulation, statement flow control (e.g. \texttt{IF, WHILE}),
\texttt{MACRO} declaration, saving sequences onto files in \madx or
\madeight format, \textsl{etc.}  


%% Moved to TWISS chapter
%% \subsection{COGUESS}
%% \label{subsec:coguess}

%% In order to help the initial finding of the closed orbit by the
%% \texttt{TWISS} module, it is possible to specify an initial guess. 

%% \madbox{
%% COGUESS, \=TOLERANCE=real, \\
%%          \>X=real, PX=real, Y=real, PY=real, T=real, PT=real, \\
%%          \>CLEAR=logical;
%% }
%% sets the required convergence precision in the closed orbit search
%% ("tolerance", see as well Twiss command
%% \href{../twiss/twiss.html#tolerance}{tolerance}).  

%% The other parameters define a first guess for all future closed orbit
%% searches in case they are different from zero.  

%% The clear parameter in the argument list resets the tolerance to its default value 
%% and cancels the effect of coguess in defining a first guess for subsequent 
%% closed orbit searches. \\
%% Default = false, \texttt{clear} alone is equivalent to \texttt{clear=true}


\section{EXIT, QUIT, STOP}
\label{sec:exit}\label{sec:quit}\label{sec:stop}
Any of these three commands ends the execution of \madx:
\madbox{
EXIT;
}
\madbox{
QUIT;
}
\madbox{
STOP;
}


\section{HELP}
\label{sec:help}
The \texttt{HELP} command prints all parameters, and their defaults
values, for the statement given; this includes basic element types.
\madbox{
HELP, statement\_name;
}

\section{SHOW}
\label{sec:show}
The \texttt{SHOW} command prints the \texttt{command} (typically
\texttt{beam}, \texttt{beam\%sequ}, or an element name), with the actual
value of all its parameters.   
\madbox{
SHOW, command;
}

\section{VALUE}
\label{sec:value}
The \texttt{VALUE} command evaluates the current value of all listed
expressions, constants or variables, and prints the result in the form
of \madx statements on the assigned output file. 
\madbox{
VALUE, expression\{, expression\} ;
}

Example: \\
\madxmp{
a = clight/1000.; \\
value, a, pmass, exp(sqrt(2));
}
results in 
\madxmp{
a = 299792.458         ; \\
pmass = 0.938272046        ; \\
exp(sqrt(2)) = 4.113250379        ; \\
}

\section{OPTION}
\label{sec:option}

The \texttt{OPTION} commands sets the logical value of a number of flags
that control the behavior of \madx.

\madbox{
OPTION, flag=logical;
}

Because all attributes of \texttt{OPTION} are logical flags, the
following two statements are identical:
\madxmp{
OPTION, flag = true;\\
OPTION, flag;
}
And the following two statements are also identical:
\madxmp{
OPTION, flag = false;\\
OPTION, -flag;
}

Several flags can be set in a single \texttt{OPTION} command, e.g.
\madxmp{
OPTION, ECHO, WARN=true, -INFO, VERBOSE=false;
}

The available flags, their default values and their effect on \madx when
they are set to \texttt{TRUE} are listed in table \ref{table:options}. Note that to obtain the proper physics in \hyperref[sec:track]{\texttt{TRACK}} with \texttt{BBORBIT} set to false, one must enable the search for the closed orbit (i.e. not use \hyperref[sec:track]{\texttt{ONEPASS}}).

\begin{table}[ht]
  \caption{Flags available to \texttt{OPTION} command}
  \vspace{1ex}
  \centering
  \label{table:options}
  \begin{tabular}{|l|c|l|}
    \hline
    \textbf{FLAG }  & \textbf{default} & \textbf{effect if \texttt{TRUE}} \\
    \hline
    \texttt{ECHO}      & true  & echoes the input on the standard output file \\
    \texttt{WARN}      & true  & issues warning statements\\
    \texttt{INFO}      & true  & issues information statements\\
    \texttt{DEBUG}     & false & issues debugging information \\
    \texttt{ECHOMACRO} & false & issues macro expansion printout for debugging \\
    \texttt{VERBOSE}   & false & issues additional printout in makethin \\
    \texttt{TRACE}     & false & prints the system time after each command \\
    \texttt{VERIFY}    & false & issues a warning if an undefined variable is used 
    \\
    \hline
    \texttt{TELL}      & false & prints the current value of all options \\
    \texttt{RESET}     & false & resets all options to their defaults \\
    \hline
    \texttt{NO\_FATAL\_STOP} & false & Prevents madx from stopping in case of a fatal error \\
    &       & \textbf{Use at your own risk !} \\
    \hline
    \texttt{KEEP\_EXP\_MOVE}& true & keeps the expression of the location after a move command \\
    \hline
    \texttt{RBARC}     & true & converts the RBEND straight length into the arc length \\
    \texttt{THIN\_FOC} & true & enables the $1/\rho^2$ focusing of thin dipoles \\
    \texttt{BBORBIT}   & false & the closed orbit is modified by beam-beam kicks \\
    \texttt{SYMPL}     & true & all element matrices are symplectified in Twiss \\
    \texttt{TWISS\_PRINT} & true & controls whether the twiss command produces output \\
    \texttt{THREADER}  & false & enables the threader for closed orbit finding in Twiss \\ 
    &       & (see Twiss module) \\ 
    \hline
  \end{tabular}
\end{table}

The option \texttt{RBARC} is implemented for backwards compatibility
with \madeight up to version 8.23.06 included; in this version, the
\texttt{RBEND} length was just taken as the arc length of an
\texttt{SBEND} with inclined pole faces, contrary to the \madeight manual.  



\section{EXEC}
\label{sec:exec}
Each statement may be preceded by a label, when parsed and executed the
statement is then also stored and can be executed again with
\madbox{
EXEC, label;
}
This mechanism can be invoked any number of times, and the executed
statement may be calling another \texttt{EXEC}, etc. 
\madxmp{
tw: TWISS, FILE, SAVE; ! first execution of TWISS \\
... \\
EXEC, tw; ! second execution of the same TWISS command \\
}
Note however, that the main usage of this \madx construct is the
execution of a \hyperref[sec:macro]{\texttt{MACRO}}.   

\section{SET}
\label{sec:set}
The \texttt{SET} command is used in two forms:
\madbox{
SET, FORMAT=string \{, string\} ;\\
SET, SEQUENCE=string;
}


The first form of the \texttt{SET} command defines the formats for the
output precision that \madx uses with the \texttt{SAVE}, \texttt{SHOW},
\texttt{VALUE} and \texttt{TABLE} commands. The formats can be
given in any order and stay valid until replaced. 

The formats follow the C convention and must be included in double
quotes. The allowed formats are \\
\textit{n}\texttt{d} for integers with a field-width = \textit{n}, \\
\textit{n.m}\texttt{f} or \textit{n.m}\texttt{g} or
\textit{n.m}\texttt{e} for floats with field-width = \textit{n}
and precision = \textit{m}, \\
\textit{n}\texttt{s} for strings with a field-width = \textit{n}.\\
The default is "right adjusted", a "-" changes it to "left adjusted".

\textbf{Example:}\\
\madxmp{
SET, FORMAT="12d", "-18.5e", "25s";
}

%% \begin{verbatim}
%% "nd" for integer with n = field width.
%% \end{verbatim}
%% \begin{verbatim}
%% "m.nf" or "m.ng" or "m.ne" for floating, m field width, n precision.
%% \end{verbatim}
%% \begin{verbatim}
%% "ns" for string output.
%% \end{verbatim} 


The default formats are \texttt{"10d", "18.10g"} and \texttt{"-18s"}.

Example: 
\begin{verbatim}
set, format="22.14e";
\end{verbatim} 
changes the current floating point format to \texttt{22.14e}; the other
formats remain unchanged.  
\begin{verbatim}
set, format="s","d","g";
\end{verbatim} 
sets all formats to automatic adjustment according to C conventions. 

The second form of the \texttt{SET} command allows to select the
current sequence without the \hyperref[sec:use]{\texttt{USE}} command,
which would bring back to a bare lattice without errors. The command
only works 
if the chosen sequence has been previously activated with a
\hyperref[sec:use]{\texttt{USE}} 
command, otherwise a warning is issued and \madx continues with the
unmodified current sequence. This command is particularly useful for
commands that do not have the sequence as an argument like
\hyperref[chap:emit]{\texttt{EMIT}} or \hyperref[chap:ibs]{\texttt{IBS}}. 



\section{SYSTEM}
\label{sec:system}
\madbox{
SYSTEM, "string";
}
transfers the quoted \texttt{string} to the operating system for
execution. The quotes are stripped and no check of the return status is
performed by \madx. 

\textbf{Example:} 
\madxmp{
SYSTEM, "ln -s /afs/cern.ch/user/j/joe/input shortname";
}
makes a local link to an AFS directory with the name \texttt{shortname}
on a \texttt{UNIX} system.  

\textbf{Attention:} Although this command is very convenient, it is
clearly not portable across systems and it should probably be avoided if
one intends to share \madx scripts with collaborators working on other
platforms.  

\section{TITLE}
\label{sec:title}
\madbox{
TITLE, "string";
}
defines a \texttt{string} that is inserted as title in various table
outputs and plot results.  


\section{USE}
\label{sec:use}
\madx operates on beamlines that must be loaded and expanded in memory
before other commands can be invoked. The \texttt{USE} command allows
this loading and expansion.

\madbox{
USE, \=SEQUENCE=sequence\_name, PERIOD=sequence\_name,\\
     \>RANGE=range, \\
     \>SURVEY=logical;
}

The attributes to the \texttt{USE} command are:
\begin{madlist}
  \ttitem{SEQUENCE} name of the sequence to be loaded and expanded. 
  \ttitem{PERIOD} name of the sequence to be loaded and expanded. \\ 
  \texttt{PERIOD} is an alias to \texttt{SEQUENCE} that was kept for
  backwards compatibility with \madeight and only one of them should be
  specified in a \texttt{USE} statement. 
  \ttitem{RANGE} specifies a \hyperref[sec:range]{range}.   
  restriction so that only the specified part of the named sequence is
  loaded and  expanded.
  \ttitem{SURVEY} option to plug the survey data into the sequence elements
  nodes on the first pass (see \hyperref[chap:survey]{\texttt{SURVEY}}).
\end{madlist}

Note that reloading a sequence with the \texttt{USE} command reloads a
bare sequence and that any \hyperref[chap:error]{\texttt{ERROR}} or
orbit correction previously assigned or associated to the sequence are
discarded. A mechanism to select a sequence without this side effect of the 
\texttt{USE} command is provided with the
\hyperref[sec:set]{\texttt{SET, SEQUENCE=...}} command. 


\section{SELECT} 
\label{sec:select}

Some \madx commands can perform specific operations on selected elements
or ranges of elements and can produce specific output for selected
elements or ranges of elements. 

The selection is made through the \texttt{SELECT} command and applies to
subsequent commands.

\madbox{
SELECT, \=FLAG=string, RANGE=string, CLASS=string, PATTERN=string, \\
        \>SEQUENCE=string, FULL=logical, CLEAR=logical,\\
        \>COLUMN=string\{,string\},  SLICE=integer, THICK=logical, \\
        \>STEP=real, AT=\{real, \ldots \};
} 

The attributes to the \texttt{SELECT} command are:
\begin{madlist}
  \ttitem{FLAG} determines the applicability of the \texttt{SELECT}
  statement and the attribute value can be one of the following: 
  \begin{madlist}
    \ttitem{SEQEDIT} selection of elements for the
    \hyperref[sec:seqedit]{\texttt{SEQEDIT}} module.
    
    \ttitem{ERROR} selection of elements for the
    \hyperref[chap:error]{error assignment} module.
    
    \ttitem{MAKETHIN} selection of elements for the
    \hyperref[chap:makethin]{\texttt{MAKETHIN}} command that
    converts the sequence into one with thin elements.
    
    \ttitem{SECTORMAP} selection of elements for the
    \hyperref[sec:sectormap]{\texttt{SECTORMAP}} output file
    from the \hyperref[chap:twiss]{\texttt{TWISS}} module.
    
    \ttitem{SAVE} selection of elements for the
    \hyperref[sec:save]{\texttt{SAVE}} command.

    \ttitem{INTERPOLATE} selection of interpolation points for the
    \hyperref[chap:twiss]{\texttt{TWISS}} command.

    \ttitem{tablename} is a table name such as \texttt{twiss}, 
    \texttt{track} etc., and the rows and columns to be written are
    selected.
  \end{madlist} 
  
  \ttitem{RANGE} the range of elements to be selected as defined in
  section \ref{sec:range} on \hyperref[sec:range]{range} selection.

  \ttitem{CLASS} the class of elements to be selected as defined in
  section \ref{sec:class} on \hyperref[sec:class]{class} selection.

  \ttitem{PATTERN} the regular expression pattern for the element names
  to be selected as defined in section \ref{sec:regex} on selection via
  \hyperref[sec:regex]{regular expressions}. 

  \ttitem{SEQUENCE} the name of a sequence to which the selection is applied.

  \ttitem{FULL} a logical falg to select ALL positions in the sequence
  for the named flag. \\
  For the flag \texttt{TWISS}, this attribute includes all standard
  columns for a \texttt{TWISS} table, and therefore the following two
  statements are equivalent:
  \madxmp{
SELECT, FLAG=twiss, COLUMN= name, s, betx, ..., var1; \\
SELECT, FLAG=twiss, FULL, COLUMN= var1; 
  } 
  \texttt{FULL=true} is the default for the \texttt{MAKETHIN} flag and
  for tables: \textsl{e.g.} \texttt{SELECT, FLAG=makethin;} is
  equivalent to \texttt{SELECT, FLAG=makethin, FULL;}   
  
  \ttitem{CLEAR} deselects ALL positions in the sequence for the flag
  "name".

  \ttitem{COLUMN} is only valid for tables and takes as attribute value
  a list of columns to be written into the TFS file. The special "\_name"
  argument refers to the actual name of the element. 
  %For an example, see \hyperref[sec:select]{\texttt{SELECT}}.  

  \ttitem{SLICE} is the number of slices into which the selected
  elements have to be cut and is only used by
  \hyperref[chap:makethin]{\texttt{MAKETHIN}} and
  \hyperref[chap:twiss]{\texttt{FLAG=INTERPOLATE}}. (Default = 1).

  \ttitem{THICK} is a logical flag to indicate  whether the selected
  elements are treated as thick elements by the
  \hyperref[chap:makethin]{\texttt{MAKETHIN}} command. \\  
  This only applies up to now to
  \hyperref[sec:quadrupole]{\texttt{QUADRUPOLE}}s and
  \hyperref[sec:bend]{\texttt{BEND}}s for which thick maps
  have been explicitely derived. 

  \ttitem{STEP} output intermediate values every \texttt{STEP} meters
  in the \hyperref[chap:twiss]{\texttt{TWISS}} command.

  \ttitem{AT} manual specification of interpolation points for the
  \hyperref[chap:twiss]{\texttt{TWISS}} command. Specified as a
  fraction of the node length, i.e. a value of 0.5 slices at
  the centre of the element.
\end{madlist}

\vskip 5mm
\textbf{Composition of \texttt{SELECT} statements:} \\
The selection criteria provided on a single \texttt{SELECT} statement
are logically \texttt{AND}ed, \textsl{i.e.} selected elements have to
fulfill \textbf{all} provided criteria in the single \texttt{SELECT}
statement. 

The selection criteria on different \texttt{SELECT} statements are
logically \texttt{OR}ed, \textsl{i.e.} selected elements have to fulfill
\textbf{any} of the selection criteria provided by the different
\texttt{SELECT} statements. 

All selections for a given flag remain valid until a \texttt{SELECT}
statement with the \texttt{CLEAR} argument is specified for the same flag.

Note that because of these composition rules, it is considered good
practice to start by clearing the selection for a given flag before
making a new selection, eg: 
\madxmp{ 
SELECT, FLAG=twiss, CLEAR; \\
SELECT, FLAG=twiss, CLASS=MQ; \\
SELECT, FLAG=twiss, RANGE=MQ[5]/MQ[7]; \\
...
}


\vskip 5mm
\textbf{Examples:} 
\madxmp{ 
SELECT, FLAG = ERROR, CLASS = quadrupole, RANGE = mb[1]/mb[5];\\
SELECT, FLAG = ERROR, PATTERN = "\textasciicircum mqw.*";
}
selects all quadrupoles in the range mb[1] to mb[5], as well as all
elements (in the whole sequence) with name starting with "mqw", for 
treatment by the \hyperref[chap:error]{\texttt{ERROR}} module.  

\vskip 5mm
\madxmp{
SELECT, FLAG=SAVE, CLASS=variable, PATTERN="abc.*"; \\
SAVE, FILE=mysave;
}
saves all variables containing "abc" in their name,
but does not save elements with names containing "abc" since the class
"variable" does not exist.  

\vskip 5mm
\madxmp{
sig1 := sqrt(beam->ex*table(twiss,betx)); \\
SELECT, FLAG=twiss, COLUMN= \_name, s, betx, ..., sig1; ! or equivalently \\
SELECT, FLAG=twiss, FULL, COLUMN= sig1; ! default columns + new
}
writes the current value of ``sig1'' into the \texttt{TWISS} table each
time a new line is added; Note that the values from the same (current)
line can be are accessed by the variable ``sig1''.
The \hyperref[chap:plot]{\texttt{PLOT}} command also accepts the new variable 
in the table.  

%% EOF