# aigverse.utils

Provides utility data structures and functions.

## Module Contents

### *class* TruthTable(num_vars: [int](https://docs.python.org/3/builtins/functions.html#int))

Represents a dynamic Boolean truth table.

#### \_\_eq_\_(other: [object](https://docs.python.org/3/builtins/functions.html#object)) → [bool](https://docs.python.org/3/builtins/functions.html#bool)

Checks equality with another truth table.

#### \_\_ne_\_(other: [object](https://docs.python.org/3/builtins/functions.html#object)) → [bool](https://docs.python.org/3/builtins/functions.html#bool)

Checks inequality with another truth table.

#### \_\_lt_\_(other: [TruthTable](#aigverse.utils.TruthTable)) → [bool](https://docs.python.org/3/builtins/functions.html#bool)

Lexicographically compares two truth tables.

#### \_\_and_\_(other: [TruthTable](#aigverse.utils.TruthTable)) → [TruthTable](#aigverse.utils.TruthTable)

Computes bitwise AND with another truth table.

#### \_\_or_\_(other: [TruthTable](#aigverse.utils.TruthTable)) → [TruthTable](#aigverse.utils.TruthTable)

Computes bitwise OR with another truth table.

#### \_\_xor_\_(other: [TruthTable](#aigverse.utils.TruthTable)) → [TruthTable](#aigverse.utils.TruthTable)

Computes bitwise XOR with another truth table.

#### \_\_invert_\_() → [TruthTable](#aigverse.utils.TruthTable)

Computes bitwise NOT.

#### \_\_len_\_() → [int](https://docs.python.org/3/builtins/functions.html#int)

Returns the number of bits.

#### \_\_getitem_\_(index: [int](https://docs.python.org/3/builtins/functions.html#int)) → [bool](https://docs.python.org/3/builtins/functions.html#bool)

Returns one bit by index.

* **Parameters:**
  **index** – Bit index.
* **Returns:**
  The bit value.
* **Raises:**
  [**IndexError**](https://docs.python.org/3/builtins/exceptions.html#IndexError) – If `index` is out of range.

#### \_\_setitem_\_(index: [int](https://docs.python.org/3/builtins/functions.html#int), value: [bool](https://docs.python.org/3/builtins/functions.html#bool)) → [None](https://docs.python.org/3/builtins/constants.html#None)

Sets one bit by index.

* **Parameters:**
  * **index** – Bit index.
  * **value** – New bit value.
* **Raises:**
  [**IndexError**](https://docs.python.org/3/builtins/exceptions.html#IndexError) – If `index` is out of range.

#### \_\_iter_\_() → [Iterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterator)[[bool](https://docs.python.org/3/builtins/functions.html#bool)]

Returns an iterator over all bits.

#### num_vars() → [int](https://docs.python.org/3/builtins/functions.html#int)

Returns the number of variables.

#### num_blocks() → [int](https://docs.python.org/3/builtins/functions.html#int)

Returns the number of storage blocks.

#### num_bits() → [int](https://docs.python.org/3/builtins/functions.html#int)

Returns the number of truth table bits.

#### \_\_copy_\_() → [TruthTable](#aigverse.utils.TruthTable)

Returns a shallow copy of the truth table.

#### \_\_deepcopy_\_(arg: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict),)  → [TruthTable](#aigverse.utils.TruthTable)

Returns a deep copy of the truth table.

#### \_\_assign_\_(other: [TruthTable](#aigverse.utils.TruthTable)) → [TruthTable](#aigverse.utils.TruthTable)

Assigns from another truth table with a compatible shape.

* **Parameters:**
  **other** – Source truth table.
* **Returns:**
  The updated truth table.

#### \_\_hash_\_() → [int](https://docs.python.org/3/builtins/functions.html#int)

Returns a hash value for dictionary/set usage.

#### \_\_getstate_\_() → [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)

Returns pickle state as `(num_vars, words)`.

#### \_\_setstate_\_(state: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)) → [None](https://docs.python.org/3/builtins/constants.html#None)

Restores a truth table from pickle state.

* **Parameters:**
  **state** – Tuple `(num_vars, words)`.
* **Raises:**
  * [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) – If the serialized state is malformed.
  * [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – If nanobind cannot convert the pickle payload to the expected C++ types.

#### set_bit(index: [int](https://docs.python.org/3/builtins/functions.html#int)) → [None](https://docs.python.org/3/builtins/constants.html#None)

Sets one bit to `1`.

* **Parameters:**
  **index** – Bit index.
* **Raises:**
  [**IndexError**](https://docs.python.org/3/builtins/exceptions.html#IndexError) – If `index` is out of range.

#### get_bit(index: [int](https://docs.python.org/3/builtins/functions.html#int)) → [bool](https://docs.python.org/3/builtins/functions.html#bool)

Returns one bit value.

* **Parameters:**
  **index** – Bit index.
* **Returns:**
  The bit value.
* **Raises:**
  [**IndexError**](https://docs.python.org/3/builtins/exceptions.html#IndexError) – If `index` is out of range.

#### clear_bit(index: [int](https://docs.python.org/3/builtins/functions.html#int)) → [None](https://docs.python.org/3/builtins/constants.html#None)

Clears one bit to `0`.

* **Parameters:**
  **index** – Bit index.
* **Raises:**
  [**IndexError**](https://docs.python.org/3/builtins/exceptions.html#IndexError) – If `index` is out of range.

#### flip_bit(index: [int](https://docs.python.org/3/builtins/functions.html#int)) → [None](https://docs.python.org/3/builtins/constants.html#None)

Toggles one bit value.

* **Parameters:**
  **index** – Bit index.
* **Raises:**
  [**IndexError**](https://docs.python.org/3/builtins/exceptions.html#IndexError) – If `index` is out of range.

#### get_block(block_index: [int](https://docs.python.org/3/builtins/functions.html#int)) → [int](https://docs.python.org/3/builtins/functions.html#int)

Returns one 64-bit storage block.

* **Parameters:**
  **block_index** – Block index.
* **Returns:**
  The block value.
* **Raises:**
  [**IndexError**](https://docs.python.org/3/builtins/exceptions.html#IndexError) – If `block_index` is out of range.

#### create_nth_var(var_index: [int](https://docs.python.org/3/builtins/functions.html#int), complement: [bool](https://docs.python.org/3/builtins/functions.html#bool) = False) → [None](https://docs.python.org/3/builtins/constants.html#None)

Creates the projection function for one variable.

* **Parameters:**
  * **var_index** – Variable index to project.
  * **complement** – Whether to complement the projection.
* **Raises:**
  [**IndexError**](https://docs.python.org/3/builtins/exceptions.html#IndexError) – If `var_index` is out of range.

#### create_from_binary_string(binary: [str](https://docs.python.org/3/builtins/stdtypes.html#str)) → [None](https://docs.python.org/3/builtins/constants.html#None)

Loads bit values from a binary string.

* **Parameters:**
  **binary** – Binary string of length `num_bits`.
* **Raises:**
  [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If the string length does not match `num_bits`.

#### create_from_hex_string(hexadecimal: [str](https://docs.python.org/3/builtins/stdtypes.html#str)) → [None](https://docs.python.org/3/builtins/constants.html#None)

Loads bit values from a hexadecimal string.

* **Parameters:**
  **hexadecimal** – Hex string matching the truth table size.
* **Raises:**
  [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If the string length does not match the expected size.

#### create_random() → [None](https://docs.python.org/3/builtins/constants.html#None)

Fills the truth table with random bits.

#### create_majority() → [None](https://docs.python.org/3/builtins/constants.html#None)

Fills the truth table with the majority function.

#### clear() → [None](https://docs.python.org/3/builtins/constants.html#None)

Clears all bits to `0`.

#### count_ones() → [int](https://docs.python.org/3/builtins/functions.html#int)

Returns the number of set bits.

#### count_zeroes() → [int](https://docs.python.org/3/builtins/functions.html#int)

Returns the number of cleared bits.

#### is_const0() → [bool](https://docs.python.org/3/builtins/functions.html#bool)

Returns whether all bits are `0`.

#### is_const1() → [bool](https://docs.python.org/3/builtins/functions.html#bool)

Returns whether all bits are `1`.

#### to_binary() → [str](https://docs.python.org/3/builtins/stdtypes.html#str)

Returns the truth table as a binary string.

#### to_hex() → [str](https://docs.python.org/3/builtins/stdtypes.html#str)

Returns the truth table as a hexadecimal string.

### ternary_majority(a: [TruthTable](#aigverse.utils.TruthTable), b: [TruthTable](#aigverse.utils.TruthTable), c: [TruthTable](#aigverse.utils.TruthTable)) → [TruthTable](#aigverse.utils.TruthTable)

Computes the ternary majority of three truth tables.

* **Parameters:**
  * **a** – First truth table.
  * **b** – Second truth table.
  * **c** – Third truth table.
* **Returns:**
  The bitwise majority truth table.

### cofactor0(tt: [TruthTable](#aigverse.utils.TruthTable), var_index: [int](https://docs.python.org/3/builtins/functions.html#int)) → [TruthTable](#aigverse.utils.TruthTable)

Computes the cofactor with respect to assigning one variable to `0`.

* **Parameters:**
  * **tt** – Input truth table.
  * **var_index** – Index of the variable to cofactor.
* **Returns:**
  The cofactored truth table with `var_index` fixed to `0`.
* **Raises:**
  [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If `var_index` is out of range.

### cofactor1(tt: [TruthTable](#aigverse.utils.TruthTable), var_index: [int](https://docs.python.org/3/builtins/functions.html#int)) → [TruthTable](#aigverse.utils.TruthTable)

Computes the cofactor with respect to assigning one variable to `1`.

* **Parameters:**
  * **tt** – Input truth table.
  * **var_index** – Index of the variable to cofactor.
* **Returns:**
  The cofactored truth table with `var_index` fixed to `1`.
* **Raises:**
  [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If `var_index` is out of range.