nnls#

cuml.solvers.nnls(
A,
b,
masks=None,
b_index=None,
*,
max_iter=None,
tol=1e-6,
compute_rnorm=True,
)[source]#

Solve a non-negative least squares problem.

Finds x >= 0 minimizing || A @ x - b ||_2, an analogue of scipy.optimize.nnls() on the GPU. Many problems that share A can be solved at once: b may hold several right-hand sides, and masks restricts each problem to a subset of the columns of A:

argmin_x  || A[:, masks[:, j]] @ x - b[:, b_index[j]] ||_2
subject to  x >= 0

The Gram matrix A.T @ A and the projections A.T @ b are computed once and shared by all problems, so solving a batch is much cheaper than solving the problems one at a time. The solver is an active-set method that keeps the state of one problem in GPU shared memory, which limits it to problems with min(m, n) up to a few thousand (depending on the GPU and the dtype); larger problems raise an error.

Parameters:
Aarray-like, shape (m, n)

The coefficient matrix. A NumPy array, a CuPy array, or any object implementing __cuda_array_interface__. The data is not modified.

barray-like, shape (m,) or (m, n_targets)

The right-hand side(s).

masksarray-like of bool or uint8, shape (n, n_problems), optional

Which columns of A each problem may use. masks[i, j] is nonzero iff column i of A is active in problem j. Columns that are not active get a coefficient of exactly zero. A 1D mask of shape (n,) describes a single problem. By default all columns are active in all problems. An F-contiguous (column-major) uint8 array is used without copying.

b_indexarray-like of int, shape (n_problems,), optional

The column of b to use in each problem, so that distinct problems can share a right-hand side. By default problem j uses column j of b.

max_iterint, optional

The maximum number of active-set iterations per problem. By default 3 * n + 1, which is enough for the method to converge.

tolfloat, default=1e-6

Absolute tolerance on the projected gradient A.T @ (A @ x - b): a problem is solved once the gradient is nonnegative, within tol, at the coefficients that are zero. The tolerance is not relative to the magnitude of the data, so for data of very large or very small scale, rescale the data or adjust tol. In single precision, a tolerance below the rounding error of the gradient is raised to that error.

compute_rnormbool, default=True

Whether to compute the residual norms. Skipping them saves one pass over A per problem.

Returns:
xcupy.ndarray, shape (n,) or (n, n_problems)

The solution(s), all entries non-negative. This is 1D only if b is 1D, b_index is not given and masks (if given) describes a single problem.

rnormfloat, cupy.ndarray or None

The residual norm(s) || A @ x - b ||_2: a float if x is 1D, and an array of shape (n_problems,) otherwise. None if compute_rnorm=False.

Notes

A and b are converted to float64 if either has that dtype, and to float32 otherwise.

Examples

>>> import cupy as cp
>>> from cuml.solvers import nnls
>>> A = cp.array([[1, 0], [1, 0], [0, 1]], dtype=cp.float32)
>>> b = cp.array([2, 1, 1], dtype=cp.float32)
>>> x, rnorm = nnls(A, b)