Skip to content

About

Python interface for SCS

Topics

Resources

Stars

48 stars

Watchers

4 watching

Forks

Repository files navigation

scs-python

Build Status Documentation PyPI Downloads Conda Downloads

Python interface for SCS 3.0.0 and higher. The full documentation is available here.

Installation

pip install scs

On 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 .

Linear solver backends

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=true

Notes:

  • With use_parallel_psd, a verbose solve prints psd cones projected in parallel by N threads when 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 (set OPENBLAS_NUM_THREADS=1 for that one).
  • x86-64 manylinux wheels ship a _scs_mkl extension 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 conda pkg-config metadata 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.
  • BLAS64 is a general SCS build mode for ILP64 BLAS/LAPACK libraries, not an MKL-only feature.
  • For the MKL Pardiso backend specifically, BLAS64 must 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.

Usage

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 solution

Reusing the solver: new b, c or settings

solver.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.

Anderson acceleration tuning

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.

Cone types

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.

Testing

pip install pytest
pytest test/

About

Python interface for SCS

Topics

Resources

Stars

48 stars

Watchers

4 watching

Forks

Releases

Packages

Used by

Contributors

Languages