Download & install

Get RELION to run on your computer in 4 easy steps:

1. Download

Download RELION for free from here.

2. Install

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

tar -zxf relion-0.9.tar.gz cd relion-0.9

Standard instalation

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. Edit the PREFIX variable in the INSTALL.sh script to change this.

Building without FFTW

If FFTW (with thread-support!) is already present on your system (e.g. in /lmb/home/scheres/app/fftw-3.2.2/), you may want to set BUILD_FFTW=false and change this line in the INSTALL.sh script: ./configure prefix=$PREFIX --enable-mpi CPPFLAGS=-I$PREFIX/include LDFLAGS=-L$PREFIX/lib > $RELION_HOME/relion_build.log

by this one: ./configure prefix=$PREFIX --enable-mpi CPPFLAGS=-I/lmb/home/scheres/app/fftw-3.2.2/include LDFLAGS=-L/lmb/home/scheres/app/fftw-3.2.2/lib

and execute the INSTALL.sh script as above. Building without FLTK

If FLTK is already present on your system set BUILD_FLTK=false, make sure fltk-config is in your PATH and execute the INSTALL.sh script as above. 3. 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 nodes to use XXXthreadsXXX integer The number of threads to use on each node XXXcoresXXX integer The number of MPI nodes times the number of threads XXXextra1XXX string Installation-specific, see below XXXextra2XXX string Installation-specific, see below

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. Two examples

At the LMB we use the following default setup on our SGE queue. We do not use any of the extra options, and our qsub template script is:

1. !/bin/tcsh
2. $ -pe XXXqueueXXX XXXcoresXXX
3. $ -e XXXerrfileXXX
4. $ -o XXXoutfileXXX
5. $ -cwd
6. $ -S /bin/tcsh
7. Environment

source ~/.cshrc mpiexec --bynode -n XXXmpinodesXXX XXXcommandXXX echo "done"

At the CNB-CSIC in Madrid, they use a TORQUE queue, which requires a maximum wall-clock-time. This requires a setup that makes use of the XXXextra1XXX variable. In their environment, one sets $RELION_QSUB_EXTRA1="Max number of hours in queue" and $RELION_QSUB_EXTRA1_DEFAULT="72", and uses the following template script:

1. !/bin/bash
   1. 1. Inherit all current environment variables
2. PBS -V
   1. 1. Job name
3. PBS -N relion
   1. 1. Output and Error
4. PBS -e XXXerrfileXXX
5. PBS -o XXXoutfileXXX
   1. 1. Queue name
6. PBS -q XXXqueueXXX
   1. 1. Specify the number of nodes and thread (ppn) for your job.
7. PBS -l nodes=XXXmpinodesXXX:ppn=XXXthreadsXXX
   1. 1. Tell PBS the anticipated run-time for your job, where walltime=HH:MM:SS
      2. PBS -l walltime=XXXextra1XXX:00:00
      3. Switch to the working directory;

cd $PBS_O_WORKDIR echo Working directory is $PBS_O_WORKDIR

1. Calculate the number of processors allocated to this run.

NPROCS=`wc -l < $PBS_NODEFILE`

1. Calculate the number of nodes allocated.

NNODES=`uniq $PBS_NODEFILE | wc -l`

1. 1. 1. Display the job context

echo Running on host `hostname` echo Time is `date` echo Directory is `pwd` echo Using ${NPROCS} processors across ${NNODES} nodes

mpirun --bynode -np XXXmpinodesXXX XXXcommandXXX echo "done" 4. Edit the environment set-up

The following assumes the program was built in /lmb/home/scheres/app/relion-0.9/; the template script for the queueing system is located in /lmb/home/scheres/app/relion-0.9/bin/qsub.csh; and no extra variables are required in this template script.

For csh or tcsh, add the following lines to your ~/.cshrc: setenv LD_LIBRARY_PATH /lmb/home/scheres/app/relion-0.9/lib:$LD_LIBRARY_PATH setenv PATH /lmb/home/scheres/app/relion-0.9/bin:$PATH setenv RELION_QSUB_TEMPLATE "/lmb/home/scheres/app/relion-0.9/bin/qsub.csh"

For bash, add the following lines to your ~/.bashrc: export LD_LIBRARY_PATH=/lmb/home/scheres/app/relion-0.9/lib:$LD_LIBRARY_PATH export PATH=/lmb/home/scheres/app/relion-0.9/bin:$PATH export RELION_QSUB_TEMPLATE="/lmb/home/scheres/app/relion-0.9/bin/qsub.csh"