Installation¶

Requirements¶

All required dependencies should be automatically taken care of if you install pymatgen using easy_install or pip. Otherwise, these packages should be available on PyPI.

Optional dependencies¶

Optional libraries that are required if you need certain features.

sympy: For defect generation and analysis.
VTK with Python bindings 5.8+ (http://www.vtk.org/): For visualization of crystal structures using the pymatgen.vis package. Note that the VTK package is incompatible with Python 3.x at the moment.
Atomistic Simulation Environment or ASE 3.6+: 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/. Note that the ASE package is compatible with Python 3.5+ at the moment.
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.
networkx: For graph analysis associated with critic2 topological analysis of electron charge densities, pygraphviz is also required for visualization.
pytest - For unittesting. Not optional for developers.

Optional non-Python programs¶

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

ffmpeg: For generation of movies in structure_vtk.py. The executable ffmpeg must be in the path. Get it at http://www.ffmpeg.org.
enum: For the use of pymatgen.transformations.advanced_transformations.EnumerateStructureTransformation and pymatgen.command_line.enumlib_caller module. This library by Gus Hart provides a robust way to enumerate derivative structures. It can be used to completely enumerate all symmetrically distinct ordered structures of disordered structures via EnumerateStructureTransformation. Many other advanced transformations (e.g., MagOrderingTransformation) use EnumerateStructureTransformation. The enum.x and makestr.x executables must be in the path. Get it at http://github.com/msg-byu/enumlib and follow the instructions to compile enum.x and makestr.x.
bader: For use with pymatgen.command_line.bader_caller.BaderAnalysis. This library by Henkelmann et al. provides a robust way to calculate the Bader analysis from a CHGCAR. The bader executable must be in the path. Get it at http://theory.cm.utexas.edu/bader.
gulp: For use with pymatgen.command_line.gulp_caller, which is in turn used extensively by pymatgen.analysis.defects to compute empirical defect energies.
aconvasp: For use with the pymatgen.command_line.aconvasp_caller.
Zeo++ (http://zeoplusplus.org): For defect structure generation. This is required in addition to installing the zeo Python package.
critic2 (https://github.com/aoterodelaroza/critic2): For topological analysis of critical points from electronic charge density. Provides more detailed information compared to bader. For use with pymatgen.command_line.critic2_caller.Critic2Caller.
graphviz (http://graphviz.org): For visualization of graphs generated using critic2.

Conda-based install¶

For these instructions, we will assume the 64-bit versions of all OSes. For OSX and Linux, both latest Python 3.x adn 2.7 are supported. For Windows, only latest Python 3.x is supported. Most common functionality should work out of the box on Windows, but some specialized analyses relying on external programs may require you to compile those programs from source.

Step 1: Install conda¶

Download and install the version of conda for your operating system from http://conda.pydata.org/miniconda.html. For Windows, make sure it is the Miniconda3 installer, and simply double-click the exe file. For Linux or Mac, run:

# If Mac
bash Miniconda3-latest-MacOSX-x86_64.sh

# If Linux
bash Miniconda3-latest-Linux-x86_64.sh

Note that you may need to create a new terminal after this step in order for the environmental variables added by conda to be loaded.

Step 2b: (Optional) Create a conda environment¶

If you are working with many python packages, it is generally recommended you create a separate environment for each of your packages. For example:

conda create --name my_pymatgen python
source activate my_pymatgen  # OSX or Linux
activate my_pymatgen  # Windows

Step 3: Install pymatgen¶

You can install pymatgen via conda as well via the conda-forge channel on Anaconda cloud:

conda install --channel conda-forge pymatgen

If the above fails, try using conda to install some critical dependencies and then do pip install:

conda install --yes numpy scipy matplotlib
pip install pymatgen

Step 4: (Optional) Install enumlib and bader (only for OSX and Linux)¶

If you would like to use the enumeration capabilities powered by Gus Hart’s enumlib or perform Bader charge analysis powered by the Bader analysis code of the Henkelmann group, please try installing these from source using the pmg command line tool as follows:

pmg config --install enumlib
pmg config --install bader

Then put these in your PATH somewhere. You can also download the source of these from the official repos and follow the compile instructions.

POTCAR Setup¶

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 the pmg command line utility includes a config functionality.

After installation, do:

pmg config -p <EXTRACTED_VASP_POTCAR> <MY_PSP>

In the above, <EXTRACTED_VASP_POTCAR> is the location of the directory that you extracted the downloaded VASP pseudopotential files. Typically, it has the following format:

- <EXTRACTED_VASP_POTCAR>
|- POT_GGA_PAW_PBE
||- Ac_s
|||-POTCAR
|||-...

or:

- <EXTRACTED_VASP_POTCAR>
|- potpaw_PBE
||- Ac_s
|||-POTCAR
|||-...

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 config variable pointing to the generated directory and you should then be able to generate POTCARs:

pmg config --add PMG_VASP_PSP_DIR <MY_PSP>

If you are using newer sets of pseudopotential files from VASP, the directory names may be different, e.g., POT_GGA_PAW_PBE_52. For such cases, please also add a default functional specification as follows:

pmg config --add PMG_DEFAULT_FUNCTIONAL PBE_52

You can also use this to specify whatever functional you would like to use by default in pymatgen, e.g., LDA_52, PW91, etc. Type:

pmg potcar -h

to see full list of choices.

Note

The Materials Project currently uses older versions of the VASP pseudopotentials for maximum compatibility with historical data, rather than the current 52/54 pseudopotentials. This setting can be overriden by the user if desired. As such, current versions of pymatgen will check the hashes of your pseudopotentials when constructing input sets to ensure the correct, compatible pseudopotential sets are used, so that total energies can be compared to those in the Materials Project database. If you use any functional other than PBE, note that you should not be combining results from these other functionals with Materials Project data. For up-to-date information on this, please consult the Materials Project documentation.

PyPy Support¶

PyPy is an alternative Python interpreter for running Python code and comes with significant speed improvements for common applications. However, historically, fewer packages offer PyPy support.

It is possible to install and use pymatgen with the PyPy interpreter but it comes with some important caveats:

While it is usable, PyPy is not officially supported by pymatgen. We do not run our full test suite on PyPy and it’s possible some parts of pymatgen will be broken.
All of pymatgen’s dependencies now support PyPy including numpy, scipy, and pandas, however matplotlib is difficult to install. If trying PyPy, the current advice is to remove the matplotlib dependency, however this means any modules using matplotlib will not be importable. The easiest way to install dependencies is using the PyPy builds on conda-forge. For spglib, cloning the repository and running python setup.py install manually is advised.
Performance improvements are unpredictible. Since pymatgen makes heavy use of numpy and custom extensions where appropriate, many code hot spots have already been optimized.

We welcome any developers interested in expanding our PyPy support.

Setup for Developers (using GitHub)¶

Step 1: Preparing your system¶

Windows¶

Download Microsoft Visual Studio 2015 (the free Community Edition) is fine.
Install Visual Studio 2015, but make sure that you select More Options -> Programming Languages -> Visual C++ during the installation process. By default, Visual Studio does not install Visual C++, which is needed.

Mac OSX¶

Download and install Xcode. Afterwards, install the XCode command line tools by typing the following in a terminal:
```
xcode-select --install
```
(Optional) Install gfortran. Get an installer at http://gcc.gnu.org/wiki/GFortranBinaries#MacOS.

Linux¶

Usually no preparation is needed as most of the standard compilers should already be available.

Step 2: Install pymatgen in developmental mode¶

Make sure you have git and git-lfs installed. Clone the repo at https://github.com/materialsproject/pymatgen.
Run git lfs install in the cloned repo first.
In your root pymatgen repo directory, type (you may need to do this with root privileges):
```
pip install -e .
```
Install any missing python libraries that are necessary.

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.

Please read up on pymatgen’s coding guidelines before you start coding. It will make integration much easier.

Installation tips for optional libraries¶

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.

VTK on Mac OS X (tested on v7.0)¶

The easiest is to install cmake from http://cmake.org/cmake/resources/software.html.

Type the following:

cd VTK (this is the directory you expanded VTK into)
mkdir build
cd build
ccmake .. (this uses cmake in an interactive manner)

Press “t” to toggle advanced mode. Then press “c” to do an initial configuration. After the list of parameters come out, ensure that the PYTHON_VERSION is set to 3, the VTK_WRAP_PYTHON is set to ON, and BUILD_SHARED_LIBS is set to ON. You may also need to modify the python paths and library paths if they are in non-standard locations. For example, if you have installed the official version of Python instead of using the Mac-provided version, you will probably need to edit the CMakeCache Python links. Example configuration for Python 3.5 installed using conda is given below (only variables that need to be modified/checked are shown):

PYTHON_EXECUTABLE:FILEPATH=/Users/<username>/miniconda3/bin/python3
PYTHON_INCLUDE_DIR:PATH=/Users/<username>/miniconda3/include/python3.5m
PYTHON_LIBRARY:FILEPATH=/Users/<username>/miniconda3/lib/libpython3.5m.dylib
VTK_INSTALL_PYTHON_MODULE_DIR:PATH=/Users/<username>/miniconda3/lib/python3.5/site-packages
VTK_PYTHON_VERSION:STRING=3
VTK_WRAP_PYTHON:BOOL=ON

Then press “c” again to configure and finally “g” to generate the required make files After the CMakeCache.txt file is generated, type:

make -j 4
sudo make install

With any luck, you should have vtk with the necessary python wrappers installed. You can test this by going into a python terminal and trying:

import vtk

OpenBabel Mac OS X (tested on v2.3.2)¶

Anaconda install

If you are using anaconda (and have pymatgen installed in your anaconda environment), you should be able to install openbabel with a single command:

conda install -c openbabel openbabel

Manual install

Openbabel must be compiled with python bindings for integration with pymatgen. Here are the steps that I took to make it work:

Install cmake from http://cmake.org/cmake/resources/software.html.
Install pcre-8.33 from ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/pcre-8.33.tar.gz.
Install pkg-config-0.28 using MacPorts or from http://pkgconfig.freedesktop.org/releases/pkg-config-0.28.tar.gz.
Install SWIG from http://prdownloads.sourceforge.net/swig/swig-2.0.10.tar.gz.
Download openbabel 2.3.2 source code from https://sourceforge.net/projects/openbabel/files/openbabel/2.3.2/.
Download Eigen version 3.1.2 from http://bitbucket.org/eigen/eigen/get/3.1.2.tar.gz.

Extract your Eigen and openbabel source distributions:

tar -zxvf openbabel-2.3.2.tar.gz
tar -zxvf eigen3.tar.gz

Now you should have two directories. Assuming that your openbabel src is in a directory called “openbabel-2.3.2” and your eigen source is in a directory called “eigen3”, do the following steps:
```
mv openbabel-2.3.2 ob-src
cd ob-src/scripts/python; rm openbabel.py openbabel-python.cpp; cd ../../..
```
Edit ob-src/scripts/CMakeLists.txt, jump to line 70, change “eigen2_define” to “eigen_define”.

Let’s create a build directory:

mkdir ob-build
cd ob-build
cmake -DPYTHON_BINDINGS=ON -DRUN_SWIG=ON -DEIGEN3_INCLUDE_DIR=../eigen3 ../ob-src 2>&1 | tee cmake.out

Before proceeding further, similar to the VTK installation process in the previous section, you may also need to modify the CMakeCache.txt file by hand if your python paths and library paths if they are in non-standard locations. For example, if you have installed the official version of Python instead of using the Mac-provided version, you will probably need to edit the CMakeCache Python links. Example configuration for Python 2.7 is given below (only variables that need to be modified are shown):
```
//Path to a program.
PYTHON_EXECUTABLE:FILEPATH=/Library/Frameworks/Python.framework/Versions/2.7/bin/python

//Path to a file.
PYTHON_INCLUDE_DIR:PATH=/Library/Frameworks/Python.framework/Versions/2.7/Headers

//Path to a library.
PYTHON_LIBRARY:FILEPATH=/Library/Frameworks/Python.framework/Versions/2.7/lib/libpython2.7.dylib
```
If you are using Mavericks (OSX 10.9) and encounter errors relating to <tr1/memory>, you might also need to include the following flag in your CMakeCache.txt:
```
CMAKE_CXX_FLAGS:STRING=-stdlib=libstdc++
```
Run make and install as follows:
```
make -j2
sudo make install
```
With any luck, you should have openbabel with python bindings installed. You can test your installation by trying to import openbabel from the python command line. Please note that despite best efforts, openbabel seems to install the python bindings into /usr/local/lib even if your Python is not the standard Mac version. In that case, you may need to add the following into your .bash_profile:
```
export PYTHONPATH=/usr/local/lib:$PYTHONPATH
```

Zeo++¶

If you use the defects analysis package, you will need to installZeo++/Voro++. Here are the steps you need to follow (thanks to Bharat)

Download and install Voro++:

mkdir Voro++
mkdir Voro++/voro
cd Voro++/voro
svn checkout --username anonsvn https://code.lbl.gov/svn/voro/trunk  # password is 'anonsvn'
cd trunk

Add -fPIC to the CFLAGS variable in config.mk, and then:

make

Download and install Zeo++:

mkdir Zeo++
mkdir Zeo++/zeo
cd Zeo++/zeo
svn checkout --username anonsvn https://code.lbl.gov/svn/zeo/trunk  # password is 'anonsvn'
cd trunk
make dylib

Create python bindings with Cython:

pip install cython
cd cython_wrapper
python setup_alt.py develop

To test that the installation worked, here is an example series of things you can do using pymatgen:

In [1]: from pymatgen.analysis.defects.core import Interstitial

In [2]: from pymatgen.core.structure import Structure

In [3]: structure = Structure.from_file('/path/to/file')

In [4]: radii, valences = {}, {}

In [5]: for element in structure.composition.elements:
   ...:     radii[element.symbol] = element.atomic_radius
   ...:     valence = element.group  # Just a first guess..
   ...:     if element.group > 12:
   ...:         valence -= 10
   ...:     valences[element.symbol] = valence

In [6]: interstitial = Interstitial(structure, radii=radii, valences=valences)

In [7]: interstitial._defect_sites