\documentclass{article}
\usepackage[affil-it]{authblk}
\usepackage{graphicx}
\usepackage[space]{grffile}
\usepackage{latexsym}
\usepackage{textcomp}
\usepackage{longtable}
\usepackage{tabulary}
\usepackage{booktabs,array,multirow}
\usepackage{amsfonts,amsmath,amssymb}
\providecommand\citet{\cite}
\providecommand\citep{\cite}
\providecommand\citealt{\cite}
% You can conditionalize code for latexml or normal latex using this.
\newif\iflatexml\latexmlfalse
\AtBeginDocument{\DeclareGraphicsExtensions{.pdf,.PDF,.eps,.EPS,.png,.PNG,.tif,.TIF,.jpg,.JPG,.jpeg,.JPEG}}
\usepackage[utf8]{inputenc}
\iflatexml
\documentclass[11pt,a4paper,twoside]{report}
\fi
\usepackage{xspace}
\usepackage[dvipsnames,svgnames]{xcolor}
% \usepackage{a4wide} % Not (yet) supported by LaTeXML.
\usepackage{amsmath}
% \usepackage[english]{babel} % Not (yet) supported by LaTeXML.
\usepackage{graphicx}
\usepackage{multirow}
\usepackage{longtable}
% \usepackage{parskip} % Not (yet) supported by LaTeXML.
\usepackage{float}
\usepackage{makeidx}
\usepackage{color}
% \usepackage[totoc]{idxlayout} % Not (yet) supported by LaTeXML.
\usepackage{hyperref}
% \usepackage{madstyle} % Not (yet) supported by LaTeXML.
\includeonly{
coverpage, copyright, changelog, contributors,
conventions, format, programflow, control, files, tables, beams, seqedit,
definitions, elements, ranges, line, sequence,
tfs, c6t, sxf, plot, index, rplot_index,
survey, twiss, match, emit, aperture, makethin, error, cororbit, sodd, touschek, ibs, thintrack,
ptc_general, ptc_track, ptc_twiss, ptc_normal, ptc_auxiliaries,
defects, pitfalls
}
\hypersetup{pdfauthor={Ghislain Roy},
pdftitle={MAD-X User's Guide},
colorlinks,
citecolor=blue, linkcolor=blue}
\hyperbaseurl{http://madx.web.cern.ch/madx/madX/doc/usrguide/}
\makeindex
\begin{document}
\title{MADX Demo: Elements}
\author{Deyan Ginev}
\affil{Affiliation not available}
\date{\today}
\maketitle
\include{coverpage}
\include{copyright}
\tableofcontents
\newpage
\listoftables
\listoffigures
\part{Elements, Beamlines and Sequences}
\chapter{Definition of Elements}
\label{chap:element_definition}
\section{Element Input Format}
\label{sec:element_input}
All physical elements are defined by statements of the form
\madbox{
label: keyword \{,attribute\};
}
where
\begin{madlist}
\ttitem{label} is a name to be given to the element.
\ttitem{keyword} is an element type keyword.
\ttitem{attribute} normally -- with exception for multipoles -- takes one of the two forms:
\madxmp{attribute-name \== attribute-value \\
attribute-name \>:= attribute-value}
\begin{madlist}
\ttitem{attribute-name} selects the attribute,
as defined for the element type keyword.
\ttitem{attribute-value} provides a value to the {\tt
attribute\_name}. The value may be specified by an expression.
\end{madlist}
The "=" assigns the value on the right to
the attribute at the time of definition, regardless of any
further change of the right hand side; the ":=" re-evaluates
the expression at the right every time the attribute is being
used. For constant right hand sides, "=" and ":=" are of
course equivalent.
Omitted attributes are assigned a default value.
{\bf Example:}
\madxmp{QF: QUADRUPOLE, L=1.8, K1=0.015832;}
A special format is used for a \hyperref[sec:multipole]{multipole}\index{multipole}:
\madxmp{
M: MULTIPOLE, \= KN= {kn0, kn1, kn2, ..., knmax},\\
\> KS= {ks0, ks1, ks2, ..., ksmax};
}
where {\tt KN} and {\tt KS} give the integrated normal and skew strengths,
respectively. The commas are mandatory, each strength can be an
expression; their position defines the order. example:
\madxmp{M: MULTIPOLE, KN={0,0,0,myoct*lrad}, KS={0,0,0,0,-1.e-5};}
defines a multipole with a normal octupole component and a skew decapole
component.
\section{Editing Element Definitions}
\label{sec:element_editing}
An element definition can be changed in two ways:
\begin{itemize}
\item \textbf{Entering a new definition:} The element will be
replaced in the main beam line expansion.
\item \textbf{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.
\end{itemize}
This example shows two ways to change the strength of a quadrupole:
\madxmp{
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\= \kill
QF: QUADRUPOLE, L = 1, K1 = 0.01; \>! Original definition of QF \\
QF: QUADRUPOLE, L = 2, K1 = 0.02; \>! Replace whole definition of QF \\
QF, K1 = 0.03; \>! Replace value of K1 for QF\\
}
When the type of the element remains the same, replacement of an
attribute is the more efficient way.
Element definitions can be edited freely. The changes do not affect
already defined objects which belong to its
\href{elm_class.html}{element class}.
\section{Element Classes}
\label{sec:element_classes}
The concept of element classes solves the problem of addressing
instances of elements in the accelerator in a convenient manner.
It will first be explained by an example. All the quadrupoles in the
accelerator form a class QUADRUPOLE. Let us define three subclasses for the
focussing quadrupoles, the defocussing quadrupoles, and the skewed
quadrupoles:
\madxmp{
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\= \kill
MQF: QUADRUPOLE, L = LQM, K1 = KQD; \>! Focussing quadrupoles \\
MQD: QUADRUPOLE, L = LQM, K1 = KQF; \>! Defocussing quadrupoles \\
MQT: QUADRUPOLE, L = LQT; \>! Skewed quadrupoles
}
These classes can be thought of as new keywords which define elements
with specified default attributes. We now use these classes to define
the real quadrupoles:
\madxmp{
xxxxxxxxxxxxxxxxxxxxxxx\= \kill
QD1: MQD; \>! Defocussing quadrupoles \\
QD2: MQD; \\
QD3: MQD; \\
... \\
QF1: MQF; \>! Focussing quadrupoles \\
QF2: MQF; \\
QF3: MQF; \\
... \\
QT1: MQT, K1S = KQT1; \> ! Skewed quadrupoles \\
QT2: MQT, K1S = KQT2; \\
...
}
These quadrupoles inherit from their class all attributes that are not
explicitly specified at time of declaration.
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 instances of elements for various purposes. Example:
\madxmp{
SELECT, FLAG=twiss, CLASS = QUADRUPOLE; \=! Select all quadrupoles for the\\
\>! Twiss TFS file
}
More formally, for each element keyword \madx 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.
\chapter{Element Types}
\section{Marker}
\ttindex{marker}
\label{sec:marker}
\madbox{
label: MARKER;
}
The simplest element which can occur in a beam line is the {\tt 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.
{\bf Example:}
\madxmp{M27: MARKER;}
\section{Drift Space}
\ttindex{drift}
\label{sec:drift}
\madbox{
label: DRIFT, L=real;
}
A drift space has one real attribute:
\begin{madlist}
\ttitem{L} The drift length (Default: 0 m)
\end{madlist}
{\bf Example: }
\madxmp{
DR1: \= DRIFT, \= L = 1.5; \\
DR2: \> DRIFT, \> L = DR1->L;
}
The length of DR2 will always be equal to the length of DR1. The
\hyperref[subsec:local_straight]{straight reference system} for a drift
space is a Cartesian coordinate system.
\section{Bending Magnet}
\ttindex{bend}
\label{sec:bend}
Two different type keywords are recognised for bending magnets, they are
distinguished only by the reference system used:
\begin{madlist}
\ttitem{SBEND}\label{bend_sbend} is a sector bending magnet. \\
The planes of the pole faces intersect at the centre of curvature of
the curved
% Its pole faces meet at the centre of curvature of the curved
\hyperref[subsec:local_rbend]{sbend reference system}.
\ttitem{RBEND}\label{bend_rbend} is a rectangular bending magnet. \\
The pole faces are parallel. The reference system is the curved
% It has parallel pole faces and is based on a curved
\hyperref[subsec:local_rbend]{rbend reference system}.
\end{madlist}
Bendig magnets are defined by the statements:
\madbox{
label: SBEND, \= L=real, ANGLE=real, TILT=real, \\
\> K0=real, K1=real, K2=real, \\
\> E1=real, E2=real, FINT=real, FINTX=real,\\
\> HGAP=real, H1=real, H2=real,\\
\> THICK=logical;\\[5mm]
label: RBEND, \> L=real, ANGLE=real, TILT=real, \\
\> K0=real, K1=real, K2=real, \\
\> E1=real, E2=real, FINT=real, FINTX=real, \\
\> HGAP=real, H1=real, H2=real, \\
\> THICK=logical, \\
\> ADD\_ANGLE='array';
}
Bending magnets have the following attributes:
\begin{madlist}
\ttitem{L} The length of the magnet (default: 0 m). \\
For sector bends the declared length is the arc length
of the reference orbit. \\
For rectangular bends the declared length is normally the length of a
straight line joining the entry and exit points, as in the
Figure. \\
Internally \madx only uses the arc length of the reference orbit for
both bend types.\\
{\bf In order to define {\tt RBEND}'s with a declared length equal to the
arc length of the reference orbit, the option {\tt RBARC} must be
previously set to FALSE in \madx with {\tt Option, RBARC= false;}}
\ttitem{ANGLE} The bend angle (default: 0 rad). \\
A positive bend angle represents a bend to the right, i.e. towards
negative {\tt x} values.
\ttitem{ADD\_ANGLE} An array of (maximum 5) bending angles for
multiple passes. See {\tt ADD\_PASS} option of the
\href{sequence.html}{\tt SEQUENCE} command. This is only allowed for
{\tt RBEND} elements and is ignored for {\tt SBEND} elements.
\ttitem{TILT} The roll angle about the longitudinal axis (default: 0
rad, i.e. a horizontal bend). \\
A positive angle represents a clockwise rotation. \\
An attribute {\tt TILT=pi/2} turns a
horizontal into a vertical bend, and a positive {\tt ANGLE} then denotes a
downwards deflection.
%% \textbf{ Please note that contrary to \madeight one has to specify
%% the desired TILT angle, otherwise it is taken as 0 rad. This was
%% needed to avoid the confusion in \madeight about the actual meaning of
%% the TILT attribute for various elements. }
\ttitem{K1} The quadrupole coefficient (Default: $0\ m^{-2}$)\\
$K_1 = (1/B\rho) (\partial B_y / \partial x)$. \\
A positive quadrupole strength implies horizontal focussing of particles,
irrespective of their charge.
% positively charged particles.
\ttitem{E1} The rotation angle for the entrance pole face (Default: 0 rad).
\ttitem{E2} The rotation angle for the exit pole face (Default: 0 rad). \\
The pole face rotation angles are referred to the magnet model for
\href{local_system.html#rbend}{rectangular bend} and
\href{local_system.html#sbend}{sector bend} respectively. \\
{\tt E1} and {\tt E2} are positive if they reduce the length of the
side of the bend that is further away from the centre of
curvature. \\
{\tt E1} and {\tt E2} must be specified as positive to give an {\tt SBEND}
parallel faces, i.e. turning it into an {\tt RBEND}. {\tt E1} and {\tt E2}
must be negative to give an {\tt RBEND} faces whose planes intersect at the
centrer of curvature, ie turning it into an {\tt SBEND}.
\ttitem{FINT} The fringe field integral at entrance and exit of the
bend. (Default: 0).
\ttitem{FINTX} If defined and positive, the fringe field integral at
the exit of the element, overriding {\tt FINT} for the exit. (Default: ={\tt
FINT}) \\
This allows to set different fringe field integrals at entrance
({\tt FINT}) and exit ({\tt FINTX}) of the element.
\ttitem{HGAP} The half gap of the magnet (default: $0\ m$).
\ttitem{K2} The sextupole coefficient. (Default: $0\ m^{-3}$) \\
$K_2 = (1/B\rho) (\partial^2 B_y / \partial x^2)$.
\ttitem{H1}The curvature of the entrance pole face.
(Default: $0\ m^{-1}$).
\ttitem{H2} The curvature of the exit pole face. (Default: $0\ m^{-1}$) \\
A positive pole face curvature induces a negative sextupole
component; i.e. for positive {\tt H1} and {\tt H2} the centres of curvature
of the pole faces are placed inside the magnet.
\ttitem{K0} {\bf OBSOLETE} \\
Please take note that $K_0$ and $K_0s$ are left in the
data base but are no longer used for the MAP of the bends,
instead {\tt ANGLE} and {\tt TILT} are used exclusively. \\
%% We believe that this will allow for a clearer and
%% unambiguous definition, in particular in view of the upcoming
%% integration of \madx with PTC which will allow a more general
%% definition of bends.
However, specifying {\tt K0} is required in order to be able to assign {\bf
relative} field errors to a bending magnet because {\tt K0} is used for the
normalization instead of the {\tt ANGLE}. (see \hyperref[sec:efcomp]{\tt
EFCOMP}).\\
With $K_0 = (1 / B \rho) B_y$, one gets {\tt K0 = ANGLE / arclength}.
% -K0:
% -The horizontal dipole coefficient
% -*K*_{0} = (1 / B rho) B_{y} .
% -The default is 0 m^{-1}.
% -A positive dipole strength is equivalent to a positive ANGLE which has the
% -precedence over K_{0}; however, if ANGLE is omitted,
% -K_{0}*L is used instead.
% -K0S:
% -The vertical dipole coefficient
% -*K*_{0s} = (1 / B rho) B_{x} .
% -The default is 0 m^{-1}. A positive K0S deflects the closed
% -orbit to positive y values.
\ttitem{THICK} If this logical flag is set to true the bending
magnet will be tracked through as a thick-element, instead of being
converted into thin-lenses. \\
(Default: false)
\end{madlist}
{\bf Note:} Additional attributes can be given to bending magnets that
are useful for \ptc and defined in \ref{sec:add_option_PTC}.
\vskip5mm
{\bf \underline{Fringe Fields:}}
\vskip3mm
The quantities {\tt FINT} and {\tt HGAP} specify the finite extent of the fringe
fields as defined in SLAC-75 \cite{slac75}:
\begin{equation}
\mathrm{FINT}=\int_{-\infty}^\infty \frac{B_y(s)(B_0-B_y(s))}{g \cdot
B_0^2}\,\mathrm{d}s ,\quad\quad g=2\cdot \mathrm{HGAP}.
\end{equation}
The default values of zero corresponds to the hard-edge approximation,
i.e. a rectangular field distribution. For other approximations, enter
the correct value of the half gap, and one of the following values for
{\tt FINT}:
\begin{center}
\begin{tabular}{l l}
Linear Field drop-off & 1/6 \\
Clamped "Rogowski" fringing field & 0.4 \\
Unclamped "Rogowski" fringing field & 0.7 \\
"Square-edged" non-saturating magnet & 0.45
\end{tabular}
\end{center}
Entering the keyword {\tt FINT} alone sets the integral to 0.5, which is a
reasonable average of the above values.
Note also that the possibility to specify both {\tt FINT} and {\tt FINTX}
allows
one to set different values at entrance and exit of a bend element. \\
This can be particularly useful to set the fringe field integral to zero
on one side only, e.g. when slicing a dipole.
{\bf \underline {Examples:}}
\madxmp{
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\= \kill
BR: RBEND, L=5., ANGLE=+0.001; \>! Deflection to the right \\
BD: RBEND, L=5., ANGLE=+0.001, TILT=pi/2; \>! Deflection down \\
BL: RBEND, L=5., ANGLE=+0.001, TILT=pi; \>! Deflection to the left \\
BU: RBEND, L=5., ANGLE=+0.001, TILT=-pi/2; \>! Deflection up
}
\section{Dipole edge}
\ttindex{dipedge}
\label{sec:dipedge}
A thin element describing the edge focusing of a dipole has been
introduced in order to make it possible to track trajectories in the
presence of dipoles with pole face angles. Only linear terms are
considered since the higher order terms would make the tracking
non-symplectic. The transformation of the machine elements into thin
lenses leaves dipole edge ({\tt DIPEDGE}) elements untouched and splits
correctly the {\tt SBEND}'s.
It does not make sense to use a {\tt DIPEDGE} alone.
It can be specified at the entrance and the exit of a {\tt SBEND}.
A dispole edge element is defined by the command:
\madbox{
label: DIPEDGE, H=real, E1=real, FINT=real, HGAP=real, TILT=real;
}
A {\tt DIPEDGE} has zero length and five attributes.
\begin{madlist}
\ttitem{H} Is angle/length or 1/rho (default: 0 m$^{-1}$ - for the
default the dipedge element has no effect). (must be equal to that
of the associated {\tt SBEND})
\ttitem{E1} The rotation angle for the pole face. The sign convention is
as for a SBEND \href{bend.html}{Bending Magnet}. Note that it is
different for an entrance and an exit. (default: 0 rad).
\ttitem{FINT} field integral as for {\tt SBEND}
\href{local_system.html#sbend}{sector bend}. Note that each {\tt DIPEDGE}
has its own {\tt FINT}, so {\tt FINTX} is no longer necessary.
\ttitem{HGAP} half gap height of the associated {\tt SBEND}
\hyperref[sec:sbend]{Bending Magnet}.
\ttitem{TILT} The roll angle about the longitudinal axis (default: 0
rad, i.e. a horizontal bend). A positive angle represents a
clockwise rotation.
\end{madlist}
\section{Quadrupole}
\ttindex{quadrupole}
\label{sec:quadrupole}
\madbox{
label: QUADRUPOLE, \= L=real, K1=real, K1S=real, TILT=real,\\
\> THICK=logical;
}
A {\tt QUADRUPOLE} has five attributes:
\begin{madlist}
\ttitem{L} The quadrupole length (default: 0 m).
\ttitem{K1} The normal quadrupole coefficient:
$K_1 = 1/(B \rho) (\partial B_y / \partial x)$.\\
The default is $0 m^{-2}$. A positive normal quadrupole strength
implies horizontal focussing, irrespective of the charge of the particles.
% of positively charged particles.
\ttitem{K1S} The skew quadrupole coefficient
$K_{1s} = 1/(2 B \rho) (\partial B_x / \partial x - \partial B_y / \partial y)$\\
where (x,y) is now a coordinate system rotated by $-45^\circ$ around s
with respect to the normal one. The default is $0\ m^{-2}$. A
positive skew quadrupole strength implies {\sl defocussing},
irrespective of the charge of the particles,
% of positively charged particles
in the (x,s) plane rotated by $45^\circ$
around {\tt s} (particles in this plane have {\tt x = y $>$ 0}).
\ttitem{TILT} The roll angle about the longitudinal axis (default: 0
rad, i.e. a normal quadrupole). A positive angle represents a
clockwise rotation. A {\tt TILT=pi/4} turns a positive normal quadrupole
into a negative skew quadrupole.
\textbf{Please note that contrary to \madeight one has to
specify the desired TILT angle, otherwise it is taken as
0 rad. This was needed to avoid the confusion in \madeight
about the actual meaning of the {\tt TILT} attribute for
various elements. }
\ttitem{THICK} If this logical flag is set to true the quadrupole
will be tracked through as a thick-element, instead of being
converted into thin-lenses.\\
(Default: false)
\end{madlist}
\textbf{Note also that $K_1$ or $K_{1s}$ can be considered as
the normal or skew quadrupole components of the magnet on
the bench, while the TILT attribute can be considered as a
tilt alignment error in the machine. In fact, a positive
$K_1$ with a $\tt{TILT} = 0$ is equivalent to a positive $K_{1s}$
with positive $\tt{TILT} = +\pi/4$ }
Example:
\madxmp{QF: QUADRUPOLE, L = 1.5, K1 = 0.001, THICK = 1;}
{\bf Note:} Additional attributes can be given to quadrupoles that
are useful for \ptc and defined in \ref{sec:add_option_PTC}.
The \hyperref[subsec:local_straight]{straight reference system} for
a quadrupole is a Cartesian coordinate system.
\section{Sextupole}
\ttindex{sextupole}
\label{sec:sextupole}
\madbox{
label: SEXTUPOLE, L=real, K2=real, K2S=real, TILT=real;
}
A {\tt SEXTUPOLE} has four real attributes:
\begin{madlist}
\ttitem{L} The sextupole length (default: 0 m).
\ttitem{K2} The normal sextupole coefficient $K_2 = \frac{1}{B \rho}
(\partial^2 B_y / \partial x^2)$. \\
(default: $0 m^{-3}$).
\ttitem{K2S} The skew sextupole coefficient
$K_{2S} = \frac{1}{B \rho} (\partial^2 B_x / \partial x^2)$ \\
%% 2013-Jul-05 17:58:30 ghislain: error reported by Christian Carli
% \textit{K}$_{2S}$ = 1/(2 \textit{B} rho)
% ($\partial$$^2$\textit{B$_x$}/$\partial$ \textit{x}$^2$ -
% $\partial$$^2$\textit{B$_y$}/$\partial$ \textit{y}$^2$).
where (x,y) is now a coordinate system rotated by $-30^\circ$ around s with
respect to the normal one. (default: $0\ m^{-3}$). A positive skew
sextupole strength implies {\sl defocussing} (!)
irrespective of the charge of the particles,
% of positively charged particles
in the (x,s) plane rotated by $30^\circ$ around s (particles in
this plane have $x > 0$, $y > 0$).
\ttitem{TILT} The roll angle about the longitudinal axis (default: 0
rad, i.e. a normal sextupole). A positive angle represents a
clockwise rotation. A $\tt{TILT} = \pi/6$ turns a positive normal
sextupole into a negative skew sextupole.
\textbf{ Please note that contrary to \madeight one has to specify the
desired TILT angle, otherwise it is taken as 0 rad. This was needed to
avoid the confusion in \madeight about the actual meaning of the TILT
attribute for various elements. }
\end{madlist}
\textbf{Note also that $K_2$ or $K_{2s}$ can be considered as the normal
or skew sextupole components of the magnet on the bench, while the
{\tt TILT} attribute can be considered as an tilt alignment error in the
machine. In fact, a positive $K_2$ with a ${\tt TILT} = 0$ is equivalent to a
positive $K_{2s}$ with positive ${\tt TILT} = \pi/6$.}
Example:
\madxmp{S: SEXTUPOLE, L=0.4, K2=0.00134;}
{\bf Note:} Additional attributes can be given to sextupoles that
are useful for \ptc and defined in \ref{sec:add_option_PTC}.
The \hyperref[subsec:local_straight]{straight reference system} for a
sextupole is a Cartesian coordinate system.
\section{Octupole}
\ttindex{octupole}
\label{sec:octupole}
\madbox{
label: OCTUPOLE, L=real, K3=real, K3S=real, TILT=real;
}
An {\tt OCTUPOLE} has four real attributes:
\begin{madlist}
\ttitem{L} The octupole length (default: 0 m).
\ttitem{K3} The normal octupole coefficient
$K_3 = \frac{1}{B \rho} (\partial^3B_y / \partial x^3)$ \\
(default: 0 m**(-4)).
\ttitem{K3S} The skew octupole coefficient
%% 2013-Jul-05 18:00:59 ghislain: to be checked wrt error reported on
%% K2S for sextupoles
$K_{3S} = \frac{1}{2 B\rho} (\partial^3B_x/\partial x^3 -
\partial^3B_y/\partial y^3)$ \\
where (x,y) is now a coordinate system rotated by -22.5$^o$ around
s with respect to the normal one. (default: $0 m^{-4}$). A positive
skew octupole strength implies {\sl defocussing} (!)
irrespective of the charge of the particles,
% of positively charged particles
in the (x,s) plane rotated by 22.5$^o$ around s
(particles in this plane have x $>$ 0, y $>$ 0).
\ttitem{TILT} The roll angle about the longitudinal axis (default: 0
rad, i.e. a normal octupole). A positive angle represents a
clockwise rotation. A TILT=pi/8 turns a positive normal octupole
into a negative skew octupole.
\textbf{Please note that contrary to \madeight one has to specify the
desired TILT angle, otherwise it is taken as 0 rad. This was
needed to avoid the confusion in \madeight about the actual meaning of
the TILT attribute for various elements. }
\end{madlist}
\textbf{Note also that $K_3$ or $K_{3S}$ can be considered as the normal or
skew quadrupole components of the magnet on the bench, while the {\tt TILT}
attribute can be considered as an tilt alignment error in the
machine. In fact, a positive $K_3$ with a {\tt TILT=0} is equivalent to a
positive $K_{3S}$ with positive {\tt TILT=+pi/8}. }
Example:
\madxmp{O3: OCTUPOLE, L=0.3, K3=0.543;}
{\bf Note:} Additional attributes can be given to octupoles that
are useful for \ptc and defined in \ref{sec:add_option_PTC}.
The \hyperref[subsec:local_straight]{straight reference system} for a
octupole is a Cartesian coordinate system. Octupoles are normally
treated as thin lenses, except when tracking by Lie-algebraic methods.
\section{General Thin Multipole}
\ttindex{multipole}
\label{sec:multipole}
A {\tt MULTIPOLE} is a thin-lens magnet of arbitrary order, including a
dipole component.
\madbox{
label: MULTIPOLE, \= LRAD=real, TILT=real, \\
\> KNL=\{real, \ldots \}, KSL=\{real, \ldots \};
}
\begin{madlist}
\ttitem{LRAD} A fictitious length, originally only used to
compute synchrotron radiation effects. \\
A non-zero {\tt LRAD} in conjunction with
\hyperref[sec:option]{\tt OPTION, THIN\_FOC=true}
takes into account the
weak focussing of bending magnets.
\ttitem{TILT} The roll angle about the longitudinal axis (default: 0
rad). A positive angle represents a clockwise rotation of the
multipole element. The roll angle affects all components.
\ttitem{KNL} An array of the integrated normal multipole coefficients,
starting from order zero and up to the maximum order (currently 20).
The parameters are positional in the array, therefore
zeros must be filled in for components that do not exist. \\
The coefficient of rank $i$ in the array corresponds to the integrated
strength $K_i L = B_i . L / (B\rho)$ where the strength is given by
equation \ref{eq:kn}.
Hence the first argument of the array, the argument for a normal
multipole of order zero, $K_0 L = B_0 . L / (B\rho)$ is equal to
the normal horizontal rotation angle of the thin dipole.
\ttitem{KSL} An array of the integrated skew multipole coefficients,
starting from order zero and up to the maximum order (currently 20). The
parameters are positional in the array, therefore zeros must be
filled in for components that do not exist.
Hence the first argument of the array, the argument for a skew
multipole of order zero, $K_0 L = B_0 . L / (B\rho)$ is equal to
the skew or vertical rotation angle of the thin dipole.
\end{madlist}
Both {\tt KNL} and {\tt KSL} may be specified for the same multipole.
Contrary to \madeight the desired {\tt TILT} angle must be explicitly
specified, and defaults otherwise to 0 rad. The roll angle specified
with {\tt TILT} is global to all multipolar components.
Hence the {\tt KNL} and {\tt KSL} components can be considered as the
normal or skew multipole components of the magnet as measured on the
bench, while the {\tt TILT} attribute can be considered as an alignment
error as measured in the machine.
A multipole with no dipole component has no effect on the reference
orbit, i.e. the reference system at its exit is the same as at its
entrance. If it includes a dipole component, it has the same effect on
the reference orbit as a dipole with zero length, total deflection
{\tt angle} and {\tt tilt} defined by:
\begin{eqnarray}
{\tt angle} = \sqrt{ {\tt KNL}(0)^2 + {\tt KSL}(0)^2 }\\
{\tt tilt} = \arctan ({\tt KSL}(0) / {\tt KNL}(0))
\end{eqnarray}
Note that the global {\tt TILT} attribute of the {\tt MULTIPOLE} is then
added to the intrinsic {\tt tilt} calculated from {\tt KNL} and {\tt KSL}.
{\bf Examples:}\\
A thin-lens sextupole:
\madxmp{ms: MULTIPOLE, KNL=\{0, 0, k2l\};}
A thin-lens skew octupole:
\madxmp{mso: MULTIPOLE, KSL=\{0, 0, 0, k3sl\};}
A thin-lens multipole with a normal octupole component and a skew decapole
component:
\madxmp{mod: MULTIPOLE, KNL=\{0,0,0,myoct*lrad\}, KSL=\{0,0,0,0,-1.e-5\};}
A thin-lens dipole bending to the right and down for a total angle of
2e-3 radians and a tilt of $\pi/4$ can be equivalently defined as:
\madxmp{
hvbend: MULTIPOLE, KNL=\{1.414e-3\}, KSL=\{1.414e-3\};\\
hvbend: MULTIPOLE, KNL=\{2.e-3\}, TILT= pi/4;\\
hvbend: MULTIPOLE, KSL=\{2.e-3\}, TILT=-pi/4;
}
\section{Solenoid}
\ttindex{solenoid}
\label{sec:solenoid}
Solenoids can be defined in two forms, a thick and a thin version:
\madbox{
xxxxxxxxxxxxxxxxxxxxxxxxxx\=xxxxxxxxxxxxxxxxxxx\= \kill
label: SOLENOID, L=real, \>KS=real; \> ! thick version \\
label: SOLENOID, L=0, \>KS=real, KSI=real; \> ! thin version
}
A {\tt SOLENOID} has three real attributes:
\begin{madlist}
\ttitem{L} The length of the solenoid (default: 0 m)
\ttitem{KS} The solenoid strength $K_s = B_0 / B\rho$ (default: 0
rad/m). For positive {\tt KS} and positive particle charge, the solenoid
field points in the direction of increasing $s$.
\ttitem{KSI} The solenoid integrated strength $K_s L$
(default: 0 rad). This additional attribute is needed only when
using the thin solenoid, where $L=0$.
\end{madlist}
Example:
\madxmp{
xxxxxxxxxx\=xxxxxxxxxxxxxxxxxxxx\= \kill
SOLO: \> SOLENOID, L = 2., \> KS = 0.001; \\
THINSOLO: \> SOLENOID, L = 0, \> KS = 0.001, KSI = 0.002;
}
{\bf Note:} Additional attributes can be given to solenoids that
are useful for \ptc and defined in \ref{sec:add_option_PTC}.
In particular multipole coefficients {\tt KNL} and {\tt KSL} can also be
specified for
solenoids. They have no effect in \madx proper but are used in \ptc for
solenoid with multipoles.
The \hyperref[subsec:local_straight]{straight reference system} for a
solenoid is a Cartesian coordinate system.
\section{Nonlinear Lens with Elliptic Potential}
\ttindex{nllens}
\label{sec:nllens}
\madbox{
label: NLLENS, KNLL=real, CNLL=real;
}
The {\tt NLLENS} element represents a thin nonlinear lens with the potential
of 'Elliptic' type as specified in \cite{danilov2010}. The lens is used
to create fully integrable 2D nonlinear accelerator lattice with very
large nonlinear tune spread/shift. The {\tt NLLENS} element is recognized by
the thin tracking module. The quadrupole term of the potential is
included in the TRANSPORT map and, consequently, affects the calculation
of tunes and Twiss functions.
\begin{madlist}
\ttitem{KNLL} The integrated strength of lens (m). The strength is
parametrized so that the quadrupole term of the multipole
expansion is {\tt k1=2*KNLL/CNLL\textasciicircum2}.
\ttitem{CNLL} The dimensional parameter of lens (m). The singularities
of the potential are located at X=-CNLL,+CNLL and Y=0.
\end{madlist}
The scalar potential function of the element is given by
\begin{equation}
U(x,y)=\frac{k}{c}\frac{\xi\sqrt{\xi^2-1} \, \text{acosh}\xi +
\eta\sqrt{1-\eta^2}(\text{acos}\eta-\pi/2)}{\xi^2-\eta^2}
\end{equation}
where \textit{k} = KNLL, \textit{c} = CNLL and
\begin{equation}
\xi = \frac{\sqrt{(x+c)^2+y^2}+\sqrt{(x-c)^2+y^2}}{2c},
\quad \eta = \frac{\sqrt{(x+c)^2+y^2}-\sqrt{(x-c)^2+y^2}}{2c},
\end{equation}
Figure below shows the contour plot of the scalar potential: \\\selectlanguage{english}
\begin{figure}[h!]
\begin{center}
\includegraphics[width=0.70\columnwidth]{figures/nllens-potential-2D/default-figure}
\caption{{\label{fig:nllens_potential} Contour plot of the scalar potential%
}}
\end{center}
\end{figure}
The multipole expansion of the scalar potential is \\
\begin{equation}
U(x,y)=k\cdot Re\left\{ \left(\dfrac{x + i y}{c}\right)^2 +
\frac{2}{3}\left(\dfrac{x + i y}{c}\right)^4 +
\frac{8}{15}\left(\dfrac{x + i y}{c}\right)^6 +
\frac{16}{35}\left(\dfrac{x + i y}{c}\right)^8 + \cdots \right\}
\end{equation}
Note that this expansion is only valid inside the \textit{r=c} circle on
the x,y plane.
In order to create integrable optics, one needs to shape the potential
along z axis according to the beta-function. Below is an example
nonlinear section representing the necessary nonlinear field with 20
thin lenses:
\begin{verbatim}
mu0 = 0.3; ! phase advance over straight section
l0 = 2.0; ! length of the straight section
nn = 20; ! number of nonlinear elements
tn = 0.45; ! strength of nonlinear lens
cn = 0.01; ! dimentional parameter of nonlinear lens
musect = mu0 + 0.5;
f0 = l0/4.0*(1.0+1.0/tan(pi*mu0)^2);
betae = l0/sqrt(1.0-(1.0-l0/2.0/f0)^2);
alfae = l0/2.0/f0/sqrt(1.0-(1.0-l0/2.0/f0)^2);
betas = l0*(1-l0/4.0/f0)/sqrt(1.0-(1.0-l0/2.0/f0)^2);
value, f0, betae, alfae, betas;
ncreate(ii,kk,cc): macro = {n.ii: nllens, knll=kk, cnll=cc;};
i=0;
while(i < nn)
{
i = i+1;
sn = l0/nn*(i-0.5);
bn = l0*(1-sn*(l0-sn)/l0/f0)/sqrt(1.0-(1.0-l0/2.0/f0)^2);
knn = l0*tn*cn^2/nn/bn;
cnn = cn*sqrt(bn);
exec, ncreate($i,knn,cnn);
value, i, bn, cnn, knn;
};
\end{verbatim}
\section{Closed Orbit Corrector}
\ttindex{kicker}\index{orbit corrector}
\label{sec:closed_orbit_cor} \label{sec:kicker}
Three types of magnetic closed orbit correctors are available:
\begin{madlist}
\ttitem{HKICKER} a corrector for the horizontal plane,
\ttitem{VKICKER} a corrector for the vertical plane,
\ttitem{KICKER} a corrector for both planes.
\end{madlist}
\madbox{
xxxxxxxxxxxxxxxx\=xxxxxxxxxxxxxxxxxxxx\= \kill
label: HKICKER, \>L=real, KICK=real, \>TILT=real; \\
label: VKICKER, \>L=real, KICK=real, \>TILT=real; \\
label: KICKER, \>L=real, HKICK=real, \>VKICK=real, TILT=real;
}
{\bf The type {\tt KICKER} should not be used when an orbit corrector
kicks only in one plane.}
The attributes have the following meaning:
\begin{madlist}
\ttitem{L} The length of the closed orbit corrector (default: 0 m).
\ttitem{KICK} The momentum change $\delta PX = \delta p_x/p_0$ or
$\delta PY = \delta p_y / p_0$ for respectively horizontal or vertical
correctors. (default: 0).
\ttitem{HKICK} The horizontal momentum change
$\delta PX = \delta p_x/p_0$ for a corrector acting in both planes
(default: 0).
\ttitem{VKICK} The vertical momentum change
$\delta PY = \delta p_y/p_0$ for a corrector acting in both planes
(default: 0).
\ttitem{TILT} The roll angle about the longitudinal axis (default: 0
rad). A positive angle represents a clockwise rotation of the
kicker.
\end{madlist}
A positive kick increases $p_x$ or $p_y$ respectively. This
means that a positive horizontal kick bends to the left, i.e. to
positive $x$ which is opposite of what is true for bends.
The deviation angle $\theta$ of the particle trajectory is related to
the momentum change through $\sin \theta = \delta P = \delta p / p_0$.
It should be noted that the kick values assigned to an orbit corrector
like above are not overwritten by an orbit correction using the
\hyperref[sec:correct]{\tt CORRECT}
command. Instead the kicks computed by an orbit correction and the
assigned values are added when the correctors are used.
Examples:
\madxmp{
xxxxxxx\=xxxxxxxxxx\=xxxxxxxxxxxxxxxxx\= \kill
HK1: \>HKICKER, \>KICK = 0.001; \\
VK3: \>VKICKER, \>KICK = 0.0005; \\
VK4: \>VKICKER, \>KICK := AVK4; \\
KHV1: \>KICKER, \>HKICK = 0.001, \>VKICK = 0.0005; \\
KHV2: \>KICKER, \>HKICK := AKHV2H, \>VKICK := AKHV2V;
}
The assignment in the form of a deferred expression has the advantage
that the values can be assigned and/or modified at any time (and
matched!).
The \hyperref[subsec:local_straight]{straight reference system} for an
orbit corrector is a Cartesian coordinate system.
Please note that there is a new feature introduced by Stefan Sorge from
GSI. Here his decription:
The elements {\tt KICKER, HKICKER}, and {\tt VKICKER} can also be used as
magnetic exciters providing sinusoidal momentum kicks. The usage in this case
is:
\madxmp{
xykick: KICKER, \= SINKICK=integer, SINPEAK=real, SINTUNE=real, SINPHASE=real; \\
xkick : HKICKER, \> SINKICK=integer, SINPEAK=real, SINTUNE=real, SINPHASE=real; \\
ykick : VKICKER, \> SINKICK=integer, SINPEAK=real, SINTUNE=real, SINPHASE=real;
}
where a sinusoidal momentum kick {\tt dpz} as a function of the revolution
number {\tt n} given by\\
{\tt dpz(n)=SINPEAK * sin(2*PI*SINTUNE*n + SINPHASE), pz=px,py} \\
is provided.
The {\tt KICKER} element generates synchronous kicks in both horizontal and
vertical planes. {\tt HKICKER} generates only a horizontal kick, and {\tt
VKICKER} generates only a vertical kick.
The variables are
\begin{madlist}
\ttitem{SINKICK} must be set to 1 to switch on the sinusoidal
signal, default: 0.
\ttitem{SINPEAK} amplitude of the bending angle (rad); default: 0
rad.
\ttitem{SINTUNE} frequency of the signal times the revolution
frequency. Hence, the phase per revolution is 2*PI*SINTUNE;
default: 0.
\ttitem{SINPHASE} initial phase; default: 0 rad.
\end{madlist}
The momentum kick of a kicker has only a single frequency. An element
having a finite bandwidth can approximately created by defining thin
kickers with all amplitudes {\tt SINPEAK}, frequencies {\tt SINTUNE}, and
initial phases {\tt SINPHASE} desired and putting them at the same position s
in the accelerator.
\section{Transverse Kicker}
\ttindex{tkicker}
\label{sec:tkicker}
The type {\tt TKICKER} should be used to create horizontal, vertical or
combined transverse magnetic kickers physically equivalent to elements of type
{\tt KICKER}, but \textbf{not used} by the \hyperref[sec:correct]{CORRECT}
command of the closed orbit correction module.
Examples of elements that may use the type {\tt TKICKER}:
\begin{itemize}
\item Fast kickers for injection, dump \& tune
\item Magnetic septa towards beam dump
\item Dampers of transverse beam oscillations
\item Undulator \& Wiggler magnets
\end{itemize}
For further information on element type {\tt TKICKER} and its attributes, look
at the documentation of the orbit corrector type
\hyperref[sec:kicker]{\tt KICKER}.
\section{RF Cavity}
\ttindex{RFcavity}
\label{sec:rf_cavity} \label{sec:rfcavity}
\madbox{
label: RFCAVITY, \= L=real, VOLT=real, LAG=real, \\
\> HARMON=integer, FREQ=real, \\
\> N\_BESSEL=integer, NO\_CAVITY\_TOTALPATH=logical;
}
An {\tt RFCAVITY} has eight real attributes and one integer attribute:
\begin{madlist}
\ttitem{L} The length of the cavity (DEFAULT: 0 m)
\ttitem{VOLT} The peak electrical RF voltage (DEFAULT: 0 MV). The effect of
the cavity is \\
delta(\textit{E}) = VOLT * sin(2 pi * (LAG - HARMON * \textit{f$_0$ t})).
\ttitem{LAG} The phase lag [2pi] (DEFAULT: 0).
\ttitem{FREQ} The frequency [MHz] (no DEFAULT). Note that if the RF
frequency is not given, it is computed from the harmonic number and
the revolution frequency \textit{f$_0$} as before. However, for
accelerating structures this makes no sense, and the frequency is
mandatory.
\ttitem{HARMON} The harmonic number \textit{h} (no DEFAULT). Only if
the frequency is not given.
\end{madlist}
\textit{ Please take note, that the following \madeight attributes:
{\tt BETRF, PG, SHUNT} and {\tt TFILL} are currently not implemented in
\madx!}
\textit{ Note as well that Twiss is 4D only. As a consequence
the {\tt TWISS} parameters in the plane of non-zero dispersion may not
close as expected. Therefore, it is best to perform {\tt TWISS} in 4D
only, i.e. with cavities switched off. If 6D is needed one has to
use the \hyperref[sec:ptc_twiss]{\tt PTC\_TWISS} command. }
The {\tt RFCAVITY} can also have attributes that will only become active in
\ptc:
\begin{madlist}
\ttitem{N\_BESSEL} (DEFAULT: 0): \\
Transverse focussing effects are typically ignored in the cavity in
\madx or even \ptc. This effect is being calculated to order {\tt
n\_bessel},
with {\tt n\_bessel=0} disregarding this effect and with a correct
treatment
when {\tt n\_bessel} goes to infinty.
\ttitem{NO\_CAVITY\_TOTALPATH} (Default: false): \\
flag to select whether the transit time factor in the cavity is to be
considered ({\tt NO\_CAVITY\_TOTALPATH = false}) or if the particle is
kept on the crest of RF voltage ({\tt NO\_CAVITY\_TOTALPATH = true}).
\end{madlist}
A cavity requires the particle energy (\href{beam.html#energy}{ENERGY})
and the particle charge (\href{beam.html#charge}{CHARGE}) to be set by a
\href{beam.html}{BEAM} command before any calculations are performed.
Example:
\madxmp{
BEAM, PARTICLE = ELECTRON, ENERGY = 50.0; \\
CAVITY: RFCAVITY, L = 10.0, VOLT = 150.0, LAG = 0.0, HARMON = 31320;
}
The \hyperref[subsec:local_straight]{straight reference system} for a
cavity is a Cartesian coordinate system.
\section{Thin Radio-Frequency Multipole}
\ttindex{rfmultipole}
\label{sec:rfmultipole}
\madbox{
xxxxxxxxxxxxxxxxxxxxx\= \kill
label: RFMULTIPOLE, \> VOLT=real, LAG=real, \\
\> HARMON=integer, FREQ=real, \\
\> LRAD=real, TILT=real, \\
\> KNL=\{real, \ldots \}, KSL=\{real, \ldots \}, \\
\> PNL=\{real, \ldots \}, PSL=\{real, \ldots \};
}
A {\tt RFMULTIPOLE} is a thin-lens element which exhibits the properties
of an RF-cavity and of a magnet of arbitrary order oscillating at
a certain frequency.
The effect of the cavity is {\tt delta(E) = VOLT * sin(2 pi * (LAG - HARMON *
f0 t))}.
\begin{madlist}
\ttitem{VOLT} The peak RF voltage (DEFAULT: 0 MV).
\ttitem{LAG} The phase lag [2pi] (DEFAULT: 0)
\ttitem{FREQ} The frequency [MHz] (no DEFAULT). \\
Note that if the RF
frequency is not given, it is computed from the harmonic
number and the revolution frequency f0 as before. However, for
accelerating structures this makes no sense, and the frequency
is mandatory.
\ttitem{HARMON} The harmonic number h (no DEFAULT). Only if the
frequency is not given.
\ttitem{LRAD} A fictitious length, which was originally just used to
compute synchrotron radiation effects. A non-zero {\tt LRAD} in
conjunction with \hyperref[sec:option]{\tt OPTION, thin\_foc = true;}
takes into account the weak focussing of bending magnets.
\ttitem{TILT} The roll angle about the longitudinal axis (default: 0
rad). A positive angle represents a clockwise rotation of the
multipole element.
\textbf{Please note that contrary to \madeight one has to specify the
desired {\tt TILT} angle, otherwise it is taken as 0 rad. We
believe that the \madeight concept of having individual {\tt TILT}
values for each component and on top with default values
led to considerable confusion and allowed for excessive
and unphysical freedom. Instead, in \madx the {\tt KNL, KSL}
components can be considered as the normal or skew
multipole components of the magnet on the bench, while the
{\tt TILT} attribute can be considered as an tilt alignment
error in the machine.}
\ttitem{KNL} An array of the integrated normal rfmultipole
coefficients, starting from order zero and up to the maximum
order (currently 20).
The parameters are positional in the array, therefore leading
zeros must be filled in for components that do not exist.
% The normal rfmultipole coefficients from order zero to
% the maximum; the parameters are positional, therefore zeros
% must be filled in for components that do not exist. Example of
% a thin-lens sextupole: ms:rfmultipole, knl:=\{0, 0, k2l\};
\ttitem{KSL} An array of the integrated skew rfmultipole
coefficients, starting from order zero and up to the maximum
order (currently 20).
The parameters are positional in the array, therefore leading
zeros must be filled in for components that do not exist.
% The skew rfmultipole coefficients from order zero to
% the maximum; the parameters are positional, therefore zeros
% must be filled in for components that do not exist. Example of
% a thin-lens skew octupole:
\ttitem{PNL} The phase for each normal rfmultipole coefficients from
order zero to the maximum; the parameters are positional,
therefore leading zeros must be filled in for components that do not
exist.
\ttitem{PSL} The phase for each skew rfmultipole coefficients from
order zero to the maximum; the parameters are positional,
therefore leading zeros must be filled in for components that do not
exist.
\end{madlist}
{\bf Example:}
\madxmp{MS: RFMULTIPOLE, KSL = \{0, 0, 0, k3sl\};}
Both {\tt KNL} and {\tt KSL} may be specified for the same multipole.
A {\tt RFMULTIPOLE} requires the particle energy ({\tt ENERGY}) and the
particle charge ({\tt CHARGE}) to be set with a \hyperref[sec:beam]{\tt BEAM}
command before any calculation is performed.
A {\tt RFMULTIPOLE} with no dipole component has no effect on the reference
orbit, i.e. the reference system at its exit is the same as at its
entrance. If it includes a dipole component, it has the same effect on
the reference orbit as a thin {\tt MULTIPOLE} with equivalent
parameters.
\section{Crab Cavity}
\ttindex{crabcavity}
\label{sec:crab_cavity} \label{sec:crabcavity}
\madbox{
label: CRABCAVITY, \=L=real, VOLT=real, LAG=real, FREQ=real, \\
\>RV1=integer, RV2=integer, RV3=integer, RV4=integer, \\
\>RPH1=integer, RPH2=integer, \\
\>LAGF=real, HARMON=integer;
}
A {\tt CRABCAVITY} has five attributes describing its steady state
and seven attributes to describe dynamic behaviour:
\begin{madlist}
\ttitem{L} The length of the cavity (default: 0 m)
\ttitem{VOLT} The peak RF voltage (default: 0 MV).
\ttitem{LAG} The initial phase lag [2pi] (default: 0).
\ttitem{FREQ} The RF frequency [MHz] (no default). \\[3mm]
{\bf Note that if the RF frequency is not given, it is computed from the
harmonic number and the revolution frequency \textit{f$_0$} as before.
However, for deflecting structures this makes no sense, and the
frequency is mandatory.}
\ttitem{HARMON} The harmonic number \textit{h} (no default). \\
Only if the frequency is not given.
% \item BETRF: RF coupling factor (default: 0).
% \item PG: The RF power per cavity (default: 0 MW).
% \item SHUNT: The relative shunt impedance (default: 0 MOhm/m).
% \item TFILL: The filling time of the cavity T_{fill} (default: 0 microseconds).
%\item EPHASE: Value of the final crab RF phase [2pi] with respect to nominal value (default: 0).
\end{madlist}
The other attributes describe the time evolution of a {\tt CRABCAVITY} behaviour:
{\begin{madlist}
\ttitem{RV1} Number of initial turns with zero voltage (default: 0).
\ttitem{RV2} Number of turns to ramp voltage from zero to nominal value (default: 0).
\ttitem{RV3} Number of turns with nominal voltage (default: 0).
\ttitem{RV4} Number of turns to ramp voltage from nominal value to zero (default: 0).
\ttitem{LAGF} Value of the final crab RF phase lag [2pi] (default: 0).
\ttitem{RPH1} Number of initial turns with nominal phase (default: 0).
\ttitem{RPH2} Number of turns to ramp phase [2pi] from nominal to
specified value \\ (default:~0).
{\bf Caveats:}
\begin{itemize}
\item Please take note, that the following \madeight attributes:
{\tt BETRF, PG, SHUNT} and {\tt TFILL} are currently not implemented in
\madx!
\item Note that crab cavities are only implemented for
tracking purposes. \\ \hyperref[chap:twiss]{\tt TWISS} ignores any effect
of the crab cavity.
% as well that twiss is 4D only. As a consequence the TWISS
% parameters in the plane of non-zero dispersion may not close as
% expected. Therefore, it is best to perform TWISS in 4D only, i.e. with
% cavities switched off. If 6D is needed one has to use the
% ptc_twiss command.
\end{itemize}
Before any calculation is performed with a {\tt CRABCAVITY}, the particle
\hyperref[sec:beam]{\tt ENERGY} and the particle \hyperref[sec:beam]{\tt CHARGE}
must be set with the \hyperref[sec:beam]{\tt BEAM} command.
The effect of a {\tt CRABCAVITY} on particle coordinates during tracking is
$\delta p_x$ = {\tt VOLT * }$\sin${\tt(PHI - OMEGA * t)}
$\delta E$ = {\tt- VOLT * OMEGA * x * }$\cos${\tt(PHI - OMEGA * t)}
where {\tt PHI = $2\pi$ * (LAG - HARMON * $f_0$ t)},
and {\tt OMEGA = $2\pi$ * FREQ / $c$}
Example:
\madxmp{
xxxxxxxx\= \kill
BEAM, PARTICLE = PROTON, ENERGY = 7000.0; \\
CAVITY: \>CRABCAVITY, L = 10.0, VOLT = 5.0, LAG = 0.0, FREQ = 400, \\
\>RV1 = 0, RV2 = 50, RV3 = 1000, RV4 = 50, \\
\>RPH1 = 100, RPH2 = 500, LAGF = 0.125;
}
The \hyperref[subsec:local_straight]{straight reference system} for a
cavity is a Cartesian coordinate system.
\section{Electrostatic Separator}
\ttindex{elseparator}
\label{sec:separator} \label{sec:elseparator}
\madbox{
label: ELSEPARATOR, L=real, EX=real, EY=real, TILT=real;
}
An {\tt ELSEPARATOR} element has four real attributes:
\begin{madlist}
\ttitem{L} The length of the separator (default: 0 m).
\ttitem{EX} The horizontal electric field strength (default: 0 MV/m).
A positive field increases \textit{p$_x$} for positive particles.
\ttitem{EY} The vertical electric field strength (default: 0 MV/m).
A positive field increases \textit{p$_y$} for positive particles.
\ttitem{TILT} The roll angle about the longitudinal axis (default: 0
rad). A positive angle represents a clockwise of the electrostatic
separator.
\end{madlist}
An electrostatic separator requires the particle energy
({\tt ENERGY}) and the particle charge
({\tt CHARGE}) to be set by a \hyperref[sec"beam]{\tt BEAM}
command before any calculation is performed.
Example:
\madxmp{
BEAM, PARTICLE=positron, ENERGY=50.0;\\
SEP: ELSEPARATOR, L=5.0, EY=0.5;
}
The \hyperref[subsec:local_straight]{straight reference system} for a
separator is a Cartesian coordinate system.
\section{Beam Position Monitor}
\label{sec:monitor}
A beam monitor has no specific effect on the beam and behaves like a
drift space.
In addition it serves to record the beam position for closed orbit
correction.
Three different types of beam position monitors are recognised:
\begin{madlist}
\ttitem{HMONITOR} Monitor for the horizontal beam position,
\ttitem{VMONITOR} Monitor for the vertical beam position,
\ttitem{MONITOR} Monitor for both horizontal and vertical beam position.
\end{madlist}
\madbox{
label: HMONITOR, \= L=real; \\
label: VMONITOR, \> L=real; \\
label: MONITOR, \> L=real;
}
A beam position monitor has one real attribute:
\begin{madlist}
\ttitem{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.
\end{madlist}
Examples:
\madxmp{
MH: HMONITOR, L = 1; \\
MV: VMONITOR;
}
The \hyperref[subsec:local_straight]{straight reference system} for a
monitor is a Cartesian coordinate system.
\section{Instrument}
\label{sec:instrument}
An instrument has no specific effect on the beam and behaves like a
drift space.
Instruments are different from beam position monitors and are not used
for closed orbit correction.
Two different types of instruments are recognised:
\begin{madlist}
\ttitem{INSTRUMENT} A place holder for any type of beam
instrumentation. Optically it behaves like a drift space; it
returns \emph{no beam observation}. It represent a class of
elements which is completely independent from drifts and monitors.
\ttitem{PLACEHOLDER} A place holder for any type of
element. Internally it is equivalent to an {\tt INSTRUMENT}:
optically it behaves as a drift space, it returns
\emph{no beam observation}. It represent a class of elements
which is completely independent from drifts and monitors.
\end{madlist}
\madbox{
xxxxxxxxxxxxxxxxxxxxx\= \kill
label: INSTRUMENT, \>L=real; \\
label: PLACEHOLDER, \>L=real;
}
An instrument or placeholder has one real attribute:
\begin{madlist}
\ttitem{L} The length of the instrument (default: 0 m).
\end{madlist}
The \hyperref[subsec:local_straight]{straight reference system} for an
instrument is a Cartesian coordinate system.
\section{Collimator}
\label{sec:collimator}
A {\tt COLLIMATOR} has no specific effect on beam optics and behaves like a
\hyperref[sec:drift]{drift space}.
\madbox{
label: COLLIMATOR, \=L=real, \\
\>APERTYPE=string, APERTURE=\{values\}, \\
\>APER\_OFFSET=\{values\}, APER\_TOL=\{values\};
}
A {\tt COLLIMATOR} has one specific real attribute:
\begin{madlist}
\ttitem{L} The collimator length (default: 0 m).
\end{madlist}
Additionally, like any other element, except {\tt DRIFT} space,
a {\tt COLLIMATOR} can have specific aperture related attributes
as defined in the related section \hyperref[sec:def_aper]{Defining
aperture in \madx}
During \hyperref[chap:thin_track]{tracking} in \madx, particle loss
is checked at the entrance of the element by comparing particle coordinates
and defined aperture, provided that the {\tt APERTURE} flag is {\tt true}
in the \hyperref[sec:track]{\tt TRACK} command,
and that the {\tt APERTYPE} attribute value of the element is one of the
predefined types.
An aperture model defined in an external file ({\tt APERTYPE=filename})
is not used to check particle loss during tracking.
Example:
\madxmp{
COLLIM: COLLIMATOR, L=0.5, APERTYPE=ellipse, APERTURE={0.01,0.005};
}
The \hyperref[subsec:local_straight]{straight reference system} for a
collimator is a Cartesian coordinate system.
\textbf{NOTE:} A collimator can be displaced transversally in order to
model an asymmetric collimator by means of the {\tt APER\_OFFSET} attributes;
During tracking particle losses are then reported with coordinates with respect
to the \textbf{displaced} reference system, not with respect to the surrounding
beam line.
Other collimator elements have been inherited from \madeight and still exist
in \madx for backward compatibility.
{\tt ECOLLIMATOR} (elliptic aperture collimator) and {\tt RCOLLIMATOR}
(rectangular aperture collimator)behave both as drift spaces in \madx
They are declared with
\madbox{
label: ECOLLIMATOR, L=real, XSIZE=real, YSIZE=real; \\
label: RCOLLIMATOR, L=real, XSIZE=real, YSIZE=real;
}
Either type has several real attributes:
\begin{madlist}
\ttitem{L} The collimator length (default: 0 m).
\ttitem{XSIZE} The horizontal half-aperture (default:
unlimited). \\ \textbf{OBSOLETE : parsed and stored but not used.}
\ttitem{YSIZE} The vertical half-aperture (default:
unlimited). \\ \textbf{OBSOLETE : parsed and stored but not used.}
\end{madlist}
It is STRONGLY advised to replaced all instances of {\tt RCOLLIMATOR}
and {\tt ECOLLIMATOR} in input files with appropriate {\tt COLLIMATOR}
elements. The {\tt RCOLLIMATOR} and {\tt ECOLLIMATOR} elements are only
kept for the time being for backward compatibility and will be removed in
the near future.
Note also that the {\tt XSIZE} and {\tt YSIZE} parameters can be declared
but are simply ignored both in the \hyperref[chap:aperture]{\tt APERTURE}
command an in \hyperref[chap:thintrack]{tracking}.
\section{Beam-beam Interaction}
The BEAMBEAM element may be inserted in a beam line to simulate a
beam-beam interaction point:
\madbox{
label: BEAMBEAM, \= SIGX=real, SIGY=real, \\
\> XMA=real, YMA=real, CHARGE=real, \\
\> BBSHAPE=integer, WIDTH=real, BBDIR=integer;
}
The beam-beam interaction is represented by a four-dimensional
interaction with a thin element, i.e. horizontal and vertical non-linear kicks.
The code for this element has been contributed by J.M.~Veuillen (1987)
and extended by S.~Sorge (2007).
\begin{madlist}
\ttitem{SIGX}
The horizontal extent of the opposite beam (default: 1 m).
Meaning depends on parameter BBSHAPE.
\ttitem{SIGY}
The vertical extent of the opposite beam (default: 1 m).
Meaning depends on parameter BBSHAPE.
\ttitem{XMA}
The horizontal displacement of the opposite beam with respect to
the ideal orbit (default: 0 m).
\ttitem{YMA}
The vertical displacement of the opposite beam with respect to
the ideal orbit (default: 0 m).
\ttitem{CHARGE}
The charge of particles in the opposite beam in elementary charges.
It is set by default to {\tt CHARGE=1}. So, if you want to describe
collisions
between beams containing the same particles having a charge different
from 1, you have to set {\tt CHARGE} explicitly in \hyperref[sec:beam]{\tt
BEAM} and in {\tt BEAMBEAM}.
\ttitem{BBSHAPE} The parameter to choose the radial density shape of the
opposite beam (default: 1)
\begin{itemize}
\item {\tt BBSHAPE=1}: Gaussian shape (default), {\tt SIGX, SIGY}:
standard deviation in horizontal, vertical direction.
\item {\tt BBSHAPE=2}: trapezoidal shape (see
fig.\ref{fig:beambeam_n_trapez}), {\tt SIGX, SIGY}: half width of
density profile, i.e. distance from the centre to half edge region with
linear decrease of density in horizontal, vertical direction. Still only
circular opposite beam possible, i.e. in the calculations {\tt
SIGX'=SIGY'=(SIGX+SIGY)/2} is used, if {\tt SIGX} and {\tt SIGY} have
different values.
\begin{figure}[h]
\begin{center}
\includegraphics[width=400px]{jpg/beambeam_n_trapez.jpg}
\caption{Trapezoidal shape of radial density for beam-beam lens.}
\label{fig:beambeam_n_trapez}
\end{center}
\end{figure}
\item {\tt BBSHAPE=3}: hollow-parabolic shape (see
fig.\ref{fig:beambeam_n_hollowparabol}, {\tt SIGX, SIGY}: distance
from the centre to the maximum of the parabolic density profile in
horizontal, vertical directions. Still only circular opposite beam
possible, i.e. in the calculations {\tt SIGX'=SIGY'=(SIGX+SIGY)/2} is
used, if {\tt SIGX} and {\tt SIGY} have different values.
\begin{figure}[h]
\begin{center}
\flushright
\includegraphics[width=420px]{jpg/beambeam_n_hollowparabol.jpg}
\caption{Hollow parabolic shape of radial density for beam-beam lens.}
\label{fig:beambeam_n_hollowparabol}
\end{center}
\end{figure}
\end{itemize}
The restriction to circular opposite beams in the cases {\tt BBSHAPE=2,3}
appears to be sufficient, because such beam profiles are more important
for the description of the interaction between the particle beam and
an electron beam of an electron cooler, which are usually circular.
\ttitem{WIDTH} The relative extent of the edge region, absolute value is
given by {\tt WIDTH*SIGX} and {\tt WIDTH*SIGY} in horizontal and vertical
direction, respectively.
For
\begin{itemize}
\item {\tt BBSHAPE=1}, {\tt WIDTH} is meaningless and will be ignored.
\item {\tt BBSHAPE=2}, {\tt WIDTH} denotes the full width of the edge
region in units of {\tt SIGX} (or {\tt SIGX'} and {\tt SIGY'},
respectively, if {\tt SIGX} and {\tt SIGY} are not equal), i.e.
if {\tt WIDTH=0.01} and {\tt SIGX=5}mm, the edge region has a full
width of 0.05\ mm. It must be {\tt WIDTH \textless 2.0}.
\item {\tt BBSHAPE=3}, {\tt WIDTH} denotes the full width at half
maximum of the parabolic density profile in units of {\tt SIGX} (or {\tt
SIGX'} and {\tt SIGY'}, respectively, if {\tt SIGX} and {\tt SIGY} are
not equal. It must be {\tt WIDTH \textless SQRT(2.0)}.
\end{itemize}
\ttitem{BBDIR} The parameter to choose the direction of motion of the
opposite beam relative to the beam considered. It determines
the sign of the Lorentz force between both beams (default: -1):
\begin{itemize}
\item {\tt BBDIR=-1}: Beams move in the opposite direction as in a
collider. The Lorentz force enhances the beam-beam interaction.
\item {\tt BBDIR=0}: Opposite beam does not move. The Lorentz force is
neglected
\item {\tt BBDIR=1}: Beams move in the same direction as in an
electron cooler. The Lorentz force reduces the beam-beam interaction.
\end{itemize}
Note:
\begin{itemize}
\item The particles in the beam considered may have a momentum
deviation given by {\tt DELTAP} defined in the \hyperref[sec:track]{\tt
TRACK} command.
\item The opposite beam is assumed to have the velocity according to
the unperturbed energy of the particles in the beam considered. Only
the direction of motion can be chosen.
\item In the case of motion in the opposite direction ({\tt
BBDIR=-1}), the time of interaction between the beams is given by {\tt
tau = length/(2*beta*c\_light)}, where {\tt length} is the length of a
bunch in the opposite beam. In the case of motion in the same direction
({\tt BBDIR=1}) as in an electron cooler, this time is given by {\tt
tau = length/(beta*c\_light)}, where {\tt length} is the length of the
cooler. Note that the factor 1/2 is inserted only for {\tt BBDIR=-1} to
calculate correct results.
\end{itemize}
\end{madlist}
A beam-beam element requires the particle energy
(\hyperref[sec:beam]{\tt ENERGY})
and the particle charge
(\hyperref[sec:beam]{\tt CHARGE})
as well as the number of particles per bunch
(\hyperref[sec:beam]{\tt NPART})
to be set by a \hyperref[sec:beam]{\tt BEAM} command
before any calculations are performed.
Examples of a four-dimensional beam-beam element definition:
Collider regime example:
\madxmp{
beam, particle = positron, npart = 1.e12, energy = 50.0; \\
bb: beambeam, sigx = 1.e-3, sigy = 5.e-4, charge = 1.;
}
Electron cooler example:
\madxmp{
gamma0 = 1.032; \= ! relativistic factors \\
beta0 = sqrt(1.0-1.0/gamm0/gamma0); \> \\
\> \\
i\_e = 0.2; \> ! electron current \\
re\_cool = 0.01; \> ! electron beam radius \\
l\_cool = 5.0; \> ! cooling length \\
nelect = i\_e*l\_cool/beta0/clight/qelect; ! electron number in e-cooler \\
beam, particle = antiproton, gamma = gamma0, npart = nelect; \\
bb\_ecool: beambeam, sigx = re\_cool, sigy = re\_cool, bbshape = 2, \\
\hskip4.2cm width = 0.01, charge = -1, bbdir = 1;
}
For the definition of the LHC head-on and parasitic beam-beam elements see
\href{../control/foot.html#macro}{beam-beam element examples}.
\section{Arbitrary Matrix Element}
\madbox{
label: MATRIX, \= TYPE=string, L=real, \\
\> KICK1=real,..., KICK6=real, \\
\> RM11=real, ..., RM66=real, \\
\> TM111=real, ..., TM666=real;
}
The MATRIX permits the definition of an arbitrary transfer matrix.
It has four real array attributes:
\begin{madlist}
\ttitem{L} Length of the element, which may be zero.
\ttitem{KICKi} Defines the kick of the element acting on the six phase
space coordinates.
\ttitem{RMik} Defines the linear transfer matrix (6*6) of the element.
\ttitem{TMikl} Defines the second-order terms (6*6*6) of the element.
\end{madlist}
Data values not entered are taken from the identity transformation, kick
and second order terms are zero as default. In the thin-lens tracking
module the length of an arbitrary matrix is accepted, however no second
order are allowed to avoid non symplectic tracking runs. In the latter
case the tracking run will be aborted.
\section{Rotation around the vertical axis}
\label{sec:yrotation}
The element {\tt YROTATION} rotates the
\hyperref[subsec:local_straight]{straight reference system} about the
vertical ({\tt y}) axis.
\madbox{
label: YROTATION, ANGLE=real;
}
{\tt YROTATION} has no effect on the beam, but it
causes the beam to be referred to the new coordinate system \\
\begin{equation}
\begin{split}
x_2 &= x_1 \cos\theta - s_1 \sin\theta \\
y_2 &= x_1 \sin\theta + s_1 \cos\theta
\end{split}\end{equation}
It has one real attribute:
\begin{madlist}
\ttitem{ANGLE} The rotation angle $\theta$ (default: 0 rad).
\end{madlist}
A positive angle means that the new reference system is rotated
clockwise about the local {\tt y}-axis with respect to the old system.
{\bf Important note:} \\
The rotation angle $\theta$ must be \emph{small}, i.e. it must be at
most comparable to the transverse angles of the orbit.
Example:
\madxmp{
KINK: YROTATION, ANGLE = 0.0001;
}
\section{Rotation around the longitudinal axis}
\label{sec:srotation}
The element {\tt SROTATION} rotates the
\hyperref[subsec:local_straight]{straight reference system} about the
longitudinal ({\tt s}) axis.
\madbox{
label: SROTATION, ANGLE=real;
}
{\tt SROTATION} has no effect on the beam, but it causes the beam to be
referred to the new coordinate system \\
\begin{equation}
\begin{split}
x_2 &= x_1 \cos\psi - y_1 \sin\psi \\
y_2 &= x_1 \sin\psi + y_1 \cos\psi
\end{split}\end{equation}
It has one real attribute:
\begin{madlist}
\ttitem{ANGLE} The rotation angle $\psi$ (default: 0 rad)
\end{madlist}
A positive angle means that the new reference system is rotated
clockwise about the {\tt s}-axis with respect to the old system.
Example:
\madxmp{
ROLL1: SROTATION, ANGLE = PI/2.; \\
ROLL2: SROTATION, ANGLE = -PI/2.; \\
HBEND: SBEND, L = 6.0, ANGLE = 0.01; \\
VBEND: LINE = (ROLL1,HBEND,ROLL2); \\
}
The VBEND definition above is a way to represent a bend down in the
vertical plane, it could be defined more simply by
\madxmp{
VBEND: SBEND, L = 6.0, K0S = 0.01/6;
}
\section{Coordinate translation}
\label{sec:translation}
The element {\tt TRANSLATION} changes the
\hyperref[subsec:local_straight]{reference system}
by applying a translation of the reference system.
\madbox{
label: TRANSLATION, \= X=real, \= Y=real, \= T=real, \\
\> PX=real, \> PY=real, \> PT=real;
}
{\tt TRANSLATION} has no effect on the beam, but it causes the beam to be
referred to the new coordinate system \\
\begin{equation}
\begin{split}
x_2 &= x_1 \cos\psi - y_1 \sin\psi \\
y_2 &= x_1 \sin\psi + y_1 \cos\psi
\end{split}\end{equation}
\section{Change of reference system}
\label{sec:changeref}
The element {\tt CHANGEREF} changes the
\hyperref[subsec:local_straight]{reference system}
by applying both translations and rotations.
\madbox{
label: CHANGEREF, \= PATCH\_ANG={real, real, real}, \\
\> PATCH\_TRANS={real, real, real};
}
{\tt CHANGEREF} has no effect on the beam, but it causes the beam to be
referred to the new coordinate system \\
\begin{equation}
\begin{split}
x_2 &= x_1 \cos\psi - y_1 \sin\psi \\
y_2 &= x_1 \sin\psi + y_1 \cos\psi
\end{split}\end{equation}
\chapter{Range and Class Selection Format}
\section{RANGE}
\label{sec:range}
A range can be defined starting at a given element and ending at
another element, both elements included. Two forms exist:
\madxmp{
RANGE=position; \\
RANGE=position1/position2;
}
In the first case, only one element is selected; in the second case, one
or several elements are selected. NOTE: position1 must not be behind
position2 in the sequence.
"position" is composed of the element name and an optional occurrence
count in the sequence: \label{range_position}
\madxmp{
xxxxxxxxxxxxxx\= \kill
mq.ir5.l6..1 \> ! no occurrence count given\\
mb[17] \> ! occurrence count given
}
There are two predefined indices in \madx:
\begin{madlist}
\ttitem{\#S} The start of the beam line expanded by USE,
\ttitem{\#E} The end of the beam line expanded by USE.
\end{madlist}
If a range is selected in a {\tt USE} statement:
\madxmp{
USE, PERIOD=lhcb1, RANGE=ir1/ir5;
}
then the {\tt \#S} and {\tt \#E} indices refer to the start and end of the
range expanded by the {\tt USE} statement .
Examples for ranges:
\madxmp{
xxxxxxxxxxxxxxxxxxxxxxxx\= \kill
.., RANGE=\#S; \>! first element \\
.., RANGE=\#S/\#E; \>! full expansion range \\
.., RANGE=mb[5]/\#E; \>! from mb 5 to end \\
.., RANGE=mq.ir5.l6..1; \>! first occurrence of element mq.ir5.l6..1
}
\section{CLASS}
\label{sec:class}
The single name of a class (no occurrence counts). A class is the name
of an element (or basic type) from which other elements have been
derived.
Example:
\madxmp{
MQ: quadrupole; \= ! makes the element MQ \\
Q1: MQ; \> ! makes the element Q1 from class MQ \\
Q2: MQ; \> ! makes the element Q2 from class MQ \\
Q1..A: Q1; \> ! makes an element from class Q1 \\
Q2..B: Q2; \> ! makes an element from class Q2
}
Subsequent selection with criterion {\tt CLASS="MQ"} will actually select
{\tt Q1, Q2, Q1..A}, and {\tt Q2..B} in this example.
\chapter{Beam Lines}
\label{chap:beamlines}
The accelerator to be studied is known to \madx either as a sequence of
physical elements called \hyperref[chap:sequence]{sequence}, or as a
hierarchically structured list of elements called a \emph{beam line}.
A beam line is built from simpler beam lines whose definitions can be
nested to any level. A powerful syntax allows to repeat, to reflect, or
to replace pieces of beam lines. However, internally \madx knows only
sequences, and lines as shown below are converted into flat sequences
with the same name when they are expanded. Consequently, only sequences
can be SAVEd onto a file.
Formally a beam line is defined by a LINE command:
\madbox{
label( arg {,arg} ): LINE=( member {,member} );
}
\hyperref[sec:label]{Label} gives a name to the beam line for later reference.
The formal argument list (arg\{,arg\}) is optional (see below). Each
"member" may be one of the following:
\begin{itemize}
\item Element label,
\item Beam line label,
\item Sub-line, enclosed in parentheses,
\item Formal argument name,
\item Replacement list label.
\end{itemize}
Beam lines may be nested to any level (see \ref{sec:sublines})
{\bf Warning:}\\
\madxhas been developed using sequences. Machine description using
beamlines was kept in \madx to a minimal extent to keep backward
compatibility but also because it is often easier to start from beamlines
when designing an accelerator {\sl ab initio}.
But since \madx works only with sequences internally, there may exist
some inconveniences when only beamlines are defined by the user. It is
therefore recommended to convert beamlines into sequences (e.g. by means
of the \hyperref[sec:save]{\tt SAVE} command) as soon as possible lines in
the design phase and to use only sequences for a finalised machine.
Attempting to do sequence edition on a sequence that has
been expanded in memory from a beam line specified by the user is
strongly discouraged.
\section{Simple Beam Lines}
\label{sec:beamline}
The simplest beam line consists of single elements:
\madbox{
label: LINE= ( member \{,member\} );
}
Example:
\madxmp{
exmp1: \=LINE=(a,b,c,d,a,d); \\
USE, \>PERIOD=exmp1;
}
The {\tt USE} command causes \madx to load and expand the specified
beamline. This in particular loads the beamline as a SEQUENCE
representation in memory. All subsequent calculations are done on this
sequence in memory.
\section{Nested Beam Lines}
\label{sec:sublines}
Instead of referring to an element, a beam line member can refer to
another beam line defined in a separate command. This provides a
shorthand notation for sub-lines or nested beam lines which can occur
several times in a beam line.
Lines and sub-lines can be entered in any order, but when a line is
expanded, all its sub-lines must be known.
Example:
\madxmp{
top: \=LINE=(a,b,S,b,a,S,a,b); \\
S: \>LINE=(c,d,e); \\
USE, \>PERIOD=top;
}
produces the following expansion steps:
\begin{enumerate}
\item Replace sub-line S:
\madxmp{(a, b, (c,d,e), b, a, (c,d,e), a, b)}
\item Omit parentheses:
\madxmp{a, b, c, d, e, b, a, c, d, e, a, b}
\end{enumerate}
\section{Reflection and Repetition}
\label{sec:reflect_repeat_lines}
An unsigned repetition count and an asterisk (multiplication sign)
indicate repetition of a beam line member.
A repetition count can be applied to sub-lines as well as elements.
A minus prefix causes reflection, i.e. all elements in the sub-line are
taken in reverse order. Sub-lines of reflected lines are also reflected.
Physical elements are not reflected head-to-tail, hence a negative
repetition count for a single element is treated as positive.
If both reflection and repetition are desired, the minus sign must
precede the repetition count.
Example:
\madxmp{
xxxxx\= \kill
R: \>LINE= (g, h); \\
S: \>LINE= (c, R, d); \\
top: \>LINE= (2*S, 2*(e,f), -S, -(a,b), -2*c); \\
USE, \>PERIOD=top;
}
produces the following expansion steps:
\begin{enumerate}
\item Replace sub-line S:
\madxmp{( (c,R,d), (c,R,d), (e,f), (e,f), (d,-R,c), (b,a), c, c)}
\item Replace sub-line R:
\madxmp{( (c, (g,h), d), (c, (g,h), d), (e,f), (e,f), (d, (h,g), c),
(b,a), c, c)}
\item Omit parentheses:
\madxmp{c, g, h, d, c, g, h, d, e, f, e, f, d, h, g, c, b, a, c, c}
\end{enumerate}
Note that the inner sub-line \texttt{R} is reflected together with the
outer sub-line \texttt{S}.
Note also that \texttt{-2*c} at the end of the \texttt{top} line is
equivalent to \texttt{2*c} since single elements are not reflected, or
\texttt{2*(c)} which would first promote \texttt{c} as a sub-line of a
single element, or \texttt{-2*(c)} since reverting a sub-line of a
single element gives the same single element.
\section{Replaceable Arguments}
\label{sec:repl_args}
A beam line definition may contain a formal argument list, consisting of
labels separated by commas and enclosed in parentheses.
\madbox{
label( arg \{,arg\} ): LINE= ( member \{,member\} );
}
where \texttt{member} can be one of the \texttt{arg} arguments.
A beam line defined with arguments can be expanded for different values
of its arguments.
The arguments can be beam lines or element names. The number of actual
arguments given at time of use must agree with the number of formal
arguments defined at declaration time. All occurrences of a formal
argument on the right-hand side of the line definition are replaced by
the corresponding actual argument.
Example:
\madxmp{
fodo(Q1,Q2): \=LINE=(Q1, d, Q2, d);\\
top: \> LINE = ( fodo(qf12, qd23), fodo(qd34,qf45) );\\
USE, PERIOD=top;
}
expands to
\madxmp{qf12, d, qd23, d, qd34, d, qf45, d}
Example showing that arguments can also be beam lines:
\madxmp{
xxxxxxxx\= \kill
s: \>LINE = (a,b,c); \\
l(x,y): \>LINE = (d,x,e,3*y); \\
l4f: \>LINE = (4*f); \\
lm2s: \>LINE = (-2*s); \\
res: \>LINE = l(l4f,lm2s); \\
}
Proceeding step by step, this example generates the expansion
\madxmp{d, f, f, f, f, e, c, b, a, c, b, a, c, b, a, c, b, a, c, b, a, c, b, a}
\section{Limits of Construction of Beam Lines}
Since Lines are in fact depreciated there are some limits of how they
can be constructed. Please find below a running \madx run which shows an
example of OK (valid) and WRONG (invalid) cases.
\begin{verbatim}
!----------------------------------------------------------------------
beam, PARTICLE=electron, energy=1;
qf: QUADRUPOLE, L:=1,K1:=1;
qd: QUADRUPOLE, L:=1,K1:=-1;
d: DRIFT, l=1;
m: MARKER;
rpl(a,b): LINE=(a,b);
sl: LINE=(qf,d,qd);
test0: LINE=(rpl(sl,sl)); !OK
test1: LINE=(rpl((sl),(sl))); !OK
test2: LINE=(rpl((sl),(-sl))); !OK
test3: LINE=(sl,-sl); !OK
test4: LINE=(rpl((3*sl),(3*sl))); ! WRONG
test5: LINE=(3*sl,3*sl); !OK
test6: LINE=(rpl((3*sl),(-3*sl))); ! WRONG
test7: LINE=(3*sl,-3*sl); !OK
use, period=test0;
twiss,BETX=1,bety=1;
use, period=test1;
twiss,BETX=1,bety=1;
use, period=test2;
twiss,BETX=1,bety=1;
use, period=test3;
twiss,BETX=1,bety=1;
use, period=test4;
twiss,BETX=1,bety=1;
use, period=test5;
twiss,BETX=1,bety=1;
use, period=test6;
twiss,BETX=1,bety=1;
use, period=test7;
twiss,BETX=1,bety=1;
!----------------------------------------------------------------------
\end{verbatim}
\chapter{Sequences}
\label{chap:sequence}
\madxaccepts two forms of an accelerator definition: sequences and
beam lines (See \ref{chap:beamlines}).
However, the sequence definition is the only one used internally by \madx.
A sequence is declared with the following statements:
\madbox{
name: \=SEQUENCE, \=L=real, REFER=string, REFPOS=string, \\
\> \>ADD\_PASS=integer, NEXT\_SEQU=string; \\
\>\dots \\
xxxxxx\=xxxxxxx\=xxxxxxxx\= \kill
\>label: \>class, \>AT=real, FROM=string \{, additional attributes\}; \\
\> \>class, \>AT=real, FROM=string \{, additional attributes\}; \\
\>seqname, \> \>AT=real, FROM=string; \\
\>\ldots \\
ENDSEQUENCE;
}
The first statement declares a sequence, giving it a name in the form of
a label, and providing some key parameters:
\begin{madlist}
\ttitem{L} (Default: {\tt 0.})\\
the total length of the sequence in meters.
\ttitem{REFER}{\tt = keyword} in {\tt \{entry, centre, exit\}} (Default:
{\tt centre}) \\
specifies which part of the element is taken as the reference point
at which the position along the beamline is given.
\ttitem{REFPOS} (Default: {\tt none})\\
specifies the name of an element in this sequence to be used as the
reference point for the insertion of this sequence in another
sequence.
\ttitem{ADD\_PASS} (Default: 0)\\
specifies a number of additional passes (max. 5) through the
structure; in case of an RBEND the angle will be overwritten in survey
using the i-th component ($1 \le i \le {\tt add\_pass} \le 5$) of
its {\tt array\_of\_angles} attribute (see \hyperref[sec:rbend]{\tt
RBEND}).
\ttitem{NEXT\_SEQU} (Default: {\tt none})\\
specifies the name of a sequence to be concatenated
to the end of this sequence.
\end{madlist}
The \texttt{ENDSEQUENCE} statement terminates the declaration of a
sequence.
Inside the \texttt{SEQUENCE \ldots ENDSEQUENCE} bracketing keywords,
several types of statements may appear:
\begin{itemize}
%% pending check...
%% \item An element already declared:
%% \madbox{label: AT=real, FROM=string \{, attributes\} ;}
%% where label is an already declared element, with additional \texttt{AT}
%% attribute giving the relative element position, and an optional
%% \texttt{FROM} attribute;
\item An element declaration with label:
\madbox{label: class, AT=real, FROM=string \{, attributes\} ;}
an element declaration as usual, with additional \texttt{AT}
attribute giving the relative element position, and an optional
\texttt{FROM} attribute; \\
{\bf CAUTION:} an existing definition for an element with the
same name (label) will be replaced, however, defining the same
element twice inside the same sequence results in a fatal error,
since a unique object (this element) would be placed at two
different positions.
\item An element declaration from class:
\madbox{class, AT=real, FROM=string \{, attributes\} ;}
a class name causing an instance of that class to be created with
specified attributes, with additional \texttt{AT} attribute giving the
relative element position, and an optional \texttt{FROM} attribute;\\
For uses inside ranges, instances of the same class can then be
accessed with an occurrence count.
\item A sub-sequence name:
\madbox{seqname, AT=real, FROM=string ;}
a sequence name with additional \texttt{AT} attribute giving the
relative element position, and an optional \texttt{FROM} attribute;\\
%this causes the sequence with that name (inserted sequence) to be
%placed at the position relative to the start of the current
%containing sequence. \\
Depending upon the {\tt REFER} attribute of the current (containing)
sequence, the \texttt{entry}, \texttt{centre}, or \texttt{exit} of
the inserted sequence is placed at the position specified. \\
HOWEVER, if the inserted sequence has a {\tt REFPOS} attribute containing
the name of an element in the inserted sequence, the inserted sequence
is placed such that the element pointed to by {\tt REFPOS} is at the location
specified in the current sequence.
\end{itemize}
The additional arguments that can be given in the declaration of sequence
elements or sub-sequences are:
\begin{madlist}
\ttitem{AT} mandatory argument giving the location at
which the reference point ({\tt entry, centre} or {\tt exit}) of
the element is to be placed in the sequence. \\
The value is absolute with the zero reference at the start of the
sequence, unless a {\tt FROM} argument is specified.
\ttitem{FROM} optional argument giving the name of an
element of the same sequence. \\
The location given for the current element or sequence in the {\tt AT}
argument is then taken as {\bf relative} to the position of the
center of the element given by the {\tt FROM} argument. \\
Only simple elements should be used in FROM; specifying a sequence
as the FROM reference can lead to erroneous sequence expansion at best.
\end{madlist}
When the sequence is expanded in a \hyperref[sec:use]{\tt USE}
command, \madx generates the drift spaces between elements according to
the following rules:
\begin{enumerate}
\item When the distance between the exit of the previous element and the
entrance of the next element is positive and greater than a threshold
of $1 \mu m$ an explicit drit is generated with its own name, unless
an already existing drift space with the same length (within $10^{-12}
m$ tolerance) can be re-used.
\item When the absolute value of the distance between the exit of the
previous element and the entrance of the next element is less than a
given tolerance of $1\mu m$, no drift space is created and the
elements are considered as contiguous. \\
{\bf Note that in very specific cases this can cause very small errors
to accumulate and the actual length of the sequence can vary
slightly from the declared length. (see second example below)}
\item When the distance between the exit of the previous element and the
entrance of the next element is negative and less than $-1\mu m$,
the elements are considered to be overlapping and \madx terminates
with a ``{\tt negative drift length}'' fatal error.
\end{enumerate}
When the sequence is expanded in a \hyperref[sec:use]{\tt USE}
command, \madx also checks that the calculated sequence length
is positive and that the lengths of all elements in the sequence
are positive or zero. A negative sequence length or negative element
length stops the \madx run with a fatal error.
For efficiency reasons \madx imposes an {\bf important restriction}
on element lengths and positions: once a sequence is expanded, the
element positions and lengths are considered as fixed; in order to vary
a position or element length, a re-expansion of the sequence becomes
necessary. The \hyperref[chap:match]{\tt MATCH} command contains a special flag
{\tt VLENGTH} to vary element lengths during matching.
{\bf 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:
sequ: sequence, l = 79;
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;
endm: marker, at = 79.0;
endsequence;
\end{verbatim}
Example of very small drift space being ignored during sequence
expansion:
\begin{verbatim}
QTEST: QUADRUPOLE, L=1.000001;
TEST: SEQUENCE, REFER=centre, L=2.;
QTEST, AT=1.5;
ENDSEQUENCE;
USE, SEQUENCE=TEST;
SURVEY, FILE='test';
\end{verbatim}
The above sequence will expand to a total length of $2.0000005 m$, half
a micron longer than the claimed length of $2 m$, but will not fail.
\bibliographystyle{unsrt}
\printindex
\selectlanguage{english}
\FloatBarrier
\bibliographystyle{plain}
\bibliography{bibliography/converted_to_latex.bib%
}
\end{document}