BoolForge: Canalization-Aware Boolean Toolbox

• BoolForge is a Python toolbox for the random generation and analysis of Boolean functions and networks with an emphasis on canalization in systems biology.
• It enables constrained sample generation by allowing users to specify canalizing depth, layered structures, and unbiased function-uniform sampling to construct structured null models.
• The package integrates simulation with analysis of attractors, robustness, modularity, and motifs, filling methodological gaps left by traditional Boolean network tools.

Searching arXiv for the specified BoolForge papers to ground the article in current preprints. BoolForge is a Python toolbox for the random generation and analysis of Boolean functions and Boolean networks, developed with a particular emphasis on canalization in systems biology. It is intended to support workflows in which researchers generate Boolean functions with prescribed structural constraints, assemble Boolean networks with tunable topological and rule-level properties, and analyze resulting structural and dynamical features such as attractors, robustness, modularity, coherence, and motifs. The software addresses a gap left by established Boolean-network packages that support simulation and attractor analysis but provide little or no direct support for generating networks with defined canalization properties, despite the empirical prevalence of canalization in curated biological regulatory systems (Kadelka et al., 2 Sep 2025). Subsequent work extended BoolForge with function-uniform samplers for canalizing Boolean functions, showing that widely used parameter-uniform sampling schemes induce systematic biases in null-model construction and consequently distort inferences about robustness and sensitivity in Boolean-network analysis (Ghosh et al., 22 May 2026).

1. Conceptual setting and scientific motivation

Boolean networks are widely used to model gene regulation, signal transduction, and cellular decision-making. In this setting, each node is updated by a Boolean function, and global dynamics emerge from the interaction of these local rules. A central empirical observation motivating BoolForge is that most biological networks exhibit a high degree of canalization, meaning that some inputs determine the output regardless of the values of the remaining inputs; this property is associated with stabilization of network dynamics (Kadelka et al., 2 Sep 2025).

BoolForge was designed to fill a specific methodological gap. Packages such as BoolNet, PyBoolNet, Cyclone, and biobalm are described as strong for simulation and attractor finding, but as offering little or no support for generating networks with prescribed canalization. BoolForge instead centers canalization-aware random generation. This enables rapid prototyping of biologically plausible Boolean models, systematic ensemble studies, and null-model comparisons that isolate the role of canalization from confounding features such as degree distributions or bias (Kadelka et al., 2 Sep 2025).

A second motivation emerged from later analysis of random-function generation itself. The 2026 study on uniform sampling of canalizing Boolean functions argues that a common practice—sampling canalizing parameters such as variable order, canalizing inputs, and canalized outputs uniformly—does not produce a uniform distribution over distinct Boolean functions. Because multiple parameterizations can encode the same function, such procedures overweight some functions and underweight others. BoolForge was extended to correct this problem through exact function-uniform samplers, thereby providing unbiased null models for Boolean-network studies (Ghosh et al., 22 May 2026).

2. Formal objects and canalization framework

A Boolean function on $n$ variables is a map $f:\{0,1\}^n \to \{0,1\}$. BoolForge’s BooleanFunction stores the right-hand side of the truth table, ordered lexicographically by inputs; for example, $f(x_0,x_1)=x_0 \wedge x_1$ is stored as [0,0,0,1] (Kadelka et al., 2 Sep 2025). The total number of distinct Boolean functions on $n$ variables is $2^{2^n}$ (Kadelka et al., 2 Sep 2025).

Canalization is defined at the level of a variable. A variable $x_i$ is canalizing with canalizing input $a \in \{0,1\}$ and canalized output $b \in \{0,1\}$ if $f(x)=b$ whenever $x_i=a$, irrespective of all other inputs (Kadelka et al., 2 Sep 2025, Ghosh et al., 22 May 2026). More generally, a function is $f:\{0,1\}^n \to \{0,1\}$0-canalizing if there exists an ordered sequence of distinct variables, associated canalizing inputs, canalized outputs, and a residual core function so that successive input conditions peel off variables one by one until a nontrivial core remains (Ghosh et al., 22 May 2026). The canalizing depth is the maximal such $f:\{0,1\}^n \to \{0,1\}$1 (Kadelka et al., 2 Sep 2025).

The distinction between exact and minimal depth is operationally important in BoolForge’s samplers. “Exact depth $f:\{0,1\}^n \to \{0,1\}$2” means that the canalizing depth equals $f:\{0,1\}^n \to \{0,1\}$3, whereas “minimal depth $f:\{0,1\}^n \to \{0,1\}$4” means the function has depth at least $f:\{0,1\}^n \to \{0,1\}$5 (Ghosh et al., 22 May 2026). Nested canalizing functions (NCFs) are the special case with full depth $f:\{0,1\}^n \to \{0,1\}$6, while partially nested canalizing functions (PNCFs) have depth $f:\{0,1\}^n \to \{0,1\}$7 (Kadelka et al., 2 Sep 2025).

Layer structure refines canalizing depth by grouping successive canalizing variables according to whether their canalized outputs are equal. In the 2026 formulation, the layer structure is a sequence $f:\{0,1\}^n \to \{0,1\}$8 of positive integers summing to the canalizing depth, where each $f:\{0,1\}^n \to \{0,1\}$9 is the size of a layer and $f(x_0,x_1)=x_0 \wedge x_1$0 is the number of constant runs in the canalized-output sequence (Ghosh et al., 22 May 2026). In the 2025 BoolForge description, this structure is connected to the extended monomial form, which reveals layers through products of terms $f(x_0,x_1)=x_0 \wedge x_1$1 nested over layers in $f(x_0,x_1)=x_0 \wedge x_1$2 around a non-canalizing core (Kadelka et al., 2 Sep 2025).

Influence and sensitivity provide the main function-level dynamical proxies. For variable $f(x_0,x_1)=x_0 \wedge x_1$3, the influence is

$f(x_0,x_1)=x_0 \wedge x_1$4

where $f(x_0,x_1)=x_0 \wedge x_1$5 is obtained by flipping the $f(x_0,x_1)=x_0 \wedge x_1$6-th bit of $f(x_0,x_1)=x_0 \wedge x_1$7 (Kadelka et al., 2 Sep 2025). The average sensitivity is

$f(x_0,x_1)=x_0 \wedge x_1$8

equivalently the expected pointwise sensitivity over the hypercube (Kadelka et al., 2 Sep 2025, Ghosh et al., 22 May 2026). BoolForge’s scientific premise is that canalization tends to reduce influences and average sensitivity, thereby contributing to robustness (Kadelka et al., 2 Sep 2025).

3. Core architecture and software capabilities

BoolForge is implemented in Python 3.8+, has no platform-specific dependencies, and is distributed under the MIT License (Kadelka et al., 2 Sep 2025). The source code, documentation, and tutorial notebooks are made freely available through the project repository, and the software can be installed with pip install git+https://github.com/ckadelka/BoolForge (Kadelka et al., 2 Sep 2025). The authors state that it will be maintained for at least two years following publication (Kadelka et al., 2 Sep 2025).

Its API is organized around two core classes: BooleanFunction and BooleanNetwork (Kadelka et al., 2 Sep 2025). BooleanFunction supports construction from truth-table arrays, Boolean expressions such as "x0 + x1 + x2 > 1", or random generation under constraints including exact or minimal canalizing depth, nested canalization, layer structure, linearity, and bias (Kadelka et al., 2 Sep 2025). BooleanNetwork stores a list of BooleanFunction objects together with a wiring diagram represented as a list of input-index lists, and can be constructed from PyBoolNet or CANA objects, by manual specification, or by random generation under topological and rule-level constraints (Kadelka et al., 2 Sep 2025).

The package supports three broad classes of operations.

Capability	BoolForge functionality	Representative details
Function generation	Random Boolean functions with constraints	Non-degenerate, linear, exact or minimal canalizing depth, NCFs, specified layer structure, prescribed Hamming weight
Network generation	Random Boolean networks with tunable topology and rules	User-controlled in-degree, strong connectedness, self-loops, custom wiring, rule assignment from selected function classes
Analysis	Structural and dynamical measures	Attractors, robustness metrics, modularity, coherence, motifs, monotonicity, essentiality, symmetry, average sensitivity

Beyond its own generators and analyzers, BoolForge is intended to interoperate with existing tools. It supports importing from and exporting to CANA and PyBoolNet, allowing users to combine canalization-aware generation with external attractor-finding and visualization workflows (Kadelka et al., 2 Sep 2025). This complementarity is explicit: BoolForge focuses on generation and structural analytics, while established backends are used for specialized analyses such as SAT-, BDD-, and trap-space-based attractor computation (Kadelka et al., 2 Sep 2025).

4. Random generation of Boolean functions and networks

A defining feature of BoolForge is that it can sample random Boolean functions from several constrained classes. The 2025 description lists uniform-at-random sampling from non-degenerate functions, linear functions, functions with exact or minimal canalizing depth, nested canalizing functions, functions with specified canalizing layer structure, and functions with prescribed Hamming weight (Kadelka et al., 2 Sep 2025). This allows researchers to construct ensembles that hold some structural properties fixed while varying others.

For fixed canalizing depth and layer structure, BoolForge leverages the extended monomial decomposition. The stated generic sampling routine proceeds by choosing the number of variables $f(x_0,x_1)=x_0 \wedge x_1$9, the desired canalizing depth $n$0, and a layer partition; selecting a variable order consistent with those layers together with canalizing inputs; sampling a non-canalizing core on the remaining variables from a specified distribution; and recursively embedding the layers around the core using products of $n$1 terms (Kadelka et al., 2 Sep 2025). According to the description, this yields exact-depth-$n$2 PNCFs, NCFs, and arbitrary layer structures, and can be uniform within the specified class when literature-based enumerations are used (Kadelka et al., 2 Sep 2025).

Network generation is organized in two stages. First, BoolForge constructs a wiring diagram for $n$3 nodes with user-specified in-degrees, optionally preserving degree sequences, enforcing strong connectedness, and controlling the presence of self-loops; alternatively, the user may provide a custom wiring diagram directly (Kadelka et al., 2 Sep 2025). Second, for each node, BoolForge assigns a Boolean rule on the node’s input set, drawn from one of the function generators described above. This permits ensembles in which canalization is controlled at the per-node level or globally across the network (Kadelka et al., 2 Sep 2025).

The package also automates null-model construction. It can rewire a curated network while preserving selected topological properties such as in-degree or out-degree, and optionally preserve rule-level features such as canalizing depth and bias (Kadelka et al., 2 Sep 2025). This functionality is methodologically significant because it enables statistical comparisons between curated biological models and matched random ensembles, with explicit control over the properties being held constant.

5. Uniform sampling and correction of parameterization bias

The 2026 BoolForge paper identifies a bias in the traditional parameter-uniform generation of canalizing Boolean functions. Under that approach, one samples the variable order, canalizing inputs, canalized outputs, and, where needed, the core function uniformly. Because different parameter choices can encode the same Boolean function, the resulting measure on distinct functions is non-uniform (Ghosh et al., 22 May 2026). In particular, functions with few large layers admit many parameterizations and are overrepresented, while functions with many small layers admit fewer parameterizations and are underrepresented (Ghosh et al., 22 May 2026).

To correct this, BoolForge implements function-uniform samplers for classes of canalizing functions. For exact canalizing depth, the 2026 paper introduces a dynamic-programming sampler over layer structures. A key combinatorial weight for a layer structure $n$4 is

$n$5

and the number of distinct functions with a given layer structure is proportional to this weight (Ghosh et al., 22 May 2026). The sampler therefore generates the layer structure with probability proportional to $n$6, then samples canalizing inputs, a variable order, and a non-canalizing core uniformly in a way that preserves uniformity over distinct functions (Ghosh et al., 22 May 2026).

The dynamic-programming construction is expressed in terms of a state $n$7, where $n$8 is the number of canalized outputs still to assign and $n$9 is the size of the current open layer. The total remaining weight satisfies

$2^{2^n}$0

with boundary condition $2^{2^n}$1, and for NCFs $2^{2^n}$2 because the final layer cannot be a singleton (Ghosh et al., 22 May 2026). The corresponding branch probabilities for extending the current layer or closing it are chosen from these weights so that the final layer structure is sampled with probability proportional to $2^{2^n}$3 (Ghosh et al., 22 May 2026).

For minimal canalizing depth, an additional issue arises because the sampled core may itself be canalizing. If its first core layer has the same canalized output as the last sampled layer, the layers merge, producing multiple parameterizations of the same function. BoolForge corrects this by a rejection-based procedure: when such a merge occurs, the sampled function is accepted with probability $2^{2^n}$4, where

$2^{2^n}$5

and otherwise the sample is rejected and regenerated (Ghosh et al., 22 May 2026). The 2026 paper states that the dynamic-programming weights can be precomputed in $2^{2^n}$6, sampling a single layer structure is $2^{2^n}$7, and the rejection probability is modest; for $2^{2^n}$8, it is $2^{2^n}$9, and it decreases exponentially as $x_i$0 grows because canalizing cores become rare (Ghosh et al., 22 May 2026).

These algorithms matter because they change the reference distribution for null models. A plausible implication is that any conclusion derived from a canalizing-function ensemble depends not only on the constraint class—such as NCFs or exact depth—but also on whether the ensemble is uniform over parameterizations or over distinct functions.

6. Analytical scope: attractors, robustness, modularity, coherence, and motifs

BoolForge supports analysis at both the function and network levels. For Boolean functions, the package computes monotonicity, essentiality, symmetry, average sensitivity, extended monomial form, layer structure, canalizing strength, and redundancy or effective degree (Kadelka et al., 2 Sep 2025). These metrics are intended to characterize both algebraic structure and dynamical susceptibility to perturbation.

At the network level, BoolForge supports attractor analysis, robustness analysis, modularity, coherence, and motif detection (Kadelka et al., 2 Sep 2025). For synchronous dynamics, an attractor is a cycle in the state-transition graph, including fixed points and higher-period limit cycles. For asynchronous dynamics, attractors are sets of states closed under allowed single-node updates; in large systems these generally require specialized algorithms, which BoolForge accesses via integration with PyBoolNet and biobalm (Kadelka et al., 2 Sep 2025).

Robustness is treated in several related ways. At the function level, BoolForge computes sensitivity $x_i$1. At the network level, it supports ensemble-based robustness tests such as empirical estimation of the Derrida curve,

$x_i$2

where $x_i$3 is Hamming distance (Kadelka et al., 2 Sep 2025). The description notes that networks “far from the edge of chaos” have $x_i$4 for small $x_i$5, indicating contraction of perturbations (Kadelka et al., 2 Sep 2025). Through integration, users may also obtain established measures such as Derrida coefficient, quasicoherence, and fragility, while BoolForge adds coherence measures for networks, attractors, and basins (Kadelka et al., 2 Sep 2025).

Modularity is derived from the wiring diagram by methods including strongly connected components, hierarchical condensation, and module interfaces, and is quantified following prior work on modular structure in Boolean networks (Kadelka et al., 2 Sep 2025). Motif detection uses standard subgraph search on the directed wiring graph to identify feed-forward loops, feedback loops, and related motifs (Kadelka et al., 2 Sep 2025).

The package’s role in null-model analysis is especially important in this analytical layer. BoolForge can construct nontrivial null-model ensembles preserving selected topological and functional properties, then compare curated biological networks against those ensembles. The 2025 paper states that such analyses showed that canalization, rather than bias alone, explains the high approximability of biological networks (Kadelka et al., 2 Sep 2025).

7. Empirical findings, interpretation, and limitations

The empirical significance of BoolForge is described in two closely related strands. First, the 2025 paper reports its use in constructing null models closely matched to curated gene regulatory networks, enabling tests of hypotheses about approximability and robustness. These ensemble comparisons showed that canalization abundance, rather than bias alone, accounts for high approximability observed in biological networks (Kadelka et al., 2 Sep 2025). The broader background cited there links strong canalization and structured motifs to gene regulatory networks and connects canalization theoretically to reduced sensitivity and stabilized dynamics (Kadelka et al., 2 Sep 2025).

Second, the 2026 paper shows that the choice of sampling scheme materially changes common metrics and network-level conclusions. For NCFs, under parameter-uniform sampling the expected average sensitivity satisfies $x_i$6 for all $x_i$7, whereas under function-uniform sampling it increases with $x_i$8 and numerically approaches approximately $x_i$9 (Ghosh et al., 22 May 2026). The paper attributes this discrepancy to exponential suppression of high-sensitivity functions under parameter-based sampling (Ghosh et al., 22 May 2026). It further reports that, in random networks of $a \in \{0,1\}$0 nodes with constant in-degree $a \in \{0,1\}$1 and NCF update rules, parameter-uniform ensembles across 10,000 networks per condition exhibit fewer attractors and shorter cycles, higher coherence, and lower basin entropy than function-uniform ensembles (Ghosh et al., 22 May 2026). These differences are interpreted as artifacts of biased overrepresentation of low-sensitivity rules in parameter-uniform sampling (Ghosh et al., 22 May 2026).

The reanalysis of published biological models is one of the strongest stated applications. Revisiting 122 Boolean gene regulatory network models, the 2026 study compares observed NCF layer structures against both parameter-uniform and function-uniform null expectations. Its main result is that function-uniform nulls reveal a substantially stronger enrichment of low-sensitivity canalizing architectures than previously inferred; the enrichment increases with in-degree (Ghosh et al., 22 May 2026). This suggests that earlier null models understated the degree to which biological systems select stabilizing canalizing rules.

Several limitations are explicitly noted. Exhaustive attractor enumeration scales as $a \in \{0,1\}$2, so BoolForge relies on external specialized solvers for large networks (Kadelka et al., 2 Sep 2025). Uniform sampling within highly constrained classes is combinatorially nontrivial, and users are advised to verify the resulting distributions for the specific hypotheses they wish to test (Kadelka et al., 2 Sep 2025). The package is described as scaling well for wiring and rule generation to thousands of nodes, whereas tasks such as motif counting, modularity analysis, robustness curves, and coherence estimation benefit from sparse-graph algorithms or subsampling strategies (Kadelka et al., 2 Sep 2025).

Recommended use-cases follow directly from these strengths and limits: rapid prototyping of canalization-aware networks, ensemble-based hypothesis testing with structured null models, canalization audits of curated rules, motif and modularity analysis in gene regulatory networks, and export to PyBoolNet or CANA for attractor analysis and visualization (Kadelka et al., 2 Sep 2025). Future extensions proposed in the 2025 description include richer random graph models, multi-valued logical rules, additional update schemes, and deeper integration with SAT/BDD solvers for direct attractor computation within BoolForge itself (Kadelka et al., 2 Sep 2025).