New match element parameter: spin_tracking_model. (#1165)

* New match element parameter: spin_tracking_model.

bmad/code/track1.f90

@@ -226,7 +226,10 @@ recursive subroutine track1 (start_orb, ele, param, end_orb, track, err_flag, ig
  call track1_bmad_photon (end_orb, ele, param, err)
  else
  call track1_bmad (end_orb, ele, param, err, track, mat6 = ele%mat6, make_matrix = make_map1)
- if (ele%key == beambeam$) do_spin_tracking = .false.
+
+ select case (ele%key)
+ case (beambeam$); do_spin_tracking = .false.
+ end select
  endif
  if (err) return
 

bmad/doc/attributes.tex

@@ -2987,7 +2987,7 @@ \subsection{Short-Range Wakes}
  trailing ! Depends linearly on the trailing particle position.
 \end{example}
 
-The \vn{z_max} component of \vn{sr_wake} specifies the the maximum $z$ value at which the pseudo
+The \vn{z_max} component of \vn{sr_wake} specifies the maximum $z$ value at which the pseudo
 mode fit is valid. The \vn{z_max} component is optional and if present and \vn{positive}, \bmad will
 check that the distance between particles does not exceed \vn{z_max}. If it does, \bmad will report
 an error. If \vn{z_max} is not positive it is ignored.

bmad/doc/charged-tracking.tex

@@ -746,7 +746,7 @@ \section{Converter Tracking}
 orientation of the outgoing particle. The outgoing particle distribution is pre-computed by a
 program \vn{converter_element_modeling} and the distribution parameters are included in the
 converter element description in the \bmad lattice file (\sref{s:converter}). The accuracy of the
-converter modeling will depend in part upon the granularity of the the probability tables generated
+converter modeling will depend in part upon the granularity of the probability tables generated
 by the \vn{converter_element_modeling} program and on other approximations made during
 tracking. Generally, inaccuracies in the 1\% to 10\% range are to be expected.
 

bmad/doc/coordinates.tex

@@ -669,7 +669,7 @@ \section{Transformation Between Laboratory and Element Body Coordinates}
 
 When tracking a particle through an element, the particle starts at the \vn{nominal}
 (\sref{s:coords.3}) upstream end of the element with the particle's position expressed in laboratory
-coordinates. Tracking from the the nominal upstream end to the actual upstream face of the element
+coordinates. Tracking from the nominal upstream end to the actual upstream face of the element
 involves first transforming to element body coordinates (with $s = 0$ in the equations below) and
 then propagating the particle as in a field free drift space from the particle's starting position
 to the actual element face. Depending upon the element's orientation, this tracking may involve

bmad/doc/electromagnetic-fields.tex

@@ -921,7 +921,7 @@ \section{RF fields}
 \label{s:rf.fields}
 \index{RF fields|hyperbf}
 
-The following describes the how RF fields are calculated when the the \vn{field_calc}
+The following describes the how RF fields are calculated when the \vn{field_calc}
 attribute of an RF element is set to \vn{bmad_standard}.\footnote
  {
 Notice that the equations here are only relavent with the \vn{tracking_method} for an RF element set

bmad/doc/elements.tex

@@ -695,7 +695,7 @@ \section{Bends: Rbend and Sbend}
  exit_end ! The exit point is the fiducial point.
 \end{example}
 With \vn{fiducial_pt} set to \vn{none} (the default). The bend shape is not held constant. With the
-other three settings, the bend shape will be help constant as discussed in \sref{s:bend.fiducial}.
+other three settings, the bend shape will be held constant as discussed in \sref{s:bend.fiducial}.
 With \vn{fiducial_pt} set to \vn{entrance_end}, the reference trajectory at the entrance end is held
 fixed in both position and orientation with respect to the bend face and \vn{g}, \vn{l} and \vn{e2},
 along with the other depdendent parameters, are adjusted to both give the desired change in what was
@@ -752,7 +752,7 @@ \section{Bends: Rbend and Sbend}
 For compatibility with MAD, for an \vn{rbend}, \vn{l} is the chord length and not the arc length as
 it is for an \vn{sbend}. After reading in a lattice, \bmad will internally convert all \vn{rbend}s
 into \vn{sbend}s, and the \vn{l_chord} attribute of the created \vn{sbend} will be set to the input
-\vn{l}. The \vn{l} of the the created \vn{sbend} will be set to the true path length (see
+\vn{l}. The \vn{l} of the created \vn{sbend} will be set to the true path length (see
 above). Alternatively for an \vn{rbend}, instead of setting \vn{l}, the \vn{l_arc} attribute can be
 used to set the true arc length. 
 
@@ -3455,7 +3455,7 @@ \section{Match}
  delta_time = <Real> ! Change in time.
  matrix = <Switch> ! Matrix calculation. Default: standard.
  kick0 = <Switch> ! Zeroth order calc. Default: standard.
- spin_tracking  = <Switch> ! Spin tracking done?
+ spin_tracking_model = <Switch> ! How to track the spin?
  recalc = <Logical> ! Calculate transfer map? Default is True.
 \end{example}
 
@@ -3605,21 +3605,23 @@ \section{Match}
 a finite \vn{delta_time} can be confusing, such a situation is not allowed. Use two separate
 \vn{match} elements if needed.
 
-The settings of \vn{spin_tracking} are:
+The settings of \vn{spin_tracking_model} are:
 \begin{example}
- off ! Spin is invariant through a match element.
- on ! Spin is tracked assuming not bends.
+ off  ! Spin direction does not change (default).
+ transverse_field ! Assumes a transverse magnetic field.
 \end{example}
-With a setting of \vn{on}, it is assumed that the orbital transfer matrix is due solely to transverse
+With a setting of \vn{off} (the default), the spin does not change when a particle is tracked through the element.
+With a setting of \vn{transverse_field}, it is assumed that the orbital transfer matrix is due solely to transverse
 magnetic fields so that the integrated spin rotation (\Eqs{orpt}, \eq{pqlbp1}, and \eq{pqlbp2}) can
 be related to the orbital transport via
 \begin{equation}
- \int {\pmb\Omega}_{BMT} = \frac{\beta}{1 + p_z} \, (1 + a \gamma) \, (-\Delta p_y, \Delta p_x, 0)
-\end{equation} 
-
+ \int {\pmb\Omega}_{BMT} = \frac{1 + a \gamma}{1 + p_z} \, (-\Delta p_y, \Delta p_x, 0)
+\end{equation}
+where $\Delta p_x$ and $\Delta p_y$ are the change in $p_x$ and $p_y$ when tracking through the match element
+and the small angle approximation ($p_x, p_y \ll 1$) has been used.
 
 A \vn{match} element that is ``turned off'' (\vn{is_on} attribute set to False), is considered to be
-like a \vn{marker} element. That is, the orbit and Twiss parameters are unchanged when tracking
+like a \vn{marker} element. That is, the orbit, spin, and Twiss parameters are unchanged when tracking
 through a \vn{match} element that is turned off.
 
 \index{l}
@@ -3866,7 +3868,7 @@ \section{Octupole}
 %-----------------------------------------------------------------------------
 \section{Overlay}
 \label{s:overlay}
-\index{ovlerlay|hyperbf}
+\index{overlay|hyperbf}
 
 \vn{Overlay} elements are a type of \vn{control} element (\sref{s:lord.slave}) used to make
 variations in the attributes of other elements (called ``slave'' attributes) while a program is
@@ -4490,7 +4492,7 @@ \section{Quadrupole}
 %-----------------------------------------------------------------------------
 \section{Ramper}
 \label{s:ramper}
-\index{ovlerlay|hyperbf}
+\index{overlay|hyperbf}
 
 A \vn{ramper} element is a type of \vn{control} element (\sref{s:lord.slave}). That is, a
 \vn{ramper} element can be used to make variations in the attributes of other elements while a

bmad/doc/list-element-attributes.tex

@@ -862,23 +862,23 @@ \chapter{List of Element Attributes}
 
  \begin{tabular}{llll} \toprule
 alias & c22_mat1 & l [m] & spin_tracking_method \\
-alpha_a0 & create_jumbo_slave & mat6_calc_method & superimpose  \\
-alpha_a1 & delta_ref_time [sec] & matrix & tracking_method \\
-alpha_b0 & delta_time [sec] & mode_flip0 & type  \\
-alpha_b1 & descrip & mode_flip1 & wrap_superimpose \\
-aperture [m] & dphi_a [rad] & offset [m] & x0 [m]  \\
-aperture_at & dphi_b [rad] & offset_moves_aperture & x1 [m] \\
-aperture_type & e_tot [eV] & p0c [eV] & x1_limit [m] \\
-beta_a0 [m] & ele_origin & ptc_integration_type & x2_limit [m] \\
-beta_a1 [m] & eta_x0 [m] & px0 & x_limit [m]  \\
-beta_b0 [m] & eta_x1 [m] & px1 & y0 [m]  \\
-beta_b1 [m] & eta_y0 [m] & py0 & y1 [m] \\
-c11_mat0 & eta_y1 [m] & py1 & y1_limit [m] \\
-c11_mat1 & etap_x0 & pz0 & y2_limit [m] \\
-c12_mat0 [m] & etap_x1 & pz1 & y_limit [m]  \\
-c12_mat1 [m] & etap_y0 & recalc & z0 [m]  \\
-c21_mat0 [1/m] & etap_y1 & ref_origin & z1 [m] \\
-c21_mat1 [1/m] & is_on & ref_time_start [sec] &   \\
+alpha_a0 & create_jumbo_slave & mat6_calc_method & spin_tracking_model \\
+alpha_a1 & delta_ref_time [sec] & matrix & superimpose  \\
+alpha_b0 & delta_time [sec] & mode_flip0 & tracking_method \\
+alpha_b1 & descrip & mode_flip1 & type  \\
+aperture [m] & dphi_a [rad] & offset [m] & wrap_superimpose \\
+aperture_at & dphi_b [rad] & offset_moves_aperture & x0 [m] \\
+aperture_type & e_tot [eV] & p0c [eV] & x1 [m]  \\
+beta_a0 [m] & ele_origin & ptc_integration_type & x1_limit [m] \\
+beta_a1 [m] & eta_x0 [m] & px0 & x2_limit [m] \\
+beta_b0 [m] & eta_x1 [m] & px1 & x_limit [m] \\
+beta_b1 [m] & eta_y0 [m] & py0 & y0 [m] \\
+c11_mat0 & eta_y1 [m] & py1 & y1 [m]  \\
+c11_mat1 & etap_x0 & pz0 & y1_limit [m] \\
+c12_mat0 [m] & etap_x1 & pz1 & y2_limit [m] \\
+c12_mat1 [m] & etap_y0 & recalc & y_limit [m] \\
+c21_mat0 [1/m] & etap_y1 & ref_origin & z0 [m] \\
+c21_mat1 [1/m] & is_on & ref_time_start [sec] & z1 [m] \\
 c22_mat0 & kick0 & reference & \\
  \bottomrule
  \end{tabular}

bmad/doc/multiparticle.tex

@@ -447,7 +447,7 @@ \subsection{Slice Space Charge Calculation}
 where $\zeta$ is the longitudinal distance between the kick point and the slice doing the kicking.
 There are two simulation modes for the longitudinal SC kick. In both these modes, the kick is
 evaluated at the center plane of each slice. The kick is a sum kicks from all the slices. Since the
-thickness of the slices is, in general, not negligible, the the integral over a slice is used to
+thickness of the slices is, in general, not negligible, the integral over a slice is used to
 calculate the kick. The total kick $K_{\mbox{\tiny SC}}(j)$ at slice $j$ is
 \begin{equation}
  K_{\mbox{\tiny SC}} (j) = 

bmad/doc/multipass.tex

@@ -227,7 +227,7 @@ \section{The Reference Energy in a Multipass Line}
 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.
+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.

bmad/doc/simulation-modules.tex

@@ -43,7 +43,7 @@ \subsection{Orbit Measurement}
 \end{equation}
 where the Gaussian random numbers $r_1$ and $r_2$ are centered at zero and have unit width and the
 factor $n_f$ represents the inherent noise in the measurement. In the above equation, $(x, y)_0$ 
-represents a measurement offset and $\bfM_g$ is a ``gain'' matrix writen in the form
+represents a measurement offset and $\bfM_g$ is a ``gain'' matrix written in the form
 \begin{equation}
  \bfM_m
  =
@@ -56,7 +56,7 @@ \subsection{Orbit Measurement}
 Here $dg_x$ and $dg_y$ represent gain errors and the angles $\theta$ and $\psi$ are tilt and 
 ``crunch'' errors.
 
-In the above equations, various quantities are writen as a difference between an ``error'' quantity
+In the above equations, various quantities are written as a difference between an ``error'' quantity
 and a ``calibration'' quantity:
 \begin{alignat}{1}
  x_0 &= x_{\text{off}} - x_{\text{calib}} \CRNO

bmad/doc/spin.tex

@@ -351,7 +351,7 @@ \section{Polarization Limits and Polarization/Depolarization Rates}
  \label{tbks}
 \end{equation}
 
-If the the stochastic excitation of the beam is taken into account, the generalized Sokolov-Ternov
+If the stochastic excitation of the beam is taken into account, the generalized Sokolov-Ternov
 polarization is called the \vn{Derbenev-Kondratenko} formula
 \begin{equation}
  P_{dk} = \pm \frac{8}{5 \, \sqrt{3}}
@@ -388,7 +388,7 @@ \section{Polarization Limits and Polarization/Depolarization Rates}
  \label{tdk}
 \end{equation}
 $\tau_{pol}^{-1}$ is the polarization rate given by the first two terms on the
-RHS in \Eq{t583} and the depolarization rate $\tau_{dep}^{-1}$ is given by the the third term:
+RHS in \Eq{t583} and the depolarization rate $\tau_{dep}^{-1}$ is given by the third term:
 \begin{align}
  \tau_{pol}^{-1} &= \frac{5 \, \sqrt{3}}{8} \frac{r_e \, \gamma^5 \, \hbar}{m} \frac{1}{C} \,
  \oint ds \, \left< g^3 \, \left( 1 - \frac{2}{9} (\bfn \dotproduct \what\bfs)^2 \right) \right> 

bmad/doc/superposition.tex

@@ -677,7 +677,7 @@ \section{The Reference Energy in a Multipass Line}
 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.
+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.

bmad/doc/tracking.tex

@@ -45,7 +45,7 @@ \section{The coord_struct}
 \item{Propagation Direction} \Newline
 The ``\vn{propagation direction}'' is the direction that a particle will be propagated in during
 tracking. The propagation direction will be in the same direction as the direction of travel when
-propagating a particle forward in time and will be opposite the the direction of travel when
+propagating a particle forward in time and will be opposite the direction of travel when
 propagating a particle backwards in time.
 %
 \item{Reverse Tracking} \Newline

bmad/low_level/track_a_match.f90

@@ -20,11 +20,12 @@ subroutine track_a_match (orbit, ele, param, err_flag, mat6, make_matrix)
 
 implicit none
 
-type (coord_struct) :: orbit
+type (coord_struct) :: orbit, start_orb
 type (ele_struct), target :: ele
 type (lat_param_struct) :: param
+type (em_field_struct) field
 
-real(rp) xmat(6,6), vec0(6), z0, beta0, dt
+real(rp) xmat(6,6), vec0(6), z0, beta0, dt, fc, dxp, dyp, om(3), quat(0:3)
 real(rp), optional :: mat6(6,6)
 
 logical, optional :: make_matrix
@@ -33,6 +34,7 @@ subroutine track_a_match (orbit, ele, param, err_flag, mat6, make_matrix)
 
 !
 
+start_orb = orbit
 call match_ele_to_mat6 (ele, orbit, xmat, vec0, err, include_delta_time = .false.)
 if (err) then
  ! Since there are cases where this error may be raised many times, do not print an error message.

bmad/modules/attribute_mod.f90

@@ -1291,6 +1291,7 @@ subroutine init_attribute_name_array ()
 call init_attribute_name1 (match$, c21_mat1$, 'C21_MAT1')
 call init_attribute_name1 (match$, c22_mat1$, 'C22_MAT1')
 call init_attribute_name1 (match$, mode_flip1$, 'MODE_FLIP1')
+call init_attribute_name1 (match$, spin_tracking_model$, 'SPIN_TRACKING_MODEL')
 
 call init_attribute_name1 (pickup$, num_steps$, 'NUM_STEPS')
 call init_attribute_name1 (pickup$, ds_step$, 'DS_STEP')
@@ -1945,7 +1946,7 @@ function attribute_type (attrib_name, ele) result (attrib_type)
  'SPATIAL_DISTRIBUTION', 'ENERGY_DISTRIBUTION', 'VELOCITY_DISTRIBUTION', 'KEY', 'SLAVE_STATUS', &
  'LORD_STATUS', 'PHOTON_TYPE', 'ELE_ORIGIN', 'REF_ORIGIN', 'CSR_METHOD', 'SPACE_CHARGE_METHOD', &
  'MULTIPASS_REF_ENERGY', 'REF_SPECIES', 'SPECIES_OUT', 'DISTRIBUTION', 'LATTICE_TYPE', &
- 'SPECIES_STRONG', 'SCATTER_METHOD', 'FIDUCIAL_PT')
+ 'SPECIES_STRONG', 'SCATTER_METHOD', 'FIDUCIAL_PT', 'SPIN_TRACKING_MODEL')
  attrib_type = is_switch$
 
 case ('TYPE', 'ALIAS', 'DESCRIP', 'SR_WAKE_FILE', 'LR_WAKE_FILE', 'LATTICE', 'PHYSICAL_SOURCE', &
@@ -2498,6 +2499,12 @@ function switch_attrib_value_name (attrib_name, attrib_value, ele, is_default, n
  is_default = (ix_attrib_val == off$)
  endif
 
+case ('SPIN_TRACKING_MODEL')
+ call get_this_attrib_name (attrib_val_name, ix_attrib_val, spin_tracking_model_name, lbound(spin_tracking_model_name, 1), name_list)
+ if (present(is_default)) then
+ is_default = (ix_attrib_val == off$)
+ endif
+
 case ('SPATIAL_DISTRIBUTION')
  call get_this_attrib_name (attrib_val_name, ix_attrib_val, distribution_name, lbound(distribution_name, 1), name_list)
  if (present(is_default)) is_default = (ix_attrib_val == gaussian$)