Kaira - A PyTorch-based toolkit for simulating communication systems

Build Better Communication Systems with Kaira. Kaira is an open-source toolkit for PyTorch designed to help you simulate and innovate in communication systems. Its name is inspired by Kayra (from Turkic mythology, meaning ‘creator’) and Kairos (a Greek concept for the ‘opportune moment’). This reflects Kaira’s core purpose: to empower engineers and researchers to architect (Kayra) advanced communication models and to ensure messages are transmitted effectively and at the right moment (Kairos). Kaira provides the tools to design, analyze, and optimize complex communication scenarios, making it an essential asset for research and development.

Kaira is built to accelerate your research. Its user-friendly, modular design allows for easy integration with existing PyTorch projects, facilitating rapid prototyping of new communication strategies. This is particularly beneficial for developing and testing advanced techniques, such as Deep Joint Source-Channel Coding (DeepJSCC) and other deep learning-based approaches. Kaira helps you bring your innovative communication concepts to life.

Documentation

Features

Research-Oriented: Designed to accelerate communications research.
Versatility: Compatible with various data types and neural network architectures.
Ease of Use: User-friendly and easy to integrate with existing PyTorch projects.
Open Source: Allows for community contributions and improvements.
Well Documented: Comes with comprehensive documentation for easy understanding.

Installation

Overview

This guide provides comprehensive instructions for installing Kaira on your system. Kaira is designed to work across multiple platforms with minimal setup required.

Prerequisites

Python 3.8 or higher
pip (Python package installer)
(Optional) CUDA-compatible GPU for accelerated processing

Installation Methods

Quick Installation

The fastest way to install Kaira is directly from PyPI:

pip install pykaira

From Source

For the latest features or contributions, install from source:

Clone the repository:

git clone https://github.com/ipc-lab/kaira.git
cd kaira

Install the package:
```
pip install .
```

Using Virtual Environment (Recommended)

For a cleaner installation that won’t interfere with other Python packages:

# Create a virtual environment
python -m venv kaira-env

# Activate the environment
# On Linux/macOS:
source kaira-env/bin/activate

# On Windows:
kaira-env\Scripts\activate

# Install Kaira
pip install pykaira

System-Specific Notes

Windows

You may need to run the Command Prompt or PowerShell as administrator
If you encounter path issues, ensure Python is added to your PATH environment variable

macOS

You may need to use python3 explicitly instead of python
Some users may need to install XCode command line tools first: xcode-select --install

Linux

Ensure you have the required build tools: sudo apt-get install build-essential python3-dev (Ubuntu/Debian)

GPU Acceleration

Kaira automatically detects and utilizes available CUDA-compatible GPUs. For GPU support, you need:

Installed the appropriate NVIDIA drivers for your GPU
Installed a compatible version of CUDA Toolkit
Properly set up your system environment variables
PyTorch with GPU support

To install Kaira with GPU support, we recommend following the PyTorch installation instructions first to ensure proper CUDA compatibility:

# Check PyTorch website for the specific command for your system and CUDA version
# https://pytorch.org/get-started/locally/
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118  # Example for CUDA 11.8

# Then install Kaira
pip install pykaira

For more details on PyTorch GPU configuration, please refer to the PyTorch documentation.

No additional Kaira-specific installation commands are required for GPU support as it’s included in the main package.

Optional Dependencies

BPG Image Compression Support

Kaira includes support for BPG (Better Portable Graphics) image compression through the BPGCompressor class. To use this feature, you need to install the BPG command-line tools separately.

Installation Instructions:

Download and Install BPG Tools

Visit the official BPG website: https://bellard.org/bpg/

Download the appropriate binary package for your system or compile from source.

Platform-Specific Instructions:

Linux (Ubuntu/Debian):

# Download and compile from source
wget https://bellard.org/bpg/libbpg-0.9.8.tar.gz
tar xzf libbpg-0.9.8.tar.gz
cd libbpg-0.9.8
make
sudo make install

macOS:

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Force tap homebrew/core
brew tap homebrew/core --force

# Edit the libbpg formula to remove the unmaintained flag
brew edit libbpg

# In the editor that opens, remove the entire line:
# disable! date: "2024-09-26", because: :unmaintained
# Save and quit the editor

# Install libbpg with API bypass
HOMEBREW_NO_INSTALL_FROM_API=1 brew install libbpg

Windows:

Download the pre-compiled Windows binaries from https://bellard.org/bpg/bpg-0.9.8-win64.zip
Extract the ZIP file to a directory (e.g., C:\bpg)
Add the directory containing bpgenc.exe and bpgdec.exe to your system PATH environment variable

Verify BPG Installation:

# Test that BPG tools are available
bpgenc
bpgdec

Usage in Kaira:

from kaira.models.image.compressors.bpg import BPGCompressor

# Create BPG compressor with quality setting
compressor = BPGCompressor(quality=30)

# Or with target bits per image
compressor = BPGCompressor(max_bits_per_image=1000)

Note: If BPG tools are not installed, the BPGCompressor will raise a RuntimeError during initialization. The rest of Kaira’s functionality remains unaffected.

Verifying Installation

Confirm your installation is working correctly:

python -c "import kaira; print(f'Kaira version {kaira.__version__} successfully installed')"

This should display your installed version without any errors.

Troubleshooting

Common Issues:

“ImportError: No module named kaira”: Make sure your virtual environment is activated or reinstall using pip install --force-reinstall pykaira
Permission errors: Use pip install --user pykaira or create a virtual environment
Dependency conflicts: Try installing in a fresh virtual environment
GPU not detected: Verify your CUDA installation with python -c "import torch; print(torch.cuda.is_available())"

For more help, see our Frequently Asked Questions or join our community forum.

Uninstallation

If you need to remove Kaira:

pip uninstall pykaira

Quick Links

GitHub Repository: https://github.com/ipc-lab/kaira/
PyPI Package: https://pypi.org/project/kaira
Codecov: https://codecov.io/gh/ipc-lab/kaira
License: https://github.com/ipc-lab/kaira/blob/master/LICENSE

Support

Get help and connect with the Kaira community through these channels:

Documentation - Official project documentation
GitHub Issues - Bug reports and feature requests
Discussions - General questions and community discussions

License

Kaira is distributed under the terms of the MIT License.

The full text of the license is shown below:

MIT License

Copyright (c) 2025 Information Processing and Communications Lab

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.

Citing Kaira

If you use Kaira in your research, please cite it using the following format:

@software{kaira2025,
title = {Kaira: A {PyTorch}-based toolkit for simulating communication systems},
author = {{Kaira Contributors}},
year = {2025},
url = {https://github.com/ipc-lab/kaira},
version = {0.1.0}
}

Welcome to Kaira’s documentation!

Warning

Kaira is currently in beta. The API is subject to change as we refine the library based on user feedback and evolving research needs.