lupine 0.1.0__tar.gz

lupine-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+.pytest_cache/
+__pycache__/
+dist/

lupine-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: lupine
+Version: 0.1.0
+Summary: Small PyTorch adapter helpers for LUPINE-backed CUDA devices
+License: MIT
+Requires-Python: >=3.9
+Provides-Extra: torch
+Requires-Dist: torch; extra == 'torch'
+Description-Content-Type: text/markdown
+
+# lupine Python adapter
+
+This package provides small PyTorch helpers for LUPINE. It intentionally returns
+ordinary `torch.device("cuda:N")` objects so PyTorch continues to use its normal
+CUDA dispatch path while LUPINE handles CUDA driver/NVML calls underneath.
+
+Declare all LUPINE hosts before any PyTorch CUDA work:
+
+```python
+import lupine
+
+with lupine.connect(host="<server>:14833") as s:
+    device = s.device()
+    model = model.to(device)
+```
+
+`connect()` loads the LUPINE `libcuda.so.1` from `../build/libcuda.so.1` when
+used from this repository. For an installed package, pass `libcuda=...` or set
+`LUPINE_LIBCUDA` if the library lives somewhere else:
+
+```python
+with lupine.connect(host="<server>:14833", libcuda="/opt/lupine/libcuda.so.1") as s:
+    device = s.device()
+```
+
+For multiple LUPINE servers, pass the full host list in one call. The order
+defines the CUDA ordinals that PyTorch sees:
+
+```python
+import lupine
+
+with lupine.connect(host=["<server-a>:14833", "<server-b>:14833"]) as s:
+    gpu0, gpu1 = s.devices()
+    model0 = model0.to(gpu0)  # cuda:0
+    model1 = model1.to(gpu1)  # cuda:1
+```
+
+Do not add a second host after tensors have already been moved to the first one.
+LUPINE opens connections from `LUPINE_SERVER` when CUDA first initializes, and
+later changes to `LUPINE_SERVER` are not picked up by the current process.
+
+Exiting the context restores `LUPINE_SERVER` only if CUDA was not initialized
+inside the block. If CUDA was initialized, the process-global LUPINE connection
+is already active and cannot be disconnected safely.
+
+The adapter does not create a new PyTorch backend such as
+`torch.device("lupine")`. A true custom PyTorch device would require registering
+PrivateUse1 kernels and backend support. LUPINE already works best when PyTorch
+sees CUDA tensors and the LUPINE library is selected through the dynamic linker.

lupine-0.1.0/README.md

@@ -0,0 +1,49 @@
+# lupine Python adapter
+
+This package provides small PyTorch helpers for LUPINE. It intentionally returns
+ordinary `torch.device("cuda:N")` objects so PyTorch continues to use its normal
+CUDA dispatch path while LUPINE handles CUDA driver/NVML calls underneath.
+
+Declare all LUPINE hosts before any PyTorch CUDA work:
+
+```python
+import lupine
+
+with lupine.connect(host="<server>:14833") as s:
+    device = s.device()
+    model = model.to(device)
+```
+
+`connect()` loads the LUPINE `libcuda.so.1` from `../build/libcuda.so.1` when
+used from this repository. For an installed package, pass `libcuda=...` or set
+`LUPINE_LIBCUDA` if the library lives somewhere else:
+
+```python
+with lupine.connect(host="<server>:14833", libcuda="/opt/lupine/libcuda.so.1") as s:
+    device = s.device()
+```
+
+For multiple LUPINE servers, pass the full host list in one call. The order
+defines the CUDA ordinals that PyTorch sees:
+
+```python
+import lupine
+
+with lupine.connect(host=["<server-a>:14833", "<server-b>:14833"]) as s:
+    gpu0, gpu1 = s.devices()
+    model0 = model0.to(gpu0)  # cuda:0
+    model1 = model1.to(gpu1)  # cuda:1
+```
+
+Do not add a second host after tensors have already been moved to the first one.
+LUPINE opens connections from `LUPINE_SERVER` when CUDA first initializes, and
+later changes to `LUPINE_SERVER` are not picked up by the current process.
+
+Exiting the context restores `LUPINE_SERVER` only if CUDA was not initialized
+inside the block. If CUDA was initialized, the process-global LUPINE connection
+is already active and cannot be disconnected safely.
+
+The adapter does not create a new PyTorch backend such as
+`torch.device("lupine")`. A true custom PyTorch device would require registering
+PrivateUse1 kernels and backend support. LUPINE already works best when PyTorch
+sees CUDA tensors and the LUPINE library is selected through the dynamic linker.

lupine-0.1.0/examples/tensor.py

@@ -0,0 +1,35 @@
+# /// script
+# dependencies = [
+#   "numpy",
+#   "lupine",
+#   "torch",
+# ]
+#
+# [tool.uv.sources]
+# lupine = { path = "..", editable = true }
+# ///
+
+import torch
+import lupine
+
+
+def prompt_endpoint() -> str:
+    host = input("LUPINE server host: ").strip()
+    while not host:
+        host = input("LUPINE server host: ").strip()
+
+    port_text = input("LUPINE server port [14833]: ").strip() or "14833"
+    port = int(port_text)
+    return f"{host}:{port}"
+
+
+with lupine.connect(host=prompt_endpoint()) as session:
+    device = session.device()
+    props = torch.cuda.get_device_properties(device)
+    x = torch.arange(8, device=device, dtype=torch.float32)
+    y = (x * 2).cpu()
+    print("cuda available:", torch.cuda.is_available())
+    print("device:", device)
+    print("count:", torch.cuda.device_count())
+    print("gpu:", props.name)
+    print("result:", y.tolist())

lupine-0.1.0/lupine/__init__.py

@@ -0,0 +1,266 @@
+"""PyTorch adapter helpers for LUPINE.
+
+The adapter returns ordinary ``torch.device("cuda:N")`` objects. PyTorch stays
+on its built-in CUDA dispatch path while LUPINE handles CUDA driver calls below
+it.
+"""
+
+from __future__ import annotations
+
+import os
+import ctypes
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+DEFAULT_PORT = 14833
+
+
+class LupineError(RuntimeError):
+    """Raised when the LUPINE adapter cannot select a usable device."""
+
+
+def _torch() -> Any:
+    try:
+        import torch
+    except ModuleNotFoundError as exc:
+        raise LupineError("PyTorch is required to use LUPINE devices.") from exc
+    return torch
+
+
+def _cuda_initialized() -> bool:
+    try:
+        return bool(_torch().cuda.is_initialized())
+    except LupineError:
+        return False
+
+
+def _require_mutable_config() -> None:
+    if _cuda_initialized():
+        raise LupineError("connect to LUPINE before PyTorch initializes CUDA")
+
+
+def _normalize_server(host: str, port: int | None = None) -> str:
+    host = str(host).strip()
+    if not host:
+        raise LupineError("host must not be empty")
+    if port is not None:
+        return f"{host}:{int(port)}"
+    if host.startswith("[") and "]:" in host:
+        return host
+    if host.count(":") == 1:
+        return host
+    return f"{host}:{DEFAULT_PORT}"
+
+
+def _normalize_hosts(host: str | Sequence[str], port: int | None = None) -> tuple[str, ...]:
+    if isinstance(host, str):
+        servers = (_normalize_server(host, port),)
+    else:
+        servers = tuple(_normalize_server(item, port) for item in host)
+    if not servers:
+        raise LupineError("at least one LUPINE host is required")
+    if len(set(servers)) != len(servers):
+        raise LupineError("LUPINE hosts must be unique")
+    return servers
+
+
+def _set_server_env(servers: Sequence[str]) -> None:
+    os.environ["LUPINE_SERVER"] = ",".join(servers)
+
+
+def _default_libcuda() -> Path | None:
+    override = os.environ.get("LUPINE_LIBCUDA")
+    if override:
+        return Path(override)
+    repo_candidate = Path(__file__).resolve().parents[2] / "build" / "libcuda.so.1"
+    if repo_candidate.exists():
+        return repo_candidate
+    return None
+
+
+def _load_libcuda(path: str | os.PathLike[str] | None) -> None:
+    libcuda = Path(path) if path is not None else _default_libcuda()
+    if libcuda is None:
+        return
+    if not libcuda.exists():
+        raise LupineError(f"LUPINE libcuda does not exist: {libcuda}")
+    ctypes.CDLL(str(libcuda), mode=ctypes.RTLD_GLOBAL)
+
+
+def _servers_from_env() -> tuple[str, ...]:
+    value = os.environ.get("LUPINE_SERVER", "")
+    return tuple(server.strip() for server in value.split(",") if server.strip())
+
+
+def _cuda_device(index: int, *, require_available: bool = False) -> Any:
+    torch = _torch()
+    index = int(index)
+    if require_available:
+        count = int(torch.cuda.device_count())
+        if count <= 0:
+            raise LupineError(
+                "PyTorch does not see any CUDA devices. Check that the LUPINE "
+                "client library is selected and LUPINE_SERVER is configured."
+            )
+        if index < 0 or index >= count:
+            raise LupineError(f"CUDA device index {index} is out of range for {count} devices")
+    return torch.device("cuda", index)
+
+
+@dataclass
+class Session:
+    """A process-local LUPINE connection declaration."""
+
+    servers: tuple[str, ...]
+    require_available: bool = False
+    libcuda: str | os.PathLike[str] | None = None
+
+    def __post_init__(self) -> None:
+        if not self.servers:
+            raise LupineError("at least one LUPINE host is required")
+
+    def __enter__(self) -> "Session":
+        _require_mutable_config()
+        self._previous_server = os.environ.get("LUPINE_SERVER")
+        configured = _servers_from_env()
+        if configured and configured != self.servers:
+            raise LupineError(
+                "LUPINE_SERVER is already configured differently; start a new "
+                "process or pass the same hosts to lupine.connect()."
+            )
+        if not configured:
+            _set_server_env(self.servers)
+        _load_libcuda(self.libcuda)
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> bool:
+        if not _cuda_initialized():
+            self._restore_env()
+        return False
+
+    def _restore_env(self) -> None:
+        if getattr(self, "_previous_server", None) is None:
+            os.environ.pop("LUPINE_SERVER", None)
+        else:
+            os.environ["LUPINE_SERVER"] = self._previous_server
+    def devices(self, *, require_available: bool | None = None) -> list[Any]:
+        """Return all declared LUPINE GPUs as ``torch.device("cuda:N")``."""
+
+        check = self.require_available if require_available is None else require_available
+        return [
+            _cuda_device(index, require_available=check)
+            for index in range(len(self.servers))
+        ]
+
+    def device(self, index: int = 0, *, require_available: bool | None = None) -> Any:
+        """Return one declared LUPINE GPU as ``torch.device("cuda:N")``."""
+
+        index = int(index)
+        if index < 0 or index >= len(self.servers):
+            raise LupineError(
+                f"LUPINE device index {index} is out of range for {len(self.servers)} hosts"
+            )
+        check = self.require_available if require_available is None else require_available
+        return _cuda_device(index, require_available=check)
+
+
+def connect(
+    *,
+    host: str | Sequence[str],
+    port: int | None = None,
+    require_available: bool = False,
+    libcuda: str | os.PathLike[str] | None = None,
+) -> Session:
+    """Create a LUPINE session for one or more remote GPU hosts.
+
+    Use the session before any PyTorch CUDA operation:
+
+    ``with lupine.connect(host=["a:14833", "b:14833"]) as s:``
+
+    ``s.devices()`` then returns ``[torch.device("cuda:0"), torch.device("cuda:1")]``.
+    """
+
+    return Session(
+        servers=_normalize_hosts(host, port),
+        require_available=require_available,
+        libcuda=libcuda,
+    )
+
+
+def devices(*, require_available: bool = True) -> list[Any]:
+    """Return devices for the current ``LUPINE_SERVER`` environment."""
+
+    servers = _servers_from_env()
+    if not servers:
+        raise LupineError("LUPINE_SERVER is not configured")
+    return [
+        _cuda_device(index, require_available=require_available)
+        for index in range(len(servers))
+    ]
+
+
+def device(index: int = 0, *, require_available: bool = True) -> Any:
+    """Return one device for the current ``LUPINE_SERVER`` environment."""
+
+    return devices(require_available=require_available)[int(index)]
+
+
+def servers() -> tuple[str, ...]:
+    """Return configured LUPINE servers from ``LUPINE_SERVER``."""
+
+    return _servers_from_env()
+
+
+def is_configured() -> bool:
+    """Return true when ``LUPINE_SERVER`` names at least one server."""
+
+    return bool(servers())
+
+
+def is_available() -> bool:
+    """Return true when PyTorch sees at least one CUDA device."""
+
+    try:
+        torch = _torch()
+    except LupineError:
+        return False
+    return bool(torch.cuda.is_available())
+
+
+def device_count() -> int:
+    """Return PyTorch's CUDA device count."""
+
+    torch = _torch()
+    return int(torch.cuda.device_count())
+
+
+def current_device() -> int:
+    """Return PyTorch's current CUDA device index."""
+
+    torch = _torch()
+    return int(torch.cuda.current_device())
+
+
+def synchronize(index: int = 0) -> None:
+    """Synchronize a LUPINE-backed CUDA device."""
+
+    torch = _torch()
+    torch.cuda.synchronize(_cuda_device(index, require_available=False))
+
+
+__all__ = [
+    "DEFAULT_PORT",
+    "LupineError",
+    "Session",
+    "connect",
+    "current_device",
+    "device",
+    "device_count",
+    "devices",
+    "is_available",
+    "is_configured",
+    "servers",
+    "synchronize",
+]

lupine-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lupine"
+version = "0.1.0"
+description = "Small PyTorch adapter helpers for LUPINE-backed CUDA devices"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+dependencies = []
+
+[project.optional-dependencies]
+torch = ["torch"]
+
+[dependency-groups]
+dev = ["pytest>=8.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["lupine"]

lupine-0.1.0/tests/test_lupine_adapter.py

@@ -0,0 +1,163 @@
+import importlib
+import os
+import sys
+import types
+
+import pytest
+
+
+class FakeDevice:
+    def __init__(self, kind, index=None):
+        self.type = kind
+        self.index = index
+
+    def __eq__(self, other):
+        return isinstance(other, FakeDevice) and (
+            self.type,
+            self.index,
+        ) == (other.type, other.index)
+
+    def __repr__(self):
+        return f"{self.type}:{self.index}"
+
+
+class FakeCuda:
+    def __init__(self):
+        self.initialized = False
+        self.count = 2
+        self.current = 1
+        self.synchronized = None
+
+    def is_initialized(self):
+        return self.initialized
+
+    def is_available(self):
+        return self.count > 0
+
+    def device_count(self):
+        return self.count
+
+    def current_device(self):
+        return self.current
+
+    def synchronize(self, selected):
+        self.synchronized = selected
+
+
+class FakeTorch(types.SimpleNamespace):
+    def __init__(self):
+        super().__init__()
+        self.cuda = FakeCuda()
+
+    def device(self, kind, index=None):
+        return FakeDevice(kind, index)
+
+
+@pytest.fixture
+def lupine_module(monkeypatch):
+    fake_torch = FakeTorch()
+    monkeypatch.setitem(sys.modules, "torch", fake_torch)
+    monkeypatch.delenv("LUPINE_SERVER", raising=False)
+    monkeypatch.setattr("ctypes.CDLL", lambda *args, **kwargs: None)
+    import lupine
+
+    yield importlib.reload(lupine), fake_torch
+    importlib.reload(lupine)
+
+
+def test_connect_sets_env_and_returns_devices(lupine_module):
+    lupine, _ = lupine_module
+
+    with lupine.connect(host="host-a") as session:
+        assert os.environ["LUPINE_SERVER"] == "host-a:14833"
+        assert session.devices() == [FakeDevice("cuda", 0)]
+        assert session.device() == FakeDevice("cuda", 0)
+
+
+def test_connect_loads_explicit_libcuda(lupine_module, monkeypatch, tmp_path):
+    lupine, _ = lupine_module
+    loaded = []
+    libcuda = tmp_path / "libcuda.so.1"
+    libcuda.write_bytes(b"")
+    monkeypatch.setattr(lupine.ctypes, "CDLL", lambda *args, **kwargs: loaded.append(args))
+
+    with lupine.connect(host="host-a", libcuda=libcuda):
+        pass
+
+    assert loaded == [(str(libcuda),)]
+
+
+def test_connect_accepts_multiple_hosts_in_order(lupine_module):
+    lupine, _ = lupine_module
+
+    with lupine.connect(host=["host-a:15000", "host-b:16000"]) as session:
+        assert session.servers == ("host-a:15000", "host-b:16000")
+        assert session.devices() == [FakeDevice("cuda", 0), FakeDevice("cuda", 1)]
+        assert session.device(1) == FakeDevice("cuda", 1)
+
+
+def test_connect_restores_env_when_cuda_was_not_initialized(lupine_module, monkeypatch):
+    lupine, _ = lupine_module
+
+    with lupine.connect(host="host-a"):
+        assert os.environ["LUPINE_SERVER"] == "host-a:14833"
+
+    assert "LUPINE_SERVER" not in os.environ
+
+
+def test_connect_leaves_env_when_cuda_initialized_inside_context(lupine_module):
+    lupine, fake_torch = lupine_module
+
+    with lupine.connect(host="host-a"):
+        fake_torch.cuda.initialized = True
+
+    assert os.environ["LUPINE_SERVER"] == "host-a:14833"
+
+
+def test_connect_accepts_matching_preconfigured_env(lupine_module, monkeypatch):
+    lupine, _ = lupine_module
+    monkeypatch.setenv("LUPINE_SERVER", "host-a:14833")
+
+    with lupine.connect(host="host-a:14833") as session:
+        assert session.devices() == [FakeDevice("cuda", 0)]
+
+
+def test_connect_rejects_different_preconfigured_env(lupine_module, monkeypatch):
+    lupine, _ = lupine_module
+    monkeypatch.setenv("LUPINE_SERVER", "other:14833")
+
+    with pytest.raises(lupine.LupineError, match="already configured differently"):
+        with lupine.connect(host="host-a:14833"):
+            pass
+
+
+def test_connect_refuses_after_cuda_init(lupine_module):
+    lupine, fake_torch = lupine_module
+    fake_torch.cuda.initialized = True
+
+    with pytest.raises(lupine.LupineError, match="before PyTorch initializes CUDA"):
+        with lupine.connect(host="host-a"):
+            pass
+
+
+def test_devices_use_current_env(lupine_module, monkeypatch):
+    lupine, _ = lupine_module
+    monkeypatch.setenv("LUPINE_SERVER", "host-a:14833,host-b:14833")
+
+    assert lupine.devices() == [FakeDevice("cuda", 0), FakeDevice("cuda", 1)]
+    assert lupine.device(1) == FakeDevice("cuda", 1)
+
+
+def test_device_bounds_check(lupine_module):
+    lupine, _ = lupine_module
+
+    with lupine.connect(host="host-a") as session:
+        with pytest.raises(lupine.LupineError, match="out of range"):
+            session.device(1)
+
+
+def test_duplicate_hosts_are_rejected(lupine_module):
+    lupine, _ = lupine_module
+
+    with pytest.raises(lupine.LupineError, match="unique"):
+        lupine.connect(host=["host-a:14833", "host-a"])