mimiqcircuits.bitstrings

Functions

bitvec_to_int(arr)

Classes

BitString(arg[, indices])

A sequence of bits, one per qubit or classical bit.

class BitString(arg, indices=None)[source]

Bases: object

A sequence of bits, one per qubit or classical bit.

A BitString represents a computational basis state of a register, such as a measurement outcome. Sampled results in QCSResults are stored as BitString objects, and the bitstrings argument of submit takes them to request amplitudes. Bit i of the string is qubit (or classical bit) i, and the printed form bs"..." lists bit 0 first.

A BitString is hashable, so it can be a dictionary key. Indexing returns a bit; slicing returns a new BitString. Assigning a bit with bs[i] = 1 changes the string, and with it its hash, so do not assign bits of a string that is used as a dictionary key.

Examples

Create one from a number of bits (all zero), a string, a sequence of 0 and 1, or a bitarray:

>>> from mimiqcircuits import *
>>> from bitarray import bitarray
>>> BitString(16) # number of qubits
bs"0000000000000000"
>>> BitString('10101') # binary string
bs"10101"
>>> BitString([1,0,0,0,1]) # binary string
bs"10001"
>>> BitString((1,0,0,0,1)) # binary string
bs"10001"
>>> BitString(bitarray('101010')) # bitarray
bs"101010"

Other constructors:

>>> BitString.fromnonzeros(16, [1, 3, 5, 7, 9, 11, 13, 15])
bs"0101010101010101"
>>> BitString.fromfunction(16, lambda i: i % 2 == 1)
bs"0101010101010101"
>>> BitString.fromstring('10101')
bs"10101"
>>> BitString.fromint(16, 21)
bs"1010100000000000"
>>> BitString.fromint(16, 21, 'little')
bs"0000000000010101"

Accessing the bits:

>>> bs = BitString('0110')
>>> bs[1] # get bit 1
1
>>> bs[0:2] # get the first 2 bits
bs"01"
>>> bs.nonzeros() # indices of the bits set to 1
[1, 2]
>>> BitString('1100').tointeger() # bit 0 is the least significant
3

Bitwise operations:

>>> bs1 = BitString('10101')
>>> bs2 = BitString('11100')
>>> bs1 | bs2 # OR
bs"11101"
>>> bs1 & bs2 # AND
bs"10100"
>>> bs1 ^ bs2 # XOR
bs"01001"
>>> ~bs1 # NOT
bs"01010"
>>> bs1 << 2 # left shift
bs"10100"
>>> bs1 >> 2 # right shift
bs"00101"

Other operations:

>>> bs1 + bs2 # concatenation
bs"1010111100"
>>> bs1 * 2 # repetition
bs"1010110101"
__init__(arg, indices=None)[source]

Create a BitString.

Parameters:
  • arg (int, str, list, tuple, bitarray or frozenbitarray) – Either the number of bits, which gives the all-zero string (or the string with ones at indices), or the bits themselves as a string of "0" and "1", a sequence of 0 and 1, or a bitarray.

  • indices (list of int, optional) – With an integer arg, the indices of the bits set to 1. Ignored otherwise.

Raises:
  • ValueError – If an index in indices is outside range(arg), or the bits contain values other than 0 and 1.

  • TypeError – If arg has another type.

Examples

>>> BitString(16) # number of qubits
bs"0000000000000000"
>>> BitString(4, [0, 2]) # number of qubits and the bits set to 1
bs"1010"
>>> BitString('10101') # binary string
bs"10101"
>>> BitString(bitarray('101010')) # bitarray
bs"101010"
property bits

The bits as a read-only frozenbitarray.

static fromnonzeros(num_qubits, nonzeros)[source]

Create a BitString with the given bits set to 1.

Parameters:
  • num_qubits (int) – The number of bits.

  • nonzeros (list) – The indices of the bits set to 1.

Returns:

The new string.

Return type:

BitString

Raises:

ValueError – If an index is outside range(num_qubits).

Examples

>>> BitString.fromnonzeros(4, [1, 3])
bs"0101"
static fromfunction(num_qubits, f)[source]

Create a BitString by evaluating a function on each index.

Parameters:
  • num_qubits (int) – The number of bits.

  • f (type[<lambda>]) – A function called with each index i; bit i is 1 when the result is true.

Returns:

The new string.

Return type:

BitString

Examples

>>> BitString.fromfunction(6, lambda i: i % 3 == 0)
bs"100100"
static fromstring(bitstring)[source]

Create a BitString from a string of "0" and "1".

Same as BitString(bitstring).

Parameters:

bitstring (str) – The bits, bit 0 first.

Returns:

The new string.

Return type:

BitString

static fromint(num_qubits, integer, endianess='big')[source]

Create a BitString from the binary digits of an integer.

Parameters:
  • num_qubits (int) – The number of bits.

  • integer (int) – A non-negative integer that fits in num_qubits bits.

  • endianess (str) – "big" puts the least significant binary digit in bit 0; "little" puts the most significant digit in bit 0. Defaults to "big". This is the inverse of tointeger() with the same endianess.

Returns:

The new string.

Return type:

BitString

Raises:

ValueError – If integer needs more than num_qubits bits, or endianess is neither "big" nor "little".

Examples

>>> BitString.fromint(4, 1)
bs"1000"
>>> BitString.fromint(4, 1, "little")
bs"0001"
>>> BitString.fromint(4, 6).tointeger()
6
num_qubits()[source]

Return the number of bits, the same as len(bs).

nonzeros()[source]

Return the indices of the bits set to 1, as a list of int.

zeros()[source]

Return the indices of the bits set to 0, as a list of int.

tointeger(endianess='big')[source]

Return the integer whose binary digits are the bits.

Parameters:

endianess (str) – "big" reads bit 0 as the least significant binary digit; "little" reads it as the most significant. Defaults to "big".

Returns:

The integer value.

Return type:

int

Raises:

ValueError – If the string is empty, or endianess is neither "big" nor "little".

Examples

>>> BitString("1000").tointeger()
1
>>> BitString("1000").tointeger("little")
8
to01(endianess='big')[source]

Return the bits as a string of "0" and "1".

Parameters:

endianess (str) – "big" lists bit 0 first, as the printed form does; "little" lists it last. Defaults to "big".

Returns:

The bits as text.

Return type:

str

Raises:

ValueError – If endianess is neither "big" nor "little".

Examples

>>> BitString("110").to01()
'110'
>>> BitString("110").to01("little")
'011'
toindex(endianess='big')[source]

Return the index of the basis state, as in a state vector.

Indices start at 0, so this is the same value as tointeger().

Parameters:

endianess (str) – See tointeger(). Defaults to "big".

Returns:

The index.

Return type:

int

Raises:

ValueError – If the string is empty, or endianess is neither "big" nor "little".

__setitem__(index, value)[source]

Set a specific bit by creating a new frozenbitarray.

The buffer stays frozen because __hash__ is defined over it and QCSResults.histogram() uses BitStrings as dictionary keys, so a freely mutable buffer would break the key contract. Copying it as a bitarray rather than through a Python list of ints is what keeps a single-bit write from costing two conversions of the whole string.