<p align="center">
<a href="https://doi.org/10.5281/zenodo.10877157"><img title="DOI" alt="DOI" src="https://zenodo.org/badge/DOI/10.5281/zenodo.8029028.svg">
<a href="https://qunfold.readthedocs.io/en/latest/"><img title="docs" alt="docs" src="https://readthedocs.org/projects/qunfold/badge/?version=latest"></br>
<img title="version" alt="version" src="https://img.shields.io/badge/version-v0.3-informational?color=red">
<img title="license" alt="license" src="https://img.shields.io/badge/license-MIT-informational?color=red">
<img title="python" alt="python" src="https://img.shields.io/badge/python-≥3.9-informational?color=red">
<a href="https://skillicons.dev">
<img src="https://skillicons.dev/icons?i=linux,anaconda,docker" width="80px;"/>
</p>
## Table of contents
- [Introduction](#introduction)
- [Documentation](#documentation)
- [Installation](#installation)
- [User-mode](#user-mode)
- [Dev-mode](#dev-mode)
- [Docker container](#docker-container)
- [Usage example](#usage-example)
- [Unfolding studies](#unfolding-studies)
- [HEP dependencies](#hep-dependencies)
- [Performance analysis](#performance-analysis)
- [Main developers](#main-developers)
- [Other contributors](#other-contributors)
## Introduction
This package provides a quantum-based approach to the *statistical unfolding* problem in High-Energy Physics (HEP). The technique is based on the reformulation of this task as a [Quadratic Unconstrained Binary Optimization](https://en.wikipedia.org/wiki/Quadratic_unconstrained_binary_optimization) (QUBO) problem to be solved by [Quantum Annealing](https://en.wikipedia.org/wiki/Quantum_annealing) (QA) on [D-Wave](https://www.dwavesys.com/) quantum devices.
The code is written in Python and relies on [`numpy`](https://numpy.org/) arrays as basic data structures. However, the package also includes simple tools to convert [`ROOT`](https://root.cern/) data to `numpy`, allowing HEP scientists to run the algorithms for their specific use-cases with a minimal effort.
The software is designed leveraging the powerful [D-Wave Ocean SDK](https://docs.ocean.dwavesys.com/en/stable/), which provides several tools to define the QUBO model and run widely-used heuristics for classical computers (e.g. Simulated Annealing) as well as hybrid/quantum solvers running on real QA [D-Wave Systems](https://docs.dwavesys.com/docs/latest/).
The idea for this project was inspired by the work done by K. Cormier, R. Di Sipio, and P. Wittek in 2019 (see [here](https://www.dwavesys.com/resources/application/unfolding-measurement-distributions-in-high-energy-physics-experiments-via-quantum-annealing/) for the links to an oral presentation and the published paper).
:warning: For a comprehensive introduction to the classical problem, see Chapter 11 of the book [*Statistical Data Analysis*](https://academic.oup.com/book/54868) by G. Cowan.
## Documentation
###### (work in progress...)
[Read the Docs](https://qunfold.readthedocs.io/en/latest/): API documentation for all the available features of the package.
## Installation
### *User-mode*
To install the `QUnfold` latest version released on [PyPI](https://pypi.org/project/QUnfold/) in user-mode you can do:
```shell
pip install QUnfold
```
If you also want to enable the classical [Gurobi](https://www.gurobi.com/) solver both for the integer optimization problem and the QUBO problem, you need to install `QUnfold` including this additional requirement:
```shell
pip install QUnfold[gurobi]
```
### *Dev-mode*
To create a dedicated [`conda`](https://docs.conda.io/en/latest/) environment and install `QUnfold` in developer-mode you can do:
```shell
conda create --name qunfold-dev python==3.10.14
conda activate qunfold-dev
git clone https://github.com/Quantum4HEP/QUnfold.git
cd QUnfold
pip install --upgrade -r requirements-dev.txt
pip install -e .[gurobi]
```
### *Docker container*
Two different Docker images are ready to be downloaded from DockerHub to start playing with a containerized version of `QUnfold`:
- [`qunfold`](https://hub.docker.com/r/marcolorusso/qunfold/tags): minimal working version for testing basic functionalities
- [`qunfold-dev`](https://hub.docker.com/r/marcolorusso/qunfold-dev/tags): full version based on the `conda` distribution for Python, including the installation of `ROOT` framework and `RooUnfold` library for expert users in High-Energy Physics
Both the containerized solutions offer the possibility to use `QUnfold` running a JupyterLab web-based environment on your favourite browser. First, run the Docker container with the porting option as follows:
```docker
docker run -itp 8888:8888 qunfold
```
Secondly, once the container has started, launch `jupyter-lab` with the following command:
```shell
jupyter-lab --ip=0.0.0.0
```
## Usage example
Here is a minimal example showing how to use `QUnfold`. The code snippet shows how to create an instance of the unfolder class, initialize the QUBO model, and run the simulated annealing algorithm to solve the problem.
```python
from qunfold import QUnfolder
# Define your input response matrix and measured histogram as numpy arrays
response = ...
measured = ...
binning = ...
# Create the QUnfolder object and initialize the QUBO model
unfolder = QUnfolder(response, measured, binning, lam=0.1)
unfolder.initialize_qubo_model()
# Run one of the available solvers to get the unfolding result
sol, cov = unfolder.solve_simulated_annealing(num_reads=100)
```
The figures show a specific example of a given response matrix as well as the correponding histograms for the case of a *gamma* distribution with Gaussian smearing.
<p align="center">
<img src="https://github.com/Quantum4HEP/QUnfold/blob/main/examples/simneal_response.png" style="width: 45%;">
<img src="https://github.com/Quantum4HEP/QUnfold/blob/main/examples/simneal_result.png" style="width: 45%;">
</p>
If you are working in High-Energy Physics, your response matrix might be a `RooUnfoldResponse` object and your measured histogram is probably stored in a `ROOT.TH1`.
The `qunfold.root2numpy` module provides some simple functions to convert these objects to standard numpy arrays:
```python
from qunfold.root2numpy import TH1_to_numpy, TH2_to_numpy
# Convert ROOT.TH1 measured histogram to numpy array
measured = TH1_to_numpy(measured)
# Convert RooUnfoldResponse object to numpy array
response = TH2_to_numpy(response.Hresponse())
```
For a complete example on how to run the `QUnfold` solvers and plot the final results, you can take a look at the [examples](https://github.com/Quantum4HEP/QUnfold/tree/main/examples) directory in the repository.
## Unfolding studies
This section contains instructions to solve the unfolding problem by classical methods (widely used in HEP data analysis) as well as the `QUnfold` quantum-based method. It also provides several tools and examples to compare the results of the two different approaches.
### HEP dependencies
To run the classical unfolding algorithms you need to install the `ROOT` framework developed by CERN (see documentation [here](https://root.cern/doc/v628/)) and the specialized `RooUnfold` library (see documentation [here](http://roounfold.web.cern.ch/index.html)).
On Linux or Mac OS this can be done automatically by running the following script in the root directory of the repository:
```shell
./install_roounfold.sh
```
This step can be ignored if you are using the `qunfold-dev` Docker container since the corresponding Docker image already includes the required HEP software.
### Performance analysis
The code available in the [studies](https://github.com/Quantum4HEP/QUnfold/tree/main/studies) directory can be used to generate syntetic data samples according to common HEP probability density functions (*normal*, *gamma*, *exponential*, *Breit-Wigner*, *double-peaked*) and apply a smearing to roughly simulate the distortion effects due to limited efficiency, acceptance, and space/time resolution of a given detector.
Then, unfolding is performed by several classical, hybrid, and quantum techniques and the results are studied to compare the performance of the different methods.
In particular, the algorithms currently available are the following:
- `RooUnfold` framework:
- Matrix Inversion unfolding (MI)
- Bin-by-Bin unfolding (B2B)
- Iterative Bayesian Unfolding (IBU)
- Tikhonov regularized unfolding (SVD)
- `QUnfold` library:
- [D-Wave Simulated Annealing](https://docs.ocean.dwavesys.com/en/stable/docs_samplers/reference.html#simulated-annealing) (SA) for QUBO unfolding
- [D-Wave Hybrid solver](https://docs.ocean.dwavesys.com/en/stable/docs_system/reference/samplers.html#leaphybridsampler) (HYB) for QUBO unfolding
- [D-Wave Quantum Annealing](https://docs.ocean.dwavesys.com/en/stable/docs_system/reference/samplers.html#dwavesampler) (QA) for QUBO unfolding
- `Gurobi` solver for integer optimization formulation of the unfolding problem
- `Gurobi` solver for QUBO unfolding problem
:warning: The HYB and QA solvers require access to a real D-Wave quantum annealer (1 min/month available for free via the [D-Wave Leap](https://cloud.dwavesys.com/leap/login/) cloud platform) while the Gurobi solvers (Python API) require a software license (freely available for 18 months).
***
### Main developers
<table>
<tr>
<td align="center"><a href="https://justwhit3.github.io/"><img src="https://avatars.githubusercontent.com/u/48323961?v=4" width="100px;" alt=""/><br /><sub><b>Gianluca Bianco</b></sub></a></td>
<td align="center"><a href="https://github.com/SimoneGasperini"><img src="https://avatars2.githubusercontent.com/u/71086758?s=400&v=4" width="100px;" alt=""/><br /><sub><b>Simone Gasperini</b></sub></a></td>
</tr>
</table>
### Other contributors
<table>
<tr>
<td align="center"><a href="https://github.com/DrWatt"><img src="https://avatars.githubusercontent.com/u/33673848?v=4" width="60px;" alt=""/><br /><sub><b>Marco Lorusso</b></sub></a></td>
</tr>
</table>
Raw data
{
"_id": null,
"home_page": null,
"name": "QUnfold",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "quantum, annealing, unfolding, statistics, python",
"author": null,
"author_email": "Gianluca Bianco <biancogianluca9@gmail.com>, Simone Gasperini <simone.gasperini4@unibo.it>",
"download_url": "https://files.pythonhosted.org/packages/55/92/2c78bf3f8218336fa7b7974105007519c692d869f5ffa6ec4f1710e701ce/qunfold-0.3.5.tar.gz",
"platform": null,
"description": "\n\n<p align=\"center\">\n\t<a href=\"https://doi.org/10.5281/zenodo.10877157\"><img title=\"DOI\" alt=\"DOI\" src=\"https://zenodo.org/badge/DOI/10.5281/zenodo.8029028.svg\">\n <a href=\"https://qunfold.readthedocs.io/en/latest/\"><img title=\"docs\" alt=\"docs\" src=\"https://readthedocs.org/projects/qunfold/badge/?version=latest\"></br>\n <img title=\"version\" alt=\"version\" src=\"https://img.shields.io/badge/version-v0.3-informational?color=red\">\n <img title=\"license\" alt=\"license\" src=\"https://img.shields.io/badge/license-MIT-informational?color=red\">\n\t<img title=\"python\" alt=\"python\" src=\"https://img.shields.io/badge/python-\u22653.9-informational?color=red\">\n <a href=\"https://skillicons.dev\">\n <img src=\"https://skillicons.dev/icons?i=linux,anaconda,docker\" width=\"80px;\"/>\n</p>\n\n## Table of contents\n- [Introduction](#introduction)\n- [Documentation](#documentation)\n- [Installation](#installation)\n - [User-mode](#user-mode)\n - [Dev-mode](#dev-mode)\n - [Docker container](#docker-container)\n- [Usage example](#usage-example)\n- [Unfolding studies](#unfolding-studies)\n - [HEP dependencies](#hep-dependencies)\n - [Performance analysis](#performance-analysis)\n- [Main developers](#main-developers)\n- [Other contributors](#other-contributors)\n\n## Introduction\nThis package provides a quantum-based approach to the *statistical unfolding* problem in High-Energy Physics (HEP). The technique is based on the reformulation of this task as a [Quadratic Unconstrained Binary Optimization](https://en.wikipedia.org/wiki/Quadratic_unconstrained_binary_optimization) (QUBO) problem to be solved by [Quantum Annealing](https://en.wikipedia.org/wiki/Quantum_annealing) (QA) on [D-Wave](https://www.dwavesys.com/) quantum devices.\n\nThe code is written in Python and relies on [`numpy`](https://numpy.org/) arrays as basic data structures. However, the package also includes simple tools to convert [`ROOT`](https://root.cern/) data to `numpy`, allowing HEP scientists to run the algorithms for their specific use-cases with a minimal effort.\nThe software is designed leveraging the powerful [D-Wave Ocean SDK](https://docs.ocean.dwavesys.com/en/stable/), which provides several tools to define the QUBO model and run widely-used heuristics for classical computers (e.g. Simulated Annealing) as well as hybrid/quantum solvers running on real QA [D-Wave Systems](https://docs.dwavesys.com/docs/latest/).\n\nThe idea for this project was inspired by the work done by K. Cormier, R. Di Sipio, and P. Wittek in 2019 (see [here](https://www.dwavesys.com/resources/application/unfolding-measurement-distributions-in-high-energy-physics-experiments-via-quantum-annealing/) for the links to an oral presentation and the published paper).\n\n:warning: For a comprehensive introduction to the classical problem, see Chapter 11 of the book [*Statistical Data Analysis*](https://academic.oup.com/book/54868) by G. Cowan.\n\n## Documentation\n###### (work in progress...)\n[Read the Docs](https://qunfold.readthedocs.io/en/latest/): API documentation for all the available features of the package.\n\n## Installation\n### *User-mode*\nTo install the `QUnfold` latest version released on [PyPI](https://pypi.org/project/QUnfold/) in user-mode you can do:\n```shell\npip install QUnfold\n```\n\nIf you also want to enable the classical [Gurobi](https://www.gurobi.com/) solver both for the integer optimization problem and the QUBO problem, you need to install `QUnfold` including this additional requirement:\n```shell\npip install QUnfold[gurobi]\n```\n\n### *Dev-mode*\nTo create a dedicated [`conda`](https://docs.conda.io/en/latest/) environment and install `QUnfold` in developer-mode you can do:\n```shell\nconda create --name qunfold-dev python==3.10.14\nconda activate qunfold-dev\ngit clone https://github.com/Quantum4HEP/QUnfold.git\ncd QUnfold\npip install --upgrade -r requirements-dev.txt\npip install -e .[gurobi]\n```\n\n### *Docker container*\nTwo different Docker images are ready to be downloaded from DockerHub to start playing with a containerized version of `QUnfold`:\n- [`qunfold`](https://hub.docker.com/r/marcolorusso/qunfold/tags): minimal working version for testing basic functionalities\n- [`qunfold-dev`](https://hub.docker.com/r/marcolorusso/qunfold-dev/tags): full version based on the `conda` distribution for Python, including the installation of `ROOT` framework and `RooUnfold` library for expert users in High-Energy Physics\n\nBoth the containerized solutions offer the possibility to use `QUnfold` running a JupyterLab web-based environment on your favourite browser. First, run the Docker container with the porting option as follows:\n```docker\ndocker run -itp 8888:8888 qunfold\n```\nSecondly, once the container has started, launch `jupyter-lab` with the following command:\n```shell\njupyter-lab --ip=0.0.0.0\n```\n\n## Usage example\nHere is a minimal example showing how to use `QUnfold`. The code snippet shows how to create an instance of the unfolder class, initialize the QUBO model, and run the simulated annealing algorithm to solve the problem.\n```python\nfrom qunfold import QUnfolder\n\n# Define your input response matrix and measured histogram as numpy arrays\nresponse = ...\nmeasured = ...\nbinning = ...\n\n# Create the QUnfolder object and initialize the QUBO model\nunfolder = QUnfolder(response, measured, binning, lam=0.1)\nunfolder.initialize_qubo_model()\n\n# Run one of the available solvers to get the unfolding result\nsol, cov = unfolder.solve_simulated_annealing(num_reads=100)\n```\n\nThe figures show a specific example of a given response matrix as well as the correponding histograms for the case of a *gamma* distribution with Gaussian smearing.\n<p align=\"center\">\n <img src=\"https://github.com/Quantum4HEP/QUnfold/blob/main/examples/simneal_response.png\" style=\"width: 45%;\">\n <img src=\"https://github.com/Quantum4HEP/QUnfold/blob/main/examples/simneal_result.png\" style=\"width: 45%;\">\n</p>\n\nIf you are working in High-Energy Physics, your response matrix might be a `RooUnfoldResponse` object and your measured histogram is probably stored in a `ROOT.TH1`.\nThe `qunfold.root2numpy` module provides some simple functions to convert these objects to standard numpy arrays:\n```python\nfrom qunfold.root2numpy import TH1_to_numpy, TH2_to_numpy\n\n# Convert ROOT.TH1 measured histogram to numpy array\nmeasured = TH1_to_numpy(measured)\n\n# Convert RooUnfoldResponse object to numpy array\nresponse = TH2_to_numpy(response.Hresponse())\n```\n\nFor a complete example on how to run the `QUnfold` solvers and plot the final results, you can take a look at the [examples](https://github.com/Quantum4HEP/QUnfold/tree/main/examples) directory in the repository.\n\n## Unfolding studies\nThis section contains instructions to solve the unfolding problem by classical methods (widely used in HEP data analysis) as well as the `QUnfold` quantum-based method. It also provides several tools and examples to compare the results of the two different approaches.\n\n### HEP dependencies\nTo run the classical unfolding algorithms you need to install the `ROOT` framework developed by CERN (see documentation [here](https://root.cern/doc/v628/)) and the specialized `RooUnfold` library (see documentation [here](http://roounfold.web.cern.ch/index.html)).\nOn Linux or Mac OS this can be done automatically by running the following script in the root directory of the repository:\n```shell\n./install_roounfold.sh\n```\nThis step can be ignored if you are using the `qunfold-dev` Docker container since the corresponding Docker image already includes the required HEP software.\n\n### Performance analysis\nThe code available in the [studies](https://github.com/Quantum4HEP/QUnfold/tree/main/studies) directory can be used to generate syntetic data samples according to common HEP probability density functions (*normal*, *gamma*, *exponential*, *Breit-Wigner*, *double-peaked*) and apply a smearing to roughly simulate the distortion effects due to limited efficiency, acceptance, and space/time resolution of a given detector.\n\nThen, unfolding is performed by several classical, hybrid, and quantum techniques and the results are studied to compare the performance of the different methods.\nIn particular, the algorithms currently available are the following:\n- `RooUnfold` framework:\n - Matrix Inversion unfolding (MI)\n - Bin-by-Bin unfolding (B2B) \n - Iterative Bayesian Unfolding (IBU)\n - Tikhonov regularized unfolding (SVD)\n- `QUnfold` library:\n - [D-Wave Simulated Annealing](https://docs.ocean.dwavesys.com/en/stable/docs_samplers/reference.html#simulated-annealing) (SA) for QUBO unfolding\n - [D-Wave Hybrid solver](https://docs.ocean.dwavesys.com/en/stable/docs_system/reference/samplers.html#leaphybridsampler) (HYB) for QUBO unfolding\n - [D-Wave Quantum Annealing](https://docs.ocean.dwavesys.com/en/stable/docs_system/reference/samplers.html#dwavesampler) (QA) for QUBO unfolding\n - `Gurobi` solver for integer optimization formulation of the unfolding problem\n - `Gurobi` solver for QUBO unfolding problem\n\n:warning: The HYB and QA solvers require access to a real D-Wave quantum annealer (1 min/month available for free via the [D-Wave Leap](https://cloud.dwavesys.com/leap/login/) cloud platform) while the Gurobi solvers (Python API) require a software license (freely available for 18 months).\n\n***\n\n### Main developers\n<table>\n <tr>\n <td align=\"center\"><a href=\"https://justwhit3.github.io/\"><img src=\"https://avatars.githubusercontent.com/u/48323961?v=4\" width=\"100px;\" alt=\"\"/><br /><sub><b>Gianluca Bianco</b></sub></a></td>\n <td align=\"center\"><a href=\"https://github.com/SimoneGasperini\"><img src=\"https://avatars2.githubusercontent.com/u/71086758?s=400&v=4\" width=\"100px;\" alt=\"\"/><br /><sub><b>Simone Gasperini</b></sub></a></td>\n </tr>\n</table>\n\n### Other contributors\n<table>\n <tr>\n <td align=\"center\"><a href=\"https://github.com/DrWatt\"><img src=\"https://avatars.githubusercontent.com/u/33673848?v=4\" width=\"60px;\" alt=\"\"/><br /><sub><b>Marco Lorusso</b></sub></a></td>\n </tr>\n</table>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A quantum-based approach to the distribution unfolding problem",
"version": "0.3.5",
"project_urls": {
"Documentation": "https://qunfold.readthedocs.io/en/latest/",
"Homepage": "https://github.com/Quantum4HEP/QUnfold"
},
"split_keywords": [
"quantum",
" annealing",
" unfolding",
" statistics",
" python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "69ccd9ba6429a24014dd7d6a6b45d952d04c3578018be55bd7d61d7a6c2411b0",
"md5": "5702cbe89cbd3ecc765469e9ffb8530f",
"sha256": "25c7d07b283eda5a0b7f3ea82ec96ee59e21e1c3d8ba641a7124b21d69be7486"
},
"downloads": -1,
"filename": "QUnfold-0.3.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5702cbe89cbd3ecc765469e9ffb8530f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 12821,
"upload_time": "2024-09-20T20:03:50",
"upload_time_iso_8601": "2024-09-20T20:03:50.107783Z",
"url": "https://files.pythonhosted.org/packages/69/cc/d9ba6429a24014dd7d6a6b45d952d04c3578018be55bd7d61d7a6c2411b0/QUnfold-0.3.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "55922c78bf3f8218336fa7b7974105007519c692d869f5ffa6ec4f1710e701ce",
"md5": "477d5a20b27bb8f8f3b258e4083a22e7",
"sha256": "19cf8d06b861a55dca0851fff1aa3d13859a43ba875e3a440d8f71a759128df1"
},
"downloads": -1,
"filename": "qunfold-0.3.5.tar.gz",
"has_sig": false,
"md5_digest": "477d5a20b27bb8f8f3b258e4083a22e7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 12831,
"upload_time": "2024-09-20T20:03:51",
"upload_time_iso_8601": "2024-09-20T20:03:51.090641Z",
"url": "https://files.pythonhosted.org/packages/55/92/2c78bf3f8218336fa7b7974105007519c692d869f5ffa6ec4f1710e701ce/qunfold-0.3.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-20 20:03:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Quantum4HEP",
"github_project": "QUnfold",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": []
},
{
"name": "scipy",
"specs": []
},
{
"name": "jax",
"specs": []
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "dwave-ocean-sdk",
"specs": []
},
{
"name": "scikit-learn",
"specs": []
},
{
"name": "tqdm",
"specs": []
}
],
"lcname": "qunfold"
}
JSON
