mimiqcircuits.bitstrings¶
Functions
|
Classes
|
A sequence of bits, one per qubit or classical bit. |
- class BitString(arg, indices=None)[source]¶
Bases:
objectA sequence of bits, one per qubit or classical bit.
A
BitStringrepresents a computational basis state of a register, such as a measurement outcome. Sampled results inQCSResultsare stored asBitStringobjects, and thebitstringsargument ofsubmittakes them to request amplitudes. Bitiof the string is qubit (or classical bit)i, and the printed formbs"..."lists bit 0 first.A
BitStringis hashable, so it can be a dictionary key. Indexing returns a bit; slicing returns a newBitString. Assigning a bit withbs[i] = 1changes 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 abitarray.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
indicesis outsiderange(arg), or the bits contain values other than 0 and 1.TypeError – If
arghas 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:
- Returns:
The new string.
- Return type:
- 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:
- Returns:
The new string.
- Return type:
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).
- 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_qubitsbits.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 oftointeger()with the sameendianess.
- Returns:
The new string.
- Return type:
- Raises:
ValueError – If
integerneeds more thannum_qubitsbits, orendianessis neither"big"nor"little".
Examples
>>> BitString.fromint(4, 1) bs"1000" >>> BitString.fromint(4, 1, "little") bs"0001" >>> BitString.fromint(4, 6).tointeger() 6
- 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:
- Raises:
ValueError – If the string is empty, or
endianessis 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:
- Raises:
ValueError – If
endianessis 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:
- Raises:
ValueError – If the string is empty, or
endianessis 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 andQCSResults.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.