Python: module NBRW

NBRW | index /Users/mwshumway/Documents/NBW/src/NBRW/NBRW.py

`NBRW.py: A Python package for Non-Backtracking Random Walks on networks.
Matthew Shumway, 2024.
Work in conjunction with Adam Knudson, Dr. Mark Kempton, and Dr. Jane Breen.
This package is a Python implementation of the Non-Backtracking Random Walks (NBRW) on networks. It is designed
to be used with SageMath, a Python-based open-source mathematics software system. The package is designed to be used in
both research and applications of NBRW. It contains a NBRW class, which is designed to compute and store various attributes
associated to NBRW and Kemeny's constant.`

Modules
`` |  |
numpy | matplotlib.pyplot |  |

Classes
`` |  | builtins.object NBRW
class NBRW(builtins.object)
`` | `NBRW(G, pinwheel: bool = False) -&gt; None A class for Non-Backtracking Random Walks on networks. Accepts as input a SageMath graph object. Attributes: ----------------BASIC ATTRIBUTES OF GRAPH---------------- G (Graph) : SageMath graph object m (int) : number of edges in G n (int) : number of vertices in G A (np.ndarray) : adjacency matrix of G edges_list (list) : list of edges in G S (np.ndarray) : endpoint incidence operator T (np.ndarray) : starting point incidence operator tau (np.ndarray) : edge reversal operator C (np.ndarray) : S @ T B (np.ndarray) : C - tau ---------------DEGREE MATRICES------------------------- D (np.ndarray) : diagonal matrix of vertex degrees D_inv (np.ndarray) : inverse of D De (np.ndarray) : diagonal matrix of edge degrees De_inv (np.ndarray) : inverse of De -----------------STATIONARY DISTRIBUTIONS---------------- pi (np.ndarray) : stationary distribution in vertex space pi_e (np.ndarray) : stationary distribution in edge space Wnb (np.ndarray) : 1/(2m) J matrix in edge space - each row is NB edge space stationary distribution Wv (np.ndarray) : matrix whose rows are SRW vertex space stationary distribution We (np.ndarray) : matrix whose rows are SRW edge space stationary distribution -----------------TRANSITION MATRICES--------------------- Pnb (np.ndarray) : non-backtracking transition matrix P (np.ndarray) : SRW transition matrix in vertex space Pe (np.ndarray) : SRW transition matrix in edge space -----------------FUNDAMENTAL MATRICES--------------------- Znb (np.ndarray) : NBW analogue to the fundamental matrix in SRW Znb_e (np.ndarray) : NBW analogue to the fundamental matrix in SRW in edge space Z (np.ndarray) : fundamental matrix in vertex space Z_e (np.ndarray) : fundamental matrix in edge space -----------------HITTING AND RETURN TIME MATRICES--------------------- M (np.ndarray) : helper matrix used to compute Mnb -- from Dario paper Mev (np.ndarray) : matrix of hitting times from edge to vertex Mnb (np.ndarray) : matrix of hitting times in vertex space Mnb_e (np.ndarray) : matrix of hitting times in edge space Mv (np.ndarray) : matrix of mean first passage times in vertex space M_e (np.ndarray) : matrix of mean first passage times in edge space R_e (np.ndarray) : diagonal mean return time matrix in edge space R (np.ndarray) : diagonal mean return time matrix in vertex space -----------------KEMENY'S CONSTANTS--------------------- Kv (float) : Kemeny's constant in vertex space Ke (float) : Kemeny's constant in edge space Knb_e (float) : NB Kemeny's constant in edge space Knb_v_trace (float) : NB Kemeny's constant in vertex space using trace of Znb Knb_v_mfpt (float) : NB Kemeny's constant in vertex space using pi @ Mnb @ pi Knb_v_sub (float) : NB Kemeny's constant in vertex space using edge space Kemeny's constant`
| Methods defined here: De_matrix(self) -> numpy.ndarray `Computes the diagonal matrix of edge degrees, De. De is a (2m x 2m) matrix. Computational Complexity - O(m). Spatial Complexity - O(m^2).` M_ev_matrix(self) -> numpy.ndarray `Computes the matrix M_{ev}, which is a (2m x n) matrix. This is the matrix of hitting times from edge e to vertex v. Computational Complexity - O(nm). Spatial Complexity - O(mn).` M_matrix(self) -> numpy.ndarray `Found in (4.4) of the Dario hitting times paper. M is a (n x n) matrix. Startpoint incident operator T divided by row sums of T. Used to calculate Mnb_v. Computational Complexity - O(nm). Spatial Complexity - O(nm).` Mnb_e_matrix(self) -> numpy.ndarray `Computes the matrix Mnb_e, which is a (2m x 2m) matrix. This is the matrix of hitting times in the edge space. Computational Complexity - O(nm). Spatial Complexity - O(m^2).` Mnb_matrix(self) -> numpy.ndarray `Computes the matrix Mv_nb, which is a (n x n) matrix. This is the matrix of hitting times in the vertex space. Computational Complexity - O(nm). Spatial Complexity - O(n^2).` S_matrix(self) -> numpy.ndarray `Computes the endpoint incidence operator, S, of the graph G. S is a (2m x n) matrix. Computational Complexity - O(m). Spatial Complexity - O(mn).` T_matrix(self) -> numpy.ndarray `Computes the starting point incidence operator, T, of the graph G. T is a (n x 2m) matrix. Computational Complexity - O(m). Spatial Complexity - O(mn).` __init__(self, G, pinwheel: bool = False) -> None `Initializes the NBRW class with a Sage"Math graph object. Stores all relevant attributes of the NBRW.` alpha_matrix(self) -> numpy.ndarray `Computes the Diag(Alpha) matrix, which is a (n x n) matrix. This is the matrix from the Dario paper.` beta_vector(self, mat) -> numpy.ndarray `Computes the Beta vector, which is a (n x 1) vector. This is the vector from the Dario paper.` fund_matrix(self, P, W) -> numpy.ndarray `Computes the fundamental matrix. Works for either the edge space or the vertex space. Computational Complexity - depends on np.linalg.inv. Spatial Complexity - O(m^2) or O(n^2).` italian_mfpt(self, alpha, beta) `Computes the NB vertex mean first passage times (Mv_nb) from methods in the Italian paper.` mfpt_matrix(self, size, Z, W) -> numpy.ndarray `Computes the square matrix of mean first passage times in the SRW. Can handle both vertex and edge spaces. This procedure is adapted from well known results, but is made explicit in Hunter, Jeffrey J. "The computation of the mean first passage times for Markov chains." Linear Algebra and its Applications 549 (2018): 100-122. Computational Complexity - dependent on numpy functions. Spatial Complexity - either O(m^3) or O(n^3).` mrt_nbrw_matrix(self) -> numpy.ndarray `Computes the diagonal mean return time matrix, which is size (n x n). Should agree with the SRW. Equations taken from (4.8) in the Dario paper. Computational Complexity - O(nm^2). Spatial Complexity - O(n^2).` nb_fund_mat(self, i: int) -> numpy.ndarray `Compute (I-Q)^-1 where Q = Pnb_{i,i} is Pnb with deleted cols/rows i. Computational Complexity - depends on np.linalg.inv. Spatial Complexity - O(m^2).` nb_hitting_times(self, j: int) -> numpy.ndarray `Compute the NB hitting times from edge e to vertex j. This implementation is based on Theorem 4.3 in the Dario paper. Resulting vector is a column of M_{ev}. Computational Complexity - depends on the np.linalg.solve() function. Spatial Complexity - O(m).` nb_trans_matrix(self) -> numpy.ndarray `Computes the non-backtracking transition matrix, Pnb, of the graph G. Pnb is a (2m x 2m) matrix. Computational Complexity - dependent on numpy implementation. Spatial Complexity - O(m^2).` show(self) -> None `Displays the graph G` tau_matrix(self) -> numpy.ndarray `Computes the edge reversal operator, tau. tau is a (2m x 2m) matrix. Computational Complexity - determined by numpy -- update later from documentation. Spatial Complexity - O(m^2).` znb_matrix(self) -> numpy.ndarray `Computes what we call the Znb matrix, which is a (n x n) matrix. This is the NBW analogue to the fundamental matrix in the SRW case. Computational Complexity - O(nm^2), or larger as determined by numpy implementation. Spatial Complexity - O(n^2).` Data descriptors defined here: __dict__ `dictionary for instance variables (if defined)` __weakref__ `list of weak references to the object (if defined)`