<p align="center">
  <img src="logos/boo_horizontal.png" alt="BooFun Logo" width="800"/>
</p>

<p align="center">
  <strong>Boolean Function Analysis in Python</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/boofun/"><img src="https://img.shields.io/pypi/v/boofun.svg" alt="PyPI version"></a>
  <a href="https://pypi.org/project/boofun/"><img src="https://img.shields.io/pypi/dm/boofun" alt="PyPI Downloads"></a>
  <a href="https://github.com/GabbyTab/boofun/blob/main/pyproject.toml"><img src="https://img.shields.io/badge/python-3.8%2B-blue.svg" alt="Python 3.8+"></a>
  <a href="https://github.com/GabbyTab/boofun/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License"></a>
  <a href="https://gabbytab.github.io/boofun/"><img src="https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg" alt="Documentation"></a>
  <a href="https://codecov.io/gh/GabbyTab/boofun"><img src="https://codecov.io/gh/GabbyTab/boofun/branch/main/graph/badge.svg" alt="codecov"></a>
  <a href="https://github.com/GabbyTab/boofun"><img src="https://img.shields.io/badge/typed-mypy-blue.svg" alt="Typed"></a>
</p>

## What This Is

A toolkit for teaching, learning, and doing research in Boolean function analysis. Fourier analysis, property testing, query complexity, hypercontractivity, pseudorandomness, and more -- with 23 interactive notebooks aligned to O'Donnell's *Analysis of Boolean Functions*.

Built at UC Berkeley alongside Avishay Tal's [CS 294-92](https://www2.eecs.berkeley.edu/Faculty/Homepages/atal.html). Cross-validated against SageMath, Tal's toolkit, and known closed-form results.

```python
import boofun as bf

# Create functions, compute properties
maj = bf.majority(5)
maj.fourier()           # Fourier coefficients
maj.influences()        # Per-variable influences
maj.total_influence()   # I[f]
maj.noise_stability(0.9)

# Query complexity
from boofun.analysis import complexity
complexity.D(maj)       # Decision tree depth
complexity.s(maj)       # Max sensitivity
```

**[Try it in Colab](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/lecture3_social_choice_influences.ipynb)** | **[All 23 Notebooks](#course-notebooks)** | **[Full Docs](https://gabbytab.github.io/boofun/)**

## Installation

```bash
pip install boofun
```

Or run notebooks in Docker:
```bash
docker-compose up notebook  # localhost:8888, token: boofun
```

## Quick Start

```python
import boofun as bf

# Create functions
maj_5 = bf.majority(5)
xor_2 = bf.create([0, 1, 1, 0])

# Evaluate (callable syntax)
maj_5([1, 1, 0, 0, 1])  # → True (majority satisfied)
maj_5(7)                # → True (7 = 00111 in binary, 3 ones)

# Fourier analysis
maj_5.fourier()           # Fourier coefficients
maj_5.influences()        # Per-variable influences
maj_5.total_influence()   # I[f]
maj_5.noise_stability(0.9)

# Properties and complexity
maj_5.is_monotone()
maj_5.is_balanced()

from boofun.analysis import complexity
complexity.D(maj_5)  # Decision tree depth D(f)
complexity.s(maj_5)  # Max sensitivity s(f)

# Full analysis
maj_5.analyze()  # dict with all metrics
```

## Features

| Category | What's Included |
|----------|-----------------|
| **Built-in Functions** | Majority, Parity, AND, OR, Tribes, Threshold, Dictator, weighted LTF, random |
| **Representations** | Truth tables (dense/sparse/packed), Fourier, ANF, DNF/CNF, BDD, circuits, LTF |
| **Fourier Analysis** | WHT, influences, noise stability, spectral concentration, p-biased analysis |
| **Query Complexity** | D(f), R(f), Q(f), sensitivity, block sensitivity, certificates, Ambainis bound |
| **Property Testing** | BLR linearity, junta, monotonicity, symmetry, balance |
| **Hypercontractivity** | Noise operator, Bonami's Lemma, KKL theorem, Friedgut's junta theorem |
| **Learning Theory** | Goldreich-Levin, PAC learning, junta learning, LMN algorithm |
| **Cryptographic** | Nonlinearity, bent functions, Walsh spectrum, LAT/DDT, S-box analysis |
| **Advanced** | Gaussian analysis, invariance principle, communication complexity, LTF analysis |
| **Visualization** | Influence plots, Fourier spectrum, truth table heatmaps, decision trees |

## Guides

Detailed documentation for each topic:

- **[Spectral Analysis](https://gabbytab.github.io/boofun/guides/spectral_analysis.html)**: Fourier, influences, p-biased, sensitivity, sampling
- **[Query Complexity](https://gabbytab.github.io/boofun/guides/query_complexity.html)**: D/R/Q, certificates, decision trees, Huang's theorem
- **[Hypercontractivity](https://gabbytab.github.io/boofun/guides/hypercontractivity.html)**: KKL, Bonami, Friedgut, global hypercontractivity
- **[Learning Theory](https://gabbytab.github.io/boofun/guides/learning.html)**: Goldreich-Levin, PAC learning, junta learning, LMN
- **[Cryptographic Analysis](https://gabbytab.github.io/boofun/guides/cryptographic.html)**: Nonlinearity, bent, LAT/DDT, S-box
- **[Probabilistic View](https://gabbytab.github.io/boofun/guides/probabilistic.html)**: Random variables, p-biased measures, estimation, pseudorandomness
- **[Representations](https://gabbytab.github.io/boofun/guides/representations.html)**: All formats, conversion graph, storage hints
- **[Operations](https://gabbytab.github.io/boofun/guides/operations.html)**: Boolean operators, composition, restriction, permutation
- **[Advanced Topics](https://gabbytab.github.io/boofun/guides/advanced.html)**: Gaussian, invariance, communication complexity, LTF, restrictions

## Flexible Input

```python
bf.create([0, 1, 1, 0])              # List → truth table
bf.create(lambda x: x[0] ^ x[1], n=2) # Callable
bf.create("x0 and not x1", n=2)      # String → symbolic
bf.load("function.cnf")              # DIMACS CNF
```

## Built-in Functions

`majority(n)`, `parity(n)`, `tribes(k, n)`, `threshold(n, k)`, `AND(n)`, `OR(n)`, `dictator(n, i)`, `weighted_majority(weights)`, `random(n)`

## Examples

| File | Topic |
|------|-------|
| `01_getting_started.py` | Basics |
| `02_fourier_basics.py` | WHT, Parseval |
| `03_common_families.py` | Majority, Parity, Tribes |
| `04_property_testing.py` | BLR, junta tests |
| `05_query_complexity.py` | Sensitivity, certificates |

## Course Notebooks

Computational companion to O'Donnell's *Analysis of Boolean Functions*, following Avishay Tal's CS 294-92. Each notebook makes the theorems runnable so the focus stays on the math. Click **Scribe** for lecture notes, **Topic** to view the static notebook, or **Play** to run in Colab.

<details>
<summary><strong>Lecture Notebooks (11)</strong></summary>

| Lecture | Scribe | Topic | Play |
|---------|--------|-------|------|
| 1 | [Joyce Lu](https://drive.google.com/file/d/1hL9brxvBAfJf8TlDf6v1OthrUamwmMAF/view?usp=share_link) | [Fourier Expansion](https://gabbytab.github.io/boofun/notebooks/lecture1_fourier_expansion.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/lecture1_fourier_expansion.ipynb) |
| 2 | [Austin Pechan](https://drive.google.com/file/d/1ik5EzybeJiOAaS7R7tjV9R6AFgeKcCf-/view?usp=share_link) | [Linearity Testing](https://gabbytab.github.io/boofun/notebooks/lecture2_linearity_testing.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/lecture2_linearity_testing.ipynb) |
| 3 | [Vivien Goyal](https://drive.google.com/file/d/1-NYv-8OeHUuU7v8NPMi6kpw5Baszw0Ss/view?usp=share_link) | [Social Choice & Influences](https://gabbytab.github.io/boofun/notebooks/lecture3_social_choice_influences.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/lecture3_social_choice_influences.ipynb) |
| 4 | [Patrick Bales](https://drive.google.com/file/d/1YYUHu6tz7eJghUzQIqanbGSZRQCEi015/view) | [Influences & Effects](https://gabbytab.github.io/boofun/notebooks/lecture4_influences_effects.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/lecture4_influences_effects.ipynb) |
| 5 | [Prastik Mohanraj](https://drive.google.com/file/d/1PIRoYDpXRd1F48fsyutyBFR_URrMMWnh/view?usp=sharing) | [Noise Stability](https://gabbytab.github.io/boofun/notebooks/lecture5_noise_stability.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/lecture5_noise_stability.ipynb) |
| 6 | *(upcoming)* | [Spectral Concentration](https://gabbytab.github.io/boofun/notebooks/lecture6_spectral_concentration.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/lecture6_spectral_concentration.ipynb) |
| 7 | [Thomas Culhane](https://drive.google.com/file/d/1aGxilyDayIcPMB6TjfqmswhHqzFUj1ac/view?usp=sharing) | [Goldreich-Levin](https://gabbytab.github.io/boofun/notebooks/lecture7_goldreich_levin.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/lecture7_goldreich_levin.ipynb) |
| 8 | [Timothe Kasriel](https://drive.google.com/file/d/1yaEXw3GDMCUrRhR8aODDjQaSl-djNae6/view?usp=sharing) | [Learning Juntas](https://gabbytab.github.io/boofun/notebooks/lecture8_learning_juntas.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/lecture8_learning_juntas.ipynb) |
| 9 | [Qinggao Hong](https://drive.google.com/file/d/1pf6IS695K3EvytBzw58baHxgA0rfWhew/view?usp=sharing) | [DNFs & Restrictions](https://gabbytab.github.io/boofun/notebooks/lecture9_dnf_restrictions.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/lecture9_dnf_restrictions.ipynb) |
| 10 | [Lucas Ericsson](https://drive.google.com/file/d/1pEuaXd0JoiD_S4b6OLJgdsKyYlrANie5/view?usp=share_link) | [Fourier Concentration](https://gabbytab.github.io/boofun/notebooks/lecture10_fourier_concentration.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/lecture10_fourier_concentration.ipynb) |
| 11 | [Thapen](http://users.math.cas.cz/~thapen/switching.pdf) | [Invariance Principle](https://gabbytab.github.io/boofun/notebooks/lecture11_invariance_principle.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/lecture11_invariance_principle.ipynb) |

</details>

<details>
<summary><strong>Homework Notebooks (4)</strong></summary>

| HW | Topic | Play |
|----|-------|------|
| 1 | [Fourier Expansion](https://gabbytab.github.io/boofun/notebooks/hw1_fourier_expansion.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/hw1_fourier_expansion.ipynb) |
| 2 | [LTFs & Decision Trees](https://gabbytab.github.io/boofun/notebooks/hw2_ltf_decision_trees.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/hw2_ltf_decision_trees.ipynb) |
| 3 | [DNFs & Restrictions](https://gabbytab.github.io/boofun/notebooks/hw3_dnf_restrictions.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/hw3_dnf_restrictions.ipynb) |
| 4 | [Hypercontractivity](https://gabbytab.github.io/boofun/notebooks/hw4_hypercontractivity.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/hw4_hypercontractivity.ipynb) |

</details>

<details>
<summary><strong>Supplementary Notebooks (8)</strong></summary>

| Topic | Description | Play |
|-------|-------------|------|
| [LTF Visualization](https://gabbytab.github.io/boofun/notebooks/ltf_visualization.html) | 3D hyperplane geometry, influences | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/ltf_visualization.ipynb) |
| [Global Hypercontractivity](https://gabbytab.github.io/boofun/notebooks/global_hypercontractivity.html) | Keevash et al. threshold phenomena | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/global_hypercontractivity.ipynb) |
| [Boolean Functions as Random Variables](https://gabbytab.github.io/boofun/notebooks/boolean_functions_as_random_variables.html) | P-biased measures, threshold curves, Russo | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/boolean_functions_as_random_variables.ipynb) |
| [Cryptographic Analysis](https://gabbytab.github.io/boofun/notebooks/cryptographic_analysis.html) | Walsh spectrum, nonlinearity, SAC | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/cryptographic_analysis.ipynb) |
| [Fractional PRGs](https://gabbytab.github.io/boofun/notebooks/fractional_prg.html) | Fourier tails, pseudorandomness (CHLT 2019) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/fractional_prg.ipynb) |
| [Flexible Inputs & Oracles](https://gabbytab.github.io/boofun/notebooks/flexible_inputs_and_oracles.html) | Input formats, lazy evaluation | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/flexible_inputs_and_oracles.ipynb) |
| [Real World Applications](https://gabbytab.github.io/boofun/notebooks/real_world_applications.html) | Cryptography, ML, voting | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/real_world_applications.ipynb) |
| [Asymptotic Visualization](https://gabbytab.github.io/boofun/notebooks/asymptotic_visualization.html) | Growth rates and scaling | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GabbyTab/boofun/blob/main/notebooks/asymptotic_visualization.ipynb) |

</details>

## Performance

- NumPy vectorization throughout (always on)
- Numba JIT for 2-10x speedups: `pip install boofun[performance]`
- CuPy GPU acceleration for large n: `pip install boofun[gpu]`
- Sparse/packed representations for memory efficiency
- Most operations complete in milliseconds for n ≤ 14

## Testing

```bash
pytest tests/
pytest --cov=boofun tests/
```

3200+ tests with 72% coverage. Cross-validation against known results in `tests/test_cross_validation.py`.

## Convention

O'Donnell standard: Boolean 0 → +1, Boolean 1 → −1. This ensures f̂(∅) = E[f].

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and test cases are especially valuable.

## Acknowledgments

- **[Avishay Tal](https://www2.eecs.berkeley.edu/Faculty/Homepages/atal.html)**: Course instructor, sensitivity analysis, p-biased measures, decision tree algorithms, Fourier analysis utilities. BooFun covers ~90% of Tal's `BooleanFunc.py` toolkit — see the [migration guide](https://gabbytab.github.io/boofun/guides/migration_from_tal.html) for a complete mapping
- **[Patrick Bales](https://www.linkedin.com/in/patrickbbales/)**: Course materials and notebook review
- **O'Donnell's *Analysis of Boolean Functions*** (Cambridge, 2014): Theoretical foundation
- **[Scott Aaronson](https://scottaaronson.blog/)'s Boolean Function Wizard** (2000): Query complexity foundations

## License

MIT. See [LICENSE](LICENSE).

## Citation

```bibtex
@software{boofun2026,
  title={BooFun: A Python Library for Boolean Function Analysis},
  author={Gabriel Taboada},
  year={2026},
  url={https://github.com/GabbyTab/boofun}
}
```

<p align="center">
  <img src="logos/boo_alt.png" alt="BooFun Logo" width="200"/>
</p>
