share/template/template_doc.c

   1 /*
   2  *
   3  *                This source code is part of
   4  *
   5  *                 G   R   O   M   A   C   S
   6  *
   7  *          GROningen MAchine for Chemical Simulations
   8  *
   9  * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
  10  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
  11  * Copyright (c) 2001-2009, The GROMACS development team,
  12  * check out http://www.gromacs.org for more information.
  13
  14  * This program is free software; you can redistribute it and/or
  15  * modify it under the terms of the GNU General Public License
  16  * as published by the Free Software Foundation; either version 2
  17  * of the License, or (at your option) any later version.
  18  *
  19  * If you want to redistribute modifications, please consider that
  20  * scientific software is very special. Version control is crucial -
  21  * bugs must be traceable. We will be happy to consider code for
  22  * inclusion in the official distribution, but derived work must not
  23  * be called official GROMACS. Details are found in the README & COPYING
  24  * files - if they are missing, get the official version at www.gromacs.org.
  25  *
  26  * To help us fund GROMACS development, we humbly ask that you cite
  27  * the papers on the package - you can find them in the top README file.
  28  *
  29  * For more info, check our website at http://www.gromacs.org
  30  */
  31 /*! \dir share/template
  32  * \brief Template code for writing analysis programs.
  33  */
  34 /*! \example template.c
  35  * \brief Template code for writing analysis programs.
  36  *
  37  * See \ref share/template/template.c "documentation" of the template for
  38  * more information.
  39  */
  40 /*! \file
  41  * \brief Doxygen documentation source for template.c.
  42  */
  43 /*! \file template.c
  44  * \brief Template code for writing analysis programs.
  45  *
  46  * The full source code for the file: \ref template.c "template.c"
  47  *
  48  * \dontinclude template.c
  49  *
  50  * \section global Global definitions
  51  *
  52  * We start by including some generic Gromacs headers
  53  * \until <xvgr.h>
  54  * and continue by including headers for the analysis library:
  55  * \until <trajana.h>
  56  * Here, we include just nbsearch.h that contains routines for performing
  57  * neighborhood searches for a set of positions.
  58  * Possibile additional header files include displacement.h and histogram.h;
  59  * see \ref include "the documentation of user header files".
  60  *
  61  * We then define a structure that holds data required during the analysis
  62  * in analyze_frame():
  63  * \until t_analysisdata;
  64  *
  65  *
  66  * \section analysis Frame analysis function
  67  *
  68  * We're now ready to define the function that (in most analysis codes) does
  69  * the main part of the work:
  70  * \until {
  71  * The topology can be accessed through \p top and the coordinates, box
  72  * size etc. through \p fr.
  73  * \p pbc can be used for periodic boundary calculations with, e.g., pbc_dx().
  74  * \p sel contains the selections defined by the user, containing both the
  75  * positions and the index groups that have been used to evaluate those.
  76  * The number of selections is available in \p nr.
  77  * The analysis should be written such that does not assume the selections to
  78  * have constant size.
  79  * The last parameter \p data points to our custom data (t_analysisdata), so we
  80  * first define a pointer that can be used to access the data:
  81  * \line t_analysisdata
  82  * Any changes made to the data through \p d can be accessed in later calls to
  83  * analyze_frame() as well as in the main function (gmx_template()).
  84  *
  85  * Here, we can do whatever calculations our program requires for a frame.
  86  * For the template, we first print the time for the current frame:
  87  * \skip  if (d->fp)
  88  * \until }
  89  * Then, we do a simple calculation:
  90  * \skip  nbsearch
  91  * \until }
  92  * \until }
  93  * \until }
  94  * \until }
  95  * After all the selections are processed, we print a newline to the output
  96  * file:
  97  * \skip  if (d->fp)
  98  * \until }
  99  * Finally, we return zero to indicate that all went well.
 100  * \skipline return 0;
 101  *
 102  *
 103  * \section gmx_template The main analysis tool
 104  *
 105  * We then define our main function in the same style as in Gromacs analysis
 106  * programs. We also provide a help text that can be shown with the \p -h
 107  * command-line option:
 108  * \skip  gmx_template
 109  * \until };
 110  *
 111  * Next, we define program-specific command-line arguments as in standard
 112  * Gromacs analysis programs:
 113  * \until };
 114  * Options for controlling the begin/end/skip of the trajectory are
 115  * automatically added, as are options for selections.
 116  * In the template, the second argument is for demonstartion purposes only;
 117  * it is not actually used.
 118  *
 119  * We also define the command-line options for output files:
 120  * \skip  t_filenm
 121  * \until NFILE
 122  * There should be no need to specify standard input files (trajectory,
 123  * topology, index), because they are automatically added and read in
 124  * by parse_trjana_args().
 125  * If you, however, define these file types with non-standard values, they
 126  * override the default values in parse_trjana_args().
 127  *
 128  * We then define some local variables:
 129  * \until gmx_ana_selection_t
 130  * The \p trj pointer holds internal data required for the library, and
 131  * can also be used to access topology information during initialization.
 132  * We also declare a t_analysisdata structure to hold data required in
 133  * analyze_frame(), as well as a few variables that will store information
 134  * about the selection that the user has provided.
 135  *
 136  * The actual code begins next. To follow the style of Gromacs tools, we
 137  * first print some information about the Gromacs build:
 138  * \skipline CopyRight
 139  *
 140  * Next, we initialize the \p trj pointer:
 141  * \skipline  gmx_ana_traj_create
 142  * We can use different flags to specify requirements for the selections and/or
 143  * other features of the library.
 144  * See \ref analysis_flags "Flags for gmx_ana_traj_create()".
 145  *
 146  * Next, we set some options:
 147  * \until nanagrps
 148  *
 149  * After initializing \p trj, we can call parse_trjana_args() to parse
 150  * command-line arguments and initialise the rest of the \p trj structure:
 151  * \skip  parse_trjana_args(trj,
 152  * \until oenv);
 153  *
 154  * After the call to parse_trjana_args(), all the command-line arguments are
 155  * available in the variables pointed by the \p pa array and can be used in
 156  * initialization.
 157  *
 158  * If you need to initialize the number of analysis groups
 159  * based on the command-line arguments, you can set \ref ANA_USER_SELINIT
 160  * and call gmx_ana_init_selections() separately.
 161  * Currently, the template does not demonstrate this to keep
 162  * it as simple as possible.
 163  *
 164  * After these calls, the program should perform any initialization that
 165  * is required before starting the analysis.
 166  * This can include allocating memory, precalculating things, preparing
 167  * output files and so on.
 168  * Any data that is required in the analysis of a single frame should be
 169  * put into \p d.
 170  * Data related to the selections, topology, and/or the first frame
 171  * can be accessed through \p trj; see the functions trajana.h.
 172  * For the template, we get the selection used as the reference positions
 173  * and the analysis groups using the following code:
 174  * \skip  gmx_ana_get_refsel
 175  * \until gmx_ana_get_anagrps
 176  * Notice that the reference selection is not included in the information
 177  * returned by the last two calls.
 178  *
 179  * For the template, we want to search the neighborhood of positions in
 180  * the first selection, so we initialize a neighborhood search.
 181  * This can be achieved with the following code:
 182  * \skip  nbsearch
 183  * \until }
 184  * Note that the calculation data is stored in \p d for it to be accessible in
 185  * analyze_frame().
 186  *
 187  * For the template, we also need some memory for calculating the average
 188  * distance for each index group, so we need to allocate it:
 189  * \skip  snew(d.ave
 190  * \until snew(d.n
 191  * We also open and prepare an output file for the data that is
 192  * written out during each frame:
 193  * \skip  d.fp
 194  * \until }
 195  *
 196  * Now we should be ready to do the actual loop over the frames.
 197  * This is accomplished by the function call
 198  * \skipline gmx_ana_do
 199  * This reads in each frame, updates the selections and calls analyze_frame()
 200  * for each frame.
 201  * All the initialized data (counters, file pointers, parameters etc.)
 202  * that is needed by the analysis (analyze_frame() in this case)
 203  * should be included in \p d.
 204  * Note that only the analysis groups are passed to analyze_frame();
 205  * the reference groups should be retrieved separately using
 206  * gmx_ana_get_refsel().
 207  * If this is not desired, one can also specify \ref ANA_USE_FULLGRPS to
 208  * include the reference groups to those passed to the analysis function.
 209  * Notice that this flag also changes the behavior of
 210  * gmx_ana_get_anagrps() and gmx_ana_get_grpnames().
 211  *
 212  * Finally, the analysis program probably needs to calculate and write out
 213  * some values such as averaged properties.
 214  * The template first closes the output file if one was opened
 215  * \skip  if (d.fp)
 216  * \until }
 217  * and then calculates and prints out the average distances for each analysis
 218  * group:
 219  * \skip  for (
 220  * \until }
 221  *
 222  * To follow the conventions of Gromacs tools, we finally print a (funny)
 223  * line
 224  * \skipline thanx
 225  * and return zero to indicate success.
 226  * \skipline return
 227  *
 228  *
 229  * \section main Definition of main()
 230  *
 231  * Now, the only thing remaining is to define the main() function.
 232  * It should simply call our gmx_template() function:
 233  * \skip int
 234  * \until }
 235  */