Add documentation for cirq.google devices #2636

dstrain115 · 2019-12-11T22:18:39Z

Add sub-directory for Google-specific documentation.
Add documentation explaining grid devices, best practices.
Add documentation about Sycamore, Bristlecone, and Foxtail.

- Add sub-directory for Google-specific documentation. - Add documentation explaining grid devices, best practices. - Add documentation about Sycamore, Bristlecone, and Foxtail.

dstrain115 · 2019-12-17T17:13:34Z

Ping. This is documentation and should be easy to review!

maffoo · 2019-12-17T17:25:43Z

docs/google/devices.md

+Measurement takes much longer than other gates.  Currently, the only supported
+configuration is to have terminal measurement in the final moment of a circuit.
+
+Most devices have a limited number of gates that can applied to the device.  Gates not


"number of gates" here might be confused with how many gates can be applied in succession in a given circuit. Might be better to say "set of gates". Could separately note that there is also an overall restriction on the length of the circuit.

missing "be"

applied on the device? applied with the device? "to" sounds ood

maffoo · 2019-12-17T17:26:04Z

docs/google/devices.md

+
+### Use built-in optimizers as a first pass
+
+Using built-in optimizers will allow you to compile to the correct .  As they are


"to the correct gate set"?

maffoo · 2019-12-17T17:26:37Z

docs/google/devices.md

+
+Using built-in optimizers will allow you to compile to the correct .  As they are
+automated solutions, they will not always perform as well as a hand-crafted solution, but
+it provides a good starting point for creating a circuit that is likely to run successfully


nit: "but they provide..."

maffoo · 2019-12-17T17:35:37Z

docs/google/devices.md

+### Good moment structure
+
+In an attempt to fulfill the user's desire, quantum devices will respect the moment
+structure of circuits to the greatest extent possible.


Might want to specify what this means, e.g. "All gates in a moment will be executed at the same on hardware, after all gates in the previous moment and before any gates in the next moment."

maffoo · 2019-12-17T17:42:25Z

docs/google/devices.md

+
+## General limitations
+
+Qubits on Google devices are laid out in a grid structure.  Connectivity is limited to


nit: One space after period throughout (so says the chicago manual of style, anyway :-))

You can use two spaces in a monospaced font, as it provides visual separation between sentences. The trouble began when people stopped using typewriters and started using word processors with variable-width fonts and continued to use two spaces.

I was always taught to use two spaces, but I changed it to one space.

maffoo · 2019-12-17T17:43:46Z

docs/google/devices.md

+
+### Keep qubits busy
+
+Qubits that remain idle for long periods tend to dephase and decoher.  Inserting a


typo: "decohere"

maffoo · 2019-12-17T17:45:38Z

docs/google/devices.md

+```
+
+It can be accessing by using `cirq.google.Sycamore`.  This device has two possible
+two-qubits that can be used.


"two-qubit gates"

maffoo · 2019-12-17T17:46:47Z

docs/google/devices.md

+7 --EFGHIJKL--
+8 ---GHIJKL---
+9 ----IJKL----
+0 -----KL-----


last row number should be 10

maffoo · 2019-12-17T17:49:30Z

docs/google/devices.md

+In the current NISQ (noisy intermediate scale quantum) era, gates and devices still
+have significant error.  Both gate errors and T1 decay rate can cause long circuits
+to have noise that overwhelms any signal in the circuit.  Also, circuits that are
+much too long can even be rejected due to various limits in the system.


I would suggest describing the overall circuit length limit separately, e.g. in the section above on "General Limitations". Here can just talk about the coherence limit, which is typically more restrictive.

Moved this up to general limitation and modified the wording a bit. Let me know if you think it is okay.

mpharrigan · 2019-12-17T18:08:23Z

docs/google/devices.md

+Since quantum hardware is an active area of research, hardware specifications and best
+practices are constantly evolving in an attempt to continuously improve performance.
+While this information should be a solid base for beginning your quantum application,
+please work with your Google sponsor to obtain the latest information on devices that


is "Google sponsor" the terminology we're using?

I think so? We'll probably need to revamp this as we determine the process a bit better. Did you have a suggestion on how to change this, or do you think it's okay to leave as it for now?

mpharrigan · 2019-12-17T18:11:00Z

docs/google/devices.md

+
+## General limitations
+
+Qubits on Google devices are laid out in a grid structure.  Connectivity is limited to


You can use two spaces in a monospaced font, as it provides visual separation between sentences. The trouble began when people stopped using typewriters and started using word processors with variable-width fonts and continued to use two spaces.

mpharrigan · 2019-12-17T18:11:43Z

docs/google/devices.md

+Measurement takes much longer than other gates.  Currently, the only supported
+configuration is to have terminal measurement in the final moment of a circuit.
+
+Most devices have a limited number of gates that can applied to the device.  Gates not


missing "be"

mpharrigan · 2019-12-17T18:12:14Z

docs/google/devices.md

+Measurement takes much longer than other gates.  Currently, the only supported
+configuration is to have terminal measurement in the final moment of a circuit.
+
+Most devices have a limited number of gates that can applied to the device.  Gates not


applied on the device? applied with the device? "to" sounds ood

mpharrigan · 2019-12-17T18:13:20Z

docs/google/devices.md

+Using built-in optimizers will allow you to compile to the correct .  As they are
+automated solutions, they will not always perform as well as a hand-crafted solution, but
+it provides a good starting point for creating a circuit that is likely to run successfully
+on hardware.


put something that no matter which optimizers you use; you should inspect your circuit to make sure nothing crazy is happening

mpharrigan · 2019-12-17T18:15:32Z

docs/google/devices.md

+To this end, it is important that the moment structure of the circuit is kept as
+short and concise as possible.  The length of a moment will generally be the length
+of the longest gate in the moment, so keeping gates with similar durations together
+will generally benefit the performance.


"help performance"

it benefits the user. performance don't care

Changed to "...keeping gates with similar durations together
will shorten the duration of the circuit and likely reduce the noise incurred"

mpharrigan · 2019-12-17T18:15:47Z

docs/google/devices.md

+will generally benefit the performance.
+
+In particular, keep measurement gates in the same moment and make sure that any
+circuit optimizers run do not alter this by pushing measurements forward.  This


mpharrigan · 2019-12-17T18:16:13Z

docs/google/devices.md

+In particular, keep measurement gates in the same moment and make sure that any
+circuit optimizers run do not alter this by pushing measurements forward.  This
+behavior can be avoided by measuring all qubits with a single gate or by adding
+the measurement gate after all optimizers have run.


link to a github issue to provide better utilities for this?

Which github issue? Did you want me to add an example of cirq.measure for different qubits? Or appending the circuit with an insert strategy?

mpharrigan · 2019-12-17T18:17:10Z

docs/google/devices.md

+
+The recommended gate depths vary significantly with the structure of the circuit itself
+and will likely increase as the devices improve.  However, circuits with more than
+50 moments will generally struggle to retain any information.


is this true?

(I don't think it is)

Performance generally depends on width * depth

A rough guide can be found by multiplying together gate fidelities to get a sense for the probability of success for an algorithm. For example, if you have 20 moments on 20 qubits, you can roughly estimate circuit fidelity as (0.995)^(20*20)

Thanks. This is much more precise. I'll link to calibration metrics once we release them.

mpharrigan · 2019-12-17T18:20:13Z

docs/google/devices.md

+
+Devices generally operate in the Z basis, so that rotations around the Z axis will become
+book-keeping measures rather than physical operations on the device.  These operations
+should be aggregated into their own moment, if possible.


open or link to github issue requesting better cirq features to do this

We have an internal bug for this, but no cirq issue. I am going to punt on creating a GH issue for this until we decide what we want. I want to keep general advice separate from creating automated functionality to do these optimizations.

dstrain115

Thanks for the detailed comments! Please take another look when you get a chance.

dstrain115 · 2019-12-17T19:16:49Z

docs/google/devices.md

+To this end, it is important that the moment structure of the circuit is kept as
+short and concise as possible.  The length of a moment will generally be the length
+of the longest gate in the moment, so keeping gates with similar durations together
+will generally benefit the performance.


Changed to "...keeping gates with similar durations together
will shorten the duration of the circuit and likely reduce the noise incurred"

dstrain115 · 2019-12-17T19:17:03Z

docs/google/devices.md

+
+## General limitations
+
+Qubits on Google devices are laid out in a grid structure.  Connectivity is limited to


I was always taught to use two spaces, but I changed it to one space.

dstrain115 · 2019-12-17T19:17:07Z

docs/google/devices.md

+Measurement takes much longer than other gates.  Currently, the only supported
+configuration is to have terminal measurement in the final moment of a circuit.
+
+Most devices have a limited number of gates that can applied to the device.  Gates not


dstrain115 · 2019-12-17T19:17:21Z

docs/google/devices.md

+
+### Use built-in optimizers as a first pass
+
+Using built-in optimizers will allow you to compile to the correct .  As they are


dstrain115 · 2019-12-17T19:17:26Z

docs/google/devices.md

+
+Using built-in optimizers will allow you to compile to the correct .  As they are
+automated solutions, they will not always perform as well as a hand-crafted solution, but
+it provides a good starting point for creating a circuit that is likely to run successfully


dstrain115 · 2019-12-17T19:25:47Z

docs/google/devices.md

+In particular, keep measurement gates in the same moment and make sure that any
+circuit optimizers run do not alter this by pushing measurements forward.  This
+behavior can be avoided by measuring all qubits with a single gate or by adding
+the measurement gate after all optimizers have run.


Which github issue? Did you want me to add an example of cirq.measure for different qubits? Or appending the circuit with an insert strategy?

dstrain115 · 2019-12-17T19:27:17Z

docs/google/devices.md

+
+### Keep qubits busy
+
+Qubits that remain idle for long periods tend to dephase and decoher.  Inserting a


dstrain115 · 2019-12-17T19:36:52Z

docs/google/devices.md

+In the current NISQ (noisy intermediate scale quantum) era, gates and devices still
+have significant error.  Both gate errors and T1 decay rate can cause long circuits
+to have noise that overwhelms any signal in the circuit.  Also, circuits that are
+much too long can even be rejected due to various limits in the system.


Moved this up to general limitation and modified the wording a bit. Let me know if you think it is okay.

dstrain115 · 2019-12-17T19:43:14Z

docs/google/devices.md

+
+The recommended gate depths vary significantly with the structure of the circuit itself
+and will likely increase as the devices improve.  However, circuits with more than
+50 moments will generally struggle to retain any information.


Thanks. This is much more precise. I'll link to calibration metrics once we release them.

dstrain115 · 2019-12-17T19:50:56Z

docs/google/devices.md

+
+Devices generally operate in the Z basis, so that rotations around the Z axis will become
+book-keeping measures rather than physical operations on the device.  These operations
+should be aggregated into their own moment, if possible.


We have an internal bug for this, but no cirq issue. I am going to punt on creating a GH issue for this until we decide what we want. I want to keep general advice separate from creating automated functionality to do these optimizations.

mpharrigan

thanks!

maffoo

LGTM

Add documentation for cirq.google devices

89872a5

- Add sub-directory for Google-specific documentation. - Add documentation explaining grid devices, best practices. - Add documentation about Sycamore, Bristlecone, and Foxtail.

googlebot added the cla: yes Makes googlebot stop complaining. label Dec 11, 2019

dstrain115 added 3 commits December 11, 2019 14:38

Merge branch 'master' into sycamore_documentation

1aa8b55

Fix doc snippet to use correct parameter

253cb9b

Fix toctree

62a52df

dstrain115 requested review from Strilanc, dabacon and maffoo December 12, 2019 21:08

maffoo reviewed Dec 17, 2019

View reviewed changes

mpharrigan reviewed Dec 17, 2019

View reviewed changes

Update documentation based on comments.

61549ca

dstrain115 commented Dec 17, 2019

View reviewed changes

dstrain115 requested review from mpharrigan and maffoo December 17, 2019 19:52

mpharrigan approved these changes Dec 17, 2019

View reviewed changes

maffoo approved these changes Dec 17, 2019

View reviewed changes

Merge branch 'master' into sycamore_documentation

5efc45b

dstrain115 merged commit 7fb1a49 into quantumlib:master Dec 17, 2019


		### Use built-in optimizers as a first pass

		Using built-in optimizers will allow you to compile to the correct . As they are


		## General limitations

		Qubits on Google devices are laid out in a grid structure. Connectivity is limited to


		### Keep qubits busy

		Qubits that remain idle for long periods tend to dephase and decoher. Inserting a

Add documentation for cirq.google devices #2636

Add documentation for cirq.google devices #2636

Conversation

dstrain115 commented Dec 11, 2019

dstrain115 commented Dec 17, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dstrain115 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mpharrigan left a comment

Choose a reason for hiding this comment

maffoo left a comment

Choose a reason for hiding this comment