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
Permalink
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
CMakeLists.txt.in 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
cythonize.py 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
setup.py wrapped IPSCut into cython and added test Mar 3, 2016
setup_with_cmake.py wrapped IPSCut into cython and added test Mar 3, 2016

README.rst

https://travis-ci.org/pele-python/pele.svg?branch=master https://coveralls.io/repos/pele-python/pele/badge.png?branch=master Code Health

pele : Python Energy Landscape Explorer

Tools for global optimization and energy landscape exploration.

Source code: https://github.com/pele-python/pele

Documentation: http://pele-python.github.io/pele/

lj38_gmin_dgraph.png

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 (http://www-wales.ch.cam.ac.uk/software.html).

Description

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

INSTALLATION

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. https://networkx.lanl.gov

  4. matplotlib:

    For making plots (e.g. disconnectivity graphs)

  5. SQLAlchemy 0.7:

    For managing database of stationary points. http://www.sqlalchemy.org/

  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

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 setup.py --help
$ python setup.py --help-commands

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

$ python setup.py build_ext -i --fcompiler=gfortran

Users can install pele in the standard python package location:

$ python setup.py build --fcompiler=gfortran
$ python setup.py 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 setup_with_cmake.py in place of setup.py

PYTHONPATH

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 setup.py fixes the problem. So, for an in-place build I would run

MACOSX_DEPLOYMENT_TARGET=10.9 python setup.py 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 http://www.pythonschool.net/mac_pyqt/. I had to install from source. This method is also detailed at http://sharewebegin.blogspot.co.uk/2013/06/install-pyqt-on-mac-osx-lion1084.html. 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 https://www.enthought.com/products/canopy/

  2. Install Qt4.8 using the pre-compiled binary http://qt-project.org/downloads

  3. Install SIP from source. http://www.riverbankcomputing.co.uk/software/sip/download

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

    python configure.py --arch=x86_64
    make
    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 (http://python.6.x6.nabble.com/installing-sip-on-os-x-with-canopy-td5037076.html). Simply comment out the following lines in sipconfig.py. 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 http://www.riverbankcomputing.co.uk/software/pyqt/download .

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

    python configure-ng.py
    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/ljsystem.py

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

Running

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

http://pele-python.github.com/pele/

Notes

pele has recently been renamed from pygmin

Tests

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.