paragon-engine 0.1.1

High-performance parallel graph processing engine (C++ + Python)

🚀 PARAGON: Parallel Graph Processing Engine

PARAGON is a high-performance parallel graph processing engine written in modern C++ with Python bindings via pybind11. P It provides scalable implementations of core graph algorithms like:

• Parallel BFS / DFS
• Connected Components
• PageRank (Pull + Push)
• Single Source Shortest Path (SSSP)
• Triangle Counting

Designed for:

• ⚡ Multicore CPUs
• 📊 Large-scale graphs
• 🧠 Systems + algorithm engineering

Architecture

C++ Core Engine (src/)
        ↓
Parallel Algorithms (threaded)
        ↓
pybind11 Bindings (bindings/)
        ↓
Python API (python/paragon/)

Project Structure

paragon/
├── include/              # Header files (Graph, algorithms, engine)
├── src/                  # C++ implementations
├── bindings/             # pybind11 bindings
├── python/paragon/       # Python API layer
│   ├── core.py
│   ├── algorithms/
│   │   ├── bfs.py
│   │   ├── dfs.py
│   │   ├── pagerank.py
│   │   ├── sssp.py
│   │   └── ...
├── examples/             # C++ examples
├── benchmark/            # Performance benchmarks
├── tests/                # Unit tests
├── CMakeLists.txt
├── pyproject.toml
└── README.md

⚙️ Installation

🔴 IMPORTANT

Windows users:

You MUST use MSVC (Visual Studio Build Tools)

❌ MinGW WILL FAIL ❌ Python 3.13 + MinGW is incompatible

Recommended Setup

Python version

Python 3.8 – 3.11 (RECOMMENDED)

⚠️ Avoid Python 3.13 for now (ABI issues with pybind11 + MinGW)

Windows Setup

1. Install Visual Studio Build Tools

Download: 👉 https://visualstudio.microsoft.com/visual-cpp-build-tools/

Select:

• ✔ C++ build tools
• ✔ MSVC compiler
• ✔ Windows SDK

2. Install package

pip install paragon-engine

Linux / Mac

Install dependencies

sudo apt install build-essential cmake python3-dev
pip install pybind11 scikit-build-core

Then:

pip install paragon-engine

🧪 Quick Start

from paragon import Graph
from paragon.algorithms import parallel_bfs, parallel_dfs

g = Graph(5)
g.add_edges([
    (0, 1),
    (1, 2),
    (2, 3),
    (3, 4)
])

print(parallel_bfs(g, 0))
print(parallel_dfs(g, 0))

API Overview

Graph

from paragon import Graph

g = Graph(5)
g.add_edge(0, 1)
g.add_edges([(1, 2), (2, 3)])

---

WeightedGraph

from paragon import WeightedGraph

g = WeightedGraph(5)
g.add_edge(0, 1, 2.5)

---

⚡ Algorithms

🔹 Parallel BFS

from paragon.algorithms import parallel_bfs

dist = parallel_bfs(g, source=0)

---

🔹 Parallel DFS

from paragon.algorithms import parallel_dfs 

visited = parallel_dfs(g, 0)

---

🔹 Connected Components

from paragon.algorithms import connected_components

labels = connected_components(g)

---

🔹 PageRank

from paragon.algorithms import pagerank

ranks = pagerank(g)

---

🔹 PageRank (Push / BFS-style)

from paragon.algorithms import pagerank_bfs

ranks = pagerank_bfs(g)

---

Example — Shortest Path (SSSP)

from paragon import WeightedGraph
from paragon.algorithms import sssp

g = WeightedGraph(6)

g.add_edges([
    (0, 1, 4.0),
    (0, 2, 2.0),
    (1, 3, 5.0),
    (2, 1, 1.0),
    (2, 3, 8.0),
    (3, 4, 3.0),
    (4, 5, 1.0)
])

dist = sssp(g, source=0)

for i, d in enumerate(dist):
    print(f"Distance from 0 → {i}: {d}")

---

🧠 What’s happening here?

• Uses parallel relaxation
• Similar to Bellman-Ford
• Stops early if no updates
• Handles large graphs efficiently

---

🧵 Parallel Engine Features

• Thread pool via std::thread
• Work partitioning (chunking)
• Atomic operations for safety
• Barrier synchronization
• Lock-based + lock-free hybrid design

⚡ Performance

PARAGON achieves:

• 🚀 Significant speedup on multicore CPUs
• ⚡ Efficient memory access patterns
• 🧠 Cache-aware adjacency traversal

🧑‍💻 Development

Build locally

pip install -e .

Build wheel

python -m build

Run examples (C++)

cmake -B build
cmake --build build
./build/example_bfs

Known Issues

MinGW + Python 3.13

You may see errors like:

undefined reference to Py_DecRefShared

Fix:

• Use MSVC
• OR use Python ≤ 3.11

🛠️ Future Improvements

• Prebuilt wheels (no compilation needed)
• GPU support (CUDA / OpenMP)
• Distributed graph processing
• Graph streaming support

🤝 Contributing

PRs welcome!

Suggested areas:

• New algorithms (e.g., SCC, MST)
• Performance optimizations
• Python API improvements

📜 License

MIT License

👤 Author

Saket Jha

⭐ Final Note

PARAGON is not just a library — it’s a systems + algorithms project combining:

• Parallel computing
• Graph theory
• High-performance engineering