Skip to content

Models

cynetdiff.models

DiffusionModel

Base class for Diffusion Models. This class provides an interface for advancing, resetting, and retrieving newly activated nodes. Nodes for the graph of the diffusion process have labels in [0, n-1] and the graph is represented in compressed sparse row format.

advance_model() method descriptor

Advances the diffusion model by one step. Since these diffusion models are progressive, the number of activated nodes cannot decrease.

Examples:

>>> old_num_active = model.get_num_activated_nodes()
>>> model.advance_model()
>>> model.get_num_activated_nodes() >= old_num_active
True

advance_until_completion() method descriptor

Continuously advances the model until the diffusion process is complete.

Examples:

>>> model.advance_until_completion()
>>> activated_nodes = model.get_num_activated_nodes()
>>> model.advance_model()
>>> activated_nodes == model.get_num_activated_nodes()
True

compute_payoffs()

Computes the payoffs of each active node. Payoffs are defaulted to 1.0 if not set.

Returns:

Type Description
float

Sum of payoffs for all activated nodes.

Examples:

>>> model.set_seeds([0, 1, 2])
>>> model.compute_payoffs()
3.0

get_activated_nodes() method descriptor

Yields all activated nodes.

Yields:

Type Description
int

All of the currently activated nodes.

Examples:

>>> model.set_seeds([0, 1, 2])
>>> for node in model.get_activated_nodes()
...    print(node)
0
1
2

get_newly_activated_nodes() method descriptor

A generator yielding the nodes that were newly activated in the last iteration of the model. If the model has not yet been run, this is just the current seed nodes.

Yields:

Type Description
int

The label of a node that was newly activated.

Examples:

>>> model.set_seeds([0, 1, 2])
>>> set(model.get_newly_activated_nodes())
{0, 1, 2}
>>> model.advance_until_completion()
>>> len(set(model.get_newly_activated_nodes()))
0

get_num_activated_nodes()

Returns the total number of activated nodes in the model.

Returns:

Type Description
int

Total number of activated nodes.

Examples:

>>> model.set_seeds([0, 1, 2])
>>> model.get_num_activated_nodes()
3

reset_model() method descriptor

Resets the model to the original set of seed nodes. This is useful if running many simulations over the same original seed set. If randomized activation is enabled, resetting the model will perform the randomized activation step.

Examples:

>>> model.set_seeds([0, 1, 2])
>>> model.advance_until_completion()
>>> model.get_num_activated_nodes()
10
>>> model.reset_model()
>>> model.get_num_activated_nodes()
3

set_rng(rng=None) method descriptor

Sets the random number generator for the model. If not set, creates a new generator by default.

Parameters:

Name Type Description Default
rng SeedLike | RNGLike | None

Random number generator to use for the model.

 None

Examples:

>>> rng_seed = 42
>>> model.set_rng(rng_seed)
>>> model.advance_until_completion()
>>> old_num = model.get_num_activated_nodes()
>>> model.set_rng(rng_seed)
>>> model.advance_until_completion()
>>> old_num == model.get_num_activated_nodes()
True

set_seeds(seeds, seed_probs=None) method descriptor

Sets the initial active nodes (seeds) for the diffusion process. Must be valid nodes in the graph. If activation probabilities are set, they represent the probability of activation for each seed node. Must be in the range [0.0, 1.0].

Parameters:

Name Type Description Default
seeds Iterable[int]

Seeds to set as initially active.

 required
seed_probs Optional[Iterable[float]]

Activation probabilities for each seed node. Entries must be in the range [0.0, 1.0]. Length must be equal to seeds. If not set, seeds are always active.

 None

Raises:

Type Description
ValueError

If a node in the seed set is invalid (not in the graph).

Examples:

>>> model.set_seeds([0, 1, 2])
>>> set(model.get_activated_nodes())
{0, 1, 2}

IndependentCascadeModel

Bases: cynetdiff.models.DiffusionModel

A Diffusion Model representing the Independent Cascade process. This class is a subclass of the DiffusionModel and provides specific implementations for the Independent Cascade diffusion process.

Parameters:

Name Type Description Default
starts array

An array of start indices for each node's edges in the edge array. Type of array elements must be unsigned int.

 required
edges array

An array of edges represented as integer indices of nodes. Type of array elements must be unsigned int.

 required
payoffs array

An array of payoffs for each node if activated. Type of array elements must be float.

 None
activation_prob float

Uniform activation probability for the Independent Cascade model. Defaults to 0.1. Should not be set if activation_probs is set. Must be in [0.0,1.0].

 0.1
activation_probs array

Set individual activation probabilities for the Independent Cascade model. Overrides activation_prob. Array elements must be floats in [0.0,1.0].

 None
rng Generator | BitGenerator | None

Random number generator to use for the model. If not set, creates a new generator by default.

 None
_edge_probabilities array

An array of success probabilities for each edge, default is None.

 None

compute_marginal_gains(seed_set, new_seeds, num_trials) method descriptor

Computes the marginal gain of adding each seed in new_seeds on top of the original seed_set. Averages over num_trials number of randomized activations. Scores are computed using payoffs if set, otherwise the number of activated nodes is used.

Parameters:

Name Type Description Default
seed_set Iterable[int]

An iterable representing the current seed set. Can be empty.

 required
new_seeds List[int]

New seeds to compute marginal gains on. Can be empty.

 required
num_trials int

Number of randomized trials to run.

 required

Returns:

Type Description
List[float]

List containing computed marginal gains. First entry is average influence of the starting seed set. Following entries are marginal gains with the addition of vertices from new_seeds in order. Has length len(new_seeds)+1.

Examples:

>>> model.compute_marginal_gains([0, 1, 2], [3, 4], 100)
[3.0, 1.0, 1.0]

LinearThresholdModel

Bases: cynetdiff.models.DiffusionModel

A Diffusion Model representing the Linear Threshold process. This class is a subclass of the DiffusionModel and provides specific implementations for the Linear Threshold diffusion process.

Parameters:

Name Type Description Default
starts array

An array of start indices for each node's edges in the edge array. Type of array elements must be unsigned int.

 required
edges array

An array of edges represented as integer indices of nodes. Type of array elements must be unsigned int.

 required
payoffs array

An array of payoffs for each node if activated. Type of array elements must be float.

 None
influence array

An array of influence values for each edge. Array elements must be floats in [0.0,1.0]. If not set, the inverse of the in-degree of a node is used for the influence.

 None
rng Generator | BitGenerator | None

Random number generator to use for the model. If not set, creates a new generator by default.

 None

compute_marginal_gains(seed_set, new_seeds, num_trials, *, _node_thresholds=None) method descriptor

Computes the marginal gain of adding each seed in new_seeds on top of the original seed_set. Averages over num_trials number of randomized activations. Scores are computed using payoffs if set, otherwise the number of activated nodes is used.

Parameters:

Name Type Description Default
seed_set Iterable[int]

An iterable representing the current seed set. Can be empty.

 required
new_seeds List[int]

New seeds to compute marginal gains on. Can be empty.

 required
num_trials int

Number of randomized trials to run.

 required

Returns:

Type Description
List[float]

List containing computed marginal gains. First entry is average influence of the starting seed set. Following entries are marginal gains with the addition of vertices from new_seeds in order. Has length len(new_seeds)+1.

Examples:

>>> model.compute_marginal_gains([0, 1, 2], [3, 4], 100)
[3.0, 1.0, 1.0]