nnls#
- cuml.solvers.nnls(
- A,
- b,
- masks=None,
- b_index=None,
- *,
- max_iter=None,
- tol=1e-6,
- compute_rnorm=True,
Solve a non-negative least squares problem.
Finds
x >= 0minimizing|| A @ x - b ||_2, an analogue ofscipy.optimize.nnls()on the GPU. Many problems that shareAcan be solved at once:bmay hold several right-hand sides, andmasksrestricts each problem to a subset of the columns ofA:argmin_x || A[:, masks[:, j]] @ x - b[:, b_index[j]] ||_2 subject to x >= 0
The Gram matrix
A.T @ Aand the projectionsA.T @ bare 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 withmin(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
Aeach problem may use.masks[i, j]is nonzero iff columniofAis active in problemj. 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)uint8array is used without copying.- b_indexarray-like of int, shape (n_problems,), optional
The column of
bto use in each problem, so that distinct problems can share a right-hand side. By default problemjuses columnjofb.- 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, withintol, 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 adjusttol. 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
Aper problem.
- Returns:
- xcupy.ndarray, shape (n,) or (n, n_problems)
The solution(s), all entries non-negative. This is 1D only if
bis 1D,b_indexis not given andmasks(if given) describes a single problem.- rnormfloat, cupy.ndarray or None
The residual norm(s)
|| A @ x - b ||_2: a float ifxis 1D, and an array of shape(n_problems,)otherwise.Noneifcompute_rnorm=False.
Notes
Aandbare converted tofloat64if either has that dtype, and tofloat32otherwise.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)