core.resistive_network

Module contains class ResNetwork.

Provides function for computing resistance based networks. It is subclassed from GeoNetwork and provides most GeoNetwork’s functions/properties.

The class has the following instance variables:

(bool) flagDebug     : flag for debugging mode
(bool) flagComplex   : flag for complex input
(ndarray) resistances: array of resistances (complex or real)

Overriden inherited methods:

(str) __str__          : extended description
(ndarray) get_adjacency: returns complex adjacency if needed

class pyunicorn.core.resistive_network.ResNetwork(resistances, grid=None, adjacency=None, edge_list=None, directed=False, node_weight_type=None, silence_level=2)

Bases: GeoNetwork

A resistive network class

ResNetwork, provides methods for an extended analysis of resistive/resistance-based networks.

Examples:

>>> print(ResNetwork.SmallTestNetwork())
ResNetwork:
GeoNetwork:
Network: undirected, 5 nodes, 5 links, link density 0.500.
Geographical boundaries:
         time     lat     lon
   min    0.0    0.00 -180.00
   max    9.0   90.00  180.00
Average resistance: 2.4

static SmallComplexNetwork()

A test network with complex resistances analogue to SmallTestNetwork()

Return type:

Resistive Network instance

Returns:

an ResNetwork instance with complex resistances

Examples:

>>> res = ResNetwork.SmallComplexNetwork()
>>> isinstance(res, ResNetwork)
True
>>> res.flagComplex
True
>>> adm = res.get_admittance()
>>> print(adm.real)
[[ 0.      0.1     0.      0.      0.    ]
 [ 0.1     0.      0.0625  0.25    0.    ]
 [ 0.      0.0625  0.      0.0625  0.    ]
 [ 0.      0.25    0.0625  0.      0.05  ]
 [ 0.      0.      0.      0.05    0.    ]]

>>> print(adm.imag)
[[ 0.     -0.2     0.      0.      0.    ]
 [-0.2     0.     -0.0625 -0.25    0.    ]
 [ 0.     -0.0625  0.     -0.0625  0.    ]
 [ 0.     -0.25   -0.0625  0.     -0.05  ]
 [ 0.      0.      0.     -0.05    0.    ]]

static SmallTestNetwork()

Create a small test network with unit resistances of the following topology:

0------1--------3------4
        \      /
         \    /
          \  /
           \/
           2

Return type:

Resistive Network instance

Returns:

an ResNetwork instance for testing purposes.

Examples:

>>> res = ResNetwork.SmallTestNetwork()
>>> isinstance(res, ResNetwork)
True

__init__(resistances, grid=None, adjacency=None, edge_list=None, directed=False, node_weight_type=None, silence_level=2)

Initialize an instance of ResNetwork.

Parameters:

• resistances (2D NumPy array) – A matrix with the resistances

• grid (GeoGrid object) – The GeoGrid object describing the network’s spatial embedding.

• adjacency (2D NumPy array (int8) [index, index]) – The network’s adjacency matrix.

• edge_list (array-like list of lists) – Edge list of the new network. Entries [i,0], [i,1] contain the end-nodes of an edge.

• directed (boolean) – Determines, whether the network is treated as directed.

• node_weight_type (string) – The type of geographical node weight to be used.

• silence_level (number (int)) – The inverse level of verbosity of the object.

__str__()

Return a short summary of the resistive network.

admittance_lapacian()

Return the (possibly non-symmetric) dense Laplacian matrix of the admittance.

Return type:

square NumPy matrix [node,node] of

Examples:

>>> print(ResNetwork.SmallTestNetwork().admittance_lapacian())
[[ 0.5   -0.5    0.     0.     0.   ]
 [-0.5    1.125 -0.125 -0.5    0.   ]
 [ 0.    -0.125  0.25  -0.125  0.   ]
 [ 0.    -0.5   -0.125  0.725 -0.1  ]
 [ 0.     0.     0.    -0.1    0.1  ]]
>>> print(type( ResNetwork.SmallTestNetwork().admittance_lapacian() ))
<class 'numpy.ndarray'>

admittive_degree()

admittive degree of the network

The admittive (or effective) degree of the resistive network, which is the counterpart to the traditional degree.

Return type:

1D NumPy array

Examples:

>>> print(ResNetwork.SmallTestNetwork().admittive_degree())
[ 0.5    1.125  0.25   0.725  0.1  ]
>>> print(type( ResNetwork.SmallTestNetwork().admittive_degree() ))
<class 'numpy.ndarray'>

average_effective_resistance()

Return the average effective resistance (<ER>) of the resistive network, the average resistances for all “paths” (connections)

Return type:

float

Examples:

>>> res = ResNetwork.SmallTestNetwork()
>>> print("%.5f" % res.average_effective_resistance())
7.28889
>>> print(type( res.average_effective_resistance() ))
<class 'numpy.float64'>

average_neighbors_admittive_degree()

Average neighbour effective degree

Return type:

1D NumPy array

Examples:

>>> print(ResNetwork.SmallTestNetwork().                average_neighbors_admittive_degree())
[ 2.25  1.31111111  7.4  2.03448276  7.25  ]
>>> print(type(ResNetwork.SmallTestNetwork().admittive_degree()))
<class 'numpy.ndarray'>

diameter_effective_resistance()

Return the diameter (the highest resistance path between any nodes).

Return type:

float

Examples:

>>> res = ResNetwork.SmallTestNetwork()
>>> print("%.3f" % res.diameter_effective_resistance())
Re-computing all effective resistances
14.444
>>> print(type(res.diameter_effective_resistance()))
<class 'numpy.float64'>
>>> res = ResNetwork.SmallTestNetwork()
>>> x = res.average_effective_resistance()
>>> print("%.3f" % res.diameter_effective_resistance())
14.444

edge_current_flow_betweenness()

The electrial version of Newmann’s edge betweeness

Return type:

NumPy float

Examples:

>>> res = ResNetwork.SmallTestNetwork()
>>> print(r(res.edge_current_flow_betweenness()))
[[ 0.      0.4     0.      0.      0.    ]
 [ 0.4     0.      0.2444  0.5333  0.    ]
 [ 0.      0.2444  0.      0.2444  0.    ]
 [ 0.      0.5333  0.2444  0.      0.4   ]
 [ 0.      0.      0.      0.4     0.    ]]
>>> # update to unit resistances
>>> res.update_resistances(res.adjacency)
>>> print(r(res.edge_current_flow_betweenness()))
[[ 0.      0.4     0.      0.      0.    ]
 [ 0.4     0.      0.3333  0.4     0.    ]
 [ 0.      0.3333  0.      0.3333  0.    ]
 [ 0.      0.4     0.3333  0.      0.4   ]
 [ 0.      0.      0.      0.4     0.    ]]

effective_resistance(a, b)

Return the effective resistance (ER) between two nodes a and b. The ER is the electrical analogue to the shortest path where a is considered as “source” and b as the “sink”

Parameters:

• a (int) – index of the “source” node

• b (int) – index of the “sink” node

Return type:

NumPy float

Examples:

>>> res = ResNetwork.SmallTestNetwork()
>>> print(res.effective_resistance(1,1))
0.0
>>> print(type( res.effective_resistance(1,1) ))
<class 'float'>
>>> print("%.3f" % res.effective_resistance(1,2))
4.444
>>> print(type( res.effective_resistance(1,1) ))
<class 'float'>

effective_resistance_closeness_centrality(a)

The effective resistance closeness centrality (ERCC) of node a

Parameters:

a (int) – index of the “source” node

Return type:

NumPy float

Examples:

>>> res = ResNetwork.SmallTestNetwork()
>>> print("%.3f" % res.effective_resistance_closeness_centrality(0))
0.154
>>> print("%.3f" % res.effective_resistance_closeness_centrality(4))
0.080

get_R()

Return the pseudo inverse of of the admittance Laplacian

The pseudoinverse is used of the novel betweeness measures such as vertex_current_flow_betweenness() and edge_current_flow_betweenness() It is computed on instantiation and on change of the resistances/admittance

Returns:

the pseudoinverse of the admittange Laplacian

Return type:

ndarray (float)

Examples:

>>> res = ResNetwork.SmallTestNetwork();print(res.get_R())
[[ 2.28444444  0.68444444 -0.56       -0.20444444 -2.20444444]
 [ 0.68444444  1.08444444 -0.16        0.19555556 -1.80444444]
 [-0.56       -0.16        3.04       -0.16       -2.16      ]
 [-0.20444444  0.19555556 -0.16        1.08444444 -0.91555556]
 [-2.20444444 -1.80444444 -2.16       -0.91555556  7.08444444]]

get_admittance()

Return the (possibly non-symmetric) dense admittance matrix

Return type:

square NumPy matrix [node,node] of ints

Examples:

>>> res = ResNetwork.SmallTestNetwork();print(res.get_admittance())
[[ 0.     0.5    0.     0.     0.   ]
 [ 0.5    0.     0.125  0.5    0.   ]
 [ 0.     0.125  0.     0.125  0.   ]
 [ 0.     0.5    0.125  0.     0.1  ]
 [ 0.     0.     0.     0.1    0.   ]]
>>> print(type( res.get_admittance() ))
<class 'numpy.ndarray'>

global_admittive_clustering()

Return node wise admittive clustering coefficient.

Return type:

NumPy float

Examples:

>>> res =  ResNetwork.SmallTestNetwork()
>>> print("%.3f" % res.global_admittive_clustering())
0.016
>>> print(type(res.global_admittive_clustering()))
<class 'numpy.float64'>

local_admittive_clustering()

Return node wise admittive clustering coefficient (AC).

The AC is the electrical analogue of the clustering coefficient for regular network (see get_admittive_ws_clustering() and get_local_clustering() and sometimes called Effective Clustering (EC))

The admittive clustering (\(ac\)) of node \(i\) is defined as:

\[\text{ac}_i = \frac {\sum_{j,k}^N\alpha_{i,j},\alpha_{i,k},\alpha_{j,k}} {\text{ad}_i(\text{d}_i-1)}\]

where

• \(\alpha\) is the admittance matrix

• \(ad_i\) is the admittive degree of the node \(i\)

• \(d_i\) is the degree of the node \(i\)

Return type:

1d NumPy array (float)

Examples:

>>> res =  ResNetwork.SmallTestNetwork()
>>> print(res.local_admittive_clustering())
[ 0.  0.00694444  0.0625  0.01077586  0. ]
>>> print(type(res.local_admittive_clustering()))
<class 'numpy.ndarray'>

update_R()

Updates R, the pseudo inverse of the admittance Laplacian

This function is run, whenever the admittance is changed.

Return type:

none

Examples:

>>> res = ResNetwork.SmallTestNetwork();print(res.get_admittance())
[[ 0.     0.5    0.     0.     0.   ]
 [ 0.5    0.     0.125  0.5    0.   ]
 [ 0.     0.125  0.     0.125  0.   ]
 [ 0.     0.5    0.125  0.     0.1  ]
 [ 0.     0.     0.     0.1    0.   ]]
>>> print(type( res.get_admittance() ))
<class 'numpy.ndarray'>

update_admittance()

Updates admittance matrix which is inverse the resistances

Return type:

none

Examples:

>>> res = ResNetwork.SmallTestNetwork();print(res.get_admittance())
[[ 0.     0.5    0.     0.     0.   ]
 [ 0.5    0.     0.125  0.5    0.   ]
 [ 0.     0.125  0.     0.125  0.   ]
 [ 0.     0.5    0.125  0.     0.1  ]
 [ 0.     0.     0.     0.1    0.   ]]
>>> print(type(res.get_admittance()))
<class 'numpy.ndarray'>

update_resistances(resistances)

Update the resistance matrix

This function is called to changed the resistance matrix. It sets the property and the calls the update_admittance() and update_R() functions.

Return type:

None

Examples:

>>> # test network with given resistances
>>> res = ResNetwork.SmallTestNetwork()
>>> print(res.resistances)
[[ 0  2  0  0  0]
 [ 2  0  8  2  0]
 [ 0  8  0  8  0]
 [ 0  2  8  0 10]
 [ 0  0  0 10  0]]
>>> # print admittance and admittance Laplacian
>>> print(res.get_admittance())
[[ 0.     0.5    0.     0.     0.   ]
 [ 0.5    0.     0.125  0.5    0.   ]
 [ 0.     0.125  0.     0.125  0.   ]
 [ 0.     0.5    0.125  0.     0.1  ]
 [ 0.     0.     0.     0.1    0.   ]]
>>> print(res.admittance_lapacian())
[[ 0.5   -0.5    0.     0.     0.   ]
 [-0.5    1.125 -0.125 -0.5    0.   ]
 [ 0.    -0.125  0.25  -0.125  0.   ]
 [ 0.    -0.5   -0.125  0.725 -0.1  ]
 [ 0.     0.     0.    -0.1    0.1  ]]
>>> # now update to unit resistance
>>> res.update_resistances(res.adjacency)
>>> # and check new admittance/admittance Laplacian
>>> print(res.get_admittance())
[[ 0.  1.  0.  0.  0.]
 [ 1.  0.  1.  1.  0.]
 [ 0.  1.  0.  1.  0.]
 [ 0.  1.  1.  0.  1.]
 [ 0.  0.  0.  1.  0.]]
>>> print(res.admittance_lapacian())
[[ 1. -1.  0.  0.  0.]
 [-1.  3. -1. -1.  0.]
 [ 0. -1.  2. -1.  0.]
 [ 0. -1. -1.  3. -1.]
 [ 0.  0.  0. -1.  1.]]

vertex_current_flow_betweenness(i)

Vertex Current Flow Betweeness (VCFB) of a node i.

The electrial version of Newmann’s node betweeness is here defined as the Vertex Current Flow Betweeness (VCGB) of a node

\[VCFB_i := \frac{ 2 }{ n \left( n-1 \right)} \sum_{s<t} I_i^{st}\]

where

\[\begin{split}I_i^{st} &= \frac{1}{2}\sum_{j} \Gamma_{i,j} | V_i - V_j |\\ &= \frac{1}{2}\sum_{j} \Gamma_{i,j} | I_s(R_{i,s}-R_{j,s}) + I_t(R_{j,t}-R_{i,t}) |\end{split}\]

and further:

• \(I_{s}^{st} := I_{s}\)

• \(I_{t}^{st} := I_{t}\)

• \(\Gamma\) is the admittance matrix

• \(R\) is the pseudoinverse of the admittance Laplacian

Parameters:

a (int) – index of the “source” node

Return type:

NumPy float

Examples:

>>> res = ResNetwork.SmallTestNetwork()
>>> print("%.3f" % res.vertex_current_flow_betweenness(1))
0.389
>>> print("%.3f" % res.vertex_current_flow_betweenness(2))
0.044