Installation and configuration (using OpenMP)

Source: vignettes/Installation_and_configuration.Rmd

Installation Options

There are two ways to install the ngme2 package:

Pre-built binaries are available for Windows and macOS with R versions 4.2, 4.3, 4.4, and 4.5. This is the recommended installation method as it avoids compilation issues, especially on macOS where OpenMP configuration can be challenging.

# Install ngme2 package from pre-built binaries
install.packages("ngme2", 
                 repos = "https://davidbolin.github.io/ngme2/.binaries",
                 type = "binary")

The installation process will automatically detect your R version and operating system, and install the appropriate binary package.

You can also use this convenience function to handle the installation:

# Function to install the appropriate ngme2 binary
install_ngme2 <- function() {
  # Detect R version
  r_version <- paste(R.version$major, strsplit(R.version$minor, ".", fixed=TRUE)[[1]][1], sep=".")
  
  # Detect system
  system_type <- Sys.info()["sysname"]
  
  # Check if the detected R version is supported
  supported_versions <- c("4.2", "4.3", "4.4", "4.5")
  if(!r_version %in% supported_versions) {
    warning("Your R version (", r_version, ") may not have a pre-built binary. ",
            "Trying the closest version or falling back to source installation.")
    # Find the closest version
    r_num <- as.numeric(r_version)
    closest_version <- supported_versions[which.min(abs(as.numeric(supported_versions) - r_num))]
    r_version <- closest_version
  }
  
  message("Installing ngme2 for R ", r_version, " from repository")
  
  # Install the package
  install.packages("ngme2", 
                  repos = "https://davidbolin.github.io/ngme2/.binaries", 
                  type = "binary")
}

# Run the function to install
install_ngme2()

2. Installing from Source

If you prefer to install from source, or if pre-built binaries are not available for your platform or R version, you can install directly from GitHub:

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

Note: Installing from source requires appropriate C++ compilers and OpenMP support. This can be complex, particularly on macOS. See the platform-specific instructions below if you encounter issues.

Platform-Specific Configuration for Source Installation

If you need to install from source, follow these platform-specific instructions:

Mac OS X

For Mac OS X, the default C++ compiler does not support OpenMP, which is required for multi-threading in ngme2.

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

To enable OpenMP on macOS:

  1. Important Note: There seems to be an incompatibility between R’s internal OpenMP dylib and newer versions of LLVM. You should specifically install LLVM version 18 to avoid issues:
brew install llvm@18 libomp
  1. Create the ~/.R directory if it doesn’t exist already:
mkdir -p ~/.R
  1. Add the following configuration to ~/.R/Makevars (use this exact configuration):
# Use Homebrew LLVM's clang compiler (supports OpenMP)
CC=/opt/homebrew/opt/llvm@18/bin/clang
CXX=/opt/homebrew/opt/llvm@18/bin/clang++
CXX11=/opt/homebrew/opt/llvm@18/bin/clang++
CXX14=/opt/homebrew/opt/llvm@18/bin/clang++
CXX17=/opt/homebrew/opt/llvm@18/bin/clang++ 
CXX20=/opt/homebrew/opt/llvm@18/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@18/include -I/opt/homebrew/opt/libomp/include
CXXFLAGS += -I/opt/homebrew/opt/llvm@18/include -I/opt/homebrew/opt/libomp/include
LDFLAGS += -L/opt/homebrew/opt/llvm@18/lib -L/opt/homebrew/opt/llvm@18/lib/c++ -Wl,-rpath,/opt/homebrew/opt/llvm@18/lib/c++ -L/opt/homebrew/opt/libomp/lib

FLIBS = -L/opt/homebrew/lib/gcc/current -lgfortran -lquadmath

Note: - The paths shown are for Apple Silicon Macs (M1/M2/M3). If you’re using an Intel Mac, replace /opt/homebrew/ with /usr/local/. - It’s critical to use LLVM version 18 specifically due to compatibility issues with R’s OpenMP implementation and newer LLVM versions.

  1. After configuring the compiler, install from GitHub:
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. Install ngme2 

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

Windows

Windows installation from source 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. Install ngme2 

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

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.