NetworkExperiment: An experiment over a network

class epydemic.NetworkExperiment(g=None)

Bases: Experiment

A very lightweight base class for providing a network to an experiment. The network can either be a fixed network used for each experimental run, or a network generator that will be used to generate a new instance for each run.

The experiment also provides the interface for Event taps, allowing external code to tap-into the changes the experiment makes to the network. Sub-classes need to insert calls to this interface as appropriate, notably around the main body of the simulation and at each significant change.

Parameters:

g (Union[Graph, NetworkGenerator]) – (optional) prototype network or network generator

In use

NetworkExperiment simply adds functions to associate a network or a network generator with a computational experiment.

NetworkExperiment.network()

Return the network this dynamics is running over. This will return None unless we’re actually running a simulation.

Return type:

Graph

Returns:

the network

NetworkExperiment.setNetworkGenerator(g)

Set the network or generator for the networks the dynamics will run over. If a network is supplied rather than a generator it will be treated as an instance of FixedNetwork.

Note that calling this method doesn’t change the working network mid-experiment: for that, use NetworkExperiment.setNetwork().

Parameters:

g (Union[Graph, NetworkGenerator]) – network or network generator

NetworkExperiment.networkGenerator()

Return the generator used for this dynamics.

Return type:

NetworkGenerator

Returns:

the generator

During set-up the experiment instantiates a working copy network for use within the experiment, deleting it afterwards. If the experiment was provided with a single “prototype” network, whis is copied each time; if it was provided with an instance of NetworkGenerator, a new instance of the class of networks defined by the generator is used.

NetworkExperiment.setUp(params)

Set up the experiment for a run. This creates a working copy of the network (class) underlying the experiment.

Parameters:

params (Dict[str, Any]) – the experimental parameters

Event taps

Whenever the network changes, there is an opportunity for the experiment to log it or take some other action. We refer to this as the event tap, as it captures the entire stream of events regardless of how they are defined. See Event taps for a discussion.

To use the event tap interface, you need to override these methods (they all have empty defaults) and ensure that they’re called from the right places.

NetworkExperiment.eventFired(t, p, name, e)

Respond to the occurrance of the given event. The method is passed the simulation time, originating process, event name, and the element affected – and isn’t passed the event function, which is used elsewhere. p will be None if the event is not associated with a Process instance.

This method is called in the past tense, after the event has happened. This lets the effects of the event be observed from within the tap.

The event name is simply the optional name to differentiate between different kinds of event. When used from Dynamics, event names are generated automatically from the names associated with event handlers when they are defined in the corresponding Process, using Process.addEventPerElement() or Process.addFixedRateEvent().

The default does nothing. It can be overridden by sub-classes to provide event-level logging or other functions.

Parameters:

  • t (float) – the simulation time

  • p (Process) – the process firing the event

  • name (str) – the event name

  • e (Union[Any, Tuple[Any, Any]]) – the element

There are three other methods that are called within the core of the experiment to set up and manage the event tap.

NetworkExperiment.initialiseEventTaps()

Initialise the event tap sub-system, which allows external code access to the event stream of the simulation as it runs.

The default does nothing.

NetworkExperiment.simulationStarted(params)

Called when the simulation has been configured and set up, any processes built, and is ready to run.

The default does nothing.

Parameters:

params (Dict[str, Any]) – the experimental parameters

NetworkExperiment.simulationEnded(res)

Called when the simulation has stopped, immediately before tear-down.

The default does nothing.

Parameters:

res (Union[Dict[str, Any], List[Dict[str, Any]]]) – the experimental results

This is simply an interface definition: all the default implementations are empty. To use the event taps you need to override these methods for every experiment. The methods should be called as follows: