GitHub - tsotchke/quantum_geometric_tensor: High performance hybrid classical-quantum computing learning framework written in C

Quantum Geometric Tensor Library (QGTL)

Version 0.777 Beta

Abstract

The Quantum Geometric Tensor Library (QGTL) is a comprehensive computational framework that unifies differential geometry, algebraic topology, and quantum information theory to address fundamental challenges in quantum computing and machine learning. By representing quantum states as points on complex projective manifolds and leveraging the intrinsic geometric structure of quantum state space, QGTL achieves provable improvements in error suppression, circuit optimization, and gradient computation that are inaccessible to conventional approaches.

This library provides the mathematical and computational infrastructure for:

• Geometric quantum error correction with quadratic error suppression
• Natural gradient optimization on quantum state manifolds
• Hardware-aware circuit compilation exploiting processor topology
• Fault-tolerant distributed training for quantum-classical hybrid systems
• Tensor network methods with hierarchical compression

QGTL supports execution on IBM Quantum (127-433 qubits), Rigetti (80+ qubits), and D-Wave (5000+ qubits) systems, with comprehensive classical simulation capabilities.

Theoretical Foundation

The Quantum Geometric Tensor

The quantum geometric tensor (QGT) is a fundamental mathematical object that encodes both the metric and topological properties of quantum state space. For a parameterized family of quantum states |ψ(θ)⟩, the QGT is defined as:

Q_μν = ⟨∂_μψ|∂_νψ⟩ - ⟨∂_μψ|ψ⟩⟨ψ|∂_νψ⟩

The real part of Q_μν yields the Fubini-Study metric tensor, which defines the natural geometry of quantum state space. The imaginary part yields the Berry curvature, which governs geometric phases and topological properties. QGTL exploits both components to achieve:

1. Optimal Parameter Updates: The Fubini-Study metric defines geodesics on quantum state space, enabling natural gradient descent that follows the intrinsic geometry rather than the arbitrary parameterization.

2. Topological Error Protection: The Berry curvature and associated Chern numbers provide topologically protected subspaces where certain classes of errors are geometrically forbidden.

3. Efficient State Representation: The manifold structure enables compression schemes that exploit the low intrinsic dimensionality of physically relevant quantum states.

Geometric Error Suppression

Classical quantum error correction treats errors as perturbations to be detected and corrected. QGTL's geometric approach instead encodes information in topological invariants that are inherently robust to local perturbations. The key insight is that the quantum state manifold M = CP^(2^n-1) possesses a rich geometric structure that can be exploited for error suppression.

For a quantum operation U(θ) parameterized by path θ(t) on the manifold:

• Classical error scaling: O(ε) where ε is the error rate
• Geometric error scaling: O(ε²) through Berry phase encoding

This quadratic improvement arises because geometric phases depend only on the enclosed solid angle, not the details of the path traversed. Small perturbations that preserve the homotopy class of the path leave the geometric phase invariant.

Hierarchical Tensor Networks

QGTL implements hierarchical tensor network structures that achieve sub-quadratic complexity for operations traditionally requiring O(n²) computation. The hierarchical matrix representation adaptively compresses tensor blocks based on their numerical rank:

H = [A₁₁  U₁₂V₁₂ᵀ]
    [U₂₁V₂₁ᵀ  A₂₂]

where diagonal blocks A_ii are recursively subdivided and off-diagonal blocks are stored in low-rank factored form. This structure enables:

• O(n log n) matrix-vector products
• O(n log² n) matrix inversion
• Controlled approximation error with adaptive rank selection

Architecture

Module Organization

quantum_geometric_tensor/
├── include/quantum_geometric/
│   ├── core/           # Tensor operations, geometric algorithms, memory management
│   ├── physics/        # Surface codes, stabilizer measurements, topological operations
│   ├── hardware/       # Backend abstraction for IBM, Rigetti, D-Wave systems
│   ├── distributed/    # MPI-based distributed training infrastructure
│   ├── ai/             # Quantum attention mechanisms, LLM integration
│   ├── learning/       # Stochastic sampling, data pipelines
│   └── algorithms/     # Grover, Shor, QAOA, amplitude amplification
├── src/
│   ├── quantum_geometric/   # C implementation (~50,000 lines)
│   ├── cuda/               # NVIDIA GPU kernels
│   └── metal/              # Apple Silicon GPU kernels
└── tests/                  # Comprehensive test suite (89 test files)

Core Components

Quantum Geometric Core: Implements the fundamental geometric operations including parallel transport, geodesic computation, curvature tensors, and natural gradient calculation. Provides the mathematical primitives upon which all other modules are built.

Hardware Abstraction Layer: Unified interface to heterogeneous quantum backends. Handles circuit transpilation to native gate sets, qubit routing on hardware topologies, and error mitigation strategies specific to each platform.

Tensor Network Engine: Efficient contraction, decomposition, and optimization of tensor networks. Supports Matrix Product States (MPS), Tree Tensor Networks (TTN), and Multi-scale Entanglement Renormalization Ansatz (MERA) structures.

Distributed Training Manager: MPI-based infrastructure for fault-tolerant distributed computation. Implements gradient synchronization, checkpoint management, and automatic failure recovery.

Development Status

Completed Components

• Core geometric algorithms and tensor operations
• Surface code error correction (standard, rotated, heavy-hex variants)
• GPU acceleration via CUDA and Metal
• Distributed training framework with fault tolerance
• Hierarchical matrix operations
• Stabilizer measurement and syndrome extraction

In Development

• Hardware backend integration (IBM Qiskit, Rigetti PyQuil, D-Wave Ocean)
• Quantum phase estimation circuits
• Advanced gradient computation for variational algorithms

System Requirements

Supported Platforms: macOS (12.0+), Linux (kernel 4.19+)

Compilers: GCC 9+, Clang 11+

Dependencies: CMake 3.16+, MPI implementation (OpenMPI or MPICH), BLAS/LAPACK

Optional: CUDA 11+ (NVIDIA GPUs), Metal (Apple Silicon)

Installation

# Install system dependencies (Ubuntu/Debian)
sudo apt install cmake libopenmpi-dev libblas-dev liblapack-dev

# Clone repository
git clone https://github.com/tsotchke/quantum_geometric_tensor.git
cd quantum_geometric_tensor

# Configure and build
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

# Run tests
ctest --output-on-failure

For macOS with Apple Silicon:

brew install cmake open-mpi
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DQGT_ENABLE_METAL=ON
make -j$(sysctl -n hw.ncpu)

Usage

Basic Quantum Circuit Execution

#include <quantum_geometric/core/quantum_geometric_core.h>

int main() {
    // Initialize quantum system with geometric optimization
    quantum_system_t* system = quantum_init_system(&(quantum_config_t){
        .backend = BACKEND_SIMULATOR,
        .optimization = {
            .geometric = true,
            .error_mitigation = true
        }
    });

    // Construct quantum circuit
    quantum_circuit_t* circuit = quantum_circuit_create(2);
    quantum_circuit_h(circuit, 0);      // Hadamard on qubit 0
    quantum_circuit_cx(circuit, 0, 1);  // CNOT: control=0, target=1

    // Execute with geometric error protection
    execution_result_t result;
    quantum_execute_circuit(system, circuit, &result);

    printf("State fidelity: %.6f\n", result.fidelity);
    printf("Circuit depth: %zu\n", result.compiled_depth);

    quantum_circuit_destroy(circuit);
    quantum_system_destroy(system);
    return 0;
}

Geometric Error Protection

#include <quantum_geometric/physics/quantum_topological_operations.h>

// Configure topological protection using surface code
protection_config_t config = {
    .code_type = SURFACE_CODE_ROTATED,
    .code_distance = 5,
    .error_model = ERROR_MODEL_DEPOLARIZING,
    .physical_error_rate = 0.001
};

// Apply protection to quantum state
quantum_state_t* protected_state = quantum_geometric_protect(state, &config);

// Perform computation in protected subspace
quantum_apply_logical_gate(protected_state, GATE_LOGICAL_HADAMARD, 0);

// Decode and extract result
quantum_decode_state(protected_state, &result);

Distributed Training

#include <quantum_geometric/distributed/distributed_training_manager.h>

distributed_config_t config = {
    .world_size = mpi_size,
    .local_rank = mpi_rank,
    .batch_size = 256,
    .learning_rate = 0.001f,
    .checkpoint_interval = 100,
    .checkpoint_dir = "./checkpoints"
};

distributed_manager_t* manager = distributed_manager_create(&config);
distributed_manager_init_environment(manager);

for (size_t epoch = 0; epoch < num_epochs; epoch++) {
    training_metrics_t metrics;
    int status = distributed_manager_train_epoch(manager, model, data, &metrics);

    if (status != 0) {
        distributed_manager_handle_failure(manager, metrics.failed_rank);
        epoch--;  // Retry failed epoch
        continue;
    }

    if (mpi_rank == 0) {
        printf("Epoch %zu: loss=%.4f\n", epoch, metrics.loss);
    }
}

Performance Characteristics

Error Suppression

Computational Efficiency

Hardware Targets

Documentation

• Installation Guide - Detailed setup instructions
• Quick Start - Introduction to basic usage
• Theory Guide - Mathematical foundations
• API Reference - Complete API documentation
• Hardware Integration - Backend configuration
• Error Correction - Error protection methods
• Performance Tuning - Optimization strategies

Generate API documentation:

Contributing

Contributions are welcome in the following areas:

• Hardware backend optimization and testing
• Novel quantum algorithms and applications
• Performance improvements and benchmarking
• Documentation and examples

Please consult CONTRIBUTING.md for guidelines.

Roadmap

v0.777 Beta (Current): Core algorithms complete, GPU acceleration available, error correction implemented, hardware backends in beta testing.

v0.9 (Q2 2026): Full hardware integration, comprehensive benchmarking, expanded test coverage.

v1.0 (Q3 2026): Production release with complete documentation, validated performance claims, and stable API.

Citation

If you use QGTL in your research, please cite:

@software{QGTL2026,
  author       = {tsotchke},
  title        = {Quantum Geometric Tensor Library: a framework for high-peformance geometric quantum computing and hybrid quantum-classical artificial intelligence},
  version      = {0.777},
  year         = {2026},
  url          = {https://github.com/tsotchke/quantum_geometric_tensor},
  note         = {A framework for advanced geometric quantum computing and machine learning}
}

License

Released under the MIT License.

References

1. Provost, J.P. and Vallee, G. (1980). "Riemannian structure on manifolds of quantum states." Communications in Mathematical Physics, 76(3), 289-301.

2. Berry, M.V. (1984). "Quantal phase factors accompanying adiabatic changes." Proceedings of the Royal Society A, 392(1802), 45-57.

3. Kitaev, A. (2003). "Fault-tolerant quantum computation by anyons." Annals of Physics, 303(1), 2-30.

4. Amari, S. (2016). Information Geometry and Its Applications. Springer.

5. Nielsen, M.A. and Chuang, I.L. (2010). Quantum Computation and Quantum Information. Cambridge University Press.