View on QuantumAI Run in Google Colab View source on GitHub Download notebook
    import cirq
except ImportError:
    print("installing cirq...")
    !pip install --quiet cirq --pre
    print("installed cirq.")
import cirq
--- Logging error ---
Traceback (most recent call last):
  File "/tmpfs/src/tf_docs_env/lib/python3.7/site-packages/cirq/", line 604, in <module>
  File "/tmpfs/src/tf_docs_env/lib/python3.7/site-packages/cirq/", line 546, in deprecated_submodule
    new_module = importlib.import_module(new_module_name)
  File "/usr/lib/python3.7/importlib/", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1006, in _gcd_import
  File "<frozen importlib._bootstrap>", line 983, in _find_and_load
  File "<frozen importlib._bootstrap>", line 965, in _find_and_load_unlocked
ModuleNotFoundError: No module named 'cirq_aqt'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/usr/lib/python3.7/logging/", line 1025, in emit
    msg = self.format(record)
  File "/usr/lib/python3.7/logging/", line 869, in format
    return fmt.format(record)
  File "/usr/lib/python3.7/logging/", line 608, in format
    record.message = record.getMessage()
  File "/usr/lib/python3.7/logging/", line 369, in getMessage
    msg = msg % self.args
TypeError: not all arguments converted during string formatting
Call stack:
  File "/usr/lib/python3.7/", line 193, in _run_module_as_main
    "__main__", mod_spec)
  File "/usr/lib/python3.7/", line 85, in _run_code
    exec(code, run_globals)
  File "/home/kbuilder/.local/lib/python3.7/site-packages/", line 16, in <module>
  File "/home/kbuilder/.local/lib/python3.7/site-packages/traitlets/config/", line 845, in launch_instance
  File "/home/kbuilder/.local/lib/python3.7/site-packages/ipykernel/", line 619, in start
  File "/home/kbuilder/.local/lib/python3.7/site-packages/tornado/platform/", line 199, in start
  File "/usr/lib/python3.7/asyncio/", line 534, in run_forever
  File "/usr/lib/python3.7/asyncio/", line 1771, in _run_once
  File "/usr/lib/python3.7/asyncio/", line 88, in _run, *self._args)
  File "/home/kbuilder/.local/lib/python3.7/site-packages/tornado/", line 688, in <lambda>
    lambda f: self._run_callback(functools.partial(callback, future))
  File "/home/kbuilder/.local/lib/python3.7/site-packages/tornado/", line 741, in _run_callback
    ret = callback()
  File "/home/kbuilder/.local/lib/python3.7/site-packages/tornado/", line 814, in inner
  File "/home/kbuilder/.local/lib/python3.7/site-packages/tornado/", line 775, in run
    yielded = self.gen.send(value)
  File "/home/kbuilder/.local/lib/python3.7/site-packages/ipykernel/", line 358, in process_one
    yield gen.maybe_future(dispatch(*args))
  File "/home/kbuilder/.local/lib/python3.7/site-packages/tornado/", line 234, in wrapper
    yielded = ctx_run(next, result)
  File "/home/kbuilder/.local/lib/python3.7/site-packages/ipykernel/", line 261, in dispatch_shell
    yield gen.maybe_future(handler(stream, idents, msg))
  File "/home/kbuilder/.local/lib/python3.7/site-packages/tornado/", line 234, in wrapper
    yielded = ctx_run(next, result)
  File "/home/kbuilder/.local/lib/python3.7/site-packages/ipykernel/", line 538, in execute_request
    user_expressions, allow_stdin,
  File "/home/kbuilder/.local/lib/python3.7/site-packages/tornado/", line 234, in wrapper
    yielded = ctx_run(next, result)
  File "/home/kbuilder/.local/lib/python3.7/site-packages/ipykernel/", line 302, in do_execute
    res = shell.run_cell(code, store_history=store_history, silent=silent)
  File "/home/kbuilder/.local/lib/python3.7/site-packages/ipykernel/", line 539, in run_cell
    return super(ZMQInteractiveShell, self).run_cell(*args, **kwargs)
  File "/home/kbuilder/.local/lib/python3.7/site-packages/IPython/core/", line 2899, in run_cell
    raw_cell, store_history, silent, shell_futures)
  File "/home/kbuilder/.local/lib/python3.7/site-packages/IPython/core/", line 2944, in _run_cell
    return runner(coro)
  File "/home/kbuilder/.local/lib/python3.7/site-packages/IPython/core/", line 68, in _pseudo_sync_runner
  File "/home/kbuilder/.local/lib/python3.7/site-packages/IPython/core/", line 3170, in run_cell_async
    interactivity=interactivity, compiler=compiler, result=result)
  File "/home/kbuilder/.local/lib/python3.7/site-packages/IPython/core/", line 3361, in run_ast_nodes
    if (await self.run_code(code, result,  async_=asy)):
  File "/home/kbuilder/.local/lib/python3.7/site-packages/IPython/core/", line 3441, in run_code
    exec(code_obj, self.user_global_ns, self.user_ns)
  File "<ipython-input-1-98520f192a76>", line 1, in <module>
    import cirq
  File "<frozen importlib._bootstrap>", line 983, in _find_and_load
  File "<frozen importlib._bootstrap>", line 967, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 677, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 728, in exec_module
  File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
  File "/tmpfs/src/tf_docs_env/lib/python3.7/site-packages/cirq/", line 608, in <module>
    warning("Can't import cirq.aqt: ", ex)
Message: "Can't import cirq.aqt: "
Arguments: (ModuleNotFoundError("No module named 'cirq_aqt'"),)

For simulation, it is useful to have Gate objects that enact noisy quantum evolution. Cirq supports modeling noise via operator sum representations of noise (these evolutions are also known as quantum operations or quantum dynamical maps).

This formalism models evolution of the density matrix $\rho$ via

$$ \rho \rightarrow \sum_{k = 1}^{m} A_k \rho A_k^\dagger $$

where $A_k$ are known as Kraus operators. These operators are not necessarily unitary but must satisfy the trace-preserving property

$$ \sum_k A_k^\dagger A_k = I . $$

A channel with $m = 1$ unitary Kraus operator is called coherent (and is equivalent to a unitary gate operation), otherwise the channel is called incoherent. For a given noisy channel, Kraus operators are not necessarily unique. For more details on these operators, see John Preskill's lecture notes.

Common channels

Cirq defines many commonly used quantum channels in ops/ For example, the single-qubit bit-flip channel

$$ \rho \rightarrow (1 - p) \rho + p X \rho X $$

with parameter $p = 0.1$ can be created as follows.

"""Get a single-qubit bit-flip channel."""
bit_flip = cirq.bit_flip(p=0.1)

To see the Kraus operators of a channel, the protocol can be used. (See the protocols guide.)

for i, kraus in enumerate(cirq.kraus(bit_flip)):
    print(f"Kraus operator {i + 1} is:\n", kraus, end="\n\n")
Kraus operator 1 is:
 [[0.9486833 0.       ]
 [0.        0.9486833]]

Kraus operator 2 is:
 [[0.        +0.j 0.31622777+0.j]
 [0.31622777+0.j 0.        +0.j]]

As mentioned, all channels are subclasses of cirq.Gates. As such, they can act on qubits and be used in circuits in the same manner as gates.

"""Example of using channels in a circuit."""
# See the number of qubits a channel acts on.
nqubits = bit_flip.num_qubits()
print(f"Bit flip channel acts on {nqubits} qubit(s).\n")

# Apply the channel to each qubit in a circuit.
circuit = cirq.Circuit(
Bit flip channel acts on 1 qubit(s).

0: ───BF(0.1)───

1: ───BF(0.1)───

2: ───BF(0.1)───

Channels can even be controlled.

"""Example of controlling a channel."""
# Get the controlled channel.
controlled_bit_flip = bit_flip.controlled(num_controls=1)

# Use it in a circuit.
circuit = cirq.Circuit(
0: ───@─────────
1: ───BF(0.1)───

In addition to the bit-flip channel, other common channels predefined in Cirq are shown below. Definitions of these channels can be found in their docstrings - e.g., help(cirq.depolarize).

For example, the asymmetric depolarizing channel is defined by

$$ \rho \rightarrow (1-p_x-p_y-p_z) \rho + p_x X \rho X + p_y Y \rho Y + p_z Z \rho Z $$

and can be instantiated as follows.

"""Get an asymmetric depolarizing channel."""
depo = cirq.asymmetric_depolarize(

circuit = cirq.Circuit(
0: ───A(0.1,0.05,0.15)───

The channel and mixture protocols

We have seen the protocol which returns the Kraus operators of a channel. Some channels have the interpretation of randomly applying a single unitary Kraus operator $U_k$ with probability $p_k$, namely

$$ \rho \rightarrow \sum_k p_k U_k \rho U_k^\dagger {\rm ~where~} \sum_k p_k =1 {\rm ~and~ U_k U_k^\dagger= I}. $$

For example, the bit-flip channel from above

$$ \rho \rightarrow (1 - p) \rho + p X \rho X $$

can be interpreted as doing nothing (applying identity) with probability $1 - p$ and flipping the bit (applying $X$) with probability $p$. Channels with these interpretations support the cirq.mixture protocol. This protocol returns the probabilities and unitary Kraus operators of the channel.

"""Example of using the mixture protocol."""
for prob, kraus in cirq.mixture(bit_flip):
    print(f"With probability {prob}, apply\n", kraus, end="\n\n")
With probability 0.9, apply
 [[1. 0.]
 [0. 1.]]

With probability 0.1, apply
 [[0.+0.j 1.+0.j]
 [1.+0.j 0.+0.j]]

Channels that do not have this interpretation do not support the cirq.mixture protocol. Such channels apply Kraus operators with probabilities that depend on the state $\rho$.

An example of a channel which does not support the mixture protocol is the amplitude damping channel with parameter $\gamma$ defined by Kraus operators

$$ M_0 = \begin{bmatrix} 1 & 0 \cr 0 & \sqrt{1 - \gamma} \end{bmatrix} \text{and } M_1 = \begin{bmatrix} 0 & \sqrt{\gamma} \cr 0 & 0 \end{bmatrix} . $$
"""The amplitude damping channel is an example of a channel without a mixture."""
channel = cirq.amplitude_damp(0.1)

if cirq.has_mixture(channel):
    print(f"Channel {channel} has a _mixture_ or _unitary_ method.")
    print(f"Channel {channel} does not have a _mixture_ or _unitary_ method.")
Channel amplitude_damp(gamma=0.1) does not have a _mixture_ or _unitary_ method.

To summarize:

For concrete examples, consider cirq.X, cirq.BitFlipChannel, and cirq.AmplitudeDampingChannel which are all subclasses of cirq.Gate.

Custom channels

Channels not defined in cirq.ops.common_channels can be user-defined. Defining custom channels is similar to defining custom gates.

A minimal example for defining the channel

$$ \rho \mapsto (1 - p) \rho + p Y \rho Y $$

is shown below.

"""Minimal example of defining a custom channel."""
class BitAndPhaseFlipChannel(cirq.SingleQubitGate):
    def __init__(self, p: float) -> None:
        self._p = p

    def _mixture_(self):
        ps = [1.0 - self._p, self._p]
        ops = [cirq.unitary(cirq.I), cirq.unitary(cirq.Y)]
        return tuple(zip(ps, ops))

    def _has_mixture_(self) -> bool:
        return True

    def _circuit_diagram_info_(self, args) -> str:
        return f"BitAndPhaseFlip({self._p})"

We can now instantiate this channel and get its mixture:

"""Custom channels can be used like any other channels."""
bit_phase_flip = BitAndPhaseFlipChannel(p=0.05)

for prob, kraus in cirq.mixture(bit_phase_flip):
    print(f"With probability {prob}, apply\n", kraus, end="\n\n")
With probability 0.95, apply
 [[1. 0.]
 [0. 1.]]

With probability 0.05, apply
 [[0.+0.j 0.-1.j]
 [0.+1.j 0.+0.j]]

The custom channel can be used in a circuit just like other predefined channels.

"""Example of using a custom channel in a circuit."""
circuit = cirq.Circuit(

This method of defining custom channels is the most general, but simple channels such as the custom BitAndPhaseFlipChannel can also be created directly from a Gate with the convenient Gate.with_probability method.

"""Create a channel with Gate.with_probability."""
channel = cirq.Y.with_probability(probability=0.05)

This produces the same mixture as the custom BitAndPhaseFlip channel above.

for prob, kraus in cirq.mixture(channel):
    print(f"With probability {prob}, apply\n", kraus, end="\n\n")
With probability 0.05, apply
 [[0.+0.j 0.-1.j]
 [0.+1.j 0.+0.j]]

With probability 0.95, apply
 [[1. 0.]
 [0. 1.]]

Note that the order of Kraus operators is reversed from above, but this of course does not affect the action of the channel.

Simulating noisy circuits

Density matrix simulation

The cirq.DensityMatrixSimulator can simulate any noisy circuit (i.e., can apply any quantum channel) because it stores the full density matrix $\rho$. This simulation strategy updates the state $\rho$ by directly applying the Kraus operators of each quantum channel.

"""Simulating a circuit with the density matrix simulator."""
# Get a circuit.
qbit = cirq.GridQubit(0, 0)
circuit = cirq.Circuit(

# Display it.
print("Simulating circuit:")

# Simulate with the density matrix simulator.
dsim = cirq.DensityMatrixSimulator()
rho = dsim.simulate(circuit).final_density_matrix

# Display the final density matrix.
print("\nFinal density matrix:")
Simulating circuit:
(0, 0): ───X───AD(0.1)───

Final density matrix:
[[0.1       +0.j 0.        +0.j]
 [0.        +0.j 0.90000004+0.j]]

Note that the density matrix simulator supports the run method which only gives access to measurements as well as the simulate method (used above) which gives access to the full density matrix.

Monte Carlo wavefunction simulation

Noisy circuits with arbitrary channels can also be simulated with the cirq.Simulator. When simulating such a channel, a single Kraus operator is randomly sampled (according to the probability distribution) and applied to the wavefunction. This method is known as "Monte Carlo (wavefunction) simulation" or "quantum trajectories."

"""Simulating a noisy circuit via Monte Carlo simulation."""
# Get a circuit.
qbit = cirq.NamedQubit("Q")
circuit = cirq.Circuit(cirq.bit_flip(p=0.5).on(qbit))

# Display it.
print("Simulating circuit:")

# Simulate with the cirq.Simulator.
sim = cirq.Simulator()
psi = sim.simulate(circuit).dirac_notation()

# Display the final wavefunction.
print("\nFinal wavefunction:")
Simulating circuit:
Q: ───BF(0.5)───

Final wavefunction:

To see that the output is stochastic, you can run the cell above multiple times. Since $p = 0.5$ in the bit-flip channel, you should get $|0\rangle$ roughly half the time and $|1\rangle$ roughly half the time. The run method with many repetitions can also be used to see this behavior.

"""Example of Monte Carlo wavefunction simulation with the `run` method."""
circuit = cirq.Circuit(
res =, repetitions=100)
Counter({0: 55, 1: 45})

Adding noise to circuits

Often circuits are defined with just unitary operations, but we want to simulate them with noise. There are several methods for inserting noise in Cirq.

For any circuit, the with_noise method can be called to insert a channel after every moment.

"""One method to insert noise in a circuit."""
# Define some noiseless circuit.
circuit = cirq.testing.random_circuit(
    qubits=3, n_moments=3, op_density=1, random_state=11

# Display the noiseless circuit.
print("Circuit without noise:")

# Add noise to the circuit.
noisy = circuit.with_noise(cirq.depolarize(p=0.01))

# Display it.
print("\nCircuit with noise:")
Circuit without noise:
0: ───@───X─────×────
      │   │     │
1: ───@───┼────S┼────
          │     │
2: ───Z───@─────×────

Circuit with noise:
0: ───@───D(0.01)[cirq.VirtualTag()]───X───D(0.01)[cirq.VirtualTag()]─────×────D(0.01)[cirq.VirtualTag()]───
      │                                │                                  │
1: ───@───D(0.01)[cirq.VirtualTag()]───┼───D(0.01)[cirq.VirtualTag()]────S┼────D(0.01)[cirq.VirtualTag()]───
                                       │                                  │
2: ───Z───D(0.01)[cirq.VirtualTag()]───@───D(0.01)[cirq.VirtualTag()]─────×────D(0.01)[cirq.VirtualTag()]───

This circuit can then be simulated using the methods described above.

The with_noise method creates a cirq.NoiseModel from its input and adds noise to each moment. A cirq.NoiseModel can be explicitly created and used to add noise to a single operation, single moment, or series of moments as follows.

"""Add noise to an operation, moment, or sequence of moments."""
# Create a noise model.
noise_model = cirq.NoiseModel.from_noise_model_like(cirq.depolarize(p=0.01))

# Get a qubit register.
qreg = cirq.LineQubit.range(2)

# Add noise to an operation.
op = cirq.CNOT(*qreg)
noisy_op = noise_model.noisy_operation(op)

# Add noise to a moment.
moment = cirq.Moment(cirq.H.on_each(qreg))
noisy_moment = noise_model.noisy_moment(moment, system_qubits=qreg)

# Add noise to a sequence of moments.
circuit = cirq.Circuit(cirq.H(qreg[0]), cirq.CNOT(*qreg))
noisy_circuit = noise_model.noisy_moments(circuit, system_qubits=qreg)

The output of each "noisy method" is a cirq.OP_TREE which can be converted to a circuit by passing it into the cirq.Circuit constructor. For example, we create a circuit from the noisy_moment below.

"""Creating a circuit from a noisy cirq.OP_TREE."""

Another technique is to pass a noise channel to the density matrix simulator as shown below.

"""Define a density matrix simulator with a noise model."""
noisy_dsim = cirq.DensityMatrixSimulator(
    noise=cirq.generalized_amplitude_damp(p=0.1, gamma=0.5)

This will not explicitly add channels to the circuit being simulated, but the circuit will be simulated as though these channels were present.

Other than these general methods, channels can be added to circuits at any moment just as gates are. The channels can be different, be correlated, act on a subset of qubits, be custom defined, etc.

"""Defining a circuit with multiple noisy channels."""
qreg = cirq.LineQubit.range(4)
circ = cirq.Circuit(
    cirq.qft(*qreg, inverse=True),

print("Circuit with multiple channels:\n")
Circuit with multiple channels:

0: ───H───D(0.01)───qft───────────────────────────qft^-1───────M──────────────
                    │                             │            │
1: ───H───D(0.01)───#2────BitAndPhaseFlip(0.05)───#2───────R───M──────────────
                    │                             │            │
2: ───H───D(0.01)───#3────────────────────────────#3───────────M───@──────────
                    │                             │            │   │
3: ───H───D(0.01)───#4────BitAndPhaseFlip(0.05)───#4───────────M───BF(0.07)───

Circuits can also be modified with standard methods like insert to add channels at any point in the circuit. For example, to model simple state preparation errors, one can add bit-flip channels to the start of the circuit as follows.

"""Example of inserting channels in circuits."""
circ.insert(0, cirq.bit_flip(p=0.1).on_each(qreg))
0: ───BF(0.1)───H───D(0.01)───qft───────────────────────────qft^-1───────M──────────────
                              │                             │            │
1: ───BF(0.1)───H───D(0.01)───#2────BitAndPhaseFlip(0.05)───#2───────R───M──────────────
                              │                             │            │
2: ───BF(0.1)───H───D(0.01)───#3────────────────────────────#3───────────M───@──────────
                              │                             │            │   │
3: ───BF(0.1)───H───D(0.01)───#4────BitAndPhaseFlip(0.05)───#4───────────M───BF(0.07)───