<commit_before>Requirements
============

Required for proper functioning of the code
-------------------------------------------

1. Python 2.7+ required.  New default modules such as json are used, as well as 
   new unittest features in Python 2.7.
2. numpy - For array, matrix and other numerical manipulations. Used extensively 
   by all core modules.

Optional Python Libraries
-------------------------
Optional python libraries that are required if you need certain features

1. scipy 0.10+ (highly recommended) - For use in Gaussian smearing and phase
   diagram construction using scipy.spatial.Delaunay.
2. matplotlib (highly recommended): For plotting (e.g., Phase Diagrams).
3. PyCifRW (highly recommended): For reading and writing Crystallographic 
   Information Format (CIF) files. Get it from http://pycifrw.berlios.de/ or a
   working version is provided in the dependencies directory of pymatgen.
4. pyspglib 1.2+ (highly recommended): For symmetry finding. Needed if you are
   using the pymatgen.symmetry, pymatgen.transformation and pymatgen.alchemy
   packages. Get it at http://spglib.sourceforge.net/ or a working version is
   provided in the dependencies directory of pymatgen.
5. VTK with Python bindings (http://www.vtk.org/): For visualization of crystal 
   structures using the pymatgen.vis package.
6. Atomistic Simulation Environment or ASE : Required for the usage of the 
   adapters in pymatgen.io.aseio between pymatgen's core Structure object and 
   the Atoms object used by ASE. Get it at https://wiki.fysik.dtu.dk/ase/.
7. OpenBabel with Python bindings (http://openbabel.org). Required for the
   usage of the adapters in pymatgen.io.babelio between pymatgen's Molecule
   and OpenBabel's OBMol. Opens up input and output support for the very large
   number of input and output formats supported by OpenBabel.
8. nose - For complete unittesting. This is NOT optional for developers!

Optional non-Python programs
----------------------------

Optional non-python libraries (because no good pythonic alternative exists at 
the moment) required only for certain features.

1. Qhull : Needed for bond length analysis (structure_analyzer.py), or if you
   use the use_external_qhull option in phase diagram generation. The executable
   qconvex and qvoronoi must be in the path.Get it at http://www.qhull.org/.
2. ffmpeg : Needed for generation of movies (structure_vtk.py).  The executable 
   ffmpeg must be in the path. Get it at http://www.ffmpeg.org.

POTCAR Setup for Users
======================

For the code to generate POTCAR files, it needs to know where the VASP 
pseudopotential files are.  We are not allowed to distribute these under the 
VASP license. The good news is that we have included a setup script to help you along.

If you cloned the repo directly from github, you should have a run_me_first.sh 
file in the root directory of your local repo. Otherwise, you can get it directly 
from our github site at http://github.com/materialsproject/pymatgen. Run the 
shell script and follow the instructions. If you have done it correctly, you 
should get a resources directory with the following directory structure::

   - psp_resources
   |- POT_GGA_PAW_PBE
   ||- POTCAR.Ac_s.gz
   ||- POTCAR.Ac.gz
   ||- POTCAR.Ag.gz
   ...
   |- POT_GGA_PAW_PW91
   ...
   
After generating the resources directory, you should add a VASP_PSP_DIR 
environment variable pointing to the generated directory and you should then be 
able to generate POTCARs.

Alternatively, you can setup the above directly structure manually and set the 
VASP_PSP_DIR environment variable accordingly.

Setup for Developers (using github)
===================================

1. Clone the repo at http://github.com/materialsproject/pymatgen.
2. Install the necessary python libraries.
3. (Recommended) Add pymatgen to your PYTHONPATH.
4. (Recommended) Copy hooks from the example-hooks directory into the .git/hooks/ 
   directory in your local repo.  

I recommend that you start by reading some of the unittests in the tests 
subdirectory for each package.  The unittests demonstrate the expected behavior 
and functionality of the code.

Installation tips for optional libaries
=======================================

This section provides a guide for installing various optional libraries used in 
pymatgen.  Some of the python libraries are rather tricky to build in certain 
operating systems, especially for users unfamiliar with building C/C++ code. 
Please feel free to send in suggestions to update the instructions based on 
your experiences. In all the instructions, it is assumed that you have standard
gcc and other compilers (e.g., Xcode on Macs) already installed.

Scipy (tested on v0.10.1)
-------------------------

Mac OS X 10.7
~~~~~~~~~~~~~

Typical installation of Xcode with python setup.py install seems to work fine. 
The pre-compiled binary for OSX 10.6 also seems to work.
<commit_msg>Update install instructions.<commit_after>Requirements
============

Required for proper functioning of the code
-------------------------------------------

1. Python 2.7+ required.  New default modules such as json are used, as well as 
   new unittest features in Python 2.7.
2. numpy - For array, matrix and other numerical manipulations. Used extensively 
   by all core modules.

Optional Python Libraries
-------------------------
Optional python libraries that are required if you need certain features

1. scipy 0.10+ (highly recommended) - For use in Gaussian smearing and phase
   diagram construction using scipy.spatial.Delaunay.
2. matplotlib (highly recommended): For plotting (e.g., Phase Diagrams).
3. PyCifRW (highly recommended): For reading and writing Crystallographic 
   Information Format (CIF) files. Get it from http://pycifrw.berlios.de/ or a
   working version is provided in the dependencies directory of pymatgen.
4. pyspglib 1.2+ (highly recommended): For symmetry finding. Needed if you are
   using the pymatgen.symmetry, pymatgen.transformation and pymatgen.alchemy
   packages. Get it at http://spglib.sourceforge.net/ or a working version is
   provided in the dependencies directory of pymatgen.
5. VTK with Python bindings (http://www.vtk.org/): For visualization of crystal 
   structures using the pymatgen.vis package.
6. Atomistic Simulation Environment or ASE : Required for the usage of the 
   adapters in pymatgen.io.aseio between pymatgen's core Structure object and 
   the Atoms object used by ASE. Get it at https://wiki.fysik.dtu.dk/ase/.
7. OpenBabel with Python bindings (http://openbabel.org). Required for the
   usage of the adapters in pymatgen.io.babelio between pymatgen's Molecule
   and OpenBabel's OBMol. Opens up input and output support for the very large
   number of input and output formats supported by OpenBabel.
8. nose - For complete unittesting. This is NOT optional for developers!

Optional non-Python programs
----------------------------

Optional non-python libraries (because no good pythonic alternative exists at 
the moment) required only for certain features.

1. Qhull : Needed for bond length analysis (structure_analyzer.py), or if you
   use the use_external_qhull option in phase diagram generation. The executable
   qconvex and qvoronoi must be in the path.Get it at http://www.qhull.org/.
2. ffmpeg : Needed for generation of movies (structure_vtk.py).  The executable 
   ffmpeg must be in the path. Get it at http://www.ffmpeg.org.

POTCAR Setup for Users
======================

For the code to generate POTCAR files, it needs to know where the VASP 
pseudopotential files are.  We are not allowed to distribute these under the 
VASP license. The good news is that we have included a setup script to help you along.

If you cloned the repo directly from github, you should have a run_me_first.sh 
file in the root directory of your local repo. Otherwise, you can get it directly 
from our github site at http://github.com/materialsproject/pymatgen. Run the 
shell script and follow the instructions. If you have done it correctly, you 
should get a resources directory with the following directory structure::

   - psp_resources
   |- POT_GGA_PAW_PBE
   ||- POTCAR.Ac_s.gz
   ||- POTCAR.Ac.gz
   ||- POTCAR.Ag.gz
   ...
   |- POT_GGA_PAW_PW91
   ...
   
After generating the resources directory, you should add a VASP_PSP_DIR 
environment variable pointing to the generated directory and you should then be 
able to generate POTCARs.

Alternatively, you can setup the above directly structure manually and set the 
VASP_PSP_DIR environment variable accordingly.

Setup for Developers (using github)
===================================

1. Clone the repo at http://github.com/materialsproject/pymatgen.
2. Install the necessary python libraries.
3. In your root pymatgen repo directory, type::

   python setup.py develop #You may need to do this with root privileges.

I recommend that you start by reading some of the unittests in the tests 
subdirectory for each package.  The unittests demonstrate the expected behavior 
and functionality of the code.

Installation tips for optional libaries
=======================================

This section provides a guide for installing various optional libraries used in 
pymatgen.  Some of the python libraries are rather tricky to build in certain 
operating systems, especially for users unfamiliar with building C/C++ code. 
Please feel free to send in suggestions to update the instructions based on 
your experiences. In all the instructions, it is assumed that you have standard
gcc and other compilers (e.g., Xcode on Macs) already installed.

Scipy (tested on v0.10.1)
-------------------------

Mac OS X 10.7
~~~~~~~~~~~~~

Typical installation of Xcode with python setup.py install seems to work fine. 
The pre-compiled binary for OSX 10.6 also seems to work.

{'fraction_non_alphanumeric': 0.09825416159155502, 'fraction_numerical': 0.007409663012586277, 'mean_word_length': 3.5615740740740742, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1962476', 'n_tokens_mistral': 2776, 'n_tokens_neox': 2620, 'n_words': 1289}