examples/15_trajectory_module.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# pyscal `Trajectory`\n",
    "\n",
    "`Trajectory` is a `pyscal` module intended for working with molecular dynamics trajectories which contain more than one time slice. Currently, the module only supports [LAMMPS dump](https://lammps.sandia.gov/doc/dump.html) text file formats. It can be used to get a single or slices from a trajectory, trim the trajectory or even combine multiple trajectories. The example below illustrates various uses of the module.\n",
    "\n",
    "**`Trajectory` is an experimental feature at the moment and may undergo significant changes in future releases**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Start with importing the module"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pyscal import Trajectory"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Read in a trajectory. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "traj = Trajectory(\"traj.light\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When using the above statement, the trajectory is not yet read in to memory. Just the basic information is available now. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Trajectory of 10 slices with 500 atoms"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "traj"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can know the number of slices in the trajectory and the number of atoms. `Trajectory` only works with fixed number of atoms. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, one can get a single slice or multiple slices just as is done with a python list. Getting the 2nd slice (counting starts from 0!)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Trajectory slice\n",
       " 2-2\n",
       " natoms=500"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sl = traj[2]\n",
    "sl"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This slice can now be converted to a more usable format, either to a pyscal `System` or just written to another text file. Convert to a pyscal `System` object, "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<pyscal.core.System at 0x7f81f93971d0>]"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sys = sl.to_system()\n",
    "sys"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`System` objects contain all the information. The atomic positions, simulation box and so on are easily accessible."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[[18.22887, 0.0, 0.0], [0.0, 18.234740000000002, 0.0], [0.0, 0.0, 18.37877]]"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sys[0].box"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[-4.9941, -6.34185, -6.8551]"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sys[0].atoms[0].pos"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If information other than positions are required, the `customkeys` keyword can be used. For example, for velocity in the x direction,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<pyscal.core.System at 0x7f81f9397530>]"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sys = sl.to_system(customkeys=[\"vx\"])\n",
    "sys"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'-1.21558'"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sys[0].atoms[0].custom[\"vx\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Instead of creating a System object, the slice can also be written to a file directly."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "sl.to_file(\"test.dump\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Like normal python lists, multiple slices can also be accessed directly"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Trajectory slice\n",
       " 0-3\n",
       " natoms=500"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sl1 = traj[0:4]\n",
    "sl1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`to_system` and `to_file` methods can be used on this object too."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Multiple slices can be added together"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Trajectory slice\n",
       " 5-6\n",
       " natoms=500"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sl2 = traj[5:7]\n",
    "sl2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Trajectory slice\n",
       " 0-3/5-6\n",
       " natoms=500"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "slnew = sl1+sl2\n",
    "slnew"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once again, one could write the combined trajectory slice to a file, or create a System object out of it."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "lammps",
   "language": "python",
   "name": "lammps"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}