Simulation preprocessor¶

This command should be named as dpspp (Dropps preprocessor). But the developer is a huge fan of gromacs so he uses grompp (Gromacs preprocessor) instead.

Bite Me.

The grompp tool in DROPPS is a system preprocessor that combines:

structural coordinates (PDB)
molecular topology files (ITP)
simulation parameters (MDP)

into a single TPR runtime file, which is later consumed by mdrun to perform the actual molecular dynamics simulation.

This is analogous to GROMACS grompp, but generates a pickled Python runtime object containing everything required by the DROPPS MD engine.

Implemented in grompp.py.

Overview¶

dps grompp performs 4 major tasks:

Reads the initial structure from a PDB file
Reads and aggregates all molecular topologies (ITP)
Reads the parameter (MDP) file

Calls the internal constructor:

mdsystem, mdtopology, positions, ITP_list = build_system(...)

to build a complete simulation state.

Finally, it packs everything into a dictionary and pickles the object to a file with extension .tpr (DROPPS-TPR format).

The output file is later passed to:

dps mdrun -s state.tpr

to perform time integration.

Usage¶

Minimal example:

dps grompp \
    -f conf.pdb \
    -p system.itp \
    -m run.mdp \
    -o state.tpr

If -o does not end with .tpr, it will be appended automatically.

Arguments¶

Required¶

-f, --structure FILE¶

PDB structure file containing the initial configuration of your system. Internally processed by:

read_pdb()
phrase_pdb_atoms()

-p, --topology FILE¶: The main topology file (GROMACS-style .itp), usually including other ITPs via #include directives.

-m, --parameter FILE¶

MDP-style parameter file. Interpreted by:

getparameter()

and passed into build_system.

-o, --output FILE¶: Output filename for the TPR runtime file. .tpr extension is added if missing.

What grompp Generates¶

The output file is a Python pickle containing all runtime data required by mdrun.

Structure of the pickled dictionary:

runtime_files = {
    "parameters": parameters,
    "mdsystem": mdsystem,
    "mdtopology": mdtopology,
    "positions": positions,
    "pdb_raw": PDB_raw,
    "ITP_list": ITP_Topology_list
}

Where:

parameters — parsed mdp dictionary
mdsystem — instantiated OpenMM system
mdtopology — DROPPS molecular-topology object
positions — initial coordinates (OpenMM array)
pdb_raw — raw PDB atom list + box vectors
ITP_list — list of all parsed ITP topologies

Program Workflow¶

Prepare output name

if not output.endswith(".tpr"):
    output_tpr = output + ".tpr"

Load parameters

parameters = getparameter(args.parameter)

Build system

Calls DROPPS system builder:

mdsystem, mdtopology, positions, ITP_list = \
    build_system(args.structure, args.topology, parameters)

This step:

builds OpenMM forces
applies forcefield parameters
resolves #includes inside ITP files
builds bonded & non-bonded interactions
extracts initial coordinates

Load raw PDB data

atoms_pdb_raw, box_raw = read_pdb(args.structure)
PDB_raw = phrase_pdb_atoms(atoms_pdb_raw, box_raw)

Stored for restart and trajectory writing later.

Package everything

runtime_files = {...}

Pickle to `.tpr`

with open(output_tpr, "wb") as f:
    pickle.dump(runtime_files, f)

Print:

## Write run time files to state.tpr.

Example¶

Typical workflow:

dps genmesh -oc init.pdb -op init.top  # build multi-chain system
dps grompp  -f init.pdb -p init.top -m eq.mdp -o eq.tpr
dps mdrun   -s eq.tpr                  # run MD

Error Messages¶

Because grompp relies heavily on file parsing, errors typically arise from:

Invalid ITP file

ERROR: Cannot open topology file ...

Invalid PDB file

ERROR: Cannot open structure file ...

Parameter file missing fields Errors thrown inside getparameter().

Internal construction errors From build_system if the topology and structure do not match.

Summary¶

dps grompp is the preparation engine of the DROPPS simulation pipeline. It:

loads structures, topologies, and parameters
builds a complete OpenMM system
collects all metadata
writes a unified DROPPS-TPR file (Python pickle)

which is required by the dps mdrun integrator.

grompp is therefore the first step in every DROPPS simulation workflow, analogous to gmx grompp in the GROMACS ecosystem.