lsqlin — Solve constrained linear least squares without forming normal equations.
lsqlin minimizes 0.5*norm(C*x-d)^2 subject to A*x<=b, Aeq*x=beq and lb<=x<=ub with residual-lifted interior-point, bound-reflective trust-region, or feasible active-set iterations.
Syntax
[wsout,resnorm,residual,exitflag,output,lambda] = lsqlin(C,d,A,b,Aeq,beq,lb,ub,ws)
[x,resnorm,residual,exitflag,output,lambda] = lsqlin(C,d,A,b,Aeq,beq,lb,ub,x0,options)
[x,resnorm,residual,exitflag,output,lambda] = lsqlin(problem)Inputs
C- Type
NumericArray- Required
- Yes
- Default
- —
- Description
- Residual coefficient matrix.
d- Type
NumericArray- Required
- Yes
- Default
- —
- Description
- Observation column.
A- Type
NumericArray- Required
- Yes
- Default
- —
- Description
- Inequality coefficients or [].
b- Type
NumericArray- Required
- Yes
- Default
- —
- Description
- Inequality right-hand sides or [].
Aeq- Type
NumericArray- Required
- Yes
- Default
- —
- Description
- Equality coefficients or [].
beq- Type
NumericArray- Required
- Yes
- Default
- —
- Description
- Equality right-hand sides or [].
lb- Type
NumericArray- Required
- Yes
- Default
- —
- Description
- Lower bounds or [].
ub- Type
NumericArray- Required
- Yes
- Default
- —
- Description
- Upper bounds or [].
ws- Type
Any- Required
- Yes
- Default
- —
- Description
- Immutable LsqlinWarmStart containing active-set options, initial point and saved working set.
C- Type
NumericArray- Required
- Yes
- Default
- —
- Description
- Real nonempty residual coefficient matrix, dense or sparse.
d- Type
NumericArray- Required
- Yes
- Default
- —
- Description
- Finite real observation vector with one element per C row.
A- Type
NumericArray- Required
- Yes
- Default
- —
- Description
- Linear inequality coefficients.
b- Type
NumericArray- Required
- Yes
- Default
- —
- Description
- Linear inequality right-hand sides.
Aeq- Type
NumericArray- Required
- No
- Default
- —
- Description
- Linear equality coefficients.
beq- Type
NumericArray- Required
- No
- Default
- —
- Description
- Linear equality right-hand sides.
lb- Type
NumericArray- Required
- No
- Default
- —
- Description
- Lower bounds; omitted trailing elements are unbounded.
ub- Type
NumericArray- Required
- No
- Default
- —
- Description
- Upper bounds; omitted trailing elements are unbounded.
x0- Type
NumericArray- Required
- No
- Default
- —
- Description
- Initial array in original column order; reflective execution uses it and interior-point ignores it.
options- Type
Any- Required
- No
- Default
- —
- Description
- Consumed lsqlin options or [].
problem- Type
Any- Required
- Yes
- Default
- —
- Description
- Scalar problem struct with C, d, solver, options and optional constraint fields.
Returns
x- Type
Any- Description
- Decision column, or a new immutable LsqlinWarmStart for the warm-start calling form; empty numeric decision on terminal failure.
resnorm- Type
NumericArray- Description
- Full sum of squared original residuals, or [] when unavailable.
residual- Type
NumericArray- Description
- Original residual column C*x-d, or [] when unavailable.
exitflag- Type
NumericScalar- Description
- Verified optimization status.
output- Type
Any- Description
- Actual iteration, algorithm and numerical diagnostic information.
lambda- Type
Any- Description
- Recovered original-row eqlin/ineqlin/lower/upper multipliers at a verified optimum; [] otherwise.
Returned values from lsqlin depend on how many outputs the caller requests.
Errors
RunMat:lsqlin:InvalidArgument- When
- Invalid arity or requested output count.
- Message
lsqlin: invalid argument
RunMat:lsqlin:InvalidInput- When
- Invalid numeric geometry, problem fields, or unsupported option.
- Message
lsqlin: invalid input
Observable solver timing
When the fifth output struct is requested, output.wallclocktime is a numeric elapsed duration from the original invocation's admitted monotonic Clock service, captured before input materialization and the solve. A declared deterministic clock supplies its logical duration; this field is not independent physical profiling evidence. Missing clock authority raises RunMat:Clock:ServiceUnavailable before provider access or solver work; no ambient/platform clock or fabricated zero is substituted. Calls requesting fewer than 5 outputs do not read or require this clock. The canonical Clock effect is narrowed only when requested output count is statically known below that threshold.
Inputs
Use lsqlin(C,d,A,b), with [] for no inequalities, then optional complete Aeq,beq and lb,ub pairs followed by x0 and options (4, 6, 8, 9 or 10 arguments). C is a nonempty real matrix; d is a vector with one element per row. Constraint right-hand sides are vectors. Bounds and x0 accept real arrays flattened in column-major order; short bounds leave trailing variables unbounded and emit a warning. The decision output is a column.
A scalar problem struct requires C, d, solver='lsqlin' and options. Optional fields are Aineq, bineq, Aeq, beq, lb, ub and x0. Interior-point validates but does not initialize from x0. Reflective execution uses x0; an omitted point starts at zero. Out-of-bound supplied coordinates move to the interior, and an infeasible default point is replaced as a whole. Inconsistent bounds retain a supplied x0, with empty residual, resnorm and multipliers.
C, A and Aeq retain sparse compressed-column storage in interior-point and reflective modes. Active-set accepts dense operands only. Interior-point introduces one residual variable per observation, a diagonal quadratic term and single-entry residual coefficients. Reflective execution applies C and its transpose directly, uses distance scaling, PCG or rectangular QR/COD and a piecewise reflected line search; none of these methods forms C'*C. Rank-deficient and underdetermined problems are allowed, without a unique or minimum-norm selection guarantee.
Double is the ordinary host input class. Single data conversion to double and role-specific native-integer data are gated RunMat extensions, not ordinary MATLAB host overloads (MATLAB limits Single to code generation/UseCodegenSolver). Native integer data must be exactly representable as binary64; logical, complex and object data reject. Transparent automatic device placement may gather through the original invocation context. Explicit or unproven device intent refuses before any numerical-operand transfer; no device solver is provided.
Warm starts
Create ws=optimwarmstart(x0,optimoptions('lsqlin','Algorithm','active-set')). Then [wsout,resnorm,residual,exitflag,output,lambda]=lsqlin(C,d,A,b,Aeq,beq,lb,ub,ws) returns a new immutable warm start; read its decision column from wsout.X. Supply all nine positions and use [] for missing numeric constraints. Options come from ws.Options, so do not append an options argument. The problem-structure form does not accept a warm start.
A warm start retains actual active-row state, not a numerical factorization. The variable count must match. Every call projects and establishes feasibility for the current seed; changed equalities discard saved state, while saved inequality and bound rows require unchanged geometry and current tightness. Current residual and KKT checks still qualify success. Copies of ws and its properties remain unchanged. An unavailable decision produces an empty X and no reusable state.
Lsqlin warm starts support host double data. Quadprog warm starts, generated-code memory-limit enforcement, finite-workspace warm backing and serialization remain unavailable. See optimwarmstart for read-only properties and the code-generation metadata limits.
Controls and supported algorithm
optimoptions('lsqlin') supplies Algorithm='interior-point', MaxIterations=200, OptimalityTolerance=1e-8, ConstraintTolerance=1e-8 and Display='final'. MaxIterations is an exact nonnegative u32 count shared by all numerical phases, including zero. Positive finite tolerances are honored without a relaxing floor. Legacy MaxIter, TolFun and TolCon name the same controls. Display accepts off/none, iter and final and writes through the original invocation's console authority.
Algorithm='trust-region-reflective' uses bound constraints with matrix-free CG or direct rectangular QR/COD steps. Linear equality or inequality rows select interior-point instead. Equal bounds are not allowed in reflective mode. Its OptimalityTolerance and FunctionTolerance defaults are 100*eps and permit zero. Legacy TolFun supplies both criteria unless a modern criterion is given. MaxPCGIter defaults to max(1,floor(n/2)); TolPCG defaults to 0.1. TypicalX has one positive finite entry per variable and scales unbounded directions when larger than one. Display in this mode accepts off/none and final.
SubproblemAlgorithm='cg' uses the original C/C' products. PrecondBandWidth selects its finite upper preconditioner bandwidth, with zero denoting diagonal preconditioning. SubproblemAlgorithm='factorization' or PrecondBandWidth=Inf uses augmented rectangular QR/COD and trust-radius regularization without forming normal equations. These direct steps report zero CG iterations and leave MaxPCGIter/TolPCG inactive. JacobianMultiplyFcn, optimwarmstart objects, callbacks, Diagnostics, detailed Display spellings, LinearSolver and code-generation controls are unavailable. StepTolerance is active-set-only; an explicit interior-point StepTolerance is rejected. Unconstrained inputs use the selected iterative algorithm rather than an automatic direct-solve shortcut.
Algorithm='active-set' requires a nonempty x0 with one entry per variable, clips out-of-bound coordinates, and shares MaxIterations across its feasibility and working-set phases (default 2000). It solves equality-constrained residual targets with rank-revealing QR/COD, adds blocking original rows and releases negative-dual rows in deterministic order. It checks original residual products, stationarity and constraints before reporting success. StepTolerance defaults to 1e-8 and is positive and finite; a small nonoptimal step is numerical difficulty, not convergence. ObjectiveLimit defaults to -1e20; a feasible half-squared objective below that value stops with flag -3 but supplies no unboundedness certificate.
Only controls used by the effective algorithm are read. Interior-point leaves reflective PCG, TypicalX and FunctionTolerance carriers inactive; reflective execution leaves ConstraintTolerance inactive. Active-set leaves reflective PCG, TypicalX and FunctionTolerance inactive, and reads StepTolerance and ObjectiveLimit. Finite-memory numerical workspace remains unsupported for all algorithms.
Outputs and execution
[x,resnorm,residual,exitflag,output,lambda] returns residual=C*x-d and resnorm=norm(residual)^2, not half the squared norm. lambda at a verified optimum has original-order ineqlin, eqlin, lower and upper columns. Its stationarity convention is C'*residual + A'*lambda.ineqlin + Aeq'*lambda.eqlin - lambda.lower + lambda.upper = 0; no factor of two is applied. Internal residual-equation multipliers are not public equality multipliers.
Interior-point exitflag 1 requires independently recomputed original residuals, original constraint feasibility, stationarity, dual signs, gap and complementarity. Reflective exitflag 1 uses the original residual and scaled bound first-order measure; 3 denotes FunctionTolerance. 0 denotes iteration exhaustion, -2 an exact constraint infeasibility certificate and -8 numerical difficulty or an unverifiable result. Interior-point and reflective stopped solves return a point and residual only when original constraints meet the requested tolerance. Active-set returns its actual stopped point, which can be infeasible; this does not certify feasibility or optimality. Multipliers are returned only at verified first-order success, not at a function-change stop. Unavailable outputs are []; unestablished numerical metrics are NaN. Overflowing/nonfinite validation arithmetic cannot establish success.
Active-set exitflag 1 requires the original KKT checks; 0 is iteration exhaustion, -2 exact infeasibility, -3 the feasible ObjectiveLimit stop, -4 ill-conditioning or a nonoptimal step below StepTolerance, and -8 failure to compute an authenticated step. Multipliers are empty at nonoptimal stops. Problem-based solve retains the original shaped candidate and objective for these stops, including an infeasible iteration-limited candidate, and publishes distinct stop members rather than a feasible-point or unboundedness certificate.
All output structures contain iterations, algorithm, firstorderopt, wallclocktime and message. Interior-point also reports linearsolver, constrviolation and dualitygap; reflective execution reports cgiterations instead. Active-set reports constrviolation but neither cgiterations, linearsolver nor dualitygap. firstorderopt is normalized original stationarity; constrviolation is absolute maximum original violation. Original cancellation and cooperative traversal are preserved; one synchronous sparse factorization is not hard-preemptible. Native and WASM share the numerical owner. Finite host-memory execution is unsupported and rejects before transfers or workspace allocations.
Examples
Inspect residual and bound multipliers
C=[1 0;0 1;1 1]; d=[2;3;5]; opts=optimoptions('lsqlin','Display','off');
[x,resnorm,residual,flag,output,lambda]=lsqlin(C,d,[],[],[],[],[0;0],[1;10],[],opts)Constrain an observation fit
problem.C=eye(2); problem.d=[2;3]; problem.Aeq=[1 1]; problem.beq=1;
problem.solver='lsqlin'; problem.options=optimoptions('lsqlin','Display','off');
[x,resnorm,residual,flag]=lsqlin(problem)Use matrix-free reflective least squares
C=[1 0;0 1;1 1]; d=[2;3;5]; opts=optimoptions('lsqlin','Algorithm','trust-region-reflective','Display','off','MaxPCGIter',2,'OptimalityTolerance',1e-8,'FunctionTolerance',0);
[x,resnorm,residual,flag,output,lambda]=lsqlin(C,d,[],[],[],[],[0;0],[1;10],[],opts)Use a feasible working set
C=[1 0;0 1;1 1]; d=[2;3;5]; opts=optimoptions('lsqlin','Algorithm','active-set','Display','off');
[x,resnorm,residual,flag,output,lambda]=lsqlin(C,d,[],[],[],[],[0;0],[1;10],[0;0],opts)Using lsqlin with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how lsqlin changes the result.
Run a small lsqlin 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 · LsqlinWarmStart.subsasgn · LsqlinWarmStart.subsref · lsqnonlin · lsqnonneg · 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 lsqlin is executed, line by line, in Rust.
- View the source for lsqlin 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.