diff --git a/docs/user_guide/4.2ADMPPmeForce.md b/docs/user_guide/4.2ADMPPmeForce.md index 2353f4865..70e8394e0 100644 --- a/docs/user_guide/4.2ADMPPmeForce.md +++ b/docs/user_guide/4.2ADMPPmeForce.md @@ -7,9 +7,10 @@ ADMPmeForce provides a support to multipolar polarizable electrostatic energy ca ### 1.1 Multipole Expansion The electrostatic interaction between two atoms can be described using multipole expansion, in which the electron cloud of an atom can be expanded as a series of multipole moments including charges, dipoles, quadrupoles, and octupoles etc. If only the charges (zero-moment) are considered, it is reduced to the point charge model in classical force fields: -```math -V=\sum_{ij} \frac{q_i q_j}{r_{ij}} -``` + +$$ +V=\sum_{ij} \\frac{q_i q_j}{r_{ij}} +$$ where $q_i$ is the charge of atom $i$. @@ -23,7 +24,7 @@ where $Q_t^A$ represents the $t$-component of the multipole moment of atom $A$. $$0, 10, 1c, 1s, 20, 21c, 21s, 22c, 22s, ...$$ -The $T_{tu}^{AB}$ represents the interaction tensor between multipoles. The mathematical expression of these tensors can be found in the appendix F of Ref 1. The user can also find the conversion rule between different representations in Ref 1 & 5. +The $T_{tu}^{AB}$ represents the interaction tensor between multipoles. The mathematical expression of these tensors can be found in the appendix F of Ref 1. The user can also find the conversion rule between different representations in Ref 1. ### 1.2 Coordinate System for Multipoles @@ -37,7 +38,7 @@ Different to charges, the definition of multipole moments depends on local coord ### 1.3 Polarization -ADMPPmeForce supports polarizable force fields, in which the dipole moment of the atom can respond to the change of the external electric field. In practice, each atom has not only permanent multipoles $Q_t$, but also induced dipoles $U_{ind}$. The induced dipole-induced dipole and induced dipole-permanent multipole interactions needs to be damped at short-range to avoid polarization catastrophe. In DMFF, we use the Thole damping scheme identical to MPID (ref 6), which introduces a damping width ($a_i$) for each atom $i$. The damping function is then computed and applied to the corresponding interaction tensor. Taking $U_{ind}$-permanent charge interaction as an example, the definition of damping function is: +ADMPPmeForce supports polarizable force fields, in which the dipole moment of the atom can respond to the change of the external electric field. In practice, each atom has not only permanent multipoles $Q_t$, but also induced dipoles $U_{ind}$. The induced dipole-induced dipole and induced dipole-permanent multipole interactions needs to be damped at short-range to avoid polarization catastrophe. In DMFF, we use the Thole damping scheme identical to MPID (ref 5), which introduces a damping width ($a_i$) for each atom $i$. The damping function is then computed and applied to the corresponding interaction tensor. Taking $U_{ind}$-permanent charge interaction as an example, the definition of damping function is: $$ \displaylines{ @@ -47,7 +48,7 @@ u=r_{ij}/\left(\alpha_i \alpha_j\right)^{1/6} } $$ -Other damping functions between multipole moments can be found in Ref 6, table I. +Other damping functions between multipole moments can be found in Ref 5, table I. It is noted that the atomic damping parameter $a=a_i+a_j$ is only effective on topological neighboring pairs (with $pscale = 0$), while a default value of $a_{default}$ is set for all other pairs. In DMFF, the atomic $a_i$ is specified via the xml API, while $a_{default}$ is controlled by the `DEFAULT_THOLE_WIDTH` variable, which is set to 5.0 by default. This variable can be changed in the following way: @@ -113,7 +114,7 @@ E = E_{real}+E_{recip}+E_{self} } $$ -As for multipolar PME and dispersion PME, the users and developers are referred to Ref 2, 3, and 5 for mathematical details. +As for multipolar PME and dispersion PME, the users and developers are referred to Ref 2, 3 for mathematical details. The key parameters in PME include: @@ -143,8 +144,7 @@ In the current version, the dispersion PME calculator uses the same parameters a 2. [The Multipolar Ewald paper in JCTC: J. Chem. Theory Comput. 2015, 11, 2, 436–450](https://pubs.acs.org/doi/abs/10.1021/ct5007983) 3. [The dispersion Ewald/PME](https://aip.scitation.org/doi/pdf/10.1063/1.470117) 4. [Frenkel & Smit book](https://www.elsevier.com/books/understanding-molecular-simulation/frenkel/978-0-12-267351-1) -5. Note on multipole ewald. [link](multipole_pme.md) -6. [MPID Reference](https://doi.org/10.1063/1.4984113) +5. [MPID Reference](https://doi.org/10.1063/1.4984113) ## 2. Frontend @@ -237,13 +237,13 @@ The important tags in the frontend includes: For each atom type, there is an `` node, with the following tags: * `type`: the label for the atomtype. -* `C6, C8, C10`: dispersion terms, defined in `e*nm^n`. +* `C6, C8, C10`: dispersion terms, defined in `kj/mol/nm^n`. To create a DispADMP PME potential function, one needs to do the following in python: ```python H = Hamiltonian('forcefield.xml') -pots = H.createPotential(pdb.topology, nonbondedCutoff=rc*unit.nanometer, nonbondedMethod=app.PME, ethresh=5e-4, step_pol=5) +pots = H.createPotential(pdb.topology, nonbondedCutoff=rc*unit.nanometer, nonbondedMethod=app.PME, ethresh=5e-4) ``` Then the potential function, the parameters, and the generator can be accessed as: @@ -251,7 +251,7 @@ Then the potential function, the parameters, and the generator can be accessed a ```python efunc_pme = pots.dmff_potentials["ADMPDispPmeForce"] params_pme = H.getParameters()["ADMPDispPmeForce"] -generator_pme = H.getGenerators()[1] # if ADMPDispPmeForce is the Second force node in xml +generator_pme = H.getGenerators()[0] # if ADMPDispPmeForce is the First force node in xml ``` The keyword `ethresh` in `createPotential` would impact the behavior of the function: @@ -408,7 +408,7 @@ The backend of the ADMPDisp PME energy is an `ADMPDispPmeForce` object. It conta ***ATTRIBUTES:*** * `ethresh`: float, accuracy for PME setups * `kappa`: float, the range-separation parameter $\kappa$ used in PME calculation -* `lpme`: bool, use PME or not (sohuld be TRUE 99.9% of time) +* `lpme`: bool, use PME or not (should be TRUE 99.9% of time) * `n_atoms`: number of atoms * `pme_order`: order of PME interpolation, now only support 6 * `rc`: real space cutoffs @@ -442,3 +442,4 @@ The backend of the ADMPDisp PME energy is an `ADMPDispPmeForce` object. It conta * `get_forces` Same as `get_energy`, only return forces per atom, instead of total energy, equivalent to `jax.grad(get_energy)` +