🎲 Generation

Submodules

hypergraphx.generation.activity_driven module

hypergraphx.generation.activity_driven.HOADmodel(N, activities_per_order, time=100, *, seed=None)

Generate a temporal hypergraph according to the HOAD model.

Parameters:

• N (int) – The number of nodes in the hypergraph.

• activities_per_order (dict) – The dictionary of activities per order. The keys are the orders and the values are the activities.

• time (int) – The number of time steps.

Returns:

HG – The temporal hypergraph generated according to the HOAD model.

Return type:

TemporalHypergraph

Examples

>>> import numpy as np
>>> from hypergraphx.generation import HOADmodel
>>> acts = {2: np.array([0.1, 0.2, 0.3])}  # order=2 => size=3 hyperedges
>>> T = HOADmodel(3, acts, time=5, seed=0)
>>> isinstance(T.get_edges(), list)
True

hypergraphx.generation.activity_driven.rnd_pwl(xmin, xmax, g, size=1, *, seed=None)

hypergraphx.generation.configuration_model module

hypergraphx.generation.configuration_model.configuration_model(hypergraph, n_steps=1000, label='edge', order=None, size=None, n_clash=1, detailed=True, seed=None)

Sample a randomized hypergraph using a configuration-model-style MCMC.

Parameters are largely legacy; the key UX improvements are: - seed= controls the RNG (reproducible, does not rely on global np.random.seed) - when order/size is provided, only that size class is rewired

Examples

>>> from hypergraphx import Hypergraph
>>> from hypergraphx.generation import configuration_model
>>> H = Hypergraph(edge_list=[(0, 1), (1, 2), (0, 1, 2)], weighted=False)
>>> H2 = configuration_model(H, n_steps=10, label="edge", seed=0)
>>> H.num_edges() == H2.num_edges()
True

hypergraphx.generation.hy_mmsbm_sampling module

MCMC sampler for the Hy-MMSBM probabilistic model, described in

“A framework to generate hypergraphs with community structure” Ruggeri N., Contisciani M., Battiston F., De Bacco C.

Notice that the sampler is separate from the probabilistic model itself. In this view, the sampler only takes care of any sampling-related operation, and refers back to the model to retrieve any probability-related value (e.g. Poisson probabilities, expected degree, etc.).

class hypergraphx.generation.hy_mmsbm_sampling.HyMMSBMSampler(u=None, w=None, max_hye_size=None, exact_dyadic_sampling=True, burn_in_steps=1000, intermediate_steps=1000, seed=42)

Bases: object

Sampler for the Hy-MMSBM model. This class takes care of the approximate sampling routine described in

“A framework to generate hypergraphs with community structure” Ruggeri N., Contisciani M., Battiston F., De Bacco C.

sample(deg_seq=None, dim_seq=None, avg_deg=None, initial_hyg=None, allow_rescaling=False)

Approximate hypergraph sampling routine presented in

“A framework to generate hypergraphs with community structure” Ruggeri N., Contisciani M., Battiston F., De Bacco C.

Possibly, condition the sampling on different quantities: the expected average degree, a given degree sequence and/or dimension sequence, or a hypergraph.

Parameters:

• deg_seq (degree sequence) – This is specified as an array of degrees, one per node in the hypergraph.

• dim_seq (dimension sequence) – This is specified as a dictionary with {key: value} pairs {dimension: number of hyperedges with that dimension}

• avg_deg (average degree)

• initial_hyg (an initial hypergraph to start the MCMC from.) – If initial_hyg is provided, all the other inputs (i.e. deg_seq, dim_seq, avg_deg, allow_rescaling) are ignored. The MCMC is started using initial_hyg as first configuration, which is statistically equivalent to conditioning on its degree and dimension sequences. During MCMC, the degree and dimension sequences in initial_hyg are preserved.

• allow_rescaling (allow the rescaling of the u and w parameters in place.) – This adjusts for the sampling constraints, e.g. average degree.

Returns:

• A generator of sampled hypergraphs.

• Notice that all the generated hypergraphs are conditioned on the same degree and

• dimension sequences (possibly provided as input, otherwise sampled at the

• beginning and kept constant). To sample conditioning on different sequences, a

• new call to this method is required.

hypergraphx.generation.hy_mmsbm_sampling.sample_truncated_poisson(lambd, rng=None)

Sample a truncated Poisson. If X is a Poisson random variable with parameter lambda, the relative truncated Poisson variable Y with same parameter lambda is defined as Y = X | X > 0.

hypergraphx.generation.random module

Generate random hypergraphs

hypergraphx.generation.random.add_random_edge(hg, order=None, size=None, inplace=False, seed=None)

Add a random hyperedge of a given order / size to a hypergraph.

Parameters:

• hg (hypergraph) – The Hypergraph of interest.

• order (int) – The order of the edge to add.

• size (int) – The size of the edge to add.

• inplace (bool) – Whether to modify the hypergraph in place or return a new one.

• seed (int, optional) – Seed for the random number generator

Returns:

The hypergraph with the added edge or None if inplace is True.

Return type:

Hypergraph or None

Raises:

ValueError – If order and size are both specified or neither are specified.

Examples

>>> from hypergraphx import Hypergraph
>>> from hypergraphx.generation import add_random_edge
>>> H = Hypergraph(edge_list=[(0, 1), (1, 2)], weighted=False)
>>> H2 = add_random_edge(H, size=3, inplace=False, seed=0)
>>> H.num_edges(), H2.num_edges()
(2, 3)

hypergraphx.generation.random.add_random_edges(hg, num_edges, order=None, size=None, inplace=False, seed=None)

Add random hyperedges of a given order / size to a hypergraph.

Parameters:

• hg (hypergraph) – The Hypergraph of interest.

• num_edges (int) – The number of edges to add.

• order (int) – The order of the edges to add.

• size (int) – The size of the edges to add.

• inplace (bool) – Whether to modify the hypergraph in place or return a copy.

• seed (int, optional) – Seed for the random number generator

Returns:

The hypergraph with the added edges or None if inplace is True.

Return type:

Hypergraph or None

Raises:

ValueError – If order and size are both specified or neither are specified.

hypergraphx.generation.random.random_hypergraph(num_nodes, num_edges_by_size, seed=None)

Generate a random hypergraph with a given number of nodes and hyperedges for each size. If a hyperedge is sampled multiple times, it will be added to the hypergraph only once.

Parameters:

• num_nodes (int)

• num_edges_by_size (dict) – A dictionary mapping the size of the hyperedges to the number of hyperedges of that size.

• seed (int, optional) – Seed for the random number generator.

Returns:

A random hypergraph with the given number of nodes and hyperedges for each size.

Return type:

Hypergraph

Examples

>>> from hypergraphx.generation import random_hypergraph
>>> random_hypergraph(10, {2: 5, 3: 3})
Hypergraph with 10 nodes and 8 edges.
Edge list: [(3, 4), (4, 9), (7, 9), (8, 9), (3, 6), (0, 6, 9), (3, 6, 8), (1, 3, 4)]

hypergraphx.generation.random.random_shuffle(hg, order=None, size=None, inplace=False, p=1.0, preserve_degree=False, seed=None)

Shuffle the nodes of a hypergraph’s hyperedges of a given order/size, replacing a fraction p of them.

Parameters:

• hg (Hypergraph) – The hypergraph to process.

• p (float, optional) – The fraction of hyperedges to randomize (0 <= p <= 1). Default is 1.0.

• order (int) – The order of the hyperedges to shuffle.

• size (int) – The size of the hyperedges to shuffle.

• inplace (bool, optional) – If True, modify the given hypergraph directly; if False, operate on a copy and return it.

• preserve_degree (bool, optional) – If True, attempt to preserve the degree distribution of the nodes during shuffling.

• seed (int, optional) – Seed for the random number generator.

Returns:

The shuffled hypergraph. If inplace=True, this is the input object.

Return type:

Hypergraph

Raises:

ValueError – If order and size are both specified or neither are specified, or if p is not between 0 and 1.

Examples

>>> from hypergraphx import Hypergraph
>>> from hypergraphx.generation import random_shuffle
>>> H = Hypergraph(edge_list=[(0, 1, 2), (2, 3, 4)], weighted=False)
>>> H2 = random_shuffle(H, size=3, p=1.0, inplace=False, seed=0)
>>> H is H2
False

hypergraphx.generation.random.random_shuffle_all_orders(hg, p=1.0, inplace=False, preserve_degree=False, seed=None)

Shuffle the nodes of a hypergraph’s hyperedges of a given order/size, replacing a fraction p of them. The process is repeated for every order of interaction.

Parameters:

• hg (Hypergraph) – The hypergraph to process.

• p (float, optional) – The fraction of hyperedges to randomize (0 <= p <= 1). Default is 1.0.

• inplace (bool, optional) – If True, modify the given hypergraph directly; if False, operate on a copy and return it.

• preserve_degree (bool, optional) – If True, attempt to preserve the degree distribution of the nodes during shuffling.

• seed (int, optional) – Seed for the random number generator.

Returns:

The hypergraph with shuffled hyperedges. This is either the original hypergraph (if inplace is True) or a new, modified copy (if inplace is False).

Return type:

Hypergraph

Raises:

ValueError – If p is not between 0 and 1.

Examples

>>> from hypergraphx import Hypergraph
>>> from hypergraphx.generation import random_shuffle_all_orders
>>> H = Hypergraph(edge_list=[(0, 1), (0, 1, 2)], weighted=False)
>>> H2 = random_shuffle_all_orders(H, p=1.0, inplace=False, seed=0)
>>> H.num_edges() == H2.num_edges()
True

hypergraphx.generation.random.random_uniform_hypergraph(num_nodes, size, num_edges, seed=None)

Generate a random hypergraph with a given number of nodes and hyperedges of a given size. If a hyperedge is sampled multiple times, it will be added to the hypergraph only once.

Parameters:

• num_nodes (int) – The number of nodes in the hypergraph.

• size (int) – The size of the hyperedges.

• num_edges (int) – The number of hyperedges of the given size.

• seed (int, optional) – Seed for the random number generator.

Returns:

A random hypergraph with the given number of nodes and hyperedges of the given size.

Return type:

Hypergraph

hypergraphx.generation.scale_free module

hypergraphx.generation.scale_free.scale_free_hypergraph(num_nodes, edges_by_size, alpha_by_size=1.0, rho=0, seed=None, enforce_unique_edges=True, max_tries_factor=50)

Generate a hypergraph from a hidden-variable (fitness / activity) model with heavy-tailed node activities, and tunable inter-size rank correlation.

Parameters:

• num_nodes (int) – Number of nodes (labeled 0..num_nodes-1).

• edges_by_size (dict[int, int]) – Mapping {hyperedge size (cardinality): number of hyperedges}.

• alpha_by_size (float | dict[int, float]) – Zipf exponent(s) controlling activity heterogeneity. Larger alpha => stronger hub dominance. If float, the same alpha is used for all sizes.

• rho (float) – Equicorrelation of latent Gaussian scores across sizes (controls inter-size rank correlation of activities). Can be negative, subject to rho ∈ [-1/(m-1), 1] when m>1.

• seed (int | None) – Seed for reproducibility.

• enforce_unique_edges (bool) – If True, enforces a simple hypergraph per size (no duplicate hyperedges) by rejection sampling.

• max_tries_factor (int) – Collision budget for uniqueness per size: ~ max_tries_factor * num_edges attempts.

Returns:

Generated hypergraph.

Return type:

Hypergraph

Module contents

Synthetic hypergraph generators.

This package exposes a curated set of generators at the package level for discoverability (e.g. hypergraphx.generation.random_hypergraph(…)).

Implementations are imported lazily on first use.

hypergraphx.generation.HOADmodel(*args, **kwargs)

hypergraphx.generation.add_random_edge(*args, **kwargs)

hypergraphx.generation.add_random_edges(*args, **kwargs)

hypergraphx.generation.random_hypergraph(*args, **kwargs)

hypergraphx.generation.random_shuffle(*args, **kwargs)

hypergraphx.generation.random_shuffle_all_orders(*args, **kwargs)

hypergraphx.generation.random_uniform_hypergraph(*args, **kwargs)

hypergraphx.generation.scale_free_hypergraph(*args, **kwargs)

Next steps

• 🚀 Quickstart

• 🧩 Core