Merge pull request #381 from cvxgrp/linear-solver-enum-docs

Update Python docs for LinearSolver enum API

Author: bodono

docs/src/api/python.rst

@@ -15,10 +15,7 @@ This module provides the :code:`SCS` class which is initialized using:
 
   solver = scs.SCS(data,
                   cone,
-                  use_indirect=False,
-                  mkl=False,
-                  apple_ldl=False,
-                  gpu=False,
+                  linear_solver=scs.LinearSolver.AUTO,
                   verbose=True,
                   normalize=True,
                   max_iters=int(1e5),
@@ -42,17 +39,52 @@ the cone length or the array that defines the cone (see the third column in
 :ref:`cones` for the keys and what the corresponding values represent).  The
 :code:`b`, and :code:`c` entries must be 1d numpy arrays and the :code:`P` and
 :code:`A` entries must be scipy sparse matrices in CSC format; if they are not
-of the proper format, SCS will attempt to convert them. The
-:code:`use_indirect` setting switches between the sparse direct
-:ref:`linear_solver` (the default) or the sparse indirect solver. If the MKL
-Pardiso direct solver for SCS is :ref:`installed <python_install>` then it can
-be used by setting :code:`mkl=True`. On macOS the Apple Accelerate sparse
-LDL\ :sup:`T` solver is included automatically and can be used by setting
-:code:`apple_ldl=True`. If a GPU solver for SCS is :ref:`installed
-<python_install>` and a GPU is available then it can be used by setting
-:code:`gpu=True`. For the direct GPU solver based on cuDSS set
-:code:`use_indirect=False`. The remaining fields are explained in
-:ref:`settings`.
+of the proper format, SCS will attempt to convert them.
+
+Linear solver selection
+-----------------------
+
+The :code:`linear_solver` setting controls which :ref:`linear_solver` backend
+SCS uses. It accepts a :code:`scs.LinearSolver` enum value.
+The default is :code:`AUTO`, which selects the best available solver for
+the platform:
+
+- **macOS**: QDLDL (Apple Accelerate is available via :code:`LinearSolver.ACCELERATE`)
+- **Linux / Windows**: MKL Pardiso if available, otherwise QDLDL
+
+.. list-table::
+   :header-rows: 1
+
+   * - Value
+     - Description
+   * - :code:`AUTO`
+     - Auto-detect best available solver (default).
+   * - :code:`QDLDL`
+     - Sparse direct solver using `QDLDL <https://github.com/oxfordcontrol/qdldl>`_ (always available).
+   * - :code:`CPU_INDIRECT`
+     - Sparse indirect solver using conjugate gradients (runs on CPU).
+   * - :code:`MKL`
+     - Intel MKL Pardiso direct solver (requires :ref:`MKL build <python_install>`).
+   * - :code:`ACCELERATE`
+     - Apple Accelerate sparse LDL\ :sup:`T` (macOS only, included automatically).
+   * - :code:`CPU_DENSE`
+     - Dense direct solver via LAPACK (requires LAPACK build).
+   * - :code:`GPU_INDIRECT`
+     - Sparse GPU indirect solver (requires GPU build).
+   * - :code:`CUDSS`
+     - Sparse GPU direct solver via cuDSS (requires :ref:`cuDSS build <python_install>`).
+
+Example:
+
+.. code:: python
+
+  # Use the default (auto-detect)
+  solver = scs.SCS(data, cone)
+
+  # Explicitly select a solver
+  solver = scs.SCS(data, cone, linear_solver=scs.LinearSolver.QDLDL)
+
+The remaining fields are explained in :ref:`settings`.
 
 Cone dict
 ---------

docs/src/install/python.rst

@@ -17,26 +17,45 @@ You can also install directly from source
   cd scs-python
   python -m pip install .
 
+Linear solver backends
+----------------------
+
+The pre-built wheels and a from-source install always include two CPU linear
+solvers that require no additional dependencies:
+
+- :code:`QDLDL` — the default sparse direct solver (bundled with SCS).
+- :code:`CPU_INDIRECT` — the sparse matrix-free solver based on conjugate
+  gradients.
+
+The remaining backends require either a platform-specific library (Apple
+Accelerate, MKL) or a build-time flag plus an external dependency (LAPACK for
+dense, CUDA + cuDSS for GPU). Each section below describes what to install and
+how to enable the backend. See :ref:`linear_solver` for an overview of each
+solver and :ref:`python_interface` for how to select one at runtime.
+
 Apple Accelerate (macOS)
 """"""""""""""""""""""""
 
 On macOS the Apple Accelerate backend is built and included automatically —
 no extra install flags are needed. It uses the Accelerate framework's sparse
 LDL\ :sup:`T` solver, which is optimized for Apple hardware including Apple
-Silicon. See :ref:`here <python_interface>` for how to select Accelerate when
-solving.
+Silicon. The default :code:`linear_solver=scs.LinearSolver.AUTO` selects the
+bundled QDLDL on macOS; opt in to Accelerate explicitly with
+:code:`linear_solver=scs.LinearSolver.ACCELERATE`.
 
 MKL
 """
 
-If you have MKL, you can install the MKL Pardiso interface using
+The pre-built wheels (:code:`pip install scs`) include MKL on x86_64 Linux and
+Windows. When installing from source, you can enable MKL with:
 
 .. code:: bash
 
   python -m pip install -Csetup-args=-Dlink_mkl=true .
 
-See :ref:`here <python_interface>` for how to enable MKL when solving. MKL is
-typically faster than the built-in linear system solver.
+When using the default :code:`linear_solver=scs.LinearSolver.AUTO`, MKL is
+selected automatically on Linux and Windows if available. MKL is
+typically faster than the built-in QDLDL linear system solver.
 
 The published Linux x86_64 wheels prefer the threaded MKL variant and include
 the Intel OpenMP runtime (:code:`libiomp5`). Windows currently falls back to
@@ -56,21 +75,71 @@ also checks that the process-wide MKL interface layer matches the LP64/ILP64
 mode it was compiled for, and fails early if another library already set an
 incompatible MKL interface.
 
-GPU
-"""
+Dense direct (LAPACK)
+"""""""""""""""""""""
+
+The :ref:`dense direct solver <dense>` reduces the KKT system to a smaller
+Gram matrix and factorizes it with LAPACK's Cholesky routines. It is well
+suited to small-to-medium problems with a dense constraint matrix :math:`A`,
+where dense BLAS/LAPACK outperforms sparse factorization.
 
-If you have a GPU and cuDSS installed you can install the GPU direct sparse
-solver using
+Build from source with:
+
+.. code:: bash
+
+  python -m pip install -Csetup-args=-Duse_lapack=true .
+
+This requires BLAS and LAPACK development headers to be discoverable by
+:code:`pkg-config`. Most platforms satisfy this out of the box (Apple
+Accelerate on macOS, OpenBLAS / MKL on Linux, MKL on Windows). Select the
+backend at runtime with
+:code:`linear_solver=scs.LinearSolver.CPU_DENSE`.
+
+GPU direct (cuDSS)
+""""""""""""""""""
+
+The :ref:`cuDSS backend <cudss_solver>` runs the sparse direct factorization
+and solves on an NVIDIA GPU via `NVIDIA cuDSS
+<https://developer.nvidia.com/cudss>`_. For large problems it is typically
+substantially faster than any CPU backend.
+
+**Prerequisites.** The build links against both the CUDA runtime and cuDSS,
+so you need all of the following installed and discoverable by
+:code:`pkg-config` / the linker before running :code:`pip install`:
+
+1. An NVIDIA GPU with a recent CUDA-capable driver.
+2. The `CUDA Toolkit <https://developer.nvidia.com/cuda-downloads>`_
+   (provides :code:`nvcc`, the CUDA runtime headers, and :code:`cuda.pc`
+   used by the build).
+3. The `cuDSS library <https://developer.nvidia.com/cudss-downloads>`_ (ships
+   a :code:`cudss.pc` pkg-config file). cuDSS is also available on
+   `conda-forge <https://anaconda.org/conda-forge/libcudss>`_ as
+   :code:`libcudss` / :code:`libcudss-dev`.
+
+Make sure the directories containing :code:`cuda.pc` and :code:`cudss.pc` are
+on :code:`PKG_CONFIG_PATH`, and that the corresponding shared libraries are on
+:code:`LD_LIBRARY_PATH` (Linux) at runtime. A typical Linux environment looks
+like:
+
+.. code:: bash
+
+  export PATH=/usr/local/cuda/bin:$PATH
+  export PKG_CONFIG_PATH=/usr/local/cuda/lib64/pkgconfig:/opt/nvidia/cudss/lib64/pkgconfig:$PKG_CONFIG_PATH
+  export LD_LIBRARY_PATH=/usr/local/cuda/lib64:/opt/nvidia/cudss/lib64:$LD_LIBRARY_PATH
+
+**Install.** Once the prerequisites are in place, build SCS with:
 
 .. code:: bash
 
   python -m pip install -Csetup-args=-Dlink_cudss=true -Csetup-args=-Dint32=true .
 
-See :ref:`here <python_interface>` for how to enable the GPU when solving. The
-sparse direct GPU solver is typically very fast.
+The :code:`int32=true` flag is required because cuDSS only supports 32-bit
+integer indices. Select the backend at runtime with
+:code:`linear_solver=scs.LinearSolver.CUDSS`.
 
-See `here <https://colab.research.google.com/drive/1POCgDNFg8fycHMI9T9N6V3iHFhXRthjn?usp=sharing>`_ for an example colab where the cuDSS version of SCS, along with
-required dependencies, is installed and used.
+See `this Colab notebook <https://colab.research.google.com/drive/1POCgDNFg8fycHMI9T9N6V3iHFhXRthjn?usp=sharing>`_
+for a worked end-to-end example that installs CUDA, cuDSS, and the cuDSS
+build of SCS, then solves a problem on a GPU.
 
 .. _python_spectral_install:
 
@@ -107,8 +176,12 @@ You can install with OpenMP parallelization support using
 
   python legacy_setup.py install --scs --openmp
 
-You can install the GPU indirect solver using
+You can install the :ref:`GPU indirect solver <gpu_indirect>` using
 
 .. code:: bash
 
   python legacy_setup.py install --scs --gpu
+
+The GPU indirect solver is effectively deprecated; the cuDSS direct solver
+above is the recommended GPU backend.
+

docs/src/linear_solver/index.rst

@@ -110,9 +110,11 @@ To build with CMake::
     cmake -DUSE_APPLE_ACCELERATE=ON ..
 
 In Python, the Accelerate backend is included automatically on macOS
-(``pip install scs`` is sufficient). Select it at solve time::
+(``pip install scs`` is sufficient). On macOS,
+``linear_solver=scs.LinearSolver.AUTO`` selects the bundled QDLDL; select
+Accelerate explicitly with::
 
-    solver = scs.SCS(data, cone, apple_ldl=True)
+    solver = scs.SCS(data, cone, linear_solver=scs.LinearSolver.ACCELERATE)
 
 .. _indirect: