Percolate: Perform bond percolation

class epydemic.Percolate

A process that bond percolates a network with a given occupation probability. This can be used independently as a basis for percolation experiments, or as a precursor to other processes that need to run on a percolated network.

The default behaviour is that edges left unoccupied by the percolation process are removed, with the set of nodes being left unaffected. This can be overridden by sub-classes.

Note that the percolation process defines no events: it performs percolation during the build() method.

Using percolation

One can use percolation as an end in itself: percolation is often used as a substitute for spidemic simulation, following the well-known similarity between the contact network arising from epidemic infection and the edges occupied by bond percolation.

A different usage comes when percolating a network prior to (or possibly after) some other process being run. This takes a base network and runs a percolation process on it first, before running another process on the remaining (“residual”) network. The cleanest way to structure this sort of code is to use a ProcessSequence with an instance of Percolate followed by the process for the residual network. This will run the Process.build() methods in order, percolating the base network before building the second process’ structures.

Percolation

The probability that an edge is retained is given by an experimental parameter.

Percolate.T: Final[str] = 'epydemic.percolate.T'

Experimental parameter for the occupation probability of an edge.

Given this, the percolation process itself simply registers edges as either occupied or unoccupied. It then executes an action for each of these sets.

Percolate.percolate(T)

Percolate the network. Edges are retained (“occupied”) with probability \(T\), with other edges being “unoccupied” with probability \((1 - T)\). The edges are divided into two sets based on occupation, and then passed to the corresponding action method: Percolation.occupy() for the occupied edges and Percolation.unoccupy() for the unoccupied edges. (These two methods are called in that order, which may be important for sub-classes that need to, for example, examine or manipulate the network before Percolation.unoccupy() removes the unoccupied edges..)

The implementation of the percolation process borrows heavily from the Newman-Ziff approach, whereby the set of edges is shuffled and the leading fraction \(T\) is treated as occupied. This is considerably faster than performing a random choice per edge.

Parameters:

params – the experimental parameters

Actions

The actions of percolation concern what to do with the occupied and unoccupied edges.

Percolate.occupy(occupied)

Handle the edges that are marked as occupied by the percolation process. The edges are presented in the order in which they were occupied. The default does nothing.

Parameters:

occupied (List[Tuple[Any, Any]]) – the occupied edges

Percolate.unoccupy(unoccupied)

Handle the edges left unoccupied by the percolation process. The edges are presented in the order in which they were left unoccupied. The default removes the unoccupied edges from the process’ network, leaving the nodes unchanged.

Parameters:

unoccupied (List[Tuple[Any, Any]]) – the unoccupied edges

Building

Percolate.build(params)

Percolate the network.

Parameters:

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