mtpl (c44b2)
Spherical Multipole Electrostatic Module using Local
Reference Axis Systems
by Tristan Bereau (bereau@alumni.cmu.edu)
Christian Kramer (christian.kramer@uibk.ac.at)
Markus Meuwly (m.meuwly@unibas.ch)
References:
T. Bereau, C. Kramer, M. Meuwly, submitted
T. Bereau et al., J. Phys. Chem. B _117_ 5460-5471 (2013)
C. Kramer, P. Gedeck, M. Meuwly, J. Comp. Chem. _33_ 1673--1688 (2012)
The MTPL module represents the charge distribution of small (diatomics) to
arbitrarily large molecules using a multipole (MTP) expansion in
spherical harmonics. MTP interactions are computed in the atoms' local
reference axis systems. This reduces the number of MTP interactions to be
evaluated by allowing to set coefficients to zero on the basis of symmetry. The
module computes both interaction energies and forces/torques for molecular
dynamics simulations.
* Coefficients | MTP coefficients
* Syntax | Syntax of the MTPL command
* Description | Description of the keywords and options
* Notes | General notes
Reference Axis Systems
by Tristan Bereau (bereau@alumni.cmu.edu)
Christian Kramer (christian.kramer@uibk.ac.at)
Markus Meuwly (m.meuwly@unibas.ch)
References:
T. Bereau, C. Kramer, M. Meuwly, submitted
T. Bereau et al., J. Phys. Chem. B _117_ 5460-5471 (2013)
C. Kramer, P. Gedeck, M. Meuwly, J. Comp. Chem. _33_ 1673--1688 (2012)
The MTPL module represents the charge distribution of small (diatomics) to
arbitrarily large molecules using a multipole (MTP) expansion in
spherical harmonics. MTP interactions are computed in the atoms' local
reference axis systems. This reduces the number of MTP interactions to be
evaluated by allowing to set coefficients to zero on the basis of symmetry. The
module computes both interaction energies and forces/torques for molecular
dynamics simulations.
* Coefficients | MTP coefficients
* Syntax | Syntax of the MTPL command
* Description | Description of the keywords and options
* Notes | General notes
Top
MTP coefficients
MTP interactions up to, and including, rank 2 (quadrupole) are implemented.
All MTP coefficients are expressed in spherical coordinates:
* 1 component for the monopole (i.e., partial charge): Q_00
* 3 components for the dipole: Q_10, Q_11c, Q_11s
* 5 components for the quadrupole: Q_20, Q_21c, Q_21s, Q_22c, Q_22s
The partial charges *replace* the charges read from a topology/PSF file.
The MTPL module computes all interactions *except* the charge-charge
interactions, which need to be taken care of by other modules (e.g., PME).
Any atom can be given an MTP rank between 0 (i.e., monopole) and 2 (i.e.,
quadrupole). Different ranks on different atoms can be used within the same
simulation.
MTP coefficients must be expressed in a modified PUN file that describes both
the MTP parameters on every atomic site and the associated local axis
system. All atoms must be specified in the same file, using the same atom ID
(and order) as in the psf file. The structure of the file consists is:
1. 3 lines for title/comments (unused)
2. atom ID; position x; position y; position z; "Rank"; rank
3. "LRA:"; lra; neighbor 1; neighbor 2; neighbor 3; neighbor 4
4. Q_00
5. Q_10; Q_11c; Q_11s
6. Q_20; Q_21c; Q_21s; Q_22c; Q_22s
7. *empty line*
8. *Repeat from step 2. to include more atoms*
where ";" corresponds to a blank space; 'lra' is the type of local reference
axis system, which can be one of the following: 'c3v', 'int', 'ter' (see
[Kramer, Gedeck, Meuwly, JCC _33_ (2012)]) as well as 'lin' for linear/diatomic
molecules (all of them without the single quotes); neighbor # is the atom ID of
a neighbor used to define the local axis system ('0' means no neighbor); and
Q_xx are the spherical MTP coefficients expressed in the local axis system.
The order and number of neighbors for each type of axis system is described in
Kramer et al., except for 'lin', where an atom has one neighbor if it's at a
terminal position and two neighbors (with the same priority rules as in Kramer
et al.) if it's an internal atom. The positions x, y, and z are not used in the
present implementation. The atom ID starts at 1 for the first particle, not 0.
The following is an example of such a file for a single water molecule
# LPUN file for a single water molecule
# MTP interactions expressed in the local axis system
1 O2HH 1.418 2.967 2.166 Rank 2
LRA: int 3 2 0 0
-0.4188
0.00 -0.00 -0.4358
-0.9632 0.00 0.00 0.4747 0.00
2 HO2H 2.185 3.54 2.157 Rank 2
LRA: ter 1 3 0 0
0.2094
-0.0279 0.00 0.00
0.17852 -0.0132 0.00 0.0278 0.00
3 HO2H 0.677 3.56 2.287 Rank 2
LRA: ter 1 2 0 0
0.2094
-0.0279 -0.00 0.00
0.17852 -0.0132 0.00 0.0278 0.00
Further assistance on the generation of this file will be provided in an
upcoming publication [Kramer, Bereau, Spinn, Liedle, Gedeck, Meuwly, in
preparation].
MTP coefficients
MTP interactions up to, and including, rank 2 (quadrupole) are implemented.
All MTP coefficients are expressed in spherical coordinates:
* 1 component for the monopole (i.e., partial charge): Q_00
* 3 components for the dipole: Q_10, Q_11c, Q_11s
* 5 components for the quadrupole: Q_20, Q_21c, Q_21s, Q_22c, Q_22s
The partial charges *replace* the charges read from a topology/PSF file.
The MTPL module computes all interactions *except* the charge-charge
interactions, which need to be taken care of by other modules (e.g., PME).
Any atom can be given an MTP rank between 0 (i.e., monopole) and 2 (i.e.,
quadrupole). Different ranks on different atoms can be used within the same
simulation.
MTP coefficients must be expressed in a modified PUN file that describes both
the MTP parameters on every atomic site and the associated local axis
system. All atoms must be specified in the same file, using the same atom ID
(and order) as in the psf file. The structure of the file consists is:
1. 3 lines for title/comments (unused)
2. atom ID; position x; position y; position z; "Rank"; rank
3. "LRA:"; lra; neighbor 1; neighbor 2; neighbor 3; neighbor 4
4. Q_00
5. Q_10; Q_11c; Q_11s
6. Q_20; Q_21c; Q_21s; Q_22c; Q_22s
7. *empty line*
8. *Repeat from step 2. to include more atoms*
where ";" corresponds to a blank space; 'lra' is the type of local reference
axis system, which can be one of the following: 'c3v', 'int', 'ter' (see
[Kramer, Gedeck, Meuwly, JCC _33_ (2012)]) as well as 'lin' for linear/diatomic
molecules (all of them without the single quotes); neighbor # is the atom ID of
a neighbor used to define the local axis system ('0' means no neighbor); and
Q_xx are the spherical MTP coefficients expressed in the local axis system.
The order and number of neighbors for each type of axis system is described in
Kramer et al., except for 'lin', where an atom has one neighbor if it's at a
terminal position and two neighbors (with the same priority rules as in Kramer
et al.) if it's an internal atom. The positions x, y, and z are not used in the
present implementation. The atom ID starts at 1 for the first particle, not 0.
The following is an example of such a file for a single water molecule
# LPUN file for a single water molecule
# MTP interactions expressed in the local axis system
1 O2HH 1.418 2.967 2.166 Rank 2
LRA: int 3 2 0 0
-0.4188
0.00 -0.00 -0.4358
-0.9632 0.00 0.00 0.4747 0.00
2 HO2H 2.185 3.54 2.157 Rank 2
LRA: ter 1 3 0 0
0.2094
-0.0279 0.00 0.00
0.17852 -0.0132 0.00 0.0278 0.00
3 HO2H 0.677 3.56 2.287 Rank 2
LRA: ter 1 2 0 0
0.2094
-0.0279 -0.00 0.00
0.17852 -0.0132 0.00 0.0278 0.00
Further assistance on the generation of this file will be provided in an
upcoming publication [Kramer, Bereau, Spinn, Liedle, Gedeck, Meuwly, in
preparation].
Top
Syntax of the MTPL command
MTPL MTPUNIT integer [PREF real] [cutoff-spec]
cutoff-spec::= [RON2 real] [ROFF2 real] [RON3 real] [ROFF3 real]
[RON4 real] [ROFF4 real] [RON5 real] [ROFF5 real]
Syntax of the MTPL command
MTPL MTPUNIT integer [PREF real] [cutoff-spec]
cutoff-spec::= [RON2 real] [ROFF2 real] [RON3 real] [ROFF3 real]
[RON4 real] [ROFF4 real] [RON5 real] [ROFF5 real]
Top
Description of the keywords and options
Keyword default Purpose
MTPUNIT read above-mentioned local PUN file (card format)
PREF 1.0 prefactor that scales all interaction energies and
forces/torques by PREF (needs to be between 0.0 and 1.0).
RON2 CTONNB Threshold value of the switching function for all
interactions with power law ~1/R^2.
RON3 CTONNB id. for ~1/R^3.
RON4 CTONNB id. for ~1/R^4.
RON5 CTONNB id. for ~1/R^5.
ROFF2 CTOFNB Cutoff value of the switching function for all interactions
with power law ~1/R^2.
ROFF3 CTOFNB id. for ~1/R^3.
ROFF4 CTOFNB id. for ~1/R^4.
ROFF5 CTOFNB id. for ~1/R^5.
Description of the keywords and options
Keyword default Purpose
MTPUNIT read above-mentioned local PUN file (card format)
PREF 1.0 prefactor that scales all interaction energies and
forces/torques by PREF (needs to be between 0.0 and 1.0).
RON2 CTONNB Threshold value of the switching function for all
interactions with power law ~1/R^2.
RON3 CTONNB id. for ~1/R^3.
RON4 CTONNB id. for ~1/R^4.
RON5 CTONNB id. for ~1/R^5.
ROFF2 CTOFNB Cutoff value of the switching function for all interactions
with power law ~1/R^2.
ROFF3 CTOFNB id. for ~1/R^3.
ROFF4 CTOFNB id. for ~1/R^4.
ROFF5 CTOFNB id. for ~1/R^5.
Top
General notes
* The use of the present module requires CHARMM to be compiled with the MTPL
flag.
* Parallelization (through MPI) is supported.
* The MTPL module converts the torques generated by the interactions into forces
on the neighboring atoms (the ones involved in an atom's local axis system).
For stability reasons, we advise the use of bond-constraint algorithms (e.g.,
SHAKE) on all bonds to hydrogens.
* The PREF option can show useful when one wishes to perform thermodynamic
integration. The interaction potential can simply be scaled to the coupling
constant linearly:
U_TI(q; lambda) = lambda * U_MTP(q)
where U_MTP(q) is the original interaction energy, q is the set of
coordinates, and lambda is the coupling parameter. In that case, the
simulation is run with PREF=lambda, and a later postprocessing read of the
trajectory can extract the energies with the original Hamiltonian (i.e.,
PREF=1.0), since the derivative of the interaction energy with respect to
lambda will yield the original interaction energy U_MTP(q).
* Increasing the PRNLEV to at least 5 will output the total MTP energy computed
by the module at every MD step.
* Compiling CHARMM with the MTPL_DEBUG flag will show detailed information about
the calculation of every energy and force/torque.
General notes
* The use of the present module requires CHARMM to be compiled with the MTPL
flag.
* Parallelization (through MPI) is supported.
* The MTPL module converts the torques generated by the interactions into forces
on the neighboring atoms (the ones involved in an atom's local axis system).
For stability reasons, we advise the use of bond-constraint algorithms (e.g.,
SHAKE) on all bonds to hydrogens.
* The PREF option can show useful when one wishes to perform thermodynamic
integration. The interaction potential can simply be scaled to the coupling
constant linearly:
U_TI(q; lambda) = lambda * U_MTP(q)
where U_MTP(q) is the original interaction energy, q is the set of
coordinates, and lambda is the coupling parameter. In that case, the
simulation is run with PREF=lambda, and a later postprocessing read of the
trajectory can extract the energies with the original Hamiltonian (i.e.,
PREF=1.0), since the derivative of the interaction energy with respect to
lambda will yield the original interaction energy U_MTP(q).
* Increasing the PRNLEV to at least 5 will output the total MTP energy computed
by the module at every MD step.
* Compiling CHARMM with the MTPL_DEBUG flag will show detailed information about
the calculation of every energy and force/torque.