| blob | c7dd970317561f02ae5dcae59217a91612ed8152 |
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.
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 */