ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

reformate, make small corrections, align with other doc files and use sphinx-design to make html more compact

Browse Source
This commit is contained in:
Axel Kohlmeyer
2024-06-26 07:30:50 -04:00
parent 252f48b2c1
commit b1d1213dfd
3 changed files with 116 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

118
doc/src/Howto_bioFF.rst
View File

@ -15,12 +15,17 @@ commands like :doc:`pair_coeff <pair_coeff>` or :doc:`bond_coeff
<bond_coeff>` and so on. See the :doc:`Tools <Tools>` doc page for <bond_coeff>` and so on. See the :doc:`Tools <Tools>` doc page for
additional tools that can use CHARMM, AMBER, or Materials Studio additional tools that can use CHARMM, AMBER, or Materials Studio
generated files to assign force field coefficients and convert their generated files to assign force field coefficients and convert their
output into LAMMPS input. LAMMPS input scripts can also be generated by `charmm-gui.org <https://charmm-gui.org/>`_. output into LAMMPS input. LAMMPS input scripts can also be generated by
`charmm-gui.org <https://charmm-gui.org/>`_.
CHARMM and AMBER CHARMM and AMBER
---------------- ----------------
The `CHARMM force field <https://mackerell.umaryland.edu/charmm_ff.shtml>`_ :ref:`(MacKerell) <howto-MacKerell>` and `AMBER force field <https://ambermd.org/AmberModels.php>`_ :ref:`(Cornell) <howto-Cornell>` have potential energy function of the form The `CHARMM force field
<https://mackerell.umaryland.edu/charmm_ff.shtml>`_ :ref:`(MacKerell)
<howto-MacKerell>` and `AMBER force field
<https://ambermd.org/AmberModels.php>`_ :ref:`(Cornell) <howto-Cornell>`
have potential energy function of the form
.. math:: .. math::
@ -38,7 +43,14 @@ The `CHARMM force field <https://mackerell.umaryland.edu/charmm_ff.shtml>`_ :ref
}} \!\!\!\!\!\!\!\!+ \!\!\sum_{special}\! E_s + \!\!\!\!\sum_{residues} \!\!\!{\scriptstyle\mathrm{CMAP}(\phi,\psi)} }} \!\!\!\!\!\!\!\!+ \!\!\sum_{special}\! E_s + \!\!\!\!\sum_{residues} \!\!\!{\scriptstyle\mathrm{CMAP}(\phi,\psi)}
The terms are computed by bond styles (relationship between 2 atoms), angle styles (between 3 atoms) , dihedral/improper styles (between 4 atoms), pair styles (non-covalently bonded pair interactions) and special bonds. The CMAP term (see :doc:`fix cmap <fix_cmap>` command for details) corrects for pairs of dihedral angles ("Correction MAP") to significantly improve the structural and dynamic properties of proteins in crystalline and solution environments :ref:`(Brooks) <howto-Brooks>`. The AMBER force field does not include the CMAP term. The terms are computed by bond styles (relationship between 2 atoms),
angle styles (between 3 atoms) , dihedral/improper styles (between 4
atoms), pair styles (non-covalently bonded pair interactions) and
special bonds. The CMAP term (see :doc:`fix cmap <fix_cmap>` command for
details) corrects for pairs of dihedral angles ("Correction MAP") to
significantly improve the structural and dynamic properties of proteins
in crystalline and solution environments :ref:`(Brooks)
<howto-Brooks>`. The AMBER force field does not include the CMAP term.
The interaction styles listed below compute force field formulas that The interaction styles listed below compute force field formulas that
are consistent with common options in CHARMM or AMBER. See each are consistent with common options in CHARMM or AMBER. See each
@ -56,15 +68,28 @@ command's documentation for the formula it computes.
* :doc:`special_bonds <special_bonds>` charmm * :doc:`special_bonds <special_bonds>` charmm
* :doc:`special_bonds <special_bonds>` amber * :doc:`special_bonds <special_bonds>` amber
The pair styles compute Lennard Jones (LJ) and Coulombic interactions with additional switching or shifting functions that ramp the energy and/or force smoothly to zero between an inner :math:`(a)` and outer :math:`(b)` cutoff. The older styles with *charmm* (not *charmmfsw* or *charmmfsh*\ ) in their name compute the LJ and Coulombic interactions with an energy switching function (esw) S(r) which ramps the energy smoothly to zero between the inner and outer cutoff. This can cause irregularities in pairwise forces (due to the discontinuous second derivative of energy at the boundaries of the switching region), which in some cases can result in complications in energy minimization and detectable artifacts in MD simulations. The pair styles compute Lennard Jones (LJ) and Coulombic interactions
with additional switching or shifting functions that ramp the energy
and/or force smoothly to zero between an inner :math:`(a)` and outer
:math:`(b)` cutoff. The older styles with *charmm* (not *charmmfsw* or
*charmmfsh*\ ) in their name compute the LJ and Coulombic interactions
with an energy switching function (esw) S(r) which ramps the energy
smoothly to zero between the inner and outer cutoff. This can cause
irregularities in pairwise forces (due to the discontinuous second
derivative of energy at the boundaries of the switching region), which
in some cases can result in complications in energy minimization and
detectable artifacts in MD simulations.
.. grid:: 1 1 2 2
.. grid-item::
.. math:: .. math::
LJ(r) &= 4 \epsilon \left[ \left(\frac{\sigma}{r}\right)^{12} - LJ(r) &= 4 \epsilon \left[ \left(\frac{\sigma}{r}\right)^{12} -
\left(\frac{\sigma}{r}\right)^6 \right]\\[.6em] \left(\frac{\sigma}{r}\right)^6 \right]\\[.6em]
C(r) &= \frac{C q_i q_j}{ \epsilon r}\\[.6em] C(r) &= \frac{C q_i q_j}{ \epsilon r}\\[.6em]
S(r) &= \frac{ \left(b^2 - r^2\right)^2 S(r) &= \frac{ \left(b^2 - r^2\right)^2 \left(b^2 + 2r^2 - 3{a^2}\right)}
\left(b^2 + 2r^2 - 3{a^2}\right)}
{ \left(b^2 - a^2\right)^3 }\\[.6em] { \left(b^2 - a^2\right)^3 }\\[.6em]
E_{LJ}(r) &= \begin{cases} E_{LJ}(r) &= \begin{cases}
LJ(r), & r \leq a \\ LJ(r), & r \leq a \\
@ -77,12 +102,19 @@ The pair styles compute Lennard Jones (LJ) and Coulombic interactions with addit
0, & r > b 0, & r > b
\end{cases} \end{cases}
.. grid-item::
.. image:: img/howto_charmm_ELJ.png .. image:: img/howto_charmm_ELJ.png
:align: center :align: center
| The newer styles with *charmmfsw* or *charmmfsh* in their name replace
energy switching with force switching (fsw) for LJ interactions and
force shifting (fsh) functions for Coulombic interactions
:ref:`(Steinbach) <howto-Steinbach>`
The newer styles with *charmmfsw* or *charmmfsh* in their name replace energy switching with force switching (fsw) for LJ interactions and force shifting (fsh) functions for Coulombic interactions :ref:`(Steinbach) <howto-Steinbach>` .. grid:: 1 1 2 2
.. grid-item::
.. math:: .. math::
@ -101,12 +133,12 @@ The newer styles with *charmmfsw* or *charmmfsh* in their name replace energy sw
0, & r > b 0, & r > b
\end{cases} \end{cases}
.. grid-item::
.. image:: img/howto_charmmfsw_ELJ.png .. image:: img/howto_charmmfsw_ELJ.png
:align: center :align: center
| These styles are used by LAMMPS input scripts generated by
https://charmm-gui.org/ :ref:`(Brooks) <howto-Brooks>`.
These styles are used by LAMMPS input scripts generated by `charmm-gui.org <https://charmm-gui.org/>`_ :ref:`(Brooks) <howto-Brooks>`. A `minimal PDB example 1HVN <https://www.rcsb.org/structure/1HVN>`_ with at least one protein segment, at least one DNA segment, and no modified engineered residues is available in the ``lammps/examples/charmm/1hvn`` directory. A better example is `PDB 2CV5 <https://www.rcsb.org/structure/2CV5>`_ with size too big to include in lammps examples, which is left as an exercise to the reader (go to charmm-gui.org and type in 2CV5 in PDB field of Solution Builder to generate LAMMPS scripts to simulate a solvated human nucleosome with histone octamer and dsDNA wrapped around it).
.. note:: .. note::
@ -118,22 +150,31 @@ These styles are used by LAMMPS input scripts generated by `charmm-gui.org <http
.. note:: .. note::
TIP3P water model MUST be used with CHARMM force field not TIP4P, TIP5P or SPC. In fact, `"using the SPC model with CHARMM parameters is a bad idea" <https://matsci.org/t/using-spc-water-with-charmm-ff/24715>`_ and `"to enable TIP4P style water in CHARMM, you would have to write a new pair style" <https://matsci.org/t/hybrid-pair-styles-for-charmm-and-tip4p-ew/32609>`_ . LAMMPS input scripts generated by Solution Builder on charmm-gui.org use TIP3P molecules for solvation. Any other water model can and probably will lead to false conclusions. The TIP3P water model is strongly recommended for use with the CHARMM
force field. In fact, `"using the SPC model with CHARMM parameters is
a bad idea"
<https://matsci.org/t/using-spc-water-with-charmm-ff/24715>`_ and `"to
enable TIP4P style water in CHARMM, you would have to write a new pair
style"
<https://matsci.org/t/hybrid-pair-styles-for-charmm-and-tip4p-ew/32609>`_
. LAMMPS input scripts generated by Solution Builder on https://charmm-gui.org
use TIP3P molecules for solvation. Any other water model can and
probably will lead to false conclusions.
COMPASS COMPASS
------- -------
COMPASS is a general force field for atomistic simulation of common COMPASS is a general force field for atomistic simulation of common
organic molecules, inorganic small molecules, and polymers which was organic molecules, inorganic small molecules, and polymers which was
developed using ab initio and empirical parameterization techniques :ref:`(Sun) <howto-Sun>`. developed using ab initio and empirical parameterization techniques
See the :doc:`Tools <Tools>` page for the msi2lmp tool for creating :ref:`(Sun) <howto-Sun>`. See the :doc:`Tools <Tools>` page for the
LAMMPS template input and data files from BIOVIA's Materials Studio msi2lmp tool for creating LAMMPS template input and data files from
files. Please note that the msi2lmp tool is very old and largely BIOVIA's Materials Studio files. Please note that the msi2lmp tool is
unmaintained, so it does not support all features of Materials Studio very old and largely unmaintained, so it does not support all features
provided force field files, especially additions during the last decade. of Materials Studio provided force field files, especially additions
You should watch the output carefully and compare results, where during the last decade. You should watch the output carefully and
possible. See :ref:`(Sun) <howto-Sun>` for a description of the COMPASS force compare results, where possible. See :ref:`(Sun) <howto-Sun>` for a
field. description of the COMPASS force field.
These interaction styles listed below compute force field formulas that These interaction styles listed below compute force field formulas that
are consistent with the COMPASS force field. See each command's are consistent with the COMPASS force field. See each command's
@ -153,14 +194,18 @@ documentation for the formula it computes.
DREIDING DREIDING
-------- --------
DREIDING is a generic force field developed by the `Goddard group <http://www.wag.caltech.edu>`_ at Caltech and is useful for DREIDING is a generic force field developed by the `Goddard group
predicting structures and dynamics of organic, biological and main-group <http://www.wag.caltech.edu>`_ at Caltech and is useful for predicting
inorganic molecules. The philosophy in DREIDING is to use general force structures and dynamics of organic, biological and main-group inorganic
constants and geometry parameters based on simple hybridization molecules. The philosophy in DREIDING is to use general force constants
considerations, rather than individual force constants and geometric and geometry parameters based on simple hybridization considerations,
parameters that depend on the particular combinations of atoms involved rather than individual force constants and geometric parameters that
in the bond, angle, or torsion terms. DREIDING has an :doc:`explicit hydrogen bond term <pair_hbond_dreiding>` to describe interactions involving a depend on the particular combinations of atoms involved in the bond,
hydrogen atom on very electronegative atoms (N, O, F). angle, or torsion terms. DREIDING has an :doc:`explicit hydrogen bond
term <pair_hbond_dreiding>` to describe interactions involving a
hydrogen atom on very electronegative atoms (N, O, F). Unlike CHARMM
or AMBER, the DREIDING force field has not been parameterized for
considering solvents (like water).
See :ref:`(Mayo) <howto-Mayo>` for a description of the DREIDING force field See :ref:`(Mayo) <howto-Mayo>` for a description of the DREIDING force field
@ -199,26 +244,25 @@ documentation for the formula it computes.
.. _howto-MacKerell: .. _howto-MacKerell:
**(MacKerell)** MacKerell, Bashford, Bellott, Dunbrack, Evanseck, Field, **(MacKerell)** MacKerell, Bashford, Bellott, Dunbrack, Evanseck, Field, Fischer, Gao, Guo, Ha, et al (1998). J Phys Chem, 102, 3586 . https://doi.org/10.1021/jp973084f
Fischer, Gao, Guo, Ha, et al (1998). All-Atom Empirical Potential for Molecular Modeling and Dynamics Studies of Proteins. J Phys Chem, 102, 3586 . https://doi.org/10.1021/jp973084f
.. _howto-Cornell: .. _howto-Cornell:
**(Cornell)** Cornell, Cieplak, Bayly, Gould, Merz, Ferguson, **(Cornell)** Cornell, Cieplak, Bayly, Gould, Merz, Ferguson, Spellmeyer, Fox, Caldwell, Kollman (1995). JACS 117, 5179-5197. https://doi.org/10.1021/ja00124a002
Spellmeyer, Fox, Caldwell, Kollman (1995). A Second Generation Force Field for the Simulation of Proteins, Nucleic Acids, and Organic Molecules. JACS 117, 5179-5197. https://doi.org/10.1021/ja00124a002
.. _howto-Steinbach: .. _howto-Steinbach:
**(Steinbach)** Steinbach, Brooks (1994). New spherical-cutoff methods for long-range forces in macromolecular simulation. J Comput Chem, 15, 667. https://doi.org/10.1002/jcc.540150702 **(Steinbach)** Steinbach, Brooks (1994). J Comput Chem, 15, 667. https://doi.org/10.1002/jcc.540150702
.. _howto-Brooks: .. _howto-Brooks:
**(Brooks)** Brooks, et al (2009). CHARMM: The biomolecular simulation program. J Comput Chem, 30, 1545. https://onlinelibrary.wiley.com/doi/10.1002/jcc.21287 **(Brooks)** Brooks, et al (2009). J Comput Chem, 30, 1545. https://onlinelibrary.wiley.com/doi/10.1002/jcc.21287
.. _howto-Sun: .. _howto-Sun:
**(Sun)** Sun (1998). COMPASS: An ab Initio Force-Field Optimized for Condensed-Phase ApplicationsOverview with Details on Alkane and Benzene Compounds. J. Phys. Chem. B, 102, 7338-7364. https://doi.org/10.1021/jp980939v **(Sun)** Sun (1998). J. Phys. Chem. B, 102, 7338-7364. https://doi.org/10.1021/jp980939v
.. _howto-Mayo: .. _howto-Mayo:
**(Mayo)** Mayo, Olfason, Goddard III (1990). DREIDING: a generic force field for molecular simulations. J Phys Chem, 94, 8897-8909. https://doi.org/10.1021/j100389a010 **(Mayo)** Mayo, Olfason, Goddard III (1990). J Phys Chem, 94, 8897-8909. https://doi.org/10.1021/j100389a010

1
doc/utils/requirements.txt
View File

@ -1,6 +1,7 @@
Sphinx >= 5.3.0, <8.0 Sphinx >= 5.3.0, <8.0
sphinxcontrib-spelling sphinxcontrib-spelling
sphinxcontrib-jquery sphinxcontrib-jquery
sphinx-design
git+https://github.com/akohlmey/sphinx-fortran@parallel-read git+https://github.com/akohlmey/sphinx-fortran@parallel-read
sphinx-tabs>=3.4.1 sphinx-tabs>=3.4.1
breathe breathe

1
doc/utils/sphinx-config/conf.py.in
View File

@ -57,6 +57,7 @@ extensions = [
'table_from_list', 'table_from_list',
'tab_or_note', 'tab_or_note',
'breathe', 'breathe',
'sphinx_design'
] ]
images_config = { images_config = {