From bd71e96c39299ed0557cbf9e699c41ad838353c6 Mon Sep 17 00:00:00 2001 From: Dave Bacon Date: Mon, 24 Jan 2022 16:38:41 -0800 Subject: [PATCH 1/3] Update module level documentation --- cirq-core/cirq/__init__.py | 2 ++ cirq-core/cirq/circuits/__init__.py | 2 +- cirq-core/cirq/contrib/__init__.py | 2 +- cirq-core/cirq/devices/__init__.py | 3 ++- cirq-core/cirq/experiments/__init__.py | 2 +- cirq-core/cirq/interop/__init__.py | 16 ++++++++++++++-- cirq-core/cirq/ion/__init__.py | 3 +-- cirq-core/cirq/json_resolver_cache.py | 1 + cirq-core/cirq/linalg/__init__.py | 2 +- cirq-core/cirq/neutral_atoms/__init__.py | 2 +- cirq-core/cirq/ops/__init__.py | 2 +- cirq-core/cirq/optimizers/__init__.py | 2 +- cirq-core/cirq/protocols/__init__.py | 2 +- cirq-core/cirq/qis/__init__.py | 2 +- cirq-core/cirq/sim/__init__.py | 2 +- cirq-core/cirq/study/__init__.py | 2 +- cirq-core/cirq/transformers/__init__.py | 2 +- cirq-core/cirq/type_workarounds.py | 3 ++- cirq-core/cirq/value/__init__.py | 2 +- cirq-core/cirq/vis/__init__.py | 9 +++++++-- 20 files changed, 42 insertions(+), 21 deletions(-) diff --git a/cirq-core/cirq/__init__.py b/cirq-core/cirq/__init__.py index f761e96c6c8..4e8542db29e 100644 --- a/cirq-core/cirq/__init__.py +++ b/cirq-core/cirq/__init__.py @@ -12,6 +12,8 @@ # See the License for the specific language governing permissions and # limitations under the License. +"""Cirq is a framework for creating, editing, and invoking quantum circuits.""" + from cirq import _import # A module can only depend on modules imported earlier in this list of modules diff --git a/cirq-core/cirq/circuits/__init__.py b/cirq-core/cirq/circuits/__init__.py index 269778baa9a..1f43cd480e1 100644 --- a/cirq-core/cirq/circuits/__init__.py +++ b/cirq-core/cirq/circuits/__init__.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Types and methods related to building and optimizing sequenced circuits.""" +"""Circuit classes, mutators, and outputs.""" from cirq.circuits.text_diagram_drawer import ( TextDiagramDrawer, diff --git a/cirq-core/cirq/contrib/__init__.py b/cirq-core/cirq/contrib/__init__.py index 1f42fe1afba..86e8944e1bb 100644 --- a/cirq-core/cirq/contrib/__init__.py +++ b/cirq-core/cirq/contrib/__init__.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Package for contributions. +"""Functionality that is not part of the core supported Cirq apis. Any contributions not ready for full production can be put in a subdirectory in this package. diff --git a/cirq-core/cirq/devices/__init__.py b/cirq-core/cirq/devices/__init__.py index 926c72c5cb0..1af4f58c8a7 100644 --- a/cirq-core/cirq/devices/__init__.py +++ b/cirq-core/cirq/devices/__init__.py @@ -12,7 +12,8 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Types for devices, device-specific qubits, and noise models.""" +"""Device classes, qubits, and topologies, as well as noise models.""" + from cirq.devices.device import ( Device, DeviceMetadata, diff --git a/cirq-core/cirq/experiments/__init__.py b/cirq-core/cirq/experiments/__init__.py index 46e99d2ef04..7a12206d15d 100644 --- a/cirq-core/cirq/experiments/__init__.py +++ b/cirq-core/cirq/experiments/__init__.py @@ -11,7 +11,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -"""Package containing characterization tools and experiments.""" +"""Experiments and tools for characterizing quantum operations.""" from cirq.experiments.google_v2_supremacy_circuit import ( generate_boixo_2018_supremacy_circuits_v2, diff --git a/cirq-core/cirq/interop/__init__.py b/cirq-core/cirq/interop/__init__.py index 7b34c17466d..6048fa5f86c 100644 --- a/cirq-core/cirq/interop/__init__.py +++ b/cirq-core/cirq/interop/__init__.py @@ -1,5 +1,17 @@ -# pylint: disable=wrong-or-nonexistent-copyright-notice -"""Package containing code for interoperating with other quantum software.""" +# Copyright 2022 The Cirq Developers +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +"""Methods for interoperating with other quantum software.""" from cirq.interop.quirk import ( quirk_json_to_circuit, diff --git a/cirq-core/cirq/ion/__init__.py b/cirq-core/cirq/ion/__init__.py index 23f230c37bf..1a4115e7855 100644 --- a/cirq-core/cirq/ion/__init__.py +++ b/cirq-core/cirq/ion/__init__.py @@ -12,8 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Types for representing and methods for manipulating ion trap operations. -""" +"""Trapped ion devices, gates, and compiling utilties.""" from cirq.ion.ion_gates import ( ms, diff --git a/cirq-core/cirq/json_resolver_cache.py b/cirq-core/cirq/json_resolver_cache.py index 03eb59c42d9..f8f14527279 100644 --- a/cirq-core/cirq/json_resolver_cache.py +++ b/cirq-core/cirq/json_resolver_cache.py @@ -11,6 +11,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +"""Methods for caching json serialization.""" import functools from typing import Dict, TYPE_CHECKING diff --git a/cirq-core/cirq/linalg/__init__.py b/cirq-core/cirq/linalg/__init__.py index 72de5494535..0574b201f7b 100644 --- a/cirq-core/cirq/linalg/__init__.py +++ b/cirq-core/cirq/linalg/__init__.py @@ -11,7 +11,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -"""Types and methods related to performing linear algebra. +"""Linear algebra methods and classes useful for quantum primitives. Focuses on methods useful for analyzing and optimizing quantum circuits. Avoids duplicating functionality present in numpy. diff --git a/cirq-core/cirq/neutral_atoms/__init__.py b/cirq-core/cirq/neutral_atoms/__init__.py index e766e6a404c..ca7741b576d 100644 --- a/cirq-core/cirq/neutral_atoms/__init__.py +++ b/cirq-core/cirq/neutral_atoms/__init__.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Device classes and tools specific to a neutral atom quantum processor.""" +"""Neutral atom devices and gates.""" from cirq.neutral_atoms.neutral_atom_devices import ( NeutralAtomDevice, diff --git a/cirq-core/cirq/ops/__init__.py b/cirq-core/cirq/ops/__init__.py index 849354a14df..f3e05092fb3 100644 --- a/cirq-core/cirq/ops/__init__.py +++ b/cirq-core/cirq/ops/__init__.py @@ -11,7 +11,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -"""Types for representing and methods for manipulating circuit operation trees. +"""Gates (unitary and non-unitary), operations, base types, and gate sets. """ from cirq.ops.arithmetic_operation import ( diff --git a/cirq-core/cirq/optimizers/__init__.py b/cirq-core/cirq/optimizers/__init__.py index 81286d45b48..36faecb6037 100644 --- a/cirq-core/cirq/optimizers/__init__.py +++ b/cirq-core/cirq/optimizers/__init__.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Circuit transformation utilities.""" +"""Classes and methods that optimize quantum circuits.""" from cirq.optimizers.align_left import ( AlignLeft, diff --git a/cirq-core/cirq/protocols/__init__.py b/cirq-core/cirq/protocols/__init__.py index f51d36370e3..daf3ddae09c 100644 --- a/cirq-core/cirq/protocols/__init__.py +++ b/cirq-core/cirq/protocols/__init__.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Methods and classes that define cirq's protocols.""" +"""Protocols (structural subtyping) supported in Cirq.""" from cirq.protocols.act_on_protocol import ( act_on, diff --git a/cirq-core/cirq/qis/__init__.py b/cirq-core/cirq/qis/__init__.py index 12e705ca5eb..87852d1dc9e 100644 --- a/cirq-core/cirq/qis/__init__.py +++ b/cirq-core/cirq/qis/__init__.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Tools and methods for quantum information science.""" +"""Tools and methods for primitives arising in quantum information science.""" from cirq.qis.channels import ( choi_to_kraus, diff --git a/cirq-core/cirq/sim/__init__.py b/cirq-core/cirq/sim/__init__.py index 2394f785b18..af1f572b4b7 100644 --- a/cirq-core/cirq/sim/__init__.py +++ b/cirq-core/cirq/sim/__init__.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Base simulation classes and generic simulators.""" +"""Classes for circuit simulators and base implementations of these classes.""" from typing import Tuple, Dict from cirq.sim.act_on_args import ( diff --git a/cirq-core/cirq/study/__init__.py b/cirq-core/cirq/study/__init__.py index c2bc2498c89..95497898f44 100644 --- a/cirq-core/cirq/study/__init__.py +++ b/cirq-core/cirq/study/__init__.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Types and methods for running studies (repeated trials).""" +"""Parameterized circuits and results.""" from cirq.study.flatten_expressions import ( ExpressionMap, diff --git a/cirq-core/cirq/transformers/__init__.py b/cirq-core/cirq/transformers/__init__.py index da5b5fc7e5e..9c2e4c89f1f 100644 --- a/cirq-core/cirq/transformers/__init__.py +++ b/cirq-core/cirq/transformers/__init__.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Circuit transformation utilities.""" +"""Classes and methods for transforming circuits.""" from cirq.transformers.analytical_decompositions import ( compute_cphase_exponents_for_fsim_decomposition, diff --git a/cirq-core/cirq/type_workarounds.py b/cirq-core/cirq/type_workarounds.py index 2e9e0d23686..919032412c6 100644 --- a/cirq-core/cirq/type_workarounds.py +++ b/cirq-core/cirq/type_workarounds.py @@ -12,7 +12,8 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Module defining NotImplementedType.""" +"""Workarounds for python typing gotchas.""" + from typing import Any # At the moment there's no reliable way to say 'NotImplementedType'. diff --git a/cirq-core/cirq/value/__init__.py b/cirq-core/cirq/value/__init__.py index da6cfc2b058..bbf81d71817 100644 --- a/cirq-core/cirq/value/__init__.py +++ b/cirq-core/cirq/value/__init__.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Value conversion utilities and types for time and quantum states.""" +"""Value conversion utilities and classes for time and quantum states.""" from cirq.value.abc_alt import ( ABCMetaImplementAnyOneOf, alternative, diff --git a/cirq-core/cirq/vis/__init__.py b/cirq-core/cirq/vis/__init__.py index bc3c8fefc94..3b5f560682e 100644 --- a/cirq-core/cirq/vis/__init__.py +++ b/cirq-core/cirq/vis/__init__.py @@ -12,14 +12,19 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Visualization utilities.""" +"""Classes and methods for visualizing results, quantum states, and devices.""" from cirq.vis.heatmap import Heatmap + from cirq.vis.heatmap import TwoQubitInteractionHeatmap from cirq.vis.histogram import integrated_histogram -from cirq.vis.state_histogram import get_state_histogram, plot_state_histogram +from cirq.vis.state_histogram import ( + get_state_histogram, + plot_state_histogram, +) + from cirq.vis.density_matrix import plot_density_matrix from cirq.vis.vis_utils import relative_luminance From 0e491270931a4ab8278a13c13a9834e3c198673a Mon Sep 17 00:00:00 2001 From: Dave Bacon Date: Mon, 24 Jan 2022 16:46:05 -0800 Subject: [PATCH 2/3] Fix wording --- cirq-core/cirq/contrib/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cirq-core/cirq/contrib/__init__.py b/cirq-core/cirq/contrib/__init__.py index 86e8944e1bb..68c3800fbf5 100644 --- a/cirq-core/cirq/contrib/__init__.py +++ b/cirq-core/cirq/contrib/__init__.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Functionality that is not part of the core supported Cirq apis. +"""Functionality that is not part of core supported Cirq apis. Any contributions not ready for full production can be put in a subdirectory in this package. From f79f23d51ce9c7a94bed5cd7e5204f52cb2c9269 Mon Sep 17 00:00:00 2001 From: Dave Bacon Date: Tue, 25 Jan 2022 14:31:42 -0800 Subject: [PATCH 3/3] Reviewer comments --- cirq-core/cirq/json_resolver_cache.py | 2 +- cirq-core/cirq/qis/__init__.py | 2 +- cirq-core/cirq/type_workarounds.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/cirq-core/cirq/json_resolver_cache.py b/cirq-core/cirq/json_resolver_cache.py index f8f14527279..cb75d22196d 100644 --- a/cirq-core/cirq/json_resolver_cache.py +++ b/cirq-core/cirq/json_resolver_cache.py @@ -11,7 +11,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -"""Methods for caching json serialization.""" +"""Methods for resolving JSON types during serialization.""" import functools from typing import Dict, TYPE_CHECKING diff --git a/cirq-core/cirq/qis/__init__.py b/cirq-core/cirq/qis/__init__.py index 87852d1dc9e..d2ca57d32f9 100644 --- a/cirq-core/cirq/qis/__init__.py +++ b/cirq-core/cirq/qis/__init__.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Tools and methods for primitives arising in quantum information science.""" +"""Tools and methods for primitives used in quantum information science.""" from cirq.qis.channels import ( choi_to_kraus, diff --git a/cirq-core/cirq/type_workarounds.py b/cirq-core/cirq/type_workarounds.py index 919032412c6..6d903f65925 100644 --- a/cirq-core/cirq/type_workarounds.py +++ b/cirq-core/cirq/type_workarounds.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Workarounds for python typing gotchas.""" +"""Workarounds for deficiencies in python's typing system.""" from typing import Any