Ubuntu에서 RELION 설치 및 튜토리얼 데이터 실행하기

이전 글에서는 단일 GPU 기반의 워크스테이션에서 CryoSPARC와 RELION을 함께 운용하기 위한 기본 환경을 구성하였습니다.
이번 글에서는 RELION 설치와 테스트, 특히 Miniforge 환경 설정, 소스코드 빌드, 그리고 튜토리얼 데이터 실행 과정을 실제 순서에 맞게 자세히 다루겠습니다.

이 글의 설치 과정은 실제 워크스테이션에서 수행한 기록을 기반으로 하였으며,
RELION 공식 문서와
K.B. Wong의 GPU 워크스테이션 구축 경험기를 함께 참고하였습니다.

1. 필수 패키지 확인

RELION을 빌드하기 전, 필요한 시스템 패키지가 모두 설치되어 있는지 확인하는 것이 중요합니다.
아래는 이를 자동으로 점검하기 위해 작성한 간단한 bash 스크립트입니다.

#!/bin/bash

packages=(
    "build-essential"
    "cmake"
    "gfortran"
    "libgtk-3-dev"
    "libfftw3-dev"
    "libgsl-dev"
    "libjpeg-dev"
    "libpng-dev"
    "libtiff-dev"
    "python3"
    "python3-pip"
)

for package in "${packages[@]}"; do
    if dpkg -s "$package" > /dev/null 2>&1; then
        echo "$package is installed."
    else
        echo "$package is NOT installed."
    fi
done

python_packages=("numpy" "scipy" "matplotlib")
for pkg in "${python_packages[@]}"; do
    if python3 -c "try: import $pkg; print('Installed') except ImportError: print('Not Installed')" | grep -q "Installed"; then
        echo "python3-$pkg is installed."
    else
        echo "python3-$pkg is NOT installed."
    fi
done

if cmake --version > /dev/null 2>&1; then
    echo "cmake version:" $(cmake --version | head -n 1)
else
    echo "cmake is NOT installed."
fi

if gfortran --version > /dev/null 2>&1; then
    echo "gfortran version:" $(gfortran --version | head -n 1)
else
    echo "gfortran is NOT installed."
fi

if pip3 --version > /dev/null 2>&1; then
    echo "pip3 version:" $(pip3 --version | head -n 1)
else
    echo "pip3 is NOT installed."
fi

모든 패키지가 정상적으로 설치되어 있다면, CMake, GCC, Python3의 버전이 출력됩니다.

2. Miniforge 설치

RELION은 PyTorch 기반의 Blush Regularisation 기능을 포함하고 있어 Python 환경을 별도로 관리하는 것이 가장 안정적입니다.

이를 위해 Miniforge를 먼저 설치합니다.

cd ~
curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh
source ~/.bashrc

Miniforge는 Conda와 동일한 기능을 제공하며, PyTorch 등 과학 계산용 패키지를 쉽게 설치할 수 있습니다.

이 단계에서는 아직 RELION 소스코드를 내려받지 않았기 때문에 환경 생성은 뒤에서 수행합니다.

3. RELION 소스코드 다운로드

이제 RELION을 GitHub에서 내려받습니다. 여기서는 RELION 5.0 버전을 기준으로 진행하였습니다.

cd ~
git clone https://github.com/3dem/relion.git
cd relion
git checkout ver5.0
git pull

RELION 폴더 안에는 environment.yml 파일이 포함되어 있으며, 이 파일을 이용해 Conda 환경을 설정할 수 있습니다.

4. Conda 환경 생성 및 활성화

RELION 폴더 내부에서 Conda 환경을 생성합니다. 이 과정을 통해 RELION 구동에 필요한 Python 및 PyTorch 관련 패키지들이 설치됩니다.

conda env create -f environment.yml
conda activate relion

이 환경을 활성화한 상태에서 빌드를 진행하면, CMake가 Conda 환경의 Python과 Torch 경로를 자동으로 인식합니다.

5. RELION 빌드 및 설치

이제 RELION을 빌드합니다. 활성화된 Conda 환경에서 빌드해야 CMake가 올바른 Python/Torch 라이브러리를 인식합니다.

cd ~/relion
mkdir build
cd build

아래는 실제 빌드에 사용한 설정 예시입니다. MotionCor2, CTFFIND4, MPI 경로는 각자의 환경에 맞게 수정하셔야 합니다.

cmake .. \
    -DCMAKE_INSTALL_PREFIX=$HOME/relion5 \
    -DMOTIONCOR2_EXECUTABLE=/opt/MotionCor2/MotionCor2 \
    -DMPI_C_COMPILER=/usr/bin/mpicc \
    -DCTFFIND4_EXECUTABLE=/usr/local/bin/ctffind \
    -DFETCH_WEIGHTS=OFF \
    -DCUDA_ARCH=89 \
    -DTORCH_HOME_PATH=$HOME/torch \
    -DFORCE_OWN_FLTK=OFF

💡 참고: CUDA_ARCH=89는 RTX 4090과 같은 Ada Lovelace 아키텍처를 의미합니다. 자신의 GPU에 맞게 코드 값을 변경하셔야 합니다.

이후 컴파일 및 설치를 진행합니다.

make -j$(nproc)
make install

설치가 완료되면, 환경 변수에 RELION 실행 경로를 추가합니다.

echo 'export PATH="$HOME/relion5/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

6. CUDA 및 라이브러리 경로 설정

시스템에 CUDA 라이브러리가 전역으로 설정되어 있지 않다면, .bashrc에 다음 내용을 추가합니다.

export PATH=/usr/local/cuda-12.9/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-12.9/lib64:$LD_LIBRARY_PATH
source ~/.bashrc

이 설정을 통해 CMake 및 RELION이 CUDA 관련 바이너리를 올바르게 인식할 수 있습니다.

7. 튜토리얼 데이터로 테스트

설치가 완료되면, RELION이 정상적으로 동작하는지 튜토리얼 데이터셋으로 검증합니다.

wget ftp://ftp.mrc-lmb.cam.ac.uk/pub/scheres/relion30_tutorial_data.tar
tar -xf relion30_tutorial_data.tar

이 데이터는 JEOL Cryo-ARM (200 kV) 장비에서 수집된 것으로, 다음과 같은 파라미터를 가집니다.

픽셀 크기: 0.885 Å/pixel
가속 전압: 200 kV
구면 수차: 1.4 mm
프레임당 전자선량: 1.277 e⁻ / Å² / frame
제공: 타카유키 카토(Takayuki Kato), 남바 연구그룹(오사카대학)

CTF 계산에는 다음 경로의 CTFFIND4를 사용하였습니다.

/usr/local/bin/ctffind

8. Blush Regularisation 테스트

RELION 5에서는 Blush Regularisation 기능이 추가되어 3D 분류 과정의 안정성과 정확도를 향상시킬 수 있습니다.

관련 모델 가중치는 아래 디렉토리에 저장됩니다.

mkdir -p ~/torch/hub/checkpoints/relion_blush

튜토리얼 데이터를 이용해 3D Classification을 실행하면, RELION이 CUDA 및 PyTorch를 모두 올바르게 인식하는지 확인할 수 있습니다.

9. 성능 및 안정성 관련 메모

단일 GPU 환경에서도 RELION 5는 중소형 데이터셋을 처리하는 데 충분히 안정적입니다. 재구성 및 CTF 계산 시 CPU 활용률도 효율적이며, GPU 메모리는 대체로 8~10 GB 정도를 사용합니다.

만약 메모리 부족 오류가 발생한다면, 다음 환경 변수를 지정한 뒤 실행하는 것이 도움이 됩니다.

export OMP_NUM_THREADS=4
export RELION_ALLOC_DEBUG=1

또한 CUDA와 NVIDIA 드라이버의 버전을 고정해 두면 세그멘테이션 오류(segmentation fault)를 예방할 수 있습니다.

10. 정리 및 다음 단계

소스코드로 RELION을 직접 빌드하는 과정은 단순한 설치 이상의 의미를 가집니다. CUDA, MPI, Python 환경의 상호 의존성을 이해함으로써 자신의 워크스테이션을 연구 목적에 맞게 최적화할 수 있습니다.

RELION 빌드와 튜토리얼 데이터 테스트가 성공적으로 완료되면, 이제 이 워크스테이션은 단일입자 분석(SPA) 전체 워크플로우를 수행할 수 있는 상태가 됩니다.

다음 글에서는 튜토리얼 데이터셋을 활용하여 실제 2D 분류, 3D 재구성, 분해능 평가 과정을 단계별로 분석해볼 예정입니다. 이제 본격적인 데이터 처리의 시작입니다.

1. 필수 패키지 확인#

2. Miniforge 설치#

3. RELION 소스코드 다운로드#

4. Conda 환경 생성 및 활성화#

5. RELION 빌드 및 설치#

6. CUDA 및 라이브러리 경로 설정#

7. 튜토리얼 데이터로 테스트#

8. Blush Regularisation 테스트#

9. 성능 및 안정성 관련 메모#

10. 정리 및 다음 단계#