gossipy.simul module#

Module contents#

class gossipy.simul.GossipSimulator(nodes, data_dispatcher, delta, protocol, drop_prob=0.0, online_prob=1.0, delay=ConstantDelay(0), sampling_eval=0.0)#

Bases: gossipy.simul.SimulationEventSender

Class that implements a vanilla gossip learning simulation.

The simulation is divided into “rounds” and each round consists of a delta timesteps. A single time step represent the time unit of the simulation. At each time step, the nodes that timed out act according to the gossip protocol, e.g., in the case of the PUSH protocol, the nodes send a message (i.e., its model) to a random neighbor. The message arrives at the destination node with a delay (see gossipy.simul.Delay). Messages can also drop according to a probability defined by the drop_prob parameter. Similarly, nodes can drop according to a probability equals to 1 - online_prob. Nodes are considered in a random order even if they time out in the same timestep.

The simulator implements the design pattern Observer (actually Event Receiver) extending the gossipy.simul.SimulationEventSender class. The events are:

  • update_message(): a message has been sent or dropped;

  • update_evaluation(): an evaluation has been computed;

  • update_timestep(): a timestep has been performed;

  • update_end(): the simulation has ended.

Parameters

  • nodes (dict[int, GossipNode]) – The nodes participating in the simulation. The keys are the node ids, and the values are the corresponding nodes (instances of the class GossipNode).

  • data_dispatcher (DataDispatcher) – The data dispatcher. Useful if the evaluation is performed on a separate test set, i.e., not on the nodes.

  • delta (int) – The number of timesteps of a round.

  • protocol (AntiEntropyProtocol) – The protocol of the gossip simulation.

  • drop_prob (float, default=0.) – The probability of a message being dropped.

  • online_prob (float, default=1.) – The probability of a node to be online.

  • delay (Delay, default=ConstantDelay(0)) – The (potential) function delay of the messages.

  • sampling_eval (float, default=0.) – The percentage of nodes to use during evaluate. If 0 or 1, all nodes are considered.

init_nodes(seed=98765)#

Initializes the nodes.

The initialization of the nodes usually involves the initialization of the local model (see GossipNode.init_model()).

Parameters

seed (int, default=98765) – The seed for the random number generator.

Return type

None

classmethod load(filename)#

Loads the state of the simulator (including the models’ cache).

Parameters

filename (str) – The name of the file to load the state.

Returns

The simulator loaded from the file.

Return type

GossipSimulator

save(filename)#

Saves the state of the simulator (including the models’ cache).

Parameters

filename (str) – The name of the file to save the state.

Return type

None

start(n_rounds=100)#

Starts the simulation.

The simulation handles the messages exchange between the nodes for n_rounds rounds. If attached to a SimulationReport, the report is updated at each time step, sent/fail message and evaluation.

Parameters

n_rounds (int, default=100) – The number of rounds of the simulation.

Return type

None

class gossipy.simul.SimulationEventReceiver#

Bases: abc.ABC

The event receiver interface declares all the update methods, used by the event sender.

abstract update_end()#

Receives an update about the end of the simulation.

Return type

None

update_evaluation(round, on_user, evaluation)#

Receives an update about an evaluation.

Parameters

  • round (int) – The round number.

  • on_user (bool) – Whether the evaluation set is store on the clients/users or on the server.

  • evaluation (list of dict[str, float]) – The evaluation metrics computed on each client.

Return type

None

abstract update_message(failed, msg=None)#

Receives an update about a sent or a failed message.

Parameters
Return type

None

abstract update_timestep(t)#

Signals the end of the timestep t.

Parameters

t (int) – The current time step.

class gossipy.simul.SimulationEventSender#

Bases: abc.ABC

The event sender interface declares methods for managing receviers.

add_receiver(receiver)#

Attaches an event receiver to the event sender.

Parameters

receiver (SimulationEventReceiver) – The receiver to attach.

Return type

None

notify_end()#

Notifies all receivers about the end of the simulation.

Return type

None

notify_evaluation(round, on_user, evaluation)#

Notifies all receivers about a performed evaluation.

Parameters

  • round (int) – The round number.

  • on_user (bool) – Whether the evaluation set is store on the clients/users or on the server.

  • evaluation (list of dict[str, float]) – The evaluation metrics computed on each client.

Return type

None

notify_message(falied, msg=None)#

Notifies all receivers about a sent message or a failed message.

Parameters
Return type

None

notify_timestep(t)#

Notifies all receivers that a timestep has happened.

Parameters

t (int) – The timestep number.

remove_receiver(receiver)#

Detaches an event receiver from the event sender.

If the receiver is not attached to the event sender, nothing happens.

Parameters

receiver (SimulationEventReceiver) – The receiver to detach.

Return type

None

class gossipy.simul.SimulationReport#

Bases: gossipy.simul.SimulationEventReceiver

Class that implements a basic simulation report.

The report traces the number of sent messages, the number of failed messages, the total size of the sent messages, and the evaluation metrics (both global and local).

The report is updated according to the design pattern Observer (actually Event Receiver). Thus, the report must be created and attached to the simulation before starting it.

Examples

>>> from gossipy.simul import SimulationReport
>>> from gossipy.simul import GossipSimulator
>>> simulator = GossipSimulator(...)
>>> report = SimulationReport()
>>> simulator.add_receiver(report)
>>> simulator.start(...)

The report object is now attached to the simulation and it will be notified about the events.

See also

gossipy.Sizeable

clear()#

Clears the report.

Return type

None

update_end()#

Receives an update about the end of the simulation.

Return type

None

update_evaluation(round, on_user, evaluation)#

Receives an update about an evaluation.

Parameters

  • round (int) – The round number.

  • on_user (bool) – Whether the evaluation set is store on the clients/users or on the server.

  • evaluation (list of dict[str, float]) – The evaluation metrics computed on each client.

Return type

None

update_message(failed, msg=None)#

Receives an update about a sent or a failed message.

Parameters
Return type

None

update_timestep(t)#

Signals the end of the timestep t.

Parameters

t (int) – The current time step.

class gossipy.simul.TokenizedGossipSimulator(nodes, data_dispatcher, token_account, utility_fun, delta, protocol, drop_prob=0.0, online_prob=1.0, delay=ConstantDelay(0), sampling_eval=0.0)#

Bases: gossipy.simul.GossipSimulator

Class that implements a gossip learning simulation using token account [].

The simulation happens similary to the GossipSimulator, but the communication pattern is handled by a token account algorithm (see TokenAccount). Token account based flow control mechanism can be useful in case of bursty communication [].

The simulator implements the design pattern Observer (actually Event Receiver) extending the gossipy.simul.SimulationEventSender class. The events are:

  • update_message(): a message has been sent or dropped;

  • update_evaluation(): an evaluation has been computed;

  • update_timestep(): a timestep has been performed;

  • update_end(): the simulation has ended.

Parameters

  • nodes (dict[int, GossipNode]) – The nodes participating in the simulation. The keys are the node ids, and the values are the corresponding nodes (instances of the class GossipNode).

  • data_dispatcher (DataDispatcher) – The data dispatcher. Useful if the evaluation is performed on a separate test set, i.e., not on the nodes.

  • token_account (TokenAccount) – The token account strategy.

  • utility_fun (Callable[[ModelHandler, ModelHandler, Message], int]) – Function defining the usefulness of a message. The usefulness expresses the notion that some messages are more important than others in most applications. For example, in the broadcast application, the received message is useful if and only if it contains new information for the node. The signatue of the function is: utility_fun(model_handler_1, model_handler_2, msg) -> int where model_handler_1 and model_handler_2 are the model handlers of the nodes involved in the message exchange, and msg is the message. The function must return an integer value.

  • delta (int) – The number of timesteps of a round.

  • protocol (AntiEntropyProtocol) – The protocol of the gossip simulation.

  • drop_prob (float, default=0.) – The probability of a message being dropped.

  • online_prob (float, default=1.) – The probability of a node to be online.

  • delay (Delay, default=ConstantDelay(0)) – The (potential) function delay of the messages.

  • sampling_eval (float, default=0.) – The percentage of nodes to use during evaluate. If 0 or 1, all nodes are considered.

init_nodes(seed=98765)#

Initializes the nodes.

The initialization of the nodes usually involves the initialization of the local model (see GossipNode.init_model()).

Parameters

seed (int, default=98765) – The seed for the random number generator.

Return type

None

start(n_rounds=100)#

Starts the simulation.

The simulation handles the messages exchange between the nodes for n_rounds rounds. If attached to a SimulationReport, the report is updated at each time step, sent/fail message and evaluation.

Parameters

n_rounds (int, default=100) – The number of rounds of the simulation.

Return type

Tuple[List[float], List[float]]

previous

gossipy.node module

next

gossipy.utils