Basic Concepts

This chapter provides a basic outline of the objects and ideas used by openMSCG.


openMSCG uses the following units:

  • distance = Angstroms

  • angle = Degrees (for 3-body angles and 4-body dihedral torsions)

  • force = Kcal/mol/Angstrom

  • temperature = Kelvin

  • mass = grams/mol


A topology file defines a group of particles (atoms or CG sites) and their molecular bonding information. Different MD software packages have their own file format to define topologies. For example:

For the openMSCG package, we offer a package-specific file format to define the topologies of CG systems, named CGTOP. The format description can be found here.

Command Line Interface (CLI) Option for Topology

Many CLI commands need to read a topology file for processing, and use the option flag --top file.

  • The file format (e.g. LAMMPS or CGTOP) is automatically determined based on the content of the file.

  • At this moment, only two formats are supported by openMSCG, lammps and cgtop. But more formats will be supported in the future.

  • In LAMMPS, the atom types are named using numeric IDs (1, 2, …). To be more user-friendly, the option --names can be used to define the list of atom types by character-string-based names.




MD trajectories are collections of particle coordinates (also called “frames”) dumped from simulations. There are also many formats of trajectories from different MD software packages, such as XYZ, DCD, TRR.

CLI Option for Trajectory

Many CLI commands need to read a trajectory file for processing, and use the option flag --traj file,[skip=n],[every=n],[frames=]. The option values consist of four fields separated by commas.

  • file: the path and name of the trajectory file.

The following optional fields are used for processing frames from a trajectory in a loop:

  • skip: skip over the first n frames for processing defined by skip.

  • every: read a frame for every n frames defined by every.

  • frames: read until n frames are read defined by frames.


--traj md.trr,skip=10,every=100,frames=50

In this example, the file md.trr will be processed. First, the first 10 frames will be skipped, then 1 frame for every 100 frames (i.e. read 1 frame and then skip then next 99 frames) will be read, and the process will end after 50 frames have been read.

Models and Functional Forms

In molecular modeling, models (or force-fields) are mathematical functions of variables (e.g. distances or angles) to describe the forces and potential energies of a molecular system. One of the important outcomes in openMSCG is to obtain optimized parameters for the force-field. Four styles of interactions can be specified as runtime options for either FM or REM methods: –pair, –bond, –angle, –dihedral.

CLI Option for Model

For example, to fit model parameters for a pairwise interaction using B-splines between atom types A and B, one can specify the following option:

--pair model=BSpline,type=A:B,min=3.0,max=8.0,resolution=0.2

The runtime argument is followed by multiple key-value attributes separated by commas. Two attributes are mandatory:

  • model: define the functional form. BSpline is the highlighted choice for multi-scale modeling, but new functional types are easy to be extended in OpenMSCG.

  • type: name that is used to specify the targeted interaction types to be optimized. In the example above, A:B indicates a pair interaction between atoms of type A and B.

Other attributes are optional and depend on the functional form. In the example above, there are three attributes to define a BSpline: min, max and resolution.

List of Supported Models



FM supported

REM supported




















Force Field (Molecular Mechanics)

Some of the functions/modules in OpenMSCG require calculating potential energies or forces for the system, which is defined by the conventional force-field for pairs, bonds, angles … OpenMSCG provides the force module for this calculation, which is usually specified by the option:

--force force.yaml

where the parameter points to a YAML file as the definition of the force field. A sample file is as below:

  CH3-CH3: Pair_CH3-CH3.table
  OH-OH:   Pair_OH-OH.table
  CH3-OH:  Pair_CH3-OH.table
  CH3-OH:  [5.0, 2.6]

The file contains a dictionary with multiple entries. The key of ach entry defines a type of potential function, and the value is another dictionary in which the keys are the targeted pair/bond/angle… types (as defined in the topology) and the values are the associated parameters.

The sample above demostrates the force field for a two-site methanol model including three types of pairwise interactions, using tabulated potential, and one type of bonded interaction, using the harmonic potential.

Supported Functional Forms




Name of the table file


Name of the table file


Name of the table file


Name of the table file


force constant, equilibrium value of the bond


force constant, equilibrium value of the angele


force constant, equilibrium value of the dihedral

  • The names of potential types are usually with two parts:

    • Type of interations: Pair, Bond, Angle

    • Type of funcional form: Table, Harmonic

  • For the table files, LAMMPS format is used.