From ec84a1a84f0eb7b833007d36b51613222f7a4182 Mon Sep 17 00:00:00 2001 From: David Sagan Date: Sun, 18 Aug 2024 18:27:57 -0400 Subject: [PATCH] Separate superposition and multipass manual sections. --- bmad/doc/attributes.tex | 6 +- bmad/doc/bmad.tex | 3 +- bmad/doc/charged-tracking.tex | 2 +- bmad/doc/concepts.tex | 18 +- bmad/doc/cover-page.tex | 2 +- bmad/doc/ele-struct.tex | 2 +- bmad/doc/elements.tex | 100 ++++---- bmad/doc/example-program.tex | 2 +- bmad/doc/lat-struct.tex | 14 +- bmad/doc/lattice-file.tex | 16 +- bmad/doc/lines-and-lists.tex | 8 +- bmad/doc/multipass.tex | 235 ++++++++++++++++++ ...se-and-multipass.tex => superposition.tex} | 52 ++-- 13 files changed, 343 insertions(+), 117 deletions(-) create mode 100644 bmad/doc/multipass.tex rename bmad/doc/{superimpose-and-multipass.tex => superposition.tex} (96%) diff --git a/bmad/doc/attributes.tex b/bmad/doc/attributes.tex index d72c44ce15..6bbbc53706 100644 --- a/bmad/doc/attributes.tex +++ b/bmad/doc/attributes.tex @@ -393,7 +393,7 @@ \section{Group, Overlay, and Ramper Element Syntax} \end{example} The energy and momentum are defined at the exit end of the element. For ultra--relativistic particles, and for photons, these two values are the same (\sref{s:phase.space}). Except for -multipass elements (\sref{s:multipass}), \vn{e_tot} and \vn{p0c} are dependent attributes and, +multipass elements (\sref{c:multipass}), \vn{e_tot} and \vn{p0c} are dependent attributes and, except for multipass elements, any setting of \vn{e_tot} and \vn{p0c} in the lattice input file is an error. The value of \vn{e_tot} and \vn{p0c} for an element is calculated by \bmad to be the same as the previous element except for \vn{e_gun}, \vn{lcavity}, \vn{converter}, and \vn{patch} @@ -450,7 +450,7 @@ \section{Group, Overlay, and Ramper Element Syntax} \end{example} For \vn{multipass} elements, the reference energy may be set by specifying one of \vn{e_tot}, -\vn{p0c}, as described in \sref{s:multipass}. +\vn{p0c}, as described in \sref{c:multipass}. For photons, the reference wavelength, \vn{ref_wavelength} is also a dependent attribute calculated from the reference energy. @@ -2803,7 +2803,7 @@ \section{Field Extending Beyond Element Boundary} b1: sbend, l = 2.3, field_overlaps = q1, field_overlaps = s2 \end{example} -Note: When the field overlaps elements that are superimposed (\sref{s:super}), the overlapped +Note: When the field overlaps elements that are superimposed (\sref{c:super}), the overlapped elements must be the \vn{super_lord} elements and never the slaved elements. The field, when \vn{field_calc} (\sref{s:integ}) is set to \vn{bmad_standard}, never extends beyond diff --git a/bmad/doc/bmad.tex b/bmad/doc/bmad.tex index 4f672694dd..4a968fc354 100644 --- a/bmad/doc/bmad.tex +++ b/bmad/doc/bmad.tex @@ -129,7 +129,8 @@ \part{Language Reference} \include{attributes} \include{methods} \include{lines-and-lists} -\include{superimpose-and-multipass} +\include{superposition} +\include{multipass} \include{param-statements} \include{param-structs} \include{beam-init} diff --git a/bmad/doc/charged-tracking.tex b/bmad/doc/charged-tracking.tex index 6b67d3c460..d2451e4301 100644 --- a/bmad/doc/charged-tracking.tex +++ b/bmad/doc/charged-tracking.tex @@ -54,7 +54,7 @@ \section{Relative Versus Absolute Time Tracking} t_\text{eff}(s) = t(s) - t_0(s_\text{ent}) \end{equation} $t_0(s_\text{ent})$, by definition, equal to the time of the reference particle at the entrance end -of the element. With multipass \sref{s:multipass}, $t_0(s_\text{ent})$ is set by the time of the +of the element. With multipass \sref{c:multipass}, $t_0(s_\text{ent})$ is set by the time of the reference particle at the entrance end of the element on the first pass. For absolute time tracking, it is important to keep in mind that $t_0(s_\text{ent})$ is a property of the element independent of how tracking is done. Thus, if a particle goes through a particular element multiple times, the diff --git a/bmad/doc/concepts.tex b/bmad/doc/concepts.tex index d5741f3d50..77940f8edc 100644 --- a/bmad/doc/concepts.tex +++ b/bmad/doc/concepts.tex @@ -71,7 +71,7 @@ \section{Lattice} rings will generally have two \vn{root} branches, one for each ring. The \vn{use} statement (\sref{s:use}) in a lattice file will list the \vn{root} \vn{branches} of a lattice. To connect together lattice elements that are physically shared between branches, for example, the interaction -region in colliding beam machines, \vn{multipass} lines (\sref{s:multipass}) can be used. +region in colliding beam machines, \vn{multipass} lines (\sref{c:multipass}) can be used. The root branches of a lattice are defined by the \vn{use} (\sref{s:use}) statement. To further define such things as dump lines, x-ray beam lines, transfer lines, etc., that branch off from a @@ -139,7 +139,7 @@ \section{Lord and Slave Elements} The other class of \vn{lord} elements embody the separation of the physical element from the track that a particle takes when it passes through the element. There are two types -An example will make this clear. \vn{Superposition} (\sref{s:super}) is the ability to overlap +An example will make this clear. \vn{Superposition} (\sref{c:super}) is the ability to overlap lattice elements spatially. \fig{f:super.ip} shows an example which is a greatly simplified version of the IR region of Cornell's CESR storage ring when CESR was an e+/e-- collider. As shown in \fig{f:super.ip}A, two quadrupoles named \vn{q1w} and \vn{q1e} are partially inside and partially @@ -163,7 +163,7 @@ \section{Lord and Slave Elements} that represents the part of \vn{q1e} outside of the solenoid. The next element is a combination solenoid/quadrupole, called a \vn{sol_quad}, that represents the part of \vn{q1e} inside \vn{cleo}, etc. The other branch section that Bmad creates is called the \vn{lord section} This section -contain the undivided ``physical'' \vn{super_lord} elements (\sref{s:super}) which, in this case are +contain the undivided ``physical'' \vn{super_lord} elements (\sref{c:super}) which, in this case are \vn{q1e}, \vn{q1w}, and \vn{cleo}. Pointers are created between the lords and their \vn{super_slave} elements in the tracking section so that changes in parameters of the lord elements can be transferred to their corresponding slaves. @@ -173,7 +173,7 @@ \section{Lord and Slave Elements} particles through comes when a particle passes through the same physical element multiple times such as in an Energy Recovery Linac or where different beams pass through the same element such as in an interaction region. In this case, \vn{multipass_lords} representing the physical elements and -\vn{multipass_slaves} elements which are used for tracking can be defined (\sref{s:multipass}). +\vn{multipass_slaves} elements which are used for tracking can be defined (\sref{c:multipass}). Superposition and multipass can be combined in situations where there are overlapping fields in elements where the particle passes through @@ -189,14 +189,14 @@ \section{Lord and Slave Elements} A \vn{girder_lord} element is a \vn{girder} element (\sref{s:girder}). \item[multipass_lord]\Newline \vn{multipass_lord} elements are created when -multipass lines are present (\sref{s:multipass}). +multipass lines are present (\sref{c:multipass}). \item[overlay_lord]\Newline An \vn{overlay_lord} is an \vn{overlay} element (\sref{s:overlay}). \item[group_lord]\Newline A \vn{group_lord} is a \vn{group} element (\sref{s:group}). \item[super_lord]\Newline A \vn{super_lord} element is created when elements are -superimposed on top of other elements (\sref{s:super}). +superimposed on top of other elements (\sref{c:super}). \item[not_a_lord]\Newline This element does not control anything. \end{description} @@ -216,14 +216,14 @@ \section{Lord and Slave Elements} \begin{description} \item[multipass_slave]\Newline A \vn{multipass_slave} element is the slave of a \vn{multipass_lord} -(\sref{s:multipass}). +(\sref{c:multipass}). \item[slice_slave]\Newline A \vn{slice_slave} element represents a longitudinal slice of another element. Slice elements are not part of the lattice but rather are created on-the-fly when, for example, a program needs to track part way through an element. \item[super_slave]\Newline A \vn{super_slave} element is an element in the tracking part of the branch that -has one or more \vn{super_lord} lords (\sref{s:super}). +has one or more \vn{super_lord} lords (\sref{c:super}). \item[minor_slave]\Newline \vn{minor_slave} elements are elements that are not \vn{slice_slave}s and are only controlled by \vn{minor} lords (\vn{overlay_lord}s, \vn{group_lord}s, or \vn{girder_lord}s). @@ -242,5 +242,5 @@ \section{Lord and Slave Elements} call a \vn{fibre}. [Actually, PTC has two structures for the physical element, \vn{element} and \vn{elementp}. The latter being the ``polymorph'' version.] This \vn{element} and \vn{fibre} combination corresponds to \bmad \vn{multipass_lord} and \vn{multipass_slave} elements. PTC does not -handle overlapping fields as \bmad does with \vn{superposition} (\sref{s:super}). +handle overlapping fields as \bmad does with \vn{superposition} (\sref{c:super}). diff --git a/bmad/doc/cover-page.tex b/bmad/doc/cover-page.tex index 84b9be61a3..9a3497e1cf 100644 --- a/bmad/doc/cover-page.tex +++ b/bmad/doc/cover-page.tex @@ -3,7 +3,7 @@ \begin{flushright} \large - Revision: August 13, 2024 \\ + Revision: August 18, 2024 \\ \end{flushright} \pdfbookmark[0]{Preamble}{Preamble} diff --git a/bmad/doc/ele-struct.tex b/bmad/doc/ele-struct.tex index 1a0b7299ff..435ee0e95e 100644 --- a/bmad/doc/ele-struct.tex +++ b/bmad/doc/ele-struct.tex @@ -828,7 +828,7 @@ \section{Custom and General Use Attributes} call set_custom_attribute_name ('QUADRUPOLE::ERROR_CURRENT', err_flag) \end{example} -Note: When there is a superposition (\sref{s:super}), the \vn{super_slave} elements that are formed +Note: When there is a superposition (\sref{c:super}), the \vn{super_slave} elements that are formed do {\em not} have any custom attributes assigned to them even when their \vn{super_lord} elements have custom attributes. This is done since the \bmad bookkeeping routines are not able to handle the situation where a \vn{super_slave} element has multiple \vn{super_lord} elements and thus the custom diff --git a/bmad/doc/elements.tex b/bmad/doc/elements.tex index bd08a38aa5..01c6dfa652 100644 --- a/bmad/doc/elements.tex +++ b/bmad/doc/elements.tex @@ -112,7 +112,7 @@ \section{AB_Multipole} a$n$, b$n$ multipoles & \ref{s:multip} & Length & \ref{s:l} \\ Aperture limits & \ref{s:limit} & Offsets \& tilt & \ref{s:offset} \\ Chamber wall & \ref{s:wall} & Reference energy & \ref{s:energy} \\ - Custom Attributes & \ref{s:cust.att} & Superposition & \ref{s:super} \\ + Custom Attributes & \ref{s:cust.att} & Superposition & \ref{c:super} \\ Description strings & \ref{s:alias} & Tracking \& transfer map & \ref{c:methods} \\ Is_on & \ref{s:is.on} & & \\ \bottomrule @@ -126,7 +126,7 @@ \section{AB_Multipole} affects the longitudinal position of the next element but does not affect any tracking or transfer map calculations. The \vn{x_pitch} and \vn{y_pitch} attributes are not used in tracking. -When an \vn{ab_multipole} is superimposed (\sref{s:super}) on a lattice, it is treated as a zero +When an \vn{ab_multipole} is superimposed (\sref{c:super}) on a lattice, it is treated as a zero length element and in this case it is an error for the length of the \vn{ab_multipole} to be set to a nonzero value. @@ -157,7 +157,7 @@ \section{AC_Kicker} Custom Attributes & \ref{s:cust.att} & Mag \& Elec multipoles & \ref{s:multip} \\ Description strings & \ref{s:alias} & Offsets, pitches \& tilt & \ref{s:offset} \\ Field Maps & \ref{s:fieldmap} & Reference energy & \ref{s:energy} \\ - Fringe Fields & \ref{s:fringe} & Superposition & \ref{s:super} \\ + Fringe Fields & \ref{s:fringe} & Superposition & \ref{c:super} \\ Hkick \& Vkick & \ref{s:kick} & Symplectify & \ref{s:symp} \\ Integration settings & \ref{s:integ} & Tracking \& transfer map & \ref{c:methods} \\ \bottomrule @@ -279,7 +279,7 @@ \section{BeamBeam} Aperture limits & \ref{s:limit} & Is_on & \ref{s:is.on} \\ Chamber wall & \ref{s:wall} & Offsets, pitches \& tilt & \ref{s:offset} \\ Custom Attributes & \ref{s:cust.att} & Reference energy & \ref{s:energy} \\ - Description strings & \ref{s:alias} & Superposition & \ref{s:super} \\ + Description strings & \ref{s:alias} & Superposition & \ref{c:super} \\ Is_on & \ref{s:is.on} & Tracking \& transfer map & \ref{c:methods} \\ \bottomrule \end{tabular} @@ -478,7 +478,7 @@ \section{Bends: Rbend and Sbend} Chamber wall & \ref{s:wall} & Offsets, pitches \& tilt & \ref{s:offset} \\ Custom Attributes & \ref{s:cust.att} & Overlapping Fields & \ref{s:overlap} \\ Description strings & \ref{s:alias} & Reference energy & \ref{s:energy} \\ - Fringe Fields & \ref{s:fringe} & Superposition & \ref{s:super} \\ + Fringe Fields & \ref{s:fringe} & Superposition & \ref{c:super} \\ Hkick \& Vkick & \ref{s:kick} & Symplectify & \ref{s:symp} \\ Is_on & \ref{s:is.on} & Field Maps & \ref{s:fieldmap} \\ Integration settings & \ref{s:integ} & Tracking \& transfer map & \ref{c:methods} \\ @@ -920,7 +920,7 @@ \section{Collimators: Ecollimator and Rcollimator} Aperture limits & \ref{s:limit} & Offsets, Pitches \& Tilt & \ref{s:offset} \\ Chamber wall & \ref{s:wall} & Overlapping Fields & \ref{s:overlap} \\ Custom Attributes & \ref{s:cust.att} & Reference energy & \ref{s:energy} \\ - Description strings & \ref{s:alias} & Superposition & \ref{s:super} \\ + Description strings & \ref{s:alias} & Superposition & \ref{c:super} \\ Hkick \& Vkick & \ref{s:kick} & Symplectify & \ref{s:symp} \\ Integration settings & \ref{s:integ} & Field Maps & \ref{s:fieldmap} \\ Is_on & \ref{s:is.on} & Tracking \& transfer map & \ref{c:methods} \\ @@ -989,7 +989,7 @@ \section{Converter} Chamber wall & \ref{s:wall} & Length & \ref{s:l} \\ Custom Attributes & \ref{s:cust.att} & Offsets, pitches \& tilt & \ref{s:offset} \\ Description strings & \ref{s:alias} & Reference energy & \ref{s:energy} \\ - Integration settings & \ref{s:integ} & Superposition & \ref{s:super} \\ + Integration settings & \ref{s:integ} & Superposition & \ref{c:super} \\ & & Tracking \& transfer map & \ref{c:methods} \\ \bottomrule \end{tabular} @@ -1164,7 +1164,7 @@ \section{Crab_Cavity} Aperture limits & \ref{s:limit} & Length & \ref{s:l} \\ Chamber wall & \ref{s:wall} & Offsets, pitches \& tilt & \ref{s:offset} \\ Custom Attributes & \ref{s:cust.att} & Reference energy & \ref{s:energy} \\ - Description strings & \ref{s:alias} & Superposition & \ref{s:super} \\ + Description strings & \ref{s:alias} & Superposition & \ref{c:super} \\ Hkick \& Vkick & \ref{s:kick} & Symplectify & \ref{s:symp} \\ Integration settings & \ref{s:integ} & Field Maps & \ref{s:fieldmap} \\ Is_on & \ref{s:is.on} & Tracking \& transfer map & \ref{c:methods} \\ @@ -1182,7 +1182,7 @@ \section{Crab_Cavity} gradient = ! Accelerating gradient (V/m). phi0 = ! Phase (rad/2\(\pi\)) of the reference particle with ! respect to the RF. phi0 = 0 is on crest. - phi0_multipass = ! Phase (rad/2\(\pi\)) with respect to a multipass lord (\sref{s:multipass}). + phi0_multipass = ! Phase (rad/2\(\pi\)) with respect to a multipass lord (\sref{c:multipass}). rf_frequency = ! RF frequency (Hz). harmon = ! Harmonic number harmon_master = ! Is harmon or rf_frequency the dependent var with ref energy changes? @@ -1474,7 +1474,7 @@ \section{Custom} Chamber wall & \ref{s:wall} & Length & \ref{s:l} \\ Custom Attributes & \ref{s:cust.att} & Offsets, pitches \& tilt & \ref{s:offset} \\ Description strings & \ref{s:alias} & Reference energy & \ref{s:energy} \\ - Field Maps & \ref{s:fieldmap} & Superposition & \ref{s:super} \\ + Field Maps & \ref{s:fieldmap} & Superposition & \ref{c:super} \\ Fringe fields & \ref{s:fringe} & Symplectify & \ref{s:symp} \\ Integration settings & \ref{s:integ} & Tracking \& transfer map & \ref{c:methods} \\ \bottomrule @@ -1534,7 +1534,7 @@ \section{Detector} {\sl Attribute Class} & Section & {\sl Attribute Class} & Section \\ \midrule Aperture limits & \ref{s:limit} & Offsets, pitches \& tilt & \ref{s:offset} \\ Chamber Wall & \ref{s:wall} & Reference energy & \ref{s:energy} \\ - Custom Attributes & \ref{s:cust.att} & Superposition & \ref{s:super} \\ + Custom Attributes & \ref{s:cust.att} & Superposition & \ref{c:super} \\ Description strings & \ref{s:alias} & Tracking \& transfer map & \ref{c:methods} \\ Detector Geometry & \ref{s:surf.grid} & & \\ \bottomrule @@ -1699,7 +1699,7 @@ \section{Drift} space, use a \vn{pipe} element instead of a \vn{drift} [a wall for a drift is not allowed due to the way drifts are treated with superposition. That is, drifts ``disappear'' when superimposed -upon. (\sref{s:super})]. +upon. (\sref{c:super})]. \newpage @@ -1826,7 +1826,7 @@ \section{ELseparator} Chamber wall & \ref{s:wall} & Offsets, pitches \& tilt & \ref{s:offset} \\ Custom Attributes & \ref{s:cust.att} & Overlapping Fields & \ref{s:overlap} \\ Description strings & \ref{s:alias} & Reference energy & \ref{s:energy} \\ - Fringe Fields & \ref{s:fringe} & Superposition & \ref{s:super} \\ + Fringe Fields & \ref{s:fringe} & Superposition & \ref{c:super} \\ Hkick \& Vkick & \ref{s:kick} & Symplectify & \ref{s:symp} \\ Integration settings & \ref{s:integ} & Field Maps & \ref{s:fieldmap} \\ Is_on & \ref{s:is.on} & Tracking \& transfer map & \ref{c:methods} \\ @@ -1884,7 +1884,7 @@ \section{EM_Field} Chamber wall & \ref{s:wall} & Length & \ref{s:l} \\ Custom Attributes & \ref{s:cust.att} & Offsets, pitches \& tilt & \ref{s:offset} \\ Description strings & \ref{s:alias} & Reference energy & \ref{s:energy} \\ - Field Maps & \ref{s:fieldmap} & Superposition & \ref{s:super} \\ + Field Maps & \ref{s:fieldmap} & Superposition & \ref{c:super} \\ Hkick \& Vkick & \ref{s:kick} & Symplectify & \ref{s:symp} \\ Integration settings & \ref{s:integ} & Tracking \& transfer map & \ref{c:methods} \\ \bottomrule @@ -1912,7 +1912,7 @@ \section{EM_Field} is set to \vn{False}, the reference energy at the exit end is calculated like it is in a \vn{lcavity} or \vn{e_gun} element. -Note: \vn{em_field} elements will be created when elements are superimposed (\sref{s:super}) and +Note: \vn{em_field} elements will be created when elements are superimposed (\sref{c:super}) and there is no other suitable element class. \newpage @@ -2003,7 +2003,7 @@ \section{Fiducial} \begin{tabular}{llll} \toprule {\sl Attribute Class} & Section & {\sl Attribute Class} & Section \\ \midrule Aperture limits & \ref{s:limit} & Reference energy & \ref{s:energy} \\ - Custom Attributes & \ref{s:cust.att} & Superposition & \ref{s:super} \\ + Custom Attributes & \ref{s:cust.att} & Superposition & \ref{c:super} \\ Description strings & \ref{s:alias} & Tracking \& transfer map & \ref{c:methods} \\ \bottomrule \end{tabular} @@ -2120,7 +2120,7 @@ \section{Floor_Shift} \begin{tabular}{llll} \toprule {\sl Attribute Class} & Section & {\sl Attribute Class} & Section \\ \midrule Aperture limits & \ref{s:limit} & Reference energy & \ref{s:energy} \\ - Custom Attributes & \ref{s:cust.att} & Superposition & \ref{s:super} \\ + Custom Attributes & \ref{s:cust.att} & Superposition & \ref{c:super} \\ Description strings & \ref{s:alias} & Tracking \& transfer map & \ref{c:methods} \\ Length & \ref{s:l} & & \\ \bottomrule @@ -2222,7 +2222,7 @@ \section{Foil} {\sl Attribute Class} & Section & {\sl Attribute Class} & Section \\ \midrule Aperture limits & \ref{s:limit} & Offsets, pitches \& tilt & \ref{s:offset} \\ Custom Attributes & \ref{s:cust.att} & Reference energy & \ref{s:energy} \\ - Description strings & \ref{s:alias} & Superposition & \ref{s:super} \\ + Description strings & \ref{s:alias} & Superposition & \ref{c:super} \\ Integration settings & \ref{s:integ} & Tracking \& transfer map & \ref{c:methods} \\ Is_on & \ref{s:is.on} & & \\ \bottomrule @@ -2387,7 +2387,7 @@ \section{Fork and Photon_Fork} {\sl Attribute Class} & Section & {\sl Attribute Class} & Section \\ \midrule Aperture limits & \ref{s:limit} & Length & \ref{s:l} \\ Chamber wall & \ref{s:wall} & Reference energy & \ref{s:energy} \\ - Custom Attributes & \ref{s:cust.att} & Superposition & \ref{s:super} \\ + Custom Attributes & \ref{s:cust.att} & Superposition & \ref{c:super} \\ Description strings & \ref{s:alias} & Tracking \& transfer map & \ref{c:methods} \\ Is_on & \ref{s:is.on} & & \\ \bottomrule @@ -2640,8 +2640,8 @@ \section{Girder} g2: girder = \{g1\} ! g2 must come after g1! \end{example} -A \vn{girder} may not directly support \vn{multipass_slave} (\sref{s:multipass}) or \vn{super_slave} -(\sref{s:super}) elements. Rather, a \vn{girder} may support the corresponding lord elements. +A \vn{girder} may not directly support \vn{multipass_slave} (\sref{c:multipass}) or \vn{super_slave} +(\sref{c:super}) elements. Rather, a \vn{girder} may support the corresponding lord elements. The reference frame from which the girder's offset, pitch, and tilt attributes (\sref{s:offset}) are measured is constructed as follows: A reference frame, called the ``\vn{origin}'' reference frame @@ -2986,7 +2986,7 @@ \section{Instrument, Monitor, and Pipe} \index{pipe|hyperbf} Essentially \bmad treats \vn{instrument}, \vn{monitor}, and \vn{pipe} elements like a -\vn{drift}. There is a difference, however, when superimposing elements (\sref{s:super}). For +\vn{drift}. There is a difference, however, when superimposing elements (\sref{c:super}). For example, a \vn{quadrupole} superimposed on top of a \vn{drift} results in a free \vn{quadrupole} element in the tracking part of the lattice and no lord elements are created. On the other hand, a \vn{quadrupole} superimposed on top of a \vn{monitor} results in a \vn{quadrupole} element in the @@ -3005,7 +3005,7 @@ \section{Instrument, Monitor, and Pipe} Chamber wall & \ref{s:wall} & Length & \ref{s:l} \\ Custom Attributes & \ref{s:cust.att} & Offsets, pitches \& tilt & \ref{s:offset} \\ Description strings & \ref{s:alias} & Reference energy & \ref{s:energy} \\ - Hkick \& Vkick & \ref{s:kick} & Superposition & \ref{s:super} \\ + Hkick \& Vkick & \ref{s:kick} & Superposition & \ref{c:super} \\ Instrumental variables & \ref{s:meas.attrib} & Symplectify & \ref{s:symp} \\ Integration settings & \ref{s:integ} & Tracking \& transfer map & \ref{c:methods} \\ \bottomrule @@ -3049,7 +3049,7 @@ \section{Kickers: Hkicker and Vkicker} Custom Attributes & \ref{s:cust.att} & Mag \& Elec multipoles & \ref{s:multip} \\ Description strings & \ref{s:alias} & Offsets, pitches \& tilt & \ref{s:offset} \\ Field Maps & \ref{s:fieldmap} & Reference energy & \ref{s:energy} \\ - Fringe Fields & \ref{s:fringe} & Superposition & \ref{s:super} \\ + Fringe Fields & \ref{s:fringe} & Superposition & \ref{c:super} \\ Hkick \& Vkick & \ref{s:kick} & Symplectify & \ref{s:symp} \\ Integration settings & \ref{s:integ} & Tracking \& transfer map & \ref{c:methods} \\ \bottomrule @@ -3091,7 +3091,7 @@ \section{Kicker} Aperture limits & \ref{s:limit} & Offsets, pitches \& tilt & \ref{s:offset} \\ Chamber wall & \ref{s:wall} & Overlapping Fields & \ref{s:overlap} \\ Custom Attributes & \ref{s:cust.att} & Reference energy & \ref{s:energy} \\ - Description strings & \ref{s:alias} & Superposition & \ref{s:super} \\ + Description strings & \ref{s:alias} & Superposition & \ref{c:super} \\ Fringe Fields & \ref{s:fringe} & Symplectify & \ref{s:symp} \\ Hkick \& Vkick & \ref{s:kick} & Field Maps & \ref{s:fieldmap} \\ Integration settings & \ref{s:integ} & Tracking \& transfer map & \ref{c:methods} \\ @@ -3127,7 +3127,7 @@ \section{Lcavity} Chamber wall & \ref{s:wall} & Overlapping Fields & \ref{s:overlap} \\ Custom Attributes & \ref{s:cust.att} & Reference energy & \ref{s:energy} \\ Description strings & \ref{s:alias} & RF Couplers & \ref{s:rf.coupler} \\ - Field autoscaling & \ref{s:autoscale} & Superposition & \ref{s:super} \\ + Field autoscaling & \ref{s:autoscale} & Superposition & \ref{c:super} \\ Fringe Fields & \ref{s:fringe} & Symplectify & \ref{s:symp} \\ Hkick \& Vkick & \ref{s:kick} & Field Maps & \ref{s:fieldmap} \\ Integration settings & \ref{s:integ} & Tracking \& transfer map & \ref{c:methods} \\ @@ -3151,7 +3151,7 @@ \section{Lcavity} phi0 = ! Phase (rad/2\(\pi\)) of the reference particle with ! respect to the RF. phi0 = 0 is on crest. phi0_autoscale ! Set by Bmad when autoscaling is turned on \sref{s:autoscale}. - phi0_multipass = ! Phase (rad/2\(\pi\)) with respect to a multipass lord (\sref{s:multipass}). + phi0_multipass = ! Phase (rad/2\(\pi\)) with respect to a multipass lord (\sref{c:multipass}). phi0_err = ! Phase error (rad/2\(\pi\)) e_loss = ! Loss parameter for short range wakefields (V/Coul). rf_frequency = ! RF frequency (Hz). @@ -3195,7 +3195,7 @@ \section{Lcavity} unity independent of the type of particle tracked. \vn{phi0_multipass} is only to be used with multipass to shift the phase of the cavity from pass to -pass. See \sref{s:multipass}. +pass. See \sref{c:multipass}. \vn{phi0_autoscale} and \vn{field_autoscale} are calculated by \bmad's auto-scale module. See Section~\sref{s:autoscale} for more details. Autoscaling can be toggled on/off by using the @@ -3299,7 +3299,7 @@ \section{Marker} Aperture limits & \ref{s:limit} & Is_on & \ref{s:is.on} \\ Chamber wall & \ref{s:wall} & Offsets \& tilt & \ref{s:offset} \\ Custom Attributes & \ref{s:cust.att} & Reference energy & \ref{s:energy} \\ - Description strings & \ref{s:alias} & Superposition & \ref{s:super} \\ + Description strings & \ref{s:alias} & Superposition & \ref{c:super} \\ Instrumental variables & \ref{s:meas.attrib} & Tracking \& transfer map & \ref{c:methods} \\ \bottomrule \end{tabular} @@ -3343,7 +3343,7 @@ \section{Mask} {\sl Attribute Class} & Section & {\sl Attribute Class} & Section \\ \midrule Aperture limits & \ref{s:limit} & Offsets, pitches \& tilt & \ref{s:offset} \\ Custom Attributes & \ref{s:cust.att} & Reference energy & \ref{s:energy} \\ - Description strings & \ref{s:alias} & Superposition & \ref{s:super} \\ + Description strings & \ref{s:alias} & Superposition & \ref{c:super} \\ Is_on & \ref{s:is.on} & Tracking \& transfer map & \ref{c:methods} \\ \bottomrule \end{tabular} @@ -3428,7 +3428,7 @@ \section{Match} {\sl Attribute Class} & Section & {\sl Attribute Class} & Section \\ \midrule Aperture limits & \ref{s:limit} & Length & \ref{s:l} \\ Custom Attributes & \ref{s:cust.att} & Reference energy & \ref{s:energy} \\ - Description strings & \ref{s:alias} & Superposition & \ref{s:super} \\ + Description strings & \ref{s:alias} & Superposition & \ref{c:super} \\ Is_on & \ref{s:is.on} & & \\ \bottomrule \end{tabular} @@ -3646,7 +3646,7 @@ \section{Mirror} \begin{tabular}{llll} \toprule {\sl Attribute Class} & Section & {\sl Attribute Class} & Section \\ \midrule Aperture limits & \ref{s:limit} & Reflection tables & \ref{s:reflect} \\ - Custom Attributes & \ref{s:cust.att} & Superposition & \ref{s:super} \\ + Custom Attributes & \ref{s:cust.att} & Superposition & \ref{c:super} \\ Description strings & \ref{s:alias} & Surface Properties & \ref{s:surface} \\ Offsets, pitches \& tilt & \ref{s:offset} & Tracking \& transfer map & \ref{c:methods} \\ Reference energy & \ref{s:energy} & & \\ @@ -3708,7 +3708,7 @@ \section{Multipole} next element but does not affect any tracking or transfer map calculations. -When an \vn{multipole} is superimposed (\sref{s:super}) on a lattice, it is +When an \vn{multipole} is superimposed (\sref{c:super}) on a lattice, it is treated as a zero length element and in this case it is an error for the length of the \vn{multipole} to be set to a nonzero value. @@ -3738,7 +3738,7 @@ \section{Multilayer_mirror} {\sl Attribute Class} & Section & {\sl Attribute Class} & Section \\ \midrule Aperture limits & \ref{s:limit} & Symplectify & \ref{s:symp} \\ Custom Attributes & \ref{s:cust.att} & Offsets, pitches \& tilt & \ref{s:offset} \\ - Description strings & \ref{s:alias} & Superposition & \ref{s:super} \\ + Description strings & \ref{s:alias} & Superposition & \ref{c:super} \\ Reference energy & \ref{s:energy} & Tracking \& transfer map & \ref{c:methods} \\ Surface Properties & \ref{s:surface} & & \\ \bottomrule @@ -3801,7 +3801,7 @@ \section{Null_Ele} A \vn{null_ele} is a special type of element. It is like a \vn{marker} but it has the property that when the lattice is expanded (\sref{s:lines.wo.arg}) all \vn{null_ele} elements are removed. The primary use of a \vn{null_ele} is in computer generated lattices where it can be used to serve as a -reference point for element superpositions (\sref{s:super}). Another use is to split an element +reference point for element superpositions (\sref{c:super}). Another use is to split an element using superposition while avoiding having to add a marker element to the lattice. Example: \begin{example} N: null_ele, superimpose, ref = quadrupole::* @@ -3831,7 +3831,7 @@ \section{Octupole} Chamber wall & \ref{s:wall} & Offsets, pitches \& tilt & \ref{s:offset} \\ Custom Attributes & \ref{s:cust.att} & Overlapping Fields & \ref{s:overlap} \\ Description strings & \ref{s:alias} & Reference energy & \ref{s:energy} \\ - Fringe Fields & \ref{s:fringe} & Superposition & \ref{s:super} \\ + Fringe Fields & \ref{s:fringe} & Superposition & \ref{c:super} \\ Hkick \& Vkick & \ref{s:kick} & Symplectify & \ref{s:symp} \\ Integration settings & \ref{s:integ} & Field Maps & \ref{s:fieldmap} \\ Is_on & \ref{s:is.on} & Tracking \& transfer map & \ref{c:methods} \\ @@ -4002,7 +4002,7 @@ \section{Patch} {\sl Attribute Class} & Section & {\sl Attribute Class} & Section \\ \midrule Aperture limits & \ref{s:limit} & Offsets, pitches \& tilt & \ref{s:offset} \\ Chamber wall & \ref{s:wall} & Reference energy & \ref{s:energy} \\ - Custom Attributes & \ref{s:cust.att} & Superposition & \ref{s:super} \\ + Custom Attributes & \ref{s:cust.att} & Superposition & \ref{c:super} \\ Description strings & \ref{s:alias} & Tracking \& transfer map & \ref{c:methods} \\ Length & \ref{s:l} & & \\ \bottomrule @@ -4062,7 +4062,7 @@ \section{Patch} The coordinates of the lattice element downstream of a \vn{flexible} \vn{patch} can be computed if there is a \vn{fiducial} element (\sref{s:fiducial}) somewhere downstream or if there is a -\vn{multipass_slave} (\sref{s:multipass}) element which is just downstream of the \vn{patch} or at +\vn{multipass_slave} (\sref{c:multipass}) element which is just downstream of the \vn{patch} or at most separated by zero length elements from the \vn{patch}. In this latter case, the \vn{multipass_slave} must represent an $N$\Th pass slave with $N$ greater than 1. This works since the first pass slave will be upstream of the \vn{patch} and so the first pass slave will have its @@ -4444,7 +4444,7 @@ \section{Quadrupole} Chamber wall & \ref{s:wall} & Offsets, pitches \& tilt & \ref{s:offset} \\ Description strings & \ref{s:alias} & Overlapping Fields & \ref{s:overlap} \\ Fringe Fields & \ref{s:fringe} & Reference energy & \ref{s:energy} \\ - Hkick \& Vkick & \ref{s:kick} & Superposition & \ref{s:super} \\ + Hkick \& Vkick & \ref{s:kick} & Superposition & \ref{c:super} \\ Integration settings & \ref{s:integ} & Symplectify & \ref{s:symp} \\ Is_on & \ref{s:is.on} & Field Maps & \ref{s:fieldmap} \\ Length & \ref{s:l} & Tracking \& transfer map & \ref{c:methods} \\ @@ -4610,7 +4610,7 @@ \section{RF_bend} Aperture limits & \ref{s:limit} & Offsets, pitches \& tilt & \ref{s:offset} \\ Chamber wall & \ref{s:wall} & Overlapping Fields & \ref{s:overlap} \\ Custom Attributes & \ref{s:cust.att} & Reference energy & \ref{s:energy} \\ - Description strings & \ref{s:alias} & Superposition & \ref{s:super} \\ + Description strings & \ref{s:alias} & Superposition & \ref{c:super} \\ Symplectify & \ref{s:symp} & Field Maps & \ref{s:fieldmap} \\ Integration settings & \ref{s:integ} & Tracking \& transfer map & \ref{c:methods} \\ Is_on & \ref{s:is.on} & Wakes & \ref{s:wakes} \\ @@ -4673,7 +4673,7 @@ \section{RFcavity} Chamber wall & \ref{s:wall} & Overlapping Fields & \ref{s:overlap} \\ Custom Attributes & \ref{s:cust.att} & Reference energy & \ref{s:energy} \\ Description strings & \ref{s:alias} & RF Couplers & \ref{s:rf.coupler} \\ - Field autoscaling & \ref{s:autoscale} & Superposition & \ref{s:super} \\ + Field autoscaling & \ref{s:autoscale} & Superposition & \ref{c:super} \\ Fringe Fields & \ref{s:fringe} & Symplectify & \ref{s:symp} \\ Hkick \& Vkick & \ref{s:kick} & Field Maps & \ref{s:fieldmap} \\ Integration settings & \ref{s:integ} & Tracking \& transfer map & \ref{c:methods} \\ @@ -4725,7 +4725,7 @@ \section{RFcavity} \end{example} \vn{phi0_multipass} is only to be used to shift the phase with respect to a \vn{multipass} lord. See -\sref{s:multipass}. \vn{e_charge} is the magnitude of the charge on an electron +\sref{c:multipass}. \vn{e_charge} is the magnitude of the charge on an electron (Table~\ref{t:constants}). Notice that the energy kick is independent of the sign of the charge of the particle @@ -4798,7 +4798,7 @@ \section{Sad_Mult} a$n$, b$n$ multipoles & \ref{s:multip} & Length & \ref{s:l} \\ Aperture limits & \ref{s:limit} & Offsets, pitches \& tilt & \ref{s:offset} \\ Chamber wall & \ref{s:wall} & Reference energy & \ref{s:energy} \\ - Custom Attributes & \ref{s:cust.att} & Superposition & \ref{s:super} \\ + Custom Attributes & \ref{s:cust.att} & Superposition & \ref{c:super} \\ Description strings & \ref{s:alias} & Tracking \& transfer map & \ref{c:methods} \\ Fringe Fields & \ref{s:fringe} & & \\ \bottomrule @@ -4912,7 +4912,7 @@ \section{Sample} Aperture limits & \ref{s:limit} & Offsets, pitches \& tilt & \ref{s:offset} \\ \midrule Chamber wall & \ref{s:wall} & Reference energy & \ref{s:energy} \\ Custom Attributes & \ref{s:cust.att} & Surface Properties & \ref{s:surface} \\ - Description strings & \ref{s:alias} & Superposition & \ref{s:super} \\ + Description strings & \ref{s:alias} & Superposition & \ref{c:super} \\ Integration settings & \ref{s:integ} & Tracking \& transfer map & \ref{c:methods} \\ Length & \ref{s:l} & & \\ \bottomrule @@ -4968,7 +4968,7 @@ \section{Sextupole} Chamber wall & \ref{s:wall} & Offsets, pitches \& tilt & \ref{s:offset} \\ Custom Attributes & \ref{s:cust.att} & Overlapping Fields & \ref{s:overlap} \\ Description strings & \ref{s:alias} & Reference energy & \ref{s:energy} \\ - Fringe Fields & \ref{s:fringe} & Superposition & \ref{s:super} \\ + Fringe Fields & \ref{s:fringe} & Superposition & \ref{c:super} \\ Hkick \& Vkick & \ref{s:kick} & Symplectify & \ref{s:symp} \\ Integration settings & \ref{s:integ} & Field Maps & \ref{s:fieldmap} \\ Is_on & \ref{s:is.on} & Tracking \& transfer map & \ref{c:methods} \\ @@ -5019,7 +5019,7 @@ \section{Sol_Quad} Chamber wall & \ref{s:wall} & Offsets, pitches \& tilt & \ref{s:offset} \\ Custom Attributes & \ref{s:cust.att} & Overlapping Fields & \ref{s:overlap} \\ Description strings & \ref{s:alias} & Reference energy & \ref{s:energy} \\ - Fringe Fields & \ref{s:fringe} & Superposition & \ref{s:super} \\ + Fringe Fields & \ref{s:fringe} & Superposition & \ref{c:super} \\ Hkick \& Vkick & \ref{s:kick} & Symplectify & \ref{s:symp} \\ Integration settings & \ref{s:integ} & Field Maps & \ref{s:fieldmap} \\ Is_on & \ref{s:is.on} & Tracking \& transfer map & \ref{c:methods} \\ @@ -5065,7 +5065,7 @@ \section{Solenoid} Chamber wall & \ref{s:wall} & Offsets, pitches \& tilt & \ref{s:offset} \\ Custom Attributes & \ref{s:cust.att} & Overlapping Fields & \ref{s:overlap} \\ Description strings & \ref{s:alias} & Reference energy & \ref{s:energy} \\ - Fringe Fields & \ref{s:fringe} & Superposition & \ref{s:super} \\ + Fringe Fields & \ref{s:fringe} & Superposition & \ref{c:super} \\ Hkick \& Vkick & \ref{s:kick} & Symplectify & \ref{s:symp} \\ Integration settings & \ref{s:integ} & Field Maps & \ref{s:fieldmap} \\ Is_on & \ref{s:is.on} & Tracking \& transfer map & \ref{c:methods} \\ @@ -5135,7 +5135,7 @@ \section{Taylor} {\sl Attribute Class} & Section & {\sl Attribute Class} & Section \\ \midrule Aperture limits & \ref{s:limit} & Offsets \& tilt & \ref{s:offset} \\ Custom Attributes & \ref{s:cust.att} & Reference energy & \ref{s:energy} \\ - Description strings & \ref{s:alias} & Superposition & \ref{s:super} \\ + Description strings & \ref{s:alias} & Superposition & \ref{c:super} \\ Is_on & \ref{s:is.on} & Symplectify & \ref{s:symp} \\ Length & \ref{s:l} & Tracking \& transfer map & \ref{c:methods} \\ \bottomrule @@ -5367,7 +5367,7 @@ \section{Thick_Multipole} Chamber wall & \ref{s:wall} & Offsets, pitches \& tilt & \ref{s:offset} \\ Custom Attributes & \ref{s:cust.att} & Overlapping Fields & \ref{s:overlap} \\ Description strings & \ref{s:alias} & Reference energy & \ref{s:energy} \\ - Fringe Fields & \ref{s:fringe} & Superposition & \ref{s:super} \\ + Fringe Fields & \ref{s:fringe} & Superposition & \ref{c:super} \\ Hkick \& Vkick & \ref{s:kick} & Symplectify & \ref{s:symp} \\ Integration settings & \ref{s:integ} & Field Maps & \ref{s:fieldmap} \\ Is_on & \ref{s:is.on} & Tracking \& transfer map & \ref{c:methods} \\ @@ -5406,7 +5406,7 @@ \section{Wiggler and Undulator} Chamber wall & \ref{s:wall} & Offsets, pitches \& tilt & \ref{s:offset} \\ Custom Attributes & \ref{s:cust.att} & Overlapping Fields & \ref{s:overlap} \\ Description strings & \ref{s:alias} & Reference energy & \ref{s:energy} \\ - Fringe Fields & \ref{s:fringe} & Superposition & \ref{s:super} \\ + Fringe Fields & \ref{s:fringe} & Superposition & \ref{c:super} \\ Hkick \& Vkick & \ref{s:kick} & Symplectify & \ref{s:symp} \\ Integration settings & \ref{s:integ} & Field Maps & \ref{s:fieldmap} \\ Is_on & \ref{s:is.on} & Tracking \& transfer map & \ref{c:methods} \\ diff --git a/bmad/doc/example-program.tex b/bmad/doc/example-program.tex index 91430b1b70..9f04aca3a6 100644 --- a/bmad/doc/example-program.tex +++ b/bmad/doc/example-program.tex @@ -187,7 +187,7 @@ \section{Explanation of the Simple_Bmad_Program} came from. Next, since the \vn{CLEO_SOL} element happens to only cover part of the \vn{Q00W} quadrupole, \vn{bmad_parser} breaks the quadrupole into two pieces. The piece that is inside the solenoid is a \vn{sol_quad} and the piece outside the solenoid is a regular quadrupole. See -\sref{s:super} for more details. Since the center of the \vn{CLEO_SOL} is at $s = 0$, half of it +\sref{c:super} for more details. Since the center of the \vn{CLEO_SOL} is at $s = 0$, half of it extends to negative $s$. In this situation, \vn{bmad_parser} will wrap this half back and superimpose it on the elements at the end of the lattice list near $s = s_{lat}$ where $s_{lat}$ is the length of the lattice. As explained in Chapter~\ref{c:lat.struct}, the lattice list that is diff --git a/bmad/doc/lat-struct.tex b/bmad/doc/lat-struct.tex index 9979f1d650..2afff3a15b 100644 --- a/bmad/doc/lat-struct.tex +++ b/bmad/doc/lat-struct.tex @@ -330,7 +330,7 @@ \section{Elements Controlling Other Elements} % \item[super_lord\$]\Newline A \vn{super_lord} element is created when elements are superimposed on top of other elements -(\sref{s:super}). \vn{super_lords} (along with \vn{multipass_lords}), are called \vn{major} lords +(\sref{c:super}). \vn{super_lords} (along with \vn{multipass_lords}), are called \vn{major} lords since the attribute values of a \vn{super_slave} are entirely determined by the attribute values of the \vn{super_lord}(s) of the slave. % @@ -339,7 +339,7 @@ \section{Elements Controlling Other Elements} have \vn{ele%key} = \vn{girder\$}. % \item[multipass_lord\$]\Newline -\vn{multipass_lord} elements are created when multipass lines are present (\sref{s:multipass}). +\vn{multipass_lord} elements are created when multipass lines are present (\sref{c:multipass}). \vn{multipass_lords} (along with \vn{super_lords}) are called \vn{major} lords since most of the attribute values of a \vn{multipass_slave} are entirely determined by the attribute values of the \vn{multipass_lord} of the slave. The few exceptions are parameters like \vn{phi0_multipass} which can @@ -373,14 +373,14 @@ \section{Elements Controlling Other Elements} \begin{description} \item[multipass_slave\$]\Newline A \vn{multipass_slave} element is the slave of a \vn{multipass_lord} -(\sref{s:multipass}). +(\sref{c:multipass}). \item[slice_slave\$]\Newline A \vn{slice_slave} element represents a longitudinal slice of another element. Slice elements are not part of the lattice but rather are created on-the-fly when, for example, a program needs to track part way through an element. \item[super_slave\$]\Newline A \vn{super_slave} element is an element in the tracking part of the branch that -has one or more \vn{super_lord} lords (\sref{s:super}). +has one or more \vn{super_lord} lords (\sref{c:super}). \item[minor_slave\$]\Newline A \vn{minor_slave} element is an element that is not a \vn{slice_slave} and does not have a \vn{major} lord. Major lords are \vn{super_lord}s and \vn{multipass_lord}s. A \vn{minor_slave} @@ -467,7 +467,7 @@ \section{Elements Controlling Other Elements} For lord/slave pairs, Table~\ref{f:lord.slave.b} lists the valid combinations of \vn{%lord_status} values in the lord element and \vn{%slave_status} values in the slave element. Thus, for example, a \vn{super_slave} may only be controlled by a \vn{super_lord}. In the example in -Section~\sref{s:multipass}, element \vn{A} would be a \vn{multipass_lord} and \vn{A\B1} and +Section~\sref{c:multipass}, element \vn{A} would be a \vn{multipass_lord} and \vn{A\B1} and \vn{A\B2} would be \vn{multipass_slave}s. When superposition is combined with multipass, the elements in the tracking part of the branch will be \vn{super_slave}s. These elements will be controlled by \vn{super_lord}s which will also be \vn{multipass_slave}s and these @@ -647,8 +647,8 @@ \section{Lattice Bookkeeping} \item[Control bookkeeping] \Newline This refers to Lord/Slave bookkeeping for \vn{overlay} (\sref{s:overlay}) and \vn{group} (\sref{s:group})elements, and for -\vn{superposition} (\sref{s:super}) and \vn{multipass} -(\sref{s:multipass}) lords. +\vn{superposition} (\sref{c:super}) and \vn{multipass} +(\sref{c:multipass}) lords. \item[Floor Position bookkeeping] This refers to bookkeeping to keep track of an elements global ``floor'' position stored in the \vn{ele%floor} structure. diff --git a/bmad/doc/lattice-file.tex b/bmad/doc/lattice-file.tex index 3c3db07e89..df6890eaf6 100644 --- a/bmad/doc/lattice-file.tex +++ b/bmad/doc/lattice-file.tex @@ -81,7 +81,7 @@ \section{File Example and Syntax} a letter (\vn{A} --- \vn{Z}). The other characters may be a letter, a digit (\vn{0} --- \vn{9}) or an underscore (\vn{_}). Other characters may appear but should be avoided since they are used by Bmad for various purposes. For example, the backslash (\vn{\B}) character is used to by Bmad when -forming the names of superposition slaves (\sref{s:super}) and dots (\vn{.}) are used by Bmad when +forming the names of superposition slaves (\sref{c:super}) and dots (\vn{.}) are used by Bmad when creating names of \vn{tagged} elements (\sref{s:tag}). Also use of special characters may make the lattice files less portable to non-Bmad programs. @@ -163,7 +163,7 @@ \section{Element Sequence Definition} \index{superimpose} The \vn{superimpose} construct allows elements to be placed in a lattice at a definite longitudinal position. What happens is that after a lattice is expanded, there is a reshuffling of the elements -to accommodate any new superimpose elements. See \sref{s:super} for more details. +to accommodate any new superimpose elements. See \sref{c:super} for more details. %--------------------------------------------------------------------------- \section{Lattice Elements} @@ -225,7 +225,7 @@ \section{Lattice Element Names} permitted since this interfers with the notation for finding the $N$\Th element with a given name (\sref{s:ele.match}). It is best to avoid these last three symbols since \bmad uses them to denote ``relationships''. Periods are used for tagging (\sref{s:tag}), and backslash and hash marks are -used for to compose names for superposition (\sref{s:super}) and multipass (\sref{s:multipass}) +used for to compose names for superposition (\sref{c:super}) and multipass (\sref{c:multipass}) slave elements. \index{reserved names} @@ -754,7 +754,7 @@ \section{Custom Element Attributes} Negative indices are accepted and if only one or two indices are present, the others are assumed to be zero. Thus \vn{r_custom(-3)} is equivalent to \vn{r_custom(-3,0,0)}. -Note: When there is a superposition (\sref{s:super}), the \vn{super_slave} elements that are formed +Note: When there is a superposition (\sref{c:super}), the \vn{super_slave} elements that are formed do {\em not} have any custom attributes assigned to them even when their \vn{super_lord} elements have custom attributes. This is done since the \bmad bookkeeping routines are not able to handle the situation where a \vn{super_slave} element has multiple \vn{super_lord} elements and thus the custom @@ -1394,7 +1394,7 @@ \section{No_Superimpose Statement} \label{s:no.sup} \index{no_superimpose statement} -In certain cases it is useful to turn off superposition (\sref{s:super}). The \vn{no_superposition} +In certain cases it is useful to turn off superposition (\sref{c:super}). The \vn{no_superposition} statement will do this. To turn off all superpositioning, this statement can appear anywhere as long as it is before any \vn{expand_lattice} (\sref{s:expand.lat}) statement. If the lattice has an \vn{expand_lattice} statement, and the \vn{no_superposition} statement appears after, the @@ -1445,7 +1445,7 @@ \section{Lattice Expansion} \item Setting the \vn{phi0_multipass} attribute for an \vn{Lcavity} or \vn{RFcavity} multipass -slave may only be done after lattice expansion (\sref{s:multipass}). +slave may only be done after lattice expansion (\sref{c:multipass}). \item \index{tags for Lines and Lists} Setting individual element attributes for tagged elements can only be done @@ -1470,10 +1470,10 @@ \section{Lattice Expansion} \item Line expansion (\sref{c:sequence}) where the element sequence is constructed from the line and sub-lines. \item -Adding any superpositions (\sref{s:super}). +Adding any superpositions (\sref{c:super}). \end{enumerate} \item -Form multipass lords and mark the appropriate multipass slaves (\sref{s:multipass}). +Form multipass lords and mark the appropriate multipass slaves (\sref{c:multipass}). \item Add girder control elements (\sref{s:girder}). \item diff --git a/bmad/doc/lines-and-lists.tex b/bmad/doc/lines-and-lists.tex index 2a0337a01a..15044aaa53 100644 --- a/bmad/doc/lines-and-lists.tex +++ b/bmad/doc/lines-and-lists.tex @@ -4,7 +4,7 @@ \chapter{Beam Lines and Replacement Lists} \index{branch} This chapter describes how to define the ordered list of elements that make up a lattice branch (\sref{s:branch.def}). In a lattice, branches may be connected together using \vn{fork} or -\vn{photon fork} elements (\vn{s:fork}), or by using \vn{multipass} (\sref{s:multipass}). +\vn{photon fork} elements (\vn{s:fork}), or by using \vn{multipass} (\sref{c:multipass}). %----------------------------------------------------------------------------- \section{Branch Construction Overview} @@ -137,7 +137,7 @@ \section{Beam Lines and Lattice Expansion} line that references it. Additionally, element definitions can come before or after any lines that reference them. -A line can have the \vn{multipass} attribute. This is covered in \sref{s:multipass}. +A line can have the \vn{multipass} attribute. This is covered in \sref{c:multipass}. %----------------------------------------------------------------------------- \section{Line Slices} @@ -214,7 +214,7 @@ \section{Element Orientation Reversal} complicates matters, it is generally only useful to employ element reversal in cases where there are multiple intersecting lines with particle beams going in opposite directions through some elements (for example, colliding beam interaction regions). In this case, element reversal is typically used -with \vn{multipass} (\sref{s:multipass}) and the lattice will contain a branch of unreversed +with \vn{multipass} (\sref{c:multipass}) and the lattice will contain a branch of unreversed elements for simulating particles going in one direction along with a branch of reversed elements to simulate particle going in the other direction. @@ -303,7 +303,7 @@ \section{Use Statement} use, line1, line2 ... \end{example} For example, \vn{line1} may correspond to one ring and \vn{line2} may correspond to the other ring -of a dual ring colliding beam machine. In this case, \vn{multipass} (\sref{s:multipass}) will be +of a dual ring colliding beam machine. In this case, \vn{multipass} (\sref{c:multipass}) will be needed to describe the common elements of the two rings. Example \begin{example} use, e_ring, p_ring diff --git a/bmad/doc/multipass.tex b/bmad/doc/multipass.tex new file mode 100644 index 0000000000..018a65b53e --- /dev/null +++ b/bmad/doc/multipass.tex @@ -0,0 +1,235 @@ +\chapter{Multipass} +\label{c:multipass} + +\index{multipass} +This chapter covers the concept of \vn{multipass}. \vn{Multipass} is used when an element is +``shared'' between branches such as the interaction region shared by two storage rings, or when a +beam goes through the same physical element in a branch multiple times as in an energy recovery +linac. With \vn{multipass}, \vn{lord} and \vn{slave} elements (\sref{s:lord.slave}) are constructed +by \bmad to hold the necessary information. The \vn{lord} elements will represent the ``physical'' +element while the \vn{slave} elements will embody the ``beam path''. + +%----------------------------------------------------------------------------- +\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 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}. diff --git a/bmad/doc/superimpose-and-multipass.tex b/bmad/doc/superposition.tex similarity index 96% rename from bmad/doc/superimpose-and-multipass.tex rename to bmad/doc/superposition.tex index 4ca3cebfd5..0d16717cd8 100644 --- a/bmad/doc/superimpose-and-multipass.tex +++ b/bmad/doc/superposition.tex @@ -1,25 +1,15 @@ -\chapter{Superposition, and Multipass} -\label{c:super.multi} +\chapter{Superposition} +\label{c:super} -\index{superposition}\index{multipass} -This chapter covers two concepts: \vn{superposition} (\sref{s:super}) and \vn{multipass} -(\sref{s:multipass}) \vn{Superposition} is used when elements overlap spatially. \vn{Multipass} is -used when an element is ``shared'' between branches such as the interaction region shared by two -storage rings, or when a beam goes through the same physical element in a branch multiple times as -in an energy recovery linac. - -In both cases, \vn{lord} and \vn{slave} elements (\sref{s:lord.slave}) are constructed by \bmad to -hold the necessary information. In both cases, the \vn{lord} elements will represent the -``physical'' element while the \vn{slave} elements will embody the ``beam path''. - -%----------------------------------------------------------------------------- -\section{Superposition} -\label{s:super} -\index{superimpose|hyperbf} +\index{superposition} +This chapter covers the concept of \vn{superposition}. \vn{Superposition} is used when elements +overlap spatially. With \vn{superposition}, \vn{lord} and \vn{slave} elements (\sref{s:lord.slave}) +are constructed by \bmad to hold the necessary information. The \vn{lord} elements will represent +the ``physical'' element while the \vn{slave} elements will embody the ``beam path''. %----------------------------------------------------------------------------- -\subsection{Superposition Fundamentals} -\label{s:super.fund} +\section{Superposition Fundamentals} +\label{c:super.fund} \begin{figure}[tb] \centering @@ -321,8 +311,8 @@ \subsection{Superposition Fundamentals} The \vn{no_superposition} statement (\sref{s:no.sup}) can be used to turn off superpositioning %----------------------------------------------------------------------------- -\subsection{Superposition and Sub-Lines} -\label{s:super.sub.line} +\section{Superposition and Sub-Lines} +\label{c:super.sub.line} Sometimes it is convenient to do simulations with only part of a lattice. The rule for how superpositions are handled in this case is illustrated in the following example. Consider a lattice @@ -359,7 +349,7 @@ \subsection{Superposition and Sub-Lines} beginning of \vn{full}. %----------------------------------------------------------------------------- -\subsection{Jumbo Super_Slaves} +\section{Jumbo Super_Slaves} \label{s:jumbo.slave} The problem with the way \vn{super_slave} elements are created as discussed above is that edge @@ -367,7 +357,7 @@ \subsection{Jumbo Super_Slaves} is important, especially at low energy, a possible remedy is to instruct \bmad to construct ``\vn{jumbo}'' super_slave elements. The general idea is to create one large \vn{super_slave} for any set of overlapping elements. Returning to the superposition example at the start of -Section~\sref{s:super}, If the superposition of solenoid \vn{S} is modified to be +Section~\sref{c:super}, If the superposition of solenoid \vn{S} is modified to be \begin{example} S: solenoid, l = 8, superimpose, ref = Q, ele_origin = beginning, create_jumbo_slave = T @@ -416,8 +406,8 @@ \subsection{Jumbo Super_Slaves} attribute as discussed in \sref{s:overlap}. %----------------------------------------------------------------------------- -\subsection{Changing Element Lengths when there is Superposition} -\label{s:super.length} +\section{Changing Element Lengths when there is Superposition} +\label{c:super.length} When a program is running, if \vn{group} (\sref{s:group}) or \vn{overlay} (\sref{s:overlay}) elements are used to vary the length of elements that are involved in superimposition, the results @@ -429,7 +419,7 @@ \subsection{Changing Element Lengths when there is Superposition} Second, even if a lattice has not been mangled, an algorithm for varying lengths that is based on the superimpose information in the lattice file could lead to unexpected results. To see this -consider the first example in Section~\sref{s:super}. If the length of \vn{S} is varied in the +consider the first example in Section~\sref{c:super}. If the length of \vn{S} is varied in the lattice file, the upstream edge of \vn{S} will remain fixed at the center of \vn{Q} which means that the length of the \vn{super_slave} element \vn{Q{\#}1} will be invariant. On the other hand, if element \vn{S} is defined by @@ -444,7 +434,7 @@ \subsection{Changing Element Lengths when there is Superposition} To avoid confusion, \bmad uses a simple algorithm for varying the lengths of elements involved in superposition: The rule is that the length of the most downstream \vn{super_slave} is varied. With -the first example in Section~\sref{s:super}, the \vn{group} \vn{G} varying the length of \vn{Q} +the first example in Section~\sref{c:super}, the \vn{group} \vn{G} varying the length of \vn{Q} defined by: \begin{example} G: group = \{Q\}, var = \{l\} @@ -466,12 +456,12 @@ \subsection{Changing Element Lengths when there is Superposition} %----------------------------------------------------------------------------- \section{Multipass} -\label{s:multipass} +\label{c:multipass} \index{multipass|hyperbf} %----------------------------------------------------------------------------- -\subsection{Multipass Fundamentals} -\label{s:multipass.fund} +\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 @@ -649,7 +639,7 @@ \subsection{Multipass Fundamentals} sure that the physical positions of the slaves makes sense (that is, are the same). %----------------------------------------------------------------------------- -\subsection{The Reference Energy in a Multipass Line} +\section{The Reference Energy in a Multipass Line} \label{s:ref.e.multi} \index{lcavity}