Download & install

Get RELION to run on your computer in 4 easy steps. Note that RELION is distributed under a GPL license, i.e. it is completely free, open-source software for both academia and industry.

Download & install relion-1.4 (stable)

Download the stable RELION-1.4 release for free from here.

First unpack the tar-ball, and enter the relion directory using:

tar -jxf relion-1.4.tar.bz2
cd relion-1.4

Note that compilation of the parallel version of RELION needs an existing MPI installation on your system. And you'll need the -devel version to link against. We use the open-source flavour openMPI, but in principle any flavour should do. However, in case of trouble, please do try compiling openMPI (with the correct --with_tm reference to your queue setup) on your system before contacting us. Just make sure the mpi executables (e.g. mpiCC and mpirun) are in your PATH and the libraries are in your LD_LIBRARY_PATH. We use the following lines in our .cshrc:

setenv PATH /public/EM/OpenMPI/bin:$PATH
setenv LD_LIBRARY_PATH /public/EM/OpenMPI/lib:$LD_LIBRARY_PATH

For compilation on Mac OSX, also use: "setenv MAC_OSX".

Together with the RELION source code, come tar.gz files for fftw-3.2.2 and fltk-1.3.0. These two external libraries are needed to build RELION. Standard installation of the whole package is performed by executing the following command:

./INSTALL.sh -j 8

Where -j 8 indicates that 8 threads may be used in parallel for compilation. By default the package will be built inside the relion directory. Move the resulting bin/ and lib/ directories to a different place if you want to install RELION elsewhere.

Download & install RELION-2.0 (beta-version)

You can now also download a beta-version of RELION 2.0 by cloning the repository from bitbucket, using the command below:

git clone https://bitbucket.org/tcblab/relion2-beta.git

Relion-2 has an installation procedure which relies on cmake. Below describes the minimum process, but more information is given in our betaGuide. You will need to have this program installed, but most UNIX-systems have this by default. You will need to make a build-directory in which the code will be compiled. This can be placed inside the repository:

cd relion-2-beta
mkdir build
cd build

You then invoke cmake inside the build-directoy, but point to the source-directoy to configure the installation. This will not install relion, just configure the build:

cmake ..

The output of cmak will notify you of what was detected and what type of build will be installed. Because relion-2.0 is more rich in terms of the possible configurations, it is important to check this output. For instance;

• GPU-capability will only be included if a cuda-installation is detected. If not, the program will install, but without support for GPUs. Don't use CUDA-8.0 yet, we recommend CUDA-7.5.
• If FFTW is not detected, instructions are included to automatically download and install a FFTW-3.3.4 in a relion-specific manner. This behavior can also be forced according to instructions in the betaGuide.
• As above, regarding FLTK (required for GUI). If a GUI is not desired, this can be escaped as explained in the betaGuide.

Following the completion of cmake-configuration without errors, make is used to install the program

make -j <N>

Where N is the number of parallel threads to use during installation.

Set-up queue job submission

The GUI allows user to submit jobs to a job queueing system with a single click. For this to work, a template job submission script needs to be provided for the queueing system at hand (e.g. TORQUE, PBS, SGE). In this script a set of strings (variables) in the template script is replaced by the values given in the GUI. The following table contains all defined variables:

String	Variable type	Meaning
XXXcommandXXX	string	relion command + arguments
XXXqueueXXX	string	Name of the queue to submit job to
XXXmpinodesXXX	integer	The number of MPI processes to use
XXXthreadsXXX	integer	The number of threads to use on each MPI process
XXXcoresXXX	integer	The number of MPI processes times the number of threads
XXXdedicatedXXX	integer	NEW The minimum number of cores on each node (use this to fill entire nodes)
XXXnodesXXX	integer	The total number of nodes to be requested
XXXextra1XXX	string	Installation-specific, see below
XXXextra2XXX	string	Installation-specific, see below

There are two environment variables that control the use of the entry of the 'Minimum number of dedicated cores per node' on the Running tabs of the GUI: $RELION_MINIMUM_DEDICATED sets its default value (1 if not set); $RELION_ALLOW_CHANGE_MINIMUM_DEDICATED sets whether the user will be able to change this entry. At LMB, we set the default to 24 and do not allow users to change it. In this way, we enforce that our hyper-threaded 12-core nodes get filled up entirely by individual RELION jobs.

By default, the XXXextra1XXX and XXXextra2XXX variables are not used. They provide additional flexibility for queueing systems that require additional variables. They may be activated by setting the $RELION_QSUB_EXTRA1, and $RELION_QSUB_EXTRA2 environment variables, respectively. This will result in extra input fields in the GUI, with the label text being equal to the value of the environment variable. Likewise, their default values (upon starting the GUI) can be set through environment variables $RELION_QSUB_EXTRA1_DEFAULT and $RELION_QSUB_EXTRA2_DEFAULT, respectively. But note that (unlike all other entries in the GUI) the extra values are not remembered from one run to the other.

The template job submission script may be saved in any location. By default, the one used at the LMB is present as gui/qsub.csh in the relion tar-ball. Upon installation this file is copied to the bin directory. It is convenient for the user if he does not have to select this file each time he opens the RELION GUI in a new directory. Therefore, one may set the environment variable $RELION_QSUB_TEMPLATE to point to the location of the script for the system at hand. This value will be pre-set as default in the GUI. (Note the user still has the liberty to define and use his own template!)

IMPORTANT NOTE: If somehow the job queue submission cannot be set up, RELION may still be run in parallel and on a job queueing system. The GUI comprises a Print command button that prints the entire RELION command, including all arguments, to the screen. Pasting of this command to a job queue submission script, and manual submission of this script may then be used to submit the parallel job to a queueing system.

For illustrative purposes, have a look at the following examples:

• SGE template script example used at the LMB
• TORQUE template script example used at the CNB-CSIC
• manual machinefile script example used at Columbia (no queueing system involved)

Edit the environment set-up

For RELION-2.0, we source the following C-shell setup in our .cshrc file. You'll need to change all the paths for your own system, and translate the script in case you use a bash shell (which uses export instead of setenv, etc).

#!/bin/csh -f

# Setup openMPI if not already done so
if ("" == "`echo $path | grep /public/EM/OpenMPI/openmpi/bin`") then
        set path=(/public/EM/OpenMPI/openmpi/bin $path)
endif
if ("1" == "$?LD_LIBRARY_PATH") then
        if ("$LD_LIBRARY_PATH" !~ */public/EM/OpenMPI/openmpi/lib*) then
                setenv LD_LIBRARY_PATH /public/EM/OpenMPI/openmpi/lib:$LD_LIBRARY_PATH
        endif
else
        setenv LD_LIBRARY_PATH /public/EM/OpenMPI/openmpi/lib
endif

# Setup RELION-2.0 if not already done so
if ("" == "`echo $path | grep /public/EM/RELION/relion-2.0/bin`") then
	set path=(/public/EM/RELION/relion-2.0/bin $path)
endif 
if ("1" == "$?LD_LIBRARY_PATH") then
        if ("$LD_LIBRARY_PATH" !~ */public/EM/RELION/relion-2.0/lib*) then
                setenv LD_LIBRARY_PATH /public/EM/RELION/relion-2.0/lib:$LD_LIBRARY_PATH
        endif
else
        setenv LD_LIBRARY_PATH /public/EM/RELION/relion-2.0/lib
endif

# CUDA for RELION
setenv PATH /public/EM/CUDA/Cuda7.0/bin:$PATH
setenv LD_LIBRARY_PATH /public/EM/CUDA/Cuda7.0/lib64:$LD_LIBRARY_PATH
setenv CUDA_HOME /public/EM/CUDA/Cuda7.0

# Where is qsub template script stored
setenv RELION_QSUB_TEMPLATE /public/EM/RELION/relion-prerelease/bin/qsub.csh

# Default PDF viewer
setenv RELION_PDFVIEWER_EXECUTABLE evince

# Default MOTIONCORR executable
setenv RELION_MOTIONCORR_EXECUTABLE /public/EM/MOTIONCORR/bin/motioncorr

# Default UNBLUR/SUMMOVIE executables
setenv RELION_UNBLUR_EXECUTABLE /public/EM/UNBLUR/unblur.exe
setenv RELION_SUMMOVIE_EXECUTABLE /public/EM/SUMMOVIE/summovie.exe

# Default CTFFIND executable, version 4.0.x
setenv RELION_CTFFIND_EXECUTABLE '"/public/EM/ctffind/ctffind.exe --omp-num-threads 1 --old-school-input"'
# For CTFFIND3 this would be
#setenv RELION_CTFFIND_EXECUTABLE /public/EM/CTFFIND_130307/ctffind3.exe
# For the new CTFFIND 4.1+ this would be
#setenv RELION_CTFFIND_EXECUTABLE /lmb/home/scheres/app/Alexis_16-03-18_5138_ctffind_160404_1358.exe

# Default Gctf executable
setenv RELION_GCTF_EXECUTABLE /public/EM/Gctf/bin/Gctf

# Default ResMap executable
setenv RELION_RESMAP_EXECUTABLE /public/EM/ResMap/ResMap-1.1.4-linux64

# Enforce cluster jobs to occupy entire nodes with 24 hyperthreads
setenv RELION_MINIMUM_DEDICATED 24
# Do not allow the user to change the enforcement of entire nodes
setenv RELION_ALLOW_CHANGE_MINIMUM_DEDICATED 0

# Ask for confirmation if users try to submit local jobs with more than 12 MPI nodes
setenv RELION_WARNING_LOCAL_MPI 12