An Introduction to CPPTRAJ (2023)

By Daniel R. Roe, July 2014

Note: This tutorial was designed for use with CPPTRAJ from AmberTools 14.

An Introduction to CPPTRAJ (1)

Loading a Topology and Trajectory
Specifying an Action
Processing the Trajectory
Working With Data Sets
Running in Batch Mode
Associated Files

This tutorial will give a brief overview of analyzing simulation data with CPPTRAJ. CPPTRAJ is the successor to PTRAJ, with many additional features. 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. For more details on atom mask selection syntax see the Amber manual (section 28.2.3. Atom Mask Selection Syntax in the Amber 14 manual). 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, but if you find that your CPPTRAJ cannot read this trajectory please contact the Amber mailing list for help. The trajectory and associated topology can be downloaded here:

  • ¦ MD5 sum: 059435cfe1fcd57c327d46711da9ceff
  • trpzip2.ff10.mbondi.parm7 ¦ MD5 sum: 140044a45c683612da3431dfd0697e22

For more detailed information on CPPTRAJ, see here:

To start CPPTRAJ, type 'cpptraj' from the command line:

[user@computer ~]$ cpptrajCPPTRAJ: Trajectory Analysis. V14.05 ___ ___ ___ ___ | \/ | \/ | \/ | _|_/\_|_/\_|_/\_|_>

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).

(Video) MD trajectory analysis with cpptraj of Ambertools

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 Reading 'trpzip2.ff10.mbondi.parm7' as Amber Topology

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

> list parmPARAMETER FILES: 0: 'trpzip2.ff10.mbondi.parm7', 220 atoms, 13 res, box: None, 1 mol

The output shows the topology index (which starts from 0) 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 0Topology trpzip2.ff10.mbondi.parm7 contains 220 atoms.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: NoneGB radii set: modified Bondi radii (mbondi)

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

> trajin Reading '' as Amber NetCDF

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 trajinINPUT TRAJECTORIES: 0: '' is a NetCDF AMBER trajectory, Parm trpzip2.ff10.mbondi.parm7 (reading 1201 of 1201) Coordinate processing will occur on 1201 frames.

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[<name>] <mask1> <mask2> [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>

The 'help' command can be used with no arguments to bring up a list of all commands.

(Video) MMPBSA In Amber How to plot RMSD graph using CPPTRAJ and MMPBSA using Production run

In order to figure out which atoms correspond with the end residues of trpzip2, we can use the 'resinfo' command:

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

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#Atom Name #Res Name #Mol Type Charge Mass GBradius El 218 N 13 NHE 1 N -0.4630 14.0100 1.5500 N 219 HN1 13 NHE 1 H 0.2315 1.0080 1.3000 H 220 HN2 13 NHE 1 H 0.2315 1.0080 1.3000 H

We can now enter our 'distance' command:

> 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. For a complete list of supported formats and their associated extensions see the Amber 14 manual.

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 actionsACTIONS: 0: [distance end-to-end :1 :13 out dist-end-to-end.agr]

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 -------------------------------------------------PARAMETER FILES: 0: 'trpzip2.ff10.mbondi.parm7', 220 atoms, 13 res, box: None, 1 mol, 1201 framesINPUT TRAJECTORIES: 0: '' is a NetCDF AMBER trajectory, Parm trpzip2.ff10.mbondi.parm7 (reading 1201 of 1201) Coordinate processing will occur on 1201 frames.TIME: Run Initialization took 0.0000 seconds.

Note that if any reference coordinates or output trajectories are specified they will appear here as well.

Next, the first trajectory will be loaded and any actions will be set up for that trajectory/topology:

(Video) AMBER19 Cluster Analysis with CPPTRAJ - ssRNA (script in description)

BEGIN TRAJECTORY PROCESSING:.....................................................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.

Here our 'distance' action has been set up.

Next, each frame in the trajectory will be read and processed:

----- (1-1201, 1) ----- 0% 10% 20% 30% 40% 50% 60% 70% 80% 90% 100% Complete. 

When all trajectories have been processed, a summary of the total run will be written, including number of frames processed, any action-specific output, data sets generated, and data files written.

Read 1201 frames and processed 1201 frames.TIME: Trajectory processing: 0.0094 sTIME: Avg. throughput= 127372.9982 frames / second.ACTION OUTPUT:DATASETS: 1 data set:end-to-end "end-to-end" (double, distance), size is 1201DATAFILES: dist-end-to-end.agr (Grace File): end-to-end---------- RUN END ---------------------------------------------------

If xmgrace is installed and you are running and X-server, you can view the output right from the CPPTRAJ command line:

> xmgrace dist-end-to-end.agr

An Introduction to CPPTRAJ (2)

From the 'DATASETS' section of the output:

DATASETS: 1 data set:end-to-end "end-to-end" (double, distance), size is 1201

we see that we have generated one data set named 'end-to-end', with the legend "end-to-end", that is a double-precision distance data set with 1201 elements. We can now continue to manipulate this data set if desired. Say for example you also want to write this data in the standard (column) data format. You can use the 'writedata' command like so:

> writedata end-to-end.dat end-to-end end-to-end

The linux 'head' command can be used directly from the CPPTRAJ command line to view the first few lines of 'end-to-end.dat'

> head end-to-end.dat #Frame end-to-end 1 6.4251 2 5.9250 3 6.7926 4 6.3125 5 5.7580 6 5.4389 7 6.1086 8 6.5588 9 5.6949

Now that we are finished, type 'quit' or 'exit' to exit CPPTRAJ.

> quitTIME: Total execution time: 131.2112 seconds.--------------------------------------------------------------------------------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.

Instead of running interactively, CPPTRAJ can also be run using one or more input files. Since the log file 'cpptraj.log' has recorded every command used, you can use the log file as the basis for a cpptraj "script". For example to generate everything we have done so far the following input could be used:

parm trpzip2.ff10.mbondi.parm7trajin end-to-end :1 :13 out dist-end-to-end.agrrunwritedata end-to-end.dat end-to-end

Paste the above commands into a file called ''. The commands can then be executed like so:

[user@computer ~]$ cpptraj -i CPPTRAJ: Trajectory Analysis. V14.05 ___ ___ ___ ___ | \/ | \/ | \/ | _|_/\_|_/\_|_/\_|_INPUT: Reading Input from file [parm trpzip2.ff10.mbondi.parm7]Reading 'trpzip2.ff10.mbondi.parm7' as Amber Topology [trajin]Reading '' as Amber NetCDF [distance end-to-end :1 :13 out dist-end-to-end.agr] DISTANCE: :1 to :13, center of mass. [run]---------- RUN BEGIN -------------------------------------------------

The rest of the output will be similar to what was seen previously.

Note that it is VERY IMPORTANT to check your output for lines containing 'Warning:' or 'Error:' as these messages indicate there may be a problem with your input.

These files can be used to check your output.


Copyright Daniel R. Roe, 2014

(Video) Desmond - Analyzing MD Trajectories with the Simulation Interactions Diagram (Part 4)


1. How to convert files from NAMD to GROMACS using CPPTRAJ in AmberTools
(المبرمج العربي)
2. AMBER Tutorial: An Introduction to LEaP (xleap and tleap) // Creating A Peptide Sequence
(MD with Gourav)
3. MDtraj Tutorials- (1) Introduction and Installation with Conda
(Mohamed shehata)
4. AMBER Tutorial 1: Specifying the Units and Contaminants
(Quintessa Ltd)
5. General overview of gmx_MMPBSA suite
(Bioinformatic Brothers)
6. Lecture 11, concept 17: Protein structure RMSD vs. sequence identity
(Erik Lindahl)
Top Articles
Latest Posts
Article information

Author: Virgilio Hermann JD

Last Updated: 11/20/2022

Views: 5824

Rating: 4 / 5 (41 voted)

Reviews: 80% of readers found this page helpful

Author information

Name: Virgilio Hermann JD

Birthday: 1997-12-21

Address: 6946 Schoen Cove, Sipesshire, MO 55944

Phone: +3763365785260

Job: Accounting Engineer

Hobby: Web surfing, Rafting, Dowsing, Stand-up comedy, Ghost hunting, Swimming, Amateur radio

Introduction: My name is Virgilio Hermann JD, I am a fine, gifted, beautiful, encouraging, kind, talented, zealous person who loves writing and wants to share my knowledge and understanding with you.