---------------------------------------------------
SMALLGRAPHGCN - FILE DESCRIPTIONS & USAGE GUIDE
---------------------------------------------------

SETUP FILES
-----------
environment.yml          : Conda environment specification (alternative to init.sh)
init.sh                  : One-command setup script that creates conda env, installs PyTorch 2.5.1+CUDA 12.1, PyG, and builds the custom CUDA kernel
setup_edge_centric.py    : Python setup script to compile and install the custom CUDA kernel extension

KERNEL SOURCE
-------------
kernels/gcn_kernel_edge_centric.cu : Custom CUDA kernels for edge-centric GCN aggregation (forward, backward, linear transform)

MODEL CODE
----------
models/__init__.py       : Package init, exports GCN class
models/autograd_wrapper.py : PyTorch autograd Function wrapping custom CUDA kernels with forward/backward methods
models/gcn_layer.py      : GCN model class that can switch between PyG GCNConv and custom kernel implementations

UTILITIES
---------
utils/__init__.py        : Package init, exports data loading and trainer utilities
utils/data_loader.py     : Dataset loading (QM9, ZINC), batching, and train/val/test splitting
utils/trainer.py         : Training loop, evaluation, and benchmarking utilities

TRAINING
--------
train.py                 : Main training script with full train/val/test loop, supports both PyG and custom kernel

TESTING & BENCHMARKING
----------------------
tests/__init__.py        : Package init for tests
tests/test_correctness.py : Numerical correctness tests comparing custom kernel output to PyG reference
tests/test_performance.py : Performance benchmarks comparing forward/backward pass times
tests/run_experiments.py  : Comprehensive experiment runner across multiple configurations (batch, layers, hidden)
tests/profile_kernels.py  : Script for NVIDIA Nsight Systems profiling with NVTX markers

PROFILING & ANALYSIS
--------------------
scripts/nsys_to_csv.py   : Converts nsys SQLite exports to CSV for kernel-level analysis

RESULTS DIRECTORIES
-------------------
results/experiments/     : Stores experiment results (JSON, summary reports)
results/nsys-profiling/  : Stores nsys profiling outputs (.nsys-rep, .sqlite, .csv)

---------------------------------------------------
SETUP COMMANDS
---------------------------------------------------

# Step 1: Clone/navigate to project directory
cd /path/to/smallgraphgnn

# Step 2: Run the setup script (creates env, installs dependencies, builds kernel)
chmod +x init.sh
./init.sh

# Step 3: Activate the environment (for subsequent sessions)
conda activate gcn_small_graphs

---------------------------------------------------
TRAINING COMMANDS
---------------------------------------------------

# Basic training with PyG baseline
python train.py --dataset qm9 --epochs 100

# Training with custom CUDA kernel
python train.py --dataset qm9 --epochs 100 --use_custom_kernel

# Full training with all parameters specified
python train.py \
    --dataset qm9 \
    --hidden_dim 64 \
    --num_layers 8 \
    --batch_size 128 \
    --epochs 100 \
    --lr 0.001 \
    --dropout 0.5 \
    --benchmark

# Training with custom kernel (add --use_custom_kernel flag)
python train.py \
    --dataset qm9 \
    --hidden_dim 64 \
    --num_layers 8 \
    --batch_size 128 \
    --epochs 100 \
    --lr 0.001 \
    --dropout 0.5 \
    --use_custom_kernel \
    --benchmark

# Training on ZINC dataset
python train.py --dataset zinc --hidden_dim 64 --num_layers 8 --epochs 100 --use_custom_kernel

---------------------------------------------------
PERFORMANCE TESTING COMMANDS
---------------------------------------------------

# Quick performance benchmark (single configuration)
python tests/test_performance.py --dataset qm9 --batch-size 128 --num-layers 8 --hidden-dim 64

# Quick experiment run (subset of configurations)
python tests/run_experiments.py --mode quick --output quick_results.json --repeats 2

# Full experiment suite (all configurations, takes 2-3 hours)
python tests/run_experiments.py --mode full --output full_results.json --repeats 3

# Correctness test (verify custom kernel matches PyG)
python tests/test_correctness.py

---------------------------------------------------
PROFILING COMMANDS (requires NVIDIA Nsight Systems)
---------------------------------------------------

# Profile custom kernel
nsys profile --output=results/nsys-profiling/profile_custom \
    --force-overwrite=true --trace=cuda,nvtx --stats=true \
    python tests/profile_kernels.py --kernel custom --iterations 50

# Profile PyG baseline
nsys profile --output=results/nsys-profiling/profile_pyg \
    --force-overwrite=true --trace=cuda,nvtx --stats=true \
    python tests/profile_kernels.py --kernel pyg --iterations 50

# Convert to CSV
python scripts/nsys_to_csv.py results/nsys-profiling/profile_custom.sqlite profile_custom
python scripts/nsys_to_csv.py results/nsys-profiling/profile_pyg.sqlite profile_pyg

# Generate comparison
python scripts/nsys_to_csv.py --compare profile_custom profile_pyg