Metadata-Version: 2.1
Name: opencudalab
Version: 0.1.0
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` on *that* machine. A Mac wheel is never the CUDA
artifact.

## pip (the real export)

On a Windows/Linux box with NVIDIA GPU, CUDA toolkit, a C/C++ compiler, and CMake:

```bat
pip install opencudalab
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
python -m opencudalab --compare --batches 8
```

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
```

---

## 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
```
