Update docs to cover CUDA-aware MPI in more details (#945)

Author: 1tnguyen

docs/sphinx/examples/python/bernstein_vazirani.py

@@ -83,6 +83,11 @@ def bernstein_vazirani(qubit_count: int):
                         required=False,
                         default='',
                         help='The target to execute the algorithm on.')
+    parser.add_argument('--seed',
+                        type=int,
+                        required=False,
+                        default=0,
+                        help='The random seed to generate the secret string.')
     args = parser.parse_args()
 
     # Depending on the available memory on your GPU, you can
@@ -94,6 +99,8 @@ def bernstein_vazirani(qubit_count: int):
     # a long time for the CPU-only backend to simulate 28+ qubits!
 
     qubit_count = args.size
+    if args.seed != 0:
+        random.seed(args.seed)
     if args.target and not args.target.isspace():
         cudaq.set_target(args.target)
 

python/README.md

@@ -33,35 +33,46 @@ CUDA Quantum can be used to compile and run quantum programs on a CPU-only
 system, but a GPU is highly recommended and necessary to use the some of the
 simulators. The GPU-based simulators included in the CUDA Quantum Python wheels
 require an existing CUDA installation. Additionally, multi-GPU simulators
-require an existing MPI installation.
+require an existing CUDA-aware MPI installation.
 
-In most cases, the CUDA and MPI dependencies can be installed via package
-manager. On Ubuntu 22.04, for example, the following commands install all
-optional CUDA dependencies:
+To install the necessary dependencies, we recommend using
+[Conda](https://docs.conda.io/en/latest/). If you are not already using Conda,
+you can install a minimal version following the instructions
+[here](https://docs.conda.io/projects/miniconda/en/latest/index.html).
+The following commands will create and activate a complete environment for
+CUDA Quantum with all its dependencies:
 
 ```console
-arch=x86_64 # set this to sbsa for ARM processors
-sudo apt-get update && sudo apt-get install -y wget
-wget -q https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/$arch/cuda-keyring_1.0-1_all.deb
-sudo dpkg -i cuda-keyring_1.0-1_all.deb && rm cuda-keyring_1.0-1_all.deb
-sudo apt-get update && sudo apt-get install -y cuda-toolkit-11.8
+    conda create -y -n cuda-quantum python==3.10 pip
+    conda install -y -n cuda-quantum -c "nvidia/label/cuda-11.8.0" cuda
+    conda install -y -n cuda-quantum -c conda-forge mpi4py openmpi
+    conda env config vars set -n cuda-quantum LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$CONDA_PREFIX/envs/cuda-quantum/lib"
+    conda run -n cuda-quantum pip install cuda-quantum
+    conda activate cuda-quantum
 ```
 
-Detailed instructions for how to install the complete CUDA toolkit on different
-operating systems can be found in the [CUDA
-documentation](https://docs.nvidia.com/cuda/).
-
-If you have several GPUs available but no MPI installation yet, we recommend
-taking a look at the [OpenMPI documentation](https://docs.open-mpi.org/)
-and installing [mpi4py](https://mpi4py.readthedocs.io/).
-On Ubuntu 22.04, for example, the following commands install the necessary MPI
-libraries:
+You must configure MPI by setting the following environment variables:
 
 ```console
-sudo apt-get update && sudo apt-get install -y libopenmpi-dev libpython3-dev gcc
-python3 -m pip install mpi4py
+  export OMPI_MCA_opal_cuda_support=true OMPI_MCA_btl='^openib'
 ```
 
+*If you do not set these variables you may encounter a segmentation fault.*
+
+**Important**: It is *not* sufficient to set these variable within the conda
+environment, like the commands above do for `LD_LIBRARY_PATH`.
+To avoid having to set them every time you launch a new
+shell, we recommend adding them to `~/.profile`
+(create the file if it does not exist).
+
+MPI uses [SSH](https://en.wikipedia.org/wiki/Secure_Shell) or
+[RSH](https://en.wikipedia.org/wiki/Remote_Shell) to communicate with
+each node unless another resource manager, such as
+[SLURM](https://slurm.schedmd.com/overview.html), is used.
+If you are encountering an error "The value of the MCA parameter
+`plm_rsh_agent` was set to a path that could not be found",
+please make sure you have an SSH Client installed.
+
 ## Running CUDA Quantum
 
 You should now be able to import CUDA Quantum and start building quantum