boofun.api

API module providing user-friendly entry points for creating Boolean functions.

This module provides the main create function that serves as the primary interface for users to create Boolean function objects from various data sources.

Also provides: - partial(): Create partial Boolean functions for streaming/incremental specification - from_hex(): Create from hex string truth table (thomasarmel-compatible) - Storage hints: storage=’packed’, storage=’sparse’, storage=’lazy’

Functions

`create`([data, storage])	Create a Boolean function from various data sources.
`from_hex`(hex_str, n, *[, storage])	Create a Boolean function from a hexadecimal truth table string.
`partial`(n[, known_values, name])	Create a partial Boolean function with incremental/streaming support.
`to_hex`(f)	Export a Boolean function to a hexadecimal truth table string.

boofun.api.create(data=None, storage: str = 'auto', **kwargs)[source]

Create a Boolean function from various data sources.

This is the main entry point for creating Boolean functions. It accepts truth tables, functions, distributions, and other representations.

Parameters:

data – Input data for the Boolean function. Can be: - List/array of boolean values (truth table) - Callable function - Dict (polynomial coefficients) - None (creates empty function)
storage – Storage strategy hint: - ‘auto’: Automatically select best representation (default) - ‘dense’: Use dense truth table (fast for n <= 14) - ‘packed’: Use 1-bit per entry (good for n > 14) - ‘sparse’: Store only exceptions (good for skewed functions) - ‘lazy’: Never materialize, compute on demand (for oracles)
**kwargs – Additional arguments: - n: Number of variables (auto-detected if not provided) - space: Mathematical space (default: BOOLEAN_CUBE) - rep_type: Representation type override

Returns:

A Boolean function object

Return type:

BooleanFunction

Examples

>>> # Create XOR function from truth table
>>> xor = create([0, 1, 1, 0])

>>> # Create majority function
>>> maj = create(lambda x: sum(x) > len(x)//2, n=3)

>>> # Create with storage hint for large function
>>> f = create(truth_table, storage='packed')

>>> # Create lazy function that computes on demand
>>> f = create(oracle_func, n=20, storage='lazy')

>>> # Create from polynomial coefficients
>>> poly = create({frozenset([0]): 1, frozenset([1]): 1}, rep_type='polynomial')

boofun.api.partial(n: int, known_values: Dict[int, bool] | None = None, name: str | None = None) → PartialBooleanFunction[source]

Create a partial Boolean function with incremental/streaming support.

A partial function allows you to specify only some outputs, useful for: - Streaming data: adding function values incrementally - Sampling: knowing only a subset of outputs - Large functions: working with sections without full materialization

Parameters:

n – Number of input variables (determines domain size 2^n)
known_values – Optional dictionary mapping input indices to output values
name – Optional name for the function

Returns:

PartialBooleanFunction instance

Examples

>>> import boofun as bf
>>>
>>> # Create empty partial function
>>> p = bf.partial(n=20)
>>>
>>> # With initial values
>>> p = bf.partial(n=20, known_values={0: True, 1: False, 7: True})
>>>
>>> # Add more values incrementally
>>> p.add(5, False)
>>> p.add_batch({10: True, 11: True, 12: False})
>>>
>>> # Check status
>>> p.completeness  # Fraction known
>>> p.num_known  # Count of known values
>>>
>>> # Evaluate
>>> p.evaluate(0)  # True (known)
>>> p.evaluate(100)  # None (unknown)
>>> p[0]  # Indexing syntax also works
>>>
>>> # Estimate unknown values
>>> val, conf = p.evaluate_with_confidence(100)
>>>
>>> # Convert to full function when ready
>>> f = p.to_function(fill_unknown=False)

boofun.api.from_hex(hex_str: str, n: int, *, storage: str = 'auto', **kwargs) → BooleanFunction[source]

Create a Boolean function from a hexadecimal truth table string.

This is compatible with thomasarmel/boolean_function’s format where the truth table is represented as a hex string.

Parameters:

hex_str – Hexadecimal string (with or without ‘0x’ prefix)
n – Number of input variables
storage – Storage strategy hint (‘auto’, ‘dense’, ‘packed’, ‘sparse’)
**kwargs – Additional arguments passed to create()

Returns:

BooleanFunction instance

Examples

>>> import boofun as bf
>>>
>>> # From thomasarmel example - 4-bit bent function
>>> f = bf.from_hex("0xac90", n=4)
>>> f.is_bent()  # True
>>>
>>> # 6-bit function
>>> f = bf.from_hex("0113077C165E76A8", n=6)
>>>
>>> # Export back to hex
>>> f.to_hex()

Cross-validation:: This format is compatible with thomasarmel/boolean_function: - BooleanFunction::from_hex_string_truth_table(“0113077C165E76A8”) - SmallBooleanFunction::from_truth_table(0xac90, 4)

boofun.api.to_hex(f: BooleanFunction) → str[source]

Export a Boolean function to a hexadecimal truth table string.

This produces output compatible with thomasarmel/boolean_function format.

Parameters:: f – BooleanFunction to export
Returns:: Hexadecimal string representation of the truth table

Examples

>>> import boofun as bf
>>>
>>> f = bf.from_hex("ac90", n=4)
>>> bf.to_hex(f)
'ac90'