Partial doc upgrade for new funciton pointers for custom and hook ele…

…ments.

.gitignore

@@ -13,6 +13,7 @@ plplot
 xraylib
 gnu_utilities_src
 packages
+__pycache__
 .directoryhash
 
 # Jupyter notebooks
@@ -37,9 +38,8 @@ bmad-doc/tao_examples/csr_beam_tracking/csr_wake.dat
 
 tao/doc/tao.pdf
 bmad/doc/bmad.pdf
-bsim/**/doc/*.pdf
 util/searchf.pyc
-util/__pycache__
+bsim/**/doc/*.pdf
 
 **/doc/*.idx
 **/doc/*.ilg

bmad/custom/apply_element_edge_kick_hook.f90

@@ -1,10 +1,11 @@
 !+
 ! Subroutine apply_element_edge_kick_hook (orb, s_edge, t_rel, hard_ele, track_ele, param, finished, mat6, make_matrix, rf_time)
 !
-! Routine that can be customized to track through the edge field of an element.
-! This routine is always called by apply_element_edge_kick.
+! Prototype routine that can be customized to track through the edge field of an element.
+! When setup, this routine will be called by apply_element_edge_kick.
+! To use, see the Bmad manual.
 !
-! Note: apply element_edge_kick and this routine may or may not be called depending upon the setting of
+! Note: apply_element_edge_kick and this routine may or may not be called depending upon the setting of
 ! ele%tracking_method. In particular, this routine is *not* called if ele%tracking_method = custom$.
 !
 ! Input:

bmad/custom/check_aperture_limit_custom.f90

@@ -1,9 +1,11 @@
 !+
 ! Subroutine check_aperture_limit_custom (orb, ele, particle_at, param, err_flag)
 !
-! A non-dummy check_aperture_limit_custom routine is needed only if ele%aperture_type is set to custom$.
+! Prototype routine that can be setup to be called by check_aperture_limit.
+! Only needed if ele%aperture_type is set to custom$.
 ! Replace the dummy code below with a routine to check for aperture limits.
 !
+! To use, see the Bmad manual.
 ! Also: The routine distance_to_wall_custom needs to be replaced.
 !
 ! General rule: Your code may NOT modify any argument that is not listed as an output agument below."

bmad/custom/distance_to_aperture_custom.f90

@@ -4,10 +4,11 @@
 ! Replace this routine with a routine to calculate the percentage distance from the particle to the wall aperture.
 ! Distances are negative if the particle is inside the wall.
 !
-! A valid distance_to_aperture_custom routine is needed only if ele%aperture_type is set to custom$.
+! A distance_to_aperture_custom routine is needed only if ele%aperture_type is set to custom$.
 ! General rule: Your code may NOT modify any argument that is not listed as an output agument below."
 !
 ! This routine is called by distance_to_aperture.
+! To use, see the Bmad manual.
 !
 ! Input:
 !   orbit             -- coord_struct: Particle position.

bmad/custom/ele_geometry_hook.f90

@@ -2,7 +2,8 @@
 ! Subroutine ele_geometry_hook (floor0, ele, floor, finished, len_scale)
 !
 ! Routine that can be customized to calculate the floor position of an element.
-! This routine is always called by ele_geometry.
+! When setup, this routine is called by ele_geometry.
+! To use, see the Bmad manual.
 !
 ! This routine is useful, for example, to provide a way to calculate the orientation of a support
 ! structure that is, say, on a kinematic mount.

bmad/custom/ele_to_fibre_hook.f90

@@ -2,7 +2,8 @@
 ! Subroutine ele_to_fibre_hook (ele, ptc_fibre, param, use_offsets, err_flag)
 !
 ! Routine that can be customized for creating a PTC fibre from a Bmad element.
-! This routine is always called by ele_to_fibre.
+! When setup, this routine is called by ele_to_fibre.
+! To use, see the Bmad manual.
 !
 ! Input:
 !   ele             -- Ele_struct: Bmad element.

bmad/custom/em_field_custom.f90

@@ -3,8 +3,8 @@
 !                                     calc_potential, use_overlap, grid_allow_s_out_of_bounds, rf_time, used_eles)
 !
 ! Routine for handling custom (user supplied) EM fields.
-! This routine is called when ele%field_calc = custom$ or when ele is a custom element (ele%key = custom$)
-! In order to be used, this stub file must be modified appropriately. See the Bmad manual for more details.
+! When setup, this routine is called when ele%field_calc = custom$ or when ele is a custom element (ele%key = custom$)
+! See the Bmad manual for more details.
 !
 ! Note: Unlike all other elements, "s_rel" and "here" areguments for a patch element are with respect to 
 ! the exit reference frame of the element. See the Bmad manual for more details.

bmad/custom/init_custom.f90

@@ -1,17 +1,14 @@
 !+
 ! Subroutine init_custom (ele, err_flag)
 !
-! Dummy routine for initializing custom elements or elements that do custom
+! Prototype routine for initializing custom elements or elements that do custom
 ! calculations. Custom calculations are done if any one of the following
 ! ele_struct components is set to custom$:
 !   ele%tracking_method
 !   ele%mat6_calc_method
 !   ele%field_calc
 !   ele%aperture_type
 !
-! If called, this routine will do nothing.
-! This routine needs to be replaced for custom initialization.
-!
 ! Input:
 !   ele    -- Ele_struct: Element to init.
 !

bmad/custom/make_mat6_custom.f90

@@ -1,9 +1,8 @@
 !+
 ! Subroutine make_mat6_custom (ele, param, start_orb, end_orb, err_flag)
 !
-! Dummy routine for custom tracking. 
-! This routine needs to be replaced for a custom calculation.
-! If not replaced, and this routine is called, this routine will generate an error message.
+! Prototype routine for custom tracking. 
+! To use, see the Bmad manual.
 !
 ! General rule: Your code may NOT modify any argument that is not listed as
 ! an output agument below."

bmad/custom/radiation_integrals_custom.f90

@@ -1,7 +1,7 @@
 !+
 ! Subroutine radiation_integrals_custom (lat, ir, orb, rad_int1, err_flag)
 !
-! Dummy routine for custom elements. Will generate an error if called.
+! Prototype routine for custom elements. 
 ! A valid radiation_integrals_custom is needed only if the 
 ! radiation_integrals routine is being used.
 !

bmad/custom/time_runge_kutta_periodic_kick_hook.f90

@@ -1,7 +1,7 @@
 !+
 ! Subroutine time_runge_kutta_periodic_kick_hook (orbit, ele, param, stop_time, init_needed)
 !
-! Custom routine to add a kick to a particle at periodic times.
+! Prototype routine to add a kick to a particle at periodic times.
 !
 ! For example, this routine could be used to add the kick due to a passing beam
 ! on a residual gas ion that is being tracked.

bmad/custom/track1_bunch_hook.f90

@@ -1,7 +1,7 @@
 !+
 ! Subroutine track1_bunch_hook (bunch, ele, err, centroid, direction, finished, bunch_track)
 !
-! Routine that can be customized for tracking a bunch through a single element.
+! Prototype routine that can be customized for tracking a bunch through a single element.
 !
 ! Input:
 !   bunch          -- Bunch_struct: Starting bunch position.

bmad/custom/track1_custom.f90

@@ -1,15 +1,13 @@
 !+
 ! Subroutine track1_custom (orbit, ele, param, err_flag, finished, track)
 !
-! Dummy routine for custom tracking. 
-! This routine needs to be replaced for a custom calculation.
-! If not replaced and this routine is called, this routine will generate an error message.
+! Prototype routine for custom tracking. 
 !
 ! Also see:
 !   track1_preprocess
 !   track1_postprocess
 !
-! If this routine takes into account radiation damping and/or excitation when bmad_com%radiation_damping_on 
+! If this routine handles radiation damping and/or excitation when bmad_com%radiation_damping_on 
 ! and/or bmad_com%radiation_fluctuations_on is True, a custom version of track1_preprocess should be 
 ! constructed to set its radiation_included argument to True.
 ! If not, the track1 routine will use track1_radiation to include the radiation effects.

bmad/custom/track1_postprocess.f90

@@ -1,7 +1,8 @@
 !+
 ! Subroutine track1_postprocess (start_orb, ele, param, end_orb)
 !
-! Dummy routine for post processing after the track1 routine is done.
+! Prototype routine for post processing after the track1 routine is done.
+! To use, see the Bmad manual.
 !
 ! Also see:
 !   track1_preprocess

bmad/custom/track1_preprocess.f90

@@ -1,7 +1,8 @@
 !+
 ! Subroutine track1_preprocess (start_orb, ele, param, err_flag, finished, radiation_included, track)
 !
-! Dummy routine for pre-processing at the start of the track1 routine.
+! Prototype routine for pre-processing at the start of the track1 routine.
+! To use, see the Bmad manual.
 !
 ! Also see:
 !   track1_postprocess

bmad/custom/track1_spin_custom.f90

@@ -1,10 +1,9 @@
 !+
 ! Subroutine track1_spin_custom (start, ele, param, end, err_flag, make_quaternion)
 !
-! Dummy routine for custom spin tracking. 
-! This routine needs to be replaced for a custom calculation.
+! Prototype routine for custom spin tracking. 
 !
-! This routine is called if ele%spin_tracking_method = custom$
+! This routine will be called if ele%spin_tracking_method = custom$
 !
 ! Note: If ele%spin_tracking_method = tracking$, this routine is not called and
 ! spin tracking must be done with the phase space tracking in track1_custom.

bmad/custom/track1_wake_hook.f90

@@ -2,6 +2,7 @@
 ! Subroutine track1_wake_hook (bunch, ele, finished)
 !
 ! Routine that can be customized for tracking through a wake.
+! To use, see the Bmad manual.
 !
 ! Input:
 !   bunch       -- bunch_struct: Bunch of particles.

bmad/custom/track_many_hook.f90

@@ -2,8 +2,7 @@
 ! Subroutine track_many_hook (finished, lat, orbit, ix_start, ix_end, direction, ix_branch, track_state)
 !
 ! Routine that can be customized to track from one point in the lat to another.
-! This routine is always called by track_many. See the track_many documentation for details.
-! 
+! To use, see the Bmad manual.
 !
 ! Input:
 !   lat              -- lat_struct: Lat to track through.

bmad/doc/misc-programming.tex

@@ -8,42 +8,37 @@ \section{Custom and Hook Routines}
 \bmad calculations, like particle tracking through a lattice element, can be customized using what
 are called ``\vn{custom}'' and ``\vn{hook}'' routines. The general idea is that a programmer can
 implement custom code which is linked into a program and this custom code will be called at the
-appropriate time by \bmad. For example, custom code can be created for Runge-Kutta tracking
-that calculates the electromagnetic field of some complicated electromagnet.
+appropriate time by \bmad. For example, custom code can be created for Runge-Kutta tracking that
+calculates the electromagnetic field of some complicated electromagnet. Prototype custom and hook
+routines are available in the \vn{/bmad/custom} directory and are discussed in detail below.
+
+To enable \bmad to be able to call customized code, \vn{function pointers} are defined, one for each
+custom or hook routine. At certain places in the \bmad code, the appropriate function pointer will
+be checked. If the funtion pointer is associated with a routine, that routine will be called. By
+default, the function pointers are not associated with any functions.
+
+The function pointers are defined in the file \vn{/bmad/modules/bmad_routine_interface.f90}. The convention
+followed is that the abstract interface name has a \vn{_def} suffix and the function pointer name
+has a \vn{_ptr} suffix. For example, there is a \vn{track1_custom} routine prototype that is given
+in the in the file \vn{/bmad/custom/track1_custom.f90}. In \vn{/bmad/modules/bmad_routine_interface.f90} there
+are two interfaces for this routine. One interface defines the argument list for \vn{track1_custom} and the
+other (abstract) interface, defines the argement list for \vn{track1_custom_def} which is used to define
+the function pointer:
+\begin{example}
+  procedure(track1_custom_def), pointer :: track1_custom_ptr => null()
+\end{example}
+
+To implement custom code for, say, \vn{track1_custom}, copy the file \vn{/bmad/custom/track1_custom.f90}
+to the area where the program is
+
 
-To enable \bmad to be able to call customized code, there are a number of \vn{function pointers}
-defined in the \bmad code. A function pointer is defined one for each custom or hook routine. By
-default, these function pointers are not associated with any functions.  At certain places in the
-\bmad code, the appropriate function pointer will be checked. If the funtion pointer is associated
-with a routine, that routine will be called.
 
 \etcetc
 
-At each entry point, a ``\vn{dummy}'' version of a custom and hook
-routine is called. For \vn{hook} routines, this dummy version does nothing except to keep the linker
-happy when customized hook routine is not implemented by a program. For \vn{custom} routines, the
-dummy version will issue an error message since it should not have been called. That is, the
-difference between \vn{custom} and \vn{hook} routines is that the \vn{hook} routine is always called
-at the appropriate time without regard to the type of lattice element under consideration or what
-tracking method is being used. See below for more details.
 
 Note: Custom and Hook entry points are added to \bmad on an as-needed basis. If you have a need that
 is not met by the existing set of entry points, please contact a \bmad maintainer.
 
-Customization is done by copying the appropriate dummy routine to the same area where code files for
-the program to be customized are, modifying the dummy routine to do what you want it to do, and then
-relinking the program.
-
-Important: 
-\begin{itemize}
-\item
-Do not put the non-dummy version of a custom routine into a library that is linked to the
-program. This will generally result in the non-dummy version {\em not} being linked to.
-\item
-Do not modify directly any dummy routine in the \vn{bmad} directory. This is unnecessary
-and it complicates updating your local copy of the \bmad code as the \bmad code is
-developed over time.
-\end{itemize}
 
 While coding a custom routine, it is important to remember that it is {\em not} permissible to
 modify any routine argument that does not appear in the list of output arguments shown in the
@@ -83,10 +78,6 @@ \section{Custom Calculations}
 [Use \vn{getf} for more details about the argument lists for these
 routines.]  
 
-The dummy versions of these custom routines, if called, will print an error message and
-stop the program. The exception is the dummy \vn{init_custom} routine which will simply do
-nothing when called.
-
 \index{descrip}
 The \Hyperref{r:init.custom}{init_custom} routine is called by \Hyperref{r:bmad.parser}{bmad_parser}
 at the end of parsing for any lattice element that is a \vn{custom} element or has set any one of

bmad/multiparticle/beam_file_io.f90

@@ -17,13 +17,11 @@ module beam_file_io
 ! A '.h5' suffix will be appended to the created file if hdf5$ format is used and file_name does not
 ! already have a '.h5' or '.hdf5' suffix.
 !
-! The ASCII format is ASCII::4 except if cols is present. In this case ASCII::5 is used.
-!
 ! Input:
 !   file_name     -- character(*): Name of file.
 !   beam          -- beam_struct: Beam to write
 !   new_file      -- logical, optional: New file or append? Default = True.
-!   file_format   -- logical, optional: ascii$, or hdf5$ (default).
+!   file_format   -- logical, optional: ascii$, or hdf5$ (default). Experimental: ascii4$. 
 !   lat           -- lat_struct, optional: If present, lattice info will be writen to hdf5 files.
 !-
 

bsim/long_term_tracking/doc/long_term_tracking.tex

@@ -85,7 +85,7 @@
 
 \title{Long Term Tracking Program}
 \author{}
-\date{David Sagan \\ October 30, 2023}
+\date{David Sagan \\ November 2, 2023}
 
 \begin{document}
 \pdfbookmark[1]{Contents}{contents}
@@ -245,7 +245,9 @@
 final position of the particles. The \vn{"INDIVIDUAL"} mode is useful for the situation when there
 is ramping (\sref{s:ramp}) and individual are seeing different guide fields due to the time
 separation between particles. Specifically, the \vn{"INDIVIDUAL"} mode is useful for simulating
-resonant slow extraction.
+resonant slow extraction. The file name for the ending particle positions is set by
+\vn{ltt%phase_space_output_file} for ASCII output and \vn{ltt%beam_binary_output_file} for binary
+output.
 %
 \item["BEAM"] \Newline
 In this mode a particle beam is tracked for \vn{ltt%n_turns} turns. Beam statistics are recorded
@@ -876,9 +878,9 @@ \subsection{Output File Parameters}
 \Sref{s:beam.part.dat} for more details.
 %
 \item[ltt\%averages_output_file] \Newline
-Used with \vn{ltt%simulation_mode} set to \vn{"BEAM"}. 
-The \vn{ltt%averages_output_file} parameter sets the prefix used for the file names for the
-\vn{averages}, \vn{sigma} and \vn{emittance} data files (\sref{s:beam.ave.dat}).
+Used with \vn{ltt%simulation_mode} set to \vn{"BEAM"}.  The \vn{ltt%averages_output_file} parameter
+sets the prefix used for the file names for the \vn{averages}, \vn{sigma} and \vn{emittance} data
+files (\sref{s:beam.ave.dat}).
 %
 \item[ltt\%averages_output_every_n_turns] \Newline
 Sets the number of turns between data rows of data files specified by:
@@ -889,13 +891,14 @@ \subsection{Output File Parameters}
 For particle phase space output, use the \vn{particle_output_every_n_turns} parameter.
 %
 \item[ltt\%beam_binary_output_file] \Newline
-Used with \vn{ltt%simulation_mode} set to \vn{"BEAM"}. This parameter sets the name of the file that
-is created to hold particle positions. This is similar to \vn{ltt%phase_space_output_file} but here
-the file will be a binary file that is portable to other programs and can also be used as input to
-the \ltt program. A beam file will be created every \vn{ltt%beam_output_every_n_turns} turns if this
-quantity is positive. Additionally, a beam file will be produced at the end of tracking. A beam file
-will be given a suffix \vn{.NNNN.h5} where \vn{NNNN} is the turn number. To save disk space, every
-time a new beam file is created, if there is an old beam file it will be deleted. 
+Used with \vn{ltt%simulation_mode} set to \vn{"BEAM"} or \vn{"INDIVIDUAL"}. This parameter sets the
+name of the file that is created to hold particle positions. This is similar to
+\vn{ltt%phase_space_output_file} but here the file will be a binary file that is portable to other
+programs and can also be used as input to the \ltt program. wITH \vn{"BEAM"} mode, a beam file will
+be created every \vn{ltt%beam_output_every_n_turns} turns if this quantity is
+positive. Additionally, a beam file will be produced at the end of tracking. A beam file will be
+given a suffix \vn{.NNNN.h5} where \vn{NNNN} is the turn number. To save disk space, every time a
+new beam file is created, if there is an old beam file it will be deleted.
 
 To translate to ASCII, use the \vn{beam_file_translate_format} program. Documentation is in any Bmad
 Distribution in the file:
@@ -962,10 +965,11 @@ \subsection{Output File Parameters}
 instead of at the end.
 %
 \item[ltt\%phase_space_output_file] \Newline
-Used with \vn{ltt%simulation_mode} set to \vn{"BEAM"} or \vn{"SINGLE"}. The name of the ASCII file
-or files that are created to hold the particle positions. A file is created every
-\vn{ltt%particle_output_every_n_turns} turns. See Section~\sref{s:beam.part.dat} for more
-details. If \vn{ltt%phase_space_output_file} is blank, no particle output file is created.
+Used with \vn{ltt%simulation_mode} set to \vn{"BEAM"}, \vn{"INDIVIDUAL"} or \vn{"SINGLE"}. The name
+of the ASCII file or files that are created to hold the particle positions. A file is created every
+\vn{ltt%particle_output_every_n_turns} turns for the \vn{"BEAM"} simulation mode. See
+Section~\sref{s:beam.part.dat} for more details. If \vn{ltt%phase_space_output_file} is blank, no
+particle output file is created.
 %
 \item[ltt\%print_on_dead_loss] \Newline
 After each turn, the number of particles that are still living (have not hit an aperture) are

bsim/long_term_tracking/long_term_tracking_mpi.f90

@@ -218,7 +218,8 @@ program long_term_tracking
 
     ! And write data.
 
-    call ltt_write_particle_data (lttp, ltt_com, 0, beam)
+    if (lttp%per_particle_output_file /= '') call write_beam_file (lttp%per_particle_output_file, beam, .true., ascii4$)
+    if (lttp%beam_binary_output_file /= '')  call write_beam_file (lttp%beam_binary_output_file, beam, .true., hdf5$)
     call mpi_finalize(ierr)
 
   !---------------------------------------------------------