boolforge 1.0.0__tar.gz → 1.0.1__tar.gz

{boolforge-1.0.0 → boolforge-1.0.1}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: boolforge
-Version: 1.0.0
+Version: 1.0.1
 Summary: Methods to generate and analyze random Boolean functions and Boolean networks, with a focus on canalization.
 Author-email: Claus Kadelka <ckadelka@iastate.edu>, Benjamin Coberly <ckadelka@iastate.edu>
 License-Expression: MIT
-Project-URL: Homepage, https://ckadelka.github.io/BoolForge/
-Project-URL: Documentation, https://ckadelka.github.io/BoolForge/
-Project-URL: Repository, https://github.com/ckadelka/BoolForge
-Project-URL: Issues, https://github.com/ckadelka/BoolForge/issues
+Project-URL: Homepage, https://KadelkaLab.github.io/BoolForge/
+Project-URL: Documentation, https://KadelkaLab.github.io/BoolForge/
+Project-URL: Repository, https://github.com/KadelkaLab/BoolForge
+Project-URL: Issues, https://github.com/KadelkaLab/BoolForge/issues
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering :: Mathematics
 Requires-Python: >=3.10
@@ -16,6 +16,7 @@ License-File: LICENSE
 Requires-Dist: numpy
 Requires-Dist: networkx
 Requires-Dist: pandas
+Requires-Dist: scipy
 Provides-Extra: cana
 Requires-Dist: cana; extra == "cana"
 Provides-Extra: bio
@@ -97,6 +98,7 @@ optional packages that can be installed via *extras*.
 
 Some internal routines are automatically accelerated if
 [numba](https://numba.pydata.org/) is available.
+Exact asynchronous attractor computation requires numba.
 
 To enable numba acceleration:
 
@@ -178,7 +180,7 @@ pip install boolforge[all]
 BoolForge supports import and export of Boolean network representations used by
 other software packages.
 
-In particular, BoolForge supports the **BNet format** commonly used by
+In particular, BoolForge supports the **.bnet format** commonly used by
 [pyboolnet](https://github.com/hklarner/pyboolnet), without requiring pyboolnet
 itself to be installed.
 
@@ -191,7 +193,7 @@ BoolForge also supports conversion to and from the format used by
 
 Full documentation, including tutorials and API reference, is available at:
 
-https://ckadelka.github.io/BoolForge/
+https://kadelkalab.github.io/BoolForge/
 
 ---
 
@@ -201,7 +203,7 @@ If you use BoolForge in your research, please cite the accompanying
 application note:
 
 Kadelka, C., & Coberly, B. (2025).  
-*BoolForge: A Python toolbox for Boolean functions and Boolean networks*.  
+*BoolForge: Controlled Generation and Analysis of Boolean Functions and Networks*.  
 arXiv:2509.02496.  
 https://arxiv.org/abs/2509.02496
 

{boolforge-1.0.0 → boolforge-1.0.1}/README.md

@@ -55,6 +55,7 @@ optional packages that can be installed via *extras*.
 
 Some internal routines are automatically accelerated if
 [numba](https://numba.pydata.org/) is available.
+Exact asynchronous attractor computation requires numba.
 
 To enable numba acceleration:
 
@@ -136,7 +137,7 @@ pip install boolforge[all]
 BoolForge supports import and export of Boolean network representations used by
 other software packages.
 
-In particular, BoolForge supports the **BNet format** commonly used by
+In particular, BoolForge supports the **.bnet format** commonly used by
 [pyboolnet](https://github.com/hklarner/pyboolnet), without requiring pyboolnet
 itself to be installed.
 
@@ -149,7 +150,7 @@ BoolForge also supports conversion to and from the format used by
 
 Full documentation, including tutorials and API reference, is available at:
 
-https://ckadelka.github.io/BoolForge/
+https://kadelkalab.github.io/BoolForge/
 
 ---
 
@@ -159,7 +160,7 @@ If you use BoolForge in your research, please cite the accompanying
 application note:
 
 Kadelka, C., & Coberly, B. (2025).  
-*BoolForge: A Python toolbox for Boolean functions and Boolean networks*.  
+*BoolForge: Controlled Generation and Analysis of Boolean Functions and Networks*.  
 arXiv:2509.02496.  
 https://arxiv.org/abs/2509.02496
 

{boolforge-1.0.0 → boolforge-1.0.1}/boolforge/__init__.py

@@ -25,6 +25,7 @@ from .utils import (
     dec2bin,
     get_left_side_of_truth_table,
     hamming_weight_to_ncf_layer_structure,
+    get_shannon_entropy,
 )
 
 from .modularity import (
@@ -46,6 +47,7 @@ __all__ = [
     "dec2bin",
     "get_left_side_of_truth_table",
     "hamming_weight_to_ncf_layer_structure",
+    "get_shannon_entropy",
     "BooleanFunction",
     "display_truth_table",
     "get_layer_structure_from_canalized_outputs",

boolforge-1.0.1/boolforge/_version.py

@@ -0,0 +1 @@
+__version__ = '1.0.1'

boolforge-1.0.1/boolforge/backend/__init__.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Low-level computational backends for BoolForge.
+
+Contains numba-accelerated kernels and graph algorithms used by
+Boolean network and wiring diagram analyses.
+"""

boolforge-1.0.1/boolforge/backend/_numba.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+try:
+    import numba
+    from numba import njit
+    from numba.typed import List
+    int64 = numba.int64
+    __LOADED_NUMBA__ = True
+except ModuleNotFoundError:
+    # List = list
+    # int64 = int
+    # def njit(*args, **kwargs):
+    #     def decorator(func):
+    #         return func
+    #     return decorator
+    
+    __LOADED_NUMBA__ = False
+    
+def _numba_required(feature: str):
+    raise ImportError(
+        f"{feature} requires numba. "
+        "Install it with: pip install numba"
+    )

boolforge-1.0.1/boolforge/backend/dynamics_async.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+import numpy as np
+
+from ._numba import njit, __LOADED_NUMBA__
+
+if __LOADED_NUMBA__:
+    @njit
+    def _build_async_transition_coo(
+        F_array_list,
+        I_array_list,
+        N
+    ):
+        nstates = 1 << N
+        max_edges = nstates * N
+    
+        rows = np.empty(max_edges, dtype=np.int32)
+        cols = np.empty(max_edges, dtype=np.int32)
+        data = np.empty(max_edges, dtype=np.float32)
+    
+        edge_count = 0
+        powers = np.empty(N, dtype=np.int32)
+        for j in range(N):
+            powers[j] = 1 << (N - 1 - j)
+    
+        for s in range(nstates):
+            unstable_count = 0
+            # count unstable nodes
+            for j in range(N):
+                regs = I_array_list[j]
+                idx = 0
+                for k in range(len(regs)):
+                    bit = (s >> (N - 1 - regs[k])) & 1
+                    idx = (idx << 1) | bit
+                new_val = F_array_list[j][idx]
+                current = (s >> (N - 1 - j)) & 1
+                if new_val != current:
+                    unstable_count += 1
+    
+            # fixed point self-loop
+            if unstable_count == 0:
+                rows[edge_count] = s
+                cols[edge_count] = s
+                data[edge_count] = 1.0
+                edge_count += 1
+                continue
+    
+            p = 1.0 / unstable_count
+    
+            # emit transitions
+            for j in range(N):
+                regs = I_array_list[j]
+                idx = 0
+                for k in range(len(regs)):
+                    bit = (s >> (N - 1 - regs[k])) & 1
+                    idx = (idx << 1) | bit
+                new_val = F_array_list[j][idx]
+                current = (s >> (N - 1 - j)) & 1
+                if new_val != current:
+                    y = s ^ powers[j]
+                    rows[edge_count] = s
+                    cols[edge_count] = y
+                    data[edge_count] = p
+                    edge_count += 1
+        return (
+            rows[:edge_count],
+            cols[:edge_count],
+            data[:edge_count]
+        )
+
+
+def get_dimension_trap_space(terminal_scc):
+    ref = terminal_scc[0]
+    varying = 0
+    for s in terminal_scc[1:]:
+        varying |= (ref ^ s)
+    return varying.bit_count()    

boolforge-1.0.1/boolforge/backend/dynamics_sync.py

@@ -0,0 +1,339 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+
+import numpy as np
+
+# load optional but desirable package
+from ._numba import njit, List, int64, __LOADED_NUMBA__
+
+if __LOADED_NUMBA__:
+    @njit(fastmath=True)  # safe: operations are integer-only
+    def _update_network_synchronously_numba(
+        x,
+        F_array_list,
+        I_array_list,
+    ):
+        """
+        Perform one synchronous update of a Boolean network.
+    
+        Given a binary state vector ``x``, this function computes the next network
+        state under synchronous updating by evaluating each node’s Boolean update
+        function based on its regulators.
+    
+        Parameters
+        ----------
+        x : np.ndarray
+            Binary state vector of shape ``(N,)`` with dtype ``uint8``.
+        F_array_list : list[np.ndarray]
+            List of truth tables for each node, where the ``j``-th entry is an
+            array of length ``2**k_j`` giving the update rule for node ``j`` with
+            ``k_j`` regulators.
+        I_array_list : list[np.ndarray]
+            List of regulator index arrays, where the ``j``-th entry contains the
+            indices of the regulators of node ``j``.
+    
+        Returns
+        -------
+        np.ndarray
+            Updated binary state vector of shape ``(N,)`` with dtype ``uint8``.
+        """
+        N = x.shape[0]
+        fx = np.empty(N, dtype=np.uint8)
+        for j in range(N):
+            regulators = I_array_list[j]
+            if regulators.shape[0] == 0:
+                fx[j] = F_array_list[j][0]
+            else:
+                idx = 0
+                for k in range(regulators.shape[0]):
+                    idx = (idx << 1) | x[regulators[k]]
+                fx[j] = F_array_list[j][idx]
+        return fx
+    
+    @njit
+    def _compute_synchronous_stg_numba(
+        F_array_list, 
+        I_array_list, 
+        N_variables
+    ):
+        """
+        Compute the synchronous state transition graph (STG).
+    
+        This Numba-compiled function computes, for every possible binary state
+        of a Boolean network, the index of its successor state under synchronous
+        updating.
+    
+        Parameters
+        ----------
+        F_array_list : list[np.ndarray]
+            List of Boolean update tables. The ``j``-th entry is a NumPy array of
+            length ``2**k_j`` representing the update rule for node ``j`` with
+            ``k_j`` regulators.
+        I_array_list : list[np.ndarray]
+            List of regulator index arrays. The ``j``-th entry contains the indices
+            of the regulators of node ``j``.
+        N_variables : int
+            Number of variables (nodes) in the network.
+    
+        Returns
+        -------
+        np.ndarray
+            One-dimensional array of length ``2**N_variables`` containing, for
+            each state index, the index of the successor state under synchronous
+            updating.
+        """
+        nstates = 2 ** N_variables
+        states = np.zeros((nstates, N_variables), dtype=np.uint8)
+        for i in range(nstates):
+            # binary representation of i
+            for j in range(N_variables):
+                states[i, N_variables - 1 - j] = (i >> j) & 1
+    
+        next_states = np.zeros_like(states)
+        powers_of_two = 2 ** np.arange(N_variables - 1, -1, -1)
+    
+        # Compute next state for each node
+        for j in range(N_variables):
+            regulators = I_array_list[j]
+            if len(regulators) == 0:
+                # constant node
+                next_states[:, j] = F_array_list[j][0]
+                continue
+    
+            n_reg = len(regulators)
+            reg_powers = 2 ** np.arange(n_reg - 1, -1, -1)
+            for s in range(nstates):
+                idx = 0
+                for k in range(n_reg):
+                    idx += states[s, regulators[k]] * reg_powers[k]
+                next_states[s, j] = F_array_list[j][idx]
+    
+        # Convert each next state to integer index
+        next_indices = np.zeros(nstates, dtype=np.int64) # NOTE: this cannot be an unsigned int for safe indexing inside Numba kernels.
+        for s in range(nstates):
+            val = 0
+            for j in range(N_variables):
+                val += next_states[s, j] * powers_of_two[j]
+            next_indices[s] = val
+    
+        return next_indices
+
+    @njit
+    def _compute_synchronous_stg_numba_low_memory(
+        F_array_list,
+        I_array_list,
+        N_variables
+    ):
+        """
+        Compute the synchronous state transition graph (STG) using minimal memory.
+    
+        For each integer state index ``i`` in ``[0, 2**N_variables)``, this function
+        decodes ``i`` into its binary state vector, computes the synchronous update
+        of the Boolean network, and encodes the resulting state back into an integer
+        index.
+    
+        Parameters
+        ----------
+        F_array_list : list[np.ndarray]
+            List of Boolean update tables. The ``j``-th entry is an array of length
+            ``2**k_j`` representing the update rule for node ``j`` with ``k_j``
+            regulators.
+        I_array_list : list[np.ndarray]
+            List of regulator index arrays. The ``j``-th entry contains the indices
+            of the regulators of node ``j``.
+        N_variables : int
+            Number of variables (nodes) in the network.
+    
+        Returns
+        -------
+        np.ndarray
+            One-dimensional array of length ``2**N_variables`` containing, for each
+            state index, the index of the successor state under synchronous updating.
+    
+        Notes
+        -----
+        This implementation avoids storing the full state matrix and therefore
+        reduces memory usage from ``O(N * 2**N)`` to ``O(N + 2**N)``. The time
+        complexity remains exponential in ``N_variables``.
+        """
+        nstates = 2 ** N_variables
+        next_indices = np.zeros(nstates, dtype=np.int64) # NOTE: this cannot be an unsigned int for safe indexing inside Numba kernels.
+        powers_of_two = 2 ** np.arange(N_variables - 1, -1, -1)
+    
+        state = np.zeros(N_variables, dtype=np.uint8)
+        next_state = np.zeros(N_variables, dtype=np.uint8)
+    
+        for i in range(nstates):
+            # --- Decode i into binary vector (most-significant bit first)
+            tmp = i
+            for j in range(N_variables):
+                state[N_variables - 1 - j] = tmp & 1
+                tmp >>= 1
+    
+            # --- Compute next-state values
+            for j in range(N_variables):
+                regulators = I_array_list[j]
+                if regulators.shape[0] == 0:
+                    next_state[j] = F_array_list[j][0]
+                else:
+                    n_reg = regulators.shape[0]
+                    idx = 0
+                    for k in range(n_reg):
+                        idx = (idx << 1) | state[regulators[k]]
+                    next_state[j] = F_array_list[j][idx]
+    
+            # --- Encode next_state back to integer
+            val = 0
+            for j in range(N_variables):
+                val += next_state[j] * powers_of_two[j]
+            next_indices[i] = val
+        return next_indices
+
+
+    @njit(cache=True)
+    def _attractors_functional_graph(next_state):
+        """
+        Identify attractors and basins in a functional graph.
+    
+        Given a functional graph represented by a successor array, this function
+        identifies all attractors (cycles), assigns each state to an attractor,
+        and computes basin sizes and cycle properties.
+    
+        Parameters
+        ----------
+        next_state : np.ndarray
+            One-dimensional integer array of length ``n`` such that
+            ``next_state[x]`` gives the successor of state ``x`` and lies in
+            ``[0, n-1]``.
+    
+        Returns
+        -------
+        attr_id : np.ndarray
+            Integer array of length ``n`` mapping each state to its attractor
+            index.
+        basin_sizes : np.ndarray
+            Integer array of length ``n_attr`` giving the basin size of each
+            attractor.
+        cycle_rep : np.ndarray
+            Integer array of length ``n_attr`` containing one representative
+            state from each attractor cycle.
+        cycle_len : np.ndarray
+            Integer array of length ``n_attr`` giving the length of each cycle.
+        n_attr : np.int32
+            Number of attractors in the functional graph.
+        """
+
+        n = next_state.shape[0]
+        attr_id = np.full(n, -1, dtype=np.int32)
+    
+        # For detecting cycles within the current walk:
+        # seen[u] == run_id  means u was visited in this run
+        # pos[u] = index of u in the current path (when first visited this run)
+        seen = np.zeros(n, dtype=np.int32)
+        pos = np.zeros(n, dtype=np.int32)
+    
+        # Upper bounds: in the worst case every node could be its own 1-cycle
+        basin_sizes_full = np.zeros(n, dtype=np.int32)
+        cycle_rep_full = np.empty(n, dtype=np.int64)
+        cycle_len_full = np.zeros(n, dtype=np.int32)
+    
+        n_attr = 0
+    
+        # Numba typed list for the current path
+        path = List.empty_list(int64)
+    
+        for start in range(n):
+            if attr_id[start] != -1:
+                continue
+    
+            path.clear()
+            u = start
+            run_id = start + 1  # unique per start; safe while n << 2**31 (always true in practice)
+    
+            # Walk until we hit a known attractor or revisit a node in this run
+            while attr_id[u] == -1 and seen[u] != run_id:
+                seen[u] = run_id
+                pos[u] = len(path)
+                path.append(u)
+                u = next_state[u]
+    
+            if attr_id[u] != -1:
+                # This path flows into an already-known attractor
+                aid = attr_id[u]
+                for i in range(len(path)):
+                    v = path[i]
+                    attr_id[v] = aid
+                    basin_sizes_full[aid] += 1
+            else:
+                # We found a cycle within the current run.
+                # u is the first repeated node; cycle starts at pos[u] in path
+                cyc_start = pos[u]
+                aid = n_attr
+                n_attr += 1
+    
+                # Representative and length of the cycle
+                cycle_rep_full[aid] = u
+                cycle_len_full[aid] = len(path) - cyc_start
+    
+                # Assign all nodes on the path to this new attractor
+                for i in range(len(path)):
+                    v = path[i]
+                    attr_id[v] = aid
+                    basin_sizes_full[aid] += 1
+    
+        return attr_id, basin_sizes_full[:n_attr], cycle_rep_full[:n_attr], cycle_len_full[:n_attr], np.int32(n_attr)
+    
+    @njit(cache=True)
+    def _transient_lengths_functional_numba(
+        succ,
+        is_attr_mask
+    ):
+        """
+        Compute exact transient length (distance to attractor) for a functional graph.
+    
+        Parameters
+        ----------
+        succ : int64 array, shape (n_states,)
+            succ[x] = successor of state x
+        is_attr_mask : uint8/bool array, shape (n_states,)
+            1 if state lies on an attractor cycle, else 0
+    
+        Returns
+        -------
+        dist : int64 array, shape (n_states,)
+            dist[x] = number of steps from x to its attractor
+        """
+        n = succ.shape[0]
+        dist = np.full(n, -1, dtype=np.int64)
+    
+        # Attractor states have distance 0
+        for i in range(n):
+            if is_attr_mask[i]:
+                dist[i] = 0
+    
+        for i in range(n):
+            if dist[i] >= 0:
+                continue
+    
+            v = i
+    
+            # Walk forward until we hit a known distance
+            while dist[v] == -1:
+                dist[v] = -2          # temporary marker: "in current path"
+                v = succ[v]
+    
+            # Now dist[v] is either:
+            #   0,1,2,...  (known)
+            # or -2       (should not happen if cycles were pre-marked)
+            d = dist[v]
+    
+            # Unwind path, assigning distances
+            v = i
+            while dist[v] == -2:
+                d += 1
+                nxt = succ[v]
+                dist[v] = d
+                v = nxt
+    
+        return dist

boolforge-1.0.1/boolforge/backend/function_analysis.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+import numpy as np
+
+from ._numba import njit
+
+@njit
+def _is_degenerate_numba(f : np.ndarray, n : int) -> bool:
+    """
+    Check whether a Boolean function contains a non-essential variable.
+
+    This Numba-accelerated helper determines whether there exists at least
+    one input variable whose value can be flipped without affecting the
+    output of the Boolean function.
+
+    Parameters
+    ----------
+    f : np.ndarray
+        Truth table of the Boolean function, of length ``2**n``.
+    n : int
+        Number of input variables.
+
+    Returns
+    -------
+    bool
+        ``True`` if the function contains at least one non-essential
+        variable, ``False`` otherwise.
+    """
+    N = 1 << n  # 2**n
+    for i in range(n):
+        stride = 1 << (n - 1 - i)
+        step = stride << 1  # 2 * stride
+        depends_on_i = False
+        # Iterate in blocks that differ only in bit i
+        for base in range(0, N, step):
+            for offset in range(stride):
+                if f[base + offset] != f[base + offset + stride]:
+                    depends_on_i = True
+                    break
+            if depends_on_i:
+                break
+        if not depends_on_i:
+            return True  # found non-essential variable
+    return False
+
+def _get_essential_variables_numba(f : np.ndarray, n : int) -> bool:
+    """
+    Check whether a Boolean function contains a non-essential variable.
+
+    This Numba-accelerated helper determines all input variables whose value 
+    cannot be flipped without affecting the output of the Boolean function.
+
+    Parameters
+    ----------
+    f : np.ndarray
+        Truth table of the Boolean function, of length ``2**n``.
+    n : int
+        Number of input variables.
+
+    Returns
+    -------
+    np.ndarray[bool]
+        Array of length n. ``True`` if the variable at position i is essential.
+    """
+    
+    N = 1 << n  # 2**n
+    is_essential = np.zeros(n, dtype=bool)
+    for i in range(n):
+        stride = 1 << (n - 1 - i)
+        step = stride << 1  # 2 * stride
+        depends_on_i = False
+        # Iterate in blocks that differ only in bit i
+        for base in range(0, N, step):
+            for offset in range(stride):
+                if f[base + offset] != f[base + offset + stride]:
+                    depends_on_i = True
+                    is_essential[i] = True
+                    break
+            if depends_on_i:
+                break
+    return is_essential

boolforge-1.0.1/boolforge/backend/helpers.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+import math
+
+def _compress_with_known_cycle(traj, cycle_len):
+    len_traj = len(traj)
+    best_trajectory = []
+    best_cycle_len = -1
+    best_length = math.inf
+    for s in range(len_traj):
+        for p in range(1, min(cycle_len, len_traj - s) + 1):
+            proposed_period = traj[s : s + p]
+            good_proposal = True
+            for i in range(s, len_traj):
+                if traj[i] != proposed_period[(i - s) % p]:
+                    good_proposal = False
+                    break
+            if not good_proposal:
+                continue
+            
+            len_proposal = s + p
+            if len_proposal < best_length:
+                best_length = len_proposal
+                best_trajectory = traj[:s] + proposed_period
+                best_cycle_len = p
+    return best_trajectory, best_cycle_len