Miscellaneous updates & fixes for typos & grammar (#814)

Co-authored-by: Pavol Juhas <[email protected]>

Author: mhucka

docs/_index.yaml

@@ -33,18 +33,18 @@ landing_page:
     - description: >
         <h4>qsim</h4>
         <p>
-        qsim is a full wave function simulator written in C++. It uses gate
-        fusion, AVX/FMA vectorized instructions and multi-threading using
-        OpenMP to achieve state of the art simulations of quantum circuits.
+        qsim is a full state-vector simulator written in C++. It uses gate
+        fusion, AVX/FMA vectorized instructions, and multithreading using
+        OpenMP to achieve state-of-the-art simulations of quantum circuits.
         qsim is integrated with Cirq and can be used to run simulations of up
-        to 40 qubits on a 90 core Intel Xeon workstation.
+        to 40 qubits on a 90-core Intel Xeon workstation.
         </p>
       buttons:
-      - label: Get started with qsim on Cirq
+      - label: Get started with qsim in Cirq
         path: /qsim/tutorials/qsimcirq
         classname: button button-primary
         icon_name: open_in_new
-      - label: GitHub repository
+      - label: GitHub repository for qsim
         path: //github.com/quantumlib/qsim
         classname: button button-white
         icon_name: open_in_new
@@ -82,10 +82,10 @@ landing_page:
       image_path: /site-assets/images/cards/qsim-card-cirq-integrations.png
       description: >
         Cirq is a python framework for writing, simulating, and executing
-        quantum programs. Cirq's built in simulator is useful to around 20
-        qubits. By using the qsim Cirq simulator one can boost the number of
-        qubits simulated to be mostly limited by available ram. Up to 40 qubits
-        can be simulated on a 90 core Intel Xeon workstation.
+        quantum programs. Cirq's built-in simulator is useful to around 20
+        qubits. By using the `qsimcirq` simulator, one can boost the number of
+        qubits simulated to be mostly limited by available RAM. Up to 40 qubits
+        can be simulated on a 90-core Intel Xeon workstation.
       buttons:
       - label: "Learn more"
         path: /qsim/cirq_interface

docs/bazel.md

@@ -51,7 +51,7 @@ Pick at most one of the following options:
 # Use SSE instructions for vector arithmetic.
 --config=sse
 
-# Do not use vector arithmetic optimization (deault).
+# Do not use vector arithmetic optimization (default).
 --config=basic
 ```
 

docs/cirq_interface.md

@@ -97,9 +97,9 @@ my_sim = qsimcirq.QSimSimulator()
 myres = my_sim.compute_amplitudes(program=my_circuit,
                                   bitstrings=[0b00, 0b01, 0b10, 0b11])
 ```
-In the above example, the simulation is performed for the specified bitstrings
+In the example above, the simulation is performed for the specified bitstrings
 of length 2. All the bitstring lengths should be equal to the number of qubits
-in `qsim_circuit`. Otherwise, BitstringsFromStream will raise an error.
+in `qsim_circuit`. Otherwise, `BitstringsFromStream` will raise an error.
 
 Finally, to retrieve sample measurements the `run` method can be used. This requires
 the circuit to have measurements to sample from, else an error will be raised.
@@ -133,7 +133,7 @@ myres = my_sim.simulate(program=my_circuit)
 
 `QSimhSimulator` uses a hybrid Schrödinger-Feynman simulator. This limits it to
 returning amplitudes for specific output bitstrings, but raises its upper
-bound on number of qubits simulated (50+ qubits, depending on depth).
+bound on number of qubits simulated (50+ qubits, depending on circuit depth).
 
 To acquire amplitudes for all output bitstrings of length 2:
 ```

docs/docker.md

@@ -3,13 +3,23 @@
 [Docker](https://docker.com) can be used to run qsim tests in a self-contained
 environment, regardless of your local operating system.
 
-**NOTE:** Docker requires root access to run. If you see errors when running
-the commands below, you may need to call them with `sudo`.
+Note that Docker is _not_ usually preinstalled on popular operating systems
+such as MacOS, Windows, or Linux, so you will most likely have to install
+Docker components yourself. Also, depending on the system, installing Docker
+may require root access on your computer (e.g., using `sudo` on Linux).
+
+The following packages are needed for the steps described on the rest of this
+page:
+
+*   `docker`
+*   `docker-buildx`
+*   `docker-compose`
 
 ## Build Docker Images
 
-Prior to building with Docker, make sure that your repository is clean and all
-submodules are up-to-date. The following commands should accomplish this:
+Prior to building with Docker, make sure that your local copy of the qsim
+source code repository is clean and all submodules are up-to-date. The
+following commands should accomplish this:
 
 ```
 make clean
@@ -19,32 +29,35 @@ git submodule update --init --recursive
 To build qsim and run all the tests:
 
 ```
-# docker compose up --build
+docker compose up --build
 ```
 
 `docker compose` will create the `qsim`, `qsim-cxx-tests`, and `qsim-py-tests`
-images and automatically run all tests. A successful run should have the
-following messages somewhere in the logs:
+images and automatically run all the tests for those targets. A successful run
+should have the following messages somewhere in the logs:
 
 ```
 qsim-cxx-tests exited with code 0
 qsim-py-tests exited with code 0
 ```
 
-To build without running tests, simply run:
+To build the Docker image without running tests, simply run:
 
 ```
-# docker compose build
+docker compose build
 ```
 
+Note that currently (qsim version 0.23.0), the Docker build does not make use
+of CUDA or GPUs.
+
 ## Run Simulations
 
-Once the `qsim` image is created, it can be used to run the `qsim_base.x`
-simulation binary with the following command:
+Once the `qsim` Docker image is created, it can be used to run the
+`qsim_base.x` simulation binary with the following command:
 
 ```
-# docker run -ti --rm -v $PWD/circuits:/qsim/circuits:ro \
-                      qsim:latest -c /qsim/circuits/circuit_q24
+docker run -ti --rm -v $PWD/circuits:/qsim/circuits:ro \
+    qsim:latest -c /qsim/circuits/circuit_q24
 ```
 
 The flag `-v [orig]:[dest]:[attr]` is required to allow access to the host
@@ -57,7 +70,7 @@ Once the `qsim-cxx-tests` image is created, use the following command to run
 all C++ tests:
 
 ```
-# docker run -ti --rm qsim-cxx-tests
+docker run -ti --rm qsim-cxx-tests
 ```
 
 ## Run Python Tests
@@ -66,5 +79,5 @@ Once the `qsim-py-tests` image is created, use the following command to run
 all Python tests:
 
 ```
-# docker run -ti --rm qsim-py-tests
+docker run -ti --rm qsim-py-tests
 ```

docs/install_qsimcirq.md

@@ -1,12 +1,12 @@
 # Installing qsimcirq
 
 The qsim-Cirq Python interface is available as a PyPI package for Linux, MacOS and Windows users.
-For all others, Dockerfiles are provided to install qsim in a contained
+For all others, Dockerfiles are provided to install qsim in a containerized
 environment.
 
 **Note:** The core qsim library (under
 [lib/](https://github.com/quantumlib/qsim/blob/master/lib)) can be included
-directly in C++ code without installing this interface.
+directly in C++ code without building and installing the qsimcirq interface.
 
 ## Before installation
 
@@ -25,46 +25,59 @@ file. You can install them with `pip3 install -r dev-requirements.txt` or
 
 ## Linux installation
 
-We provide `qsimcirq` Python wheels on 64-bit `x86` architectures with `Python 3.{7,8,9,10,11,12}`.
+We provide `qsimcirq` Python wheels on 64-bit `x86` architectures with
+`Python 3.{10,11,12,13}`. The installation process will automatically check for
+CUDA and GPUs on your computer if they exist and attempt to build a version of
+qsim that can make use of the GPU(s). (Note that this is presently an
+installation-time action and will take several minutes to finish.)
 
 Simply run `pip3 install qsimcirq`.
 
 ## MacOS installation
 
-We provide `qsimcirq` Python wheels on `x86` architectures with `Python 3.{7,8,9,10,11,12}`.
+We provide `qsimcirq` Python wheels on `x86` and Apple Silicon architectures
+with `Python 3.{10,11,12,13}`.
 
 Simply run `pip3 install qsimcirq`.
 
+Note that, due to architectural differences, CUDA support is not available on
+MacOS. The version of `qsimcirq` on MacOS will only use the CPU, without GPU
+acceleration.
+
 ## Windows installation
 
-We provide `qsimcirq` Python wheels on 64-bit `x86` and `amd64` architectures with `Python 3.{7,8,9,10,11,12}`.
+We provide `qsimcirq` Python wheels on 64-bit `x86` and `amd64` architectures
+with `Python 3.{10,11,12,13}`.
 
 Simply run `pip3 install qsimcirq`.
 
-## There's no compatible wheel for my machine!
-
-If existing wheels do no meet your needs please open an issue with your machine configuration (i.e. CPU architecture, Python version) and consider using the [Docker config](./docker.md) provided with this repository.
-
 ## Conda Installation
 
-`qsimcirq` is now also available on conda-forge for Linux x86 including CUDA builds and MacOS x86 and Apple Silicon ARM64.
-To install `qsimcirq` using conda, you can use the following command:
+`qsimcirq` is also available on conda-forge for Linux x86 including CUDA builds
+and MacOS x86 and Apple Silicon ARM64. To install `qsimcirq` using conda, you
+can use the following command:
 
 ```
 conda install -c conda-forge qsimcirq
 ```
 
 This will install the `qsimcirq` package from the conda-forge channel.
 
+## Help! There's no compatible wheel for my machine!
+
+If existing wheels do no meet your needs, please open an issue with your
+machine configuration (i.e., CPU architecture, Python version) and consider
+using the [Docker config](./docker.md) provided in the qsim GitHub repository.
+
 ## Testing
 
 After installing `qsimcirq` on your machine, you can test the installation by
 copying [qsimcirq_tests/qsimcirq_test.py](qsimcirq_tests/qsimcirq_test.py)
 to your machine and running `python3 -m pytest qsimcirq_test.py`.
 
-It also has examples of how how to use this package.
+The file `qsimcirq_test.py` also has examples of how to use qsimcirq.
 
 **Note:** Because of how Python searches for modules, the test file cannot
 be run from inside a clone of the qsim repository, or from any parent
 directory of such a repository. Failure to meet this criteria may result
-in misbehaving tests (e.g. false positives after a failed install).
+in misbehaving tests (e.g., false positives after a failed installation).

docs/overview.md

@@ -8,27 +8,28 @@ qsim makes use of AVX/FMA vector operations, OpenMP multithreading, and
 gate fusion [[1]](https://arxiv.org/abs/1601.07195)
 [[2]](https://arxiv.org/abs/1704.01127)
 to accelerate simulations. This performance is best demonstrated by the use
-of qsim in cross-entropy benchmarks here:
+of qsim in cross-entropy benchmarks
 [[3]](https://www.nature.com/articles/s41586-019-1666-5).
 
-Integration with [Cirq](https://github.com/quantumlib/Cirq) makes getting 
+Integration with [Cirq](https://github.com/quantumlib/Cirq) makes getting
 started with qsim easy! Check out the
-[install guide](https://github.com/quantumlib/qsim/blob/master/docs/install_qsimcirq.md)
+[installation guide](https://github.com/quantumlib/qsim/blob/master/docs/install_qsimcirq.md)
 or try the runnable
 [notebook tutorial](https://github.com/quantumlib/qsim/blob/master/docs/tutorials/qsimcirq.ipynb).
 
 ## Design
 
-This repository includes two top-level libraries for simulation:
+The git repository for qsim includes two top-level libraries for simulation:
 
 -   **qsim** is a Schrödinger state-vector simulator designed to run on a
-    single machine. It produces the full state vector as output which, 
+    single machine. It produces the full state vector as output which,
     for instance, allows users to sample repeatedly from a single execution.
 -   **qsimh** is a hybrid Schrödinger-Feynman simulator built for parallel
-    execution on a cluster of machines. It produces amplitudes for user-
-    specified output bitstrings.
+    execution on a cluster of machines. It produces amplitudes for
+    user-specified output bitstrings. Compared to qsim, by limiting what it
+    returns, qsimh can simulate more qubits.
 
-These libraries can be invoked either directly or through the qsim-Cirq 
+These libraries can be invoked either directly or through the qsim-Cirq
 interface to perform the following operations:
 
 -   Determine the final state vector of a circuit (qsim only).