boofun.core.partial

Partial Boolean functions for streaming and incremental specification.

This module provides user-friendly classes for working with Boolean functions where only some outputs are known. This is useful for: - Streaming data: adding function values incrementally - Sampling: knowing only a subset of outputs - Large functions: avoiding full materialization - Studying sections of very large objects

Example

>>> import boofun as bf
>>>
>>> # Create partial function with some known values
>>> partial = bf.partial(n=20, known_values={0: True, 1: False, 7: True})
>>>
>>> # Add more values incrementally
>>> partial.add(5, False)
>>> partial.add_batch({10: True, 11: True})
>>>
>>> # Query status
>>> partial.completeness  # Very small fraction
>>> partial.num_known  # 6
>>>
>>> # Evaluate known and unknown points
>>> partial.evaluate(0)  # True (known)
>>> partial.evaluate(100)  # None (unknown)
>>>
>>> # Get estimate with confidence for unknown
>>> val, conf = partial.evaluate_with_confidence(100)
>>>
>>> # Convert to full function when ready
>>> f = partial.to_function(fill_unknown=False)

Cross-validation:

This design is inspired by thomasarmel/boolean_function’s partial representation capabilities, adapted for Python’s streaming/incremental use cases.

Functions

partial(n[, known_values, name])

Create a partial Boolean function.

Classes

PartialBooleanFunction(n_vars[, ...])

A Boolean function with partial/incomplete specification.

class boofun.core.partial.PartialBooleanFunction(n_vars: int, known_values: Dict[int, bool] | None = None, name: str | None = None)

A Boolean function with partial/incomplete specification.

This class wraps PartialRepresentation to provide a user-friendly interface for working with Boolean functions where only some outputs are known.

Key features: - Incremental value addition (streaming) - Completeness tracking - Confidence-based estimation for unknown values - Conversion to full BooleanFunction when complete

n_vars

Number of input variables

size

Total number of possible inputs (2^n_vars)

completeness

Fraction of known values (0.0 to 1.0)

num_known

Count of known values

num_unknown

Count of unknown values

Example

>>> partial = PartialBooleanFunction(n_vars=10)
>>> partial.add(0, True)
>>> partial.add(1, False)
>>> partial.completeness
0.001953125  # 2/1024

__init__(n_vars: int, known_values: Dict[int, bool] | None = None, name: str | None = None)

Initialize a partial Boolean function.

Parameters:

• n_vars – Number of input variables (determines domain size 2^n_vars)

• known_values – Optional dictionary mapping input indices to output values

• name – Optional name for the function

Raises:

ValueError – If n_vars < 0 or n_vars > 30

property n_vars: int

Number of input variables.

property size: int

Total number of possible inputs (2^n_vars).

property completeness: float

Fraction of values that are known (0.0 to 1.0).

property num_known: int

Number of known values.

property num_unknown: int

Number of unknown values.

property is_complete: bool

Check if all values are known.

property name: str | None

Optional name for this function.

add(idx: int, value: bool) → None

Add a known value at a specific input index.

Parameters:

• idx – Input index (0 to size-1)

• value – Output value at this input

Raises:

IndexError – If idx is out of range

Example

>>> partial.add(5, True)
>>> partial.is_known(5)
True

add_batch(values: Dict[int, bool]) → None

Add multiple known values at once.

Parameters:

values – Dictionary mapping input indices to output values

Raises:

IndexError – If any index is out of range

Example

>>> partial.add_batch({0: True, 1: False, 7: True})

add_from_samples(inputs: ndarray, outputs: ndarray) → None

Add values from arrays of inputs and outputs.

Parameters:

• inputs – Array of input indices or binary vectors

• outputs – Array of corresponding output values

Example

>>> inputs = np.array([0, 1, 2, 3])
>>> outputs = np.array([True, False, False, True])
>>> partial.add_from_samples(inputs, outputs)

is_known(idx: int) → bool

Check if a specific input’s output is known.

Parameters:

idx – Input index

Returns:

True if the output at this index is known

evaluate(idx: int) → bool | None

Evaluate the function at a specific input.

Parameters:

idx – Input index

Returns:

The output value if known, None if unknown

Example

>>> partial.add(5, True)
>>> partial.evaluate(5)
True
>>> partial.evaluate(6)
None

evaluate_with_confidence(idx: int) → Tuple[bool, float]

Evaluate with confidence estimate for unknown values.

For known values, returns (value, 1.0). For unknown values, estimates based on Hamming neighbors.

Parameters:

idx – Input index

Returns:

Tuple of (estimated_value, confidence) - confidence is 1.0 for known values - confidence < 1.0 for estimated values

Example

>>> partial.add(0, True)
>>> partial.add(2, True)
>>> val, conf = partial.evaluate_with_confidence(1)
>>> # val might be True (neighbors are True), conf < 1.0

get_known_indices() → ndarray

Get indices of all known values.

Returns:

Array of input indices where output is known

get_unknown_indices() → ndarray

Get indices of all unknown values.

Returns:

Array of input indices where output is unknown

get_known_values() → Dict[int, bool]

Get dictionary of all known (index, value) pairs.

Returns:

Dictionary mapping known indices to their values

to_function(fill_unknown: bool = False, estimate_unknown: bool = False) → BooleanFunction

Convert to a full BooleanFunction.

Parameters:

• fill_unknown – Value to use for unknown entries (default False)

• estimate_unknown – If True, estimate unknown values using neighbors

Returns:

Complete BooleanFunction

Raises:

ValueError – If not complete and neither fill_unknown nor estimate_unknown

Example

>>> partial = bf.partial(n=2, known_values={0: True, 1: False, 2: False, 3: True})
>>> f = partial.to_function()  # Complete, so this works

to_dense_array(fill_value: bool = False) → ndarray

Convert to dense numpy array, filling unknown with specified value.

Parameters:

fill_value – Value to use for unknown entries

Returns:

Boolean numpy array of shape (2^n_vars,)

sample_unknown(n_samples: int = 1, seed: int | None = None) → ndarray

Randomly sample from unknown indices.

Useful for active learning or guided sampling.

Parameters:

• n_samples – Number of indices to sample

• seed – Random seed for reproducibility

Returns:

Array of sampled unknown indices

summary() → str

Return human-readable summary of the partial function.

Returns:

Multi-line summary string

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

Create a partial Boolean function.

This is the main factory function for creating partial functions where only some outputs are known.

Parameters:

• n – Number of input variables

• known_values – Optional dictionary mapping input indices to output values

• name – Optional name for the function

Returns:

PartialBooleanFunction instance

Example

>>> import boofun as bf
>>>
>>> # Empty partial function
>>> p = bf.partial(n=10)
>>>
>>> # With initial values
>>> p = bf.partial(n=10, known_values={0: True, 1: False})
>>>
>>> # Add more values
>>> p.add(5, True)
>>> p.completeness