barahona-research-group · arnaudon · May 29, 2026 · Apr 19, 2026 · Apr 19, 2026 · Apr 19, 2026
diff --git a/.github/workflows/run-tox.yml b/.github/workflows/run-tox.yml
@@ -7,6 +7,17 @@ on:
       - master
 
 jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+    - run: pip install ruff
+    - run: ruff check src/pygenstability
+    - run: ruff format --check src/pygenstability
+
   build:
 
     runs-on: ubuntu-latest

diff --git a/.gitignore b/.gitignore
@@ -109,6 +109,12 @@ test/model/
 
 test/data/
 
+# pygenstability run artifacts
+results.pkl
+
+# Auto-generated Sphinx PDF (regenerated on release via `tox -e docs`)
+pygenstability_doc.pdf
+
 .DS_Store
 
 # vscode

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.8
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: [--maxkb=1024]
diff --git a/.pylintrc b/.pylintrc
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,60 @@
+# CLAUDE.md
+
+Orientation for Claude Code sessions working in this repo.
+
+## Project
+
+PyGenStability is a Python package for multiscale community detection via
+**generalized Markov Stability**. The core loop scans a range of Markov times,
+runs many generalized-Louvain (or Leiden) optimizations per scale, and
+post-processes the partitions (robustness, NVI, optimal scale selection).
+
+A C++ Louvain implementation is shipped as a pybind11 extension.
+
+## Layout
+
+- `src/pygenstability/` — package source
+- `tests/` — pytest suite (100% coverage enforced, see `tox.ini`)
+- `examples/` — notebooks and scripts, including `real_examples/` (powergrid, protein)
+- `docs/` — Sphinx + nbsphinx
+- `extra/lemon/`, `generalizedLouvain/` — C++ headers / sources used by the extension
+
+## Key modules (`src/pygenstability/`)
+
+- `pygenstability.py` — `run()` orchestrates the scale scan, parallelism, and post-processing
+- `constructors.py` — quality-matrix / null-model builders (linearized, continuous, directed, signed, …)
+- `optimal_scales.py` — robustness-based optimal scale selection
+- `plotting.py` — matplotlib plots; optional plotly/networkx branches
+- `data_clustering.py` — end-to-end data-to-graph clustering workflow
+- `app.py` — Click CLI; console script `pygenstability=pygenstability.app:cli`
+- `io.py` — pickle save/load helpers
+- `contrib/sankey.py` — interactive Sankey diagram (optional plotly)
+
+## Build / test
+
+```bash
+pip install -e .             # builds pybind11 C++ extension (-std=c++11)
+pytest                       # needs the extension built first
+tox                          # full matrix
+tox -e py310 | py311 | py312 # single interpreter
+tox -e lint                  # pylint + pycodestyle + pydocstyle + isort + black --check
+tox -e format                # black + isort (writes)
+tox -e docs                  # Sphinx build
+```
+
+Supported Python: **3.10 / 3.11 / 3.12** (see `tox.ini`).
+
+## Gotchas
+
+- The C++ extension is declared `optional=True` in `setup.py`. If it fails to
+  compile, `import pygenstability.generalized_louvain` silently fails and
+  Louvain is unavailable; Leiden fallback only kicks in if `leidenalg` is
+  installed (see `_check_method` in `pygenstability.py`).
+- BLAS/OpenMP thread counts are pinned to 1 inside worker processes
+  (`_limit_numpy` in `constructors.py`) to avoid multiprocessing contention.
+  Don't remove this without understanding the parallelism model.
+- Optional extras: `[plotly]`, `[leiden]` (igraph + leidenalg), `[networkx]`,
+  `[all]`.
+- Tests write expected-output YAMLs under `tests/data/`. When changing
+  numerics, regenerate fixtures deliberately rather than blindly accepting
+  diffs.
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -4,3 +4,4 @@ include extra/lemon/concepts/*
 include generalizedLouvain/*
 include generalizedLouvain/CPP/*
 include generalizedLouvain/CPP/cliques/*
+include src/pygenstability/py.typed
diff --git a/README.md b/README.md
@@ -18,7 +18,7 @@ We further provide specific analysis tools to process and analyse the results fr
 
 ## Documentation
 
-A documentation of all features of the *PyGenStability* package is available here: https://barahona-research-group.github.io/PyGenStability/, or in pdf [here](pygenstability_doc.pdf).
+A documentation of all features of the *PyGenStability* package is available here: https://barahona-research-group.github.io/PyGenStability/.
 
 ## Installation
 
@@ -54,7 +54,7 @@ pip install pygenstability[all]
 
 You can also install the source code of this package from GitHub directly by first cloning this repo with:
 ```bash
-git clone --recurse-submodules https://github.com/ImperialCollegeLondon/PyGenStability.git
+git clone --recurse-submodules https://github.com/barahona-research-group/PyGenStability.git
 ```
 
 (if the `--recurse-submodules` has not been used, just do `git submodule update --init --recursive` to fetch the submodule with M. Schaub's code).

diff --git a/docs/index_readme.md b/docs/index_readme.md
@@ -39,7 +39,7 @@ pip install pygenstability[all]
 
 You can also install the source code of this package from GitHub directly by first cloning this repo with:
 ```bash
-git clone --recurse-submodules https://github.com/ImperialCollegeLondon/PyGenStability.git
+git clone --recurse-submodules https://github.com/barahona-research-group/PyGenStability.git
 ```
 
 (if the `--recurse-submodules` has not been used, just do `git submodule update --init --recursive` to fetch the submodule with M. Schaub's code).

diff --git a/generalizedLouvain b/generalizedLouvain
diff --git a/pygenstability_doc.pdf b/pygenstability_doc.pdf
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,3 +1,96 @@
 [build-system]
 requires = ["setuptools", "numpy", "cython", "pybind11>=2.6.0", "wheel"]
 build-backend = "setuptools.build_meta"
+
+[project]
+name = "PyGenStability"
+version = "0.2.7"
+description = "Python binding of generalised Louvain with Markov Stability"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    {name = "Alexis Arnaudon", email = "alexis.arnaudon@epfl.ch"},
+    {name = "Juni Schindler", email = "juni.schindler19@imperial.ac.uk"},
+]
+dependencies = [
+    "numpy>=1.18.1,<3",
+    "scipy>=1.4.1,<2",
+    "matplotlib>=3.1.3",
+    "scikit-learn",
+    "cmake>=3.16.3",
+    "click>=7.0",
+    "tqdm>=4.45.0",
+    "pybind11>=2.10.0",
+    "pandas>=1.0.0",
+    "threadpoolctl",
+]
+
+[project.urls]
+Homepage = "https://github.com/barahona-research-group/PyGenStability"
+
+[project.optional-dependencies]
+plotly = ["plotly>=3.6.0"]
+leiden = ["igraph", "leidenalg"]
+networkx = ["networkx>=3.0"]
+all = [
+    "plotly>=3.6.0",
+    "igraph",
+    "leidenalg",
+    "networkx>=3.0",
+    "pyyaml",
+    "dictdiffer",
+    "pytest",
+    "pytest-cov",
+    "pytest-html",
+    "diff-pdf-visually",
+    "ipython!=8.7.0",
+]
+
+[project.scripts]
+pygenstability = "pygenstability.app:cli"
+
+[tool.setuptools]
+zip-safe = false
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = true
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "D",    # pydocstyle
+    "PLE",  # pylint errors
+]
+ignore = [
+    "E731",  # do not assign a lambda expression
+    "E741",  # ambiguous variable name
+    "E203",  # whitespace before ':' (black-compatible)
+    "W605",  # invalid escape sequence
+    "D102",  # missing docstring in public method
+    "D105",  # missing docstring in magic method
+    "D107",  # missing docstring in __init__
+    "D416",  # section name should end with a colon (numpy-style headers used)
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.isort]
+force-single-line = true
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D"]
+"docs/**" = ["D"]
+"examples/**" = ["D", "E", "F"]
diff --git a/setup.py b/setup.py
@@ -1,66 +1,20 @@
-"""Setup."""
+"""Setup for the pybind11 C++ extension.
 
-from pybind11.setup_helpers import Pybind11Extension
-from setuptools import find_namespace_packages, setup
-
-__version__ = "0.2.7"
+All project metadata lives in pyproject.toml (PEP 621). This file
+only declares the optional C++ extension.
+"""
 
-ext_modules = [
-    Pybind11Extension(
-        "pygenstability.generalized_louvain",
-        ["src/pygenstability/generalized_louvain/generalized_louvain.cpp"],
-        include_dirs=["extra", "generalizedLouvain"],
-        extra_compile_args=["-std=c++11"],
-        optional=True,
-    ),
-]
-plotly_require = ["plotly>=3.6.0"]
-
-test_require = [
-    "pyyaml",
-    "dictdiffer",
-    "pytest",
-    "pytest-cov",
-    "pytest-html",
-    "diff-pdf-visually",
-    "ipython!=8.7.0",  # see https://github.com/spatialaudio/nbsphinx/issues/687
-]
-install_requires = [
-    "numpy>=1.18.1",
-    "scipy>=1.4.1",
-    "matplotlib>=3.1.3",
-    "scikit-learn",
-    "cmake>=3.16.3",
-    "click>=7.0",
-    "tqdm>=4.45.0",
-    "pybind11>=2.10.0",
-    "pandas>=1.0.0",
-    "threadpoolctl",
-]
-leiden_install = ["igraph", "leidenalg"]
-networkx_install = ["networkx>=3.0"]
+from pybind11.setup_helpers import Pybind11Extension
+from setuptools import setup
 
 setup(
-    name="PyGenStability",
-    version=__version__,
-    author="Alexis Arnaudon, Juni Schindler",
-    author_email="alexis.arnaudon@epfl.ch, juni.schindler19@imperial.ac.uk",
-    url="https://github.com/ImperialCollegeLondon/PyGenStability",
-    description="Python binding of generalised Louvain with Markov Stability",
-    long_description=open("README.md", "r").read(),
-    long_description_content_type="text/markdown",
-    ext_modules=ext_modules,
-    setup_requires=["pybind11>=2.10.0"],
-    install_requires=install_requires,
-    zip_safe=False,
-    extras_require={
-        "plotly": plotly_require,
-        "leiden": leiden_install,
-        "networkx": networkx_install,
-        "all": plotly_require + test_require + leiden_install + networkx_install,
-    },
-    entry_points={"console_scripts": ["pygenstability=pygenstability.app:cli"]},
-    packages=find_namespace_packages("src"),
-    include_package_data=True,
-    package_dir={"": "src"},
+    ext_modules=[
+        Pybind11Extension(
+            "pygenstability.generalized_louvain",
+            ["src/pygenstability/generalized_louvain/generalized_louvain.cpp"],
+            include_dirs=["extra", "generalizedLouvain"],
+            extra_compile_args=["-std=c++11"],
+            optional=True,
+        ),
+    ],
 )
+20 −9		CPP/cliques/Makefile
+89 −26		CPP/cliques/graphhelpers.h
+23 −46		CPP/cliques/linearised_internals_comb.h
+22 −57		CPP/cliques/linearised_internals_generic.h
+22 −39		CPP/cliques/linearised_internals_norm.h
+177 −171		CPP/cliques/louvain_gen.h
+7 −7		CPP/cliques/run_gen_louvain.cpp
+11 −28		CPP/cliques/stability_gen.h
+28 −41		CPP/cliques/vector_partition.h