Add softcore info

docs/guide/protocols/absolutesolvation.rst

@@ -31,7 +31,11 @@ The Lennard-Jones interactions are instead decoupled, meaning the intermolecular
 The lambda schedule
 ~~~~~~~~~~~~~~~~~~~
 
-Molecular interactions are turned off during an alchemical path using a discrete set of lambda windows. The electrostatic interactions are turned off first, followed by the decoupling of the Lennard-Jones interactions. A soft-core potential is applied to the Lennard-Jones potential to avoid instablilites in intermediate lambda windows. The lambda schedule is defined in the ``lambda_settings`` objects ``lambda_elec`` and ``lambda_vdw``. Note that the ``lambda_restraints`` setting is ignored for the :class:`.AbsoluteSolvationProtocol`.
+Molecular interactions are turned off during an alchemical path using a discrete set of lambda windows. The electrostatic interactions are turned off first, followed by the decoupling of the Lennard-Jones interactions. 
+A soft-core potential is applied to the Lennard-Jones potential to avoid instablilites in intermediate lambda windows. 
+Both the soft-core potential function from Beutler et al. [1]_ and from Gapsys et al. [2]_ are available and can be selected in the ``softcore_LJ`` settings
+(default is ``gapsys``).
+The lambda schedule is defined in the ``lambda_settings`` objects ``lambda_elec`` and ``lambda_vdw``. Note that the ``lambda_restraints`` setting is ignored for the :class:`.AbsoluteSolvationProtocol`.
 
 Simulation overview
 ~~~~~~~~~~~~~~~~~~~
@@ -59,7 +63,7 @@ Simulation details
 
 Here are some details of how the simulation is carried out which are not detailed in the :class:`.AbsoluteSolvationSettings`:
 
-* The protocol applies a `LangevinMiddleIntegrator <https://openmmtools.readthedocs.io/en/latest/api/generated/openmmtools.mcmc.LangevinDynamicsMove.html>`_ which uses Langevin dynamics, with the LFMiddle discretization [1]_.
+* The protocol applies a `LangevinMiddleIntegrator <https://openmmtools.readthedocs.io/en/latest/api/generated/openmmtools.mcmc.LangevinDynamicsMove.html>`_ which uses Langevin dynamics, with the LFMiddle discretization [3]_.
 * A MonteCarloBarostat is used in the NPT ensemble to maintain constant pressure.
 
 Getting the free energy estimate
@@ -103,4 +107,6 @@ References
 * `OpenMMTools <https://openmmtools.readthedocs.io/en/stable/>`_
 * `OpenMM <https://openmm.org/>`_
 
-.. [1] Unified Efficient Thermostat Scheme for the Canonical Ensemble with Holonomic or Isokinetic Constraints via Molecular Dynamics, Zhijun Zhang, Xinzijian Liu, Kangyu Yan, Mark E. Tuckerman, and Jian Liu, J. Phys. Chem. A 2019, 123, 28, 6056-6079
+.. [1] Avoiding singularities and numerical instabilities in free energy calculations based on molecular simulations, T.C. Beutler, A.E. Mark, R.C. van Schaik, P.R. Greber, and W.F. van Gunsteren, Chem. Phys. Lett., 222 529–539 (1994)
+.. [2] New Soft-Core Potential Function for Molecular Dynamics Based Alchemical Free Energy Calculations, V. Gapsys, D. Seeliger, and B.L. de Groot, J. Chem. Theor. Comput., 8 2373-2382 (2012)
+.. [3] Unified Efficient Thermostat Scheme for the Canonical Ensemble with Holonomic or Isokinetic Constraints via Molecular Dynamics, Zhijun Zhang, Xinzijian Liu, Kangyu Yan, Mark E. Tuckerman, and Jian Liu, J. Phys. Chem. A 2019, 123, 28, 6056-6079

docs/guide/protocols/relativehybridtopology.rst

@@ -37,20 +37,23 @@ ligands, meaning that a single set of coordinates is used to represent the
 common core of the two ligands while the atoms that differ between the two
 ligands are represented separately. An atom map defines which atoms belong
 to the core (mapped atoms) and which atoms are unmapped and represented
-separately (see :ref:`Creating atom mappings <.. _Creating Atom Mappings:>`. During the alchemical transformation, mapped atoms are switched
+separately (see :ref:`Creating atom mappings <Creating Atom Mappings>`). During the alchemical transformation, mapped atoms are switched
 from the type in one ligand to the type in the other ligands, while unmapped
 atoms are switched on or off, depending on which ligand they belong to.
 
-.. note: In this hybrid topology approach, all bonded interactions between the dummy region and the core region are kept. 
-         As pointed out by Fleck et al. [1]_, this can lead to systematic errors if the contribution of the dummy group does not cancel out
-         in the thermodynamic cycle (no separability of the partition function). We are currently working on fixing this issue.
+.. note:: In this hybrid topology approach, all bonded interactions between the dummy region and the core region are kept. 
+          As pointed out by Fleck et al. [1]_, this can lead to systematic errors if the contribution of the dummy group does not cancel out
+          in the thermodynamic cycle (no separability of the partition function). We are currently working on fixing this issue.
 
 The lambda schedule
 ~~~~~~~~~~~~~~~~~~~
 
 The protocol interpolates molecular interactions between the initial and final state of the perturbation using a discrete set of lambda windows. A function describes how the different lambda components (bonded and nonbonded terms) are interpolated.
 Only parameters that differ between state A (``lambda=0``) and state B (``lambda=1``) are interpolated. 
 In the default lambda function in the :class:`.RelativeHybridTopologyProtocol`, first the electrostatic interactions of state A are turned off while simulataneously turning on the van-der-Waals interactions of state B. Then, the van-der-Waals interactions of state A are turned off while simulatenously turning on the electrostatic interactions of state B. Bonded interactions are interpolated linearly between ``lambda=0`` and ``lambda=1``. The ``lambda_settings`` ``lambda_functions`` and ``lambda_windows`` define the alchemical pathway. 
+A soft-core potential is applied to the Lennard-Jones potential to avoid instablilites in intermediate lambda windows.
+Both the soft-core potential function from Beutler et al. [2]_ and from Gapsys et al. [3]_ are available and can be selected in the ``softcore_LJ`` settings 
+(default is ``gapsys``).
 
 Simulation overview
 ~~~~~~~~~~~~~~~~~~~
@@ -78,7 +81,7 @@ Simulation details
 
 Here are some details of how the simulation is carried out which are not detailed in the :class:`.RelativeHybridTopologySettings`:
 
-* The protocol applies a `LangevinMiddleIntegrator <https://openmmtools.readthedocs.io/en/latest/api/generated/openmmtools.mcmc.LangevinDynamicsMove.html>`_ which uses Langevin dynamics, with the LFMiddle discretization [2]_.
+* The protocol applies a `LangevinMiddleIntegrator <https://openmmtools.readthedocs.io/en/latest/api/generated/openmmtools.mcmc.LangevinDynamicsMove.html>`_ which uses Langevin dynamics, with the LFMiddle discretization [4]_.
 * A MonteCarloBarostat is used in the NPT ensemble to maintain constant pressure.
 
 Getting the free energy estimate
@@ -121,4 +124,6 @@ References
 * `OpenMM <https://openmm.org/>`_
 
 .. [1] Dummy Atoms in Alchemical Free Energy Calculations, Markus Fleck, Marcus Wieder, and Stefan Boresch, J. Chem. Theory Comput.2021, 17, 4403−4419
-.. [2] Unified Efficient Thermostat Scheme for the Canonical Ensemble with Holonomic or Isokinetic Constraints via Molecular Dynamics, Zhijun Zhang, Xinzijian Liu, Kangyu Yan, Mark E. Tuckerman, and Jian Liu, J. Phys. Chem. A 2019, 123, 28, 6056-6079
+.. [2] Avoiding singularities and numerical instabilities in free energy calculations based on molecular simulations, T.C. Beutler, A.E. Mark, R.C. van Schaik, P.R. Greber, and W.F. van Gunsteren, Chem. Phys. Lett., 222 529–539 (1994)
+.. [3] New Soft-Core Potential Function for Molecular Dynamics Based Alchemical Free Energy Calculations, V. Gapsys, D. Seeliger, and B.L. de Groot, J. Chem. Theor. Comput., 8 2373-2382 (2012)
+.. [4] Unified Efficient Thermostat Scheme for the Canonical Ensemble with Holonomic or Isokinetic Constraints via Molecular Dynamics, Zhijun Zhang, Xinzijian Liu, Kangyu Yan, Mark E. Tuckerman, and Jian Liu, J. Phys. Chem. A 2019, 123, 28, 6056-6079