<p align="center">
<img title="license" src="https://img.shields.io/badge/license-Apache_2.0-blue.svg">
<img title="python" src="https://img.shields.io/badge/python-≥3.9-blue.svg">
<a href="https://qiskit.org/ecosystem/" alt="Ecosystem">
<img src="https://img.shields.io/badge/Qiskit-Ecosystem-blueviolet.svg" /></a>
</p>
<p align="center">
<img title="build" src='https://github.com/SimoneGasperini/qiskit-symb/actions/workflows/python-package.yml/badge.svg?branch=master'>
<img title="coverage" src='https://codecov.io/github/SimoneGasperini/qiskit-symb/graph/badge.svg?token=R62B2D4SR6'>
</p>
# Table of contents
- [Introduction](#introduction)
- [Installation](#installation)
- [User-mode](#user-mode)
- [Dev-mode](#dev-mode)
- [Usage examples](#usage-examples)
- [_Sympify_ a Qiskit circuit](#sympify-a-qiskit-circuit)
- [_Lambdify_ a Qiskit circuit](#lambdify-a-qiskit-circuit)
- [Qiskit Medium](#qiskit-medium)
- [Contributors](#contributors)
# Introduction
The `qiskit-symb` package is meant to be a Python tool to enable the symbolic evaluation of parametric quantum states defined by [Qiskit](https://github.com/Qiskit/qiskit) by parameterized quantum circuits.
A Parameterized Quantum Circuit (PQC) is a quantum circuit where we have at least one free parameter (e.g. a rotation angle $\theta$). PQCs are particularly relevant in Quantum Machine Learning (QML) models, where the values of these parameters can be learned during training to reach the desired output.
In particular, `qiskit-symb` can be used to create a symbolic representation of a parametric quantum state directly from the Qiskit quantum circuit. This has been achieved through the re-implementation of some basic classes defined in the [`qiskit/quantum_info/`](https://github.com/Qiskit/qiskit/tree/main/qiskit/quantum_info) module by using [sympy](https://github.com/sympy/sympy) as a backend for symbolic expressions manipulation.
# Installation
## User-mode
```
pip install qiskit-symb
```
:warning: The package requires `qiskit==1.x`. It doesn't support `qiskit==2.x` yet.
## Dev-mode
```
git clone https://github.com/SimoneGasperini/qiskit-symb.git
cd qiskit-symb
pip install requirements-dev.txt
pip install -e .
```
# Usage examples
### _Sympify_ a Qiskit circuit
Let's get started on how to use `qiskit-symb` to get the symbolic representation of a given Qiskit circuit. In particular, in this first basic example, we consider the following quantum circuit:
```python
from qiskit import QuantumCircuit
from qiskit.circuit import Parameter, ParameterVector
y = Parameter('y')
p = ParameterVector('p', length=2)
pqc = QuantumCircuit(2)
pqc.ry(y, 0)
pqc.cx(0, 1)
pqc.u(p[0], 0, p[1], 1)
pqc.draw('mpl')
```
To get the *sympy* representation of the unit-norm complex vector prepared by the parameterized circuit, we just have to create the symbolic `Statevector` instance and call the `to_sympy()` method:
```python
from qiskit_symb.quantum_info import Statevector
psi = Statevector(pqc)
psi.to_sympy()
```
```math
\left[\begin{matrix}\cos{\left(\frac{p[0]}{2} \right)} \cos{\left(\frac{y}{2} \right)} & - e^{1.0 i p[1]} \sin{\left(\frac{p[0]}{2} \right)} \sin{\left(\frac{y}{2} \right)} & \sin{\left(\frac{p[0]}{2} \right)} \cos{\left(\frac{y}{2} \right)} & e^{1.0 i p[1]} \sin{\left(\frac{y}{2} \right)} \cos{\left(\frac{p[0]}{2} \right)}\end{matrix}\right]
```
If you want then to assign a value to some specific parameter, you can use the `subs(<dict>)` method passing a dictionary that maps each parameter to the desired corresponding value:
```python
new_psi = psi.subs({p: [-1, 2]})
new_psi.to_sympy()
```
```math
\left[\begin{matrix}\cos{\left(\frac{1}{2} \right)} \cos{\left(\frac{y}{2} \right)} & e^{2.0 i} \sin{\left(\frac{1}{2} \right)} \sin{\left(\frac{y}{2} \right)} & - \sin{\left(\frac{1}{2} \right)} \cos{\left(\frac{y}{2} \right)} & e^{2.0 i} \sin{\left(\frac{y}{2} \right)} \cos{\left(\frac{1}{2} \right)}\end{matrix}\right]
```
### _Lambdify_ a Qiskit circuit
Given a Qiskit circuit, `qiskit-symb` also allows to generate a Python lambda function with actual arguments matching the Qiskit unbound parameters.
Let's consider the following example starting from a `ZZFeatureMap` circuit, commonly used as a data embedding ansatz in QML applications:
```python
from qiskit.circuit.library import ZZFeatureMap
pqc = ZZFeatureMap(feature_dimension=3, reps=1)
pqc.draw('mpl')
```
To get the Python function representing the final parameteric statevector, we just have to create the symbolic `Statevector` instance and call the `to_lambda()` method:
```python
from qiskit_symb.quantum_info import Statevector
pqc = pqc.decompose()
statevec = Statevector(pqc).to_lambda()
```
We can now call the lambda-generated function `statevec` passing the `x` values we want to assign to each parameter. The returned object will be a *numpy* 2D-array (with `shape=(8,1)` in this case) representing the final output statevector `psi`.
```python
x = [1.24, 2.27, 0.29]
psi = statevec(*x)
```
This feature can be useful when, given a Qiskit PQC, we want to run it multiple times with different parameters values. Indeed, we can perform a single symbolic evalutation and then call the lambda generated function as many times as needed, passing different values of the parameters at each iteration.
# Qiskit Medium
Read my [blog post](https://medium.com/p/b6b4407fa705) introducing to `qiskit-symb` published on the official Qiskit Medium blog.
# Contributors
<table>
<td align="center"><a href="https://github.com/SimoneGasperini"><img src="https://avatars2.githubusercontent.com/u/71086758?s=400&v=4" width="120px;"/><br/><b>Simone Gasperini</b></a></td>
<td align="center"><a href="https://github.com/sbrandhsn"><img src="https://avatars.githubusercontent.com/u/148463728?v=4" width="60px;"/><br/>Sebastian<br/>Brandhofer</a></td>
</table>
Raw data
{
"_id": null,
"home_page": null,
"name": "qiskit-symb",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "quantum-computing, symbolic-computation, qiskit, sympy",
"author": null,
"author_email": "Simone Gasperini <simone.gasperini4@unibo.it>",
"download_url": "https://files.pythonhosted.org/packages/fb/e4/2250b526f45f3e6b4640014730ab2131614074fe55b4bb1bb9aa6629ff46/qiskit_symb-0.5.0.tar.gz",
"platform": null,
"description": "\n\n<p align=\"center\">\n <img title=\"license\" src=\"https://img.shields.io/badge/license-Apache_2.0-blue.svg\">\n <img title=\"python\" src=\"https://img.shields.io/badge/python-\u22653.9-blue.svg\">\n <a href=\"https://qiskit.org/ecosystem/\" alt=\"Ecosystem\">\n <img src=\"https://img.shields.io/badge/Qiskit-Ecosystem-blueviolet.svg\" /></a>\n</p>\n\n<p align=\"center\">\n <img title=\"build\" src='https://github.com/SimoneGasperini/qiskit-symb/actions/workflows/python-package.yml/badge.svg?branch=master'>\n <img title=\"coverage\" src='https://codecov.io/github/SimoneGasperini/qiskit-symb/graph/badge.svg?token=R62B2D4SR6'>\n</p>\n\n# Table of contents\n- [Introduction](#introduction)\n- [Installation](#installation)\n - [User-mode](#user-mode)\n - [Dev-mode](#dev-mode)\n- [Usage examples](#usage-examples)\n - [_Sympify_ a Qiskit circuit](#sympify-a-qiskit-circuit)\n - [_Lambdify_ a Qiskit circuit](#lambdify-a-qiskit-circuit)\n- [Qiskit Medium](#qiskit-medium)\n- [Contributors](#contributors)\n\n\n# Introduction\nThe `qiskit-symb` package is meant to be a Python tool to enable the symbolic evaluation of parametric quantum states defined by [Qiskit](https://github.com/Qiskit/qiskit) by parameterized quantum circuits.\n\nA Parameterized Quantum Circuit (PQC) is a quantum circuit where we have at least one free parameter (e.g. a rotation angle $\\theta$). PQCs are particularly relevant in Quantum Machine Learning (QML) models, where the values of these parameters can be learned during training to reach the desired output.\n\nIn particular, `qiskit-symb` can be used to create a symbolic representation of a parametric quantum state directly from the Qiskit quantum circuit. This has been achieved through the re-implementation of some basic classes defined in the [`qiskit/quantum_info/`](https://github.com/Qiskit/qiskit/tree/main/qiskit/quantum_info) module by using [sympy](https://github.com/sympy/sympy) as a backend for symbolic expressions manipulation.\n\n\n# Installation\n\n## User-mode\n```\npip install qiskit-symb\n```\n\n:warning: The package requires `qiskit==1.x`. It doesn't support `qiskit==2.x` yet.\n\n## Dev-mode\n```\ngit clone https://github.com/SimoneGasperini/qiskit-symb.git\ncd qiskit-symb\npip install requirements-dev.txt\npip install -e .\n```\n\n\n# Usage examples\n\n### _Sympify_ a Qiskit circuit\nLet's get started on how to use `qiskit-symb` to get the symbolic representation of a given Qiskit circuit. In particular, in this first basic example, we consider the following quantum circuit:\n```python\nfrom qiskit import QuantumCircuit\nfrom qiskit.circuit import Parameter, ParameterVector\n\ny = Parameter('y')\np = ParameterVector('p', length=2)\n\npqc = QuantumCircuit(2)\npqc.ry(y, 0)\npqc.cx(0, 1)\npqc.u(p[0], 0, p[1], 1)\n\npqc.draw('mpl')\n```\n\n\nTo get the *sympy* representation of the unit-norm complex vector prepared by the parameterized circuit, we just have to create the symbolic `Statevector` instance and call the `to_sympy()` method:\n```python\nfrom qiskit_symb.quantum_info import Statevector\n\npsi = Statevector(pqc)\npsi.to_sympy()\n```\n```math\n\\left[\\begin{matrix}\\cos{\\left(\\frac{p[0]}{2} \\right)} \\cos{\\left(\\frac{y}{2} \\right)} & - e^{1.0 i p[1]} \\sin{\\left(\\frac{p[0]}{2} \\right)} \\sin{\\left(\\frac{y}{2} \\right)} & \\sin{\\left(\\frac{p[0]}{2} \\right)} \\cos{\\left(\\frac{y}{2} \\right)} & e^{1.0 i p[1]} \\sin{\\left(\\frac{y}{2} \\right)} \\cos{\\left(\\frac{p[0]}{2} \\right)}\\end{matrix}\\right]\n```\n\nIf you want then to assign a value to some specific parameter, you can use the `subs(<dict>)` method passing a dictionary that maps each parameter to the desired corresponding value:\n```python\nnew_psi = psi.subs({p: [-1, 2]})\nnew_psi.to_sympy()\n```\n```math\n\\left[\\begin{matrix}\\cos{\\left(\\frac{1}{2} \\right)} \\cos{\\left(\\frac{y}{2} \\right)} & e^{2.0 i} \\sin{\\left(\\frac{1}{2} \\right)} \\sin{\\left(\\frac{y}{2} \\right)} & - \\sin{\\left(\\frac{1}{2} \\right)} \\cos{\\left(\\frac{y}{2} \\right)} & e^{2.0 i} \\sin{\\left(\\frac{y}{2} \\right)} \\cos{\\left(\\frac{1}{2} \\right)}\\end{matrix}\\right]\n```\n\n### _Lambdify_ a Qiskit circuit\nGiven a Qiskit circuit, `qiskit-symb` also allows to generate a Python lambda function with actual arguments matching the Qiskit unbound parameters.\nLet's consider the following example starting from a `ZZFeatureMap` circuit, commonly used as a data embedding ansatz in QML applications:\n```python\nfrom qiskit.circuit.library import ZZFeatureMap\n\npqc = ZZFeatureMap(feature_dimension=3, reps=1)\npqc.draw('mpl')\n```\n\n\nTo get the Python function representing the final parameteric statevector, we just have to create the symbolic `Statevector` instance and call the `to_lambda()` method:\n```python\nfrom qiskit_symb.quantum_info import Statevector\n\npqc = pqc.decompose()\nstatevec = Statevector(pqc).to_lambda()\n```\n\nWe can now call the lambda-generated function `statevec` passing the `x` values we want to assign to each parameter. The returned object will be a *numpy* 2D-array (with `shape=(8,1)` in this case) representing the final output statevector `psi`.\n```python\nx = [1.24, 2.27, 0.29]\npsi = statevec(*x)\n```\n\nThis feature can be useful when, given a Qiskit PQC, we want to run it multiple times with different parameters values. Indeed, we can perform a single symbolic evalutation and then call the lambda generated function as many times as needed, passing different values of the parameters at each iteration.\n\n\n# Qiskit Medium\nRead my [blog post](https://medium.com/p/b6b4407fa705) introducing to `qiskit-symb` published on the official Qiskit Medium blog.\n\n\n\n\n# Contributors\n\n<table>\n <td align=\"center\"><a href=\"https://github.com/SimoneGasperini\"><img src=\"https://avatars2.githubusercontent.com/u/71086758?s=400&v=4\" width=\"120px;\"/><br/><b>Simone Gasperini</b></a></td>\n <td align=\"center\"><a href=\"https://github.com/sbrandhsn\"><img src=\"https://avatars.githubusercontent.com/u/148463728?v=4\" width=\"60px;\"/><br/>Sebastian<br/>Brandhofer</a></td>\n</table>\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Symbolic evaluation of parameterized quantum circuits in Qiskit",
"version": "0.5.0",
"project_urls": null,
"split_keywords": [
"quantum-computing",
" symbolic-computation",
" qiskit",
" sympy"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "634f42413ce9a13ad35a9bc5e12908b854351a37b3c8b899b29686ab8b81f916",
"md5": "524f26e3f685f08fb0d20f7ee5e21b82",
"sha256": "7551f799c7be8853d1c0c05441b0d10a746d7e09646c255652046e65221cec4d"
},
"downloads": -1,
"filename": "qiskit_symb-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "524f26e3f685f08fb0d20f7ee5e21b82",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 25094,
"upload_time": "2025-07-24T02:33:27",
"upload_time_iso_8601": "2025-07-24T02:33:27.272768Z",
"url": "https://files.pythonhosted.org/packages/63/4f/42413ce9a13ad35a9bc5e12908b854351a37b3c8b899b29686ab8b81f916/qiskit_symb-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fbe42250b526f45f3e6b4640014730ab2131614074fe55b4bb1bb9aa6629ff46",
"md5": "614a03fe6901f579e5d3bed1c4d566a2",
"sha256": "5ff0ca849f68ef92638d8b8ac9eda64a79f90c8a093ca0cba8270e17767d9410"
},
"downloads": -1,
"filename": "qiskit_symb-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "614a03fe6901f579e5d3bed1c4d566a2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 18362,
"upload_time": "2025-07-24T02:33:28",
"upload_time_iso_8601": "2025-07-24T02:33:28.080297Z",
"url": "https://files.pythonhosted.org/packages/fb/e4/2250b526f45f3e6b4640014730ab2131614074fe55b4bb1bb9aa6629ff46/qiskit_symb-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 02:33:28",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "qiskit-symb"
}
JSON