Enhanced tutorial book for Issue #424

docs/_book.yaml

@@ -6,49 +6,60 @@ upper_tabs:
   menu:
   - include: /_book/menu_software.yaml
   lower_tabs:
-    # Subsite tabs
-    other:
-    - name: "Tutorials"
-      - title: "Get started with qsimcirq"
-        path: /qsim/tutorials/qsimcirq
-      - title: "Quantum simulation on GCP with Cirq and qsim"
-        path: /qsim/tutorials/qsimcirq_gcp
-      - title: "Simulate a large quantum circuit"
-        path: /qsim/tutorials/q32d14
-    - name: "Guide"
-      contents:
-      - title: "qsim and qsimh"
-        path: /qsim/overview
-      - title: "Usage"
-        path: /qsim/usage
-      - title: "Installing qsimcirq"
-        path: /qsim/install_qsimcirq
-      - title: "Cirq interface"
-        path: /qsim/cirq_interface
-      - title: "Input circuit file format"
-        path: /qsim/input_format
-      - title: "Template naming"
-        path: /qsim/type_reference
-      - title: "Build with Bazel"
-        path: /qsim/bazel
-      - title: "Testing qsim"
-        path: /qsim/testing
-      - title: "Docker"
-        path: /qsim/docker
-      - title: "Release process"
-        path: /qsim/release
-    - name: "Python Reference"
-      skip_translation: true
-      contents:
-      - title: "All Symbols"
-        path: /reference/python/qsimcirq/all_symbols
-      - include: /reference/python/qsimcirq/_toc.yaml
+   # Subsite tabs
+   other:
+   - name: "Tutorials"
+     contents:
+       - title: "Get started with qsimcirq"
+         path: /qsim/tutorials/qsimcirq
+       - heading: "qsim on Google Cloud"
+       - title: "Before you begin"
+         path: /qsim/tutorials/gcp_before_you_begin
+       - title: "CPU-based simulation"
+         path: /qsim/tutorials/gcp_cpu
+       - title: "GPU-based simulation"
+         path: /qsim/tutorials/gcp_gpu
+       - heading: "Other tutorials"
+       - title: "Simulate a large circuit"
+         path: /qsim/tutorials/q32d14
+       - title: "Noise simulation"
+         path: /qsim/tutorials/noisy_qsimcirq
 
-    - name: "C++ Reference"
-      skip_translation: true
-      contents:
-      - title: "All Symbols"
-        path: /reference/cc/qsim
-      - include: /reference/cc/qsim/_doxygen.yaml
+   - name: "Guide"
+     contents:
+       - title: "qsim and qsimh"
+         path: /qsim/overview
+       - title: "Usage"
+         path: /qsim/usage
+       - title: "Installing qsimcirq"
+         path: /qsim/install_qsimcirq
+       - title: "Cirq interface"
+         path: /qsim/cirq_interface
+       - title: "Input circuit file format"
+         path: /qsim/input_format
+       - title: "Template naming"
+         path: /qsim/type_reference
+       - title: "Build with Bazel"
+         path: /qsim/bazel
+       - title: "Testing qsim"
+         path: /qsim/testing
+       - title: "Docker"
+         path: /qsim/docker
+       - title: "Release process"
+         path: /qsim/release
+
+   - name: "Python Reference"
+     skip_translation: true
+     contents:
+       - title: "All Symbols"
+         path: /reference/python/qsimcirq/all_symbols
+       - include: /reference/python/qsimcirq/_toc.yaml
+
+   - name: "C++ Reference"
+     skip_translation: true
+     contents:
+     - title: "All Symbols"
+       path: /reference/cc/qsim
+     - include: /reference/cc/qsim/_doxygen.yaml
 
 - include: /_book/upper_tabs_right.yaml

docs/tutorials/gcp_before_you_begin.md

@@ -0,0 +1,34 @@
+# Before you begin
+
+The following tutorials demonstrate how to configure the Google Cloud Platform
+to run quantum simulations with qsim.
+
+You can use Google Cloud to run high-performance CPU-based simulations or
+GPU-based simulations, depending on your requirements. For more information
+about making a choice between CPU- and GPU-based simulations, see
+[Choosing hardware for your qsim simulation]().
+
+This tutorial depends on resources provided by the Google Cloud Platform.
+
+*   **Ensure that you have a Google Cloud Platform project.** You can reuse an
+    existing project, or create a new one, from your
+    [project dashboard](https://console.cloud.google.com/projectselector2/home/dashboard).
+    *   For more information about Google Cloud projects, see
+        [Creating and managing projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects)
+        in the Google Cloud documentation.
+*   **Ensure that billing is enabled for your project.**
+    *   For more information about billing, see
+        [Enable, disable, or change billing for a project](https://cloud.google.com/billing/docs/how-to/modify-project#enable-billing)
+        in the Google Cloud documentation.
+*   **Estimate costs for your project** Use the
+    [Google Cloud Pricing Calculator](https://cloud.google.com/products/calculator)
+    to estimate the scale of the costs you might incur, based on your projected
+    usage. The resources that you use to simulate a quantum circuit on the
+    Google Cloud platform are billable.
+*   **Enable the Compute Engine API for your project.** You can enable APIs from
+    the [API Library Console](https://console.cloud.google.com/apis/library). On
+    the console, in the search box, enter "compute engine api" to find the API
+    and click through to Enable it.
+    *   For more information about enabling the Compute Engine API, see
+        [Getting Started](https://cloud.google.com/apis/docs/getting-started) in
+        the Google Cloud documentation.

docs/tutorials/gcp_cpu.md

@@ -0,0 +1,242 @@
+# CPU-based quantum simulation on Google Cloud
+
+In this tutorial, you configure and test a virtual machine (VM) to run CPU-based
+quantum simulations. The configuration in this tutorial uses the qsim Docker
+container, running on a Google Compute Engine VM.
+
+## 1. Create a virtual machine
+
+Follow the instructions in the
+[Quickstart using a Linux VM](https://cloud.google.com/compute/docs/quickstart-linux)
+guide to create a VM. In addition to the guidance under the Create a Linux VM
+instance heading, ensure that your VM has the following properties:
+
+*   In the Machine Configuration section, in the Machine family options,
+    click on the **Compute Optimized** filter.
+*   In the Machine Configuration section, in the Machine family options, in
+    the Series option, choose **C2**.
+*   In the Machine Configuration section, in the Machine family options, in
+    the Machine type option, choose **c2-standard-16**. This option gives
+    you 16 virtual CPUS and 64MB of RAM.
+    *   This choice is for demonstration purposes only.
+<!-- TODO(cognigami): Add the following sentence to the sub-bullet when the doc
+is published: "For a live experiment, see [Choosing hardware for your qsim simulation]().-->
+*   In the Boot disk section, click the Change button, and choose
+    Container-Optimized OS. This overrides step 3 in the quickstart guide.
+*   In the Firewall section, ensure that both the **Allow HTTP traffic**
+    checkbox and **Allow HTTPS traffic** checkbox have marks.
+
+When Google Cloud finishes creating the VM, you can see your VM listed in the
+[Compute Instances dashboard](https://pantheon.corp.google.com/compute/instances)
+for your project.
+
+### Find out more
+* [Choosing the right machine family and
+  type](https://cloud.google.com/blog/products/compute/choose-the-right-google-compute-engine-machine-type-for-you)
+* [Container-Optimized OS
+  Overview](https://cloud.google.com/container-optimized-os/docs/concepts/features-and-benefits)
+
+## 2. Prepare your computer
+
+Use SSH to create an encrypted tunnel from your computer to your VM and redirect
+a local port to your VM over the tunnel.
+
+1.  Install the `gcloud` command line tool. Follow the instructions in the
+    [Installing Cloud SDK](https://cloud.google.com/sdk/docs/install)
+    documentation.
+2.  After installation, run the `gcloud init` command to initialize the Google
+    Cloud environment. You need to provide the `gcloud` tool with details
+    about your VM, such as the project name and the region where your VM is
+    located.
+    1.  You can verify your environment by using the `gcloud config list`
+        command.
+3.  Create an SSH tunnel and redirect a local port to use the tunnel by typing
+    the following command in a terminal window on your computer. Replace
+    `[YOUR_INSTANCE_NAME]` with the name of your VM.
+
+    ```
+    gcloud compute ssh [YOUR_INSTANCE_NAME] -- -L 8888:localhost:8888
+    ```
+
+When the command completes successfully, your prompt changes from your local
+machine to your virtual machine.
+
+## 3. Start the qsim Docker container on your virtual machine
+
+On your VM, start the qsim container by typing the following command at the
+command prompt, on your VM from the previous step.
+
+```
+docker run -v `pwd`:/homedir -p 8888:8888 gcr.io/quantum-builds/github.com/quantumlib/jupyter_qsim:latest &
+```
+
+If you see a `permission denied` error message, you might need to add `sudo`
+before your Docker command. For more information about running Docker, see the
+[`docker run` command reference](https://docs.docker.com/engine/reference/run/#general-form).
+
+As Docker downloads and starts the container, it prints many lines of output.
+The last few lines should be similar to the following output:
+
+```
+To access the notebook, open this file in a browser:
+    file:///root/.local/share/jupyter/runtime/nbserver-1-open.html
+Or copy and paste one of these URLs:
+    http://e1f7a7cca9fa:8888/?token=aa16e1b6d3f51c58928037d34cc6854dac47347dd4c0eae5
+    or http://127.0.0.1:8888/?token=aa16e1b6d3f51c58928037d34cc6854dac47347dd4c0eae5
+```
+
+Copy the URL in the last line of output from your console, and save it for the
+next step.
+
+## 4. Connect to your virtual machine
+
+The easiest way to use your VM is through a notebook environment like
+[Google Colaboratory](https://colab.sandbox.google.com/notebooks/intro.ipynb?utm_source=scs-index#recent=true)
+(Colab). Google Colab is a free, hosted notebook environment that enables you to
+write, execute, and share Python code from your browser.
+
+However, the qsim Docker image also includes a Jupyter kernel and other
+command-line tools. These tools enable you to connect directly to your container
+and run your code.
+
+*   {Colab}
+
+      You can write code in a Colab notebook, and use your VM to run your code. In
+      this scenario, we use the
+      [Get Started with qsimcirq Colab notebook](https://quantumai.google/qsim/tutorials/qsimcirq).
+
+      1.  Open the
+          [Get Started with qsimcirq notebook](https://quantumai.google/qsim/tutorials/qsimcirq).
+      2.  Near the top-right corner of your notebook, click the small triangle beside
+          the Connect button to open the menu.
+      3.  Choose the **Connect to a local runtime** option to open the Local
+          connection settings window.
+          <img src="../images/colab_connect.png" alt="Google Colab Connect to Local Runtime button" style="width: 62%" class="screenshot">
+      1.  In the Backend URL text field, paste the URL that you saved in step 5.
+      2.  Change the part of your URL that read `127.0.0.1` to `localhost`.
+          <img src="../images/colab_remote.png" alt="Google Colab Local Runtime connection window" style="width: 62%" class="screenshot">
+      1.  Click the **Connect** button in the Local connection settings window.
+
+      When your connection is ready, Colab displays a green checkmark beside the
+      Connected (Local) button near the top-right corner of your notebook.
+
+      <img src="../images/colab_connected.png" alt="Google Colab Local Runtime connection windo" style="width: 62%" class="screenshot">
+
+      The code cells in your notebook now execute on your VM instead of your local
+      computer.
+
+*   {Jupyter}
+
+      You can run your simulation directly in your Docker container, in Jupyter.
+      Jupyter runs in the qsim Docker container.
+
+      1.  Open a browser window.
+      2.  In the navigation bar, paste the URL that you copied in step 4.
+      3.  In the browser you should now see the Jupyter UI, running on your VM.
+
+      The code that you execute here executes on your VM. You can navigate to qsim >
+      docs > tutorials to try other tutorials.
+
+*   {Command line}
+
+      You can run a quantum simulation using qsim from the command line.
+      Your code runs in the qsim Docker container.
+
+      **Before you begin**
+
+      For this scenario, you can connect to your machine directly over SSH rather than
+      create a tunnel. In step 2.3 above, remove the second half of the command.
+      Instead of the following command:
+
+      ```
+      gcloud compute ssh [YOUR_INSTANCE_NAME] -- -L 8888:localhost:8888
+      ```
+
+      Run:
+
+      ```
+      gcloud compute ssh [YOUR_INSTANCE_NAME]
+      ```
+
+      Either command works for the purpose of this tutorial. Continue to step 4 then
+      complete the steps below, regardless of which command you use.
+
+      **1. Copy the container ID for your qsim Docker container**
+
+      Run `docker ps` to display the container ID. The output should look like
+      the following text:
+
+      ```
+      CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES i
+      8ab217d640a3 gcr.io/quantum-291919/jupyter_qsim:latest "jupyter-notebook --…" 2 hours ago Up 2 hours 0.0.0.0:8888->8888/tcp dazzling_lovelace.
+      ```
+
+      In this case, the container ID is `8ab217d640a3`.
+
+      **2. Connect to your qsim Docker container**
+
+      Run `docker exec` to login to your container. Replace `[CONTAINER_ID]`
+      with the ID that you copied in step 1.
+
+      ```
+      docker exec -it [CONTAINER_ID] /bin/bash
+      ```
+
+      Your command prompt now executes commands in the container.
+
+      **3. Verify your installation**
+
+      You can use the code below to verify that qsim uses your qsim installation.
+      You can paste the code directly into the REPL, or paste the code in a
+      file.
+
+      ```
+      # Import Cirq and qsim
+      import cirq
+      import qsimcirq
+
+      # Instantiate qubits and create a circuit
+      q0, q1 = cirq.LineQubit.range(2)
+      circuit = cirq.Circuit(cirq.H(q0), cirq.CX(q0, q1))
+
+      # Instantiate a simulator that uses the GPU
+      qsim_simulator = qsimcirq.QSimSimulator()
+
+      # Run the simulation
+      print("Running simulation for the following circuit:")
+      print(circuit)
+
+      qsim_results = qsim_simulator.compute_amplitudes(
+          circuit, bitstrings=[0b00, 0b01])
+
+      print("qsim results:")
+      print(qsim_results)
+      ```
+
+      After a moment, you should see a result that looks similar to the following.
+
+      ```
+      [(0.7071067690849304+0j), 0j]
+      ```
+
+## Next steps
+
+After you finish, don't forget to stop or delete your VM on the Compute
+Instances dashboard.
+
+You are now ready to run your own large simulations on Google Cloud. If you want
+to try a large circuit on Google Cloud, you can connect the
+[Simulate a large quantum circuit](https://colab.sandbox.google.com/github/quantumlib/qsim/blob/master/docs/tutorials/q32d14.ipynb)
+Colab notebook to your VM
+([documentation](https://quantumai.google/qsim/tutorials/q32d14)).
+
+For more information about managing your VM, see the following documentation
+from Google Cloud:
+
+*   [Stopping and starting a VM](https://cloud.google.com/compute/docs/instances/stop-start-instance)
+*   [Suspending and resuming an instance](https://cloud.google.com/compute/docs/instances/suspend-resume-instance)
+*   [Deleting a VM instance](https://cloud.google.com/compute/docs/instances/deleting-instance)
+
+As an alternative to Google Cloud, you can download the Docker container or the
+qsim source code to run quantum simulations on your own high-performance
+computing platform.