# nnls

### cuml.solvers.nnls(A, b, masks=None, b_index=None, , max_iter=None, tol=1e-6, compute_rnorm=True)[[source]](https://github.com/NVIDIA/cuml/blob/30bf74066/python/cuml/cuml/solvers/nnls.pyx#L149)

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`:

```default
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:**
  **A**
  : The coefficient matrix. A NumPy array, a CuPy array, or any object
    implementing `__cuda_array_interface__`. The data is not modified.

  **b**
  : The right-hand side(s).

  **masks**
  : 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_index**
  : 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_iter**
  : The maximum number of active-set iterations per problem. By default
    `3 * n + 1`, which is enough for the method to converge.

  **tol**
  : 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_rnorm**
  : Whether to compute the residual norms. Skipping them saves one pass
    over `A` per problem.
* **Returns:**
  **x**
  : 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.

  **rnorm**
  : 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

```pycon
>>> 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)
```

<!-- !! processed by numpydoc !! -->
