microquantum.stdlib.bits

Standard library: bitstring and integer utilities (Phase 117).

Bitstring conventions match the rest of the SDK: measurement outcomes are MSB-first strings ("101") whose unsigned-binary integer value is int(bitstring, 2). Every helper here adopts the same left-to-right, most-significant-bit-first order, so int_to_bits / bits_to_int and int_to_bitstring / bitstring_to_int are exact inverses of one another.

These are dependency-light, application-independent building blocks intended for user programs, the runtime and the compiler alike.

Module Contents

microquantum.stdlib.bits.int_to_bitstring(value, width=None)

Convert a non-negative integer to an MSB-first binary bitstring.

Parameters:

• value (int) – Non-negative integer to convert.

• width (int | None) – Optional fixed width (zero-padded). Must be >= 1 and large enough to represent value.

Returns:

A 0/1 string with no leading zeros (unless width pads it).

Raises:

• TypeError – If value/width is not an int.

• ValueError – If value is negative, or width is too small.

Return type:

str

microquantum.stdlib.bits.bitstring_to_int(bitstring)

Convert an MSB-first bitstring to its unsigned integer value.

Parameters:

bitstring (str) – Non-empty string of 0/1 characters.

Returns:

The integer value (MSB first), i.e. int(bitstring, 2).

Raises:

• TypeError – If bitstring is not a str.

• ValueError – If bitstring is empty or contains non-binary chars.

Return type:

int

microquantum.stdlib.bits.int_to_bits(value, width=None)

Convert a non-negative integer to an MSB-first tuple of bits.

Parameters:

• value (int) – Non-negative integer to convert.

• width (int | None) – Optional fixed length (most-significant side zero-padded). Must be >= 1 and large enough to represent value.

Returns:

A tuple of 0/1 entries in MSB-first order (no leading zeros unless width pads them).

Raises:

• TypeError – If value/width is not an int.

• ValueError – If value is negative, or width is too small.

Return type:

tuple[int, …]

microquantum.stdlib.bits.bits_to_int(bits)

Convert an MSB-first iterable of bits to its integer value.

Parameters:

bits (Iterable[int]) – A non-empty iterable of integer bits (0 or 1), read in MSB-first order.

Returns:

The unsigned integer value the bits represent.

Raises:

• TypeError – If any element is not an int.

• ValueError – If bits is empty or contains values other than 0/1.

Return type:

int

microquantum.stdlib.bits.hamming_weight(value)

Number of set bits in an integer or a 0/1 bitstring.

Parameters:

value (int | str) – Either a non-negative integer (its set bits counted) or an MSB-first bitstring (its '1' characters counted).

Returns:

The Hamming weight.

Raises:

• TypeError – If value is neither an int nor a str.

• ValueError – If the integer is negative, or the bitstring is empty or non-binary.

Return type:

int

microquantum.stdlib.bits.hamming_distance(left, right)

Number of positions where two integers or bitstrings differ.

Parameters:

• left (int | str) – Non-negative integer or MSB-first bitstring.

• right (int | str) – Non-negative integer or MSB-first bitstring of the same kind. Two bitstrings must have equal length.

Returns:

The Hamming distance.

Raises:

• TypeError – If the arguments have different kinds, or either is not an int/str.

• ValueError – If an integer is negative, or a bitstring is empty, non-binary, or the two bitstrings have different lengths.

Return type:

int

microquantum.stdlib.bits.gray_code(num_bits)

Binary reflected Gray code of num_bits bits.

Adjacent entries differ in exactly one bit; the sequence starts at "0" * num_bits. MSB-first strings matching SDK conventions.

Parameters:

num_bits (int) – Code width (must be >= 1).

Returns:

The 2**num_bits Gray-code words in order.

Return type:

list[str]