{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Molecular Visualization"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After defining the configuration and topology of a `Universe`, either manually or by reading a configuration file, it is useful to visualize the setup.  The `view` function provides a simple molecular visualizer for establishing the accuracy of a simulation setup.  It can be used to visualize one or more `Atom` objects, one or more `Molecule` objects, or a `Universe`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Start by simply creating H and O atoms\n",
    "from MDMC.MD import Atom, Molecule, Bond\n",
    "H1 = Atom('H', charge=0.4238)\n",
    "O = Atom('O', position=(0., 0.81649, 0.57736), charge=-0.8476)\n",
    "atoms = [H1, O]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Two different viewers are available:\n",
    "\n",
    "### `'X3DOM'`\n",
    "This is an inline viewer which displays within a Jupyter notebook.  It is ideally suited to <3000 atoms, and may suffer performance issues when displaying more than this.  `'X3DOM'` is the default viewer when `view` is called.\n",
    "\n",
    "### `'ASE'`\n",
    "This is a modified version of the default [ASE](https://wiki.fysik.dtu.dk/ase/) GUI.  It displays in a separate window (which may appear on the desktop), and requires X11 forwarding to be enabled if MDMC is being run from within a Docker container. This viewer has a few additional menu options, which are discussed below.\n",
    "\n",
    "Both viewers require ASE to be installed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As mentioned above, calling view without passing `viewer` uses `'X3DOM'` as the viewer, which displays inline in a Jupyter notebook. It should display:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from MDMC.gui import view\n",
    "view(atoms)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively, the `'ASE'` viewer can be selected. This will open an external window, and the execution of any further Jupyter notebook cells will be paused until this window is closed. This execution being paused at the `view(atoms, viewer='ASE')` cell is denoted by a `[*]` to the left of the cell."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "view(atoms, viewer='ASE')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ASE GUI should show:\n",
    "\n",
    "![Display for H and O atoms](../_static/images/gui_HO.png)\n",
    "\n",
    "Within the ASE GUI, the View menu has options which assist in checking the setup.  For example, View -> Show Labels -> Charges, displays the charges on each atom:\n",
    "\n",
    "![Display charges for H and O atoms](../_static/images/gui_HO_charges.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are also optins to show the elements or atom ID labels."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Bonds are also displayed in both viewers.  To see this in action, add a `Bond` between the atoms and view the atoms again:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "HO_bond = Bond((H1, O))\n",
    "view(atoms)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And using the `'ASE'` viewer:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "view(atoms, viewer='ASE')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![Display bond between H and O atoms](../_static/images/gui_HO_bond.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**It is important to note that while `Bond` objects are displayed, `BondAngle` and `DihedralAngle` objects are not currently shown.**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As mentioned above, `Molecule` objects can also be passed to `view`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "H2 = H1.copy(position=(0., 1.63298, 0.))\n",
    "water = Molecule(atoms=[H1, O, H2])\n",
    "view(water)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And again with the `'ASE'` viewer:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "view(water, viewer='ASE')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![Display water molecule](../_static/images/gui_water.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally to visualize a `Universe`, create one and fill it with copies of the water `Molecule`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from MDMC.MD import Universe\n",
    "universe = Universe(10.)\n",
    "universe.fill(water, num_density=0.0336)\n",
    "view(universe)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And again with the `'ASE'` viewer, which also delimits the bounds of the `Universe` with a dashed line:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "view(universe, viewer='ASE')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When viewing a `Universe`, the bounds are delimited by a dashed line.  The `Universe`, tiled with water molecules, should appear as:\n",
    "\n",
    "![Display universe filled with water](../_static/images/gui_universe.png)"
   ]
  }
 ],
 "metadata": {
  "interpreter": {
   "hash": "add738a18a8c9080256f416f48e2f1975a0b0948846decec7f4bbc677823fdf5"
  },
  "kernelspec": {
   "display_name": "Python 3.7.4 32-bit ('mdmc-venv': virtualenv)",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": ""
  },
  "nbsphinx": {
   "execute": "never"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}