Utilities (puxle.utils)

Utility functions for bitpacking, image rendering, and visualization.

Utility functions and constants for PuXle puzzles.

This module provides helper functions, annotations, and common utilities used across puzzle implementations.

Bitpacking & Visualization

PuXle utilities.

Bitpacking note: - to_uint8 / from_uint8 and the variable-bit helpers are legacy utilities kept for

backwards compatibility and generic packing needs.

  • For in-memory bitpacked puzzle states, prefer xtructure’s built-in support: FieldDescriptor.packed_tensor(…) + <field>_unpacked + set_unpacked(…), or aggregate bitpacking via bits=… on primitive leaves with .packed / .unpacked views.

puxle.utils.util.to_uint8(input, active_bits=1)[source]

Efficiently pack arrays into uint8 format with support for 1-8 bits per value. Now supports all bit widths (1-8) efficiently, including 3,5,6,7 bits, using only uint32 accumulators.

Return type:

Array

Parameters:

  • input (chex.Array)

  • active_bits (int)

puxle.utils.util.from_uint8(packed_bytes, target_shape, active_bits=1)[source]

Efficiently unpack uint8 array back to original format. Now supports all bit widths (1-8) efficiently, including 3,5,6,7 bits, using only uint32 accumulators.

Return type:

Array

Parameters:

  • packed_bytes (chex.Array)

  • target_shape (tuple[int, ...])

  • active_bits (int)

puxle.utils.util.pack_variable_bits(values_and_bits)[source]

Pack multiple arrays with different bit requirements into a single uint8 array.

Parameters:

values_and_bits (list[tuple[Array, int]]) – List of (values_array, bits_per_value) tuples

Return type:

Array

Returns:

Packed uint8 array with metadata for unpacking

Example

# Pack different data types together efficiently bool_array = jnp.array([True, False, True]) # 1 bit each nibble_array = jnp.array([3, 7, 1]) # 4 bits each byte_array = jnp.array([255, 128]) # 8 bits each

packed = pack_variable_bits([

(bool_array, 1), (nibble_array, 4), (byte_array, 8)

])

puxle.utils.util.unpack_variable_bits(packed_data, target_shapes)[source]

Unpack variable bit data back to original arrays.

Parameters:

  • packed_data (Array) – Packed uint8 array from pack_variable_bits

  • target_shapes (list[tuple[int, ...]]) – List of target shapes for each array

Return type:

list[Array]

Returns:

List of unpacked arrays

puxle.utils.util.add_img_parser(cls, imgfunc)[source]

This function is a decorator that adds a __str__ method to the class that returns a string representation of the class.

Return type:

Type[TypeVar(T)]

Parameters:

  • cls (Type[T])

  • imgfunc (callable)

puxle.utils.util.coloring_str(string, color)[source]
Return type:

str

Parameters: