Skip to content
/ q-store-examples Public

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.

www.q-store.tech

License

MIT license
0 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

yucelz/q-store-examples

BranchesTags

Repository files navigation

Q-Store Examples

Standalone example projects demonstrating Q-Store 3.4.3 quantum database capabilities for ML training, financial applications, and more.

Note: This is a standalone examples repository. Q-Store 3.4.3 is installed via pip or from a local wheel file.

📖 For detailed setup instructions and troubleshooting, see SETUP.md

🚀 Quick Start

Prerequisites

  • Python 3.8 or higher
  • pip or conda package manager
  • API keys (see API Keys section)

Installation

Option 1: Editable Install (Recommended for Development)

# 1. Clone this repository
git clone https://github.com/yucelz/q-store-examples.git
cd q-store-examples

# 2. Install package in editable mode (changes are immediately reflected)
pip install -e .

# Or with optional ML dependencies
pip install -e ".[ml,data,dev]"

# 3. Set up environment variables
cp .env.example .env
# Edit .env and add your API keys

# 4. Verify installation
python scripts/verify_installation.py

Option 2: Using requirements.txt

# 1. Clone this repository
git clone https://github.com/yucelz/q-store-examples.git
cd q-store-examples

# 2. Install Q-Store 3.4.3 and dependencies
pip install -r requirements.txt

# 3. Install the package (required for imports to work)
pip install -e .

# 4. Set up environment variables
cp .env.example .env
# Edit .env and add your API keys

# 5. Verify installation
python scripts/verify_installation.py

Option 3: Using conda

# 1. Clone this repository
git clone https://github.com/yucelz/q-store-examples.git
cd q-store-examples

# 2. Create conda environment
conda create -n q-store-examples python=3.11
conda activate q-store-examples

# 3. Install the package
pip install -e .

# 4. Set up environment variables
cp .env.example .env
# Edit .env and add your API keys

# 5. Verify installation
python scripts/verify_installation.py

Option 4: Using Local Wheel File

If you have the Q-Store wheel file:

# 1. Clone this repository
git clone https://github.com/yucelz/q-store-examples.git
cd q-store-examples

# 2. Copy the wheel file to this directory
cp /path/to/q_store-3.4.3-cp313-cp313-manylinux_2_17_x86_64.whl .

# 3. Install using make
make install-wheel

# Or install manually:
# pip install q_store-3.4.3-cp313-cp313-manylinux_2_17_x86_64.whl
# pip install -r requirements.txt --no-deps

# 4. Set up environment variables
cp .env.example .env
# Edit .env and add your API keys

# 5. Verify installation
python scripts/verify_installation.py

Option 4: Using Local Wheel File

If you have the Q-Store wheel file:

# 1. Clone this repository
git clone https://github.com/yucelz/q-store-examples.git
cd q-store-examples

# 2. Copy the wheel file to this directory
cp /path/to/q_store-3.4.3-cp313-cp313-manylinux_2_17_x86_64.whl .

# 3. Install using make
make install-wheel

# Or install manually:
# pip install q_store-3.4.3-cp313-cp313-manylinux_2_17_x86_64.whl
# pip install -e .

# 4. Set up environment variables
cp .env.example .env
# Edit .env and add your API keys

# 5. Verify installation
python scripts/verify_installation.py

Option 5: Minimal Installation (No ML Dependencies)

# Clone and navigate to repository
git clone https://github.com/yucelz/q-store-examples.git
cd q-store-examples

# Install only core dependencies (includes q-store==3.4.3)
pip install -r requirements-minimal.txt

# This allows running:
# - basic_example.py
# - financial_example.py
# - quantum_db_quickstart.py

🔑 API Keys

Required

Optional

Configuration

# Copy the example file
cp .env.example .env

# Edit with your favorite editor
nano .env  # or vim, code, etc.

# Add your keys:
PINECONE_API_KEY=your_actual_key_here
PINECONE_ENVIRONMENT=us-east-1
IONQ_API_KEY=your_ionq_key_here  # Optional

# Verify configuration
python show_config.py

The show_config.py script will display your current configuration and guide you on next steps.

📚 Available Examples

1. Basic Example (basic_example.py)

Demonstrates core Q-Store functionality:

  • Inserting vectors with quantum contexts
  • Querying with superposition
  • Creating entangled groups
  • Quantum tunneling for exploration
python basic_example.py

2. Financial Example (financial_example.py)

Financial data analysis with quantum features:

  • Portfolio optimization
  • Risk correlation analysis
  • Market regime detection
  • Anomaly detection
python financial_example.py

3. Quantum Database Quickstart (quantum_db_quickstart.py)

Comprehensive tutorial covering:

  • Database initialization
  • All query modes (PRECISE, BALANCED, EXPLORATORY)
  • Advanced quantum features
  • Performance optimization
python quantum_db_quickstart.py

4. V3.2 ML Training Examples (src/q_store_examples/examples_v3_2.py)

Complete quantum ML training demonstrations:

  • Basic quantum neural network training
  • Quantum data encoding strategies
  • Transfer learning with quantum models
  • Multiple backend comparison
  • Database-ML integration
  • Quantum autoencoder
# Run with mock backends (no API keys needed)
python src/q_store_examples/examples_v3_2.py

# Run with real Pinecone and IonQ backends
# Option 1: Using .env file (recommended)
# Make sure your .env file has PINECONE_API_KEY and IONQ_API_KEY set
python src/q_store_examples/examples_v3_2.py --no-mock

# Option 2: Using environment variables
export PINECONE_API_KEY="your-pinecone-key"
export IONQ_API_KEY="your-ionq-key"
export PINECONE_ENVIRONMENT="us-east-1"
export IONQ_TARGET="simulator"

python src/q_store_examples/examples_v3_2.py --no-mock

# Option 3: Using command-line arguments (overrides .env)
python src/q_store_examples/examples_v3_2.py --no-mock \
  --pinecone-api-key YOUR_PINECONE_KEY \
  --pinecone-env us-east-1 \
  --ionq-api-key YOUR_IONQ_KEY \
  --ionq-target simulator

# Available IonQ targets:
# - simulator (free, default)
# - ionq_simulator 
# - qpu.aria-1 (requires credits)
# - qpu.forte-1 (requires credits)

Priority Order: Command-line args → Environment variables → .env file → Defaults

5. V3.3 High-Performance ML Training Examples (src/q_store_examples/examples_v3_3.py)

NEW - 24-48x faster training with algorithmic optimization:

  • SPSA gradient estimation (2 circuits instead of 96)
  • Hardware-efficient quantum layers (33% fewer parameters)
  • Adaptive gradient optimization
  • Circuit caching and batching
  • Performance tracking and comparison
  • Real-time speedup analysis
# With mock backends (default - for testing)
python src/q_store_examples/examples_v3_3.py

# With real IonQ/Pinecone backends
python src/q_store_examples/examples_v3_3.py --no-mock

# With specific credentials
python src/q_store_examples/examples_v3_3.py --no-mock \
  --ionq-api-key YOUR_KEY \
  --pinecone-api-key YOUR_KEY

# See all options
python src/q_store_examples/examples_v3_3.py --help

Performance Improvements:

  • 🚀 48x fewer circuits with SPSA (2 vs 96 per batch)
  • ⚡ 33% fewer parameters with hardware-efficient ansatz
  • 💾 Circuit caching eliminates redundant compilations
  • 🔄 Batch execution enables parallel quantum jobs
  • 📊 Performance tracking shows real-time speedup metrics

Priority Order: Command-line args → Environment variables → .env file → Defaults

6. V3.4 Performance-Optimized ML Training Examples (src/q_store_examples/examples_v3_4.py)

LATEST - 8-10x faster than v3.3.1 through true parallelization:

  • IonQBatchClient: Single API call for all circuits (12x faster submission)
  • IonQNativeGateCompiler: GPi/GPi2/MS native gates (30% faster execution)
  • SmartCircuitCache: Template-based caching (10x faster preparation)
  • CircuitBatchManagerV34: Orchestrates all optimizations together
  • Production training workflow with full v3.4 features
  • Configuration guide and performance evolution analysis
# ============================================================================
# BASIC USAGE
# ============================================================================

# 1. Mock mode (default - safe testing, no API calls needed)
python src/q_store_examples/examples_v3_4.py

# 2. Real IonQ/Pinecone backends (uses .env file)
python src/q_store_examples/examples_v3_4.py --no-mock

# ============================================================================
# CONFIGURATION OPTIONS
# ============================================================================

# Option 1: Using .env file (RECOMMENDED)
# Make sure your .env file has:
#   PINECONE_API_KEY=your-pinecone-key
#   IONQ_API_KEY=your-ionq-key
#   PINECONE_ENVIRONMENT=us-east-1
#   IONQ_TARGET=simulator

python src/q_store_examples/examples_v3_4.py --no-mock

# Option 2: Using environment variables
export PINECONE_API_KEY="your-pinecone-key"
export IONQ_API_KEY="your-ionq-key"
export PINECONE_ENVIRONMENT="us-east-1"
export IONQ_TARGET="simulator"

python src/q_store_examples/examples_v3_4.py --no-mock

# Option 3: Using command-line arguments (overrides .env and env vars)
python src/q_store_examples/examples_v3_4.py --no-mock \
  --pinecone-api-key YOUR_PINECONE_KEY \
  --pinecone-env us-east-1 \
  --ionq-api-key YOUR_IONQ_KEY \
  --ionq-target simulator

# ============================================================================
# IONQ TARGET OPTIONS
# ============================================================================

# Simulator (free, default)
python src/q_store_examples/examples_v3_4.py --no-mock --ionq-target simulator

# IonQ Harmony QPU (requires credits)
python src/q_store_examples/examples_v3_4.py --no-mock --ionq-target qpu.harmony

# IonQ Aria QPU (requires credits)
python src/q_store_examples/examples_v3_4.py --no-mock --ionq-target qpu.aria-1

# ============================================================================
# ADVANCED USAGE
# ============================================================================

# Show all available options
python src/q_store_examples/examples_v3_4.py --help

# Full example with all parameters
python src/q_store_examples/examples_v3_4.py \
  --no-mock \
  --pinecone-api-key pk-xxxxx \
  --pinecone-env us-east-1 \
  --ionq-api-key xxxxxxxx \
  --ionq-target simulator

What Each Example Demonstrates:

Example Focus Key Feature
Example 1 IonQBatchClient True batch submission (1 API call vs 20)
Example 2 IonQNativeGateCompiler Native gate compilation (GPi/GPi2/MS)
Example 3 SmartCircuitCache Template-based circuit caching
Example 4 CircuitBatchManagerV34 All optimizations integrated
Example 5 Production Training Complete training workflow with v3.4
Example 6 Configuration Guide 4 config scenarios for different use cases
Example 7 Performance Evolution v3.2 → v3.3 → v3.3.1 → v3.4 comparison

Performance Targets:

  • 📊 Batch time: 35s (v3.3.1) → 4s (v3.4) = 8.75x faster
  • ⚡ Circuits/sec: 0.57 (v3.3.1) → 5.0 (v3.4) = 8.8x throughput
  • 🚀 Training time: 29.6 min (v3.3.1) → 3.75 min (v3.4) = 7.9x faster

Key Innovations:

Batch API:     20 circuits → 1 API call     = 12x faster submission
Native Gates:  GPi/GPi2/MS gates            = 30% faster execution  
Smart Cache:   Template reuse               = 10x faster preparation
─────────────────────────────────────────────────────────────────────
Combined:      All optimizations together   = 8-10x overall speedup

Migration from v3.3.1:

# Just add one line to your existing config:
config = TrainingConfig(
    # ... all your existing v3.3.1 settings ...
    enable_all_v34_features=True  # 🔥 Enable v3.4 optimizations
)
# That's it! Fully backward compatible.

Priority Order: Command-line args → Environment variables → .env file → Defaults

7. ML Training Example (ml_training_example.py)

Machine learning integration:

  • Model embedding storage
  • Training data selection
  • Curriculum learning
  • Hard negative mining
python ml_training_example.py

8. Connection Tests

Verify Pinecone and IonQ connections:

# Option 1: Using .env file (recommended)
# Ensure your .env has PINECONE_API_KEY and IONQ_API_KEY set
python test_pinecone_ionq_connection.py
python test_cirq_adapter_fix.py

# Option 2: Set environment variables explicitly
export PINECONE_API_KEY="your-key"
export IONQ_API_KEY="your-key"

python test_pinecone_ionq_connection.py
python test_cirq_adapter_fix.py

These tests will:

  • ✅ Initialize Pinecone client and create test indexes
  • ✅ Configure IonQ backend (simulator and QPU)
  • ✅ Execute quantum circuits on IonQ
  • ✅ Run small training session with real backends
  • ✅ Verify Pinecone index creation during training

9. TinyLlama React Training (tinyllama_react_training.py)

Complete LLM fine-tuning workflow:

  • React code dataset generation
  • Quantum-enhanced data sampling
  • LoRA fine-tuning
  • Curriculum learning
# Option 1: Automated workflow
./run_react_training.sh

# Option 2: Step-by-step
python react_dataset_generator.py
python tinyllama_react_training.py

# See REACT_QUICK_REFERENCE.md for details

📖 Documentation

Document Description
REACT_QUICK_REFERENCE.md Quick start for React training
REACT_TRAINING_WORKFLOW.md Detailed React training guide
TINYLLAMA_TRAINING_README.md TinyLlama fine-tuning guide
IMPROVEMENTS_SUMMARY.md Code improvements and comparisons

🔧 Configuration

Environment Variables

All configuration is done through .env file:

# Required
PINECONE_API_KEY=your_key
PINECONE_ENVIRONMENT=us-east-1

# Optional
IONQ_API_KEY=your_ionq_key
IONQ_TARGET=simulator

# ML Training (optional)
HUGGING_FACE_TOKEN=your_token
OUTPUT_DIR=./models

Custom Settings

Edit configuration in each example file:

# Example: tinyllama_react_training.py
config = TrainingConfig(
    max_samples=1000,
    num_train_epochs=3,
    use_quantum_sampling=True,
    use_curriculum_learning=True
)

🧪 Testing

Verify Installation

# Test Q-Store installation
python verify_installation.py

# Check your configuration (.env file)
python show_config.py

# Test React integration
python verify_react_integration.py

# Test TinyLlama setup
python verify_tinyllama_example.py

# Verify v3.2 components
cd ..
python verify_v3_2.py
cd examples

Test Quantum Backends

# Quick Cirq adapter test
python test_cirq_adapter_fix.py

# Comprehensive Pinecone + IonQ test
python test_pinecone_ionq_connection.py

Run Unit Tests

# Install dev dependencies
pip install pytest pytest-cov black isort flake8 mypy

# Run tests
pytest

# With coverage
pytest --cov=. --cov-report=html

💡 Usage Tips

GPU Support

For CUDA GPU support:

# Install PyTorch with CUDA
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# Verify GPU availability
python -c "import torch; print('GPU Available:', torch.cuda.is_available())"

Memory Management

For large datasets or limited RAM:

# Reduce batch size
config = TrainingConfig(
    per_device_train_batch_size=1,  # Smaller batches
    gradient_accumulation_steps=16,  # Accumulate gradients
    max_samples=500                   # Limit dataset size
)

Development Mode

For development with the latest Q-Store:

# If you have Q-Store source code, install in editable mode
cd /path/to/q-store
pip install -e .

# Or use the latest from PyPI
pip install --upgrade q-store

# Now run examples with the updated version

🐛 Troubleshooting

Common Issues

Issue Solution
ModuleNotFoundError: q_store Install Q-Store: pip install q-store==3.4.3
PINECONE_API_KEY not found Create .env file with your API key
ImportError: transformers Install ML dependencies: pip install -r requirements.txt
CUDA out of memory Reduce batch size or use CPU
Dataset file not found Run dataset generator first
'list' object has no attribute 'measurements' Fixed in latest version - Cirq adapter updated
Pinecone index not created Ensure API key is valid, check --no-mock flag

Debug Mode

Enable verbose logging:

# Set environment variable
export LOG_LEVEL=DEBUG

# Or in .env file
echo "LOG_LEVEL=DEBUG" >> .env

Getting Help

  1. Check the documentation files in this directory
  2. Review the parent Q-Store README
  3. Open an issue on GitHub
  4. Review existing issues and discussions

🎯 Next Steps

  1. Run Basic Example: Start with basic_example.py
  2. Try React Training: Use the automated workflow
  3. Experiment: Modify configs and try different strategies
  4. Build Your Own: Use examples as templates
  5. Contribute: Share improvements and new examples

📊 Performance Benchmarks

Dataset Sizes

  • Minimal: 500-1,000 samples (fast, for testing)
  • Medium: 1,000-5,000 samples (balanced)
  • Large: 5,000-10,000+ samples (best results)

Training Times (approximate)

  • Dataset Generation: 10-30 seconds
  • Database Loading: 1-3 minutes
  • Quantum Sampling Demo: 30 seconds
  • Full Training: 30-90 minutes (with GPU)

🤝 Contributing

Contributions are welcome! To add new examples:

  1. Follow the existing code structure
  2. Add documentation
  3. Include requirements
  4. Test thoroughly
  5. Submit a pull request

📄 License

MIT License - see parent repository for details

🔗 Related Resources

📞 Support

Ready to start? Check your configuration:

python show_config.py

If all checks pass, you're ready to explore quantum-enhanced machine learning! 🚀

Quick Start:

# V3.2 - Standard quantum ML training
# With mock backends (safe, no API calls)
python src/q_store_examples/examples_v3_2.py

# With real Pinecone + IonQ (uses your .env configuration)
python src/q_store_examples/examples_v3_2.py --no-mock

# V3.3 - High-performance quantum ML training (24-48x faster!)
# With mock backends (safe, no API calls)
python src/q_store_examples/examples_v3_3.py

# With real Pinecone + IonQ (uses your .env configuration)
python src/q_store_examples/examples_v3_3.py --no-mock

# V3.3.1 - Corrected batch gradient training (True SPSA parallelization)
# With mock backends (safe, no API calls)
python src/q_store_examples/examples_v3_3_1.py

# With real Pinecone + IonQ (uses your .env configuration)
python src/q_store_examples/examples_v3_3_1.py --no-mock

# V3.4 - Performance optimized (8-10x faster than v3.3.1!) ⚡ RECOMMENDED
# With mock backends (safe, no API calls)
python src/q_store_examples/examples_v3_4.py

# With real Pinecone + IonQ (uses your .env configuration)
python src/q_store_examples/examples_v3_4.py --no-mock

# With specific API keys (overrides .env)
python src/q_store_examples/examples_v3_4.py --no-mock \
  --pinecone-api-key YOUR_PINECONE_KEY \
  --ionq-api-key YOUR_IONQ_KEY

# ============================================================================
# PERFORMANCE COMPARISON
# ============================================================================
# v3.2:   Parameter Shift (960 circuits/batch) - Baseline
# v3.3:   SPSA (20 circuits/batch) - 48x fewer circuits
# v3.3.1: Parallel SPSA (20 circuits/batch, parallel) - Correct implementation
# v3.4:   Batch API + Native Gates + Caching - 8-10x faster than v3.3.1!
#
# Recommended: Start with v3.4 for best performance! 🚀
# ============================================================================

docs/sphinx

# Install documentation dependencies
pip install sphinx sphinx-rtd-theme
cd docs/sphinx
sphinx-build -b html . _build/html

About

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.

www.q-store.tech

Topics

quantum-computing q-store quatum-database

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages