{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# ChemEnv : a fast and robust tool to automatically identify coordination environments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "ChemEnv is a fast and robust tool to automatically identify coordination environments (e.g. tetrahedral, octahedral, icosahedral, ...) in a structure. The package is in pymatgen/analysis/chemenv and a script (get_environments.py) is provided in the pymatgen/scripts directory for simple usages. For more advanced usages, you should write your own script(s).\n",
    "\n",
    "This example section consists of a small introduction describing the idea and the procedure for the identification of the environments. The simple \"get_environments.py\" script is then presented. Some more sophisticated examples of usage will be provided in a near future."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Introduction"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Describing materials and compounds in terms of the coordination environments of their constituent atoms is a common and useful practice amongst chemists, crystallographers and materials scientists. The ChemEnv package allows to identify the model coordination environment to which a given (slightly or highly distorted) local environment is the closest. Model coordination environments have been taken from the following two references that were published by the Internation Union of Crystallographers and the Internation Union of Pure and Applied Chemistry respectively :\n",
    "\n",
    "* J. Lima-de-Faria, E. Hellner, F. Liebau, E. Makovicky and E. Parthé, *Nomenclature of inorganic structure types*, Acta Crystallographica Section A **46**, 1 (1990).\n",
    "* R. M. Hartshorn, E. Hey-Hawkins, R. Kalio and G. J. Leigh, *Representation of configuration in coordination polyhedra and the extension of current methodology to coordination numbers greater than six*, Pure and Applied Chemistry **79**, 1779.\n",
    "\n",
    "Without entering into too many details, the identification procedure can be described as follows :\n",
    "1. Voronoi analysis to identify the neighbours\n",
    "2. Computation of the Continuous Symmetry Measure (measure of distortion) with respect to all model coordination environments (see [M. Pinsky and D. Avnir, *Continuous Symmetry Measures. 5. The Classical Polyhedra*, Inorganic Chemistry **37**, 5575 (1998).])\n",
    "3. The coordination environment is the one with the smallest CSM.\n",
    "\n",
    "The real procedure is in fact more complicated but will be described in a forecoming paper."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Quickly get environments of a given structure"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The \"get_environments.py\" script is available in pymatgen/scripts. It should be installed automatically when you install pymatgen and should thus be available directly in a terminal. The script is self explanatory. Just run it by issuing \"get_environment.py\" in a terminal.\n",
    "\n",
    "By default, the script will ask you the path to the CIF file of the structure you want to analyze. The script is also able to get a structure directly from the MaterialsProject database using the MaterialsProject id. In order to use this feature, you should setup the connection to the MaterialsProject by issuing \"get_environment.py -s\". Just follow the instructions of this setup option in order to setup the connection to the MaterialsProject. You can also specify other options (related to the procedure of identification of the coordination environments).\n",
    "\n",
    "After having specified your structure (either from a CIF file or by MaterialsProject Id), the script will automatically identify the coordination environments. Be carefull that this can take some time for large and/or complex structures (structures with large coordination numbers typically take more time to process).\n",
    "\n",
    "After the identification has been performed, the script asks you what you want to do :\n",
    "* See the list of environments for each site (\"y\" or \"d\" with more details)\n",
    "* See the grid of angle/distance parameters (\"g\", advanced/expert usage, description of this will follow)\n",
    "\n",
    "If you have VTK installed, you can also visualize the structure directly."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2.0
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}