beams.tex

\chapter{Beam Handling Statements} 
\label{chap:beam}

Many commands in \mad require the prior setting of various quantities related
to the beam in the machine. Therefore, \mad will stop with a fatal
error if an attempt is made to expand (\hyperref[sec:use]{\texttt{USE}}) a sequence 
for which no \texttt{BEAM} command has been issued before.



\section{BEAM}
\label{sec:beam}

The quantities are entered by a \texttt{BEAM} command: 
\madbox{
BEAM, \= PARTICLE=string, MASS=real, CHARGE=real,\\
      \> ENERGY=real, PC=real, GAMMA=real, BETA=real, BRHO=real,\\
      \> EX=real, EXN=real, EY=real, EYN=real,\\
      \> ET=real, SIGT=real, SIGE=real,\\
      \> KBUNCH=integer, NPART=real, BCURRENT=real,\\
      \> BUNCHED=logical, RADIATE=logical, BV=integer, \\
      \> SEQUENCE=string;
}

The attributes of the \texttt{BEAM} command are: 
\begin{madlist}
  \ttitem{PARTICLE} The name of particles in the beam. Default=\texttt{POSITRON}\\
  \mad knows the restmass and the charge for the following particles:
  \begin{madlist}
    \ttitem{POSITRON} The particles are positrons (\texttt{MASS=$m_e$, CHARGE=1})
    \ttitem{ELECTRON} The particles are electrons (\texttt{MASS=$m_e$, CHARGE=-1}) 
    \ttitem{PROTON} The particles are protons (\texttt{MASS=$m_p$, CHARGE=1})
    \ttitem{ANTIPROTON} The particles are anti-protons (\texttt{MASS=$m_p$, CHARGE=-1}) 
    \ttitem{POSMUON} The particles are positive muons (\texttt{MASS=$m_{\mu}$, CHARGE=1}) 
    \ttitem{NEGMUON} The particles are negative muons (\texttt{MASS=$m_{\mu}$, CHARGE=-1}) 
    \ttitem{ION} The particles are simple generic ions (\texttt{MASS=$u$, CHARGE=1})
  \end{madlist}
  \ttitem{MASS} the restmass of the particles in the beam in GeV. \\
  (Default=$m_e \approx 0.511\ 10^{-3}$ GeV).\\
  Note that a zero mass particle is not allowed in \mad.
  \ttitem{CHARGE}\label{beam_charge} the electrical charge of the
  particles in the beam in units of $q_p$, the proton charge. (Default=1) \\
  Note that a zero charge particle is not allowed in \mad.
\end{madlist} 
The order of precedence for arguments is:  \texttt{particle->(mass+charge)}\\ 
If the particle name given is recognized in the list above, the restmass
and charge are set directly by \madx, and the \texttt{MASS} and \texttt{CHARGE} 
arguments provided in the \texttt{BEAM} command are
simply ignored. For other particles, and in particular for ions, any
combination of name, mass and charge can be entered independently.
\\

\begin{madlist}
  \ttitem{ENERGY} \label{beam_energy} Total energy per particle in
  GeV.\\ If given, it must be greater than the particle
  restmass. (Default=1 GeV)
  \ttitem{PC} Particle momentum times the speed of light, in GeV. \\
  If given, it must be greater than zero. 
  \ttitem{GAMMA} Relativistic factor, \textsl{i.e.} ratio between total
  energy and rest energy of the particles: \texttt{GAMMA = ENERGY/MASS
  =} $E / m_0 c^2$. 
  \\ \texttt{GAMMA} must be greater than one. 
  \ttitem{BETA} Ratio between the speed of the particle
  and the speed of light: \texttt{BETA}$ = v / c$.\\
  \texttt{BETA} must be strictly less than one.
  \ttitem{BRHO} Magnetic rigidity of the particles in T.m. \\ 
  \texttt{BRHO}$ = P / abs(q)$ \texttt{= PC / ( abs(CHARGE) * c * 1.e-9)}. 
\end{madlist}  
The order of precedence for arguments is: \texttt{energy->pc->gamma->beta->brho}

Note that if the restmass is changed after the energy has been set, ie
in separate \texttt{BEAM} commands, the energy is left unchanged and the momentum
\texttt{PC} and relativistic factor \texttt{GAMMA} are recalculated. 
\\

\begin{madlist}
  \ttitem{EX} The horizontal emittance $\epsilon_x$ (default: 1 m). 
  \ttitem{EY} The vertical emittance $\epsilon_y$ (default: 1 m). 
  \ttitem{ET} The longitudinal emittance $\epsilon_t$ (default: 1 m). 
  \ttitem{EXN} The normalised horizontal emittance [m]:
  $\epsilon_{xn} = \sqrt{\gamma^2 - 1} \ \epsilon_x =  \beta \gamma\ \epsilon_x$
  \ttitem{EYN} The normalised vertical emittance [m]:
  $\epsilon_{yn} = \sqrt{\gamma^2 - 1} \ \epsilon_y = \beta \gamma\ \epsilon_y$
  \ttitem{SIGT} The bunch length $c\ \sigma_t$ in [m].  
  \ttitem{SIGE} The \emph{relative} energy spread
  $\sigma_E / E$ in [1].  
\end{madlist} 

The order of precedence for arguments is: \texttt{ex->exn}, \texttt{ey->eyn}.

The order of precedens for the logitudinal emittance is in the following order \texttt{ET->(SIGT and SIGE)}, \texttt{(SIGT and SIGE)->ET}, \texttt{(SIGT)->(ET and SIGE}, \texttt{(SIGE)->(ET and SIGT}. This means that if you define a \texttt{ET} this values will be used to override any value that you might have set for \texttt{SIGT and SIGE}.  

Note that up to version 5.02.04 the definition of normalised emittance used in 
\madx was referring to the so-called 2-sigma geometric emittance:
$\epsilon_{n} = 4 \sqrt{\gamma^2 - 1} \ \epsilon = 4 \beta \gamma\ \epsilon$ 
This definition was different from the definition usually found in literature 
and used for example in the \hyperref[chap:aperture]{\texttt{APERTURE}} module.\\
The standard one sigma definition is now used across all \madx modules. 

Certain commands compute the synchrotron tune $Q_s$ taking into account
the settings of RF cavities. 
If $Q_s$ is non-zero, the relative energy spread and 
the bunch length are calculated with
\begin{align}
    \sigma_E / p_0 c  &=  \sqrt{\epsilon_t\ \frac{2 \pi Q_s}{\eta\ C}} \\
          c\ \sigma_t &= \sqrt{\epsilon_t\ \frac{\eta\ C}{2 \pi Q_s}}
\end{align}
where $C$ is the machine circumference, and 
\begin{equation}
  \eta = 1/\gamma^2 - 1/\gamma_t^2  
\end{equation}

\begin{madlist}
  \ttitem{KBUNCH} The number of particle bunches in the
  machine (default: 1).  
  \ttitem{NPART} \label{beam_npart} The number of particles per bunch (default: 0). 
  \ttitem{BCURRENT} The bunch current (default: 0 A). 
  \ttitem{BUNCHED} A logical flag. If set, the beam is
  treated as bunched whenever this makes sense.  
  \ttitem{RADIATE} \label{beam_radiate} A logical flag. If set, synchrotron
  radiation is considered in all dipole magnets.  
  \ttitem{BV} an integer specifying the direction of the
  particle movement in a beam line; either +1 (default), or -1. For a
  detailed explanation see the section below on bv flag.  
  \ttitem{SEQUENCE} attaches the defined beam to the named sequence; if
  the name is omitted, the BEAM command refers to the default beam
  which is always present. Sequences without attached beam use this
  default beam. When updating a beam with a corresponding sequence name,
  tye sequence name must always be mentioned.    
\end{madlist} 

\textbf{\underline{Order and Precedence:}}\\
Internally the BEAM command processes the parameters in the following
order and with the following precedence (left to right): 
\madxmp{
    particle -> (mass+charge) \\
    energy -> pc -> gamma -> beta -> brho \\
    ex -> exn \\
    ey -> eyn \\
    current -> npart
}

\textbf{Warning:} BEAM updates, i.e. it replaces attributes explicitly
mentioned, may calculate other attributes according to the precedence rules
given, but does NOT return attributes not specified to default values! 
In order to reset to reset BEAM attributes to their default values, use
the \texttt{RESBEAM} command.


\textbf{\underline{Additional variables:}}\\ 
Some \mad modules may also compute and store data into a beam data 
block. These attributes may NOT be set directly through the BEAM
command. The corresponding variables are:  
\begin{madlist}
  \ttitem{CIRC} total length or circumference of the machine [m].
  \ttitem{FREQ0} revolution frequency [MHz].
  \ttitem{DTBYDS} phase slip factor.
  \ttitem{DELTAP} momentum deviation.
  \ttitem{ALFA} momentum compaction factor.
  \ttitem{U0} radiation loss per turn [GeV].
  \ttitem{QS} synchrotron tune [1].
  \ttitem{ARAD} classical particle radius [m].
  \ttitem{PDAMP} damping partition numbers; Default is {1,1,2}.
  \ttitem{N1MIN} minimum available aperture, set by the APERTURE module.
\end{madlist}

\section{RESBEAM}
\label{sec:resbeam}

The \texttt{RESBEAM} command resets the default values of the beam belonging to
the specified sequence, or of the default beam if no sequence is given.  

\madbox{
RESBEAM, SEQUENCE=string;
}

The only argument to \texttt{RESBEAM} is a string for the sequence name.
If the sequence name is omitted, the default beam is reset. 

\begin{table}[h]
  \caption{Default Beam Data}
  \vspace{1ex}
  \centering
  \begin{tabular}{|l|l|l|}
    \hline
    \textbf{Attribute}   &  \textbf{Value} & \textbf{Unit}  \\
    \hline
    \texttt{PARTICLE} &  \texttt{POSITRON} & \\
    \texttt{ENERGY}   &  1           & GeV \\
    \texttt{EX}       &  1           & rad.m \\
    \texttt{EY}       &  1           & rad.m \\
    \texttt{ET}       &  1           & rad.m \\
    \texttt{KBUNCH}   &  1           & \\
    \texttt{NPART}    &  0           & \\
    \texttt{BCURRENT} &  0           & A \\
    \texttt{BUNCHED}  &  \texttt{TRUE}  & \\
    \texttt{RADIATE}  &  \texttt{FALSE} & \\     
    \hline
  \end{tabular}
\end{table}


\section{Referring to BEAM data attributes}
 
Expressions may refer to data in the beam data block using the
notation  
\madbox{
BEAM->attribute-name
}
or 
\madbox{
BEAM\%sequence-name->attribute-name.
}

This notation refers to the value of attribute-name found in the default
\texttt{BEAM}, respectively the beam belonging to the sequence
\texttt{sequence-name}.  
This can be used for receiving or using values, e.g. 
\madxmp{value, beam\%lhcb2->bv;}
but also for storing values in the beam bank, e.g.  
\madxmp{beam->charge=-1;}
Note however that this does NOT trigger an update of dependent variables
and you are strongly advised against setting \texttt{BEAM} parameters
with this method.

The current values in the \texttt{BEAM} bank can be obtained by the command
\madbox{SHOW, BEAM;}
or to obtain the data for a beam linked to a named sequence:
\madbox{SHOW, BEAM\%sequence-name;}


\textbf{\underline{Example:}} 
\madxmp{
! select electrons, set energy and emittances\\
BEAM, PARTICLE=ELECTRON, ENERGY=50, EX=1.E-6, EY=1.E-8, SIGE=1.E-3;\\
 ...\\
! turn on synchrotron radiation\\
BEAM, RADIATE;\\
 ...\\
! reset all values to their defaults, \\
! ie positrons, energy = 1GeV, default emittances, no radiation...\\
RESBEAM;\\
 ...\\
! select new emittances\\
BEAM, EX=2.E-5, EY=3.E-7, SIGE=4.E-3;
}





\section{BV FLAG}
\label{sec:bvflag}
When reversing the direction ($\vec V$) of a particle in a magnetic field
($\vec B$) while keeping its charge constant, the resulting force $\vec
V \times \vec B$ changes sign. This is equivalent to flipping the field,
but not the direction.  

For practical reasons the properties of all elements of the LHC are
defined in the \madx input as if they apply to a clockwise proton beam
("LHC beam 1"). This allows a single definition for elements traversed
by both beams. Their effects on a beam with identical particle charge
but running in the opposite direction ("LHC beam 2") must then be
reversed inside the program.  

In \madx this may be taken into account by setting the value of
the BV attribute in the \texttt{BEAM} commands. In the case of LHC
beam~1 (clockwise) and beam 2 (counter-clockwise), that are both treated
in \madx as clockwise proton beams, the \texttt{BEAM} commands must look
as follows:   

\madxmp{
BEAM, SEQUENCE=lhcb1, PARTICLE=proton, PC=450, BV = +1;\\
\\
BEAM, SEQUENCE=lhcb2, PARTICLE=proton, PC=450, BV = -1;}


%% EOF