From b1d1213dfd16a94c79af97d01c3b3edc6f14b50e Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 26 Jun 2024 07:30:50 -0400 Subject: [PATCH] reformate, make small corrections, align with other doc files and use sphinx-design to make html more compact --- doc/src/Howto_bioFF.rst | 184 ++++++++++++++++++----------- doc/utils/requirements.txt | 1 + doc/utils/sphinx-config/conf.py.in | 1 + 3 files changed, 116 insertions(+), 70 deletions(-) diff --git a/doc/src/Howto_bioFF.rst b/doc/src/Howto_bioFF.rst index a04ea5a157..7418a43861 100644 --- a/doc/src/Howto_bioFF.rst +++ b/doc/src/Howto_bioFF.rst @@ -15,12 +15,17 @@ commands like :doc:`pair_coeff ` or :doc:`bond_coeff ` and so on. See the :doc:`Tools ` doc page for additional tools that can use CHARMM, AMBER, or Materials Studio 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 `_. +output into LAMMPS input. LAMMPS input scripts can also be generated by +`charmm-gui.org `_. CHARMM and AMBER ---------------- -The `CHARMM force field `_ :ref:`(MacKerell) ` and `AMBER force field `_ :ref:`(Cornell) ` have potential energy function of the form +The `CHARMM force field +`_ :ref:`(MacKerell) +` and `AMBER force field +`_ :ref:`(Cornell) ` +have potential energy function of the form .. math:: @@ -38,7 +43,14 @@ The `CHARMM force field `_ :ref }} \!\!\!\!\!\!\!\!+ \!\!\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 ` 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) `. 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 ` 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) +`. The AMBER force field does not include the CMAP term. The interaction styles listed below compute force field formulas that are consistent with common options in CHARMM or AMBER. See each @@ -56,57 +68,77 @@ command's documentation for the formula it computes. * :doc:`special_bonds ` charmm * :doc:`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. -.. math:: +.. grid:: 1 1 2 2 - LJ(r) &= 4 \epsilon \left[ \left(\frac{\sigma}{r}\right)^{12} - - \left(\frac{\sigma}{r}\right)^6 \right]\\[.6em] - C(r) &= \frac{C q_i q_j}{ \epsilon r}\\[.6em] - S(r) &= \frac{ \left(b^2 - r^2\right)^2 - \left(b^2 + 2r^2 - 3{a^2}\right)} - { \left(b^2 - a^2\right)^3 }\\[.6em] - E_{LJ}(r) &= \begin{cases} - LJ(r), & r \leq a \\ - LJ(r) S(r), & a < r \leq b \\ - 0, &r > b - \end{cases} \\[.6em] - E_{coul}(r) &= \begin{cases} - C(r), & r \leq a \\ - C(r) S(r), & a < r \leq b \\ - 0, & r > b - \end{cases} + .. grid-item:: -.. image:: img/howto_charmm_ELJ.png - :align: center + .. math:: -| + LJ(r) &= 4 \epsilon \left[ \left(\frac{\sigma}{r}\right)^{12} - + \left(\frac{\sigma}{r}\right)^6 \right]\\[.6em] + C(r) &= \frac{C q_i q_j}{ \epsilon r}\\[.6em] + S(r) &= \frac{ \left(b^2 - r^2\right)^2 \left(b^2 + 2r^2 - 3{a^2}\right)} + { \left(b^2 - a^2\right)^3 }\\[.6em] + E_{LJ}(r) &= \begin{cases} + LJ(r), & r \leq a \\ + LJ(r) S(r), & a < r \leq b \\ + 0, &r > b + \end{cases} \\[.6em] + E_{coul}(r) &= \begin{cases} + C(r), & r \leq a \\ + C(r) S(r), & a < r \leq b \\ + 0, & r > b + \end{cases} -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) ` + .. grid-item:: -.. math:: + .. image:: img/howto_charmm_ELJ.png + :align: center - E_{LJ}(r) = & \begin{cases} - 4 \epsilon \sigma^6 \left(\frac{\displaystyle\sigma - ^6-r^6}{\displaystyle r^{12}}-\frac{\displaystyle\sigma ^6}{\displaystyle a^6 - b^6}+\frac{\displaystyle 1}{\displaystyle a^3 b^3}\right) & r\leq a \\ - \frac{\displaystyle 4 \epsilon \sigma^6 \left(\sigma ^6 - \left(b^6-r^6\right)^2-b^3 r^6 \left(a^3+b^3\right) - \left(b^3-r^3\right)^2\right)}{\displaystyle b^6 r^{12} - \left(b^6-a^6\right)} & ab - \end{cases}\\[.6em] - E_{coul}(r) & = \begin{cases} - C(r) \frac{\displaystyle (b-r)^2}{\displaystyle r b^2}, & r \leq b \\ - 0, & r > b - \end{cases} +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) ` -.. image:: img/howto_charmmfsw_ELJ.png - :align: center +.. grid:: 1 1 2 2 -| + .. grid-item:: -These styles are used by LAMMPS input scripts generated by `charmm-gui.org `_ :ref:`(Brooks) `. A `minimal PDB example 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 `_ 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). + .. math:: + + E_{LJ}(r) = & \begin{cases} + 4 \epsilon \sigma^6 \left(\frac{\displaystyle\sigma + ^6-r^6}{\displaystyle r^{12}}-\frac{\displaystyle\sigma ^6}{\displaystyle a^6 + b^6}+\frac{\displaystyle 1}{\displaystyle a^3 b^3}\right) & r\leq a \\ + \frac{\displaystyle 4 \epsilon \sigma^6 \left(\sigma ^6 + \left(b^6-r^6\right)^2-b^3 r^6 \left(a^3+b^3\right) + \left(b^3-r^3\right)^2\right)}{\displaystyle b^6 r^{12} + \left(b^6-a^6\right)} & ab + \end{cases}\\[.6em] + E_{coul}(r) & = \begin{cases} + C(r) \frac{\displaystyle (b-r)^2}{\displaystyle r b^2}, & r \leq b \\ + 0, & r > b + \end{cases} + + .. grid-item:: + .. image:: img/howto_charmmfsw_ELJ.png + :align: center + +These styles are used by LAMMPS input scripts generated by +https://charmm-gui.org/ :ref:`(Brooks) `. .. note:: @@ -118,22 +150,31 @@ These styles are used by LAMMPS input scripts generated by `charmm-gui.org `_ and `"to enable TIP4P style water in CHARMM, you would have to write a new pair style" `_ . 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" + `_ and `"to + enable TIP4P style water in CHARMM, you would have to write a new pair + style" + `_ + . 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 is a general force field for atomistic simulation of common organic molecules, inorganic small molecules, and polymers which was -developed using ab initio and empirical parameterization techniques :ref:`(Sun) `. -See the :doc:`Tools ` page for the msi2lmp tool for creating -LAMMPS template input and data files from BIOVIA's Materials Studio -files. Please note that the msi2lmp tool is very old and largely -unmaintained, so it does not support all features of Materials Studio -provided force field files, especially additions during the last decade. -You should watch the output carefully and compare results, where -possible. See :ref:`(Sun) ` for a description of the COMPASS force -field. +developed using ab initio and empirical parameterization techniques +:ref:`(Sun) `. See the :doc:`Tools ` page for the +msi2lmp tool for creating LAMMPS template input and data files from +BIOVIA's Materials Studio files. Please note that the msi2lmp tool is +very old and largely unmaintained, so it does not support all features +of Materials Studio provided force field files, especially additions +during the last decade. You should watch the output carefully and +compare results, where possible. See :ref:`(Sun) ` for a +description of the COMPASS force field. These interaction styles listed below compute force field formulas that are consistent with the COMPASS force field. See each command's @@ -153,14 +194,18 @@ documentation for the formula it computes. DREIDING -------- -DREIDING is a generic force field developed by the `Goddard group `_ at Caltech and is useful for -predicting structures and dynamics of organic, biological and main-group -inorganic molecules. The philosophy in DREIDING is to use general force -constants and geometry parameters based on simple hybridization -considerations, rather than individual force constants and geometric -parameters that depend on the particular combinations of atoms involved -in the bond, angle, or torsion terms. DREIDING has an :doc:`explicit hydrogen bond term ` to describe interactions involving a -hydrogen atom on very electronegative atoms (N, O, F). +DREIDING is a generic force field developed by the `Goddard group +`_ at Caltech and is useful for predicting +structures and dynamics of organic, biological and main-group inorganic +molecules. The philosophy in DREIDING is to use general force constants +and geometry parameters based on simple hybridization considerations, +rather than individual force constants and geometric parameters that +depend on the particular combinations of atoms involved in the bond, +angle, or torsion terms. DREIDING has an :doc:`explicit hydrogen bond +term ` 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) ` for a description of the DREIDING force field @@ -199,26 +244,25 @@ documentation for the formula it computes. .. _howto-MacKerell: -**(MacKerell)** MacKerell, Bashford, Bellott, Dunbrack, Evanseck, Field, -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 +**(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 .. _howto-Cornell: -**(Cornell)** Cornell, Cieplak, Bayly, Gould, Merz, Ferguson, -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 +**(Cornell)** Cornell, Cieplak, Bayly, Gould, Merz, Ferguson, Spellmeyer, Fox, Caldwell, Kollman (1995). JACS 117, 5179-5197. https://doi.org/10.1021/ja00124a002 .. _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: -**(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: -**(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: -**(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 + diff --git a/doc/utils/requirements.txt b/doc/utils/requirements.txt index 5bb8e3911d..83d4999dd7 100644 --- a/doc/utils/requirements.txt +++ b/doc/utils/requirements.txt @@ -1,6 +1,7 @@ Sphinx >= 5.3.0, <8.0 sphinxcontrib-spelling sphinxcontrib-jquery +sphinx-design git+https://github.com/akohlmey/sphinx-fortran@parallel-read sphinx-tabs>=3.4.1 breathe diff --git a/doc/utils/sphinx-config/conf.py.in b/doc/utils/sphinx-config/conf.py.in index c0805ba6b1..337485e689 100644 --- a/doc/utils/sphinx-config/conf.py.in +++ b/doc/utils/sphinx-config/conf.py.in @@ -57,6 +57,7 @@ extensions = [ 'table_from_list', 'tab_or_note', 'breathe', + 'sphinx_design' ] images_config = {