Modernize tooling, migrate metadata, refactor run(), make Louvain RNG deterministic

[arnaudon]

Summary

One PR with several logically-distinct commits. All behaviour-preserving unless called out. Originally drafted on the fork at arnaudon#1; moved here for review against upstream master.

Tooling & metadata

• Migrate lint + format to ruff (replaces black, pylint, pycodestyle, pydocstyle, isort). tox -e lint/tox -e format rewired; .pylintrc removed; rules in [tool.ruff].
• Migrate project metadata setup.py → pyproject.toml (PEP 621). setup.py keeps only the pybind11 extension declaration.
• Add upper bounds (numpy<3, scipy<2).
• Drop print() for logging in optional-dep fallback paths.
• python_requires=">=3.10" to match the tox matrix.

Code quality

• Type hints on the public API (run, evaluate_NVI, identify_optimal_scales, save_results, load_results); from __future__ import annotations.
• Refactor run() (150 lines → ~35). Extracted _resolve_exp_comp_mode, _scan_scales, _run_post_scan_analysis. Public signature unchanged.
• Fix np.divide(... where=...) UserWarnings in constructors.py by pre-allocating the zero output buffer (numpy 2.x made the uninitialised-buffer behaviour stricter; dangling-node entries now explicitly 0.0).
• Silence benign RuntimeWarnings in constructors.signed_modularity and optimal_scales._pool2d_nvi.
• Resolve the spectral-decomp TODO in constructors.py: use v.T instead of la.inv(v) (orthonormal eigenvectors → transpose is inverse, O(n²) instead of O(n³)).
• Type run(graph=...) as scipy.sparse.spmatrix | None.

CI

• Add a standalone lint job to .github/workflows/run-tox.yml.

Repo hygiene

• Drop pygenstability_doc.pdf (~720 KB build artifact); added to .gitignore.
• Add results.pkl plus example/run artifacts (scan_results.pdf, *.gpickle, examples/communities/, …) to .gitignore.
• Cover .coverage-* multi-env coverage files in .gitignore.
• Fix Homepage URL: ImperialCollegeLondon/PyGenStability → barahona-research-group/PyGenStability (matches CI badges + issues).

Make Louvain RNG deterministic end-to-end

Three coordinated changes that replace the global C rand() / std::random_shuffle path with an explicit std::mt19937& threaded through the optimiser, and fix the multiprocessing.Pool ordering leak:

1. Submodule (michaelschaub/generalizedLouvain master): find_optimal_partition_louvain[_gen] takes a std::mt19937& and uses a portable Fisher-Yates shuffle. Submodule pointer + .gitmodules now track upstream master (the RNG fix has merged via Replace global rand with std::mt19937 in Louvain michaelschaub/generalizedLouvain#1, Clean the test script #2, doc #3).
2. Binding (generalized_louvain.cpp): drop std::srand(seed), construct a local std::mt19937(seed) and pass it explicitly. No global state touched.
3. Python (_optimise / _run_optimisations): pre-generate per-try seeds in the parent process, dispatch via pool.starmap so each try always gets the same seed regardless of which worker picks it up.

pgs.run(...) now produces bit-identical results across re-runs, processes, and n_workers for a given numpy seed. Determinism guarded by test_run_is_deterministic parameterised on n_workers=[1, 2].

The earlier "Loosen flaky RNG-dependent equality asserts" commit is reverted as part of this change — strict dictdiffer.diff(..., tolerance=1e-5) == [] checks are restored, the test_run_gap.yaml fixture is regenerated against the new RNG path, and the tautological yaml.dump(...) in test_run_times is commented out so its assert actually validates.

Test plan

• tox -e lint passes (ruff check + ruff format --check)
• Full pytest tests/ (excluding test_plotting) passes locally on Python 3.14: 14/14, ~96s with MPLBACKEND=Agg
• Determinism smoke test: same numpy seed → identical community_id and stability across pgs.run invocations, with both n_workers=1 and n_workers=2
• CI green on 3.10 / 3.11 / 3.12 (this PR)
• Editable install builds and links the pybind11 extension; import pygenstability; pygenstability.run resolves

[juni-schindler]

I added a few suggestions. Some of the new comments in the code are a bit weird because Claude explained why the code has been changed.

[juni-schindler]

It would be good to have a seed parameter for the run function that the user can set. A few changes will be required but it would be really useful.

[arnaudon]

good point, I added rng option

[juni-schindler]

It looks good! But what happens if the seed is None? Would it not be better to provide a default seed 42?

[juni-schindler]

and should we also address #111 here?

[arnaudon]

On seed=None vs seed=42 default — I'd keep seed=None:

• Convention. Scientific Python defaults to non-deterministic: np.random.default_rng(), sklearn random_state=None, scipy optimisers. "No seed argument" → "fresh entropy" is the expectation users bring in.
• Backward compatibility. Pre-PR behaviour was non-deterministic (unseeded global np.random). seed=None preserves that for anyone upgrading; seed=42 would silently change every existing run's output.
• Silent reproducibility is a footgun. With a hardcoded default, every pgs.run(graph) returns the same partition. A user re-running their script to characterise stability across runs would see no variance and wrongly conclude the algorithm is deterministic, when really they're just reusing one seed. The whole point of n_tries is to characterise optimiser variance — locking the inter-run RNG defeats that motivation at the outer scale.
• Explicit > implicit. seed=None makes users who want reproducibility type seed=42, which is the line they'll also need in their paper's methods section. Worth the small friction.

The cost is that tests/examples need explicit seeds — which is what we just did, and what they should have anyway.

On #111 — I'd address it separately. It's a numerical-correctness bug in Leiden vs Louvain when n_null ≥ 2, well-scoped but unrelated to the tooling/refactor/seed work here. Fixing it changes signed_modularity numerics (another fixture regen), needs cross-backend convergence tests, and this PR is already 30+ files across several concerns. Cleaner to merge this one and open a focused follow-up.