Skip to content
/ relion Public

Image-processing software for cryo-electron microscopy

License

GPL-2.0, GPL-2.0 licenses found

Licenses found

GPL-2.0
LICENSE
GPL-2.0
COPYING
Notifications You must be signed in to change notification settings

3dem/relion

Folders and files

NameName
Last commit message
Last commit date

Latest commit

051a654 · Oct 20, 2023
Sep 9, 2022
Aug 23, 2023
Feb 1, 2021
Nov 19, 2020
Sep 27, 2023
Oct 17, 2023
Nov 12, 2022
Feb 24, 2021
Jul 20, 2022
Oct 18, 2023
Jun 17, 2016
Sep 16, 2021
Oct 20, 2023
Oct 17, 2023
Sep 26, 2023
May 9, 2023
Jun 17, 2016
May 9, 2023

Repository files navigation

RELION 5.0-alpha

RELION (for REgularised LIkelihood OptimisatioN) is a stand-alone computer program for Maximum A Posteriori refinement of (multiple) 3D reconstructions or 2D class averages in cryo-electron microscopy. It is developed in the research group of Sjors Scheres at the MRC Laboratory of Molecular Biology.

If RELION is useful in your work, please cite our papers.

The more comprehensive documentation of RELION is stored here.

Installation

More extensive options and configurations are available here, but the outlines to clone and install RELION for typical use are made easy through cmake.

On Debian or Ubuntu machines, installing cmake, the compiler, and additional dependencies (mpi, fftw) is as easy as:

sudo apt install cmake git build-essential mpi-default-bin mpi-default-dev libfftw3-dev libtiff-dev libpng-dev ghostscript libxft-dev

RedHat-like systems (CentOS, RHEL, Scientific Linux etc) use yum package manager:

sudo yum install cmake git gcc gcc-c++ openmpi-devel fftw-devel libtiff-devel libpng-devel ghostscript libXft-devel libX11-devel

Now download RELION and checkout the verison you want, by running:

git clone https://github.com/3dem/relion.git
cd relion
git checkout master # or ver5.0; see below

To add support for Python modules (e.g. Blush, ModelAngelo and DynaMight) you will have to install a Python environment. We recommend installing miniconda3. You can find that here: miniconda

Once you have Conda setup, you can install all the RELION Python dependencies into a new environment by running: conda env create -f environment.yml

Using a Custom Conda/Python Environment with RELION (Advanced) To enforce RELION to utilize a particular Python interpreter, incorporate the following flag during the cmake call:

-DPYTHON_EXE_PATH=path/to/python

Additionally, if you intend to make use of automatically downloaded pretrained model weights (used in e.g. Blush, ModelAngelo and Classranker), it's recommended to set the TORCH_HOME directory. To do this, include the following flag:

-DTORCH_HOME_PATH=path/to/torch/home

Before installing RELION make sure Conda is not active. If it is, you can deactivate it by running: conda deactivate

You can now build RELION through:

mkdir build
cd build
cmake ..
make

By performing git checkout ver5.0 instead of git checkout master, you can access the latest (developmental) updates for RELION 5.0.x. The code there is not tested as throughfully as that in the master branch and not generally recommended.

The binaries will be produced in the build/bin directory. If you want to copy binaries into somewhere else, run cmake with -DCMAKE_INSTALL_PREFIX=/where/to/install/ and perform make install as the final step. Do not specify the build directory itself as CMAKE_INSTALL_PREFIX! This will not work.

Also note that the MPI library used for compilation must be the one you intend to use RELION with. Compiling RELION with one version of MPI and running the resulting binary with mpirun from another version can cause crash. See our wiki below for details.

In any case, you have to make sure your PATH environmental variable points to the directory containing RELION binaries. Launching RELION as /path/to/relion is NOT a right way; this starts the right GUI, but the GUI might invoke other versions of RELION in the PATH.

If FLTK related errors are reported, please add -DFORCE_OWN_FLTK=ON to cmake. For FFTW related errors, try -DFORCE_OWN_FFTW=ON.

RELION also requires libtiff. Most Linux distributions have packages like libtiff-dev or libtiff-devel. Note that you need a developer package. You need version 4.0.x to read BigTIFF files. If you installed libtiff in a non-standard location, specify the location by -DTIFF_INCLUDE_DIR=/path/to/include -DTIFF_LIBRARY=/path/to/libtiff.so.5.

Building with HIP

Currently the AMD GPU ROCm port and HIP optimisation of RELION are housed in an internal repo. Once the pre-requistes are loaded (follow the steps in previous sections), the configuration with HIP can be easily done through:

git clone [email protected]:AMD-HPC/RELION.git relion
cd relion
git checkout suyash/ver4.0-hip
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=/where/to/install/ \
      -DCMAKE_BUILD_TYPE=release   \
      -DHIP=on -DHIP_ARCH="gfx90a" \
      -DGUI=off                    \
      -DTIFF_INCLUDE_DIR=/path/to/include  \
      -DTIFF_LIBRARY=/path/to/libtiff.so.5 \
      -DAMDFFTW=on .. # only on AMD systems to build an optimized version of FFTW lib
make -j

Building with SYCL

For detailed information on RELION build with SYCL support, please read README_sycl file.

Updating

RELION is intermittently updated, with both minor and major features. To update an existing installation, simply use the following commands

cd relion
git pull
cd build
make
make install # Only when you have specified CMAKE_INSTALL_PREFIX in the cmake step

If something went wrong, remove the build directory and try again from cmake.

Class Ranker

The default model for the class ranker has been trained and tested in Python 3.9.12 with Pytorch 1.10.0 and Numpy 1.20.0. If you wish to retrain the class ranker model with your own data, please refer to this repo.