Xmipp

Installing Xmipp

Xmipp is now integrated into Scipion . We recommend that you install Scipion and run Xmipp inside it.

If you need to run old Xmipp versions, read on about how to install the 3.1 version.


Download

Latest stable release

Fill in the XMIPP DOWNLOAD FORM to download precompiled binaries or the platform-independent source code. Note: We're still working to offer Windows binaries and OS-dependent packages to download. In the meanwhile, just platform-independent sources or GNU/Linux and MACOSX binaries are available.

Latest version from Git repository

Developers contributing to Xmipp may download the latest (possibly unstable) xmipp developing version where new features are being included (see also xmipp@sourceforge). Note that this option is NOT recommended for standard users, and we do not offer support for this version.

To do so, use (for read-only downloads):

git clone http://git.code.sf.net/p/newxmipp/code xmipp

or

git clone git://git.code.sf.net/p/newxmipp/code xmipp

Note if you use the second option destination port 9418 for sourforge shouldn't be blocked.

If you are a developer and want to submit changes, download with

git clone ssh://USERNAME@git.code.sf.net/p/newxmipp/code xmipp

For standard users and and programmers using Xmipp core libraries, v3.1 oficial release can also been used from git repository. To use the v3.1 branch, execute the following after clone command:

git checkout 3.1-release


Resolving external dependencies

First, you will need to manually solve the external dependencies of Xmipp3.0 before you run the Xmipp3.0 installation script. To do so, go to the OS-dependent section and find there your OS.

Compiling with MATLAB support

If you want to have a binding to MATLAB, you need to have MATLAB installed first and set MATLAB_DIR in the Xmipp configuration window. For instance, MATLAB_DIR=/usr/local/MATLAB/R2011a. This will make MATLAB mex compile the Xmipp binding libraries. You may see some error messages like:

Warning: You are using gcc version "4.4.4-14ubuntu5)".  The version
         currently supported with MEX is "4.3.4".
         For a list of currently supported compilers see:
         http://www.mathworks.com/support/compilers/current_release/

The reason is that MATLAB only supports some relatively old compiler versions. If you are using g++ as your standard compiler, you may "upgrade" the compiler supported by MATLAB by linking the libstdc++ library in MATLAB to that of the system

ln -s /usr/lib/x86_64-linux-gnu/libstdc++.so.6 /usr/local/MATLAB/R2011a/sys/os/glnxa64/libstdc++.so.6

In summary:

  • link ibstdc++.so as described above
  • In xmipp edit file .xmipp_scons.options and add lines

#MATLAB_DIR='/home/roberto/MATLAB_Production_Server/R2013a'
MATLAB_DIR='path_to_matlab'
matlab=True

  • Compile
  • In matlab add path to binding directory for example: /home/roberto/xmipp/libraries/bindings/matlab/

Compiling and Installing Xmipp3.1

Option 1: Using precompiled binaries

If you got the precompiled binaries, you just need to uncompress the tarball in the directory where you wish to install Xmipp and execute the install_binaries.sh script: 3.0

$ tar zxvf Xmipp-%XMIPPVERSION%-i386.tar.gz 
$ cd xmipp
$ source install_binaries.sh

and you are done. If you execute ./install_binaries.sh instead of source install.sh, then you should manually source .xmipp.bashrc file if you want to be able to execute xmipp in that shell without needing to reload your .bashrc file. To be able to execute xmipp every time you open your user session, follow the proper step from this guide.

Option 2: Building from source

Uncompress the tarball containing the sources (or download it already uncompressed from the git repository), go to the directory, and find the installation script install.sh

Then execute

./install.sh -j 2

Note: The number that follows the "-j" option in the install.sh order determines the number of CPU that you want to use for the compilation. Obviously, that depends strongly on you specific hardware. Nowadays a value of 2 CPU is present in almost every computer, but if you want to compile even faster, you can see the number of CPU your computer has using the following command on GNU/Linux:

cat /proc/cpuinfo

There you will see how many CPU you can use for the compilation, and change de "-j" argument according to that number. If you use a CPU number lower than the number of CPU that you have, it won't affect to the compilation, it just will take more time to compile.

*Installing NMA and CLTOMO extensions*

If you want to use NMA or CLTOMO extensions, after installing Xmipp, you can compile them by using

./install.sh --disable-all --cltomo --nma -j 2

Make sure you have installed cltomo and nma dependencies (arpack, blas and gfortran) before installing them

OS-dependent resolving external dependencies

These external dependencies are:

for xmipp itself...

make
g++  
opempi
java (jdk)
libpng
libfreetype6

for avoiding some anoying warning messages on python compilation and for making the development more confortable...

libssl-dev 
libncurses-dev 
libreadline-dev

for using NMA and CLTOMO extensions...

blas
arpack
gfortran

Depending on the OS, you must take different actions to satisfy those external dependencies:

OpenSUSE 12.1/12.2/12.3/13.1

All Packages can be installed by typing in the command line the following command:

sudo zypper --no-refresh install make gcc-c++ openmpi-devel xorg-x11-libX11-devel java-1_6_0-openjdk-devel freetype2-devel libpng14-devel readline-devel libopenssl-devel python-pyOpenSSL ncurses-devel 

The only difference in 12.2 and 12.3 with 12.1 is the jdk version, that must be 1.7.0 in 12.2, 12.3 and 13.1.

sudo zypper --no-refresh install make gcc-c++ openmpi-devel xorg-x11-libX11-devel java-1_7_0-openjdk-devel freetype2-devel libpng14-devel readline-devel libopenssl-devel python-pyOpenSSL ncurses-devel

In 13.1 you will need also some extra packages to use Xmipp with fonts improved

sudo zypper --no-refresh install make gcc-c++ openmpi-devel xorg-x11-libX11-devel java-1_7_0-openjdk-devel freetype2-devel libpng14-devel readline-devel libopenssl-devel python-pyOpenSSL ncurses-devel libXft-devel libXfont-devel libXau-devel libXrender-devel libexpat-devel libXss1

If you're not installing 3.1 version of Xmipp, please beware that it may be necessary to introduce bin and lib mpi folders in PATH and LD_LIBRARY_PATH respectively. To do that, put these lines in your ~/.bashrc file.

for 64bit OS:

export PATH=$PATH:/usr/lib64/mpi/gcc/openmpi/bin
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib64/mpi/gcc/openmpi/lib64

for 32bit OS:

export PATH=$PATH:/usr/lib/mpi/gcc/openmpi/bin
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib/mpi/gcc/openmpi/lib

Ubuntu 10.04/10.10/11.10/12.04/12.10/13.04/13.10 & Debian 6.0.4 & Linux Mint 12

From a clean Ubuntu, Mint or Debian installation, you can use the following command to install the required software:

sudo apt-get install build-essential openmpi-dev openmpi-bin libx11-dev openjdk-6-jdk libfreetype6-dev libpng12-dev libncurses-dev libssl-dev libreadline-dev libxft-dev

Note: Optionally, openjdk-7-jdk can be used instead of openjdk-6-jdk

Note: In recent versions of Debian, you have to install libopenmpi-dev instead of openmpi-dev

Arch 2011.08.19

If you're trying to install Xmipp3.0 on an Arch Linux clean installation, be sure your g++ version is the apropiate one. Xmipp3.0 doesn't compile with >4.6.2 versions, so if you have =4.7.0 (default in core-devel repositories) you will need to downgrade it. To do so, just download it from GNU website, untar it (with tar -xvjf gcc-4.6.2.tar.bz2), configure and compile it.

For compiling it, according to GNU guidelines, you should need to create a different directory for the object files.

mkdir objdir && cd objdir

Then you can configure it:

srcdir/configure

When it finish, you can compile it from the objdir with...

make

Finally, you can install the new compiler doing as root...

make install

Once you've got the apropiate compiler, you need to install dependencies. In order to install all these packages in Arch, you should write in the command line the command...

pacman -S make openmpi libx11 openjdk6 openssl readline pyopenssl ncurses libpng freetype2

Note that gcc has already been installed by compiling and not using pacman utility to avoid the 4.7.0 version that comes by default with Arch repositories.

Gentoo 20120306

External dependencies installation can be achieved by writting in the command line...

emerge openmpi libX11 icedtea-bin openssl ncurses readline libpng freetype

Note: In Gentoo, JAVA_HOME environment variable is not properly taken by the Xmipp installation script, so you will need to set it manually. If you installed icedtea-bin, you will have to write...

/etc/java-config-2/current-system-vm

in the JAVA_HOME setting field, in order to make Xmipp compile with java support

Mandriva 2011

Installing Xmipp on Madriva 2011 requires executing as root (for 64bits processors):

urpmi openmpi openmpi-devel gcc-c++ libx11-devel java-1.6.0-openjdk-devel lib64png-devel lib64freetype6-devel libreadline-devel libopenssl-devel

If your processor has 32bits architecture, the order would be:

urpmi openmpi openmpi-devel gcc-c++ libx11-devel java-1.6.0-openjdk-devel libpng-devel libfreetype6-devel libreadline-devel libopenssl-devel

Fedora 16 & CentOS 5.8/6.2/6.4

From a Fedora 16 or CentOS 6.2 clean installation, packages that will be needed for having Xmipp working can be installed typing in the command line the following order:

sudo yum install make gcc-c++ openmpi-devel libX11-devel java-1.6.0-openjdk-devel libpng-devel freetype-devel readline-devel libopenssl-devel libXft-devel libXext-devel expat-devel

There's a difference in Fedora16 respecting to the rest of the distributions. openmpi binaries are not introduced automatically in the PATH variable after openmpi package installation, so it has to be done manually. To do so, just insert the following line at the end of your ~/.bashrc file:

export PATH=$PATH:/usr/lib/openmpi/bin

If you need to proceed with the installation without rebooting the system or login again, just type that order directly in the console from where you're installing Xmipp.

Note: If you're running a 64 bits OS, probably your path to OpenMPI should be /usr/lib64/openmpi/bin

MAC OS X 10.6 (Snow Leopard)

In order to have Xmipp3.0 working on OS X compiled from sources you need to have installed gcc v4.0.1 and g++ v4.0.1

The fastest way to have this compiler in OS X is by installing XCode package for the OS version. In the case of Snow Leopard, the appropiate version of Xcode is 3.2.1. You can download it from apple developer webpage (you'll need to register as a developer, it's for free).

Once you've installed Xcode, you'll see gcc and g++ symbolic links under /usr/bin directory. You have to point them to 4.0.1 version by executing the following commands.

cd /usr/bin
rm gcc cc g++
ln -s i686-apple-darwin10-gcc-4.0.1 gcc
ln -s i686-apple-darwin10-gcc-4.0.1 cc
ln -s i868-apple-darwin10-g++-4.0.1 g++

By default /usr/bin/javac will be pointing to /System/Library/Frameworks/JavaVM.framework/Versions/Current/Commands/javac. To have Xmipp3.0 working on MAC, you will have to change that sym link to /System/Library/Frameworks/JavaVM.framework/Home. Be sure also that in .xmipp_scons.options file generated there's no "-m64" option in the CXXFLAGS and CCFLAGS if your architecture is not x86_64.

After these changes, compilation should work as in a GNU/Linux system.

Note: This information is deprecated. Xmipp 3.1 version is not MAC compilable at this moment, and only binaries are available for downloading. Please, do not try to compile it yourself, unless you want to spend several time writing code.

Windows

At this moment, Xmipp 3.0 only will compile its libraries and will not be functional at all for a typical Xmipp user, but for a developer who want to use Xmipp programs as part of his software.

Xmipp can be compiled using cross compiling with MinGW (http://www.mingw.org/). You need to install a number of development packages before being able to fully compile it and the compilation is very manual yet. You will need a git bash or GUI and MinGW cross compilation tool.

At this moment, the compilation is done as follows:

1 - Installation of every dependencies (on MinGW shell, it's also needed to install msys-libregex package using "mingw32-get.exe install msys-libregex" and copy regex.h from /include to $XMIPP_HOME/libraries/data folder) 2 - Put java bin folder inside the PATH env variable 3 - Clone the code with "git clone http://git.code.sf.net/p/newxmipp/code xmipp" 4 - Move to if_windows branch with "git checkout if_windows" 5 - Execute installation script with "./install.sh" After this step, all the external libraries should compile (don't worry about python) 6 - Build your own .xmipp_scons.options file and put it into Xmipp home directory. It should be something like this:

CCFLAGS = ['-fpermissive','-I/c/MinGW/include','-I/include','-Ilibraries/data'] CXXFLAGS = ['-fpermissive','-I/c/MinGW/include','-I/include','-Ilibraries/data'] MINGW_PATHS = [] gtest = False mpi = False JAVA_HOME = 'C:\\Java\\jdk1.6.0_37 JNI_CPPPATH = ['C:\\Java\\jdk1.6.0_37\\include', 'C:\\Java\\jdk1.6.0_37\\include\\win32']

7 - Load Xmipp environment with "source .xmipp.bashrc" 8 - Run Xmipp compilation with "xmipp_python external/scons/scons.py quiet=no mode=compile -j 1

At this point, everything should compile, but if some jar file could not be created, simply re-run the step 8 and it will compile fine.


If you just want to run on your Linux desktop machine, the precompiled binaries will probably work for you, and are definitely the easiest way to install. If you are installing Xmipp on a cluster (using MPI for parallelization), then you will most probably have to compile from source.


Edit the environment setup

After Xmipp installation, .xmipp.bashrc file is generated in the Xmipp folder. This bashrc file is needed to be loaded into the environment in order to have Xmipp working. We do not automatically set this into your environment because our external libraries may collide with your system ones so, just in case you're completely sure it won't make other software stop working (or if you don't care), set it automatically in your /etc/profile file. However, if you're a normal user and you want to automatically set xmipp in your user, you can put it in your user .bashrc file, so it won't destroy any other user stuff. To set automatically the environment variables needed to run Xmipp, include this line in the user's .bashrc file.

test -s ~/Xmipp_dir/.xmipp.bashrc && . ~/Xmipp_dir/.xmipp.bashrc || true

Note: On Gentoo GNU/Linux this line should be included in /etc/profile file instead of ~/.bashrc, or alternatively you can add the following lines to /etc/profile...

if [ -e ~/.bashrc ] ; then
  . ~/.bashrc
fi

If you have compiled with Matlab support, then add $XMIPP_HOME/libraries/binding/matlab to the Matlab path

Note II: You can alternatively give your system users the option to easily add xmipp environment variables, by adding a function to your /etc/profile. Therefore, if you use something like...

xmipp(){
   . /path/to/xmipp/.xmipp.bashrc
}

...then by typing "xmipp" in your console, you'll automatically load Xmipp environment variables.


Customize Xmipp

There are a few default behaviors that may be customized. The defaults are adequate for most users but if needed they may be changed editing the file $XMIPP_HOME/.xmipp.cfg.

# This file will serve to customize some settings of you Xmipp installation
# Each setting will be in the form o a shell variable set to some value

# BASH style
#---------- GUI ----------
# If you set to 1 the value of this variable, by default the programs 
# will launch the gui when call without argments, default is print the help
export XMIPP_GUI_DEFAULT=0

# If you set to 0 the value of this variable the script generated
# by programs gui will not be erased and you can use the same parameters
export XMIPP_GUI_CLEAN=1

#---------- Parallel ----------
# This variable will point to your job submition template file
export XMIPP_PARALLEL_LAUNCH=config_launch.py

# CSH style 
# Read descriptions of variable before
#setenv XMIPP_GUI_DEFAULT 0
#setenv XMIPP_GUI_CLEAN 1
#setenv XMIPP_CONFIG_LAUNCH config_launch_sge.py

# If you have .xmipp.cfg in your home folder it will override 
# this configurations

test -s ~/.xmipp.cfg && . ~/.xmipp.cfg || true

Make a job submission template script

Clusters with queue systems may required further configuration. Since each cluster is different you may need to edit the file $XMIPP_PARALLEL_LAUNCH (usually config_launch.py). By default xmipp is shipped with the following file that will work with clusters using PBS/TORQUE (as queue system). You may need to adjust it to your system. Xmipp will pass the following variables that may be used to create the command/file needed to launch the job. If you have created a new script for your cluster please send as a copy so we may add it to our gallery

# 1.- FileTemplate: string holding the template for launch script
#      Following vars are availables to template:
#      - %(jobName)s     : job name 
#      - %(nodes)d       : number of mpi nodes
#      - %(threads)d     : number of threads
#      - %(hours)d       : limit of running hours
#      - %(memory)d      : limit of memory used
#      - %(command)s     : command to be executed
#
#
# 2.- ArgsTemplate: string with the template arguments passed to launch Program
#      Following vars are availables to template:
#      - %(file)s     : file to be launched
#
# 3.- MpiArgsTemplate: string with the template arguments to run MPI program
#      Following vars are availables to template:
#      - %(nodes)d       : number of mpi nodes
#      - %(command)s     : command to be executed in parallel
#

In the .xmipp.bashrc or .xmipp.csh file, now, you can point to your configuration file through the variable XMIPP_PARALLEL_LAUNCH.


Running libraries tests (optional but recommended)

This tests can only be executed from a code-based installation. There's no xcompile command on binaries installation.

If you want to check xmipp instalation, you can run the tests

by executing (from inside Xmipp home directory) the command:

xcompile gtest=yes run_tests

If everything is OK and green, you probably have Xmipp3.0 installed correctly. Otherwise, send us your error messages.

You also can compile and run the libraries' tests using the installation GUI. For that purpose, you just have to check the checkbox "Build tests? gtest" in the "Advanced" tab.

install.sh script options in detail

options:

  • --disable-all, -d
  • --num-cpus=, -j
  • --configure-args=
  • --compile-args=
  • --unattended=[true|false]
  • --help, -h
  • --clean, -u
  • --untar, -u
  • --configure, -f
  • --compile, -c
  • --alglib=[true|false]
  • --bilib=[true|false]
  • --condor=[true|false]
  • --fftw=[true|false]
  • --gtest=[true|false]
  • --hdf5=[true|false]
  • --imagej=[true|false]
  • --jpeg=[true|false]
  • --scons=[true|false]
  • --sqlite=[true|false]
  • --tiff=[true|false]
  • --nma=[true|false]
  • --cltomo=[true|false]
  • --python=[true|false]
  • --matplotlib=[true|false]
  • --mpi4py=[true|false]
  • --numpy=[true|false]
  • --psutil=[true|false]
  • --tcl-tk=[true|false]
  • --tcl=[true|false]
  • --tk=[true|false]
  • --pymodules=[true|false]
  • --xmipp=[true|false]
  • --gui=[true|false]

Typical daily useful examples

  • I want to recompile an external library, let's say sqlite:
./install.sh --disable-all --sqlite=true -j 2

  • My system-wide library is exactly the same version as Xmipp one. Then you can use it, but Xmipp team strongly recommend use Xmipp one. For do that, when compiling you can tell xmipp not to compile that certain library with:
./install.sh --sqlite=false -j 2

  • I want to recompile xmipp_python:
./install.sh --disable-all --python=true

  • I need to recompile python modules
./install.sh --disable-all --pymodules=true

  • I need the installation script to do its best to install Xmipp without any interaction, because I'm not going to be in front of it for a while (that means if the system cannot find anything it will fail instead of asking you):
./install.sh --unattended=true -j 2

  • I need to configure Xmipp compilation flags
./setup.py -j 4 configure compile gui install

Tested Platforms

Xmipp has been successfully tested on the following OS:

OS Distribution Version Architecture Xmipp Version
GNU/Linux OpenSuSE 12.1 i386 & x86_64 3.0 / 3.0.1
x86_64 3.1
12.2 i386 & x86_64 3.0 / 3.0.1
x86_64 3.1
12.3 i386 & x86_64 3.0 / 3.0.1
13.1 x86_64 3.1
Ubuntu 10.04 i386 & x86_64 3.0 / 3.0.1 / 3.1
x86_64 3.1
10.10 i386 & x86_64 3.0 / 3.0.1
11.10 i386 & x86_64 3.0 / 3.0.1
12.04 i386 & x86_64 3.0 / 3.0.1
x86_64 3.1
12.10 i386 & x86_64 3.0 / 3.0.1
13.04 i386 & x86_64 3.0 / 3.0.1
13.10 i386 & x86_64 3.0 / 3.0.1
Debian 6.0.4 (squeeze) i386 & x86_64 3.0 / 3.0.1
7 (wheezy) x86_64 3.1
Mint 12 i386 & x86_64 3.0 / 3.0.1
Arch 2011.08.19 i386 & x86_64 3.0 / 3.0.1
Mandriva 2011 i386 & x86_64 3.0 / 3.0.1
Fedora 16 i386 & x86_64 3.0 / 3.0.1
Gentoo 20120306 i386 & x86_64 3.0 / 3.0.1
CentOS 5.8 i386 & x86_64 3.0 / 3.0.1
6.2 i386 & x86_64 3.0 / 3.0.1
6.4 i386 & x86_64 3.0 / 3.0.1
x86_64 3.1
MAC OS X Snow Leopard 10.6 i386 & x86_64 3.0 / 3.0.1
Mountain Lion 10.8 x86_64 3.1
Windows Xp (just library building from source) i386 3.0
7 (just library building from source) i386 3.0

If you have been able to compile Xmipp in any different OS, distro or version, please let us know.

Most common installation problems (FAQ)

  • Problem: When I try to execute some programs like xmipp_phantom_project a message tells me that it cannot find python dynamic library

xmipp_phantom_project: error while loading shared libraries: libpython2.7.so.1.0: cannot open shared object file: No such file or directory

Typical solution: copy the library files to $XMIPP_HOME/lib folder

cp $XMIPP_HOME/external/python/Python-2.7.2/libpython2.7.* $XMIPP_HOME/lib