quantumflow-sdk 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

api/main.py

@@ -36,6 +36,9 @@ from api.auth import get_current_user, get_optional_user, get_db_session
 from api.routes.auth_routes import router as auth_router
 from api.routes.teleport_routes import router as teleport_router
 from api.routes.algorithm_routes import router as algorithm_router
+from api.routes.chat_routes import router as chat_router
+# Pipeline routes disabled - internal research only (not public API)
+# from api.routes.pipeline_routes import router as pipeline_router
 
 # Import billing routes (optional - only if Stripe is configured)
 try:
@@ -120,6 +123,13 @@ app.include_router(teleport_router)
 # Include algorithm routes (QNN, Grover, QAOA, VQE, QSVM, QKD, QRNG, QFT)
 app.include_router(algorithm_router)
 
+# Include QChat messaging routes (P2P encrypted messaging)
+app.include_router(chat_router)
+
+# Pipeline routes disabled - internal research only
+# To enable: uncomment import and line below
+# app.include_router(pipeline_router)
+
 # Include billing routes if available
 if BILLING_ENABLED and billing_router:
     app.include_router(billing_router)
@@ -160,14 +170,29 @@ async def compress_tokens(
     Compress tokens using quantum amplitude encoding.
 
     Achieves 53% token reduction via quantum superposition.
+
+    Options:
+    - `use_gray_code`: Enable Gray-code measurement protocol (arXiv:2601.00247)
+      which reduces measurement settings from O(N) to 2n+1.
     """
     if not _compressor:
         raise HTTPException(status_code=503, detail="Quantum compressor not initialized")
 
     start_time = time.perf_counter()
+    measurement_settings = None
+    gray_code_enabled = request.use_gray_code
 
     try:
-        if request.execute:
+        if request.use_gray_code and request.execute:
+            # Use Gray-code measurement protocol
+            result, gray_result = _compressor.compress_with_gray_code(
+                tokens=request.tokens,
+                compression_level=request.compression_level,
+                shots=request.shots,
+            )
+            fidelity = result.execution_result.fidelity if result.execution_result else None
+            measurement_settings = gray_result.n_measurement_settings
+        elif request.execute:
             result = _compressor.compress_and_execute(
                 tokens=request.tokens,
                 compression_level=request.compression_level,
@@ -210,6 +235,8 @@ async def compress_tokens(
             fidelity=fidelity,
             execution_time_ms=execution_time,
             backend_used=request.backend,
+            measurement_settings=measurement_settings,
+            gray_code_enabled=gray_code_enabled,
         )
 
     except Exception as e:

api/models.py

@@ -16,6 +16,10 @@ class CompressRequest(BaseModel):
     backend: str = Field(default="auto", description="Backend: auto, simulator, ibm")
     execute: bool = Field(default=False, description="Execute on quantum backend")
     shots: int = Field(default=1024, ge=1, le=10000)
+    use_gray_code: bool = Field(
+        default=False,
+        description="Use Gray-code measurement protocol (arXiv:2601.00247) for efficient readout"
+    )
 
 
 class CompressResponse(BaseModel):
@@ -29,6 +33,43 @@ class CompressResponse(BaseModel):
     fidelity: Optional[float] = None
     execution_time_ms: Optional[float] = None
     backend_used: str
+    # Gray-code specific fields
+    measurement_settings: Optional[int] = Field(
+        default=None,
+        description="Number of measurement settings used (2n+1 for Gray-code)"
+    )
+    gray_code_enabled: bool = Field(default=False)
+
+
+# === SES VQE Models (arXiv:2601.00247) ===
+
+class SESVQERequest(BaseModel):
+    """Request for Single Excitation Subspace VQE."""
+
+    n_sites: int = Field(..., ge=2, le=1024, description="Number of lattice sites")
+    on_site_energies: list[float] = Field(..., description="Energy at each site [h_11, h_22, ...]")
+    hopping_terms: list[tuple[int, int, float]] = Field(
+        ...,
+        description="Hopping amplitudes [(i, j, t_ij), ...] between sites"
+    )
+    max_iterations: int = Field(default=100, ge=10, le=1000)
+    backend: str = Field(default="auto")
+    shots: int = Field(default=1024, ge=100, le=10000)
+
+
+class SESVQEResponse(BaseModel):
+    """Response from SES VQE computation."""
+
+    ground_energy: float
+    n_sites: int
+    n_qubits_used: int = Field(description="Logarithmic encoding: log₂(n_sites)")
+    qubit_reduction_percent: float
+    iterations: int
+    volumetric_cost: int
+    original_volumetric_cost: int
+    speedup: float
+    execution_time_ms: float
+    ansatz_type: str = "ses_binary"
 
 
 # === Gradient Models ===

api/routes/algorithm_routes.py

@@ -506,6 +506,128 @@ async def vqe_compute(
         raise HTTPException(status_code=400, detail=str(e))
 
 
+# ============================================================
+# SES VQE - Single Excitation Subspace (arXiv:2601.00247)
+# ============================================================
+
+class SESVQERequest(BaseModel):
+    """Request for Single Excitation Subspace VQE.
+
+    Uses logarithmic qubit encoding from arXiv:2601.00247:
+    - N lattice sites encoded in log₂(N) qubits
+    - Exponential reduction in quantum resources
+    - Ideal for tight-binding Hamiltonians
+    """
+    n_sites: int = Field(..., ge=2, le=1024, description="Number of lattice sites")
+    on_site_energies: List[float] = Field(
+        ...,
+        description="Diagonal energies [h_11, h_22, ...] for each site"
+    )
+    hopping_terms: List[List] = Field(
+        ...,
+        description="Hopping terms [[i, j, t_ij], ...] between sites"
+    )
+    max_iterations: int = Field(default=100, ge=10, le=1000)
+    backend: str = Field(default="simulator")
+    shots: int = Field(default=1024, ge=100, le=10000)
+
+
+class SESVQEResponse(BaseModel):
+    """Response from SES VQE computation."""
+    ground_energy: float
+    n_sites: int
+    n_qubits_used: int = Field(description="Logarithmic encoding: ⌈log₂(n_sites)⌉")
+    qubit_reduction_percent: float
+    iterations: int
+    energy_history: List[float]
+    volumetric_cost: int
+    original_volumetric_cost: int
+    speedup: float
+    execution_time_ms: float
+    ansatz_type: str = "ses_binary"
+
+
+@router.post("/ses/solve", response_model=SESVQEResponse)
+async def ses_vqe_solve(
+    request: SESVQERequest,
+    user: User = Depends(get_current_user),  # Requires API key
+):
+    """
+    Run VQE with Single Excitation Subspace (SES) ansatz.
+
+    Based on arXiv:2601.00247 - achieves exponential reduction in
+    quantum resources for tight-binding Hamiltonians:
+
+    - **Qubit reduction**: N sites → log₂(N) qubits
+    - **Volumetric speedup**: O(N²) → O((log N)³)
+
+    Use cases:
+    - Tight-binding band structure calculations
+    - Solid-state physics simulations
+    - Material property prediction
+
+    Example (8-site chain):
+    ```json
+    {
+        "n_sites": 8,
+        "on_site_energies": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
+        "hopping_terms": [[0,1,-1.0], [1,2,-1.0], [2,3,-1.0], ...]
+    }
+    ```
+    Uses only 3 qubits instead of 8!
+    """
+    import math
+    from quantumflow.algorithms.machine_learning.vqe import run_ses_vqe, calculate_volumetric_cost
+
+    start_time = time.perf_counter()
+
+    try:
+        # Validate input
+        if len(request.on_site_energies) != request.n_sites:
+            raise ValueError(
+                f"on_site_energies length ({len(request.on_site_energies)}) "
+                f"must match n_sites ({request.n_sites})"
+            )
+
+        # Convert hopping terms to tuples
+        hopping_tuples = [
+            (int(h[0]), int(h[1]), complex(h[2]) if len(h) > 2 else complex(-1.0))
+            for h in request.hopping_terms
+        ]
+
+        # Run SES VQE
+        result = run_ses_vqe(
+            n_sites=request.n_sites,
+            on_site_energies=request.on_site_energies,
+            hopping_terms=hopping_tuples,
+            max_iterations=request.max_iterations,
+            backend=request.backend,
+        )
+
+        execution_time = (time.perf_counter() - start_time) * 1000
+
+        # Calculate efficiency metrics
+        n_qubits = math.ceil(math.log2(request.n_sites))
+        costs = calculate_volumetric_cost(request.n_sites, "ses_binary")
+
+        return SESVQEResponse(
+            ground_energy=result.ground_energy,
+            n_sites=request.n_sites,
+            n_qubits_used=n_qubits,
+            qubit_reduction_percent=(1 - n_qubits / request.n_sites) * 100,
+            iterations=result.n_iterations,
+            energy_history=result.energy_history,
+            volumetric_cost=costs["volumetric_cost"],
+            original_volumetric_cost=costs["original_volumetric_cost"],
+            speedup=costs["speedup"],
+            execution_time_ms=execution_time,
+            ansatz_type="ses_binary",
+        )
+
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
 # ============================================================
 # Algorithm Info Endpoint
 # ============================================================
@@ -863,6 +985,18 @@ async def list_algorithms():
                 "endpoints": ["/v1/algorithms/vqe/compute"],
                 "use_cases": ["Molecular simulation", "Ground state energy", "Quantum chemistry"],
             },
+            {
+                "id": "ses",
+                "name": "SES VQE",
+                "description": "Single Excitation Subspace VQE with logarithmic qubit encoding (arXiv:2601.00247)",
+                "endpoints": ["/v1/algorithms/ses/solve"],
+                "use_cases": ["Tight-binding Hamiltonians", "Band structure", "Solid-state physics"],
+                "features": {
+                    "qubit_reduction": "N sites → log₂(N) qubits",
+                    "speedup": "O(N²) → O((log N)³)",
+                    "ansatz": "Binary-encoded SES with Gray-code measurement"
+                }
+            },
             {
                 "id": "qsvm",
                 "name": "Quantum SVM",