Skip to content

Quickstart

Get up and running with TQC in just a few minutes! This guide will walk you through your first topological quantum compilation.

Your First Compilation

Let's start with the classic quantum computing example - creating a Bell state:

from tqc import TopologicalCompiler, FibonacciAnyons
from qiskit import QuantumCircuit

# Step 1: Create a quantum circuit
qc = QuantumCircuit(2, 2)
qc.h(0)        # Hadamard on qubit 0
qc.cx(0, 1)    # CNOT from qubit 0 to 1
qc.measure_all()

print(f"Original circuit: {qc.num_qubits} qubits, {len(qc.data)} gates")

# Step 2: Create a topological compiler
compiler = TopologicalCompiler(anyon_type=FibonacciAnyons())

# Step 3: Compile to braids
result = compiler.compile(qc)

# Step 4: Examine the results
print(f"Compiled to: {len(result.braid_program)} braid operations")
print(f"Braid sequence: {result.braid_program}")
print(f"Estimated fidelity: {result.fidelity_estimate:.4f}")

Output:

Original circuit: 2 qubits, 3 gates
Compiled to: 7 braid operations  
Braid sequence: σ_0 σ_0^(-1) σ_0 σ_0 σ_1^(-1) σ_0 σ_1
Estimated fidelity: 0.9847

Congratulations! You've just compiled your first quantum circuit to topological braids.

Understanding the Output

Let's break down what happened:

  • Original circuit: A 2-qubit Bell state circuit with Hadamard + CNOT
  • Braid operations: 7 braiding operations between anyons
  • Braid sequence: The specific sequence of generators σᵢ and σᵢ⁻¹
  • Fidelity: How accurately the braids approximate the original circuit

Simulating the Braided Computation

Now let's simulate the braided quantum computation:

# Simulate the compiled braids
sim_result = compiler.simulator.simulate(result.braid_program, shots=1000)

print("Simulation results:")
for outcome, count in sim_result.counts.items():
    probability = count / sim_result.total_shots
    print(f"  |{outcome}⟩: {count:3d} shots ({probability:.1%})")

print(f"Total simulation time: {sim_result.simulation_time:.3f} seconds")

Output:

Simulation results:
  |('I', 'I')⟩: 523 shots (52.3%)
  |('τ', 'τ')⟩: 477 shots (47.7%)
Total simulation time: 0.142 seconds

The results show the Bell state entanglement encoded in anyonic degrees of freedom!

Visualizing the Braids

TQC can generate beautiful visualizations of your braided computations:

# Generate a braid diagram
svg_content = result.braid_program.visualize(show_labels=True)

# Save to file
with open("bell_state_braids.svg", "w") as f:
    f.write(svg_content)

print("Braid diagram saved to bell_state_braids.svg")

This creates an SVG diagram showing the braiding pattern with over/under crossings clearly marked.

Trying Different Anyon Types

TQC supports multiple anyon types. Let's compare Fibonacci and Ising anyons:

from tqc import IsingAnyons

# Compile with Ising anyons
ising_compiler = TopologicalCompiler(anyon_type=IsingAnyons())
ising_result = ising_compiler.compile(qc)

print("Comparison:")
print(f"Fibonacci anyons: {len(result.braid_program)} braids, "
      f"fidelity {result.fidelity_estimate:.4f}")
print(f"Ising anyons:     {len(ising_result.braid_program)} braids, "
      f"fidelity {ising_result.fidelity_estimate:.4f}")

Output:

Comparison:
Fibonacci anyons: 7 braids, fidelity 0.9847
Ising anyons:     9 braids, fidelity 0.9823

Different anyon types can lead to different compilation strategies and trade-offs.

Optimization Levels

TQC offers different optimization levels for braid sequences:

# Try different optimization levels
for level in [0, 1, 2, 3]:
    opt_compiler = TopologicalCompiler(
        anyon_type=FibonacciAnyons(),
        optimization_level=level
    )
    opt_result = opt_compiler.compile(qc)

    print(f"Level {level}: {len(opt_result.braid_program):2d} braids, "
          f"fidelity {opt_result.fidelity_estimate:.4f}")

Output:

Level 0: 12 braids, fidelity 0.9723
Level 1:  7 braids, fidelity 0.9847  
Level 2:  5 braids, fidelity 0.9891
Level 3:  4 braids, fidelity 0.9923

Higher optimization levels typically produce shorter, higher-fidelity braid sequences.

Command Line Interface

TQC also provides a command-line interface for quick compilations:

# Save your circuit as a QASM file
echo 'OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0],q[1];
measure q -> c;' > bell.qasm

# Compile with TQC CLI
tqc-cli bell.qasm --anyon-type fibonacci --optimization-level 2

Interactive Mode

For exploration and experimentation, try interactive mode:

tqc-cli --interactive

This opens an interactive session where you can:

  • Build braid sequences step by step
  • Test different anyon types
  • Optimize and simulate braids
  • Visualize results

Working with Larger Circuits

TQC can handle more complex quantum algorithms:

from qiskit.algorithms import VQE
from qiskit.circuit.library import TwoLocal

# Create a more complex circuit (VQE ansatz)
ansatz = TwoLocal(4, 'ry', 'cz', reps=2)
params = [0.1] * ansatz.num_parameters
bound_circuit = ansatz.bind_parameters(params)

# Add measurements
bound_circuit.measure_all()

# Compile to braids
large_result = compiler.compile(bound_circuit)

print(f"VQE circuit: {bound_circuit.num_qubits} qubits, "
      f"{len(bound_circuit.data)} gates")
print(f"Compiled to: {len(large_result.braid_program)} braids")
print(f"Fidelity: {large_result.fidelity_estimate:.4f}")

Error Handling

TQC provides clear error messages to help you debug:

from qiskit import QuantumCircuit

# This will raise a clear error
try:
    empty_circuit = QuantumCircuit(0)  # No qubits!
    compiler.compile(empty_circuit)
except ValueError as e:
    print(f"Error: {e}")
    # Output: Error: Circuit must have at least one qubit

What's Next?

Now that you've completed the quickstart, you can:

  1. Learn the Fundamentals - Deep dive into compilation principles
  2. Explore Advanced Features - Custom anyon types, optimization strategies
  3. Check the API Reference - Complete documentation of all classes and methods
  4. Run the Examples - Real-world quantum algorithms compiled to braids

Key Concepts Recap

  • Topological Compilation: Converting quantum gates to anyonic braiding operations
  • Anyon Types: Different mathematical structures (Fibonacci, Ising, etc.) with unique properties
  • Braid Words: Sequences of braiding operations that implement quantum computations
  • Optimization: Reducing braid length while maintaining fidelity
  • Simulation: Classical simulation of anyonic quantum states and dynamics

Getting Help

If you run into issues:

Welcome to the world of topological quantum computing! 🎉