Correction of .gitignore, Clean requirements.txt, Clarify Setup

.gitignore

@@ -0,0 +1,147 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+# Usually these files are written by a python script from a template
+# before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Benchmarking reports
+*.benchmark
+*.prof
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Jupyter Notebook
+.ipynb_checkpoints
+# Exclude notebooks in specific output/solution folders if desired, e.g.:
+# qec101/Solutions/*.ipynb
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule.*
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.envrc
+# direnv
+.direnv/
+# virtualenv
+.direnv/python-*
+
+# Microsoft VS Code
+.vscode/
+
+# JetBrains PyCharm
+.idea/
+
+# Sublime Text
+*.sublime-project
+*.sublime-workspace
+
+# Atom
+.atom/
+
+# Eclipse
+.project
+.pydevproject
+.settings/
+
+# Mac OS
+.DS_Store
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Output files / Data (add project-specific ones if needed)
+# Example: output_data/
+# Example: *.csv
+# Example: *.png
+
+# Compiled C++ object files and executables (if building locally)
+*.o
+*.out
+*.exe
+*.dll
+*.dylib
+
+# CUDA specific cache/build files
+*.ptx
+*.cubin

README.md

@@ -28,6 +28,45 @@ The Quick Start to Quantum Computing with CUDA-Q module aims to take a learner f
 * Completion of the [Quick Start to Quantum Computing with CUDA-Q](https://github.com/NVIDIA/cuda-q-academic/tree/main/quick-start-to-quantum)
 
 ---
+## Setup and Installation
+
+Using the examples in this repository requires **NVIDIA CUDA Quantum** to be installed first.
+
+1.  **Install CUDA Quantum SDK:** Follow the official installation guide for your operating system, preferably using the **SDK installer or Conda**:
+    [https://nvidia.github.io/cuda-quantum/latest/install.html](https://nvidia.github.io/cuda-quantum/latest/install.html)
+    *   Ensure your NVIDIA drivers and CUDA Toolkit (if needed by the chosen install method) are compatible.
+    *   Verify the installation by checking if you can import `cudaq` in Python and run `nvq++ --version` (for C++ examples) in your terminal.
+
+2.  **Clone this Repository:**
+    ```bash
+    git clone https://github.com/KaranSinghDev/cuda-q-academic.git
+    cd cuda-q-academic
+    ```
+
+3.  **(Recommended)** Create and activate a Python virtual environment within the cloned directory, using the Python environment where your CUDA Quantum SDK was installed or is accessible.
+    ```bash
+    python -m venv venv
+    source venv/bin/activate # Linux/macOS
+    # venv\Scripts\activate # Windows
+    ```
+
+4.  **Install Python Dependencies for Examples:** Install helper libraries used in the notebooks and scripts:
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+**Running Examples:**
+You can now run the Python scripts (`.py`) or open the Jupyter Notebooks (`.ipynb`) within your configured environment. C++ examples will require using the `nvq++` compiler provided by the SDK.
+
+## Dependencies
+
+*   **NVIDIA CUDA Quantum SDK:** The core requirement. Must be installed separately via the official SDK installer or Conda (see Setup). Provides `cudaq` (Python) and `nvq++` (C++).
+*   **Python:** Version compatible with your CUDA Quantum installation (check official docs).
+*   **Python Libraries:** Various helper libraries used in the examples (e.g., `numpy`, `matplotlib`, `jupyter`, `qutip`, etc.). These can be installed via `pip install -r requirements.txt` *after* setting up CUDA Quantum.
+*   **C++ Compiler:** A compatible C++ compiler (like g++) is needed if you intend to build or run custom C++ code alongside `nvq++`.
+
+---
+
 ## QAOA for Max Cut Module
 The Divide-and-Conquer QAOA for Max Cut module takes a learner from the implementation of QAOA to solve a small max problem
 to an application of a divide-and-conquer QAOA algorithm to a large max cut problem using parallel computation. This visual introduction to QAOA and circuit cutting provides the learner the background to understand more advanced topics such as [ADAPT-QAOA](https://nvidia.github.io/cuda-quantum/latest/applications/python/adapt_qaoa.html), [Adaptive Circuit Knitting](https://arxiv.org/pdf/2411.10406), and [QAOA-GPT](https://arxiv.org/pdf/2504.16350).

requirements.txt

@@ -1,3 +1,15 @@
+# ----------------------------------------------------------------------
+# Python dependencies for running the CUDA-Q Academic examples/notebooks.
+#
+# IMPORTANT: The core NVIDIA CUDA Quantum SDK (providing the `cudaq`
+# Python module and potentially the nvq++ compiler) MUST be installed
+# separately BEFORE installing these requirements. Follow the official
+# guide: https://nvidia.github.io/cuda-quantum/latest/install.html
+#
+# This file primarily lists libraries used by the Jupyter notebooks
+# and Python example scripts.
+# ----------------------------------------------------------------------
+
 astpretty==3.0.0
 asttokens==2.4.1
 attrs==23.2.0
@@ -7,11 +19,11 @@ bleach==6.1.0
 certifi==2024.7.4
 charset-normalizer==3.3.2
 contourpy==1.2.1
-cuda-quantum==0.7.1
-cuquantum-cu11==23.10.0
-custatevec-cu11==1.5.0
-cutensor-cu11==1.7.0
-cutensornet-cu11==2.3.0
+# cuda-quantum==0.7.1 # REMOVED - Must be installed via SDK/Conda
+cuquantum-cu11==23.10.0 # Note: These cuQuantum packages are specific to CUDA 11.x
+custatevec-cu11==1.5.0 # Might cause issues if system CUDA is different.
+cutensor-cu11==1.7.0 # Consider removing these unless CUDA 11 is a hard req.
+cutensornet-cu11==2.3.0 # Consider removing these unless CUDA 11 is a hard req.
 cycler==0.12.1
 decorator==5.1.1
 defusedxml==0.7.1
@@ -69,4 +81,4 @@ traitlets==5.14.3
 urllib3==2.2.2
 wcwidth==0.2.13
 webencodings==0.5.1
-yarg==0.1.9
+yarg==0.1.9