quantumlib / cirq

A python framework for creating, editing, and invoking Noisy Intermediate Scale Quantum (NISQ) circuits.

Cirq is a Python library for writing, manipulating, and optimizing quantum circuits and running them against quantum computers and simulators.

Installation and Documentation

Cirq documentation is available at quantumai.google/cirq.

Documentation for the latest pre-release version of cirq (tracks the repository's main branch; what you get if you pip install cirq~=1.0.dev), is available here.

Documentation for the latest stable version of cirq (what you get if you pip install cirq) is available here.

• Installation
• Documentation
• Tutorials

For a comprehensive list all of the interactive Jupyter Notebooks in our repo (including the ones not yet published to the site) open our repo in Colab.

For the latest news regarding Cirq, sign up to the Cirq-announce email list!

Hello Qubit

A simple example to get you up and running:

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)

Example output:

Circuit:
(0, 0): ───X^0.5───M('m')───
Results:
m=11000111111011001000

Feature requests / Bugs / Questions

If you have feature requests or you found a bug, please file them on GitHub.

For questions about how to use Cirq post to Quantum Computing Stack Exchange with the cirq tag.

How to cite Cirq

Cirq is uploaded to Zenodo automatically. Click on the badge below to see all the citation formats for all versions.

Cirq Contributors Community

We welcome contributions! Before opening your first PR, a good place to start is to read our guidelines.

We are dedicated to cultivating an open and inclusive community to build software for near term quantum computers. Please read our code of conduct for the rules of engagement within our community.

Cirq Cynque is our weekly meeting for contributors to discuss upcoming features, designs, issues, community and status of different efforts. To get an invitation please join the cirq-dev email list which also serves as yet another platform to discuss contributions and design ideas.

See Also

For those interested in using quantum computers to solve problems in chemistry and materials science, we encourage exploring OpenFermion and its sister library for compiling quantum simulation algorithms in Cirq, OpenFermion-Cirq.

For machine learning enthusiasts, Tensorflow Quantum is a great project to check out!

For a powerful quantum circuit simulator that integrates well with Cirq, we recommend looking at qsim.

Finally, ReCirq contains real world experiments using Cirq.

Cirq is not an official Google product. Copyright 2019 The Cirq Developers

cirq's Issues

How to run a Program with multiple ParameterSweeps

Currently a Program can contain multiple ParameterSweeps, each of which calls for a certain number of repetitions. I presume that if there are multiple sweeps, we just run each sweep one after another and then return data from all of them.

However, the Result type has a single num_repetitions field and then a single list of ParameterizedResult values. We can't just concatenate results from different sweeps into this list because they might come from ParameterSweeps with different numbers of repetitions. I think we need to either need to limit programs to one sweep, or else have separate "SweepResult" messages for each sweep, something like:

message Result {
  repeated MeasurementKey measurement_keys = 1;
  repeated SweepResult sweep_results = 2;
}

message SweepResult {
  int32 repetitions = 1;  // NB: same name as in `ParameterSweep`
  repeated ParameterizedResult parameterized_results = 2;
}

Simulator should avoid extra copy into scratch

There is an extra copy of scratch back to state in the xmon simulator. We could avoid this copy by have two states and a flag that keeps track of which state is the current state. Since copy is the heaviest operation in the simulator this could potentially speed up the simulator significantly.

Add QCircuit latex output

Rename 'Moment' to 'Cycle'

OP_TREE include iterators?

The current contract is that the object passed in must be Iterable. But it might also be useful to include iterators themselves. So that
circuit = cirq.circuits.Circuit() circuit.append(iter([q0, q1, q2]))
works.

Typo in docstring.

https://github.com/quantumlib/cirq/blob/66a5d8b694bf0360b54348871520dff2ba12e1ac/cirq/sim/google/xmon_simulator.py#L222

I think you're missing a Y after the sin(2 pi rotation_axis_turns)

Burndown: integrate simulator

Before partner launch: wipe repo history

Blocked on other tasks.

Add a simple cirq.google.simulate method hiding Study/XmonSimulator/etc details

Incorrect evaluation of norm

https://github.com/quantumlib/cirq/blob/41c33f7ae930adbb4b410ca4610ba530c2dad73c/cirq/sim/google/xmon_stepper.py#L346

I get errors when state is complex valued. Consider:

norm = np.sum(np.abs(state) ** 2)

Feature request: simulate multiple independent measurements

Currently XmonSimulator.simulate_measurement causes the current state to collapse.

This means that in order to simulate X sample measurements after a long unitary evolution, we need to simulate the evolution X times, then carry out the measurement after each evolution. It would be nice to be able to save the current state prior to the measurement. That way, after doing a single long unitary evolution, we could just reload the final state X times and simulate measurement on it.

Consistent path in cirq api protos

The directory structure is
cirq/apis/google/v1
but the proto path is
cirq.api.google.v1

Either api or apis should be used, but not both.

Generating parameters

Ways to generate parameters for studies.

Especially ways that match what is specified against api.

adding people outside Google

The interns that will work with Jarrod and I are interested in starting some aspects of their projects early. Their projects are going to involve some aspect of implementing some OpenFermion routines with Cirq. Is it possible to invite them to Cirq? Or is Cirq strictly Google-only for now?

Native measurement Gate is only one that is ASCII diagramable

native_gates.Measurements is ASCII diagramable but other native_gates are not.

Think this is an artifact of some cleanup?

"cirquit" != "circuit"

I find myself typing "cirquit" when it should be "circuit". It feels like this is going to be a generic problem with using this library. I'm not sure whether there's anything we can do about it, but I thought I'd raise the issue.

Bazel rules for protobufs so that we don't have to regenerate generated protobuf code

Add "scale_factor" or "negate" to ParameterizedValue

A couple optimization passes would be able to work transparently with ParameterizedValues if they supported the __neg__ operation. For example, to multiply an ExpW gate by X you negate its axis_half_turns parameter.

This would also require updating the API to support the scale factor.

Make XmonDevice.__str__ and Circuit.__str__ output a text diagram

Significantly more useful than what they output now.

Unexpected behavior in XmonSimulator.simulate_phases

When running

turns = {(0, 1): 0.5}
acquired_phases = []
for state in range(4):
    with XmonSimulator(num_qubits=2, initial_state=state) as xmon:
        xmon.simulate_phases(turns)
        acquired_phases.append(xmon.current_state.round(2)[state])
print(acquired_phases)

the output is:
[(-1-0j), (-1-0j), (-1-0j), (-1+0j)]

What I would expected to happen from the XmonSimulator docstring is the unitary exp( i \pi | 11 >< 11 |) to be applied, so that only state 3 should acquire a -1 phase, while the other states should remain unchanged.

Burndown: Simulator speed

Running the hello world with 10 repetitions is reported by @Strilanc to be veryslow.

XGate, YGate, ZGate, CZGate should be renamed

These names are confusing because when anyone sees XGate they will think "Pauli X". But this is hiding a rotation angle. Suggestion:
RotXGate
RotYGate
RotZGate
CZ is even more peculiar because it is really exp(it |11><11|) so maybe Rot11Gate

Burndown: documentation

Hello Qubit runtime error

Tried to run the "hello qubit" example from the README.md. Got this error:
Python 3.5.3 (default, Jan 19 2017, 14:11:04) [GCC 6.3.0 20170118] on linux

exec(open('hello_qubit.py').read())
Traceback (most recent call last):
File "", line 1, in
File "", line 17, in
File "/usr/local/google/home/sxwang/cirq/cirq/sim/google/xmon_simulator.py", line 103, in run
return functools.reduce(Result.merge_measurements_with, all_results)
File "/usr/local/google/home/sxwang/cirq/cirq/sim/google/xmon_simulator.py", line 166, in simulator_iterator
for op in moment.operations:
AttributeError: 'Operation' object has no attribute 'operations'

It seems the variable "circuit" should contain a list of moments (which have the operations attribute), but instead it contains a list of operations.

I think all it needs is to add a line to create a list of moments for the operations and provide that to the Circuit initializer. Let me know if that's not the intended design.

xmon simulator should support schedules

Allow a schedule to be passed in and then greedily construct moments for this simulation.

Refactor package structure

Step 1: Argue about what structure to use.

Should Circuit#append be chainable?

It seems like a common pattern to want to do
circuit = Circuit().append(o1).append([o2, o3])
?

Flatten module hierarchy?

One thing I've noticed is that it's a bit annoying to remember of "QubitLoc" is under "circuits" or "devices" or "ops". A solution to this problem is to flatten the whole library down to a single-level module in the way that numpy does: there's still some internal structure, but for the most part everything is just at the base level.

This would improve the learning curve significantly, I think.

Burndown: refactor native gates to derive from other gate types

xmon simulator should take extension to override gate mapping

Right now it uses the fixed xmon_gate_ext, but users may want to supply their own mapping

Symmetric operations having equality that depends on qubit order

Not too surprising but
CZ(q0, q1) != CZ(q1, q0)

Not sure whether this is a problem or not and I guess fixing this for more than 2 qubits could get expensive

nit: Default argument should not be a mutable type.

https://github.com/quantumlib/cirq/blob/afbf94d85a4c07f28fd5c5e2c5b4114564b4899c/cirq/sim/google/xmon_simulator.py#L81

QASM output and input

We should be able to turn a Circuit into QASM.

It would also be useful to read the QASM back in, though it would have to be a subset of the language (no loops etc).

pip3 error in installation instructions

Followed the installation instructions in docs/install.md on my corp linux machine. Got this error at step 6:

(circEnv) sxwang@sxwang0:~$ pip3 install -e ./cirq/cirq
Directory './cirq/cirq' is not installable. File 'setup.py' not found.

Also, the next line of the instructions says "If you want to install Cirq and have changes you make to Cirq show up when you edit Cirq, add -editable to the last command." Isn't -e = --editable?

Add __str__ to TrialResult

copy for Circuit

optimization passes are done in place on a circuit, which makes sense as we don't want to recreate the whole circuit

when writing test code, or even in preliminary work using optimization passes, however, this means that you will lose the original circuit.

To fix this I think we need a copy method for Circuit so that you can copy before optimizing.

Burndown: tighten ascii diagram code

Burndown: implement a scheduler

Implement a `GraphQubit` type

Right now QubitLoc is just a 2d point. This is very reasonable for our hardware, but there are other qubit types that are very natural and which we should support (lines, staggered grids, general graph connectivities).

Proposal:
Abstract out the interface that describes adjacency, i.e. make an interface type HasAdjacency which requires the method is_adjacent. (Right constant two qubit gate assumes that the qubits implement this method).

New Qubit types
GridQubit
LineQubit

Also a way to go from an Adjacency graph to a set of GraphQubits which implement HasAdjacency and which obey the adjacency relation of the graph.

This would mostly be relevant for defining a single / two qubit gates that respect adjacency, and also for device which use this adjacency in some of their constraints.

half_turn name in ExpZGate is confusing

In sim.google.xmon_simulator_test, I added the following test:

@pytest.mark.parametrize('phase', (0.0, 0.2))
def test_param_resolver_exp_z_half_turns(phase):
    exp_z = ExpZGate(half_turns=phase)
    circuit = Circuit()
    circuit.append(exp_z(Q1))

    resolver = ParamResolver({'a': phase})
    result = compute_gate(circuit, resolver)

    np.testing.assert_almost_equal(
        result,
        np.array([[cmath.exp(1j * math.pi * phase / 2), 0],
                  [0, cmath.exp(-1j * math.pi * phase / 2)]]))

This test passes, which confuses me, because the gate implemented is
\exp( i (\pi "phase" / 2) \sigma_z )
So ExpZGate(half_turns=1) actually implements a "quarter turn" instead of a "half_turn", and ExpZGate(half_turns=2) is not the identity.

Xmon simulator puts measurements in the wrong order, with later measurements before earlier ones

Fails:

def test_measurement_order():
    circuit = Circuit.from_ops(
        XmonMeasurementGate().on(Q1),
        X(Q1),
        XmonMeasurementGate().on(Q1),
    )
    _, result = xmon_simulator.Simulator().run(circuit)
    assert result.measurements[''] == [False, True]

test-pull-request.sh fails silently if supplied access token is invalid

If your run continuous_integration/test-pull-request.sh with an invalid access token, it will say "Success!" but then it doesn't set the status.

Increase performance of simulator tests

At the moment, 90% of testing time (~1 minute) is spent in the simulator tests. Making them more performant would save a lot of test time.

Support invert_result for measurement in API

This is useful when doing randomized compilation, so that final Paulis can be merged into the measurement.

helpers for qubits

I think I find myself writing, I want a bunch of ordered qubits all the time.

A helper for getting n qubits would be nice.

If @Strilanc doesn't yell at me I might make this
qrange(n)

NamedQubits don't use their name in to_ascii

q0, q1, q2 = [NamedQubit(i) for i in range(3)]
circuit = cirq.circuits.Circuit()
circuit.append([CZ(q0, q1), H(q2)])

print(cirq.circuits.to_ascii(circuit))

<cirq.ops.raw_types.NamedQubit object at 0xa4c0a90>: ---Z---
                                                        |
<cirq.ops.raw_types.NamedQubit object at 0xa4c0350>: ---Z---

<cirq.ops.raw_types.NamedQubit object at 0xa558190>: ---H---

Make tight trace distance bounds

Currently gates that implement the trace_distance_bound do not so approximately. For many of these we can explicitly calculate these bounds and we should do so.

Burndown: implement xmon device

#55

CompositeGates confusion

When a gate is composite, it is composite with respect to a fixed set of other gates. For different contexts these decompositions are either the one you want or not the one you want.

Ultimately circuits end up being written in some gate set (for now just Xmon at the bottom), where we use an extension to define the mapping. Can we do a simpler thing for composite gates, i.e us an extension to define the composite gate? I think this may be possible now, but we should have an example of this and document it in compositegate's doc.

to_ascii qubit order should be modifiable

At least give an optional method for providing a key in case the string order isn't what people want (if you use the string order with raw QubitId() objects it is also really bad, but I guess we just encourage the use of NamedQubit?)