CGMap

CGMap is a Python tool for coarse-grain mapping of molecular dynamics trajectories. It provides efficient mapping of atomistic trajectories to coarse-grained representations with support for various output formats.

Features

• Read LAMMPS dump files
• Configurable coarse-graining mapping through YAML files
• Multiple output formats supported:
  • XYZ trajectory files
  • LAMMPS data files
  • Compressed NPZ files
• Coordinate wrapping for periodic boundary conditions
• Detailed logging system
• Command-line interface

Installation

Requirements

• Python >= 3.8
• NumPy
• PyYAML

Installing from source

git clone https://github.com/Chenghao-Wu/cgmap.git
cd cgmap
pip install .

Usage

Basic Command

cgmap --dump trajectory.dump --system system.yaml --output cg_system

Command-line Options

cgmap [-h] --dump DUMP --system SYSTEM [--output OUTPUT]
[--format {xyz,data,npz}] [--wrap WRAP]
[--separate-xyz] [--frame FRAME]
[--log-dir LOG_DIR] [--debug]

Example System Configuration (system.yaml)

system:
  names:
    - "mapping_wat.yaml"
  numbers:
    - 1

Example Mapping Configuration (mapping_wat.yaml)

site-types:
  WAT:
    index: [0, 1, 2]
    x-weight: [16.0, 1.0, 1.0]
    f-weight: [1.0, 1.0, 1.0]

config:
  - anchor: 0
    offset: 3
    repeat: 900
    sites:
      - ["WAT", 0]

Configuration File Structure

The mapping configuration file consists of two main sections: site-types and config.

Site Types Section

The site-types section defines how atomic positions are mapped to coarse-grained (CG) sites:

• Each entry (e.g., WAT) represents a CG site type
• index: List of atomic indices to be mapped to this CG site
• x-weight: Weights for position mapping (e.g., center of mass)
• f-weight: Weights for force mapping

Config Section

The config section defines how the mapping is applied across the system:

• anchor: Starting index in the atomic configuration
• offset: Number of atoms per mapping unit (typically atoms per molecule)
• repeat: Number of times to repeat this mapping pattern
• sites: List of CG sites to create, each defined by:
  • Site type name (e.g., "WAT")
  • Local offset within the group

Example Explained

In the example above:

• Three atoms (indices 0,1,2) are mapped to one WAT bead
• Position mapping uses weights [16.0, 1.0, 1.0] (typical for water O:H:H mass ratio)
• The pattern is repeated 900 times (for 256 water molecules)
• Each water molecule takes 3 atoms (offset=3)
• The mapping starts from the first atom (anchor=0)

This mapping would process a trajectory of 2700 atoms (900 water molecules × 3 atoms) into 900 CG beads.

Output Formats

XYZ Format

• Single trajectory file or separate files per frame
• Simple format for visualization

cgmap --dump traj.dump --system system.yaml --format xyz

LAMMPS Data Format

• Full atom style
• Includes box dimensions and atom types

cgmap --dump traj.dump --system system.yaml --format data --frame 0

NPZ Format

• Compressed NumPy format
• Contains coordinates, forces, site types, and box dimensions

cgmap --dump traj.dump --system system.yaml --format npz

Logging

Enable detailed logging with the --debug flag and specify a log directory:

cgmap --dump traj.dump --system system.yaml --log-dir ./logs --debug

Examples

1. Basic coarse-graining with NPZ output:

cgmap --dump trajectory.dump --system system.yaml

2. Generate XYZ trajectory with wrapped coordinates:

cgmap --dump trajectory.dump --system system.yaml --format xyz --wrap True

3. Create LAMMPS data file for a specific frame:

cgmap --dump trajectory.dump --system system.yaml --format data --frame 10

4. Generate separate XYZ files for each frame:

cgmap --dump trajectory.dump --system system.yaml --format xyz --separate-xyz

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Citation

If you use CGMap in your research, please cite:

@software{cgmap2025, author = {Wu, Zhenghao}, title = {CGMap: A Tool for Coarse-Grain Mapping of Molecular Dynamics Trajectories}, year = {2024}, url = {https://github.com/yourusername/cgmap} }