Metadata-Version: 2.4
Name: nvqsp
Version: 0.1.0.post1
Summary: GPU-accelerated sparse RODAS4 stiff ODE solver for QSP/PBPK population studies
License-Expression: LicenseRef-NVIDIA-Software-License-Agreement
Project-URL: Homepage, https://github.com/NVIDIA-Digital-Bio/nvQSP
Project-URL: NVIDIA SLA, https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-software-license-agreement/
Project-URL: AI Product Terms, https://www.nvidia.com/en-us/agreements/enterprise-software/product-specific-terms-for-ai-products/
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Provides-Extra: test
Requires-Dist: scipy; extra == "test"
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# nvQSP — GPU-Accelerated RODAS4 ODE Solver

GPU-accelerated RODAS4 (4th-order Rosenbrock) stiff ODE solver for
Quantitative Systems Pharmacology (QSP) and PBPK population studies.
Solves thousands of patient simulations per second on a single NVIDIA GPU.

## Install

```bash
pip install nvqsp
```

**No CUDA Toolkit required** — only an NVIDIA driver (525+) and GPU
(Ampere, Ada Lovelace, or Hopper).

## Quick Start

```python
import numpy as np
from nvqsp import sparse
from nvqsp.options import SparseOptions

# Two-compartment model: dy/dt = A0 + A1*y + A2*(y⊗y)
neq = 2
A0 = np.array([0.0, 0.0])

# First-order (linear) terms in CSR format
A1_rowptr = np.array([0, 2, 4], dtype=np.int32)
A1_col    = np.array([0, 1, 0, 1], dtype=np.int32)
A1_val    = np.array([-0.3, 0.1, 0.3, -0.1])

# Second-order terms — must have >= 1 entry; use epsilon for linear models
A2_rowptr = np.array([0, 1, 1], dtype=np.int32)
A2_col1   = np.array([0], dtype=np.int32)
A2_col2   = np.array([0], dtype=np.int32)
A2_val    = np.array([1e-30])

# Solve for 100 patients with a 100 mg dose at t=0
result = sparse.solve(
    A0=A0,
    A1_csr=(A1_rowptr, A1_col, A1_val),
    A2_csr=(A2_rowptr, A2_col1, A2_col2, A2_val),
    y0=np.tile([10.0, 0.0], (100, 1)),
    times=np.linspace(1.0, 24.0, 48),
    doses=[(0.0, 100.0)],
    opts=SparseOptions(rtol=1e-6, atol=1e-9),
)

print(result.y.shape)   # (100, 48, 2) — batch × time × state
print(result.steps)     # total ODE steps across all patients
```

## Model Form

The solver handles polynomial ODE systems:

```
dy/dt = A0 + A1·y + A2·(y ⊗ y)
```

| Term | Shape | Meaning |
|---|---|---|
| `A0` | `(neq,)` | Zeroth-order (constant synthesis, zero-order infusion) |
| `A1` | `(neq, neq)` sparse CSR | First-order (linear elimination, transfer rates) |
| `A2` | `(neq, neq, neq)` sparse CSR | Second-order bilinear (mass-action kinetics) |

**Covers:** linear PBPK models, first-order absorption, IV bolus/infusion,
bimolecular mass-action kinetics (drug-receptor binding).

**Does not cover:** Michaelis-Menten elimination, Hill-function PD, TMDD with
quasi-steady-state, indirect response models, DAE systems.

## Key Features

- **Batch solving** — 1 to 10,000+ patients in a single GPU launch
- **Automatic Jacobian** — analytic from the polynomial representation
- **Adaptive step control** — per-patient with configurable tolerances
- **Dosing events** — bolus doses at specified times
- **Per-patient parameters** — vary A0, A1, A2 values across patients
- **Fat binary** — sm_80 (Ampere), sm_89 (Ada Lovelace), sm_90 (Hopper) + PTX

## Solver Options

```python
from nvqsp.options import SparseOptions

opts = SparseOptions(
    rtol            = 1e-6,    # Relative ODE tolerance
    atol            = 1e-12,   # Absolute ODE tolerance
    max_steps       = 20000,   # Maximum ODE steps per interval
    linsol_max_iters= 30,      # BiCGSTAB iteration limit
)
```

## Requirements

- Linux x86_64
- NVIDIA GPU: Ampere (sm_80), Ada Lovelace (sm_89), or Hopper (sm_90)
- NVIDIA driver 525+ (CUDA runtime 12.0+)
- Python 3.8+, NumPy

## Documentation

Full documentation, C API reference, and the Debian package are available at:

https://github.com/NVIDIA-Digital-Bio/nvQSP

## License

This software is licensed under the
[NVIDIA Software License Agreement](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-software-license-agreement/)
and the
[Product-Specific Terms for AI Products](https://www.nvidia.com/en-us/agreements/enterprise-software/product-specific-terms-for-ai-products/).
By installing this software you agree to the terms of both licenses.
