Chapter 01: Setting Up OpenCL and Enabling GPU Acceleration

Overview

nmathopencl can run in two modes:

• CPU-only mode: all distribution functions fall back to stats:: or base-R equivalents. No special setup is needed. This is the default when the package is installed from a prebuilt binary (e.g., from CRAN or R-universe). Most downstream use of the nmath .cl library does not require a GPU-enabled build of nmathopencl itself; the .cl source files are always present on disk regardless.
• GPU-accelerated mode: kernels execute on an OpenCL device. This requires compiling the package from source on a machine with an OpenCL SDK installed. It is necessary when you want to use the exported *_opencl wrappers to validate GPU pipeline operation, or when your downstream package links directly against the nmathopencl kernel runners.

This vignette describes how to read the attach-time advisory, understand the opencltools dependency, and enable OpenCL specifically for nmathopencl. Detailed per-OS driver, header, and ICD instructions are maintained in opencltools vignette Chapter 01; end-user GPU setup notes also appear in Chapter 02.

When you load nmathopencl

Attaching the package in an interactive session may print a short packageStartupMessage. This is intentional: it gives a first-pass diagnosis of whether GPU acceleration is feasible on your machine and whether this install was compiled with OpenCL support.

CPU execution is always available. The message appears only when there is a plausible GPU/OpenCL path that is not yet enabled in the installed binaries, or when the host stack looks incomplete. When both nmathopencl and opencltools were built with OpenCL, attach is silent.

To suppress the message in scripts or CI:

options(nmathopencl.quiet_opencl_startup = TRUE)

Further detail: ?gpu_diagnostics, ?nmathopencl-package, this vignette, and vignette("Chapter-12", package = "nmathopencl").

opencltools as imported dependency

nmathopencl lists opencltools in Imports (>= 0.8.0). It is installed automatically with nmathopencl and provides two categories of functionality:

• Host/runtime diagnostics — GPU vendor detection, driver and ICD checks, verify_opencl_runtime(), and related probes. These are not re-exported; call opencltools::… directly.
• Kernel-library authoring tools — dependency tagging, sorting, and subset loading (load_library_for_kernel, extract_library_subset, …). These are re-exported from nmathopencl for downstream kernel authors.

Work through opencltools first when enabling OpenCL: fix the host environment and confirm opencltools::has_opencl() before reinstalling nmathopencl from source. Useful opencltools vignettes:

What “compiling with OpenCL” means

At compile time, each package’s configure script detects whether CL/cl.h is present and a linkable OpenCL library exists. If both are found, it sets -DUSE_OPENCL and links against -lOpenCL. All OpenCL-specific C++ code is guarded by #ifdef USE_OPENCL, so the package compiles cleanly without OpenCL headers.

A binary built without USE_OPENCL is a fully valid CPU-only package. nmathopencl_has_opencl() returns FALSE and every *_opencl wrapper silently uses its stats:: fallback.

Because nmathopencl Imports opencltools, both packages must be built with OpenCL for the exported *_opencl wrappers to dispatch to a GPU. The attach message compares nmathopencl_has_opencl() (nmathopencl) and opencltools::has_opencl() (opencltools) and tells you which reinstall is needed.

Enabling OpenCL for nmathopencl

Work through these steps in order.

library(nmathopencl)

opencltools::has_opencl()   # opencltools build flag
nmathopencl_has_opencl()                # nmathopencl build flag
opencltools::diagnose_glmbayes()   # host/runtime report
nmathopencl_has_opencl()           # nmathopencl compile-time flag

# From CRAN or R-universe:
install.packages("nmathopencl", type = "source")

nmathopencl_has_opencl()
#> [1] TRUE

Verifying the setup

After Steps 2–3, confirm the full stack:

library(nmathopencl)

# nmathopencl compile-time flag
nmathopencl_has_opencl()
#> [1] TRUE

# opencltools compile-time flag (imported dependency)
opencltools::has_opencl()
#> [1] TRUE

# Host GPU inventory via opencltools (not the compile flag)
opencltools::gpu_names()
#> [1] "NVIDIA GeForce RTX 4090"

# Host/runtime diagnostic report (opencltools)
opencltools::diagnose_glmbayes()

opencltools::diagnose_glmbayes() runs a layered host check (environment, GPU vendors, drivers, OpenCL headers and ICD, Linux/WSL runtime probe, PATH / LD_LIBRARY_PATH). Pair it with nmathopencl_has_opencl() for this package’s compile-time OpenCL build flag. On Windows, the Linux/WSL runtime probe is skipped; rely on driver and ICD checks instead.

x <- rnorm(1e7)
system.time(dnorm_opencl(x, mean = 0, sd = 1))
system.time(dnorm(x, mean = 0, sd = 1))

Troubleshooting common failures

For package developers: next steps

Once OpenCL is working for nmathopencl itself, the next step is adding USE_OPENCL and nmathopencl_has_opencl() to your own downstream package so that it also builds cleanly on CRAN. See vignette("Chapter-02", package = "nmathopencl") for the use_opencl_configure() / port_to_opencl_configure() workflow.