Metadata-Version: 2.1
Name: qdd-mpi
Version: 0.3.2
Summary: Qiskit Provider for QDD
Author-Email: Yusuke Kimura <yusuke-kimura@fujitsu.com>
License: Copyright (c) 2022-2023 Fujitsu Limited and Li Shaowen
         All rights reserved.
         
         Redistribution and use in source and binary forms, with or without modification, are permitted (subject to the limitations in the disclaimer below) provided that the following conditions are met:
         
         * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
         * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
         * Neither the name of Fujitsu Limited nor Li Shaowen nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
         NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Project-URL: Homepage, https://github.com/Fujitsu-UTokyo-QDD/QDD
Project-URL: Documentation, https://fujitsu-utokyo-qdd.github.io/QDD/
Project-URL: Repository, https://github.com/Fujitsu-UTokyo-QDD/QDD
Project-URL: Issues, https://github.com/Fujitsu-UTokyo-QDD/QDD/issues
Requires-Python: >=3.9
Requires-Dist: qiskit~=2.2.0
Provides-Extra: test
Requires-Dist: pytest>=7.2.2; extra == "test"
Requires-Dist: qiskit-aer>=0.13.3; extra == "test"
Requires-Dist: scipy>=1.10; extra == "test"
Requires-Dist: qiskit-algorithms>=0.3; extra == "test"
Requires-Dist: qiskit-nature>=0.7; extra == "test"
Requires-Dist: pyscf>=2.4; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx>=7.4; extra == "docs"
Requires-Dist: myst-parser>=4.0; extra == "docs"
Requires-Dist: breathe>=4.35; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
Description-Content-Type: text/markdown

[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://fujitsu-utokyo-qdd.github.io/QDD/)

# QDD
[Documentation](https://fujitsu-utokyo-qdd.github.io/QDD/) is available on GitHub Pages.

QDD is a decision diagram based quantum computing simulator for Qiskit. It can
reduce memory usage compared with typical state-vector simulators when the
decision diagram representation remains compact.

## Installation

Install QDD from PyPI:

```sh
pip install qdd
```

Supported environment:

- Linux x86_64 and aarch64
- Python 3.9 through 3.13

## Quick Start

QDD works as a Qiskit backend.

```python
from qiskit import QuantumCircuit

from qdd import QddProvider

backend = QddProvider().get_backend("qasm_simulator")

circuit = QuantumCircuit(3)
circuit.h(0)
circuit.cx(0, 1)
circuit.measure_all()

job = backend.run(circuit, shots=1024, seed_simulator=1234)
print(job.result().get_counts())
```

For statevector simulation:

```python
from qiskit import QuantumCircuit

from qdd import QddProvider

backend = QddProvider().get_backend("statevector_simulator")

circuit = QuantumCircuit(2)
circuit.h(0)
circuit.cx(0, 1)

statevector = backend.run(circuit).result().get_statevector()
print(statevector)
```

## MPI Usage

MPI support is optional. Use the MPI-enabled `qdd-mpi` distribution only when
you want to run QDD across MPI ranks.

The `qdd` and `qdd-mpi` distributions provide the same `import qdd` Python
package namespace. Do not install both in the same environment.

Install the MPI-enabled package from PyPI:

```sh
pip install mpi4py
CC=mpicc CXX=mpicxx pip install qdd-mpi --no-binary qdd-mpi
```

Minimal MPI run with Qiskit:

```python
# mpi_bell.py
from mpi4py import MPI
from qiskit import QuantumCircuit

from qdd import QddProvider

backend = QddProvider().get_backend("qasm_simulator")
backend.set_options(use_mpi=True)

circuit = QuantumCircuit(3)
circuit.h(0)
circuit.cx(0, 1)
circuit.cx(1, 2)
circuit.measure_all()

result = backend.run(circuit, shots=1024).result()
if MPI.COMM_WORLD.Get_rank() == 0:
    print(result.get_counts())
```

Run the script under MPI:

```sh
mpirun -n 2 python mpi_bell.py
```

You can also pass `use_mpi=True` per run, or through QDD primitive backend
options such as `Sampler(backend_options={"use_mpi": True})` and
`Estimator(backend_options={"use_mpi": True})`.

## Documentation

Full documentation, including source builds, testing, MPI usage, and Python/C++
API references, is published with GitHub Pages:

https://fujitsu-utokyo-qdd.github.io/QDD/

The documentation source is in `docs/source`.

## Citation

If you use QDD in academic work, please cite:

- "Accelerating Decision Diagram-based Multi-node Quantum Simulation with Ring
  Communication and Automatic SWAP Insertion," IEEE QSW 2024: [10.1109/QSW62656.2024.00025](https://doi.org/10.1109/QSW62656.2024.00025)

Additional references:

- "Variable ordering and multi-node ring communication", IEEE TQE:
  [10.1109/TQE.2026.3654543](https://doi.org/10.1109/TQE.2026.3654543)
- Decision-diagram and state-vector simulator characteristics, IEEE QCE 2024:
  [10.1109/QCE60285.2024.00095](https://doi.org/10.1109/QCE60285.2024.00095)

## License

BSD 3-Clause Clear License

## Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
