Improve cirq-dev installation command

README.md

@@ -125,7 +125,7 @@ documentation for Cirq is available.
 *   Docs for the [current stable release] correspond to what you get with
     `pip install cirq`.
 *   Docs for the [pre-release] correspond to what you get with
-    `pip install cirq~=1.0.dev`.
+    `pip install --upgrade cirq~=1.0.dev`.
 
 [current stable release]: https://quantumai.google/reference/python/cirq/all_symbols
 [pre-release]: https://quantumai.google/reference/python/cirq/all_symbols?version=nightly

cirq-aqt/README.md

@@ -38,7 +38,7 @@ two installation options for the `cirq-aqt` module:
 *   To install the latest pre-release version of `cirq-aqt`, use
 
     ```shell
-    pip install cirq-aqt~=1.0.dev
+    pip install --upgrade cirq-aqt~=1.0.dev
     ```
 
     (The `~=` has a special meaning to `pip` of selecting the latest version
@@ -47,7 +47,7 @@ two installation options for the `cirq-aqt` module:
 
 If you would like to install Cirq with all the optional modules, not just
 `cirq-aqt`, then instead of the above commands, use `pip install cirq` for the
-stable release or `pip install cirq~=1.0.dev` for the latest pre-release
+stable release or `pip install --upgrade cirq~=1.0.dev` for the latest pre-release
 version.
 
 ## Documentation

cirq-core/README.md

@@ -39,7 +39,7 @@ There are two installation options for the `cirq-core` module:
 *   To install the latest pre-release version of `cirq-core`, use
 
     ```shell
-    pip install cirq-core~=1.0.dev
+    pip install --upgrade cirq-core~=1.0.dev
     ```
 
     (The `~=` has a special meaning to `pip` of selecting the latest version
@@ -48,7 +48,7 @@ There are two installation options for the `cirq-core` module:
 
 If you would like to install Cirq with all the optional modules, not just
 `cirq-core`, then instead of the above commands, use `pip install cirq` for the
-stable release or `pip install cirq~=1.0.dev` for the latest pre-release
+stable release or `pip install --upgrade cirq~=1.0.dev` for the latest pre-release
 version.
 
 ## Documentation

cirq-core/cirq/contrib/quimb/Cirq-to-Tensor-Networks.ipynb

@@ -89,7 +89,7 @@
     "### Circuit to Tensors\n",
     "The circuit defines a tensor network representation. By default, the initial state is the `|0...0>` state (represented by the \"zero qubit\" operations labeled \"Q0\" in the legend. \"Q1\" are single qubit operations and \"Q2\" are two qubit operations. The open legs are the indices into the state vector and are of the form \"i{m}_q{n}\" where `m` is the time index (given by the returned `qubit_frontier` dictionary) and \"n\" is the qubit string.\n",
     "\n",
-    "Note: this notebook relies on unreleased Cirq features. If you want to try these features, make sure you install cirq via `pip install cirq~=1.0.dev`."
+    "Note: this notebook relies on unreleased Cirq features. If you want to try these features, make sure you install cirq via `pip install --upgrade cirq~=1.0.dev`."
    ]
   },
   {

cirq-core/cirq/contrib/quimb/Contract-a-Grid-Circuit.ipynb

@@ -5,7 +5,7 @@
    "metadata": {},
    "source": [
     "## Setup\n",
-    "Note: this notebook relies on unreleased Cirq features. If you want to try these features, make sure you install cirq via `pip install cirq~=1.0.dev`."
+    "Note: this notebook relies on unreleased Cirq features. If you want to try these features, make sure you install cirq via `pip install --upgrade cirq~=1.0.dev`."
    ]
   },
   {
@@ -20,14 +20,14 @@
     "    import cirq\n",
     "except ImportError:\n",
     "    print(\"installing cirq...\")\n",
-    "    !pip install --quiet cirq~=1.0.dev\n",
+    "    !pip install --upgrade --quiet cirq~=1.0.dev\n",
     "    print(\"installed cirq.\")\n",
     "\n",
     "try:\n",
     "    import quimb\n",
     "except ImportError:\n",
     "    print(\"installing cirq-core[contrib]...\")\n",
-    "    !pip install --quiet 'cirq-core[contrib]~=1.0.dev'\n",
+    "    !pip install --upgrade --quiet 'cirq-core[contrib]~=1.0.dev'\n",
     "    print(\"installed cirq-core[contrib].\")"
    ]
   },
@@ -38,7 +38,7 @@
     "# Contract a Grid Circuit\n",
     "Shallow circuits on a planar grid with low-weight observables permit easy contraction.\n",
     "\n",
-    "Note: this notebook relies on unreleased Cirq features. If you want to try these features, make sure you install cirq via `pip install cirq~=1.0.dev`."
+    "Note: this notebook relies on unreleased Cirq features. If you want to try these features, make sure you install cirq via `pip install --upgrade cirq~=1.0.dev`."
    ]
   },
   {

cirq-google/README.md

@@ -41,7 +41,7 @@ installation options for the `cirq-google` module:
 *   To install the latest pre-release version of `cirq-google`, use
 
     ```shell
-    pip install cirq-google~=1.0.dev
+    pip install --upgrade cirq-google~=1.0.dev
     ```
 
     (The `~=` has a special meaning to `pip` of selecting the latest version
@@ -50,7 +50,7 @@ installation options for the `cirq-google` module:
 
 If you would like to install Cirq with all the optional modules, not just
 `cirq-google`, then instead of the above commands, use `pip install cirq` for
-the stable release or `pip install cirq~=1.0.dev` for the latest pre-release
+the stable release or `pip install --upgrade cirq~=1.0.dev` for the latest pre-release
 version.
 
 ## Documentation

cirq-ionq/README.md

@@ -38,7 +38,7 @@ two installation options for the `cirq-ionq` module:
 *   To install the latest pre-release version of `cirq-ionq`, use
 
     ```shell
-    pip install cirq-ionq~=1.0.dev
+    pip install --upgrade cirq-ionq~=1.0.dev
     ```
 
     (The `~=` has a special meaning to `pip` of selecting the latest version
@@ -47,7 +47,7 @@ two installation options for the `cirq-ionq` module:
 
 If you would like to install Cirq with all the optional modules, not just
 `cirq-ionq`, then instead of the above commands, use `pip install cirq` for the
-stable release or `pip install cirq~=1.0.dev` for the latest pre-release
+stable release or `pip install --upgrade cirq~=1.0.dev` for the latest pre-release
 version.
 
 ## Documentation

cirq-pasqal/README.md

@@ -38,7 +38,7 @@ two installation options for the `cirq-pasqal` module:
 *   To install the latest pre-release version of `cirq-pasqal`, use
 
     ```shell
-    pip install cirq-pasqal~=1.0.dev
+    pip install --upgrade cirq-pasqal~=1.0.dev
     ```
 
     (The `~=` has a special meaning to `pip` of selecting the latest version
@@ -47,7 +47,7 @@ two installation options for the `cirq-pasqal` module:
 
 If you would like to install Cirq with all the optional modules, not just
 `cirq-pasqal`, then instead of the above commands, use `pip install cirq` for the
-stable release or `pip install cirq~=1.0.dev` for the latest pre-release
+stable release or `pip install --upgrade cirq~=1.0.dev` for the latest pre-release
 version.
 
 ## Documentation

cirq-rigetti/README.md

@@ -47,7 +47,7 @@ two installation options for the `cirq-rigetti` module:
 *   To install the latest pre-release version of `cirq-rigetti`, use
 
     ```shell
-    pip install cirq-rigetti~=1.0.dev
+    pip install --upgrade cirq-rigetti~=1.0.dev
     ```
 
     (The `~=` has a special meaning to `pip` of selecting the latest version
@@ -56,7 +56,7 @@ two installation options for the `cirq-rigetti` module:
 
 If you would like to install Cirq with all the optional modules, not just
 `cirq-rigetti`, then instead of the above commands, use `pip install cirq` for the
-stable release or `pip install cirq~=1.0.dev` for the latest pre-release
+stable release or `pip install --upgrade cirq~=1.0.dev` for the latest pre-release
 version.
 
 ## Documentation

cirq-web/README.md

@@ -36,7 +36,7 @@ two installation options for the `cirq-web` module:
 *   To install the latest pre-release version of `cirq-web`, use
 
     ```shell
-    pip install cirq-web~=1.0.dev
+    pip install --upgrade cirq-web~=1.0.dev
     ```
 
     (The `~=` has a special meaning to `pip` of selecting the latest version
@@ -45,7 +45,7 @@ two installation options for the `cirq-web` module:
 
 If you would like to install Cirq with all the optional modules, not just
 `cirq-web`, then instead of the above commands, use `pip install cirq` for the
-stable release or `pip install cirq~=1.0.dev` for the latest pre-release
+stable release or `pip install --upgrade cirq~=1.0.dev` for the latest pre-release
 version.
 
 ## Documentation

dev_tools/docs/build_api_docs.py

@@ -17,8 +17,8 @@
 In order to publish to our site, devsite runs two jobs for us: stable and nightly.
 The stable one downloads the latest cirq release from pypi and uses that to generate the reference
 API docs.
-The nightly one downloads the latest cirq pre-release (pip install cirq~=1.0.dev) and uses that to
-generate the "nightly diff".
+The nightly one downloads the latest cirq pre-release (pip install --upgrade cirq~=1.0.dev) and
+uses that to generate the "nightly diff".
 
 This script needs to cater for both of these cases.
 """

dev_tools/notebooks/isolated_notebook_test.py

@@ -44,11 +44,11 @@
 NOTEBOOKS_DEPENDING_ON_UNRELEASED_FEATURES: List[str] = [
     # Requires pinned quimb from #6438
     'cirq-core/cirq/contrib/quimb/Contract-a-Grid-Circuit.ipynb',
-    # Requires OpenQASM 3.0 support from cirq 1.6
+    # Requires OpenQASM 3.0 support from cirq 1.5
     'docs/build/interop.ipynb',
     # get_qcs_objects_for_notebook
     'docs/noise/qcvv/xeb_calibration_example.ipynb',
-    # Requires features the require cirq 1.5.
+    # Requires features in cirq 1.5.
     'docs/build/classical_control.ipynb',
 ]
 
@@ -173,7 +173,8 @@ def _rewrite_and_run_notebook(notebook_path, cloned_env):
             f"notebook (in Github Actions, you can download it from the workflow artifact"
             f" 'notebook-outputs'). \n"
             f"If this is a new failure in this notebook due to a new change, "
-            f"that is only available in main for now, consider adding `pip install cirq~=1.0.dev` "
+            f"that is only available in main for now, consider adding "
+            f"`pip install --upgrade cirq~=1.0.dev` "
             f"instead of `pip install cirq` to this notebook, and exclude it from "
             f"dev_tools/notebooks/isolated_notebook_test.py."
         )
@@ -221,10 +222,10 @@ def test_ensure_unreleased_notebooks_install_cirq_pre(notebook_path):
     with open(notebook_path, encoding="utf-8") as notebook:
         content = notebook.read()
         mandatory_matches = [
-            r"!pip install --quiet cirq(-google)?~=1\.\d*\.dev",
+            r"!pip install --upgrade --quiet cirq(-google)?~=1.0.dev",
             r"Note: this notebook relies on unreleased Cirq features\. "
             r"If you want to try these features, make sure you install cirq(-google)? via "
-            r"`pip install cirq(-google)?~=1\.\d*\.dev`\.",
+            r"`pip install --upgrade cirq(-google)?~=1.0.dev`\.",
         ]
 
         for m in mandatory_matches:

docs/build/classical_control.ipynb

@@ -59,7 +59,7 @@
     "id": "bb398b9478d3"
    },
    "source": [
-    "Note: this notebook relies on unreleased Cirq features. If you want to try these features, make sure you install cirq via `pip install cirq~=1.5.dev`."
+    "Note: this notebook relies on unreleased Cirq features. If you want to try these features, make sure you install cirq via `pip install --upgrade cirq~=1.0.dev`."
    ]
   },
   {
@@ -74,7 +74,7 @@
     "    import cirq\n",
     "except ImportError:\n",
     "    print(\"installing cirq...\")\n",
-    "    !pip install --quiet cirq~=1.5.dev\n",
+    "    !pip install --upgrade --quiet cirq~=1.0.dev\n",
     "    import cirq\n",
     "\n",
     "    print(\"installed cirq.\")"

docs/build/interop.ipynb

@@ -74,8 +74,8 @@
     "    import cirq\n",
     "except ImportError:\n",
     "    print(\"installing cirq...\")\n",
-    "    # Cirq 1.6 needed for OpenQASM 3.0 support",
-    "    !pip install --quiet cirq~=1.0.dev\n",
+    "    # Cirq 1.5 needed for OpenQASM 3.0 support",
+    "    !pip install --upgrade --quiet cirq~=1.0.dev\n",
     "    print(\"installed cirq.\")"
    ]
   },
@@ -86,7 +86,7 @@
    },
    "source": [
     "Cirq has several features that allow the user to import/export from other quantum languages.",
-    "Note: this notebook relies on unreleased Cirq features. If you want to try these features, make sure you install cirq via `pip install cirq~=1.0.dev`."
+    "Note: this notebook relies on unreleased Cirq features. If you want to try these features, make sure you install cirq via `pip install --upgrade cirq~=1.0.dev`."
    ]
   },
   {

docs/dev/notebooks.md

@@ -77,22 +77,22 @@ You should configure notebooks differently depending on whether they rely on fea
 
 When you introduce a notebook that depends on pre-release features of Cirq, make sure to
 
- - mark the notebook at the top that `Note: this notebook relies on unreleased Cirq features. If you want to try these feature, make sure you install cirq via pip install cirq~=1.0.dev`.
- - use `pip install cirq~=1.0.dev`  in the installation instructions
+ - mark the notebook at the top that `Note: this notebook relies on unreleased Cirq features. If you want to try these feature, make sure you install cirq via pip install --upgrade cirq~=1.0.dev`.
+ - use `pip install --upgrade cirq~=1.0.dev`  in the installation instructions
  - make sure [notebook_test.py](https://github.com/quantumlib/Cirq/blob/main/dev_tools/notebooks/notebook_test.py) covers the notebook
  - exclude the notebook from the [isolated_notebook_test.py](https://github.com/quantumlib/Cirq/blob/main/dev_tools/notebooks/isolated_notebook_test.py) by adding it to `NOTEBOOKS_DEPENDING_ON_UNRELEASED_FEATURES`
 
 ### Stable notebooks
 
 When you introduce a notebook that only uses already released features of Cirq, make sure to
- - use `pip install cirq` (NOT `pip install cirq~=1.0.dev`)
+ - use `pip install cirq` (NOT `pip install --upgrade cirq~=1.0.dev`)
  - ensure the notebook is not excluded from either [notebook_test.py](https://github.com/quantumlib/Cirq/blob/main/dev_tools/notebooks/notebook_test.py) or [isolated_notebook_test.py](https://github.com/quantumlib/Cirq/blob/main/dev_tools/notebooks/isolated_notebook_test.py)  (except if the notebook has external dependencies, in which case you should exclude this from both!)
 
 ### Release
 
 At release time, we change all the **pre-release notebooks** in bulk:
  - remove the pre-release notices
- - change `pip install cirq~=1.0.dev` to `pip install cirq`
+ - change `pip install --upgrade cirq~=1.0.dev` to `pip install cirq`
  - remove the exclusions in [isolated_notebook_test.py](https://github.com/quantumlib/Cirq/blob/main/dev_tools/notebooks/isolated_notebook_test.py) by making `NOTEBOOKS_DEPENDING_ON_UNRELEASED_FEATURES=[]`
 
 As all the notebooks have been tested continuously up to this point, the release notebook PR should pass without issues.

docs/gatezoo.ipynb

@@ -61,7 +61,7 @@
    },
    "source": [
     "## Setup\n",
-    "Note: this notebook relies on unreleased Cirq features. If you want to try these features, make sure you install cirq via `pip install cirq~=1.0.dev`"
+    "Note: this notebook relies on unreleased Cirq features. If you want to try these features, make sure you install cirq via `pip install --upgrade cirq~=1.0.dev`"
    ]
   },
   {
@@ -76,7 +76,7 @@
     "    import cirq\n",
     "except ImportError:\n",
     "    print(\"installing cirq...\")\n",
-    "    !pip install --quiet cirq~=1.0.dev\n",
+    "    !pip install --upgrade --quiet cirq~=1.0.dev\n",
     "    print(\"installed cirq.\")\n",
     "    \n",
     "import IPython.display as ipd\n",

docs/noise/qcvv/parallel_xeb.ipynb

@@ -65,7 +65,7 @@
     "    import cirq\n",
     "except ImportError:\n",
     "    print(\"installing cirq...\")\n",
-    "    !pip install --quiet cirq~=1.0.dev\n",
+    "    !pip install --upgrade --quiet cirq~=1.0.dev\n",
     "    print(\"installed cirq.\")"
    ]
   },

docs/noise/qcvv/xeb_calibration_example.ipynb

@@ -90,7 +90,7 @@
    "source": [
     "## Setup\n",
     "\n",
-    "Note: this notebook relies on unreleased Cirq features. If you want to try these features, make sure you install cirq via `pip install cirq~=1.0.dev`."
+    "Note: this notebook relies on unreleased Cirq features. If you want to try these features, make sure you install cirq via `pip install --upgrade cirq~=1.0.dev`."
    ]
   },
   {
@@ -116,7 +116,7 @@
     "try:\n",
     "    import cirq\n",
     "except ImportError:\n",
-    "    !pip install --quiet cirq~=1.0.dev"
+    "    !pip install --upgrade --quiet cirq~=1.0.dev"
    ]
   },
   {

docs/simulate/qvm_stabilizer_example.ipynb

@@ -504,7 +504,7 @@
    },
    "outputs": [],
    "source": [
-    "!pip install -q cirq-web~=1.0.dev\n",
+    "!pip install --upgrade --quiet cirq-web~=1.0.dev\n",
     "import cirq_web\n",
     "\n",
     "circuit_vis = cirq_web.Circuit3D(stabilizer_grid_circuit)\n",

docs/tutorials/google/colab.ipynb

@@ -84,7 +84,7 @@
     "    import cirq_google\n",
     "except ImportError:\n",
     "    print(\"installing cirq...\")\n",
-    "    !pip install --quiet cirq-google~=1.0.dev\n",
+    "    !pip install --upgrade --quiet cirq-google~=1.0.dev\n",
     "    print(\"installed cirq.\")\n",
     "    import cirq\n",
     "    import cirq_google"
@@ -157,7 +157,7 @@
     "\n",
     "For details of authentication and installation, please see [Get started with Quantum Computing Service](start.ipynb).\n",
     "\n",
-    "Note:  The below code will install the latest stable release of Cirq.  If you need the latest and greatest features and don't mind if a few things aren't quite working correctly, you can install the pre-release version of `cirq` using `pip install cirq~=1.0.dev` instead of `pip install cirq` to get the most up-to-date features of Cirq.\n",
+    "Note:  The below code will install the latest stable release of Cirq.  If you need the latest and greatest features and don't mind if a few things aren't quite working correctly, you can install the pre-release version of `cirq` using `pip install --upgrade cirq~=1.0.dev` instead of `pip install cirq` to get the most up-to-date features of Cirq.\n",
     "\n",
     "1. Enter the Cloud project ID you'd like to use in the `project_id` field.\n",
     "2. Then run the cell below (and go through the auth flow for access to the project id you entered).\n",

docs/tutorials/google/start.ipynb

@@ -69,7 +69,7 @@
    },
    "source": [
     "## Setup\n",
-    "Note: this notebook relies on unreleased Cirq features. If you want to try these features, make sure you install cirq via `pip install cirq-google~=1.0.dev`."
+    "Note: this notebook relies on unreleased Cirq features. If you want to try these features, make sure you install cirq via `pip install --upgrade cirq-google~=1.0.dev`."
    ]
   },
   {
@@ -85,7 +85,7 @@
     "    import cirq_google as cg\n",
     "except ImportError:\n",
     "    print(\"installing cirq-google and cirq...\")\n",
-    "    !pip install --quiet cirq-google~=1.0.dev cirq~=1.0.dev\n",
+    "    !pip install --upgrade --quiet cirq-google~=1.0.dev cirq~=1.0.dev\n",
     "    print(\"installed cirq-google and cirq.\")\n",
     "    import cirq\n",
     "    import cirq_google as cg"

docs/tutorials/google/visualizing_calibration_metrics.ipynb

@@ -105,7 +105,7 @@
     "\n",
     "For details of authentication and installation, please see [Get started with Quantum Computing Service](start.ipynb).\n",
     "\n",
-    "Note:  The below code will install the latest stable release of cirq.  If you need the latest and greatest features and don't mind if a few things aren't quite working correctly, you can install the pre-release version of `cirq` using `pip install cirq~=1.0.dev` instead of `pip install cirq` to get the most up-to-date features of cirq.\n",
+    "Note:  The below code will install the latest stable release of cirq.  If you need the latest and greatest features and don't mind if a few things aren't quite working correctly, you can install the pre-release version of `cirq` using `pip install --upgrade cirq~=1.0.dev` instead of `pip install cirq` to get the most up-to-date features of cirq.\n",
     "\n",
     "1. Enter the Cloud project ID you'd like to use in the `YOUR_PROJECT_ID` field.\n",
     "2. Then run the cell below (and go through the auth flow for access to the project id you entered).\n",

release.md

@@ -7,7 +7,7 @@ Note that Cirq development takes place on the `main` branch in GitHub. If you
 want to use a more stable version of Cirq, you should use one of the
 [releases](https://github.com/quantumlib/Cirq/releases) or install the package
 from PyPI using `pip install cirq`. The release from the latest commit to `main`
-can be installed with `pip install cirq~=1.0.dev`.
+can be installed with `pip install --upgrade cirq~=1.0.dev`.
 
 ## Versioning