Metadata-Version: 2.1
Name: scs
Version: 3.3.2
Summary: Splitting conic solver
Author-Email: Brendan O'Donoghue <bodonoghue85@gmail.com>
License: MIT License
         
         Copyright (c) 2017 Brendan O'Donoghue
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: C
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Requires-Python: >=3.9
Requires-Dist: numpy
Requires-Dist: scipy
Description-Content-Type: text/markdown

scs-python
===

[![Build Status](https://github.com/bodono/scs-python/actions/workflows/build.yml/badge.svg)](https://github.com/bodono/scs-python/actions/workflows/build.yml)
[![Documentation](https://img.shields.io/badge/docs-online-brightgreen?logo=read-the-docs&style=flat)](https://www.cvxgrp.org/scs/)
[![PyPI Downloads](https://api.pepy.tech/personalized-badge/scs?period=month&units=international_system&left_color=grey&right_color=blue&left_text=PyPI%20downloads%2Fmonth)](https://pepy.tech/projects/scs)
[![Conda Downloads](https://img.shields.io/conda/dn/conda-forge/scs.svg?label=Conda%20downloads)](https://anaconda.org/conda-forge/scs)

Python interface for [SCS](https://github.com/cvxgrp/scs) 3.0.0 and higher.
The full documentation is available [here](https://www.cvxgrp.org/scs/).

## Installation

```bash
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:
```bash
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

```python
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:

```bash
# 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)
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
```

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

```python
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
```

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

```python
# Type-II AA with tighter regularization
solver = scs.SCS(data, cone,
                 acceleration_type_1=0,
                 acceleration_regularization=1e-12)
```

See the [acceleration docs](https://www.cvxgrp.org/scs/algorithm/acceleration.html)
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](https://www.cvxgrp.org/scs/api/cones.html) for
mathematical definitions and data layout details.

## Testing

```bash
pip install pytest
pytest test/
```
