Quick reference

This page aims to serve as a reference point for how to initialize and use the cone, model, and solver classes provided by QICS. Further details about these classes can be found in the API reference.

Modelling

QICS solves conic programs of the form

\[\min_{x \in \mathbb{R}^n} \quad c^\top x \quad \text{s.t.} \quad b - Ax = 0, \ h - Gx \in \mathcal{K},\]

where \(c\in\mathbb{R}^n\), \(b\in\mathbb{R}^p\), \(h\in\mathbb{R}^q\), \(A\in\mathbb{R}^{p\times n}\), \(G\in\mathbb{R}^{q\times n}\), and \(\mathcal{K} \subset \mathbb{R}^{q}\) is a Cartesian product of convex cones. This is representing using the qics.Model class, which is initialized using the following parameters.

Input parameters for qics.Model

Parameter	Description	Default
c	numpy.ndarray of size (n, 1) representing the linear objective \(c\).	n/a
A	numpy.ndarray or scipy.sparse.sparray of size (p, n) representing the left-hand side of the linear equality constraints \(A\).	numpy.zeros((0, 1))
b	numpy.ndarray of size (p, 1) representing the right-hand side of the linear equality constraints \(b\).	numpy.zeros((p, 1))
G	numpy.ndarray or scipy.sparse.sparray of size (q, n) representing the left-hand side of the linear conic constraints \(G\).	-numpy.eye(n)
h	numpy.ndarray of size (q, 1) representing the right-hand side of the linear equality constraints \(h\).	numpy.zeros((q, 1))
cones	List of qics.cones representing the Cartesian product of cones \(\mathcal{K}\).	[]
offset	Constant offset term to add to the objective function.	0.0

Note

When the parameters G and h are not specified when initializing a qics.Model, QICS instead solves the simplified conic program

\[\min_{x \in \mathbb{R}^n} \quad c^\top x \quad \text{s.t.} \quad Ax = b, \ x \in \mathcal{K}.\]

Cones

Users define the Cartesian product of cones \(\mathcal{K}\) by defining a list of cone classes from the qics.cones module. We list the definitions and interfaces to all of the cones QICS currently support below.

Symmetric cones

Cone	QICS class	Description
Nonnegative orthant	qics.cones.NonNegOrthant	\(\{ x \in \mathbb{R}^n : x \geq 0 \}\)
Positive semidefinite	qics.cones.PosSemidefinite	\(\{ X \in \mathbb{H}^n : X \succeq 0 \}\)
Second order cone	qics.cones.SecondOrder	\(\{(t, x) \in \mathbb{R} \times \mathbb{R}^{n} : t \geq \|x\|_2\}.\)

Classical entropy cones

Cone	QICS class	Description
Classical entropy	qics.cones.QuantEntr	\(\text{cl}\{ (t, u, x) \in \mathbb{R} \times \mathbb{R}_{++} \times \mathbb{R}^n_{++} : t \geq -u H(u^{-1} x) \}\)
Classical relative entropy	qics.cones.QuantRelEntr	\(\text{cl}\{ (t, x, y) \in \mathbb{R} \times \mathbb{R}^n_{++} \times \mathbb{R}^n_{++} : t \geq H(x \| y) \}\)

Quantum entropy cones

Cone	QICS class	Description
Quantum entropy	qics.cones.QuantEntr	\(\text{cl}\{ (t, u, X) \in \mathbb{R} \times \mathbb{R}_{++} \times \mathbb{H}^n_{++} : t \geq -u S(u^{-1} X) \}\)
Quantum relative entropy	qics.cones.QuantRelEntr	\(\text{cl}\{ (t, X, Y) \in \mathbb{R} \times \mathbb{H}^n_{++} \times \mathbb{H}^n_{++} : t \geq S(X \| Y) \}\)
Quantum conditional entropy	qics.cones.QuantCondEntr	\(\text{cl}\{ (t, X) \in \mathbb{R}\times\mathbb{H}^{\Pi_in_i}_{++}: t \geq -S(X) + S(\text{tr}_i(X)) \}\)
Quantum key distribution	qics.cones.QuantKeyDist	\(\text{cl}\{ (t, X) \in \mathbb{R} \times \mathbb{H}^n_{++} : t \geq -S(\mathcal{G}(X)) + S(\mathcal{Z}(\mathcal{G}(X))) \}\)

Noncommutative perspective cones

Cone	QICS class	Description
Operator perspective trace	qics.cones.OpPerspecTr	\(\text{cl}\{ (t, X, Y) \in \mathbb{R} \times \mathbb{H}^n_{++} \times \mathbb{H}^n_{++} : t \geq \text{tr}[P_g(X, Y)] \}\)
Operator perspective epigraph	qics.cones.OpPerspecEpi	\(\text{cl}\{ (T, X, Y) \in \mathbb{H}^n \times \mathbb{H}^n_{++} \times \mathbb{H}^n_{++} : T \succeq P_g(X, Y) \}\)

Renyi entropy cones

Cone	QICS class	Range of \(\alpha\)	Description
Renyi entropy	qics.cones.RenyiEntr	\([0,1)\)	\(\text{cl} \{ (t, u, X, Y) \in \mathbb{R} \times \mathbb{R}_{++} \times \mathbb{H}^n_{++} \times \mathbb{H}^n_{++} : t \geq u D_\alpha(u^{-1}X \| u^{-1}Y) \}\)
Sandwiched Renyi entropy	qics.cones.SandRenyiEntr	\([1/2,1)\)	\(\text{cl} \{ (t, u, X, Y) \in \mathbb{R} \times \mathbb{R}_{++} \times \mathbb{H}^n_{++} \times \mathbb{H}^n_{++} : t \geq u \hat{D}_\alpha(u^{-1}X \| u^{-1}Y) \}\)
Quasi-relative entropy	qics.cones.QuasiEntr	\([-1,0]\cup[1,2]\)	\(\text{cl} \{ (t, X, Y) \in \mathbb{R} \times \mathbb{H}^n_{++} \times \mathbb{H}^n_{++} : t \geq \text{tr}[ X^\alpha Y^{1-\alpha} ] \}\)
		\([0,1]\)	\(\text{cl} \{ (t, X, Y) \in \mathbb{R} \times \mathbb{H}^n_{++} \times \mathbb{H}^n_{++} : t \geq -\text{tr}[ X^\alpha Y^{1-\alpha} ] \}\)
Sandwiched quasi-relative entropy	qics.cones.SandQuasiEntr	\([1,2]\)	\(\text{cl} \{ (t, X, Y) \in \mathbb{R} \times \mathbb{H}^n_{++} \times \mathbb{H}^n_{++} : t \geq \text{tr}[ ( Y^{\frac{1-\alpha}{2\alpha}} X Y^{\frac{1-\alpha}{2\alpha}} )^\alpha ] \}\)
		\([1/2,1]\)	\(\text{cl} \{ (t, X, Y) \in \mathbb{R} \times \mathbb{H}^n_{++} \times \mathbb{H}^n_{++} : t \geq -\text{tr}[ ( Y^{\frac{1-\alpha}{2\alpha}} X Y^{\frac{1-\alpha}{2\alpha}} )^\alpha ] \}\)

Solving

Input parameters

Once a conic program has been defined by a qics.Model, the problem is solved using a qics.Solver class. This can be initialized with the following settings.

Input parameters for qics.Solver

Parameter	Description	Default
model	qics.Model which specifies an instance of a conic program.	n/a
max_iter	Maximum number of solver iterations before terminating.	100
max_time	Maximum time elapsed, in seconds, before terminating.	3600
tol_gap	Stopping tolerance for (relative) optimality gap.	1e-8
tol_feas	Stopping tolerance for (relative) primal and dual feasibility.	1e-8
tol_infeas	Tolerance for detecting infeasible problem.	1e-12
tol_ip	Tolerance for detecting ill-posed problem.	1e-13
tol_near	Allowable margin for certifying near optimality when solver is stopped early.	1000
verbose	Verbosity level of the solver, where 0: No output. 1: Only print problem and solution summary. 2: Also print summary of the solver at each iteration. 3: Also print symmary of the stepper at each iteration.	2
ir	Whether to use iterative refinement when solving the KKT system.	True
toa	Whether to use third-order adjustments to improve the stepping directions.	True
init_pnt	qics.point.Point representing where to initialize the interior-point algorithm from. Variables which contain numpy.nan are flagged to be intialized using QICS’ default initialization.	None
use_invhess	Whether to avoid using inverse Hessian product oracles by solving a modified cone program with \(G^{-1}(\mathcal{K})=\{x:Gx\in\mathcal{K}\}\).	False if \(G\neq-\mathbb{I}\), \(G\) is full column rank, and \(\mathcal{K}\) mainly consists of QuantRelEntr, OpPerspecEpi, OpPerspecTr. True otherwise.

Output parameters

Once a qics.Solver has been initialized, the conic program can be solved with qics.Solver.solve(). This returns a dictionary which summarizes the solution of the conic program, and has the following keys.

Dictionary keys for output of qics.Solver.solve()

Parameter	Description
x_opt, y_opt, z_opt, s_opt	Optimal primal and dual variables \(x^*\), \(y^*\), \(z^*\), and \(s^*\).
sol_status	Solution status. Can either be optimal: Primal-dual optimal solution reached pinfeas: Detected primal infeasibility dinfeas: Detected dual infeasibility near_optimal: Near primal-dual optimal solution near_pinfeas: Near primal infeasibility near_dinfeas: Near dual infeasibiltiy illposed: Problem is ill-posed unknown: Unknown solution status
exit_status	Solver exit status. Can either be solved: Terminated at desired tolerance max_iter: Exceeded maximum allowable iterations max_time: Exceeded maximum allowable time step_failure: Unable to take another step slow_progress: Residuals are decreasing too slowly
num_iter	Number of solver iterations.
solve_time	Total time elapsed by solver (in seconds).
p_obj, d_obj	Optimal primal objective \(c^\top x^*\) and dual objective \(-b^\top y^* - h^\top z^*\).
opt_gap	Relative optimality gap.
p_feas, d_feas	Relative primal feasibility and dual feasiblity.