| Name | qubolite JSON |
| Version |
0.8.5
JSON |
| download |
| home_page | |
| Summary | Toolbox for quadratic binary optimization |
| upload_time | 2023-10-23 15:38:21 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | |
| keywords |
qubo
optimization
quantum
annealing
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# qubolite
A light-weight toolbox for working with QUBO instances in NumPy.
<img src="qubolite.png" width="100" height="100">
## Installation
```
pip install qubolite
```
This package was created using Python 3.10, but runs with Python >= 3.8.
## Optional Dependencies
If 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 calling
`qubolite.bounds.lb_roof_dual()`. It requires that the [igraph](https://igraph.org/) library is
installed. This can be done with `pip install igraph` or by installing qubolite with
`pip install qubolite[roof_dual]`.
Using the function `qubolite.ordering_distance()` requires the Kendall-τ measure from the
[scipy](https://scipy.org/) library which can be installed by `pip install scipy` or by installing
qubolite with `pip install qubolite[kendall_tau]`.
For exemplary QUBO embeddings (e.g. clustering or subset sum), the
[scikit-learn](https://scikit-learn.org/) library is required. It can be installed by either using
`pip install scikit-learn` or installing qubolite with `pip install qubolite[embeddings]`.
If you would like to install all optional dependencies you can use `pip install qubolite[all]` for
achieving this.
## Usage Examples
By design, `qubolite` is a shallow wrapper around `numpy` arrays, which represent QUBO parameters.
The core class is `qubo`, which receives a `numpy.ndarray` of size `(n, n)`.
Alternatively, a random instance can be created using `qubo.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 a `numpy.ndarray` of 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])
```
### Solving
The submodule `solving` contains 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.394893116198653
```
The method `brute_force` is implemented efficiently in C and parallelized with OpenMP.
Still, for instances with more than 30 variables take a long time to solve this way.
## Documentation
The complete API documentation can be found [here](https://smuecke.github.io/qubolite/api.html).
## Version Log
* **0.2** Added problem embeddings (binary clustering, subset sum problem)
* **0.3** Added `QUBOSample` class and sampling methods `full` and `gibbs`
* **0.4** Renamed `QUBOSample` to `BinarySample`; added methods for saving and loading QUBO and Sample instances
* **0.5** Moved `gibbs` to `mcmc` and implemented true Gibbs sampling as `gibbs`; added `numba` as dependency
* **0.5.1** changed `keep_prob` to `keep_interval` in Gibbs sampling, making the algorithm's runtime deterministic; renamed `sample` to `random` in QUBO embedding classes, added MAX 2-SAT problem embedding
* **0.6** Changed Python version to 3.8; removed `bitvec` dependency; added `scipy` dependency required for matrix operations in numba functions
* **0.6.1** added scaling and rounding
* **0.6.2** removed `seedpy` dependency
* **0.6.3** renamed `shots` to `size` in `BinarySample`; cleaned up sampling, simplified type hints
* **0.6.4** added probabilistic functions to `qubo` class
* **0.6.5** complete empirical prob. vector can be returned from `BinarySample`
* **0.6.6** fixed spectral gap implementation
* **0.6.7** moved `brute_force` to new sub-module `solving`; added some approximate solving methods
* **0.6.8** added `bitvec` sub-module; `dynamic_range` now uses bits by default, changed `bits=False` to `decibel=False`; removed scipy from requirements
* **0.6.9** new, more memory-efficient save format
* **0.6.10** fixed requirements in `setup.py`; fixed size estimation in `qubo.save()`
* **0.7** Added more efficient brute-force implementation using C extension; added optional dependencies for calculating bounds and ordering distance
* **0.8** New embeddings, new solving methods; switched to NumPy random generators from `RandomState`; added parameter compression for dynamic range reduction; Added documentation
* **0.8.1** some fixes to documentation
* **0.8.2** implemented `qubo.dx2()`; added several new solving heuristics
* **0.8.3** added submodule `preprocessing` and moved DR reduction there; added `partial_assignment` class as replacement of `qubo.clamp()`, which is now deprecated
* **0.8.4** added fast Gibbs sampling and QUBO parameter training
Raw data
{
"_id": null,
"home_page": "",
"name": "qubolite",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "qubo,optimization,quantum,annealing",
"author": "",
"author_email": "Sascha M\u00fccke <sascha.muecke@tu-dortmund.de>, Thore Gerlach <thore.gerlach@iais.fraunhofer.de>, Nico Piatkowski <nico.piatkowski@iais.fraunhofer.de>",
"download_url": "https://files.pythonhosted.org/packages/db/f6/cd5720c91862d687a7ff66a56b7a0e2ac5a87d0a2f68d76b338704990acb/qubolite-0.8.5.tar.gz",
"platform": null,
"description": "# qubolite\n\nA light-weight toolbox for working with QUBO instances in NumPy.\n\n\n<img src=\"qubolite.png\" width=\"100\" height=\"100\">\n\n\n## Installation\n\n```\npip install qubolite\n```\n\nThis package was created using Python 3.10, but runs with Python >= 3.8.\n\n## Optional Dependencies\n\nIf you're planning to use the roof dual function as lower bound you will need to install optional\ndependencies. The igraph based roof dual lower bound function can be used by calling \n`qubolite.bounds.lb_roof_dual()`. It requires that the [igraph](https://igraph.org/) library is \ninstalled. This can be done with `pip install igraph` or by installing qubolite with \n`pip install qubolite[roof_dual]`.\n\nUsing the function `qubolite.ordering_distance()` requires the Kendall-\u03c4 measure from the\n[scipy](https://scipy.org/) library which can be installed by `pip install scipy` or by installing \nqubolite with `pip install qubolite[kendall_tau]`.\n\nFor exemplary QUBO embeddings (e.g. clustering or subset sum), the \n[scikit-learn](https://scikit-learn.org/) library is required. It can be installed by either using \n`pip install scikit-learn` or installing qubolite with `pip install qubolite[embeddings]`.\n\nIf you would like to install all optional dependencies you can use `pip install qubolite[all]` for\nachieving this.\n\n## Usage Examples\n\nBy design, `qubolite` is a shallow wrapper around `numpy` arrays, which represent QUBO parameters.\nThe core class is `qubo`, which receives a `numpy.ndarray` of size `(n, n)`.\nAlternatively, a random instance can be created using `qubo.random()`.\n\n```\n>>> import numpy as np\n>>> from qubolite import qubo\n>>> arr = np.triu(np.random.random((8, 8)))\n>>> Q = qubo(arr)\n>>> Q2 = qubo.random(12, distr='uniform')\n```\n\nBy default, `qubo()` takes an upper triangle matrix.\nA non-triangular matrix is converted to an upper triangle matrix by adding the lower to the upper triangle.\n\nTo get the QUBO function value, instances can be called directly with a bit vector.\nThe bit vector must be a `numpy.ndarray` of size `(n,)` or `(m, n)`.\n\n```\n>>> x = np.random.random(8) < 0.5\n>>> Q(x)\n7.488225478498116\n>>> xs = np.random.random((5,8)) < 0.5\n>>> Q(xs)\narray([5.81642745, 4.41380893, 11.3391062, 4.34253921, 6.07799747])\n```\n\n### Solving\n\nThe submodule `solving` contains several methods to obtain the minimizing bit vector or energy value of a given QUBO instance, both exact and approximative.\n\n```\n>>> from qubolite.solving import brute_force\n>>> x_min, value = brute_force(Q, return_value=True)\n>>> x_min\narray([1., 1., 1., 0., 1., 0., 0., 0.])\n>>> value\n-3.394893116198653\n```\n\nThe method `brute_force` is implemented efficiently in C and parallelized with OpenMP.\nStill, for instances with more than 30 variables take a long time to solve this way.\n\n## Documentation\n\nThe complete API documentation can be found [here](https://smuecke.github.io/qubolite/api.html).\n\n## Version Log\n\n* **0.2** Added problem embeddings (binary clustering, subset sum problem)\n* **0.3** Added `QUBOSample` class and sampling methods `full` and `gibbs`\n* **0.4** Renamed `QUBOSample` to `BinarySample`; added methods for saving and loading QUBO and Sample instances\n* **0.5** Moved `gibbs` to `mcmc` and implemented true Gibbs sampling as `gibbs`; added `numba` as dependency\n * **0.5.1** changed `keep_prob` to `keep_interval` in Gibbs sampling, making the algorithm's runtime deterministic; renamed `sample` to `random` in QUBO embedding classes, added MAX 2-SAT problem embedding\n* **0.6** Changed Python version to 3.8; removed `bitvec` dependency; added `scipy` dependency required for matrix operations in numba functions\n * **0.6.1** added scaling and rounding\n * **0.6.2** removed `seedpy` dependency\n * **0.6.3** renamed `shots` to `size` in `BinarySample`; cleaned up sampling, simplified type hints\n * **0.6.4** added probabilistic functions to `qubo` class\n * **0.6.5** complete empirical prob. vector can be returned from `BinarySample`\n * **0.6.6** fixed spectral gap implementation\n * **0.6.7** moved `brute_force` to new sub-module `solving`; added some approximate solving methods\n * **0.6.8** added `bitvec` sub-module; `dynamic_range` now uses bits by default, changed `bits=False` to `decibel=False`; removed scipy from requirements\n * **0.6.9** new, more memory-efficient save format\n * **0.6.10** fixed requirements in `setup.py`; fixed size estimation in `qubo.save()`\n* **0.7** Added more efficient brute-force implementation using C extension; added optional dependencies for calculating bounds and ordering distance\n* **0.8** New embeddings, new solving methods; switched to NumPy random generators from `RandomState`; added parameter compression for dynamic range reduction; Added documentation\n * **0.8.1** some fixes to documentation\n * **0.8.2** implemented `qubo.dx2()`; added several new solving heuristics\n * **0.8.3** added submodule `preprocessing` and moved DR reduction there; added `partial_assignment` class as replacement of `qubo.clamp()`, which is now deprecated\n * **0.8.4** added fast Gibbs sampling and QUBO parameter training\n",
"bugtrack_url": null,
"license": "",
"summary": "Toolbox for quadratic binary optimization",
"version": "0.8.5",
"project_urls": {
"Documentation": "https://smuecke.github.io/qubolite",
"Homepage": "https://github.com/smuecke/qubolite"
},
"split_keywords": [
"qubo",
"optimization",
"quantum",
"annealing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dbf6cd5720c91862d687a7ff66a56b7a0e2ac5a87d0a2f68d76b338704990acb",
"md5": "a57778195004abf216b5ea3e2717a644",
"sha256": "578b8c2294958a127ccd72becb1bce9b01df275d6c37f62a2d1d4301861b0d26"
},
"downloads": -1,
"filename": "qubolite-0.8.5.tar.gz",
"has_sig": false,
"md5_digest": "a57778195004abf216b5ea3e2717a644",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 45201,
"upload_time": "2023-10-23T15:38:21",
"upload_time_iso_8601": "2023-10-23T15:38:21.711079Z",
"url": "https://files.pythonhosted.org/packages/db/f6/cd5720c91862d687a7ff66a56b7a0e2ac5a87d0a2f68d76b338704990acb/qubolite-0.8.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-23 15:38:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "smuecke",
"github_project": "qubolite",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "qubolite"
}
