Download & install
Get RELION to run on your computer in a few easy steps. Note that RELION is distributed under a GPLv2 license, i.e. it is completely free, open-source software for both academia and industry.
- 1 Download & install RELION
- 1.1 Getting the source code
- 1.2 Updating source code
- 1.3 Installing from source code
- 1.4 Installation configurations from source code
- 1.5 Installation using apt-get
- 2 Set-up queue job submission
- 3 Edit the environment set-up
Download & install RELION
Getting the source code
We store the public release versions of RELION on github, a site that provides code-development with version control and issue tracking through the use of git. We will not describe the use of git in general, as you will not need more than very basic features. Below we outline the few commands needed on a UNIX-system, please refer to general git descriptions and tutorials to suit your system. To get the code, you clone or download the repository. We recommend cloning, because it allows you very easily update the code when new versions are released. To do so, use the shell command-line
git clone https://github.com/3dem/relion.git
This will create a local git repository. All subsequent git-commands should be run inside this directory.
Updating source code
The code will be intermittently updated to amend minor issues detected during beta-development. To incorporate these changes, use the command-line
inside you local repository (the source-code directory downloaded). If you have changed the code in some way, this will force you to commit a local merge. You are free to do so, but we will assume you have not changed the code. Refer to external instructions regarding git and merging so-called conflicts if you have changed the code an need to keep those changes.
Installing from source code
RELION-2 has an installation procedure which relies on cmake. 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 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:
The output will notify you of what was detected and what type of build will be installed. Because RELION is 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
- If FFTW is not detected, instructions are included to download and install it in a local directory known to the RELION installation.
- As above, regarding FLTK (required for GUI). If a GUI is not desired, this can be escaped as explained in the following section.
Following the completion of cmake-configuration without errors,
make is used to install the program:
make -j <N>
Where N is the number of processes to use during installation. Using a higher number simply means that it will install faster. Take note of any warnings or errors reported. RELION will be installed in the build directory sub-folder bin, and using additional, native cmake-features this can be easily extended to making the installation system-wide (see below details regarding installation location).
Installation configurations from source code
Cmake allows configuration of many aspects of the installation, some of which are outlined here. We recommend to read up on the use of ccmake (note the extra ’c’) if one wants to examine many different configurations and options, as this greatly eases reconfiguration. Most options can be set by adding options to the cmake configuration. Under the below subheadings, some example replacement commands are given to substitute the original configuration command. It is also recommended to clean or purge you build-directory between builds:
cd build rm -r *
And of course, any of the below options can be combined.
Omitting the GUI
cmake -DGUI=OFF ..
Using double-precision on the GPU
Unless you have professional GPUs, this will slow down GPU-execution considerably.
cmake -DDoublePrec_GPU=ON ..
Compiling GPU-code for your architecture
CUDA-capable devices have a so-called compute-version, which code can be compiled against for optimal performance. If you know the compute-verison of your GPUs, you can specify it. The default value is 3.5 (sm 35), which is the lowest supported by RELION
cmake -DCUDA_ARCH=52 ..
Forcing build and use of local fftw and fltk-libs
This will add download, verification and installation of FFTW and/or FLTK during the installation process. If any of these are not detected during configuration, this will happen automatically anyway, and you should not have to specify the below options manually.
cmake -DFORCE_OWN_FFTW=ON .. cmake -DFORCE_OWN_FLTK=ON ..
Specifying an installation location
To allow RELION a system-wide installation use
cmake -DCMAKE_INSTALL_PREFIX=/path/to/install/dir/ ..
make -j <N>
as before, and then further
Installation using apt-get
The binary repository below distributes old 2.0.6 binaries with the gold-standard refinement bug. It is also incompatible with Ubuntu 17.04 as reported in GitHub. Until we update the repository, users are encouraged to build RELION from source as described above.
Using the installation program apt on e.g. ubuntu, you can also make a system-installation of RELION with a few short commands;
sudo sh -c 'sudo echo "deb http://developer.download.nvidia.com/compute/cuda/repos/ubuntu1604/x86_64 /" > /etc/apt/sources.list.d/cuda.list' sudo sh -c 'sudo echo "deb http://packages.cryoem.se/ubuntu/xenial xenial main" > /etc/apt/sources.list.d/relion.list' sudo apt-get update sudo apt-get install region
If you have CUDA already installed, this will install RELION with support for GPUs. If you do not have CUDA, RELION will still install, but without GPU-support. If you don not have CUDA but wish to have GPU-support, you can install CUDA along with RELION by instead using as the final command:
sudo apt-get install relion-cuda
Set-up queue job submission
The GUI allows the 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:
|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, 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 if not already done so if ("" == "`echo $path | grep /public/EM/RELION/relion/bin`") then set path=(/public/EM/RELION/relion/bin $path) endif if ("1" == "$?LD_LIBRARY_PATH") then if ("$LD_LIBRARY_PATH" !~ */public/EM/RELION/relion/lib*) then setenv LD_LIBRARY_PATH /public/EM/RELION/relion/lib:$LD_LIBRARY_PATH endif else setenv LD_LIBRARY_PATH /public/EM/RELION/relion/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 MOTIONCOR2 executable setenv RELION_MOTIONCOR2_EXECUTABLE /public/EM/MOTIONCOR2/bin/MotionCor2_1.0.4 # 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