z i}}nSrSSKJr SSKJr SSKJr SSKJrJ r SSK J r J r J r JrJr SSKrSSKJr SS KJr SS KJrJr S S KJrJr S S KJrJrJr \R@"\RB"S\RDS9RGSS 5S S9RIS S9r%SSjr&SSjr'SSjr("SS\5r)g)z BitArray ) annotations) defaultdict)partial)chainrepeat)CallableIterableLiteralMappingSequenceN)NDArray) QiskitError)Countssampled_expectation_value)ObservablesArrayObservablesArrayLike) ShapedMixin ShapeInput shape_tupledtypeaxiscUS-US-S:-$)z@Return the minimum number of bytes needed to store ``num_bits``.rnum_bitss `/home/james-whalen/.local/lib/python3.13/site-packages/qiskit/primitives/containers/bit_array.py_min_num_bytesr#%s q=HqL1, --BitArraycv[R"URSSS9nUSSUR*S- S24nU$)Nrbigrbitorder.r)np unpackbitsarrayr!) bit_arrayarrs r"_unpackr/*sA -- b5 AC c2+++a/"44 5C Jr$cUSSSS24nURSnU*S-nUS:a.S/URS- -US4/-n[R"XSS9n[R"USSS 9nX4$) N.rrr)rrr)constant_valuesr'r()shapendimr*padpackbits)r.r!pad_size pad_widths r"_packr80s{ c4R4i.Cyy}Hy1}H!|H1 -(A? ffSQ7 ++cU 3C =r$c(^\rSrSrSrS$U4SjjrS%SjrS&SjrS'SjrS(Sjr S&Sjr S&S jr S r S r \S)S j5r\S*S j5r\S*Sj5r\S+Sj5r\S,Sj5rS-SjrS.Sjr\S/S0Sjj5r\S1S2Sjj5r\S1S3Sjj5rS/S4SjjrS1S5SjjrS1S6SjjrS1S7SjjrS8SjrS(SjrS9Sjr S9Sjr!S:Sjr"S;Sjr#\SS!j5r%\S>S"j5r&S#r'U=r($)?r%;a)Stores an array of bit values. This object contains a single, contiguous block of data that represents an array of bitstrings. The last axis is over packed bits, the second last axis is over shots, and the preceding axes correspond to the shape of the pub that was executed to sample these bits. c>[TU]5 [U[R5(d[ S[ U535eUR[R:wa[ SURS35eURS:a [S5eURS[U5=n:wa[SUS35eXl X lURRS S Ulg ) aU Args: array: The ``uint8`` data array. num_bits: How many bit are in each outcome. Raises: TypeError: If the input is not a NumPy array with type ``numpy.uint8``. ValueError: If the input array has fewer than two axes, or the size of the last axis is not the smallest number of bytes that can contain ``num_bits``. z"Input must be a numpy.ndarray not z'Input array must have dtype uint8, not .z,The input array must have at least two axes.rz$The input array is expected to have z bytes per shot.N)super__init__ isinstancer*ndarray TypeErrortyperuint8r3 ValueErrorr2r#_array _num_bits_shape)selfr,r!expected __class__s r"r@BitArray.__init__Cs %,,@e NO O ;;"(( "Eekk]RSTU U ::>KL L ;;r?>(+CCx DCH:M]^_ _ !kk'', r$cURUR:wa[SUSUS35eURUR4-nURUR4-n[R "X#5UR RS4-n[R"URU5[R"URU54$![an[USUS35UeSnAff=f)zSValidation and broadcasting of two bit arrays before element-wise binary operation.z'num_bits' must match in z and r<rz' are not compatible for this operation.N) r!rFr2 num_shotsr*broadcast_shapesrG broadcast_tor,)rJother self_shape other_shaper2exs r"_prepare_broadcastableBitArray._prepare_broadcastable^s ==ENN *8eE7!LM MZZ4>>"33 kkU__$66  c'' @DKKDUDUVXDYC[[Etzz512??5;;PU3VVV cvU5'1XYZ`b b cs"1C C6C11C6cn[[R"URU56UR5$N)r%r* bitwise_andrVr!rJrRs r"__and__BitArray.__and__j'(C(CE(JKT]][[r$chUR=o!R:wagURUR/nUS-S:a[[R"SU*S-- /S/US---[RS9nUVs/sHn[R "XT5PM nn[R "USS06$s snf)NFrrr equal_nan)r!rGr*r,rErZ array_equal)rJrRnarrsmaskr.s r"__eq__BitArray.__eq__ms A>> 1 U\\* q51988SqbAX./3%162BB"((SD9=>#BNN3-D>~~t5u55?s7 B/cj[[R"UR5UR5$rY)r%r* bitwise_notrGr!rJs r" __invert__BitArray.__invert__ws t{{3T]]CCr$cn[[R"URU56UR5$rY)r%r* bitwise_orrVr!r[s r"__or__BitArray.__or__zs' t'B'B5'IJDMMZZr$cn[[R"URU56UR5$rY)r%r* bitwise_xorrVr!r[s r"__xor__BitArray.__xor__}r^r$cbSURSURSURS3nSUS3$)Nzz BitArray())r2rOr!)rJdescs r"__repr__BitArray.__repr__s9 L0@ DMM?Z[\4&""r$c[U[5(aN[U5URS-:Xa [ S5e[U5URS-:a [ S5e[ UR UUR5$)NrzJBitArray cannot be sliced along the shots axis, use slice_shots() instead.r=zHBitArray cannot be sliced along the bits axis, use slice_bits() instead.)rAtuplelenr3 IndexErrorr%rGr!)rJindicess r" __getitem__BitArray.__getitem__su gu % %7|tyy1}, `7|tyy1}, ^ G,dmm<)rGr2rjs r"rOBitArray.num_shotss {{  $$r$cn[RUS5U-n[U5SSRU5$)Nr'r=)int from_bytesbinzfill)datar!revals r"_bytes_to_bitstringBitArray._bytes_to_bitstrings2nnT5)D03x|!!(++r$c4[RUS5U-$)Nr')rr)rres r" _bytes_to_intBitArray._bytes_to_ints~~dE*T11r$cUc3URRSURRS5OURUn[[5nUH#nXB"UR 55==S- ss'M% [ U5$)Nrr)rGreshaper2rrtobytesdict)rJloc converterr.countsshot_rows r" _get_countsBitArray._get_countsszAD dkk!!"dkk&7&7&;AB B H #tt)$E e^,UG3Z[ ;;r?"a '9 '((;u{{3B'7C4PCNNC'BitArray.from_counts..s.dgIBRXY[RcQRcs:<rz;All of your mappings need to have the same number of shots.) rAr listrFr int_outcomesr% from_samplesrOr}r)rr! singletonrrr-s r" from_countsBitArray.from_countss.#673 39 3XF&\F !HII_e ^dSZj&&A&AG "w N^d  ed))$9 ""S[014 !^__!))#f+y7J7JcRXk7YZI s1C/cP^^[U5n[U5n[ U/U5n[ U[ 5(a&URS5(aSOSmU4SjU5nUc6[U5n[[[RU55nUS:XaSn[U5mS RU4S jU55n[R "U[R"[%U5S 9n['UR)S T5U5$![an[S5UeSnAff=f) aConstruct a new bit array from an iterable of bitstrings, hexstrings, or integers. All samples are assumed to be integers if the first one is. Strings are all assumed to be bitstrings whenever the first string doesn't start with ``"0x"``. Consider pairing this method with :meth:`~reshape` if your samples represent nested data. Args: samples: A list of bitstrings, a list of integers, or a list of hexstrings. num_bits: The desired number of bits per sample. If unset, the biggest sample provided is used to determine this value, with a minimum of one bit. Returns: A new bit array. Raises: ValueError: If no strings are given. z At least one sample is required.N0xr=c38># UHn[UTS9v M g7f))baseN)r)rrrs r"r(BitArray.from_samples...s84CC$'4srrr$c3F># UHoRTS5v M g7f)r'N)to_bytes)rr num_bytess r"rr9sG$3 Y66$s!)rrr)iternext StopIterationrFrrAstr startswithrmaxmapr bit_lengthr#joinr* frombufferrEr}r%r) samplesr! first_samplerUintsrr,rrs @@r"rBitArray.from_sampless,w- I=Ll^W- lC ( (%00662AD848D  :D3s~~t45H1}"8, xxG$GG d"((#d)D b)4h??' I?@b H Is D D% D  D%cUS;a[SUS35e[R"URSS9SUR*S24nUS:Xa USSSS24nUR [R 5$) aoConvert this :class:`~BitArray` to a boolean array. Args: order: One of ``"big"`` or ``"little"``, respectively indicating whether the most significant bit or the least significant bit of each bitstring should be placed at ``[..., 0]``. Returns: A NumPy array of bools. Raises: ValueError: If the order is not one of ``"big"`` or ``"little"``. )r'rzInvalid value for order: 'rrr.Nr)rFr*r+r,r!astypebool_)rJrr.s r" to_bool_arrayBitArray.to_bool_array=s| ) ),UG3Z[ mmDJJR0t}}n6F1FG H c4R4i.Czz"((##r$cSUR-S- n[URURUS9nURXS9$)a'Return a counts dictionary with bitstring keys. Args: loc: Which entry of this array to return a dictionary for. If ``None``, counts from all positions in this array are unioned together. Returns: A dictionary mapping bitstrings to the number of occurrences of that bitstring. r=rr!rerr)r!rrr)rJrrers r" get_countsBitArray.get_countsTsD$--!#D44t}}SWX C==r$ch[URSUR-S- S9nURXS9$)a:Return a counts dictionary, where bitstrings are stored as ``int``\s. Args: loc: Which entry of this array to return a dictionary for. If ``None``, counts from all positions in this array are unioned together. Returns: A dictionary mapping ``ints`` to the number of occurrences of that ``int``. r=r)rer)rrr!r)rJrrs r"get_int_countsBitArray.get_int_countsbs8D..Q 5E5IJ C==r$cDSUR-S- n[URURUS9nUc3URR SURR S5OURUnUVs/sHoS"UR 55PM sn$s snf)zReturn a list of bitstrings. Args: loc: Which entry of this array to return a dictionary for. If ``None``, counts from all positions in this array are unioned together. Returns: A list of bitstrings. r=rrr)r!rrrGrr2r)rJrrerr.rs r"get_bitstringsBitArray.get_bitstringsps$--!#D44t}}SWX @C dkk!!"dkk&7&7&;ABc( (**,-cBBBs;Bc[U5n[R"U[S9=o R:Xa#[XR R SS5nOJX RUR-:Xa#[XR R SS5nO [S5e[UR RU5UR5$)aReturn a new reshaped bit array. The :attr:`~num_shots` axis is either included or excluded from the reshaping procedure depending on which picture the new shape is compatible with. For example, for a bit array with shape ``(20, 5)`` and ``64`` shots, a reshape to ``(100,)`` would leave the number of shots intact, whereas a reshape to ``(200, 32)`` would change the number of shots to ``32``. Args: *shape: The new desired shape. Returns: A new bit array. Raises: ValueError: If the size corresponding to your new shape is not equal to either :attr:`~size`, or the product of :attr:`~size` and :attr:`~num_shots`. rr>Nrz$Cannot change the size of the array.) rr*prodrsizerGr2rOrFr%rr!)rJr2rs r"rBitArray.reshapes&E"GGE- -D)) ;{{'8'8'=>E YY/ /{{'8'8'=>ECD D ++E2DMMBBr$c.^[U5S:Xa'[[[TR555n[U5S:Xa[ US[ 5(aUSn[U5TR:wa [S5eUHBnUTR:dTRU-S:dM([SUSTRS35e [U4SjU55S-n[TRRU5TR5$) aReturn a bit array with axes transposed. Args: axes: None, tuple of ints or n ints. See `ndarray.transpose `_ for the details. Returns: BitArray: A bit array with axes permuted. Raises: ValueError: If ``axes`` don't match this bit array. ValueError: If ``axes`` includes any indices that are out of bounds. rrzaxes don't match bit arrayaxis - is out of bounds for bit array of dimension r<c3P># UHoS:aUOTRU-v M g7f)rN)r3)rirJs r"r%BitArray.transpose..s"BTq&Qdii!m3Ts#&)r>r) r}r|reversedranger3rAr rFr%rG transposer!)rJaxesrs` r"rBitArray.transposes t9>% "234D t9>ja(;;7D t9 !9: :ADII~Q!2 A3KDII;VWX BTBBXM --d3T]]CCr$c[U[5(aU4nUH4nUS:dX R:dM[SUSURS35e [ U5nUSU4n[ U5up4[ X45$)aReturn a bit array sliced along the bit axis of some indices of interest. .. note:: The convention used by this method is that the index ``0`` corresponds to the least-significant bit in the :attr:`~array`, or equivalently the right-most bitstring entry as returned by :meth:`~get_counts` or :meth:`~get_bitstrings`, etc. If this bit array was produced by a sampler, then an index ``i`` corresponds to the :class:`~.ClassicalRegister` location ``creg[i]``. Args: indices: The bit positions of interest to slice along. Returns: A bit array sliced along the bit axis. Raises: IndexError: If there are any invalid indices of the bit axis. rindex z) is out of bounds for the number of bits r<.)rArr!r~r/r8r%)rJrindexr.r!s r" slice_bitsBitArray.slice_bitss, gs # #jGEqyE]]2 UG#LT]]O[\]dm#w,c &&r$c[U[5(aU4nUH4nUS:dX R:dM[SUSURS35e URnUSUSS24n[ X0R 5$)aReturn a bit array sliced along the shots axis of some indices of interest. Args: indices: The shots positions of interest to slice along. Returns: A bit array sliced along the shots axis. Raises: IndexError: If there are any invalid indices of the shots axis. rrz* is out of bounds for the number of shots r<.N)rArrOr~rGr%r!)rJrrr.s r" slice_shotsBitArray.slice_shotss gs # #jGEqyE^^3 UG#MdnnM]]^_ kk#w/"]]++r$c [U[5(aU4n[U[[45(aU4n[R"U[S9n[ U5n[ U5U:wa [ S5eURRSn[R"U5nUS:aUR5UR:a3[S[UR55SURS35eUR5UR*:a3[S[UR55SURS35eURSURUR-5nUS:XaU$XR-n[R "XU[R""U55RS:a7[%[R&"SU4[R(S9URS 9$[R*"US 5upgUS - U- nUR-[R(5n [R."U[R(S9n [R0R3X[R("S 5U -5 [R."U[R(S9n [R0R3X[R"U[R(S9U -5 [%URURU -U :HR5SS 9URS 9$) aPost-select this bit array based on sliced equality with a given bitstring. .. note:: If this bit array contains any shape axes, it is first flattened into a long list of shots before applying post-selection. This is done because :class:`~BitArray` cannot handle ragged numbers of shots across axes. Args: indices: A list of the indices of the cbits on which to postselect. If this bit array was produced by a sampler, then an index ``i`` corresponds to the :class:`~.ClassicalRegister` location ``creg[i]`` (as in :meth:`~slice_bits`). Negative indices are allowed. selection: A list of binary values (will be cast to ``bool``) of length matching ``indices``, with ``indices[i]`` corresponding to ``selection[i]``. Shots will be discarded unless all cbits specified by ``indices`` have the values given by ``selection``. Returns: A new bit array with ``shape=(), num_bits=data.num_bits, num_shots<=data.num_shots``. Raises: IndexError: If ``max(indices)`` is greater than or equal to :attr:`num_bits`. IndexError: If ``min(indices)`` is less than negative :attr:`num_bits`. ValueError: If the lengths of ``selection`` and ``indices`` do not match. rz.Lengths of indices and selection do not match.rrrz& out of bounds for the number of bits r<rr rrr)rArrr*rr}rFrGr2rr!r~minrrrO intersect1d logical_notr%emptyrEdivmodrrrnatall) rJr selection num_indicesr flattenedbyte_significancebit_significancebyte_idx bit_offsetbitmaskselection_bytess r" postselectBitArray.postselects> gs # #jG i$ - -" IJJy5 'l y>[ (MN NKK%%b) **W% ?{{} - S/00VW[WdWdVeefg{{} ~- S/00VW[WdWdVeefgLLTYY%?@  !   ==  >>',gbnnY6O.P Q V VYZ ZBHHa^288Dt}}] ]/1ii.C+M%66%,,RXX6 ((9BHH5 BHHQK:,EF((9BHH=  rzz)288'LPZ'Z    y//'9oMRRXZR[ \]]  r$c~[R"U5n[R"[R"UR 5[ S9RUR 5n[R"X!5up40n[R"U[S9n[R"UR 5HWnX7nXGR5H:upX;aURU5XX'[XXU 5n Xg==X-- ss'M< MY U$![an [U R 5U eSn A ff=f)aCompute the expectation values of the provided observables, broadcasted against this bit array. .. note:: This method returns the real part of the expectation value even if the operator has complex coefficients due to the specification of :func:`~.sampled_expectation_value`. Args: observables: The observable(s) to take the expectation value of. Must have a shape broadcastable with with this bit array and the same number of qubits as the number of bits of this bit array. The observables must be diagonal (I, Z, 0 or 1) too. Returns: An array of expectation values whose shape is the broadcast shape of ``observables`` and this bit array. Raises: ValueError: If the provided observables does not have a shape broadcastable with this bit array. ValueError: If the provided observables does not have the same number of qubits as the number of bits of this bit array. ValueError: If the provided observables are not diagonal. rN)rcoercer*fromiterndindexr2objectrbroadcast_arrays zeros_likefloatrrrrrFmessage) rJ observables arr_indices bc_indicesbc_obsrr.rrpaulicoeffexpvalrUs r"expectation_valuesBitArray.expectation_valuesPs6'--k: kk"**TZZ"8GOOPTPZPZ[ 00J mmJe4ZZ 0 01E#C & 3 3 5 $"&//#"6FK96v{EJF fn, !62 #9$RZZ0b89s1D D<!D77D<c [U5S:Xa [S5eUSRnUSRnUSRnUS:Xa [S5e[ U5HupVURU:wa[SUSUSURS35eURU:wa[SUS USURS 35eURU:wdMu[S US USURS 35e US:dX:a[SUSUS35e[ R"UVs/sHofRPM snUS9n[Xr5$s snf)aJoin a sequence of bit arrays along an existing axis. Args: bit_arrays: The bit arrays must have (1) the same number of bits, (2) the same number of shots, and (3) the same shape, except in the dimension corresponding to axis (the first, by default). axis: The axis along which the arrays will be joined. Default is 0. Returns: The concatenated bit array. Raises: ValueError: If the sequence of bit arrays is empty. ValueError: If any bit arrays has a different number of bits. ValueError: If any bit arrays has a different number of shots. ValueError: If any bit arrays has a different number of dimensions. rz*Need at least one bit array to concatenatez2Zero-dimensional bit arrays cannot be concatenatedOAll bit arrays must have same number of bits, but the bit array at index 0 has ! bits and the bit array at index  has  bits.PAll bit arrays must have same number of shots, but the bit array at index 0 has " shots and the bit array at index  shots.zUAll bit arrays must have same number of dimensions, but the bit array at index 0 has z) dimension(s) and the bit array at index z dimension(s).rrr<r) r}rFr!rOr3 enumerater*rr,r%) bit_arraysrr!rOr3rbars r"rBitArray.concatenate|s( z?a IJ Ja=))qM++ !}!! 19QR Rz*EA{{h& 88@zB223E"++fN ||y( 88A{C223E",,wP ww$ 88223E"''.R+& !8t|uTF*WX\W]]^_` `~~*=*Bxx*=DI''>s+Ec [U5S:Xa [S5eUSRnUSRn[ U5Hcup4URU:wa[SUSUSURS35eURU:wdMF[SUSUS URS 35e [ R "UVs/sHoDRPM snS S 9n[XQ5$s snf) aJoin a sequence of bit arrays along the shots axis. Args: bit_arrays: The bit arrays must have (1) the same number of bits, and (2) the same shape. Returns: The stacked bit array. Raises: ValueError: If the sequence of bit arrays is empty. ValueError: If any bit arrays has a different number of bits. ValueError: If any bit arrays has a different shape. r$Need at least one bit array to stackr"r#r$r%LAll bit arrays must have same shape, but the bit array at index 0 has shape  and the bit array at index has shape r<r>r) r}rFr!r2r)r*rr,r%)r*r!r2rr+rs r"concatenate_shotsBitArray.concatenate_shotss z?a CD Da=))1 ##z*EA{{h& 88@zB223E"++fN xx5  >>CWE223KzL+~~*=*Bxx*=BG''>s?C%c [U5S:Xa [S5eUSRnUSRn[ U5Hcup4URU:wa[SUSUSURS35eURU:wdMF[SUSUS URS 35e [ R "UVs/sHn[U5PM snS S 9n[U5upV[XV5$s snf) aJoin a sequence of bit arrays along the bits axis. .. note:: This method is equivalent to per-shot bitstring concatenation. Args: bit_arrays: Bit arrays that have (1) the same number of shots, and (2) the same shape. Returns: The stacked bit array. Raises: ValueError: If the sequence of bit arrays is empty. ValueError: If any bit arrays has a different number of shots. ValueError: If any bit arrays has a different shape. rr.r&r'r$r(r/r0r1r<rr) r}rFrOr2r)r*rr/r8r%)r*rOr2rr+rr!s r"concatenate_bitsBitArray.concatenate_bitss& z?a CD DqM++ 1 ##z*EA||y( 88A{C223E",,wP xx5  >>CWE223KzL+ ~~Z@Zrwr{Z@rJt''As?C2)rGrHrI)r,NDArray[np.uint8]r!r)rR 'BitArray'returnztuple[NDArray[np.uint8], ...])rRr8r9r8)rRr8r9r)r9r8)r9r7)r9r)rbytesr!rrerr9r)rr:rerr9r)rint | tuple[int, ...] | NonerzCallable[[bytes], str | int]r9zdict[str, int] | dict[int, int])r9zNDArray[np.uint64])r')r,NDArray[np.bool_]rLiteral['big', 'little']r9r8rY)rz;Mapping[str | int, int] | Iterable[Mapping[str | int, int]]r! int | Noner9r8)rzIterable[str] | Iterable[int]r!r>r9r8)rr=r9r<)rr;r9zdict[str, int])rr;r9zdict[int, int])rr;r9z list[str])r2rr9r8)rzint | Sequence[int]r9r8)rzSequence[int] | intrz!Sequence[bool | int] | bool | intr9r%)rrr9zNDArray[np.float64])r)r*Sequence[BitArray]rrr9r%)r*r?r9r%))__name__ __module__ __qualname____firstlineno____doc__r@rVr\rfrkrorsryrpropertyr,r!rO staticmethodrrrrrrrrrrrrrrrr rrr2r5__static_attributes__ __classcell__)rLs@r"r%r%;s-6 W\6D[\# =%%,,222?[ (8DI!H !H)A!H !H!HF $(K(( ((TGK+@.+@:D+@ +@+@Z$. > > CC8D<#'J,.Y $Y 5Y   Y v*X0(0(d!(!(F((((r$)r!rr9r)r-r%r9r7)r.r7r9ztuple[NDArray[np.uint8], int])*rD __future__r collectionsr functoolsr itertoolsrrtypingrr r r r numpyr* numpy.typingr qiskit.exceptionsr qiskit.resultrrobservables_arrayrrr2rrrr+arangerErrrr#r/r8r%rr$r"rTs###AA );E77ryyBHH=EEb!LSTUYY_`Ya.  A ({A (r$