Metadata-Version: 2.1
Name: qdeepsdk
Version: 0.2.0
Summary: Our hybrid solver for QUBO problems merges classical and quantum computing, efficiently solving complex optimization tasks. It offers fast, accurate results for applications in logistics, finance, and more.
Home-page: UNKNOWN
Author: Ahmad Sarhan
Author-email: ahmadhasansarhana@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: numpy (>=1.18.0)
Requires-Dist: requests (>=2.24.0)

# QDeep Hybrid Solver - Quadratic Unconstrained Binary Optimization Solver

**QDeep Hybrid Solver** is a Python library specifically developed for efficiently solving **Quadratic Unconstrained Binary Optimization (QUBO)** problems through advanced hybrid quantum-classical computing methods. It provides a user-friendly interface to submit QUBO matrices and retrieve structured, optimized solutions.

## Mathematical Formulation

A QUBO problem is mathematically expressed as:

![1742437383961](images/README/1742437383961.png)

where:

- \(x\) is a binary vector.
- \(Q\) is a symmetric matrix representing the problem's coefficients.

## Features

- Type-hinted implementation using Python's `TypedDict`
- Comprehensive input validation for matrices
- Secure authentication token management
- Structured and detailed response handling

## Installation

Install the required dependencies along with the solver:

```bash
pip install numpy requests qdeepsdk
```

### Dependencies

- `numpy`
- `requests`
- `qdeepsdk`

## Usage

```python
import numpy as np
from qdeepsdk import QDeepHybridSolver

# Initialize solver
solver = QDeepHybridSolver()

# Set authentication token
solver.token = "your-auth-token-here"

# Create a QUBO matrix
matrix = np.array([
    [-1,  2,  2],
    [ 0, -1,  2],
    [ 0,  0, -1]
])

# Solve the QUBO problem
try:
    results = solver.solve(matrix)
  
    # Access results
    print("Hybrid Solver Results:", results)
  
except ValueError as e:
    print(f"Error: {e}")
except requests.RequestException as e:
    print(f"API Error: {e}")
```

## API Response Structure

The solver returns a structured dictionary with the following format:

```json
{
    "configuration": [int],  # Solution vector
    "energy": float,         # Energy of the solution
    "time": float            # Computation time in seconds
}
```

## Requirements

- Python 3.7+
- NumPy
- Requests

The library includes comprehensive error handling for:

- Invalid or missing authentication tokens
- Non-square matrices
- Non-2D matrices
- Non-numpy array inputs
- API connection issues

```

```


