Boolean Network

Created on Wed Aug 13 11:08:44 2025

@author: Benjamin Coberly, Claus Kadelka

class boolforge.boolean_network.BooleanNetwork(F: list | ndarray, I: list | ndarray, variables: list | array | None = None)[source]

Bases: object

A class representing a Boolean network with N variables.

Constructor Parameters:

  • F (list | np.ndarray): A list of N Boolean functions, or of N lists of length 2^n representing the outputs of a Boolean function with n inputs.

  • I (list | np.ndarray): A list of N lists representing the regulators (or inputs) for each Boolean function.

  • variables (list | np.array, optional): A list of N strings representing the names of each variable, default = None.

Members:

  • F (list): As passed by the constructor.

  • I (list): As passed by the constructor.

  • variables (np.array): As passed by the constructor.

  • N (int): The number of variables in the Boolean network.

to_cana() → cana.boolean_network.BooleanNetwork[source]

Compatability method:

Returns an instance of the class cana.BooleanNetwork from the cana module.

Returns:

  • An instance of cana.boolean_network.BooleanNetwork

to_bnet() → str[source]

Compatability method:

Returns a bnet object from the pyboolnet module.

Returns:

  • A string describing a bnet from the pyboolnet module.

get_outdegrees() → array[source]

Returns the outdegree of each node.

Returns:

  • np.array: Outdegree of each node.

update_single_node(index: int, states_regulators: list | array) → int[source]

Update the state of a single node.

The new state is obtained by applying the Boolean function f to the states of its regulators. The regulator states are converted to a decimal index using utils.bin2dec.

Parameters:

  • index (int): The index of the Boolean Function in F.

  • states_regulators (list | np.array): Binary vector representing the states of the node’s regulators.

Returns:

  • int: Updated state of the node (0 or 1).

update_network_synchronously(X: list | array) → array[source]

Perform a synchronous update of a Boolean network.

Each node’s new state is determined by applying its Boolean function to the current states of its regulators.

Parameters:

  • X (list | np.array): Current state vector of the network.

Returns:

  • np.array: New state vector after the update.

update_network_synchronously_many_times(X: list | array, n_steps: int) → array[source]

Update the state of a Boolean network sychronously multiple time steps.

Starting from the initial state, the network is updated synchronously n_steps times using the update_network_synchronously function.

Parameters:

  • X (list | np.array): Initial state vector of the network.

  • n_steps (int): Number of update iterations to perform.

Returns:

  • np.array: Final state vector after n_steps updates.

update_network_SDDS(X: list | array, P: array, *, rng=None) → array[source]

Perform a stochastic update (SDDS) on a Boolean network.

For each node, the next state is computed as nextstep = F[i] evaluated on the current states of its regulators. If nextstep > X[i], the node is activated with probability P[i,0]; if nextstep < X[i], the node is degraded with probability P[i,1]. Otherwise, the state remains unchanged.

Parameters:

  • X (list | np.array): Current state vector.

  • P (np.array): A len(F)×2 array of probabilities; for each node i, P[i,0] is the activation probability, and P[i,1] is the degradation probability.

Returns:

  • np.array: Updated state vector after applying the stochastic update.

get_steady_states_asynchronous(nsim: int = 500, EXACT: bool = False, initial_sample_points: list = [], search_depth: int = 50, DEBUG: bool = False, *, rng=None) → dict[source]

Compute the steady states of a Boolean network under asynchronous updates.

This function simulates asynchronous updates of a Boolean network (with N nodes) for a given number of initial conditions (nsim). For each initial state, the network is updated asynchronously until a steady state (or attractor) is reached or until a maximum search depth is exceeded. The simulation can be performed either approximately (by sampling nsim random initial conditions) or exactly (by iterating over the entire state space when EXACT=True).

Parameters:

  • nsim (int, optional): Number of initial conditions to simulate (default is 500).

  • EXACT (bool, optional): If True, iterate over the entire state space and guarantee finding all steady states (2^N initial conditions); otherwise, use nsim random initial conditions. (Default is False.)

  • initial_sample_points (list, optional): List of initial states (as binary vectors) to use. If provided and EXACT is False, these override random sampling.

  • search_depth (int, optional): Maximum number of asynchronous update iterations to attempt per simulation.

  • DEBUG (bool, optional): If True, print debugging information during simulation.

Returns:

  • dict: A dictionary containing:

    • SteadyStates (list): List of steady state values (in decimal form) found.

    • NumberOfSteadyStates (int): Total number of unique steady states.

    • BasinSizes (list): List of counts showing how many initial conditions converged to each steady state.

    • SteadyStateDict (dict): Dictionary mapping a steady state (in decimal) to its index in the steady_states list.

    • FunctionTransitionDict (dict): Dictionary caching state transitions. Keys are tuples (xdec, i) and values are the updated state.

    • InitialSamplePoints (list): The list of initial sample points used (if provided) or those generated during simulation.

get_steady_states_asynchronous_given_one_initial_condition(nsim: int = 500, stochastic_weights: list = [], initial_condition: int | list | array = 0, search_depth: int = 50, DEBUG: bool = False, *, rng=None) → dict[source]

Determine the steady states reachable from one initial condition using weighted asynchronous updates.

This function is similar to steady_states_asynchronous_given_one_IC but allows the update order to be influenced by provided stochastic weights (one per node). A weight vector (of length N) may be provided, and if given, it is normalized and used to bias the random permutation of node update order.

Parameters:

  • nsim (int, optional): Number of simulation runs (default is 500).

  • stochastic_weights (list, optional): List of stochastic weights (one per node) used to bias update order. If empty, uniform random order is used.

  • initial_condition (int | list | np.array, optional): The initial state for all simulations. If an integer, it is converted to a binary vector. Default is 0.

  • search_depth (int, optional): Maximum number of asynchronous update iterations per simulation (default is 50).

  • DEBUG (bool, optional): If True, print debugging information (default is False).

Returns:

  • dict: A dictionary containing:

    • SteadyStates (list): List of steady state values (in decimal form) reached.

    • NumberOfSteadyStates (int): Total number of unique steady states.

    • BasinSizes (list): List of counts of how many simulations reached each steady state.

    • TransientTimes (list): List of lists with transient times (number of updates) for each steady state.

    • SteadyStateDict (dict): Dictionary mapping a steady state (in decimal) to its index.

    • FunctionTransitionDict (dict): Dictionary caching computed state transitions.

    • UpdateQueues (list): List of state update queues (the sequence of states encountered) for each simulation.

get_attractors_synchronous(nsim: int = 500, initial_sample_points: list = [], n_steps_timeout: int = 100000, INITIAL_SAMPLE_POINTS_AS_BINARY_VECTORS: bool = True, *, rng=None) → dict[source]

Compute the number of attractors in a Boolean network using an alternative (v2) approach.

This version is optimized for networks with longer average path lengths. For each of nb initial conditions, the network is updated synchronously until an attractor is reached or until n_steps_timeout is exceeded. The function returns the attractors found, their basin sizes, a mapping of states to attractors, the set of initial sample points used, the explored state space, and the number of simulations that timed out.

Parameters:

  • nsim (int, optional): Number of initial conditions to simulate (default is 500). Ignored if ‘initial_sample_points’ are provided.

  • initial_sample_points (list, optional): List of initial states (in decimal) to use.

  • n_steps_timeout (int, optional): Maximum number of update steps allowed per simulation (default 100000).

  • INITIAL_SAMPLE_POINTS_AS_BINARY_VECTORS (bool, optional): If True, initial_sample_points are provided as binary vectors; if False, they are given as decimal numbers. Default is True.

Returns:

  • dict: A dictionary containing:

    • Attractors (list): List of attractors (each as a list of states in the attractor cycle).

    • NumberOfAttractors (int): Total number of unique attractors found. This is a lower bound.

    • BasinSizes (list): List of counts for each attractor. This is an unbiased estimator.

    • AttractorDict (dict): Dictionary mapping states (in decimal) to the index of their attractor.

    • InitialSamplePoints (list): The initial sample points used (if provided, they are returned; otherwise, the ‘nsim’ generated points are returned).

    • StateSpace (list): Sample of the state transition graph (for ‘InitialSamplePoints’), with each state represented as a decimal.

    • NumberOfTimeouts (int): Number of simulations that timed out before reaching an attractor.

get_attractors_synchronous_exact(RETURN_STG_DICT: bool = False) → dict[source]

Compute the exact number of attractors in a Boolean network using a fast, vectorized approach.

This function computes the state of each node for all 2^N states by constructing the network’s state space, then maps each state to its corresponding successor state via the Boolean functions F. Attractors and their basin sizes are then determined by iterating over the entire state space.

Parameters:

  • RETURN_STG_DICT (bool, optional): If True, the state space is returned as a dictionary, in which each state is associated by its decimal representation.

Returns:

  • dict: A dictionary containing:

    • Attractors (list): List of attractors (each attractor is represented as a list of states forming the cycle).

    • NumberOfAttractors (int): Total number of unique attractors.

    • BasinSizes (list): List of counts for each attractor.

    • AttractorDict (dict): Dictionary mapping each state (in decimal) to its attractor index.

    • STG (np.array): The state transition graph (of shape (2^N, N)).

    • STGDict (dict, only returned if RETURN_DICTF==True): The state transition graph as dictionary, with each state represented by its decimal representation.

get_essential_network() → BooleanNetwork[source]

Determine the essential components of a Boolean network.

For each node in a Boolean network, represented by its Boolean function and its regulators, this function extracts the “essential” part of the function by removing non-essential regulators. The resulting network contains, for each node, a reduced truth table (with only the essential inputs) and a corresponding list of essential regulators.

Returns:

  • BooleanNetwork: A Boolean network object where:

    • F is a list of N Boolean functions containing functions of length 2^(m_i), with m_i ≤ n_i, representing the functions restricted to the essential regulators.

    • I is a list of N lists containing the indices of the essential regulators for each node.

get_edge_controlled_network(control_target: int, control_source: int, type_of_edge_control: int = 0) → BooleanNetwork[source]

Generate a perturbed Boolean network by removing the influence of a specified regulator on a specified target.

The function modifies the Boolean function for a target node by restricting it to those entries in its truth table where the input from a given regulator equals the specified type_of_control. The regulator is then removed from the wiring diagram for that node.

Parameters:

  • control_target (int): Index of the target node to be perturbed.

  • control_source (int): Index of the regulator whose influence is to be removed.

  • type_of_edge_control (int, optional): Source value in regulation after control. Default is 0.

Returns:

  • BooleanNetwork object where:

    • F is the updated list of Boolean functions after perturbation.

    • I is the updated wiring diagram after removing the control regulator from the target node.

get_external_inputs() → array[source]

Identify external inputs in a Boolean network.

A node is considered an external input if it has exactly one regulator and that regulator is the node itself.

Returns:

  • np.array: Array of node indices that are external inputs.

get_derrida_value(nsim: int = 1000, EXACT: bool = False, *, rng=None) → float[source]

Estimate the Derrida value for a Boolean network.

The Derrida value is computed by perturbing a single node in a randomly chosen state and measuring the average Hamming distance between the resulting updated states of the original and perturbed networks.

Parameters:

  • nsim (int, optional): Number of simulations to perform. Default is 1000.

  • EXACT (bool, optional): #TODO

Returns:

  • float: The average Hamming distance (Derrida value) over nsim simulations.

References:

  1. Derrida, B., & Pomeau, Y. (1986). Random networks of automata: a simple annealed approximation. Europhysics letters, 1(2), 45.

get_attractors_and_robustness_measures_synchronous_exact() → dict[source]

Compute the attractors and several robustness measures of a Boolean network.

This function computes the exact attractors and robustness (coherence and fragility) of the entire network, as well as robustness measures for each basin of attraction and each attractor.

Returns:

  • dict: A dictionary containing:

    • Attractors (list): List of attractors (each attractor is represented as a list of state decimal numbers).

    • ExactNumberOfAttractors (int): The exact number of network attractors.

    • BasinSizes (list): List of exact basin sizes for each attractor.

    • AttractorDict (dict): Dictionary mapping each state (in decimal) to its attractor index.

    • Coherence (float): overall exact network coherence

    • Fragility (float): overall exact network fragility

    • BasinCoherence (list): exact coherence of each basin.

    • BasinFragility (list): exact fragility of each basin.

    • AttractorCoherence (list): exact coherence of each attractor.

    • AttractorFragility (list): exact fragility of each attractor.

References:

  1. Park, K. H., Costa, F. X., Rocha, L. M., Albert, R., & Rozum, J. C. (2023). Models of cell processes are far from the edge of chaos. PRX life, 1(2), 023009.

  2. Bavisetty, V. S. N., Wheeler, M., & Kadelka, C. (2025). xxxx arXiv preprint arXiv:xxx.xxx.

get_attractors_and_robustness_measures_synchronous(number_different_IC: int = 500, RETURN_ATTRACTOR_COHERENCE: bool = True, *, rng=None) → dict[source]

Approximate global robustness measures and attractors.

This function samples the attractor landscape by simulating the network from a number of different initial conditions. It computes:

  • The coherence: the proportion of neighboring states (in the Boolean hypercube) that, after synchronous update, transition to the same attractor.

  • The fragility: a measure of how much the attractor state changes (assumed under synchronous update) in response to perturbations.

  • The final time-step Hamming distance between perturbed trajectories.

In addition, it collects several details about each attractor (such as basin sizes, coherence of each basin, etc.).

Parameters:

  • number_different_IC (int, optional): Number of different initial conditions to sample (default is 500).

  • RETURN_ATTRACTOR_COHERENCE (bool, optional): Determines whether the attractor coherence should also be computed (default True, i.e., Yes).

Returns:

  • dict: A dictionary containing:

    • Attractors (list): List of attractors (each attractor is represented as a list of state decimal numbers).

    • LowerBoundOfNumberOfAttractors (int): The lower bound on the number of attractors found.

    • BasinSizes (list): List of basin sizes for each attractor.

    • CoherenceApproximation (float): The approximate overall network coherence.

    • FragilityApproximation (float): The approximate overall network fragility.

    • FinalHammingDistanceApproximation (float): The approximate final Hamming distance measure.

    • BasinCoherenceApproximation (list): The approximate coherence of each basin.

    • BasinFragilityApproximation (list): The approximate fragility of each basin.

    • AttractorCoherence (list): The exact coherence of each attractor (only computed and returned if RETURN_ATTRACTOR_COHERENCE == True).

    • AttractorFragility (list): The exact fragility of each attractor (only computed and returned if RETURN_ATTRACTOR_COHERENCE == True).

References:

  1. Park, K. H., Costa, F. X., Rocha, L. M., Albert, R., & Rozum, J. C. (2023). Models of cell processes are far from the edge of chaos. PRX life, 1(2), 023009.

  2. Bavisetty, V. S. N., Wheeler, M., & Kadelka, C. (2025). xxxx arXiv preprint arXiv:xxx.xxx.

get_strongly_connected_components() → list[source]

Determine the strongly connected components of a wiring diagram.

The wiring diagram is provided as a list of lists I, where I[i] contains the indices of regulators for node i. The function constructs a directed graph from these edges and returns its strongly connected components.

Returns:

  • list: A list of sets, each representing a strongly connected component.

adjacency_matrix(constants: list = [], IGNORE_SELFLOOPS: bool = False, IGNORE_CONSTANTS: bool = True) → array[source]

Construct the (binary) adjacency matrix from the wiring diagram.

Given the wiring diagram I (a list of regulator lists for each node) and a list of constants, this function builds an adjacency matrix where each entry m[j, i] is 1 if node j regulates node i. Self-loops can be optionally ignored, and constant nodes can be excluded.

Parameters:

  • constants (list, optional): List of constant nodes.

  • IGNORE_SELFLOOPS (bool, optional): If True, self-loops are ignored.

  • IGNORE_CONSTANTS (bool, optional): If True, constant nodes are excluded from the matrix.

Returns:

  • np.array: The binary adjacency matrix.

get_signed_adjacency_matrix(type_of_each_regulation: list, constants: list = [], IGNORE_SELFLOOPS: bool = False, IGNORE_CONSTANTS: bool = True) → array[source]

Construct the signed adjacency matrix of a Boolean network.

The signed adjacency matrix assigns +1 for increasing (activating) regulations, -1 for decreasing (inhibiting) regulations, and NaN for any other type.

Parameters:

  • type_of_each_regulation (list): List of lists corresponding to the type of regulation (‘increasing’ or ‘decreasing’) for each edge in I.

  • constants (list, optional): List of constant nodes.

  • IGNORE_SELFLOOPS (bool, optional): If True, self-loops are ignored.

  • IGNORE_CONSTANTS (bool, optional): If True, constant nodes are excluded.

Returns:

  • np.array: The signed adjacency matrix.

get_signed_effective_graph(type_of_each_regulation: list, constants: list = [], IGNORE_SELFLOOPS: bool = False, IGNORE_CONSTANTS: bool = True) → array[source]

Construct the signed effective graph of a Boolean network.

This function computes an effective graph in which each edge is weighted by its effectiveness. Effectiveness is obtained via get_edge_effectiveness on the corresponding Boolean function. Edges are signed according to the type of regulation (‘increasing’ or ‘decreasing’).

Parameters:

  • type_of_each_regulation (list): List of lists specifying the type of regulation for each edge.

  • constants (list, optional): List of constant nodes.

  • IGNORE_SELFLOOPS (bool, optional): If True, self-loops are ignored.

  • IGNORE_CONSTANTS (bool, optional): If True, constant nodes are excluded.

Returns:

  • np.array: The signed effective graph as a matrix of edge effectiveness values.

get_ffls() → tuple[source]

Identify feed-forward loops (FFLs) in a Boolean network and optionally determine their types.

A feed-forward loop (FFL) is a three-node motif where node i regulates node k both directly and indirectly via node j.

Returns:

  • tuple: A tuple (ffls, types), where ffls is a list of FFLs and types is a list of corresponding monotonicity types.

get_ffls_from_I(types_I: list | None = None) → tuple | list[source]

Identify feed-forward loops (FFLs) in a Boolean network based solely on the wiring diagram.

The function uses the inverted wiring diagram to identify common targets and returns the FFLs found. If types_I (the type of each regulation) is provided, it also returns the corresponding regulation types.

Parameters:

  • types_I (list, optional): List of lists specifying the type (e.g., ‘increasing’ or ‘decreasing’) for each regulation.

Returns:

If types_I is provided:

  • tuple: (ffls, types) where ffls is a list of identified FFLs (each as a list [i, j, k]), and types is a list of corresponding regulation type triplets.

Otherwise:

  • list: A list of identified FFLs.

generate_networkx_graph(constants: list, variables: list) → DiGraph[source]

Generate a NetworkX directed graph from a wiring diagram.

Nodes are labeled with variable names (from variables) and constant names (from constants). Edges are added from each regulator to its target based on the wiring diagram I.

Parameters:

  • constants (list): List of constant names.

  • variables (list): List of variable names.

Returns:

  • networkx.DiGraph: The noderated directed graph.

generate_networkx_graph_from_edges(n_variables: int) → DiGraph[source]

Generate a NetworkX directed graph from an edge list derived from the wiring diagram.

Only edges among the first n_variables (excluding constant self-loops) are included.

Parameters:

  • n_variables (int): Number of variable nodes (constants are excluded).

Returns:

  • networkx.DiGraph: The generated directed graph.

get_type_of_loop(loop: list) → list[source]

Determine the regulation types along a feedback loop.

For a given loop (a list of node indices), this function returns a list containing the type (e.g., ‘increasing’ or ‘decreasing’) of each regulation along the loop. The loop is assumed to be ordered such that the first node is repeated at the end.

Parameters:

  • loop (list): List of node indices representing the loop.

Returns:

  • list: A list of regulation types corresponding to each edge in the loop.