quboify

quboify is an open-source Python package for constructing Quadratic Unconstrained Binary Optimization (QUBO) models from symbolic expressions while preserving symbolic parameters.

The primary use case of quboify is to take a SymPy model, and convert it into QUBO form with a qubovert data structure while maintaining the symbolic expressions such that late-stage adjustments of parameters is possible.

quboify offers only limited links to existing quantum optimization solvers. As these solvers are expected to develop and change in the future, this toolkit offers an extendable solver-independent interface.

quboify was developed at the Institute of Energy Systems Engineering (ICE-1) at Forschungszentrum Jülich GmbH, Germany.

Getting Started

Installation

The authors recommend installation using Pixi:

pixi add quboify

Alternatively from PyPI:

pip install quboify

The core package builds and modifies QUBOs without any solver installed. To run the built-in solver backends (used by the example below via solve_simulated_annealing()), install the optional solvers extra, which pulls in the D-Wave and Gurobi dependencies:

pip install "quboify[solvers]"

Usage

The following example showcases quboify's main additions over mqt-qao: the preservation of symbolic variables and parameters. It supports variable names containing characters such as - (see a-0-0) and allows parameter modification without reconstructing the QUBO (see p).

from quboify import Constraints, ObjectiveFunctions, Problem, Solver, Symbols

variables = Symbols()
constraints = Constraints()
obj_func = ObjectiveFunctions()

a = variables.add_binary_variable("a-0-0")
b = variables.add_discrete_variable("b", [-1, 1, 3])
c = variables.add_continuous_variable("c", -2, 2, 0.25)
p = variables.add_parameter("p")

constraints.add_constraint(variables.encoding_constraints)
constraints.add_constraint("b + c >= 2", variable_precision=True)

obj_func.add_objective_function(a*p + b*c*p + c**2)

problem = Problem(variables, constraints, obj_func)

solver = Solver(problem)

problem.set_parameters({"p": 2})
solutions = solver.solve_simulated_annealing()
print(f"Best solution: {solutions.best_solution}")
print(f"with objective function value: {solutions.best_solution_objective_values}")

problem.set_parameters({"p": -1})
solutions = solver.solve_simulated_annealing()
print(f"Best solution: {solutions.best_solution}")
print(f"with objective function value: {solutions.best_solution_objective_values}")

Contributing

If you wish to contribute to quboify by creating Work Items (Issues) or Merge Requests (Pull Requests), you can login with your Google, Github or ORCID accounts using the "Helmholtz AAI" login option.

Referencing

In case you are using quboify in your work, we would be thankful if you referred to it by citing the following publication (also found in paper/paper.md):

to be published

Acknowledgements

The project originated as a fork of mqt-qao. The authors acknowledge the original developers for establishing the foundational concepts on which quboify builds.

The code and paper for this project were written as part of the project “Quantum-based Energy Grids (QuGrids)”, which is receiving funding from the programme “Profilbildung 2022”, an initiative of the Ministry of Culture and Science of the State of North Rhine-Westphalia.