Metadata-Version: 2.1
Name: opencudalab
Version: 0.1.7
Summary: Risk-calibrated GPU memory runtime (libopencuda) with Python bindings
Keywords: cuda,gpu,memory,allocator,conformal
Author: OpenCUDA-Lab
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: C
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Project-URL: Homepage, https://pypi.org/project/opencudalab/
Requires-Python: >=3.9
Provides-Extra: vision
Requires-Dist: torch>=2.1; extra == "vision"
Requires-Dist: torchvision>=0.16; extra == "vision"
Description-Content-Type: text/markdown

# Install OpenCUDA-Lab 0.1 (exportable preview)

This is **not** a frozen production ABI (`SOVERSION` is still 0).

The PyPI package is a **source distribution**. `pip install opencudalab`
compiles `libopencuda` **inside pip** on that machine (Ninja from pip;
CMake generator is chosen for the host). The third person does not run
CMake by hand. A Mac wheel is never the CUDA artifact.

| Host | Compiler pip uses | GPU backends |
| --- | --- | --- |
| Google Colab | preinstalled `gcc` | on if `nvcc` is present |
| Linux / RHEL | `gcc` (`dnf install gcc cmake`) | on if `nvcc` is present |
| Windows | MSVC (`cl.exe` via vswhere / Build Tools) | on if `nvcc` is present |
| macOS | clang | mock only (no NVIDIA) |

Windows still needs Visual Studio **C++** Build Tools installed; pip
cannot invent `cl.exe`. It will find VS automatically (no x64 Native
Tools prompt, no NMake).

## pip (what a third person runs)

Needs: Python 3.9+ and a C compiler as in the table. `nvcc` on `PATH`
enables GPU backends.

```bat
pip install opencudalab
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
python -c "from opencudalab import Runtime, install_pytorch_allocator; print('ok')"
```

`ocl_pytorch_alloc` is always compiled into the shared library. After
`pip install`, `import opencudalab` loads the DLL from `site-packages`.

If CUDA is on `PATH` (`nvcc`), the GPU backends are built automatically.
Force the mock backend: `set OCL_FORCE_MOCK=1` before pip install.

Until the project is published to PyPI, the same command works from a clone:

```bat
pip install .
```

## USB tarball (no GitHub / no PyPI yet)

```bash
./scripts/pack_v1.sh
```

Copy `dist/opencudalab-0.1.0-usb.tar.gz`. Do **not** copy a Mac `.dylib`.

## Windows + NVIDIA + CUDA (friend laptop)

Needs: NVIDIA GPU, CUDA Toolkit, Visual Studio 2022 **Build Tools** (C++ workload),
Python 3.10+, CMake on PATH (`winget install Kitware.CMake`).

In **x64 Native Tools Command Prompt** or a terminal where `nvcc` works:

```bat
tar -xf opencudalab-0.1.0.tar.gz
cd opencudalab-0.1.0

python -m venv .venv
.venv\Scripts\activate
python -m pip install -U pip

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124

pip install opencudalab
```

Then the with-vs-without comparison:

```bat
python -m opencudalab --compare --batches 8
```

Or without pip, CMake + the example:

```bat
cmake -S . -B build -DOCL_ENABLE_CUDA=ON
cmake --build build --config Release
python examples/python/resnet_cifar10.py --compare --lib build\Release\opencuda.dll
```

If native Windows build fights you, **WSL2 Ubuntu + CUDA on WSL** is the same
Linux path as the paper's GPU box:

```bash
cmake -S . -B build -DOCL_ENABLE_CUDA=ON && cmake --build build -j
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
python examples/python/resnet_cifar10.py --compare --lib build/libopencuda.so
```

Look at `torch_peak_alloc_MiB` and `ocl_n_oom_actual` in the table.

---

## pip (Mac / Linux)

From this repo, or from PyPI after publish:

```bash
pip install opencudalab
python -c "import opencudalab; print(opencudalab.library_path())"
python -m opencudalab --cpu --compare --dataset synthetic
```

On this Mac that installs the mock backend (no NVIDIA GPU).

To publish the source distribution (maintainers):

```bash
./scripts/publish_pypi.sh           # build + print upload commands
./scripts/publish_pypi.sh --test    # TestPyPI (needs token)
./scripts/publish_pypi.sh --upload  # PyPI (needs token)
```

---

## Homebrew (macOS, mock backend only)

```bash
brew install cmake
./scripts/pack_v1.sh
brew install --build-from-source ./packaging/homebrew/opencudalab.rb
```

---

## Python API (0.1.4+)

`opencudalab.Runtime` / `Pipeline` wrap the C ABI. ctypes layouts are not part of
notebooks. Mock-backend checks (no GPU):

```bash
cmake -S . -B build -DOCL_ENABLE_CUDA=OFF
cmake --build build -j
PYTHONPATH=python pytest tests/python/test_api.py
```

## C / pkg-config

```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
cmake --install build --prefix /usr/local
pkg-config --libs --cflags opencuda
```

---

## Java (JNA, same DLL/.so/.dylib)

```bash
cd bindings/java
mvn -q package
# Windows: put opencuda.dll on PATH or java.library.path
mvn -q exec:java
```
