Analyse

The pmx analyse script can be used to analyse the xvg output from Gromacs. Effectively, it allows to perform all the steps described in the API example and more using a convenient command line tool.

$ pmx analyse -h
usage: pmx [-h] -fA dgdl [dgdl ...] -fB dgdl [dgdl ...]
   [-m method [method ...]] [-t temperature] [-o result file]
   [-b nboots] [-n nblocks] [--integ_only] [-iA work input]
   [-iB work input] [-oA work output] [-oB work output] [--reverseB]
   [--skip  | --slice   | --rand  | --index  [...]] [--prec] [--units]
   [--pickle] [--no_ks] [--cgi_plot] [--nbins] [--dpi] [--quiet]

Calculates free energies from fast growth thermodynamic integration
simulations. Available methods for free energy estimation: Crooks Gaussian
Intersection (CGI); Benett Acceptance Ratio (BAR); Jarzinski equality (JARZ).

optional arguments:
-h, --help            show this help message and exit
-fA dgdl [dgdl ...]   dgdl.xvg files for the A->B simulations. Use wildcard
                      to select multiple xvg files: e.g. "-fa
                      ./forward_results/dgdl*.xvg"
-fB dgdl [dgdl ...]   dgdl.xvg files for the B->A simulations Use wildcard
                      to select multiple xvg files: e.g. "-fb
                      ./backward_results/dgdl*.xvg"
-m method [method ...]
                      Choose one or more estimators to use from the
                      available ones: CGI, BAR, JARZ. Default is all.
-t temperature        Temperature in Kelvin. Default is 298.15.
-o result file        Filename of output result file. Default is
                      "results.txt."
-b nboots             Number of bootstrap samples to use for the bootstrap
                      estimate of the standard errors. Default is 0 (no
                      bootstrap).
-n nblocks            Number of blocks to divide the data into for an
                      estimate of the standard error. You can use this when
                      multiple independent equilibrium simulationshave been
                      run so to estimate the error from the repeats. Default
                      is 1 (i.e. no repeats). It assumes the dgdl files for
                      each repeat are read in order and are contiguous, e.g.
                      dgdl_0 to dgdl_9 is the first repeat, dgdl_10 to
                      dgdl_19 is the second one, etc.
-w plot               Name of image file showing the distribution of work
                      values. Default is "wplot.png". If you want to avoid
                      saving this plot, pass "none" to this flag. If you
                      choose to calculate the free energy with multiple
                      estimators, the dG values shown on the plot will be
                      chosen following the hierarchy BAR > CGI > JARZ.
--nbins               Number of histograms bins for the plot. Default is 20.
--dpi                 Resolution of the plot. Default is 300.
--reverseB            Whether to reverse the work values for the backward
                      (B->A) transformation. This is useful when in Gromacs
                      both forward and reverse simulations were run from
                      lambda zero to one. Default is False.
--integ_only          Whether to do integration only; the integrated values
                      are computed and saved, and the program terminated.
                      Default is False.
-iA work input        Two-column dat file containing the list of input files
                      and their respective integrated work values for the
                      forward (A->B) tranformation.
-iB work input        Two-column dat file containing the list of input files
                      and their respective integrated work values for the
                      reverse (B->A) tranformation.
-oA work output       File where to save the list of input dgdl files and
                      their respective integrated work values for the
                      forward (A->B) tranformation. Default is "integA.dat"
-oB work output       File where to save the list of input dgdl files and
                      their respective integrated work values for the
                      reverse (B->A) tranformation. Default is "integB.dat"
--skip                Skip files, i.e. pick every nth work value. Default is
                      1 (all); with 2, every other work value is discarded,
                      etc.
--slice               Subset of trajectories to analyze. Provide list slice,
                      e.g. "10 50" will result in selecting
                      dgdl_files[10:50]. Default is all.
--rand                Take a random subset of trajectories. Default is None
                      (do not take random subset)
--index  [ ...]       Zero-based index of files to analyze (e.g. 0 10 20 50
                      60). It keeps the dgdl.xvg files according to their
                      position in the list, sorted according to the
                      filenames. Default is None (i.e. all dgdl are used).
--prec                The decimal precision of the screen/file output.
                      Default is 2.
--units               The units of the output. Choose from "kJ", "kcal",
                      "kT". Default is "kJ."
--pickle              Whether to save the free energy results from the
                      estimators in pickled files. Default is False.
--no_ks               Whether to do a Kolmogorov-Smirnov test to check
                      whether the Gaussian assumption for CGI holds. Default
                      is True; this flag turns it to False.
--quiet               Minimal screen output.