{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Simulation Boxes\n",
    "\n",
    "While Freud attempts to make as few assumptions about your data as possible, in order to be as general and flexible as possible, Freud often has to assume your data exist in some kind of 2D or 3D physical space, henceforth known as a *simulation box* or just *box*. Full [Box Documentation](http://glotzerlab.engin.umich.edu/freud/box.html) is available.\n",
    "\n",
    "# Import box"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from freud import box"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Box Creation\n",
    "\n",
    "There are many ways to construct a box, listed below.\n",
    "\n",
    "## Default (full) API\n",
    "\n",
    "The first way to construct a box is to pass in all arguments"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "box0 = box.Box(Lx=5, Ly=6, Lz=7, xy=0.5, xz=0.6, yz=0.7, is2D=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Convenience APIs\n",
    "\n",
    "Many simulation boxes have some degree of symmetry, so we have provided the following convenience constructors for common box geometries.\n",
    "\n",
    "### Cube\n",
    "\n",
    "If your box is a cube, you may use the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "5.0 5.0 5.0 0.0 0.0 0.0 False\n"
     ]
    }
   ],
   "source": [
    "cube_box = box.Box.cube(L=5)\n",
    "print(cube_box.Lx, cube_box.Lz, cube_box.Ly, cube_box.xy, cube_box.xz, cube_box.yz, cube_box.is2D())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Square\n",
    "\n",
    "If your box is a square, you may use the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "5.0 0.0 5.0 0.0 0.0 0.0 True\n"
     ]
    }
   ],
   "source": [
    "square_box = box.Box.square(L=5)\n",
    "print(square_box.Lx, square_box.Lz, square_box.Ly, square_box.xy, square_box.xz, square_box.yz, square_box.is2D())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### From existing box\n",
    "\n",
    "Some data readers may provide box objects which can be directly passed in:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "#box_data = some_object.box\n",
    "#box_from_box = box.Box.from_box(box_data)\n",
    "#box_matrix = to_matrix(some_object.box)\n",
    "#box_from_matrix = box.Box.from_matrix(box_matrix)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Export\n",
    "\n",
    "If you want to export or display the box, you can use the following:\n",
    "\n",
    "## `to_matrix()`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[[5.0, 0.0, 0.0], [0, 5.0, 0.0], [0, 0, 0.0]]"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "square_box = box.Box.square(L=5)\n",
    "square_box.to_matrix()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `to_tuple()`\n",
    "\n",
    "You may also export as a named tuple (which can be used to initialize another Freud box):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "BoxTuple(Lx=5.0, Ly=5.0, Lz=0.0, xy=0.0, xz=0.0, yz=0.0)"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "square_box.to_tuple()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "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.5.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}