z iπ6SrSSKJr SSKrSSKJr SSKJr SSK r SSK J r SSK Jr SSKJr SS KJr SS KJr SS KJr SS KJr SS KJr SSKJrJr SSKJr SSK J!r! SSK J"r" SSK#J$r$ SSK%J&r& SSK'J(r(J)r) SSK*J+r+ \(aSSK J,r, "SS\\5r-g)z$ DensityMatrix quantum state class. ) annotationsN)Number) TYPE_CHECKING) _numpy_compat)QuantumCircuit) Instruction) QiskitError) QuantumState)TolerancesMixin)OpShape)Operator)Pauli SparsePauliOp)ScalarOp)is_hermitian_matrix)is_positive_semidefinite_matrix)QuantumChannel)SuperOp)density_expval_pauli_no_xdensity_expval_pauli_with_x) Statevector)circuitc^\rSrSrSrS%S&U4SjjjrS\R4SjrU4Sjr Sr \ S5r S%S'S jjr S r\ S 5rS(S jrS)S jrSrSrSrS*SjrS*SjrSrSrS%S+SjjrS,SjrS%SjrS%S-SjjrS(S.SjjrS%S/Sjjr\S0Sj5r \!S1Sj5r"\S2Sj5r#S%S3Sjjr$S%Sjr%S%S jr&S%S!jr'S(S4S"jjr(S5S#jr)S$r*U=r+$)6 DensityMatrix.zDensityMatrix classNc0>[U[[R45(a[R"U[ S9UlO[U[[45(a%[RU5R UlO[US5(a5UR5nURUlUcUR5nOI[US5(a-[R"UR5[ S9UlO [!S5eUR R"nUR R$nUS:Xa USUS:XaOUS:XaE[R&"UR [R("UR 55UlODUS:Xa3USS:Xa*[R*"UR US5UlO [!S 5e[,TU]][0R2"UR R$X"S 9S 9 g) a_Initialize a density matrix object. Args: data: A statevector, quantum instruction or an object with a ``to_operator`` or ``to_matrix`` method from which the density matrix can be constructed. If a vector the density matrix is constructed as the projector of that vector. If a quantum instruction, the density matrix is constructed by assuming all qubits are initialized in the zero state. dims: The subsystem dimension of the state (See additional information). Raises: QiskitError: if input data is not valid. Additional Information: The ``dims`` kwarg can be None, an integer, or an iterable of integers. * ``Iterable`` -- the subsystem dimensions are the values in the list with the total number of subsystems given by the length of the list. * ``Int`` or ``None`` -- the leading dimension of the input matrix specifies the total dimension of the density matrix. If it is a power of two the state will be initialized as an N-qubit state. If it is not a power of two the state will have a single d-dimensional subsystem. dtype to_operatorN to_matrixz+Invalid input data format for DensityMatrixrz1Invalid DensityMatrix input: not a square matrix.)shapedims_ldims_r)op_shape) isinstancelistnpndarrayasarraycomplex_datarrrfrom_instructionhasattrrdata output_dimsr r ndimr#outerconjreshapesuper__init__r auto)selfr0dimsopr2r# __class__s b/home/james-whalen/.local/lib/python3.13/site-packages/qiskit/quantum_info/states/densitymatrix.pyr7DensityMatrix.__init__1s> dT2::. / /D8DJ ~{; < <'77=CCDJ T= ) )!!#BDJ|~~' T; ' 'DNN$4GDDJKL Lzz    19qU1X-  QY$**bggdjj.ABDJ QY58q=DJJa9DJQR R ',,TZZ5E5Ed"`acvUcURROUn[R"URXS9$)N)rcopy)r0rr)array)r9rrAs r= __array__DensityMatrix.__array__ts*#(= exx ::r?c>[TU]U5=(a? [R"URURUR UR S9$)Nrtolatol)r6__eq__r)allcloser-rGrH)r9otherr<s r=rIDensityMatrix.__eq__xs=w~e$  JJ $))$))*  r?cSn[U5S-nU[R"URSUS9SUSURR 5S3$)NzDensityMatrix( z, ) separatorprefixz, zdims=))lenr) array2stringr- _op_shaper$)r9rPpads r=__repr__DensityMatrix.__repr__}sX!&kChrtzzT&QRRUe5..01 4 r?cPURURR5S.$)zReturn settings.)r0r:)r0rTr$r9s r=settingsDensityMatrix.settingss  4>>+@+@+BCCr?c $SSKJn U"U4SU0UD6$)aReturn a visualization of the Statevector. **repr**: ASCII TextMatrix of the state's ``__repr__``. **text**: ASCII TextMatrix that can be printed in the console. **latex**: An IPython Latex object for displaying in Jupyter Notebooks. **latex_source**: Raw, uncompiled ASCII source to generate array using LaTeX. **qsphere**: Matplotlib figure, rendering of density matrix using `plot_state_qsphere()`. **hinton**: Matplotlib figure, rendering of density matrix using `plot_state_hinton()`. **bloch**: Matplotlib figure, rendering of density matrix using `plot_bloch_multivector()`. Args: output (str): Select the output method to use for drawing the state. Valid choices are `repr`, `text`, `latex`, `latex_source`, `qsphere`, `hinton`, or `bloch`. Default is `repr`. Default can be changed by adding the line ``state_drawer = `` to ``~/.qiskit/settings.conf`` under ``[default]``. drawer_args: Arguments to be passed directly to the relevant drawing function or constructor (`TextMatrix()`, `array_to_latex()`, `plot_state_qsphere()`, `plot_state_hinton()` or `plot_bloch_multivector()`). See the relevant function under `qiskit.visualization` for that function's documentation. Returns: :class:`matplotlib.Figure` or :class:`str` or :class:`TextMatrix` or :class:`IPython.display.Latex`: Drawing of the Statevector. Raises: ValueError: when an invalid output method is selected. r) state_draweroutput)(qiskit.visualization.state_visualizationr])r9r^ drawer_argsr]s r=drawDensityMatrix.drawsL JD??;??r?cUR5n[U[5(a [U5 gSSKJn U"U5 g)Nr)display)rar'strprintIPython.displayrd)r9outrds r=_ipython_display_DensityMatrix._ipython_display_s+iik c3   #J / CLr?cUR$)z Return data.r-rYs r=r0DensityMatrix.dataszzr?cUc URnUc URn[R"UR 5SX!S9(dg[ UR X!S9(dg[UR X!S9$)z1Return True if trace 1 and positive semidefinite.r"rFF)rHrGr)rJtracerr0r)r9rHrGs r=is_validDensityMatrix.is_validsY <99D <99D{{4::<A"4994C.tyytOOr?cJUR5n[URXS9$)zConvert to Operator input_dimsr1)r:r r0)r9r:s r=rDensityMatrix.to_operatorsyy{ dEEr?cn[[R"UR5UR 5S9$)z+Return the conjugate of the density matrix.r:)rr)r4r0r:rYs r= conjugateDensityMatrix.conjugates"RWWTYY/diikBBr?cB[R"UR5$)z'Return the trace of the density matrix.)r)ror0rYs r=roDensityMatrix.tracesxx ""r?c[R"[R"URUR55$)z'Return the purity of the quantum state.)r)rodotr0rYs r=purityDensityMatrix.puritys& xxtyy$))455r?c&[U[5(d [U5n[R"U5n[R "UR UR 5UlURRUR5UlU$)uReturn the tensor product state self ⊗ other. Args: other (DensityMatrix): a quantum state object. Returns: DensityMatrix: the tensor product operator self ⊗ other. Raises: QiskitError: if other is not a quantum state. ) r'r_copyrAr)kronr-rTtensorr9rKrets r=rDensityMatrix.tensorsb%//!%(EjjGGDJJ 4 --eoo>  r?c&[U[5(d [U5n[R"U5n[R "UR UR 5UlURRUR5UlU$)uReturn the tensor product state other ⊗ self. Args: other (DensityMatrix): a quantum state object. Returns: DensityMatrix: the tensor product state other ⊗ self. Raises: QiskitError: if other is not a quantum state. ) r'rrrAr)rr-rTexpandrs r=rDensityMatrix.expandsb%//!%(EjjGGEKK4 --eoo>  r?c[U[5(d [U5nURRUR5 [R "U5nUR UR -UlU$)aReturn the linear combination self + other. Args: other (DensityMatrix): a quantum state object. Returns: DensityMatrix: the linear combination self + other. Raises: QiskitError: if other is not a quantum state, or has incompatible dimensions. )r'rrT _validate_addrrAr0r-rs r=_addDensityMatrix._add sX%//!%(E $$U__5jjII *  r?c[U[5(d [S5e[R"U5nXR -UlU$)zReturn the scalar multiplied state other * self. Args: other (complex): a complex number. Returns: DensityMatrix: the scalar multiplied state other * self. Raises: QiskitError: if other is not a valid complex number. zother is not a number)r'rr rrAr0r-rs r= _multiplyDensityMatrix._multiply s>%((56 6jjII%  r?cUc [USS5n[U[[45(aUR XS9$[ US5(aUR 5RXS9$[U[5(aURXS9$[U[5(dURUS9n[XUS9nURXS9$)aREvolve a quantum state by an operator. Args: other: The operator to evolve by. qargs: a list of QuantumState subsystem positions to apply the operator on. Returns: The output density matrix. Raises: QiskitError: if the operator dimension does not match the specified QuantumState subsystem dimensions. Nqargsrto_quantumchannelrs) getattrr'rr_evolve_instructionr/r_evolverr r:_evolve_operator)r9rKrr:s r=evolveDensityMatrix.evolve2s$ =E7D1E enk: ; ;++E+? ? 5- . .**,44T4G G e^ , ,===3 3%**9959)DUFE$$U$88r?c^[R"U5n[[URR S- SS55mT[U4SjT55-m[ R"[ R"[ R"URURR5T5URR5Ul URR5UlU$)awReturn a DensityMatrix with reversed subsystem ordering. For a tensor product state this is equivalent to reversing the order of tensor product subsystems. For a density matrix :math:`\rho = \rho_{n-1} \otimes ... \otimes \rho_0` the returned state will be :math:`\rho_0 \otimes ... \otimes \rho_{n-1}`. Returns: DensityMatrix: the state with reversed subsystem order. r"c3@># UHn[T5U-v M g7fN)rR).0iaxess r= .DensityMatrix.reverse_qargs..gs84aCIM4s)rrAtuplerangerT _num_qargs_lr)r5 transposer0 tensor_shaper#r-reverse)r9rrs @r= reverse_qargsDensityMatrix.reverse_qargsYsjjU4>>66:BCDe84888JJ LLDIIt~~/J/JKT R NN   ..0  r?c [U5nUc[R"U5nO[R"U5n[R"SU-UR 5n[R"SU-UR 5nUR(aSUR-OSnXV-S:XaXpR5-$[R"URSS9nUS:XaU[XRU5-$XAR Sn SUR5-n U Sn U[XRXeX5-$)zCompute the expectation value of a Pauli. Args: pauli (Pauli): a Pauli operator to evaluate expval of. qargs (None or list): subsystems to apply operator on. Returns: complex: the expectation value. r"yrF)orderr)rRr)arangerBr}xzphaseroravelr0r num_qubits_count_yr) r9paulirn_pauliqubitsx_maskz_mask pauli_phaser0x_maxy_phases r=_expectation_value_pauli&DensityMatrix._expectation_value_paulios e* =YYw'FXXe_FV UWW-V UWW-.3kksu{{*q ?a - -xx - Q;!:4RX!YY Yww#5>>++!*8 //67   r?c^^[U[5(aTRUT5$[U[5(aS[ UU4Sj[ UR RUR RUR555$[U[5(d [U5n[R"[T5RUTS9R5$)zCompute the expectation value of an operator. Args: oper (Operator): an operator to evaluate expval. qargs (None or list): subsystems to apply the operator on. Returns: complex: the expectation value. c3h># UH'upnUTR[X45T5-v M) g7fr)rr)rrrcoeffrr9s r=r2DensityMatrix.expectation_value..s4#QKA%55eQFmUKK#Qs/2r)r'rrrsumzippaulisrrcoeffsr r)ror}r0)r9operrs` `r=expectation_valueDensityMatrix.expectation_values dE " "00u= = dM * *#&t{{}}dkkmmT[[#Q  $))D>Dxx**4u*=BBCCr?cUR[R"URR 55UR R 5US9n[R"USSS9nUbURUS9nU$)a'Return the subsystem measurement probability vector. Measurement probabilities are with respect to measurement in the computation (diagonal) basis. Args: qargs (None or list): subsystems to return probabilities for, if None return for all subsystems (Default: None). decimals (None or int): the number of decimal places to round values. If None no rounding is done (Default: None). Returns: np.array: The Numpy vector array of probabilities. Examples: Consider a 2-qubit product state :math:`\rho=\rho_1\otimes\rho_0` with :math:`\rho_1=|+\rangle\!\langle+|`, :math:`\rho_0=|0\rangle\!\langle0|`. .. plot:: :include-source: :nofigs: from qiskit.quantum_info import DensityMatrix rho = DensityMatrix.from_label('+0') # Probabilities for measuring both qubits probs = rho.probabilities() print('probs: {}'.format(probs)) # Probabilities for measuring only qubit-0 probs_qubit_0 = rho.probabilities([0]) print('Qubit-0 probs: {}'.format(probs_qubit_0)) # Probabilities for measuring only qubit-1 probs_qubit_1 = rho.probabilities([1]) print('Qubit-1 probs: {}'.format(probs_qubit_1)) .. code-block:: text probs: [0.5 0. 0.5 0. ] Qubit-0 probs: [1. 0.] Qubit-1 probs: [0.5 0.5] We can also permute the order of qubits in the ``qargs`` list to change the qubit position in the probabilities output .. plot:: :include-source: :nofigs: from qiskit.quantum_info import DensityMatrix rho = DensityMatrix.from_label('+0') # Probabilities for measuring both qubits probs = rho.probabilities([0, 1]) print('probs: {}'.format(probs)) # Probabilities for measuring both qubits # but swapping qubits 0 and 1 in output probs_swapped = rho.probabilities([1, 0]) print('Swapped probs: {}'.format(probs_swapped)) .. code-block:: text probs: [0.5 0. 0.5 0. ] Swapped probs: [0.5 0.5 0. 0. ] rrr")a_mina_max)decimals) _subsystem_probabilitiesr)absr0diagonalrTr$clipround)r9rrprobss r= probabilitiesDensityMatrix.probabilitiesssT-- FF499%%' ($..*?*?*A.  Qa0  KKK2E r?cUcP[R"U5n[R"URR [ S9nSUS'X2lU$URU5n[[USS95n[[U55RR5URS'URXQS9$)aReset state or subsystems to the 0-state. Args: qargs (list or None): subsystems to reset, if None all subsystems will be reset to their 0-state (Default: None). Returns: DensityMatrix: the reset state. Additional Information: If all subsystems are reset this will return the ground state on all subsystems. If only a some subsystems are reset this function will perform evolution by the reset :class:`~qiskit.quantum_info.SuperOp` of the reset subsystems. rr"rrr)rr)rrAr)zerosrTr#r,r-r:rrr r0rr)r9rrstater: reset_superops r=resetDensityMatrix.resets" =**T"CHHT^^11AEE$KIJyyQ 78 ($ 8 = = C C E 1{{={66r?c@[[R"U55$)aReturn a tensor product of Pauli X,Y,Z eigenstates. .. list-table:: Single-qubit state labels :header-rows: 1 * - Label - Statevector * - ``"0"`` - :math:`\begin{pmatrix} 1 & 0 \\ 0 & 0 \end{pmatrix}` * - ``"1"`` - :math:`\begin{pmatrix} 0 & 0 \\ 0 & 1 \end{pmatrix}` * - ``"+"`` - :math:`\frac{1}{2}\begin{pmatrix} 1 & 1 \\ 1 & 1 \end{pmatrix}` * - ``"-"`` - :math:`\frac{1}{2}\begin{pmatrix} 1 & -1 \\ -1 & 1 \end{pmatrix}` * - ``"r"`` - :math:`\frac{1}{2}\begin{pmatrix} 1 & -i \\ i & 1 \end{pmatrix}` * - ``"l"`` - :math:`\frac{1}{2}\begin{pmatrix} 1 & i \\ -i & 1 \end{pmatrix}` Args: label (string): a eigenstate string ket label (see table for allowed values). Returns: DensityMatrix: The N-qubit basis state density matrix. Raises: QiskitError: if the label contains invalid characters, or the length of the label is larger than an explicitly specified num_qubits. )rr from_label)clslabels r=rDensityMatrix.from_labelsD[33E:;;r?c[R"U5n[R"X"4[S9nSX0U4'[ X1S9$)a4Return a computational basis state density matrix. Args: i (int): the basis state element. dims (int or tuple or list): The subsystem dimensions of the statevector (See additional information). Returns: DensityMatrix: The computational basis state :math:`|i\rangle\!\langle i|`. Additional Information: The ``dims`` kwarg can be an integer or an iterable of integers. * ``Iterable`` -- the subsystem dimensions are the values in the list with the total number of subsystems given by the length of the list. * ``Int`` -- the integer specifies the total dimension of the state. If it is a power of two the state will be initialized as an N-qubit state. If it is not a power of two the state will have a single d-dimensional subsystem. rg?rw)r)prodrr,r)rr:sizers r=from_intDensityMatrix.from_int@s9.wwt}$W5d U..r?c[U[5(aUR5nURn[R "SU-SU-4[ S9nSUS'[X2S-S9nURU5 U$)aReturn the output density matrix of an instruction. The statevector is initialized in the state :math:`|{0,\ldots,0}\rangle` of the same number of qubits as the input instruction or circuit, evolved by the input instruction, and the output statevector returned. Args: instruction: instruction or circuit Returns: The final density matrix. Raises: QiskitError: if the instruction contains invalid instructions for density matrix simulation. r!rr"r)r!rw) r'rto_instructionrr)rr,r_append_instruction)r instructionrinitvecs r=r.DensityMatrix.from_instruction\sr* k> 2 2%446K ++ xxJ: 6gFT DD'89  , r?cjURURURR5USS9$)aConvert the density matrix to dictionary form. This dictionary representation uses a Ket-like notation where the dictionary keys are qudit strings for the subsystem basis vectors. If any subsystem has a dimension greater than 10 comma delimiters are inserted between integers so that subsystems can be distinguished. Args: decimals (None or int): the number of decimal places to round values. If None no rounding is done (Default: None). Returns: dict: the dictionary form of the DensityMatrix. Examples: The ket-form of a 2-qubit density matrix :math:`rho = |-\rangle\!\langle -|\otimes |0\rangle\!\langle 0|` .. plot:: :include-source: :nofigs: from qiskit.quantum_info import DensityMatrix rho = DensityMatrix.from_label('-0') print(rho.to_dict()) .. code-block:: text { '00|00': (0.4999999999999999+0j), '10|00': (-0.4999999999999999-0j), '00|10': (-0.4999999999999999+0j), '10|10': (0.4999999999999999+0j) } For non-qubit subsystems the integer range can go from 0 to 9. For example in a qutrit system .. plot:: :include-source: :nofigs: import numpy as np from qiskit.quantum_info import DensityMatrix mat = np.zeros((9, 9)) mat[0, 0] = 0.25 mat[3, 3] = 0.25 mat[6, 6] = 0.25 mat[-1, -1] = 0.25 rho = DensityMatrix(mat, dims=(3, 3)) print(rho.to_dict()) .. code-block:: text {'00|00': (0.25+0j), '10|10': (0.25+0j), '20|20': (0.25+0j), '22|22': (0.25+0j)} For large subsystem dimensions delimiters are required. The following example is for a 20-dimensional system consisting of a qubit and 10-dimensional qudit. .. plot:: :include-source: :nofigs: import numpy as np from qiskit.quantum_info import DensityMatrix mat = np.zeros((2 * 10, 2 * 10)) mat[0, 0] = 0.5 mat[-1, -1] = 0.5 rho = DensityMatrix(mat, dims=(2, 10)) print(rho.to_dict()) .. code-block:: text {'00|00': (0.5+0j), '91|91': (0.5+0j)} T)r string_labels)_matrix_to_dictr0rTr$)r9rs r=to_dictDensityMatrix.to_dict{s8d## IIt~~,,.QU$  r?cURRURUS9nURUlURUl[ R"U5nUc`URn[R"XPR5RURR55Ul X4lU$[R"URURR5n[!UR#55nUVs/sH oS- U- PM n n[R"URURR5n [$R&"XjU 5nUR)5n [R"U RU RR5n [$R&"XlXS5n[R"XcR*5Ul X4lU$s snf)z$Evolve density matrix by an operatorrr"T)rTcompose_dims_l_dims_rr _num_qargs_rrrAr0r)r}Tr4r-r5rrRr:r _einsum_matmuladjointr#) r9rKr new_shaperop_matr num_indicesqubitindicesmatadjmat_adjs r=rDensityMatrix._evolve_operatorshNN**5??%*H %-- !*!7!7 jj =ZZFvyy155fhhmmoFCI%MJDIIt~~'B'BC$))+& 8=>u?U*>jjU__%A%AB((g>mmo**SXXs}}'A'AB(('PTUJJv7 !  ?sG;cBSSKJn SSKJn [R "U5nUb)UR [ U5US9RUlg[X5(a!URU5RUlg[X5(ag[R"U5nUbURXS9RUlgURc[SUR 35e[UR["5(d.[UR S[%UR5S35e['URR(5VVs0sHupxX_M n nnURHn U R*(a"[S U R,R 35eUcU R(V s/sHoU PM n n O U R(V s/sH oXPM n n UR/U R,U S9 M gs snnfs sn fs sn f) z:Update the current Statevector by applying an instruction.r)Reset)BarrierNrzCannot apply Instruction: z instruction definition is z; expected QuantumCircuitz.Cannot apply instruction with classical bits: )qiskit.circuit.resetrqiskit.circuit.barrierrr _instruction_to_matrixrr0r-r'rr_instruction_to_superopr definitionr namertype enumeraterclbits operationr) r9rKrrrrchanidxbit qubit_indicesrtup new_qargss r=r!DensityMatrix._append_instructions.2--e4 ?..x}E.JOODJ  e # #E*00DJ  e % % ..u5  d8==DJ     # :5::,GH H%**N;;::,9$u?O?O:P9QR+, 3 * *$$&Cjj 1 r?cUc URnUc URn[URXS9(d [ S5e[ R RUR5up4U[U5U:n[U5S:wd[ R"USSXS9(d [ S5eUSS2[ R"U54n[U5$)aReturn a statevector from a pure density matrix. Args: atol (float): Absolute tolerance for checking operation validity. rtol (float): Relative tolerance for checking operation validity. Returns: Statevector: The pure density matrix's corresponding statevector. Corresponds to the eigenvector of the only non-zero eigenvalue. Raises: QiskitError: if the state is not pure. N)rHrGz+Not a valid density matrix (non-hermitian).r"rz"Density matrix is not a pure state) rHrGrr-r r)linalgeigrrRiscloseargmaxr)r9rHrGevalsevecs nonzero_evalspsis r=to_statevectorDensityMatrix.to_statevector(s <99D <99D"4::DDKL Lyy}}TZZ0 c%j4/0 }  ""**]15Eqt*_BC CAryy''(3r?c URRURR5n[ URR 55S- [ R"U5- n[ UR55n[[SU-55nUHnXEU-XEsXE'XEU-'M [ R"X$5n[ R"X`RR5n[X`R5S9$)zReturn partially transposed density matrix. Args: qargs (list): The subsystems to be transposed. Returns: DensityMatrix: The partially transposed density matrix. r"r!rw)r-r5rTrrRr$r)rBr:r(rrr#r)r9rarrnlstrrhos r=partial_transposeDensityMatrix.partial_transposeHsjj  !!<!rTsa#  82)AK:;I<HTPAb>k 4L/k 4r?