{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Visualising a Universe"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After defining the configuration and topology of a `Universe`, either [manually](creating-atomic-configurations.ipynb) or by [reading a configuration file](read-configurations.ipynb), 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`."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To demonstrate visualisation, we start by creating some atoms."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from MDMC.MD import Atom, Molecule, Bond, Universe\n",
    "H1 = Atom('H', charge=0.4238)\n",
    "O = Atom('O', position=(0., 0.81649, 0.57736), charge=-0.8476)\n",
    "atoms = [H1, O]\n",
    "universe = Universe(10.)\n",
    "universe.add_structure(H1)\n",
    "universe.add_structure(O)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Visualisation is done through ASE, so [any format supported by ASE](https://wiki.fysik.dtu.dk/ase/ase/visualize/visualize.html) is supported here. We will demonstrate\n",
    "two different viewers:\n",
    "\n",
    "`'X3D'`:  \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.  `'X3D'` is the default viewer when `view` is called.\n",
    "\n",
    "`'ASE'`:  \n",
    "This is 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](../../installation/docker.rst) if MDMC is being run from within a Docker container. This viewer has a few additional menu options, which are discussed below."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As mentioned above, calling view without passing `viewer` uses `'X3D'` 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)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are also options 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)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And using the `'ASE'` viewer, press `Ctrl+B` to show bonds:"
   ]
  },
  {
   "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)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally we visualise a `Universe`; first, we 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)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And then pass it to the `'X3DOM'` viewer:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "view(universe)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And again with the `'ASE'` viewer, which also shows 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 represented 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
}