Start here

CPPTRAJ is the main program in AMBER for processing coordinate trajectories and data files.

The program CPPTRAJ, included in AmberTools, is a new and rewritten version of the historical PTRAJ program developed by Prof. Thomas E. Cheatham III, at the University of Utah. CPPTRAJ is at least as fast as PTRAJ was, and is in many cases significantly faster, and offers multiple option for analysis and trajectory processing of Molecular Dynamics data in multiple formats. For more information about CPPTRAJ, there are two published articles in JCTC and JCC

In this introduction, we present a brief overview of analyzing simulation data with CPPTRAJ. Some basic and common types of analysis will be covered, as well as the basics of data set handling in CPPTRAJ. This assumes that AmberTools has been successfully installed and has been tested. This also assumes some familiarity with AMBER atom mask selection syntax. In addition, xmgrace will be required to view some of the output data.

Throughout this tutorial a short example trajectory of the beta-hairpin trpzip2 will be used. The trajectory is in NetCDF format, which is faster to process, more compact, higher precision, and more robust than the ASCII format. NetCDF is enabled by default in AMBER. The trajectory and associated topology can be downloaded here:

trpzip2.ff10.mbondi.parm7 — This is the topology file.  — This is the trajectory file.

A movie of the trajectory of the beta-hairpin trpzip2 is presented below:

Loading a Topology and Trajectory

To start CPPTRAJ, type cpptraj from the command line:

[user@computer ~]$ cpptraj
CPPTRAJ: Trajectory Analysis. V5.0.4 (GitHub)
___ ___ ___ ___ __
 | \/ | \/ | \/ |

| Date/time: 11/03/23 16:02:12
| Available memory: 10.203 GB

Running CPPTRAJ with no arguments brings up the interactive command line. The command line is useful for running simple or short analyses. The command line allows tab completion of file names and commands. Also, in interactive mode all commands used are written to the file ‘cpptraj.log’ (this name can be changed with the ‘–log ‘ command line switch). Before reading in a trajectory, CPPTRAJ needs to know what the system looks like. This information is contained with topology files. The first step is to load the topology file with the parm command:

> parm trpzip2.ff10.mbondi.parm7
   [parm trpzip2.ff10.mbondi.parm7]
   Reading 'trpzip2.ff10.mbondi.parm7' as Amber Topology
   Radius Set: modified Bondi radii (mbondi)
   This Amber topology does not include atomic numbers.
   Assigning elements from atom masses/names.
   No SCEE section: setting Amber default (1.2)
   No SCNB section: setting Amber default (2.0)

The topology has now been loaded. You can see what topologies are loaded with the list command:

> list parm
   [list parm]

   PARAMETER FILES (1 total):
   0: trpzip2.ff10.mbondi.parm7, 220 atoms, 13 res, box: None, 1 mol

The output shows the topology index (which starts from 0, depicted in red here) followed by some brief information on the topology. More detailed information can be obtained using the ‘parminfo <#>’ command, where <#> is the index of the desired topology:

> parminfo 0    
   [parminfo 0]    Topology trpzip2.ff10.mbondi.parm7 contains 220 atoms.    
   Original filename: trpzip2.ff10.mbondi.parm7    
   13 residues.    
   1 molecules.    
   227 bonds (104 to H, 123 other).    
   402 angles (233 with H, 169 other).    
   853 dihedrals (481 with H, 372 other).    
   Box: None    
   GB radii set: modified Bondi radii (mbondi)

Now that the topology file is loaded, we can tell CPPTRAJ which trajectory we are going to process, we use the command trajin:

> trajin
   Reading '' as Amber NetCDF
   Warning: NetCDF file time variable defined but empty. Disabling.

Note that this does not immediately read the trajectory, rather it places the trajectory in the input trajectory list for processing later. To see what trajectories are currently in the input trajectory list we can again use the list command:

> list trajin
   [list trajin]

   0: '' is a NetCDF AMBER trajectory with coordinates, Parm trpzip2.ff10.mbondi.parm7 (reading 1201 of 1201)
   Coordinate processing will occur on 1201 frames.
Specifying an Action

Now that a topology and trajectory have been loaded, we can specify actions to generate data from the trajectory. Say for example we would like to know the end-to-end distance for the hairpin over the course of the trajectory. We can use the distance command to get this information. First, we can use the help command to remind us of the syntax for distance:

> help distance
   [help distance]
   [<name>] <mask1> [<mask2>] [point <X> <Y> <Z>]
   [ reference | ref <name> | refindex <#> ]
   [out <filename>] [geom] [noimage] [type noe]
   Options for 'type noe':
   [bound <lower> bound <upper>] [rexp <expected>] [noe_strong] [noe_medium] [noe_weak]
   Calculate distance between atoms in <mask1> and <mask2>, between
   atoms in <mask1> and atoms in <mask2> in specified reference, or
   atoms in <mask1> and the specified point.

The help command can be used with no arguments to bring up a list of all commands. In order to figure out which atoms correspond with the end residues of trpzip2, we can use the resinfo command:

> resinfo
13 residues selected.
#Res Name First Last Natom #Orig #Mol C I
   1 SER  1     13   13    1     1
   2 TRP  14    37   24    2     1
   3 THR  38    51   14    3     1
   4 TRP  52    75   24    4     1
   5 GLU  76    90   15    5     1
   6 ASN  91    104  14    6     1
   7 GLY  105   111  7     7     1
   8 LYS  112   133  22    8     1
   9 TRP  134   157  24    9     1
  10 THR  158   171  14    10    1
  11 TRP  172   195  24    11    1
  12 LYS  196   217  22    12    1
  13 NHE  218   220  3     13    1

From this output we can see that our end residues are 1 and 13. In general, the resinfo, atominfo, and molinfo commands are useful for examining your system layout and/or testing the result of an atom mask expression. For example, to see what atoms will be selected by the atom mask :13 (residue 13):

> atominfo :13
   [atominfo :13]
   3 atoms selected.
   #Atom Name #Res Name #Mol Type Charge  Mass    GBradius El rVDW   eVDW
   218   N    13   NHE  1    N    -0.4630 14.0100 1.5500   N  1.8240 0.1700
   219   HN1  13   NHE  1    H    0.2315   1.0080 1.3000   H  0.6000 0.0157
   220   HN2  13   NHE  1    H    0.2315   1.0080 1.3000   H  0.6000 0.0157

We can now enter our distance command:

> distance end-to-end :1 :13 out dist-end-to-end.agr
   [distance end-to-end :1 :13 out dist-end-to-end.agr]
   DISTANCE: :1 to :13, center of mass.

This says to calculate a distance named end-to-end from the center of mass of residue 1 to residue 13, writing the results to a file named dist-end-to-end.agr. The file format will be xmgrace-readable because the filename extension ‘.agr’ is recognized by CPPTRAJ as xmgrace. We could change the format to gnuplot-readable by specifying a ‘.gnu’ extension instead. If the extension is ‘.dat’ or not recognized, CPPTRAJ will default to a standard column format. The supported formats and their options are listed here. Note that similar to trajin, entering an action does not execute it right away. Instead, it has gone into the action list. To see what actions are currently present in the action list we can use the list command:

> list actions
   [list actions]

   ACTIONS (1 total):
   0: [distance end-to-end :1 :13 out dist-end-to-end.agr]
Processing the Trajectory

We have now loaded a topology, a trajectory, and have specified an action. The command can now be executed by specifying ‘run’ or ‘go’. This tells CPPTRAJ to process each loaded trajectory, executing any specified actions on each frame. During trajectory processing some information will be printed that describes what CPPTRAJ is doing. First, information on the currently loaded topologies and trajectories are printed:

> run
---------- RUN BEGIN -------------------------------------------------

0: trpzip2.ff10.mbondi.parm7, 220 atoms, 13 res, box: None, 1 mol

0: '' is a NetCDF AMBER trajectory with coordinates, Parm trpzip2.ff10.mbondi.parm7 (reading 1201 of 1201)
Coordinate processing will occur on 1201 frames.

ACTION SETUP FOR PARM 'trpzip2.ff10.mbondi.parm7' (1 actions):
0: [distance end-to-end :1 :13 out dist-end-to-end.agr]
:1 (13 atoms) to :13 (3 atoms), imaging off.
----- (1-1201, 1) -----
0% 10% 20% 30% 40% 50% 60% 70% 80% 90% 100% Complete.

Read 1201 frames and processed 1201 frames.
TIME: Avg. throughput= 106217.3875 frames / second.

TIME: Analyses took 0.0000 seconds.

DATASETS (1 total):
end-to-end "end-to-end" (double, distance), size is 1201 (9.608 kB)
Total data set memory usage is at least 9.608 kB

DATAFILES (1 total):
dist-end-to-end.agr (Grace File): end-to-end

TIME: Init : 0.0000 s ( 0.23%)
TIME: Trajectory Process : 0.0113 s ( 82.68%)
TIME: Action Post : 0.0000 s ( 0.01%)
TIME: Analysis : 0.0000 s ( 0.01%)
TIME: Data File Write : 0.0023 s ( 16.90%)
TIME: Other : 0.0000 s ( 0.00%)
TIME: Run Total 0.0137 s
---------- RUN END ---------------------------------------------------

After CPPTRAJ finishes the analysis, you can exit CPPTRAJ typing quit:

> quit
To cite CPPTRAJ use:
Daniel R. Roe and Thomas E. Cheatham, III, "PTRAJ and CPPTRAJ: Software for
Processing and Analysis of Molecular Dynamics Trajectory Data". J. Chem.
Theory Comput., 2013, 9 (7), pp 3084-3095.

You should have an xmgrace file (with the name dist-end-to-end.agr) that you can open with xmgrace:

 [user@computer ~]$ xmgrace dist-end-to-end.agr














This shows a plot of the distance (in Angstroms) between the first residue and residue number 13 (as per the mask used of :1 :13). The frame number in the X axis translates to the simulation time.

Next we recommend a tutorial on working with Data Sets following this link (Introduction to Data Sets).