Propagation models

Propagation models#

What is a propagation model?#

In network_diffusion, a propagation model is considered as one or several phenomena acting in the network. To create a spreading model, we must extend the abstract base class nd.models.BaseModel by implementing the following methods, which define the mechanism of diffusion:

  • determine_initial_states,

  • agent_evaluation_step,

  • network_evaluation_step.

Additionally, the following class attributes must be provided:

  • _compartmental_graph,

  • _seed_selector,

and two auxiliary methods for reporting: __str__ and get_allowed_states.

It is important to note that the spreading model does not treat a network as an internal parameter. Networks are bound to models during experiment execution in the nd.Simulator class.

nd.models.BaseModel.determine_initial_states#

This method determines the initial state of the network before the start of the simulation. At this stage, the diffusion seeds are also chosen. The method returns a list of NetworkUpdateBuffer structures, which contain the necessary information for updating the network state (specifically, the agent’s ID and states in each layer).

nd.models.BaseModel.agent_evaluation_step#

This method is called during each simulation step for each agent individually. It takes the agent’s ID, the ID of the layer for which the evaluation takes place, and the network itself. It determines the state the agent will adopt in the next step of the experiment. This is done by reading the set of possible states into which the agent can fall, and by iteratively attempting (for example) to adopt the neighbour’s state with a probability derived from the _compartmental_graph. The output of this function is the new state of an agent in the given network layer.

nd.models.BaseModel.network_evaluation_step#

This method is responsible for evaluating the entire network in a single experiment step. It involves iterating over each agent to determine its new state according to the method agent_evaluation_step. The output is a list of NetworkUpdateBuffer structures.

nd.models.BaseModel._seed_selector#

This property ranks agents of the network. Then, the ranking is used to set seeds of diffusion, i.e., a given fraction of agents is chosen from the beginning of the list. For details, see a reference <seed_selection.html> of available seed selectors.

nd.models.BaseModel._compartmental_graph#

This property is used to store all possible states of the agents and allowed transitions between them. For details, see a guide of using this class.

Auxiliary abstract methods#

To provide comprehensive experiment logging, a user needs to implement two functions. The first one - __str__ should print a general description of the model with compartments and allowed transitions (which can be readily derived from a property _compartmental_graph ). The second method, get_allowed_states is used in the process of creating a simulation report. It is supposed to return a dictionary with a list of network layers where each of phenomena took place and allowed states in each layer.

Concrete spreading models#

network_diffusion also provides out-of-the-box spreading models (like LTM or ICM) adapted to multilayer networks. For details, see a reference.

Contents