Package: nmathopencl 0.8.2.9000

Overview | Checking availability | Normal distribution | Distribution families | Gamma | Binomial | Poisson | Beta | Additional families | Noncentral distributions | Special functions and math support | R extension utilities (R_ext) | RNG core | Fallback behavior in detail | Performance notes

What is nmathopencl? | Three-layer architecture | C++ layout inside the package DLL | Related packages | R-side API families | Checking OpenCL availability | Vignette guide

Overview | When you load nmathopencl | What the message means | opencltools as imported dependency | What "compiling with OpenCL" means | Enabling OpenCL for nmathopencl | Step 1: Read the load message | Step 2: If OpenCL is not enabled at all | Step 3: If opencltools is enabled but nmathopencl is not | Verifying the setup | Validating GPU calls with the exported wrappers | Troubleshooting common failures | nmathopencl_has_opencl() returns FALSE after driver installation | Compilation fails with CL/cl.h: No such file or directory | Runtime error: clGetPlatformIDs: CL_PLATFORM_NOT_FOUND_KHR | PATH warnings from opencltools::diagnose_glmbayes() | For package developers: next steps

Why "programs" rather than compiled objects | No #include on the device | The four-layer program structure | Layer 0: OPENCL.cl --- the global configuration header | Layer 1: The upstream shim layer | Type stubs | Capability macros | Runtime no-ops | Math declarations | The design principle | Layer 2: The nmath library and its annotation scheme | @provides and @depends annotations | Only the required subset is loaded | Layer 3: The kernel function | Assembling the program in C++ | What this means for downstream developers

Introduction | How this chapter is organized | The computation in the example: GLM log-posterior over a grid | Serial vs. parallel execution: the fundamental concept | The serial (CPU) mental model | The parallel (GPU) mental model | When OpenCL is not available | Summary | The kernel wrapper | General description | Example: f2_f3_opencl from ex_glmbayes | Step 1 — Convert C++ input types to flat std::vector | Step 2 — Allocate output buffers | Step 3 — Select the kernel and assemble the program string | Step 4 — Dispatch to the runner | Step 5 — Convert outputs from plain C++ back to the required return types | The kernel runner | Example: f2_f3_kernel_runner from ex_glmbayes | Step 1 — Select a device | Step 2 — Create a context and command queue | Step 3 — Compile the program on-device | Step 4 — Allocate device buffers and transfer input data | Step 5 — Bind kernel arguments | Step 6 — Launch the kernel | Step 7 — Read results back to the host (blocking) | Step 8 — Release all resources | The kernel (*.cl) | Example: f2_f3_binomial_logit from ex_glmbayes | The kernel signature | The parallel execution body | The complete call chain | CRAN safety: how the architecture prevents build failures | Applying the pattern in your package | File layout | Type conversion reference | Headers and DESCRIPTION

Introduction | The two integration patterns | Pattern 1: wrapper with a direct R interface | Pattern 2: wrapper as an internal C++ component | Pattern 1 in detail: dnorm_opencl | The R wrapper | The .opencl_try_or_fallback helper | The C++ kernel wrapper | Pattern 2 in detail: f2_f3_opencl | The exported R function | The C++ dispatcher | Why a dedicated CPU implementation? | Choosing between the two patterns | Naming conventions | Summary

The openclPort namespace | opencl_dbl_scalar_kernel_runner | Declaration | Arguments | What it does | Argument layout contract | Example: calling the runner from a kernel wrapper | Error-handling utilities | opencl_status_name | opencl_status_hint | opencl_read_platform_info_str / opencl_read_device_info_str | opencl_make_context_error | Other utilities in openclPort | Rcpp -> std::vector conversion | Device probing (C++ / openclPort) | OpenCL build configuration | Using openclPort from a downstream package

Overview | Step 1 --- Identify the nmath functions your kernel needs | Step 2 --- Extract the minimal nmath subset | Step 3 --- Write the kernel files | Step 4 --- Write the kernel runner (C++) | Step 5 --- Write the kernel wrapper (C++) | Why load_library_for_kernel() rather than load_kernel_library()? | Step 6 --- Write the Rcpp export wrappers (C++ and R) | Step 7 --- Implement the CPU fallback | File inventory | OpenCL source (inst/cl/) | C++ source (src/) | C++ headers (src/) | R source (R/) | Adapting this pattern for a new package

Correctness testing | Debugging kernel failures | Benchmarking

Overview | Why a static src/Makevars breaks CRAN | The configure → USE_OPENCL → has_opencl() chain | Adding has_opencl() to your package | C++ side | R side | Case 1: New package with no existing src/Makevars | Case 2: Existing package with a static src/Makevars | What is preserved | Caveats | Guarding OpenCL code in C++ | Testing the CPU-only path before CRAN submission | DESCRIPTION dependencies | Migration note

What is inst/cl/nmath/? | Annotation scheme | File families | Infrastructure / header files | Core math helpers | Density functions (d*) | CDF functions (p*) | Quantile functions (q*) | Random-variate generators (r*) | Special functions | Additional utilities | Cycle-breaking artifacts | The ex_glmbayes_nmath/ subset | Porting fidelity

What is a kernel? | Anatomy of a simple kernel | Standard argument layout | The *_ex_kernel.cl variants | Kernel file index | Density kernels | CDF kernels | Quantile kernels | Random-variate kernels | Special function kernels | Math support kernels | RNG core kernels | Utility kernels | Bessel kernels (standard and extended) | Program assembly | Writing a custom kernel

The assembly problem | opencltools::load_kernel_source() | opencltools::load_kernel_library() | The annotation format | The topological sort algorithm | Verbose output | Cycle detection and breaking | Assembling a complete program | Using libraries from another package | Dependency index --- faster, kernel-specific loading | Building the index --- write_kernel_dependency_index() | Loading with the index --- load_library_for_kernel() (R) | Extracting a subset --- extract_library_subset() | C++ equivalent --- openclPort::load_library_for_kernel() | Error messages