Metadata-Version: 2.4
Name: openqubo
Version: 0.1.0
Summary: OpenQUBO: QUBO analysis, compilation, visualization, and solver pipelines
Author-email: Micah Shaw <dogpup3@semperkite.io>
Project-URL: Homepage, https://semperkite.io
Keywords: qubo,quantum,optimization,annealing,qiskit,dwave
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: networkx>=3.0
Requires-Dist: matplotlib>=3.8
Requires-Dist: qiskit>=1.0
Provides-Extra: solve
Requires-Dist: dimod>=0.12; extra == "solve"
Provides-Extra: anneal
Requires-Dist: minorminer>=0.2.12; extra == "anneal"
Provides-Extra: dev
Requires-Dist: build>=1.2.1; extra == "dev"
Requires-Dist: twine>=5.1.1; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Provides-Extra: full
Requires-Dist: dimod>=0.12; extra == "full"
Requires-Dist: minorminer>=0.2.12; extra == "full"
Dynamic: license-file

# 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
