Internals

DECAES.CLI

Experimental Julia app entry point for Julia v1.12 and later. Install the decaes app using the package manager:

$ julia --project=@decaes -e 'using Pkg; Pkg.Apps.add("DECAES")'

The installed decaes app is then usable via:

$ decaes <JULIA ARGS> -- <COMMAND LINE ARGS>

This forwards command line arguments to DECAES.main. Equivalently, the app CLI can be called via:

$ julia --project=@decaes --threads=auto -m DECAES.CLI <COMMAND LINE ARGS>

NNLSLassoWorkspace(A::AbstractMatrix{T}, b::AbstractVector{T})

Preallocated workspace for the $\ell^1$-regularized nonnegative least squares problem

\[\min_{x \ge 0} ||Ax - b||_2^2 + \mu ||x||_1\]

for an m × n matrix A, reusable across solves so that repeated calls to solve! are allocation-free. A and b are held by reference; callers that overwrite either must call reset! before the next solve.

NNLSWorkspace(A::AbstractMatrix{T}, b::AbstractVector{T})
NNLSWorkspace(::Type{T}, m::Int, n::Int)

Preallocated workspace for the nonnegative least squares problem

\[\min_{x \ge 0} ||Ax - b||_2\]

for an m × n matrix A, reused across solves so that repeated calls allocate nothing. Pass it to nnls!, then read the results with solution, dual, components, ncomponents and residualnorm.

The Tikhonov-regularized problem is solved by passing A = [A₀; λI] and b = [b₀; 0], in which case the workspace must be sized for the padded system.

NormalEquation

Singleton type indicating the normal-equations factorization of an NNLSWorkspace; see NormalEquationCholesky.

NormalEquationCholesky <: LinearAlgebra.Factorization

Cholesky factorization of the normal equations AₚᵀAₚ, where Aₚ = A[:, components(work)] holds the positive components of the last solve. Obtained from cholesky(NormalEquation(), work) and usable with ldiv!. The factor is the triangular factor the solver already maintains, so nothing is refactorized.

components(work::NNLSWorkspace)

Original column indices of the positive components in the solution of the last solve.

dual(work::NNLSWorkspace)

Dual vector w = Aᵀ(b - Ax) of the last solve, indexed by original column. At a solution, w ≤ 0 with w = 0 on the solution indices; see components.

issolved(work::NNLSWorkspace)

Whether solution, residual, residualnorm and components hold the solution of the A and b most recently passed to a solve. Every solve sets it. Callers that overwrite the A they solved against must clear it, since the workspace keeps no reference to A and cannot detect the write.

load!(work::NNLSWorkspace, A::AbstractMatrix, b::AbstractVector)

Copy the problem data A and b into work. The sizes must match those the workspace was constructed for.

ncomponents(work::NNLSWorkspace)

Number of positive components in the solution of the last solve.

nnls!(work::NNLSWorkspace, A::AbstractMatrix, b::AbstractVector)
nnls!(work::NNLSWorkspace, A::AbstractMatrix, b::AbstractVector, λ::Real)

Solve min_{x ≥ 0} ||Ax - b||₂ in place, returning solution(work).

The second form solves the Tikhonov-regularized problem min_{x ≥ 0} ||A₀x - b₀||₂² + λ²||x||₂² and requires A = [A₀; λI] and b = [b₀; 0], i.e. size(A, 1) > size(A, 2).

x = nnls(A, b; ...)

Solves non-negative least-squares problem by the active set method of Lawson & Hanson (1974).

Optional arguments:

- max_iter: maximum number of iterations (counts inner loop iterations)

References:

- Lawson, C.L. and R.J. Hanson, Solving Least-Squares Problems
- Prentice-Hall, Chapter 23, p. 161, 1974

residual(work::NNLSWorkspace)

Residual r = b₀ - A₀x of the last solve, in original data coordinates. Every solve leaves it current, so consumers that need the residual itself, and not only its norm, can read it instead of rebuilding b₀ - A₀[:, P] x_P. For the padded Tikhonov convention only the leading m₀ data rows are meaningful; the Tikhonov rows contribute λ²||x₊||² to the norm separately. Note the sign: this is b₀ - A₀x, the negative of the fit residual reported by the output maps.

residualnorm(work::NNLSWorkspace)

Residual norm ||Ax - b||₂ at the solution of the last solve.

solution(work::NNLSWorkspace)

Solution x of the last solve, indexed by original column. Inactive components are exactly zero.

Algorithm NNLS: NONNEGATIVE LEAST SQUARES

The original version of this code was developed by Charles L. Lawson and Richard J. Hanson at Jet Propulsion Laboratory 1973 JUN 15, and published in the book "SOLVING LEAST SQUARES PROBLEMS", Prentice-HalL, 1974. Revised FEB 1995 to accompany reprinting of the book by SIAM.

GIVEN AN M BY N MATRIX, A, AND AN M-VECTOR, B, COMPUTE AN N-VECTOR, X, THAT SOLVES THE LEAST SQUARES PROBLEM A * X = B SUBJECT TO X .GE. 0