Restructure of examples and applications

.github/workflows/config/spellcheck_config.yml

@@ -192,6 +192,8 @@ matrix:
 - name: cxx_examples
   sources:
   - 'docs/sphinx/examples/**/*.cpp'
+  - 'docs/sphinx/applications/cpp/*.cpp'
+  - 'docs/sphinx/targets/cpp/*.cpp'
   expect_match: false
   aspell:
     lang: en

.github/workflows/integration_tests.yml

@@ -490,7 +490,7 @@ jobs:
           export ORCA_ACCESS_URL='${{ secrets.ORCA_ACCESS_URL }}'
           set +e # Allow script to keep going through errors
           test_err_sum=0
-          cpp_tests="docs/sphinx/examples/cpp/providers/orca.cpp"
+          cpp_tests="docs/sphinx/targets/cpp/orca.cpp"
           for filename in $cpp_tests; do
             [ -e "$filename" ] || echo "::error::Couldn't find file ($filename)"
             nvq++ --target orca --orca-url $ORCA_ACCESS_URL $filename
@@ -509,7 +509,7 @@ jobs:
               test_err_sum=$((test_err_sum+1))
             fi
           done
-          python_tests="docs/sphinx/examples/python/providers/orca.py"
+          python_tests="docs/sphinx/targets/python/orca.py"
           for filename in $python_tests; do
             [ -e "$filename" ] || echo "::error::Couldn't find file ($filename)"
             python3 $filename 1> /dev/null
@@ -636,7 +636,7 @@ jobs:
           done
 
           # Test C++ examples with NVQC
-          for filename in `find examples/cpp/ -name '*.cpp'`; do
+          for filename in `find examples/cpp/ applications/cpp/ targets/cpp/ -name '*.cpp'`; do
             if [[ "$filename" == *"nvqc"* ]]; then
               echo "$filename"
               nvqc_config=""
@@ -672,7 +672,7 @@ jobs:
 
           # Test NVQC Python examples + Python MLIR execution tests (not IR tests)
           python3 -m pip install pytest
-          for ex in `find examples/python python/tests/mlir/target -name '*.py' -not -path '*/python/tutorials/*'`; do
+          for ex in `find examples/python python/tests/mlir/target -name '*.py'`; do
             filename=$(basename -- "$ex")
             filename="${filename%.*}"
             echo "Testing $filename:"
@@ -789,7 +789,7 @@ jobs:
           set +e # Allow script to keep going through errors
           python$python_version -m pip install pytest
           test_err_sum=0
-          for ex in `find examples/python python/tests/mlir/target -name '*.py' -not -path '*/python/tutorials/*'`; do
+          for ex in `find examples/python python/tests/mlir/target -name '*.py'`; do
             filename=$(basename -- "$ex")
             filename="${filename%.*}"
             echo "Testing $filename:"

.github/workflows/nvqc_regression_tests.yml

@@ -158,7 +158,7 @@ jobs:
           done
 
           # Test C++ examples with NVQC
-          for filename in `find examples/cpp/ -name '*.cpp'`; do
+          for filename in `find examples/cpp/ applications/cpp/ targets/cpp/ -name '*.cpp'`; do
             if [[ "$filename" == *"nvqc"* ]]; then
               echo "$filename"
               nvqc_config=""
@@ -194,7 +194,7 @@ jobs:
 
           # Test NVQC Python examples + Python MLIR execution tests (not IR tests)
           python3 -m pip install pytest
-          for ex in `find examples/python python/tests/mlir/target -name '*.py' -not -path '*/python/tutorials/*'`; do
+          for ex in `find examples/python python/tests/mlir/target -name '*.py'`; do
             filename=$(basename -- "$ex")
             filename="${filename%.*}"
             echo "Testing $filename:"
@@ -308,7 +308,7 @@ jobs:
           set +e # Allow script to keep going through errors
           python$python_version -m pip install pytest
           test_err_sum=0
-          for ex in `find examples/python python/tests/mlir/target -name '*.py' -not -path '*/python/tutorials/*'`; do
+          for ex in `find examples/python python/tests/mlir/target -name '*.py'; do
             filename=$(basename -- "$ex")
             filename="${filename%.*}"
             echo "Testing $filename:"

.github/workflows/publishing.yml

@@ -789,7 +789,7 @@ jobs:
         run: |
           chmod +x /tmp/install/install_cuda_quantum.*
           /tmp/install/install_cuda_quantum.* --accept
-          rm -rf examples && mv docs/sphinx/examples examples && rm -rf examples/python
+          rm -rf examples applications targets && mv docs/sphinx/examples examples && mv docs/sphinx/applications applications && mv docs/sphinx/targets targets && rm -rf examples/python && rm -rf applications/python && rm -rf targets/python
 
           GITHUB_STEP_SUMMARY=$GITHUB_STEP_SUMMARY \
           bash -l scripts/validate_container.sh | tee /tmp/validation.out
@@ -835,6 +835,8 @@ jobs:
           # Setup links for validate_wheel.sh script
           ln -s $GITHUB_WORKSPACE/scripts/validate_wheel.sh .
           ln -s $GITHUB_WORKSPACE/docs/sphinx/examples/python /tmp/examples
+          ln -s $GITHUB_WORKSPACE/docs/sphinx/applications/python /tmp/applications
+          ln -s $GITHUB_WORKSPACE/docs/sphinx/targets/python /tmp/targets
           ln -s $GITHUB_WORKSPACE/docs/sphinx/snippets/python /tmp/snippets
           ln -s $GITHUB_WORKSPACE/python/tests /tmp/tests
           ln -s $GITHUB_WORKSPACE/python/README.md .
@@ -941,7 +943,7 @@ jobs:
                   fi; \
               done`
 
-          rm -rf examples && mv github-repo/docs/sphinx/examples examples
+          rm -rf examples applications targets && mv github-repo/docs/sphinx/examples examples && mv github-repo/docs/sphinx/applications applications && mv github-repo/docs/sphinx/targets targets
           mv github-repo/docs/notebook_validation.py .
           GITHUB_STEP_SUMMARY=$GITHUB_STEP_SUMMARY \
           bash github-repo/scripts/validate_container.sh $backends_to_test | tee /tmp/validation.out

.github/workflows/python_wheels.yml

@@ -316,7 +316,7 @@ jobs:
           docker run --rm -dit --name wheel-validation-examples wheel_validation:local
           status_sum=0
 
-          for ex in `find docs/sphinx/examples/python -name '*.py' -not -path '*/providers/*' -not -path '*/divisive_clustering_src/*' -not -path '*/utils_ipie.py' -not -path '*/vqe_cudaq_qnp.py'`; do
+          for ex in `find docs/sphinx/examples/python -name '*.py' -not -path '*/building_kernels.py'`; do
             file="${ex#docs/sphinx/examples/python/}"
             echo "__Example ${file}:__" >> /tmp/validation.out
             (docker exec wheel-validation-examples bash -c "python${{ inputs.python_version }} /tmp/examples/$file" >> /tmp/validation.out) && success=true || success=false

.github/workflows/repo_checks.yml

@@ -82,7 +82,7 @@ jobs:
 
           create_output cxx '*.cpp *.h *.hpp :!:test :!:targettests :!:tpls :!:**/nlopt-src/*'
           create_output cxx_headers '*.h *.hpp :!:test :!:targettests :!:tpls :!:**/nlopt-src/*'
-          create_output cxx_examples 'docs/sphinx/examples/**/*.cpp'
+          create_output cxx_examples 'docs/sphinx/examples/**/*.cpp' 'docs/sphinx/applications/cpp/*.cpp' 'docs/sphinx/targets/cpp/*.cpp'
           create_output python '*.py :!:python/tests :!:test :!:targettests :!:tpls :!:docs/sphinx/conf.py'
           create_output markdown '*.md :!:tpls'
           create_output rst '*.rst :!:tpls'

.licenserc.yaml

@@ -32,7 +32,9 @@ header:
     - 'examples'
     - 'tpls'
     - 'docs/sphinx/**/*.html'
+    - 'docs/sphinx/applications'
     - 'docs/sphinx/examples'
+    - 'docs/sphinx/targets'
     - 'docs/sphinx/_templates'
     - 'docs/sphinx/_static/cuda_quantum_icon.svg'
     - 'docker/test/installer/mpi_cuda_check.cpp'

Developing.md

@@ -28,26 +28,26 @@ line printed when you build the code and run an example using the command
 
 ```bash
 bash "$CUDAQ_REPO_ROOT/scripts/build_cudaq.sh" && \
-nvq++ "$CUDAQ_REPO_ROOT/docs/sphinx/examples/cpp/algorithms/grover.cpp" -o grover.out && \
+nvq++ "$CUDAQ_REPO_ROOT/docs/sphinx/applications/cpp/grover.cpp" -o grover.out && \
 ./grover.out
 ```
 
 When working on compiler internals, it can be useful to look at intermediate
 representations for CUDA-Q kernels.
 
 To see how the kernels in [this
-example](./docs/sphinx/examples/cpp/algorithms/grover.cpp) are translated, you
+example](./docs/sphinx/applications/cpp/grover.cpp) are translated, you
 can run
 
 ```bash
-cudaq-quake $CUDAQ_REPO_ROOT/docs/sphinx/examples/cpp/algorithms/grover.cpp
+cudaq-quake $CUDAQ_REPO_ROOT/docs/sphinx/applications/cpp/grover.cpp
 ```
 
 to see its representation in the Quake MLIR dialect. To see its translation to
 [QIR](https://www.qir-alliance.org/), you can run
 
 ```bash
-cudaq-quake $CUDAQ_REPO_ROOT/docs/sphinx/examples/cpp/algorithms/grover.cpp |
+cudaq-quake $CUDAQ_REPO_ROOT/docs/sphinx/applications/cpp/grover.cpp |
 cudaq-opt --canonicalize --add-dealloc |
 quake-translate --convert-to=qir
 ```

docker/build/assets.Dockerfile

@@ -92,6 +92,8 @@ FROM prereqs AS cpp_build
 ADD "cmake" /cuda-quantum/cmake
 ADD "docs/CMakeLists.txt" /cuda-quantum/docs/CMakeLists.txt
 ADD "docs/sphinx/examples" /cuda-quantum/docs/sphinx/examples
+ADD "docs/sphinx/applications" /cuda-quantum/docs/sphinx/applications
+ADD "docs/sphinx/targets" /cuda-quantum/docs/sphinx/targets
 ADD "docs/sphinx/snippets" /cuda-quantum/docs/sphinx/snippets
 ADD "include" /cuda-quantum/include
 ADD "lib" /cuda-quantum/lib

docker/release/cudaq.Dockerfile

@@ -117,9 +117,10 @@ RUN adduser --disabled-password --gecos '' cudaq && adduser cudaq sudo \
 ENV PATH="$PATH:/home/cudaq/.local/bin"
 
 ADD ./docs/sphinx/examples/ /home/cudaq/examples/
+ADD ./docs/sphinx/applications/ /home/cudaq/applications/
+ADD ./docs/sphinx/targets/ /home/cudaq/targets/
 ADD ./docker/release/README.md /home/cudaq/README.md
-RUN mv /home/cudaq/examples/python/tutorials /home/cudaq/tutorials \
-    && chown -R cudaq /home/cudaq && chgrp -R cudaq /home/cudaq
+RUN chown -R cudaq /home/cudaq && chgrp -R cudaq /home/cudaq
 
 USER cudaq
 WORKDIR /home/cudaq

docker/test/installer/linux.Dockerfile

@@ -75,6 +75,8 @@ ADD scripts/validate_container.sh /home/cudaq/validate.sh
 ADD scripts/configure_build.sh /home/cudaq/configure_build.sh
 ADD docker/test/installer/mpi_cuda_check.cpp /home/cudaq/mpi_cuda_check.cpp
 ADD docs/sphinx/examples/cpp /home/cudaq/examples
+ADD docs/sphinx/applications/cpp /home/cudaq/applications
+ADD docs/sphinx/targets/cpp /home/cudaq/targets
 
 # Wheel to check side-by-side installation of Python and C++ support
 ARG cuda_quantum_wheel='cuda_quantum_*.whl'

docker/test/wheels/debian.Dockerfile

@@ -31,6 +31,8 @@ ARG optional_dependencies=
 ARG cuda_quantum_wheel=cuda_quantum-0.0.0-cp311-cp311-manylinux_2_28_x86_64.whl
 COPY $cuda_quantum_wheel /tmp/$cuda_quantum_wheel
 COPY docs/sphinx/examples/python /tmp/examples/
+COPY docs/sphinx/applications/python /tmp/applications/
+COPY docs/sphinx/targets/python /tmp/targets/
 COPY docs/sphinx/snippets/python /tmp/snippets/
 COPY python/tests /tmp/tests/
 COPY python/README.md /tmp/README.md

docker/test/wheels/fedora.Dockerfile

@@ -29,6 +29,8 @@ ARG optional_dependencies=
 ARG cuda_quantum_wheel=cuda_quantum-0.0.0-cp310-cp310-manylinux_2_28_x86_64.whl
 COPY $cuda_quantum_wheel /tmp/$cuda_quantum_wheel
 COPY docs/sphinx/examples/python /tmp/examples/
+COPY docs/sphinx/applications/python /tmp/applications/
+COPY docs/sphinx/targets/python /tmp/targets/
 COPY docs/sphinx/snippets/python /tmp/snippets/
 COPY python/tests /tmp/tests/
 COPY python/README.md /tmp/README.md

docker/test/wheels/opensuse.Dockerfile

@@ -26,6 +26,8 @@ ARG optional_dependencies=
 ARG cuda_quantum_wheel=cuda_quantum-0.0.0-cp39-cp39-manylinux_2_28_x86_64.whl
 COPY $cuda_quantum_wheel /tmp/$cuda_quantum_wheel
 COPY docs/sphinx/examples/python /tmp/examples/
+COPY docs/sphinx/applications/python /tmp/applications/
+COPY docs/sphinx/targets/python /tmp/targets/
 COPY docs/sphinx/snippets/python /tmp/snippets/
 COPY python/tests /tmp/tests/
 COPY python/README.md /tmp/README.md

docker/test/wheels/redhat.Dockerfile

@@ -25,6 +25,8 @@ ARG optional_dependencies=
 ARG cuda_quantum_wheel=cuda_quantum-0.0.0-cp311-cp311-manylinux_2_28_x86_64.whl
 COPY $cuda_quantum_wheel /tmp/$cuda_quantum_wheel
 COPY docs/sphinx/examples/python /tmp/examples/
+COPY docs/sphinx/applications/python /tmp/applications/
+COPY docs/sphinx/targets/python /tmp/targets/
 COPY docs/sphinx/snippets/python /tmp/snippets/
 COPY python/tests /tmp/tests/
 COPY python/README.md /tmp/README.md

docker/test/wheels/ubuntu.Dockerfile

@@ -24,6 +24,8 @@ ARG optional_dependencies=
 ARG cuda_quantum_wheel=cuda_quantum-0.0.0-cp310-cp310-manylinux_2_28_x86_64.whl
 COPY $cuda_quantum_wheel /tmp/$cuda_quantum_wheel
 COPY docs/sphinx/examples/python /tmp/examples/
+COPY docs/sphinx/applications/python /tmp/applications/
+COPY docs/sphinx/targets/python /tmp/targets/
 COPY docs/sphinx/snippets/python /tmp/snippets/
 COPY python/tests /tmp/tests/
 COPY python/README.md /tmp/README.md

docs/CMakeLists.txt

@@ -9,7 +9,7 @@
 # Add nvq++ compile + execution test of code examples
 # Args:
 #   TEST_NAME: name of the test executable. Test name is prefixed with "nvqpp"
-#   SOURCE_LOCATION: location of the source file (relative to 'sphinx/examples/cpp' directory by default) 
+#   SOURCE_LOCATION: location of the source file (relative to 'sphinx' directory by default) 
 # Optional keyword args:
 #   TARGET <TARGET_NAME>: name of the target to use
 #   TARGET_OPTION <Option>: extra option for the target
@@ -25,7 +25,7 @@ function(add_nvqpp_test TEST_NAME SOURCE_LOCATION)
     endif()
   endif()
   if (NOT PARSED_ARGS_SOURCE_DIR)
-    set(PARSED_ARGS_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/sphinx/examples/cpp")
+    set(PARSED_ARGS_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/sphinx")
   endif()
   add_test(
   NAME
@@ -39,26 +39,26 @@ function(add_nvqpp_test TEST_NAME SOURCE_LOCATION)
   endif()
 endfunction()
 
-add_nvqpp_test(GHZ basics/static_kernel.cpp)
-add_nvqpp_test(MultiControlOps basics/multi_controlled_operations.cpp)
-add_nvqpp_test(ExpVals basics/expectation_values.cpp)
-add_nvqpp_test(MidCircuitMeasurements basics/mid_circuit_measurement.cpp)
-add_nvqpp_test(PhaseEstimation algorithms/phase_estimation.cpp)
-add_nvqpp_test(Grover algorithms/grover.cpp)
-add_nvqpp_test(QAOA algorithms/qaoa_maxcut.cpp)
-add_nvqpp_test(VQEH2 algorithms/vqe_h2.cpp)
-add_nvqpp_test(AmplitudeEstimation algorithms/amplitude_estimation.cpp)
-add_nvqpp_test(Builder other/builder/builder.cpp)
-add_nvqpp_test(QAOABuilder other/builder/qaoa_maxcut_builder.cpp)
-add_nvqpp_test(VQEH2Builder other/builder/vqe_h2_builder.cpp)
-add_nvqpp_test(ComputeAction other/compute_actions.cpp)
-add_nvqpp_test(Gradients other/gradients.cpp)
-add_nvqpp_test(IterativePhaseEstimation other/iterative_qpe.cpp)
-add_nvqpp_test(RandomWalkPhaseEstimation other/random_walk_qpe.cpp)
+add_nvqpp_test(GHZ examples/cpp/basics/static_kernel.cpp)
+add_nvqpp_test(MultiControlOps examples/cpp/basics/multi_controlled_operations.cpp)
+add_nvqpp_test(ExpVals examples/cpp/basics/expectation_values.cpp)
+add_nvqpp_test(MidCircuitMeasurements examples/cpp/basics/mid_circuit_measurement.cpp)
+add_nvqpp_test(PhaseEstimation applications/cpp/phase_estimation.cpp)
+add_nvqpp_test(Grover applications/cpp/grover.cpp)
+add_nvqpp_test(QAOA applications/cpp/qaoa_maxcut.cpp)
+add_nvqpp_test(VQEH2 applications/cpp/vqe_h2.cpp)
+add_nvqpp_test(AmplitudeEstimation applications/cpp/amplitude_estimation.cpp)
+add_nvqpp_test(Builder examples/cpp/other/builder/builder.cpp)
+add_nvqpp_test(QAOABuilder examples/cpp/other/builder/qaoa_maxcut_builder.cpp)
+add_nvqpp_test(VQEH2Builder examples/cpp/other/builder/vqe_h2_builder.cpp)
+add_nvqpp_test(ComputeAction examples/cpp/other/compute_actions.cpp)
+add_nvqpp_test(Gradients examples/cpp/other/gradients.cpp)
+add_nvqpp_test(IterativePhaseEstimation applications/cpp/iterative_qpe.cpp)
+add_nvqpp_test(RandomWalkPhaseEstimation applications/cpp/random_walk_qpe.cpp)
 
 if (CUSTATEVEC_ROOT AND CUDA_FOUND) 
-  add_nvqpp_test(CuQuantumGHZ basics/cuquantum_backends.cpp TARGET nvidia LABELS gpu_required)  
-  add_nvqpp_test(CuQuantumBernsteinVazirani algorithms/bernstein_vazirani.cpp TARGET nvidia LABELS gpu_required)  
+  add_nvqpp_test(CuQuantumGHZ examples/cpp/basics/cuquantum_backends.cpp TARGET nvidia LABELS gpu_required)  
+  add_nvqpp_test(CuQuantumBernsteinVazirani applications/cpp/bernstein_vazirani.cpp TARGET nvidia LABELS gpu_required)  
 endif()
 
 # code snippets in docs
@@ -103,7 +103,7 @@ if (CUSTATEVEC_ROOT AND CUDA_FOUND)
   endif()   
 endif()
 
-add_nvqpp_test(photonics_sim providers/photonics.cpp TARGET photonics)
+add_nvqpp_test(photonics_sim targets/cpp/photonics.cpp TARGET photonics)
 add_nvqpp_test(SampleAsyncRemote using/cudaq/platform/sample_async_remote.cpp TARGET remote-mqpu SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/snippets/cpp)
 set_tests_properties(
   nvqpp_SampleAsyncRemote
@@ -130,19 +130,6 @@ if (CUDAQ_ENABLE_PYTHON)
     endif()
   endfunction()
 
-  add_pycudaq_test(Intro intro.py)
-  add_pycudaq_test(BernsteinVazirani bernstein_vazirani.py)
-  add_pycudaq_test(QAOA qaoa_maxcut.py)
-  add_pycudaq_test(VQE simple_vqe.py)
-  add_pycudaq_test(VQEAdvanced advanced_vqe.py)
-
-  add_pycudaq_test(AmplitudeDampingNoise noise_amplitude_damping.py)
-  add_pycudaq_test(BitFlipNoise noise_bit_flip.py)
-  add_pycudaq_test(DepolarizingNoise noise_depolarization.py)
-  add_pycudaq_test(PhaseFlipNoise noise_phase_flip.py)
-  add_pycudaq_test(KrausNoise noise_kraus_operator.py)
-  add_pycudaq_test(NoiseCallback noise_callback.py)
-
   if (CUTENSORNET_ROOT AND CUDA_FOUND) 
     # This example uses tensornet backend.
     add_pycudaq_test(SampleAsyncRemote using/cudaq/platform/sample_async_remote.py SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/snippets/python)