Package: qubolite
quboliteA light-weight toolbox for working with QUBO instances in NumPy.Installationpip install quboliteThis package was created using Python 3.10, but runs with Python >= 3.8.Optional DependenciesIf you're planning to use the roof dual function as lower bound you will need to install optional
dependencies. The igraph based roof dual lower bound function can be used by callingqubolite.bounds.lb_roof_dual(). It requires that theigraphlibrary is
installed. This can be done withpip install igraphor by installing qubolite withpip install qubolite[roof_dual].Using the functionqubolite.ordering_distance()requires the Kendall-τ measure from thescipylibrary which can be installed bypip install scipyor by installing
qubolite withpip install qubolite[kendall_tau].For exemplary QUBO embeddings (e.g. clustering or subset sum), thescikit-learnlibrary is required. It can be installed by either usingpip install scikit-learnor installing qubolite withpip install qubolite[embeddings].If you would like to install all optional dependencies you can usepip install qubolite[all]for
achieving this.Usage ExamplesBy design,quboliteis a shallow wrapper aroundnumpyarrays, which represent QUBO parameters.
The core class isqubo, which receives anumpy.ndarrayof size(n, n).
Alternatively, a random instance can be created usingqubo.random().>>> import numpy as np
>>> from qubolite import qubo
>>> arr = np.triu(np.random.random((8, 8)))
>>> Q = qubo(arr)
>>> Q2 = qubo.random(12, distr='uniform')By default,qubo()takes an upper triangle matrix.
A non-triangular matrix is converted to an upper triangle matrix by adding the lower to the upper triangle.To get the QUBO function value, instances can be called directly with a bit vector.
The bit vector must be anumpy.ndarrayof size(n,)or(m, n).>>> x = np.random.random(8) < 0.5
>>> Q(x)
7.488225478498116
>>> xs = np.random.random((5,8)) < 0.5
>>> Q(xs)
array([5.81642745, 4.41380893, 11.3391062, 4.34253921, 6.07799747])SolvingThe submodulesolvingcontains several methods to obtain the minimizing bit vector or energy value of a given QUBO instance, both exact and approximative.>>> from qubolite.solving import brute_force
>>> x_min, value = brute_force(Q, return_value=True)
>>> x_min
array([1., 1., 1., 0., 1., 0., 0., 0.])
>>> value
-3.394893116198653The methodbrute_forceis implemented efficiently in C and parallelized with OpenMP.
Still, for instances with more than 30 variables take a long time to solve this way.DocumentationThe complete API documentation can be foundhere.Version Log0.2Added problem embeddings (binary clustering, subset sum problem)0.3AddedQUBOSampleclass and sampling methodsfullandgibbs0.4RenamedQUBOSampletoBinarySample; added methods for saving and loading QUBO and Sample instances0.5Movedgibbstomcmcand implemented true Gibbs sampling asgibbs; addednumbaas dependency0.5.1changedkeep_probtokeep_intervalin Gibbs sampling, making the algorithm's runtime deterministic; renamedsampletorandomin QUBO embedding classes, added MAX 2-SAT problem embedding0.6Changed Python version to 3.8; removedbitvecdependency; addedscipydependency required for matrix operations in numba functions0.6.1added scaling and rounding0.6.2removedseedpydependency0.6.3renamedshotstosizeinBinarySample; cleaned up sampling, simplified type hints0.6.4added probabilistic functions toquboclass0.6.5complete empirical prob. vector can be returned fromBinarySample0.6.6fixed spectral gap implementation0.6.7movedbrute_forceto new sub-modulesolving; added some approximate solving methods0.6.8addedbitvecsub-module;dynamic_rangenow uses bits by default, changedbits=Falsetodecibel=False; removed scipy from requirements0.6.9new, more memory-efficient save format0.6.10fixed requirements insetup.py; fixed size estimation inqubo.save()0.7Added more efficient brute-force implementation using C extension; added optional dependencies for calculating bounds and ordering distance0.8New embeddings, new solving methods; switched to NumPy random generators fromRandomState; added parameter compression for dynamic range reduction; Added documentation0.8.1some fixes to documentation0.8.2implementedqubo.dx2(); added several new solving heuristics0.8.3added submodulepreprocessingand moved DR reduction there; addedpartial_assignmentclass as replacement ofqubo.clamp(), which is now deprecated0.8.4added fast Gibbs sampling and QUBO parameter training