Package 'nmathopencl'

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

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
###############################################################################

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
###############################################################################

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
###############################################################################

Description

OpenCL-backed wrappers for Bessel functions.

Usage

besselI_opencl(x, nu, expon.scaled = FALSE, fallback = FALSE, verbose = FALSE)

besselJ_opencl(x, nu, fallback = FALSE, verbose = FALSE)

besselK_opencl(x, nu, expon.scaled = FALSE, fallback = FALSE, verbose = FALSE)

besselY_opencl(x, nu, fallback = FALSE, verbose = FALSE)

Arguments

Value

Numeric vector of recycled common length.

Known OpenCL limitations

Current Bessel OpenCL paths may require temporary-workspace allocation semantics equivalent to host R_alloc/vmax* behavior. On some GPU stacks this can fail at runtime; use fallback = TRUE if you must tolerate failures until device-side workspace handling is implemented.

Examples

if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  # Bessel OpenCL paths currently depend on temporary-workspace allocation
  # behavior (R_alloc/vmax* semantics) not yet fully implemented for device
  # execution. Keep these commented to avoid flaky CI/check failures:
  # n <- 1L
  # besselI_opencl(x = 2.0, nu = 1.5, expon.scaled = FALSE, fallback = FALSE, verbose = TRUE)
  # besselJ_opencl(x = 2.0, nu = 1.5, fallback = FALSE, verbose = TRUE)
  # besselK_opencl(x = 2.0, nu = 1.5, expon.scaled = FALSE, fallback = FALSE, verbose = TRUE)
  # besselY_opencl(x = 2.0, nu = 1.5, fallback = FALSE, verbose = TRUE)
} else {
  besselI(2.0, nu = 1.5)
  besselJ(2.0, nu = 1.5)
  besselK(2.0, nu = 1.5)
  besselY(2.0, nu = 1.5)
}

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
)

qbeta_opencl(
  p,
  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

Non-central tails

qbeta_opencl with ncp > 0 may stress devices.

Build quirks

Rf_lbeta linkage breaks on GPUs; skip GPU demos.
Tracker: ‘inst/OPENCL_KERNEL_KNOWN_FAILURES.md’

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)
  ## qbeta_opencl: disabled — see inst/OPENCL_KERNEL_KNOWN_FAILURES.md
  # qbeta_opencl(rep(0.8, n), 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)
}

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.

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)
}

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.

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)
}

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.

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)
}

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.

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)
}

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.

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)
}

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
)

qgamma_opencl(
  p,
  shape,
  scale = 1,
  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). Runnable examples omit GPU qgamma_opencl until resolved. See ‘inst/OPENCL_KERNEL_KNOWN_FAILURES.md’.

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)
  ## qgamma_opencl: disabled — see inst/OPENCL_KERNEL_KNOWN_FAILURES.md
  # qgamma_opencl(rep(0.8, n), 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)
}

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.

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)
}

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.

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)
}

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.

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)
}

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

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)
}

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.

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)
}

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.

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)
}

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.

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)
}

Description

OpenCL-backed density, distribution, quantile, and random generation wrappers for the Wilcoxon signed rank distribution.

Usage

dsignrank_opencl(
  x,
  nsize,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

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

qsignrank_opencl(
  p,
  nsize,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

rsignrank_opencl(n, nsize, fallback = FALSE, verbose = FALSE)

Arguments

Value

Numeric vector result from the corresponding signed-rank operation.

Known OpenCL limitations

Signed-rank kernels can fail to build on some GPU toolchains due to unresolved runtime allocation symbols (for example R_chk_calloc). Use fallback = TRUE only if you need to tolerate those failures until device-safe shims are complete.

Examples

if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  # Signed-rank OpenCL kernels are currently known to fail on some GPU stacks
  # due to unresolved runtime allocation symbols (e.g., R_chk_calloc).
  # Keeping these commented avoids flaky check failures:
  # n <- 5L
  # dsignrank_opencl(n, x = 6, nsize = 8, fallback = FALSE, verbose = TRUE)
  # psignrank_opencl(q = 6, nsize = 8, fallback = FALSE, verbose = TRUE)
  # qsignrank_opencl(rep(0.8, n), nsize = 8, fallback = FALSE, verbose = TRUE)
  # rsignrank_opencl(n, nsize = 8, fallback = FALSE, verbose = TRUE)
} else {
  n <- 5L
  stats::dsignrank(rep(6, n), n = 8)
  stats::psignrank(6, n = 8)
  stats::qsignrank(rep(0.8, n), n = 8)
  stats::rsignrank(n, n = 8)
}

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

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)
}

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

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)
}

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.

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)
}

Description

OpenCL-backed density, distribution, quantile, and random generation wrappers for the Wilcoxon rank sum distribution.

Usage

dwilcox_opencl(
  x,
  m,
  nn,
  log = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

pwilcox_opencl(
  q,
  m,
  nn,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

qwilcox_opencl(
  p,
  m,
  nn,
  lower.tail = TRUE,
  log.p = FALSE,
  opencl_parallel = NA,
  fallback = FALSE,
  verbose = FALSE
)

rwilcox_opencl(n, m, nn, fallback = FALSE, verbose = FALSE)

Arguments

Value

Numeric vector result from the corresponding Wilcoxon-family operation.

Known OpenCL limitations

Wilcoxon kernels can still hit runtime-shim gaps depending on device and driver stack (for example unresolved runtime symbols in some builds). Defaults follow ⁠fallback = FALSE⁠: OpenCL failures surface unless you pass fallback = TRUE.

Examples

if (!nmathopencl_has_opencl() || identical(Sys.getenv("NOT_CRAN"), "true")) {
  # Wilcoxon OpenCL kernels are currently known to fail on some GPU stacks due
  # to unresolved runtime symbols. Keeping these commented avoids flaky checks:
  # n <- 1L
  # dwilcox_opencl(n, x = 5, m = 5, nn = 7, fallback = FALSE, verbose = TRUE)
  # pwilcox_opencl(q = 5, m = 5, nn = 7, fallback = FALSE, verbose = TRUE)
  # qwilcox_opencl(rep(0.8, n), m = 5, nn = 7, fallback = FALSE, verbose = TRUE)
  #
  # Known allocator/runtime fragility on some stacks:
  # rwilcox_opencl(n, m = 5, nn = 7, fallback = FALSE, verbose = TRUE)
} else {
  n <- 1L
  stats::dwilcox(5, m = 5, n = 7)
  stats::pwilcox(5, m = 5, n = 7)
  stats::qwilcox(rep(0.8, n), m = 5, n = 7)
  stats::rwilcox(n, m = 5, n = 7)
}

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
###############################################################################

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)

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.

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

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.