---
title: 'BoolForge: Canalization-Aware Boolean Toolbox'
url: https://www.emergentmind.com/topics/boolforge
type: topic
---

# BoolForge: Canalization-Aware Boolean Toolbox

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 [2509.02496]. 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 [2606.05196].

## 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 [2509.02496].

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 [2509.02496].

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 [2606.05196].

## 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]` [2509.02496]. The total number of distinct Boolean functions on $n$ variables is $2^{2^n}$ [2509.02496].

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 [2509.02496; 2606.05196]. More generally, a function is $k$-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 [2606.05196]. The canalizing depth is the maximal such $k$ [2509.02496].

The distinction between exact and minimal depth is operationally important in BoolForge’s samplers. “Exact depth $k$” means that the canalizing depth equals $k$, whereas “minimal depth $k$” means the function has depth at least $k$ [2606.05196]. Nested canalizing functions (NCFs) are the special case with full depth $n$, while partially nested canalizing functions (PNCFs) have depth $k<n$ [2509.02496].

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 $\lambda=(k_1,\ldots,k_r)$ of positive integers summing to the canalizing depth, where each $k_j$ is the size of a layer and $r$ is the number of constant runs in the canalized-output sequence [2606.05196]. In the 2025 BoolForge description, this structure is connected to the extended monomial form, which reveals layers through products of terms $(x_i \oplus a_i)$ nested over layers in $GF(2)$ around a non-canalizing core [2509.02496].

Influence and sensitivity provide the main function-level dynamical proxies. For variable $i$, the influence is
$$
I_i(f)=\Pr_x[f(x)\neq f(x^{(i)})],
$$
where $x^{(i)}$ is obtained by flipping the $i$-th bit of $x$ [2509.02496]. The average sensitivity is
$$
s(f)=\sum_{i=1}^n I_i(f),
$$
equivalently the expected pointwise sensitivity over the hypercube [2509.02496; 2606.05196]. BoolForge’s scientific premise is that canalization tends to reduce influences and average sensitivity, thereby contributing to robustness [2509.02496].

## 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 [2509.02496]. 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` [2509.02496]. The authors state that it will be maintained for at least two years following publication [2509.02496].

Its API is organized around two core classes: `BooleanFunction` and `BooleanNetwork` [2509.02496]. `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 [2509.02496]. `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 [2509.02496].

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 [2509.02496]. 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 [2509.02496].

## 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 [2509.02496]. 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 $n$, the desired canalizing depth $k$, 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 $(x_i \oplus a_i)$ terms [2509.02496]. According to the description, this yields exact-depth-$k$ PNCFs, NCFs, and arbitrary layer structures, and can be uniform within the specified class when literature-based enumerations are used [2509.02496].

Network generation is organized in two stages. First, BoolForge constructs a wiring diagram for $N$ 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 [2509.02496]. 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 [2509.02496].

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 [2509.02496]. 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 [2606.05196]. 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 [2606.05196].

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 $\lambda=(k_1,\ldots,k_r)$ is
$$
\omega(\lambda):=\frac{1}{\prod_{j=1}^r k_j!},
$$
and the number of distinct functions with a given layer structure is proportional to this weight [2606.05196]. The sampler therefore generates the layer structure with probability proportional to $\omega(\lambda)$, then samples canalizing inputs, a variable order, and a non-canalizing core uniformly in a way that preserves uniformity over distinct functions [2606.05196].

The dynamic-programming construction is expressed in terms of a state $(m,s)$, where $m$ is the number of canalized outputs still to assign and $s$ is the size of the current open layer. The total remaining weight satisfies
$$
W(m,s)=W(m-1,s+1)+\frac{1}{s!}W(m-1,1),
$$
with boundary condition $W(0,s)=1/s!$, and for NCFs $W(0,1)=0$ because the final layer cannot be a singleton [2606.05196]. 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 $\omega(\lambda)$ [2606.05196].

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 $1/N_{\text{over}}$, where
$$
N_{\text{over}}=\binom{k_r+k_{\text{core}}}{k_r},
$$
and otherwise the sample is rejected and regenerated [2606.05196]. The 2026 paper states that the dynamic-programming weights can be precomputed in $O(n^2)$, sampling a single layer structure is $O(n)$, and the rejection probability is modest; for $n-k=2$, it is $5/8$, and it decreases exponentially as $n-k$ grows because canalizing cores become rare [2606.05196].

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 [2509.02496]. 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 [2509.02496]. 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 [2509.02496].

Robustness is treated in several related ways. At the function level, BoolForge computes sensitivity $s(f)$. At the network level, it supports ensemble-based robustness tests such as empirical estimation of the Derrida curve,
$$
D(p)=E[d(F(x),F(y))/N \mid d(x,y)=\lfloor pN \rfloor],
$$
where $d(\cdot,\cdot)$ is Hamming distance [2509.02496]. The description notes that networks “far from the edge of chaos” have $D(p)<p$ for small $p$, indicating contraction of perturbations [2509.02496]. 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 [2509.02496].

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 [2509.02496]. Motif detection uses standard subgraph search on the directed wiring graph to identify feed-forward loops, feedback loops, and related motifs [2509.02496].

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 [2509.02496].

## 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 [2509.02496]. 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 [2509.02496].

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 $E[s(f)]=1$ for all $n$, whereas under function-uniform sampling it increases with $n$ and numerically approaches approximately $1.183$ [2606.05196]. The paper attributes this discrepancy to exponential suppression of high-sensitivity functions under parameter-based sampling [2606.05196]. It further reports that, in random networks of $N=12$ nodes with constant in-degree $n \in \{2,3,4,5,6\}$ 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 [2606.05196]. These differences are interpreted as artifacts of biased overrepresentation of low-sensitivity rules in parameter-uniform sampling [2606.05196].

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 [2606.05196]. 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 $O(2^N)$, so BoolForge relies on external specialized solvers for large networks [2509.02496]. 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 [2509.02496]. 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 [2509.02496].

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 [2509.02496]. 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 [2509.02496].

Source: https://www.emergentmind.com/topics/boolforge