Skip to content

Getting Started

Jump to bottom
Mohammadreza Khellat edited this page Dec 16, 2025 · 1 revision

Getting Started with openqcp-lab

Welcome to openqcp-lab! This guide will help you set up your environment and get started with your first quantum computing tutorial.

Table of Contents

  1. Prerequisites
  2. Environment Setup
  3. Framework Selection
  4. Verification
  5. Choosing Your First Tutorial
  6. Common Issues
  7. Next Steps

Prerequisites

Mathematical Background

Before starting, you should be familiar with:

  • Linear Algebra: Vectors, matrices, eigenvalues/eigenvectors, inner products
  • Complex Numbers: Basic operations, complex exponentials
  • Probability Theory: Basic probability distributions, expectation values
  • Calculus: Derivatives (for optimization tutorials)

Recommended Resources:

Programming Background

  • Python: Basic syntax, data structures, functions, classes
  • Jupyter Notebooks: How to run cells, view outputs
  • NumPy: Array operations (helpful but not strictly required)

Recommended Resources:

Quantum Computing Background

For Beginners:

  • Basic understanding of qubits, superposition, and measurement
  • Familiarity with quantum gates (Pauli gates, Hadamard, CNOT)

For Intermediate/Advanced:

  • Quantum circuits and algorithms
  • Variational methods
  • Hamiltonian simulation

Recommended Resources:

Environment Setup

Step 1: Clone the Repository

git clone https://codeberg.org/mkhellat/openqcp-lab.git
cd openqcp-lab

Or if you prefer GitHub:

git clone https://github.com/mkhellat/openqcp-lab.git
cd openqcp-lab

Step 2: Set Up Python Environment

We recommend using Python 3.9 or later. Check your Python version:

python3 --version

Option A: Using the Setup Script (Recommended)

./setup_env.sh

This script will:

  • Create a virtual environment in venv/
  • Install all required dependencies
  • Print activation instructions

Option B: Using Makefile

If you have make installed:

make env

Option C: Manual Setup

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# On Linux/macOS:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

# Upgrade pip
pip install --upgrade pip

# Install dependencies
pip install -r requirements.txt

Step 3: Activate the Environment

Linux/macOS:

source venv/bin/activate

Windows:

venv\Scripts\activate

You should see (venv) in your terminal prompt.

Step 4: Start Jupyter

jupyter notebook

Or if you prefer JupyterLab:

jupyter lab

This will open a web browser with the Jupyter interface. Navigate to any tutorial directory to open the notebooks.

Framework Selection

This project uses multiple quantum computing frameworks. Each tutorial specifies which framework it uses. Here's a quick guide:

Classiq

Used in: Tutorials 00, 02, 03, 05

When to use:

  • High-level quantum algorithm design
  • Automatic circuit synthesis and optimization
  • Research and educational purposes

Installation: Included in requirements.txt (installed automatically)

Authentication: Some Classiq features may require API authentication. See the Classiq documentation for details.

PennyLane

Used in: Tutorial 01

When to use:

  • Variational quantum algorithms
  • Quantum machine learning
  • Gradient-based optimization

Installation: Included in requirements.txt (installed automatically)

Qiskit

Used in: Tutorial 04

When to use:

  • IBM Quantum hardware access
  • Variational Quantum Eigensolvers (VQE)
  • QUBO problem solving

Installation: Optional dependency. The notebook will install it automatically if needed, or you can install manually:

pip install qiskit qiskit-optimization

Framework Comparison

Framework Best For Hardware Access Learning Curve
Classiq Algorithm design, synthesis Limited Moderate
PennyLane Optimization, ML Multiple backends Moderate
Qiskit IBM Quantum, VQE IBM Quantum Moderate

For detailed comparison, see the Framework Guide.

Verification

After setup, verify your installation:

1. Check Python Packages

python3 -c "import numpy, scipy, matplotlib, classiq, pennylane; print('Core packages OK')"

2. Test Jupyter

Open a new notebook and run:

import numpy as np
import matplotlib.pyplot as plt
print("NumPy version:", np.__version__)
print("Setup verified!")

3. Test Quantum Framework (Optional)

Classiq:

from classiq import *
print("Classiq imported successfully")

PennyLane:

import pennylane as qml
print("PennyLane version:", qml.__version__)

Qiskit (if installed):

import qiskit
print("Qiskit version:", qiskit.__version__)

Choosing Your First Tutorial

🟢 I'm New to Quantum Computing

Start with: Tutorial 00 - Quantum Fourier Transform

Why: Builds fundamental understanding of quantum algorithms and mathematical foundations.

Time: ~2 hours

Next: Tutorial 01 - Minimize Expectation Value

🟡 I Have Basic Quantum Knowledge

Start with: Tutorial 02 - Quantum Walk

Why: Introduces graph-based quantum algorithms with practical implementations.

Time: ~2-3 hours

Next: Tutorial 03 - Non-Unitary Computing

🔴 I'm Experienced

Start with: Tutorial 04 - Quantum Variational Algorithms

Why: Covers advanced optimization techniques (VQE, QUBO).

Time: ~3-4 hours

Next: Tutorial 05 - Coupled Harmonic Oscillators

📚 I'm a Researcher

Start with: Tutorial 05 - Coupled Harmonic Oscillators

Why: Cutting-edge research application with exponential speedup.

Time: ~4-5 hours

See Learning Paths for detailed guidance and prerequisite chains.

Common Issues

Issue: command not found: python3

Solution:

  • On Windows, try python instead of python3
  • Ensure Python 3.9+ is installed
  • Add Python to your system PATH

Issue: Permission denied when running setup_env.sh

Solution:

chmod +x setup_env.sh
./setup_env.sh

Issue: ModuleNotFoundError for specific packages

Solution:

  1. Ensure virtual environment is activated
  2. Reinstall dependencies: pip install -r requirements.txt
  3. For Qiskit (optional): pip install qiskit qiskit-optimization

Issue: Jupyter doesn't open in browser

Solution:

  1. Check the terminal for a URL (usually http://localhost:8888)
  2. Copy the URL and paste it in your browser
  3. Or use: jupyter notebook --no-browser and manually open the URL

Issue: LaTeX errors in plots (Tutorial 05)

Solution:

  • Install LaTeX distribution (TeX Live, MiKTeX, or MacTeX)
  • Install cm-super package for your LaTeX distribution
  • Or disable LaTeX in the notebook: plt.rcParams['text.usetex'] = False

Issue: Classiq authentication errors

Solution:

  • Some Classiq features require API authentication
  • See Classiq documentation for authentication setup
  • Most tutorials work without authentication for basic usage

Issue: Notebooks run slowly

Solution:

  • Reduce the number of shots in quantum simulations
  • Use smaller problem sizes for initial testing
  • Check if you're using a quantum simulator (expected to be slower than classical)

For more troubleshooting, see the FAQ.

Next Steps

  1. ✅ Environment set up - You're here!
  2. 📖 Choose a tutorial - See Tutorial Catalog for details
  3. 🚀 Start learning - Open your first notebook
  4. 📚 Explore resources - Check Academic Resources for papers
  5. 🔄 Reproduce results - See Reproducing Results guide

Recommended Reading

Getting Help

  • Documentation Issues: Open an issue on Codeberg
  • Code Issues: Check the main repository's CONTRIBUTING.md
  • Questions: See FAQ for common questions

Ready to start? Head to the Tutorial Catalog to choose your first tutorial!

Clone this wiki locally