Package 'amatrix'

Description

Dispatches %*% through the amatrix backend for sparse adgCMatrix objects on the left-hand side, preserving GPU residency metadata across the operation.

Usage

## S4 method for signature 'adgCMatrix,ANY'
x %*% y

## S4 method for signature 'adgCMatrix,matrix'
x %*% y

## S4 method for signature 'adgCMatrix,Matrix'
x %*% y

## S4 method for signature 'adgCMatrix,dgeMatrix'
x %*% y

## S4 method for signature 'adgCMatrix,dgCMatrix'
x %*% y

## S4 method for signature 'adgCMatrix,adgeMatrix'
x %*% y

## S4 method for signature 'adgCMatrix,adgCMatrix'
x %*% y

Arguments

Value

An adgeMatrix or adgCMatrix containing the product, with backend metadata inherited from x.

Examples

sp <- as(matrix(c(1, 0, 0, 2), 2, 2), "dgCMatrix")
A  <- adgCMatrix(sp)
B  <- matrix(1:4, 2, 2)
A %*% B

Description

Scaled matrix multiply with optional bias: alpha*(A%*%B) + beta*C

Usage

addmm(A, B, C = NULL, alpha = 1, beta = 1)

Arguments

Value

adgeMatrix if A is resident, otherwise plain matrix.

Description

Converts a sparse or dense matrix to an adgCMatrix with the specified backend, policy, and precision. This is the primary user-facing constructor for sparse amatrix objects.

Usage

adgCMatrix(
  x,
  mode = NULL,
  backend = NULL,
  preferred_backend = NULL,
  policy = NULL,
  precision = NULL
)

Arguments

Value

An adgCMatrix with the data from x and the requested backend metadata.

Examples

m <- matrix(c(1, 0, 0, 2), nrow = 2)
S <- adgCMatrix(m)
S

Description

adgCMatrix extends both aMatrix and Matrix::dgCMatrix, adding backend-dispatch slots to a compressed-column sparse double-precision matrix.

See Also

adgCMatrix for the user-facing constructor, adgeMatrix-class for the dense counterpart

Description

Converts a base R matrix or Matrix::dgeMatrix to an adgeMatrix with the specified backend, policy, and precision. This is the primary user-facing constructor for dense amatrix objects.

Usage

adgeMatrix(
  x,
  mode = NULL,
  backend = NULL,
  preferred_backend = NULL,
  policy = NULL,
  precision = NULL
)

Arguments

Value

An adgeMatrix with the data from x and the requested backend metadata.

Examples

m <- matrix(1:6, nrow = 2)
A <- adgeMatrix(m)
A

Description

adgeMatrix extends both aMatrix and Matrix::dgeMatrix, adding backend-dispatch slots to a column-major dense double-precision matrix. All arithmetic generics dispatch through the amatrix backend system rather than directly to BLAS.

See Also

adgeMatrix for the user-facing constructor, adgCMatrix for the sparse counterpart

Description

adlgCMatrix extends both aMatrix and Matrix::lgCMatrix, adding backend-dispatch slots to a compressed-column sparse logical matrix.

Description

adlgeMatrix extends both aMatrix and Matrix::lgeMatrix, adding backend-dispatch slots to a column-major dense logical matrix.

Description

Return the index of the maximum or minimum value in each row or column.

Usage

am_rowargmax(x)

am_rowargmin(x)

am_colargmax(x)

am_colargmin(x)

Arguments

Value

An integer vector of indices.

Description

Applies an elementwise arithmetic operation between the handle's resident matrix and either a scalar or another resident handle, replacing the handle's device buffer with the result.

Usage

am_ewise_inplace(h, rhs, op)

Arguments

Value

h, invisibly. The handle is modified in place.

See Also

am_sweep_inplace, resident_handle

Examples

# requires a backend with residency support (e.g. MLX, OpenCL)

Description

Computes the QR decomposition of a matrix or aMatrix, routing to a backend-specific implementation when available.

Usage

am_qr(x, ...)

Arguments

Value

An object of class amDenseQR (or a wrapped sparse QR for adgCMatrix input) containing the factorisation components.

Examples

m <- adgeMatrix(matrix(rnorm(12), 4, 3))
qr_obj <- am_qr(m)
qr.R(qr_obj)

Description

Compute the mean of rows of x grouped by integer labels.

Usage

am_scatter_mean(x, labels, K)

Arguments

Value

A K-by-ncol(x) matrix of group means.

Description

Apply a function to each row or column of a matrix, dispatching to the preferred GPU backend when available.

Usage

am_sweep(x, MARGIN, STATS, FUN = "+")

Arguments

Value

A matrix of the same dimensions as x.

See Also

am_sweep_inplace

Description

Applies a row-wise or column-wise arithmetic operation between the resident matrix and a statistics vector, mutating the handle in place. Equivalent to sweep(as.matrix(h), MARGIN, STATS, FUN) but avoids downloading the matrix to host.

Usage

am_sweep_inplace(h, MARGIN, STATS, FUN = "+")

Arguments

Value

h, invisibly. The handle is modified in place; the underlying device buffer is replaced with the sweep result.

See Also

resident_handle, am_ewise_inplace

Examples

# requires a backend with residency support (e.g. MLX, OpenCL)

Description

Returns the unique capability strings advertised by the named backend, as reported by its capabilities() function.

Usage

amatrix_backend_capabilities(name)

Arguments

Value

Character vector of capability identifiers (e.g. "matmul", "svd").

See Also

amatrix_backend_features, amatrix_backend_status

Examples

amatrix_backend_capabilities("cpu")

Description

Returns the unique feature strings advertised by the named backend, as reported by its features() function. Features describe optional capabilities such as sparse residency or deferred execution.

Usage

amatrix_backend_features(name)

Arguments

Value

Character vector of feature identifiers.

See Also

amatrix_backend_capabilities, amatrix_backend_status

Examples

amatrix_backend_features("cpu")

Description

Executes a small matmul round-trip against the named backend and compares the result to the base R reference. On success the backend is marked healthy; on failure it is marked unhealthy:<reason>. Subsequent calls to amatrix_backend_status() reflect the recorded health.

Usage

amatrix_backend_health_probe(name, tol = NULL)

Arguments

Details

The probe is intentionally tiny (10x10 double-precision matmul) so it completes in milliseconds even on cold GPU. It is not a benchmark; it is a liveness check.

Value

Invisibly, the health record as a list with elements status, reason, timestamp.

See Also

amatrix_backend_status, amatrix_fallback_log

Examples

amatrix_backend_health_probe("cpu")

Description

Runs amatrix_backend_plan for each requested operation and returns the results as a single data.frame, one row per operation. Useful for inspecting which backend will be used across an entire workload.

Usage

amatrix_backend_matrix(
  x,
  ops = c("matmul", "crossprod", "tcrossprod", "ewise", "rowSums", "colSums", "solve",
    "chol", "qr", "svd", "eigen", "diag"),
  y_map = list()
)

Arguments

Value

A data.frame with one row per operation and columns:

op

Character. Operation name.

precision

Character. Precision mode.

pinned_backend

Character. Backend to which x is GPU-resident, or NA.

preferred

Character. Preference order string.

chosen

Character. Selected backend.

chosen_path

Character. "resident" or "cold".

resident_reuse

Logical. Whether the resident path is active.

cpu_fallback

Logical. Whether CPU was chosen despite not being first preference.

candidate_summary

Character. Compact flag string for all candidates.

See Also

amatrix_backend_plan, amatrix_execution_info

Examples

m <- adgeMatrix(matrix(1:6, 2, 3))
amatrix_backend_matrix(m, ops = c("matmul", "crossprod"))

Description

Returns the names of every backend currently in the session registry. When optional backends are enabled (the default), this also attempts to auto-register any installed optional backend packages before returning the list.

Usage

amatrix_backend_names()

Value

Character vector of registered backend names, sorted alphabetically. Always includes at least "cpu".

See Also

amatrix_backend_status, amatrix_register_backend

Examples

amatrix_backend_names()

Description

Evaluates each candidate backend in preference order and returns a structured plan describing which backend was chosen and why each candidate was accepted or rejected. The plan respects GPU residency, precision compatibility, and calibration thresholds.

Usage

amatrix_backend_plan(x, op, y = NULL)

Arguments

Value

A named list with elements:

op

Character. The requested operation.

pinned_backend

Character or NULL. Backend to which x is currently GPU-resident.

preferred

Character vector. Backends evaluated in order.

requested_precision

Character. Precision mode of x.

chosen

Character. Name of the chosen backend.

chosen_path

Character. Either "resident" or "cold".

candidates

List of per-candidate evaluation records, each a named list with logical flags for registered, available, precision_compatible, supported_cold, supported_resident, calibration_ok, supported, and chosen.

See Also

amatrix_backend_matrix, amatrix_explain, amatrix_execution_info

Examples

m <- adgeMatrix(matrix(1:6, 2, 3))
amatrix_backend_plan(m, "matmul")

Description

Returns the precision mode strings advertised by the named backend. Valid values are "strict" (double precision) and "fast" (single/mixed precision).

Usage

amatrix_backend_precision_modes(name)

Arguments

Value

Character vector of precision mode identifiers, a subset of c("strict", "fast").

See Also

amatrix_backend_capabilities, amatrix_backend_status

Examples

amatrix_backend_precision_modes("cpu")

Description

Returns a data.frame with one row per backend describing its availability, supported precision modes, features, capabilities, and whether it supports GPU residency.

Usage

amatrix_backend_status(names = NULL)

Arguments

Value

A data.frame with columns:

name

Character. Backend identifier.

available

Logical. Whether the backend reports itself as available on this machine.

precision_modes

Character. Comma-separated precision modes ("strict", "fast").

features

Character. Comma-separated feature strings.

residency_capable

Logical. Whether the backend supports GPU-resident matrix storage.

capabilities

Character. Comma-separated operation capability strings.

See Also

amatrix_backend_names, amatrix_register_backend

Examples

amatrix_backend_status()
amatrix_backend_status("cpu")

Description

Reads a machine-local benchmark baseline CSV (a table of recorded per-op cold and warm timings), if one is present, together with the cached calibration in the user cache directory, and returns a structured data.frame surfacing per-op cold vs warm timings and the currently-calibrated dispatch thresholds.

Usage

amatrix_benchmark_report(baseline_path = file.path("tools", "baseline.csv"))

Arguments

Details

This is the user-facing honesty surface for Track 4's speed contract: users can see (a) which backends are calibrated on their machine, (b) cold-start vs warm-run ratios per op, and (c) where the dispatcher will currently route.

Value

A list with two elements:

baseline

data.frame with columns op, size, backend, cold_ms, warm_ms, warm_vs_cold_ratio, speedup_vs_cpu. Rows with missing cold OR warm data use NA for the missing variant. Empty when the baseline file is absent.

calibration

data.frame with columns backend, op, threshold_elements, gpu_wins. Rows come from the cached calibration; empty when no calibration is available.

See Also

amatrix_calibrate, amatrix_calibration_info

Examples

## Not run: 
rep <- amatrix_benchmark_report()
head(rep$baseline)
head(rep$calibration)

## End(Not run)

Description

Upload a dense or sparse matrix to a residency-capable backend and return the corresponding aMatrix object with a live resident binding. This is primarily useful for repeated GPU work where paying the upload cost once is preferable to relying on cold-path dispatch.

Usage

amatrix_bind_resident(x, backend = NULL, op = NULL, y = NULL)

Arguments

Value

An adgeMatrix or adgCMatrix with a live resident binding on backend. When no suitable accelerator backend is available in automatic mode, returns x unchanged.

Description

amatrix_cache_max_size returns the current limit. amatrix_set_cache_max_size changes the limit and immediately evicts the least-recently-used entries if the cache exceeds the new bound. When max_size is Inf (the default) the cache grows without bound.

Usage

amatrix_cache_max_size()

amatrix_set_cache_max_size(max_size)

Arguments

Value

amatrix_cache_max_size returns a length-1 numeric giving the current limit. amatrix_set_cache_max_size returns the new limit invisibly.

Examples

old <- amatrix_cache_max_size()
amatrix_set_cache_max_size(10)
amatrix_cache_max_size()
amatrix_set_cache_max_size(old)

Description

Runs micro-benchmarks for each (op, backend, size) combination and derives the minimum matrix element count at which each GPU backend reliably outperforms CPU. Results are stored in the current session and optionally persisted to disk for reuse in future sessions.

Usage

amatrix_calibrate(
  backend = NULL,
  ops = c("gemm", "gemv", "crossprod", "rowSums", "colSums", "qr", "chol", "solve",
    "svd"),
  sizes = list(c(64L, 32L), c(128L, 64L), c(256L, 128L), c(512L, 256L), c(1024L, 512L)),
  sparse_densities = c(0.01, 0.05, 0.2),
  n_reps = 10L,
  margin = 0.1,
  persist = TRUE,
  quiet = FALSE
)

Arguments

Value

Invisibly, a list with elements version, calibrated_at (POSIXct), thresholds (nested list keyed by backend then op), and results (data.frame of all benchmark measurements).

See Also

amatrix_calibration_info, amatrix_backend_plan

Description

Returns the calibration data stored in the current session. If no calibration has been run yet, the function attempts to load a previously persisted calibration from the user cache directory. Returns NULL when no calibration is available.

Usage

amatrix_calibration_info()

Value

A list as returned by amatrix_calibrate, or NULL if no calibration data exists for this session.

See Also

amatrix_calibrate

Examples

cal <- amatrix_calibration_info()
is.null(cal) # TRUE when no calibration has been run

Description

Prepares a fixed left operand for repeated products, choosing and binding a resident accelerator backend when beneficial. The returned object is a callable function, so repeated right-hand sides can be applied without rethinking backend selection each time.

Usage

amatrix_compile_product(
  x,
  op = c("matmul", "crossprod", "tcrossprod"),
  backend = "auto",
  precision = amatrix_default_precision(),
  policy = amatrix_default_policy()
)

Arguments

Value

A callable am_product_plan. Calling the plan with materialize = "matrix" returns a base matrix directly, which is useful for internal algorithms that immediately need host matrix data.

Description

Returns the dispatch policy used when an aMatrix object does not specify its own policy. The policy controls which backend is preferred for operations on new matrices.

Usage

amatrix_default_policy()

Value

Character string, one of "auto", "cpu", "mlx", "metal", "arrayfire", or "opencl".

See Also

amatrix_set_default_policy, amatrix_default_precision

Examples

amatrix_default_policy()

Description

Returns the precision mode used when constructing new aMatrix objects that do not specify their own precision.

Usage

amatrix_default_precision()

Value

Character string, either "strict" (double precision) or "fast" (single/mixed precision).

See Also

amatrix_set_default_precision, amatrix_default_policy

Examples

amatrix_default_precision()

Description

Resolves the best available backend for op on x, attempts the GPU-resident path when applicable, and falls back to the cold path (materializing x to host) if needed. If the chosen backend does not implement method, the fallback function is called instead.

Usage

amatrix_dispatch_op(x, op, method = op, y = NULL, args = list(), fallback)

Arguments

Value

The result of the backend method, or the result of fallback() if the method is unavailable.

See Also

amatrix_backend_plan, amatrix_materialize_host

Description

Returns a snapshot of the dispatch state for an aMatrix, including residency, preferred backend, policy, precision, and the per-operation dispatch matrix for a set of operations.

Usage

amatrix_execution_info(
  x,
  ops = c("matmul", "crossprod", "tcrossprod", "ewise", "rowSums", "colSums"),
  y_map = list()
)

Arguments

Value

A named list with elements:

object_id

Character. Internal object identifier.

preferred_backend

Character. Preferred backend slot value.

pinned_backend

Character or NULL. Backend to which the object is currently GPU-resident.

policy

Character. Dispatch policy slot value.

precision

Character. Precision mode ("strict" or "fast").

residency

data.frame. Output of amatrix_residency_info.

plans

data.frame. Output of amatrix_backend_matrix.

See Also

amatrix_backend_plan, amatrix_backend_matrix, amatrix_explain

Description

Prints a human-readable diagnostic showing which backend was chosen for op on x, the accept/reject status of every candidate backend, and actionable suggestions for improving performance.

Usage

amatrix_explain(x, op, y = NULL)

Arguments

Value

Invisibly, the dispatch plan list from amatrix_backend_plan. Called primarily for its printed output.

See Also

amatrix_backend_plan, amatrix_backend_matrix, amatrix_execution_info

Examples

m <- adgeMatrix(matrix(1:12, 3, 4))
amatrix_explain(m, "matmul")

Description

The fallback log records every runtime fall-through from a preferred backend to the CPU reference path. A non-empty log after a clean conformance run is a stop-ship condition: it means a backend claimed support for an op it cannot actually execute, so the result silently came from a different backend than the one that was requested.

Usage

amatrix_fallback_log()

Value

A data.frame with columns timestamp, op, from_backend, to_backend, reason. Zero rows means no fallbacks have been recorded.

See Also

amatrix_fallback_log_reset, amatrix_backend_health_probe

Examples

amatrix_fallback_log()
amatrix_fallback_log_reset()

Description

Resets the fallback log to empty. Typically called at the start of a test block to isolate the assertion that the log is empty after a clean run.

Usage

amatrix_fallback_log_reset()

Value

Invisibly, NULL.

See Also

amatrix_fallback_log

Description

Scans the residency registry and removes entries whose backend no longer reports the associated device buffer as present. Such stale entries arise when a backend is unloaded or the device is reset between sessions. Optionally flushes all cached matrix factors (QR, Cholesky, SVD) from the session model cache.

Usage

amatrix_gc(cache = FALSE)

Arguments

Value

Invisibly, a list with two integer elements:

dead_entries

Number of stale residency slots removed.

cache_entries_cleared

Number of model-cache entries flushed (0 when cache = FALSE).

See Also

amatrix_memory_stats, amatrix_residency_info

Examples

amatrix_gc()
amatrix_gc(cache = TRUE)

Description

One row per known GPU backend with the state of every gate between "installed" and "computing on the GPU": package installed, backend registered, device available, health, and the registry's recorded reason when something is off.

Usage

amatrix_gpu_status()

Value

A data frame with columns backend, package, installed, registered, available, health, and reason.

See Also

amatrix_use_gpu, amatrix_backend_status, amatrix_explain

Examples

amatrix_gpu_status()

Description

Downloads any GPU-resident data and returns a standard Matrix-package object on the host. For adgeMatrix inputs the result is a dgeMatrix; for adgCMatrix inputs the result is a dgCMatrix; for aTransposeView the transposed dense host matrix is returned. Host-only objects are returned unchanged.

Usage

amatrix_materialize_host(x)

Arguments

Value

A dgeMatrix, dgCMatrix, or the original object if no materialization is needed.

See Also

amatrix_residency_info, amatrix_gc

Examples

m <- adgeMatrix(matrix(1:6, 2, 3))
host <- amatrix_materialize_host(m)
class(host)

Description

Returns a snapshot of GPU device memory usage and model cache occupancy for the current session. Backends that expose a memory_usage() method contribute device byte counts; backends without that method show NA for byte fields.

Usage

amatrix_memory_stats()

Value

An object of class amatrix_memory_stats, which is a list with two components:

residency

data.frame with one row per registered backend and columns backend (character), resident_objects (integer count of GPU-resident R objects), bytes_used (numeric, device bytes in use, or NA), and bytes_total (numeric, total device capacity, or NA).

model_cache

List with n_entries (integer, number of cached matrix factors) and max_size (integer or Inf, the cache size limit).

See Also

amatrix_gc, amatrix_residency_info

Examples

stats <- amatrix_memory_stats()
print(stats)

Description

Converts inputs to amatrix wrappers when needed, chooses a residency-capable accelerator backend in automatic mode, and binds the operands so repeated products reuse the resident fast path.

Usage

amatrix_prepare_operands(
  x,
  y,
  op = c("matmul", "crossprod", "tcrossprod"),
  backend = "auto",
  precision = amatrix_default_precision(),
  policy = amatrix_default_policy()
)

Arguments

Value

A list with elements x, y, and backend.

Description

Adds a named backend to the session backend registry. The backend must be a named list containing all required callable fields. Once registered, the backend is available for dispatch by any aMatrix object whose preferred_backend or policy slot names it.

Usage

amatrix_register_backend(name, backend, overwrite = FALSE)

Arguments

Value

Invisibly, name.

See Also

amatrix_backend_names, amatrix_backend_status

Examples

# Minimal no-op backend for illustration only
noop <- list(
  capabilities   = function() character(),
  features       = function() character(),
  precision_modes = function() "strict",
  available      = function() FALSE,
  supports       = function(op, x, y = NULL) FALSE,
  matmul         = function(x, y) x,
  crossprod      = function(x, y = NULL) x,
  tcrossprod     = function(x, y = NULL) x,
  ewise          = function(x, y, op) x,
  rowSums        = function(x) numeric(nrow(x)),
  colSums        = function(x) numeric(ncol(x))
)
amatrix_register_backend("noop_test", noop, overwrite = TRUE)

Description

Frees any device-resident buffer associated with x and drops its residency-registry binding, leaving the host copy as the authoritative storage. This gives long-lived GPU pipelines explicit control over device memory instead of waiting for garbage collection to reclaim resident handles.

Usage

amatrix_release_resident(x)

Arguments

Details

The object remains fully usable afterwards: its data is served from the host copy and is re-uploaded to the device on the next GPU operation if needed. On CPU-only sessions, or for any object that currently holds no device buffer, this is a safe no-op.

Value

Invisibly, TRUE if a resident binding was released, and FALSE otherwise (including the CPU-only no-op case).

Examples

A <- adgeMatrix(matrix(1:6, 2, 3))
# On a CPU-only session there is no device buffer, so this is a no-op:
released <- amatrix_release_resident(A)
released

Description

Returns a single-row data.frame describing whether x is currently uploaded to a GPU backend and, if so, which backend holds it and whether that binding is still live (the device buffer still exists).

Usage

amatrix_residency_info(x)

Arguments

Value

A data.frame with one row and columns:

backend

Character. Backend name, or NA when not resident.

resident_key

Character. Internal device buffer key, or NA.

pinned_backend

Character. Backend name when the binding is confirmed live, otherwise NA.

live

Logical. TRUE when the backend still holds the buffer identified by resident_key.

See Also

amatrix_materialize_host, amatrix_memory_stats

Examples

m <- adgeMatrix(matrix(1:4, 2, 2))
amatrix_residency_info(m)

Description

Returns the first available non-CPU backend that can keep x resident for the requested operation. This is intended for package authors who want repeated work to stay on the fastest available accelerator without hardcoding backend names such as "metal" or "mlx".

Usage

amatrix_resident_backend_for(x, op = NULL, y = NULL)

Arguments

Value

A backend name, or NULL when no residency-capable accelerator is available for the requested operation.

Description

Sets the dispatch policy applied to new aMatrix objects that do not specify their own policy. The change affects all subsequent matrix constructions in the current session.

Usage

amatrix_set_default_policy(policy)

Arguments

Value

Invisibly, policy.

See Also

amatrix_default_policy, amatrix_set_default_precision

Examples

old <- amatrix_default_policy()
amatrix_set_default_policy("auto")
amatrix_set_default_policy(old) # restore

Description

Sets the precision mode applied to new aMatrix objects that do not specify their own precision. Use "strict" for reproducible double-precision results and "fast" for maximum GPU throughput with single/mixed precision.

Usage

amatrix_set_default_precision(precision)

Arguments

Value

Invisibly, precision.

See Also

amatrix_default_precision, amatrix_set_default_policy

Examples

old <- amatrix_default_precision()
amatrix_set_default_precision("strict")
amatrix_set_default_precision(old) # restore

Description

Finds, enables, and health-checks an installed GPU backend, then adopts it as the session default for "fast"-precision work. On Apple Silicon with amatrix.mlx installed this is usually unnecessary: MLX probing is on by default and activates on first use. Call this for the opt-in backends (amatrix.opencl, amatrix.arrayfire, amatrix.metal), to force a specific backend, or to get an explicit confirmation line.

Usage

amatrix_use_gpu(backend = NULL, quiet = FALSE)

Arguments

Details

GPU backends compute in float32 ("fast" precision, conformance tolerance ~1e-4); "strict" float64 work always stays on the CPU reference backend regardless of this setting.

Side effect: on success this sets the session default precision to "fast" (and, when backend is given explicitly, the session default policy to that backend) so subsequent matrices route to the GPU without per-object arguments. Undo with amatrix_set_default_precision("strict") / amatrix_set_default_policy("auto").

Value

Invisibly, the name of the enabled backend, or FALSE if no GPU backend could be enabled.

See Also

amatrix_gpu_status, amatrix_backend_status, amatrix_set_default_precision

Examples

status <- amatrix_gpu_status()
if (interactive()) amatrix_use_gpu()

Description

Pre-compiles GPU kernels by running tiny dummy operations through each requested backend. Call once before timed work to pay JIT compilation costs upfront. Errors are silently swallowed; warming never alters numerical state.

Usage

amatrix_warm(
  backend = NULL,
  ops = c("matmul", "crossprod", "qr", "chol"),
  size = c(64L, 64L),
  quiet = FALSE
)

Arguments

Value

An invisible named list, one entry per backend, each a list with elements warmed (logical) and elapsed_ms (numeric milliseconds, or NA when unavailable).

See Also

amatrix_backend_names

Examples

results <- amatrix_warm(quiet = TRUE)

Description

aMatrix is the abstract base from which all concrete amatrix classes inherit. It carries backend-dispatch metadata that controls which compute backend (CPU, GPU, etc.) is used for operations on the matrix.

Slots

preferred_backend

Single string naming the preferred compute backend; one of "cpu", "mlx", "metal", or "arrayfire".

policy

Single string controlling dispatch policy; one of "auto", "cpu", "mlx", "metal", or "arrayfire".

precision

Single string; either "strict" (double precision, exact results) or "fast" (backend may use lower precision).

object_id

Non-empty string uniquely identifying this object within the session; used for caching and residency tracking.

src_id

String recording the object_id of the object this was derived from, or "" for originals.

finalizer_env

Environment used to manage GPU-resident memory and deferred host-copy state.

Description

Stores the upper-triangular Cholesky factor R of a symmetric positive-definite adgeMatrix, as returned by chol_factor. When the factor is resident on a GPU backend the host-side @factor slot may be an empty zero-row matrix; use chol_solve rather than accessing slots directly.

Slots

factor

Numeric matrix; the upper-triangular factor R such that t(R) %*% R equals the source matrix. May be matrix(numeric(0), 0, 0) when the factor lives only on the device.

factor_obj

Either an adgeMatrix holding the GPU-resident factor, or NULL for CPU-only factors.

source_id

Character string; the object_id of the source adgeMatrix.

precision

Character string; "strict" or "fast".

backend

Character string; the backend that computed the factorization.

See Also

chol_factor, chol_solve, chol_logdet

Description

Stores the original square matrix for use with LAPACK's DGESV routine. Unlike amChol, which caches the explicit triangular factor, amLU retains A and delegates factorization to base::solve at solve time.

Slots

A

Numeric square matrix; the original matrix passed to lu_factor.

source_id

Character string; the object_id of the source adgeMatrix, or NA for base matrices.

precision

Character string; "strict" or "fast", or NA for base matrices.

backend

Character string; the preferred backend of the source object, or NA for base matrices.

See Also

lu_factor, lu_solve

Description

Stores the rank-k truncated singular value decomposition of an aMatrix as returned by svd_factor. Left and right singular vectors are kept as base R matrices so they are always host-accessible; optional adgeMatrix copies of t(u) and v may be present for GPU-accelerated projection.

Slots

u

Numeric matrix of left singular vectors; nrow(u) equals the number of rows of the source matrix and ncol(u) equals k.

d

Numeric vector of singular values of length k, in descending order.

v

Numeric matrix of right singular vectors; nrow(v) equals the number of columns of the source matrix and ncol(v) equals k.

k

Integer; the requested rank.

method

Character string; one of "exact", "rsvd", or "subspace".

engine

Character string identifying the low-level solver used (e.g., "exact_svd", "irlba_svdr", "backend_rsvd").

source_id

Character string; the object_id of the source aMatrix.

precision

Character string; "strict" or "fast".

backend

Character string; the backend that computed the SVD.

ut_am

Either an adgeMatrix holding t(u) for GPU matrix-multiply routing, or NULL on CPU paths.

v_am

Either an adgeMatrix holding v for GPU matrix-multiply routing, or NULL on CPU paths.

See Also

svd_factor, svd_project, svd_reconstruct

Description

Wraps many_lm to accept a response Y with more than two dimensions (e.g. a 3-D array). The trailing dimensions are collapsed into columns for fitting and optionally restored in the output.

Usage

array_lm(
  X,
  Y,
  weights = NULL,
  intercept = FALSE,
  include_fitted = FALSE,
  include_residuals = FALSE,
  cache = TRUE,
  method = c("normal", "qr"),
  restore_array = TRUE
)

Arguments

Value

An object of class "am_array_lm_fit", a named list containing the same fields as many_lm plus:

response_dims

Integer vector of trailing dimensions of Y.

rss

Array or vector of residual sums of squares.

sigma2

Array or vector of residual variances.

See Also

many_lm, lm_fit

Examples

X <- matrix(rnorm(50), nrow = 10)
Y <- array(rnorm(10 * 3 * 4), dim = c(10, 3, 4))
fit <- array_lm(X, Y)
dim(fit$sigma2)

Description

Converts a sparse or dense matrix-like object to an adgCMatrix with the requested backend metadata.

Usage

as_adgCMatrix(
  x,
  mode = NULL,
  backend = NULL,
  preferred_backend = NULL,
  policy = NULL,
  precision = NULL
)

Arguments

Value

An adgCMatrix.

Description

Converts a matrix-like object or a resident_handle to an adgeMatrix. When x is a resident_handle, ownership of the GPU-resident buffer is transferred to the new adgeMatrix.

Usage

as_adgeMatrix(
  x,
  mode = NULL,
  backend = NULL,
  preferred_backend = NULL,
  policy = NULL,
  precision = NULL
)

Arguments

Value

An adgeMatrix.

Examples

m <- matrix(1:6, nrow = 2)
A <- as_adgeMatrix(m)
dim(A)

Description

Creates an adgeMatrix with the resident key still bound. By default the GPU data is materialized to a host copy. If defer_host = TRUE, the host copy is not materialized until first host access.

Usage

as_adgeMatrix.resident_handle(h, ..., defer_host = FALSE)

Arguments

Value

An adgeMatrix.

Description

Convert adgeMatrix, adgCMatrix, or aTransposeView objects to base R matrix, numeric vector, or array by materializing the host copy.

Usage

## S4 method for signature 'adgeMatrix'
as.matrix(x, ...)

## S3 method for class 'adgeMatrix'
as.matrix(x, ...)

## S4 method for signature 'adgCMatrix'
as.matrix(x, ...)

## S3 method for class 'adgCMatrix'
as.matrix(x, ...)

## S4 method for signature 'aTransposeView'
as.matrix(x, ...)

## S3 method for class 'aTransposeView'
as.matrix(x, ...)

## S4 method for signature 'amChol'
as.matrix(x, ...)

## S4 method for signature 'KronMatrix'
as.matrix(x, ...)

## S4 method for signature 'adgeMatrix'
as.numeric(x, ...)

## S4 method for signature 'adgeMatrix'
as.vector(x, mode = "any")

## S4 method for signature 'adgeMatrix'
as.array(x, ...)

## S4 method for signature 'adgCMatrix'
as.array(x, ...)

Arguments

Value

A plain R matrix, numeric vector, or array containing the materialized host data.

Examples

A <- adgeMatrix(matrix(1:6, 2, 3))
as.matrix(A)

Description

aTransposeView is a zero-copy structural view representing the transpose of an adgeMatrix. It carries no independent dense host storage; the underlying data lives in source. The transposed matrix is materialized on demand via as.matrix() or amatrix_materialize_host().

Slots

source

The originating adgeMatrix; kept alive by this reference.

Dim

Integer vector of length 2 giving the transposed dimensions c(ncol_src, nrow_src).

Dimnames

List of length 2 with transposed dimnames.

Description

Factorize B symmetric positive-definite matrices in parallel. Each matrix is dispatched through the same backend as chol_factor, so MLX GPU acceleration applies to every element when available.

Usage

batch_chol(A)

Arguments

Value

A list of amChol objects, one per input matrix.

See Also

chol_factor, batch_solve

Description

Compute t(A_b) %*% A_b for each matrix in a batch.

Usage

batch_crossprod(A)

Arguments

Value

A list of p x p crossproduct matrices.

See Also

batch_chol

Description

Solve B linear systems A_b x_b = B_b where each A_b is represented by its Cholesky factor from batch_chol.

Usage

batch_solve(Ls, B)

Arguments

Value

A list of solution matrices (or vectors when each rhs is a vector).

See Also

batch_chol, chol_solve

Description

Computes a truncated SVD using a block Lanczos bidiagonalization. Each Krylov step issues one GPU GEMM per block rather than sequential GEMVs, significantly reducing kernel-launch overhead on accelerated backends.

Usage

block_lanczos(
  A,
  nv = 5L,
  nu = nv,
  block_size = NULL,
  n_steps = NULL,
  mode = "fast",
  backend = NULL
)

block_svd(
  A,
  k,
  block_size = NULL,
  n_steps = NULL,
  mode = "fast",
  backend = NULL
)

Arguments

Value

A named list with components:

u

Numeric matrix [m, nu]: left singular vectors.

d

Numeric vector of length min(nu, nv): singular values in decreasing order.

v

Numeric matrix [n, nv]: right singular vectors.

iter

Integer: number of Krylov steps performed.

mprod

Integer: total matrix-vector products issued.

See Also

rsvd, block_svd

Examples

A <- matrix(rnorm(200), nrow = 20)
res <- block_lanczos(A, nv = 3L)
length(res$d)

Description

Returns the diagonal of the upper-triangular matrix R stored in an amChol object.

Usage

chol_diag(factor)

Arguments

Value

Numeric vector of length equal to the matrix dimension.

Examples

m <- crossprod(matrix(rnorm(16), 4, 4)) + diag(4)
A <- adgeMatrix(m)
fac <- chol_factor(A)
chol_diag(fac)

Description

Computes the upper-triangular Cholesky factor R of a symmetric positive-definite adgeMatrix X such that t(R) %*% R == X. Results are cached by object_id; repeated calls with the same object return the cached factor.

Usage

chol_factor(X)

Arguments

Value

An amChol object.

Examples

m <- crossprod(matrix(rnorm(16), 4, 4)) + diag(4)
A <- adgeMatrix(m)
fac <- chol_factor(A)
fac

Description

Computes log(det(X)) from the Cholesky factor of a symmetric positive-definite matrix X as 2 * sum(log(diag(R))), which avoids forming the full determinant and is numerically stable.

Usage

chol_logdet(factor)

Arguments

Value

Scalar double; the log-determinant of the source matrix.

Examples

m <- crossprod(matrix(rnorm(16), 4, 4)) + diag(4)
A <- adgeMatrix(m)
fac <- chol_factor(A)
chol_logdet(fac)

Description

Solves X %*% x = B where X is the symmetric positive-definite matrix whose Cholesky factorization is stored in factor. Dispatches to a GPU backend when the factor was computed in "fast" precision and a device-resident factor is available.

Usage

chol_solve(factor, B)

Arguments

Value

Numeric vector or matrix x satisfying X %*% x == B. Returns a vector when B is a vector.

Examples

m <- crossprod(matrix(rnorm(16), 4, 4)) + diag(4)
A <- adgeMatrix(m)
fac <- chol_factor(A)
b <- rnorm(4)
x <- chol_solve(fac, b)

Description

This is the same operation as repeatedly calling chol_solve(factor, B[[i]]), but it packs all RHS batches into one wide solve and then splits the result. BLAS/GPU backends generally amortize launch and dispatch overhead much better on one wide RHS than on many small independent solves.

Usage

chol_solve_batches(factor, B)

Arguments

Value

A list of solution vectors/matrices.

Description

Compute the Cholesky factorization of a sparse symmetric positive-definite adgCMatrix.

Usage

## S4 method for signature 'adgCMatrix'
chol(x, ...)

Arguments

Value

An adgCMatrix or sparse Cholesky factor object.

Description

Compute the Cholesky factor of a symmetric positive-definite adgeMatrix, dispatching through the amatrix backend.

Usage

## S4 method for signature 'adgeMatrix'
chol(x, ...)

Arguments

Value

An adgeMatrix containing the upper triangular Cholesky factor.

Examples

S <- adgeMatrix(crossprod(matrix(rnorm(9), 3, 3)) + 3 * diag(3))
R <- chol(S)

Description

Computes the sample correlation matrix of the columns of X, optionally with observation weights and column-blocked covariance accumulation.

Usage

correlation(X, center = TRUE, weights = NULL, block_size = NULL)

Arguments

Value

An adgeMatrix of shape [p, p]: the sample correlation matrix with diagonal entries set to 1.

See Also

covariance

Examples

X <- matrix(rnorm(50), nrow = 10)
R <- correlation(X)
round(diag(as.matrix(R)), 6)

Description

Bridge cov2cor() through Matrix's covariance-to-correlation methods so standard workflows such as cov2cor(crossprod(X)) keep working when crossprod() preserves an amatrix class.

Usage

## S4 method for signature 'adgeMatrix'
cov2cor(V)

## S4 method for signature 'adgCMatrix'
cov2cor(V)

Arguments

Value

A base R correlation matrix, matching stats::cov2cor() on the corresponding host matrix.

Examples

X <- adgeMatrix(matrix(1:9 + 0, 3, 3))
cov2cor(crossprod(X))

Description

Computes the (possibly weighted) sample or population covariance matrix of X. Sparse inputs use a memory-efficient path; dense inputs use a fused GPU kernel when available, otherwise fall back to CPU centering followed by a GPU cross-product.

Usage

covariance(X, center = TRUE, sample = TRUE, weights = NULL, block_size = NULL)

Arguments

Value

An adgeMatrix of shape [p, p].

See Also

many_lm

Examples

X <- matrix(rnorm(200), nrow = 40)
C <- covariance(X)
dim(C)

Description

Computes $X^T X + \lambda I$ (scalar lambda) or $X^T X + \mathrm{diag}(\lambda)$ (vector lambda) in a single fused call.

Usage

crossprod_add_diag(X, lambda)

Arguments

Value

An adgeMatrix of shape [p, p]: the perturbed cross-product.

See Also

crossprod_weighted

Examples

X <- matrix(rnorm(20), nrow = 5)
crossprod_add_diag(X, lambda = 0.1)

Description

Computes $X^T \mathrm{diag}(w) X$, a p x p weighted cross-product. A GPU-resident fast path is used when available.

Usage

crossprod_weighted(X, w)

Arguments

Value

An adgeMatrix of shape [p, p].

See Also

tcrossprod_weighted, xty_weighted

Examples

X <- matrix(rnorm(20), nrow = 5)
w <- runif(5)
crossprod_weighted(X, w)

Description

Compute $t(x) \%*\% y$ (crossprod) or $x \%*\% t(y)$ (tcrossprod) for sparse adgCMatrix objects, dispatching through the amatrix backend.

Usage

## S4 method for signature 'adgCMatrix,missing'
crossprod(x, y = NULL, ...)

## S4 method for signature 'adgCMatrix,ANY'
crossprod(x, y = NULL, ...)

## S4 method for signature 'adgCMatrix,matrix'
crossprod(x, y = NULL, ...)

## S4 method for signature 'adgCMatrix,Matrix'
crossprod(x, y = NULL, ...)

## S4 method for signature 'adgCMatrix,dgeMatrix'
crossprod(x, y = NULL, ...)

## S4 method for signature 'adgCMatrix,dgCMatrix'
crossprod(x, y = NULL, ...)

## S4 method for signature 'adgCMatrix,adgeMatrix'
crossprod(x, y = NULL, ...)

## S4 method for signature 'adgCMatrix,adgCMatrix'
crossprod(x, y = NULL, ...)

## S4 method for signature 'adgCMatrix,missing'
tcrossprod(x, y = NULL, ...)

## S4 method for signature 'adgCMatrix,ANY'
tcrossprod(x, y = NULL, ...)

## S4 method for signature 'adgCMatrix,matrix'
tcrossprod(x, y = NULL, ...)

## S4 method for signature 'adgCMatrix,Matrix'
tcrossprod(x, y = NULL, ...)

## S4 method for signature 'adgCMatrix,dgeMatrix'
tcrossprod(x, y = NULL, ...)

## S4 method for signature 'adgCMatrix,dgCMatrix'
tcrossprod(x, y = NULL, ...)

## S4 method for signature 'adgCMatrix,adgeMatrix'
tcrossprod(x, y = NULL, ...)

## S4 method for signature 'adgCMatrix,adgCMatrix'
tcrossprod(x, y = NULL, ...)

Arguments

Value

An adgeMatrix or adgCMatrix containing the result.

Examples

sp <- as(matrix(c(1, 0, 0, 2, 1, 0), 3, 2), "dgCMatrix")
A  <- adgCMatrix(sp)
crossprod(A)

Description

Compute $t(x) \%*\% y$ (crossprod) or $x \%*\% t(y)$ (tcrossprod) for adgeMatrix objects, dispatching through the amatrix backend to preserve GPU residency.

Usage

## S4 method for signature 'adgeMatrix,ANY'
crossprod(x, y = NULL, ...)

## S4 method for signature 'adgeMatrix,missing'
crossprod(x, y = NULL, ...)

## S4 method for signature 'adgeMatrix,ANY'
tcrossprod(x, y = NULL, ...)

## S4 method for signature 'adgeMatrix,missing'
tcrossprod(x, y = NULL, ...)

Arguments

Value

An adgeMatrix containing the result.

Examples

A <- adgeMatrix(matrix(rnorm(12), 4, 3))
crossprod(A)
tcrossprod(A)

Description

Computes the pairwise distance matrix between rows of X and Y. The dominant cost (row inner-products via am_tcrossprod) is dispatched to the active GPU backend (ArrayFire or MLX); norm computation and final transforms run on CPU where they are O(mp + np) — negligible versus the O(mnp) GEMM.

Usage

dist_matrix(
  X,
  Y = NULL,
  method = c("euclidean", "sqeuclidean", "cosine"),
  tile_size = NULL
)

Arguments

Value

Numeric matrix [m, n] of pairwise distances.

See Also

kernel_matrix

Examples

X <- matrix(rnorm(30), nrow = 6)
D <- dist_matrix(X)
dim(D)

Description

Computes the element-wise inner product sum(x * y), equivalent to as.numeric(t(x) %*% y) for vectors.

Usage

dot(x, y)

Arguments

Value

A single numeric scalar.

Examples

dot(1:4, 4:1)

Description

Compute eigenvalues and eigenvectors of a sparse adgCMatrix, dispatching through the amatrix backend.

Usage

## S4 method for signature 'adgCMatrix'
eigen(x, symmetric, only.values = FALSE, EISPACK = FALSE)

Arguments

Value

A list with components values and vectors.

Description

Compute eigenvalues and eigenvectors of an adgeMatrix, dispatching through the amatrix backend for symmetric matrices when GPU acceleration is available. A fallback method for plain matrix preserves base R behaviour after the generic is promoted to S4.

Usage

## S4 method for signature 'adgeMatrix'
eigen(x, symmetric, only.values = FALSE, EISPACK = FALSE)

Arguments

Value

A list with components values (numeric vector) and vectors (matrix, omitted when only.values = TRUE).

Examples

S <- adgeMatrix(crossprod(matrix(rnorm(9), 3, 3)))
ev <- eigen(S, symmetric = TRUE)
length(ev$values)

Description

Computes eigenvalues and eigenvectors of a real symmetric matrix by dispatching to the active backend via eigen with symmetric = TRUE.

Usage

eigh(x)

Arguments

Value

A list with components values (numeric vector of eigenvalues in ascending order) and vectors (numeric matrix whose columns are the corresponding eigenvectors).

See Also

rsvd

Examples

S <- crossprod(matrix(rnorm(25), nrow = 5))
ev <- eigh(adgeMatrix(S))
length(ev$values)

Description

Apply an element-wise arithmetic operation to one or two matrices, dispatching to the preferred GPU backend when available.

Usage

ewise(op, e1, e2 = NULL)

Arguments

Value

A matrix of the same dimensions as e1.

Description

Computes alpha * op(A) %*% op(B) + beta * C, where op(X) = t(X) when the corresponding trans flag is TRUE. Routes internally to the most efficient resident operation for the chosen transpose combination.

Usage

gemm(A, B, C = NULL, alpha = 1, beta = 1, transA = FALSE, transB = FALSE)

Arguments

Value

A matrix of dimensions nrow(op(A)) by ncol(op(B)).

Examples

A <- adgeMatrix(matrix(1:6, 2, 3))
B <- adgeMatrix(matrix(1:6, 2, 3))
gemm(A, B, transA = TRUE)          # t(A) %*% B
gemm(A, B, transB = TRUE)          # A %*% t(B)

Description

Wraps irlba::irlba() with an adgeMatrix input so that every Lanczos matrix-vector product routes through the amatrix GPU dispatch path. The matrix A is kept resident on device; consecutive matvecs in the Lanczos loop avoid host round-trips.

Usage

irlba(
  A,
  nv = 5,
  nu = nv,
  ...,
  mode = "fast",
  backend = NULL,
  implementation = c("compat", "block"),
  block_size = NULL,
  n_steps = NULL
)

Arguments

Details

The hot loop in irlba is two matrix-vector products per Lanczos step: A %*% v and w %*% A. Both route through am_matmul() when A is an adgeMatrix, giving GPU acceleration on the dominant cost. Orthogonalization, svd(B), and convergence tests remain on CPU where they belong (the subspace dimension work is always small).

Do not pass mult= — it is deprecated in irlba and forces a non-standard dispatch path. Pass an adgeMatrix instead.

Value

Same structure as irlba::irlba(): a list with components d, u, v, iter, mprod.

See Also

adgeMatrix, svd_factor

Description

Implements Golub-Kahan Lanczos bidiagonalization directly in ArrayFire C, keeping all matvecs and CGS2 reorthogonalization on the GPU. Only 2*work scalars and the final basis matrices cross PCIe per restart; no per-step host transfers.

Usage

irlba_native(
  A,
  nv = 5L,
  nu = nv,
  tol = sqrt(.Machine$double.eps),
  maxit = 100L,
  work = max(nv + 20L, 3L * nv),
  v0 = NULL,
  mode = "fast",
  backend = NULL
)

Arguments

Details

Compared to am_irlba, which routes each Lanczos matvec through S4 dispatch, this function:

• eliminates S4 overhead on the hot path

• replaces k sequential GEMVs for reorthogonalization with one GEMM

• uploads A once and never re-uploads it across restarts

Value

A list with components d, u, v, iter, mprod, compatible with irlba::irlba().

See Also

irlba, adgeMatrix

Description

Computes the pairwise kernel matrix between rows of X and Y. The expensive am_tcrossprod is GPU-dispatched; element-wise transforms (exp, sqrt, pow) run on CPU.

Usage

kernel_matrix(
  X,
  Y = NULL,
  kernel = c("linear", "rbf", "polynomial", "cosine", "laplacian"),
  sigma = 1,
  degree = 2L,
  coef = 0,
  preferred_backend = NULL,
  zero_diag = FALSE
)

Arguments

Details

Kernels:

linear

$k(x,y) = x^\top y$

rbf

$k(x,y) = \exp(-\|x - y\|^2 / (2 \sigma^2))$

polynomial

$k(x,y) = (\mathrm{coef} + x^\top y)^{\mathrm{degree}}$

cosine

$k(x,y) = (x^\top y) / (\|x\| \|y\|)$

laplacian

$k(x,y) = \exp(-\|x - y\| / \sigma)$

Value

Numeric matrix [m, n] of kernel values.

See Also

dist_matrix

Description

Computes the Kronecker product $A \otimes B$ and returns the result as an adgeMatrix. Accepts plain matrices or any aMatrix subclass. For a lazy variant that avoids forming the full product see kron_matrix.

Usage

kron(A, B)

Arguments

Value

An adgeMatrix of dimension (nrow(A)*nrow(B)) x (ncol(A)*ncol(B)).

See Also

kron_matrix

Description

Creates a KronMatrix that stores the factor matrices A and B without materializing the full Kronecker product. Standard operations such as %*%, crossprod, solve, and determinant are available and exploit the Kronecker structure.

Usage

kron_matrix(A, B)

Arguments

Value

A KronMatrix of implicit dimensions c(nrow(A) * nrow(B), ncol(A) * ncol(B)).

Examples

A <- matrix(1:4, 2, 2)
B <- diag(3)
K <- kron_matrix(A, B)
dim(K)
as.matrix(K)

Description

S4 methods for kronecker and the %x% operator that keep the result as an amatrix. Without them, kronecker(A, B) and A %x% B dispatch to the Matrix methods for the parent dgeMatrix / dgCMatrix classes and silently demote to a plain (non-amatrix) result, discarding backend-dispatch metadata.

Usage

## S4 method for signature 'adgeMatrix,adgeMatrix'
kronecker(X, Y, FUN = "*", make.dimnames = FALSE, ...)

## S4 method for signature 'adgeMatrix,adgCMatrix'
kronecker(X, Y, FUN = "*", make.dimnames = FALSE, ...)

## S4 method for signature 'adgCMatrix,adgeMatrix'
kronecker(X, Y, FUN = "*", make.dimnames = FALSE, ...)

## S4 method for signature 'adgCMatrix,adgCMatrix'
kronecker(X, Y, FUN = "*", make.dimnames = FALSE, ...)

## S4 method for signature 'adgeMatrix,matrix'
kronecker(X, Y, FUN = "*", make.dimnames = FALSE, ...)

## S4 method for signature 'matrix,adgeMatrix'
kronecker(X, Y, FUN = "*", make.dimnames = FALSE, ...)

## S4 method for signature 'adgCMatrix,matrix'
kronecker(X, Y, FUN = "*", make.dimnames = FALSE, ...)

## S4 method for signature 'matrix,adgCMatrix'
kronecker(X, Y, FUN = "*", make.dimnames = FALSE, ...)

Arguments

Details

The product itself is computed by Matrix's own Kronecker methods on the materialized host contents, so values are identical to base::kronecker() on the dense contents. The result is re-wrapped as an adgCMatrix when it is sparse and an adgeMatrix otherwise, inheriting the preferred backend, policy, and precision of the first amatrix operand.

Value

An adgeMatrix (dense) or adgCMatrix (sparse).

Examples

A <- adgeMatrix(matrix(1:4, 2, 2))
B <- adgeMatrix(diag(2))
kronecker(A, B)
A %x% B

Description

KronMatrix stores the two factor matrices A (m x n) and B (p x q) without forming the full (mp x nq) Kronecker product. Matrix-vector and matrix-matrix products are evaluated using the vec-permutation identity (A x B) vec(X) = vec(B X t(A)), keeping memory use at O(mn + pq) rather than O(mnpq).

Slots

A

Numeric matrix; the left factor of the Kronecker product.

B

Numeric matrix; the right factor of the Kronecker product.

See Also

kron_matrix

Description

Solves the ordinary least-squares problem $Y \approx X \beta$ for a single design matrix X and one or more response columns Y.

Usage

lm_fit(
  X,
  Y,
  intercept = FALSE,
  include_fitted = TRUE,
  include_residuals = TRUE,
  cache = TRUE,
  method = c("normal", "qr")
)

Arguments

Value

An object of class "lm_fit", a named list containing:

coefficients

adgeMatrix of shape [p, q].

fitted.values

adgeMatrix of shape [n, q], or NULL when include_fitted = FALSE.

residuals

adgeMatrix of shape [n, q], or NULL when include_residuals = FALSE.

rank

Integer model rank.

df.residual

Residual degrees of freedom.

See Also

many_lm, array_lm

Examples

X <- matrix(rnorm(50), nrow = 10)
y <- rnorm(10)
fit <- lm_fit(X, y)
coef(fit)

Description

Computes exact leave-one-out (LOO) prediction errors by refitting the model n times, each time dropping one observation. Uses qr_downdate internally to avoid recomputing the full factorization from scratch.

Usage

lm_loo_cv(X, y, method = "qr", ...)

Arguments

Value

A named list with two elements:

residuals

Numeric vector of length n: LOO prediction errors $y_i - \hat{y}_i^{(-i)}$.

mse

Scalar mean squared LOO error.

See Also

lm_fit, many_lm

Examples

## Not run: 
X <- adgeMatrix(matrix(rnorm(50), nrow = 10))
y <- rnorm(10)
cv <- lm_loo_cv(X, y)
cv$mse

## End(Not run)

Description

Wraps a square numeric matrix or adgeMatrix in an amLU object. The actual LU decomposition is performed by base::solve at solve time via LAPACK's DGESV.

Usage

lu_factor(A)

Arguments

Value

An amLU object.

Examples

m <- matrix(c(2, 1, 5, 3), nrow = 2)
fac <- lu_factor(m)
fac

Description

Solves A %*% x = B where A is the square matrix stored in factor, delegating to base::solve (LAPACK DGESV).

Usage

lu_solve(factor, B)

Arguments

Value

Numeric vector or matrix x satisfying A %*% x == B. Returns a vector when B is a vector or single-column matrix.

Examples

m <- matrix(c(2, 1, 5, 3), nrow = 2)
fac <- lu_factor(m)
b <- c(1, 2)
lu_solve(fac, b)

Description

The flagship batch regression function. Solves $Y \approx X B$ where Y is a matrix whose columns are independent response variables. When no GPU backend is active the normal-equations or QR path runs on CPU. With an active GPU backend the QR path dispatches the factorization to the device and keeps intermediate results resident to minimise host round-trips.

Usage

many_lm(
  X,
  Y,
  weights = NULL,
  intercept = FALSE,
  include_fitted = FALSE,
  include_residuals = FALSE,
  cache = TRUE,
  method = c("normal", "qr")
)

Arguments

Value

An object of class "am_many_lm_fit", a named list containing:

coefficients

adgeMatrix of shape [p, q].

fitted.values

adgeMatrix [n, q] or NULL.

residuals

adgeMatrix [n, q] or NULL.

rss

Numeric vector of length q: residual sums of squares.

sigma2

Numeric vector of length q: residual variances.

rank

Integer model rank.

df.residual

Residual degrees of freedom.

See Also

lm_fit, array_lm

Examples

X <- matrix(rnorm(100), nrow = 20)
Y <- matrix(rnorm(60), nrow = 20)
fit <- many_lm(X, Y, method = "qr")
dim(coef(fit))

Description

Apply an elementwise function to the eigenvalues of a symmetric positive definite matrix and reconstruct the result: $f(X) = Q \, \mathrm{diag}(f(\lambda)) \, Q^T$.

Usage

mat_sqrt(X)

mat_pow(X, p)

mat_log(X)

Arguments

Value

An adgeMatrix of shape [p, p]: the matrix function applied to X.

Examples

S <- crossprod(matrix(rnorm(16), 4)) + diag(4)
mat_sqrt(S)
mat_log(S)
mat_pow(S, -1)

Description

Multiplies two matrices, routing to an accelerated backend when available. Plain numeric vectors supplied as y are promoted to a column matrix and the result is dropped back to a vector.

Usage

matmul(x, y)

Arguments

Value

A matrix (or numeric vector when y was a vector) of dimensions nrow(x) by ncol(y).

Examples

A <- adgeMatrix(matrix(1:6, 2, 3))
B <- adgeMatrix(matrix(1:6, 3, 2))
matmul(A, B)

Description

Dispatches %*% through the amatrix backend for dense adgeMatrix objects on the left-hand side, preserving GPU residency across the operation.

Usage

## S4 method for signature 'adgeMatrix,matrix'
x %*% y

## S4 method for signature 'adgeMatrix,Matrix'
x %*% y

## S4 method for signature 'adgeMatrix,dgeMatrix'
x %*% y

## S4 method for signature 'adgeMatrix,dgCMatrix'
x %*% y

## S4 method for signature 'adgeMatrix,adgeMatrix'
x %*% y

## S4 method for signature 'adgeMatrix,adgCMatrix'
x %*% y

## S4 method for signature 'numeric,adgeMatrix'
x %*% y

Arguments

Value

An adgeMatrix (or numeric vector when y is a vector and x is adgeMatrix), with the same backend metadata as x.

Examples

A <- adgeMatrix(matrix(1:6, 2, 3))
B <- matrix(1:3, 3, 1)
A %*% B

Description

Computes $D[i,k] = \|x_i\|^2 - 2 x_i^\top c_k + \|c_k\|^2$ and returns $\arg\min_k D[i,k]$ for each row $i$, 1-indexed. GPU path avoids host round-trips by chaining resident operations.

Usage

pairwise_sqdist_argmin(X, Ct, x_norms = NULL, c_norms = NULL)

Arguments

Value

Integer vector of length n, 1-indexed nearest centroid per row.

Description

Convenience wrapper that calls svd_project followed by svd_reconstruct, yielding the rank-k least-squares approximation of Y in the column space of the original matrix.

Usage

pca_coef(factor, Y)

Arguments

Value

Numeric matrix with the same dimensions as Y, containing the rank-k approximation.

Examples

m <- matrix(rnorm(30), nrow = 6)
A <- adgeMatrix(m)
fac <- svd_factor(A, k = 2L)
approx <- pca_coef(fac, m)

Description

Updates a QR factorization to reflect the removal of a single row from the original matrix. The current implementation refits from the reduced matrix; a Givens-rotation path is planned for a future release.

Usage

qr_downdate(qr_factor, row_idx, X = NULL)

Arguments

Value

An updated amQR factor with row row_idx excluded.

See Also

am_qr, qr_info, lm_loo_cv

Examples

## Not run: 
X <- adgeMatrix(matrix(rnorm(40), nrow = 8))
qf <- am_qr(X)
qf2 <- qr_downdate(qf, row_idx = 3L, X = X)
qr_info(qf2)$dim

## End(Not run)

Description

Returns a named list of metadata fields describing an amQR factor produced by am_qr().

Usage

qr_info(qr)

Arguments

Value

A named list with the following elements:

rank

Integer effective rank of the factored matrix.

dim

Integer vector of length 2: c(nrow, ncol) of the source matrix.

thin

Logical; TRUE when a thin (economy) QR was computed.

pivoted

Logical; TRUE when column pivoting was used.

pivot

Integer permutation vector, or NULL when unpivoted.

representation

Character string describing the internal storage format.

backend_ops

Character string naming the backend that owns any resident buffers, or NULL.

backend

Character string: the preferred backend.

precision

Character string: "strict" or "fast".

method

Character string: QR algorithm used.

compact_factor_available

Logical.

compact_factor_source

Character string or NULL.

compact_factor_materialized

Logical.

q_materialized

Logical.

r_materialized

Logical.

See Also

am_qr, qr_downdate

Examples

X <- adgeMatrix(matrix(rnorm(30), nrow = 6))
qf <- am_qr(X)
info <- qr_info(qf)
info$rank

Description

Computes t(v) %*% solve(X) %*% v (for a vector v) or t(V) %*% solve(X) %*% V (for a matrix V) efficiently via the Cholesky factor of X, without forming the inverse.

Usage

quad_form(factor, v)

Arguments