Metadata-Version: 2.4
Name: openqarp
Version: 0.1.1
Summary: Open Quantum Application Research Package
Keywords: quantum computing,quantum algorithms,quantum simulation,quantum chemistry,circuit compilation
License-Expression: Apache-2.0
License-File: LICENSE
License-File: LICENSES_bundled.txt
License-File: NOTICE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Project-URL: Homepage, https://github.com/OpenQARP/openqarp
Project-URL: Documentation, https://openqarp.github.io/openqarp/
Project-URL: Repository, https://github.com/OpenQARP/openqarp
Project-URL: Issues, https://github.com/OpenQARP/openqarp/issues
Project-URL: Changelog, https://github.com/OpenQARP/openqarp/blob/main/CHANGELOG.md
Requires-Python: >=3.11
Requires-Dist: ipython
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: sympy
Requires-Dist: networkx>=3.4.2
Provides-Extra: docs
Requires-Dist: sphinx==9.1.0; extra == "docs"
Requires-Dist: furo==2025.12.19; extra == "docs"
Requires-Dist: sphinx-copybutton==0.5.2; extra == "docs"
Provides-Extra: mps
Requires-Dist: quimb>=1.12.1; extra == "mps"
Requires-Dist: opt_einsum>=3.3; extra == "mps"
Provides-Extra: hypergraph
Requires-Dist: hypernetx>=2.4.0; extra == "hypergraph"
Requires-Dist: fastjsonschema>=2.21.0; extra == "hypergraph"
Requires-Dist: pandas<3; extra == "hypergraph"
Provides-Extra: convex-optim
Requires-Dist: cvxpy; extra == "convex-optim"
Provides-Extra: cliffordt
Requires-Dist: pygridsynth>=2.0; extra == "cliffordt"
Provides-Extra: openfermion
Requires-Dist: openfermion<1.8,>=1.7.1; extra == "openfermion"
Provides-Extra: cudaq-runtime
Requires-Dist: cuda-quantum-cu12>=0.9; extra == "cudaq-runtime"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: hypothesis>=6.100; extra == "test"
Requires-Dist: pytest-cov==7.1.0; extra == "test"
Requires-Dist: coverage==7.15.4; extra == "test"
Requires-Dist: diff-cover==10.5.0; extra == "test"
Requires-Dist: openfermion<1.8,>=1.7.1; extra == "test"
Provides-Extra: dev
Requires-Dist: ruff==0.15.22; extra == "dev"
Requires-Dist: mypy==1.19.1; extra == "dev"
Requires-Dist: pre-commit>=3.5; extra == "dev"
Provides-Extra: notebooks
Requires-Dist: nbmake==1.5.5; extra == "notebooks"
Requires-Dist: pymoo>=0.6.2; extra == "notebooks"
Requires-Dist: pyscf>=2.10; extra == "notebooks"
Requires-Dist: scikit-learn>=1.3; extra == "notebooks"
Provides-Extra: integrations
Requires-Dist: qiskit>=1.0; extra == "integrations"
Requires-Dist: qiskit-qasm3-import; extra == "integrations"
Requires-Dist: pytket; extra == "integrations"
Requires-Dist: pennylane>=0.36; extra == "integrations"
Requires-Dist: qulacs; extra == "integrations"
Requires-Dist: jax; extra == "integrations"
Provides-Extra: bench
Requires-Dist: qiskit-aer; extra == "bench"
Requires-Dist: cirq-core; extra == "bench"
Requires-Dist: qsimcirq; extra == "bench"
Requires-Dist: mqt.bench<3,>=2.2.3; extra == "bench"
Requires-Dist: mqt.qcec<4,>=3.10; extra == "bench"
Requires-Dist: ffsim; extra == "bench"
Requires-Dist: openfermionpyscf; extra == "bench"
Provides-Extra: full
Requires-Dist: quimb>=1.12.1; extra == "full"
Requires-Dist: opt_einsum>=3.3; extra == "full"
Requires-Dist: hypernetx>=2.4.0; extra == "full"
Requires-Dist: fastjsonschema>=2.21.0; extra == "full"
Requires-Dist: pandas<3; extra == "full"
Requires-Dist: cvxpy; extra == "full"
Requires-Dist: pygridsynth>=2.0; extra == "full"
Requires-Dist: pytest; extra == "full"
Requires-Dist: hypothesis>=6.100; extra == "full"
Requires-Dist: pytest-cov==7.1.0; extra == "full"
Requires-Dist: coverage==7.15.4; extra == "full"
Requires-Dist: diff-cover==10.5.0; extra == "full"
Requires-Dist: openfermion<1.8,>=1.7.1; extra == "full"
Provides-Extra: full-dev
Requires-Dist: pyscf>=2.10; extra == "full-dev"
Requires-Dist: quimb>=1.12.1; extra == "full-dev"
Requires-Dist: opt_einsum>=3.3; extra == "full-dev"
Requires-Dist: hypernetx>=2.4.0; extra == "full-dev"
Requires-Dist: fastjsonschema>=2.21.0; extra == "full-dev"
Requires-Dist: pandas<3; extra == "full-dev"
Requires-Dist: cvxpy; extra == "full-dev"
Requires-Dist: pygridsynth>=2.0; extra == "full-dev"
Requires-Dist: pytest; extra == "full-dev"
Requires-Dist: hypothesis>=6.100; extra == "full-dev"
Requires-Dist: pytest-cov==7.1.0; extra == "full-dev"
Requires-Dist: coverage==7.15.4; extra == "full-dev"
Requires-Dist: diff-cover==10.5.0; extra == "full-dev"
Requires-Dist: openfermion<1.8,>=1.7.1; extra == "full-dev"
Requires-Dist: ruff==0.15.22; extra == "full-dev"
Requires-Dist: mypy==1.19.1; extra == "full-dev"
Requires-Dist: pre-commit>=3.5; extra == "full-dev"
Description-Content-Type: text/x-rst

=========================================
Open Quantum Application Research Package
=========================================

|pypi| |python| |wheels| |license|

|ci| |coverage| |docs|

|arxiv| |doi|

.. |pypi| image:: https://img.shields.io/pypi/v/openqarp?label=pypi&labelColor=201B34&color=2B4DFF
   :target: https://pypi.org/project/openqarp/
   :alt: PyPI version

.. |python| image:: https://img.shields.io/pypi/pyversions/openqarp?labelColor=201B34&color=2B4DFF
   :target: https://pypi.org/project/openqarp/
   :alt: Supported Python versions

.. |wheels| image:: https://img.shields.io/badge/wheels-Linux%20%C2%B7%20macOS%20%C2%B7%20Windows-2B4DFF?labelColor=201B34
   :target: https://pypi.org/project/openqarp/#files
   :alt: Wheels for Linux, macOS and Windows

.. |license| image:: https://img.shields.io/github/license/OpenQARP/openqarp?labelColor=201B34&color=2B4DFF
   :target: https://github.com/OpenQARP/openqarp/blob/develop/LICENSE
   :alt: License: Apache 2.0

.. |ci| image:: https://img.shields.io/github/actions/workflow/status/OpenQARP/openqarp/ci.yml?branch=develop&label=CI&labelColor=201B34
   :target: https://github.com/OpenQARP/openqarp/actions/workflows/ci.yml
   :alt: CI

.. |coverage| image:: https://img.shields.io/endpoint?url=https%3A%2F%2Fopenqarp.github.io%2Fopenqarp%2Fbadges%2Fcoverage.json&labelColor=201B34
   :target: https://github.com/OpenQARP/openqarp/actions/workflows/ci.yml
   :alt: Coverage

.. |docs| image:: https://img.shields.io/website?url=https%3A%2F%2Fopenqarp.github.io%2Fopenqarp%2F&label=docs&up_message=online&up_color=brightgreen&down_color=red&labelColor=201B34
   :target: https://openqarp.github.io/openqarp/
   :alt: Documentation

.. |arxiv| image:: https://img.shields.io/badge/arXiv-2609.15697-B31B1B?labelColor=201B34
   :target: https://arxiv.org/abs/2609.15697
   :alt: arXiv:2609.15697

.. |doi| image:: https://img.shields.io/badge/DOI-10.5281%2Fzenodo.22755228-B31B1B?labelColor=201B34
   :target: https://doi.org/10.5281/zenodo.22755228
   :alt: DOI

----

OpenQARP is a Python package for quantum computing research.  You start from
a problem, such as a molecule, a spin model or an optimisation instance.  You
build a circuit for it, then run the circuit on a fast simulator or compile it
for real hardware.  The simulator and compiler are written in C++, and you use
them entirely from Python.

.. image:: https://raw.githubusercontent.com/OpenQARP/openqarp/develop/docs/source/images/block_primitive_engine.svg
   :target: https://openqarp.github.io/openqarp/source/qarp_philosophy.html
   :alt: Blocks describe circuits, primitives and composites describe what to extract, engines describe how they run.

----

Install
=======

.. code-block:: bash

   pip install openqarp

Wheels ship for Linux (x86_64, arm64), macOS (Apple silicon, Intel) and
Windows on Python 3.11–3.14.  Anywhere else ``pip`` compiles the C++ backend
from source, which takes a few minutes.  For GPUs, editable installs, or a
build on a machine with little memory, see the `Installation Guide`_.  The
distribution is named ``openqarp``; the package you import is ``qarp``.

----

Getting started
===============

Three snippets.  Paste them into a Jupyter notebook in order — each one builds
on the last.

**1. Build a circuit and look at it.**  Circuits are *blocks*: you say how many
qubits, add gates, then ``build()``.

.. code-block:: python

   from qarp.blocks import SimpleBlock

   bell = SimpleBlock(2, name="bell")
   bell.h(0)
   bell.cx(0, 1)
   bell.measure([(q, q) for q in range(2)])   # measure qubit q into bit q
   bell.build()

   bell.plot()                                # draws the circuit diagram

**2. Run it and get the results.**  A *primitive* says what you want out of the
circuit — here, the distribution of measured bitstrings.  The *engine* runs it.

.. code-block:: python

   from qarp.algorithms import Sampler
   from qarp.engines import QarpEngine

   sampler = Sampler(ket=bell, n_shots=4000)

   engine = QarpEngine(seed=42)               # seed makes shots reproducible
   engine.build([sampler])
   results = engine.run()

   print(results[0])
   # {(0, 0): 0.48875, (1, 1): 0.51125}   ← a Bell state, up to shot noise

Keys are tuples of bits indexed by qubit: position ``q`` is qubit ``q``.  OpenQARP
is least-significant-bit-first everywhere.  Values are probabilities, not raw
counts.

**3. Measure an observable.**  Swap the primitive to get an expectation value
instead — exactly, or sampled with shots, from the same circuit.

.. code-block:: python

   from qarp.operators import QubitOperator
   from qarp.algorithms import PauliAveraging, StateVector

   circuit = SimpleBlock(2, name="bell")
   circuit.h(0)
   circuit.cx(0, 1)
   circuit.build()                            # no measurements this time

   H = QubitOperator("Z0 Z1") + 0.5 * QubitOperator("X0 X1")

   exact = StateVector(ket=circuit, operator=H)
   shots = PauliAveraging(ket=circuit, operator=H, n_shots=4000)

   engine = QarpEngine(seed=42)
   engine.build([exact, shots])
   results = engine.run()

   print(results[0], results[1])
   # (1.4999999999999998+0j) 1.5        ← both agree with ⟨H⟩ = 1.5 by hand

These are the three layers of OpenQARP.  A **block** describes the circuit, a
**primitive** describes what to extract from it, and an **engine** describes how
it runs.  VQE, QPE, circuit cutting and noisy simulation use the same three
layers with different parts plugged in.

**Next:** the six ``tutorial_00`` … ``tutorial_05`` notebooks in
`examples/ <https://github.com/OpenQARP/openqarp/tree/main/examples>`_
take about an hour end to end, or jump straight to the `OpenQARP Tutorial`_.

----

What's in OpenQARP
==================

.. list-table::
   :widths: 24 76
   :header-rows: 0

   * - **Algorithms**
     - `VQE`_, `VQD`_, `SSVQE`_, `ADAPT-VQE`_ / `ADAPT-VQD`_, `QAOA`_, `QPE`_,
       `DOS-QPE`_, `PCE`_ — ready to run, or assembled from primitives.
   * - **Circuits**
     - Composable blocks: hardware-efficient and QAOA ansatzes, Trotterised
       evolution, and custom blocks of your own.
   * - **Chemistry & physics**
     - Electronic structure from plain numpy integral tensors, with
       Jordan-Wigner, Bravyi-Kitaev and parity mappings.
   * - **Simulation**
     - Exact state vectors, shot-based sampling, noisy simulation with
       configurable channels, mid-circuit measurement, and circuit cutting for problems
       too big for the qubits you have.
   * - **Hardware**
     - Compile to a device's gate set and qubit layout, with noise and routing
       models — and plot any of it with Matplotlib.

----

Documentation
=============

Full documentation is on `GitHub Pages`_.

+-------------------------+------------------------------------------------------------+
| Resource                | Description                                                |
+=========================+============================================================+
| `OpenQARP Tutorial`_    | Guided path: blocks, primitives, engines, VQE loops        |
+-------------------------+------------------------------------------------------------+
| `OpenQARP Philosophy`_  | Design principles behind OpenQARP                          |
+-------------------------+------------------------------------------------------------+
| `Installation Guide`_   | Build options, GPU, LAPACK, developer setup                |
+-------------------------+------------------------------------------------------------+
| `Examples Directory`_   | ~50 runnable notebooks by API area, plus worked use cases  |
+-------------------------+------------------------------------------------------------+

----

Benchmarks
==========

OpenQARP is benchmarked against qiskit, pennylane, pytket, qulacs and cirq on
operator algebra, simulation, sampling, compilation and end-to-end algorithm
runs.  Tables are in ``benchmarks/tables/``; every timing row carries a
correctness check against an independent reference, and rows whose checks
disagree are not published.  The harness that regenerates them is
`benchmarks/README.md
<https://github.com/OpenQARP/openqarp/blob/main/benchmarks/README.md>`_.

----

Citing
======

If OpenQARP is useful in your research, please cite the paper describing the
framework (``CITATION.cff`` carries the same entry in machine-readable form):

.. code-block:: bibtex

   @misc{scali2026openqarpmodularframeworkquantum,
     title         = {OpenQARP: a modular framework for quantum application research},
     author        = {Stefano Scali and Vicente P. Soloviev and Antonio M{\'a}rquez Romero and
                      Brian Coyle and Giuseppe Buonaiuto and Annie Paine and Jonathan H. Fetherolf and
                      Marcos Diez Garc{\'i}a and Michal Krompiec and Josh Kirsopp},
     year          = {2026},
     eprint        = {2609.15697},
     archivePrefix = {arXiv},
     primaryClass  = {quant-ph},
     url           = {https://arxiv.org/abs/2609.15697},
   }

To cite a specific software release, use the version DOI on `Zenodo
<https://doi.org/10.5281/zenodo.22755228>`_ alongside the paper.

----

Contributing & support
======================

Contributions are welcome — please read the `Contributing Guidelines`_ first
and the `Code of Conduct`_, which applies to every project space.  For bugs,
questions, or feature ideas, open an issue in the `Issue Tracker`_.

OpenQARP is developed and maintained by the Fujitsu Research of Europe team, and
released under the Apache License 2.0 — see ``LICENSE``.  The copyright notice
is in ``NOTICE``, which the Apache License requires you to carry forward if you
redistribute OpenQARP or a derivative work; the licenses of the bundled
third-party components are in ``LICENSES_bundled.txt``.

.. _GitHub Pages: https://openqarp.github.io/openqarp/
.. _OpenQARP Philosophy: https://openqarp.github.io/openqarp/source/qarp_philosophy.html
.. _OpenQARP Tutorial: https://openqarp.github.io/openqarp/source/tutorial.html
.. _Installation Guide: https://openqarp.github.io/openqarp/source/installation.html
.. _Examples Directory: https://github.com/OpenQARP/openqarp/tree/main/examples
.. _Contributing Guidelines: https://github.com/OpenQARP/openqarp/blob/main/CONTRIBUTING.md
.. _Code of Conduct: https://github.com/OpenQARP/openqarp/blob/main/CODE_OF_CONDUCT.md
.. _Issue Tracker: https://github.com/OpenQARP/openqarp/issues


.. _ADAPT-VQE: https://arxiv.org/abs/1812.11173
.. _ADAPT-VQD: https://arxiv.org/abs/2105.10275
.. _QPE: https://www.cambridge.org/highereducation/books/quantum-computation-and-quantum-information/01E10196D0A682A6AEFFEA52D53BE9AE#overview
.. _DOS-QPE: https://arxiv.org/abs/2510.14744
.. _PCE: https://www.nature.com/articles/s41467-024-55346-z.pdf
.. _QAOA: https://arxiv.org/pdf/1411.4028
.. _SSVQE: https://journals.aps.org/prresearch/pdf/10.1103/PhysRevResearch.1.033062
.. _VQD: https://arxiv.org/abs/1805.08138
.. _VQE: https://www.nature.com/articles/ncomms5213.pdf
