New long_term_tracking parameter: ltt%ramp_particle_energy_without_rf.

bmad/code/lat_ele_locator.f90

@@ -18,8 +18,10 @@
 !                 If a name and no branch is given, all branches are searched.
 !                 If an index and no branch is given, branch 0 is assumed.
 !   ##N       -- N = integer. N^th instance of ele_id in the branch.
-!   +/-offset -- Element offset. For example, "Q1+1" is the element after "Q1" and 
-!                 "Q1-2" is the second element before "Q1".
+!   +/-offset -- Element offset. For example, "Q1+1" is the element after "Q1" and "Q1-2" is the second element 
+!                 before "Q1". Modulo arithmatic is used so the offset wraps around the ends of the lattice. 
+!                 EG: "BEGINNING-1" gives the END element and "END+1" gives the BEGINNING element.
+!                     
 ! Note: An old syntax that is still supported is:
 !   {key::}{branch>>}ele_id{##N}
 !

bsim/bbu/README.TXT

@@ -64,7 +64,7 @@ Note: the output files will be stored in the working directory at which python3
        -------------------------------------------------------
        Command:  python $DIST_BASE_DIR/bsim/bbu/test_run.py  PHASE_X  PHASE_Y
        -------------------------------------------------------
-       Obtain (Ith v.s. tr/tb) for a lattice with two free phases (with coupled or decoupled optics)
+       Obtain (Ith versus tr/tb) for a lattice with two free phases (with coupled or decoupled optics)
        Phase advances are changed via a Taylor element in the lattice, named talylorW.
        The correct Twiss parameters must be extracted from the lattice and set in phase_scan.py.
        Output file: thresh_v_phase_PHASE.txt  (produced at where it's called)

bsim/long_term_tracking/doc/long_term_tracking.tex

@@ -85,7 +85,7 @@
 
 \title{Long Term Tracking Program}
 \author{}
-\date{David Sagan \\ August 13, 2024}
+\date{David Sagan \\ September 6, 2024}
 
 \begin{document}
 \pdfbookmark[1]{Contents}{contents}
@@ -465,6 +465,14 @@
 unnormalized strength \vn{B1_gradient} will remain fixed and normalized \vn{k1} will vary
 inversely with the reference momentum.
 
+\ltt program parameters that affect ramping in the simulation are:
+\begin{code}
+ltt%ramping_start_time              -- Default 0.
+ltt%ramping_on                      -- Default False.
+ltt%ramp_update_each_particle       -- Default False.
+ltt%ramp_particle_energy_without_rf -- Default False.
+\end{code}
+
 There are two modes that can be selected to determine how ramper elements are applied. If using
 \vn{"BEAM"} mode, and if\vn{ltt%ramp_update_each_particle} is set to True, rampers are applied to a
 given lattice element as each particle of the beam passes through the element using the time the
@@ -487,21 +495,30 @@
 If \vn{ltt%ramping_on} is set to True, ramping will be done if \vn{ltt%simulation_mode} is set to
 "\vn{BEAM}" or "\vn{SINGLE}". Ramping will be ignored in the other modes.
 
-\ltt program parameters that affect ramping in the simulation are:
-\begin{code}
-ltt%ramping_on
-ltt%ramping_start_time
-\end{code}
-
 When ramping, the \vn{ltt%simulation_mode} (\sref{s:track.methods}) must be set to "\vn{BMAD}". The
 program will detect if there is a conflict and issue an error message and stop.
 
+Normally, when the reference energy \vn{E_tot} or the reference momentum \vn{p0c} is varied by a
+ramper element, the phase space $p_z$ of the particles are adjusted in tandem to keep the particle
+momentum $(1 + pz) * p0c$ invariant. This also keeps the particle energy invariant. This mirrors
+what is actually happening in a machine: It is the energy kick in the RF cavities that makes particles
+change energy, not the change in field strengths that result from changing the reference energy.
+The RF kick will result in synchrotron oscillations. For some simulations, it is useful to see what
+would happen if the synchrotron oscillations were magically ``turned off''.
+This unphysical simulation can be done by turning off the RF in the lattice and by setting
+\begin{code}
+ltt%ramp_particle_energy_without_rf = True
+\end{code}
+When this is set, the $p_z$ of the particles are {\em not} adjusted when the reference energy is
+adjusted. And since the RF is off, $p_z$ will be an invariant and there are no synchrotron
+oscillations.
+
 The \vn{ltt%ix_turn_start} parameter can be used to start tracking at any turn. This can be useful if a
 simulation is accidentally interrupted. In this case the beam positions can be saved by setting
 \begin{code}
-  ltt%beam_output_file
-  ltt%beam_output_every_n_turns
-  ltt%output_only_last_turns
+ltt%beam_output_file
+ltt%beam_output_every_n_turns
+ltt%output_only_last_turns
 \end{code}
 
 With ramping, the concept of the closed orbit (possibly needed to initialize particle positions) is
@@ -696,6 +713,7 @@
   ltt%lat_file   =  "lat.bmad"       ! Bmad lattice file
   ltt%ramping_on = F
   ltt%ramp_update_each_particle = F
+  ltt%ramp_particle_energy_without_rf = F
   ltt%ramping_start_time        = 0
   ltt%extraction_method         = ""
   ltt%simulation_mode           = "BEAM"
@@ -876,6 +894,10 @@ \subsection{Simulation Parameters}
 the \ltt program will additionally impose a 0.9~meters aperture independent of the setting of
 \vn{ltt%ptc_aperture}.
 %
+\item[ltt\%ramp_particle_energy_without_rf] \Newline
+Simulate the unphysical situation where particle energy moves in tandem with the reference energy?
+See \sref{s:ramp} for more details.
+%
 \item[ltt\%ramp_update_each_particle] \Newline
 Default is False which means only apply rampers to a given lattice element once per beam passage
 (\sref{s:ramp}). This parameter is only used for \vn{"BEAM"} mode.

bsim/modules/lt_tracking_mod.f90

@@ -83,6 +83,7 @@ module lt_tracking_mod
   logical :: only_live_particles_out = .true.
   logical :: ramping_on = .false.
   logical :: ramp_update_each_particle = .false.
+  logical :: ramp_particle_energy_without_rf = .false.
   logical :: rfcavity_on = .true.
   logical :: add_closed_orbit_to_init_position = .true.
   logical :: symplectic_map_tracking = .false.
@@ -906,6 +907,7 @@ subroutine ltt_write_preheader(iu, lttp, ltt_com, print_this)
 call ltt_write_line('# ltt%ramping_on                          = ' // logic_str(lttp%ramping_on), lttp, iu, print_this)
 call ltt_write_line('# ltt%output_combined_bunches             = ' // logic_str(lttp%output_combined_bunches), lttp, iu, print_this)
 call ltt_write_line('# ltt%ramp_update_each_particle           = ' // logic_str(lttp%ramp_update_each_particle), lttp, iu, print_this)
+call ltt_write_line('# ltt%ramp_particle_energy_without_rf     = ' // logic_str(lttp%ramp_particle_energy_without_rf), lttp, iu, print_this)
 call ltt_write_line('# ltt%ramping_start_time                  = ' // real_str(lttp%ramping_start_time, 6), lttp, iu, print_this)
 call ltt_write_line('# ltt%set_beambeam_z_crossing             = ' // logic_str(lttp%set_beambeam_z_crossing), lttp, iu, print_this)
 call ltt_write_line('# ltt%random_seed                         = ' // int_str(lttp%random_seed), lttp, iu, print_this)
@@ -2318,6 +2320,7 @@ subroutine ltt_write_params_header(lttp, ltt_com, iu, n_particle, n_bunch)
 write (iu,  '(a, i8)')   '# n_turns                             = ', lttp%n_turns
 write (iu,  '(a, l1)')   '# ramping_on                          = ', lttp%ramping_on
 write (iu,  '(a, l1)')   '# ramp_update_each_particle           = ', lttp%ramp_update_each_particle
+write (iu,  '(a, l1)')   '# ramp_particle_energy_without_rf     = ', lttp%ramp_particle_energy_without_rf
 write (iu,  '(2a)')      '# ramping_start_time                  = ', real_str(lttp%ramping_start_time, 6)
 write (iu,  '(a, i8)')   '# particle_output_every_n_turns       = ', lttp%particle_output_every_n_turns
 write (iu,  '(a, i8)')   '# averages_output_every_n_turns       = ', lttp%averages_output_every_n_turns
@@ -3438,7 +3441,10 @@ subroutine ltt_track1_bunch_hook (bunch, ele, err, centroid, direction, finished
   r = orb%p0c / ele%value(p0c_start$)
   orb%vec(2) = r * orb%vec(2)
   orb%vec(4) = r * orb%vec(4)
-  orb%vec(6) = r * orb%vec(6) + (orb%p0c - ele%value(p0c_start$)) / ele%value(p0c_start$)
+  ! Normally need to adjust pz (vec(6)) so that the particle energy (1 + orb%vec(6)) * orb%p0c is not changed.
+  if (.not. ltt_params_global%ramp_particle_energy_without_rf) then
+    orb%vec(6) = r * orb%vec(6) + (orb%p0c - ele%value(p0c_start$)) / ele%value(p0c_start$)
+  endif
   orb%p0c = ele%value(p0c_start$)
 enddo
 
@@ -3537,7 +3543,10 @@ subroutine ltt_track1_preprocess (start_orb, ele, param, err_flag, finished, rad
 r = start_orb%p0c / ele%value(p0c_start$)
 start_orb%vec(2) = r * start_orb%vec(2)
 start_orb%vec(4) = r * start_orb%vec(4)
-start_orb%vec(6) = r * start_orb%vec(6) + (start_orb%p0c - ele%value(p0c_start$)) / ele%value(p0c_start$)
+! Normally need to adjust pz (vec(6)) so that the particle energy (1 + orb%vec(6)) * orb%p0c is not changed.
+if (.not. ltt_params_global%ramp_particle_energy_without_rf) then
+  start_orb%vec(6) = r * start_orb%vec(6) + (start_orb%p0c - ele%value(p0c_start$)) / ele%value(p0c_start$)
+endif
 start_orb%p0c = ele%value(p0c_start$)
 
 end subroutine ltt_track1_preprocess

tao/version/tao_version_mod.f90

@@ -6,5 +6,5 @@
 !-
 
 module tao_version_mod
-character(*), parameter :: tao_version_date = "2024/08/28 21:24:21"
+character(*), parameter :: tao_version_date = "2024/09/04 22:30:30"
 end module