Merge pull request #610 from bmad-sim/devel/46

Minor doc update.

bmad/code/create_element_slice.f90

@@ -140,7 +140,7 @@ recursive subroutine create_element_slice (sliced_ele, ele_in, l_slice, offset,
  .not. include_downstream_end .and. ele0%value(l$) == sliced_ele%value(l$) .and. &
  (ele_in%tracking_method == bmad_standard$ .or. ele_in%field_calc == bmad_standard$)) then
  select case (ele_in%key)
- case (sbend$, quadrupole$, sextupole$, octupole$)
+ case (sbend$, quadrupole$, sextupole$, octupole$, thick_multipole$)
  if (associated(sliced_ele%rad_map)) sliced_ele%rad_map%stale = .false.
  end select
 endif 

bmad/code/em_field_calc.f90

@@ -329,7 +329,7 @@ recursive subroutine em_field_calc (ele, param, s_pos, orbit, local_ref_frame, f
  !------------------
  ! Drift, et. al. Note that kicks get added at the end for all elements
 
- case (drift$, ecollimator$, rcollimator$, instrument$, monitor$, pipe$, marker$, detector$)
+ case (drift$, ecollimator$, rcollimator$, instrument$, monitor$, pipe$, marker$, detector$, thick_multipole$)
 
  !------------------
  ! E_Gun

bmad/code/lat_sanity_check.f90

@@ -1080,7 +1080,7 @@ subroutine lat_sanity_check (lat, err_flag)
  if (l_stat == multipass_lord$ .and. .not. ele%field_master .and. ele%value(p0c$) == 0 .and. &
  ele%value(e_tot$) == 0 .and. ele%value(multipass_ref_energy$) == 0) then
  select case (ele%key)
- case (quadrupole$, sextupole$, octupole$, solenoid$, sol_quad$, sbend$, rf_bend$, &
+ case (quadrupole$, sextupole$, octupole$, thick_multipole$, solenoid$, sol_quad$, sbend$, rf_bend$, &
  hkicker$, vkicker$, kicker$, elseparator$)
  call out_io (s_fatal$, r_name, &
  'FOR MULTIPASS LORD: ' // ele_full_name(ele, '@N (&#)'), &

bmad/code/multipole_ele_to_ab.f90

@@ -431,7 +431,7 @@ subroutine convert_this_ab (this_ele, p_type, a_pole, b_pole, this_a, this_b)
  const = this_ele%value(k3$) * this_ele%value(l$)
  ref_exp = 3
 
-case (ab_multipole$, sad_mult$) ! multipoles do not scale
+case (ab_multipole$, sad_mult$, thick_multipole$) ! multipoles do not scale
  return
 
 case default

bmad/code/offset_particle.f90

@@ -247,7 +247,7 @@ subroutine offset_particle (ele, set, orbit, set_tilt, set_hvkicks, drift_to_edg
 
  pz = rel_p**2 - orbit%vec(2)**2 - orbit%vec(4)**2
  if (pz <= 0) then
- orbit%state = lost_pz_aperture$
+ orbit%state = lost_pz$
  else
  p_vec0 = [orbit%vec(2), orbit%vec(4), sign_z_vel * sqrt(pz)]
  p_vec = matmul(position%w, p_vec0)
@@ -445,7 +445,7 @@ subroutine offset_particle (ele, set, orbit, set_tilt, set_hvkicks, drift_to_edg
 
  pz = rel_p**2 - orbit%vec(2)**2 - orbit%vec(4)**2
  if (pz <= 0) then
- orbit%state = lost_pz_aperture$
+ orbit%state = lost_pz$
  else
  p_vec0 = [orbit%vec(2), orbit%vec(4), sign_z_vel * sqrt(pz)]
  p_vec = matmul(position%w, p_vec0)

bmad/code/valid_mat6_calc_method.f90

@@ -210,7 +210,7 @@ function valid_mat6_calc_method (ele, species, mat6_calc_method) result (is_vali
 case (null_ele$)
  ! Nothing to do
 
-case (octupole$)
+case (octupole$, thick_multipole$)
  select case (mat6_calc_method)
  case (auto$, bmad_standard$, symp_lie_ptc$, taylor$, tracking$, custom$)
  is_valid = .true.

bmad/code/valid_tracking_method.f90

@@ -217,7 +217,7 @@ function valid_tracking_method (ele, species, tracking_method) result (is_valid)
 case (null_ele$)
  ! Nothing to do
 
-case (octupole$)
+case (octupole$, thick_multipole$)
  select case (method)
  case (bmad_standard$, symp_lie_ptc$, runge_kutta$, linear$, taylor$, time_runge_kutta$, custom$)
  is_valid = .true.

bmad/code/write_lattice_in_foreign_format.f90

@@ -293,7 +293,7 @@ subroutine write_lattice_in_foreign_format (out_type, out_file_name, lat, ref_or
  monopole = .false.
  if (out_type == 'ELEGANT') then
  select case (ele%key)
- case (quadrupole$, sextupole$, octupole$) ! Elegant
+ case (quadrupole$, sextupole$, octupole$, thick_multipole$) ! Elegant
  call multipole_ele_to_kt(ele, .true., ix_pole_max, knl, tilts, magnetic$, include_kicks$)
  if (count(knl /= 0) == 1 .and. all(knl(0:3) == 0)) monopole = .true.
  end select
@@ -668,7 +668,7 @@ subroutine write_lattice_in_foreign_format (out_type, out_file_name, lat, ref_or
 
  ! Special case where element is a pure thick N-pole of order greater than octupole.
  select case (ele%key)
- case (quadrupole$, sextupole$, octupole$) ! Elegant
+ case (quadrupole$, sextupole$, octupole$, thick_multipole$) ! Elegant
  call multipole_ele_to_kt(ele, .true., ix_pole_max, knl, tilts, magnetic$, include_kicks$)
  if (count(knl /= 0) == 1 .and. all(knl(0:3) == 0)) then
  n = find_location(knl /= 0, .true.) - 1

bmad/doc/beam-init.tex

@@ -406,3 +406,61 @@ \section{File Based Beam Initialization}
 When the particle coordinates are read in the centroid will be shifted by the setting of
 \vn{beam_init%center} (unless \vn{beam_init%use_particle_start} is set True) and
 \vn{beam_init%center_jitter}.
+
+%-----------------------------------------------------------------
+\subsection{New Beam Initialization Format}
+
+2023/11: Note! The above ASCII format is in the process of being replaced. The new ASCII format is
+still undergoing testing so caution must be used when using the new format.
+
+The new ASCII format describes a particle bunch with a \vn{header} section followed by a \vn{table}
+of particle parameters. Multiple bunches that comprise a beam can be specified by multiple header
+section / particle parameter table pairs, one pair for each bunch. An example header section:
+\begin{example}
+\# The header field lines all start with a pound "\#" sign.
+\# Any line in the header field that does not start with a recognized parameter or
+\# does not have an equal sign is ignored.
+\# my_param = 1.23 ! Thus Custom parameters can be set an will be ignored by Bmad.
+\# species = proton ! This parameter will be read by Bmad.
+\# spin = 1, 0, 0 ! and this one too.
+\# The last line in the header field starts with "\#!" and defines the table columns.
+\#! index x px y py ... etc...
+\end{example}
+The header section lines all start with a pound ``\#'' sign. The last line in the header section
+must start with ``\#!'' and this line defines the particle parameter table columns. With the
+exception of the last line, all header lines will be ignored except ones that begin with a
+recognized parameter followed by an equal sign. Recognized parameters are the components of the
+\vn{coord_struct}, as documented in \sref{s:coord.struct}, that describes individual particles. In
+addition, the following parameters are recognized:
+\begin{example}
+ charge_tot ! Total bunch charge (including dead particles).
+ s_position ! Longitudinal position of bunch. Can be used in place of "s".
+ time ! Time particles of bunch are at. Can be used in place of "t".
+\end{example}
+These parameters, if present, will be used to set the corresponding particle parameter in all the
+particles of the corresponding bunch. Possible \vn{location} and \vn{state} parameter settings are
+documented in \sref{s:coord.struct}. The string equivalent to any setting is obtained by removing
+the trailing ``\$'' from the variable name. For example, the variable \vn{alive\$} which is a
+possible \vn{state} setting becomes the string \vn{alive}. Note: \vn{charge_tot} (total bunch
+charge) will superceed \vn{charge} (the charge per particle).
+
+The particle parameter table follows the header section. Each row gives the parameters for one
+particle. Not all particle parameters must be specified. If a particular parameter is not present,
+its default value will be used or, if present, the value given in the header section. Column order
+is irrelavent and what determines what particle parameter is associated with a given column is the
+last line of the header section which starts with the characters \vn{\#!}. Except for vector
+parameters, column names correspond to \vn{coord_struct} parameters the same as in the header
+section. For parameters that are vectors, the mapping from column name to parameter is:
+\begin{example}
+ Column Name Corresponding coord_struct components
+ ---------------------- -----------------------------------------
+ x, px, y, py, z, pz vec(1), ..., vec(6)
+ spin_x, spin_y, spin_z spin(1), spin(2), spin(3)
+ field_x, field_y field(1), field(2)
+ phase_x, phase_y phase(1), phase(2)
+\end{example}
+Additionally, there can be (but is not required) an \vn{index} column giving the particle index in
+the array of particles of a bunch. This column is ignored so, for example, values in the first line
+of the table will always be used to set the particle with index 1 independent of the
+value given in the index column. This behavior is implemented so that a beam file can be edited to add
+or remove particles without worrying about reindexing.

bmad/doc/cover-page.tex

@@ -3,7 +3,7 @@
 
 \begin{flushright}
 \large
- Revision: October 3, 2023 \\
+ Revision: November 1, 2023 \\
 \end{flushright}
 
 \pdfbookmark[0]{Preamble}{Preamble} 

bmad/doc/elements.tex

@@ -10,35 +10,35 @@ \chapter{Lattice Elements}
 \centering
 {\tt
 \begin{tabular}{llll} \toprule
- {\it Element} & {\it Section} & {\it Element} & {\it Section} \\ \midrule
- AB_Multipole & \ref{s:ab.m} & Mask & \ref{s:mask} \\
- AC_Kicker & \ref{s:ac.kick} & Match & \ref{s:match} \\ 
- BeamBeam & \ref{s:beambeam} & Monitor & \ref{s:monitor} \\
- Beginning_Ele & \ref{s:begin.ele} & Multipole & \ref{s:mult} \\
- Converter & \ref{s:converter} & Null_Ele & \ref{s:null.ele} \\
- Crab_Cavity & \ref{s:crab} & Octupole & \ref{s:oct} \\
- Custom & \ref{s:custom} & Patch & \ref{s:patch} \\
- Drift & \ref{s:drift} & Photon_Fork & \ref{s:fork} \\
- E_Gun & \ref{s:e.gun} & Pipe & \ref{s:monitor} \\
- Ecollimator & \ref{s:col} & Quadrupole & \ref{s:quad} \\
- ElSeparator & \ref{s:elsep} & Rbend & \ref{s:bend} \\
- EM_Field & \ref{s:em.field} & Rcollimator & \ref{s:col} \\
- Fiducial & \ref{s:fiducial} & RF_bend & \ref{s:rf.bend} \\
- Floor_Shift & \ref{s:floor.ele} & RFcavity & \ref{s:rfcav} \\
- Foil & \ref{s:foil} & Sad_Mult & \ref{s:sad.mult} \\
- Fork & \ref{s:fork} & Sbend & \ref{s:bend} \\
- GKicker & \ref{s:gkicker} & Sextupole & \ref{s:sex} \\
- HKicker & \ref{s:hvkicker} & Sol_Quad & \ref{s:sq} \\
- Hybrid & \ref{s:hybrid} & Solenoid & \ref{s:sol} \\
- Instrument & \ref{s:monitor} & Taylor & \ref{s:taylor} \\
- Kicker & \ref{s:kicker} & Undulator & \ref{s:wiggler} \\
- Lcavity & \ref{s:lcav} & VKicker & \ref{s:hvkicker} \\ 
- Marker & \ref{s:mark} & Wiggler & \ref{s:wiggler} \\
+ {\it Element} & {\it Section} & {\it Element} & {\it Section} \\ \midrule
+ AB_Multipole & \ref{s:ab.m} & Match & \ref{s:match} \\
+ AC_Kicker & \ref{s:ac.kick} & Monitor & \ref{s:monitor} \\
+ BeamBeam & \ref{s:beambeam} & Multipole & \ref{s:mult} \\
+ Beginning_Ele & \ref{s:begin.ele} & Null_Ele & \ref{s:null.ele} \\
+ Converter & \ref{s:converter} & Octupole & \ref{s:oct} \\
+ Crab_Cavity & \ref{s:crab} & Patch & \ref{s:patch} \\
+ Custom & \ref{s:custom} & Photon_Fork & \ref{s:fork} \\
+ Drift & \ref{s:drift} & Pipe & \ref{s:monitor} \\
+ E_Gun & \ref{s:e.gun} & Quadrupole & \ref{s:quad} \\
+ Ecollimator & \ref{s:col} & Rbend & \ref{s:bend} \\
+ ElSeparator & \ref{s:elsep} & Rcollimator & \ref{s:col} \\
+ EM_Field & \ref{s:em.field} & RF_bend & \ref{s:rf.bend} \\
+ Fiducial & \ref{s:fiducial} & RFcavity & \ref{s:rfcav} \\
+ Floor_Shift & \ref{s:floor.ele} & Sad_Mult & \ref{s:sad.mult} \\
+ Foil & \ref{s:foil} & Sbend & \ref{s:bend} \\
+ Fork & \ref{s:fork} & Sextupole & \ref{s:sex} \\
+ GKicker & \ref{s:gkicker} & Sol_Quad & \ref{s:sq} \\
+ HKicker & \ref{s:hvkicker} & Solenoid & \ref{s:sol} \\
+ Hybrid & \ref{s:hybrid} & Taylor & \ref{s:taylor} \\
+ Instrument & \ref{s:monitor} & Thick_Multipole & \ref{s:thick.mult} \\
+ Kicker & \ref{s:kicker} & Undulator & \ref{s:wiggler} \\
+ Lcavity & \ref{s:lcav} & VKicker & \ref{s:hvkicker} \\ 
+ Marker & \ref{s:mark} & Wiggler & \ref{s:wiggler} \\
+ Mask & \ref{s:mask} & & \\
  \bottomrule
 \end{tabular}
-}
-\caption{Table of element types suitable for use with charged particles. Also see Table~\ref{t:control.classes}}
-\label{t:particle.classes}
+} \caption{Table of element types suitable for use with charged particles. Also see
+Table~\ref{t:control.classes}} \label{t:particle.classes}
 \end{table}
 
 \index{MAD}
@@ -5047,6 +5047,46 @@ \section{Taylor}
 
 \newpage
 
+%-----------------------------------------------------------------
+\section{Thick_Multipole}
+\label{s:thick.mult}
+\index{thick_multipole|hyperbf} 
+
+A \vn{thick_multipole} element is like a \vn{sextupole} or \vn{octupole} element except that the
+\vn{thick_multipole} does not have a \vn{K2} sextupole like parameter nor a \vn{K3} octupole like
+parameter. Rather, \vn{thick_multipoles}, like \vn{sextupole} or \vn{octupole} elements, have
+\vn{a0}, \vn{a1}, \vn{a2}, etc. and \vn{b0}, \vn{b1}, \vn{b2}, etc. multipoles
+(\sref{s:mag.field}). In terms of tracking, given equivalent multipole values, \vn{thick_multipoles}
+are indistinguishable from \vn{sextupoles} or \vn{octupoles}. \vn{thick_multipole} elements are
+useful for differentiating elements that only have higher order multipole moments.
+
+General \vn{thick_multipole} attributes are:
+\begin{center}
+\tt
+\begin{tabular}{llll} \toprule
+ {\sl Attribute Class} & Section & {\sl Attribute Class} & Section \\ \midrule
+ Aperture limits & \ref{s:limit} & Mag \& Elec multipoles & \ref{s:multip} \\
+ 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} \\
+ 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} \\ 
+ Length & \ref{s:l} & & \\
+ \bottomrule
+\end{tabular}
+\end{center}
+\toffset
+See \sref{s:list.thick.multipole} for a full list of element attributes along with a their units.
+
+Example:
+\begin{example}
+ tm1: thick_multipole, l = 4.5, tilt, x_pitch = 0.34, a7 = 1.23e3, b8 = 7.54e5
+\end{example}
+
+\newpage
+
 %-----------------------------------------------------------------
 \section{Wiggler and Undulator} 
 \label{s:wiggler}

bmad/doc/list-element-attributes.tex

@@ -1320,6 +1320,35 @@ \chapter{List of Element Attributes}
  \end{tabular}
  \vfill
 
+ %---------------------------------
+ \section{Thick_Multipole Element Attributes}
+ \label{s:list.thick.multipole}
+
+ \begin{tabular}{llll} \toprule
+a0 - a20, b0 - b20 & fringe_at & ptc_canonical_coords & wall \\
+alias & fringe_type & ptc_integration_type & wrap_superimpose \\
+aperture [m] & gen_grad_map & ref_origin & x1_limit [m] \\
+aperture_at & grid_field & ref_time_start [sec] & x2_limit [m] \\
+aperture_type & hkick & reference & x_limit [m] \\
+bl_hkick [T*m] & integrator_order & scale_multipoles & x_offset [m] \\
+bl_vkick [T*m] & is_on & space_charge_method & x_offset_tot [m] \\
+cartesian_map & l [m] & spin_fringe_on & x_pitch [rad] \\
+create_jumbo_slave & lord_pad1 [m] & spin_tracking_method & x_pitch_tot [rad] \\
+csr_ds_step [m] & lord_pad2 [m] & sr_wake & y1_limit [m] \\
+csr_method & lr_freq_spread [Hz] & sr_wake_file & y2_limit [m] \\
+cylindrical_map & lr_self_wake_on & static_linear_map & y_limit [m] \\
+delta_ref_time [sec] & lr_wake & superimpose & y_offset [m] \\
+descrip & lr_wake_file & symplectify & y_offset_tot [m] \\
+ds_step [m] & mat6_calc_method & taylor_map_includes_offsets & y_pitch [rad] \\
+e_tot [eV] & multipoles_on & tilt [rad] & y_pitch_tot [rad] \\
+ele_origin & num_steps & tilt_tot [rad] & z_offset [m] \\
+field_calc & offset [m] & tracking_method & z_offset_tot [m] \\
+field_master & offset_moves_aperture & type & \\
+field_overlaps & p0c [eV] & vkick & \\
+ \bottomrule
+ \end{tabular}
+ \vfill
+
  %---------------------------------
  \section{Wiggler and Undulator Element Attributes}
  \label{s:list.wiggler}