opencudalab 0.1.0__tar.gz

opencudalab-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,113 @@
+name: ci
+
+# Everything here runs without a GPU. That is the point of the device memory
+# provider interface: the allocator core, planner, estimator and calibrator are
+# CUDA-free, so the whole test suite is exercised on hosted runners and only the
+# VMM and runtime backends need the GPU box.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-and-test:
+    name: ${{ matrix.os }} / ${{ matrix.preset }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, macos-14]
+        preset: [release, asan, tsan]
+        exclude:
+          # Apple clang's TSan reports on the pthread interceptors used by the
+          # runtime lock in a way that differs from libstdc++; one platform's
+          # TSan run is enough to catch a real data race.
+          - os: macos-14
+            preset: tsan
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure
+        run: |
+          case "${{ matrix.preset }}" in
+            release) EXTRA="-DCMAKE_BUILD_TYPE=Release" ;;
+            asan)    EXTRA="-DCMAKE_BUILD_TYPE=Debug -DOCL_ENABLE_ASAN=ON" ;;
+            tsan)    EXTRA="-DCMAKE_BUILD_TYPE=Debug -DOCL_ENABLE_TSAN=ON" ;;
+          esac
+          cmake -S . -B build -DOCL_ENABLE_CUDA=OFF -DOCL_WERROR=ON $EXTRA
+
+      - name: Build
+        run: cmake --build build -j
+
+      - name: Test
+        working-directory: build
+        # The stress and thread tests dominate the runtime under a sanitizer, so
+        # the timeout is generous rather than tight.
+        run: ctest --output-on-failure --timeout 900
+
+  # A configure-only check that the CUDA sources still compile as C. It cannot
+  # link or run without a driver, but it catches the common breakage where a
+  # host-side change to provider.h invalidates the VMM or runtime backend and
+  # nobody notices until the next trip to the GPU box.
+  cuda-compile:
+    name: cuda backends compile
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: Jimver/cuda-toolkit@v0.2.19
+        id: cuda
+        with:
+          cuda: '12.5.0'
+          method: network
+          sub-packages: '["nvcc", "cudart", "cuda-driver-dev"]'
+
+      - name: Configure and build
+        run: |
+          cmake -S . -B build-cuda \
+            -DOCL_ENABLE_CUDA=ON -DOCL_ENABLE_TESTS=OFF \
+            -DCMAKE_CUDA_ARCHITECTURES=80
+          cmake --build build-cuda -j
+
+  figures:
+    name: figures regenerate from raw data
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+
+      - name: Install pinned analysis dependencies
+        run: pip install -r analysis/requirements.txt
+
+      # The rule the project enforces from day one is that no number in the
+      # paper is hand-made. This job is what makes that rule verifiable: it
+      # rebuilds every figure and table from the committed CSVs and fails if any
+      # script cannot reproduce its output. It deliberately does not assert that
+      # the bytes match the committed figures: the table headers carry the git
+      # revision, and PDF output is only reproducible within one matplotlib and
+      # platform combination, so a byte check would fail for reasons that have
+      # nothing to do with the results.
+      - name: Regenerate every figure and table
+        run: python analysis/make_all.py --results dev --keep-going
+
+      - name: Report which figures changed
+        if: always()
+        run: git diff --stat -- paper/figures paper/tables || true
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: figures
+          path: |
+            paper/figures
+            paper/tables

opencudalab-0.1.0/.github/workflows/pypi.yml

@@ -0,0 +1,38 @@
+name: pypi
+
+# Source distribution only. Never upload a Mac/Linux wheel from CI: CUDA
+# wheels have to be built on the OS that will run them.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  sdist:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist
+        run: |
+          python -m pip install -U pip build
+          python -m build --sdist
+          test -z "$(find dist -name '*.whl')"
+          ls -l dist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+      - name: Publish to PyPI
+        if: github.event_name == 'release'
+        uses: pypa/gh-action-pypi-publish@release/v1

opencudalab-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+build/
+build-*/
+*.o
+*.a
+*.so
+*.so.*
+*.dylib
+.DS_Store
+__pycache__/
+*.pyc
+.venv/
+dist/
+_skbuild/
+*.egg-info/
+python/*.egg-info/
+analysis/.cache/
+
+# Raw measurement output. results/dev is checked in because the paper's
+# CI-reproducible figures are regenerated from it; everything else is
+# machine-specific and is fetched from the GPU box on demand.
+results/*
+!results/dev/
+paper/*.aux
+paper/*.log
+paper/*.out
+paper/*.bbl
+paper/*.blg
+paper/*.pdf
+!paper/opencuda-lab.pdf

opencudalab-0.1.0/CMakeLists.txt

@@ -0,0 +1,235 @@
+cmake_minimum_required(VERSION 3.20)
+project(opencuda_lab VERSION 0.1.0 LANGUAGES C)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+  set(CMAKE_BUILD_TYPE Release CACHE STRING "" FORCE)
+endif()
+
+option(OCL_ENABLE_CUDA   "Build the CUDA runtime and VMM backends, tools and benchmarks" OFF)
+option(OCL_ENABLE_TESTS  "Build the test suite" ON)
+option(OCL_BUILD_APPS    "Build replay drivers, quickstart and CUDA tools" ON)
+option(OCL_ENABLE_ASAN   "Build with address and undefined-behaviour sanitizers" OFF)
+option(OCL_ENABLE_TSAN   "Build with the thread sanitizer" OFF)
+option(OCL_WERROR        "Treat warnings as errors" ON)
+
+if(DEFINED SKBUILD)
+  set(OCL_ENABLE_TESTS OFF CACHE BOOL "" FORCE)
+  set(OCL_BUILD_APPS OFF CACHE BOOL "" FORCE)
+  set(OCL_WERROR OFF CACHE BOOL "" FORCE)
+  # pip install: use CUDA backends when nvcc is present. Set OCL_FORCE_MOCK=1
+  # to keep the host mock on a machine that also has a toolkit.
+  if(NOT DEFINED ENV{OCL_FORCE_MOCK})
+    include(CheckLanguage)
+    check_language(CUDA)
+    if(CMAKE_CUDA_COMPILER)
+      set(OCL_ENABLE_CUDA ON)
+      message(STATUS "CUDA compiler found; pip package will include GPU backends")
+    endif()
+  endif()
+endif()
+
+# CUDA is optional so the allocator core, planner, estimator, calibrator and the
+# whole test suite can be developed and validated on machines without a GPU.
+if(OCL_ENABLE_CUDA)
+  include(CheckLanguage)
+  check_language(CUDA)
+  if(CMAKE_CUDA_COMPILER)
+    enable_language(CUDA)
+    set(CMAKE_CUDA_STANDARD 14)
+    if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES)
+      set(CMAKE_CUDA_ARCHITECTURES 70 75 80 86 89 90)
+    endif()
+    find_package(CUDAToolkit REQUIRED)
+    set(OCL_HAVE_CUDA TRUE)
+  else()
+    message(WARNING "OCL_ENABLE_CUDA requested but no CUDA compiler was found; "
+                    "building the host-only configuration")
+    set(OCL_HAVE_CUDA FALSE)
+  endif()
+else()
+  set(OCL_HAVE_CUDA FALSE)
+endif()
+
+set(CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS ON)
+
+add_library(ocl_flags INTERFACE)
+if(MSVC)
+  target_compile_options(ocl_flags INTERFACE
+    $<$<COMPILE_LANGUAGE:C>:/W3 /wd4996>)
+  if(OCL_WERROR)
+    target_compile_options(ocl_flags INTERFACE $<$<COMPILE_LANGUAGE:C>:/WX>)
+  endif()
+else()
+  target_compile_options(ocl_flags INTERFACE
+    $<$<COMPILE_LANGUAGE:C>:-Wall -Wextra -Wshadow -Wpointer-arith -Wcast-qual>)
+  if(OCL_WERROR)
+    target_compile_options(ocl_flags INTERFACE $<$<COMPILE_LANGUAGE:C>:-Werror>)
+  endif()
+endif()
+if(OCL_ENABLE_ASAN AND NOT MSVC)
+  target_compile_options(ocl_flags INTERFACE -fsanitize=address,undefined -fno-omit-frame-pointer -g)
+  target_link_options(ocl_flags INTERFACE -fsanitize=address,undefined)
+endif()
+if(OCL_ENABLE_TSAN AND NOT MSVC)
+  target_compile_options(ocl_flags INTERFACE -fsanitize=thread -g)
+  target_link_options(ocl_flags INTERFACE -fsanitize=thread)
+endif()
+
+set(OCL_SOURCES
+  src/core/runtime.c
+  src/core/allocator.c
+  src/core/planner.c
+  src/core/util.c
+  src/core/ocl_vm.c
+  src/estimator/estimator.c
+  src/estimator/conformal.c
+  src/telemetry/telemetry.c
+  src/backend/mock/provider_mock.c
+  src/interop/pytorch_alloc.c)
+
+if(OCL_HAVE_CUDA)
+  list(APPEND OCL_SOURCES
+    src/backend/runtime/provider_runtime.c
+    src/backend/vmm/provider_vmm.c)
+endif()
+
+add_library(opencuda SHARED ${OCL_SOURCES})
+add_library(opencuda_static STATIC ${OCL_SOURCES})
+
+foreach(tgt opencuda opencuda_static)
+  target_include_directories(${tgt} PUBLIC
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+    $<INSTALL_INTERFACE:include>)
+  target_include_directories(${tgt} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
+  target_link_libraries(${tgt} PUBLIC ocl_flags)
+  find_library(OCL_LIBM m)
+  if(OCL_LIBM)
+    target_link_libraries(${tgt} PUBLIC ${OCL_LIBM})
+  endif()
+  find_package(Threads REQUIRED)
+  target_link_libraries(${tgt} PUBLIC Threads::Threads)
+  if(OCL_HAVE_CUDA)
+    target_compile_definitions(${tgt} PUBLIC OCL_WITH_CUDA=1)
+    target_link_libraries(${tgt} PUBLIC CUDA::cudart CUDA::cuda_driver)
+  endif()
+endforeach()
+
+set_target_properties(opencuda PROPERTIES
+  OUTPUT_NAME opencuda VERSION ${PROJECT_VERSION} SOVERSION 0)
+set_target_properties(opencuda_static PROPERTIES OUTPUT_NAME opencuda_static)
+
+# ------------------------------------------------------- benchmark support --
+if(OCL_BUILD_APPS)
+# The workload generators are shared by the host-only replay driver and the CUDA
+# drivers, so that a result produced in CI and one produced on the GPU box refer
+# to the same allocation sequence.
+add_library(ocl_bench STATIC
+  bench/workloads/workloads.c
+  bench/baselines/baselines.c)
+target_include_directories(ocl_bench PUBLIC
+  ${CMAKE_CURRENT_SOURCE_DIR}/bench/workloads
+  ${CMAKE_CURRENT_SOURCE_DIR}/bench/baselines)
+target_link_libraries(ocl_bench PUBLIC opencuda_static)
+
+add_executable(ocl_replay bench/replay/replay.c)
+target_link_libraries(ocl_replay PRIVATE ocl_bench)
+target_include_directories(ocl_replay PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
+
+add_executable(ocl_calibrate experiments/drivers/calibrate.c)
+target_link_libraries(ocl_calibrate PRIVATE ocl_bench)
+target_include_directories(ocl_calibrate PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
+
+add_executable(ocl_admission experiments/drivers/admission.c)
+target_link_libraries(ocl_admission PRIVATE ocl_bench)
+target_include_directories(ocl_admission PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
+
+add_executable(ocl_capacity experiments/drivers/capacity.c)
+target_link_libraries(ocl_capacity PRIVATE ocl_bench)
+target_include_directories(ocl_capacity PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
+
+add_executable(ocl_baselines experiments/drivers/baselines.c)
+target_link_libraries(ocl_baselines PRIVATE ocl_bench)
+target_include_directories(ocl_baselines PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
+
+add_executable(ocl_multitenant experiments/drivers/multitenant.c)
+target_link_libraries(ocl_multitenant PRIVATE ocl_bench)
+target_include_directories(ocl_multitenant PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
+
+# The README's usage example, built and run so that a rename in the public
+# header cannot leave documentation that no longer compiles.
+add_executable(ocl_quickstart examples/quickstart.c)
+target_link_libraries(ocl_quickstart PRIVATE opencuda_static)
+
+if(OCL_HAVE_CUDA)
+  add_executable(ocl_probe tools/ocl_probe.cu)
+  target_link_libraries(ocl_probe PRIVATE CUDA::cudart CUDA::cuda_driver)
+
+  add_executable(ocl_micro tools/ocl_micro.cu)
+  target_link_libraries(ocl_micro PRIVATE CUDA::cudart CUDA::cuda_driver)
+
+  add_executable(ocl_gap tools/ocl_gap.cu)
+  target_link_libraries(ocl_gap PRIVATE ocl_bench CUDA::cudart CUDA::cuda_driver)
+  target_include_directories(ocl_gap PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
+
+  add_executable(ocl_kernels bench/kernels/kernels.cu)
+  target_link_libraries(ocl_kernels PRIVATE ocl_bench CUDA::cudart CUDA::cuda_driver)
+  target_include_directories(ocl_kernels PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
+endif()
+endif() # OCL_BUILD_APPS
+
+# ------------------------------------------------------------------- tests --
+if(OCL_ENABLE_TESTS)
+  enable_testing()
+  set(OCL_TESTS
+    test_allocator
+    test_realloc
+    test_planner
+    test_estimator
+    test_conformal
+    test_admission
+    test_telemetry
+    test_stress
+    test_threads
+    test_pytorch_alloc)
+  if(OCL_BUILD_APPS)
+    list(APPEND OCL_TESTS test_baselines)
+  endif()
+  foreach(t ${OCL_TESTS})
+    add_executable(${t} tests/${t}.c)
+    target_link_libraries(${t} PRIVATE opencuda_static)
+    target_include_directories(${t} PRIVATE
+      ${CMAKE_CURRENT_SOURCE_DIR}/src ${CMAKE_CURRENT_SOURCE_DIR}/tests)
+    add_test(NAME ${t} COMMAND ${t})
+  endforeach()
+  if(OCL_BUILD_APPS)
+    add_test(NAME quickstart COMMAND ocl_quickstart)
+    target_link_libraries(test_baselines PRIVATE ocl_bench)
+  endif()
+endif()
+
+if(DEFINED SKBUILD)
+  install(TARGETS opencuda
+    RUNTIME DESTINATION opencudalab
+    LIBRARY DESTINATION opencudalab
+    ARCHIVE DESTINATION opencudalab)
+  install(FILES examples/python/resnet_cifar10.py DESTINATION opencudalab)
+else()
+  install(TARGETS opencuda opencuda_static
+          RUNTIME DESTINATION bin
+          LIBRARY DESTINATION lib
+          ARCHIVE DESTINATION lib)
+  install(DIRECTORY include/ DESTINATION include)
+
+  configure_file(${CMAKE_CURRENT_SOURCE_DIR}/opencuda.pc.in
+                 ${CMAKE_CURRENT_BINARY_DIR}/opencuda.pc @ONLY)
+  install(FILES ${CMAKE_CURRENT_BINARY_DIR}/opencuda.pc
+          DESTINATION lib/pkgconfig)
+endif()
+
+message(STATUS "OpenCUDA-Lab ${PROJECT_VERSION}")
+message(STATUS "  CUDA backends : ${OCL_HAVE_CUDA}")
+message(STATUS "  tests         : ${OCL_ENABLE_TESTS}")
+message(STATUS "  apps          : ${OCL_BUILD_APPS}")
+message(STATUS "  asan/ubsan    : ${OCL_ENABLE_ASAN}")

opencudalab-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+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
+```