Python interface for SCS 3.0.0 and higher. The full documentation is available here.
pip install scsOn x86-64 Linux the manylinux (glibc) wheels include the MKL Pardiso direct linear solver
(MKL linked statically into _scs_mkl, single-threaded) and use it
automatically: it is faster than the built-in QDLDL solver for most problems,
often dramatically so on larger ones, and nothing extra needs to be
installed. Intel's license notice ships in the wheel as
LICENSE-INTEL-MKL.txt. Every other wheel falls back to QDLDL.
To install from source:
git clone --recursive https://github.com/bodono/scs-python.git
cd scs-python
pip install .SCS supports several linear solver backends. The default is AUTO, which
selects the best available solver for the platform:
- macOS: QDLDL (Apple Accelerate is available via
LinearSolver.ACCELERATE) - Linux / Windows: MKL Pardiso if available, otherwise QDLDL
import numpy as np
import scipy.sparse as sp
import scs
# A minimal LP: maximize x subject to 0 <= x <= 1
data = {
"A": sp.csc_matrix(np.array([[1.0], [-1.0]])),
"b": np.array([1.0, 0.0]),
"c": np.array([-1.0]),
}
cone = {"l": 2}
# Auto-detect best backend (default)
solver = scs.SCS(data, cone)
# Explicitly select a solver
solver = scs.SCS(data, cone, linear_solver=scs.LinearSolver.QDLDL)Available values: AUTO, QDLDL, CPU_INDIRECT, MKL, ACCELERATE,
CPU_DENSE, GPU_INDIRECT, CUDSS.
The pre-built wheels (pip install scs) link OpenBLAS on Linux and Windows,
and Apple Accelerate on macOS; the x86-64 manylinux wheels also ship the MKL
Pardiso backend (see Installation). MKL is linked statically rather than
bundled as shared libraries, whose dlopen'd CPU dispatch kernels wheel-repair
tools cannot see (cvxgrp/scs#423). The MKL backend is also available in
source builds (e.g. conda environments providing MKL), where
additional backends can be enabled with build-time flags:
# MKL Pardiso direct solver
pip install . -Csetup-args=-Dlink_mkl=true
# Use 64-bit BLAS/LAPACK integers (ILP64 / BLAS64). Requires the MKL
# backend (-Dlink_mkl=true): standard system BLAS (Accelerate/OpenBLAS)
# is LP64 and the build rejects the combination as unsafe.
pip install . -Csetup-args=-Dlink_mkl=true -Csetup-args=-Duse_blas64=true
# GPU direct solver (cuDSS). Also links cuBLAS and cuSPARSE, which must be
# installed in the same CUDA toolkit as cudart.
pip install . -Csetup-args=-Dlink_cudss=true -Csetup-args=-Dint32=true
# Dense direct solver (LAPACK)
pip install . -Csetup-args=-Duse_lapack=true
# Spectral cones (logdet, nuclear norm, ell-1, sum-of-largest)
pip install . -Csetup-args=-Duse_spectral_cones=true
# Project the PSD blocks of a problem in parallel with OpenMP. Off by
# default: it is only faster when BLAS runs on one thread inside the threads
# of SCS (see "Parallel projection of PSD blocks" in the SCS documentation).
pip install . -Csetup-args=-Duse_openmp=true -Csetup-args=-Duse_parallel_psd=true
# x86-64 Linux, GCC: static MKL (as in the wheel) on its threaded layer, so
# MKL Pardiso and MKL's LAPACK use OMP_NUM_THREADS threads. MKL runs on GCC's
# libgomp, which SCS's OpenMP code shares. The module then needs libgomp at
# run time; the wheel stays sequential.
pip install . -Csetup-args=-Dmkl_static_prefix=/opt/mkl-static \
-Csetup-args=-Dmkl_static_threading=gnu_thread \
-Csetup-args=-Duse_openmp=true -Csetup-args=-Duse_parallel_psd=trueNotes:
- With
use_parallel_psd, a verbose solve printspsd cones projected in parallel by N threadswhen SCS projects the PSD blocks in parallel. The line is absent when SCS keeps the projection serial, for example with a single PSD block, with too little work for threads, with one OpenMP thread, or when it sees an OpenBLAS with a thread pool of its own on more than one thread (setOPENBLAS_NUM_THREADS=1for that one). - x86-64 manylinux wheels ship a
_scs_mklextension with sequential MKL linked statically (CI asserts the shipped inventory and that no wheel carries a dynamic MKL dependency). The musllinux, aarch64, macOS and Windows wheels do not include the MKL backend; Windows source builds use sequential MKL because Intel's condapkg-configmetadata for the threaded variant is still broken. - Windows x86-64 wheels link the OpenBLAS 0.3.33 release binaries from OpenBLAS's GitHub releases, and Windows ARM64 wheels link OpenBLAS 0.3.33 built for the portable ARMV8 target. 0.3.34 is skipped because its DGEMM kernels crash on AMD Zen 4/5 CPUs that expose AVX-512 (fixed in OpenMathLib/OpenBLAS#6013), so Windows source builds should avoid it too.
BLAS64is a general SCS build mode for ILP64 BLAS/LAPACK libraries, not an MKL-only feature.- For the MKL Pardiso backend specifically,
BLAS64must be paired with 64-bit SCS integers (DLONG/int32=false), and SCS now fails early if another library in the process has already fixed MKL to an incompatible LP64/ILP64 interface layer.
import numpy as np
import scipy.sparse as sp
import scs
np.random.seed(0) # so the printed status below is reproducible
m, n = 4, 2
A = sp.random(m, n, density=0.5, format="csc")
b = np.random.randn(m)
c = np.random.randn(n)
P = sp.eye(n, format="csc")
cone = {"l": m} # non-negative cone
data = {"P": P, "A": A, "b": b, "c": c}
solver = scs.SCS(data, cone, verbose=False)
sol = solver.solve()
print(sol["info"]["status"]) # 'solved'
print(sol["info"]["aa_stats"]) # Anderson acceleration diagnostics
print(sol["x"]) # primal solutionsolver.update(b=..., c=...) changes b and c before the next solve()
and keeps the setup (data scaling and factorization). The settings that only
the solve reads, time_limit_secs, max_iters, eps_abs, eps_rel,
eps_infeas, alpha, verbose and log_csv_filename, can be changed the
same way, and stay in force for later solves:
import time
budget = 60.0 # seconds for setup and solve together
t0 = time.perf_counter()
solver = scs.SCS(data, cone, verbose=False)
remaining = budget - (time.perf_counter() - t0)
if remaining > 0: # time_limit_secs=0 would mean no limit
solver.update(time_limit_secs=remaining)
sol = solver.solve()time_limit_secs counts the solve only, so this is how to make a time budget
cover the setup as well. Settings used to set up the solver (scale,
rho_x, normalize, adaptive_scale, adaptive_diag_scale, the
acceleration_* settings, write_data_filename, linear_solver) raise
ValueError and change nothing, even when passed their current value;
create a new scs.SCS object instead.
Unknown names raise TypeError. See the
settings docs for what an
update does not change.
SCS applies Anderson acceleration (AA) on top of ADMM. The defaults work well for most problems, but the following settings can be tuned:
| Setting | Default | Description |
|---|---|---|
acceleration_lookback |
10 |
AA memory size; 0 disables AA. |
acceleration_interval |
5 |
Apply AA every N ADMM iterations. |
acceleration_type_1 |
1 |
1 = type-I AA, 0 = type-II AA. |
acceleration_regularization |
1e-8 |
Tikhonov regularization for the AA least-squares solve; a negative value pins its absolute value. Tuned for type-I; type-II typically prefers 1e-12. |
acceleration_relaxation |
1.0 |
Relaxation factor in [0, 2]; 1.0 is vanilla AA. |
# Type-II AA with tighter regularization
solver = scs.SCS(data, cone,
acceleration_type_1=0,
acceleration_regularization=1e-12)See the acceleration docs for the underlying algorithm.
The cone dict supports the following keys:
| Key | Type | Description |
|---|---|---|
z |
int |
Zero cone |
l |
int |
Non-negative cone |
bu, bl |
array |
Box cone bounds |
q |
list[int] |
Second-order cone lengths |
s |
list[int] |
PSD cone matrix dimensions |
cs |
list[int] |
Complex PSD cone matrix dimensions |
ep |
int |
Primal exponential cone triples |
ed |
int |
Dual exponential cone triples |
p |
list[float] |
Power cone parameters |
With -Duse_spectral_cones=true:
| Key | Type | Description |
|---|---|---|
d |
list[int] |
Log-determinant cone matrix dimensions |
nuc_m, nuc_n |
list[int] |
Nuclear norm cone row/column dimensions |
ell1 |
list[int] |
ell-1 norm cone dimensions |
sl_n, sl_k |
list[int] |
Sum-of-largest-eigenvalues dimensions and k values |
See the cone documentation for mathematical definitions and data layout details.
pip install pytest
pytest test/