Update README.md

_setup/cudaq/README.md

@@ -5,44 +5,62 @@
 This directory describes the requirements and operational conventions for using CUDA Quantum as the programming environment for running the benchmark programs contained in the QC-App-Oriented-Benchmarks repository.
 In particular, this document explains how to set up the tools needed to run the CUDA Quantum implementation of these benchmarks.
 
+## IMPORTANT Note about Benchmark Directory Structure for CUDA Quantum
+
+Integrating CUDA Quantum into the QED-C benchmarking suite prompted a restructuring of all the benchmark source code in the repository to consolidate common code in a reusable fashion, shareable across API implementations. This effort is a WORK-IN-PROGRESS and has been only partially completed across the suite of benchmarks. In particular, the restructuring defines a shared module for each problem definition and its benchmark looping logic, while isolating code that is specific to each API into a unique quantum "kernel" for that problem definition.
+
+With this strucutre, used by the CUDA Quantum version of the benchmarks, the main routine for each benchmark resides at the top level of the benchmark directory, while the kernels are situated one level deeper in a directory identifed by the API name.  For example, the Bernstein-Vazirani benchmark main program is contained in:
+
+    bernstein-vazirani/bv_benchmark.py
+
+While the CUDA Quantum implementation of the quantum kernel for this benchmark is in:
+
+    bernstein-vazirani/cudaq/bv_kernel.py
+
+As of now, 4 of the benchmarks have been implemented for CUDA Quantum, with kernels contained within the **cudaq** sub-directory for each: **berstein-vazirani, hidden-shift, quantum-fourier transfor, and phase-estimation**. More coming soon. Instructions for running benchmarks on CUDA Quantum are presented below.
+
+Note that for the Qiskit version of the benchmarks, we retained a version of the benhcmark main program in the **qiskit** sub-directory, in order to provide backwards compatibility for users, during this transition period and until the change has been implemented across the entire suite. 
+
+
 ## Configure a CUDA Quantum Environment
-Create an environment named "cudaq" and then "activate" it using the following commands:
 
-    conda create -n cudaq python=3
+There are two ways in which the QED-C benchmarks can be executed using CUDA Quantum.  These are described in this section. (Note: more detail could be added here, but this info is provided to get users started)
 
-    conda activate cudaq
+### Run within the CUDA Quantum Docker Container
 
-The conda environment is now ready for you to install the CUDA Quantum package.
+This is the easiest way to execute the benchmarks with CUDA Quantum.  After cloning the QED-C repository into a directory within your container, simply change directory to the top level of the QED-C repository. You then can bring up a Jupyter Notebook to enable execution of all the benchmarks there or you can change directory to any of the available benchmark directories and execute that benchmark on the command line.  
 
-## Install CUDA Quantum
+Alternatively, you may want to clone the QED-C repository outisde the CUDA Quantum container, and map the directory to a shared volume within the container.  This method will provide persistence of the data generated by the benchmarks if the container is stopped and removed (to update to a newer version of CUDA Quantum, for example).
 
-After activating the conda environment, to ensure you are using the correct installation of `pip`, run the following command:
+To start a Jupyter notebook within the CUDA Quantum container and make the port available outside, it is recommended that you start Jupyter with a command similar to the following:
 
-    pip show pip
+    jupyter notebook --ip 0.0.0.0 --no-browser --allow-root
 
-If everything is working correctly, the `Location` field should have your newly created environment's name present. For example:
+When starting the container, you will also need to map the port used by the Jupyter notebook, using a Docker option like this, where 8888 is the default Jupyter port:
 
-    Location: c:\users\[user]\miniconda\envs\cudaq\lib\site-packages
+    -p 8888:8888
+
+### Install CUDA Quantum using Pip 
 
-Enter the following commands to install the latest version of CUDA Quantum and the other required packages.
+Many users will install the CUDA Quantum package directly onto their system and skip the container entirely. After cloning the QED-C repository to a location on your system, simply change directory to the top level of the QED-C repository. You then can bring up a Jupyter Notebook to enable execution of all the benchmarks there or you can change directory to any of the available benchmark directories and execute that benchmark on the command line.
 
-    pip install numpy matplotlib dwave-cudaq-sdk dwave-neal notebook
+In addition to the CUDA Quantum package, the benchmarks require two other Python packages and, optionally, the Jupyter notebook package.
 
-You are now ready to run the benchmark programs.
+    pip install numpy matplotlib notebook
 
-## Configuring Quantum Hardware
+Once installed, you are ready to run the benchmark programs.
 
-The `cudaq` package allows quantum circuits to be run in a real quantum hardware hosted by [D-Wave Leap](https://cloud.dwavesys.com/leap/). 
+In the section below, we provide some instructions for executing the benchmarks in either of these modes.
 
-## Run the benchmark programs in an Anaconda command window.
+## Run the benchmark programs in a command window.
 
-For example, in an Anaconda command window, you can enter the following commands to change directory to the Ocean MaxCut directory and run the benchmark program:
+To execute the benchmarks in a command or shell window, you simply change directory to the desired benchmark directory and execute the benchmark program as follows:
 
-    cd [your github home directory]\QC-App-Oriented-Benchmarks\maxcut\cudaq
+    cd [your github home directory]\QC-App-Oriented-Benchmarks\bernstein-vazirani
 
-    python maxcut_benchmark.py
+    python bv_benchmark.py -a cudaq
 
-This will execute the benchmark program and report the benchmark metrics to the console.
+This command instructs the benchmark program to exeucte using the CUDA Quantum kernel.  By default, the benchmark will sweep over qubits widths from 2 to 24 qubits.As it executes, the benchmark program will report the benchmark metrics to the console, save them to a data file, and also generate a set of plots depicting the results.
 
 The other benchmarks follow a similar format and structure and are executed in the same way (using the appropriate benchmark pgrogram filename).