Add some documentation on usign CUDA with CUDA Quantum.

docs/sphinx/using/advanced.rst

@@ -8,4 +8,5 @@ Advanced CUDA Quantum Topics
   Create a new NVQIR Simulator <advanced/nvqir_simulator.rst>
   Downstream CMake Integration <advanced/cmake_app.rst>
   Working with CUDA Quantum IR <advanced/cudaq_ir.rst>
-  Create an MLIR Pass for CUDA Quantum <advanced/mlir_pass.rst>
+  Create an MLIR Pass for CUDA Quantum <advanced/mlir_pass.rst>
+  Combining CUDA (GPU) with CUDA Quantum <advanced/cuda_gpu.rst>

docs/sphinx/using/advanced/cuda_gpu.rst

@@ -0,0 +1,52 @@
+Using CUDA and CUDA Quantum in a Project
+****************************************
+
+It may be the case that a project that uses CUDA Quantum kernels may also
+want to use CUDA code to do computation on a GPU.  This is possible by using
+both the CUDA Toolkit and CUDA Quantum tools.
+
+If you are using a CUDA Quantum container, the CUDA Toolkit can be installed
+using a command such as
+
+.. code:: bash
+
+    apt-get install cuda-toolkit-11-8
+
+Once the :code:`nvcc` compiler is installed, it is possible to write
+CUDA kernels and have them execute on the system GPU. See NVIDIA's `An
+Easy Introduction to CUDA C and
+C++`<https://developer.nvidia.com/blog/easy-introduction-cuda-c-and-c/>`__
+for more information on getting started with CUDA.
+
+CUDA code uses a unique syntax and is, typically, saved in a file with
+the extension :code:`.cu`. For our example, assume we have written our
+CUDA code in the file :code:`my_proj.cu`.
+
+CUDA Quantum code is a library-based extension of C++ and uses
+standard conforming C++ syntax. Typically, a quantum kernel would be
+saved in a file with the :code:`.cpp` extension. Again for our
+example, let's assume that we've written quantum kernels and saved
+them in the file :code:`my_proj_quantum.cpp`.
+
+There is a bit of a wrinkle to be aware of before we compile these two
+compilation units. Version 11 (and earlier) of CUDA :code:`nvcc`
+supports the C++ 11, 14, and 17 standards and the default standard is
+determined by the host C++ compiler. The CUDA Quantum compiler,
+:code:`nvq++`, defaults to the C++ 20 standard. To get around this
+limitation, the project makefiles should select a common C++ standard
+version. Fortunately, :code:`nvq++` does allow the use of C++ 17.
+
+Note that starting with version 12 of the CUDA toolkit, the C++ 20
+standard is supported.
+
+Our project can then be built with commands such as
+
+.. code:: bash
+
+    nvcc -std=c++17 -c <options> my_proj.cu -o my_proj.o
+    nvq++ -std=c++17 -c <options> my_proj_quantum.cpp -o my_proj_quantum.o
+    ...
+    nvq++ my_proj.o my_proj_quantum.o ... -o my_executable
+
+Using :code:`nvq++` for the link step will make sure the CUDA Quantum runtime
+libraries are linked correctly to the executable program.