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

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`) include MKL on x86_64 Linux and
Windows, and Apple Accelerate on macOS. When installing from source, 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)
pip install . -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:
- Linux x86_64 wheels are built and tested against threaded MKL, and CI asserts a `libiomp5` dependency on the packaged `_scs_mkl` extension. Windows currently falls back to sequential MKL because Intel's conda `pkg-config` metadata for the threaded variant is still broken.
- `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` | `10` | 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. 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/
```
