Rewiring

Degree-preserving rewiring algorithms for controlling clustering.

Big-V rewiring

big_v

Big-V rewiring for introducing clustering into networks.

Degree-preserving rewiring that adds triangles by finding 5-node paths and reconnecting the endpoints. Uses net triangle tracking to allow rewires that break some triangles if they create more.

BigVRewirer

BigVRewirer(
    adjacency: csr_matrix,
    rng: Generator | None = None,
    min_delta: int = 1,
)

Degree-preserving rewiring to increase network clustering.

Finds 5-node paths and rewires endpoints to create triangles while preserving the degree sequence. Uses net triangle tracking to accept rewires that have a positive net effect on triangles.

Parameters:

Name	Type	Description	Default
adjacency	csr_matrix	Input network (will not be modified).	required
rng	Generator | None	Random generator for reproducibility.	None
min_delta	int	Minimum net triangle change to accept a rewire. Default is 1 (must add at least one triangle). Set to 0 to accept triangle-neutral rewires.	1

clustering_components

clustering_components() -> ClusteringComponents

Get current clustering coefficient components.

rewire

rewire(iterations: int) -> csr_matrix

Apply rewiring iterations and return the modified network.

rewire_to_clustering

rewire_to_clustering(
    target: float, max_attempts: int | None = None
) -> csr_matrix

Rewire until target clustering coefficient is reached.

Parameters:

Name	Type	Description	Default
target	float	Target global clustering coefficient.	required
max_attempts	int | None	Maximum rewiring attempts.	None

Returns:

Type	Description
csr_matrix	Rewired network.

Raises:

Type	Description
ValueError	If target is not achievable.

ClusteringComponents dataclass

ClusteringComponents(triangles: int, triplets: float)

Numerator and denominator of global clustering coefficient.

C = 3 × triangles / triplets

coefficient property

coefficient: float

Compute the clustering coefficient.

big_v_rewire

big_v_rewire(
    adjacency: csr_matrix,
    iterations: int | None = None,
    target_clustering: float | None = None,
    rng: Generator | None = None,
    min_delta: int = 1,
) -> csr_matrix

Apply Big-V rewiring to introduce clustering.

Provide either iterations for fixed rewiring count, or target_clustering to rewire until a specific coefficient is reached.

Parameters:

Name	Type	Description	Default
adjacency	csr_matrix	Input network (will not be modified).	required
iterations	int | None	Number of rewiring attempts.	None
target_clustering	float | None	Target global clustering coefficient.	None
rng	Generator | None	Random generator for reproducibility.	None
min_delta	int	Minimum net triangle change to accept a rewire. Default is 1. Set to 0 for more flexible rewiring.	1

Returns:

Type	Description
csr_matrix	Rewired network with increased clustering.

Motif decomposition

motif_decomposition

Motif Decomposition algorithm for generating networks with target clustering.

Implements the "tearing" algorithm from Ritchie et al. (2014) Section 2.1.2. Starts with disconnected cliques (clustering = 1.0) and iteratively rewires edges to reduce clustering to a target level.

Uses incremental triangle tracking for efficient clustering coefficient updates.

motif_decomposition

motif_decomposition(
    num_nodes: int,
    clique_size: int,
    target_clustering: float,
    *,
    rng: Generator | None = None,
    max_iterations: int = 100000,
) -> csr_matrix

Generate network via motif decomposition.

Starts with disconnected complete subgraphs (cliques) and iteratively rewires edges to reduce clustering from 1.0 to the target level.

Parameters:

Name	Type	Description	Default
num_nodes	int	Total nodes N (must be divisible by clique_size).	required
clique_size	int	Size of initial cliques m (e.g., 3 for triangles, 4 for K4).	required
target_clustering	float	Desired global clustering coefficient (0 to 1).	required
rng	Generator | None	Random generator for reproducibility.	None
max_iterations	int	Safety limit to prevent infinite loops.	100000

Returns:

Type	Description
csr_matrix	Sparse adjacency matrix with target clustering.

Raises:

Type	Description
ValueError	If num_nodes is not divisible by clique_size.
ValueError	If target_clustering is not in [0, 1].
ValueError	If clique_size < 2.