Skip to content

Installation

TQC can be installed in several ways depending on your needs and environment.

Quick Installation

The fastest way to get started with TQC:

pip install topological-quantum-compiler

This installs the latest stable release from PyPI with all required dependencies.

Development Installation

For development work or to access the latest features:

git clone https://github.com/tqc/topological-quantum-compiler.git
cd topological-quantum-compiler
poetry install

This installs TQC in development mode with all development dependencies.

If you're using Poetry for dependency management:

poetry add topological-quantum-compiler

Using Conda

TQC will be available on conda-forge soon:

# Coming soon!
conda install -c conda-forge topological-quantum-compiler

System Requirements

Minimum Requirements

  • Python: 3.10 or higher
  • Memory: 4GB RAM
  • Storage: 500MB available space
  • OS: Windows 10+, macOS 10.14+, or Linux
  • Python: 3.11 or 3.12 (latest stable)
  • Memory: 8GB+ RAM (for larger simulations)
  • GPU: Optional JAX-compatible GPU for tensor operations
  • Storage: 2GB+ for examples and documentation

Dependencies

TQC automatically installs these core dependencies:

Required Dependencies

  • numpy (≥1.24.0) - Numerical computing foundation
  • scipy (≥1.10.0) - Scientific computing algorithms
  • qiskit (≥0.43.0) - Quantum circuit interface
  • networkx (≥3.1) - Graph algorithms for optimization
  • matplotlib (≥3.7.0) - Visualization and plotting
  • jax (≥0.4.13) - High-performance tensor operations
  • sympy (≥1.12) - Symbolic mathematics
  • pydantic (≥2.0.0) - Data validation and serialization

Optional Dependencies

For enhanced functionality, consider installing:

# GPU acceleration (if you have compatible hardware)
pip install "jax[cuda]"  # For NVIDIA GPUs
pip install "jax[metal]"  # For Apple Silicon

# Visualization enhancements
pip install seaborn plotly

# Jupyter notebook support
pip install jupyter ipywidgets

# Development tools
pip install black isort mypy pytest

Verification

After installation, verify TQC works correctly:

import tqc
print(f"TQC version: {tqc.__version__}")

# Test basic functionality
from tqc import FibonacciAnyons, create_compiler
compiler = create_compiler('fibonacci')
print(f"Compiler ready with {compiler.anyon_type.name} anyons")

You should see output similar to:

TQC version: 0.1.0
Compiler ready with Fibonacci anyons

Installation Issues

Common Problems

Import Errors

If you get import errors, check your Python environment:

python -c "import sys; print(sys.path)"
pip list | grep topological

JAX Installation Issues

JAX can be tricky to install. If you have problems:

# Try CPU-only version first
pip install --upgrade "jax[cpu]"

# For specific platforms, see: https://jax.readthedocs.io/en/latest/installation.html

Poetry Lock Issues

If using Poetry and encountering lock file issues:

poetry lock --no-update
poetry install

Platform-Specific Notes

Windows

  • Use Python 3.10+ from python.org or Anaconda
  • Consider using WSL2 for better performance
  • Visual Studio Build Tools may be required for some dependencies

macOS

  • Works with both Intel and Apple Silicon Macs
  • Use Homebrew Python or Anaconda for best results
  • Xcode Command Line Tools required: xcode-select --install

Linux

  • Most distributions work out of the box
  • Install build dependencies: sudo apt install build-essential python3-dev
  • Consider using pyenv for Python version management

Docker Installation

For containerized deployment:

FROM python:3.11-slim

RUN pip install topological-quantum-compiler

WORKDIR /workspace
COPY . .

CMD ["python", "your_script.py"]

Virtual Environments

We strongly recommend using virtual environments:

With venv

python -m venv tqc-env
source tqc-env/bin/activate  # On Windows: tqc-env\Scripts\activate
pip install topological-quantum-compiler

With conda

conda create -n tqc python=3.11
conda activate tqc
pip install topological-quantum-compiler

IDE Integration

VS Code

Install the Python extension and configure your interpreter to point to your TQC environment.

Recommended extensions:

  • Python
  • Pylance
  • Jupyter
  • Python Docstring Generator

PyCharm

Configure the Python interpreter in Settings → Project → Python Interpreter to use your TQC environment.

Jupyter

TQC works great in Jupyter notebooks:

pip install jupyter
jupyter notebook

Then try the examples in the examples/ directory.

Next Steps

Once installed, check out:

Getting Help

If you encounter installation issues:

  1. Check the FAQ for common solutions
  2. Search GitHub Issues
  3. Ask on GitHub Discussions
  4. Join our community chat