fix mscg command — LAMMPS documentation

\(\renewcommand{\AA}{\text{Å}}\)

# fix mscg command

## Syntax

    fix ID group-ID mscg N keyword args ...

- ID, group-ID are documented in fix command

- mscg = style name of this fix command

- N = envoke this fix every this many timesteps

- zero or more keyword/value pairs may be appended

- keyword = range or name or max

      range arg = on or off
        on = range finding functionality is performed
        off = force matching functionality is performed
      name args = name1 ... nameN
        name1,...,nameN = string names for each atom type (1-Ntype)
      max args = maxb maxa maxd
        maxb,maxa,maxd = maximum bonds/angles/dihedrals per atom

## Examples

    fix 1 all mscg 1
    fix 1 all mscg 1 range name A B
    fix 1 all mscg 1 max 4 8 20

## Description

This fix applies the Multi-Scale Coarse-Graining (MSCG) method to snapshots from a dump file to generate potentials for coarse-grained simulations from all-atom simulations, using a force-matching technique (Izvekov, Noid).

It makes use of the MS-CG library, written and maintained by Greg Voth’s group at the University of Chicago, which is freely available on their MS-CG GitHub site. See instructions on obtaining and installing the MS-CG library in the src/MSCG/README file, which must be done before you build LAMMPS with this fix command and use the command in a LAMMPS input script.

An example script using this fix is provided the examples/mscg directory.

The general workflow for using LAMMPS in conjunction with the MS-CG library to create a coarse-grained model and run coarse-grained simulations is as follows:

1. Perform all-atom simulations on the system to be coarse grained.

2. Generate a trajectory mapped to the coarse-grained model.

3. Create input files for the MS-CG library.

4. Run the range finder functionality of the MS-CG library.

5. Run the force matching functionality of the MS-CG library.

6. Check the results of the force matching.

7. Run coarse-grained simulations using the new coarse-grained potentials.

This fix can perform the range finding and force matching steps 4 and 5 of the above workflow when used in conjunction with the rerun command. It does not perform steps 1-3 and 6-7.

Step 2 can be performed using a Python script (cgmap), which defines the coarse-grained model and converts a standard LAMMPS dump file for an all-atom simulation (step 1) into a LAMMPS dump file which has the positions of and forces on the coarse-grained beads. To use cgmap the following repositories need to be downloaded and installed.

1. The custom lammpsdata branch of mdtraj from https://github.com/hockyg/mdtraj/tree/lammpsdata

2. The master branch of cgmap from https://github.com/uchicago-voth/cgmap

In step 3, an input file named “control.in” is needed by the MS-CG library which sets parameters for the range finding and force matching functionalities. See the examples/mscg/control.in file as an example. And see the documentation provided with the MS-CG library for more info on this file.

When this fix is used to perform steps 4 and 5, the MS-CG library also produces additional output files. The range finder functionality (step 4) outputs files defining pair and bonded interaction ranges. The force matching functionality (step 5) outputs tabulated force files for every interaction in the system. Other diagnostic files can also be output depending on the parameters in the MS-CG library input script. Again, see the documentation provided with the MS-CG library for more info.

The range keyword specifies which MS-CG library functionality should be invoked. If on, the step 4 range finder functionality is invoked. off, the step 5 force matching functionality is invoked.

If the name keyword is used, string names are defined to associate with the integer atom types in LAMMPS. Ntype names must be provided, one for each atom type (1-Ntype).

The max keyword specifies the maximum number of bonds, angles, and dihedrals a bead can have in the coarse-grained model.

## Restrictions

This fix is part of the MSCG package. It is only enabled if LAMMPS was built with that package. Building the MSCG package also requires external libraries. See the Include packages in build and Packages with extra build options pages for more info.

Currently, the MS-CG library is not set up to run in parallel with MPI, so this fix can only be used in a serial LAMMPS build and run on a single processor.

## Related commands

none

## Default

The default keyword settings are range off, max 4 12 36.

(Izvekov) Izvekov, Voth, J Chem Phys 123, 134105 (2005).

(Noid) Noid, Chu, Ayton, Krishna, Izvekov, Voth, Das, Andersen, J Chem Phys 128, 134105 (2008).