diff --git a/bmad/doc/cover-page.tex b/bmad/doc/cover-page.tex index 81d71530be..efc767ffa2 100644 --- a/bmad/doc/cover-page.tex +++ b/bmad/doc/cover-page.tex @@ -3,7 +3,7 @@ \begin{flushright} \large - Revision: November 1, 2023 \\ + Revision: November 4, 2023 \\ \end{flushright} \pdfbookmark[0]{Preamble}{Preamble} diff --git a/bmad/doc/misc-programming.tex b/bmad/doc/misc-programming.tex index 7720a79901..40d00e8641 100644 --- a/bmad/doc/misc-programming.tex +++ b/bmad/doc/misc-programming.tex @@ -15,15 +15,14 @@ \section{Custom and Hook Routines} 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: +default, the function pointers are not associated with any functions and the only way there will be +an association by user code modification. + +The function pointers are defined in the file \vn{/bmad/modules/bmad_routine_interface.f90}. The +convention followed is that for any given custom or hook routine there is a base name, for example, +\vn{track1_custom}, and in \vn{bmad_routine_interface.f90} there will be an abstract interface which +with the base name with a \vn{_def} suffix (\vn{track1_custom_def} for this example). Additionally +the corresponding function pointer uses a \vn{_ptr} suffix and is defined like: \begin{example} procedure(track1_custom_def), pointer :: track1_custom_ptr => null() \end{example} @@ -32,27 +31,45 @@ \section{Custom and Hook Routines} \begin{itemize} % \item -copy the file \vn{/bmad/custom/track1_custom.f90} to the area where the program is to be compiled. +Copy the file \vn{/bmad/custom/track1_custom.f90} to the area where the program is to be compiled. % \item -Code desired, - - - -\etcetc - - -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. - +Customize file as desired. The name of the routine can be changed if desired as long as that name is used +consistently throughout the program. In fact, multiple custom +routines can be created and switched in and out as desired in the program. +% +\item +In the program define an interface for the custom routine like: +\begin{example} + procedure(track1_custom_def) :: track1_custom +\end{example} +Note: If the custom routine has been put in a module this will not be needed. +% +\item +Somewhere near the beginning of the program (generally before \vn{bmad_parser} is called), set the +function pointer to point to your custom routine: +\begin{example} + track_custom_ptr => track1_custom +\end{example} +% +\item +If needed modify the compile script(s) (typically named something like ``cmake.XXX'') to compile the +file the custom routine is in. +% +\item +Compile the program using the \vn{mk} command. +% +\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 comment section at the top of the file. -Note: Remember to modify the appropriate compile script file (typically named something like -``cmake.XXX'') so that any routines that you have added to your program area are compiled and -linked. +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. + +Note: The custom and hook routines in \vn{/bmad/custom/} are not compiled with the \bmad library. Their +only purpose is to surve as prototypes for code development. %----------------------------------------------------------------------------- \section{Custom Calculations} diff --git a/tao/doc/cover-page.tex b/tao/doc/cover-page.tex index 8458d2d1f0..e5f47e6452 100644 --- a/tao/doc/cover-page.tex +++ b/tao/doc/cover-page.tex @@ -2,7 +2,7 @@ \begin{flushright} \large -Revision: October 28, 2023 \\ +Revision: November 4, 2023 \\ \end{flushright} \vfill diff --git a/tao/doc/customization.tex b/tao/doc/customization.tex index 147899e51d..a131ef3227 100644 --- a/tao/doc/customization.tex +++ b/tao/doc/customization.tex @@ -52,12 +52,13 @@ \section{Initial Setup} \begin{example} \vn{ROOT/production/bin/custom_tao}. \end{example} -Similarly, the command \vn{mkd} will create a debug executable +If a debug executable is wanted, the command \vn{mkd} will create one at: \begin{example} \vn{ROOT/debug/bin/custom_tao} \end{example} \end{enumerate} -A debug executable only needs to be created if you a debugging the code. +A debug executable is only needed if you are debugging the code. The debug exe will run much +slower than the production version. %---------------------------------------------------------------- \section{It's All a Matter of Hooks} @@ -68,12 +69,29 @@ \section{It's All a Matter of Hooks} these files, copy it from \vn{tao/hook} to \vn{ROOT} and then make modifications to the copy. The reason for this golden rule is to ensure that, as time goes by, and revisions are made to the -\tao routines to extend it's usefulness and to eliminate bugs, these changes will have a minimum +\tao routines to extend \tao's usefulness and to eliminate bugs, these changes will have a minimum impact on the specialized routines you write. What happens if the modification you want to do cannot be accomplished by customizing a hook routine? The answer is to contact the \tao programming team and we will modify \tao and provide the hooks you need so that you can then do your customization. +%---------------------------------------------------------------- +\section{Implementing a Hook Routine in Tao} + +Function pointers are used by \tao to call customized hook routines. \tao uses the same system as \bmad +where an abstract interface with a \vn{_def} suffix in the name is defined along with a function +pointer with a \vn{_ptr} suffix. See the section ``Custom and Hook Routines'' in the \bmad manual +for more details. For example, the \vn{tao_hook_command} routine has the function pointer (defined +in \vn{/tao/code/tao_interface.f90}): +\begin{example} + procedure(tao_hook_command_def), pointer :: tao_hook_command_ptr => null() +\end{example} +To use a customized \vn{tao_hook_command} routine, the following can be put in the +\vn{tao_program.f90} that was copied to your area: +\begin{example} + tao_hook_command_ptr => tao_hook_command +\end{example} + %---------------------------------------------------------------- \section{Initializing Hook Routines}