Package: qss
QSS: Quadratic-Separable SolverQSS solves problems of the form$$\begin{equation*} \begin{array}{ll} \text{minimize} & (1/2) x^T P x + q^T x + r + g(x) \\ \text{subject to} & Ax = b \end{array} \end{equation*}$$where $x \in \bf{R}^n$ is the decision variable being optimized over. The
objective is defined by a positive definite matrix $P \in \bf{S}^n_+$, a vector
$q \in \bf{R}^n$, a scalar $r \in \bf{R}$, and a $g$ that is separable in the
entries of $x$, i.e., $g$ can be written as
$$g(x) = \sum_{i=1}^n g_i(x_i).$$
The constraints are defined by a matrix $A \in \bf{R}^{m \times n}$ and a vector
$b \in \bf{R}^m$.To use QSS, the user must specify $P$, $q$, $r$, $A$, $b$, as well as the $g_i$ from a built-in collection of separable functions.Installationpip install qssUsageAfter installingqss, import it withimportqssThis will expose the QSS class which is used to instantiate a solver object:solver=qss.QSS(data)Use thesolve()method when ready to solve:results=solver.solve(eps_abs=1e-5,eps_rel=1e-5,alpha=1.4,rho=0.1,max_iter=np.inf,precond=True,warm_start=False,reg=True,use_iter_refinement=False,verbose=False,)Parametersdata: dictionary with the following keys:'P','q','r','A','b'specify the quadratic part of the objective and the linear constraint as in the problem formulation above.'P'and'A'should bescipy.sparseCSC matrices or QSSLinearOperators (see below),'q'and'b'should benumpyarrays,  and'r'should be a scalar.'A'and'b'can be excluded fromdataor set toNoneif the linear equality constraints are not needed.'g'is a list of separable function definitions. Each separable function is declared as a dictionary with the following keys:'g': string that corresponds to a valid separable function name (see below for a list of supported functions).'args':'weight'(default 1),'scale'(default 1),'shift'(default 0) allow the'g'function to be applied in a weighted manner to a shifted and scaled input. Some functions take additional arguments, see below.'range': tuple specifying the start index and end index that the function should be applied to.Note that the zero function will be applied to any indices that don't have another function specified for them.eps_abs: scalar specifying absolute tolerance.eps_abs: scalar specifying relative tolerance.alpha: scalar specifying overstep size.rho: scalar specifying ADMM step size.max_iter: maximum number of ADMM iterations to perform.precond: boolean specifying whether to perform matrix equilibration.warm_start: boolean specifying whether to warm start upon a repeat call ofsolve().reg: boolean specifying whether to regularize KKT matrix. May fail on certain problem instances if set toFalse.use_iter_refinement: boolean, only matters ifregisTrue. Helps mitigate some of the accuracy loss due to regularization.verbose: boolean specifying whether to print verbose output.ReturnsA list containing the following:objective: the objective value attained by the solution found byqss.solution: the solution vector.Separable functionsThe following convex separable functions are supported ( $\mathcal{I}$ is the $\{0, \infty\}$ indicator function):FunctionParameters$g_i(x)$zero$0$abs$|x|$is_pos$\mathcal I(x \geq 0)$is_neg$\mathcal I(x \leq 0)$is_boundlb: lower bound (default 0),ub: upper bound (default 1)$\mathcal I(l \leq x \leq u)$is_zero$\mathcal I(x = 0)$pos$\max\{x, 0\}$neg$\max\{-x, 0\}$quantiletau: scalar in $(0, 1)$$0.5 |x| + (\tau - 0.5) x$huberM: positive scalar$x^2 \text{ if } |x| \leq M, 2M|x| - M^2 \text{ else}$The following nonconvex separable functions are supported:FunctionParameters$g_i(x)$card$0$ for $x = 0$; $1$ for $x \neq 0$is_int$\mathcal I(x \text{ is an integer})$is_finite_setS: Python list of scalars$\mathcal I(x \in S)$is_bool$\mathcal I(x \in \{0,1\})$Thet(weight),a(scale),b(shift) parameters are used to shift and scale the above as follows:t * g(ax - b).ExampleApplying the Huber function to a shifted version of the first 100 entries:[{"g":"huber","args":{"M":2,"shift":-5},"range":(0,100)}]Abstract linear operatorsQSS comes with built-in support for abstract linear operators via theqss.linearoperator.LinearOperatorclass (hereafter referred to simply asLinearOperator).The easiest way to build aLinearOperatoris via its constructor. The argument to the constructor should be a list of lists representing a block matrix, in which each block is one of the following:SciPy sparse matrix orscipy.sparse.linalg.LinearOperatororqss.linearoperator.LinearOperatororNone.As an example, a constraint matrixAcould be built as follows:fromqss.linearoperatorimportLinearOperatorA=LinearOperator([[None,F,-I],[I,I,None]])WhereFis ascipy.sparse.linalg.LinearOperatorthat implements the Fourier transform andIis a SciPy sparse identity matrix.There are several helper functions available to facilitate the creation ofLinearOperators, all accessible throughqss.linearoperator:block_diag(D): Returns a block diagonalLinearOperatorfromD, a list of linear operators (SciPy sparse matrix,scipy.sparse.linalg.LinearOperator, orqss.linearoperator.LinearOperator).hstack(D): Horizontally concatenates list of linear operatorsDinto a singleLinearOperator.vstack(D): Vertically concatenates a list of linear operatorsDinto a singleLinearOperator.Left and right matrix multiplication between aLinearOperatorand a NumPy array is supported. Multiplication betweenLinearOperators is currently not supported. Matrix-vector multiplication between aLinearOperatorFand a NumPy arrayvcan be achieved withF.matvec(v)orF @ v. Multiplication with the adjoint ofFcan be achieved withF.rmatvec(v)orv @ F.Note that solve times may be slower whenLinearOperators are involved. If eitherPorAis aLinearOperator, the linear KKT system central to the QSS algorithm is solved indirectly, as opposed to directly via a factorization.ExampleNonnegative least squares is a problem of the form$$\begin{equation*} \begin{array}{ll} \text{minimize} & (1/2) \Vert Gx - h \Vert_2^2 \\ \text{subject to} & x \geq 0. \end{array} \end{equation*} $$qsscan be used to solve this problem as follows:importnumpyasnpimportscipyasspimportqssp=100n=500G=sp.sparse.random(n,p,density=0.2,format="csc")h=np.random.rand(n)data={}data["P"]=G.T@Gdata["q"]=-h.T@Gdata["r"]=0.5*h.T@hdata["g"]=[{"g":"is_pos","range":(0,p)}]# Enforce x >= 0solver=qss.QSS(data)objective,x=solver.solve()print(objective)DevelopmentTo create a virtual environment, runpython3 -m venv envActivate it withsource env/bin/activateClone theqssrepository,cdinto it, and installqssin development mode:pip install -e ./ -r requirements.txtFinally, test to make sure the installation worked:pytest tests/