Metadata-Version: 2.4
Name: hpr
Version: 0.1.1
Summary: Source-built GPU solvers for linear and convex quadratic programming
Maintainer: bay
License-Expression: MIT
Project-URL: Repository, https://github.com/Simonsbay/hpr
Project-URL: Issues, https://github.com/Simonsbay/hpr/issues
Project-URL: Documentation, https://pypi.org/project/hpr/0.1.1/
Project-URL: Release notes, https://github.com/Simonsbay/hpr/blob/release/hpr-0.1.1/releases/0.1.1/RELEASE.md
Project-URL: Upstream LP, https://github.com/PolyU-IOR/HPR-LP-C
Project-URL: Upstream QP, https://github.com/PolyU-IOR/HPR-QP-C
Keywords: optimization,linear-programming,quadratic-programming,CUDA,GPU,HPR
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: licenses/GPU-Presolver-C.txt
License-File: licenses/HPR-LP-C.txt
License-File: licenses/HPR-QP-C.txt
License-File: licenses/PSLP.txt
License-File: licenses/cpu-presolve-reference.txt
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.9
Dynamic: license-file

# hpr

GPU solvers for linear programming (`hpr.lp`) and convex quadratic programming
(`hpr.qp`).

## Installation

```sh
pip install hpr
```

Requires Linux, Python 3.10+, an NVIDIA GPU with a compatible driver, and a
complete CUDA 12 or 13 Toolkit. A C/C++ compiler, Python headers, zlib development
files and OpenSSL libcrypto are also required. Installation compiles both solvers
and downloads missing supported native dependencies. Automatic BLAS/LAPACK setup
requires Debian/Ubuntu x86_64 with APT metadata; other environments need those
libraries installed. Native Windows support is not validated.

## Parameters

Pass an MPS filename, or model arrays: `A`, `AL`, `AU`, `l`, `u`, `c`, and
additionally `Q` for QP. Dense arrays and SciPy sparse matrices are supported.
Both solvers minimize the objective subject to `AL <= A @ x <= AU` and
`l <= x <= u`. LP uses `c @ x`; QP uses `0.5 * x @ Q @ x + c @ x`.
Use `obj_constant` to add a constant. File input and model arrays cannot be mixed.

Omitted options retain the native defaults shown below.

| Setting | LP keyword (default) | QP keyword (default) |
|---|---|---|
| Stopping tolerance | `tol=1e-6` | `stoptol=1e-8` |
| Time limit, seconds | `time_limit=1000` | `time_limit=3600` |
| Iteration limit | `max_iter=2147483647` | `max_iter=2147483647` |
| GPU index | `device=0` | `device_number=0` |
| Convergence check interval | `check_iter=150` | `check_iter=100` |

- **LP:** `presolver="gpu"` accepts `"gpu"`, `"pslp"` or `"none"`.
  `gpu_folding`, `reduced_matrix`, and scaling options `cr`, `ruiz`, `pock`,
  `bc` default to `True`. `cusparse_spmv`, `autotune_verbose` and
  `print_debug_info` default to `False`.
- **QP:** `use_gpu`, `use_scaling`, `polishing` and `verbose` default to `True`.
  `gram_mode="auto"` accepts `"off"`, `"auto"` or `"request"`.
  `spmv_mode_q` and `spmv_mode_a` default to `"auto"` and also accept
  `"cusparse"` or `"customized"`. `print_frequency=-1` uses native logging.
- LP `stop_tol` is an alias of `tol`; QP `gram` is an alias of `gram_mode`.
  Pass only one keyword from each alias pair. Start with defaults and adjust
  tolerance and time limit first. QP `use_gpu=False` selects CPU solving but
  installation still requires CUDA.

## Example

```python
import hpr

# Minimize x[0]**2 + x[1]**2 - 4*x[0] - 2*x[1],
# subject to 0 <= x[0] + x[1] <= 10 and 0 <= x <= 10.
result = hpr.qp(
    Q=[[2.0, 0.0], [0.0, 2.0]],
    A=[[1.0, 1.0]],
    AL=[0.0], AU=[10.0],
    l=[0.0, 0.0], u=[10.0, 10.0],
    c=[-4.0, -2.0],
    stoptol=1e-8,
    time_limit=60,
)
print(result.status, result.primal_obj, result.x)
# Expected optimum: objective approximately -5, x approximately [2, 1].
# QP status 6 means optimal; inspect status and residuals before using a result.

# For an existing LP file: result = hpr.lp("model.mps", tol=1e-6)
```

Both results expose `status`, `primal_obj`, `residuals`, `x`, `y`, and `z`.
LP status is a native string; QP status is a native integer.
