# <!-- H1 title omitted because our logo acts as the title. -->
<div align="center">
<img width="280px" height="135px" alt="Cirq logo"
src="https://raw.githubusercontent.com/quantumlib/Cirq/refs/heads/main/docs/images/Cirq_logo_color.svg">
Python package for writing, manipulating, and running [quantum
circuits](https://en.wikipedia.org/wiki/Quantum_circuit) on quantum computers
and simulators.
[](https://github.com/quantumlib/Cirq/blob/main/LICENSE)
[](https://www.python.org/downloads/)
[](https://www.bestpractices.dev/projects/10063)
[](https://pypi.org/project/cirq)
[](https://doi.org/10.5281/zenodo.4062499)
[Features](#features) –
[Installation](#installation) –
[Quick Start](#quick-start--hello-qubit-example) –
[Documentation](#cirq-documentation) –
[Integrations](#integrations) –
[Community](#community) –
[Citing Cirq](#citing-cirq) –
[Contact](#contact)
</div>
## Features
Cirq provides useful abstractions for dealing with today’s [noisy
intermediate-scale quantum](https://arxiv.org/abs/1801.00862) (NISQ) computers,
where the details of quantum hardware are vital to achieving state-of-the-art
results. Some of its features include:
* Flexible gate definitions and custom gates
* Parameterized circuits with symbolic variables
* Circuit transformation, compilation and optimization
* Hardware device modeling
* Noise modeling
* Multiple built-in quantum circuit simulators
* Integration with [qsim](https://github.com/quantumlib/qsim) for
high-performance simulation
* Interoperability with [NumPy](https://numpy.org) and
[SciPy](https://scipy.org)
* Cross-platform compatibility
## Installation
Cirq supports Python version 3.10 and later, and can be used on Linux, MacOS,
and Windows, as well as [Google Colab](https://colab.google). For complete
installation instructions, please refer to the
[Install](https://quantumai.google/cirq/start/install) section of the online
Cirq documentation.
## Quick Start – “Hello Qubit” Example
Here is a simple example to get you up and running with Cirq after you have
installed it. Start a Python interpreter, and then type the following:
```python
import cirq
# Pick a qubit.
qubit = cirq.GridQubit(0, 0)
# Create a circuit.
circuit = cirq.Circuit(
cirq.X(qubit)**0.5, # Square root of NOT.
cirq.measure(qubit, key='m') # Measurement.
)
print("Circuit:")
print(circuit)
# Simulate the circuit several times.
simulator = cirq.Simulator()
result = simulator.run(circuit, repetitions=20)
print("Results:")
print(result)
```
Python should then print output similar to this:
```text
Circuit:
(0, 0): ───X^0.5───M('m')───
Results:
m=11000111111011001000
```
Congratulations! You have run your first quantum simulation in Cirq. You can
continue to learn more by exploring the [many Cirq tutorials](#tutorials)
described below.
## Cirq Documentation
The primary documentation site for Cirq is the [Cirq home page on the Quantum
AI website](https://quantumai.google/cirq). There and elsewhere, a variety of
documentation for Cirq is available.
### Tutorials
* [Video tutorials] on YouTube are an engaging way to learn Cirq.
* [Jupyter notebook-based tutorials] let you learn Cirq from your browser – no
installation needed.
* [Text-based tutorials] on the Cirq home page are great when combined with a
local [installation] of Cirq on your computer. After starting with the
[basics], you'll be ready to dive into tutorials on circuit building and
circuit simulation under the [Build] and [Simulate] tabs, respectively. Check
out the other tabs for more!
[Video tutorials]: https://www.youtube.com/playlist?list=PLpO2pyKisOjLVt_tDJ2K6ZTapZtHXPLB4
[Jupyter notebook-based tutorials]: https://colab.research.google.com/github/quantumlib/Cirq
[Text-based tutorials]: https://quantumai.google/cirq
[installation]: https://quantumai.google/cirq/start/install
[basics]: https://quantumai.google/cirq/start/basics
[Build]: https://quantumai.google/cirq/build
[Simulate]: https://quantumai.google/cirq/simula
### Reference Documentation
* Docs for the [current stable release] correspond to what you get with
`pip install cirq`.
* Docs for the [pre-release] correspond to what you get with
`pip install --upgrade cirq~=1.0.dev`.
[current stable release]: https://quantumai.google/reference/python/cirq/all_symbols
[pre-release]: https://quantumai.google/reference/python/cirq/all_symbols?version=nightly
### Examples
* The [examples subdirectory](./examples/) of the Cirq GitHub repo has many
programs illustrating the application of Cirq to everything from common
textbook algorithms to more advanced methods.
* The [Experiments page](https://quantumai.google/cirq/experiments/) on the
Cirq documentation site has yet more examples, from simple to advanced.
### Change log
* The [Cirq releases](https://github.com/quantumlib/cirq/releases) page on
GitHub lists the changes in each release.
## Integrations
Google Quantum AI has a suite of open-source software that lets you do more
with Cirq. From high-performance simulators, to novel tools for expressing and
analyzing fault-tolerant quantum algorithms, our software stack lets you
develop quantum programs for a variety of applications.
<div align="center">
| Your interests | Software to explore |
|-------------------------------------------------|----------------------|
| Quantum algorithms?<br>Fault-tolerant quantum computing (FTQC)? | [Qualtran] |
| Large circuits and/or a lot of simulations? | [qsim] |
| Circuits with thousands of qubits and millions of Clifford operations? | [Stim] |
| Quantum error correction (QEC)? | [Stim] |
| Chemistry and/or material science? | [OpenFermion]<br>[OpenFermion-FQE]<br>[OpenFermion-PySCF]<br>[OpenFermion-Psi4] |
| Quantum machine learning (QML)? | [TensorFlow Quantum] |
| Real experiments using Cirq? | [ReCirq] |
</div>
[Qualtran]: https://github.com/quantumlib/qualtran
[qsim]: https://github.com/quantumlib/qsim
[Stim]: https://github.com/quantumlib/stim
[OpenFermion]: https://github.com/quantumlib/openfermion
[OpenFermion-FQE]: https://github.com/quantumlib/OpenFermion-FQE
[OpenFermion-PySCF]: https://github.com/quantumlib/OpenFermion-PySCF
[OpenFermion-Psi4]: https://github.com/quantumlib/OpenFermion-Psi4
[TensorFlow Quantum]: https://github.com/tensorflow/quantum
[ReCirq]: https://github.com/quantumlib/ReCirq
## Community
<a href="https://github.com/quantumlib/Cirq/graphs/contributors"><img
width="150em" alt="Total number of contributors to Cirq"
src="https://img.shields.io/github/contributors/quantumlib/cirq?label=Contributors&logo=github&color=ccc&style=flat-square"/></a>
Cirq has benefited from [contributions] by over 200 people and
counting. We are dedicated to cultivating an open and inclusive community to
build software for quantum computers, and have a community [code of conduct].
[contributions]: https://github.com/quantumlib/Cirq/graphs/contributors
[code of conduct]: https://github.com/quantumlib/cirq/blob/main/CODE_OF_CONDUCT.md
### Announcements
Stay on top of Cirq developments using the approach that best suits your needs:
* For releases and major announcements: sign up to the low-volume mailing list
[`cirq-announce`].
* For releases only:
* Via GitHub notifications: configure [repository notifications] for Cirq.
* Via Atom/RSS from GitHub: subscribe to the GitHub [Cirq releases Atom feed].
* Via RSS from PyPI: subscribe to the [PyPI releases RSS feed] for Cirq.
Cirq releases take place approximately every quarter.
[`cirq-announce`]: https://groups.google.com/forum/#!forum/cirq-announce
[repository notifications]: https://docs.github.com/github/managing-subscriptions-and-notifications-on-github/configuring-notifications
[Cirq releases Atom feed]: https://github.com/quantumlib/Cirq/releases.atom
[PyPI releases RSS feed]: https://pypi.org/rss/project/cirq/releases.xml
### Questions and Discussions
* Have questions about Cirq? Post them to the [Quantum Computing
Stack Exchange] and tag them with [`cirq`]. You can also search past
questions using that tag – it's a great way to learn!
* Want meet other Cirq developers and participate in discussions? Join
_Cirq Cynq_, our biweekly virtual meeting of contributors. Sign up
to [_cirq-dev_] to get an automatic meeting invitation!
[Quantum Computing Stack Exchange]: https://quantumcomputing.stackexchange.com
[`cirq`]: https://quantumcomputing.stackexchange.com/questions/tagged/cirq
[_cirq-dev_]: https://groups.google.com/forum/#!forum/cirq-dev
### Contributions
* Have a feature request or bug report? [Open an issue on GitHub]!
* Want to develop Cirq code? Look at the [list of good first issues] to
tackle, read our [contribution guidelines], and then start opening
[pull requests]!
[Open an issue on GitHub]: https://github.com/quantumlib/Cirq/issues/new/choose
[list of good first issues]: https://github.com/quantumlib/Cirq/contribute
[contribution guidelines]: https://github.com/quantumlib/cirq/blob/main/CONTRIBUTING.md
[pull requests]: https://help.github.com/articles/about-pull-requests
## Citing Cirq<a name="how-to-cite-cirq"></a>
When publishing articles or otherwise writing about Cirq, please cite the Cirq
version you use – it will help others reproduce your results. We use Zenodo to
preserve releases. The following links let you download the bibliographic
record for the latest stable release of Cirq in some popular formats:
<div align="center">
[](https://citation.doi.org/format?doi=10.5281/zenodo.4062499&style=bibtex)
[](https://citation.doi.org/metadata?doi=10.5281/zenodo.4062499)
</div>
For formatted citations and records in other formats, as well as records for
all releases of Cirq past and present, please visit the [Cirq page on
Zenodo](https://doi.org/10.5281/zenodo.4062499).
## Contact
For any questions or concerns not addressed here, please email
<quantum-oss-maintainers@google.com>.
## Disclaimer
Cirq is not an official Google product. Copyright 2019 The Cirq Developers.
Raw data
{
"_id": null,
"home_page": "http://github.com/quantumlib/cirq",
"name": "cirq",
"maintainer": "Google Quantum AI open-source maintainers",
"docs_url": null,
"requires_python": ">=3.10.0",
"maintainer_email": "quantum-oss-maintainers@google.com",
"keywords": "algorithms, api, cirq, google, google quantum, nisq, python, quantum, quantum algorithms, quantum circuit, quantum circuit simulator, quantum computer simulator, quantum computing, quantum development kit, quantum information, quantum programming, quantum programming language, quantum simulation, sdk, simulation",
"author": "The Cirq Developers",
"author_email": "cirq-dev@googlegroups.com",
"download_url": null,
"platform": null,
"description": "# <!-- H1 title omitted because our logo acts as the title. -->\n\n<div align=\"center\">\n<img width=\"280px\" height=\"135px\" alt=\"Cirq logo\"\nsrc=\"https://raw.githubusercontent.com/quantumlib/Cirq/refs/heads/main/docs/images/Cirq_logo_color.svg\">\n\nPython package for writing, manipulating, and running [quantum\ncircuits](https://en.wikipedia.org/wiki/Quantum_circuit) on quantum computers\nand simulators.\n\n[](https://github.com/quantumlib/Cirq/blob/main/LICENSE)\n[](https://www.python.org/downloads/)\n[](https://www.bestpractices.dev/projects/10063)\n[](https://pypi.org/project/cirq)\n[](https://doi.org/10.5281/zenodo.4062499)\n\n[Features](#features) –\n[Installation](#installation) –\n[Quick Start](#quick-start--hello-qubit-example) –\n[Documentation](#cirq-documentation) –\n[Integrations](#integrations) –\n[Community](#community) –\n[Citing Cirq](#citing-cirq) –\n[Contact](#contact)\n\n</div>\n\n## Features\n\nCirq provides useful abstractions for dealing with today\u2019s [noisy\nintermediate-scale quantum](https://arxiv.org/abs/1801.00862) (NISQ) computers,\nwhere the details of quantum hardware are vital to achieving state-of-the-art\nresults. Some of its features include:\n\n* Flexible gate definitions and custom gates\n* Parameterized circuits with symbolic variables\n* Circuit transformation, compilation and optimization\n* Hardware device modeling\n* Noise modeling\n* Multiple built-in quantum circuit simulators\n* Integration with [qsim](https://github.com/quantumlib/qsim) for\n high-performance simulation\n* Interoperability with [NumPy](https://numpy.org) and\n [SciPy](https://scipy.org)\n* Cross-platform compatibility\n\n## Installation\n\nCirq supports Python version 3.10 and later, and can be used on Linux, MacOS,\nand Windows, as well as [Google Colab](https://colab.google). For complete\ninstallation instructions, please refer to the\n[Install](https://quantumai.google/cirq/start/install) section of the online\nCirq documentation.\n\n## Quick Start \u2013 \u201cHello Qubit\u201d Example\n\nHere is a simple example to get you up and running with Cirq after you have\ninstalled it. Start a Python interpreter, and then type the following:\n\n```python\nimport cirq\n\n# Pick a qubit.\nqubit = cirq.GridQubit(0, 0)\n\n# Create a circuit.\ncircuit = cirq.Circuit(\n cirq.X(qubit)**0.5, # Square root of NOT.\n cirq.measure(qubit, key='m') # Measurement.\n)\nprint(\"Circuit:\")\nprint(circuit)\n\n# Simulate the circuit several times.\nsimulator = cirq.Simulator()\nresult = simulator.run(circuit, repetitions=20)\nprint(\"Results:\")\nprint(result)\n```\n\nPython should then print output similar to this:\n\n```text\nCircuit:\n(0, 0): \u2500\u2500\u2500X^0.5\u2500\u2500\u2500M('m')\u2500\u2500\u2500\nResults:\nm=11000111111011001000\n```\n\nCongratulations! You have run your first quantum simulation in Cirq. You can\ncontinue to learn more by exploring the [many Cirq tutorials](#tutorials)\ndescribed below.\n\n## Cirq Documentation\n\nThe primary documentation site for Cirq is the [Cirq home page on the Quantum\nAI website](https://quantumai.google/cirq). There and elsewhere, a variety of\ndocumentation for Cirq is available.\n\n### Tutorials\n\n* [Video tutorials] on YouTube are an engaging way to learn Cirq.\n* [Jupyter notebook-based tutorials] let you learn Cirq from your browser \u2013 no\n installation needed.\n* [Text-based tutorials] on the Cirq home page are great when combined with a\n local [installation] of Cirq on your computer. After starting with the\n [basics], you'll be ready to dive into tutorials on circuit building and\n circuit simulation under the [Build] and [Simulate] tabs, respectively. Check\n out the other tabs for more!\n\n[Video tutorials]: https://www.youtube.com/playlist?list=PLpO2pyKisOjLVt_tDJ2K6ZTapZtHXPLB4\n[Jupyter notebook-based tutorials]: https://colab.research.google.com/github/quantumlib/Cirq\n[Text-based tutorials]: https://quantumai.google/cirq\n[installation]: https://quantumai.google/cirq/start/install\n[basics]: https://quantumai.google/cirq/start/basics\n[Build]: https://quantumai.google/cirq/build\n[Simulate]: https://quantumai.google/cirq/simula\n\n### Reference Documentation\n\n* Docs for the [current stable release] correspond to what you get with\n `pip install cirq`.\n* Docs for the [pre-release] correspond to what you get with\n `pip install --upgrade cirq~=1.0.dev`.\n\n[current stable release]: https://quantumai.google/reference/python/cirq/all_symbols\n[pre-release]: https://quantumai.google/reference/python/cirq/all_symbols?version=nightly\n\n### Examples\n\n* The [examples subdirectory](./examples/) of the Cirq GitHub repo has many\n programs illustrating the application of Cirq to everything from common\n textbook algorithms to more advanced methods.\n* The [Experiments page](https://quantumai.google/cirq/experiments/) on the\n Cirq documentation site has yet more examples, from simple to advanced.\n\n### Change log\n\n* The [Cirq releases](https://github.com/quantumlib/cirq/releases) page on\n GitHub lists the changes in each release.\n\n## Integrations\n\nGoogle Quantum AI has a suite of open-source software that lets you do more\nwith Cirq. From high-performance simulators, to novel tools for expressing and\nanalyzing fault-tolerant quantum algorithms, our software stack lets you\ndevelop quantum programs for a variety of applications.\n\n<div align=\"center\">\n\n| Your interests | Software to explore |\n|-------------------------------------------------|----------------------|\n| Quantum algorithms?<br>Fault-tolerant quantum computing (FTQC)? | [Qualtran] |\n| Large circuits and/or a lot of simulations? | [qsim] |\n| Circuits with thousands of qubits and millions of Clifford operations? | [Stim] |\n| Quantum error correction (QEC)? | [Stim] |\n| Chemistry and/or material science? | [OpenFermion]<br>[OpenFermion-FQE]<br>[OpenFermion-PySCF]<br>[OpenFermion-Psi4] |\n| Quantum machine learning (QML)? | [TensorFlow Quantum] |\n| Real experiments using Cirq? | [ReCirq] |\n\n</div>\n\n[Qualtran]: https://github.com/quantumlib/qualtran\n[qsim]: https://github.com/quantumlib/qsim\n[Stim]: https://github.com/quantumlib/stim\n[OpenFermion]: https://github.com/quantumlib/openfermion\n[OpenFermion-FQE]: https://github.com/quantumlib/OpenFermion-FQE\n[OpenFermion-PySCF]: https://github.com/quantumlib/OpenFermion-PySCF\n[OpenFermion-Psi4]: https://github.com/quantumlib/OpenFermion-Psi4\n[TensorFlow Quantum]: https://github.com/tensorflow/quantum\n[ReCirq]: https://github.com/quantumlib/ReCirq\n\n## Community\n\n<a href=\"https://github.com/quantumlib/Cirq/graphs/contributors\"><img\nwidth=\"150em\" alt=\"Total number of contributors to Cirq\"\nsrc=\"https://img.shields.io/github/contributors/quantumlib/cirq?label=Contributors&logo=github&color=ccc&style=flat-square\"/></a>\n\nCirq has benefited from [contributions] by over 200 people and\ncounting. We are dedicated to cultivating an open and inclusive community to\nbuild software for quantum computers, and have a community [code of conduct].\n\n[contributions]: https://github.com/quantumlib/Cirq/graphs/contributors\n[code of conduct]: https://github.com/quantumlib/cirq/blob/main/CODE_OF_CONDUCT.md\n\n### Announcements\n\nStay on top of Cirq developments using the approach that best suits your needs:\n\n* For releases and major announcements: sign up to the low-volume mailing list\n [`cirq-announce`].\n* For releases only:\n * Via GitHub notifications: configure [repository notifications] for Cirq.\n * Via Atom/RSS from GitHub: subscribe to the GitHub [Cirq releases Atom feed].\n * Via RSS from PyPI: subscribe to the [PyPI releases RSS feed] for Cirq.\n\nCirq releases take place approximately every quarter.\n\n[`cirq-announce`]: https://groups.google.com/forum/#!forum/cirq-announce\n[repository notifications]: https://docs.github.com/github/managing-subscriptions-and-notifications-on-github/configuring-notifications\n[Cirq releases Atom feed]: https://github.com/quantumlib/Cirq/releases.atom\n[PyPI releases RSS feed]: https://pypi.org/rss/project/cirq/releases.xml\n\n### Questions and Discussions\n\n* Have questions about Cirq? Post them to the [Quantum Computing\n Stack Exchange] and tag them with [`cirq`]. You can also search past\n questions using that tag \u2013 it's a great way to learn!\n* Want meet other Cirq developers and participate in discussions? Join\n _Cirq Cynq_, our biweekly virtual meeting of contributors. Sign up\n to [_cirq-dev_] to get an automatic meeting invitation!\n\n[Quantum Computing Stack Exchange]: https://quantumcomputing.stackexchange.com\n[`cirq`]: https://quantumcomputing.stackexchange.com/questions/tagged/cirq\n[_cirq-dev_]: https://groups.google.com/forum/#!forum/cirq-dev\n\n### Contributions\n\n* Have a feature request or bug report? [Open an issue on GitHub]!\n* Want to develop Cirq code? Look at the [list of good first issues] to\n tackle, read our [contribution guidelines], and then start opening\n [pull requests]!\n\n[Open an issue on GitHub]: https://github.com/quantumlib/Cirq/issues/new/choose\n[list of good first issues]: https://github.com/quantumlib/Cirq/contribute\n[contribution guidelines]: https://github.com/quantumlib/cirq/blob/main/CONTRIBUTING.md\n[pull requests]: https://help.github.com/articles/about-pull-requests\n\n## Citing Cirq<a name=\"how-to-cite-cirq\"></a>\n\nWhen publishing articles or otherwise writing about Cirq, please cite the Cirq\nversion you use \u2013 it will help others reproduce your results. We use Zenodo to\npreserve releases. The following links let you download the bibliographic\nrecord for the latest stable release of Cirq in some popular formats:\n\n<div align=\"center\">\n\n[](https://citation.doi.org/format?doi=10.5281/zenodo.4062499&style=bibtex) \n[](https://citation.doi.org/metadata?doi=10.5281/zenodo.4062499)\n\n</div>\n\nFor formatted citations and records in other formats, as well as records for\nall releases of Cirq past and present, please visit the [Cirq page on\nZenodo](https://doi.org/10.5281/zenodo.4062499).\n\n## Contact\n\nFor any questions or concerns not addressed here, please email\n<quantum-oss-maintainers@google.com>.\n\n## Disclaimer\n\nCirq is not an official Google product. Copyright 2019 The Cirq Developers.\n",
"bugtrack_url": null,
"license": "Apache 2",
"summary": "A framework for creating, editing, and invoking Noisy Intermediate Scale Quantum (NISQ) circuits.",
"version": "1.5.0",
"project_urls": {
"Homepage": "http://github.com/quantumlib/cirq"
},
"split_keywords": [
"algorithms",
" api",
" cirq",
" google",
" google quantum",
" nisq",
" python",
" quantum",
" quantum algorithms",
" quantum circuit",
" quantum circuit simulator",
" quantum computer simulator",
" quantum computing",
" quantum development kit",
" quantum information",
" quantum programming",
" quantum programming language",
" quantum simulation",
" sdk",
" simulation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dbd75dff0e4d5e697118c44b702da1bdcfc85a7822adb13d8a93c4d1fd23a06e",
"md5": "006f4464b7b525cacf305e72ab1d057a",
"sha256": "c710e5be35087a6d2457dcb1ecb93a0a492a98bb3b27e8a14b8a3a9ad14dca3c"
},
"downloads": -1,
"filename": "cirq-1.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "006f4464b7b525cacf305e72ab1d057a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10.0",
"size": 10916,
"upload_time": "2025-04-10T18:06:11",
"upload_time_iso_8601": "2025-04-10T18:06:11.906823Z",
"url": "https://files.pythonhosted.org/packages/db/d7/5dff0e4d5e697118c44b702da1bdcfc85a7822adb13d8a93c4d1fd23a06e/cirq-1.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-04-10 18:06:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "quantumlib",
"github_project": "cirq",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cirq"
}
JSON
