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, Mark Kempton, and Jane Breen.
This package is a Python implementation of a Non-Backtracking Random Walk (NBRW) on networks. It is designed
to be used with SageMath, a Python-based open-source mathematics software system. It contains a NBRW class, which is designed to compute and store various attributes
associated to NBRW and Kemeny's constant. It also contains a few extra graph families.
It will not work without the SageMath module installed. If you do not have SageMath, you can download it from here.
To view the source code of this project, click here.
`

Installation Guide
`` |  | To download the NBRW package, enter the following command in your sage terminal: `pip install NBRW==0.1.5` After this, you will need to restart your terminal. OR Enter the following command into a Jupyter Notebook cell: `!pip install NBRW==0.1.5` To stay current with latest updates, visit PyPI.

Example Usage
`` |  | This section shows the proper way to import the module into a Jupyter Notebook (or Sage terminal) and some basic usage of the NBRW class. For a complete list of the methods and attributes of the NBRW class, see 'Classes' below. `sage: from nbrw import NBRW sage: from sage.all import * sage: g = graphs.PetersenGraph() sage: G = NBRW(g) sage: G.G.is_edge_transitive() True sage: G.Knb_v_mfpt 6.3 sage: G.pi.T @ G.Mnb @ G.pi == G.Knb_v_mfpt True sage: np.allclose(G.Mnb_e @ G.S, G.Pnb @ G.Mnb_e @ G.T.T) True sage: np.allclose(G.M_e @ G.S, G.Pe @ G.M_e @ G.T.T) True` There is also an 'extra_graphs' file located within the nbrw module. This file contains a few extra graphs that are not built into SageMath. It includes implemented Necklace, Cycle Barbell, and Pinwheel Graphs. To use them, follow the examples below: `sage: from nbrw import extra_graphs as exg sage: N = exg.necklace(5) # necklace graph with 5 beads sage: C = exg.cycle_barbell(k=2, a=5, b=6) # cycle barbell with 2-path, 5-cycle and a 6-cycle sage: P = exg.pinwheel([3, 4, 5]) # pinwheel graph with 3 spokes of 3-, 4-, and 5- cycles`

Suggestions, Issues, etc.
`` |  | If you have any suggestions, issues, or questions, please submit a 'New Issue' on the GitHub repository. Alternatively, you can just tell me in person or reach me through email at mwshumway7@gmail.com.

Modules Used
`` |  |
numpy | matplotlib.pyplot | sagemath |  |

Classes
`` |  | NBRW
class NBRW()
`` | `NBRW(G: Graph, pinwheel: bool = False) -> 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) : NBW transition matrix in edge space 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 fundamental matrix 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 Fasino paper Mev (np.ndarray) : matrix of NBW hitting times from edge to vertex Mnb (np.ndarray) : matrix of NBW hitting times in vertex space Mnb_e (np.ndarray) : matrix of NBW hitting times in edge space Mv (np.ndarray) : matrix of SRW hitting times in vertex space M_e (np.ndarray) : matrix of SRW hitting 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 subtracting (2m-n) from edge Kemeny's`
`` | 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 Fasino 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 Fasino 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 Fasino 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 Fasino 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 Fasino 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).`

Functions (located in extra_graphs)
`` |  | cycle_barbell(k: int, a: int, b: int) -> Graph `Path on k vertices, the end two are shared with a cycle of size a and a cycle of size b so |V(G)| = a + b + k - 2` necklace(k: int) -> Graph `|V| = n = 4k + 2 k is number of beads (including the first and last bead, which are different) Needs k >= 2` pinwheel(cycle_sizes: list[int]) -> Graph `Accepts a list of integers called cycle_sizes, which will determine the number of cycles and also their size.`

Resources Used
`` |  | Fasino, Dario, Arianna Tonetto, and Francesco Tudisco. "Hitting times for second-order random walks." European Journal of Applied Mathematics 34.4 (2023): 642-666. Hunter, Jeffrey J. "The computation of the mean first passage times for Markov chains." Linear Algebra and its Applications 549 (2018): 100-122. *Add more resources on a later iteration*