Installation and configuration (using OpenMP)

Source: vignettes/Installation_and_configuration.Rmd

Currently, the develop version can be installed using the command.

remotes::install_github("davidbolin/ngme2", ref = "devel")

Mac OS X

For Mac OS X system, the default C++ compiler in OS X has does not support OpenMP.

➜ clang -fopenmp hello.cpp
clang: error: unsupported option '-fopenmp'

In order to make use of OpenMP to enable multi-threading in OS X, we need to use compilers which supports OpneMP.

The macOS default Apple Clang compiler doesn’t support OpenMP. To enable OpenMP functionality in packages like ngme2, we need to:

  1. Install LLVM/Clang compiler with OpenMP support via Homebrew:
brew install llvm libomp
  1. Create the ~/.R directory if it doesn’t exist already:
mkdir -p ~/.R
  1. Add the following configuration to ~/.R/Makevars:
# Use Homebrew LLVM's clang compiler (supports OpenMP)
CC=/opt/homebrew/opt/llvm/bin/clang
CXX=/opt/homebrew/opt/llvm/bin/clang++
CXX11=/opt/homebrew/opt/llvm/bin/clang++
CXX14=/opt/homebrew/opt/llvm/bin/clang++
CXX17=/opt/homebrew/opt/llvm/bin/clang++
CXX20=/opt/homebrew/opt/llvm/bin/clang++

# Add OpenMP flags
SHLIB_OPENMP_CFLAGS = -fopenmp
SHLIB_OPENMP_CXXFLAGS = -fopenmp
SHLIB_OPENMP_FFLAGS = -fopenmp

# Include and library paths for LLVM and OpenMP
CFLAGS += -I/opt/homebrew/opt/llvm/include
CXXFLAGS += -I/opt/homebrew/opt/llvm/include
LDFLAGS += -L/opt/homebrew/opt/llvm/lib -L/opt/homebrew/opt/llvm/lib/c++ -Wl,-rpath,/opt/homebrew/opt/llvm/lib/c++

After making these changes, reinstall the ngme2 package to take advantage of the OpenMP functionality for parallel processing.

remotes::install_github("davidbolin/ngme2", ref = "devel")

Linux

Most Linux distributions come with GCC/G++ compilers that already support OpenMP. If not, you can install the development tools package for your distribution.

1. Install required dependencies

For Debian/Ubuntu-based systems:

sudo apt-get update
sudo apt-get install r-base-dev build-essential libopenblas-dev liblapack-dev gfortran

For Red Hat/Fedora-based systems:

sudo dnf install R-devel gcc-c++ openblas-devel lapack-devel gcc-gfortran

2. Verify OpenMP support

Check if your GCC compiler supports OpenMP:

gcc --version
echo "#include <omp.h>
#include <stdio.h>
int main() {
  #pragma omp parallel
  {
    printf(\"Hello from thread %d\\n\", omp_get_thread_num());
  }
  return 0;
}" > test_omp.c

gcc -fopenmp test_omp.c -o test_omp
./test_omp

3. Configure OpenMP for R (optional)

If you want to customize the OpenMP settings, you can create a ~/.R/Makevars file:

mkdir -p ~/.R
cat > ~/.R/Makevars << EOF
# Use all available cores by default
# Adjust the number as needed for your system
OMP_NUM_THREADS=4

# OpenMP flags
SHLIB_OPENMP_CFLAGS = -fopenmp
SHLIB_OPENMP_CXXFLAGS = -fopenmp
SHLIB_OPENMP_FFLAGS = -fopenmp
EOF

4. Install ngme2 

# From within R
install.packages("remotes")
remotes::install_github("davidbolin/ngme2", ref = "devel")

Windows

Windows installation is generally simpler as the standard R tools for Windows already include appropriate C++ compilers with OpenMP support.

1. Install Rtools

Download and install the version of Rtools that corresponds to your R version from: https://cran.r-project.org/bin/windows/Rtools/

For R 4.0.0 and newer, use Rtools40 or newer.

During installation: - Make sure to select the option to add Rtools to your system PATH - Install the toolchain components

2. Verify installation

From your R console, check if Rtools is properly installed:

Sys.which("make")
# Should return the path to the make executable

3. Install ngme2 

# From within R
install.packages("remotes")
remotes::install_github("davidbolin/ngme2", ref = "devel")

4. Configure OpenMP settings (optional)

If you need to customize the OpenMP behavior, you can create a .Renviron file in your user directory:

# Open R and run:
file.edit("~/.Renviron")

# Add the following line to control the number of OpenMP threads:
OMP_NUM_THREADS=4

This will limit OpenMP to using 4 threads. Adjust the number according to your system’s capabilities.

Verifying OpenMP installation

To verify that OpenMP is working correctly with ngme2, you can run a simple test:

library(ngme2)

# Check OpenMP capabilities
cat("OpenMP threads available:", ngme2:::openmp_test(), "\n")

# If the function returns a number greater than 1, OpenMP is working

Troubleshooting

Common issues on macOS:

  • “Unsupported option ‘-fopenmp’” error: This indicates the Apple Clang compiler is being used instead of LLVM Clang. Double-check your ~/.R/Makevars configuration.
  • “Library not loaded: libiomp5.dylib” error: The OpenMP runtime libraries aren’t in the system path. Make sure to include the correct library paths in LDFLAGS.

Common issues on Linux:

  • Missing compiler: Install the development tools package for your distribution.
  • Missing BLAS/LAPACK: Install the appropriate numerical libraries for your distribution.

Common issues on Windows:

  • “Rtools not found”: Make sure Rtools is installed and added to your system PATH.
  • Compilation errors: Make sure you’re using the correct version of Rtools for your R version.