Introduction to MDTraj
----------------------

Start by loading up a trajectory from disk. MDTraj will automatically parse the file extension and use the appropriate loader. ::

  >>> import mdtraj as md
  >>> t = md.load('trajectory.xtc', top='trajectory.pdb')
  >>> print t
  <mdtraj.Trajectory with 100 frames, 22 atoms at 0x109f0a3d0>

To load files that don't contain topology information, like Gromacs XTC files,
we need to supply something with the ``top`` keyword argument that describes 
the topology, for example a PDB file.

If I'm interested in only a subset of the frames of the trajectory, I can slice it ::
  
  >>> # lets take a look at the first ten frames
  >>> print t[1:10]
  <mdtraj.Trajectory with 9 frames, 22 atoms at 0x109b91310>
  
  >>> # or maybe the last frame?
  >>> print t[-1]
  <mdtraj.Trajectory with 1 frames, 22 atoms at 0x109b97810>

There's a lot of information in the trajectory object. The most obvious is the
Cartesian coordinates. They're stored as a numpy array under ``xyz``. All of
the distances in the `Trajectory` are stored in nanometers. The time unit
is picoseconds. Angles are stored in degrees (not radians). ::

  >>> print t.xyz.shape
  (100, 22, 3)
  >>> print np.mean(t.xyz)
  0.89365752249053032

  >>> # the simulation time (in picoseconds) of th first 10 frames
  >>> print t.time[0:10]
  array([ 0.002,  0.004,  0.006,  0.008,  0.01 ,  0.012,  0.014,  0.016,
        0.018,  0.02 ], dtype=float32)
  
  >>> # or the unitcell lengths in the last frame? (in nanometers of course)
  >>> t.unitcell_lengths[-1]
  array([ 2.,  2.,  2.], dtype=float32)
  

Saving the trajectory back to disk is easy. ::

  >>> # the hdf5 format stores the topology inside the file for convenience
  >>> t[::2].save('halftraj.h5')
  
  >>> # the format will be parsed based on the extension, or you can call the
  >>> # format-specific save methods
  >>> t[0:10].save_dcd('first-ten-frames.dcd')


The trajectory contains a reference to a topology object, which can come in handy. For example, if you want to save a copy of your trajectory with
only alpha carbons present, you can do that pretty easily. ::

  >>> atoms_to_keep = [a.index for a in t.topology.atoms if a.name == 'CA']
  >>> t.restrict_atoms(atoms_to_keep)  # this acts inplace on the trajectory
  >>> t.save('CA-only.h5')