{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# freud - Example Notebooks\n",
    "\n",
    "The `freud` library enables advanced analysis of particle simulations, particularly those utilizing periodic boundary conditions.\n",
    "This collection of Jupyter notebooks provides examples of how the different modules of `freud` can be used for different types of analysis.\n",
    "These notebooks may be launched [interactively on Binder](https://mybinder.org/v2/gh/glotzerlab/freud-examples/master?filepath=index.ipynb) or downloaded and run on your own system.\n",
    "\n",
    "Run locally:\n",
    "```bash\n",
    "git clone https://github.com/glotzerlab/freud-examples.git\n",
    "cd freud-examples\n",
    "jupyter notebook  # or \"jupyter lab\"\n",
    "```\n",
    "\n",
    "See [Notebook Basics](http://nbviewer.jupyter.org/github/jupyter/notebook/blob/master/docs/source/examples/Notebook/Notebook%20Basics.ipynb) and [Running Code](http://nbviewer.jupyter.org/github/jupyter/notebook/blob/master/docs/source/examples/Notebook/Running%20Code.ipynb) for tutorials on using Jupyter itself."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Getting Started\n",
    "\n",
    "The recommended method for installing `freud` is using conda (`conda install -c conda-forge freud`) or pip (`pip install freud-analysis`).\n",
    "Refer to the [Installation Guide](https://freud.readthedocs.io/en/stable/gettingstarted/installation.html) for instructions to install from source.\n",
    "\n",
    "\n",
    "Some of these notebooks also have a number of additional dependencies.\n",
    "In particular, all of these notebooks involve making plots with either [Matplotlib](https://matplotlib.org/) or [Bokeh](https://bokeh.pydata.org/en/latest/), so you will also need to install those to run these notebooks locally.\n",
    "Note that because Bokeh uses Javascript, if you are running these notebooks using JupyterLab you will need to execute an additional command for installation:\n",
    "\n",
    "```bash\n",
    "jupyter labextension install jupyterlab_bokeh\n",
    "```\n",
    "\n",
    "If you have any issues with installing or seek more information about `freud`, please refer to the [`freud` documentation](https://freud.readthedocs.io/)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Key concepts\n",
    "\n",
    "There are a few critical concepts, algorithms, and data structures that are central to all of `freud`.\n",
    "In order to familiarize yourself with these before delving too deep into the workings of specific `freud` modules, we recommend looking through certain notebooks first.\n",
    "**In this cell and the next one, each `freud` module is linked to the documentation for more information, while the links in the list point to Jupyter notebooks demonstrating the classes in those modules.**\n",
    "\n",
    "- [`freud.box`](https://freud.readthedocs.io/en/stable/box.html): The box module defines the Box object used throughout `freud` to represent periodic simulation boxes. Since all analysis methods involve some representation of particles in a box of some sort, it is useful to understand boxes and periodicity before attempting to use the rest of `freud`.\n",
    "  - [Box](module_intros/box.Box.ipynb)\n",
    "- [`freud.locality`](https://freud.readthedocs.io/en/stable/locality.html): The locality module enables `NeighborQuery` and `NeighborList` calculations, which provide information on which particles are near to other particles in a system. These are described in the Reference documentation. Additional classes are demonstrated below.\n",
    "  - [PeriodicBuffer](module_intros/locality.PeriodicBuffer.ipynb): Replicate periodic systems for long-range analyses.\n",
    "  - [Voronoi](module_intros/locality.Voronoi.ipynb): Compute Voronoi diagrams."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Module Examples\n",
    "\n",
    "These notebooks go into greater detail, showing the full functionality of each module in `freud`.\n",
    "\n",
    "- [`freud.cluster`](https://freud.readthedocs.io/en/stable/cluster.html)\n",
    "  - [Cluster](module_intros/cluster.Cluster.ipynb): Cluster neighboring points.\n",
    "- [`freud.density`](https://freud.readthedocs.io/en/stable/density.html)\n",
    "  - [CorrelationFunction: Long Range Orientational Order](module_intros/density.CorrelationFunction.ipynb): Calculation complex-valued correlation functions.\n",
    "  - [Gaussian Density](module_intros/density.GaussianDensity.ipynb): Interpolate particle densities onto a regular grid.\n",
    "  - [Local Density](module_intros/density.LocalDensity.ipynb): Estimate system density near specific points.\n",
    "  - RDF: Compute the radial distribution function $g(r)$.\n",
    "    - [RDF: Calculating $g(r)$](module_intros/density.RDF-AccumulateFluid.ipynb)\n",
    "    - [RDF: Choosing Bin Widths](module_intros/density.RDF-BinWidth.ipynb)\n",
    "- [`freud.diffraction`](https://freud.readthedocs.io/en/stable/diffraction.html)\n",
    "  - [DiffractionPattern](module_intros/diffraction.DiffractionPattern.ipynb): Compute a 2D image of the static structure factor $S(\\vec{k})$.\n",
    "  - [StaticStructureFactor](module_intros/diffraction.StaticStructureFactor.ipynb): Compute the 1D static structure factor $S(k)$.\n",
    "- [`freud.environment`](https://freud.readthedocs.io/en/stable/environment.html)\n",
    "  - [AngularSeparation](module_intros/environment.AngularSeparation.ipynb): Find relative angles of nearby particles.\n",
    "  - [BondOrder: Computing Bond Order Diagrams](module_intros/environment.BondOrder.ipynb): Compute bond orientational order diagrams.\n",
    "  - [LocalDescriptors](module_intros/environment.LocalDescriptors.ipynb): Calculate spherical harmonics for nearest-neighbors.\n",
    "  - [EnvironmentCluster: Clustering Particles' Local Environments](module_intros/environment.EnvironmentCluster.ipynb): Cluster various particle motifs.\n",
    "- [`freud.interface`](https://freud.readthedocs.io/en/stable/interface.html)\n",
    "  - [Interface](module_intros/interface.Interface.ipynb): Find interfaces between particles.\n",
    "- [`freud.order`](https://freud.readthedocs.io/en/stable/order.html)\n",
    "  - Hexatic: Calculate the hexatic (or $k$-atic) order parameter $\\psi_k$.\n",
    "    - [Hexatic: Hard Hexagons](module_intros/order.Hexatic-HardHexagons.ipynb)\n",
    "    - [Hexatic: 2D Minkowski Structure Metrics](module_intros/order.Hexatic-Minkowski.ipynb)\n",
    "  - [Nematic Order Parameter](module_intros/order.Nematic.ipynb): Calculate the nematic order parameter.\n",
    "  - [Steinhardt Order Parameters](module_intros/order.Steinhardt.ipynb): Calculate the $q_l$ and $w_l$ Steinhardt order parameters (and some variants).\n",
    "- [`freud.pmft`](https://freud.readthedocs.io/en/stable/pmft.html)\n",
    "  - [PMFT in 2D](module_intros/pmft.PMFTXY.ipynb): Compute the potential of mean force for 2D systems.\n",
    "  - [PMFT in 3D](module_intros/pmft.PMFTXYZ.ipynb): Compute the potential of mean force for 3D systems."
   ]
  }
 ],
 "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.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}