libQAOA

A small Python library for modeling binary linear programs (BLP) and converting them into QUBO/Ising formulations suitable for quantum or classical optimization workflows.

This repository provides lightweight symbolic representations for linear and quadratic functions, constraint systems, and utilities to convert binary linear programs into QUBO and Ising models.

Features

• Define linear and quadratic objective functions symbolically (classes: LinearFunction, QuadraticFunction).
• Represent linear inequality constraints via Constraint and ConstraintSystem.
• Build a BinaryLinearProgram (BLP) and convert it to a QUBO (and then to an Ising model).
• Compute energies for QUBO and Ising assignments and export QUBO matrices.

Quick example

The file src/main.py contains a small runnable example. It builds a linear objective, a couple of constraints, assembles a BinaryLinearProgram and converts it into a QUBO.

Equivalent snippet:

from functions import LinearFunction
from constraint import Constraint
from constraint_system import ConstraintSystem
from binary_linear_program import BinaryLinearProgram

obj = LinearFunction([-5, 3, -2])
c1 = Constraint(LinearFunction([1, 0, 1]), bound=1)
c2 = Constraint(LinearFunction([3, -1, 3]), bound=4)
system = ConstraintSystem([c1, c2])

blp = BinaryLinearProgram(objective=obj, constraints=system)
print(blp)

qubo = blp.to_qubo()
print(qubo)

From a QUBO instance you can:

• call qubo.to_matrix() to get (Q, constant, var_list)
• call qubo.qubo_energy(assignment) to evaluate an assignment where variables map to 0/1
• call qubo.to_ising() to convert to an Ising model and then ising.ising_energy(assignment) where variables map to -1/+1

Module overview (what's in src/)

• functions.py

  • LinearFunction: symbolic linear expressions. Supports construction from lists or dicts, evaluation, addition and multiplication, copy and equality.
  • QuadraticFunction: quadratic objectives with symmetric (var1, var2) pair keys. Supports addition, scalar multiplication, evaluation and conversion helpers.

• constraint.py

  • Constraint: represents a single linear inequality expression <= bound where expression is a LinearFunction.

• constraint_system.py

  • ConstraintSystem: a collection of Constraint objects. Builds a consistent variable ordering and matrix form (A, b). Supports evaluation helpers and conversion from matrix form.

• binary_linear_program.py

  • BinaryLinearProgram: ties an objective (LinearFunction) and a ConstraintSystem. Implements to_qubo() which encodes constraints using a tight slack-variable scheme and forms a penalized quadratic objective. Note: there is a TODO comment in the implementation—see the source for details.

• qubo.py

  • QUBO: wraps a QuadraticFunction objective and provides helpers:
    • variables(): ordered variable list
    • to_matrix(): converts the objective into an n×n symmetric Q matrix, constant and variable order
    • qubo_energy(assignment): compute energy of a 0/1 assignment
    • to_ising(): returns an Ising object (conversion derives h, J and adjusts constant)

• ising.py

  • Ising: wrapper around a QuadraticFunction intended for spins s_i ∈ {-1, +1}; provides ising_energy(assignment).

Usage notes & examples

• Building and evaluating a LinearFunction:

from functions import LinearFunction
f = LinearFunction({"x_0": 2.0, "x_1": -1.0}, constant=0.5)
val = f.evaluate({"x_0": 1, "x_1": 0})  # -> 2.5

• Converting a BinaryLinearProgram to a QUBO and evaluating a candidate solution:

# assume blp is BinaryLinearProgram
qubo = blp.to_qubo()
Q, const, var_list = qubo.to_matrix()
assign = {v: 0 for v in var_list}
energy = qubo.qubo_energy(assign)

• Converting a QUBO to Ising:

ising = qubo.to_ising()
# ising.objective is a QuadraticFunction; evaluate with s_i in {-1, +1}
e = ising.ising_energy({v: -1 for v in ising.objective.linear.coefficients.keys()})

Running tests

Unit tests live under tests/ and use the unittest framework. From the repository root run:

python -m unittest discover -v