lsqnonneg — Solve nonnegative linear least squares with an actual feasible active-set method.
lsqnonneg minimizes norm(C*x-d)^2 with x>=0. Passive subproblems use the existing rank-revealing Householder QR/complete orthogonal solver, without forming C'*C.
Syntax
[x,resnorm,residual,exitflag,output,lambda] = lsqnonneg(C,d,options)
[x,resnorm,residual,exitflag,output,lambda] = lsqnonneg(problem)Inputs
C- Type
NumericArray- Required
- Yes
- Default
- —
- Description
- Nonempty real observation coefficient matrix, dense or sparse.
d- Type
NumericArray- Required
- Yes
- Default
- —
- Description
- Real observation vector with one element per C row.
options- Type
Any- Required
- No
- Default
- —
- Description
- Consumed TolX, MaxIter and Display controls or [].
problem- Type
Any- Required
- Yes
- Default
- —
- Description
- Scalar struct with C,d,solver='lsqnonneg' and options.
Returns
x- Type
NumericArray- Description
- Nonnegative decision column, one element per C column.
resnorm- Type
NumericScalar- Description
- Full squared residual norm.
residual- Type
NumericArray- Description
- Original residual d-C*x, opposite to lsqlin.
exitflag- Type
NumericScalar- Description
- 1 verified solution, 0 iteration limit.
output- Type
Any- Description
- Actual accepted-feasibility iterations, active-set algorithm and message.
lambda- Type
NumericArray- Description
- Original dual column C'*(d-C*x), without factor two; nonpositive up to tolerance at convergence.
Returned values from lsqnonneg depend on how many outputs the caller requests.
Errors
RunMat:lsqnonneg:InvalidArgument- When
- Invalid requested output count.
- Message
lsqnonneg: invalid argument
RunMat:lsqnonneg:InvalidInput- When
- Invalid arity, geometry, class, control or problem fields.
- Message
lsqnonneg: invalid input
RunMat:lsqnonneg:NumericalFailure- When
- Numerical rank, original residual/dual validation, or representable coordinates cannot be established.
- Message
lsqnonneg: numerical failure
Inputs and controls
Use lsqnonneg(C,d), lsqnonneg(C,d,options), or a scalar problem struct with C, d, solver='lsqnonneg' and options. C is a nonempty real matrix and d a nonempty vector with one entry per C row. Dense and sparse matrices, row observation vectors, rank-deficient and underdetermined inputs are supported. A unique or minimum-norm nonnegative solution is not promised. Extra problem fields are not interpreted.
Double is the ordinary input class. Single data normalized to double and native-integer C, d and numeric controls are separately declared RunMat extensions. Integer data must be exactly representable as binary64; MaxIter remains an exact structural count. Single floating numeric controls are ordinary scalar controls. Logical, complex and object inputs reject. Authenticated automatic residency may gather through the original invocation; explicit or unproven device intent refuses before any transfer. No gpuArray overload or device optimizer is provided.
options may be [] or a scalar struct such as optimset('Display','final','TolX',1e-10). Display is notify by default (print only on nonconvergence), off/none or final. TolX must be positive and finite when supplied; its default is 10*eps*norm(C,1)*max(size(C)), evaluated in normalized coordinates to avoid norm range loss. RunMat uses TolX as an absolute active-set dual threshold together with physical feasibility, stationary positive coordinates and scaled complementarity checks. It does not promise identical MATLAB stopping details.
MaxIter is a nonnegative exact addressable count; its default is 3*size(C,2). output.iterations counts accepted passive-solution feasibility passes, including subsequent boundary removal/re-solves; rejected independence or prospective-positive probes do not increment it. With MaxIter=0 no passive solve runs; the already verified zero point may return convergence, otherwise it returns an iteration stop. Empty known fields from optimset structures are unset; unsupported nonempty options and unknown/ambiguous names reject. Algorithm selection, callbacks and optimoptions solver construction are not supplied.
Outputs and numerical execution
[x,resnorm,residual,exitflag,output,lambda] returns x as a double column with one element per C column, residual=d-C*x as an observation column and resnorm=norm(residual)^2. The residual sign is opposite to lsqlin. lambda is the original dual column C'*(d-C*x), with no factor of two and no lower-bound multiplier struct. At convergence it is nonpositive up to TolX and approximately zero at positive x; at an iteration stop it is the actual dual estimate, not a convergence certificate.
exitflag 1 requires independently recomputed original physical x, residual and dual conditions. exitflag 0 denotes MaxIter exhaustion and returns the actual feasible iterate. output contains iterations, algorithm='active-set' and message. Numerical rank/representation breakdown or unverifiable original checks raises a numerical error, never a fabricated successful result. Squaring a finite residual norm may legitimately return Inf; nonfinite residual or dual arithmetic cannot establish convergence.
The Lawson–Hanson method selects a positive-dual inactive column, verifies passive rank and prospective positivity, then follows a feasible segment to remove nonpositive passive coordinates when necessary. No unconstrained solution is clamped to manufacture an answer. Positive coefficient scaling is internal; physical outputs and checks use original data. A nonzero coefficient or physical coordinate lost by normalization/conversion raises a numerical error.
Passive-set changes rebuild the owned sparse QR/COD factorization; no incremental rank-update performance claim is made. This can be substantially more expensive on medium or large dense models than an incremental QR implementation. Only selected columns are assembled, and an accepted trial result is reused rather than factored a second time.
The solver requires its selected RuntimeContext; CLI/VM/native/browser invocation supplies it. A contextless direct embedding call returns the canonical capability-unavailable error instead of fabricating execution ownership. Original cancellation/cooperative traversal and factor allocation ownership are preserved; one synchronous storage constructor is not hard-preemptible. Finite host-memory requests refuse before transfer/workspace allocation because the complete passive-set workspace frontier is uncertified. Native and WASM share the same numerical owner.
Examples
Inspect a fitted nonnegative basis
C=[0.0372 0.2869;0.6861 0.7071;0.6233 0.6245;0.6344 0.6170]; d=[0.8587;0.1781;0.0747;0.8405];
[x,resnorm,residual,flag,output,lambda]=lsqnonneg(C,d)Follow an active-set boundary
problem.C=[1 2;0 1]; problem.d=[1;-0.5]; problem.solver='lsqnonneg';
problem.options=optimset('Display','off');
[x,resnorm,residual,flag,output,lambda]=lsqnonneg(problem)Using lsqnonneg with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how lsqnonneg changes the result.
Run a small lsqnonneg example, explain the result, then change one input and compare the output.
Related Math functions
Optim
acceptancesa · annealingboltz · annealingfast · coneprog · crossoverarithmetic · crossoverheuristic · crossoverintermediate · crossoverlaplace · crossoverscattered · crossoversinglepoint · crossovertwopoint · eqnproblem · EquationProblem.solve · EquationProblem.subsasgn · EquationProblem.subsref · evaluate · fgoalattain · fitscalingprop · fitscalingrank · fitscalingshiftlinear · fitscalingtop · fminbnd · fmincon · fminimax · fminsearch · fminunc · fseminf · fsolve · fzero · ga · gacreationlinearfeasible · gacreationnonlinearfeasible · gacreationsobol · gacreationuniform · gacreationuniformint · gaplotbestf · gaplotbestindiv · gaplotdistance · gaplotexpectation · gaplotgenealogy · gaplotmaxconstr · gaplotrange · gaplotscorediversity · gaplotscores · gaplotselection · gaplotstopping · integerConstraint · integral · intlinprog · linprog · lsqcurvefit · lsqlin · LsqlinWarmStart.subsasgn · LsqlinWarmStart.subsref · lsqnonlin · mutationadaptfeasible · mutationgaussian · mutationpositivebasis · mutationpower · mutationuniform · optimexpr · optimget · OptimizationConstraint.evaluate · OptimizationConstraint.subsasgn · OptimizationConstraint.subsref · OptimizationExitflag.double · OptimizationExitflag.eq · OptimizationExitflag.ne · OptimizationExitflag.string · OptimizationExpression.acos · OptimizationExpression.acosh · OptimizationExpression.acot · OptimizationExpression.acoth · OptimizationExpression.acsc · OptimizationExpression.acsch · OptimizationExpression.asec · OptimizationExpression.asech · OptimizationExpression.asin · OptimizationExpression.asinh · OptimizationExpression.atan · OptimizationExpression.atanh · OptimizationExpression.cat · OptimizationExpression.cos · OptimizationExpression.cosh · OptimizationExpression.cot · OptimizationExpression.coth · OptimizationExpression.csc · OptimizationExpression.csch · OptimizationExpression.ctranspose · OptimizationExpression.cumprod · OptimizationExpression.cumsum · OptimizationExpression.diag · OptimizationExpression.diff · OptimizationExpression.dot · OptimizationExpression.eq · OptimizationExpression.evaluate · OptimizationExpression.exp · OptimizationExpression.ge · OptimizationExpression.horzcat · OptimizationExpression.ldivide · OptimizationExpression.le · OptimizationExpression.log · OptimizationExpression.mean · OptimizationExpression.minus · OptimizationExpression.mldivide · OptimizationExpression.mpower · OptimizationExpression.mrdivide · OptimizationExpression.mtimes · OptimizationExpression.norm · OptimizationExpression.plus · OptimizationExpression.power · OptimizationExpression.prod · OptimizationExpression.rdivide · OptimizationExpression.reshape · OptimizationExpression.sec · OptimizationExpression.sech · OptimizationExpression.sin · OptimizationExpression.sinh · OptimizationExpression.sqrt · OptimizationExpression.subsasgn · OptimizationExpression.subsref · OptimizationExpression.sum · OptimizationExpression.tan · OptimizationExpression.tanh · OptimizationExpression.times · OptimizationExpression.trace · OptimizationExpression.transpose · OptimizationExpression.uminus · OptimizationExpression.uplus · OptimizationExpression.vertcat · OptimizationExpression.zeros · OptimizationExpression.zerosLike · OptimizationProblem.solve · OptimizationProblem.subsasgn · OptimizationProblem.subsref · OptimizationVariable.subsasgn · OptimizationVariable.subsref · optimoptions · optimplotconstrviolation · optimplotfirstorderopt · optimplotfunccount · optimplotfval · optimplotfvalconstr · optimplotmilp · optimplotstepsize · optimplotx · optimproblem · optimset · optimvar · optimwarmstart · particleswarm · patternsearch · psplotbestf · psplotbestx · psplotfuncount · psplotmaxconstr · psplotmeshsize · pswcreationuniform · pswplotbestf · quad · quadprog · QuadprogWarmStart.subsasgn · QuadprogWarmStart.subsref · saplotbestf · saplotbestx · saplotf · saplotstopping · saplottemperature · saplotx · savemilpsolutions · secondordercone · selectionremainder · selectionroulette · selectionstochunif · selectiontournament · selectionuniform · simulannealbnd · solve · surrogateopt · surrogateoptplot · temperatureboltz · temperatureexp · temperaturefast
Elementwise
abs · angle · besselj · bsxfun · complex · conj · double · eps · erf · erfcinv · exp · expm1 · flintmax · gamma · gammaln · heaviside · hypot · imag · int16 · int32 · int64 · int8 · intmax · intmin · ldivide · log · log10 · log1p · log2 · minus · nextpow2 · plus · pow2 · power · rdivide · real · realmax · realmin · realsqrt · rescale · sign · single · sqrt · times · typecast · uint16 · uint32 · uint64 · uint8
Trigonometry
acos · acosd · acosh · acotd · acscd · asecd · asin · asind · asinh · atan · atan2 · atan2d · atand · atanh · cos · cosd · cosh · cospi · deg2rad · pol2cart · rad2deg · sin · sind · sinh · sinpi · tan · tand · tanh
Reduction
all · any · bounds · cummax · cummin · cumprod · cumsum · cumtrapz · diff · gradient · max · maxk · mean · median · min · mink · movmax · movmean · movmedian · movmin · movprod · movstd · movsum · movvar · nnz · prod · rms · std · sum · trapz · var
Structure
bandwidth · isdiag · ishermitian · issymmetric · istril · istriu · symrcm
Signal
blackman · butter · buttord · cheb2ord · conv · conv2 · deconv · downsample · envelope · filter · filtfilt · fir1 · freqz · gauspuls · hamming · hann · hilbert · periodogram · pulstran · pwelch · rectpuls · resample · sawtooth · sinc · spectrogram · square · tripuls · unwrap · upsample · zplane
Factor
chol · decomposition · decomposition.ctranspose · decomposition.mldivide · decomposition.mrdivide · decomposition.mtimes · decomposition.rdivide · decomposition.subsref · decomposition.times · decomposition.uminus · decomposition.uplus · eig · eigs · gmres · ichol · ilu · lu · ordeig · ordqz · ordschur · pcg · qr · qz · rsf2csf · schur · svd
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Interpolation
griddedInterpolant · griddedInterpolant.subsref · interp1 · interp1q · interp2 · pchip · ppval · spline
Integer Division
Source you can read
Every RunMat function's source is public. Read exactly how lsqnonneg is executed, line by line, in Rust.
- View the source for lsqnonneg in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.