{"id":16764769,"url":"https://github.com/tomekzaw/ewl","last_synced_at":"2026-03-27T04:51:53.808Z","repository":{"id":40450933,"uuid":"359591770","full_name":"tomekzaw/ewl","owner":"tomekzaw","description":"A Python tool for symbolic analysis of quantum games in EWL protocol with IBM Q integration.","archived":false,"fork":false,"pushed_at":"2022-05-07T19:55:48.000Z","size":3889,"stargazers_count":9,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-08T06:06:15.356Z","etag":null,"topics":["ewl","ibmq","python","qiskit","quantum","sympy"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/ewl/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tomekzaw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-04-19T20:38:24.000Z","updated_at":"2024-02-14T17:47:55.000Z","dependencies_parsed_at":"2022-08-09T20:51:06.896Z","dependency_job_id":null,"html_url":"https://github.com/tomekzaw/ewl","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/tomekzaw/ewl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomekzaw%2Fewl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomekzaw%2Fewl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomekzaw%2Fewl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomekzaw%2Fewl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tomekzaw","download_url":"https://codeload.github.com/tomekzaw/ewl/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomekzaw%2Fewl/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264207096,"owners_count":23572728,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ewl","ibmq","python","qiskit","quantum","sympy"],"created_at":"2024-10-13T05:27:07.694Z","updated_at":"2026-03-27T04:51:53.762Z","avatar_url":"https://github.com/tomekzaw.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EWL\n\nA simple Python library to simulate and execute EWL quantum circuits on IBM Q with symbolic calculations using SymPy.\n\n![](https://raw.githubusercontent.com/tomekzaw/ewl/master/docs/ewl.png)\n\n## Installation\n\n```bash\npip install ewl\n```\n\n## Examples\n\n-   Prisoner's dilemma\n    -   [Two players](https://github.com/tomekzaw/ewl/blob/master/examples/example.ipynb)\n    -   [Three players](https://github.com/tomekzaw/ewl/blob/master/examples/three_players.ipynb)\n    -   [Payoff function 3D plot](https://github.com/tomekzaw/ewl/blob/master/examples/payoff_function_plot_3d.ipynb)\n    -   [Simulation with predefined gate noises](https://github.com/tomekzaw/ewl/blob/master/examples/noise_model.ipynb)\n\n## Usage\n\n### Initialization\n\nThis library uses [SymPy](https://www.sympy.org/en/index.html) to perform symbolic calculations. It's convenient to import it as `sp` and define frequently used constants for future use.\n\n```python\nimport sympy as sp\n\ni = sp.I\npi = sp.pi\nsqrt2 = sp.sqrt(2)\n```\n\nWhen using this library in Jupyter Notebook, call [`init_printing`](https://docs.sympy.org/latest/tutorial/printing.html#setting-up-pretty-printing) to enable pretty printing.\n\n```python\nsp.init_printing()\n```\n\n### EWL instance\n\nFirst, you need to define the initial (preferably entangled) quantum state:\n\n```python\nfrom sympy.physics.quantum.qubit import Qubit\n\npsi = (Qubit('00') + i * Qubit('11')) / sqrt2\n```\n\nIt is also necessary to define two unitary strategies that represent the classical strategies:\n\n```python\nC = sp.Matrix([\n    [1, 0],\n    [0, 1],\n])\n\nD = sp.Matrix([\n    [0, i],\n    [i, 0],\n])\n```\n\nThen you need to define the players' strategies. Each strategy must be a unitary matrix as it represents a single-qubit quantum gate.\n\n```python\nalice = sp.Matrix([\n    [1, 0],\n    [0, 1],\n])\n```\n\nThe library comes with a series of built-in parametrizations, including the original one from EWL paper as well as other 2- and 3 degrees of freedom parametrizations (see [here](https://github.com/tomekzaw/ewl/blob/master/src/ewl/parametrizations.py)).\n\n```python\nfrom ewl.parametrizations import *\n\nbob = U_Eisert_Wilkens_Lewenstein(theta=pi / 2, phi=0)\n```\n\nAt this point you can also use arbitrary symbols and compound expressions to generalize the analysis.\n\n```python\ntheta, gamma = sp.symbols('theta gamma', real=True)\n\ncharlie = U_Eisert_Wilkens_Lewenstein(theta=theta, phi=gamma / 2)\n```\n\nYou also need to define the payoff matrix, possibly with symbols, for arbitrary number of players.\n\n```python\npayoff_matrix = sp.Array([\n    [\n        [3, 0],\n        [5, 1],\n    ],\n    [\n        [3, 5],\n        [0, 1],\n    ],\n])\n```\n\nFinally, you can make an instance of quantum game in the EWL protocol by providing the initial quantum state, a list of players' strategies and the payoff matrix with corresponding shape. The library supports arbitrary number of players, although it works best for 2-player games.\n\n```python\nfrom ewl import EWL\n\newl = EWL(psi=psi, C=C, D=D, players=[alice, bob], payoff_matrix=payoff_matrix)\n```\n\n### Calculations\n\nBased on the provided initial quantum state, the library automatically calculates the corresponding matrix of *J* and *J*\u003csup\u003e†\u003c/sup\u003e gates.\n\n```python\newl.J\newl.J_H\n```\n\nBased on the players' strategies, the library also calculates the amplitudes of the result quantum state in the computational basis.\n\n```python\newl.amplitudes()\newl.amplitudes(simplify=False)\n```\n\nFrom the amplitudes one can easily derive the probabilities of possible game results. By default, the expressions are simplified using trigonometric identities. Make sure to enable `real=True` flag when defining real-valued symbols to allow for further simplification.\n\n```python\newl.probs()\newl.probs(simplify=False)\n```\n\nFinally, based on the payoff matrix and previously mentioned probabilities, the library calculates the payoff functions as symbolic expressions (possibly with parameters from the initial state and strategies).\n\n```python\newl.payoff_function(player=0)  # first player\newl.payoff_function(player=1, simplify=False)  # second player\newl.payoff_function(player=None)  # payoff sum\n```\n\nYou can also obtain a tuple containing the payoffs for each respective player.\n\n```python\newl.payoffs()\newl.payoffs(simplify=False)\n```\n\nFor quantum games parametrized with exactly two symbols, it is possible to plot a three-dimensional graph of the payoff function.\n\n```python\nfrom ewl.plotting import plot_payoff_function\n\nplot_payoff_function(\n    ewl, player=0,\n    x=alpha, x_min=0, x_max=pi / 2,\n    y=beta, y_min=0, y_max=pi / 2)\n```\n\n### Parameters\n\nHere's how you can list all symbols used either in the initial quantum state or in the players' strategies:\n\n```python\newl.params\n```\n\nYou can also substitute the symbols with specific values to obtain a non-parametrized instance of quantum game as new EWL instance:\n\n```python\newl_fixed = ewl.fix(theta=0, gamma=pi / 2)\n```\n\nIt is also possible to substitute specific players' strategies for further analysis of a certain case of the game.\n\n```python\newl_CD = ewl.play(C, D)\n```\n### Mixed strategies\n\nThe library also supports quantum games with mixed strategies. You can define a mixed strategy by passing a list of probabilities and corresponding pure strategies:\n\n```python\nfrom ewl.mixed import MixedStrategy\n\nalice = MixedStrategy([(p1, U1), (p2, U2)])\n```\n\n**Note:** The library will check if the probabilities sum up to 1. To disable this check, pass `check_sum=False`.\n\nThen you can create an instance of EWL quantum game with mixed strategies:\n\n```python\nfrom ewl.mixed import MixedEWL\n\nmixed_ewl = MixedEWL(psi=psi, C=C, D=D, players=[alice, bob], payoff_matrix=payoff_matrix)\n```\n\nThe major difference is that you cannot call `amplitudes` method due to the fact that the state of quantum game with mixed strategies cannot be expressed as a vector in a general case. Instead, you can calculate the density matrix.\n\n```python\nmixed_ewl.density_matrix()\n```\n\nOther properties and methods such as `J`, `J_H`, `params`, `fix`, `probs` and `payoff_function` behave similarly as for the regular EWL instance with pure strategies.\n\n### Example games\n\nThe library comes with a series of built-in example games, in particular a few variants of Quantum Prisoner's Dilemma with different parametrizations from various articles (see [here](https://github.com/tomekzaw/ewl/blob/master/src/ewl/games.py)).\n\n### Qiskit integration\n\nThis library also integrates with [Qiskit](https://qiskit.org/), allowing arbitrary quantum games in the EWL protocol to be executed on [IBM Q](https://www.ibm.com/quantum-computing/) devices. First, you need to load your credentials:\n\n```python\nfrom qiskit import IBMQ\n\nIBMQ.load_account()\n```\n\nWhen running locally, make sure to save the access token to disk first using [`IBMQ.save_account`](https://qiskit.org/documentation/stubs/qiskit.providers.ibmq.IBMQFactory.save_account.html).\n\nIn order to access backend-specific features of EWL instance, first you need to convert it to `EWL_IBMQ` instance. Note that the input quantum game must be non-parametrized (cannot have any symbols).\n\n```python\nfrom ewl.ibmq import EWL_IBMQ\n\newl_ibmq = EWL_IBMQ(ewl_fixed)\n```\n\nYou can also specify and apply noise model used in quantum simulation.\n\n```python\nfrom qiskit.providers.aer.noise import NoiseModel, pauli_error\n\np_error = 0.05\nbit_flip = pauli_error([('X', p_error), ('I', 1 - p_error)])\nphase_flip = pauli_error([('Z', p_error), ('I', 1 - p_error)])\n\nnoise_model = NoiseModel()\nnoise_model.add_all_qubit_quantum_error(bit_flip, ['u1', 'u2', 'u3'])\nnoise_model.add_all_qubit_quantum_error(phase_flip, ['x'], [0])\n\newl_ibmq = EWL_IBMQ(ewl_fixed, noise_model=noise_model)\n```\n\nYou can draw the original quantum circuit of quantum game in the EWL protocol.\n\n```python\newl_ibmq.draw()\n```\n\nIt is also possible to draw the quantum circuit transpiled for a specific backend.\n\n```python\newl_ibmq.draw_transpiled(backend_name='ibmq_quito', optimization_level=3)\n```\n\nHere's how you can execute the quantum game on a specific statevector simulator:\n\n```python\newl_ibmq.simulate_probs(backend_name='statevector_simulator')\n```\n\nYou may also run the quantum circuit on QASM simulator and get histogram data of the experiment.\n\n```python\newl_ibmq.simulate_counts(backend_name='qasm_simulator')\n```\n\nFinally, you can run the quantum game on a real quantum device:\n\n```python\newl_ibmq.run(backend_name='ibmq_quito', optimization_level=3)\n```\n\n## Citation\n\n```bibtex\n@software{PythonEWL2022,\n  author = {Tomasz Zawadzki and Piotr Kotara},\n  title = {A Python tool for symbolic analysis of quantum games in EWL protocol with IBM Q integration},\n  howpublished = {\\url{https://github.com/tomekzaw/ewl}},\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomekzaw%2Fewl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomekzaw%2Fewl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomekzaw%2Fewl/lists"}