refs-converge

Assessing the convergence with respect to the reference-solvent calculation

Some of the parameters mentioned below are set in the parameters_fe file.
See Parameter files for slvfe for description of those parameters which can be specified in parameters_fe and control the slvfe run.

As described in the section of Running slvfe: Getting Final Output of Quick Start Guide, the slvfe program outputs the free-energy value in each of the trajectory blocks of the solution system and its cumulative average.
The cumulative average is shown as the last part of the output, and provides the convergence behavior of the solvation free energy with respect to the MD length of the solution system.

The number of blocks for the reference-solvent simulation is specified by the engdiv parameter within the parameters_er file in the refs directory (the default value of engdiv for refs is 5).
It should be noted, though, that with its default, the slvfe program does not perform any block averaging for the reference-solvent system.
When engdiv is set to 5 in the reference-solvent simulation and engref.01 -- engref.05 and corref.01 -- corref.05 are prepared, all of them are used in the slvfe run.
Furthermore, when refmerge = 'yes' in parameters_fe (default in the slvfe run), the engref and corref files within the refs directory are summed (with the weights specified in weight_refs) and treated like single files when the slvfe program is executed.

To analyze the cumulative average for the reference-solvent system, user opens the parameters_fe file and modifies the numref parameter in it.
When numref is set to 1, only engref.01 and corref.01 are used for slvfe.
When numref is 2, engref.01 -- engref.02 and corref.01 -- corref.02 are used, and similarly for the other values of numref.
With changing the numref value, user sees the convergence of the solvation free energy value with respect to the reference-solvent simulation.

The mesh error usually reduces with the progress of the reference-solvent calculation.
To see the mesh error, it is convenient to set the mesherr parameter at any negative value in the parameters_fe file.
The mesh error does not appear as an output of slvfe when it is smaller than mesherr in the parameters_fe file.
The default value of mesherr is 0.1 kcal/mol, and if users sets mesherr at an (arbitrary) negative value, the slvfe program always shows the mesh error as an output.

Python scripts for the above procedure are prepared in the distributed packge of ERmod as of ver 0.3.5.
Before running the script, it is necessary to set the path to the slvfe program with

export PATH=(ERmod directory)/bin:$PATH

for bash and

set path = ((ERmod directory)/bin $path)

for csh or tcsh, where (ERmod directory) is the directory where the ERmod programs are installed.
This directory was specified with the option of --prefix of ./configure described in General build guide.
The script then runs tthrough

(ERmod directory)/share/ermod/tools/refs_converge

where (ERmod directory) is the directory where the ERmod programs are installed.
An example output reads like

block   solvationFE 95%Error    MeshError
 1       -4.6621     0.1045      0.204
 2       -4.7137     0.1090      0.169
 3       -4.6962     0.1070      0.130
 4       -4.6699     0.1079      0.075
 5       -4.6733     0.1073      0.013

As described above, numref is to be varied to set the numbers of engref.XX and corref.XX files used for the slvfe run.
When numref = 3, for example, engref.01 -- engref.03 and corref.01 -- corref.03 are used.
The first column of the refs_converge output refes to the numref parameter thus varied.
The second and thirs columns are the solvation free energy and its 95% error computed using engref.XX and corref.XX with their numbers set by numref.
The fourth column is the mesh error. See Parameter files for slvfe for the description of mesh error.

It is typically observed that the 95% error decreases with the length of the solution run
and that the mesh error reduces with the progress of the reference-solvent run.
Thus, the procedure described in this page is useful also for determining the length of reference-solvent run that can suppress the mesh error.

With its default, refs_converge changes the numref parameter to the maximum XX of engref.XX and corref.XX contained in the refs directory.
When user wants to set the maximum numref to 3, for example, an option of --num (or -n) is to be used like

::::sh
(ERmod directory)/share/ermod/tools/refs_converge --num 3