Python energy landscape explorer
Python C++ Fortran C CMake Shell
Latest commit d81d5b4 Apr 1, 2016 @kjs73 kjs73 Merge pull request #152 from kjs73/test_rectangular_cell_lists
Rectangular cell lists
Failed to load latest commit information.
cpp_tests add cpp tests for cell lists with particles uniformly in [-L/2, L/2] … Mar 24, 2016
doc updates to documentation Feb 19, 2015
examples removed unused arguments Feb 19, 2016
pele Merge pull request #150 from smcantab/invstill_poly Mar 22, 2016
playground removed unused file Mar 3, 2016
scripts add utility to convert pele database to pathsample db Feb 23, 2015
source reformulate one efficiency warning Mar 24, 2016
.coveragerc exclude test_functions/ from coverage report Jan 14, 2015
.gitignore remove CMakeLists.txt from gitignore May 15, 2015
.hgignore worked on doku, now numpydoc format in database Aug 16, 2012
.landscape.yaml update .landscape.yaml Nov 15, 2014
.travis.yml add explanation of problem solved by added line Mar 11, 2016 improve benchmarking for cell lists Dec 4, 2014
COPYING Add statement about GPL licence Aug 6, 2012
LICENSE change files with PyGMIN to pele Jun 4, 2013
README.rst fix small issue in README Dec 10, 2014 return by reference in HackyMatrix Jul 14, 2014
dgraph_lj38.png update the readme file and add some images Feb 12, 2014
gmin_lj38.png update the readme file and add some images Feb 12, 2014
lj38_gmin_dgraph.png github couldn't handle scaling images, so I put both in 1 image Feb 12, 2014
requirements.txt numpydocs -> numpydoc to agree with the name used in the Python Packa… Nov 5, 2014 wrapped IPSCut into cython and added test Mar 3, 2016 wrapped IPSCut into cython and added test Mar 3, 2016

README.rst Code Health

pele : Python Energy Landscape Explorer

Tools for global optimization and energy landscape exploration.

Source code:



Images: The global minimum energy structure of a 38 atom Lennard-Jones cluster. On the right is a disconnectivity graph showing a visualization of the energy landscape. The competing low energy basins are shown in color.

pele is a python partial-rewriting of GMIN, OPTIM, and PATHSAMPLE: fortran programs written by David Wales of Cambridge University and collaborators (


pele has tools for energy minimization, global optimization, saddle point (transition state) search, data analysis, visualization and much more. Some of the algorithms implemented are:

  1. Basinhopping global optimization
  2. LBFGS minimization (plus other minimizers)
  3. Single ended saddle point search:
    • Hybrid Eigenvector Following
    • Dimer method
  1. Double ended saddle point search
    • Nudged Elastic Band (NEB)
    • Doubly Nudged Elastic Band (DNEB)
  2. Disconnectivity Graph visualization
  3. Structure alignment algorithms
  4. Thermodynamics (e.g. heat capacity) via the Harmonic Superposition Approximation
  5. Transition rates analysis


Required packages

for compilation:

  1. fortran compiler
  2. c++ compiler (must support c++11, GCC 4.6 or similar)

python packages:

  1. numpy:

    We use numpy everywhere for doing numerical work. It also installs f2py which is used to compile fortran code into modules callable by python.

  2. scipy:

    For some of the optimizers and various scientific tools

  3. networkx:

    For graph functionality.

  4. matplotlib:

    For making plots (e.g. disconnectivity graphs)

  5. SQLAlchemy 0.7:

    For managing database of stationary points.

  6. hungarian:

    For permutational alignment

  7. pyro4:

    For parallel jobs

  8. scikits.sparse: optional

    For use of sparse Cholesky decomposition methods when calculating rates

  9. pymol: optional

    For viewing molecular structures

All the above packages can be installed via the python package manager pip (or easy_install). However, some of the packages (numpy, scipy) have additional dependencies and it can be more convenient to use the linux package manager (apt, yum, ...).

If you want to use the gui you will additionally need:

  1. qt4 and qt4 python bindings
  2. opengl python bindings

The Ubuntu packages (apt-get) for these are: python-qt4, python-opengl, and python-qt4-gl

In fedora Fedora (yum) you will want the packages: PyQt4, and PyOpenGl

Installing prerequisites on Ubuntu

If you're running ubuntu, you can get all the prerequisites with the following commands:

$ sudo apt-get install python-numpy python-scipy python-matplotlib python-qt4 python-opengl python-qt4-gl python-pip pymol
$ pip install --user networkx sqlalchemy hungarian pyro4 brewer2mpl cython

(in the above, the flag --user will install localy, in directory $HOME/.local/)


Compilation is required as many of the computationally intensive parts (especially potentials) are written in fortran and c++. Theoretically you should be able to use any fortran compiler, but we mostly use gfortran and GCC, so it's the least likely to have problems. This package uses the standard python setup utility (distutils). There are lots of options for how and where to install. For more information:

$ python --help
$ python --help-commands

Developers probably want to install "in-place", i.e. build the extension modules in their current directories:

$ python build_ext -i --fcompiler=gfortran

Users can install pele in the standard python package location:

$ python build --fcompiler=gfortran
$ python install [--user]

where --user installs it in $HOME/.local/

We now have an alternate form of compilation that uses CMake to compile the c++ libraries. This is much faster because it can be done in parallel and can take advantage of common libraries. Simply use the file in place of


If you do an in-place install, make sure to add the install directory to your PYTHONPATH environment variable. This is not necessary if you install to a standard location.

Installing on OS X

Most things installed very easily on my Macbook Air OS X Version 10.9 but it turns out that python distutils doesn't play very nicely with clang, the osx c compiler.

I was seeing erros of the type:

error: no type named 'shared_ptr' in namespace 'std'

This is a strange error because I'm using clang version 5.1 and the c++11 class shared_ptr has been part of clang since 3.2. Some googling suggested I try using the flag '-stdlib=libc++', which gave me the error:

clang: error: invalid deployment target for -stdlib=libc++ (requires OS X 10.7 or later)

Again, very strange becuase I have OS X version 10.9. But this error message eventually led me to figure out how to get past this. It appears that distutils is setting the environment variable MACOSX_DEPLOYMENT_TARGET to have the wrong value. I'm still not sure why, but setting the environment variable correctly before running fixes the problem. So, for an in-place build I would run

MACOSX_DEPLOYMENT_TARGET=10.9 python build_ext -i

Installing GUI on OS X

If you want to use the gui you have to install PyQt4 and its dependencies. This is not as simple as it should be, but is actually not too hard. There is a good guide at I had to install from source. This method is also detailed at This worked even though I'm using osx Mavericks

  1. Ensure you're using a decent python installation, the osx pre-packaged one won't suffice. I use the Enthought Canopy python distribution

  2. Install Qt4.8 using the pre-compiled binary

  3. Install SIP from source.

    In the directory you unpack the tar.gz file run the following commands

    python --arch=x86_64
    sudo make install

    You may need to use the -d flag to specify the install directory, but for me it selected the correct location. If you get the error "SIP requires Python to be built as a framework", don't worry, you can ignore this ( Simply comment out the following lines in They were at roughly line number 1675 for me.

    if "Python.framework" not in dl:
        error("SIP requires Python to be built as a framework")
  4. Install PyQt4 from source .

    In the directory you unpack the tar.gz file run the following commands

    make -j8
    sudo make install

    The -j8 flag specifies parallel compilation. You may need to use the -q flag to specify the location of the qmake program. Pass the location of the qmake file that is in the directory of Qt, which you installed in step 2.

  5. You're done! Test if it works by running examples/gui/

If you have updates or more complete installation instructions please email or submit a pull request.


You can find examples of how to run pele in the examples folder. More information can be found in the documentation at


pele has recently been renamed from pygmin


Pele has a large suite of unit tests. They can be run using the nose testing framework (which can be installed using pip). The tests are run from the top directory with this command:

nosetests pele

We also have test for our c++ code writen in pure c++. These are stored in the folder cpp_tests/ and can be compiled using CMake.