#!/usr/bin/env python
# coding: utf-8

# # freud - Example Notebooks
# 
# The `freud` library enables advanced analysis of particle simulations, particularly those utilizing periodic boundary conditions.
# This collection of Jupyter notebooks provides examples of how the different modules of `freud` can be used for different types of analysis.
# 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.
# 
# Run locally:
# ```bash
# git clone https://github.com/glotzerlab/freud-examples.git
# cd freud-examples
# jupyter notebook  # or "jupyter lab"
# ```
# 
# 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.

# ## Getting Started
# 
# The recommended method for installing `freud` is using conda (`conda install -c conda-forge freud`) or pip (`pip install freud-analysis`).
# Refer to the [Installation Guide](https://freud.readthedocs.io/en/stable/gettingstarted/installation.html) for instructions to install from source.
# 
# 
# Some of these notebooks also have a number of additional dependencies.
# 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.
# Note that because Bokeh uses Javascript, if you are running these notebooks using JupyterLab you will need to execute an additional command for installation:
# 
# ```bash
# jupyter labextension install jupyterlab_bokeh
# ```
# 
# If you have any issues with installing or seek more information about `freud`, please refer to the [`freud` documentation](https://freud.readthedocs.io/).

# ## Key concepts
# 
# There are a few critical concepts, algorithms, and data structures that are central to all of `freud`.
# 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.
# **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.**
# 
# - [`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`.
#   - [Box](module_intros/box.Box.ipynb)
# - [`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.
#   - [PeriodicBuffer](module_intros/locality.PeriodicBuffer.ipynb): Replicate periodic systems for long-range analyses.
#   - [Voronoi](module_intros/locality.Voronoi.ipynb): Compute Voronoi diagrams.

# ## Module Examples
# 
# These notebooks go into greater detail, showing the full functionality of each module in `freud`.
# 
# - [`freud.cluster`](https://freud.readthedocs.io/en/stable/cluster.html)
#   - [Cluster](module_intros/cluster.Cluster.ipynb): Cluster neighboring points.
# - [`freud.density`](https://freud.readthedocs.io/en/stable/density.html)
#   - [CorrelationFunction: Long Range Orientational Order](module_intros/density.CorrelationFunction.ipynb): Calculation complex-valued correlation functions.
#   - [Gaussian Density](module_intros/density.GaussianDensity.ipynb): Interpolate particle densities onto a regular grid.
#   - [Local Density](module_intros/density.LocalDensity.ipynb): Estimate system density near specific points.
#   - RDF: Compute the radial distribution function $g(r)$.
#     - [RDF: Calculating $g(r)$](module_intros/density.RDF-AccumulateFluid.ipynb)
#     - [RDF: Choosing Bin Widths](module_intros/density.RDF-BinWidth.ipynb)
# - [`freud.diffraction`](https://freud.readthedocs.io/en/stable/diffraction.html)
#   - [DiffractionPattern](module_intros/diffraction.DiffractionPattern.ipynb): Compute a 2D image of the static structure factor $S(\vec{k})$.
#   - [StaticStructureFactor](module_intros/diffraction.StaticStructureFactor.ipynb): Compute the 1D static structure factor $S(k)$.
# - [`freud.environment`](https://freud.readthedocs.io/en/stable/environment.html)
#   - [AngularSeparation](module_intros/environment.AngularSeparation.ipynb): Find relative angles of nearby particles.
#   - [BondOrder: Computing Bond Order Diagrams](module_intros/environment.BondOrder.ipynb): Compute bond orientational order diagrams.
#   - [LocalDescriptors](module_intros/environment.LocalDescriptors.ipynb): Calculate spherical harmonics for nearest-neighbors.
#   - [EnvironmentCluster: Clustering Particles' Local Environments](module_intros/environment.EnvironmentCluster.ipynb): Cluster various particle motifs.
# - [`freud.interface`](https://freud.readthedocs.io/en/stable/interface.html)
#   - [Interface](module_intros/interface.Interface.ipynb): Find interfaces between particles.
# - [`freud.order`](https://freud.readthedocs.io/en/stable/order.html)
#   - Hexatic: Calculate the hexatic (or $k$-atic) order parameter $\psi_k$.
#     - [Hexatic: Hard Hexagons](module_intros/order.Hexatic-HardHexagons.ipynb)
#     - [Hexatic: 2D Minkowski Structure Metrics](module_intros/order.Hexatic-Minkowski.ipynb)
#   - [Nematic Order Parameter](module_intros/order.Nematic.ipynb): Calculate the nematic order parameter.
#   - [Steinhardt Order Parameters](module_intros/order.Steinhardt.ipynb): Calculate the $q_l$ and $w_l$ Steinhardt order parameters (and some variants).
# - [`freud.pmft`](https://freud.readthedocs.io/en/stable/pmft.html)
#   - [PMFT in 2D](module_intros/pmft.PMFTXY.ipynb): Compute the potential of mean force for 2D systems.
#   - [PMFT in 3D](module_intros/pmft.PMFTXYZ.ipynb): Compute the potential of mean force for 3D systems.