py_ctln

class KnownNetworks:

A helper class for managing requests to use existing lists of known classes of CTLNs. This class allows us to provide these lists without forcing the user to load them all ahead of time, as these lists can get quite large.

Note that this class is not designed to be used directly, but rather a user should access these lists through the CTLN class via CTLN.collections.method_name_here()!

@classmethod
def all_n(cls, n):

A method for obtaining a list of all CTLNs with n nodes.

Parameters
  • n (integer): The number of nodes to obtain all CTLNs for.
Returns
  • Returns the requested list.
Raises
  • ValueError: If the requested list cannot be found.
@classmethod
def core_n(cls, n):

A method for obtaining a list of all CTLNs with n nodes that are core motifs.

Parameters
  • n (integer): The number of nodes to obtain all core CTLNs for.
Returns
  • Returns the requested list.
@classmethod
def strongly_core_n(cls, n):

A method for obtaining a list of all CTLNs with n nodes that are strongly core motifs.

Parameters
  • n (integer): The number of nodes to obtain all core CTLNs for.
Returns
  • Returns the requested list.
class CTLN:

A class used to provide functions for Combinatorial Threshold Linear Network (CTLN) calculations and research.

DEFAULT_EPSILON = 0.51
DEFAULT_DELTA = 1.76
collections = <KnownNetworks object>
@classmethod
def get_w_mat(cls, sA, epsilon=0.51, delta=1.76):

Creates the W matrix from the adjacency matrix.

The W matrix, when constructed from an adjacency matrix, is defined to be a matrix of the same dimensions where: - 0s are replaced by -1-delta - 1s are replaced by -1+epsilon - diagonals are kept as 0 regardless of the above

Parameters
  • sA (array-like): The adjacency matrix to create the W matrix from.
  • epsilon (float, optional): The value to use for the epsilon parameter (default is 0.51).
  • delta (float, optional): The value to use for the delta parameter (default is 1.76).
Returns
  • W (array-like): The constructed W matrix.
@classmethod
def check_fp(cls, sA, sig: list, **kwargs):

Checks if a given subgraph (sigma) is a fixed point support of a given CTLN

Uses the computations from "Predicting neural network dynamics via graphical analysis" by Katherine Morrison and Carina Curto found in Section 2.

This section states that a given sigma is a fixed point support in a CTLN iff: x_sig = ((I-W_sig)^{-1})(b_sig)

This method uses this principle to check a given sigma for a CTLN.

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
  • sig (array-like): The sigma/subgraph of the CTLN to check.
  • b (array-like, optional): The b vector to use. (Defaults to a column of 1s)
  • epsilon (float, optional): The value to use for the epsilon parameter (default is 0.51).
  • delta (float, optional): The value to use for the delta parameter (default is 1.76).
Returns
  • is_fp (bool): A boolean that states whether or not the sigma is a fixed point support of the given CTLN.
  • x_sig (array-like): A column vector representing the firing rate of each neuron in the system in the course of the fixed point.
@classmethod
def check_stability(cls, sA, sig, **kwargs):

Checks whether a given fixed point support (sigma) is a stable fixed point or not (unstable).

A fixed point is stable precisely when all eigenvalues of -I+W_sigma have a negative real part, and are unstable otherwise.

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
  • sig (array-like): The sigma/subgraph of the CTLN for which we want to check the stability of its corresponding fixed point.
  • epsilon (float, optional): The value to use for the epsilon parameter (default is 0.51).
  • delta (float, optional): The value to use for the delta parameter (default is 1.76).
Returns
  • stable (bool): A boolean that states whether or not the fixed point is stable. (True = Stable, False = Unstable)
  • eigvals (array-like): The set of eigenvalues of the matrix -I+W_sig
@classmethod
def get_fp(cls, sA, **kwargs):

A method that finds all of the fixed points, their supports, and their stability for a given CTLN.

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
  • epsilon (float, optional): The value to use for the epsilon parameter (default is 0.51).
  • delta (float, optional): The value to use for the delta parameter (default is 1.76).
Returns
  • fixpts (array-like): The set of all fixed points of the CTLN.
  • stability (array-like): The stability of each fixed point in the CTLN.
  • supports (array-like): The fixed point support for each fixed point in the CTLN.
@classmethod
def threshlin_ode(cls, sA, t, x0, **kwargs):

A method for solving the system of piecewise linear ordinary differential equations to get the firing rates of the neurons over time for a given set of initial conditions

Uses the defined system of ODEs where: (x_i)' = -x_i + [sum_{j=1}^n (W_{ij}x_j + theta)]_{+} for i = 1, ..., n

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
  • t (float): The time period to calculate up to (ie. solve the ode for times in interval [0,t])
  • x0 (array-like): The vector of initial conditions (starting firing rates) for each neuron in the CTLN.
  • b (array-like, optional): Allows the user to set the b vector manually (Defaults to a column of 1s)
  • epsilon (float, optional): The value to use for the epsilon parameter (default is 0.51).
  • delta (float, optional): The value to use for the delta parameter (default is 1.76).
Returns
  • W (array-like): The constructed W matrix
  • b (array-like): The b vector that was used
  • t (float): The t value that was used
  • x0 (array-like): The vector of initial conditions that was used
  • soln_y (list): A list of all of the y values the ODE solved for
  • soln_time (list): A list of all the time values that correspond to the computed values in soln_y
  • sA (array-like): The adjacency matrix that was used.
@classmethod
def get_soln(cls, sA, **kwargs):

A method for obtaining the solution for a CTLN

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
  • theta (int, optional): The value to use for theta (Defaults to 1)
  • t (int, optional): The endpoint of the time interval to calculate (Defaults to 100)
  • x0 (array-like, optional): The initial firing rates of each neuron in the CTLN. ( Defaults to random values between 0 and 0.1)
  • b (array-like, optional): The b vector to use (Defaults to a column of 1s times theta)
  • epsilon (float, optional): The value to use for the epsilon parameter (default is 0.51).
  • delta (float, optional): The value to use for the delta parameter (default is 1.76).
Returns
  • soln (array-like): A list of the returned values from cls.threshlin_ode()
@classmethod
def plot_graph(cls, sA, ax=None, show=True):

A method that plots the graph of the CTLN.

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
  • ax (matplotlib.axes.Axes, optional): The axes to plot the graph on. (Defaults to creating a new one)
  • show (bool, optional): Whether to show the graph after creation. (Defaults to True)
@classmethod
def plot_soln(cls, sA, **kwargs):

A method that plots both the graph and the solution of the CTLN.

(Note: plot_soln and run_ctln_model_script() are identical, they are just aliases of each other for ease of use.)

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
  • epsilon (float, optional): The value to use for the epsilon parameter (default is 0.51).
  • delta (float, optional): The value to use for the delta parameter (default is 1.76).
@classmethod
def run_ctln_model_script(cls, sA, **kwargs):

A method that plots both the graph and the solution of the CTLN.

(Note: plot_soln and run_ctln_model_script() are identical, they are just aliases of each other for ease of use.)

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
  • epsilon (float, optional): The value to use for the epsilon parameter (default is 0.51).
  • delta (float, optional): The value to use for the delta parameter (default is 1.76).
@classmethod
def is_uid(cls, sA):

A method for seeing if a CTLN is uniform in-degree

Checks that all of the row sums are equal

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
Returns
  • bool: True if the CTLN is uniform in-degree, False otherwise
@classmethod
def is_uod(cls, sA):

A method for seeing if a CTLN is uniform out-degree

Checks that all of the column sums are equal

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
Returns
  • bool: True if the CTLN is uniform out-degree, False otherwise
@classmethod
def is_core(cls, sA, **kwargs):

A method for seeing if a CTLN is core.

A core motif is a CTLN that has exactly one fixed point support which includes every node of the graph.

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
  • epsilon (float, optional): The value to use for the epsilon parameter (default is 0.51).
  • delta (float, optional): The value to use for the delta parameter (default is 1.76).
Returns
  • is_core (bool): True if the CTLN is a core motif, False otherwise
@classmethod
def is_permitted(cls, sA, **kwargs):

A method for seeing if a CTLN is permitted.

A permitted motif is a CTLN that has a fixed point support containing every node of the graph (though this support is not necessarily the only one, as in core motifs).

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
  • epsilon (float, optional): The value to use for the epsilon parameter (default is 0.51).
  • delta (float, optional): The value to use for the delta parameter (default is 1.76).
Returns
  • is_permitted (bool): True if the CTLN is a permitted motif, False otherwise
@classmethod
def find_graphical_domination( cls, sA, types_to_look_for=('inside-in', 'outside-in', 'inside-out', 'outside-out')):

A method for finding domination relationships within a CTLN.

This is specific to graphical domination. This is defined such that:

a node k "graphically dominates" a node j with respect to a subgraph sigma in G if

  1. For all i in sigma excluding j and k, if i -> j then i -> k
  2. If j in sigma, then j -> k
  3. If k in sigma, then k -/> j

For determining the type of domination, the following rules hold: if j and k are in sigma: inside-in if j is in sigma but k is not: outside-in if k is in sigma but j is not: inside-out if j and k are not in sigma: outside-out

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
  • types_to_look_for (array-list, optional): A list of the "types" of domination to look for. (Defaults to all possible types, but exists as an option in case user wants to ignore certain types of domination)
Returns
  • all_k (array-like): A list of all the dominator nodes
  • all_j: A list of all the dominated nodes
  • all_sigma: A list of the sigmas that each k dominates j with respect to
  • all_dom_type: A list of the type of domination found for each domination relationship we have
@classmethod
def is_strongly_connected(cls, sA):

A method for determining if a CTLN is strongly connected.

The easiest way to find if a digraph is strongly connected is to use its reachability matrix. This is computed as (sA + I)^n

If this matrix has all positive entries (including the diagonal), then the digraph is strongly connected.

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
Returns
  • True if the CTLN is strongly connected, False otherwise.
@classmethod
def is_weakly_connected(cls, sA):

A method for determining if a CTLN is weakly connected.

The easiest way to find if a digraph is weakly connected is to find the underlying non-directed graph and check if it is connected.

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
Returns
  • True if the CTLN is weakly connected, False otherwise.
@classmethod
def is_connected(cls, sA):

A method for determining if a CTLN is connected.

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
Returns
  • A list of the form (is_weakly_connected, is_strongly_connected)
@classmethod
def is_strongly_core(cls, sA):

A method for determining if a CTLN is strongly core.

A CTLN is strongly core if it is both a core motif and each of it's subgraphs that are not fixed point supports (all but the largest) are ruled out by some form of graphical domination.

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
Returns
  • True if the CTLN is strongly core, False otherwise.
@classmethod
def is_hamiltonian(cls, sA):

A method for determining if a CTLN is hamiltonian (Contains a hamiltonian cycle of size n).

To do this, we get every possible hamiltonian cycle of size n and check if it is found in the adjacency matrix.

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
Returns
  • True if the CTLN is hamiltonian, False otherwise.
  • ham_cycle (array-like): A list of the hamiltonian cycles that were found in the graph.
@classmethod
def get_projection_direction(cls, sA):

A method for generating a random projection direction.

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
Returns
  • direction_vector (array-like): A vector of size n by 2 that gives the two random directions to project onto.
@classmethod
def plot_projection( cls, sA, tstart=40, tstop=80, direction=None, ax=None, show=True, **kwargs):

A method for plotting the projection of the solution onto two dimensions.

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
  • tstart (int, optional): The starting time index for the projection. (Defaults to 40)
  • tstop (int, optional): The stopping time index for the projection. (Defaults to 80)
  • ax (matplotlib.axes.Axes, optional): The axes to plot on. (Defaults to creating a new one)
  • show (bool, optional): Whether to show the graph after creation. (Defaults to True)
  • epsilon (float, optional): The value to use for the epsilon parameter (default is 0.51).
  • delta (float, optional): The value to use for the delta parameter (default is 1.76).
@classmethod
def plot_grayscale(cls, soln, ax):

A method for plotting the solution in grayscale.

Parameters
  • soln (array-like): The solution to plot, as returned by cls.get_soln()
  • ax (matplotlib.axes.Axes): The axes to plot on.
@classmethod
def parallel_run(cls, matrices, method, num_processes=None):

Apply a CTLN class method to a list of matrices in parallel.

This method uses multiprocessing to parallelize operations on multiple adjacency matrices, allowing for efficient batch processing without requiring users to set up parallelization themselves.

Parameters
  • matrices (list): A list of adjacency matrices (array-like) to process.
  • method (callable): A CTLN class method (e.g., CTLN.is_core, CTLN.get_fp, CTLN.is_strongly_connected).
  • num_processes (int, optional): Number of processes to use. If None (default), uses all available CPU cores.
Returns
  • results (list): A list of results from applying the method to each matrix, in the same order as the input matrices.
@classmethod
def is_circulant(cls, sA):

A method for determining if a CTLN is circulant.

A circulant graph is one where there is some ordering of the nodes such that the adjacency matrix is circulant. A circulant matrix is one where each column is a shifted version of the previous column.

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
Returns
  • is_circulant (bool): True if the CTLN is circulant, False otherwise.
  • ordering (array-like): The ordering of the nodes that makes the adjacency matrix circulant
  • forward_edges (array-like): The pattern used for circulant graph notation
@classmethod
def is_clique_union(cls, sA, tau_partition):

A method for determining if a CTLN is a clique union.

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
  • tau_partition (list of lists): A partition of the nodes into subsets.
Returns
  • True if the CTLN is a clique union with respect to the given partition, False otherwise.
@classmethod
def is_directional(cls, sA, omega, tau):

A method for determining if a CTLN is directional with respect to a given omega and tau partition.

Parameters
  • sA (array-like): The adjacency matrix of the CTLN.
  • omega (array-like): A subset of the nodes in the CTLN.
  • tau (array-like): A subset of the nodes in the CTLN, disjoint from omega and together with omega containing all nodes in the CTLN.
Returns
  • directional (bool): True if the CTLN is directional with respect to the given omega and tau, False otherwise
  • sigma_fail (list): If the CTLN is not directional, a list of the nodes in the sigma that fails the directional condition.
@staticmethod
def get_circulant_graph(n, forward_edges):

A method for generating the adjacency matrix of a circulant graph.

Parameters
  • n (int): The number of nodes in the circulant graph.
  • forward_edges (list of ints): A list of the indices of the forward edges in the circulant graph. For example, if forward_edges = [1, 3], then each node i sends to nodes (i+1) mod n and (i+3) mod n.
Returns
  • sA (array-like): The adjacency matrix of the circulant graph.