Installation

The use of the qe-util/elastic packages and QE-doc tutorials require some preparations to be made. You need to install and configure several packages. The operation is fairly simple and contains just a few steps.

Pre-requisites

To run the programs you need a fairly recent Linux system. Any decent and modern Linux distribution will do, but the code was developed and tested on Ubuntu 13.10/64 and Debian stable.

Installation

These are new unified istructions which, thanks to people at Continuum Analytics and their Anaconda system, should be compatible with most of the current Linux systems.

You can install the software even on Mac or Windows system with some additional work (you need to build few external dependencies separately).

For legacy instructions see below.

The setup requires installation of the conda package menager followed by the installation of the reguired packages.

conda package menager

To install conda you need to go to Conda website and download the package appropriate for your system. After downloading the package install the menager as ordinary user (the path is an example, replace with your actual path):

    bash Downloads/Miniconda-3.4.2-Linux-x86.sh

You need to accept the license (it is free and quite reasonable) and select the place to where to put the software (accept the default). An decide if you want the software added to your standard path (I recommend you do - so change the default). After finishing the installation close the terminal an open a different one (to get new search path initialized) or re-login into your session. Then update the package menager:

    conda update conda

Basic packages

Except for standard system software you will need only the gcc compiler for compilation of the pyspglib module.

Building nipy environment

  1. Create a new environment nipy with the basic packages installed:

     conda create -n nipy ipython ipython-notebook numpy scipy matplotlib
  2. install the non-standard packages:

     conda install -n nipy -c https://conda.binstar.org/jochym python-ase pyspglib elastic qeutil

Update the packages

Since qe-util and elastic are under constant development one needs to upgrade them from time to time. Some changes may make your old calculations stop working, due to the incompatible changes to the interfaces (we do try to avoid this, but still sometimes there is simply no other way). Thus, upgrading is a good idea at the start of the project, but not in the middle of it.

The command to update all installed packages:

    conda update -n nipy -c https://conda.binstar.org/jochym --all

If you need to update single package you use:

    conda update -n nipy -c https://conda.binstar.org/jochym  name_of_the_package

Configuration

First you need to grab the supporting files archive and unpack it in your working directory:

tar -xvzf qe-doc-support.tgz

The system is configured by default to use a quantum espresso software present and configured locally for the first tutorial and remote execution for the rest of tutorials. The installation of the Q-E software is beyond the scope of this tutorial. The debian and ubuntu distributions provide stable but fairly old versions of this package. It is highly recommended to obtain a recent version or, better still, to use one installed in some HPTC centre. The example of such remote configuration is provided in the examples and also the skeleton host.py configuration file is included in the supporting files. The supporting files contain also examples of the host.py modifications (in the config-examples directory) for some of the machines in the WestGrid Canadian research network and the University of Saskatchewan.

The information concerned with local configuration at the University of Saskatchewan is also included on the USASK NiPy page.

Essentially you need to figure out how to transport files from your workstation to the computing machine and how to run jobs there. One very comfortable way of doing this is mounting the remote directory locally using sshfs and setting up the key-authentication execution over ssh to the computing machine. Such a setup makes the "remoteness" of the calculations almost transparent.

Usage

Activation

To activate the environment execute (nipy is the name of the environment here):

    source activate nipy

Since the qe-util package is designed to be used inside the iPython notebook environment go to the directory where you downloaded the example notebooks (.ipynb files - it should be outside* of the nipy tree) and run (remember to have the nipy environment activated!) :

ipython notebook --pylab=inline

Your web browser will open a page with a list of example notebooks. Open (click) the first and follow the instructions there.

Deactivation

After you are done with the environment you deactivate it by the command:

    source deactivate

Legacy instructions

These legacy instructions are provided just for all installs and are not recommended for current installations. In fact I recommend migration from the old install to the new style. It is easy and will save you time going forward.

Older distributions (RHEL, CentOS, Scientific Linux)

You will need the current python install with virtualenv system installed.

The software is not fully compatible with python 2.6, so if you are on the old distribution (e.g. RHEL 6) you will need to compile the python interpreter from source. Python source can be downloaded from the python web page - you need version 2.7.x. To install alternative python interpreter without interfering with the system interpreter you unpack the distribution and run:

./configure
make 
sudo make altinstall

(the last line executed as superuser). The rest of the instalation is the same except the virtual environment creation command will change into:

virtualenv -p python2.7 nipy

The installation instructions for the virtualenv package can be found on its web page. Tha package is avaliable for download at Virtualenv PyPi page. You do not need to install the package. It is enough to just unpack it and run it as (from the directory you have unpacked it into):

python virtualenv.py [any_parameters_you_need]

Your system should also have a basic set of development packages installed:

  • gcc
  • g++
  • gfortran
  • python 2.7
  • development libraries for openssl and other basic system libraries (for Python compilation)
  • lapack and blas development libraries (for scipy installation)
  • freetype and png development libraries (for matplotlib installation)

Installation

It is best to perform all your work in the python virtualenv. To create one, go to the directory of your choice and run (nipy is a name of the environment we have chosen, you can use a different name, just stick with it):

virtualenv nipy

This will create the nipy directory which is a place where all software will be installed. You do not need to work in this directory! In fact it is better not too. If you have a recent and complete distribution and you know what you are doing you can try to use a --system-site-packages option to virtualenv and skip the installation of any packages already present in your system (you should install at least iPython, ASE, SPGlib, Elastic, QE-doc). Just remember that this is not fully supported and tested variant (but it should work anyway).

Next step is activation. Execute in your terminal the following line:

source nipy/bin/activate

replacing the nipy by your path to the environment directory. This command activates the environment. To deactivate simply run:

deactivate

Next you need to install the software. Activate the environment and run:

pip install distribute --upgrade
pip install ipython
pip install pyzmq
pip install jinja2
pip install tornado
pip install numpy
pip install scipy
pip install matplotlib

This will take some time but should execute without problems.

Next go to the ASE website and download the latest tarball. At this moment it is ASE 3.8.1.3440

Unpack it in some temporary place, enter its directory and run:

python setup.py install

We are almost done. The last dependence is the space-group library SPGlib. Download the spglib distribution and unpack it in some temporary place. Next enter the python/ase subdirectory and execute:

python setup.py install

The last step is installation of the qe-util and elastic packages. It is simple, just execute:

pip install qeutil
pip install elastic

Now you have a ready working environment.

Upgrading

Since qe-util and elastic are under constant development one needs to upgrade them from time to time. Some changes may make your old calculations stop working, due to the incompatible changes to the interfaces (we do try to avoid this, but still sometimes there is simply no other way). Thus, upgrading is a good idea at the start of the project, but not in the middle of it.

The command to upgrade a package_name is:

pip install package_name --upgrade

(e.g. pip install qeutil --upgrade)