Installation

This guide covers the installation of arraybridge and its optional dependencies.

Requirements

Minimum Requirements:

  • Python 3.9 or later

  • NumPy 1.20 or later

Optional Framework Support:

  • CuPy 10.0+ (for GPU arrays via CuPy)

  • PyTorch 1.10+ (for PyTorch tensors)

  • TensorFlow 2.8+ (for TensorFlow tensors)

  • JAX 0.3+ with jaxlib 0.3+ (for JAX arrays)

  • pyclesperanto 0.10+ (for GPU image processing)

Basic Installation

Install arraybridge with pip:

pip install arraybridge

This installs arraybridge with NumPy as the only dependency. All framework integrations are optional and can be installed separately.

Framework-Specific Installation

Install with specific framework support using extras:

PyTorch Support

pip install arraybridge[torch]

This adds PyTorch as a dependency, enabling conversion to/from PyTorch tensors.

CuPy Support

pip install arraybridge[cupy]

This adds CuPy for GPU array support. Note that CuPy requires CUDA to be installed on your system.

TensorFlow Support

pip install arraybridge[tensorflow]

This adds TensorFlow, enabling conversion to/from TensorFlow tensors.

JAX Support

pip install arraybridge[jax]

This adds JAX and jaxlib for JAX array support.

pyclesperanto Support

pip install arraybridge[pyclesperanto]

This adds pyclesperanto for GPU-accelerated image processing.

All Frameworks

Install all optional framework dependencies at once:

pip install arraybridge[all]

This is useful for development and testing across multiple frameworks.

Development Installation

For development work, install arraybridge in editable mode with development dependencies:

git clone https://github.com/trissim/arraybridge.git
cd arraybridge
pip install -e .[dev]

This includes testing tools (pytest, pytest-cov), linters (black, ruff), and type checking (mypy).

Documentation Building

To build the documentation locally:

pip install -e .[docs]
cd docs
make html

The built documentation will be available in docs/build/html/.

Verifying Installation

After installation, verify that arraybridge is working:

import arraybridge
print(arraybridge.__version__)

# Check which frameworks are available
from arraybridge import detect_memory_type
import numpy as np

data = np.array([1, 2, 3])
print(detect_memory_type(data))  # Should print 'numpy'

If you installed framework support, verify it works:

from arraybridge import convert_memory
import numpy as np

# Example with PyTorch (if installed)
try:
    data = np.array([1, 2, 3])
    torch_data = convert_memory(data, source_type='numpy', target_type='torch')
    print("PyTorch support is working!")
except Exception as e:
    print(f"PyTorch not available: {e}")

GPU Setup

If you want to use GPU features (CuPy, GPU-enabled PyTorch, etc.), ensure you have:

  1. NVIDIA GPU: With compute capability 3.5 or higher

  2. CUDA Toolkit: Compatible version for your framework

  3. cuDNN: Required for TensorFlow and some PyTorch operations

CUDA Installation

For CuPy and GPU support:

  • Install CUDA Toolkit from NVIDIA’s website

  • For CuPy, the CUDA version should match your CuPy installation

  • Check CuPy’s installation guide for version compatibility

PyTorch CUDA

PyTorch can be installed with CUDA support:

# Example for CUDA 12.1
pip install torch --index-url https://download.pytorch.org/whl/cu121

Refer to PyTorch’s official website for the latest installation instructions.

Troubleshooting

Common Issues

Import errors for optional frameworks

If you see import errors like ModuleNotFoundError: No module named 'torch', this means the optional framework is not installed. arraybridge will work with NumPy-only operations, but framework-specific conversions will fail.

CUDA/GPU errors

If you encounter CUDA-related errors:

  • Verify CUDA is installed: nvidia-smi

  • Check that your CUDA version matches your framework requirements

  • Ensure GPU drivers are up to date

Out of memory errors

arraybridge includes automatic OOM recovery, but you may need to:

  • Reduce batch sizes or array dimensions

  • Use the memory cleanup utilities (see Advanced Topics)

  • Monitor GPU memory usage with nvidia-smi

Getting Help

If you encounter issues:

  1. Check the User Guide for usage patterns

  2. Review the API Reference for function signatures

  3. Open an issue on GitHub

Next Steps

After installation: