Skip to main content

​
Overview

HH-suite uses CMake as its build system and supports various architectures and SIMD instruction sets. This guide covers advanced compilation options for optimal performance.

​
Requirements

​
Compiler Requirements

GCC

Version 4.8 or later required

Clang

Version 3.6 or later supported

Intel ICC

Fully supported with optimizations

CMake

Version 2.8.12 or later required

​
System Requirements

  • 64-bit system (x86_64, ARM64, or PPC64LE)
  • At least SSE2 instruction set support (x86/x64)
  • OpenMP support (recommended for multi-threading)
  • MPI library (optional, for distributed computing)

​
Basic Compilation

The simplest way to compile HH-suite: 
git clone https://github.com/soedinglab/hh-suite.git
mkdir -p hh-suite/build && cd hh-suite/build
cmake -DCMAKE_INSTALL_PREFIX=. ..
make -j 4 && make install
export PATH="$(pwd)/bin:$(pwd)/scripts:$PATH"

​
CMake Build Options

​
SIMD Instruction Sets

HH-suite supports various SIMD instruction sets for performance optimization:
CMake Options
# Auto-detect (recommended)
cmake -DNATIVE_ARCH=1 ..

# Specific SIMD levels
cmake -DHAVE_SSE2=1 ..
cmake -DHAVE_SSE4_1=1 ..
cmake -DHAVE_AVX2=1 ..
AVX2 is approximately 2x faster than SSE2. Use -DHAVE_AVX2=1 if your CPU supports it.

​
Core Build Options

OptionDefaultDescription
CHECK_MPI1Enable MPI availability check
NATIVE_ARCH1Use native architecture for SIMD
EXE_SUFFIX""Optional executable suffix for SIMD builds
ENABLE_SANITIZERS0Enable memory/thread sanitizers (debug)
CMAKE_BUILD_TYPEReleaseBuild type (Release/Debug)

​
Example: Custom SIMD Build

Build for a specific architecture without native detection: 
mkdir build-avx2 && cd build-avx2
cmake -DNATIVE_ARCH=0 \
      -DHAVE_AVX2=1 \
      -DEXE_SUFFIX="_avx2" \
      -DCMAKE_INSTALL_PREFIX=. \
      ..
make -j 8 && make install
This creates executables like hhblits_avx2, hhsearch_avx2, etc.

​
OpenMP Support

OpenMP is automatically detected and enabled if available. It provides:
  • Multi-threaded profile alignment
  • Parallel database searches
  • Additional *_omp executables (hhblits_omp, hhsearch_omp, hhalign_omp, hhblits_ca3m)
cat /proc/cpuinfo | grep -i "cpu cores"
export OMP_NUM_THREADS=8

​
MPI Compilation

Only self-compiled versions include MPI support. Pre-built binaries do not have MPI.

​
Prerequisites

Install an MPI implementation: 
sudo apt-get install libopenmpi-dev openmpi-bin

​
Build with MPI

mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=. \
      -DCHECK_MPI=1 \
      ..
make -j 4 && make install
If MPI is found, this creates:
  • hhblits_mpi
  • hhsearch_mpi
  • hhalign_mpi
  • cstranslate_mpi

​
Running MPI Programs

Example: Distributed Search
mpirun -np 16 hhblits_mpi \
  -i query.a3m \
  -d /path/to/database \
  -o results.hhr \
  -n 3

​
Platform-Specific Notes

​
macOS Compilation

macOS default clang doesn’t support OpenMP. Install GCC via Homebrew.
# Install GCC with OpenMP support
brew install gcc

# Compile with GCC
CC="$(brew --prefix)/bin/gcc-13" \
CXX="$(brew --prefix)/bin/g++-13" \
cmake -DCMAKE_INSTALL_PREFIX=. ..

make -j 4 && make install

​
Static Builds

For portable binaries: 
cmake -DCMAKE_EXE_LINKER_FLAGS="-static" \
      -DCMAKE_FIND_LIBRARY_SUFFIXES=".a" \
      -DCMAKE_INSTALL_PREFIX=. \
      ..

​
Advanced Compiler Flags

​
Intel Compiler Optimizations

cmake -DCMAKE_C_COMPILER=icc \
      -DCMAKE_CXX_COMPILER=icpc \
      -DCMAKE_CXX_FLAGS="-fp-model precise -xHost" \
      ..
The -fp-model precise flag is automatically set for ICC to ensure consistent results.

​
Custom SIMD Flags

If auto-detection fails: 
cmake -DNATIVE_ARCH=0 \
      -DCMAKE_CXX_FLAGS="-march=skylake -mtune=skylake" \
      ..

​
Viterbi Algorithm Variants

HH-suite compiles multiple Viterbi algorithm variants for different scoring modes:
CMakeLists.txt (src/)
add_library(hhviterbialgorithm_with_celloff hhviterbialgorithm.cpp)
set_property(TARGET hhviterbialgorithm_with_celloff 
             PROPERTY COMPILE_FLAGS "-DVITERBI_CELLOFF=1")

add_library(hhviterbialgorithm_with_celloff_and_ss hhviterbialgorithm.cpp)
set_property(TARGET hhviterbialgorithm_with_celloff_and_ss 
             PROPERTY COMPILE_FLAGS "-DVITERBI_CELLOFF=1 -DVITERBI_SS_SCORE=1")
These variants optimize:
  • CELLOFF: Exclude regions from alignment
  • SS_SCORE: Include secondary structure scoring

​
Troubleshooting

Update GCC to version 4.8 or later:
gcc --version
sudo apt-get install gcc-9 g++-9
Your CPU is too old. Check SIMD support:
cat /proc/cpuinfo | grep -i sse2
Ensure MPI is in your PATH:
which mpicc
export PATH=/path/to/mpi/bin:$PATH
cmake -DCHECK_MPI=1 ..
Verify SIMD flags are applied:
# Check compilation flags
make VERBOSE=1 | grep march

# Verify AVX2 in binary
objdump -d bin/hhblits | grep vpmul

​
Verification

After compilation, verify the build: 
# Check version
./bin/hhblits -h | head -n 3

# Test basic functionality
./bin/hhblits -i test.fas -d database -o test.hhr -n 1

# Check OpenMP support
export OMP_NUM_THREADS=4
./bin/hhblits_omp -h

# Check MPI support (if compiled)
mpirun -np 2 ./bin/hhblits_mpi -h

​
Next Steps

Parameters

Learn about command-line parameters

Algorithms

Understand the underlying algorithms

Build docs developers (and LLMs) love

Get started for freeTalk to us