Installing Qualia¶

Introduction¶

Welcome to the Qualia installation guide. Qualia is a modular system composed of multiple components that work together. There are three main ways to set up Qualia:

User Setup: For using Qualia as is or developing independent plugins. Choose between three package managers:
- uv (Recommended for best performance)
- PDM (Recommended for advanced dependency management)
- pip (Simple option)
Developer Setup: For modifying Qualia’s core components.
Docker Setup: For a containerized environment with GPU support.

Before You Begin¶

System Requirements¶

Python >= 3.9, <= 3.12 (recommended: 3.12)
Git
For GPU support: NVIDIA GPU with appropriate drivers

Understanding Virtual Environments¶

Virtual environments provide isolated spaces for Python packages, preventing conflicts between different projects and making your setup more reproducible. We’ll use them throughout this guide.

User Setup¶

Brackets enable specifying optional dependency groups at installation, see the “Optional Dependencies” section below for more information.

Option 1: Using uv (Recommended for Performance)¶

uv is an extremely fast Python package installer and resolver.

# Install uv
pip install uv

# Create and activate a virtual environment
uv venv qualia_env
source qualia_env/bin/activate  # Unix/macOS
qualia_env\Scripts\activate     # Windows

# Install Qualia with PyTorch support
uv pip install qualia-core[pytorch]

Option 2: Using PDM (Recommended for Dependency Management)¶

PDM is a modern Python package manager with robust dependency management.

# Install PDM
# On Ubuntu 24.10 or newer:
sudo apt install python3-pdm
# Or using pip:
pip install pdm

# Create and set up project
pdm venv create -n qualia_env
$(pdm venv activate qualia_env)

# Install Qualia
pdm add qualia-core[pytorch]

Option 3: Using pip (Simple Option)¶

For a straightforward setup using standard Python tools:

# Create virtual environment
python -m venv qualia_env
source qualia_env/bin/activate  # Unix/macOS
qualia_env\Scripts\activate     # Windows

# Install Qualia
pip install -U qualia-core[pytorch]

Developer Setup¶

For modifying Qualia’s source code, follow these steps using either uv or PDM:

Using uv for Development¶

# Clone repositories
git clone https://github.com/LEAT-EDGE/qualia-core.git
cd qualia-core

# Create development environment
uv venv qualia_env
source qualia_env/bin/activate

# Install dependencies
uv pip install -e .

# For additional components
uv pip install -e .[pytorch, clearml, AllTheComponentAvailable]

# For all available components
uv pip install -e .[codegen,tensorflow,pytorch,gtsrb,gsc,dataaugmentation_image,clearml,visualize,deployment-sparkfunedge,evaluation-host-tflite,evaluation-target-qualia,tests,lint,typecheck,docs]

Using PDM for Development¶

# Clone repositories
git clone https://github.com/LEAT-EDGE/qualia-core.git
cd qualia-core

# Create development environment
pdm venv create -n qualia_env
pdm use "$(pwd)/qualia_env/bin/python"

# Install dependencies
pdm add -e ./qualia-core[pytorch,clearml] --dev

# For additional components
git clone https://github.com/LEAT-EDGE/qualia-core.git
pdm add -e ./qualia-core[pytorch,clearml] --dev

The -e flag enables “editable” mode, allowing source code changes to take effect without reinstalling.

Docker Setup¶

For a ready-to-use environment with GPU support, use our Docker container.

Detailed Docker setup instructions continue as in the original document…

Optional Dependencies¶

Qualia uses a modular system. Add features by including them in brackets:

# Using uv
uv pip install "qualia-core[pytorch,clearml,visualize]"

# Using PDM
pdm add "qualia-core[pytorch,clearml,visualize]"

# Using pip
pip install "qualia-core[pytorch,clearml,visualize]"

Available options:

Machine Learning: [pytorch], [tensorflow]
Development: [codegen], [tests], [lint], [typecheck], [docs]
Visualization: [visualize], [clearml]
Datasets: [gtsrb], [gsc], [pytorch3drotation], [dataaugmentation_image]
Deployment: [deployment-sparkfunedge], [evaluation-host-tflite], [evaluation-target-qualia]

Qualia components¶

If you want to take a look at all the available components here is the link Optional Components.

Common Issues and Solutions¶

Package Installation Errors¶

You may need to install additional dependencies:

# Python packages
uv pip install --upgrade pip virtualenv graphviz tensorflow torch-optimizer matplotlib numpy pydot
# or with PDM
pdm add pip virtualenv graphviz tensorflow torch-optimizer matplotlib numpy pydot

# System packages (Ubuntu/Debian)
sudo apt install cmake ninja-build git gcc

Cmake ninja-build gcc are used for compiling C code.

Environment Issues¶

# Check Python version
python --version  # Should be 3.9-3.12 (3.11 recommended)

# Verify Qualia installation
pip show qualia-core

# If using wrong Python version
uv venv qualia_env --python=3.11
# or with PDM
pdm venv create -n qualia_env 3.11

Others¶

If you encounter issues:

Check error messages carefully
Verify Python version (3.12 recommended)
Ensure virtual environment is activated
Check all dependencies are installed

Remember to activate your environment before using Qualia:

# For uv and pip:
source qualia_env/bin/activate  # Unix/macOS
qualia_env\Scripts\activate     # Windows

# For PDM:
$(pdm venv activate qualia_env)