Threshold

The Threshold model [1] describes a diffusion process in which each node in a network adopts a behavior (becomes active) when a sufficient fraction or weighted sum of its neighbors are already active. Unlike the Independent Cascades model, which uses independent stochastic activations, the Threshold model relies on deterministic or probabilistic thresholds that control adoption.

Model Description

At each iteration \(k\), every inactive node \(i\) checks the fraction (or weighted fraction) of its neighbors that are active. If this value exceeds its threshold \(\theta_i\), the node becomes active in the next iteration.

Threshold model diagram

We use one Boolean indicator vector \(h \in \{0,1\}^N\), where \(h_i=1\) denotes Active, \(h_i=0\) denotes Inactive.

  1. Each active neighbor \(j\) of node \(i\) transmits a contribution

\[m_{ji}^{(k)} = h_j^{(k-1)}\]

  1. Node \(i\) collects contributions from all neighbors \(N(i)\) to compute its active probability:

\[m_i^{(k)} = \frac{1}{|N(i)|}\sum_{j \in N(i)} m_{ji}^{(k)}\]

  1. The indicator variables are updated by:

\[\begin{split} h_i^{(k)} = \begin{cases} 1, \text{if} (\theta_i \leq m_i^{(k)}) \land h_i^{(k-1)}=0 , \\[4pt] h_i^{(k-1)}, \text{otherwise}, \end{cases} \\[6pt]\end{split}\]

Status

During the simulation, each node can be in one of two states:

Status

Code

Inactive

0

Active

1

ThresholdModel

class fs_gplib.Epidemics.ThresholdModel(data, seeds, threshold: float, device='cpu', use_weight: bool = False, rand_seed=None)[source]

Bases: DiffusionModel

Threshold diffusion model on static graphs.

Each node starts as inactive or active (seed). At every step an inactive node becomes active if the influence received from its active neighbors reaches its threshold. Once activated, a node stays active permanently.

Returned node states are encoded as: 0 = inactive, 1 = active.

Parameters:

  • data (torch_geometric.data.Data) -- PyTorch Geometric Data object representing graph \(G=(V,E)\). Must contain edge_index (the edge set \(E\)) and num_nodes (\(|V|\)). When use_weight is True, edge_attr supplies per-edge weights.

  • seeds (list[int] | float) -- Nodes whose initial state is Active. Pass a list of node IDs, or a float in (0, 1) to activate that fraction of nodes chosen uniformly at random.

  • threshold (float) -- Adoption threshold. When \(\theta \in (0,1)\), all nodes share the same threshold value. When \(\theta == 0\), a threshold is sampled independently for each node from Uniform(0,1); for batched Monte-Carlo epochs, thresholds are sampled independently in each epoch.

  • device (str | int) -- (optional) 'cpu' or a CUDA device index. Defaults to 'cpu'.

  • use_weight (bool) -- (optional) If True, use weighted influence from data.edge_attr; otherwise use the mean fraction of active neighbors. Defaults to False.

  • rand_seed (int | None) -- (optional) Random seed used when seeds is a float. Defaults to None.

run_iteration()[source]

Execute a single simulation step.

The internal node_status is updated so that subsequent calls continue from the latest state.

Returns:

Node states after one step, shape (1, N).

Return type:

torch.Tensor

run_iterations(times)[source]

Execute times simulation steps sequentially.

The internal node_status is updated in-place so that subsequent calls continue from the latest state.

Parameters:

times (int) -- Number of maximum simulation steps to run, each step runs until no node remains newly active.

Returns:

Node states at final step, shape (1, N).

Return type:

torch.Tensor

run_epoch(iterations_times)[source]

Run a single Monte-Carlo epoch (one independent realisation).

Node states are re-initialised before the epoch starts.

Parameters:

iterations_times (int) -- Number of maximum simulation steps per epoch, each epoch runs until no node remains newly active.

Returns:

Node states at final step of the epoch, shape (1, N).

Return type:

torch.Tensor

run_epochs(epochs, iterations_times, batch_size=100)[source]

Run multiple independent Monte-Carlo epochs in batches.

Node states are re-initialised before the run.

Parameters:

  • epochs (int) -- Total number of independent realisations.

  • iterations_times (int) -- Number of maximum simulation steps per epoch, each epoch runs until no node remains newly active.

  • batch_size (int) -- (optional) Number of epochs processed in parallel per batch. Defaults to 100.

Returns:

Node states at final step of all epochs, shape (epochs, N).

Return type:

torch.Tensor

References