/*
* This file is part of the GROMACS molecular simulation package.
*
- * Copyright (c) 2007,2008,2009,2010,2011,2012,2013,2014, by the GROMACS development team, led by
+ * Copyright (c) 2007,2008,2009,2010,2011,2012,2013,2014,2015, by the GROMACS development team, led by
* Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
* and including many others, as listed in the AUTHORS file in the
* top-level source directory and at http://www.gromacs.org.
int gmx_spatial(int argc, char *argv[])
{
const char *desc[] = {
- "[THISMODULE] calculates the spatial distribution function and ",
- "outputs it in a form that can be read by VMD as Gaussian98 cube format. ",
- "For a system of 32,000 atoms and a 50 ns trajectory, the SDF can be generated ",
- "in about 30 minutes, with most of the time dedicated to the two runs through ",
- "[TT]trjconv[tt] that are required to center everything properly. ",
- "This also takes a whole bunch of space (3 copies of the trajectory file). ",
- "Still, the pictures are pretty and very informative when the fitted selection is properly made. ",
- "3-4 atoms in a widely mobile group (like a free amino acid in solution) works ",
- "well, or select the protein backbone in a stable folded structure to get the SDF ",
- "of solvent and look at the time-averaged solvation shell. ",
- "It is also possible using this program to generate the SDF based on some arbitrary ",
- "Cartesian coordinate. To do that, simply omit the preliminary [gmx-trjconv] steps. \n",
- "USAGE: \n",
- "1. Use [gmx-make_ndx] to create a group containing the atoms around which you want the SDF \n",
- "2. [TT]gmx trjconv -s a.tpr -f a.tng -o b.tng -boxcenter tric -ur compact -pbc none[tt] \n",
- "3. [TT]gmx trjconv -s a.tpr -f b.tng -o c.tng -fit rot+trans[tt] \n",
- "4. run [THISMODULE] on the [TT]c.tng[tt] output of step #3. \n",
- "5. Load [TT]grid.cube[tt] into VMD and view as an isosurface. \n",
- "[BB]Note[bb] that systems such as micelles will require [TT]gmx trjconv -pbc cluster[tt] between steps 1 and 2\n",
- "WARNINGS:[BR]",
- "The SDF will be generated for a cube that contains all bins that have some non-zero occupancy. ",
- "However, the preparatory [TT]-fit rot+trans[tt] option to [gmx-trjconv] implies that your system will be rotating ",
- "and translating in space (in order that the selected group does not). Therefore the values that are ",
- "returned will only be valid for some region around your central group/coordinate that has full overlap ",
- "with system volume throughout the entire translated/rotated system over the course of the trajectory. ",
- "It is up to the user to ensure that this is the case. \n",
- "BUGS:[BR]",
- "When the allocated memory is not large enough, a segmentation fault may occur. This is usually detected ",
- "and the program is halted prior to the fault while displaying a warning message suggesting the use of the [TT]-nab[tt] (Number of Additional Bins)",
- "option. However, the program does not detect all such events. If you encounter a segmentation fault, run it again ",
- "with an increased [TT]-nab[tt] value. \n",
- "RISKY OPTIONS:[BR]",
- "To reduce the amount of space and time required, you can output only the coords ",
- "that are going to be used in the first and subsequent run through [gmx-trjconv]. ",
- "However, be sure to set the [TT]-nab[tt] option to a sufficiently high value since ",
- "memory is allocated for cube bins based on the initial coordinates and the [TT]-nab[tt] ",
- "option value. \n"
+ "[THISMODULE] calculates the spatial distribution function and",
+ "outputs it in a form that can be read by VMD as Gaussian98 cube format.",
+ "For a system of 32,000 atoms and a 50 ns trajectory, the SDF can be generated",
+ "in about 30 minutes, with most of the time dedicated to the two runs through",
+ "[TT]trjconv[tt] that are required to center everything properly.",
+ "This also takes a whole bunch of space (3 copies of the trajectory file).",
+ "Still, the pictures are pretty and very informative when the fitted selection is properly made.",
+ "3-4 atoms in a widely mobile group (like a free amino acid in solution) works",
+ "well, or select the protein backbone in a stable folded structure to get the SDF",
+ "of solvent and look at the time-averaged solvation shell.",
+ "It is also possible using this program to generate the SDF based on some arbitrary",
+ "Cartesian coordinate. To do that, simply omit the preliminary [gmx-trjconv] steps.",
+ "",
+ "Usage:",
+ "",
+ "1. Use [gmx-make_ndx] to create a group containing the atoms around which you want the SDF",
+ "2. [TT]gmx trjconv -s a.tpr -f a.tng -o b.tng -boxcenter tric -ur compact -pbc none[tt]",
+ "3. [TT]gmx trjconv -s a.tpr -f b.tng -o c.tng -fit rot+trans[tt]",
+ "4. run [THISMODULE] on the [TT]c.tng[tt] output of step #3.",
+ "5. Load [TT]grid.cube[tt] into VMD and view as an isosurface.",
+ "",
+ "[BB]Note[bb] that systems such as micelles will require [TT]gmx trjconv -pbc cluster[tt] between steps 1 and 2.",
+ "",
+ "Warnings",
+ "^^^^^^^^",
+ "",
+ "The SDF will be generated for a cube that contains all bins that have some non-zero occupancy.",
+ "However, the preparatory [TT]-fit rot+trans[tt] option to [gmx-trjconv] implies that your system will be rotating",
+ "and translating in space (in order that the selected group does not). Therefore the values that are",
+ "returned will only be valid for some region around your central group/coordinate that has full overlap",
+ "with system volume throughout the entire translated/rotated system over the course of the trajectory.",
+ "It is up to the user to ensure that this is the case.",
+ "",
+ "Risky options",
+ "^^^^^^^^^^^^^",
+ "",
+ "To reduce the amount of space and time required, you can output only the coords",
+ "that are going to be used in the first and subsequent run through [gmx-trjconv].",
+ "However, be sure to set the [TT]-nab[tt] option to a sufficiently high value since",
+ "memory is allocated for cube bins based on the initial coordinates and the [TT]-nab[tt]",
+ "option value."
+ };
+ const char *bugs[] = {
+ "When the allocated memory is not large enough, a segmentation fault may occur. This is usually detected "
+ "and the program is halted prior to the fault while displaying a warning message suggesting the use of the [TT]-nab[tt] (Number of Additional Bins) "
+ "option. However, the program does not detect all such events. If you encounter a segmentation fault, run it again "
+ "with an increased [TT]-nab[tt] value."
};
static gmx_bool bPBC = FALSE;
/* This is the routine responsible for adding default options,
* calling the X/motif interface, etc. */
if (!parse_common_args(&argc, argv, PCA_CAN_TIME | PCA_CAN_VIEW,
- NFILE, fnm, asize(pa), pa, asize(desc), desc, 0, NULL, &oenv))
+ NFILE, fnm, asize(pa), pa, asize(desc), desc, asize(bugs), bugs, &oenv))
{
return 0;
}
"",
"At present, three input modes are supported.",
"",
- " * With option [TT]-it[tt], the user provides a file which contains the",
- " file names of the umbrella simulation run-input files ([REF].tpr[ref] files),",
- " AND, with option [TT]-ix[tt], a file which contains file names of",
- " the pullx [TT]mdrun[tt] output files. The [REF].tpr[ref] and pullx files must",
- " be in corresponding order, i.e. the first [REF].tpr[ref] created the",
- " first pullx, etc.",
- " * Same as the previous input mode, except that the the user",
- " provides the pull force output file names ([TT]pullf.xvg[tt]) with option [TT]-if[tt].",
- " From the pull force the position in the umbrella potential is",
- " computed. This does not work with tabulated umbrella potentials.",
- " * With option [TT]-ip[tt], the user provides file names of (gzipped) [REF].pdo[ref] files, i.e.",
- " the GROMACS 3.3 umbrella output files. If you have some unusual"
- " reaction coordinate you may also generate your own [REF].pdo[ref] files and",
- " feed them with the [TT]-ip[tt] option into to [THISMODULE]. The [REF].pdo[ref] file header",
- " must be similar to the following::",
+ "* With option [TT]-it[tt], the user provides a file which contains the",
+ " file names of the umbrella simulation run-input files ([REF].tpr[ref] files),",
+ " AND, with option [TT]-ix[tt], a file which contains file names of",
+ " the pullx [TT]mdrun[tt] output files. The [REF].tpr[ref] and pullx files must",
+ " be in corresponding order, i.e. the first [REF].tpr[ref] created the",
+ " first pullx, etc.",
+ "* Same as the previous input mode, except that the the user",
+ " provides the pull force output file names ([TT]pullf.xvg[tt]) with option [TT]-if[tt].",
+ " From the pull force the position in the umbrella potential is",
+ " computed. This does not work with tabulated umbrella potentials.",
+ "* With option [TT]-ip[tt], the user provides file names of (gzipped) [REF].pdo[ref] files, i.e.",
+ " the GROMACS 3.3 umbrella output files. If you have some unusual"
+ " reaction coordinate you may also generate your own [REF].pdo[ref] files and",
+ " feed them with the [TT]-ip[tt] option into to [THISMODULE]. The [REF].pdo[ref] file header",
+ " must be similar to the following::",
"",
- " # UMBRELLA 3.0",
- " # Component selection: 0 0 1",
- " # nSkip 1",
- " # Ref. Group 'TestAtom'",
- " # Nr. of pull groups 2",
- " # Group 1 'GR1' Umb. Pos. 5.0 Umb. Cons. 1000.0",
- " # Group 2 'GR2' Umb. Pos. 2.0 Umb. Cons. 500.0",
- " #####",
+ " # UMBRELLA 3.0",
+ " # Component selection: 0 0 1",
+ " # nSkip 1",
+ " # Ref. Group 'TestAtom'",
+ " # Nr. of pull groups 2",
+ " # Group 1 'GR1' Umb. Pos. 5.0 Umb. Cons. 1000.0",
+ " # Group 2 'GR2' Umb. Pos. 2.0 Umb. Cons. 500.0",
+ " #####",
"",
- " The number of pull groups, umbrella positions, force constants, and names ",
- " may (of course) differ. Following the header, a time column and ",
- " a data column for each pull group follows (i.e. the displacement",
- " with respect to the umbrella center). Up to four pull groups are possible ",
- " per [REF].pdo[ref] file at present.",
+ " The number of pull groups, umbrella positions, force constants, and names ",
+ " may (of course) differ. Following the header, a time column and ",
+ " a data column for each pull group follows (i.e. the displacement",
+ " with respect to the umbrella center). Up to four pull groups are possible ",
+ " per [REF].pdo[ref] file at present.",
"",
"By default, all pull groups found in all pullx/pullf files are used in WHAM. If only ",
"some of the pull groups should be used, a pull group selection file (option [TT]-is[tt]) can ",
"",
"By default, the output files are",
"",
- " * [TT]-o[tt] PMF output file",
- " * [TT]-hist[tt] Histograms output file",
+ "* [TT]-o[tt] PMF output file",
+ "* [TT]-hist[tt] Histograms output file",
"",
"Always check whether the histograms sufficiently overlap.[PAR]",
"The umbrella potential is assumed to be harmonic and the force constants are ",
"read from the [REF].tpr[ref] or [REF].pdo[ref] files. If a non-harmonic umbrella force was applied ",
- "a tabulated potential can be provided with [TT]-tab[tt].[PAR]",
- "WHAM OPTIONS[BR]------------[BR]",
+ "a tabulated potential can be provided with [TT]-tab[tt].",
"",
- " * [TT]-bins[tt] Number of bins used in analysis",
- " * [TT]-temp[tt] Temperature in the simulations",
- " * [TT]-tol[tt] Stop iteration if profile (probability) changed less than tolerance",
- " * [TT]-auto[tt] Automatic determination of boundaries",
- " * [TT]-min,-max[tt] Boundaries of the profile",
+ "WHAM options",
+ "^^^^^^^^^^^^",
+ "",
+ "* [TT]-bins[tt] Number of bins used in analysis",
+ "* [TT]-temp[tt] Temperature in the simulations",
+ "* [TT]-tol[tt] Stop iteration if profile (probability) changed less than tolerance",
+ "* [TT]-auto[tt] Automatic determination of boundaries",
+ "* [TT]-min,-max[tt] Boundaries of the profile",
"",
"The data points that are used to compute the profile",
"can be restricted with options [TT]-b[tt], [TT]-e[tt], and [TT]-dt[tt]. ",
"periodicity of the system and generate a periodic PMF. The first and the last bin of the",
"reaction coordinate will assumed be be neighbors.[PAR]",
"Option [TT]-sym[tt] symmetrizes the profile around z=0 before output, ",
- "which may be useful for, e.g. membranes.[PAR]",
- "PARALLELIZATION[BR]----------------[BR]",
- "If available, the number of OpenMP threads used by g_wham is controlled with [TT]-nt[tt].[PAR]",
- "AUTOCORRELATIONS[BR]----------------[BR]",
+ "which may be useful for, e.g. membranes.",
+ "",
+ "Parallelization",
+ "^^^^^^^^^^^^^^^",
+ "",
+ "If available, the number of OpenMP threads used by g_wham is controlled with [TT]-nt[tt].",
+ "",
+ "Autocorrelations",
+ "^^^^^^^^^^^^^^^^",
+ "",
"With [TT]-ac[tt], [THISMODULE] estimates the integrated autocorrelation ",
"time (IACT) [GRK]tau[grk] for each umbrella window and weights the respective ",
"window with 1/[1+2*[GRK]tau[grk]/dt]. The IACTs are written ",
"less robust) method such as fitting to a double exponential, you can ",
"compute the IACTs with [gmx-analyze] and provide them to [THISMODULE] with the file ",
"[TT]iact-in.dat[tt] (option [TT]-iiact[tt]), which should contain one line per ",
- "input file ([REF].pdo[ref] or pullx/f file) and one column per pull group in the respective file.[PAR]",
- "ERROR ANALYSIS[BR]--------------[BR]",
+ "input file ([REF].pdo[ref] or pullx/f file) and one column per pull group in the respective file.",
+ "",
+ "Error analysis",
+ "^^^^^^^^^^^^^^",
+ "",
"Statistical errors may be estimated with bootstrap analysis. Use it with care, ",
"otherwise the statistical error may be substantially underestimated. ",
"More background and examples for the bootstrap technique can be found in ",
"Four bootstrapping methods are supported and ",
"selected with [TT]-bs-method[tt].",
"",
- " * [TT]b-hist[tt] Default: complete histograms are considered as independent ",
- " data points, and the bootstrap is carried out by assigning random weights to the ",
- " histograms (\"Bayesian bootstrap\"). Note that each point along the reaction coordinate",
- " must be covered by multiple independent histograms (e.g. 10 histograms), otherwise the ",
- " statistical error is underestimated.",
- " * [TT]hist[tt] Complete histograms are considered as independent data points. ",
- " For each bootstrap, N histograms are randomly chosen from the N given histograms ",
- " (allowing duplication, i.e. sampling with replacement).",
- " To avoid gaps without data along the reaction coordinate blocks of histograms ",
- " ([TT]-histbs-block[tt]) may be defined. In that case, the given histograms are ",
- " divided into blocks and only histograms within each block are mixed. Note that ",
- " the histograms within each block must be representative for all possible histograms, ",
- " otherwise the statistical error is underestimated.",
- " * [TT]traj[tt] The given histograms are used to generate new random trajectories,",
- " such that the generated data points are distributed according the given histograms ",
- " and properly autocorrelated. The autocorrelation time (ACT) for each window must be ",
- " known, so use [TT]-ac[tt] or provide the ACT with [TT]-iiact[tt]. If the ACT of all ",
- " windows are identical (and known), you can also provide them with [TT]-bs-tau[tt]. ",
- " Note that this method may severely underestimate the error in case of limited sampling, ",
- " that is if individual histograms do not represent the complete phase space at ",
- " the respective positions.",
- " * [TT]traj-gauss[tt] The same as method [TT]traj[tt], but the trajectories are ",
- " not bootstrapped from the umbrella histograms but from Gaussians with the average ",
- " and width of the umbrella histograms. That method yields similar error estimates ",
- " like method [TT]traj[tt].",
+ "* [TT]b-hist[tt] Default: complete histograms are considered as independent ",
+ " data points, and the bootstrap is carried out by assigning random weights to the ",
+ " histograms (\"Bayesian bootstrap\"). Note that each point along the reaction coordinate",
+ " must be covered by multiple independent histograms (e.g. 10 histograms), otherwise the ",
+ " statistical error is underestimated.",
+ "* [TT]hist[tt] Complete histograms are considered as independent data points. ",
+ " For each bootstrap, N histograms are randomly chosen from the N given histograms ",
+ " (allowing duplication, i.e. sampling with replacement).",
+ " To avoid gaps without data along the reaction coordinate blocks of histograms ",
+ " ([TT]-histbs-block[tt]) may be defined. In that case, the given histograms are ",
+ " divided into blocks and only histograms within each block are mixed. Note that ",
+ " the histograms within each block must be representative for all possible histograms, ",
+ " otherwise the statistical error is underestimated.",
+ "* [TT]traj[tt] The given histograms are used to generate new random trajectories,",
+ " such that the generated data points are distributed according the given histograms ",
+ " and properly autocorrelated. The autocorrelation time (ACT) for each window must be ",
+ " known, so use [TT]-ac[tt] or provide the ACT with [TT]-iiact[tt]. If the ACT of all ",
+ " windows are identical (and known), you can also provide them with [TT]-bs-tau[tt]. ",
+ " Note that this method may severely underestimate the error in case of limited sampling, ",
+ " that is if individual histograms do not represent the complete phase space at ",
+ " the respective positions.",
+ "* [TT]traj-gauss[tt] The same as method [TT]traj[tt], but the trajectories are ",
+ " not bootstrapped from the umbrella histograms but from Gaussians with the average ",
+ " and width of the umbrella histograms. That method yields similar error estimates ",
+ " like method [TT]traj[tt].",
"",
"Bootstrapping output:",
"",
- " * [TT]-bsres[tt] Average profile and standard deviations",
- " * [TT]-bsprof[tt] All bootstrapping profiles",
+ "* [TT]-bsres[tt] Average profile and standard deviations",
+ "* [TT]-bsprof[tt] All bootstrapping profiles",
"",
"With [TT]-vbs[tt] (verbose bootstrapping), the histograms of each bootstrap are written, ",
"and, with bootstrap method [TT]traj[tt], the cumulative distribution functions of ",
biod.pnpi.spb.ru / alexxy / gromacs.git / commitdiff