Frequently Asked Questions¶

General Questions¶

What is topological quantum computing?¶

Topological quantum computing is a revolutionary approach to quantum computation that encodes information in the topological properties of anyonic quasiparticles rather than fragile qubits. These properties are inherently protected from local environmental disturbances, making computations naturally fault-tolerant.

How is TQC different from other quantum compilers?¶

Traditional quantum compilers (like Qiskit's transpiler) translate between different gate-based representations. TQC is unique because it:

Compiles to braiding operations instead of gates
Provides inherent fault tolerance through topological protection
Works with anyonic degrees of freedom rather than qubits
Offers natural error suppression without requiring active error correction

What are anyons?¶

Anyons are exotic quasiparticles that exist in two-dimensional systems. Unlike fermions or bosons, anyons have non-trivial braiding statistics - when you exchange two anyons, the quantum state picks up a complex phase or undergoes a unitary transformation. This braiding behavior is what enables topological quantum computation.

Which anyon types does TQC support?¶

Currently, TQC supports:

Fibonacci anyons - Universal for quantum computation, simplest non-abelian anyons
Ising anyons - Related to the 2D Ising model, useful for certain algorithms
SU(2)_k anyons - Planned for future releases

More anyon types can be added by implementing the AnyonType interface.

Installation and Setup¶

I'm getting import errors after installation. What's wrong?¶

This usually indicates a problem with your Python environment. Try:

Check your Python version: TQC requires Python 3.10 or higher

python --version

Verify TQC is installed:

pip list | grep topological

Try reinstalling:

pip uninstall topological-quantum-compiler
pip install topological-quantum-compiler

Use a virtual environment:

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

JAX installation is failing. What should I do?¶

JAX can be tricky to install. Try these solutions:

Install CPU-only version first:

pip install --upgrade "jax[cpu]"

For NVIDIA GPUs:

pip install --upgrade "jax[cuda12_pip]" -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html

For Apple Silicon:

pip install --upgrade "jax[metal]"

See JAX installation guide for platform-specific instructions.

Can I use TQC without JAX?¶

JAX is currently required for tensor operations in the simulation engine. However, we're working on making it optional for users who only need compilation without simulation.

Usage Questions¶

What size circuits can TQC handle?¶

TQC performance depends on several factors:

Small circuits (2-4 qubits): Very fast, real-time compilation and simulation
Medium circuits (5-8 qubits): Good performance, may take several seconds
Large circuits (9+ qubits): Performance depends on circuit structure and available memory

The bottleneck is usually simulation rather than compilation. Compilation scales polynomially, while simulation scales exponentially with the number of anyons.

How do I choose between Fibonacci and Ising anyons?¶

Fibonacci anyons:

✅ Universal for quantum computation
✅ Simpler mathematical structure
✅ Well-studied in literature
❌ May require more braids for some gates

Ising anyons:

✅ Often more efficient for certain algorithms
✅ Natural for fermion-based problems
❌ Not universal alone (needs additional operations)
❌ More complex mathematical structure

Recommendation: Start with Fibonacci anyons unless you have specific requirements.

Why are my braid sequences so long?¶

Braid sequences can be longer than the original gate sequences because:

Approximation overhead: Complex gates require multiple braids to approximate
Non-locality: Moving anyons requires additional braiding operations
Limited gate set: Not all gates map directly to simple braids

Solutions:

Increase optimization level: optimization_level=3
Use higher target fidelity: target_fidelity=0.999
Try different anyon types
Preprocess circuits to use TQC-friendly gates

How accurate are the compiled braids?¶

Accuracy depends on several factors:

Target fidelity setting: Higher values give more accurate but longer braids
Optimization level: Higher levels find better approximations
Circuit complexity: Simple circuits compile more accurately
Anyon type: Different anyons have different approximation capabilities

Typical fidelities range from 0.95 to 0.999+ depending on settings.

Technical Questions¶

How does TQC simulate anyonic systems classically?¶

TQC uses several techniques for efficient classical simulation:

Fusion tree basis: Represents anyonic states in the fusion tree basis
Sparse linear algebra: Exploits sparsity in small fusion spaces
Tensor networks: For larger systems, uses tensor network methods
JAX acceleration: Leverages JAX for efficient tensor operations

The simulation is approximate but captures the essential physics of anyonic braiding.

What's the relationship between braids and quantum gates?¶

The relationship is complex:

Single-qubit gates → Multiple anyonic braids (approximation required)
Two-qubit gates → Braiding between anyon pairs
Multi-qubit gates → Complex braiding patterns

The compilation process uses techniques like the Solovay-Kitaev algorithm to find efficient braid approximations.

Can I add my own anyon types?¶

Yes! TQC is designed to be extensible. To add a new anyon type:

Inherit from AnyonType:

class MyAnyons(AnyonType):
    def __init__(self):
        super().__init__("MyAnyons", quantum_dimension=2.0)

Implement required methods:
get_labels() - Anyon species
fusion_rules() - How anyons fuse
f_matrix() - Pentagon equation matrices
r_matrix() - Braiding phases
Add comprehensive tests for mathematical consistency
Update factory functions to include your anyon type

See the Contributing Guide for detailed instructions.

How do I optimize compilation performance?¶

Several strategies can improve performance:

For Compilation:

Use optimization_level=0 for fastest compilation
Reduce target_fidelity for shorter braids
Preprocess circuits to use native TQC gates

For Simulation:

Reduce number of shots: shots=100
Use smaller circuits when possible
Consider statevector simulation instead of sampling

For Large Systems:

Use tensor network simulation (max_bond_dimension)
Enable JAX GPU acceleration if available
Process circuits in smaller chunks

Troubleshooting¶

My simulation is taking forever. What's wrong?¶

Long simulation times usually indicate:

Too many anyons: Simulation time grows exponentially
Complex braid sequences: Long braids take more time
High shot count: Reduce to 100-1000 for testing

Solutions:

Start with smaller circuits
Use simulate_statevector() instead of simulate() for testing
Check if your circuit compiles to reasonable braid lengths

I'm getting "Invalid anyon label" errors¶

This error occurs when:

Typos in anyon labels: Check spelling ("τ" not "t")
Mixing anyon types: Don't mix Fibonacci and Ising labels
Incorrect initialization: Make sure metadata matches anyon type

Fix: Use the correct labels from anyon_type.get_labels().

The braid visualization isn't working¶

Visualization issues are often due to:

Missing matplotlib: pip install matplotlib
No display available: Save to file instead of showing
Large braids: Very long braids may not render well

Solutions:

# Save to file instead of displaying
svg = braid.visualize(filename="my_braid.svg")

# For large braids, try simplifying first
simplified = braid.simplify()
svg = simplified.visualize()

Can TQC run on quantum hardware?¶

TQC currently provides classical simulation of topological quantum systems. Real topological quantum hardware is still in early experimental stages.

However, TQC's output (braid sequences) could theoretically be executed on future topological quantum computers when they become available.

Performance and Scaling¶

How does TQC scale with circuit size?¶

Compilation scaling (polynomial):

Time: O(n²) to O(n³) depending on optimization level
Memory: O(n) for circuit representation

Simulation scaling (exponential):

Time: O(2^n) for exact simulation
Memory: O(2^n) for state storage

Practical limits:

Compilation: Can handle 20+ qubit circuits
Simulation: Limited to ~10 qubits for exact simulation

Can I parallelize TQC computations?¶

Currently, TQC runs on a single thread, but parallelization opportunities exist:

JAX vectorization: Some tensor operations are automatically parallelized
Multiple circuits: Compile different circuits in parallel processes
Monte Carlo sampling: Parallelize measurement sampling

Future versions will include better parallelization support.

Getting Help¶

Where can I get more help?¶

If your question isn't answered here:

Search existing issues: GitHub Issues
Ask the community: GitHub Discussions
Check examples: GitHub Examples
Read the docs: Complete API Reference

How can I contribute to TQC?¶

We welcome all types of contributions:

Bug reports: Help us fix issues
Feature requests: Suggest improvements
Code contributions: Add new features or anyon types
Documentation: Improve guides and examples
Testing: Help us find edge cases

See our Contributing Guide for details on how to get involved.

Is TQC production-ready?¶

TQC v0.1.0 is an alpha release suitable for:

✅ Research and education
✅ Prototyping and experimentation
✅ Algorithm development
✅ Learning topological quantum computing

❌ Not yet recommended for:

Mission-critical applications
Large-scale production use
Real-time systems

We're working toward production readiness in future releases.