Python SDK

The Quantag Python SDK provides high-level access to the Quantag Quantum Virtual Machine (QVM) and optimization routines (QAOA) on different backends including Qiskit simulators and D-Wave.

Installation

Install from PyPI:

pip install quantag

Optional extras:

pip install quantag[dwave]

Quick Start

from quantag import QVMBackend

backend = QVMBackend()
result = backend.run("H 0; CX 0 1; measure 0; measure 1;")
print(result)

This executes a simple Bell-state circuit on the Quantag simulator.

Simulator

The QVM backend provides a local quantum simulator compatible with OpenQASM input.

Example:

from quantag import QVMBackend

qasm_code = """
OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0], q[1];
measure q -> c;
"""

backend = QVMBackend()
result = backend.run(qasm_code, shots=1024)
print(result.get_counts())

Optimizer (QAOA)

The SDK also provides a high-level QAOA solver for combinatorial optimization.

Portfolio optimization example:

from quantag import QAOASolver

# Local portfolio definition (CSV with "returns" column)
solver = QAOASolver(backend="dwave")   # or "qiskit"
result = solver.solve("portfolio.csv", problem="portfolio")
print(result)

  • If backend=”qiskit”, QAOA is executed with Qiskit simulators (Sampler-based).

  • If backend=”dwave”, the problem is mapped to QUBO and submitted to D-Wave (if API token is provided).

  • If no token is provided or access is unavailable, a local dimod.ExactSolver() is used.

Example with explicit D-Wave cloud access:

solver = QAOASolver(backend="dwave")
result = solver.solve(
    "portfolio.csv",
    problem="portfolio",
    api_token="YOUR_DWAVE_API_KEY",
    solver="Advantage_system4.1"
)
print(result)

Data Sources

One unique feature of the Quantag QAOA optimizer is flexible data ingestion. Optimization problems can be defined directly from real-world data without tedious preprocessing.

Currently supported:

  • CSV files (recommended; lightweight and universal)

  • SQL databases (PostgreSQL, MySQL, SQLite) via SQLAlchemy

Planned extensions:

  • JSON and Parquet files

  • Cloud storage URIs (AWS S3, Google Cloud Storage, Azure Blob)

  • REST APIs returning JSON or CSV

  • Streaming sources (Kafka, MQTT) for real-time optimization

Examples:

# From CSV
solver.solve("portfolio.csv", problem="portfolio")

# From PostgreSQL
solver.solve(
    "postgresql://user:pass@localhost/mydb",
    problem="portfolio",
    table="portfolio_data"
)

# From a REST API (planned)
solver.solve("https://api.example.com/portfolio.json", problem="portfolio")

Results

  • Simulator returns Qiskit-like counts dictionaries (e.g., {“00”: 512, “11”: 512}).

  • QAOA returns either a structured optimization result (Qiskit) or a dimod.SampleSet (D-Wave/local).

QImage Module

The quantag.qimage module provides quantum-inspired image compression based on Quantum Principal Component Analysis (QPCA).

Overview

This module demonstrates how classical images can be represented as quantum-like states (normalized amplitudes) and then analyzed using QPCA methods. The algorithm works classically today, but follows the same mathematical structure that can be deployed on future Quantum Processing Units (QPUs).

Main class

Example usage

from quantag import QImageCompressor
from PIL import Image

# Initialize compressor with 95% energy threshold
compressor = QImageCompressor(energy_threshold=0.95)

# Compress an image
result = compressor.compress("example.png")

print("Number of components kept (k):", result["k"])
print("Mean Squared Error (MSE):", result["mse"])

# Save outputs
Image.fromarray(result["reconstructed"]).save("reconstructed.png")
Image.fromarray(result["compressed"]).save("compressed.png")

# Inspect overlay components
for i, comp in enumerate(result["components"]):
    Image.fromarray(comp.astype("uint8")).save(f"component_{i}.png")

The compress() method returns:

  • original: the original grayscale data as NumPy array

  • reconstructed: full reconstruction from all components

  • compressed: compressed reconstruction (~95% variance preserved)

  • mse: mean squared error of compression

  • components: leading principal components reshaped as images

  • k: number of components retained

QImageCompressor also provides a utility to_base64 for embedding results in web frontends.

qimage is fully integrated into the quantag package and can be used together with other modules such as QAOA optimization.

Roadmap

Future extensions of the Python SDK will include:

  • Support for Quantag?s QBIN binary circuit format.

  • Additional optimization problems (MaxCut, scheduling, etc.).

  • Hybrid quantum-classical routines.