DyKThreshold

The DyKThreshold (Dynamic Kertesz Threshold) model extends the static KThreshold model to time-varying networks. Instead of evolving on a fixed graph \(G=(V,E)\), diffusion is performed on a sequence of snapshots \(\{G^{(k)}=(V,E^{(k)})\}_{k=1}^{T}\), where neighborhood relations may change at each discrete step \(k\).

Compared with DyThreshold, DyKThreshold introduces two extra mechanisms:

1. spontaneous adoption with probability adopter_rate;

2. blocked nodes sampled once from initially inactive nodes with ratio percentage_blocked.

Blocked nodes never become active. Non-blocked inactive nodes can become active either by spontaneous adoption or by threshold-based adoption.

Implementation

Let \(h_i^{(k)} \in \{0,1\}\) denote the activity indicator of node \(i\) at step \(k\), and \(b_i \in \{0,1\}\) denote whether node \(i\) is blocked.

• \(h_i=0, b_i=0\): inactive

• \(h_i=1, b_i=0\): active

• \(h_i=0, b_i=1\): blocked

The dynamics follow four stages:

1. Blocked-node initialization (performed once): among initially inactive nodes, sample a subset as blocked according to percentage_blocked.

2. Neighbor contribution at snapshot \(k\):

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

where \(w_{ji}^{(k)}=1\) when edge weights are not provided.

3. Influence aggregation for node \(i\):

\[m_i^{(k)} = \operatorname{Agg}_{j\in N^{(k)}(i)} m_{ji}^{(k)}.\]

When edge_attr_list is not provided, aggregation uses mean influence; otherwise weighted sum is used.

4. State update for non-blocked inactive nodes:

\[\begin{split}h_i^{(k)} = \begin{cases} 1, & \text{if } h_i^{(k-1)}=0 \land b_i=0 \land \bigl((U_i^{\mathrm{adopt}} < \alpha)\ \lor\ (\theta_i \le m_i^{(k)})\bigr), \\[4pt] h_i^{(k-1)}, & \text{otherwise}, \end{cases}\end{split}\]

where \(U_i^{\mathrm{adopt}} \sim \mathrm{Uniform}(0,1)\), \(\alpha =\) adopter_rate, and \(\theta_i\) is the node threshold.

Blocked nodes are fixed and always reported as state -1 in outputs. As with other dynamic models, \(N^{(k)}(i)\) and optional edge weights are time-dependent, and the maximum number of iterations is bounded by \(T =\) len(edge_index_list).

Status

During the simulation, a node can be in one of the following states:

Status	Code
Inactive	0
Active	1
Blocked	-1

DyKerteszThresholdModel

class fs_gplib.Dynamic.DyKerteszThresholdModel(x, edge_index_list, seeds, threshold: float, adopter_rate: float, percentage_blocked: float, device='cpu', rand_seed=None, edge_attr_list=None)

Bases: DiffusionModel

Dynamic Kertesz Threshold diffusion model on time-varying networks.

This model extends the dynamic Threshold process with two additional mechanisms: spontaneous adoption and blocked nodes. Diffusion evolves on a snapshot sequence \(\{G^{(k)}=(V,E^{(k)})\}_{k=1}^{T}\). A non-blocked inactive node may become active either because the influence aggregated from active neighbors in the current snapshot reaches its threshold, or because it spontaneously adopts with probability adopter_rate at that step. Once activated, a node remains active.

A fraction percentage_blocked of initially inactive nodes is sampled as blocked when a realisation starts. Blocked nodes never activate and are reported as state -1 in outputs.

Returned tensors encode states as float values: blocked -1, inactive 0, active 1.

The number of simulation steps cannot exceed len(edge_index_list).

Parameters:

• x (torch.Tensor) -- Node tensor of shape (N, 1).

• edge_index_list (list[torch.Tensor]) -- List of snapshot edge_index tensors, length \(T\).

• seeds (list[int] | float) -- Initially active nodes: list of node IDs or a float in (0,1).

• threshold (float) -- Node adoption threshold in [0,1]. If threshold > 0, every node uses that same threshold value; if threshold == 0, node thresholds are sampled uniformly in \([0,1)\); during batched multi-epoch execution, random thresholds are re-sampled independently for each epoch batch when threshold == 0.

• adopter_rate (float) -- Spontaneous adoption probability per step for each non-blocked inactive node.

• percentage_blocked (float) -- Fraction of initially inactive nodes randomly designated as blocked.

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

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

• edge_attr_list (list[torch.Tensor] | None) -- (optional) Snapshot edge weights aligned with edge_index_list.

run_iteration()

Advance the diffusion by one snapshot step.

The internal node_status is updated so that subsequent calls continue from the latest state. Requires at least one remaining snapshot. If blocked nodes have not yet been sampled for this realisation, they are initialised during this call.

Returns:

Node states after that step, shape (1, 1, N) (values -1, 0, or 1).

Return type:

torch.Tensor

run_iterations(times)

Run times consecutive snapshot steps on the evolving graph sequence.

The internal node_status is updated to the state after the last step. Requires len(edge_index_list) - t >= times where \(t\) is the number of steps already consumed on this process. If blocked nodes have not yet been sampled for this realisation, they are initialised once before the first step.

Parameters:

times (int) -- Number of snapshots to advance (must not exceed remaining snapshots).

Returns:

Node states after each step, stacked with shape (times, 1, N) (values -1, 0, or 1).

Return type:

torch.Tensor

run_epoch()

Run one Monte-Carlo realisation over the full snapshot sequence.

The process internal step counter is reset; node states are re-initialised before the epoch starts. A new blocked-node set is sampled for that realisation from initially inactive nodes.

Returns:

Node states trajectory over all snapshots, shape (T, 1, N) with \(T =\) len(edge_index_list) (values -1, 0, or 1).

Return type:

torch.Tensor

run_epochs(epochs, batch_size=200)

Run multiple independent Monte-Carlo realisations in batches.

For each realisation the snapshot index is reset to the beginning and the diffusion is evolved through all snapshots. Node states are re-initialised before the run. A blocked-node set is sampled once per realisation from initially inactive nodes.

When threshold == 0, random node thresholds are re-sampled independently for each epoch batch.

Parameters:

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

• batch_size (int) -- (optional) Parallel epochs per batch. Defaults to 200.

Returns:

Node states trajectories for all realisations, shape (T, E, N) where \(T =\) len(edge_index_list) and \(E\) is epochs (values -1, 0, or 1).

Return type:

torch.Tensor

Note

The dynamic model uses x + edge_index_list instead of a single static data object. Optional edge weights are passed as edge_attr_list.