Installation and configuration (using OpenMP)

Installation Options

There are currently two ways to install the ngme2 package:

1. Pre-built Binaries (Easy and Recommended)
2. Installing from Source (Advanced)

1. Installing Pre-built Binaries (Recommended)

Pre-built binaries are available for Windows and macOS with R versions 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/")

The update of the installed package can be done using the ngme_update function.

# Update ngme2 package
ngme_update()

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 the multiple-chain estimation functionality 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

2. Create the ~/.R directory if it doesn’t exist already:

mkdir -p ~/.R

3. 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.

4. 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
openmp_test()

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.