LGPA 1.0.0__tar.gz

lgpa-1.0.0/LGPA/__init__.py

@@ -0,0 +1,26 @@
+import networkx as nx
+from ._lgpa_core import LGPA_Core
+
+class LGPA:
+    """
+    Log-Gravity Propagation Algorithm (LGPA) 
+    """
+    def __init__(self, graph):
+        self.G = graph.to_undirected()
+        
+        self.nodes = list(self.G.nodes())
+        self.node_to_idx = {node: i for i, node in enumerate(self.nodes)}
+        self.idx_to_node = {i: node for i, node in enumerate(self.nodes)}
+        
+        n = len(self.nodes)
+        edges = [(self.node_to_idx[u], self.node_to_idx[v]) for u, v in self.G.edges()]
+        
+        self.core = LGPA_Core(n, edges)
+
+    def fit_predict(self, max_iter=50):
+        if not self.nodes:
+            return {}
+        
+        raw_labels = self.core.fit_predict(max_iter)
+        
+        return {self.idx_to_node[idx]: label for idx, label in raw_labels.items()}

lgpa-1.0.0/LGPA/lgpa_core.cpp

@@ -0,0 +1,194 @@
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+#include <vector>
+#include <cmath>
+#include <algorithm>
+#include <numeric>
+#include <unordered_map>
+
+namespace py = pybind11;
+
+class LGPA_Core {
+private:
+    int n;
+    int m;
+    std::vector<std::vector<int>> adj;
+    std::vector<int> degree;
+    std::vector<std::unordered_map<int, double>> sj; 
+    std::vector<double> strength;
+    double core_threshold;
+
+public:
+    LGPA_Core(int num_nodes, const std::vector<std::pair<int, int>>& edges) {
+        n = num_nodes;
+        m = edges.size();
+        adj.resize(n);
+        degree.resize(n, 0);
+        sj.resize(n);
+        strength.resize(n, 0.0);
+
+        for (const auto& edge : edges) {
+            int u = edge.first;
+            int v = edge.second;
+            adj[u].push_back(v);
+            adj[v].push_back(u);
+            degree[u]++;
+            degree[v]++;
+        }
+
+        for (int i = 0; i < n; ++i) {
+            std::sort(adj[i].begin(), adj[i].end());
+        }
+
+        std::vector<double> sj_values;
+        sj_values.reserve(m);
+
+        // STEP 1: Laplacian-Smoothed Jaccard
+        for (const auto& edge : edges) {
+            int u = edge.first;
+            int v = edge.second;
+            
+            int common = 0;
+            auto it_u = adj[u].begin();
+            auto it_v = adj[v].begin();
+            while (it_u != adj[u].end() && it_v != adj[v].end()) {
+                if (*it_u < *it_v) ++it_u;
+                else if (*it_v < *it_u) ++it_v;
+                else {
+                    common++;
+                    ++it_u; ++it_v;
+                }
+            }
+            
+            int union_size = degree[u] + degree[v] - common;
+            double sim = (common + 1.0) / (union_size + 1.0);
+            sj[u][v] = sim;
+            sj[v][u] = sim;
+            sj_values.push_back(sim);
+        }
+
+        // STEP 2: Intrinsic Structural Strength
+        for (int u = 0; u < n; ++u) {
+            double s = 0.0;
+            for (int v : adj[u]) {
+                s += sj[u][v];
+            }
+            strength[u] = s;
+        }
+
+        // STEP 3: Statistical Regime Thresholds
+        double mean_sj = 0.0, std_sj = 0.0, sci = 0.0;
+        if (!sj_values.empty()) {
+            double sum = std::accumulate(sj_values.begin(), sj_values.end(), 0.0);
+            mean_sj = sum / sj_values.size();
+            double sq_sum = std::inner_product(sj_values.begin(), sj_values.end(), sj_values.begin(), 0.0);
+            // std::max guards against tiny negative variance from round-off.
+            double var = std::max(0.0, sq_sum / sj_values.size() - mean_sj * mean_sj);
+            std_sj = std::sqrt(var);
+            sci = std_sj / mean_sj;  
+        }
+
+        double w_struct = 1.0 - std::exp(-sci);
+        core_threshold = mean_sj + (w_struct * std_sj);
+    }
+
+    std::unordered_map<int, int> fit_predict(int max_iter) {
+        if (n == 0) return {};
+
+        // PHASE 1:  Coring
+        std::vector<int> merged_to(n);
+        std::iota(merged_to.begin(), merged_to.end(), 0);
+
+        std::vector<int> nodes_desc(n);
+        std::iota(nodes_desc.begin(), nodes_desc.end(), 0);
+        std::sort(nodes_desc.begin(), nodes_desc.end(), [&](int a, int b) {
+            if (strength[a] != strength[b]) return strength[a] > strength[b];
+            return a > b; 
+        });
+
+        for (int u : nodes_desc) {
+            if (adj[u].empty()) continue;
+
+            int best_nbr = adj[u][0];
+            double max_sj = sj[u][best_nbr];
+            for (int v : adj[u]) {
+                if (sj[u][v] > max_sj) {
+                    max_sj = sj[u][v];
+                    best_nbr = v;
+                }
+            }
+
+            if (max_sj > core_threshold) {
+                if (strength[best_nbr] > strength[u] || (strength[best_nbr] == strength[u] && best_nbr > u)) {
+                    merged_to[u] = best_nbr;
+                }
+            }
+        }
+
+        // Path Compression
+        for (int u = 0; u < n; ++u) {
+            int curr = u;
+            while (curr != merged_to[curr]) {
+                curr = merged_to[curr];
+            }
+            merged_to[u] = curr;
+        }
+
+        // PHASE 2: Log-Gravity Propagation
+        std::vector<int> labels = merged_to;
+        std::vector<int> nodes_asc = nodes_desc;
+        std::reverse(nodes_asc.begin(), nodes_asc.end());
+        
+        const double EULER_E = std::exp(1.0);
+
+        for (int iter = 0; iter < max_iter; ++iter) {
+            bool changed = false;
+            for (int u : nodes_asc) {
+                if (adj[u].empty()) continue;
+
+                std::unordered_map<int, double> scores;
+                for (int v : adj[u]) {
+                    double weight = sj[u][v] * std::log(strength[v] + EULER_E);
+                    scores[labels[v]] += weight;
+                }
+
+                if (scores.empty()) continue;
+
+                int best_label = -1;
+                double max_score = -1.0;
+                for (const auto& pair : scores) {
+                    if (pair.second > max_score) {
+                        max_score = pair.second;
+                        best_label = pair.first;
+                    }
+                }
+
+                if (labels[u] != best_label) {
+                    labels[u] = best_label;
+                    changed = true;
+                }
+            }
+            if (!changed) break;
+        }
+
+        std::unordered_map<int, int> final_labels;
+        std::unordered_map<int, int> label_mapping;
+        int current_id = 0;
+
+        for (int u = 0; u < n; ++u) {
+            int l = labels[u];
+            if (label_mapping.find(l) == label_mapping.end()) {
+                label_mapping[l] = current_id++;
+            }
+            final_labels[u] = label_mapping[l];
+        }
+
+        return final_labels;
+    }
+};
+
+PYBIND11_MODULE(_lgpa_core, m) {
+    py::class_<LGPA_Core>(m, "LGPA_Core")
+        .def(py::init<int, const std::vector<std::pair<int, int>>&>())
+        .def("fit_predict", &LGPA_Core::fit_predict, py::arg("max_iter") = 50, py::call_guard<py::gil_scoped_release>()); 
+}

lgpa-1.0.0/LGPA.egg-info/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: LGPA
+Version: 1.0.0
+Summary: Log-Gravity Propagation Algorithm (LGPA) for community detection in complex networks
+Author: Anasse Tahboun
+License: MIT
+Project-URL: Homepage, https://github.com/tahbounanas/LGPA
+Project-URL: Repository, https://github.com/tahbounanas/LGPA
+Keywords: community-detection,graph,networks,label-propagation,LGPA,Complex-Networks,Graph-Mining,Social-Network-Analysis,Log-Gravity-Propagation-Algorithm
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: networkx>=2.5
+Dynamic: license-file
+
+# LGPA — Log-Gravity Propagation Algorithm
+
+A deterministic, tuning-free community detection algorithm for complex networks, implemented in C++ (via [pybind11](https://github.com/pybind/pybind11)) with a simple Python/[NetworkX](https://networkx.org/) interface.
+
+LGPA resolves two well-known weaknesses of standard Label Propagation — run-to-run instability and the formation of oversized *"monster"* communities — using a Laplacian-smoothed Jaccard similarity, a statistical Coring phase, and a log-gravity propagation rule that logarithmically dampens the influence of high-degree hubs. Its threshold and update rule are derived entirely from the graph's own structure, so there is nothing to tune, and its native C++ core scales to networks of tens of thousands of nodes in seconds.
+
+This repository is the reference implementation for the paper *"LGPA: Log-Gravity Propagation Algorithm for Community Detection in Complex Networks"* (ASONAM 2026, Research Track). See [Citation](#citation).
+
+---
+
+## Requirements
+
+Installing LGPA compiles a small C++ extension, so you need a C++ compiler in addition to Python. Everything else is installed automatically.
+
+| Requirement | Notes |
+|---|---|
+| **Python** | 3.8 or newer |
+| **A C++ compiler** | Windows: [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) (select the *"Desktop development with C++"* workload). macOS: `xcode-select --install`. Linux: `sudo apt install build-essential` (or your distro's equivalent). |
+| **pybind11** | Installed automatically during the build. |
+| **networkx** | Installed automatically as a dependency. |
+
+---
+
+## Installation
+
+### Option 1 — Install directly from GitHub (recommended)
+
+```bash
+pip install git+https://github.com/tahbounanas/LGPA.git
+```
+
+### Option 2 — Clone, then install
+
+```bash
+git clone https://github.com/tahbounanas/LGPA.git
+cd LGPA
+pip install .
+```
+
+To develop (edit the C++/Python and rebuild in place), use `pip install -e .` instead.
+
+`pip` handles `pybind11`, `networkx`, and compiling the extension. After it finishes, LGPA is importable from any folder in that Python environment.
+
+---
+
+## Usage
+
+```python
+import networkx as nx
+from LGPA import LGPA
+
+# A simple graph with two communities of 10 nodes each,
+# joined by a single bridge edge.
+G = nx.Graph()
+for start in (0, 10):
+    block = range(start, start + 10)
+    for i in block:
+        for j in block:
+            if i < j:
+                G.add_edge(i, j)   # dense links inside each community
+G.add_edge(9, 10)                  # one bridge between the two communities
+
+# Run LGPA
+lgpa = LGPA(G)
+partition = lgpa.fit_predict(max_iter=50) # or simply   partition = LGPA(G).fit_predict()
+
+
+# partition: {node -> community_id}
+print("Communities found:", len(set(partition.values())))
+print(partition)
+```
+
+Expected output:
+
+```
+Communities found: 2
+{0: 0, 1: 0, 2: 0, 3: 0, 4: 0, 5: 0, 6: 0, 7: 0, 8: 0, 9: 0,
+ 10: 1, 11: 1, 12: 1, 13: 1, 14: 1, 15: 1, 16: 1, 17: 1, 18: 1, 19: 1}
+```
+
+| Input graph | LGPA result |
+|:---:|:---:|
+| ![Input graph](lgpa_before.jpg) | ![LGPA communities](lgpa_after.jpg) |
+
+LGPA correctly separates the two communities (nodes 0–9 and 10–19) despite the bridge edge linking them.
+
+`fit_predict` returns a dictionary mapping each node to its community id, so it works with any node labels (integers, strings, etc.), not just consecutive integers. LGPA is fully deterministic: the same graph always yields the same partition, with no random seed.
+
+**Parameters**
+
+- `max_iter` (int, default `50`): a safeguard cap on the number of propagation sweeps. It is not a tuned parameter — the loop stops on its own once labels stabilize, which in practice happens well before this cap.
+
+---
+
+## Example on a real dataset (Thiers)
+
+The [`Datasets/`](Datasets/) folder contains the **Thiers** high-school contact network (327 nodes, 9 ground-truth classes): `Thiers.gml` is the graph and `Thiers_GR.txt` holds the ground-truth class label of each node (in GML node order).
+
+> This example also uses `scikit-learn` and `scipy` for the metrics (`pip install scikit-learn scipy`); they are not required by LGPA itself.
+
+```python
+import json
+import time
+import networkx as nx
+from sklearn.metrics import (
+    normalized_mutual_info_score as nmi_score,
+    adjusted_rand_score as ari_score,
+    f1_score,
+)
+from scipy.optimize import linear_sum_assignment
+from sklearn.metrics import confusion_matrix
+import numpy as np
+
+from LGPA import LGPA
+
+# Load the graph and its ground-truth labels
+G = nx.read_gml("Datasets/Thiers.gml", label="id").to_undirected()
+G.remove_edges_from(nx.selfloop_edges(G))
+gt_labels = json.load(open("Datasets/Thiers_GR.txt"))
+
+nodes = list(G.nodes())
+gt = {nodes[i]: gt_labels[i] for i in range(len(nodes))}   # GR is in GML node order
+
+# Run LGPA (timed)
+start = time.perf_counter()
+partition = LGPA(G).fit_predict()
+runtime = time.perf_counter() - start
+
+# Encode labels as integers
+classes = sorted(set(gt.values()))
+cmap = {c: i for i, c in enumerate(classes)}
+y_true = np.array([cmap[gt[n]] for n in nodes])
+y_pred = np.array([partition[n] for n in nodes])
+
+# NMI and ARI
+nmi = nmi_score(y_true, y_pred)
+ari = ari_score(y_true, y_pred)
+
+# Macro-F1 (align predicted communities to ground-truth classes via Hungarian matching)
+labels_p = sorted(set(y_pred))
+C = confusion_matrix(y_true, [labels_p.index(x) for x in y_pred])
+n = max(C.shape)
+Cp = np.zeros((n, n)); Cp[:C.shape[0], :C.shape[1]] = C
+r, c = linear_sum_assignment(-Cp)
+mapping = {labels_p[cc]: rr for rr, cc in zip(r, c) if cc < len(labels_p)}
+y_pred_aligned = np.array([mapping.get(x, -1) for x in y_pred])
+f1 = f1_score(y_true, y_pred_aligned, average="macro")
+
+print(f"Communities found: {len(set(y_pred))}")
+print(f"NMI: {nmi:.3f}")
+print(f"ARI: {ari:.3f}")
+print(f"F1 : {f1:.3f}")
+print(f"Runtime: {runtime:.3f} s")
+```
+
+Output:
+
+```
+Communities found: 9
+NMI: 0.970
+ARI: 0.964
+F1 : 0.979
+Runtime: 0.116 s
+```
+
+LGPA recovers all 9 classes with near-perfect agreement to the ground truth (NMI 0.970, ARI 0.964). In the two coloured figures below, each detected community has been matched to its best-corresponding ground-truth class (via Hungarian assignment) and drawn in that class's colour, so the ground-truth and LGPA plots line up directly. The metrics, not the colours, are what quantify the agreement.
+
+| Input network | Ground truth | LGPA communities |
+|:---:|:---:|:---:|
+| ![Thiers input](thiers_before.jpg) | ![Thiers ground truth](thiers_groundtruth.jpg) | ![Thiers LGPA](thiers_after.jpg) |
+
+
+### Reproducing the figures
+
+The three plots above are produced with the snippet below (requires `matplotlib`, `pip install matplotlib`). A single shared layout is used so the input, ground-truth, and LGPA figures line up node-for-node.
+
+```python
+import json
+import networkx as nx
+import matplotlib.pyplot as plt
+import matplotlib.patches as mpatches
+from LGPA import LGPA
+
+# Load graph + ground truth
+G = nx.read_gml("Datasets/Thiers.gml", label="id").to_undirected()
+G.remove_edges_from(nx.selfloop_edges(G))
+gt_labels = json.load(open("Datasets/Thiers_GR.txt"))
+nodes = list(G.nodes())
+gt = {nodes[i]: gt_labels[i] for i in range(len(nodes))}
+
+# Run LGPA
+partition = LGPA(G).fit_predict()
+
+# One shared layout so all three plots are comparable
+pos = nx.spring_layout(G, seed=42, k=0.3, iterations=60)
+cmap = plt.colormaps["tab10"]
+
+def draw(color_by, title, filename, legend=None):
+    plt.figure(figsize=(8, 8))
+    nx.draw_networkx_edges(G, pos, alpha=0.15, width=0.5)
+    nx.draw_networkx_nodes(G, pos, node_color=color_by, edgecolors="#333333",
+                           linewidths=0.4, node_size=90)
+    if legend:
+        plt.legend(handles=legend, loc="upper left", fontsize=8)
+    plt.title(title, fontsize=14)
+    plt.axis("off"); plt.tight_layout()
+    plt.savefig(filename, dpi=150, bbox_inches="tight"); plt.close()
+
+# 1) Input graph (grey, unlabelled)
+draw("#cccccc", "Thiers network - input", "thiers_before.jpg")
+
+# 2) Ground truth (coloured by true class, with legend)
+classes = sorted(set(gt.values()))
+gt_colors = [cmap(classes.index(gt[n])) for n in G.nodes()]
+handles = [mpatches.Patch(color=cmap(i), label=c) for i, c in enumerate(classes)]
+draw(gt_colors, f"Thiers - ground truth ({len(classes)} classes)",
+     "thiers_groundtruth.jpg", legend=handles)
+
+# 3) LGPA result — colours matched to ground-truth classes via Hungarian assignment
+import numpy as np
+from scipy.optimize import linear_sum_assignment
+from sklearn.metrics import confusion_matrix
+
+y_true = np.array([classes.index(gt[n]) for n in nodes])
+y_pred = np.array([partition[n] for n in nodes])
+labels_p = sorted(set(y_pred))
+C = confusion_matrix(y_true, [labels_p.index(x) for x in y_pred])
+m = max(C.shape); Cp = np.zeros((m, m)); Cp[:C.shape[0], :C.shape[1]] = C
+r, c = linear_sum_assignment(-Cp)
+comm_to_class = {labels_p[cc]: rr for rr, cc in zip(r, c) if cc < len(labels_p)}
+
+lgpa_colors = [cmap(comm_to_class.get(partition[n], len(classes))) for n in G.nodes()]
+draw(lgpa_colors, f"Thiers - LGPA ({len(set(y_pred))} communities)",
+     "thiers_after.jpg", legend=handles)
+```
+
+---
+
+## Method at a glance
+
+1. **Preprocessing** — a Laplacian-smoothed Jaccard similarity is computed for every edge, per-node structural strength is aggregated, and an adaptive threshold is derived from the graph's Structural Complexity Index.
+2. **Phase 1 (Coring)** — nodes are merged with their most similar neighbour, in a deterministic strength-based order, to form stable proto-communities.
+3. **Phase 2 (Log-Gravity Propagation)** — remaining labels are updated with a log-gravity score in which each neighbour's influence grows only logarithmically with its strength, suppressing hub dominance and preventing the avalanche effect.
+
+---
+
+## Citation
+
+If you use LGPA in your research, please cite:
+
+```bibtex
+
+```
+
+---
+
+## License
+
+Released under the [MIT License](LICENSE).

lgpa-1.0.0/LGPA.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+setup.py
+LGPA/__init__.py
+LGPA/lgpa_core.cpp
+LGPA.egg-info/PKG-INFO
+LGPA.egg-info/SOURCES.txt
+LGPA.egg-info/dependency_links.txt
+LGPA.egg-info/requires.txt
+LGPA.egg-info/top_level.txt

lgpa-1.0.0/LGPA.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lgpa-1.0.0/LGPA.egg-info/requires.txt

@@ -0,0 +1 @@
+networkx>=2.5

lgpa-1.0.0/LGPA.egg-info/top_level.txt

@@ -0,0 +1 @@
+LGPA

lgpa-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anasse Tahboun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lgpa-1.0.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LGPA/lgpa_core.cpp
+include LICENSE
+include README.md

lgpa-1.0.0/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: LGPA
+Version: 1.0.0
+Summary: Log-Gravity Propagation Algorithm (LGPA) for community detection in complex networks
+Author: Anasse Tahboun
+License: MIT
+Project-URL: Homepage, https://github.com/tahbounanas/LGPA
+Project-URL: Repository, https://github.com/tahbounanas/LGPA
+Keywords: community-detection,graph,networks,label-propagation,LGPA,Complex-Networks,Graph-Mining,Social-Network-Analysis,Log-Gravity-Propagation-Algorithm
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: networkx>=2.5
+Dynamic: license-file
+
+# LGPA — Log-Gravity Propagation Algorithm
+
+A deterministic, tuning-free community detection algorithm for complex networks, implemented in C++ (via [pybind11](https://github.com/pybind/pybind11)) with a simple Python/[NetworkX](https://networkx.org/) interface.
+
+LGPA resolves two well-known weaknesses of standard Label Propagation — run-to-run instability and the formation of oversized *"monster"* communities — using a Laplacian-smoothed Jaccard similarity, a statistical Coring phase, and a log-gravity propagation rule that logarithmically dampens the influence of high-degree hubs. Its threshold and update rule are derived entirely from the graph's own structure, so there is nothing to tune, and its native C++ core scales to networks of tens of thousands of nodes in seconds.
+
+This repository is the reference implementation for the paper *"LGPA: Log-Gravity Propagation Algorithm for Community Detection in Complex Networks"* (ASONAM 2026, Research Track). See [Citation](#citation).
+
+---
+
+## Requirements
+
+Installing LGPA compiles a small C++ extension, so you need a C++ compiler in addition to Python. Everything else is installed automatically.
+
+| Requirement | Notes |
+|---|---|
+| **Python** | 3.8 or newer |
+| **A C++ compiler** | Windows: [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) (select the *"Desktop development with C++"* workload). macOS: `xcode-select --install`. Linux: `sudo apt install build-essential` (or your distro's equivalent). |
+| **pybind11** | Installed automatically during the build. |
+| **networkx** | Installed automatically as a dependency. |
+
+---
+
+## Installation
+
+### Option 1 — Install directly from GitHub (recommended)
+
+```bash
+pip install git+https://github.com/tahbounanas/LGPA.git
+```
+
+### Option 2 — Clone, then install
+
+```bash
+git clone https://github.com/tahbounanas/LGPA.git
+cd LGPA
+pip install .
+```
+
+To develop (edit the C++/Python and rebuild in place), use `pip install -e .` instead.
+
+`pip` handles `pybind11`, `networkx`, and compiling the extension. After it finishes, LGPA is importable from any folder in that Python environment.
+
+---
+
+## Usage
+
+```python
+import networkx as nx
+from LGPA import LGPA
+
+# A simple graph with two communities of 10 nodes each,
+# joined by a single bridge edge.
+G = nx.Graph()
+for start in (0, 10):
+    block = range(start, start + 10)
+    for i in block:
+        for j in block:
+            if i < j:
+                G.add_edge(i, j)   # dense links inside each community
+G.add_edge(9, 10)                  # one bridge between the two communities
+
+# Run LGPA
+lgpa = LGPA(G)
+partition = lgpa.fit_predict(max_iter=50) # or simply   partition = LGPA(G).fit_predict()
+
+
+# partition: {node -> community_id}
+print("Communities found:", len(set(partition.values())))
+print(partition)
+```
+
+Expected output:
+
+```
+Communities found: 2
+{0: 0, 1: 0, 2: 0, 3: 0, 4: 0, 5: 0, 6: 0, 7: 0, 8: 0, 9: 0,
+ 10: 1, 11: 1, 12: 1, 13: 1, 14: 1, 15: 1, 16: 1, 17: 1, 18: 1, 19: 1}
+```
+
+| Input graph | LGPA result |
+|:---:|:---:|
+| ![Input graph](lgpa_before.jpg) | ![LGPA communities](lgpa_after.jpg) |
+
+LGPA correctly separates the two communities (nodes 0–9 and 10–19) despite the bridge edge linking them.
+
+`fit_predict` returns a dictionary mapping each node to its community id, so it works with any node labels (integers, strings, etc.), not just consecutive integers. LGPA is fully deterministic: the same graph always yields the same partition, with no random seed.
+
+**Parameters**
+
+- `max_iter` (int, default `50`): a safeguard cap on the number of propagation sweeps. It is not a tuned parameter — the loop stops on its own once labels stabilize, which in practice happens well before this cap.
+
+---
+
+## Example on a real dataset (Thiers)
+
+The [`Datasets/`](Datasets/) folder contains the **Thiers** high-school contact network (327 nodes, 9 ground-truth classes): `Thiers.gml` is the graph and `Thiers_GR.txt` holds the ground-truth class label of each node (in GML node order).
+
+> This example also uses `scikit-learn` and `scipy` for the metrics (`pip install scikit-learn scipy`); they are not required by LGPA itself.
+
+```python
+import json
+import time
+import networkx as nx
+from sklearn.metrics import (
+    normalized_mutual_info_score as nmi_score,
+    adjusted_rand_score as ari_score,
+    f1_score,
+)
+from scipy.optimize import linear_sum_assignment
+from sklearn.metrics import confusion_matrix
+import numpy as np
+
+from LGPA import LGPA
+
+# Load the graph and its ground-truth labels
+G = nx.read_gml("Datasets/Thiers.gml", label="id").to_undirected()
+G.remove_edges_from(nx.selfloop_edges(G))
+gt_labels = json.load(open("Datasets/Thiers_GR.txt"))
+
+nodes = list(G.nodes())
+gt = {nodes[i]: gt_labels[i] for i in range(len(nodes))}   # GR is in GML node order
+
+# Run LGPA (timed)
+start = time.perf_counter()
+partition = LGPA(G).fit_predict()
+runtime = time.perf_counter() - start
+
+# Encode labels as integers
+classes = sorted(set(gt.values()))
+cmap = {c: i for i, c in enumerate(classes)}
+y_true = np.array([cmap[gt[n]] for n in nodes])
+y_pred = np.array([partition[n] for n in nodes])
+
+# NMI and ARI
+nmi = nmi_score(y_true, y_pred)
+ari = ari_score(y_true, y_pred)
+
+# Macro-F1 (align predicted communities to ground-truth classes via Hungarian matching)
+labels_p = sorted(set(y_pred))
+C = confusion_matrix(y_true, [labels_p.index(x) for x in y_pred])
+n = max(C.shape)
+Cp = np.zeros((n, n)); Cp[:C.shape[0], :C.shape[1]] = C
+r, c = linear_sum_assignment(-Cp)
+mapping = {labels_p[cc]: rr for rr, cc in zip(r, c) if cc < len(labels_p)}
+y_pred_aligned = np.array([mapping.get(x, -1) for x in y_pred])
+f1 = f1_score(y_true, y_pred_aligned, average="macro")
+
+print(f"Communities found: {len(set(y_pred))}")
+print(f"NMI: {nmi:.3f}")
+print(f"ARI: {ari:.3f}")
+print(f"F1 : {f1:.3f}")
+print(f"Runtime: {runtime:.3f} s")
+```
+
+Output:
+
+```
+Communities found: 9
+NMI: 0.970
+ARI: 0.964
+F1 : 0.979
+Runtime: 0.116 s
+```
+
+LGPA recovers all 9 classes with near-perfect agreement to the ground truth (NMI 0.970, ARI 0.964). In the two coloured figures below, each detected community has been matched to its best-corresponding ground-truth class (via Hungarian assignment) and drawn in that class's colour, so the ground-truth and LGPA plots line up directly. The metrics, not the colours, are what quantify the agreement.
+
+| Input network | Ground truth | LGPA communities |
+|:---:|:---:|:---:|
+| ![Thiers input](thiers_before.jpg) | ![Thiers ground truth](thiers_groundtruth.jpg) | ![Thiers LGPA](thiers_after.jpg) |
+
+
+### Reproducing the figures
+
+The three plots above are produced with the snippet below (requires `matplotlib`, `pip install matplotlib`). A single shared layout is used so the input, ground-truth, and LGPA figures line up node-for-node.
+
+```python
+import json
+import networkx as nx
+import matplotlib.pyplot as plt
+import matplotlib.patches as mpatches
+from LGPA import LGPA
+
+# Load graph + ground truth
+G = nx.read_gml("Datasets/Thiers.gml", label="id").to_undirected()
+G.remove_edges_from(nx.selfloop_edges(G))
+gt_labels = json.load(open("Datasets/Thiers_GR.txt"))
+nodes = list(G.nodes())
+gt = {nodes[i]: gt_labels[i] for i in range(len(nodes))}
+
+# Run LGPA
+partition = LGPA(G).fit_predict()
+
+# One shared layout so all three plots are comparable
+pos = nx.spring_layout(G, seed=42, k=0.3, iterations=60)
+cmap = plt.colormaps["tab10"]
+
+def draw(color_by, title, filename, legend=None):
+    plt.figure(figsize=(8, 8))
+    nx.draw_networkx_edges(G, pos, alpha=0.15, width=0.5)
+    nx.draw_networkx_nodes(G, pos, node_color=color_by, edgecolors="#333333",
+                           linewidths=0.4, node_size=90)
+    if legend:
+        plt.legend(handles=legend, loc="upper left", fontsize=8)
+    plt.title(title, fontsize=14)
+    plt.axis("off"); plt.tight_layout()
+    plt.savefig(filename, dpi=150, bbox_inches="tight"); plt.close()
+
+# 1) Input graph (grey, unlabelled)
+draw("#cccccc", "Thiers network - input", "thiers_before.jpg")
+
+# 2) Ground truth (coloured by true class, with legend)
+classes = sorted(set(gt.values()))
+gt_colors = [cmap(classes.index(gt[n])) for n in G.nodes()]
+handles = [mpatches.Patch(color=cmap(i), label=c) for i, c in enumerate(classes)]
+draw(gt_colors, f"Thiers - ground truth ({len(classes)} classes)",
+     "thiers_groundtruth.jpg", legend=handles)
+
+# 3) LGPA result — colours matched to ground-truth classes via Hungarian assignment
+import numpy as np
+from scipy.optimize import linear_sum_assignment
+from sklearn.metrics import confusion_matrix
+
+y_true = np.array([classes.index(gt[n]) for n in nodes])
+y_pred = np.array([partition[n] for n in nodes])
+labels_p = sorted(set(y_pred))
+C = confusion_matrix(y_true, [labels_p.index(x) for x in y_pred])
+m = max(C.shape); Cp = np.zeros((m, m)); Cp[:C.shape[0], :C.shape[1]] = C
+r, c = linear_sum_assignment(-Cp)
+comm_to_class = {labels_p[cc]: rr for rr, cc in zip(r, c) if cc < len(labels_p)}
+
+lgpa_colors = [cmap(comm_to_class.get(partition[n], len(classes))) for n in G.nodes()]
+draw(lgpa_colors, f"Thiers - LGPA ({len(set(y_pred))} communities)",
+     "thiers_after.jpg", legend=handles)
+```
+
+---
+
+## Method at a glance
+
+1. **Preprocessing** — a Laplacian-smoothed Jaccard similarity is computed for every edge, per-node structural strength is aggregated, and an adaptive threshold is derived from the graph's Structural Complexity Index.
+2. **Phase 1 (Coring)** — nodes are merged with their most similar neighbour, in a deterministic strength-based order, to form stable proto-communities.
+3. **Phase 2 (Log-Gravity Propagation)** — remaining labels are updated with a log-gravity score in which each neighbour's influence grows only logarithmically with its strength, suppressing hub dominance and preventing the avalanche effect.
+
+---
+
+## Citation
+
+If you use LGPA in your research, please cite:
+
+```bibtex
+
+```
+
+---
+
+## License
+
+Released under the [MIT License](LICENSE).

lgpa-1.0.0/README.md

@@ -0,0 +1,259 @@
+# LGPA — Log-Gravity Propagation Algorithm
+
+A deterministic, tuning-free community detection algorithm for complex networks, implemented in C++ (via [pybind11](https://github.com/pybind/pybind11)) with a simple Python/[NetworkX](https://networkx.org/) interface.
+
+LGPA resolves two well-known weaknesses of standard Label Propagation — run-to-run instability and the formation of oversized *"monster"* communities — using a Laplacian-smoothed Jaccard similarity, a statistical Coring phase, and a log-gravity propagation rule that logarithmically dampens the influence of high-degree hubs. Its threshold and update rule are derived entirely from the graph's own structure, so there is nothing to tune, and its native C++ core scales to networks of tens of thousands of nodes in seconds.
+
+This repository is the reference implementation for the paper *"LGPA: Log-Gravity Propagation Algorithm for Community Detection in Complex Networks"* (ASONAM 2026, Research Track). See [Citation](#citation).
+
+---
+
+## Requirements
+
+Installing LGPA compiles a small C++ extension, so you need a C++ compiler in addition to Python. Everything else is installed automatically.
+
+| Requirement | Notes |
+|---|---|
+| **Python** | 3.8 or newer |
+| **A C++ compiler** | Windows: [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) (select the *"Desktop development with C++"* workload). macOS: `xcode-select --install`. Linux: `sudo apt install build-essential` (or your distro's equivalent). |
+| **pybind11** | Installed automatically during the build. |
+| **networkx** | Installed automatically as a dependency. |
+
+---
+
+## Installation
+
+### Option 1 — Install directly from GitHub (recommended)
+
+```bash
+pip install git+https://github.com/tahbounanas/LGPA.git
+```
+
+### Option 2 — Clone, then install
+
+```bash
+git clone https://github.com/tahbounanas/LGPA.git
+cd LGPA
+pip install .
+```
+
+To develop (edit the C++/Python and rebuild in place), use `pip install -e .` instead.
+
+`pip` handles `pybind11`, `networkx`, and compiling the extension. After it finishes, LGPA is importable from any folder in that Python environment.
+
+---
+
+## Usage
+
+```python
+import networkx as nx
+from LGPA import LGPA
+
+# A simple graph with two communities of 10 nodes each,
+# joined by a single bridge edge.
+G = nx.Graph()
+for start in (0, 10):
+    block = range(start, start + 10)
+    for i in block:
+        for j in block:
+            if i < j:
+                G.add_edge(i, j)   # dense links inside each community
+G.add_edge(9, 10)                  # one bridge between the two communities
+
+# Run LGPA
+lgpa = LGPA(G)
+partition = lgpa.fit_predict(max_iter=50) # or simply   partition = LGPA(G).fit_predict()
+
+
+# partition: {node -> community_id}
+print("Communities found:", len(set(partition.values())))
+print(partition)
+```
+
+Expected output:
+
+```
+Communities found: 2
+{0: 0, 1: 0, 2: 0, 3: 0, 4: 0, 5: 0, 6: 0, 7: 0, 8: 0, 9: 0,
+ 10: 1, 11: 1, 12: 1, 13: 1, 14: 1, 15: 1, 16: 1, 17: 1, 18: 1, 19: 1}
+```
+
+| Input graph | LGPA result |
+|:---:|:---:|
+| ![Input graph](lgpa_before.jpg) | ![LGPA communities](lgpa_after.jpg) |
+
+LGPA correctly separates the two communities (nodes 0–9 and 10–19) despite the bridge edge linking them.
+
+`fit_predict` returns a dictionary mapping each node to its community id, so it works with any node labels (integers, strings, etc.), not just consecutive integers. LGPA is fully deterministic: the same graph always yields the same partition, with no random seed.
+
+**Parameters**
+
+- `max_iter` (int, default `50`): a safeguard cap on the number of propagation sweeps. It is not a tuned parameter — the loop stops on its own once labels stabilize, which in practice happens well before this cap.
+
+---
+
+## Example on a real dataset (Thiers)
+
+The [`Datasets/`](Datasets/) folder contains the **Thiers** high-school contact network (327 nodes, 9 ground-truth classes): `Thiers.gml` is the graph and `Thiers_GR.txt` holds the ground-truth class label of each node (in GML node order).
+
+> This example also uses `scikit-learn` and `scipy` for the metrics (`pip install scikit-learn scipy`); they are not required by LGPA itself.
+
+```python
+import json
+import time
+import networkx as nx
+from sklearn.metrics import (
+    normalized_mutual_info_score as nmi_score,
+    adjusted_rand_score as ari_score,
+    f1_score,
+)
+from scipy.optimize import linear_sum_assignment
+from sklearn.metrics import confusion_matrix
+import numpy as np
+
+from LGPA import LGPA
+
+# Load the graph and its ground-truth labels
+G = nx.read_gml("Datasets/Thiers.gml", label="id").to_undirected()
+G.remove_edges_from(nx.selfloop_edges(G))
+gt_labels = json.load(open("Datasets/Thiers_GR.txt"))
+
+nodes = list(G.nodes())
+gt = {nodes[i]: gt_labels[i] for i in range(len(nodes))}   # GR is in GML node order
+
+# Run LGPA (timed)
+start = time.perf_counter()
+partition = LGPA(G).fit_predict()
+runtime = time.perf_counter() - start
+
+# Encode labels as integers
+classes = sorted(set(gt.values()))
+cmap = {c: i for i, c in enumerate(classes)}
+y_true = np.array([cmap[gt[n]] for n in nodes])
+y_pred = np.array([partition[n] for n in nodes])
+
+# NMI and ARI
+nmi = nmi_score(y_true, y_pred)
+ari = ari_score(y_true, y_pred)
+
+# Macro-F1 (align predicted communities to ground-truth classes via Hungarian matching)
+labels_p = sorted(set(y_pred))
+C = confusion_matrix(y_true, [labels_p.index(x) for x in y_pred])
+n = max(C.shape)
+Cp = np.zeros((n, n)); Cp[:C.shape[0], :C.shape[1]] = C
+r, c = linear_sum_assignment(-Cp)
+mapping = {labels_p[cc]: rr for rr, cc in zip(r, c) if cc < len(labels_p)}
+y_pred_aligned = np.array([mapping.get(x, -1) for x in y_pred])
+f1 = f1_score(y_true, y_pred_aligned, average="macro")
+
+print(f"Communities found: {len(set(y_pred))}")
+print(f"NMI: {nmi:.3f}")
+print(f"ARI: {ari:.3f}")
+print(f"F1 : {f1:.3f}")
+print(f"Runtime: {runtime:.3f} s")
+```
+
+Output:
+
+```
+Communities found: 9
+NMI: 0.970
+ARI: 0.964
+F1 : 0.979
+Runtime: 0.116 s
+```
+
+LGPA recovers all 9 classes with near-perfect agreement to the ground truth (NMI 0.970, ARI 0.964). In the two coloured figures below, each detected community has been matched to its best-corresponding ground-truth class (via Hungarian assignment) and drawn in that class's colour, so the ground-truth and LGPA plots line up directly. The metrics, not the colours, are what quantify the agreement.
+
+| Input network | Ground truth | LGPA communities |
+|:---:|:---:|:---:|
+| ![Thiers input](thiers_before.jpg) | ![Thiers ground truth](thiers_groundtruth.jpg) | ![Thiers LGPA](thiers_after.jpg) |
+
+
+### Reproducing the figures
+
+The three plots above are produced with the snippet below (requires `matplotlib`, `pip install matplotlib`). A single shared layout is used so the input, ground-truth, and LGPA figures line up node-for-node.
+
+```python
+import json
+import networkx as nx
+import matplotlib.pyplot as plt
+import matplotlib.patches as mpatches
+from LGPA import LGPA
+
+# Load graph + ground truth
+G = nx.read_gml("Datasets/Thiers.gml", label="id").to_undirected()
+G.remove_edges_from(nx.selfloop_edges(G))
+gt_labels = json.load(open("Datasets/Thiers_GR.txt"))
+nodes = list(G.nodes())
+gt = {nodes[i]: gt_labels[i] for i in range(len(nodes))}
+
+# Run LGPA
+partition = LGPA(G).fit_predict()
+
+# One shared layout so all three plots are comparable
+pos = nx.spring_layout(G, seed=42, k=0.3, iterations=60)
+cmap = plt.colormaps["tab10"]
+
+def draw(color_by, title, filename, legend=None):
+    plt.figure(figsize=(8, 8))
+    nx.draw_networkx_edges(G, pos, alpha=0.15, width=0.5)
+    nx.draw_networkx_nodes(G, pos, node_color=color_by, edgecolors="#333333",
+                           linewidths=0.4, node_size=90)
+    if legend:
+        plt.legend(handles=legend, loc="upper left", fontsize=8)
+    plt.title(title, fontsize=14)
+    plt.axis("off"); plt.tight_layout()
+    plt.savefig(filename, dpi=150, bbox_inches="tight"); plt.close()
+
+# 1) Input graph (grey, unlabelled)
+draw("#cccccc", "Thiers network - input", "thiers_before.jpg")
+
+# 2) Ground truth (coloured by true class, with legend)
+classes = sorted(set(gt.values()))
+gt_colors = [cmap(classes.index(gt[n])) for n in G.nodes()]
+handles = [mpatches.Patch(color=cmap(i), label=c) for i, c in enumerate(classes)]
+draw(gt_colors, f"Thiers - ground truth ({len(classes)} classes)",
+     "thiers_groundtruth.jpg", legend=handles)
+
+# 3) LGPA result — colours matched to ground-truth classes via Hungarian assignment
+import numpy as np
+from scipy.optimize import linear_sum_assignment
+from sklearn.metrics import confusion_matrix
+
+y_true = np.array([classes.index(gt[n]) for n in nodes])
+y_pred = np.array([partition[n] for n in nodes])
+labels_p = sorted(set(y_pred))
+C = confusion_matrix(y_true, [labels_p.index(x) for x in y_pred])
+m = max(C.shape); Cp = np.zeros((m, m)); Cp[:C.shape[0], :C.shape[1]] = C
+r, c = linear_sum_assignment(-Cp)
+comm_to_class = {labels_p[cc]: rr for rr, cc in zip(r, c) if cc < len(labels_p)}
+
+lgpa_colors = [cmap(comm_to_class.get(partition[n], len(classes))) for n in G.nodes()]
+draw(lgpa_colors, f"Thiers - LGPA ({len(set(y_pred))} communities)",
+     "thiers_after.jpg", legend=handles)
+```
+
+---
+
+## Method at a glance
+
+1. **Preprocessing** — a Laplacian-smoothed Jaccard similarity is computed for every edge, per-node structural strength is aggregated, and an adaptive threshold is derived from the graph's Structural Complexity Index.
+2. **Phase 1 (Coring)** — nodes are merged with their most similar neighbour, in a deterministic strength-based order, to form stable proto-communities.
+3. **Phase 2 (Log-Gravity Propagation)** — remaining labels are updated with a log-gravity score in which each neighbour's influence grows only logarithmically with its strength, suppressing hub dominance and preventing the avalanche effect.
+
+---
+
+## Citation
+
+If you use LGPA in your research, please cite:
+
+```bibtex
+
+```
+
+---
+
+## License
+
+Released under the [MIT License](LICENSE).

lgpa-1.0.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=64", "pybind11>=2.10"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "LGPA"
+version = "1.0.0"
+description = "Log-Gravity Propagation Algorithm (LGPA) for community detection in complex networks"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Anasse Tahboun" }]
+keywords = ["community-detection", "graph", "networks", "label-propagation", "LGPA","Complex-Networks","Graph-Mining","Social-Network-Analysis","Log-Gravity-Propagation-Algorithm"]
+dependencies = ["networkx>=2.5"]
+
+[project.urls]
+Homepage = "https://github.com/tahbounanas/LGPA"
+Repository = "https://github.com/tahbounanas/LGPA"
+
+[tool.setuptools]
+packages = ["LGPA"]
+
+
+
+

lgpa-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lgpa-1.0.0/setup.py

@@ -0,0 +1,19 @@
+import sys
+from setuptools import setup
+from pybind11.setup_helpers import Pybind11Extension, build_ext
+
+# MSVC uses /O2, GCC/Clang use -O3
+opt_flags = ["/O2"] if sys.platform == "win32" else ["-O3"]
+
+ext_modules = [
+    Pybind11Extension(
+        "LGPA._lgpa_core",
+        ["LGPA/lgpa_core.cpp"],
+        extra_compile_args=opt_flags,
+    ),
+]
+
+setup(
+    ext_modules=ext_modules,
+    cmdclass={"build_ext": build_ext},
+)