Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Minor Bmad manual revision. #1182

Merged
merged 1 commit into from
Sep 7, 2024
Merged

Minor Bmad manual revision. #1182

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion bmad/doc/cover-page.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

\begin{flushright}
\large
Revision: August 31, 2024 \\
Revision: September 6, 2024 \\
\end{flushright}

\pdfbookmark[0]{Preamble}{Preamble}
Expand Down
2 changes: 1 addition & 1 deletion bmad/doc/linear-optics.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -426,7 +426,7 @@ \section{Dispersion Calculation}
\begin{equation}
\bfeta(s_2) = \bfM_{21} \, \bfeta(s_1)
\end{equation}
where $\bfM_{21} is the transfer matrix between points $s_1$ and $s_2$.
where $\bfM_{21}$ is the transfer matrix between points $s_1$ and $s_2$.

For an open geometry lattice branch, there are two ways one can imagine
defining the dispersion: Either with respect to changes in energy at the beginning of the machine or
Expand Down
229 changes: 0 additions & 229 deletions bmad/doc/superposition.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -454,232 +454,3 @@ \section{Changing Element Lengths when there is Superposition}
G3: group = \{Q\}, var = \{end_edge\}
\end{example}

%-----------------------------------------------------------------------------
\section{Multipass}
\label{c:multipass}
\index{multipass|hyperbf}

%-----------------------------------------------------------------------------
\section{Multipass Fundamentals}
\label{c:multipass.fund}

\vn{Multipass} lines are a way to handle the bookkeeping when different elements being tracked
through represent the same physical element. For example, consider the case where dual ring colliding
beam machine is to be simulated. In this case the lattice file might look like:
\begin{example}
ring1: line = (..., IR_region, ...)
ring2: line = (..., --IR_region, ...)
IR_region: line = (Q1, ....)
use, ring1, ring2
\end{example}
[The ``--'' construct means go through the line backwards (\sref{s:ele.reverse})] In this case, the
\vn{Q1} element in \vn{ring1} represents the same physical element in \vn{ring2}. Thus the parameters
of both the \vn{Q1}s should be varied in tandem. This can be done automatically using \vn{multipass}.
The use of multipass simplifies lattice and program development since the bookkeeping details are left
to the \bmad bookkeeping routines.

\index{multipass_slave}\index{multipass_lord}
To illustrate how \vn{multipass} works, consider the example of an Energy Recovery Linac (ERL) where
the beam will recirculate back through the LINAC section to recover the energy in the beam before it
is dumped. In \bmad, this situation can simulated by designating the LINAC section as \vn{multipass}.
The lattice file might look like:
\index{expand_lattice}
\begin{example}
RF1: lcavity
linac: line[multipass] = (RF1, ...)
erl: line = (linac, ..., linac)
use, erl
expand_lattice
RF1\B2[phi0_multipass] = 0.5
\end{example}
The line called \vn{linac} is designated as \vn{multipass}. This \vn{linac} line appears twice in
the line \vn{erl} and \vn{erl} is the root line for lattice expansion. The lattice constructed from
\vn{erl} will have two \vn{RF1} elements in the tracking part of the lattice:
\begin{example}
RF1\B1, ..., RF1\B2, ...
\end{example}
Since the two elements are derived from a \vn{multipass} line, they are given unique names by adding
a \vn{{\B}n} suffix. These types of elements are known as \vn{multipass_slave} elements. In
addition, to the \vn{multipass_slave} elements, there is a \vn{multipass_lord} element (that doesn't
get tracked through) called \vn{RF1} in the lord part of the lattice (\sref{s:lord.slave}). Changes
to attributes of the lord \vn{RF1} element will be passed to the slave elements by \bmad's
bookkeeping routines. Assuming that the phase of \vn{RF1\B1} gives acceleration, to make \vn{RF1\B2}
decelerate the \vn{phi0_multipass} attribute of \vn{RF1\B2} is set to 0.5. This is the one attribute
that \bmad's bookkeeping routines will not touch when transferring attribute values from \vn{RF1} to
its slaves. Notice that the \vn{phi0_multipass} attribute had to be set after \vn{expand_lattice}
(\sref{s:expand}) is used to expand the lattice. This is true since \bmad does immediate evaluation and
\vn{RF1\B2} does not exist before the lattice is expanded. \vn{Phi0_multipass} is useful with
relative time tracking \sref{s:rf.time}. However, \vn{phi0_multipass} is ``unphysical'' and is just
a convenient way to shift the phase pass-to-pass through a given cavity. To ``correctly'' simulate
the recirculating beam, absolute time tracking should be used and the length of the lattice from a
cavity back to itself needs to be properly adjusted to get the desired phase advance. See the discussion
in section~\sref{s:rf.time}.

``Intrinsic'' attributes are attributes that must, to make sense physically, be the same for all
slaves of a given multipass lord. The element length is one such example. The following
non-intrinsic attributes can be set in a multipass slave and will not affect the corresponding
attributes in the lord or the other slaves of the lord:
\begin{example}
csr_ds_step num_steps
csr_method ptc_integration_type
ds_step spin_tracking_method
field_calc space_charge_method
integrator_order tracking_method
mat6_calc_method
\end{example}

Multiple elements of the same name in a multipass line are considered
physically distinct. Example:
\begin{example}
m_line: line[multipass] = (A, A, B)
u_line: line = (m_line, m_line)
use, u_line
\end{example}
In this example the tracking part of the lattice is
\begin{example}
A\B1, A\B1, B\B1, A\B2, A\B2, B\B2
\end{example}
In the control section of the lattice there will be two multipass lords called \vn{A} and one called
\vn{B}. [That is, \bmad considers the lattice to have three physically distinct elements.] The first
\vn{A} lord controls the 1\St and 4\Th elements in the tracking part of the lattice and the second
\vn{A} lord controls the 2\Nd and 5\Th elements. If \vn{m_line} was {\em not} marked \vn{multipass},
the tracking part of the lattice would have four \vn{A} and two \vn{B} elements and there would be
no lord elements.

Sublines contained in a multipass line that are themselves not marked multipass act the same as if
the elements of the subline where substituted directly in place of the subline in the containing
line. For example:
\begin{example}
a_line: line = (A)
m_line: line[multipass] = (a_line, a_line, B)
u_line: line = (m_line, m_line)
use, u_line
\end{example}
In this example, \vn{a_line}, which is a subline of the multipass \vn{m_line}, is {\em not}
designated \vn{multipass} and the result is the same as the previous example where \vn{m_line} was
defined to be \vn{(A, A, B)}. That is, there will be three physical elements represented by three
multipass lords.

Multipass lines do not have to be at the same ``level'' in terms of nesting of lines within
lines. Additionally, multipass can be used with line reversal (\sref{s:ele.reverse}). Example:
\begin{example}
m_line: line[multipass] = (A, B)
m2_line: line = (m_line)
P: patch, ...
arc: line = (..., P)
u_line: line = (m_line, arc, --m2_line)
use, u_line
\end{example}
Here the tracking part of the lattice is
\begin{example}
A\B1, B\B1, ..., B\B2 (r), A\B2 (r)
\end{example}
The ``(r)'' here just denotes that the element is reversed and is not part of the name. The lattice
will have a multipass lord \vn{A} that controls the two \vn{A\B n} elements and similarly with
\vn{B}. This lattice represents the case where a particle goes through the m_line in the ``forward''
direction, gets turned around in the \vn{arc} line, and then passes back through \vn{m_line} in the
reverse direction. While it is possible to use reflection ``$-$'' (\sref{s:lines.wo.arg}) instead
of reversal ``$--$'' (\sref{s:ele.reverse}), reflection here does not make physical sense. Needed
here is a reflection patch \vn{P} (\sref{s:patch}) between reversed and unreversed elements.

The procedure for how to group lattice elements into multipass slave groups which represent the same
physical element is as follows. For any given element in the lattice, this element has some line it
came from. Call this line $L_0$. The $L_0$ line in turn may have been contained in some other line
$L_1$, etc. The chain of lines $L_0$, $L_1$, ..., $L_n$ ends at some point and the last (top) line
$L_n$ will be one of the root lines listed in the \vn{use} statement (\sref{s:use}) in the lattice
file. For any given element in the lattice, starting with $L_0$ and proceeding upwards through the
chain, let $L_m$ be the {\em first} line in the chain that is marked as \vn{multipass}. If no such
line exists for a given element, that element will not be a multipass slave. For elements that have
an associated $L_m$ multipass line, all elements that have a common $L_m$ line and have the same
element index when $L_m$ is expanded are put into a multipass slave group (for a given line the
element index with respect to that line is 1 for the first element in the expanded line, the second
element has index 2, etc.). For example, using the example above, the first element of the lattice,
\vn{A\B1}, has the chain:
\begin{example}
m_line, u_line
\end{example}
The last element in the lattice, (\vn{A\B2}), has the chain
\begin{example}
m_line, m2_line, u_line
\end{example}
For both elements the $L_m$ line is \vn{m_line} and both elements are derived from the element with
index 1 with respect to \vn{m_line}. Therefore, the two elements will be slaved together.

As a final example, consider the case where a subline of a multipass line is also marked
\vn{multipass}:
\begin{example}
a_line: line[multipass] = (A)
m_line: line[multipass] = (a_line, a_line, B)
u_line: line = (m_line, m_line)
use, u_line
\end{example}
In this case the tracking part of the lattice will be:
\begin{example}
A\B1, A\B2, B\B1, A\B3, A\B4, B\B2
\end{example}
There will be two lord elements representing the two physically distinct elements \vn{A} and \vn{B}.
The \vn{A} lord element will will control the four \vn{A\B n} elements in the tracking
part of the lattice. The \vn{B} lord will control the two \vn{B\B n} elements in the tracking part
of the lattice.

To simplify the constructed lattice, if the set of lattice elements to slave together only contains
one element, a multipass lord is not constructed. For example:
\begin{example}
m_line: line[multipass] = (A, A, B)
u_line: line = (m_line)
use, u_line
\end{example}
In this example no multipass lords are constructed and the lattice is simply
\begin{example}
A, A, B
\end{example}

It is important to note that the global coordinates (\sref{s:global}) of the slaves of a given
multipass lord are not constrained by \bmad to be the same. It is up to the lattice designer to make
sure that the physical positions of the slaves makes sense (that is, are the same).

%-----------------------------------------------------------------------------
\section{The Reference Energy in a Multipass Line}
\label{s:ref.e.multi}

\index{lcavity}
\index{p0c}\index{e_tot}\index{multipass_ref_energy}
Consider the lattice where the tracking elements are
\begin{example}
A\B1, C, A\B2
\end{example}
where \vn{A\B1} and \vn{A\B2} are multipass slaves of element \vn{A} and \vn{C} is a \vn{lcavity}
element with some finite voltage. In this case, the reference energy calculation (\sref{s:energy})
where the reference energy of an element is inherited from the previous element, assigns differing
reference energies to \vn{A\B1} and \vn{A\B2}. In such a situation, what should be the assigned
reference energy for the multipass lord element \vn{A}? \bmad calculates the lord reference energy
in one of two ways. If, in the lattice file, \vn{e_tot} or \vn{p0c} is set for the multipass lord
element, that setting will be used. Exception: For \vn{em_field}, \vn{lcavity}, and \vn{custom}
elements where the reference energy may change, set \vn{e_tot_start} or \vn{p0c_start} instead of
\vn{e_tot} or \vn{p0c}. If the reference energy (or reference momentum) is not set in the lattice
file, the reference energy of the lord is set equal to the reference energy of the first pass slave
element.

It is important to keep this convention in mind if the normalized field strength (k1, for a
quadrupole, etc.) for the lord element is set in the lattice file. To be physical, the unnormalized
strength (the actual field) has to be the same for all slave elements. \bmad therefore calculates
the unnormalized strength for the lord and sets the slave unnormalized strengths to be equal to the
lord unnormalized strength. After this, the normalized strength for the slaves is calculated. Notice
that the normalized strengths for the slaves will differ from each other. For \vn{sbend} and
\vn{rbend} elements the calculation is a bit trickier. Here the \vn{g} bending strength must be the
same for all slaves since the setting of \vn{g} determines the reference geometry. In this case,
\vn{dg} for each slave is adjusted accordingly so that the total normalized field, \vn{g} +
\vn{dg}, gives the same unnormalized field for all slaves. Note that since the normalized field
is calculated from the unnormalized field for the slaves, the setting of \vn{field_master}
(\sref{s:field.master}) is set to True for all the slaves independent of the setting of
\vn{field_master} for the lord.

To keep track of how the reference energy has been calculated for an element, \bmad sets an internal
element switch called \vn{multipass_ref_energy} which is set to ``\vn{user_set}'' if the energy is
explicitly set in the lattice file and is set to ``\vn{first_pass}'' if the reference energy is
calculated from the standard reference energy calculation of the first pass slave element.

Note: Historically, there was an element parameter \vn{n_ref_pass} that could be set to control the
reference energy. This parameter may be seen in old lattice files but will be ignored.

An example of an ERL lattice with multipass can be found in Section~\sref{s:ex.erl}.