diff --git a/doc/special_bonds.html b/doc/special_bonds.html index 252b7b0ae..d5d66ff83 100644 --- a/doc/special_bonds.html +++ b/doc/special_bonds.html @@ -1,247 +1,276 @@ <HTML> <CENTER><A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A> </CENTER> <HR> <H3>special_bonds command </H3> <P><B>Syntax:</B> </P> <PRE>special_bonds keyword values ... </PRE> <UL><LI>one or more keyword/value pairs may be appended <LI>keyword = <I>amber</I> or <I>charmm</I> or <I>dreiding</I> or <I>fene</I> or <I>lj/coul</I> or <I>lj</I> or <I>coul</I> or <I>angle</I> or <I>dihedral</I> or <I>extra</I> <PRE> <I>amber</I> values = none <I>charmm</I> values = none <I>dreiding</I> values = none <I>fene</I> values = none <I>lj/coul</I> values = w1,w2,w3 w1,w2,w3 = weights (0.0 to 1.0) on pairwise Lennard-Jones and Coulombic interactions <I>lj</I> values = w1,w2,w3 w1,w2,w3 = weights (0.0 to 1.0) on pairwise Lennard-Jones interactions <I>coul</I> values = w1,w2,w3 w1,w2,w3 = weights (0.0 to 1.0) on pairwise Coulombic interactions <I>angle</I> value = <I>yes</I> or <I>no</I> <I>dihedral</I> value = <I>yes</I> or <I>no</I> <I>extra</I> value = N N = number of extra 1-2,1-3,1-4 interactions to save space for </PRE> </UL> <P>Examples: </P> <PRE>special_bonds amber special_bonds charmm special_bonds fene dihedral no special_bonds lj/coul 0.0 0.0 0.5 angle yes dihedral yes special_bonds lj 0.0 0.0 0.5 coul 0.0 0.0 0.0 dihedral yes special_bonds lj/coul 0 1 1 extra 2 </PRE> <P><B>Description:</B> </P> <P>Set weighting coefficients for pairwise energy and force contributions between pairs of atoms that are also permanently bonded to each other, either directly or via one or two intermediate bonds. These weighting factors are used by nearly all <A HREF = "pair_style.html">pair styles</A> in LAMMPS that compute simple pairwise interactions. Permanent bonds between atoms are specified by defining the bond topology in the data file read by the <A HREF = "read_data.html">read_data</A> command. Typically a <A HREF = "bond_style.html">bond_style</A> command is also used to define a bond potential. The rationale for using these weighting factors is that the interaction between a pair of bonded atoms is all (or mostly) specified by the bond, angle, dihedral potentials, and thus the non-bonded Lennard-Jones or Coulombic interaction between the pair of atoms should be excluded (or reduced by a weighting factor). </P> <P>IMPORTANT NOTE: These weighting factors are NOT used by <A HREF = "pair_style.html">pair styles</A> that compute many-body interactions, since the "bonds" that result from such interactions are not permanent, but are created and broken dynamically as atom conformations change. Examples of pair styles in this category are EAM, MEAM, Stillinger-Weber, Tersoff, COMB, AIREBO, and ReaxFF. In fact, it generally makes no sense to define permanent bonds between atoms that interact via these potentials, though such bonds may exist elsewhere in your system, e.g. when using the <A HREF = "pair_hybrid.html">pair_style hybrid</A> command. Thus LAMMPS ignores special_bonds settings when manybody potentials are calculated. </P> +<P>IMPORTANT NOTE: Unlike some commands in LAMMPS, you cannot use this +command multiple times in an incremental fashion: e.g. to first set +the LJ settings and then the Coulombic ones. Each time you use this +command it sets all the coefficients to default values and only +overrides the one you specify, so you should set all the options you +need each time you use it. See more details at the bottom of this +page. +</P> <P>The Coulomb factors are applied to any Coulomb (charge interaction) term that the potential calculates. The LJ factors are applied to the remaining terms that the potential calculates, whether they represent LJ interactions or not. The weighting factors are a scaling pre-factor on the energy and force between the pair of atoms. A value of 1.0 means include the full interaction; a value of 0.0 means exclude it completely. </P> <P>The 1st of the 3 coefficients (LJ or Coulombic) is the weighting factor on 1-2 atom pairs, which are pairs of atoms directly bonded to each other. The 2nd coefficient is the weighting factor on 1-3 atom pairs which are those separated by 2 bonds (e.g. the two H atoms in a water molecule). The 3rd coefficient is the weighting factor on 1-4 atom pairs which are those separated by 3 bonds (e.g. the 1st and 4th atoms in a dihedral interaction). Thus if the 1-2 coefficient is set to 0.0, then the pairwise interaction is effectively turned off for all pairs of atoms bonded to each other. If it is set to 1.0, then that interaction will be at full strength. </P> <P>IMPORTANT NOTE: For purposes of computing weighted pairwise interactions, 1-3 and 1-4 interactions are not defined from the list of angles or dihedrals used by the simulation. Rather, they are inferred topologically from the set of bonds specified when the simulation is defined from a data or restart file (see <A HREF = "read_data.html">read_data</A> or <A HREF = "read_restart.html">read_restart</A> commands). Thus the set of 1-2,1-3,1-4 interactions that the weights apply to is the same whether angle and dihedral potentials are computed or not, and remains the same even if bonds are constrained, or turned off, or removed during a simulation. </P> <P>The two exceptions to this rule are (a) if the <I>angle</I> or <I>dihedral</I> keywords are set to <I>yes</I> (see below), or (b) if the <A HREF = "delete_bonds.html">delete_bonds</A> command is used with the <I>special</I> option that recomputes the 1-2,1-3,1-4 topologies after bonds are deleted; see the <A HREF = "delete_bonds.html">delete_bonds</A> command for more details. </P> <P>The <I>amber</I> keyword sets the 3 coefficients to 0.0, 0.0, 0.5 for LJ interactions and to 0.0, 0.0, 0.8333 for Coulombic interactions, which is the default for a commonly used version of the AMBER force field, where the last value is really 5/6. See <A HREF = "#Cornell">(Cornell)</A> for a description of the AMBER force field. </P> <P>The <I>charmm</I> keyword sets the 3 coefficients to 0.0, 0.0, 0.0 for both LJ and Coulombic interactions, which is the default for a commonly used version of the CHARMM force field. Note that in pair styles <I>lj/charmm/coul/charmm</I> and <I>lj/charmm/coul/long</I> the 1-4 coefficients are defined explicitly, and these pairwise contributions are computed as part of the charmm dihedral style - see the <A HREF = "pair_coeff.html">pair_coeff</A> and <A HREF = "dihedral_style.html">dihedral_style</A> commands for more information. See <A HREF = "#MacKerell">(MacKerell)</A> for a description of the CHARMM force field. </P> <P>The <I>dreiding</I> keyword sets the 3 coefficients to 0.0, 0.0, 1.0 for both LJ and Coulombic interactions, which is the default for the Dreiding force field, as discussed in <A HREF = "#Mayo">(Mayo)</A>. </P> <P>The <I>fene</I> keyword sets the 3 coefficients to 0.0, 1.0, 1.0 for both LJ and Coulombic interactions, which is consistent with a coarse-grained polymer model with <A HREF = "bond_fene.html">FENE bonds</A>. See <A HREF = "#Kremer">(Kremer)</A> for a description of FENE bonds. </P> <P>The <I>lj/coul</I>, <I>lj</I>, and <I>coul</I> keywords allow the 3 coefficients to be set explicitly. The <I>lj/coul</I> keyword sets both the LJ and Coulombic coefficients to the same 3 values. The <I>lj</I> and <I>coul</I> keywords only set either the LJ or Coulombic coefficients. Use both of them if you wish to set the LJ coefficients to different values than the Coulombic coefficients. </P> <P>The <I>angle</I> keyword allows the 1-3 weighting factor to be ignored for individual atom pairs if they are not listed as the first and last atoms in any angle defined in the simulation or as 1,3 or 2,4 atoms in any dihedral defined in the simulation. For example, imagine the 1-3 weighting factor is set to 0.5 and you have a linear molecule with 4 atoms and bonds as follows: 1-2-3-4. If your data file defines 1-2-3 as an angle, but does not define 2-3-4 as an angle or 1-2-3-4 as a dihedral, then the pairwise interaction between atoms 1 and 3 will always be weighted by 0.5, but different force fields use different rules for weighting the pairwise interaction between atoms 2 and 4. If the <I>angle</I> keyword is specified as <I>yes</I>, then the pairwise interaction between atoms 2 and 4 will be unaffected (full weighting of 1.0). If the <I>angle</I> keyword is specified as <I>no</I> which is the default, then the 2,4 interaction will also be weighted by 0.5. </P> <P>The <I>dihedral</I> keyword allows the 1-4 weighting factor to be ignored for individual atom pairs if they are not listed as the first and last atoms in any dihedral defined in the simulation. For example, imagine the 1-4 weighting factor is set to 0.5 and you have a linear molecule with 5 atoms and bonds as follows: 1-2-3-4-5. If your data file defines 1-2-3-4 as a dihedral, but does not define 2-3-4-5 as a dihedral, then the pairwise interaction between atoms 1 and 4 will always be weighted by 0.5, but different force fields use different rules for weighting the pairwise interaction between atoms 2 and 5. If the <I>dihedral</I> keyword is specified as <I>yes</I>, then the pairwise interaction between atoms 2 and 5 will be unaffected (full weighting of 1.0). If the <I>dihedral</I> keyword is specified as <I>no</I> which is the default, then the 2,5 interaction will also be weighted by 0.5. </P> <P>The <I>extra</I> keyword can be used when additional bonds will be created during a simulation run, e.g. by the <A HREF = "fix_bond_create.html">fix bond/create</A> command. It can also be used if molecules will be added to the system, e.g. via the <A HREF = "fix_deposit.html">fix deposit</A>, or <A HREF = "fix_pour.html">fix pour</A> commands, which will have atoms with more special neighbors than any atom in the current system has. </P> +<HR> + <P>IMPORTANT NOTE: LAMMPS stores and maintains a data structure with a list of the 1st, 2nd, and 3rd neighbors of each atom (within the bond topology of the system). If new bonds are created (or molecules added containing atoms with more special neighbors), the size of this list needs to grow. Note that adding a single bond always adds a new 1st neighbor but may also induce *many* new 2nd and 3rd neighbors, depending on the molecular topology of your syste. Using the <I>extra</I> keyword leaves empty space in the list for this N additional 1st, 2nd, or 3rd neighbors to be added. If you do not do this, you may get an error when bonds (or molecules) are added. </P> +<HR> + <P>IMPORTANT NOTE: If you reuse this command in an input script, you should set all the options you need each time. This command cannot be used a 2nd time incrementally, e.g. to add some extra storage locations via the <I>extra</I> keyword. E.g. these two commands: </P> +<P>special_bonds lj 0.0 1.0 1.0 +special_bonds coul 0.0 0.0 1.0 +</P> +<P>are not the same as +</P> +<P>special_bonds lj 0.0 1.0 1.0 coul 0.0 0.0 1.0 +</P> +<P>In the first case you end up with (after the 2nd command): +</P> +<P>LJ: 0.0 0.0 0.0 +Coul: coul 0.0 0.0 1.0 +</P> +<P>because the LJ settings are reset to their default values +each time the command is issued. +</P> +<P>Likewise +</P> <PRE>special_bonds amber special_bonds extra 2 </PRE> -<P>are not the same as this single command: +<P>is not the same as this single command: </P> <PRE>special_bonds amber extra 2 </PRE> <P>since in the former case, the 2nd command will reset all the LJ and Coulombic weights to 0.0 (the default). </P> <P>One exception to this rule is the <I>extra</I> option itself. It is not reset to its default value of 0 each time the special_bonds command is invoked. This is because it can also be set by the <A HREF = "read_data.html">read_data</A> and <A HREF = "create_box.html">create_box</A> commands, so this command will not override those settings unless you explicitly use <I>extra</I> as an option. </P> <P><B>Restrictions:</B> none </P> <P><B>Related commands:</B> </P> <P><A HREF = "delete_bonds.html">delete_bonds</A>, <A HREF = "fix_bond_create.html">fix bond/create</A> </P> <P><B>Default:</B> </P> <P>All 3 Lennard-Jones and 3 Coulombic weighting coefficients = 0.0, angle = no, dihedral = no, and extra = 0. </P> <HR> <A NAME = "Cornell"></A> <P><B>(Cornell)</B> Cornell, Cieplak, Bayly, Gould, Merz, Ferguson, Spellmeyer, Fox, Caldwell, Kollman, JACS 117, 5179-5197 (1995). </P> <A NAME = "Kremer"></A> <P><B>(Kremer)</B> Kremer, Grest, J Chem Phys, 92, 5057 (1990). </P> <A NAME = "MacKerell"></A> <P><B>(MacKerell)</B> MacKerell, Bashford, Bellott, Dunbrack, Evanseck, Field, Fischer, Gao, Guo, Ha, et al, J Phys Chem, 102, 3586 (1998). </P> <A NAME = "Mayo"></A> <P><B>(Mayo)</B> Mayo, Olfason, Goddard III, J Phys Chem, 94, 8897-8909 (1990). </P> </HTML> diff --git a/doc/special_bonds.txt b/doc/special_bonds.txt index 36918b7b5..3cafe85ee 100644 --- a/doc/special_bonds.txt +++ b/doc/special_bonds.txt @@ -1,235 +1,264 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line special_bonds command :h3 [Syntax:] special_bonds keyword values ... :pre one or more keyword/value pairs may be appended :ulb,l keyword = {amber} or {charmm} or {dreiding} or {fene} or {lj/coul} or {lj} or {coul} or {angle} or {dihedral} or {extra} :l {amber} values = none {charmm} values = none {dreiding} values = none {fene} values = none {lj/coul} values = w1,w2,w3 w1,w2,w3 = weights (0.0 to 1.0) on pairwise Lennard-Jones and Coulombic interactions {lj} values = w1,w2,w3 w1,w2,w3 = weights (0.0 to 1.0) on pairwise Lennard-Jones interactions {coul} values = w1,w2,w3 w1,w2,w3 = weights (0.0 to 1.0) on pairwise Coulombic interactions {angle} value = {yes} or {no} {dihedral} value = {yes} or {no} {extra} value = N N = number of extra 1-2,1-3,1-4 interactions to save space for :pre :ule Examples: special_bonds amber special_bonds charmm special_bonds fene dihedral no special_bonds lj/coul 0.0 0.0 0.5 angle yes dihedral yes special_bonds lj 0.0 0.0 0.5 coul 0.0 0.0 0.0 dihedral yes special_bonds lj/coul 0 1 1 extra 2 :pre [Description:] Set weighting coefficients for pairwise energy and force contributions between pairs of atoms that are also permanently bonded to each other, either directly or via one or two intermediate bonds. These weighting factors are used by nearly all "pair styles"_pair_style.html in LAMMPS that compute simple pairwise interactions. Permanent bonds between atoms are specified by defining the bond topology in the data file read by the "read_data"_read_data.html command. Typically a "bond_style"_bond_style.html command is also used to define a bond potential. The rationale for using these weighting factors is that the interaction between a pair of bonded atoms is all (or mostly) specified by the bond, angle, dihedral potentials, and thus the non-bonded Lennard-Jones or Coulombic interaction between the pair of atoms should be excluded (or reduced by a weighting factor). IMPORTANT NOTE: These weighting factors are NOT used by "pair styles"_pair_style.html that compute many-body interactions, since the "bonds" that result from such interactions are not permanent, but are created and broken dynamically as atom conformations change. Examples of pair styles in this category are EAM, MEAM, Stillinger-Weber, Tersoff, COMB, AIREBO, and ReaxFF. In fact, it generally makes no sense to define permanent bonds between atoms that interact via these potentials, though such bonds may exist elsewhere in your system, e.g. when using the "pair_style hybrid"_pair_hybrid.html command. Thus LAMMPS ignores special_bonds settings when manybody potentials are calculated. +IMPORTANT NOTE: Unlike some commands in LAMMPS, you cannot use this +command multiple times in an incremental fashion: e.g. to first set +the LJ settings and then the Coulombic ones. Each time you use this +command it sets all the coefficients to default values and only +overrides the one you specify, so you should set all the options you +need each time you use it. See more details at the bottom of this +page. + The Coulomb factors are applied to any Coulomb (charge interaction) term that the potential calculates. The LJ factors are applied to the remaining terms that the potential calculates, whether they represent LJ interactions or not. The weighting factors are a scaling pre-factor on the energy and force between the pair of atoms. A value of 1.0 means include the full interaction; a value of 0.0 means exclude it completely. The 1st of the 3 coefficients (LJ or Coulombic) is the weighting factor on 1-2 atom pairs, which are pairs of atoms directly bonded to each other. The 2nd coefficient is the weighting factor on 1-3 atom pairs which are those separated by 2 bonds (e.g. the two H atoms in a water molecule). The 3rd coefficient is the weighting factor on 1-4 atom pairs which are those separated by 3 bonds (e.g. the 1st and 4th atoms in a dihedral interaction). Thus if the 1-2 coefficient is set to 0.0, then the pairwise interaction is effectively turned off for all pairs of atoms bonded to each other. If it is set to 1.0, then that interaction will be at full strength. IMPORTANT NOTE: For purposes of computing weighted pairwise interactions, 1-3 and 1-4 interactions are not defined from the list of angles or dihedrals used by the simulation. Rather, they are inferred topologically from the set of bonds specified when the simulation is defined from a data or restart file (see "read_data"_read_data.html or "read_restart"_read_restart.html commands). Thus the set of 1-2,1-3,1-4 interactions that the weights apply to is the same whether angle and dihedral potentials are computed or not, and remains the same even if bonds are constrained, or turned off, or removed during a simulation. The two exceptions to this rule are (a) if the {angle} or {dihedral} keywords are set to {yes} (see below), or (b) if the "delete_bonds"_delete_bonds.html command is used with the {special} option that recomputes the 1-2,1-3,1-4 topologies after bonds are deleted; see the "delete_bonds"_delete_bonds.html command for more details. The {amber} keyword sets the 3 coefficients to 0.0, 0.0, 0.5 for LJ interactions and to 0.0, 0.0, 0.8333 for Coulombic interactions, which is the default for a commonly used version of the AMBER force field, where the last value is really 5/6. See "(Cornell)"_#Cornell for a description of the AMBER force field. The {charmm} keyword sets the 3 coefficients to 0.0, 0.0, 0.0 for both LJ and Coulombic interactions, which is the default for a commonly used version of the CHARMM force field. Note that in pair styles {lj/charmm/coul/charmm} and {lj/charmm/coul/long} the 1-4 coefficients are defined explicitly, and these pairwise contributions are computed as part of the charmm dihedral style - see the "pair_coeff"_pair_coeff.html and "dihedral_style"_dihedral_style.html commands for more information. See "(MacKerell)"_#MacKerell for a description of the CHARMM force field. The {dreiding} keyword sets the 3 coefficients to 0.0, 0.0, 1.0 for both LJ and Coulombic interactions, which is the default for the Dreiding force field, as discussed in "(Mayo)"_#Mayo. The {fene} keyword sets the 3 coefficients to 0.0, 1.0, 1.0 for both LJ and Coulombic interactions, which is consistent with a coarse-grained polymer model with "FENE bonds"_bond_fene.html. See "(Kremer)"_#Kremer for a description of FENE bonds. The {lj/coul}, {lj}, and {coul} keywords allow the 3 coefficients to be set explicitly. The {lj/coul} keyword sets both the LJ and Coulombic coefficients to the same 3 values. The {lj} and {coul} keywords only set either the LJ or Coulombic coefficients. Use both of them if you wish to set the LJ coefficients to different values than the Coulombic coefficients. The {angle} keyword allows the 1-3 weighting factor to be ignored for individual atom pairs if they are not listed as the first and last atoms in any angle defined in the simulation or as 1,3 or 2,4 atoms in any dihedral defined in the simulation. For example, imagine the 1-3 weighting factor is set to 0.5 and you have a linear molecule with 4 atoms and bonds as follows: 1-2-3-4. If your data file defines 1-2-3 as an angle, but does not define 2-3-4 as an angle or 1-2-3-4 as a dihedral, then the pairwise interaction between atoms 1 and 3 will always be weighted by 0.5, but different force fields use different rules for weighting the pairwise interaction between atoms 2 and 4. If the {angle} keyword is specified as {yes}, then the pairwise interaction between atoms 2 and 4 will be unaffected (full weighting of 1.0). If the {angle} keyword is specified as {no} which is the default, then the 2,4 interaction will also be weighted by 0.5. The {dihedral} keyword allows the 1-4 weighting factor to be ignored for individual atom pairs if they are not listed as the first and last atoms in any dihedral defined in the simulation. For example, imagine the 1-4 weighting factor is set to 0.5 and you have a linear molecule with 5 atoms and bonds as follows: 1-2-3-4-5. If your data file defines 1-2-3-4 as a dihedral, but does not define 2-3-4-5 as a dihedral, then the pairwise interaction between atoms 1 and 4 will always be weighted by 0.5, but different force fields use different rules for weighting the pairwise interaction between atoms 2 and 5. If the {dihedral} keyword is specified as {yes}, then the pairwise interaction between atoms 2 and 5 will be unaffected (full weighting of 1.0). If the {dihedral} keyword is specified as {no} which is the default, then the 2,5 interaction will also be weighted by 0.5. The {extra} keyword can be used when additional bonds will be created during a simulation run, e.g. by the "fix bond/create"_fix_bond_create.html command. It can also be used if molecules will be added to the system, e.g. via the "fix deposit"_fix_deposit.html, or "fix pour"_fix_pour.html commands, which will have atoms with more special neighbors than any atom in the current system has. +:line + IMPORTANT NOTE: LAMMPS stores and maintains a data structure with a list of the 1st, 2nd, and 3rd neighbors of each atom (within the bond topology of the system). If new bonds are created (or molecules added containing atoms with more special neighbors), the size of this list needs to grow. Note that adding a single bond always adds a new 1st neighbor but may also induce *many* new 2nd and 3rd neighbors, depending on the molecular topology of your syste. Using the {extra} keyword leaves empty space in the list for this N additional 1st, 2nd, or 3rd neighbors to be added. If you do not do this, you may get an error when bonds (or molecules) are added. +:line + IMPORTANT NOTE: If you reuse this command in an input script, you should set all the options you need each time. This command cannot be used a 2nd time incrementally, e.g. to add some extra storage locations via the {extra} keyword. E.g. these two commands: +special_bonds lj 0.0 1.0 1.0 +special_bonds coul 0.0 0.0 1.0 + +are not the same as + +special_bonds lj 0.0 1.0 1.0 coul 0.0 0.0 1.0 + +In the first case you end up with (after the 2nd command): + +LJ: 0.0 0.0 0.0 +Coul: coul 0.0 0.0 1.0 + +because the LJ settings are reset to their default values +each time the command is issued. + +Likewise + special_bonds amber special_bonds extra 2 :pre -are not the same as this single command: +is not the same as this single command: special_bonds amber extra 2 :pre since in the former case, the 2nd command will reset all the LJ and Coulombic weights to 0.0 (the default). One exception to this rule is the {extra} option itself. It is not reset to its default value of 0 each time the special_bonds command is invoked. This is because it can also be set by the "read_data"_read_data.html and "create_box"_create_box.html commands, so this command will not override those settings unless you explicitly use {extra} as an option. [Restrictions:] none [Related commands:] "delete_bonds"_delete_bonds.html, "fix bond/create"_fix_bond_create.html [Default:] All 3 Lennard-Jones and 3 Coulombic weighting coefficients = 0.0, angle = no, dihedral = no, and extra = 0. :line :link(Cornell) [(Cornell)] Cornell, Cieplak, Bayly, Gould, Merz, Ferguson, Spellmeyer, Fox, Caldwell, Kollman, JACS 117, 5179-5197 (1995). :link(Kremer) [(Kremer)] Kremer, Grest, J Chem Phys, 92, 5057 (1990). :link(MacKerell) [(MacKerell)] MacKerell, Bashford, Bellott, Dunbrack, Evanseck, Field, Fischer, Gao, Guo, Ha, et al, J Phys Chem, 102, 3586 (1998). :link(Mayo) [(Mayo)] Mayo, Olfason, Goddard III, J Phys Chem, 94, 8897-8909 (1990).