mscale (c49b1)
Multi Scale Command: MSCALE
by Milan Hodoscek and Bernard Brooks
The multiscale command causes CHARMM to run several
independent but connected calculations using subsystems. The
calculations can use either CHARMM or other programs with a consistent
interface. For general information and some of the usage see the reference:
Woodcock HL, Miller BT, Hodoscek M, Okur A, Larkin JD, Ponder JW,
Brooks BR, "MSCALE: A General Utility for Multiscale Modeling",
J. Chem. Theo. and Comp., 2011, Vol 7, 1208-1219.
* Syntax | Syntax of the mscale specification
* REPDSTR | Notes to run the MSCAle command with REPDSTR
* Examples | Examples to run the MSCAle command
* Notes | Notes abot the MSCAle command
by Milan Hodoscek and Bernard Brooks
The multiscale command causes CHARMM to run several
independent but connected calculations using subsystems. The
calculations can use either CHARMM or other programs with a consistent
interface. For general information and some of the usage see the reference:
Woodcock HL, Miller BT, Hodoscek M, Okur A, Larkin JD, Ponder JW,
Brooks BR, "MSCALE: A General Utility for Multiscale Modeling",
J. Chem. Theo. and Comp., 2011, Vol 7, 1208-1219.
* Syntax | Syntax of the mscale specification
* REPDSTR | Notes to run the MSCAle command with REPDSTR
* Examples | Examples to run the MSCAle command
* Notes | Notes abot the MSCAle command
Top
[SYNTAX MSCAle]
Main script commands:
MSCAle [ NSUBsystems integer ] [ UPEN integer [ REDU ] ]
SUBSystem keyname [ PROGram filename ] [ CRYStal ] [ ATOM ] -
[ AMBEr ] [ TORQue ] [ FCHArge ] -
[ NPROC integer ] [ FNPR integer ] -
[ COEFf real ] [ LAMBda ] [ MLAMbda ] -
[ INPUt filename ] [ OUTPut filename ] atom-selection
SYSDisplay
END
Subsystem commands:
SERVer [ NCALls integer ] [ ATOM ] [ CRYStal ] [ TORQue ] [ DEBUg ]
Meaning of individual keywords:
SUBSystem - Create a new subsystem
NSUBS - the number of SUBSystems to be setup
If NSUBs -1 the mscale section does nothing but is
needed when part of the distributed replica run (REPDSTR)
keyname - Always read but currently not used for further usage in the
code. Must follow immediately the SUBSystem keyword.
This is the name of the subsystem.
COEFf real - coefficient with which to scale the energy/forces
of this subsystem
LAMBda - Also scale by PERT's lambda value
MLAMbda - Also scale by PERT's 1-lambda value
ATOM - Flag to decide on communication of atom data:
number of atoms in this subsystem and their atomic
numbers in floating point format
NPROC - How many processes this subsystem will use. eg
semipempirical methods 1, since they are not
parallel, but ab initio and some MM methods can use
parallel here.
FNPRoc - Forward this number to the program which is run
through the interface in CALL SYSTEM(). Only works
with ATOM flag!
AMBEr - Specify that the specified program is a SANDER executable
from AMBER. This option calls the PROGram with the
"-server" command line argument, which is needed to start
SANDER as an MSCALE server.
FCHArge - Fluctuating charges. This key-word indicates that the
charge on the subsystem may change over time (as dictated
by the main processor). The charge array will be broadcast
to the subsystem at each integration step.
The folowing 3 keywords must be specified. There are no defaults for them!
PROGram - the filename of the program to execute for this subsystem
INPUt - the filename of the script to run on the subsystem
OUTPut - the filename of the output from the program
CRYStal - communicate the crystal type (CUBIc, RHDO, etc.), unit cell
data, and the virial. This option must be specified in both
the SUBSystem and SERVer commands.
TORQue - indicates that the 3x3 rotation matrix of any defined torque
centers (» torque ) within the atom-selection is to
be passed via MSCALe to the slaves andf the 1x3 torque vector
is to be returned to the master process. This option must be
specified in both the SUBSystem and SERVer commands.
SYSDisplay - Display the info about the whole setup
END - Must be specified to end the MSCAle block.
SERVer - Put CHARMM in server mode.
NCALLs integer - Number of energy calls in server mode before going
to next CHARMM command in the server script.
If the number is not specified, the command will
run until the client terminates.
DEBUg - Makes the server print out the results of each energy evaluation
that it performs. This option is useful for debugging, but
probably should not be used for long runs (it will produce too
much output).
UPEN - If a Fortran unit number is specified, the energy of each
subsystem and the EDS energy (if EDS is being used, » eds
for details) will be written to it at each energy evaluation. This
can assist in debugging or calculating the EDS free energies.
REDU - If UPEN is used, the REDU key-word will only write data to
the log in energy calls made from the dynamics subroutines.
As of c36a1 MSCAle now supports normal mode (i.e. second derivatives) at both
the all-atom and hybrid QM/MM levels of theory. Both analytic and finite
difference 2nd derivatives are supported. To activate the finite difference
2nd derivatives use the following SERVer command (see vibran_mscale, vsys1.inp,
or vsys2.inp in c35test)...
SERVer finite step 0.005
where 0.005 is the step size used during the finite difference calculation.
[SYNTAX MSCAle]
Main script commands:
MSCAle [ NSUBsystems integer ] [ UPEN integer [ REDU ] ]
SUBSystem keyname [ PROGram filename ] [ CRYStal ] [ ATOM ] -
[ AMBEr ] [ TORQue ] [ FCHArge ] -
[ NPROC integer ] [ FNPR integer ] -
[ COEFf real ] [ LAMBda ] [ MLAMbda ] -
[ INPUt filename ] [ OUTPut filename ] atom-selection
SYSDisplay
END
Subsystem commands:
SERVer [ NCALls integer ] [ ATOM ] [ CRYStal ] [ TORQue ] [ DEBUg ]
Meaning of individual keywords:
SUBSystem - Create a new subsystem
NSUBS - the number of SUBSystems to be setup
If NSUBs -1 the mscale section does nothing but is
needed when part of the distributed replica run (REPDSTR)
keyname - Always read but currently not used for further usage in the
code. Must follow immediately the SUBSystem keyword.
This is the name of the subsystem.
COEFf real - coefficient with which to scale the energy/forces
of this subsystem
LAMBda - Also scale by PERT's lambda value
MLAMbda - Also scale by PERT's 1-lambda value
ATOM - Flag to decide on communication of atom data:
number of atoms in this subsystem and their atomic
numbers in floating point format
NPROC - How many processes this subsystem will use. eg
semipempirical methods 1, since they are not
parallel, but ab initio and some MM methods can use
parallel here.
FNPRoc - Forward this number to the program which is run
through the interface in CALL SYSTEM(). Only works
with ATOM flag!
AMBEr - Specify that the specified program is a SANDER executable
from AMBER. This option calls the PROGram with the
"-server" command line argument, which is needed to start
SANDER as an MSCALE server.
FCHArge - Fluctuating charges. This key-word indicates that the
charge on the subsystem may change over time (as dictated
by the main processor). The charge array will be broadcast
to the subsystem at each integration step.
The folowing 3 keywords must be specified. There are no defaults for them!
PROGram - the filename of the program to execute for this subsystem
INPUt - the filename of the script to run on the subsystem
OUTPut - the filename of the output from the program
CRYStal - communicate the crystal type (CUBIc, RHDO, etc.), unit cell
data, and the virial. This option must be specified in both
the SUBSystem and SERVer commands.
TORQue - indicates that the 3x3 rotation matrix of any defined torque
centers (» torque ) within the atom-selection is to
be passed via MSCALe to the slaves andf the 1x3 torque vector
is to be returned to the master process. This option must be
specified in both the SUBSystem and SERVer commands.
SYSDisplay - Display the info about the whole setup
END - Must be specified to end the MSCAle block.
SERVer - Put CHARMM in server mode.
NCALLs integer - Number of energy calls in server mode before going
to next CHARMM command in the server script.
If the number is not specified, the command will
run until the client terminates.
DEBUg - Makes the server print out the results of each energy evaluation
that it performs. This option is useful for debugging, but
probably should not be used for long runs (it will produce too
much output).
UPEN - If a Fortran unit number is specified, the energy of each
subsystem and the EDS energy (if EDS is being used, » eds
for details) will be written to it at each energy evaluation. This
can assist in debugging or calculating the EDS free energies.
REDU - If UPEN is used, the REDU key-word will only write data to
the log in energy calls made from the dynamics subroutines.
As of c36a1 MSCAle now supports normal mode (i.e. second derivatives) at both
the all-atom and hybrid QM/MM levels of theory. Both analytic and finite
difference 2nd derivatives are supported. To activate the finite difference
2nd derivatives use the following SERVer command (see vibran_mscale, vsys1.inp,
or vsys2.inp in c35test)...
SERVer finite step 0.005
where 0.005 is the step size used during the finite difference calculation.
Top
It is possible to combine MSCALe setup with distributed replica
(REPDSTR) in CHARMM. CHARMM must be compiled with the following commands.
To use the CMake infrastructure, execute
$ ./configure --with-repdstr --add mscale
$ make -C build/cmake install
Each of the replica input script may have different mscale
setups, including no mscale. However when mscale is not used in the
replica one still need to specify MSCAle NSUB -1 in the input
script. See the test case c38test/repdmscale.inp for more details.
It is possible to combine MSCALe setup with distributed replica
(REPDSTR) in CHARMM. CHARMM must be compiled with the following commands.
To use the CMake infrastructure, execute
$ ./configure --with-repdstr --add mscale
$ make -C build/cmake install
Each of the replica input script may have different mscale
setups, including no mscale. However when mscale is not used in the
replica one still need to specify MSCAle NSUB -1 in the input
script. See the test case c38test/repdmscale.inp for more details.
Top
EXAMPLE 1: Typical input for substraction method (ONIOM):
Main script:
READ/GENERATE PSF
READ PARAM
READ COOR
MSCAle NSUBs 2
SUBSystem high coef 1.0 program "charmm" input "sub1.inp" -
output "sub1.out" sele resid 4 end
SUBSystem low coef -1.0 program "charmm" input "sub2.inp" -
output "sub2.out" sele resid 4 end
END
DYNA ....
Subsystem 1 (sub1.inp)
READ/GENERATE PSF for one residue
READ PARAM (one kind of parameters)
READ COOR
NBONDS
SERVER
Subsystem 2 (sub2.inp)
READ/GENERATE PSF for one residue
READ PARAM (different kind of parameters than in one)
READ COOR
NBONDS
SERVER
EXAMPLE 1: Typical input for substraction method (ONIOM):
Main script:
READ/GENERATE PSF
READ PARAM
READ COOR
MSCAle NSUBs 2
SUBSystem high coef 1.0 program "charmm" input "sub1.inp" -
output "sub1.out" sele resid 4 end
SUBSystem low coef -1.0 program "charmm" input "sub2.inp" -
output "sub2.out" sele resid 4 end
END
DYNA ....
Subsystem 1 (sub1.inp)
READ/GENERATE PSF for one residue
READ PARAM (one kind of parameters)
READ COOR
NBONDS
SERVER
Subsystem 2 (sub2.inp)
READ/GENERATE PSF for one residue
READ PARAM (different kind of parameters than in one)
READ COOR
NBONDS
SERVER
Top
Miscellaneous Notes:
I.
To dynamically start new processes in parallel MPI-2 standard is used,
namely MPI_COMM_SPAWN routine. It is availalble in OpenMPI library
(currently in use) and MPICH-2.
As of July 2018 the recommended commands to compile CHARMM are the
following.
To use the cmake infrastructure, execute
$ ./configure --with-repdstr --add mscale
$ make -C build/cmake install
II.
Matrices for coefficients in substraction methods:
L=low level theory, H=high level theory
B=big system, S=small system
B S
L 1 -1
H 0 1
If you have 3 levels:L, M, H, and 3 reagions B, M, S: B > M > S!
B M S
L 1 -1 0
M 0 1 -1
H 0 0 1
III.
How to do the additive methods ?
Miscellaneous Notes:
I.
To dynamically start new processes in parallel MPI-2 standard is used,
namely MPI_COMM_SPAWN routine. It is availalble in OpenMPI library
(currently in use) and MPICH-2.
As of July 2018 the recommended commands to compile CHARMM are the
following.
To use the cmake infrastructure, execute
$ ./configure --with-repdstr --add mscale
$ make -C build/cmake install
II.
Matrices for coefficients in substraction methods:
L=low level theory, H=high level theory
B=big system, S=small system
B S
L 1 -1
H 0 1
If you have 3 levels:L, M, H, and 3 reagions B, M, S: B > M > S!
B M S
L 1 -1 0
M 0 1 -1
H 0 0 1
III.
How to do the additive methods ?
Top
MSCAle Interfaces contributed by: H. Lee Woodcock (hlwood-at-nih-dot-gov),
Benjamin T. Miller (btmiller-at-nhlbi-dot-nih-dot-gov), Joseph D. Larkin
(larkinj3-at-nhlbi-dot-nih-dot-gov), and Milan Hodoscek
(milan-at-cmm-dot-ki-dot-si).
Currently four (4) external QM programs are interfaced to CHARMM via the
MSCAle command. These programs are in addition to the currently supported
QM packages that are interfaced with CHARMM (GAMESS, GAMESS-UK, Q-Chem,
SCC-DFTB, ect.).
1. NWChem (http://www.emsl.pnl.gov/docs/nwchem/nwchem.html)
2. MOLPRO (http://www.molpro.net/)
3. PSI 3 (http://www.psicode.org/) License:(GPL)
4. GAUSSIAN 03 (http://www.gaussian.com/)
Support for additional QM packages is underway and will be added in the
future. To request support for a particular package please contact
H. Lee Woodcock, Joseph D. Larkin, or Milan Hodoscek.
Below are examples of how to run the various QM packages via MSCAle. All
packages require a control file that dictates the options to be passed
to the individual package.
-----------------------------------------------------------------------------
1. NWChem: Here is an example of control file that is needed for a NWChem
calculation...
title "for interface"
basis "ao basis"
* library "6-31g*"
end
geometry noautosym
end
task dft gradient
task shell "/bin/rm -f sys1.b sys1.b^-1 sys1.c sys1.db"
task shell "/bin/rm -f sys1.gridpts.0 sys1.grinfo.0"
task shell "/bin/rm -f sys1.movecs sys1.p sys1.zmat"
-----------------------------------------------------------------------------
2. MOLPRO: Here is an example of control file that is needed for a MOLPRO
calculation...
***Title
memory,1,m
SET,CHARGE=0
BASIS=sto-3g
thresh,energy=1.d-10
hf
optg,maxit=0,coord=cart,startcmd=hf
-----------------------------------------------------------------------------
This file will perform a single SCF analytic gradient calculation. If a method
that does not support analytic gradients (i.e. CCSD(T)) is desired the "optg"
line must be changed to read like the following line:
optg,numerical,maxit=0,coord=cart,displace=cart,startcmd=hf
The correct geometry section will be written with the correct keywords immediately
following the line containing the "memory" specification.
-----------------------------------------------------------------------------
3. PSI 3: Here is an example of control file that is needed for a PSI 3
calculation...
psi: (
label = "Title"
no_reorient=true
subgroup=c1
jobtype = sp
wfn = scf
reference = rhf
dertype = first
basis = "STO-3G"
geometry = (
)
In this case the "no_reorient" keyword must be used to keep all forces in the
correct reference frame. The current molecular geometry will be placed automatically
in the "geometry" section.
-----------------------------------------------------------------------------
4. Gaussian 03: Here is an example of control file that is needed for a G03
calculation...
%mem=100MB
%NProcShared=2
%NProcLinda=4
#HF/sto-3g FORCE NOSYMM
***user specified title
0 1
-----------------------------------------------------------------------------
Here it should be noted the last line in the control file should be the spin
and multiplicity specifications. i.e. there should be no blank line at the
end of this control file as there is in a typical gaussian input file as the
current geometry will be appended and the final blank line inserted afterwards.
Additionally, interfaces have been developed to the SANDER program (part of
the AMBER package) and to the TINKER program. Please contact Benjamin T. Miller
for further information about these interfaces.
MSCAle Interfaces contributed by: H. Lee Woodcock (hlwood-at-nih-dot-gov),
Benjamin T. Miller (btmiller-at-nhlbi-dot-nih-dot-gov), Joseph D. Larkin
(larkinj3-at-nhlbi-dot-nih-dot-gov), and Milan Hodoscek
(milan-at-cmm-dot-ki-dot-si).
Currently four (4) external QM programs are interfaced to CHARMM via the
MSCAle command. These programs are in addition to the currently supported
QM packages that are interfaced with CHARMM (GAMESS, GAMESS-UK, Q-Chem,
SCC-DFTB, ect.).
1. NWChem (http://www.emsl.pnl.gov/docs/nwchem/nwchem.html)
2. MOLPRO (http://www.molpro.net/)
3. PSI 3 (http://www.psicode.org/) License:(GPL)
4. GAUSSIAN 03 (http://www.gaussian.com/)
Support for additional QM packages is underway and will be added in the
future. To request support for a particular package please contact
H. Lee Woodcock, Joseph D. Larkin, or Milan Hodoscek.
Below are examples of how to run the various QM packages via MSCAle. All
packages require a control file that dictates the options to be passed
to the individual package.
-----------------------------------------------------------------------------
1. NWChem: Here is an example of control file that is needed for a NWChem
calculation...
title "for interface"
basis "ao basis"
* library "6-31g*"
end
geometry noautosym
end
task dft gradient
task shell "/bin/rm -f sys1.b sys1.b^-1 sys1.c sys1.db"
task shell "/bin/rm -f sys1.gridpts.0 sys1.grinfo.0"
task shell "/bin/rm -f sys1.movecs sys1.p sys1.zmat"
-----------------------------------------------------------------------------
2. MOLPRO: Here is an example of control file that is needed for a MOLPRO
calculation...
***Title
memory,1,m
SET,CHARGE=0
BASIS=sto-3g
thresh,energy=1.d-10
hf
optg,maxit=0,coord=cart,startcmd=hf
-----------------------------------------------------------------------------
This file will perform a single SCF analytic gradient calculation. If a method
that does not support analytic gradients (i.e. CCSD(T)) is desired the "optg"
line must be changed to read like the following line:
optg,numerical,maxit=0,coord=cart,displace=cart,startcmd=hf
The correct geometry section will be written with the correct keywords immediately
following the line containing the "memory" specification.
-----------------------------------------------------------------------------
3. PSI 3: Here is an example of control file that is needed for a PSI 3
calculation...
psi: (
label = "Title"
no_reorient=true
subgroup=c1
jobtype = sp
wfn = scf
reference = rhf
dertype = first
basis = "STO-3G"
geometry = (
)
In this case the "no_reorient" keyword must be used to keep all forces in the
correct reference frame. The current molecular geometry will be placed automatically
in the "geometry" section.
-----------------------------------------------------------------------------
4. Gaussian 03: Here is an example of control file that is needed for a G03
calculation...
%mem=100MB
%NProcShared=2
%NProcLinda=4
#HF/sto-3g FORCE NOSYMM
***user specified title
0 1
-----------------------------------------------------------------------------
Here it should be noted the last line in the control file should be the spin
and multiplicity specifications. i.e. there should be no blank line at the
end of this control file as there is in a typical gaussian input file as the
current geometry will be appended and the final blank line inserted afterwards.
Additionally, interfaces have been developed to the SANDER program (part of
the AMBER package) and to the TINKER program. Please contact Benjamin T. Miller
for further information about these interfaces.