Package {nmathopencl}

nmathopencl: OpenCL-Ported R Math Library for GPU-Accelerated Packages

Description

nmathopencl provides OpenCL-ported versions of R's internal nmath and R_ext math routines, enabling downstream R packages to build custom GPU-accelerated kernels that call the same statistical distribution functions available in base R. The package is intended as a developer library: users install it to gain access to the ported .cl source files, then write their own OpenCL kernels that ⁠#include⁠ those sources as needed.

Details

The core deliverable is a collection of .cl files installed under ⁠inst/cl/nmath/⁠ that mirror the R nmath library (density, distribution, quantile, and random-variate functions). Downstream packages locate these files at runtime with system.file("cl", package = "nmathopencl") and assemble them into an OpenCL program using opencltools::load_kernel_library(..., package = "nmathopencl").

The package also ships Ex_EnvelopeEval and its supporting functions (Ex_glmbfamfunc, Ex_glmb_Standardize_Model, Ex_EnvelopeSize) as a worked example of how a downstream package—here the glmbayes Bayesian GLM sampler—builds a custom kernel on top of the ported nmath routines. See system.file("examples", "Ex_EnvelopeEval.R", package = "nmathopencl") and vignette("Chapter-10") for a complete walkthrough.

Optional GPU acceleration is available wherever an OpenCL runtime is installed. Use nmathopencl_has_opencl to query compile-time OpenCL support, nmathopencl_opencl_fp64_available / nmathopencl_opencl_device_info for double-precision device selection used by kernels. Host/runtime diagnostics use opencltools::diagnose_glmbayes().

The simulation theory underlying the envelope construction is described in (Nygren and Nygren 2006), with implementation details in (Nygren 2025, 2025). OpenCL GPU execution follows (Stone et al. 2010); package vignettes also discuss GPU workflows ((Nygren 2025, 2025)).

C-callable API (C++ package developers)

GPU *_opencl routines are registered for R_GetCCallable on load. Downstream packages should LinkingTo: nmathopencl, Imports: nmathopencl, opencltools, and ⁠#include <nmathopencl/nmathopencl_capi.h>⁠ (see system.file("include/nmathopencl/README.md", package = "nmathopencl")). Call nmathopencl_api_version() for ABI compatibility. Kernel loading remains on opencltools (opencltools_capi.h).

OpenCL startup checks

In interactive sessions, attaching the package with library(nmathopencl) may emit a packageStartupMessage comparing compile-time OpenCL support in nmathopencl and opencltools, noting that CPU fallbacks remain available, and summarizing whether an OpenCL runtime appears available on the host. Messages point to ?gpu_diagnostics, vignette("Chapter-01") (OpenCL enablement), vignette("Chapter-12") (packaged *_opencl API), and this help page. Host-side OpenCL diagnostics use opencltools. Set options(nmathopencl.quiet_opencl_startup = TRUE) to suppress these notes (recommended for CI and R CMD check).

Author(s)

Kjell Nygren

References

Nygren K (2025). “Chapter A05: Simulation Methods – Likelihood Subgradient Densities.” Vignette in the glmbayes R package. R vignette name: Chapter-A05.

Nygren K (2025). “Chapter A08: Overview of Envelope Related Functions.” Vignette in the glmbayes R package. R vignette name: Chapter-A08.

Nygren K (2025). “Chapter 12: Large Models: GPU Acceleration using OpenCL.” Vignette in the glmbayes R package. R vignette name: Chapter-12.

Nygren K (2025). “Chapter A10: Accelerated EnvelopeBuild Implementation using OpenCL.” Vignette in the glmbayes R package. R vignette name: Chapter-A10.

Nygren K~N, Nygren L~M (2006). “Likelihood Subgradient Densities.” Journal of the American Statistical Association, 101(475), 1144–1156. doi:10.1198/016214506000000357.

Stone JE, Gohara D, Shi G (2010). “OpenCL: A Parallel Programming Standard for Heterogeneous Computing Systems.” Computing in Science & Engineering, 12(3), 66–72. doi:10.1109/MCSE.2010.69.

See Also

Key developer entry points:

• opencltools::load_kernel_library — assemble the nmath .cl sources (package = "nmathopencl").

• nmathopencl_has_opencl — check whether an OpenCL runtime is present.

• nmathopencl_opencl_device_info — which OpenCL device is used for fp64 kernels.

• Ex_EnvelopeEval — worked example of a custom kernel built on the ported nmath routines.

Useful links:

• GitHub: https://github.com/knygren/nmathopencl

• R-Universe: https://knygren.r-universe.dev/nmathopencl

• Related sampler package (Suggests): glmbayes

Evaluate Negative Log-Likelihood and Gradients

Description

These functions implement the grid evaluation logic used in envelope construction for rejection sampling. They make use of the theory described in (Nygren and Nygren 2006) and the general implementation outlined in (Nygren 2025).

Usage

Ex_EnvelopeEval(G4, y, x, mu, P, alpha, wt,
                    family, link,
                    use_opencl = FALSE, verbose = FALSE)

Arguments

Details

Compact overview.
Derivations:\cr vignettes/equations ((Nygren and Nygren 2006)).

• Dispatcher fans out to CPU and OpenCL kernel runners.
  

• ⁠NegLL⁠ vectors plus ⁠cbars⁠ matrices feed envelopes in rNormal_reg internals.
  

• Acceptance inequalities mirror the vignette “Simulation execution” chapter.

Value

Ex_EnvelopeEval

NegLL: negatives logLik; cbars: tangent gradients.

f2_f3_non_opencl

qf/grad from CPU kernels.

f2_f3_opencl

qf/grad from OpenCL.

run_opencl_pilot

Pilot runtime estimate (seconds).

References

Nygren K (2025). “Chapter A05: Simulation Methods – Likelihood Subgradient Densities.” Vignette in the glmbayes R package. R vignette name: Chapter-A05.

Nygren K~N, Nygren L~M (2006). “Likelihood Subgradient Densities.” Journal of the American Statistical Association, 101(475), 1144–1156. doi:10.1198/016214506000000357.

See Also

Ex_EnvelopeSize (Nygren 2025) (Nygren 2025) (Nygren 2025) (Nygren 2025)

Examples

############################### Start of Ex_EnvelopeEval example ####################

# This example demonstrates Ex_EnvelopeEval in isolation. Ex_EnvelopeEval evaluates
# the negative log-likelihood and gradients at a grid of parameter values.
# It is called internally by EnvelopeBuild. Here we build the same inputs
# (grid G4, standardized model) using Ex_EnvelopeSize and expand.grid, then
# call Ex_EnvelopeEval directly. The setup mirrors Ex_EnvelopeBuild through
# the standardization step.

data(menarche, package = "MASS")
Age2 <- menarche$Age - 13

x <- matrix(as.numeric(1.0), nrow = length(Age2), ncol = 2)
x[, 2] <- Age2

y <- menarche$Menarche / menarche$Total
wt <- menarche$Total

mu <- matrix(as.numeric(0.0), nrow = 2, ncol = 1)
mu[2, 1] <- (log(0.9 / 0.1) - log(0.5 / 0.5)) / 3

V1 <- 1 * diag(as.numeric(2.0))
V1[1, 1] <- ((log(0.9 / 0.1) - log(0.5 / 0.5)) / 2)^2
V1[2, 2] <- (3 * mu[2, 1] / 2)^2

famfunc <- Ex_glmbfamfunc(binomial(logit))
f2 <- famfunc$f2
f3 <- famfunc$f3

dispersion2 <- as.numeric(1.0)
start <- mu
offset2 <- rep(as.numeric(0.0), length(y))
P <- solve(V1)
n <- 1000

wt2 <- wt / dispersion2
alpha <- x %*% as.vector(mu) + offset2
mu2 <- 0 * as.vector(mu)
P2 <- P
x2 <- x

parin <- start - mu
opt_out <- optim(parin, f2, f3,
  y = as.vector(y), x = as.matrix(x), mu = as.vector(mu2),
  P = as.matrix(P), alpha = as.vector(alpha), wt = as.vector(wt2),
  method = "BFGS", hessian = TRUE
)

bstar <- opt_out$par
A1 <- opt_out$hessian

Standard_Mod <- Ex_glmb_Standardize_Model(
  y = as.vector(y), x = as.matrix(x), P = as.matrix(P),
  bstar = as.matrix(bstar, ncol = 1), A1 = as.matrix(A1)
)

bstar2 <- Standard_Mod$bstar2
A <- Standard_Mod$A
x2 <- Standard_Mod$x2
mu2 <- Standard_Mod$mu2
P2 <- Standard_Mod$P2

###############################################################################
# Build grid G4 via Ex_EnvelopeSize and expand.grid (as EnvelopeBuild does)
###############################################################################
a <- diag(A)
omega <- (sqrt(2) - exp(-1.20491 - 0.7321 * sqrt(0.5 + a))) / sqrt(1 + a)
b2 <- as.vector(bstar2)
G1 <- rbind(b2 - omega, b2, b2 + omega)

size_info <- Ex_EnvelopeSize(a, G1, Gridtype = 3L, n = n)
G2 <- size_info$G2

G3 <- as.matrix(do.call(expand.grid, G2))
G4 <- t(G3)

###############################################################################
# Ex_EnvelopeEval: negative log-likelihood and gradients at grid points
###############################################################################
eval_out <- Ex_EnvelopeEval(
  G4 = G4,
  y = y,
  x = as.matrix(x2),
  mu = as.matrix(mu2, ncol = 1),
  P = as.matrix(P2),
  alpha = as.vector(alpha),
  wt = as.vector(wt2),
  family = "binomial",
  link = "logit",
  use_opencl = FALSE,
  verbose = FALSE
)

eval_out$NegLL
eval_out$cbars

###############################################################################
# End of Ex_EnvelopeEval example
###############################################################################

Ex_EnvelopeOpt

Description

Internal adaptive grid optimizer called by .EnvelopeSize_cpp.

Usage

Ex_EnvelopeOpt(a1, n, core_cnt = 1L)

Arguments

Value

Integer vector of grid sizes (1 or 3) per dimension.

Envelope Sizing and Optimization

Description

Ex_EnvelopeSize() is the high-level entry point that constructs per-dimension grids and expected draw counts, while Ex_EnvelopeOpt() performs the adaptive optimization used when Gridtype = 2.

Usage

Ex_EnvelopeSize(a, G1, Gridtype = 2L, n = 1000L, n_envopt = -1,
                    use_opencl = FALSE, verbose = FALSE)

Arguments

Details

These functions implement the grid sizing logic used in envelope construction for rejection sampling. They make use of the theory described in (Nygren and Nygren 2006) and the general implementation outlined in (Nygren 2025).

Ex_EnvelopeSize() returns the constructed grid (G2), index vectors (GIndex1), expected draw count (E_draws), and the per-dimension grid index.

Ex_EnvelopeOpt() implements the adaptive optimization used in Gridtype = 2, ranking dimensions by posterior variance and promoting them to three-point tangents when the tradeoff is favorable.

Value

Ex_EnvelopeSize()

A list with components G2, GIndex1, E_draws, and gridindex.

Ex_EnvelopeOpt()

An integer vector of length l1 with entries 1 (single-point) or 3 (three-point).

Gridtype Logic and Candidates per Draw

The envelope sizing logic follows the analysis of (Nygren and Nygren 2006).

Gridtype 1: Static Threshold

For each dimension i, if \sqrt{1 + a_i} \leq 2/\sqrt{\pi} \approx 1.128379, then a single tangent at the posterior mode suffices. Expected candidates per draw in that dimension: \sqrt{1 + a_i}. Otherwise, a symmetric three-point envelope is used at (\theta^\star_i - \omega_i, \theta^\star_i, \theta^\star_i + \omega_i), with expected candidates per draw bounded above by 2/\sqrt{\pi}.

Gridtype 2: Adaptive Optimization

Each dimension is assigned either a single-point or three-point envelope by minimizing

T_\mathrm{total}(g_i) = T_\mathrm{build}(g_i) + T_\mathrm{sample}(n, acc_i(g_i)).

The optimizer balances build cost (grows with number of tangents) against sampling cost (decreases as acceptance improves). Expected candidates per draw: \prod_j \mathrm{scaleest}_{i,j}, where each factor is either \sqrt{1+a_j} (single-point) or 2/\sqrt{\pi} (three-point), depending on the optimization outcome.

Gridtype 3: Always Three-Point

Every dimension uses a symmetric three-point envelope. Expected candidates per draw:

\left(\tfrac{2}{\sqrt{\pi}}\right)^k

for k dimensions, as shown in Theorem 3 of (Nygren and Nygren 2006).

Gridtype 4: Always Single-Point

Every dimension uses a single tangent at the posterior mode. Expected candidates per draw:

\prod_{i=1}^k \sqrt{1 + a_i}

(Example 1 in (Nygren and Nygren 2006)).

References

Nygren K (2025). “Chapter A05: Simulation Methods – Likelihood Subgradient Densities.” Vignette in the glmbayes R package. R vignette name: Chapter-A05.

Nygren K~N, Nygren L~M (2006). “Likelihood Subgradient Densities.” Journal of the American Statistical Association, 101(475), 1144–1156. doi:10.1198/016214506000000357.

See Also

Ex_EnvelopeEval for evaluating these grids. (Nygren 2025) (Nygren 2025)

Standardize A Non-Gaussian Model

Description

Standardizes a Non-Gaussian Model prior to Envelope Creation

Usage

Ex_glmb_Standardize_Model(y, x, P, bstar, A1)

Arguments

Details

Starts from the posterior mode quantities and proceeds in three transformations.
Step 1: posterior-precision eigendecomp.
Interim model gets identity posterior precision.
Step 2: isolate diagonal epsilon; remainder behaves like likelihood information.
Step 3: another eigendecomp diagonalizes data precision A.
The prior tied to epsilon becomes identity.
(Nygren and Nygren 2006)

Value

A list with the following components

References

Nygren K~N, Nygren L~M (2006). “Likelihood Subgradient Densities.” Journal of the American Statistical Association, 101(475), 1144–1156. doi:10.1198/016214506000000357.

Return family functions used during simulation and post processing

Description

This function takes as input a family object and returns a set of functions that are used during simulation and summarization of models using the simulation functions in this package.

Usage

Ex_glmbfamfunc(family)

## S3 method for class 'Ex_glmbfamfunc'
print(x, ...)

Arguments

Details

Compiled paths dominate;
retain Ex_glmbfamfunc closures for scripted workflows.

Value

A list (class "Ex_glmbfamfunc") whose first four components are always present for every supported family and link. The names f1–f4 are stable: they mean the same roles across families (only the internal formulas change).

f1

Neg log-likelihood in coefficients b (usual data args).

f2

Neg log-posterior: likelihood plus Normal(mu, P) quadratic penalty.

f3

Gradient of f2 w.r.t.\ b (argument pattern mirrors f2).

f4

Deviance gap vs saturation; honors dispersion;
quasi / DIC helper.

f7

Weighted curvature / Hessian proxy at b.

Slots f5 and f6 are not returned: they were reserved for alternate or C++-aligned likelihood/posterior routines and remain commented out in the implementation (only f1, f2, f3, f4, and f7 are assigned in the returned list).

Attach Cross-Library Dependency Tags to Kernel Files

Description

Given a set of user-facing kernel .cl files and a library directory, computes the full transitive dependency list for each kernel (using the library's pre-built dependency index) and writes the results back into the kernel files as annotation tags.

Usage

attach_cross_library_tags(
  kernel_paths,
  library_dir,
  depends_tag = "depends_nmath",
  index = NULL,
  dry_run = FALSE
)

Arguments

Details

Cross-library analogue of attach_kernel_dependency_tags: it targets kernels that depend on a library through a ⁠@{depends_tag}⁠ tag (entry-point stems), instead of expanding ⁠@depends⁠ purely inside one library tree.

Typical usage for kernels that call nmath functions:

nmath_dir <- system.file(
  "cl", "nmath", package = "opencltools")
idx <- readRDS(file.path(nmath_dir, "kernel_dependency_index.rds"))

attach_cross_library_tags(
  kernel_paths = list.files("inst/cl/src", "\\\\.cl$", full.names = TRUE),
  library_dir  = nmath_dir,
  depends_tag  = "depends_nmath",
  index        = idx
)

This writes ⁠@all_depends_nmath_count⁠ and ⁠@all_depends_nmath⁠ into each kernel file that carries a ⁠@depends_nmath⁠ annotation.

Value

A data frame (returned invisibly) with one row per kernel file and columns:

file

Basename of the kernel file.

direct_stems

Comma-separated direct entry-point stems read from ⁠@{depends_tag}⁠.

all_depends_count

Number of library files in the full transitive closure.

all_depends

Comma-separated full transitive dependency list in load order.

changed

TRUE if the file was (or would be, under dry_run) modified.

See Also

attach_kernel_dependency_tags write_kernel_dependency_index load_library_for_kernel

Examples

############################ Start of kernel_tagging_workflow example ########################

lib_dir <- system.file("cl/ex_glmbayes_nmath", package = "opencltools")
kernels <- list.files(
  system.file("cl/ex_glmbayes_draft_src", package = "opencltools"),
  pattern = "\\.cl$", full.names = TRUE
)

# Step 1: scan draft kernels for library calls (read-only dry run)
step1 <- attach_kernel_call_tags(
  kernel_paths = kernels,
  library_dir  = lib_dir,
  library_tag  = "nmath",
  dry_run      = TRUE
)
step1

# Step 2: expand transitive closure (small nmath library; runs on CRAN check)
nmath_small <- system.file("cl/nmath_small", package = "opencltools")
tagged      <- system.file("cl/src/dnorm_kernel.cl", package = "opencltools")
idx_small   <- write_kernel_dependency_index(library_dir = nmath_small, write = FALSE)

step2_small <- attach_cross_library_tags(
  kernel_paths = tagged,
  library_dir  = nmath_small,
  depends_tag  = "depends_nmath",
  index        = idx_small,
  dry_run      = TRUE
)
nrow(step2_small)


# Step 2: full nmath (slow)
nmath_dir <- system.file("cl/nmath", package = "opencltools")
idx       <- write_kernel_dependency_index(library_dir = nmath_dir, write = FALSE)

step2 <- attach_cross_library_tags(
  kernel_paths = tagged,
  library_dir  = nmath_dir,
  depends_tag  = "depends_nmath",
  index        = idx,
  dry_run      = TRUE
)
step2


###############################################################################
## End of kernel_tagging_workflow example
###############################################################################

Attach Library Call Tags to Kernel Files

Description

Scans kernel .cl source files for calls to functions provided by a pre-annotated library, then writes the discovered dependencies as annotation tags directly into the kernel files.

Usage

attach_kernel_call_tags(
  kernel_paths,
  library_dir,
  library_tag,
  overwrite_existing = FALSE,
  dry_run = FALSE
)

Arguments

Details

For a library such as nmathopencl, each .cl shard carries a ⁠@provides⁠ annotation listing the symbols it defines. This function builds a provides map from those annotations (symbol \to shard stem), scans each kernel's source (with comments and string literals stripped) for matching function calls, and writes four annotation tags at the top of each kernel file:

⁠@library_deps: <library_tag>⁠

Library name (written if absent).

⁠@calls_<library_tag>: sym1, sym2⁠

Symbols from the library actually called in this kernel.

⁠@depends_<library_tag>: stem1, stem2⁠

Library shard stems that define the called symbols.

⁠@calls_opencl_builtin: sym | (none)⁠

Detected OpenCL work-item and synchronization builtins (standard math builtins excluded).

Two-step tagging workflow:

# Step 1 — this function: infer direct library calls from source
nmath_dir <- system.file("cl/nmath", package = "nmathopencl")
attach_kernel_call_tags(
  kernel_paths = list.files("inst/cl/src", "\\.cl$", full.names = TRUE),
  library_dir  = nmath_dir,
  library_tag  = "nmath"
)

# Step 2 — expand to full transitive closure
attach_cross_library_tags(
  kernel_paths = list.files("inst/cl/src", "\\.cl$", full.names = TRUE),
  library_dir  = nmath_dir,
  depends_tag  = "depends_nmath"
)

Value

A data frame (returned invisibly) with one row per kernel file and columns:

file

Basename of the kernel file.

calls

Comma-separated library symbols detected in source.

depends

Comma-separated shard stems for the detected symbols.

opencl_builtins

Comma-separated OpenCL builtins detected, or empty string if none.

changed

TRUE if the file was (or would be) modified. NA means the file was skipped (already tagged).

See Also

attach_cross_library_tags, attach_kernel_dependency_tags

Examples

############################ Start of kernel_tagging_workflow example ########################

lib_dir <- system.file("cl/ex_glmbayes_nmath", package = "opencltools")
kernels <- list.files(
  system.file("cl/ex_glmbayes_draft_src", package = "opencltools"),
  pattern = "\\.cl$", full.names = TRUE
)

# Step 1: scan draft kernels for library calls (read-only dry run)
step1 <- attach_kernel_call_tags(
  kernel_paths = kernels,
  library_dir  = lib_dir,
  library_tag  = "nmath",
  dry_run      = TRUE
)
step1

# Step 2: expand transitive closure (small nmath library; runs on CRAN check)
nmath_small <- system.file("cl/nmath_small", package = "opencltools")
tagged      <- system.file("cl/src/dnorm_kernel.cl", package = "opencltools")
idx_small   <- write_kernel_dependency_index(library_dir = nmath_small, write = FALSE)

step2_small <- attach_cross_library_tags(
  kernel_paths = tagged,
  library_dir  = nmath_small,
  depends_tag  = "depends_nmath",
  index        = idx_small,
  dry_run      = TRUE
)
nrow(step2_small)


# Step 2: full nmath (slow)
nmath_dir <- system.file("cl/nmath", package = "opencltools")
idx       <- write_kernel_dependency_index(library_dir = nmath_dir, write = FALSE)

step2 <- attach_cross_library_tags(
  kernel_paths = tagged,
  library_dir  = nmath_dir,
  depends_tag  = "depends_nmath",
  index        = idx,
  dry_run      = TRUE
)
step2


###############################################################################
## End of kernel_tagging_workflow example
###############################################################################

Attach Dependency Tags to a Dependency-Ordered Kernel Library

Description

Compute and attach derived tags to each .cl file in a library: ⁠@load_order⁠, ⁠@all_depends⁠, and ⁠@all_depends_count⁠.

Usage

attach_kernel_dependency_tags(library_dir, dry_run = FALSE)

Arguments

Details

Tags are written only if dependency sorting fully succeeds. If unresolved files remain, no files are modified and a cycle report is returned so source refactoring can be prioritized.

Value

A list with:

ok

Logical success flag.

message

Human-readable summary.

sorted

Sorted records data frame.

unresolved

Unresolved records data frame (empty on success).

cycles

Cycle report data frame (empty on success).

tags

Per-file tag data frame with source_origin, source_type, includes, depends, provides, load_order, all_depends, and all_depends_count (present on success).

header_functions

Functions declared in header files without attribute_hidden, including declaring header, inferred definition file, declaration signature, define_alias, and all_depends for the definition file.

An S3 class "opencl_dependency_tags" is attached for use with print().

Examples

############################ Start of attach_kernel_dependency_tags example ########################

lib_dir <- system.file("cl/ex_glmbayes_nmath", package = "opencltools")
res <- attach_kernel_dependency_tags(lib_dir, dry_run = TRUE)
res$ok
print(res)

###############################################################################
## End of attach_kernel_dependency_tags example
###############################################################################

The Beta Distribution (OpenCL)

Description

OpenCL-backed density, distribution, quantile, and random generation wrappers for the beta distribution. These mirror the base stats beta family while adding OpenCL dispatch and optional CPU fallback behavior.

Usage

dbeta_opencl(
  x,
  shape1,
  shape2,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

dnbeta_opencl(
  x,
  shape1,
  shape2,
  ncp,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

pbeta_opencl(
  q,
  shape1,
  shape2,
  ncp = 0,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

rbeta_opencl(n, shape1, shape2, fallback = FALSE, verbose = FALSE)

Arguments

Value

Numeric vector of length n.

Known OpenCL limitations

Quantile path

The beta quantile OpenCL kernel fails at device link (Rf_lbeta unresolved), so no qbeta wrapper is exported; use stats::qbeta().
Tracker: ‘inst/OPENCL_KERNEL_KNOWN_FAILURES.md’

References

Abramowitz M, Stegun IA (1972). Handbook of Mathematical Functions with Formulas, Graphs, and Mathematical Tables. Dover Publications, New York. ISBN 0486612724.

Becker RA, Chambers JM, Wilks AR (1988). The New S Language. Chapman and Hall/CRC, London. ISBN 053409192X.

Brown BW, Levy LB (1994). “Certification of Algorithm 708: Significant-Digit Computation of the Incomplete Beta.” ACM Transactions on Mathematical Software, 20(3), 393–397. doi:10.1145/192115.192155.

Cheng RCH (1978). “Generating Beta Variates with Nonintegral Shape Parameters.” Communications of the ACM, 21(4), 317–322. doi:10.1145/359460.359482.

Cran GW, Martin KJ, Thomas GE (1977). “Remark AS R19 and Algorithm AS 109: A Remark on Algorithms AS 63: The Incomplete Beta Integral, AS 64: Inverse of the Incomplete Beta Function Ratio.” Applied Statistics, 26(1), 111–114. doi:10.2307/2346887.

Didonato AR, Morris Jr. AH (1992). “Algorithm 708: Significant Digit Computation of the Incomplete Beta Function Ratios.” ACM Transactions on Mathematical Software, 18(3), 360–373. doi:10.1145/131766.131776.

Frick H (1990). “Algorithm AS R84: A Remark on Algorithm AS 226: Computing Non-Central Beta Probabilities.” Applied Statistics, 39(2), 311–312. doi:10.2307/2347780.

Johnson NL, Kotz S, Balakrishnan N (1995). Continuous Univariate Distributions, volume 2, 2nd edition. Wiley, New York. ISBN 978-0-471-58494-0.

Lam ML (1995). “Remark AS R95: A Remark on Algorithm AS 226: Computing Non-Central Beta Probabilities.” Applied Statistics, 44(4), 551–552. doi:10.2307/2986147.

Lenth RV (1987). “Algorithm AS 226: Computing Noncentral Beta Probabilities.” Applied Statistics, 36(2), 241–244. doi:10.2307/2347558.

Examples

n <- 5L
if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  dbeta_opencl(rep(0.6, n), shape1 = 2.5, shape2 = 4, fallback = FALSE, verbose = TRUE)
  dnbeta_opencl(rep(0.6, n), shape1 = 2.5, shape2 = 4, ncp = 0.8, fallback = FALSE, verbose = TRUE)
  pbeta_opencl(q = 0.6, shape1 = 2.5, shape2 = 4, ncp = 0, fallback = FALSE, verbose = TRUE)
  rbeta_opencl(n, shape1 = 2.5, shape2 = 4, fallback = FALSE, verbose = TRUE)
} else {
  stats::dbeta(rep(0.6, n), shape1 = 2.5, shape2 = 4)
  stats::pbeta(0.6, shape1 = 2.5, shape2 = 4, ncp = 0)
  stats::rbeta(n, shape1 = 2.5, shape2 = 4)
}

The Binomial Distribution (OpenCL)

Description

OpenCL-backed density, distribution, quantile, and random generation wrappers for the binomial distribution.

Usage

dbinom_raw_opencl(
  x,
  size,
  prob,
  qprob = NULL,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

dbinom_opencl(
  x,
  size,
  prob,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

pbinom_opencl(
  q,
  size,
  prob,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

qbinom_opencl(
  p,
  size,
  prob,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

rbinom_opencl(n, size, prob, fallback = FALSE, verbose = FALSE)

Arguments

Value

Numeric vector result from the corresponding binomial-family operation.

References

Kachitvichyanukul V, Schmeiser BW (1988). “Binomial Random Variate Generation.” Communications of the ACM, 31(2), 216–222. doi:10.1145/42372.42381.

Loader C (2000). “Fast and Accurate Computation of Binomial Probabilities.” Bell Laboratories. https://www.r-project.org/doc/reports/CLoader-dbinom-2002.pdf.

Examples

n <- 5L
if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  dbinom_raw_opencl(rep(6, n), size = 10, prob = 0.3, fallback = FALSE, verbose = TRUE)
  dbinom_opencl(rep(6, n), size = 10, prob = 0.3, fallback = FALSE, verbose = TRUE)
  pbinom_opencl(q = 6, size = 10, prob = 0.3, fallback = FALSE, verbose = TRUE)
  qbinom_opencl(rep(0.8, n), size = 10, prob = 0.3, fallback = FALSE, verbose = TRUE)
  rbinom_opencl(n, size = 10, prob = 0.3, fallback = FALSE, verbose = TRUE)
} else {
  stats::dbinom(rep(6, n), size = 10, prob = 0.3)
  stats::dbinom(rep(6, n), size = 10, prob = 0.3)
  stats::pbinom(6, size = 10, prob = 0.3)
  stats::qbinom(rep(0.8, n), size = 10, prob = 0.3)
  stats::rbinom(n, size = 10, prob = 0.3)
}

The Cauchy Distribution (OpenCL)

Description

OpenCL-backed density, distribution, quantile, and random generation wrappers for the Cauchy distribution.

Usage

dcauchy_opencl(
  x,
  location = 0,
  scale = 1,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

pcauchy_opencl(
  q,
  location = 0,
  scale = 1,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

qcauchy_opencl(
  p,
  location = 0,
  scale = 1,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

rcauchy_opencl(n, location = 0, scale = 1, fallback = FALSE, verbose = FALSE)

Arguments

Value

Numeric vector result from the corresponding Cauchy-family operation.

References

Becker RA, Chambers JM, Wilks AR (1988). The New S Language. Chapman and Hall/CRC, London. ISBN 053409192X.

Johnson NL, Kotz S, Balakrishnan N (1994). Continuous Univariate Distributions, volume 1, 2nd edition. Wiley, New York. ISBN 978-0-471-58495-7.

Examples

n <- 5L
if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  dcauchy_opencl(rep(0.2, n), location = 0, scale = 1, fallback = FALSE, verbose = TRUE)
  pcauchy_opencl(q = 0.2, location = 0, scale = 1, fallback = FALSE, verbose = TRUE)
  qcauchy_opencl(rep(0.8, n), location = 0, scale = 1, fallback = FALSE, verbose = TRUE)
  rcauchy_opencl(n, location = 0, scale = 1, fallback = FALSE, verbose = TRUE)
} else {
  stats::dcauchy(rep(0.2, n), location = 0, scale = 1)
  stats::pcauchy(0.2, location = 0, scale = 1)
  stats::qcauchy(rep(0.8, n), location = 0, scale = 1)
  stats::rcauchy(n, location = 0, scale = 1)
}

The Chi-squared Distribution (OpenCL)

Description

OpenCL-backed density, distribution, quantile, and random generation wrappers for the chi-squared distribution, including non-central paths via ncp.

Usage

dchisq_opencl(
  x,
  df,
  ncp = 0,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

pchisq_opencl(
  q,
  df,
  ncp = 0,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

qchisq_opencl(
  p,
  df,
  ncp = 0,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

rchisq_opencl(n, df, ncp = 0, fallback = FALSE, verbose = FALSE)

Arguments

Value

Numeric vector of length n.

References

Becker RA, Chambers JM, Wilks AR (1988). The New S Language. Chapman and Hall/CRC, London. ISBN 053409192X.

Ding CG (1992). “Algorithm AS 275: Computing the Non-Central Chi-Squared Distribution Function.” Applied Statistics, 41(2), 478–482. doi:10.2307/2347584.

Johnson NL, Kotz S, Balakrishnan N (1994). Continuous Univariate Distributions, volume 1, 2nd edition. Wiley, New York. ISBN 978-0-471-58495-7.

Johnson NL, Kotz S, Balakrishnan N (1995). Continuous Univariate Distributions, volume 2, 2nd edition. Wiley, New York. ISBN 978-0-471-58494-0.

Examples

n <- 5L
if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  dchisq_opencl(rep(4.5, n), df = 6, ncp = 0, fallback = FALSE, verbose = TRUE)
  pchisq_opencl(q = 4.5, df = 6, ncp = 0, fallback = FALSE, verbose = TRUE)
  qchisq_opencl(rep(0.8, n), df = 6, ncp = 0, fallback = FALSE, verbose = TRUE)
  rchisq_opencl(n, df = 6, ncp = 0, fallback = FALSE, verbose = TRUE)
} else {
  stats::dchisq(rep(4.5, n), df = 6, ncp = 0)
  stats::pchisq(4.5, df = 6, ncp = 0)
  stats::qchisq(rep(0.8, n), df = 6, ncp = 0)
  stats::rchisq(n, df = 6, ncp = 0)
}

The Exponential Distribution (OpenCL)

Description

OpenCL-backed density, distribution, quantile, and random generation wrappers for the exponential distribution.

Usage

dexp_opencl(
  x,
  rate = 1,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

pexp_opencl(
  q,
  rate = 1,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

qexp_opencl(
  p,
  rate = 1,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

rexp_opencl(n, rate = 1, fallback = FALSE, verbose = FALSE)

Arguments

Value

Numeric vector result from the corresponding exponential-family operation.

References

Ahrens JH, Dieter U (1972). “Computer Methods for Sampling from the Exponential and Normal Distributions.” Communications of the ACM, 15(10), 873–882. doi:10.1145/355604.361593.

Becker RA, Chambers JM, Wilks AR (1988). The New S Language. Chapman and Hall/CRC, London. ISBN 053409192X.

Johnson NL, Kotz S, Balakrishnan N (1994). Continuous Univariate Distributions, volume 1, 2nd edition. Wiley, New York. ISBN 978-0-471-58495-7.

Examples

n <- 5L
if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  dexp_opencl(rep(1.2, n), rate = 1, fallback = FALSE, verbose = TRUE)
  pexp_opencl(q = 1.2, rate = 1, fallback = FALSE, verbose = TRUE)
  qexp_opencl(rep(0.8, n), rate = 1, fallback = FALSE, verbose = TRUE)
  rexp_opencl(n, rate = 1, fallback = FALSE, verbose = TRUE)
} else {
  stats::dexp(rep(1.2, n), rate = 1)
  stats::pexp(1.2, rate = 1)
  stats::qexp(rep(0.8, n), rate = 1)
  stats::rexp(n, rate = 1)
}

The F Distribution (OpenCL)

Description

OpenCL-backed density, distribution, quantile, and random generation wrappers for the F distribution.

Usage

df_opencl(
  x,
  df1,
  df2,
  ncp = 0,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

pf_opencl(
  q,
  df1,
  df2,
  ncp = 0,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

qf_opencl(
  p,
  df1,
  df2,
  ncp = 0,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

rf_opencl(n, df1, df2, fallback = FALSE, verbose = FALSE)

Arguments

Value

For df_opencl, qf_opencl, rf_opencl: numeric vector result. For pf_opencl: numeric vector of recycled length (see stats::pf).

Known OpenCL limitations

qf_opencl() can fail on some GPU/driver combinations with CL_OUT_OF_RESOURCES. This has been observed in both central and non-central settings, with non-central paths typically more fragile.

References

Abramowitz M, Stegun IA (1972). Handbook of Mathematical Functions with Formulas, Graphs, and Mathematical Tables. Dover Publications, New York. ISBN 0486612724.

Becker RA, Chambers JM, Wilks AR (1988). The New S Language. Chapman and Hall/CRC, London. ISBN 053409192X.

Johnson NL, Kotz S, Balakrishnan N (1995). Continuous Univariate Distributions, volume 2, 2nd edition. Wiley, New York. ISBN 978-0-471-58494-0.

Examples

n <- 5L
if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  df_opencl(rep(2, n), df1 = 5, df2 = 9, ncp = 0, fallback = FALSE, verbose = TRUE)
  df_opencl(rep(2, n), df1 = 5, df2 = 9, ncp = 1.1, fallback = FALSE, verbose = TRUE)
  pf_opencl(q = 2, df1 = 5, df2 = 9, ncp = 0, fallback = FALSE, verbose = TRUE)
  pf_opencl(q = 2, df1 = 5, df2 = 9, ncp = 1.1, fallback = FALSE, verbose = TRUE)
  rf_opencl(n, df1 = 5, df2 = 9, fallback = FALSE, verbose = TRUE)
  ## qf_opencl: disabled — see inst/OPENCL_KERNEL_KNOWN_FAILURES.md
} else {
  stats::df(rep(2, n), df1 = 5, df2 = 9, ncp = 0)
  stats::df(rep(2, n), df1 = 5, df2 = 9, ncp = 1.1)
  stats::pf(2, df1 = 5, df2 = 9, ncp = 0)
  stats::pf(2, df1 = 5, df2 = 9, ncp = 1.1)
  stats::rf(n, df1 = 5, df2 = 9)
}

The Gamma Distribution (OpenCL)

Description

OpenCL-backed density, distribution, quantile, and random generation wrappers for the gamma distribution. These mirror the base stats gamma family while adding OpenCL dispatch and optional CPU fallback behavior.

Usage

dgamma_opencl(
  x,
  shape,
  scale = 1,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

pgamma_opencl(
  q,
  shape,
  rate = 1,
  scale = 1/rate,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

rgamma_opencl(n, shape, scale = 1, fallback = FALSE, verbose = FALSE)

Arguments

Details

pgamma_opencl follows pgamma argument names and rate/scale handling (including the error when both are supplied inconsistently). Recycling of q, shape, and scale follows stats::pgamma. Vector lower.tail and log.p are recycled row-wise with those arguments (like pnorm_opencl); a single-vector stats::pgamma() call does not apply tail flags element-wise. There is no leading n argument for pgamma_opencl. On the GPU path each recycled row runs pgamma_kernel once with n_out = 1. Missing or non-finite values after recycling, or non-positive shape/scale, use row-wise stats::pgamma.

Value

Numeric vector result from the corresponding gamma-family operation.

Known OpenCL limitations

Compilation of qgamma_kernel can fail (ptxas: unresolved stirlerr_cycle_free), so no qgamma wrapper is exported; use stats::qgamma(). See ‘inst/OPENCL_KERNEL_KNOWN_FAILURES.md’.

References

Abramowitz M, Stegun IA (1972). Handbook of Mathematical Functions with Formulas, Graphs, and Mathematical Tables. Dover Publications, New York. ISBN 0486612724.

Ahrens JH, Dieter U (1974). “Computer Methods for Sampling from Gamma, Beta, Poisson and Binomial Distributions.” Computing, 12(3), 223–246. doi:10.1007/bf02293108.

Ahrens JH, Dieter U (1982). “Generating Gamma Variates by a Modified Rejection Technique.” Communications of the ACM, 25(1), 47–54. doi:10.1145/358315.358390.

Becker RA, Chambers JM, Wilks AR (1988). The New S Language. Chapman and Hall/CRC, London. ISBN 053409192X.

Best DJ, Roberts DE (1975). “Algorithm AS 89: The Upper Tail Probabilities of Spearman's Rho.” Applied Statistics, 24(3), 377–379. doi:10.2307/2347111.

NIST (2024). “NIST Digital Library of Mathematical Functions.” https://dlmf.nist.gov/. Section 8.2.

Shea BL (1988). “Algorithm AS 239: Chi-Squared and Incomplete Gamma Integral.” Applied Statistics, 37(3), 466–473. doi:10.2307/2347328.

Examples

n <- 5L
if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  dgamma_opencl(rep(1.2, n), shape = 2, scale = 1, fallback = FALSE, verbose = TRUE)
  pgamma_opencl(q = 1.2, shape = 2, scale = 1, fallback = FALSE, verbose = TRUE)
  rgamma_opencl(n, shape = 2, scale = 1, fallback = FALSE, verbose = TRUE)
} else {
  stats::dgamma(rep(1.2, n), shape = 2, scale = 1)
  stats::pgamma(1.2, shape = 2, scale = 1)
  stats::rgamma(n, shape = 2, scale = 1)
}

The Geometric Distribution (OpenCL)

Description

OpenCL-backed density, distribution, quantile, and random generation wrappers for the geometric distribution.

Usage

dgeom_opencl(
  x,
  prob,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

pgeom_opencl(
  q,
  prob,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

qgeom_opencl(
  p,
  prob,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

rgeom_opencl(n, prob, fallback = FALSE, verbose = FALSE)

Arguments

Value

Numeric vector result from the corresponding geometric-family operation.

References

Devroye L (1986). Non-Uniform Random Variate Generation. Springer, New York.

Examples

n <- 5L
if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  dgeom_opencl(rep(4, n), prob = 0.3, fallback = FALSE, verbose = TRUE)
  pgeom_opencl(q = 4, prob = 0.3, fallback = FALSE, verbose = TRUE)
  qgeom_opencl(rep(0.8, n), prob = 0.3, fallback = FALSE, verbose = TRUE)
  rgeom_opencl(n, prob = 0.3, fallback = FALSE, verbose = TRUE)
} else {
  stats::dgeom(rep(4, n), prob = 0.3)
  stats::pgeom(4, prob = 0.3)
  stats::qgeom(rep(0.8, n), prob = 0.3)
  stats::rgeom(n, prob = 0.3)
}

The Hypergeometric Distribution (OpenCL)

Description

OpenCL-backed density, distribution, quantile, and random generation wrappers for the hypergeometric distribution.

Usage

dhyper_opencl(
  x,
  m,
  n_black,
  k,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

phyper_opencl(
  q,
  m,
  n_black,
  k,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

qhyper_opencl(
  p,
  m,
  n_black,
  k,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

rhyper_opencl(n, m, n_black, k, fallback = FALSE, verbose = FALSE)

Arguments

Value

Numeric vector result from the corresponding hypergeometric-family operation.

References

Johnson NL, Kotz S, Kemp AW (1993). Univariate Discrete Distributions, 2nd edition. Wiley, New York. ISBN 978-0471548973.

Kachitvichyanukul V, Schmeiser BW (1985). “Computer Generation of Hypergeometric Random Variates.” Journal of Statistical Computation and Simulation, 22(2), 127–145. doi:10.1080/00949658508810839.

Examples

n <- 5L
if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  dhyper_opencl(rep(3, n), m = 10, n_black = 12, k = 8, fallback = FALSE, verbose = TRUE)
  phyper_opencl(q = 3, m = 10, n_black = 12, k = 8, fallback = FALSE, verbose = TRUE)
  qhyper_opencl(rep(0.8, n), m = 10, n_black = 12, k = 8, fallback = FALSE, verbose = TRUE)
  rhyper_opencl(n, m = 10, n_black = 12, k = 8, fallback = FALSE, verbose = TRUE)
} else {
  stats::dhyper(rep(3, n), m = 10, n = 12, k = 8)
  stats::phyper(3, m = 10, n = 12, k = 8)
  stats::qhyper(rep(0.8, n), m = 10, n = 12, k = 8)
  stats::rhyper(n, m = 10, n = 12, k = 8)
}

The Lognormal Distribution (OpenCL)

Description

OpenCL-backed density, distribution, quantile, and random generation wrappers for the lognormal distribution.

Usage

dlnorm_opencl(
  x,
  meanlog = 0,
  sdlog = 1,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

plnorm_opencl(
  q,
  meanlog = 0,
  sdlog = 1,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

qlnorm_opencl(
  p,
  meanlog = 0,
  sdlog = 1,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

rlnorm_opencl(n, meanlog = 0, sdlog = 1, fallback = FALSE, verbose = FALSE)

Arguments

Value

Numeric vector of length n.

References

Becker RA, Chambers JM, Wilks AR (1988). The New S Language. Chapman and Hall/CRC, London. ISBN 053409192X.

Johnson NL, Kotz S, Balakrishnan N (1994). Continuous Univariate Distributions, volume 1, 2nd edition. Wiley, New York. ISBN 978-0-471-58495-7.

Examples

n <- 5L
if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  dlnorm_opencl(rep(1.2, n), meanlog = 0.1, sdlog = 0.8, fallback = FALSE, verbose = TRUE)
  plnorm_opencl(q = 1.2, meanlog = 0.1, sdlog = 0.8, fallback = FALSE, verbose = TRUE)
  qlnorm_opencl(rep(0.8, n), meanlog = 0.1, sdlog = 0.8, fallback = FALSE, verbose = TRUE)
  rlnorm_opencl(n, meanlog = 0.1, sdlog = 0.8, fallback = FALSE, verbose = TRUE)
} else {
  stats::dlnorm(rep(1.2, n), meanlog = 0.1, sdlog = 0.8)
  stats::plnorm(1.2, meanlog = 0.1, sdlog = 0.8)
  stats::qlnorm(rep(0.8, n), meanlog = 0.1, sdlog = 0.8)
  stats::rlnorm(n, meanlog = 0.1, sdlog = 0.8)
}

The Logistic Distribution (OpenCL)

Description

OpenCL-backed density, distribution, quantile, and random generation wrappers for the logistic distribution.

Usage

dlogis_opencl(
  x,
  location = 0,
  scale = 1,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

plogis_opencl(
  q,
  location = 0,
  scale = 1,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

qlogis_opencl(
  p,
  location = 0,
  scale = 1,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

rlogis_opencl(n, location = 0, scale = 1, fallback = FALSE, verbose = FALSE)

Arguments

Value

Numeric vector result from the corresponding logistic-family operation.

Known OpenCL limitations

Some platforms fail to link qlogis_kernel (ptxas unresolved Rf_qlogis). Runnable examples omit GPU qlogis_opencl until resolved. See ‘inst/OPENCL_KERNEL_KNOWN_FAILURES.md’.

References

Becker RA, Chambers JM, Wilks AR (1988). The New S Language. Chapman and Hall/CRC, London. ISBN 053409192X.

Johnson NL, Kotz S, Balakrishnan N (1995). Continuous Univariate Distributions, volume 2, 2nd edition. Wiley, New York. ISBN 978-0-471-58494-0.

Examples

n <- 5L
if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  dlogis_opencl(rep(0.2, n), location = 0, scale = 1, fallback = FALSE, verbose = TRUE)
  plogis_opencl(q = 0.2, location = 0, scale = 1, fallback = FALSE, verbose = TRUE)
  ## qlogis_opencl: disabled — see inst/OPENCL_KERNEL_KNOWN_FAILURES.md
  rlogis_opencl(n, location = 0, scale = 1, fallback = FALSE, verbose = TRUE)
} else {
  stats::dlogis(rep(0.2, n), location = 0, scale = 1)
  stats::plogis(0.2, location = 0, scale = 1)
  stats::rlogis(n, location = 0, scale = 1)
}

The Negative Binomial Distribution (OpenCL)

Description

OpenCL-backed density, distribution, quantile, and random generation wrappers for the negative binomial distribution, with variants parameterized by prob and by mu.

Usage

dnbinom_opencl(
  x,
  size,
  prob,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

pnbinom_opencl(
  q,
  size,
  prob,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

qnbinom_opencl(
  p,
  size,
  prob,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

rnbinom_opencl(n, size, prob, fallback = FALSE, verbose = FALSE)

dnbinom_mu_opencl(
  x,
  size,
  mu,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

pnbinom_mu_opencl(
  q,
  size,
  mu,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

qnbinom_mu_opencl(
  p,
  size,
  mu,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

rnbinom_mu_opencl(n, size, mu, fallback = FALSE, verbose = FALSE)

Arguments

Value

Numeric vector result from the corresponding negative-binomial operation.

References

Devroye L (1986). Non-Uniform Random Variate Generation. Springer, New York.

Examples

n <- 5L
if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  dnbinom_opencl(rep(4, n), size = 7, prob = 0.4, fallback = FALSE, verbose = TRUE)
  pnbinom_opencl(q = 4, size = 7, prob = 0.4, fallback = FALSE, verbose = TRUE)
  qnbinom_opencl(rep(0.8, n), size = 7, prob = 0.4, fallback = FALSE, verbose = TRUE)
  rnbinom_opencl(n, size = 7, prob = 0.4, fallback = FALSE, verbose = TRUE)

  dnbinom_mu_opencl(rep(4, n), size = 7, mu = 5, fallback = FALSE, verbose = TRUE)
  pnbinom_mu_opencl(q = 4, size = 7, mu = 5, fallback = FALSE, verbose = TRUE)
  qnbinom_mu_opencl(rep(0.8, n), size = 7, mu = 5, fallback = FALSE, verbose = TRUE)
  rnbinom_mu_opencl(n, size = 7, mu = 5, fallback = FALSE, verbose = TRUE)
} else {
  stats::dnbinom(rep(4, n), size = 7, prob = 0.4)
  stats::pnbinom(4, size = 7, prob = 0.4)
  stats::qnbinom(rep(0.8, n), size = 7, prob = 0.4)
  stats::rnbinom(n, size = 7, prob = 0.4)

  stats::dnbinom(rep(4, n), size = 7, mu = 5)
  stats::pnbinom(4, size = 7, mu = 5)
  stats::qnbinom(rep(0.8, n), size = 7, mu = 5)
  stats::rnbinom(n, size = 7, mu = 5)
}

The Normal Distribution (OpenCL)

Description

OpenCL-backed density, distribution, quantile, and random generation wrappers for the normal distribution. These mirror the base stats normal family while adding OpenCL dispatch and optional CPU fallback behavior.

Usage

dnorm_opencl(
  x,
  mean = 0,
  sd = 1,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

pnorm_opencl(
  q,
  mean = 0,
  sd = 1,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

qnorm_opencl(
  p,
  mean = 0,
  sd = 1,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

rnorm_opencl(n, mean = 0, sd = 1, fallback = FALSE, verbose = FALSE)

Arguments

Details

pnorm_opencl matches pnorm on the first five statistical arguments (q, mean, sd, lower.tail, log.p) and the usual defaults. It also accepts opencl_parallel, fallback, and verbose. Only rnorm_opencl uses a leading n.
Recycling follows pnorm once arguments are aligned. On the GPU path, each recycled row calls the scalar pnorm_kernel once (len submissions).
Vector q, mean, sd, lower.tail, and log.p yield one OpenCL evaluation per output index.
Length-zero q returns numeric(0) as in pnorm.
Missing or non-finite values (after recycling), or any sd == 0, use CPU pnorm. Zero-length recycling errors and negative sd still error.

Value

Numeric vector result from the corresponding normal-family operation.

References

Becker RA, Chambers JM, Wilks AR (1988). The New S Language. Chapman and Hall/CRC, London. ISBN 053409192X.

Cody WJ (1993). “Algorithm 715: SPECFUN – A Portable FORTRAN Package of Special Function Routines and Test Drivers.” ACM Transactions on Mathematical Software, 19(1), 22–30. doi:10.1145/151271.151273.

Johnson NL, Kotz S, Balakrishnan N (1994). Continuous Univariate Distributions, volume 1, 2nd edition. Wiley, New York. ISBN 978-0-471-58495-7.

Wichura MJ (1988). “Algorithm AS 241: The Percentage Points of the Normal Distribution.” Applied Statistics, 37(3), 477–484. doi:10.2307/2347330.

Examples

n <- 5L
x <- c(-1, 0, 1)
if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  dnorm_opencl(x, mean = 0, sd = 1, fallback = FALSE, verbose = TRUE)
  pnorm_opencl(q = 0.2, mean = 0, sd = 1, fallback = FALSE, verbose = TRUE)
  qnorm_opencl(rep(0.8, n), mean = 0, sd = 1, fallback = FALSE, verbose = TRUE)
  rnorm_opencl(n, mean = 0, sd = 1, fallback = FALSE, verbose = TRUE)
} else {
  stats::dnorm(x, mean = 0, sd = 1)
  stats::pnorm(0.2, mean = 0, sd = 1)
  stats::qnorm(rep(0.8, n), mean = 0, sd = 1)
  stats::rnorm(n, mean = 0, sd = 1)
}

The Poisson Distribution (OpenCL)

Description

OpenCL-backed density, distribution, quantile, and random generation wrappers for the Poisson distribution.

Usage

dpois_raw_opencl(
  x,
  lambda,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

dpois_opencl(
  x,
  lambda,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

ppois_opencl(
  q,
  lambda,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

qpois_opencl(
  p,
  lambda,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

rpois_opencl(n, lambda, fallback = FALSE, verbose = FALSE)

Arguments

Value

Numeric vector result from the corresponding Poisson-family operation.

References

Ahrens JH, Dieter U (1982). “Computer Generation of Poisson Deviates from Modified Normal Distributions.” ACM Transactions on Mathematical Software, 8(2), 163–179. doi:10.1145/355993.355997.

Examples

n <- 5L
if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  dpois_raw_opencl(rep(4, n), lambda = 4, fallback = FALSE, verbose = TRUE)
  dpois_opencl(rep(4, n), lambda = 4, fallback = FALSE, verbose = TRUE)
  ppois_opencl(q = 4, lambda = 4, fallback = FALSE, verbose = TRUE)
  qpois_opencl(rep(0.8, n), lambda = 4, fallback = FALSE, verbose = TRUE)
  rpois_opencl(n, lambda = 4, fallback = FALSE, verbose = TRUE)
} else {
  stats::dpois(rep(4, n), lambda = 4)
  stats::dpois(rep(4, n), lambda = 4)
  stats::ppois(4, lambda = 4)
  stats::qpois(rep(0.8, n), lambda = 4)
  stats::rpois(n, lambda = 4)
}

The Student t Distribution (OpenCL)

Description

OpenCL-backed density, distribution, quantile, and random generation wrappers for the Student t distribution.

Usage

dt_opencl(
  x,
  df,
  ncp = 0,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

pt_opencl(
  q,
  df,
  ncp = 0,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

qt_opencl(
  p,
  df,
  ncp = 0,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

rt_opencl(n, df, fallback = FALSE, verbose = FALSE)

Arguments

Value

For dt_opencl, qt_opencl, rt_opencl: numeric vector result. For pt_opencl: numeric vector of recycled length (see stats::pt).

Known OpenCL limitations

Some platforms fail to link qnt_kernel (ptxas unresolved Rf_qnt). Runnable examples omit GPU qt_opencl until resolved. See ‘inst/OPENCL_KERNEL_KNOWN_FAILURES.md’.

References

Becker RA, Chambers JM, Wilks AR (1988). The New S Language. Chapman and Hall/CRC, London. ISBN 053409192X.

Hill GW (1970). “ACM Algorithm 395: Student's t-Distribution.” Communications of the ACM, 13(10), 617–619. doi:10.1145/355598.355599.

Hill GW (1981). “Remark on “Algorithm 396: Student's t-Quantiles”.” ACM Transactions on Mathematical Software, 7(2), 250–251. doi:10.1145/355945.355956.

Johnson NL, Kotz S, Balakrishnan N (1995). Continuous Univariate Distributions, volume 2, 2nd edition. Wiley, New York. ISBN 978-0-471-58494-0.

Lenth RV (1989). “Algorithm AS 243: Cumulative Distribution Function of the Non-Central t Distribution.” Applied Statistics, 38(1), 185–189. doi:10.2307/2347693.

Examples

n <- 5L
if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  dt_opencl(rep(1.5, n), df = 8, ncp = 0, fallback = FALSE, verbose = TRUE)
  dt_opencl(rep(1.5, n), df = 8, ncp = 1.2, fallback = FALSE, verbose = TRUE)
  pt_opencl(q = 1.5, df = 8, ncp = 0, fallback = FALSE, verbose = TRUE)
  pt_opencl(q = 1.5, df = 8, ncp = 1.2, fallback = FALSE, verbose = TRUE)
  ## qt_opencl: disabled — see inst/OPENCL_KERNEL_KNOWN_FAILURES.md
  rt_opencl(n, df = 8, fallback = FALSE, verbose = TRUE)
} else {
  stats::dt(rep(1.5, n), df = 8, ncp = 0)
  stats::dt(rep(1.5, n), df = 8, ncp = 1.2)
  stats::pt(1.5, df = 8, ncp = 0)
  stats::pt(1.5, df = 8, ncp = 1.2)
  stats::rt(n, df = 8)
}

The Uniform Distribution (OpenCL)

Description

OpenCL-backed density, distribution, quantile, and random generation wrappers for the uniform distribution. These mirror the base stats uniform family while adding OpenCL dispatch and optional CPU fallback behavior.

Usage

dunif_opencl(
  x,
  min = 0,
  max = 1,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

punif_opencl(
  q,
  min = 0,
  max = 1,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

qunif_opencl(
  p,
  min = 0,
  max = 1,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

runif_opencl(n, min = 0, max = 1, fallback = FALSE, verbose = FALSE)

Arguments

Value

Numeric vector result from the corresponding uniform-family operation.

Known OpenCL limitations

Some platforms fail to link qunif_kernel (ptxas unresolved Rf_qunif). Runnable examples omit GPU qunif_opencl until resolved. See ‘inst/OPENCL_KERNEL_KNOWN_FAILURES.md’.

References

Becker RA, Chambers JM, Wilks AR (1988). The New S Language. Chapman and Hall/CRC, London. ISBN 053409192X.

Examples

n <- 5L
if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  dunif_opencl(rep(0.4, n), min = 0, max = 1, fallback = FALSE, verbose = TRUE)
  punif_opencl(q = 0.4, min = 0, max = 1, fallback = FALSE, verbose = TRUE)
  ## qunif_opencl: disabled — see inst/OPENCL_KERNEL_KNOWN_FAILURES.md
  runif_opencl(n, min = 0, max = 1, fallback = FALSE, verbose = TRUE)
} else {
  stats::dunif(rep(0.4, n), min = 0, max = 1)
  stats::punif(0.4, min = 0, max = 1)
  stats::runif(n, min = 0, max = 1)
}

The Weibull Distribution (OpenCL)

Description

OpenCL-backed density, distribution, quantile, and random generation wrappers for the Weibull distribution.

Usage

dweibull_opencl(
  x,
  shape,
  scale = 1,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

pweibull_opencl(
  q,
  shape,
  scale = 1,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

qweibull_opencl(
  p,
  shape,
  scale = 1,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

rweibull_opencl(n, shape, scale = 1, fallback = FALSE, verbose = FALSE)

Arguments

Value

Numeric vector result from the corresponding Weibull-family operation.

References

Johnson NL, Kotz S, Balakrishnan N (1994). Continuous Univariate Distributions, volume 1, 2nd edition. Wiley, New York. ISBN 978-0-471-58495-7.

Examples

n <- 5L
if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  dweibull_opencl(rep(1.2, n), shape = 2, scale = 1.5, fallback = FALSE, verbose = TRUE)
  pweibull_opencl(q = 1.2, shape = 2, scale = 1.5, fallback = FALSE, verbose = TRUE)
  qweibull_opencl(rep(0.8, n), shape = 2, scale = 1.5, fallback = FALSE, verbose = TRUE)
  rweibull_opencl(n, shape = 2, scale = 1.5, fallback = FALSE, verbose = TRUE)
} else {
  stats::dweibull(rep(1.2, n), shape = 2, scale = 1.5)
  stats::pweibull(1.2, shape = 2, scale = 1.5)
  stats::qweibull(rep(0.8, n), shape = 2, scale = 1.5)
  stats::rweibull(n, shape = 2, scale = 1.5)
}

Extract a Minimal Library Subset for a Set of Kernels

Description

Given one or more kernel .cl files and a library directory, determines the minimal set of library files required (union of all kernels' dependency annotations) and copies them — in dependency order — to a destination directory.

Usage

extract_library_subset(
  kernel_paths,
  library_dir,
  dest_dir,
  depends_tag = "all_depends",
  index = NULL,
  overwrite = FALSE
)

Arguments

Details

Use this to populate a project-local copy containing only the library files actually needed by your kernels. The result can then be committed alongside your kernel files, removing a runtime dependency on the full library.

Bundled libraries such as ⁠inst/cl/nmath⁠ ship kernel_dependency_index.rds next to their .cl shards. Pass index = when you pass a pre-loaded index object to avoid redundant reads; regenerate the files with write_kernel_dependency_index, for example after porting via ⁠nmathtools/port_inst_cl_nmath_from_src.R⁠ in the openclport package source tree.

lib_dir <- system.file("cl/nmath", package = "opencltools")
kernel_paths <- system.file(
  c("cl/src/dnorm_kernel.cl", "cl/src/pnorm_kernel.cl"),
  package = "opencltools"
)
dest_dir <- tempfile("ex_subset"); dir.create(dest_dir)
## on.exit(unlink(dest_dir, recursive = TRUE), add = TRUE)
result <- extract_library_subset(
  kernel_paths, lib_dir, dest_dir,
  depends_tag = "all_depends_nmath")

⁠extract_library_subset()⁠ evaluates ⁠inst/extdata/opencl_known_failures.json⁠ against the union of depends_tag annotations and launcher paths.

Value

A ⁠nmathopencl_lib_extract_df⁠ subclass of ⁠data.frame⁠ with one row per library shard (.cl files in dependency order, followed by companion index files when planned or copied) and columns:

stem

Stem name (filename without .cl), or index filenames.

source

Full path to the source file under library_dir.

dest

Intended destination path under dest_dir.

copied

TRUE if copied; otherwise FALSE including when dest_dir is missing (copied = FALSE for every row), a source path is missing, or an existing destination was skipped.

See Also

printing methods

load_library_for_kernel

write_kernel_dependency_index

Other OpenCL kernel library subsets: load_library_for_kernel(), write_kernel_dependency_index()

Examples

############################ Start of extract_library_subset example #########################

## Small library (fast; runs on CRAN check)
lib_small <- system.file("cl/nmath_small", package = "opencltools")
kpath     <- system.file("cl/src/dnorm_kernel.cl", package = "opencltools")
idx_small <- write_kernel_dependency_index(library_dir = lib_small, write = FALSE)
dest_small <- file.path(tempdir(), "opencltools_extract_small")
if (dir.exists(dest_small)) unlink(dest_small, recursive = TRUE)
dir.create(dest_small, recursive = TRUE)
on.exit(unlink(dest_small, recursive = TRUE), add = TRUE)
df_small <- extract_library_subset(
  kpath, lib_small, dest_small,
  depends_tag = "all_depends_nmath",
  index       = idx_small
)
sum(df_small$copied)


## Full nmath (slow)
lib_dir <- system.file("cl/nmath", package = "opencltools")
kernel_paths <- system.file(
  c("cl/src/dnorm_kernel.cl", "cl/src/pnorm_kernel.cl"),
  package = "opencltools"
)
idx <- write_kernel_dependency_index(library_dir = lib_dir, write = FALSE)
dest_dir <- file.path(tempdir(), "opencltools_extract_example")
if (dir.exists(dest_dir)) unlink(dest_dir, recursive = TRUE)
dir.create(dest_dir, recursive = TRUE)
on.exit(unlink(dest_dir, recursive = TRUE), add = TRUE)
df <- extract_library_subset(
  kernel_paths, lib_dir, dest_dir,
  depends_tag = "all_depends_nmath",
  index       = idx
)
print(df)
sum(df$copied)


###############################################################################
## End of extract_library_subset example
###############################################################################

Special Functions (OpenCL)

Description

OpenCL-backed wrappers for selected special functions from R Mathlib.

Usage

gammafn_opencl(x, fallback = FALSE, verbose = FALSE)

lgammafn_opencl(x, fallback = FALSE, verbose = FALSE)

digamma_opencl(x, fallback = FALSE, verbose = FALSE)

trigamma_opencl(x, fallback = FALSE, verbose = FALSE)

tetragamma_opencl(x, fallback = FALSE, verbose = FALSE)

pentagamma_opencl(x, fallback = FALSE, verbose = FALSE)

psigamma_opencl(x, deriv, fallback = FALSE, verbose = FALSE)

beta_opencl(a, b, fallback = FALSE, verbose = FALSE)

lbeta_opencl(a, b, fallback = FALSE, verbose = FALSE)

choose_opencl(n, k, fallback = FALSE, verbose = FALSE)

lchoose_opencl(n, k, fallback = FALSE, verbose = FALSE)

Arguments

Value

Numeric vector of recycled common length.

References

Abramowitz M, Stegun IA (1972). Handbook of Mathematical Functions with Formulas, Graphs, and Mathematical Tables. Dover Publications, New York. ISBN 0486612724.

Amos DE (1983). “Algorithm 610: A Portable FORTRAN Subroutine for Derivatives of the Psi Function.” ACM Transactions on Mathematical Software, 9(4), 494–502. doi:10.1145/356056.356065.

Becker RA, Chambers JM, Wilks AR (1988). The New S Language. Chapman and Hall/CRC, London. ISBN 053409192X.

Examples

if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  gammafn_opencl(x = 2.5, fallback = FALSE, verbose = TRUE)
  lgammafn_opencl(x = 2.5, fallback = FALSE, verbose = TRUE)
  digamma_opencl(x = 2.5, fallback = FALSE, verbose = TRUE)
  trigamma_opencl(x = 2.5, fallback = FALSE, verbose = TRUE)
  tetragamma_opencl(x = 2.5, fallback = FALSE, verbose = TRUE)
  pentagamma_opencl(x = 2.5, fallback = FALSE, verbose = TRUE)
  psigamma_opencl(x = 2.5, deriv = 1, fallback = FALSE, verbose = TRUE)

  beta_opencl(a = 2.5, b = 3.0, fallback = FALSE, verbose = TRUE)
  lbeta_opencl(a = 2.5, b = 3.0, fallback = FALSE, verbose = TRUE)
  choose_opencl(n = 10, k = 4, fallback = FALSE, verbose = TRUE)
  lchoose_opencl(n = 10, k = 4, fallback = FALSE, verbose = TRUE)
} else {
  base::gamma(2.5)
  base::lgamma(2.5)
  base::digamma(2.5)
  base::trigamma(2.5)
  base::psigamma(2.5, deriv = 2L)
  base::psigamma(2.5, deriv = 3L)
  base::psigamma(2.5, deriv = 1L)
  base::beta(2.5, 3.0)
  base::lbeta(2.5, 3.0)
  base::choose(10, 4)
  base::lchoose(10, 4)
}

Envelope Evaluation Utilities

Description

Core utilities for envelope-based posterior simulation using GPU-accelerated OpenCL kernels. These functions support the construction and evaluation of log-likelihood envelopes used in rejection sampling, and serve as an example of how downstream packages can build custom OpenCL kernels on top of the ported nmath routines in nmathopencl.

References

There are no references for Rd macro ⁠\insertAllCites⁠ on this help page.

Math Support Functions (OpenCL)

Description

OpenCL-backed wrappers for miscellaneous scalar support functions.

Usage

imax2_opencl(x, y, fallback = FALSE, verbose = FALSE)

imin2_opencl(x, y, fallback = FALSE, verbose = FALSE)

fmax2_opencl(x, y, fallback = FALSE, verbose = FALSE)

fmin2_opencl(x, y, fallback = FALSE, verbose = FALSE)

sign_opencl(x, fallback = FALSE, verbose = FALSE)

fprec_opencl(x, digits, fallback = FALSE, verbose = FALSE)

fround_opencl(x, digits, fallback = FALSE, verbose = FALSE)

fsign_opencl(x, y, fallback = FALSE, verbose = FALSE)

ftrunc_opencl(x, fallback = FALSE, verbose = FALSE)

Arguments

Value

Numeric vector of recycled common length.

References

Abramowitz M, Stegun IA (1972). Handbook of Mathematical Functions with Formulas, Graphs, and Mathematical Tables. Dover Publications, New York. ISBN 0486612724.

Becker RA, Chambers JM, Wilks AR (1988). The New S Language. Chapman and Hall/CRC, London. ISBN 053409192X.

Examples

if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  imax2_opencl(x = 7, y = 3, fallback = FALSE, verbose = TRUE)
  imin2_opencl(x = 7, y = 3, fallback = FALSE, verbose = TRUE)
  fmax2_opencl(x = 7.2, y = 3.1, fallback = FALSE, verbose = TRUE)
  fmin2_opencl(x = 7.2, y = 3.1, fallback = FALSE, verbose = TRUE)
  sign_opencl(x = -2.5, fallback = FALSE, verbose = TRUE)
  fprec_opencl(x = 123.456, digits = 4, fallback = FALSE, verbose = TRUE)
  fround_opencl(x = 123.456, digits = 2, fallback = FALSE, verbose = TRUE)
  fsign_opencl(x = -2.5, y = 4.0, fallback = FALSE, verbose = TRUE)
  ftrunc_opencl(x = 123.456, fallback = FALSE, verbose = TRUE)
} else {
  as.double(pmax(7L, 3L))
  as.double(pmin(7L, 3L))
  pmax(7.2, 3.1)
  pmin(7.2, 3.1)
  base::sign(-2.5)
  signif(123.456, digits = 4)
  base::round(123.456, digits = 2)
  base::sign(-2.5) * abs(4.0)
  base::trunc(123.456)
}

Load a Minimal OpenCL Library Subset for a Single Kernel

Description

Given a single kernel .cl file and a library directory (with an associated dependency index), reads the annotation tag that lists needed library files and returns their source code concatenated in the correct dependency order.

Usage

load_library_for_kernel(
  kernel_path,
  library_dir,
  depends_tag = "all_depends",
  index = NULL
)

Arguments

Details

For repeated calls in R code, loading kernel_dependency_index.rds once and passing index = avoids redundant disk reads. The bundled ⁠cl/nmath⁠ directory ships kernel_dependency_index.rds beside the .cl files; use write_kernel_dependency_index to regenerate it after porting (for example via ⁠nmathtools/port_inst_cl_nmath_from_src.R⁠ in the openclport package source tree).

lib_dir <- system.file("cl/nmath", package = "opencltools")
kpath <- system.file("cl/src/dnorm_kernel.cl", package = "opencltools")
src <- load_library_for_kernel(
  kpath, lib_dir,
  depends_tag = "all_depends_nmath")

Subsets come only from each launcher file's transitive @all_depends_nmath-style annotations (use attach_cross_library_tags where dependency graphs span libraries). Deliberately loading every ⁠.cl⁠ under ⁠cl/nmath⁠ remains available via load_kernel_library(..., "nmath") where appropriate.

When ⁠inst/extdata/opencl_known_failures.json⁠ matches the launcher path or the declared / loaded stems, warning(...) points to fragile ports.

Value

A character vector subclass ⁠nmathopencl_concatenated_lib⁠ holding concatenated sources (often length 1; blank annotations yield length-zero concatenation). Attachments describe requested and loaded library stems, paths, and byte size; see print methods.

See Also

extract_library_subset

printing methods

write_kernel_dependency_index

Other OpenCL kernel library subsets: extract_library_subset(), write_kernel_dependency_index()

Examples

############################ Start of load_library_for_kernel example ########################

## Small library (fast; runs on CRAN check)
lib_small <- system.file("cl/nmath_small", package = "opencltools")
kpath     <- system.file("cl/src/dnorm_kernel.cl", package = "opencltools")
idx_small <- write_kernel_dependency_index(library_dir = lib_small, write = FALSE)
src_small <- load_library_for_kernel(
  kpath, lib_small,
  depends_tag = "all_depends_nmath",
  index       = idx_small
)
nzchar(src_small)


## Full nmath (slow; rebuilds index over all shards)
lib_dir <- system.file("cl/nmath", package = "opencltools")
idx   <- write_kernel_dependency_index(library_dir = lib_dir, write = FALSE)
src <- load_library_for_kernel(
  kpath, lib_dir,
  depends_tag = "all_depends_nmath",
  index       = idx
)
print(src)
nzchar(src)


###############################################################################
## End of load_library_for_kernel example
###############################################################################

GPU and OpenCL diagnostics for nmathopencl

Description

Compile-time and device-selection probes for nmathopencl.

Low-level workstation probes (GPU vendor detection, driver and ICD checks, PATH validation, verify_opencl_runtime(), PATH helpers, combined diagnostic reports, etc.) live in opencltools; call them as opencltools::detect_environment_and_gpus(), opencltools::diagnose_glmbayes(), and related topics documented under ?opencltools.

Usage

nmathopencl_has_opencl()

nmathopencl_opencl_device_info(force = FALSE, details = FALSE)

nmathopencl_opencl_fp64_available(force = FALSE)

nmathopencl_opencl_reset_device_selection()

Arguments

Details

GPU acceleration uses OpenCL kernels and *_opencl wrappers when nmathopencl_has_opencl() is TRUE and a suitable device is available ((Stone et al. 2010)). CPU fallbacks apply for many routines when OpenCL is absent at compile time or runtime.

For a readable host/runtime report, use opencltools::diagnose_glmbayes(); use nmathopencl_has_opencl() for this package's compile-time flag. Setup: vignette("Chapter-01", package = "nmathopencl"); packaged GPU API: vignette("Chapter-12", package = "nmathopencl").

Value

A list with ok (logical), reason (character), indices, vendor/name strings, device_type, extension_cl_khr_fp64, probe_fp64_ok, selection_policy, and optionally candidates.

Functions

• nmathopencl_opencl_device_info(): Cached OpenCL device selection for double-precision (cl_khr_fp64) kernels in nmathopencl: enumerates platforms and devices, prefers GPU, checks the extension token, then verifies with a tiny clBuildProgram probe. Override with environment variables NMATHOPENCL_PLATFORM_INDEX and/or NMATHOPENCL_DEVICE_INDEX (0-based; device index is within the platform's device list). Use nmathopencl_opencl_reset_device_selection() to clear the cache (e.g. after driver changes).

• nmathopencl_opencl_fp64_available(): Returns TRUE if a cached OpenCL device passes the cl_khr_fp64 extension check and build probe used for double kernels in nmathopencl (uses this package's compile-time OpenCL build and device cache, not opencltools).

• nmathopencl_opencl_reset_device_selection(): Clears the process-local OpenCL device selection cache so the next kernel or nmathopencl_opencl_device_info() run re-enumerates devices.

Diagnostics exported from nmathopencl

• nmathopencl_has_opencl() — TRUE if this build was compiled with OpenCL support.

• nmathopencl_opencl_device_info(), nmathopencl_opencl_fp64_available() — cached double-precision device selection for kernels.

• nmathopencl_opencl_reset_device_selection() — clear device cache.

• opencltools::get_opencl_core_count() — compute units on the opencltools default device.

Host / runtime checks (opencltools)

• detect_environment_and_gpus()

• detect_compute_runtimes()

• verify_opencl_runtime()

• check_runtime_env()

• opencltools::diagnose_glmbayes()

• add_to_path_windows() and related PATH helpers

References

Stone JE, Gohara D, Shi G (2010). “OpenCL: A Parallel Programming Standard for Heterogeneous Computing Systems.” Computing in Science & Engineering, 12(3), 66–72. doi:10.1109/MCSE.2010.69.

See Also

nmathopencl_has_opencl, nmathopencl_opencl_device_info, opencltools.

OpenCL-backed RNG Core linkage checks

Description

Linkage wrappers for core RNG primitives used by translated Mathlib paths.

Usage

norm_rand_opencl(n, fallback = FALSE, verbose = FALSE)

unif_rand_opencl(n, fallback = FALSE, verbose = FALSE)

r_unif_index_opencl(n, dn, fallback = FALSE, verbose = FALSE)

exp_rand_opencl(n, fallback = FALSE, verbose = FALSE)

Arguments

Value

Numeric vector of length n.

Examples

n <- 5L
if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  norm_rand_opencl(n, fallback = FALSE, verbose = TRUE)
  unif_rand_opencl(n, fallback = FALSE, verbose = TRUE)
  r_unif_index_opencl(n, dn = 10, fallback = FALSE, verbose = TRUE)
  exp_rand_opencl(n, fallback = FALSE, verbose = TRUE)
} else {
  stats::rnorm(n)
  stats::runif(n)
  floor(stats::runif(n, min = 0, max = 10))
  stats::rexp(n)
}

Port an existing static src/Makevars to use OpenCL configure scripts

Description

Migrates a package that already has a static committed src/Makevars (and optionally src/Makevars.win) to the configure-script pattern required for CRAN-safe OpenCL support.

The function renames the existing src/Makevars to src/Makevars.in (the maintained source template) and generates configure (Linux/macOS) and configure.win (Windows) scripts that read src/Makevars.in at R CMD INSTALL time, run OpenCL detection, and write the final src/Makevars with OpenCL flags merged in – or copied verbatim from src/Makevars.in for CPU-only builds.

The generated scripts always succeed: if no OpenCL SDK is found the package installs cleanly as CPU-only. This is the property that makes packages safe for CRAN submission on build machines without a GPU SDK.

For packages with no existing src/Makevars, use use_opencl_configure instead. This function is for migrating an existing static Makevars.

Usage

port_to_opencl_configure(path = ".", backup = TRUE, overwrite = FALSE)

Arguments

Value

Invisibly returns a character vector of the file paths written.

src/Makevars.in workflow

After porting, maintain src/Makevars.in for your base build flags (OpenMP, RcppParallel, LAPACK, etc.). The configure script reads it at install time and appends (or omits) the OpenCL flags. The generated src/Makevars is a build artifact – add it to .gitignore and never commit it. To update base flags, edit src/Makevars.in and reinstall.

configure -> USE_OPENCL -> has_opencl()

  configure / configure.win
    -> reads src/Makevars.in for base flags
    -> detects CL/cl.h + libOpenCL (+ runtime probe on Linux)
    -> writes -DUSE_OPENCL into Makevars  (or copies .in verbatim)

  #ifdef USE_OPENCL in C++ source
    -> guards all GPU code; package compiles cleanly either way

  has_opencl() in R
    -> mirrors the compile-time flag; TRUE only if USE_OPENCL was set

Limitations

• += (append) assignments in src/Makevars are detected and trigger a warning; review the generated configure carefully.

• If src/Makevars looks like a generated file (contains absolute paths, -lOpenCL, or -DUSE_OPENCL), the function warns. Run on the static committed file, not a build artifact.

• Packages that already have configure or configure.win are refused unless overwrite = TRUE. Users with existing configure scripts should integrate the OpenCL block manually; see system.file("configure-templates", "README.md", package = "opencltools").

See Also

use_opencl_configure for packages without an existing src/Makevars. vignette("Chapter-02", package = "nmathopencl") in nmathopencl for a full guide when building on the ported nmath kernel library.

Examples

############################ Start of port_to_opencl_configure example ########################

tmp <- tempfile("port_opencl_pkg")
dir.create(tmp)
dir.create(file.path(tmp, "src"))
on.exit(unlink(tmp, recursive = TRUE), add = TRUE)

writeLines(
  c(
    "PKG_CXXFLAGS = $(SHLIB_OPENMP_CXXFLAGS)",
    "PKG_LIBS = $(LAPACK_LIBS) $(BLAS_LIBS) $(FLIBS)"
  ),
  file.path(tmp, "src", "Makevars")
)

written <- port_to_opencl_configure(path = tmp, backup = TRUE)
written
file.exists(file.path(tmp, "configure"))
file.exists(file.path(tmp, "src", "Makevars.in"))

## Regenerate configure scripts after editing Makevars.in (same temp tree)
written2 <- port_to_opencl_configure(path = tmp, backup = FALSE, overwrite = TRUE)
length(written2)

###############################################################################
## End of port_to_opencl_configure example
###############################################################################

The Studentized Range Distribution (OpenCL)

Description

OpenCL-backed distribution and quantile wrappers for the studentized range (Tukey) distribution.

Usage

ptukey_opencl(
  q,
  nmeans,
  df,
  nranges = 1,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

qtukey_opencl(
  p,
  nmeans,
  df,
  nranges = 1,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

Arguments

Value

Numeric vector result from ptukey_opencl or qtukey_opencl.

References

Copenhaver MD, Holland BS (1988). “Computation of the Distribution of the Maximum Studentized Range Statistic with Application to Multiple Significance Testing of Simple Effects.” Journal of Statistical Computation and Simulation, 30(1), 1–15. doi:10.1080/00949658808811082.

Odeh RE, Evans JO (1974). “Algorithm AS 70: The Percentage Points of the Normal Distribution.” Applied Statistics, 23(1), 96–97. doi:10.2307/2347061.

Examples

n <- 1L
if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  ptukey_opencl(q = 3.4, nmeans = 5, df = 10, nranges = 1, fallback = FALSE, verbose = TRUE)
  qtukey_opencl(rep(0.8, n), nmeans = 5, df = 10, nranges = 1, fallback = FALSE, verbose = TRUE)
} else {
  stats::ptukey(3.4, nmeans = 5, df = 10, nranges = 1)
  stats::qtukey(rep(0.8, n), nmeans = 5, df = 10, nranges = 1)
}

OpenCL-backed R_ext runtime utility linkage checks

Description

Wrappers for utility hooks used by translated R_ext-dependent kernels.

Usage

r_check_user_interrupt_opencl(n, fallback = FALSE, verbose = FALSE)

Arguments

Value

Numeric vector of length n.

Known OpenCL limitations

The stack-check linkage wrapper can fail in device compilation or runtime due to missing host/runtime stack symbols, so it is not exported.

Examples

n <- 5L
if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  r_check_user_interrupt_opencl(n, fallback = FALSE, verbose = TRUE)
} else {
  as.numeric(seq_len(n))
}

OpenCL-backed R Math runtime linkage checks

Description

Wrappers for low-level Mathlib runtime helpers used by translated kernels.

Usage

r_pow_opencl(x, y, fallback = FALSE, verbose = FALSE)

r_pow_di_opencl(x, n_exp, fallback = FALSE, verbose = FALSE)

log1pmx_opencl(x, fallback = FALSE, verbose = FALSE)

log1pexp_opencl(x, fallback = FALSE, verbose = FALSE)

log1mexp_opencl(x, fallback = FALSE, verbose = FALSE)

lgamma1p_opencl(x, fallback = FALSE, verbose = FALSE)

pow1p_opencl(x, y, fallback = FALSE, verbose = FALSE)

logspace_add_opencl(logx, logy, fallback = FALSE, verbose = FALSE)

logspace_sub_opencl(logx, logy, fallback = FALSE, verbose = FALSE)

logspace_sum_opencl(logx, logy, fallback = FALSE, verbose = FALSE)

Arguments

Details

On the GPU path, arguments are recycled to a common length len (maximum argument length, R recycling rules). Each output index runs one scalar kernel launch.

Value

Numeric vector of the recycled common length (see Details).

Examples

if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  r_pow_opencl(x = 1.2, y = 2, fallback = FALSE, verbose = TRUE)
  r_pow_di_opencl(x = 1.2, n_exp = 3L, fallback = FALSE, verbose = TRUE)
  log1pmx_opencl(x = 0.2, fallback = FALSE, verbose = TRUE)
  log1pexp_opencl(x = 0.2, fallback = FALSE, verbose = TRUE)
  log1mexp_opencl(x = 0.5, fallback = FALSE, verbose = TRUE)
  lgamma1p_opencl(x = 0.2, fallback = FALSE, verbose = TRUE)
  pow1p_opencl(x = 0.2, y = 3, fallback = FALSE, verbose = TRUE)
  logspace_add_opencl(logx = -2, logy = -3, fallback = FALSE, verbose = TRUE)
  logspace_sub_opencl(logx = -2, logy = -3, fallback = FALSE, verbose = TRUE)
  logspace_sum_opencl(logx = -2, logy = -3, fallback = FALSE, verbose = TRUE)
  log1pmx_opencl(x = seq(-0.5, 0.5, by = 0.25), fallback = FALSE, verbose = TRUE)
} else {
  (1.2 + seq_len(1L) * 1e-3)^2
  1.2^3
  log1p(0.2) - 0.2
  ifelse(0.2 > 0, 0.2 + log1p(exp(-0.2)), log1p(exp(0.2)))
  ifelse(0.5 <= log(2), log(-expm1(-0.5)), log1p(-exp(-0.5)))
  lgamma(1.2)
  exp(3 * log1p(0.2))
  {
    m <- max(-2, -3)
    m + log1p(exp(min(-2, -3) - m))
  }
  -2 + log1p(-exp(-3 - (-2)))
  {
    m <- max(-2, -3)
    m + log1p(exp(min(-2, -3) - m))
  }
  {
    xv <- seq(-0.5, 0.5, by = 0.25)
    log1p(xv) - xv
  }
}

The Multinomial Distribution (OpenCL linkage subset)

Description

OpenCL-backed linkage wrapper for multinomial sampling. The current OpenCL kernel supports a 2-category multinomial parameterization via scalar prob, and returns a 2 x n count matrix.

Usage

rmultinom_opencl(n, size, prob, fallback = FALSE, verbose = FALSE)

Arguments

Value

Integer matrix with 2 rows and n columns.

Examples

n <- 5L
if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  rmultinom_opencl(n, size = 12L, prob = 0.4, fallback = FALSE, verbose = TRUE)
} else {
  stats::rmultinom(n, size = 12L, prob = c(0.4, 0.6))
}

Stage Kernel Library Dependency Sort Results

Description

Run the file-level ⁠@depends⁠ sort without requiring full success. Files that can be sorted are copied in order, and files blocked by unresolved dependencies are copied into a separate folder with CSV reports.

Usage

stage_kernel_dependency_sort(library_dir, output_dir, overwrite = FALSE)

Arguments

Value

A named list with:

sorted

Data frame of files placed in dependency order (order, pass, file, source_type, depends).

unresolved

Data frame of files blocked by missing dependencies.

sorted_dir, unresolved_dir

Output directory paths; CSV reports ‘sorted_files.csv’ and ‘unresolved_files.csv’ are written under output_dir.

Examples

############################ Start of stage_kernel_dependency_sort example ########################

lib_dir    <- system.file("cl/ex_glmbayes_nmath", package = "opencltools")
output_dir <- tempfile("stage_sort")
on.exit(unlink(output_dir, recursive = TRUE), add = TRUE)

res <- stage_kernel_dependency_sort(lib_dir, output_dir, overwrite = TRUE)
nrow(res$sorted)
length(list.files(output_dir, recursive = TRUE))

###############################################################################
## End of stage_kernel_dependency_sort example
###############################################################################

Set up OpenCL configure scripts in a downstream R package

Description

Copies generic OpenCL configure and configure.win scripts to the root directory of a package. The scripts detect CL/cl.h and libOpenCL at compile time and generate src/Makevars (Linux / macOS) or src/Makevars.win (Windows) with or without -DUSE_OPENCL, depending on what is found.

The scripts always succeed. When no OpenCL SDK is present they produce a CPU-only Makevars with no -lOpenCL. This is the key property that makes packages safe for CRAN submission without requiring a GPU SDK on the build machine.

Usage

use_opencl_configure(path = ".", overwrite = FALSE)

Arguments

Value

Invisibly returns a character vector of the file paths that were written (empty if all files were skipped).

Why configure scripts are necessary

A package that references -lOpenCL or CL/cl.h in a static src/Makevars will fail to compile on 'CRAN' build machines (which have no GPU SDK installed), and no binary will be produced. The configure scripts here avoid this by probing for the SDK at install time and falling back to a CPU-only build when it is absent. The relationship is:

  configure / configure.win
    -> detects CL/cl.h + libOpenCL
    -> writes -DUSE_OPENCL into Makevars   (or omits it)

  #ifdef USE_OPENCL in C++ source
    -> guards all GPU code; package compiles cleanly either way

  has_opencl() in R
    -> mirrors the compile-time flag; returns TRUE only if USE_OPENCL was set

See Also

port_to_opencl_configure for packages with an existing static src/Makevars. opencltoolsLdFlags for linking against this package from C++. vignette("Chapter-02", package = "nmathopencl") in nmathopencl for a full downstream package guide when using the ported nmath kernel library. Template source: system.file("configure-templates", package = "opencltools").

Examples

############################ Start of use_opencl_configure example ########################

tmp <- tempfile("use_opencl_pkg")
dir.create(tmp)
on.exit(unlink(tmp, recursive = TRUE), add = TRUE)

written <- use_opencl_configure(path = tmp)
written
file.exists(file.path(tmp, "configure"))
file.exists(file.path(tmp, "configure.win"))

## Overwrite path (same temp tree; safe when run.dontest = TRUE)
written2 <- use_opencl_configure(path = tmp, overwrite = TRUE)
length(written2)

###############################################################################
## End of use_opencl_configure example
###############################################################################

Build and save a kernel dependency index

Description

Writes two companion index files next to the .cl files in the kernel library directory:

Usage

write_kernel_dependency_index(
  library_dir = NULL,
  tags = NULL,
  output_path = NULL,
  write = TRUE,
  verbose = FALSE
)

Arguments

Details

• RDS helper shard for loaders such as load_library_for_kernel.
  

• Tab-separated (.tsv) stem map for C++ (rows ⁠stem<TAB>dependencies⁠, pre-sorted).
  

Both files encode the same information and are always written together so they remain in sync.

Value

Invisibly, the index list() (version schema):

• version: integer schema version.

• generated_at: timestamp from Sys.time().

• library_dir, library_name: resolved library path / basename.

• stems_ordered: stems in global load order.

• load_order: named integer vector stem -> rank.

• depends: named list stem -> character() (direct ⁠@depends⁠).

• all_depends: named list stem -> character() (transitive dependencies, order consistent with global load order).

• n_files: file count.

See Also

load_library_for_kernel

extract_library_subset

Other OpenCL kernel library subsets: extract_library_subset(), load_library_for_kernel()

Examples

############################ Start of write_kernel_dependency_index example ########################

lib_dir <- system.file("cl/ex_glmbayes_nmath", package = "opencltools")
idx <- write_kernel_dependency_index(library_dir = lib_dir, write = FALSE)
names(idx)
length(idx$stems_ordered)
idx$n_files

###############################################################################
## End of write_kernel_dependency_index example
###############################################################################