z i/\SrSSKrSSKrSSKJr SSKJr SSKJr S Sjr Sr Sr S S jr g) z6 This module contains utility functions for circuits. N) _numpy_compat) QiskitError) CircuitErrorc~[[R"URS55nSU-n[R "S/S//SUS- /5nUcUS- nO![ U[5(a [US5n[ U[5(aSUs=::aU:d O [S5eO [S5e[R"[R"XR55n[R"[R"SU-5[R"U5U- 5[R"X5-nU$)a  Compute the controlled version of the input matrix with qiskit ordering. This function computes the controlled unitary with :math:`n` control qubits and :math:`m` target qubits, .. math:: V_n^j(U_{2^m}) = (U_{2^m} \otimes |j\rangle\!\langle j|) + (I_{2^m} \otimes (I_{2^n} - |j\rangle\!\langle j|)). where :math:`|j\rangle \in \mathcal{H}^{2^n}` is the control state. Args: base_mat (ndarray): unitary to be controlled num_ctrl_qubits (int): number of controls for new unitary ctrl_state (int or str or None): The control state in decimal or as a bitstring (e.g. '111'). If None, use 2**num_ctrl_qubits-1. Returns: ndarray: controlled version of base matrix. Raises: QiskitError: unrecognized mode or invalid ctrl_state rz&Invalid control state value specified.z%Invalid control state type specified.) intmathlog2shapenumpyrepeat isinstancestrrdiagrollkroneye)base_matnum_ctrl_qubits ctrl_state num_targetctrl_dim ctrl_grnd ctrl_projfull_mats O/home/james-whalen/.local/lib/python3.13/site-packages/qiskit/circuit/_utils.py_compute_control_matrixrs 2TYYx~~a012J/!H qcA3Z!X\):;I\ J $ $Q' *c""J))FG G*ABB 5::i<=Izz%))AzM2EIIh4G)4STW\WaWaXH OcSn[U[5(a[U5U:Xde[US5n[U[5(a"SUs=::a SU-:aO OUnU$[ S5eUc SU-S- nU$[ S[U535e![an[ SU-5UeSnAf[ an[ S5UeSnAff=f) a'Convert ctrl_state to int. Args: ctrl_state (None, str, int): ctrl_state. If None, set to 2**num_ctrl_qubits-1. If str, convert to int. If int, pass. num_ctrl_qubits (int): The number of control qubits. Return: int: ctrl_state Raises: CircuitError: invalid ctrl_state Nrzinvalid control bit string: z5invalid control bit string: length != num_ctrl_qubitsrz#invalid control state specificationrz%invalid control state specification: )rrlenr ValueErrorrAssertionErrorrepr)rrctrl_state_stdexs r_ctrl_state_to_intr'DsN*c"" `z?o5 55Z+J *c"" /Q/ /'N  DE E  O+a/ B4 CSBTUVV T= JKQS S `VW]_ _ `s#B CB** C7 CCc^^[R"U[RS9mTRSS9 S[R 4U4SjjmU4SjnU$)zClass decorator that adds an ``__array__`` method to a :class:`.Gate` instance that returns a singleton nonwritable view onto the complex matrix described by ``base_array``.dtypeFwriteNcP>Uc TROUn[R"TXS9$Nr*copy)r*r array)_selfr*r0 nonwritables r __array__"with_gate_array..__array__ms%%*] !!{{;e??rcN>[US5(a [S5eTUlU$Nr4zBRefusing to decorate a class that already has '__array__' defined.hasattr RuntimeErrorr4clsr4s r decorator"with_gate_array..decoratorq( 3 $ $cd d!  r)r r1 complex128setflagsrCOPY_ONLY_IF_NEEDED) base_arrayr=r4r3s @@rwith_gate_arrayrDgsJ++j0@0@AKu%#-*K*K@ rch^^^^[R"U[RS9mUU4SjnUc=[ST-5Vs/sH oC"U5PM snmS[R 4U4SjjmO3UVs0sH oDU"U5_M snmS[R 4UUU4SjjmU4SjnU$s snfs snf)aClass decorator that adds an ``__array__`` method to a :class:`.ControlledGate` instance that returns singleton nonwritable views onto a relevant precomputed complex matrix for the given control state. If ``cached_states`` is not given, then all possible control states are precomputed. If it is given, it should be an iterable of integers, and only these control states will be cached.r)c>[R"[TTU5[RS9nUR SS9 U$)Nr)Fr+)r asarrayrr@rA)stateoutbasers rmatrix_for_control_state.matrix_for_control_states;mm #D/5 A""  5 ! rNrcn>TURnUc UROUn[R"X1US9$r.)rr*r r1)selfr*r0arr nonwritabless rr4-with_controlled_gate_array..__array__s1t/C!&CIIEE;;sd; ;rc&>TRUR5=nb&Uc UROUn[R"X1US9$USLaU[ R La [S5e[R"[TTUR5US9$)Nr/Fz,could not produce matrix without calculationr)) getrr*r r1rrBr"rGr)rNr*r0rOrJrPrs rr4rQs#''88E%*] {{3$??u}]-N-N!N !OPP=='otOW\ rcN>[US5(a [S5eTUlU$r7r8r;s rr=-with_controlled_gate_array..decoratorr?r)r rGr@rangerrB) rCr cached_statesrKrHr=r4rJrPs ` @@@rwith_controlled_gate_arrayrXzs ==5+;+; >MZ "&]-N-N   7`[s B*3B/)N) __doc__r r qiskitrqiskit.exceptionsrqiskit.circuit.exceptionsrrr'rDrXrrr^s1 )2)X F&-r