GraphFlow
=========

C++/CUDA library for deep learning with dynamic computation graphs and automatic differentiation. Includes high-performance tensor and matrix ops (CPU and CUDA) and reference implementations of graph neural networks and standard neural models.

Highlights
----------
- Dynamic computation graphs with forward/backward execution
- Symbolic/automatic differentiation for training
- CPU back end (C++11, multi-threaded) and CUDA GPU back end
- Graph neural networks: CCN/Steerable Message Passing, GCN, Neural Graph Fingerprints, GGNN, and more
- Standard models: CNNs, MLPs, Autoencoders, LSTM/GRU
- Self-contained headers and runnable tests/examples

Repository layout
-----------------
- `GraphFlow/` and `GraphFlow_32bit/`: CPU headers and ops (C++11, -pthread)
- `GraphFlow_gpu/` and `GraphFlow_gpu_32bit/`: CUDA implementations and GPU tests
- `tests/`: runnable examples covering GNNs, CNNs/RNNs, optimizers, and GPU kernels

Build prerequisites
-------------------
- CPU: g++ with C++11 support. POSIX threads are used (`-pthread`).
- GPU: NVIDIA CUDA Toolkit (nvcc) for `.cu` tests.

Notes for Windows
- Recommended: MSYS2/MinGW-w64 or WSL for POSIX toolchain (`g++`, `-pthread`).
- For native MSVC, small adjustments may be required (POSIX threads are used in CPU tests).

Quick start (CPU)
-----------------
Build and run a small GCN example that predicts simple molecular graph properties.

Linux/macOS (bash):
  g++ -O3 -std=c++11 -pthread -I GraphFlow tests/test_GCN_1D.cpp -o build/test_gcn_1d
  ./build/test_gcn_1d

Windows (PowerShell, MSYS2 MinGW-w64 toolchain):
  g++ -O3 -std=gnu++11 -pthread -I GraphFlow tests\test_GCN_1D.cpp -o build\test_gcn_1d.exe
  .\build\test_gcn_1d.exe

Quick start (GPU)
-----------------
Compile a CUDA example (requires a CUDA-capable GPU):

Linux/macOS (bash):
  nvcc -O3 -std=c++11 -I GraphFlow_gpu tests/test_MatMul_gpu.cu -o build/test_matmul_gpu
  ./build/test_matmul_gpu

Windows (PowerShell):
  nvcc -O3 -std=c++11 -I GraphFlow_gpu tests\test_MatMul_gpu.cu -o build\test_matmul_gpu.exe
  .\build\test_matmul_gpu.exe

What’s included in tests
------------------------
- First-order CCN / Steerable Message Passing (SMP): `tests/test_CCN_1D.cpp`, `tests/test_SMP_theta*.cpp`, `tests/test_SMP_1D*.cpp`, `tests/test_Unrestricted_SMP_1D*.cpp`
- Second-order CCN / SMP variants: `tests/test_SMP_beta*.{cpp,cu}`, `tests/test_SMP_gamma*.cpp`, `tests/test_SMP_omega*.{cpp,cu}`, `tests/test_SMP_sigma*.cpp`, `tests/test_SMP_2D*.cpp`, `tests/test_Unrestricted_SMP_2D*.cpp`
- GCN and Neural Graph Fingerprints: `tests/test_GCN*.cpp`
- GGNN-style gated sequence on graphs: `tests/test_GRU_GCN*.cpp`
- CNNs for graphs and vision: `tests/test_LCNN.cpp`, `tests/test_CNN*.cpp`
- RNNs for language modeling: `tests/test_LSTM.cpp`, `tests/test_GRU.cpp`
- Optimizers: AdaDelta, Adam, AdaMax on MNIST: `tests/test_AdaDelta.cpp`, `tests/test_Adam.cpp`, `tests/test_AdaMax.cpp`
- Classic models on MNIST: Autoencoder and MLP: `tests/test_autoencoder.cpp`, `tests/test_mlp.cpp`
- GPU kernels: tensor contraction and matmul: `tests/test_RisiContraction_18_gpu.cu`, `tests/test_MatMul_gpu.cu`; CPU multithreaded contraction: `tests/test_RisiContraction*.cpp`

Usage notes
-----------
- Include headers from `GraphFlow/` (CPU) or `GraphFlow_gpu/` (GPU) directly in your program.
- Most models expose simple training/inference methods; see tests for end-to-end usage, e.g. `tests/test_GCN_1D.cpp` with `GCN_1D::BatchLearn`, `save_model`, `load_model`, and `Predict`.

Authorship
----------
- Framework: GraphFlow
- Author: Machine Learning Group, Department of Computer Science, The University of Chicago
- Main contributor: Hy Truong Son (Advisor: Prof. Risi Kondor)

Contact / bug reports
---------------------
Please report issues to: hytruongson@uchicago.edu or sonpascal93@gmail.com.

References
----------
[1] Covariant Compositional Networks for Learning Graphs (R. Kondor et al., 2017)

[2] Convolutional Networks on Graphs for Learning Molecular Fingerprints (D. Duvenaud et al., 2015)

[3] Learning Convolutional Neural Networks for Graphs (M. Niepert et al., 2016)

[4] Gated Graph Sequence Neural Networks (Y. Li et al., 2016)

[5] Semi-Supervised Classification with Graph Convolutional Networks (T. Kipf, M. Welling, 2017)

[6] Long Short-Term Memory (S. Hochreiter, J. Schmidhuber, 1997)

[7] Empirical Evaluation of Gated Recurrent Neural Networks on Sequence Modeling (J. Chung et al., 2014)

[8] Adam: A Method for Stochastic Optimization (D. Kingma, J. Ba, 2015)

License
-------
GPL-3.0. See `LICENSE` for details.