{"id":22882518,"url":"https://github.com/cqcl/qujax","last_synced_at":"2025-10-19T20:24:03.156Z","repository":{"id":46700593,"uuid":"515163593","full_name":"CQCL/qujax","owner":"CQCL","description":"Simulating quantum circuits with JAX","archived":false,"fork":false,"pushed_at":"2025-02-24T11:23:54.000Z","size":4503,"stargazers_count":63,"open_issues_count":7,"forks_count":12,"subscribers_count":5,"default_branch":"develop","last_synced_at":"2025-03-29T04:06:51.149Z","etag":null,"topics":["jax","python","quantum"],"latest_commit_sha":null,"homepage":"https://cqcl.github.io/qujax/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CQCL.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-18T11:54:20.000Z","updated_at":"2025-02-24T11:23:59.000Z","dependencies_parsed_at":"2024-01-12T18:05:40.868Z","dependency_job_id":"445de57c-f646-42ed-8ad1-c7859044c22e","html_url":"https://github.com/CQCL/qujax","commit_stats":{"total_commits":176,"total_committers":8,"mean_commits":22.0,"dds":0.2272727272727273,"last_synced_commit":"249b2cb648cac8ef660a5b18bc9b7614df1f6944"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CQCL%2Fqujax","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CQCL%2Fqujax/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CQCL%2Fqujax/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CQCL%2Fqujax/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CQCL","download_url":"https://codeload.github.com/CQCL/qujax/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289428,"owners_count":20914464,"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":["jax","python","quantum"],"created_at":"2024-12-13T18:18:06.049Z","updated_at":"2025-10-19T20:23:58.102Z","avatar_url":"https://github.com/CQCL.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# qujax\n\n\u003cdiv align=\"center\"\u003e\n\u003ca href=\"https://cqcl.github.io/qujax/\"\u003e\n\u003cpicture\u003e\n    \u003csource srcset=\"docs/logo_dark_mode.svg\"  media=\"(prefers-color-scheme: dark)\"\u003e\n    \u003cimg src=\"docs/logo.svg\"\u003e\n\u003c/picture\u003e\n\u003c/a\u003e\n\u003c/div\u003e\n\n[![PyPI - Version](https://img.shields.io/pypi/v/qujax)](https://pypi.org/project/qujax/)\n[![DOI](https://joss.theoj.org/papers/10.21105/joss.05504/status.svg)](https://doi.org/10.21105/joss.05504)\n\n[**Documentation**](https://cqcl.github.io/qujax/) | [**Installation**](#installation) | [**Quick start**](#quick-start) | [**Examples**](https://cqcl.github.io/qujax/examples.html) | [**Contributing**](#contributing) | [**Citing qujax**](#citing-qujax)\n\nqujax is a [JAX](https://github.com/google/jax)-based Python library for the classical simulation of quantum circuits. It is designed to be *simple*, *fast* and *flexible*.\n\nIt follows a functional programming design by translating circuits into pure functions. This allows qujax to [seamlessly interface with JAX](https://jax.readthedocs.io/en/latest/notebooks/Common_Gotchas_in_JAX.html#pure-functions), enabling direct access to its powerful automatic differentiation tools, just-in-time compiler, vectorization capabilities, GPU/TPU integration and growing ecosystem of packages.\n\nqujax can be used both for pure and for mixed quantum state simulation. It not only supports the standard gate set, but also allows user-defined custom operations, including general quantum channels, enabling the user to e.g. model device noise and errors. \n\nA summary of the core functionalities of qujax can be found in the [Quick start](#quick-start) section. More advanced use-cases, including the training of parameterised quantum circuits, can be found in the [Examples](https://cqcl.github.io/qujax/examples.html) section of the documentation.\n\n\n## Installation\n\nqujax is [hosted on PyPI](https://pypi.org/project/qujax/) and can be installed via the pip package manager\n```\npip install qujax\n```\n\n## Quick start\n\n**Important note: qujax circuit parameters are expressed in units of $\\pi$ (e.g. in the range $[0,2]$ as opposed to $[0, 2\\pi]$)**.\n\nStart by defining the quantum gates making up the circuit, the qubits that they act on, and the indices of the parameters for each gate. \n\nA list of all gates can be found [here](https://github.com/CQCL/qujax/blob/main/qujax/gates.py) (custom operations can be included by [passing an array or function](https://cqcl.github.io/qujax/statetensor/get_params_to_statetensor_func.html) instead of a string).\n\n```python\nfrom jax import numpy as jnp\nimport qujax\n\n# List of quantum gates\ncircuit_gates = ['H', 'Ry', 'CZ']\n# Indices of qubits the gates will be applied to\ncircuit_qubit_inds = [[0], [0], [0, 1]]\n# Indices of parameters each parameterised gate will use\ncircuit_params_inds = [[], [0], []]\n\nqujax.print_circuit(circuit_gates, circuit_qubit_inds, circuit_params_inds);\n# q0: -----H-----Ry[0]-----◯---\n#                          |   \n# q1: ---------------------CZ--\n```\n\nTranslate the circuit to a pure function `param_to_st` that takes a set of parameters and an (optional) initial quantum state as its input.\n\n```python\nparam_to_st = qujax.get_params_to_statetensor_func(circuit_gates,\n                                                   circuit_qubit_inds,\n                                                   circuit_params_inds)\n\nparam_to_st(jnp.array([0.1]))\n# Array([[0.58778524+0.j, 0.        +0.j],\n#        [0.80901706+0.j, 0.        +0.j]], dtype=complex64)\n```\n\nThe optional initial state can be passed to `param_to_st` using the `statetensor_in` argument. When it is not provided, the initial state defaults to $\\ket{0...0}$.\n\nMap the state to an expectation value by defining an observable using lists of Pauli matrices, the qubits they act on, and the associated coefficients. \n\n```python\nst_to_expectation = qujax.get_statetensor_to_expectation_func([['Z']], [[0]], [1.])\n```\n\nCombining `param_to_st` and `st_to_expectation` gives us a parameter to expectation function that can be automatically differentiated using JAX.\n\n```python\nfrom jax import value_and_grad\n\nparam_to_expectation = lambda param: st_to_expectation(param_to_st(param))\nexpectation_and_grad = value_and_grad(param_to_expectation)\nexpectation_and_grad(jnp.array([0.1]))\n# (Array(-0.3090171, dtype=float32),\n#  Array([-2.987832], dtype=float32))\n```\n\nMixed state simulations are analogous to the above, but with calls to [`get_params_to_densitytensor_func`](https://cqcl.github.io/qujax/densitytensor/get_params_to_densitytensor_func.html) and [`get_densitytensor_to_expectation_func`](https://cqcl.github.io/qujax/densitytensor/get_densitytensor_to_expectation_func.html) instead.\n\nA more in-depth version of the above can be found in the [Getting started](https://cqcl.github.io/qujax/getting_started.html) section of the documentation. More advanced use-cases, including the training of parameterised quantum circuits, can be found in the [Examples](https://cqcl.github.io/qujax/examples.html) section of the documentation.\n\n## Converting from TKET\n\nA [`pytket`](https://cqcl.github.io/tket/pytket/api/) circuit can be directly converted using the [`tk_to_qujax`](https://cqcl.github.io/pytket-qujax/api/api.html#pytket.extensions.qujax.qujax_convert.tk_to_qujax) and [`tk_to_qujax_symbolic`](https://cqcl.github.io/pytket-qujax/api/api.html#pytket.extensions.qujax.qujax_convert.tk_to_qujax_symbolic) functions in the [**`pytket-qujax`**](https://github.com/CQCL/pytket-qujax) extension. See [`pytket-qujax_heisenberg_vqe.ipynb`](https://github.com/CQCL/pytket/blob/main/examples/pytket-qujax_heisenberg_vqe.ipynb) for an example.\n\n## Contributing\n\nYou can open a bug report or a feature request by creating a new [issue on GitHub](https://github.com/CQCL/qujax/issues).\n\nPull requests are welcome! To open a new one, please go through the following steps:\n\n1. First fork the repo and create your branch from [`develop`](https://github.com/CQCL/qujax/tree/develop).\n2. Commit your code and tests.\n4. Update the documentation, if required.\n5. Check the code lints (run `black . --check` and `pylint */`).\n6. Issue a pull request into the [`develop`](https://github.com/CQCL/qujax/tree/develop) branch.\n\nNew commits on [`develop`](https://github.com/CQCL/qujax/tree/develop) will be merged into\n[`main`](https://github.com/CQCL/qujax/tree/main) in the next release.\n\n\n## Citing qujax\n\nIf you have used qujax in your code or research, we kindly ask that you cite it. You can use the following BibTeX entry for this:\n\n```bibtex\n@article{qujax2023,\n  author = {Duffield, Samuel and Matos, Gabriel and Johannsen, Melf},\n  doi = {10.21105/joss.05504},\n  journal = {Journal of Open Source Software},\n  month = sep,\n  number = {89},\n  pages = {5504},\n  title = {{qujax: Simulating quantum circuits with JAX}},\n  url = {https://joss.theoj.org/papers/10.21105/joss.05504},\n  volume = {8},\n  year = {2023}\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcqcl%2Fqujax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcqcl%2Fqujax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcqcl%2Fqujax/lists"}