linearized_directed: sparse path for alpha<1 (issue #69)

[arnaudon]

Summary

• Refactors constructor_linearized_directed so the alpha < 1 path no longer materialises an N×N teleportation matrix. Decomposes M(alpha) = alpha * D^-1 A + u * 1^T and stores only the sparse part alpha * D^-1 A - I in partial_quality_matrix; the rank-1 teleportation correction is folded into the null model as an extra pair (-t * Pi * u, 1). The stationary distribution pi is computed via a matrix-free scipy.sparse.linalg.LinearOperator + ARPACK, never allocating a dense matrix.
• Memory drops from O(N^2) to O(nnz(A) + N). The original 180k-node OOM in Memory issue for large directed graphs #69 (~241 GiB) becomes a few hundred MB.
• Adds a docstring warning to constructor_directed (matrix-exponential variant remains unsupported for large graphs — exp(t * (M - I)) is dense even with the sparse + low-rank decomposition).
• Targets plotting-cleanup rather than master since it stacks on that branch.

Changes

• src/pygenstability/constructors.py: refactored constructor_linearized_directed.prepare() and _get_data(); warning admonition added to constructor_directed.
• tests/test_constructors.py: 6 new test cases (parametrised over alpha):
  • test_linearized_directed_alpha_lt_one_matches_dense — sparse path equals dense reference at machine eps for alpha ∈ {0.5, 0.8, 0.99}.
  • test_linearized_directed_alpha_lt_one_dangling — handles dangling sinks (out-degree 0) for alpha ∈ {0.5, 0.85}.
  • test_linearized_directed_alpha_lt_one_sparse_memory — 10k-node graph stays sparse with nnz <= nnz(A) + N.
• tests/data/test_constructor_linearized_directed{,_gap}.yaml: regenerated to reflect new sparse quality + 4-vector null_model shape.

Notes

• C++ Louvain backend already supports arbitrary even number of null-model vector pairs (signed_modularity uses 2 pairs); no C++ changes needed.
• The matrix-free LinearOperator uses v0 = linspace(1, 2)/sum(...) to avoid ARPACK error -9 ("starting vector is zero") on doubly-stochastic walks where the uniform vector is exactly the stationary distribution.
• All 26 existing tests still pass; mypy and ruff clean.

Test plan

• pytest tests/test_constructors.py — 10 passed (4 existing + 6 new)
• pytest tests/ — 26 passed
• mypy src/pygenstability/constructors.py — no issues
• ruff check and ruff format --check — clean
• Manual smoke on 50k-node random graph: prepare in 0.24s, peak RSS 212 MB
• CI runs

Closes part of #69 (linearized_directed only; the matrix-exponential directed constructor remains O(N²) by design, now documented as such).

🤖 Generated with Claude Code