Pmf-integrate: Difference between revisions

← Older edit

Pmf-integrate (view source)

Revision as of 13:45, 28 July 2021

11,479 bytes added , 28 July 2021

no edit summary

Maintenance script

29

edits

@@ Line 1: / Line 1: @@
-Navigation: [[Documentation]] / [[Methods]] / [[Constrained Dynamics]] / [[CON:Utilities]] / [[pmf-integrate]]
+{{DISPLAYTITLE:pmf-integrate}}
+Navigation: [[Documentation]] / [[Utilities]] / [[pmf-integrate]]
 ----
-{{CONUtils}}
+<div style="text-align: center">pmf-integrate: version 6.380.1d87074 (2021-07-26 16:36)</div>'''Name'''
-'''Name'''
-pmf-integrate
+<span style="margin-left: 15px;">pmf-integrate</span>
 '''Synopsis'''
-<span style="color: maroon;">con-integrate</span> <span style="color: blue;">[OPTIONS]</span> [--] <span style="color: purple;">input output </span>
+<span style="color: maroon; margin-left: 15px;">pmf-integrate</span> <span style="color: blue;">[OPTIONS]</span> [--] <span style="color: purple;">accuname fename [fullfename]</span>
 '''Description'''
-Numerically integrate given data by Simpson method. Program reads three numbers from input file (x coordinate, derivative, and standard deviation of derivative). As output program prints copy of input data plus integrated values and its standard error.
+<p style="text-indent: 1em; text-align: justify;">The program numerically integrates data from the PMF calculations. The integration is performed either by the reverse finite difference (RFD) method, radial basis functions (RBF), or Gaussian process (GPR).</p>
 '''Arguments'''
-{| style="margin-left: 2em; width: 75%;"
+<div style="margin-left: 2em;"><span style="color: darkcyan;"><span style="font-style: bold;">accuname</span></span>                   Name of file containing the ABF accumulator. If the name is '-' then the accumulator is read from the standard input.<br /><span style="color: darkcyan;"><span style="font-style: bold;">fename</span></span>                     Name of file where the resulting free energy surface will be printed. If the name is '-' then the output will be written to the standard output.<br /><span style="color: darkcyan;"><span style="font-style: bold;">fullfename</span></span>                 Optional name of file with free energy surface containing all regions (sampled and unsampled).</div>
-|- style="vertical-align: top; background-color: #e6e6e6;"
-| <span style="color: purple;">input</span><br/>
-<span style="margin-left: 30px;">input data file or - for data taken from standard input</span>
-|- style="vertical-align: top;"
-| <span style="color: purple;">output</span><br/>
-<span style="margin-left: 30px;">output data file or - for data written to standard output</span>
-|}
 '''Options'''
@@ Line 29: / Line 22: @@
 {| style="margin-left: 2em; width: 95%;"
 |- style="vertical-align: top; background-color: #e6e6e6;"
-|<span style="color: blue;">--offset REAL</span><br/><span style="margin-left: 30px;">specifies integration constant</span><br/><span style="color:purple; margin-left: 30px;"> (Default: 0)</span>
+|<span style="color: blue;">-r, --realm NAME</span><br/><div style="margin-left: 30px;">Intended output from the integration:<br />**  dG     - free energy (default)<br />** -TdS    - entropy contribution to the free energy<br />**  dG_p   - free energy (potential part) - ABF<br />**  dG_k   - free energy (kinetic part) - ABF<br />** -TdS_PP - entropy contribution to the free energy, cov(dH_p/dx,Epot) - ABF<br />** -TdS_PK - entropy contribution to the free energy, cov(dH_p/dx,Ekin) - ABF<br />** -TdS_PR - entropy contribution to the free energy, cov(dH_p/dx,Erst) - ABF<br />** -TdS_KP - entropy contribution to the free energy, cov(dH_k/dx,Epot) - ABF<br />** -TdS_KK - entropy contribution to the free energy, cov(dH_k/dx,Ekin) - ABF<br />** -TdS_KR - entropy contribution to the free energy, cov(dH_k/dx,Erst) - ABF<br />** -TdS_HP - entropy contribution to the free energy, cov(dH/dx,Epot) - CST<br />** -TdS_HK - entropy contribution to the free energy, cov(dH/dx,Ekin) - CST<br />** -TdS_HR - entropy contribution to the free energy, cov(dH/dx,Erst) - CST</div><span style="color:purple; margin-left: 30px;">(Default: dG)</span>
-|- style="vertical-align: top; "
+|- style="vertical-align: top;"
-|<span style="color: blue;">-s, --skip LINES</span><br/><span style="margin-left: 30px;">number of lines skipped from the beginning of input file</span><br/><span style="color:purple; margin-left: 30px;"> (Default: 0)</span>
+|<span style="color: blue;">-m, --method NAME</span><br/><div style="margin-left: 30px;">Integration method. Supported methods are: rfd (reverse finite differences via csparse), rbf (radial basis functions), and gpr (gaussian process).</div><span style="color:purple; margin-left: 30px;">(Default: rfd)</span>
+|- style="vertical-align: top; background-color: #e6e6e6;"
+|<span style="color: blue;">--emethod NAME</span><br/><div style="margin-left: 30px;">Integration method for energy cut-off. Supported methods are: rfd (reverse finite differences via csparse), rbf (radial basis functions), and gpr (gaussian process).</div><span style="color:purple; margin-left: 30px;">(Default: rfd)</span>
+|- style="vertical-align: top;"
+|<span style="color: blue;">-a, --lmethod NAME</span><br/><div style="margin-left: 30px;">Linear algebra method for LLS solution or matrix inversion. Supported algorithms are: default, svd (SVD - singular value decomposition, divide and conquer driver), svd2 (SVD - singular value decomposition, simple driver), qr (QR factorization), lu (LU factorization), ll (LL - Cholesky factorization). Possible combinations are: RFD(LU,default), RBF(QR,SVD,default), and GPR(LU,SVD,SVD2,LL,default).</div><span style="color:purple; margin-left: 30px;">(Default: default)</span>
+|- style="vertical-align: top; background-color: #e6e6e6;"
+|<span style="color: blue;">--rcond NUMBER</span><br/><div style="margin-left: 30px;">RBF+GPR: Rank condition for SVD. Used value must be carefully tested. Calculation at computer precision is requested with -1 (not recommended).</div><span style="color:purple; margin-left: 30px;">(Default: 1e-06)</span>
+|- style="vertical-align: top;"
+|<span style="color: blue;">-l, --limit NUMBER</span><br/><div style="margin-left: 30px;">Only bins containing more samples than NUMBER are considered as properly sampled.</div><span style="color:purple; margin-left: 30px;">(Default: 100)</span>
+|- style="vertical-align: top; background-color: #e6e6e6;"
+|<span style="color: blue;">--skipfftest</span><br/><div style="margin-left: 30px;">Skip flood fill test for discontinuous regions.</div>
+|- style="vertical-align: top;"
+|<span style="color: blue;">-q, --energylimit NUMBER</span><br/><div style="margin-left: 30px;">Integrate data only if the free energy is below NUMBER. This limit enforces two integration runs. Negative value disables the limit.</div><span style="color:purple; margin-left: 30px;">(Default: -1)</span>
+|- style="vertical-align: top; background-color: #e6e6e6;"
+|<span style="color: blue;">--rmnegene</span><br/><div style="margin-left: 30px;">Remove regions with negative free energy.</div>
+|- style="vertical-align: top;"
+|<span style="color: blue;">--skiplastelimit</span><br/><div style="margin-left: 30px;">Skip energy limit filter after final integration.</div>
+|- style="vertical-align: top; background-color: #e6e6e6;"
+|<span style="color: blue;">--mfmaxzscore NUMBER</span><br/><div style="margin-left: 30px;">RBF+GPR: Reject mean forces whose errors in prediction have z-score above NUMBER. In the test, it is assumend that mean force errors have zero mean and they follow normal distribution. This limit is aplied in the each pass. Negative value disables the limit.</div><span style="color:purple; margin-left: 30px;">(Default: -1)</span>
+|- style="vertical-align: top;"
+|<span style="color: blue;">--mfnumofztests NUMBER</span><br/><div style="margin-left: 30px;">RBF+GPR: Repeat z-score test for mean force errrors NUMBER times.</div><span style="color:purple; margin-left: 30px;">(Default: 1)</span>
+|- style="vertical-align: top; background-color: #e6e6e6;"
+|<span style="color: blue;">-s, --sigmaf2 NUMBER</span><br/><div style="margin-left: 30px;">GPR: Variance of the reconstructed free energy surface (signal variance).</div><span style="color:purple; margin-left: 30px;">(Default: 15)</span>
+|- style="vertical-align: top;"
+|<span style="color: blue;">-c, --ncorr NUMBER</span><br/><div style="margin-left: 30px;">GPR: Number of statistically correlated samples.</div><span style="color:purple; margin-left: 30px;">(Default: 1)</span>
+|- style="vertical-align: top; background-color: #e6e6e6;"
+|<span style="color: blue;">-w, --wfac SPEC</span><br/><div style="margin-left: 30px;">RBF+GPR: Factors influencing widths of RBFs or square exponential kernels. The width is distance between the adjacent square exponential functions multiplied by this factors in the form WFac1[xWFac2x...]. The last value pads the rest.</div><span style="color:purple; margin-left: 30px;">(Default: 3.0)</span>
+|- style="vertical-align: top;"
+|<span style="color: blue;">--loadhyprms NAME</span><br/><div style="margin-left: 30px;">GPR: Name of file with GPR hyperparameters.</div>
+|- style="vertical-align: top; background-color: #e6e6e6;"
+|<span style="color: blue;">-t, --rfac SPEC</span><br/><div style="margin-left: 30px;">RBF: Reduction factor for number of RBFs. Number of RBFs in given direction is number of bins in that direction divided by this factor in the form RFac1[xRFac2x...]. The last value pads the rest.</div><span style="color:purple; margin-left: 30px;">(Default: 1.0)</span>
+|- style="vertical-align: top;"
+|<span style="color: blue;">-g, --overhang NUMBER</span><br/><div style="margin-left: 30px;">RBFs overhang to properly integrate areas near sampled edges. Ignored for periodic CVs.</div><span style="color:purple; margin-left: 30px;">(Default: 2)</span>
+|- style="vertical-align: top; background-color: #e6e6e6;"
+|<span style="color: blue;">--includeglued</span><br/><div style="margin-left: 30px;">RBF+GPR: Explicitly include glued regions. This options is set ON when --glueing > 0.</div>
+|- style="vertical-align: top;"
+|<span style="color: blue;">--glueing NUMBER</span><br/><div style="margin-left: 30px;">RBF+GPR: Calculate energy also for unsampled bins in close vicinity to sampled ones.</div><span style="color:purple; margin-left: 30px;">(Default: 0)</span>
+|- style="vertical-align: top; background-color: #e6e6e6;"
+|<span style="color: blue;">--glueholes</span><br/><div style="margin-left: 30px;">RBF+GPR: Calculate energy also for unsampled regions inside the FES.</div>
+|- style="vertical-align: top;"
+|<span style="color: blue;">-p, --periodic</span><br/><div style="margin-left: 30px;">RFD: Switch on periodicity for collective variables that are periodic.</div>
+|- style="vertical-align: top; background-color: #e6e6e6;"
+|<span style="color: blue;">--globalmin SPEC</span><br/><div style="margin-left: 30px;">RBF+GPR: position of global minimum provided as a single string in the form CV1xCV2x...xCVn (relevant for error determination), if not set the position is determined automatically.</div>
+|- style="vertical-align: top;"
+|<span style="color: blue;">--userealglbmin</span><br/><div style="margin-left: 30px;">RBF+GPR: ignore --globalmin in the final integration step</div>
+|- style="vertical-align: top; background-color: #e6e6e6;"
+|<span style="color: blue;">-o, --offset NUMBER</span><br/><div style="margin-left: 30px;">Specify an integration constant.</div><span style="color:purple; margin-left: 30px;">(Default: 0)</span>
+|- style="vertical-align: top;"
+|<span style="color: blue;">-e, --witherror</span><br/><div style="margin-left: 30px;">GPR: Estimate free energy errors.</div>
+|- style="vertical-align: top; background-color: #e6e6e6;"
+|<span style="color: blue;">--noenergy</span><br/><div style="margin-left: 30px;">GPR: Skip calculation of energy and errors (it can save some time when only logML is required).</div>
+|- style="vertical-align: top;"
+|<span style="color: blue;">--saveabf NAME</span><br/><div style="margin-left: 30px;">Save the final ABF accumulator into the file with NAME.</div>
+|- style="vertical-align: top; background-color: #e6e6e6;"
+|<span style="color: blue;">--mfinfo NAME</span><br/><div style="margin-left: 30px;">RBF+GPR: name of file with input and predicted mean forces.</div>
+|- style="vertical-align: top;"
+|<span style="color: blue;">--output FORMAT</span><br/><div style="margin-left: 30px;">Output FORMAT to print the free energy surface. Supported formats are: plain, and gnuplot.</div><span style="color:purple; margin-left: 30px;">(Default: gnuplot)</span>
 |- style="vertical-align: top; background-color: #e6e6e6;"
-|<span style="color: blue;">-a, --anal LINES</span><br/><span style="margin-left: 30px;">number of LINES from input file to be analyzed</span><br/><span style="color:purple; margin-left: 30px;"> (Default: -1)</span>
+|<span style="color: blue;">--printall</span><br/><div style="margin-left: 30px;">Print results for all bins even if not properly sampled.</div>
-|- style="vertical-align: top; "
+|- style="vertical-align: top;"
-|<span style="color: blue;">-p, --pad LINES</span><br/><span style="margin-left: 30px;">number of padding LINES between used records from input file</span><br/><span style="color:purple; margin-left: 30px;"> (Default: 0)</span>
+|<span style="color: blue;">--unsampledasmax</span><br/><div style="margin-left: 30px;">Set energy values in unsampled region to maximum energy from sampled region or to value provided by --maxenergy.</div>
 |- style="vertical-align: top; background-color: #e6e6e6;"
-|<span style="color: blue;">--nosigma</span><br/><span style="margin-left: 30px;">standard deviation of derivative is not present in input data</span>
+|<span style="color: blue;">--maxenergy NUMBER</span><br/><div style="margin-left: 30px;">If set, this is the energy used of unsampled regions.</div><span style="color:purple; margin-left: 30px;">(Default: 0)</span>
-|- style="vertical-align: top; "
+|- style="vertical-align: top;"
-|<span style="color: blue;">--noheader</span><br/><span style="margin-left: 30px;">do not print header to output</span>
+|<span style="color: blue;">--noheader</span><br/><div style="margin-left: 30px;">Do not print header to the output file.</div>
 |- style="vertical-align: top; background-color: #e6e6e6;"
-|<span style="color: blue;">--fx FORMAT</span><br/><span style="margin-left: 30px;">output FORMAT of echoed x values</span><br/><span style="color:purple; margin-left: 30px;"> (Default: %15.7le)</span>
+|<span style="color: blue;">--includebinstat</span><br/><div style="margin-left: 30px;">Include bin statuses (1=sampled, 0=unsampled, -1=glued) into resulting FES.</div>
-|- style="vertical-align: top; "
+|- style="vertical-align: top;"
-|<span style="color: blue;">--fy FORMAT</span><br/><span style="margin-left: 30px;">output FORMAT of echoed derivative values</span><br/><span style="color:purple; margin-left: 30px;"> (Default: %15.7le)</span>
+|<span style="color: blue;">--oldrfd</span><br/><div style="margin-left: 30px;">RFD: Use old RFD implementation.</div>
 |- style="vertical-align: top; background-color: #e6e6e6;"
-|<span style="color: blue;">--fs FORMAT</span><br/><span style="margin-left: 30px;">output FORMAT of echoed sigma values</span><br/><span style="color:purple; margin-left: 30px;"> (Default: %14.6le)</span>
+|<span style="color: blue;">--fdpoints NUMBER</span><br/><div style="margin-left: 30px;">RFD: Determine number of points employed in differenciation scheme (three or four is upported) in RFD method.</div><span style="color:purple; margin-left: 30px;">(Default: 3)</span>
-|- style="vertical-align: top; "
+|- style="vertical-align: top;"
-|<span style="color: blue;">--fi FORMAT</span><br/><span style="margin-left: 30px;">output FORMAT of integrated values</span><br/><span style="color:purple; margin-left: 30px;"> (Default: %15.7le)</span>
+|<span style="color: blue;">--fx FORMAT</span><br/><div style="margin-left: 30px;">Output FORMAT, which will be used to print values of collective variables.</div><span style="color:purple; margin-left: 30px;">(Default: %15.7e)</span>
 |- style="vertical-align: top; background-color: #e6e6e6;"
-|<span style="color: blue;">--fe FORMAT</span><br/><span style="margin-left: 30px;">output FORMAT of integrated error values</span><br/><span style="color:purple; margin-left: 30px;"> (Default: %14.6le)</span>
+|<span style="color: blue;">--fe FORMAT</span><br/><div style="margin-left: 30px;">Output FORMAT, which will be used to print values of free energy.</div><span style="color:purple; margin-left: 30px;">(Default: %15.7e)</span>
-|- style="vertical-align: top; "
+|- style="vertical-align: top;"
-|<span style="color: blue;">-v, --verbose</span><br/><span style="margin-left: 30px;">increase output verbosity</span>
+|<span style="color: blue;">--kernel NAME</span><br/><div style="margin-left: 30px;">GPR: Kernel type. Supported types: ardse (ARD squared exponential), ardmc52 (ARD Matern class 5/2), default(=ardse)</div><span style="color:purple; margin-left: 30px;">(Default: default)</span>
+|- style="vertical-align: top; background-color: #e6e6e6;"
+|<span style="color: blue;">--numdiff</span><br/><div style="margin-left: 30px;">GPR: Use numerical differentiation of kernel function (for testing only).</div>
+|- style="vertical-align: top;"
+|<span style="color: blue;">--useinv</span><br/><div style="margin-left: 30px;">GPR: Use matrix inversion pathway (for testing only).</div>
+|- style="vertical-align: top; background-color: #e6e6e6;"
+|<span style="color: blue;">--calclogpl</span><br/><div style="margin-left: 30px;">GPR: Calculate logPL.</div>
+|- style="vertical-align: top;"
+|<span style="color: blue;">--inczpe</span><br/><div style="margin-left: 30px;">GPR: Include zero-point energy at position specified by --globalmin.</div>
+|- style="vertical-align: top; background-color: #e6e6e6;"
+|<span style="color: blue;">--nofasterror</span><br/><div style="margin-left: 30px;">GPR: Do not use faster algorithm for error calculation.</div>
+|- style="vertical-align: top;"
+|<span style="color: blue;">--slevel VALUE</span><br/><div style="margin-left: 30px;">Sigma-level for confidence interval.</div><span style="color:purple; margin-left: 30px;">(Default: 1)</span>
+|- style="vertical-align: top; background-color: #e6e6e6;"
+|<span style="color: blue;">--keepcvs SPEC</span><br/><div style="margin-left: 30px;">Which CVs should be kept during statistical reweighting of FES. Flags are specified in the form CV1[xCV2x...] with F and T for skip and kept CV, respectively. The last value pads the rest.</div><span style="color:purple; margin-left: 30px;">(Default: T)</span>
+|- style="vertical-align: top;"
+|<span style="color: blue;">--reducedfes NAME</span><br/><div style="margin-left: 30px;">Name of file for FES reduced by statistical reweighting containing only kept CVs.</div>
+|- style="vertical-align: top; background-color: #e6e6e6;"
+|<span style="color: blue;">-v, --verbose</span><br/><div style="margin-left: 30px;">Increase output verbosity.</div>
+|- style="vertical-align: top;"
+|<span style="color: blue;">--version</span><br/><div style="margin-left: 30px;">Output version information and exit.</div>
 |- style="vertical-align: top; background-color: #e6e6e6;"
-|<span style="color: blue;">--version</span><br/><span style="margin-left: 30px;">output version information and exit</span>
+|<span style="color: blue;">-h, --help</span><br/><div style="margin-left: 30px;">Display this help and exit.</div>
-|- style="vertical-align: top; "
-|<span style="color: blue;">-h, --help</span><br/><span style="margin-left: 30px;">display this help and exit</span>
 |}