Metadata-Version: 2.4
Name: tensor-ipc
Version: 0.1.0
Summary: High-performance IPC for tensor data with seamless ROS integration
Home-page: https://github.com/danielhou315/tensor-ipc
Author: Daniel Hou
Author-email: Daniel Hou <houhd@umich.edu>
License: MIT License
        
        Copyright (c) 2025 Huaidian Hou
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/danielhou315/tensor-ipc
Project-URL: Repository, https://github.com/danielhou315/tensor-ipc.git
Project-URL: Issues, https://github.com/danielhou315/tensor-ipc/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: cyclonedds==0.10.5
Requires-Dist: posix-ipc>=1.0.0
Provides-Extra: torch
Requires-Dist: torch>=1.10.0; extra == "torch"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Provides-Extra: all
Requires-Dist: torch>=1.10.0; extra == "all"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Tensor IPC

High-performance and Flexible IPC for tensor data with seamless ROS integration for robotics research.

## Overview

`tensor-ipc` provides efficient shared memory communication for tensor data between processes, with built-in support for ROS topics. It enables zero-copy data sharing using POSIX shared memory and integrates with ROS for distributed communication and sim/real transfer.

## Key Features

- 🚀 **Zero-Copy Shared Memory**: POSIX shared memory with per-frame locking for safe concurrent access
- 🤖 **ROS Integration**: Built-in ROS producers and consumers with automatic type conversion (custom types are supported through ros2_numpy)
- 🧠 **Multi-Backend Support**: Native support for NumPy arrays and PyTorch tensors (CPU/CUDA)
- 📦 **DDS Notifications**: Real-time notifications and synchronization using CycloneDDS for efficient polling
- 🛡️ **Type Safety**: Automatic validation of tensor shapes, dtypes, and devices
- 🔄 **History Management**: Configurable history buffers with circular indexing

## Installation

```bash
git clone https://github.com/danielhou315/tensor-ipc.git
cd tensor-ipc
pip install -e .
```
- For torch/torch CUDA support, you must install `torch` in the same Python environment. 
- For ROS support, you must install [ros2_numpy](https://github.com/Box-Robotics/ros2_numpy) in the same Python environment.
- Otherwise, only `numpy` backend will be available. 

## Quick Start

Refer to `examples/` to see basic usage. Documentation is coming soon (hopefully). 

### CUDA Support

```python
import torch
from tensor_ipc.core.producer import TensorProducer

# CUDA tensors with IPC sharing
if torch.cuda.is_available():
    cuda_tensor = torch.zeros(3, 224, 224, device='cuda:0')
    producer = TensorProducer.from_sample("cuda_pool", cuda_tensor)
    
    # Publish CUDA tensor directly
    gpu_data = torch.randn(3, 224, 224, device='cuda:0')
    producer.put(gpu_data)
```

### Callbacks and Notifications

```python
def on_new_data(data):
    print(f"Callback triggered with data shape: {data.shape}")

consumer = TensorConsumer(
    metadata,
    on_new_data_callback=on_new_data
)

# Callback will be triggered when new data arrives
```

### History Management

```python
# Get last 5 frames in chronological order
history = consumer.get(history_len=5, latest_first=False)

# Get last 3 frames with latest first
recent = consumer.get(history_len=3, latest_first=True)
```

## Architecture

- **Backends**: Pluggable backends for NumPy, PyTorch CPU, and PyTorch CUDA
- **Shared Memory**: Numpy/PyTorch backend uses POSIX shared memory with memory-mapped arrays. Torch CUDA backend uses CUDA API through PyTorch. 
- **Locking**: Per-frame reader-writer locks for safe concurrent access
- **Notifications**: CycloneDDS for real-time progress updates
- **ROS Bridge**: Automatic conversion between ROS messages and tensor data

## API Reference

### Core Classes

- `TensorProducer`: Creates and publishes to shared memory pools
- `TensorConsumer`: Subscribes to and reads from shared memory pools
- `PoolMetadata`: Describes pool structure and properties

### ROS Extensions

- `ROSTensorProducer`: Publishes shared memory data to ROS topics
- `ROSTensorConsumer`: Subscribes to ROS topics and creates shared memory pools

### Metadata Creation

- `MetadataCreator.from_numpy_sample()`: Create metadata from NumPy arrays
- `MetadataCreator.from_torch_sample()`: Create metadata from PyTorch tensors
- `MetadataCreator.from_torch_cuda_sample()`: Create metadata for CUDA tensors
- `MetadataCreator.from_sample()`: Unifies creation of metadata from sample

## Requirements

- Python 3.7+
- NumPy
- CycloneDDS (for DDS notifications)
- Optional: PyTorch (for tensor support)
- Optional: ROS 2 + ros2_numpy (for ROS integration)

## License

MIT License

## GenAI 
This library (especially documentation) is partly written by various LLMs. 
