Metadata-Version: 2.1
Name: scs
Version: 3.3.1
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 :: 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
# 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
```

Notes:
- 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 wheels link conda-forge OpenBLAS pinned to 0.3.33: the win-64 0.3.34 build crashes inside its DGEMM kernels on AMD Zen 4/5 CPUs that expose AVX-512 (conda-forge/openblas-feedstock#196), so Windows source builds should avoid that build 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

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