# Technical Documentation: quantumlib/Cirq
> ℹ️ **Provenance:** Hybrid Fusion: `quantumlib/Cirq` (README + 10 In-Tree Chapters) · [CodeWiki Reference](https://codewiki.google/github.com/quantumlib/Cirq) · Recency: Active (< 180 days)
## 1. Project Overview & Quickstart (quantumlib/Cirq)
## 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.11 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/simulate
### 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.
[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
[](https://github.com/quantumlib/Cirq/graphs/contributors)
Cirq has benefited from [contributions] by over 250 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/g/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/g/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
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:
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
This is not an officially supported Google product. This project is not
eligible for the [Google Open Source Software Vulnerability Rewards
Program](https://bughunters.google.com/open-source-security).
Copyright 2019 The Cirq Developers.
## 2. In-Tree Documentation Chapters (quantumlib/Cirq)
## File: README.md
## 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.11 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/simulate
### 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.
[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
[](https://github.com/quantumlib/Cirq/graphs/contributors)
Cirq has benefited from [contributions] by over 250 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/g/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/g/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
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:
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
This is not an officially supported Google product. This project is not
eligible for the [Google Open Source Software Vulnerability Rewards
Program](https://bughunters.google.com/open-source-security).
Copyright 2019 The Cirq Developers.
---
## File: benchmarks/README.md
# Cirq Performance Benchmarks
This directory contains Cirq performance benchmarks established using the
[pytest-benchmark] plugin for pytest.
## Overview
The benchmarks are defined by the `*_perf.py` files provided in this
`benchmarks` package and its sub-folders. The benchmark definitions are
very similar to common pytest test functions, but they use an extra features
from the pytest-benchmark plugin to collect code execution times and statistics.
For more information on how to write new benchmarks, please refer to
existing benchmark files and to the [pytest-benchmark] documentation
## Usage
To run all benchmarks, navigate to the root Cirq directory in
a shell and execute the following command:
```bash
pytest -p no:randomly --override-ini="python_files=*_perf.py" \
--benchmark-enable ./benchmarks
```
This will run the entire benchmark suite which takes approximately
30 minutes. Note that it is important to pass the `--benchmark-enable`
option as otherwise the code would run as a standard one-shot
pytest and would not collect timing statistics (this may be preferable
for benchmark development). Some of the benchmarks are labeled with
the `slow` marker and are by default deselected in a standard benchmark
session. The `slow` marker is applied for larger sizes of parametrized
benchmarks, which are also covered at smaller computational scales, and
are thus not critical for assessing performance trends.
That said, to execute all benchmarks including the `slow` ones, use
```bash
pytest -p no:randomly --override-ini="python_files=*_perf.py" \
--benchmark-enable --enable-slow-tests ./benchmarks
```
Finally, to run a single specific benchmark and save its results
for later comparison, use the `--benchmark-autosave` option together
with the pytest identifier of the benchmark, for example,
```bash
pytest -p no:randomly --benchmark-enable \
--benchmark-enable --benchmark-autosave \
"benchmarks/linalg_decompositions_perf.py::test_kak_decomposition[CNOT]"
```
Please refer to the [pytest-benchmark] documentation for further instructions
on comparing and visualizing benchmark results.
## Results Database
TODO: b/393456969 - provide pointers to the internal results database
[pytest-benchmark]: https://pytest-benchmark.readthedocs.io/en/latest
---
## File: cirq-aqt/README.md
# cirq-aqt
This is the Cirq-AQT integration module. It provides an interface that allows
[Cirq] quantum algorithms to run on quantum computers made by [Alpine Quantum
Technologies GmbH](https://www.aqt.eu). (See the [Documentation](#documentation)
section below for information about getting access to AQT devices.)
[Cirq] is a Python package for writing, manipulating, and running [quantum
circuits](https://en.wikipedia.org/wiki/Quantum_circuit) on quantum computers
and simulators. 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. For more information about Cirq, please visit the
[Cirq documentation site].
[Cirq]: https://github.com/quantumlib/cirq
[Cirq documentation site]: https://quantumai.google/cirq
## Installation
This module is built on top of [Cirq]; installing this module will
automatically install the `cirq-core` module and other dependencies. There are
two installation options for the `cirq-aqt` module:
* To install the stable version of `cirq-aqt`, use
```shell
pip install cirq-aqt
```
* To install the latest pre-release version of `cirq-aqt`, use
```shell
pip install --upgrade cirq-aqt~=1.0.dev
```
(The `~=` has a special meaning to `pip` of selecting the latest version
compatible with the `1.*` and `dev` in the name. Despite appearances,
this will not install an old version 1.0 release!)
If you would like to install Cirq with all the optional modules, not just
`cirq-aqt`, then instead of the above commands, use `pip install cirq` for the
stable release or `pip install --upgrade cirq~=1.0.dev` for the latest pre-release
version.
## Documentation
To get started with using AQT quantum computers through Cirq, please refer to
the following documentation:
* [Access and authentication](https://quantumai.google/cirq/aqt/access).
* [Getting started
guide](https://quantumai.google/cirq/tutorials/aqt/getting_started).
To get started with using Cirq in general, please refer to the [Cirq
documentation site].
For more information about getting help, reporting bugs, and other matters
related to Cirq and the Cirq-AQT integration module, please visit the [Cirq
repository on GitHub](https://github.com/quantumlib/Cirq).
## Disclaimer
Cirq is not an official Google product. Copyright 2019 The Cirq Developers.
---
## File: cirq-core/README.md
# cirq-core
[Cirq] is a Python package for writing, manipulating, and running [quantum
circuits](https://en.wikipedia.org/wiki/Quantum_circuit) on quantum computers
and simulators. 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. For more information about Cirq, please visit the
[Cirq documentation site].
This Python module is `cirq-core`, which contains all the code you need to
write quantum algorithms for NISQ devices and run them on the built-in Cirq
simulators.
To run algorithms on a given quantum computing platform, you will also need to
install an appropriate Cirq hardware interface module. Please visit the
[hardware section of the Cirq documentation
site](https://quantumai.google/cirq/hardware) for information about the
hardware interface modules currently available.
[Cirq]: https://github.com/quantumlib/cirq
[Cirq documentation site]: https://quantumai.google/cirq
## Installation
There are two installation options for the `cirq-core` module:
* To install the stable version of `cirq-core`, use
```shell
pip install cirq-core
```
* To install the latest pre-release version of `cirq-core`, use
```shell
pip install --upgrade cirq-core~=1.0.dev
```
(The `~=` has a special meaning to `pip` of selecting the latest version
compatible with the `1.*` and `dev` in the name. Despite appearances,
this will not install an old version 1.0 release!)
If you would like to install Cirq with all the optional modules, not just
`cirq-core`, then instead of the above commands, use `pip install cirq` for the
stable release or `pip install --upgrade cirq~=1.0.dev` for the latest pre-release
version.
## Documentation
To get started with using Cirq, please refer to the [Cirq documentation site].
For more information about getting help, reporting bugs, and other matters
related to Cirq and the Cirq-Core integration module, please visit the [Cirq
repository on GitHub](https://github.com/quantumlib/Cirq).
## Disclaimer
Cirq is not an official Google product. Copyright 2019 The Cirq Developers.
---
## File: cirq-google/cirq_google/devices/specifications/README.md
# Device specifications of Google quantum processors
This directory contains snapshots of `DeviceSpecification` proto messages
(defined in `cirq-google/cirq_google/api/v2/device.proto`) describing Google
devices.
Files with the suffix `_for_grid_device` are equivalent representations of
corresponding proto files without the suffix, but in the new
`DeviceSpecification` format which is parsed into `cirq_google.GridDevice`.
---
## File: cirq-google/README.md
# cirq-google
This is the Cirq-Google integration module. It provides an interface to
Google's [Quantum Computing
Service](https://quantumai.google/cirq/google/concepts), and also contains
additional tools for calibration and characterization of Google's quantum
hardware devices.
| Please note! |
|:--------------------:|
| Google's quantum hardware is currently available only to authorized partners. Access requires an application, usually with a Google sponsor.|
[Cirq] is a Python package for writing, manipulating, and running [quantum
circuits](https://en.wikipedia.org/wiki/Quantum_circuit) on quantum computers
and simulators. 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. For more information about Cirq, please visit the
[Cirq documentation site].
[Cirq]: https://github.com/quantumlib/cirq
[Cirq documentation site]: https://quantumai.google/cirq
## Installation
This module is built on top of [Cirq]; installing this module will
automatically install `cirq-core` and other dependencies. There are two
installation options for the `cirq-google` module:
* To install the stable version of `cirq-google`, use
```shell
pip install cirq-google
```
* To install the latest pre-release version of `cirq-google`, use
```shell
pip install --upgrade cirq-google~=1.0.dev
```
(The `~=` has a special meaning to `pip` of selecting the latest version
compatible with the `1.*` and `dev` in the name. Despite appearances,
this will not install an old version 1.0 release!)
If you would like to install Cirq with all the optional modules, not just
`cirq-google`, then instead of the above commands, use `pip install cirq` for
the stable release or `pip install --upgrade cirq~=1.0.dev` for the latest pre-release
version.
## Documentation
To get started with using Google quantum computers through Cirq, please refer to
the following documentation:
* [Access and authentication](https://quantumai.google/cirq/google/access).
* [Getting started
guide](https://quantumai.google/cirq/tutorials/google/start).
To get started with using Cirq in general, please refer to the [Cirq
documentation site].
For more information about getting help, reporting bugs, and other matters
related to Cirq and the Cirq-Core integration module, please visit the [Cirq
repository on GitHub](https://github.com/quantumlib/Cirq).
## Disclaimer
Cirq is not an official Google product. Copyright 2019 The Cirq Developers.
---
## File: cirq-ionq/README.md
# cirq-ionq
This is the Cirq-IonQ integration module. It provides an interface that allows
[Cirq] quantum algorithms to run on quantum computers made by [IonQ
Inc.](https://ionq.com/). (See the [Documentation](#documentation) section
below for information about getting access to IonQ devices.)
[Cirq] is a Python package for writing, manipulating, and running [quantum
circuits](https://en.wikipedia.org/wiki/Quantum_circuit) on quantum computers
and simulators. 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. For more information about Cirq, please visit the
[Cirq documentation site].
[Cirq]: https://github.com/quantumlib/cirq
[Cirq documentation site]: https://quantumai.google/cirq
## Installation
This module is built on top of [Cirq]; installing this module will
automatically install the `cirq-core` module and other dependencies. There are
two installation options for the `cirq-ionq` module:
* To install the stable version of `cirq-ionq`, use
```shell
pip install cirq-ionq
```
* To install the latest pre-release version of `cirq-ionq`, use
```shell
pip install --upgrade cirq-ionq~=1.0.dev
```
(The `~=` has a special meaning to `pip` of selecting the latest version
compatible with the `1.*` and `dev` in the name. Despite appearances,
this will not install an old version 1.0 release!)
If you would like to install Cirq with all the optional modules, not just
`cirq-ionq`, then instead of the above commands, use `pip install cirq` for the
stable release or `pip install --upgrade cirq~=1.0.dev` for the latest pre-release
version.
## Documentation
To get started with using IonQ quantum computers through Cirq, please refer to
the following documentation:
* [Access and authentication](https://quantumai.google/cirq/ionq/access).
* [Getting started
guide](https://quantumai.google/cirq/tutorials/ionq/getting_started).
To get started with using Cirq in general, please refer to the [Cirq
documentation site].
For more information about getting help, reporting bugs, and other matters
related to Cirq and the Cirq-IonQ integration module, please visit the [Cirq
repository on GitHub](https://github.com/quantumlib/Cirq).
## Disclaimer
Cirq is not an official Google product. Copyright 2019 The Cirq Developers.
---
## File: cirq-pasqal/README.md
# cirq-pasqal
This is the Cirq-Pasqal integration module. It provides an interface that
allows [Cirq] quantum algorithms to run on quantum computers made by
[Pasqal](https://pasqal.com/). (See the [Documentation](#documentation) section
below for information about getting access to Pasqal devices.)
[Cirq] is a Python package for writing, manipulating, and running [quantum
circuits](https://en.wikipedia.org/wiki/Quantum_circuit) on quantum computers
and simulators. 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. For more information about Cirq, please visit the
[Cirq documentation site].
[Cirq]: https://github.com/quantumlib/cirq
[Cirq documentation site]: https://quantumai.google/cirq
## Installation
This module is built on top of [Cirq]; installing this module will
automatically install the `cirq-core` module and other dependencies. There are
two installation options for the `cirq-pasqal` module:
* To install the stable version of `cirq-pasqal`, use
```shell
pip install cirq-pasqal
```
* To install the latest pre-release version of `cirq-pasqal`, use
```shell
pip install --upgrade cirq-pasqal~=1.0.dev
```
(The `~=` has a special meaning to `pip` of selecting the latest version
compatible with the `1.*` and `dev` in the name. Despite appearances,
this will not install an old version 1.0 release!)
If you would like to install Cirq with all the optional modules, not just
`cirq-pasqal`, then instead of the above commands, use `pip install cirq` for the
stable release or `pip install --upgrade cirq~=1.0.dev` for the latest pre-release
version.
## Documentation
To get started with using Pasqal quantum computers through Cirq, please refer to
the following documentation:
* [Access and authentication](https://quantumai.google/cirq/pasqal/access).
* [Getting started
guide](https://quantumai.google/cirq/tutorials/pasqal/getting_started).
To get started with using Cirq in general, please refer to the [Cirq
documentation site].
For more information about getting help, reporting bugs, and other matters
related to Cirq and the Cirq-Pasqal integration module, please visit the [Cirq
repository on GitHub](https://github.com/quantumlib/Cirq).
## Disclaimer
Cirq is not an official Google product. Copyright 2019 The Cirq Developers.
---
## File: cirq-web/cirq_web/README.md
## Cirq Visualizations
_This section contains instructions for calling Typescript
visualization in Cirq using Python._
The `cirq_web` package runs separately from the rest of Cirq, and can be used
on an opt-in basis with the rest of the project.
### Module build structure
A reference for the build structure of a module is the Bloch sphere. Reference
the `bloch_sphere/` directory to see the code. Modules should:
* Abide by Cirq convention in terms of testing, styling, and initialization
files.
* Contain a "root" folder labeled according to the title of the module. In
the case of the Bloch sphere, this is `bloch_sphere/`.
* Contain a main class that contains the code for the visualization. All
supporting files should be imported into this class. In the case of the
Bloch sphere, this is `bloch_sphere.py`.
* Make sure that any additional modules and files are in separate
subdirectories labeled accordingly.
### Developing Python modules for visualization
In order to actually get visualization output from our Python calls, we return
strings of HTML and Javascript. In order to keep things organized, we include a
parent class `Widget` (`widget.py`) which handles the configuration behind
locating and reading files so that only code specific to each visualization
lives in its main class.
The main class for all visualizations should inherit from the `Widget` class
located in this directory. Upon creating a new Widget, you should include a
call to initialize the parent like so:
```python
class MyWidget(widget.Widget):
def __init__(self,...):
...
super().__init__()
...
```
This ensures that your widget has the standard functionality of all Cirq
visualization widgets, including:
* A unique id for each instance of your visualization.
* Magic method so that your visualization can be displayed in a Colab/Jupyter
notebook.
* The ability to generate a standalone HTML file with your visualization.
`Widget` is an abstract class with methods `get_client_code()` and
`get_widget_bundle_name()` that need to be implemented in your visualization as
well. Failure to implement these will lead to a `NotImplementedError` at
runtime. Instructions on how to properly implement these methods are in the
next section.
### Handling HTML output from Python
In your individual visualizations class, you only need to handle two things:
1. The client code that's unique to your visualization.
2. The name of the bundle file.
```python
from cirq_web import widget
class MyWidget(widget.Widget):
...
def get_client_code(self) -> str:
return f"""
"""
def get_widget_bundle_name(self) -> str:
return 'YOUR_BUNDLE_FILE.bundle.js'
```
`Widget` will take this information and organize it so that it can be properly displayed.
#### Viewing a visualization in a notebook setting
We capitalize on IPython's `_repr_html_` magic method to help display
visualizations in the notebook. This will allow your visualization to be
displayed in a notebook cell with:
```python
widget = MyWidget()
display(widget)
```
#### Generating a standalone HTML file from a visualization
You can generate a standalone HTML file of your visualization like so:
```python
widget = MyWidget()
output_directory = './'
file_name = 'YOUR_VIZ.html'
open_in_browser = False
widget.generate_html_file(output_directory, file_name, open_in_browser)
```
This code above writes a file named `YOUR_VIZ.html` to the specified output
directory, returning the path of the file as a string. If the `open_in_browser`
flag is used, Python will automatically open your visualization in a new tab
using the default browser on your computer.
The important thing about generating standalone HTML files is that they can be
sent and viewed anywhere, regardless of whether the recipient has Cirq
installed on their computer or not.
## Cirq Typescript Development
_This section contains the instructions for visualization tools in
a web browser or Colab/Juptyer notebooks. We do this using Typescript._
Visualizations run on [NodeJS](https://nodejs.org/en/), and we use
[npm](https://www.npmjs.com/) for package management. To start developing,
clone the Cirq repository and run `npm install` within this directory, or
`check/npm install` from the top level directory, to install the necessary
packages and begin development. You will need to install Node and npm if you
haven't already.
For developing 3D visualizations, we rely on the
[three.js](https://threejs.org/) framework.
For bundling the Typescript into Javascript that can be run in the browser,
and for overall ease of development, we use
[Webpack](https://webpack.js.org/).
As an additional note, all `npm` and `npx` commands can be run from the
top-level of Cirq like so:
```bash
# check/npm runs npm --prefix 'cirq-web/cirq_web` and forwards arguments
check/npm [YOUR_COMMAND]
# check/npx navigates to this directory and runs from there
check/npx [YOUR_COMMAND]
```
### Visualization build structure
The reference example for the build structure of a visualization is the Bloch
sphere. Reference the `src/bloch_sphere/main.ts` file and the
`src/bloch_sphere/bloch_sphere.ts` file to see the code. The
`src/bloch_sphere/` directory should serve as a guide for how Typescript
visualizations in Cirq should be structured. Visualizations should have:
* A "root" folder within the `src/` directory labeled according to the
title of the visualization. All files and directories for a particular
visualization will live here. In the case of the Bloch Sphere, this is
`bloch_sphere/`.
* A `components/` directory which contains classes representing different
components of the larger visualization, following typical object oriented
programming techniques. In the case of the Bloch sphere, you can see that
we have different classes for `Axes`, `Meridians`, `Text` etc.
* Any `assets/` directory with information necessary for the visualization
(fonts, images, etc.). In the case of the Bloch Sphere, we can see a
`fonts/` subdirectory which holds necessary font data, within the
`assets/` directory, but for instances where there isn't a lot of extra
information necessary subdirectories may not be needed.
* A class within the visualization's "root" folder which brings the
individual components of the visualization together. In the case of the
Bloch Sphere, this is `bloch_sphere.ts`.
* A `main.ts` consisting of functions which will be called from the bundled
library. These function should handle:
* Receiving any input data which could affect the visualization.
* Sending final visualization output to the development environment,
notebook, or HTML files.
* Combining aspects of the visualization that need to be added separately.
This `main.ts` file will also need to be added as an entry point in the
`webpack.config.js` file in order for your visualization to be bundled
accordingly.
```javascript
module.exports = {
entry: {
bloch_sphere: './src/bloch_sphere/main.ts',
...
YOUR_VIZ_NAME: './src/YOUR_VIZ_NAME/main.ts',
},
...
};
```
You can learn more about Webpack entry points here: [Webpack Entry
Points](https://webpack.js.org/concepts/entry-points/).
### Creating visualization bundle files
Following this structure, you will be able to bundle your visualization by
running the command `npx webpack --mode production` in this directory, or
`check/ts-build` from the top-level directory. This will build the bundled
Javascript file(s) within the `dist/` directory, where you can access and
reference them in HTML.
### Developing visualizations
There are two main ways to develop visualizations you are creating in Cirq.
The first, and recommended way, is to spin up a Webpack development server and
view your visualizations in the browser. You can also develop using Jupyter
notebook if you want to easily test integration with Python code.
#### Hot reloading development server (Recommended)
Using `webpack-dev-server`, we are able to develop and test visualizations in
the browser and have changes update as we're writing the code. You can start
this server by running `npm run start` in this directory, and view your work
on the port specified by Webpack. This method also requires an `index.html`
file placed within the `dist` folder. You can also manually determine where
your index file is served from by modifying where `webpack-dev-server`
searches for files in the `webpack.config.js` file:
```javascript
module.exports = {
...
devServer: {
static: path.join(__dirname, 'dist'),
public: 'localhost:8080',
},
...
};
```
Note that the bundled files that `webpack-dev-server` creates live in memory,
so you won't be able to find them on the file system.
```html
```
Note that you can also inspect the bundle Javascript from the browser by
navigating to `http://localhost:8080/YOUR_VIZ_NAME.bundle.js`.
### Developing in a Jupyter Notebook
An alternative to developing using `webpack-dev-server` is to bundle the
Typescript and reference the Javascript output. You can spin up a notebook
server with `jupyter notebook`, and bundle (while watching for live changes
and updating accordingly) with `npx webpack --mode production --watch`. These
processes must run simultaneously. This is especially useful for if you want
to work with integrating Python code into your visualization. There's an
example notebook `example.ipynb` that provides an example on how to do this.
**NOTE:** In order to access the bundled javascript, you need to include the
full path to it: `cirq_web/dist/YOUR_VIZ_NAME.bundle.js`. If you make any
changes to the directory structure, take into account that the path may change
as well.
### Developing in Google Colaboratory
We currently do not support developing visualizations in Google Colaboratory
notebooks. However, visualization ran from the PyPI package are able to be
viewed in Colab.
### Formatting and linting
All Typescript files need to be formatted/linted according to [Google's public
Typescript style guide](https://google.github.io/styleguide/tsguide.html). We
use Google's open source tool [GTS](https://github.com/google/gts) to handle
this for you. Run `npm run fix` to handle fixing changes automatically, or
refer to the `package.json` file for more options.
### Testing
We expect developed visualizations to be well tested. The Cirq typescript
development environment requires two types of tests for any created
visualization, unit testing and visualization testing. Unit testing ensures
that the Typescript you wrote compiles correctly and generates the appropriate
Three.js objects without breaking the rest of your code. Visualization testing
actually compares the visualizations by building the visualization, taking a
PNG screenshot, and comparing it to an expected PNG.
We use [Mocha](https://mochajs.org) and [Chai](https://www.chaijs.com/) as our
main testing tools. For comparing image diffs, we use
[Pixelmatch](https://github.com/mapbox/pixelmatch) and
[pngjs](https://github.com/lukeapage/pngjs).
#### Unit testing
Run unit tests using `npm run test`. We expect 100% code coverage for unit
tests. You can check coverage by running `npm run coverage`.
Unit tests must live adjacent to their source file with the `_test.ts` suffix.
So for the file `dir/MyFile.ts`, the corresponding testfile will be
`dir/MyFile_test.ts`.
#### Visualization testing
We take the following steps for visualization testing in our development
environment:
1. We generate an generic HTML file with the specified visualization's
current JS bundle.
2. We run the HTML file in a headless browser using
[Puppeteer](https://github.com/puppeteer/puppeteer).
3. We take a screenshot of the HTML output in the "browser" using Puppeteer.
4. We compare the result of the screenshot with a pre-generated PNG file.
The screenshot of the HTML browser output must live in a temporary directory;
we use the [temp](https://github.com/bruce/node-temp) package to handle that
for us. Reference the test at `e2e/bloch_sphere/bloch_sphere_e2e_test.ts` to
see how to easily generate the screenshot in a temporary directory.
The pre-generated PNG file is a screenshot of the developer's choice that
represents what the visualization should look like. Each visualization is
required to have at least one expected PNG screenshot. For more complex
visualizations, multiple screenshots may be needed.
---
## File: cirq-web/README.md
# cirq-web
[Cirq] is a Python package for writing, manipulating, and running [quantum
circuits](https://en.wikipedia.org/wiki/Quantum_circuit) on quantum computers
and simulators. 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. For more information about Cirq, please visit the
[Cirq documentation site].
This Python module is `cirq-web`, which allows users to take advantage of
browser-based 3D visualization tools and features in Cirq. `cirq-web` also
provides a development environment for contributors to create and add their
own visualizations to the module.
[Cirq]: https://github.com/quantumlib/cirq
[Cirq documentation site]: https://quantumai.google/cirq
## Installation
This module is built on top of [Cirq]; installing this module will
automatically install the `cirq-core` module and other dependencies. There are
two installation options for the `cirq-web` module:
* To install the stable version of `cirq-web`, use
```shell
pip install cirq-web
```
* To install the latest pre-release version of `cirq-web`, use
```shell
pip install --upgrade cirq-web~=1.0.dev
```
(The `~=` has a special meaning to `pip` of selecting the latest version
compatible with the `1.*` and `dev` in the name. Despite appearances,
this will not install an old version 1.0 release!)
If you would like to install Cirq with all the optional modules, not just
`cirq-web`, then instead of the above commands, use `pip install cirq` for the
stable release or `pip install --upgrade cirq~=1.0.dev` for the latest pre-release
version.
## Documentation
Documentation for `cirq-web` can be found in the `README` file located in the
module's subdirectory in the [Cirq repository on GitHub]. To get started
with using Cirq in general, please refer to the [Cirq documentation site].
Below is a quick example of using `cirq-web` to generate a portable 3D
rendering of the Bloch sphere:
```python
import cirq
from cirq_web import BlochSphere
# Prepare a state
zero_state = [1+0j, 0+0j]
state_vector = cirq.to_valid_state_vector(zero_state)
# Create and display the Bloch sphere
sphere = BlochSphere(state_vector=state_vector)
sphere.generate_html_file()
```
This will create an HTML file in the current working directory. There are
additional options to specify the output directory or to open the
visualization in a browser, for example.
You can also view and interact with a Bloch sphere in a [Google
Colab](https://colab.google.com) notebook or Jupyter notebook. Here is an
example:
```python
import cirq
from cirq_web import BlochSphere
# Prepare a state
zero_state = [1+0j, 0+0j]
state_vector = cirq.to_valid_state_vector(zero_state)
# Create and display the Bloch sphere
sphere = BlochSphere(state_vector=state_vector)
display(sphere)
```
You can find more example Jupyter notebooks in the `cirq-web` subdirectory of
the [Cirq repository on GitHub].
For more information about getting help, reporting bugs, and other matters
related to Cirq and the Cirq-Web integration module, please visit the [Cirq
repository on GitHub].
[Cirq repository on GitHub]: https://github.com/quantumlib/Cirq
## Disclaimer
Cirq is not an official Google product. Copyright 2019 The Cirq Developers.
--- METRICS ---
- Files Extracted: 11
- Estimated Token Budget: ~12104 tokens
- Recency Window: Active (< 180 days)
- Canonical Reference: https://codewiki.google/github.com/quantumlib/Cirq