{"id":34931266,"url":"https://github.com/yucelz/q-store","last_synced_at":"2026-01-26T21:23:12.376Z","repository":{"id":328178581,"uuid":"1114516636","full_name":"yucelz/q-store","owner":"yucelz","description":"A database architecture that leverages quantum mechanical properties—superposition, entanglement, decoherence, and tunneling—as **core features** for exponential performance advantages in vector similarity search, relationship management, and pattern discovery.","archived":false,"fork":false,"pushed_at":"2026-01-15T00:04:25.000Z","size":11036,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-15T07:08:48.698Z","etag":null,"topics":["database","q-store","quatum"],"latest_commit_sha":null,"homepage":"http://www.q-store.tech","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yucelz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-11T13:39:14.000Z","updated_at":"2025-12-29T22:54:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yucelz/q-store","commit_stats":null,"previous_names":["yucelz/q-store"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/yucelz/q-store","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yucelz%2Fq-store","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yucelz%2Fq-store/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yucelz%2Fq-store/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yucelz%2Fq-store/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yucelz","download_url":"https://codeload.github.com/yucelz/q-store/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yucelz%2Fq-store/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28788369,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T21:13:08.818Z","status":"ssl_error","status_checked_at":"2026-01-26T21:13:08.448Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","q-store","quatum"],"created_at":"2025-12-26T16:19:38.319Z","updated_at":"2026-01-26T21:23:12.356Z","avatar_url":"https://github.com/yucelz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://www.q-store.tech/_astro/logo.CnqA1_E2.svg\" alt=\"Q-Store Logo\" width=\"200\"/\u003e\n\u003c/div\u003e\n\n# Q-Store: Quantum-Native Database v4.1.1\n\nA production-ready quantum-first ML platform with **async execution**, comprehensive verification/profiling/visualization tools, and hardware-agnostic support for quantum computing. Leverages quantum mechanical properties—superposition, entanglement, and tunneling—for quantum-accelerated ML training with 10-20x throughput improvements.\n\n## Community\n\n[![Slack](https://img.shields.io/badge/Slack-Join%20Group-4A154B?logo=slack\u0026logoColor=white)](https://q-storeworkspace.slack.com/archives/C0A4X3S055Y)\n[![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?logo=discord\u0026logoColor=white)](https://discord.gg/wYmXxEvm)\n\n\u003ca href=\"http://www.q-store.tech\" target=\"_blank\"\u003e\n  \u003cstrong\u003eQ-STORE website Link \u003c/strong\u003e\n\u003c/a\u003e\n\n\u003c\u003c\u003c\u003c\u003c\u003c\u003c HEAD\n## 🆕 What's New in v4.1.0\n=======\n### 🚀 Example Projects\n[![Docs](https://img.shields.io/badge/Docs-Other%20Project-blue)](https://github.com/yucelz/q-store-examples)\n\n\n## 🆕 What's New in v3.4\n\u003e\u003e\u003e\u003e\u003e\u003e\u003e main\n\n### 🚀 Async-First Quantum Execution (10-20x Throughput)\n- **AsyncQuantumExecutor**: Non-blocking circuit submission with parallel execution\n- **Zero-Blocking Storage**: Async Zarr/Parquet writers with background tasks\n- **Result Caching**: LRU cache for instant retrieval of repeated circuits\n- **Connection Pooling**: Multi-connection backend clients for better utilization\n- **Background Polling**: Async workers poll quantum backends without blocking training\n- **PyTorch Integration**: Fixed QuantumLayer with proper async support\n\n### 📊 Verification, Profiling \u0026 Visualization (v4.0 Foundation)\n- **Circuit Verification**: Equivalence checking, property verification, formal analysis\n- **Performance Profiling**: Gate-level profiling, optimization benchmarks\n- **State Visualization**: Circuit diagrams (ASCII/LaTeX), Bloch sphere, state vectors\n- **144 Comprehensive Tests**: Full coverage for all verification/profiling/visualization modules\n\n### v4.1.0 Performance Achievements\n\n**IMPORTANT**: Improvements shown are **v4.1 vs v4.0 quantum**, not quantum vs classical GPU!\n\n| Metric | v4.0 Quantum | v4.1 Quantum | Improvement |\n|--------|--------------|--------------|-------------|\n| Circuit throughput | Sequential | 10-20x parallel | **10-20x faster** |\n| Storage operations | Blocking | Async (0ms) | **∞ faster** |\n| Result caching | None | LRU cache | **Instant repeats** |\n| PyTorch integration | Broken | Fixed + async | **Production-ready** |\n| Module count | 22 | 29 | **7 new modules** |\n| Total Python files | 118 | 145 | **27 new files** |\n\n### ⚡ Reality Check: Quantum vs Classical GPU\n\n**Current NISQ quantum hardware is typically 0.7-1.2x classical GPU speed** (often slower)\n\n**Why?** Circuit overhead, API latency, limited parallelization, measurement shots\n\n**Quantum's Value:** Better exploration of non-convex loss landscapes, not raw speed\n\n**When Quantum Helps:**\n- ✅ Complex optimization landscapes\n- ✅ Small datasets (\u003c10K samples)\n- ✅ Problems where classical gets stuck in local minima\n- ✅ Research and algorithm development\n\n**When Classical GPU Wins:**\n- ✅ Large datasets (\u003e10K samples)\n- ✅ Production workloads\n- ✅ Cost-sensitive applications\n- ✅ Most practical ML tasks today\n\n### Quantum ML Training (v3.2+, Enhanced in v4.1)\n- **Async Quantum Execution**: Non-blocking circuit submission with 10-20x throughput\n- **Hardware-Agnostic Architecture**: Works with Cirq, Qiskit, IonQ, and simulators\n- **Quantum Feature Extractor**: Replace Dense layers with quantum circuits\n- **Quantum Neural Network Layers**: Variational quantum circuits with async execution\n- **Quantum Gradient Computation**: Parameter shift rule and SPSA estimation\n- **Hybrid Classical-Quantum Pipelines**: Seamless PyTorch/TensorFlow integration\n- **Quantum Data Encoding**: Amplitude and angle encoding strategies\n- **Production Storage**: Async Zarr checkpoints and Parquet metrics\n\n### Advanced ML Features\n- **Quantum Transfer Learning**: Fine-tune pre-trained quantum models\n- **Quantum Data Augmentation**: Superposition-based data expansion\n- **Quantum Regularization**: Entanglement-based model optimization\n- **Quantum Adversarial Training**: Robust model training with quantum gradients\n- **Hyperparameter Optimization**: Quantum annealing for HPO\n\n### Training Infrastructure (v4.1 Enhanced)\n- **Async Execution Pipeline**: Non-blocking quantum circuit execution\n- **Background Workers**: Async polling without blocking training loop\n- **Result Caching**: LRU cache for repeated circuit measurements\n- **Connection Pooling**: Multi-connection quantum backend clients\n- **Distributed Quantum Training**: Multi-backend orchestration (v4.0)\n- **Training Data Management**: Store datasets with async writers\n- **Model Checkpointing**: Zarr-based async checkpoint saves\n- **Metrics Tracking**: Parquet-based async metrics logging\n- **Framework Integration**: PyTorch, TensorFlow, and JAX support\n\n## Overview\n\nQ-Store provides a hardware-agnostic hybrid classical-quantum database architecture that:\n- **Stores data in quantum superposition** for context-aware retrieval\n- **Uses entanglement** for automatic relationship synchronization\n- **Applies decoherence** as adaptive time-to-live (TTL)\n- **Leverages quantum tunneling** for global pattern discovery\n- **Trains quantum ML models** with variational quantum circuits (8-12x faster in v3.4)\n- **Supports multiple quantum backends** (Cirq/IonQ, Qiskit/IonQ, simulators)\n- **Integrates with classical ML frameworks** (PyTorch, TensorFlow, JAX)\n- **Scales with Pinecone** for classical vector storage\n- **Optimized IonQ execution** with batch API, native gates, and smart caching\n\n## Key Features\n\n### 🌌 Quantum Superposition\nStore vectors in superposition of multiple contexts simultaneously. Measurement collapses to the most relevant context for your query.\n\n```python\nawait db.insert(\n    id='doc_1',\n    vector=embedding,\n    contexts=[\n        ('technical_query', 0.6),\n        ('general_query', 0.3),\n        ('historical_query', 0.1)\n    ],\n    coherence_time=5000.0  # ms\n)\n```\n\n### 🔗 Quantum Entanglement\nCreate entangled groups where updates propagate automatically via quantum correlation. No cache invalidation needed.\n\n```python\ndb.create_entangled_group(\n    group_id='related_docs',\n    entity_ids=['doc_1', 'doc_2', 'doc_3'],\n    correlation_strength=0.85\n)\n```\n\n### ⏱️ Adaptive Decoherence\nPhysics-based relevance decay. Old data naturally fades without explicit TTL management.\n\n### ⏱️ Adaptive Decoherence\nPhysics-based relevance decay. Old data naturally fades without explicit TTL management.\n\n```python\nawait db.insert(\n    id='hot_data',\n    vector=embedding,\n    coherence_time=1000  # ms - stays relevant\n)\n```\n\n### 🌀 Quantum Tunneling\nEscape local optima to find globally optimal patterns that classical methods miss.\n\n```python\nresults = await db.query(\n    vector=query_embedding,\n    enable_tunneling=True,  # Find distant patterns\n    mode=QueryMode.EXPLORATORY,\n    top_k=10\n)\n```\n\n### 🧠 Quantum ML Training (v3.2+, 8x Faster in v3.4)\nTrain quantum neural networks with hardware-agnostic quantum circuits.\n\n**QuantumLayer** - Variational quantum circuit layer for neural networks\n**QuantumTrainer** - Training orchestration with quantum gradient computation\n**QuantumGradientComputer** - Parameter shift rule for gradient calculation\n**QuantumDataEncoder** - Classical-to-quantum data encoding (amplitude/angle)\n**IonQBatchClient** (v3.4) - Parallel circuit submission with connection pooling\n**SmartCircuitCache** (v3.4) - Template-based circuit caching\n**IonQNativeGateCompiler** (v3.4) - Native gate optimization\n\n```python\n# Define quantum neural network layer\nquantum_layer = QuantumLayer(\n    n_qubits=10,\n    depth=4,\n    backend=backend,\n    entanglement='linear'\n)\n\n# Train quantum model with v3.4 optimizations\ntrainer = QuantumTrainer(config, backend_manager)\nawait trainer.train(\n    model=quantum_model,\n    train_loader=data_loader,\n    epochs=100  # Now 8x faster with v3.4!\n)\n```\n\n## Installation\n\n### Quick Start (5 minutes)\n\n**New users:** See [docs/QUICKSTART.md](docs/QUICKSTART.md) for a step-by-step beginner guide.\n\n### Prerequisites\n- Python 3.11+\n- Conda package manager (recommended) or pip\n- [Pinecone API key](https://www.pinecone.io/)\n- [IonQ API key](https://cloud.ionq.com/settings/keys) (optional for quantum hardware)\n- Choose quantum SDK: Cirq or Qiskit (for hardware-agnostic support)\n\n### Setup\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/yucelz/q-store.git\ncd q-store\n```\n\n2. Create conda environment:\n```bash\nconda env create -f environment.yml\nconda activate q-store\n```\n\n3. Install the package in development mode:\n```bash\n# Install with all dependencies\npip install -e \".[dev,backends]\"\n\n# Or use the Makefile\nmake install-dev\n```\n\n4. Install required libraries:\n```bash\n# Install the new Pinecone SDK (not pinecone-client)\npip install pinecone\n\n# Verify installation\npython -c \"import pinecone; print('Pinecone installed successfully')\"\n```\n\n5. Configure your API keys in `.env` file:\n\nCreate a `.env` file in the project root:\n```bash\n# Required: Pinecone for vector storage\nPINECONE_API_KEY=your_pinecone_api_key\nPINECONE_ENVIRONMENT=us-east-1\n\n# Optional: IonQ for quantum features\nIONQ_API_KEY=your_ionq_api_key\n\n# Quantum SDK selection (cirq or qiskit)\nQUANTUM_SDK=cirq  # or 'qiskit' for hardware-agnostic support\nQUANTUM_TARGET=simulator  # or 'qpu.aria', 'qpu.forte'\n```\n\nGet your API keys:\n- **Pinecone**: Sign up at [pinecone.io](https://www.pinecone.io/) and get your API key from the dashboard\n- **IonQ** (Optional): Get your API key from [cloud.ionq.com/settings/keys](https://cloud.ionq.com/settings/keys)\n\n6. **First Test - Run the Quickstart Example:**\n```bash\n# Verify installation\npython verify_installation.py\n\n# Run the full quickstart demo\npython examples/quantum_db_quickstart.py\n```\n\nExpected output from verification:\n```\n============================================================\nQ-Store Installation Verification\n============================================================\n\nChecking imports...\n  ✓ NumPy\n  ✓ SciPy\n  ✓ Cirq\n  ✓ Pinecone\n  ✓ Q-Store\n\nChecking .env file...\n  ✓ .env file exists\n  ✓ PINECONE_API_KEY set\n  ✓ PINECONE_ENVIRONMENT set\n\nTesting basic functionality...\n  ✓ DatabaseConfig created\n  ✓ QuantumDatabase instantiated\n\n============================================================\n✓ All checks passed!\n============================================================\n```\n\nExpected output from quickstart:\n```\n============================================================\nQUANTUM DATABASE - INTERACTIVE DEMO\n============================================================\n\n=== Quantum Database Setup ===\n\nConfiguration:\n  - Pinecone Index: quantum-demo\n  - Pinecone Environment: us-east-1\n  - Dimension: 768\n  - Quantum Enabled: True\n  - Superposition: True\n  - IonQ Target: simulator\n\nInitializing database...\nINFO:q_store.quantum_database:Pinecone initialized with environment: us-east-1\nINFO:q_store.quantum_database:Creating Pinecone index: quantum-demo\nINFO:q_store.quantum_database:Pinecone index 'quantum-demo' created successfully\n✓ Database initialized successfully\n\n=== Example 1: Basic Operations ===\n...\n```\n\n**Note:** The first run will create Pinecone indexes (`quantum-demo` and `production-index`). Subsequent runs will use existing indexes.\n\n## Quick Start\n\n### Using .env File (Recommended)\n\n1. Create a `.env` file in your project root:\n```bash\nPINECONE_API_KEY=your_pinecone_api_key\nPINECONE_ENVIRONMENT=us-east-1\nIONQ_API_KEY=your_ionq_api_key  # Optional\n```\n\n2. Run the quickstart example:\n```bash\npython examples/quantum_db_quickstart.py\n```\n\nThe example automatically loads credentials from `.env` using `python-dotenv`.\n\n### Basic Usage with Async/Await\n\n```python\nimport asyncio\nimport numpy as np\nfrom dotenv import load_dotenv\nfrom q_store import QuantumDatabase, DatabaseConfig, QueryMode\n\n# Load environment variables\nload_dotenv()\n\nasync def main():\n    # Configure database (reads from .env automatically)\n    config = DatabaseConfig(\n        # Pinecone settings\n        pinecone_api_key=os.getenv('PINECONE_API_KEY'),\n        pinecone_environment=os.getenv('PINECONE_ENVIRONMENT', 'us-east-1'),\n        pinecone_index_name='my-index',\n        pinecone_dimension=768,\n        \n        # Quantum backend (hardware-agnostic)\n        quantum_sdk=os.getenv('QUANTUM_SDK', 'cirq'),  # 'cirq' or 'qiskit'\n        ionq_api_key=os.getenv('IONQ_API_KEY'),\n        ionq_target=os.getenv('QUANTUM_TARGET', 'simulator'),\n        enable_quantum=True,\n        enable_superposition=True\n    )\n    \n    # Initialize database with context manager\n    db = QuantumDatabase(config)\n    \n    async with db.connect():\n        # Insert vector with quantum superposition\n        embedding = np.random.randn(768)\n        await db.insert(\n            id='item_1',\n            vector=embedding,\n            contexts=[('context_a', 0.7), ('context_b', 0.3)],\n            metadata={'category': 'example'}\n        )\n        \n        # Query with context-aware collapse\n        results = await db.query(\n            vector=embedding,\n            context='context_a',\n            mode=QueryMode.BALANCED,\n            top_k=5\n        )\n        \n        # Display results\n        for result in results:\n            print(f\"ID: {result.id}, Score: {result.score:.4f}\")\n            print(f\"Quantum Enhanced: {result.quantum_enhanced}\")\n\n# Run\nasyncio.run(main())\n```\n\n### Quantum ML Training\n\n```python\nfrom q_store import QuantumTrainer, QuantumModel, TrainingConfig\n\n# Configure training\ntraining_config = TrainingConfig(\n    # Database config\n    **config,\n    \n    # ML training settings\n    learning_rate=0.01,\n    batch_size=32,\n    epochs=100,\n    \n    # Quantum model architecture\n    n_qubits=10,\n    circuit_depth=4,\n    entanglement='linear'\n)\n\nasync def train_quantum_model():\n    db = QuantumDatabase(training_config)\n    \n    async with db.connect():\n        # Store training data in quantum database\n        await db.store_training_data(\n            dataset_id='mnist_train',\n            data=X_train,\n            labels=y_train\n        )\n        \n        # Create quantum model\n        model = QuantumModel(\n            input_dim=784,\n            n_qubits=10,\n            output_dim=10,\n            backend=db.backend_manager.get_backend()\n        )\n        \n        # Create trainer\n        trainer = QuantumTrainer(training_config, db.backend_manager)\n        \n        # Create data loader\n        train_loader = db.create_ml_data_loader(\n            dataset_id='mnist_train',\n            batch_size=32\n        )\n        \n        # Train quantum neural network\n        await trainer.train(\n            model=model,\n            train_loader=train_loader,\n            epochs=100\n        )\n\nasyncio.run(train_quantum_model())\n```\n\n### Batch Operations\n\n```python\nasync with db.connect():\n    # Prepare batch\n    batch = [\n        {\n            'id': f'doc_{i}',\n            'vector': np.random.rand(768),\n            'contexts': [('general', 1.0)],\n            'metadata': {'index': i}\n        }\n        for i in range(100)\n    ]\n    \n    # Batch insert (efficient)\n    await db.insert_batch(batch)\n```\n\n### Monitoring and Metrics\n\n```python\n# Get performance metrics\nmetrics = db.get_metrics()\nprint(f\"Total Queries: {metrics.total_queries}\")\nprint(f\"Cache Hit Rate: {metrics.cache_hits / max(1, metrics.total_queries):.2%}\")\nprint(f\"Avg Latency: {metrics.avg_latency_ms:.2f}ms\")\nprint(f\"Active Quantum States: {metrics.active_quantum_states}\")\n\n# Get comprehensive stats\nstats = db.get_stats()\nprint(stats)\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**1. ModuleNotFoundError: No module named 'q_store'**\n```bash\n# Solution: Install the package in development mode\npip install -e .\n```\n\n**2. ImportError: Pinecone package is required**\n```bash\n# Solution: Install the new Pinecone SDK (not pinecone-client)\npip uninstall -y pinecone-client\npip install pinecone\n```\n\n**3. PINECONE_API_KEY not found**\n```bash\n# Solution: Create a .env file in the project root\ncat \u003e .env \u003c\u003c EOF\nPINECONE_API_KEY=your_actual_api_key\nPINECONE_ENVIRONMENT=us-east-1\nIONQ_API_KEY=your_ionq_key\nEOF\n```\n\n**4. Pinecone index creation fails**\n- Ensure your Pinecone account has available index quota\n- Check that the environment (e.g., `us-east-1`) is valid\n- Verify your API key has the necessary permissions\n\n**5. IonQ quantum features not working**\n- IonQ API key is optional - the system works without it\n- Quantum features will be disabled if `IONQ_API_KEY` is not set\n- Verify your IonQ API key at [cloud.ionq.com](https://cloud.ionq.com/settings/keys)\n\n**6. Package version conflicts**\n```bash\n# Solution: Recreate the conda environment\nconda deactivate\nconda env remove -n q-store\nconda env create -f environment.yml\nconda activate q-store\npip install -e .\npip install pinecone\n```\n\n### Getting Help\n\n- Check the [examples](examples/) directory for working code\n- Review the [design document](quantum_db_design_v2.md) for architecture details\n- Submit issues on [GitHub](https://github.com/yucelz/q-store/issues)\n- Contact: yucelz@gmail.com\n\n## Common Commands\n\n```bash\n# Installation and setup\nconda activate q-store              # Activate environment\npython verify_installation.py       # Verify installation\npip install -e .                    # Install package in dev mode\n\n# Running examples\npython examples/quantum_db_quickstart.py  # Run quickstart demo\npython examples/basic_example.py          # Run basic example\npython examples/financial_example.py      # Run financial example\npython examples/ml_training_example.py    # Run ML training example\npython examples/tinyllama_react_training.py  # Run TinyLlama fine-tuning\n\n# Testing\npytest tests/ -v                    # Run all tests\npytest tests/ -v -k \"test_state\"    # Run specific tests\n\n# Maintenance\nconda env update -f environment.yml # Update dependencies\nconda deactivate                    # Deactivate environment\n```\n\n## Architecture (v4.1.0)\n\n```\n┌─────────────────────────────────────────────────┐\n│           Application Layer                     │\n│  • PyTorch • TensorFlow • JAX                   │\n└────────────────┬────────────────────────────────┘\n                 │\n┌────────────────▼────────────────────────────────┐\n│    Quantum Training Engine (v4.1)               │\n│  • QuantumTrainer  • QuantumLayer (Fixed)       │\n│  • QuantumFeatureExtractor (Async)              │\n│  • QuantumGradientComputer  • QuantumOptimizer  │\n│  • QuantumDataEncoder  • Natural Gradients      │\n└────────────────┬────────────────────────────────┘\n                 │\n┌────────────────▼────────────────────────────────┐\n│       Async Execution Layer (v4.1 NEW)          │\n│  • AsyncQuantumExecutor (Non-blocking)          │\n│  • ResultCache (LRU)  • BackendClient (Pool)    │\n│  • Background Workers  • IonQAdapter            │\n└────────────────┬────────────────────────────────┘\n                 │\n┌────────────────▼────────────────────────────────┐\n│       Async Storage Layer (v4.1 NEW)            │\n│  • AsyncBuffer  • AsyncMetricsWriter (Parquet)  │\n│  • CheckpointManager (Zarr)  • AsyncLogger      │\n└────────────────┬────────────────────────────────┘\n                 │\n        ┌────────┴────────┐\n        │                 │\n┌───────▼──────┐   ┌─────▼──────────────────────┐\n│  Classical   │   │   Quantum Backends (v4.1)   │\n│   Backend    │◄──►  • IonQ Hardware            │\n│              │   │  • Cirq Simulators          │\n│  • Pinecone  │   │  • Qiskit Backends          │\n│  • Vector DB │   │  • Mock Backends            │\n│  • Zarr/     │   │  • Multi-Backend Orchestr.  │\n│    Parquet   │   │                             │\n│  • Async I/O │   │  Verification (v4.0):       │\n│              │   │  • Equivalence • Properties │\n│              │   │                             │\n│              │   │  Profiling (v4.0):          │\n│              │   │  • CircuitProfiler          │\n│              │   │  • PerformanceAnalyzer      │\n│              │   │                             │\n│              │   │  Visualization (v4.0):      │\n│              │   │  • CircuitVisualizer        │\n│              │   │  • StateVisualizer          │\n└──────────────┘   └─────────────────────────────┘\n```\n\n## Configuration\n\n### DatabaseConfig Options\n\n```python\nfrom q_store import DatabaseConfig\n\nconfig = DatabaseConfig(\n    # Pinecone configuration\n    pinecone_api_key='your_key',\n    pinecone_environment='us-east-1',\n    pinecone_index_name='my-index',\n    pinecone_dimension=768,\n    pinecone_metric='cosine',\n    \n    # Quantum backend (hardware-agnostic)\n    quantum_sdk='cirq',  # or 'qiskit'\n    ionq_api_key='your_ionq_key',\n    ionq_target='simulator',  # or 'qpu.aria', 'qpu.forte'\n    \n    # Feature flags\n    enable_quantum=True,\n    enable_superposition=True,\n    enable_entanglement=True,\n    enable_tunneling=True,\n    \n    # Performance tuning\n    max_quantum_states=1000,\n    classical_candidate_pool=1000,\n    result_cache_ttl=300,  # seconds\n    \n    # Connection pooling\n    max_connections=50,\n    connection_timeout=30,\n    \n    # Coherence settings\n    default_coherence_time=1000.0,  # ms\n    decoherence_check_interval=60,  # seconds\n    \n    # Monitoring\n    enable_metrics=True,\n    enable_tracing=True\n)\n```\n\n### TrainingConfig Options (v3.4)\n\n```python\nfrom q_store import TrainingConfig\n\ntraining_config = TrainingConfig(\n    # Inherits all DatabaseConfig options\n    **config,\n    \n    # ML Training settings\n    learning_rate=0.01,\n    batch_size=32,\n    epochs=100,\n    optimizer='adam',  # 'adam', 'sgd', 'rmsprop'\n    \n    # Quantum model architecture\n    n_qubits=10,\n    circuit_depth=4,\n    entanglement='linear',  # 'linear', 'circular', 'full'\n    \n    # Data encoding\n    encoding_method='amplitude',  # or 'angle'\n    \n    # v3.4 Performance Optimizations (NEW)\n    use_batch_api=True,          # Enable IonQ batch API (8x faster)\n    use_native_gates=True,        # Enable native gate compilation (30% faster)\n    enable_smart_caching=True,    # Enable circuit caching (10x faster)\n    connection_pool_size=5,       # HTTP connection pool size\n    adaptive_batch_sizing=True,   # Automatic batch size optimization\n    \n    # Regularization\n    quantum_regularization=True,\n    entanglement_penalty=0.01,\n    \n    # Checkpointing\n    checkpoint_interval=10,  # epochs\n    save_best_only=True,\n    \n    # Advanced features\n    enable_data_augmentation=True,\n    enable_adversarial_training=False,\n    enable_transfer_learning=False\n)\n```\n\n## API Reference v3.4\n\n### QuantumDatabase\n\n**`async def initialize()`**\nInitialize database and start background tasks.\n\n**`async def close()`**\nClose database and cleanup resources.\n\n**`async def connect()`**\nContext manager for database lifecycle.\n\n**`async def insert(id, vector, contexts=None, coherence_time=None, metadata=None)`**\nInsert vector with optional quantum superposition.\n\n**`async def insert_batch(vectors: List[Dict])`**\nBatch insert for efficiency.\n\n**`async def query(vector, context=None, mode=QueryMode.BALANCED, enable_tunneling=None, top_k=10)`**\nQuery database with quantum enhancements.\n\n**`async def store_training_data(dataset_id, data, labels, metadata=None)`**\nStore training dataset in quantum database.\n\n**`async def load_training_batch(dataset_id, batch_size, shuffle=True)`**\nLoad training batch from quantum database.\n\n**`create_ml_data_loader(dataset_id, batch_size=32, shuffle=True)`**\nCreate async data loader for training.\n\n**`get_metrics() -\u003e Metrics`**\nGet performance metrics.\n\n**`get_stats() -\u003e Dict`**\nGet comprehensive database statistics.\n\n### Quantum ML Training Classes (v3.4)\n\n**QuantumLayer**\n- `__init__(n_qubits, depth, backend, entanglement='linear')`\n- `async forward(x: np.ndarray) -\u003e np.ndarray` - Forward pass through quantum circuit\n\n**QuantumTrainer**\n- `__init__(config, backend_manager)`\n- `async train_epoch(model, data_loader, epoch)` - Train for one epoch (8x faster in v3.4)\n- `async train(model, train_loader, val_loader=None, epochs=100)` - Full training loop\n- `async validate(model, val_loader)` - Validation pass\n\n**QuantumGradientComputer**\n- `async compute_gradients(circuit, loss_function, current_params)` - Compute quantum gradients using parameter shift rule\n\n**QuantumDataEncoder**\n- `amplitude_encode(data: np.ndarray) -\u003e QuantumCircuit` - Amplitude encoding\n- `angle_encode(data: np.ndarray, n_qubits: int) -\u003e QuantumCircuit` - Angle encoding\n\n**QuantumOptimizer**\n- `__init__(learning_rate, method='adam')`\n- `step(parameters, gradients)` - Update parameters\n\n**IonQBatchClient** (NEW v3.4)\n- `__init__(api_key, connection_pool_size=5)`\n- `async submit_batch(circuits: List[Circuit])` - Submit circuits in parallel\n- `async get_results(job_ids: List[str])` - Retrieve results efficiently\n\n**SmartCircuitCache** (NEW v3.4)\n- `__init__(max_size=1000)`\n- `get_or_build(template_key, parameters)` - Get cached or build circuit\n- `get_statistics()` - Cache performance metrics\n\n**IonQNativeGateCompiler** (NEW v3.4)\n- `__init__()`\n- `compile_to_native(circuit: Circuit)` - Compile to GPi, GPi2, MS gates\n- `estimate_fidelity(circuit: Circuit)` - Estimate gate fidelity\n\n**QuantumHPOSearch**\n- `__init__(config, search_space, backend_manager)`\n- `async search(model_class, dataset_id, metric, n_trials, use_quantum_annealing=True)` - Hyperparameter search\n\n**CheckpointManager**\n- `__init__(config)`\n- `async save(model, epoch, metrics)` - Save model checkpoint\n- `async load(checkpoint_name)` - Load model checkpoint\n\n**MetricsTracker**\n- `__init__(config)`\n- `log_metrics(epoch, metrics)` - Log training metrics\n- `get_history()` - Get training history\n\n### QueryMode Enum\n\n- `PRECISE`: High precision, narrow results\n- `BALANCED`: Balanced precision and coverage  \n- `EXPLORATORY`: Broad exploration, diverse results\n\n### StateStatus Enum\n\n- `CREATED`: Newly created state\n- `ACTIVE`: Active coherent state\n- `MEASURED`: State has been measured\n- `DECOHERED`: State has lost coherence\n- `ARCHIVED`: Archived state\n\n## Quantum Backend\n\nQ-Store integrates with multiple quantum backends for hardware-agnostic ML training.\n\n**Supported SDKs:**\n- `cirq` - Google Cirq with IonQ integration\n- `qiskit` - IBM Qiskit with IonQ integration\n- Mock simulators for development and testing\n\n**Supported Targets:**\n- `simulator` - Free simulator (unlimited use)\n- `qpu.aria` - 25 qubits, #AQ 25 (production)\n- `qpu.forte` - 36 qubits, #AQ 36 (advanced)\n- `qpu.forte.1` - 36 qubits, enterprise\n\n**IonQ Advantages:**\n- All-to-all qubit connectivity (no SWAP gates)\n- High-fidelity native gates (\u003e99.5% single-qubit, \u003e97% two-qubit)\n- Native gate set: RX, RY, RZ, XX (Mølmer-Sørensen)\n- Optimal for variational quantum circuits in ML training\n\n**Backend Selection:**\nThe **BackendManager** automatically selects the best backend based on:\n- Circuit requirements (qubit count, depth)\n- Cost constraints\n- Latency requirements\n- Backend availability\n\n## Performance\n\n| Operation | Classical | Quantum (v3.3.1) | Quantum (v3.4) | v3.4 Speedup |\n|-----------|-----------|------------------|----------------|--------------|\n| Vector Search | O(N) | O(√N) | O(√N) | Quadratic |\n| Pattern Discovery | O(N·M) | O(√(N·M)) | O(√(N·M)) | Quadratic |\n| Correlation Updates | O(K²) | O(1) | O(1) | K² (entanglement) |\n| Storage Compression | N vectors | log₂(N) qubits | log₂(N) qubits | Exponential |\n| Gradient Computation | O(N) backprop | O(N) param shift | O(N) param shift | Comparable* |\n| Circuit Execution | Sequential | Sequential | **Parallel Batch** | **8-12x faster** |\n| HPO Search | O(M·N) grid | O(√M) tunneling | O(√M) tunneling | Quadratic |\n\n*Quantum gradients enable exploration of non-convex loss landscapes  \n**v3.4 achieves 8-12x speedup through batch API, native gates, and smart caching\n\n## Use Cases\n\n### Quantum ML Training (v3.2+, 8x Faster in v3.4)\n- Quantum neural network training\n- Hybrid classical-quantum models\n- Transfer learning with quantum layers\n- Hyperparameter optimization\n- Adversarial training\n- Few-shot learning\n\n### Financial Services\n- Portfolio correlation management\n- Crisis pattern detection\n- Time-series prediction\n- Risk analysis\n\n### ML Model Training\n- Context-aware training data selection\n- Hyperparameter optimization\n- Multi-task learning\n- Active learning\n\n### Recommendation Systems\n- User preference modeling\n- Item similarity\n- Cold start problem\n- Session-based recommendations\n\n### Scientific Computing\n- Molecular similarity search\n- Protein structure comparison\n- Drug discovery\n- Materials science\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nSee [LICENSE](LICENCE) file for details.\n\n## References\n\n- [IonQ Getting Started](https://github.com/ionq-samples/getting-started)\n- [Cirq Documentation](https://quantumai.google/cirq)\n- [Qiskit Documentation](https://qiskit.org/documentation/)\n- [Pinecone Documentation](https://docs.pinecone.io/)\n\n\n### Development Commands\n\n```bash\nmake install-dev    # Install with development dependencies\nmake test          # Run tests\nmake format        # Auto-format code\nmake lint          # Run linters\nmake verify        # Run all checks\n```\n\n## Support\n\nFor support, submit issues in this repository or contact yucelz@gmail.com.\n\n## Citation\n\nIf you use Q-Store in your research, please cite:\n\n```bibtex\n@software{qstore2025,\n  title={Q-Store: Quantum-Native Database Architecture v3.4},\n  author={Yucel Zengin},\n  year={2025},\n  url={https://github.com/yucelz/q-store}\n}\n```\n\n## Changelog\n\n### v4.1.0 (2024-12-28)\n- **NEW**: AsyncQuantumExecutor - Non-blocking circuit execution (10-20x throughput)\n- **NEW**: Async Storage System - Zero-blocking Zarr/Parquet with background writers\n- **NEW**: ResultCache - LRU cache for instant repeated circuit results\n- **NEW**: Connection Pooling - Multi-connection backend clients\n- **NEW**: IonQAdapter - Seamless IonQ hardware backend integration\n- **FIXED**: PyTorch QuantumLayer - n_parameters attribute and async execution\n- **ENHANCED**: QuantumFeatureExtractor - Async execution and multi-basis measurements\n- **FOUNDATION**: Built on v4.0.0 verification/profiling/visualization (144 tests)\n- **ARCHITECTURE**: 145 Python files across 29 specialized modules\n- **PERFORMANCE**: 10-20x circuit throughput improvement over v4.0\n- **STORAGE**: Zero-blocking async I/O for all storage operations\n- **PRODUCTION**: Complete async/await API with comprehensive error handling\n\n### v4.0.0 (2024-12-19)\n- **NEW**: Verification Module - Circuit equivalence, property verification, formal analysis\n- **NEW**: Profiling Module - Performance profiling, optimization benchmarks\n- **NEW**: Visualization Module - Circuit diagrams, state visualization, Bloch sphere\n- **NEW**: 144 comprehensive tests for verification/profiling/visualization\n- **NEW**: Integration tests for end-to-end workflows\n- **NEW**: Benchmark suite for performance tracking\n- **IMPROVED**: Complete examples directory with basic/advanced/QML/chemistry/error-correction\n- **PERFORMANCE**: Benchmark baselines established for regression testing\n\n### v4.0.0 (2024-12-XX)\n- **NEW**: Multi-backend orchestration for distributed quantum computing\n- **NEW**: Adaptive circuit optimization with dynamic simplification\n- **NEW**: Adaptive shot allocation for smart resource management\n- **NEW**: Natural gradient descent for improved convergence\n- **PERFORMANCE**: 2-3x throughput improvement via multi-backend distribution\n- **PERFORMANCE**: 30-40% faster execution with adaptive optimization\n\n### v3.4.0 (2024-12-16)\n- **NEW**: IonQ Batch API integration for parallel circuit submission\n- **NEW**: Smart circuit caching with template-based caching\n- **NEW**: IonQ native gate compilation (GPi, GPi2, MS gates)\n- **NEW**: Connection pooling for persistent HTTP connections\n- **PERFORMANCE**: 8-12x faster training (29 min → 3.3 min)\n- **PERFORMANCE**: 5-8 circuits/second (up from 0.5-0.6)\n\n### v3.2.0 (2024-12-15)\n- **New**: Hardware-agnostic quantum ML training infrastructure\n- **New**: QuantumLayer - Variational quantum circuit layers\n- **New**: QuantumTrainer - Training orchestration with quantum gradients\n- **New**: QuantumGradientComputer - Parameter shift rule implementation\n- **New**: QuantumDataEncoder - Amplitude and angle encoding\n- **New**: QuantumOptimizer - Quantum-aware optimization algorithms\n- **New**: QuantumHPOSearch - Quantum-enhanced hyperparameter optimization\n- **New**: CheckpointManager - Model persistence with quantum states\n- **New**: Support for multiple quantum SDKs (Cirq, Qiskit)\n- **New**: Hybrid classical-quantum model support\n- **New**: Quantum transfer learning capabilities\n- **New**: Quantum data augmentation\n- **New**: Quantum regularization techniques\n- **New**: Training data management in quantum database\n- **New**: BackendManager - Intelligent backend selection\n- **Improved**: Database API extended for ML training workflows\n- **Improved**: StateManager for model parameter storage\n\n### v2.0.0 (2025-12-13)\n- **New**: Modern Python project structure with src/ layout\n- **New**: pyproject.toml-based configuration (PEP 621)\n- **New**: Modular package organization (core/, backends/, utils/)\n- **New**: Development automation with Makefile\n- **New**: Comprehensive documentation in docs/\n- **Breaking Changes**: Full async/await API\n- **New**: Production-ready architecture with connection pooling\n- **New**: Pinecone integration for classical vector storage\n- **New**: Comprehensive monitoring and metrics\n- **New**: Enhanced configuration system (DatabaseConfig)\n- **New**: Type-safe API with full type hints\n- **New**: Lifecycle management with context managers\n- **New**: Result caching for improved performance\n- **New**: Comprehensive test suite\n- **Improved**: State management with background decoherence loops\n- **Improved**: Error handling and retry logic\n- **Improved**: Documentation and examples\n\n### v1.0.0 (2025-01-08)\n- Initial release\n- Basic quantum database features\n- IonQ integration\n- Simple examples\n\n---\n\n**Note:** Q-Store v3.4 delivers production-ready quantum ML training with 8-12x performance improvements over v3.3.1. The system features hardware-agnostic support, seamless integration with classical ML frameworks (PyTorch, TensorFlow, JAX), and optimized IonQ execution through batch API, native gates, and smart caching. For mission-critical applications, additional validation and optimization are recommended.\n## Developer Guide\n\n### Setting Up Development Environment\n\n```bash\n# Clone repository\ngit clone https://github.com/yucelz/q-store.git\ncd q-store\n\n# Install in development mode with all dependencies\npip install -e \".[dev,backends,all]\"\n\n# Install pre-commit hooks\npip install pre-commit\npre-commit install\n```\n\n### Code Quality Tools\n\nQ-Store uses automated code quality tools configured in `pyproject.toml` and `.pre-commit-config.yaml`:\n\n**Formatting**:\n```bash\n# Format code with black (line length: 100)\nblack src/q_store\n\n# Sort imports with isort\nisort src/q_store --profile black\n```\n\n**Linting**:\n```bash\n# Run ruff (fast Python linter)\nruff check src/q_store\n\n# Run flake8\nflake8 src/q_store\n\n# Run mypy for type checking\nmypy src/q_store\n```\n\n**Pre-commit Hooks**:\nAll code quality checks run automatically on commit:\n- Trailing whitespace removal\n- End-of-file fixing\n- YAML/JSON/TOML validation\n- Black formatting\n- Import sorting (isort)\n- Ruff linting\n- Type checking (mypy)\n\n**Run All Checks Manually**:\n```bash\npre-commit run --all-files\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=src/q_store --cov-report=html\n\n# Run specific test file\npytest tests/test_quantum_database.py\n\n# Run with specific markers\npytest -m \"not slow\"\npytest -m integration\n```\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/my-feature`\n3. Make your changes\n4. Run code quality tools: `pre-commit run --all-files`\n5. Run tests: `pytest`\n6. Commit changes (pre-commit hooks will run automatically)\n7. Push to your fork: `git push origin feature/my-feature`\n8. Create a Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyucelz%2Fq-store","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyucelz%2Fq-store","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyucelz%2Fq-store/lists"}