better documentation and headers

Author: Michael Ehrlichman

bsim/touschek_background/doc/touschek_background.tex

@@ -186,6 +186,164 @@ \section{Input Parameters}
 &end
 \end{example}
 
+\section{Output Parameters}
+Descriptions of output files generated by \vn{touschek_background}.
+
+\subsection{\vn{collimator_profile.out}}
+The \vn{.in} files contains a \vn{test_collimator} parameter that is a radius in units meters.
+For each element between a location where a Touschek particle is generated and where it is lost,
+the program tests if the Touschek particle trajectory exceeds \vn{test_collimator}.  If it does,
+then the number of particles represented by the Touschek particle is added to running tally kept 
+at that element.
+
+This data can be used to determine where in the lattice a collimator should be placed so as to capture the most
+Touschek particles.
+
+Header:
+\begin{verbatim}
+#     slice   location   potential N    element name                           
+#     index        (s)        caught                       
+\end{verbatim}
+
+\subsection{\vn{energy_deposited_at_s.out}}
+Records the amount of energy deposited by Touschek particles colliding with the physical aperture
+at each location.
+
+This data can be used to determine radiation backgrounds.
+Header: 
+\begin{verbatim}
+#      slice   location   nrg deposited at         cumulative
+#      index        (m)    slice per bunch                nrg
+#                                     (eV)               (eV)
+\end{verbatim}
+
+\subsection{\vn{generation_pipe.out}}
+Records the number of Touschek particles generated at each location which are destined
+to be lost to colliding with the beampipe, as opposed to those Touschek particles which
+are lost due to stopping during deceleration.  This distinction is important for energy
+recovery linacs.
+
+Header:
+\begin{verbatim}
+#     slice   location    N generated   cumulative N
+#     index        (s)       at slice      generated
+\end{verbatim}
+
+\subsection{\vn{generation_stop.out}}
+Records the number of Touschek particles generated at each location which are destined
+to be lost to stopping during deceleration, as opposed to those Touschek particles which
+are lost due to colliding with the beampipe.  This distinction is important for energy
+recovery linacs.
+
+Header:
+\begin{verbatim}
+#     slice   location    N generated   cumulative N
+#     index        (s)       at slice      generated
+\end{verbatim}
+
+\subsection{\vn{Npart_striking_pipe_by_s.out}}
+Records the number of Touschek particles colliding with the beampipe at each location.
+
+Header:
+\begin{verbatim}
+#      slice   location     N deposited at       cumulative N
+#      index        (s)    slice per bunch                   
+\end{verbatim}
+
+\subsection{\vn{Npart_stopping_with_no_energy_by_s.out}}
+Records the number of Touschek particles stopping at each slice due deceleration.
+
+Header:
+\begin{verbatim}
+#      slice   location     N deposited at       cumulative N
+#      index        (s)    slice per bunch                   
+\end{verbatim}
+
+\subsection{\vn{Npart_total_losses_by_s.out}}
+Records the number of Touschek particles lost at each slice, counting
+both those particles that stop due to deceleration and those that collide with the
+beampipe.
+
+Header:
+\begin{verbatim}
+#      slice   location     N deposited at       cumulative N
+#      index        (s)    slice per bunch                   
+\end{verbatim}
+
+\subsection{\vn{physical_aperture_from_track.out}}
+The physical apertures in the lattice that was tracked through.
+
+Header:
+\begin{verbatim}
+#       ele     location     aperture   element name         
+#     index          (s)       radius                 
+\end{verbatim}
+
+\subsection{\vn{raw_rates.out}}
+This is the rate of Touschek particles scattered above the positive momentum aperture
+and below the negative momentum aperture for each location in the lattice.
+It is essentially, the Touschek formula evaluated at the given location
+at the momentum aperture for that location.
+
+Header:
+\begin{verbatim}
+#   slice    location     positive aperture     negative aperture
+#   index         (s)    rate (N/bunch/sec)    rate (N/bunch/sec)
+\end{verbatim}
+
+\subsection{\vn{sigma_matrix.out}}
+The matrix of second order moments of all the Touschek particles
+passing through each location in the lattice.
+
+Header:
+\begin{verbatim}
+# Slice     Location        Cov(x,x)       Cov(x,px)        Cov(x,y)   ...
+# index            m             m^2               m             m^2   ...
+#    row number:                   1               1               1   ...
+# column number:                   1               2               3   ...
+\end{verbatim}
+
+\subsection{\vn{sigma_p.out}}
+The energy spread at each location in the lattice after taking 
+intrabeam scattering into account.
+
+Header:
+\begin{verbatim}
+#  location       sigma_p    Total energy
+#       (s)       (dp/p0)            (eV)
+\end{verbatim}
+
+\subsection{\vn{slice_index_from_track.out}}
+The slice index assigned to each location in the lattice that was tracked
+through.
+
+Header:
+\begin{verbatim}
+#     slice      location   element
+#     index           (s)   name
+\end{verbatim}
+
+\subsection{\vn{touschek_track.details}}
+Compiled statistics from the Touschek tracking simulation.
+
+\vn{Halo}: Was halo tracking enabled?\\
+\vn{Number of data points:}  Number of samples of the Touschek formula per slice.\\
+\vn{Number of test particles:}  Number of test particles used to represent the \\
+distribution of Touschek particles at each slice.\\
+\vn{Total Integrated current (\#e-):}  Total number of Touschek particles generated.\\
+\vn{Beam Pipe Collisions:}  Total number of particles lost due to collision \\
+with the physical aperture.\\
+\vn{Zero Energy in Linac:}  Total number of particles lost due to stopping during \\
+deceleration.\\
+\vn{Energy deposited into beam pipe (eV):}  Total energy in eV deposited into the \\
+beampipe due by Touschek particles.\\
+\vn{Number of test particles:}  Total number of test particles generated \\
+and tracked.\\
+\vn{Number lost to beam pipe:}  Number of test particles lost to beam \\
+pipe collisions.\\
+\vn{Number lost to zero energy:}   Number of test particles stopped during \\
+deceleration.\\
+
 %------------------------------------------------------------------
 
 \begin{thebibliography}{9}

bsim/touschek_background/touschek_background.f90

@@ -1401,7 +1401,8 @@ PROGRAM touschek_background
   OPEN(77, FILE="energy_deposited_at_s.out")
   accumulator = 0.
   WRITE(77,'(A61)') "#      slice   location   nrg deposited at         cumulative"
-  WRITE(77,'(A61)') "#      index        (s)    slice per bunch                nrg"
+  WRITE(77,'(A61)') "#      index        (m)    slice per bunch                nrg"
+  WRITE(77,'(A61)') "#                                     (eV)               (eV)"
   DO i=slix_lost_start, slix_lost_end
     accumulator = accumulator + energy_deposited_at_slice(i)
     WRITE(77,'(I12,F11.3,2ES19.4)') i, slices(i), energy_deposited_at_slice(i), accumulator
@@ -1460,22 +1461,22 @@ PROGRAM touschek_background
   !- Write generation profile files
   !-----------------------------------------------------------------------
   OPEN(18,FILE="generation_pipe.out")
-    WRITE(18,'(A52)') "      slice   location    N generated   cumulative N"
-    WRITE(18,'(A52)') "      index        (s)       at slice      generated"
+    WRITE(18,'(A52)') "#     slice   location    N generated   cumulative N"
+    WRITE(18,'(A52)') "#     index        (s)       at slice      generated"
     DO i=slix_prod_start, slix_prod_end
       WRITE(18,'(I11,F11.3,ES15.4,ES15.4)') i, slices(i), generation_at_slice(i)%pipe_this_slice, generation_at_slice(i)%pipe_cumulative
     ENDDO
   CLOSE(18)
   OPEN(19,FILE="generation_stop.out")
-    WRITE(19,'(A52)') "      slice   location    N generated   cumulative N"
-    WRITE(19,'(A52)') "      index        (s)       at slice      generated"
+    WRITE(19,'(A52)') "#     slice   location    N generated   cumulative N"
+    WRITE(19,'(A52)') "#     index        (s)       at slice      generated"
     DO i=slix_prod_start, slix_prod_end
       WRITE(19,'(I11,F11.3,ES15.4,ES15.4)') i, slices(i), generation_at_slice(i)%stop_this_slice, generation_at_slice(i)%stop_cumulative
     ENDDO
   CLOSE(19)
   OPEN(19,FILE="raw_rates.out")
-    WRITE(19,'(A65)') "    slice    location     positive aperture     negative aperture"
-    WRITE(19,'(A65)') "    index         (s)    rate (N/bunch/sec)    rate (N/bunch/sec)"
+    WRITE(19,'(A65)') "#   slice    location     positive aperture     negative aperture"
+    WRITE(19,'(A65)') "#   index         (s)    rate (N/bunch/sec)    rate (N/bunch/sec)"
     DO i=slix_prod_start, slix_prod_end
       WRITE(19,'(I9,F12.3,ES22.4E3,ES22.4E3)') i, slices(i), raw_scattering_rates(i,1), raw_scattering_rates(i,2)
     ENDDO