Opensportslib Setup Environment (PyTorch, CUDA aware & Optional Dependencies)

.github/workflows/ci-tests.yml

@@ -20,7 +20,8 @@ jobs:
       - name: Install package and test dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[test,localization,py-geometric]" -f https://pytorch-geometric.com/whl/torch-2.10.0+cu128.html
+          pip install -e ".[test]"
+          opensportslib setup --pyg --dali
 
       - name: Run smoke tests
         run: bash scripts/run_smoke_tests.sh

CONTRIBUTING.md

@@ -20,12 +20,18 @@ Install the base package or include optional dependencies for specific tasks lik
 ```bash
 # Install core package in editable mode
 pip install -e .
+```
+
+#### Step 4: Setup Environment (PyTorch, CUDA aware & Optional Dependencies)
+```bash
+# Install PyTorch (CPU/GPU auto-detected)
+opensportslib setup
+
+# Optional: install PyTorch Geometric support
+opensportslib setup --pyg
 
-# OR for localization support
-pip install -e ".[localization]"
-
-# OR want to use "torch-geometric","torch-scatter", "torch-sparse", "torch-cluster", "torch-spline-conv"
-pip install -e ".[py-geometric]" -f https://pytorch-geometric.com/whl/torch-2.10.0+cu128.html
+# Optional: install for DALI support
+opensportslib setup --dali
 ```
 
 ## 2. Branching and Merging - Daily workflow for developers

README.md

@@ -29,7 +29,9 @@ OpenSportsLib is designed for **researchers, ML engineers, and sports analytics
 
 ## Installation
 
-> Requires **Python 3.12+**.
+> Requires **Python 3.12+**.  
+> Supports CUDA 12.6 / 12.8 / 13.0 (with CPU fallback).  
+> PyTorch Geometric is supported up to PyTorch 2.10.*.
 
 ### Stable release
 
@@ -43,6 +45,23 @@ pip install opensportslib
 pip install --pre opensportslib
 ```
 
+### Setup Environment (PyTorch, CUDA aware & Optional Dependencies)
+```bash
+# Install PyTorch (CPU/GPU auto-detected)
+opensportslib setup
+
+# Optional: install PyTorch Geometric support
+opensportslib setup --pyg
+
+# Optional: install for DALI support
+opensportslib setup --dali
+``` 
+---
+
+**Note:**  
+Run `opensportslib setup` to automatically configure dependencies.  
+If issues occur, manually install compatible versions of `torch`, `torchvision`, and related libraries according to your CUDA version or system compatibility.
+
 ---
 
 ## Data and pretrained models
@@ -166,13 +185,6 @@ cd opensportslib
 pip install -e .
 ```
 
-### With extras
-
-```bash
-pip install -e ".[localization]"
-pip install -e ".[py-geometric]" -f https://pytorch-geometric.com/whl/torch-2.10.0+cu128.html
-```
-
 ### Conda option
 
 If you prefer conda:
@@ -183,6 +195,18 @@ conda activate osl
 pip install -e .
 ```
 
+### Setup Environment (PyTorch, CUDA aware & Optional Dependencies)
+```bash
+# Install PyTorch (CPU/GPU auto-detected)
+opensportslib setup
+
+# Optional: install PyTorch Geometric support
+opensportslib setup --pyg
+
+# Optional: install for DALI support
+opensportslib setup --dali
+```
+
 ### Git workflow
 
 1. Make sure you are branching from `dev`

docs/getting-started/installation.md

@@ -13,6 +13,11 @@ conda create -n osl python=3.12 pip
 conda activate osl
 ```
 
+> Requires **Python 3.12+**  
+> Supports CUDA 12.6 / 12.8 / 13.0 (with CPU fallback).  
+> PyTorch Geometric is supported up to PyTorch 2.10.*.
+
+
 #### PyPI install
 Stable version
 ```bash
@@ -26,6 +31,25 @@ pip install --pre opensportslib
 !!! note
     The `--pre` flag installs the latest pre-release version from PyPI.
 
+#### Setup Environment (PyTorch, CUDA aware & Optional Dependencies)
+```bash
+# Install PyTorch (CPU/GPU auto-detected)
+opensportslib setup
+
+# Optional: install PyTorch Geometric support
+opensportslib setup --pyg
+
+# Optional: install for DALI support
+opensportslib setup --dali
+```
+
+---
+
+!!! note   
+    Run `opensportslib setup` to automatically configure dependencies.
+    If issues occur, manually install compatible versions of `torch`, `torchvision`, and related libraries according to your CUDA version or system compatibility.
+
+
 ## Verify installation
 
 ```python
@@ -56,10 +80,16 @@ Install the base package or include optional dependencies for specific tasks lik
 ```bash
 # Install core package in editable mode
 pip install -e .
+```
+
+#### Step 4: Setup Environment (PyTorch, CUDA aware & Optional Dependencies)
+```bash
+# Install PyTorch (CPU/GPU auto-detected)
+opensportslib setup
+
+# Optional: install PyTorch Geometric support
+opensportslib setup --pyg
 
-# OR for localization support
-pip install -e ".[localization]"
-
-# OR want to use "torch-geometric","torch-scatter", "torch-sparse", "torch-cluster", "torch-spline-conv"
-pip install -e ".[py-geometric]" -f https://pytorch-geometric.com/whl/torch-2.10.0+cu128.html
+# Optional: install for DALI support
+opensportslib setup --dali
 ```

opensportslib/core/utils/data.py

@@ -57,10 +57,8 @@ def tracking_collate_fn(batch):
     except ImportError as exc:
         raise ImportError(
             "torch-geometric is required for tracking_collate_fn. "
-            "Install with: pip install \"opensportslib[py-geometric]\" "
-            "-f https://pytorch-geometric.com/whl/torch-2.10.0+cu128.html "
-            "or (editable): pip install -e \".[py-geometric]\" "
-            "-f https://pytorch-geometric.com/whl/torch-2.10.0+cu128.html"
+            "Run: `opensportslib setup --pyg` to install the correct version "
+            "based on your system (PyTorch & CUDA compatible)."
         ) from exc
 
     batch_size = len(batch)

opensportslib/datasets/classification_dataset.py

@@ -500,11 +500,9 @@ def _getitem_preloaded(self, idx):
             from torch_geometric.data import Data
         except ImportError as exc:
             raise ImportError(
-                "torch-geometric is required for tracking_parquet datasets. "
-                "Install with: pip install \"opensportslib[py-geometric]\" "
-                "-f https://pytorch-geometric.com/whl/torch-2.10.0+cu128.html "
-                "or (editable): pip install -e \".[py-geometric]\" "
-                "-f https://pytorch-geometric.com/whl/torch-2.10.0+cu128.html"
+                "torch-geometric is required for tracking_collate_fn. "
+                "Run: `opensportslib setup --pyg` to install the correct version "
+                "based on your system (PyTorch & CUDA compatible)."
             ) from exc
 
         from opensportslib.datasets.utils.tracking import normalize_features
@@ -546,11 +544,9 @@ def _getitem_on_the_fly(self, idx):
             from torch_geometric.data import Data
         except ImportError as exc:
             raise ImportError(
-                "torch-geometric is required for tracking_parquet datasets. "
-                "Install with: pip install \"opensportslib[py-geometric]\" "
-                "-f https://pytorch-geometric.com/whl/torch-2.10.0+cu128.html "
-                "or (editable): pip install -e \".[py-geometric]\" "
-                "-f https://pytorch-geometric.com/whl/torch-2.10.0+cu128.html"
+                "torch-geometric is required for tracking_collate_fn. "
+                "Run: `opensportslib setup --pyg` to install the correct version "
+                "based on your system (PyTorch & CUDA compatible)."
             ) from exc
 
         from opensportslib.datasets.utils.tracking import (

opensportslib/models/backbones/builder.py

@@ -39,11 +39,9 @@
 
 
 _PYG_IMPORT_ERROR_MSG = (
-    "torch-geometric is required for graph/tracking models. "
-    "Install with: pip install \"opensportslib[py-geometric]\" "
-    "-f https://pytorch-geometric.com/whl/torch-2.10.0+cu128.html "
-    "or (editable): pip install -e \".[py-geometric]\" "
-    "-f https://pytorch-geometric.com/whl/torch-2.10.0+cu128.html"
+    "torch-geometric is required for tracking_collate_fn. "
+    "Run: `opensportslib setup --pyg` to install the correct version "
+    "based on your system (PyTorch & CUDA compatible)."
 )