QuickStartGuide

Quick Start Guide

This page describes how to install and use the ERmod (Energy Representation MODule) program package.

Obtaining Software

The software can be downloaded from https://sourceforge.net/projects/ermod/files/.
Refer to the build-Guide to build and install the program.

Calculation Workflow of Solvation Free Energy

Typical calculation workflow of the solvation free energy is shown in the following figure.

There are two systems to be considered, namely solution system and reference system.
The former refers to the solution system of interest; the solute and solvent interact with each other at full coupling.
In the latter, the ensembles for the solute and solvent are constructed independently, and the solute-solvent configuration is generated by placing the solute in the solvent system as a test particle.
From the trajectories of the MD simulations, the histogram of solute-solvent pair interaction energy rho^e is calculated, for both the solution and reference systems.
By using the pair-energy histograms in the solution and reference systems as well as the correlation matrix in the reference, the solvation free energy is calculated approximately through a functional.

From this point, there are three choices depending upon which MD program is being used

Running erdst: Obtaining the energy histogram with GROMACS

Please see Quick Start Guide/GROMACS.

Running erdst: Obtaining the energy histogram with AMBER

Please see Quick Start Guide/AMBER.

Running erdst: Obtaining the energy histogram with LAMMPS

Please see Quick Start Guide/LAMMPS.

Running slvfe: Getting Final Output

After obtaining the energy distribution functions in both the solution and reference-solvent systems,
user moves to the top directory (the directory where he ran the gen_structure script) and runs the slvfe program.

(ERmod directory)/bin/slvfe

where (ERmod directory) is the directory where the ERmod programs are installed; the directory was specified with the option of --prefix of ./configure described in General build guide.
The slvfe program provides the solvation energy and the solvation free energy, with error bars and cumulative averages to examine the convergence.
All the energy and free energy values are given in kcal/mol.
A typical output reads as:

  Number of the   1-th solvent  =         1000               # (1)

  Self-energy of the solute   =        -0.0055  kcal/mol     # (2)


 cumulative average & 95% error for solvation energy         # (3)
  1   -21.1775                                               # (3a)
  2   -20.6965     0.9621                                    # (3b)
  ...
 10   -20.5052     0.5123                                    # (3c)


  ...
                                                             # (4)
 group    solvation free energy     error          difference
   1            -4.16860           0.23723           0.00865
   2            -4.17575           0.23726           0.00149
   3            -4.17725           0.23551           0.00000
   4            -4.16655           0.23346           0.01070
   5            -4.17864           0.23660          -0.00139
  ...

 group   Estimated free energy (kcal/mol)                    # (5)
   1        -4.3431      -4.0160      -3.5930      -4.2506      -3.8395
            -4.4264      -4.5224      -3.7374      -4.1658      -4.7920
   2        -4.3429      -4.0176      -3.5985      -4.2743      -3.8493
            -4.4241      -4.5162      -3.7449      -4.1809      -4.8089
  ...

 cumulative average & 95% error for solvation free energy    # (6)
  1    -4.3485                                               # (6a)
  2    -4.1912     0.3146                                    # (6b)
  3    -3.9957     0.4311                                    # (6c)
  ...
 10    -4.1772     0.2355                                    # (6d)

The most important part of this output is (6), the solvation free energy.
Especially, the final line (6d) is the solvation free energy and its 95% confidence interval (or twice the standard error, 2-sigma).
In above example, -4.18 +/- 0.24 kcal/mol is the final estimate of the solvation free energy.

The explanation of each part follows;

(1) Number of Solvent Molecules

The number of solvent molecules is shown.
When the system is of mixed solvent and has more than 1 solvent species, the number is shown for each species.

(2) Self-Energy of the Solute

If user runs the simulations in periodic boundary condition (PBC), there is a correction from the electrostatic interaction of the solute with its own images and the neutralizing background.
This correction is listed as "Self-Energy of the Solute" in the output.
The correction is actually computed only for the electrostatic interaction in periodic boundary condition;
it is not the gas-phase energy of the solute or does not contain, for example, the correction due to the Lennard-Jones interaction.

Usually, the value is negligibly small when the solute is neutral and its size is much smaller than the system size.
For an ionic solute, the value is not negligible.
The self-energy value is added to the solvation energy in section (3) and the solvation free energy in sections (4)--(6).

When there is more than 1 solvent species, the energies values in sections (3)--(6) are shown both for the total and for each solvent species.
The self-energy correction is done only for the total value, and not for the value for each solvent species.
This is because the self-energy is of solute and does not correspond to any of the solvent species.
It should thus be noted in sections (3)--(6) that the sum of the values over the solvent species is not equal to the total value.

(3) Solvation Energy

This section represents the solvation energy, not solvation free energy, of the solute with the solvent.
This is the average sum of the interaction energy of the solute with all the solvent molecules.

In the above example, the trajectory of the solution system is divided into 10 blocks, and the average solvation energy is obtained in each of the 10 blocks;
the number of divisions of the solution MD is specified by the engdiv parameter within the parameters_er file in the soln directory as described in Parameter files for erdst, and its default value is 10.
Each line then presents the cumulative average of the solvation energy and the 95% error (twice the standard error).
For example, the 3rd line is the averaged solvation energy and the error, calculated from the first 3/10 of the trajectory of the solution system.
If the error is too large, the simulation is not equilibrated well or the simulation time is insufficient.
There will be a need for longer simulation or for use of an extended ensemble method such as replica exchange.

It should be further noted that the solvation energy is NOT the change in thermodynamic energy or enthalpy of the system upon insertion of the solute.
The change in the solvent-solvent energy needs to be incorporated to obtain the change in the thermodynamic energy or enthalpy, the solvation energy in this section refers only to the solute-solvent interaction.
Still, the solvation energy can be major part of the change in thermodynamic energy, especially when the solute-solvent interaction is highly attractive.

When the solvent is of more than a single solvent species, the output for the solvation energy looks like:

::::text
  cumulative average & 95% error for solvation energy
              total             1st component         2nd component
  1   -19.1070               -8.2407              -10.8662
  2   -19.4067     0.5994    -9.0809     1.6805   -10.3257     1.0810
 ...
 10   -19.6375     0.3491    -9.8521     0.8416    -9.7853     0.5163

"1st component", "2nd component", ... corresponds to the interaction energies between the solute and 1st solvent species, between the solute and 2nd solvent species, and so on. For each component the 95% error is also shown.
See also Notes on the outputs of slvfe for mixed solvent at the end of this page.

(4) Solvation Free Energy with its Statistical Error and Mesh Error

The solvation free energy is calculated first by constructing the average histograms with ermod and then by using the histograms as the inputs to slvfe.
As noted in section (3), the trajectory of the solution system is divided into 10 blocks.
In the slvfe program, the solvation free energy is calculated in each of the trajectory blocks.
In the above example, 10 values of the solvation free energy are obtained.
In each line specified by the value of group in the first column (see below for the explanation of group),
the second column provides the average value of the solvation free energy and the third column corresponds to its 95% error (twice the standard error).
In the above example, the solvation free energy is computed in each of the 10 blocks,
and the 10 values computed are used to determine the average and error.
The 10 values corresponding to the blocks are listed in section (5).

When numdiv = 1 in parameters_fe, the column for the 95% error is absent in the slvfe output.

To construct the histogram, a set of meshes need to be introduced to the value of solute-solvent pair energy.
It is thus necessary to examine whether the energy meshes employed are appropriate.
The last column is prepared to examine the error due to introduction of energy meshes.

The values in the line of group = 1 corresponds to those evaluating from the energy meshes appearing in the distribution functions engsln and engref obtained as outputs of the ermod program.
With group = 5, for example, each 5 contiguous bins of the histogram are merged into a single bin and the solvation free energy is re-calculated with its average and error.
This calculation is done over different values of group and the outputs are shown for the average and 95% error of solvation free energy at each value of group.

The last column then shows the mesh error.
The error is expressed by setting the value at group = 3 as the reference and showing the difference of the value at each group from the reference.
Further, the values obtained with group = 3 are used in the final result presented in section (6).

If the mesh error is too large, it is likely that the reference simulation is too short.
It suffices often to increase the number of configuration in the reference system.
See Warning: mesh error is (real value1) kcal/mol and is larger than the recommended value of (real value2) kcal/mol for a possible cure.

If the system is of mixed solvent and has more than 1 solvent species, user sees the free energy values for each of the solvent species with the group and difference columns.

(5) Value of Solvation Free Energy in Each Block

In the above example, the trajectory of the solution system is divided into 10 blocks, and the solvation free energy is obtained in each of the 10 blocks. In (5), all of the 10 values are listed. The list tends to be long because the listing is done at each value of group and further for each solvent species if the number of solvent species is more than 1. When numdiv = 1 in parameters_fe, section (5) is absent in the slvfe output.

(6) Solvation Free Energy: Cumulative Average

This section presents the cumulative averages and errors of the computed solvation free energy.
In the above example, the trajectory of the solution system is divided into 10 blocks, and the solvation free energy is obtained in each of the 10 blocks.
The first line (6a) is for the value of the solvation free energy in the first of 10 blocks.
The second line (6b) shows the average and error calculated from the two values corresponding to the first two blocks.
Similarly, the third line (6c) provides the average and error obtained from the three values corresponding to the first three blocks.
The last line (6d) presents the final results determined from all of the 10 values.
The first line does not have an entry for error since it corresponds to only a single value from the first of the 10 blocks.
When the system has more than 1 solvent species, the output is of the format given at the end of section (3).

The trajectory is divided into a set of blocks both for soln and refs.
The default value of the number of divisions is 10 for the solution system and is 5 for the reference solvent.
The number of divisions can be modified with the engdiv parameter in the parameters_er file when the ermod program is run; engdiv can be changed independently for the soln and refs calculations through the respective parameters_er files.
See Parameter files for erdst for the description of the parameters which can be specified in parameters_er.

Note that no block averaging is performed for the reference-solvent system.
See Assessing the convergence with respect to the reference-solvent calculation for the procedure to examine the the convergence behavior of the solvation free energy with respect to the reference-solvent calculation.

When the solvent is of more than a single solvent species, the output for the solvation free energy looks like:

cumulative average & 95% error for solvation free energy
              total             1st component         2nd component
  1    -1.8497               -2.5013                0.6516
  2    -1.9801     0.2607    -2.8383     0.6742     0.8584     0.4135
 ...
 10    -2.0899     0.1462    -3.1861     0.3494     1.0963     0.2173

"1st component", "2nd component", ... corresponds to the contribution from the 1st solvent species, that from 2nd solvent species, and so on. For each component the 95% error is also shown.
The decomposition of the free energy is done on the basis of the approxiamte, free-energy functional adopted in slvfe.
See also Notes on the outputs of slvfe for mixed solvent at the end of this page.

Notes on the outputs of slvfe for mixed solvent

When the solvent is of more than a single solvent species, the output for a slvfe run looks like:

  Number of the   1-th solvent  =          184
  Number of the   2-th solvent  =          816

  Self-energy of the solute   =       -13.9110  kcal/mol


 cumulative average & 95% error for solvation energy
              total             1st component         2nd component
   1   -116.5834             -17.4833              -85.1891
   2   -117.4970    1.8271   -32.4797   29.9929    -71.1062    28.1658
  ...
  10   -116.9123    0.4796   -29.9985    7.4632    -73.0028     7.0562

 group    solvation free energy     error          difference
  total solvation free energy
    1         -47.59623           0.24064          -0.04003
    2         -47.55620           0.24266           0.00000
    ...

  contribution from  1-th solvent component
    1         -11.05226           1.62199          -0.01722
    2         -11.03890           1.62182          -0.00386
   ...

  contribution from  2-th solvent component
    1         -22.63297           1.44212          -0.02281
    2         -22.61711           1.44167          -0.00696
   ...

 group   Estimated free energy: total (kcal/mol)
   1      -46.8618     -48.0330     -48.4726     -46.6320     -46.3906
          -47.7664     -46.9254     -47.0262     -46.4624     -47.1932
   2      -46.8276     -48.0010     -48.4534     -46.6049     -46.3559
  ...

 group   Estimated free energy: 1-th solvent contribution (kcal/mol)
   1       -3.8740     -18.6660     -20.3002      -7.3065      -8.0750
          -11.3430      -3.9699     -10.1766      -3.9702     -12.9707
   2       -3.8534     -18.6464     -20.2890      -7.2937      -8.0573
  ...

 group   Estimated free energy: 2-th solvent contribution (kcal/mol)
   1      -29.0768     -15.4560     -14.2615     -25.4145     -24.4045
          -22.5124     -29.0444     -22.9386     -28.5812     -20.3116
   2      -29.0632     -15.4436     -14.2534     -25.4001     -24.3876
  ...

  cumulative average & 95% error for solvation free energy
                total             1st component         2nd component
   1    -46.8232               -3.8497              -29.0625
   2    -47.4110     1.1757   -11.2460    14.7927   -22.2540    13.6170
  ...
  10    -47.1353     0.4458   -10.0437     3.7303   -23.1806     3.3489

For a mixed-solvent system, the sum of the contributions from the 1st, 2nd, ... solvent species is not equal to the total value.
Instead, the total values for the solvation energy and solvation free energy are the sum of the contributions from the solvent species and of the self-energy of the solute listed at the beginning part of the slvfe output.

When the solvent is of a single species, the contribution from the "1st" solvent species is not separately shown and the self-energy of the solute is incorporated into the output values of the energy and free energy.

It should be further noted, irrespective of the number of solvent species, that the self-energy is not incorporated into the aveuv.tt and flcuv.tt outputs of the erdst program described in Outputs from erdst run.