From ad52de7ed131f0ee59b37f515786743df21f0b1a Mon Sep 17 00:00:00 2001 From: Doug Strain Date: Fri, 24 Jun 2022 11:41:37 -0700 Subject: [PATCH 1/6] Add user best practices documentation - Add document under 'start' about some basic best practices, like using 'cirq.X' instead of 'cirq.ops.X'. - Also added sections about immutability of gates, operations, and parameter resolvers. - Removed name of former product manager. --- docs/_book.yaml | 2 + docs/build/gates.ipynb | 13 ++++++ docs/dev/rfc_process.md | 2 +- docs/simulate/params.ipynb | 15 +++++++ docs/start/best_practices.md | 79 ++++++++++++++++++++++++++++++++++++ 5 files changed, 110 insertions(+), 1 deletion(-) create mode 100644 docs/start/best_practices.md diff --git a/docs/_book.yaml b/docs/_book.yaml index 5a9613622da..00c21a81767 100644 --- a/docs/_book.yaml +++ b/docs/_book.yaml @@ -37,6 +37,8 @@ upper_tabs: path: /cirq/start/start - title: "Cirq Basics" path: /cirq/start/basics + - title: "Best Practices" + path: /cirq/start/best_practices #### TEST UNDERSTANDING #### - heading: "Test understanding" diff --git a/docs/build/gates.ipynb b/docs/build/gates.ipynb index 2ed56a5a086..d9c4ff078f2 100644 --- a/docs/build/gates.ipynb +++ b/docs/build/gates.ipynb @@ -157,6 +157,19 @@ "[Circuits](circuits.ipynb)." ] }, + { + "cell_type": "markdown", + "metadata": { + "id": "yS2UiFDQt-sk" + }, + "source": [ + "## Immutability of Gates and Operations\n", + "\n", + "Gates and Operations in Cirq are considered to be immutable objects. This means that a `cirq.Gate` or `cirq.Operation` should not be modified after its creation. If attributes of these objects need to be modified, a new object should be created.\n", + "\n", + "Modifying these objects in-place could cause unexpected behavior. For instance, changing the qubits of an existing `cirq.Operation` object could cause an existing `cirq.Moment` that contains this object to have operations with overlapping qubits." + ] + }, { "cell_type": "markdown", "metadata": { diff --git a/docs/dev/rfc_process.md b/docs/dev/rfc_process.md index 855d45461a7..fbc911893ec 100644 --- a/docs/dev/rfc_process.md +++ b/docs/dev/rfc_process.md @@ -41,7 +41,7 @@ and have a discussion with the maintainers. Mention that you are willing to writ * Make sure to share your doc with cirq-dev@googlegroups.com for comments. * Link the RFC in your issue. 4. Recruiting a sponsor: - * A sponsor must be a maintainer of the project or the product manager (currently Alan Ho). + * A sponsor must be a maintainer of the project or the product manager. * Write a comment in your Github issue that calls out that you are "Looking for a sponsor". A maintainer will mark the issue with a label: "rfc/needs-sponsor". * While it might take some time to get a maintainer to sponsor your RFC, it is essential, as the sponsor will facilitate the process for reviewing your design. * Tips to recruit a sponsor: 1) keep commenting on the issue weekly 2) attend Cirq Cynq and push for a sponsor. diff --git a/docs/simulate/params.ipynb b/docs/simulate/params.ipynb index d114ee5a279..c8916cab935 100644 --- a/docs/simulate/params.ipynb +++ b/docs/simulate/params.ipynb @@ -629,6 +629,21 @@ "You can see that the different flattened parameters have corresponding different results for their simulation." ] }, + { + "cell_type": "markdown", + "metadata": { + "id": "63FrLKWk9_mC" + }, + "source": [ + "### Immutability of Sweeps\n", + "\n", + "Sweeps and parameter resolvers should be considered immutable objects and should not be modified after creation.\n", + "\n", + "Many of these parameter resolvers use dictionaries for internal storage of symbol mappings. Though dictionaries are mutable in python, users should not modify internal mappings of resolvers after creation. Doing so may have undesirable and unpredictable results.\n", + "\n", + "Instead, create a new dictionary and a new parameter resolver object rather than attempting to modify an existing object." + ] + }, { "cell_type": "markdown", "metadata": { diff --git a/docs/start/best_practices.md b/docs/start/best_practices.md new file mode 100644 index 00000000000..118c3df5a7d --- /dev/null +++ b/docs/start/best_practices.md @@ -0,0 +1,79 @@ +# Best Practices + +This page describes some of the best practices when using the Cirq library. +Following these guidelines will help you write code that is more performant and +less likely to break from version to version. Many of these rules apply to +other python libraries as well. + +## Use top-level constructs + +The Cirq library is designed so that important user-facing classes and objects +are exposed at the package level. Avoid referencing module names within cirq. + +For instance, use `cirq.X` and **not** `cirq.ops.X`. The second version will +break if we rename modules or move classes around from version to version. + +## Do not use private member variables of classes + +Any member of a class that is prefixed with an underscore is, by convention, a +private variable and should not be used outside of this class. For instance, +`cirq.XPowGate._dimension` should not be accessed or modified, since it is a +private member of that class. Using or modifying these values could result in +unexpected behavior or in broken code. + +## Do not mutate "immutable" classes + +While python's flexibility allows developers to modify just about anything, it +is bad practice to modify classes that are designed to be immutable. Doing so +can violate assumptions made in other parts of the library. + +In particular, attributes of `cirq.Gate`, `cirq.Operation`, `cirq.Moment`, and +`cirq.ParamResolver` should not be modified after creation. If these objects +need to be modified, a new object should be created instead. + +Violating this priniciple could cause problems in other parts of the code. For +instance, changing the qubits of an `cirq.Operation` could cause a `cirq.Moment` +that contains this Operation to have two Operations with the same qubits (which +is not allowed). + +Note that `Circuit` objects can be modified, but `FrozenCircuit` objects cannot. + +## Be mindful of exponential scaling + +Many algorithms and procedures in quantum computing scale in an exponential +pattern. Cirq is designed for the noisy intermediate-scale quantum computing +(NISQ) regime. Creating circuits with hundreds or thousands of qubits may +surpass the capabilities of this library. + +Even with smaller numbers of qubits, simulation and other tasks can very quickly +consume resources and time. The difference between a one second and an hour's +computation can be as few as ten qubits. + +## What you see is what you get + +Cirq tries to be as true to the specified circuits as possible, especially with +respect to hardware execution. Cirq highly discourages any hidden automatic +decomposition, compilation, or other modification of a circuit that is unknown +to the user. Any modification or transformation to the circuit should be +initiated by the user of the library. + +This philosophy is important for many use cases. For instance, certain +benchmarking algorithms rely on the fact that gate sequences will not be transparently optimized, even if the circuit is nominally inefficient. + +Of course, cirq provides routines and functions for compilation and +transformation of circuits. Users can and should call these routines. However, +cirq and resulting hardware integrations should not modify the circuits without +the user's "permission". + +## Other style and performance guidelines + +* Use `cirq.CircuitOperation` to more compactly define large, repeated + circuits. This can save space and time for analysis of larger circuits. +* For hardware execution of multiple circuits, prefer using `run_sweep` to + run variants of circuits. When not possible, try using `run_batch`. Using + these methods gives the hardware service the most opportunity to optimize + the execution of circuits and can result in much faster execution. +* Consider defining and allocating qubits at the beginning of your code or + function, then applying gates and circuits to those qubits. While not + required, this style can produce cleaner code. + From 194b6a89515e2344af6fdb8512747a83ef6a1129 Mon Sep 17 00:00:00 2001 From: Doug Strain Date: Fri, 24 Jun 2022 12:46:46 -0700 Subject: [PATCH 2/6] Review comments. --- docs/start/best_practices.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/start/best_practices.md b/docs/start/best_practices.md index 118c3df5a7d..24b3cb27c22 100644 --- a/docs/start/best_practices.md +++ b/docs/start/best_practices.md @@ -58,7 +58,7 @@ to the user. Any modification or transformation to the circuit should be initiated by the user of the library. This philosophy is important for many use cases. For instance, certain -benchmarking algorithms rely on the fact that gate sequences will not be transparently optimized, even if the circuit is nominally inefficient. +benchmarking algorithms rely on the fact that gate sequences will not be optimized, even if the circuit is nominally inefficient. Of course, cirq provides routines and functions for compilation and transformation of circuits. Users can and should call these routines. However, @@ -73,6 +73,7 @@ the user's "permission". run variants of circuits. When not possible, try using `run_batch`. Using these methods gives the hardware service the most opportunity to optimize the execution of circuits and can result in much faster execution. + Read more details on the [Parameter Sweeps](/cirq/simulate/params) page. * Consider defining and allocating qubits at the beginning of your code or function, then applying gates and circuits to those qubits. While not required, this style can produce cleaner code. From 4c9c8ea21b109eff3cb95a717c470cf34e9f053e Mon Sep 17 00:00:00 2001 From: Pavol Juhas Date: Fri, 24 Jun 2022 13:43:19 -0700 Subject: [PATCH 3/6] Fix typo and remove trailing blank line Make `git diff --check master` happy. --- docs/start/best_practices.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/start/best_practices.md b/docs/start/best_practices.md index 24b3cb27c22..a5b8b9379d5 100644 --- a/docs/start/best_practices.md +++ b/docs/start/best_practices.md @@ -31,7 +31,7 @@ In particular, attributes of `cirq.Gate`, `cirq.Operation`, `cirq.Moment`, and `cirq.ParamResolver` should not be modified after creation. If these objects need to be modified, a new object should be created instead. -Violating this priniciple could cause problems in other parts of the code. For +Violating this principle could cause problems in other parts of the code. For instance, changing the qubits of an `cirq.Operation` could cause a `cirq.Moment` that contains this Operation to have two Operations with the same qubits (which is not allowed). @@ -58,7 +58,8 @@ to the user. Any modification or transformation to the circuit should be initiated by the user of the library. This philosophy is important for many use cases. For instance, certain -benchmarking algorithms rely on the fact that gate sequences will not be optimized, even if the circuit is nominally inefficient. +benchmarking algorithms rely on the fact that gate sequences will not be optimized, +even if the circuit is nominally inefficient. Of course, cirq provides routines and functions for compilation and transformation of circuits. Users can and should call these routines. However, @@ -77,4 +78,3 @@ the user's "permission". * Consider defining and allocating qubits at the beginning of your code or function, then applying gates and circuits to those qubits. While not required, this style can produce cleaner code. - From 820e46eb4e325327537aa0ecd8d657d1e4349c5a Mon Sep 17 00:00:00 2001 From: Doug Strain Date: Fri, 24 Jun 2022 13:50:14 -0700 Subject: [PATCH 4/6] Update docs/start/best_practices.md Co-authored-by: Victory Omole --- docs/start/best_practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/start/best_practices.md b/docs/start/best_practices.md index a5b8b9379d5..b10f29ac70d 100644 --- a/docs/start/best_practices.md +++ b/docs/start/best_practices.md @@ -61,7 +61,7 @@ This philosophy is important for many use cases. For instance, certain benchmarking algorithms rely on the fact that gate sequences will not be optimized, even if the circuit is nominally inefficient. -Of course, cirq provides routines and functions for compilation and +Of course, Cirq provides routines and functions for compilation and transformation of circuits. Users can and should call these routines. However, cirq and resulting hardware integrations should not modify the circuits without the user's "permission". From 258d359762b064d02d3db7cd5662e627420eeab8 Mon Sep 17 00:00:00 2001 From: Doug Strain Date: Fri, 24 Jun 2022 13:50:21 -0700 Subject: [PATCH 5/6] Update docs/start/best_practices.md Co-authored-by: Victory Omole --- docs/start/best_practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/start/best_practices.md b/docs/start/best_practices.md index b10f29ac70d..4290e78dd32 100644 --- a/docs/start/best_practices.md +++ b/docs/start/best_practices.md @@ -63,7 +63,7 @@ even if the circuit is nominally inefficient. Of course, Cirq provides routines and functions for compilation and transformation of circuits. Users can and should call these routines. However, -cirq and resulting hardware integrations should not modify the circuits without +Cirq and resulting hardware integrations should not modify the circuits without the user's "permission". ## Other style and performance guidelines From ae2e7f9c362ed07574acaa675be14244fcfc7a5a Mon Sep 17 00:00:00 2001 From: Doug Strain Date: Fri, 24 Jun 2022 13:50:31 -0700 Subject: [PATCH 6/6] Update docs/start/best_practices.md Co-authored-by: Victory Omole --- docs/start/best_practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/start/best_practices.md b/docs/start/best_practices.md index 4290e78dd32..134c5b23531 100644 --- a/docs/start/best_practices.md +++ b/docs/start/best_practices.md @@ -8,7 +8,7 @@ other python libraries as well. ## Use top-level constructs The Cirq library is designed so that important user-facing classes and objects -are exposed at the package level. Avoid referencing module names within cirq. +are exposed at the package level. Avoid referencing module names within Cirq. For instance, use `cirq.X` and **not** `cirq.ops.X`. The second version will break if we rename modules or move classes around from version to version.