openqubo 0.1.0

OpenQUBO: QUBO analysis, compilation, visualization, and solver pipelines

OpenQUBO

OpenQUBO is a toolkit for analyzing, compiling, and solving Quadratic Unconstrained Binary Optimization (QUBO) problems across classical, quantum annealing, and gate-based quantum backends.

Developed by Micah Shaw
SemperKite Quantum Labs
https://semperkite.io

---

Overview

OpenQUBO provides tools for working with QUBO models in research and optimization workflows, including:

• QUBO normalization and graph analysis
• Gate-model layout optimization for quantum circuits
• Annealing topology and embedding selection
• Classical validation and solver pipelines
• Visualization tools for QUBO structure and embeddings
• CLI tools for running QUBO pipelines

The library is designed to work with modern quantum and classical toolchains such as:

• Qiskit
• D-Wave Ocean / dimod
• NetworkX
• NumPy

---

Features

QUBO Analysis

Parse and normalize QUBO inputs from:

• matrices
• dictionaries
• edge lists

Convert QUBO problems into graph representations for analysis and visualization.

---

Gate Model Backend

Analyze QUBO interaction graphs and map them onto quantum hardware coupling graphs.

Features include:

• layout method comparison
• routing method comparison
• circuit transpilation scoring
• logical → physical qubit mapping

Built using Qiskit transpiler tools.

---

Annealing Backend

Evaluate whether a QUBO problem fits annealing hardware topologies such as:

• Pegasus-like graphs
• Chimera-like graphs

Includes:

• embedding search (via minorminer)
• chain length analysis
• topology scoring

---

Solver Pipeline

Validate and solve QUBO models using classical solvers.

Capabilities include:

• QUBO ↔ Ising validation
• Binary Quadratic Model solving
• simulated annealing
• exact solver for small problems
• logical solution decoding

Uses dimod when available.

---

Visualization

OpenQUBO includes tools for visualizing:

• QUBO problem graphs
• coupling graphs
• logical → physical mappings
• annealing embeddings

These visualizations help debug optimization problems and understand hardware constraints.

---

Installation

Clone the repository and install locally:

pip install -e .

Or install dependencies manually:

pip install -r requirements.txt

---

CLI Usage

After installation the CLI command becomes available:

openqubo --help

Example workflows:

openqubo gate ...

openqubo anneal ...

---

Python Usage

Example usage inside Python:

from openqubo import normalize_qubo

qubo = {
    (0,0): -1,
    (1,1): -1,
    (0,1): 2
}

normalized = normalize_qubo(qubo)

print(normalized.Q)

---

Project Structure

openqubo/
│
├── pyproject.toml
├── README.md
├── LICENSE
│
└── openqubo/
    ├── cli.py
    ├── qubo.py
    ├── gate.py
    ├── anneal.py
    ├── solver.py
    ├── viz.py
    ├── viz_gate.py
    ├── viz_anneal.py
    │
    └── compiler/
        ├── anneal_export.py
        └── gate_export.py

---

Citation

If you use OpenQUBO in research or publications, please cite:

Micah Shaw
OpenQUBO
SemperKite Quantum Labs
https://semperkite.io

Example BibTeX:

@software{openqubo_semperkite,
  author = {Micah Shaw},
  title = {OpenQUBO},
  institution = {SemperKite Quantum Labs},
  year = {2026},
  url = {https://semperkite.io}
}

---

License

MIT License
© 2026 Micah Shaw --- SemperKite Quantum Labs

See the LICENSE file for details.

---

About SemperKite Quantum Labs

SemperKite Quantum Labs develops open research software for quantum computing, optimization, and quantum simulation.

Learn more:

https://semperkite.io