z iSrSSKJr SSKrSSKrSSKrSSKJrJrJrJ r J r J r J r SSK Jr SSKJr SSKJr SSKJrJr SS KJr SS KJr SS KJr SS KJrJr S SKJrJr \R@(aSSK!r!"SS\RD5r#"SS\RH5r%"SS\\RD5r&"SS\#5r'g)z4Builder types for the basic control-flow constructs.) annotationsN) CollectionIterable FrozenSetTupleUnionOptionalSequence) CircuitData)Register)expr)ClbitClassicalRegister CircuitError) Instruction)CircuitInstruction)QubitQuantumRegister)condition_resourcesnode_resourcesc\rSrSrSrSr\\RSSj55r \RSS.SSjj5r \RSSj5r \RSS j5r \RSS j5r \RSS j5r\RSS j5r\RSS j5r\RSSj5r\RSSj5r\RSSj5rSrg)CircuitScopeInterface*aAn interface that circuits and builder blocks explicitly fulfill, which contains the primitive methods of circuit construction and object validation. This allows core circuit methods to be applied to the currently open builder scope, and allows the builders to hook into all places where circuit resources might be used. This allows the builders to track the resources being used, without getting in the way of :class:`.QuantumCircuit` doing its own thing. cg)zIIndexable view onto the :class:`.CircuitInstruction`s backing this scope.Nrselfs \/home/james-whalen/.local/lib/python3.13/site-packages/qiskit/circuit/controlflow/builder.py instructions"CircuitScopeInterface.instructions6F_standard_gatecg)aLow-level 'append' primitive; this may assume that the qubits, clbits and operation are all valid for the circuit. Abstraction of :meth:`.QuantumCircuit._append` (the low-level one, not the high-level). Args: instruction: the resource-validated instruction context object. Returns: the instruction context object actually appended. This is not required to be the same as the object given (but typically will be). Nr)r instructionr&s r appendCircuitScopeInterface.append;r#r$cg)z_Appends all instructions from ``data`` to the scope. Args: data: The instruction listing. Nr)rdatas r extendCircuitScopeInterface.extendLr#r$cg)aResolve a single bit-like classical-resource specifier. A resource refers to either a classical bit or a register, where integers index into the classical bits of the greater circuit. This is called whenever a classical bit or register is being used outside the standard :class:`.Clbit` usage of instructions in :meth:`append`, such as in a legacy two-tuple condition. Args: specifier: the classical resource specifier. Returns: the resolved resource. This cannot be an integer any more; an integer input is resolved into a classical bit. Raises: CircuitError: if the resource cannot be used by the scope, such as an out-of-range index or a :class:`.Clbit` that isn't actually in the circuit. Nr)r specifiers r resolve_classical_resource0CircuitScopeInterface.resolve_classical_resourceTr#r$cg)aAdd an uninitialized variable to the circuit scope. The general circuit context is responsible for ensuring the variable is initialized. These uninitialized variables are guaranteed to be standalone. Args: var: the variable to add, if valid. Raises: CircuitError: if the variable cannot be added, such as because it invalidly shadows or redefines an existing name. Nrrvars r add_uninitialized_var+CircuitScopeInterface.add_uninitialized_varmr#r$cg)zAdd a stretch to the circuit scope. Args: stretch: the stretch to add, if valid. Raises: CircuitError: if the stretch cannot be added, such as because it invalidly shadows or redefines an existing name. Nrrstretchs r add_stretch!CircuitScopeInterface.add_stretch|r#r$cg)aCalled for every standalone classical real-time variable being used by some circuit instruction. The given variable is guaranteed to be a stand-alone variable; bit-like resource-wrapping variables will have been filtered out and their resources given to :meth:`resolve_classical_resource`. Args: var: the variable to validate. Raises: CircuitError: if the variable is not valid for this scope. Nrr4s r use_varCircuitScopeInterface.use_varr#r$cg)zCalled for every stretch being used by some circuit instruction. Args: stretch: the stretch to validate. Raises: CircuitError: if the stretch is not valid for this scope. Nrr9s r use_stretch!CircuitScopeInterface.use_stretchr#r$cg)a&Get the variable (if any) in scope with the given name. This should call up to the parent scope if in a control-flow builder scope, in case the variable exists in an outer scope. Args: name: the name of the symbol to lookup. Returns: the variable if it is found, otherwise ``None``. Nrrnames r get_varCircuitScopeInterface.get_varr#r$cg)a#Get the stretch (if any) in scope with the given name. This should call up to the parent scope if in a control-flow builder scope, in case the stretch exists in an outer scope. Args: name: the name of the symbol to lookup. Returns: the stretch if it is found, otherwise ``None``. NrrDs r get_stretch!CircuitScopeInterface.get_stretchr#r$cg)zCalled to mark that a :class:`~.circuit.Qubit` should be considered "used" by this scope, without appending an explicit instruction. The subclass may assume that the ``qubit`` is valid for the root scope.Nrrqubits r use_qubitCircuitScopeInterface.use_qubitr#r$N)returnzSequence[CircuitInstruction])r(rrPrr,r )r0zClbit | ClassicalRegister | intrPzClbit | ClassicalRegisterr5zexpr.Varr:z expr.Stretch)rEstrrPzOptional[expr.Var])rErTrPzOptional[expr.Stretch]rMr)__name__ __module__ __qualname____firstlineno____doc__ __slots__propertyabcabstractmethodr!r)r-r1r6r;r>rArFrIrN__static_attributes__rr$r rr*sYI XX AF -        8 "  0                             SSr$rcR\rSrSr%SrSrS\S'SrS\S'SrS\S 'Sr S \S 'Sr g ) InstructionResourcesaThe quantum and classical resources used within a particular instruction. .. warning:: This is an internal interface and no part of it should be relied upon outside of Qiskit Terra. Attributes: qubits: A collection of qubits that will be used by the instruction. clbits: A collection of clbits that will be used by the instruction. qregs: A collection of quantum registers that are used by the instruction. cregs: A collection of classical registers that are used by the instruction. rzCollection[Qubit]qubitszCollection[Clbit]clbitszCollection[QuantumRegister]qregszCollection[ClassicalRegister]cregsN) rVrWrXrYrZrc__annotations__rdrerfr_rr$r raras5 !#F " "F ")+E &++-E (-r$rac~\rSrSrSrSr\RS Sj5r\RS Sj5r Sr Sr g) InstructionPlaceholderaA fake instruction that lies about its number of qubits and clbits. These instances are used to temporarily represent control-flow instructions during the builder process, when their lengths cannot be known until the end of the block. This is necessary to allow constructs like:: with qc.for_loop(range(5)): qc.h(0) qc.measure(0, 0) with qc.if_test((0, 0)): qc.break_loop() ``qc.break_loop()`` needed to return a (mostly) functional :obj:`~qiskit.circuit.Instruction` in order for the historical ``.InstructionSet.c_if`` to work correctly. When appending a placeholder instruction into a circuit scope, you should create the placeholder, and then ask it what resources it should be considered as using from the start by calling :meth:`.InstructionPlaceholder.placeholder_instructions`. This set will be a subset of the final resources it asks for, but it is used for initializing resources that *must* be supplied, such as the bits used in the conditions of placeholder ``if`` statements. .. warning:: This is an internal interface and no part of it should be relied upon outside of Qiskit Terra. Tc[e)a$Get a concrete, complete instruction that is valid to act over all the given resources. The returned resources may not be the full width of the given resources, but will certainly be a subset of them; this can occur if (for example) a placeholder ``if`` statement is present, but does not itself contain any placeholder instructions. For resource efficiency, the returned :class:`.ControlFlowOp` will not unnecessarily span all resources, but only the ones that it needs. .. note:: The caller of this function is responsible for ensuring that the inputs to this function are non-strict supersets of the bits returned by :meth:`placeholder_resources`. Args: qubits: The qubits the created instruction should be defined across. clbits: The clbits the created instruction should be defined across. Returns: A full version of the relevant control-flow instruction, and the resources that it uses. This is a "proper" instruction instance, as if it had been defined with the correct number of qubits and clbits from the beginning. NotImplementedError)rrcrds r concrete_instruction+InstructionPlaceholder.concrete_instructions 6"!r$c[e)aGet the qubit and clbit resources that this placeholder instruction should be considered as using before construction. This will likely not include *all* resources after the block has been built, but using the output of this method ensures that all resources will pass through a :meth:`.QuantumCircuit.append` call, even if they come from a placeholder, and consequently will be tracked by the scope managers. Returns: A collection of the quantum and classical resources this placeholder instruction will certainly use. rlrs r placeholder_resources,InstructionPlaceholder.placeholder_resourcess "!r$c[S5e)Nz(Cannot repeat a placeholder instruction.r)rns r repeatInstructionPlaceholder.repeat+sEFFr$rN)rcFrozenSet[Qubit]rdFrozenSet[Clbit]rPz(Tuple[Instruction, InstructionResources])rPra) rVrWrXrYrZ _directiver]r^rnrqrur_rr$r riris^8J"&"0@" 1""8  " "$Gr$ricV\rSrSrSrSrSSSS.S%SjjrS rS r\ S 5r \ S 5r \ S 5r SS.S&SjjrS'SjrSrS(SjrS)SjrS*SjrS*SjrS(SjrS)SjrS+SjrSrSrSrSrS,SjrS,SjrS-S jrS.S!jrS/S"jr S0S#jr!S$r"g)1ControlFlowBuilderBlocki/a5A lightweight scoped block for holding instructions within a control-flow builder context. This class is designed only to be used by :obj:`.QuantumCircuit` as an internal context for control-flow builder instructions, and in general should never be instantiated by any code other than that. Note that the instructions that are added to this scope may not be valid yet, so this elides some of the type-checking of :obj:`.QuantumCircuit` until those things are known. The general principle of the resource tracking through these builder blocks is that every necessary resource should pass through an :meth:`.append` call, so that at the point that :meth:`.build` is called, the scope knows all the concrete resources that it requires. However, the scope can also contain "placeholder" instructions, which may need extra resources filling in from outer scopes (such as a ``break`` needing to know the width of its containing ``for`` loop). This means that :meth:`.build` takes all the *containing* scope's resources as well. This does not break the "all resources pass through an append" rule, because the containing scope will only begin to build its instructions once it has received them all. In short, :meth:`.append` adds resources, and :meth:`.build` may use only a subset of the extra ones passed. This ensures that all instructions know about all the resources they need, even in the case of ``break``, but do not block any resources that they do *not* need. .. warning:: This is an internal interface and no part of it should be relied upon outside of Qiskit Terra. ) _instructions registers global_phase _allow_jumps_parent_built_forbidden_message _vars_local _vars_capture_stretches_local_stretches_capturerTN)r} allow_jumpsforbidden_messagec[X5Ul[U5UlSUl0Ul0Ul0Ul0UlXPl X0l SUl X`l g)a Args: qubits: Any qubits this scope should consider itself as using from the beginning. clbits: Any clbits this scope should consider itself as using from the beginning. Along with ``qubits``, this is useful for things such as ``if`` and ``while`` loop builders, where the classical condition has associated resources, and is known when this scope is created. registers: Any registers this scope should consider itself as using from the beginning. This is useful for :obj:`.IfElseOp` and :obj:`.WhileLoopOp` instances which use a classical register as their condition. allow_jumps: Whether this builder scope should allow ``break`` and ``continue`` statements within it. This is intended to help give sensible error messages when dangerous behavior is encountered, such as using ``break`` inside an ``if`` context manager that is not within a ``for`` manager. This can only be safe if the user is going to place the resulting :obj:`.QuantumCircuit` inside a :obj:`.ForLoopOp` that uses *exactly* the same set of resources. We cannot verify this from within the builder interface (and it is too expensive to do when the ``for`` op is made), so we fail safe, and require the user to use the more verbose, internal form. parent: The scope interface of the containing scope. forbidden_message: If a string is given here, a :exc:`.CircuitError` will be raised on any attempts to append instructions to the scope with this message. This is used by pseudo scopes where the state machine of the builder scopes has changed into a position where no instructions should be accepted, such as when inside a ``switch`` but outside any cases. gFN) r r|setr}r~rrrrrrrr)rrcrdparentr}rrs r __init__ ControlFlowBuilderBlock.__init__Zs]F)8Y ""$'  "3r$c@[URR5$)z-The set of qubits associated with this scope.)rr!rcrs r rcControlFlowBuilderBlock.qubits4$$++,,r$c@[URR5$)z-The set of clbits associated with this scope.)rr!rdrs r rdControlFlowBuilderBlock.clbitsrr$cUR$)aWhether this builder scope should allow ``break`` and ``continue`` statements within it. This is intended to help give sensible error messages when dangerous behavior is encountered, such as using ``break`` inside an ``if`` context manager that is not within a ``for`` manager. This can only be safe if the user is going to place the resulting :obj:`.QuantumCircuit` inside a :obj:`.ForLoopOp` that uses *exactly* the same set of resources. We cannot verify this from within the builder interface (and it is too expensive to do when the ``for`` op is made), so we fail safe, and require the user to use the more verbose, internal form. )rrs r r#ControlFlowBuilderBlock.allow_jumpss   r$cUR$N)r|rs r r!$ControlFlowBuilderBlock.instructionss!!!r$c~SSKJnJn SSKJnJn XX44n[ X5(a[SURS35eg)Nr) BreakLoopOpBreakLoopPlaceholder)ContinueLoopOpContinueLoopPlaceholderz)The current builder scope cannot take a 'z' because it is not in a loop.) break_looprr continue_looprr isinstancerrE) operationrrrr forbiddens r _raise_on_jump&ControlFlowBuilderBlock._raise_on_jumpsI BJ ` i + +;INN;KL00  ,r$Fr%cURb[UR5eUR(dURUR5 UR HnUR RUSS9 M URHnUR RUSS9 M URRU5 U$NFstrict) rrrrrrcr! add_qubitrd add_clbitr|r))rr(r&bs r r)ControlFlowBuilderBlock.appends  " " .t667 7     5 5 6##A    ' '% ' 8$##A    ' '% ' 8$ !!+.r$cURb[UR5eUR(dURUR5 UR 5up#UR H$nXB;dM URRUSS9 M& URH$nXC;dM URRUSS9 M& URRU5 gr) rrr foreach_opr active_bitsrcr!rrdrr-)rr, active_qubits active_clbitsrs r r-ControlFlowBuilderBlock.extends  " " .t667 7  OOD// 0'+'7'7'9$ A!!!++Ae+<A!!!++Ae+<   &r$cUR(a [S5eURRU5n[ U[ 5(aUR U45 U$URU5 U$)N4Cannot add resources after the scope has been built.)rrrr1rradd_bits add_register)rr0resources r r12ControlFlowBuilderBlock.resolve_classical_resources` ;;UV V<<::9E h & & MM8+ &   h 'r$cUR(a [S5eURRUR5=nb[SUSUS35eUR RUR5=nb&X!:Xa[SUS35e[SUSUS35eURUR ;dURUR;a[SUSUS35eXR UR'gNrz cannot add 'z$' as its name shadows the existing ''z!' is already present in the scope)rrrgetrErrr)rr5previouss r r6-ControlFlowBuilderBlock.add_uninitialized_vars ;;UV V--11#((; ;H HcU2VW_V``abc c((,,SXX6 6H C"Qse+L#MNNcU2VW_V``abc c 88t)) )SXX9P9P-PcU2VW_V``abc c%("r$cUR(a [S5eURRUR5=nb[SUSUS35eUR RUR5=nb&X!:Xa[SUS35e[SUSUS35eURUR ;dURUR;a[SUSUS35eXR UR'gr)rrrrrErrr)rr:rs r r;#ControlFlowBuilderBlock.add_stretchs ;;UV V((,,W\\: :H Gwi'KH:UVW --11',,? ?H L""Qwi/P#QRRwi'KH:UVW  <<4-- -AXAX1Xwi'KH:UVW /6gll+r$cXR;agURRU5=nbU$URR U5$r)rrrrrFrrEouts r rFControlFlowBuilderBlock.get_varsG (( (##''- -C :J||##D))r$cXR;agURRU5=nbU$URR U5$r)rrrrrIrs r rI#ControlFlowBuilderBlock.get_stretchsG ## #((,,T2 2C ?J||''--r$c"URRUR5=nb[SUSUS35eURRUR5=nbX!:Xag[SUSUS35eUR RUR5U:XagUR RUR5U:wa[SUS35eUR RU5 XR UR'gNz cannot use 'z"' which is shadowed by the local 'rzcannot close over 'z', which is not in scope) rrrErrrrrFr>)rr5locals r r>ControlFlowBuilderBlock.use_var s**..sxx8 8E EcU2TUZT[[\]^ ^%%))#((3 3E @|cU2TUZT[[\]^ ^    ! !#(( +s 2  <<   )S 0!4SE9QRS S S!'*388$r$c"URRUR5=nb[SUSUS35eURRUR5=nbX!:Xag[SUSUS35eUR RUR5U:XagUR RUR5U:wa[SUS35eUR RU5 XR UR'gr) rrrErrrrrIrA)rr:rs r rA#ControlFlowBuilderBlock.use_stretchs%%))',,7 7E DgY6XY^X__`ab b**..w||< C''!!++C+>"WX[W\\^ _`` r$c|XR;agURRU5 URU5 g)zAdd a :obj:`.Register` to the set of resources used by this block, ensuring that all bits contained within are also accounted for. Args: register: the register to add to the block. N)r}addr)rregisters r r$ControlFlowBuilderBlock.add_register]s/ ~~ %  8$ hr$c ^^^^ ^ ^ ^ ^ SSKJnJm STlTRb [ S5e[ T5TR5- m [ T5TR5- m U"TRRTRR/TRQ7TR[R"TRR5TR R55S.6m TR"R5HnT R%U5 M TR&R5HnT R)U5 M 0m U UUU U U U U4SjnTRR+U5 TRR-5nUR/T RT R5 T R15H upxXU'M T R35R5U5 T $)abBuild this scoped block into a complete :obj:`.QuantumCircuit` instance. This will build a circuit which contains all of the necessary qubits and clbits and no others. The ``qubits`` and ``clbits`` arguments should be sets that contains all the resources in the outer scope; these will be passed down to inner placeholder instructions, so they can apply themselves across the whole scope should they need to. The resulting :obj:`.QuantumCircuit` will be defined over a (nonstrict) subset of these resources. This is used to let ``break`` and ``continue`` span all resources, even if they are nested within several :obj:`.IfElsePlaceholder` objects, without requiring :obj:`.IfElsePlaceholder` objects *without* any ``break`` or ``continue`` statements to be full-width. Args: all_qubits: all the qubits in the containing scope of this block. The block may expand to use some or all of these qubits, but will never gain qubits that are not in this set. all_clbits: all the clbits in the containing scope of this block. The block may expand to use some or all of these clbits, but will never gain clbits that are not in this set. Returns: A circuit containing concrete versions of all the instructions that were in the scope, and using the minimal set of resources necessary to support them, within the enclosing scope. r)QuantumCircuit SwitchCaseOpTz[U[5(GaCURT T 5up[UR5n[UR 5n[ XU5TU'T(aAU(a:TRU5nU(a"TRU5 T RU5 T(aAU(a:TRU5nU(a"TRU5 T RU5 [R"URUR5H7nUTR;dMTRU5 T RU5 M9 [!USS5b[[#UR$5RH7nUTR;dMTRU5 T RU5 M9 g[UT 5(aUR&n[U[(5(aSn O.[U[*5(aU4n O[-U5Rn U H7nUTR;dMTRU5 T RU5 M9 gg)N _conditionr)rrirntuplercrdr intersectiondifference_updater itertoolschainrerfr}rgetattrrrtargetrrr)indexop resourcesrcrd add_qubits add_clbitsrrtarget_registersr all_clbits all_qubitsrplaceholder_to_concretepotential_clbitspotential_qubitsrs r update_registers7ControlFlowBuilderBlock.build..update_registerss"455 " 7 7 J O y//0y//01CBPV1W'.$!1!>!>v!FJ!(:::F Z0#!1!>!>v!FJ!(:::F Z0 )  QHt~~5))(3((2 !R r<.: 3BMM B H HHt~~5))(3((2!IB --fe,,')$(9::(.y$'5f'='C'C$ 0Ht~~5))(3((2!1.r$)qiskit.circuitrrrr RuntimeErrorrrcrdr|r}r~rrrrrrr6rr;foreach_op_indexedcopy replace_bitsitems_current_scoper-)rrrrr5rout_datair(rrrrrs``` @@@@@r buildControlFlowBuilderBlock.buildjs< @   " " .]^ ^z?T[[]:z?T[[]:    % %    % % ^^ **__T%7%7%>%>%@$BYBYB`B`Bbc  ##**,C  % %c *- ((//1C OOC 2#%( 3( 3V --.>?%%**,cjj#**55;;=NA%QK> ##H- r$cH[U5R[U55nURR5UlURR5UlUR UlUR R5UlURR5UlURR5UlURR5Ul URUl URUl URUl U$)aReturn a semi-shallow copy of this builder block. The instruction lists and sets of qubits and clbits will be new instances (so mutations will not propagate), but any :obj:`.Instruction` instances within them will not be copied. Returns: a semi-shallow copy of this object. ) type__new__r|r r}r~rrrrrrr)rrs r r ControlFlowBuilderBlock.copys4j  d, ..335++- ,,**//1 ..335#4499;!%!8!8!=!=!?ll ,,!%!8!8 r$) rrrr|rrrrrr~r}) rczIterable[Qubit]rdzIterable[Clbit]rrr}zIterable[Register]rboolrz Optional[str])r(rr&rrPrrQrRrS)rErTrU)rPr)rzIterable[Union[Qubit, Clbit]])rr )rrwrrxrPz'qiskit.circuit.QuantumCircuit')rPz'ControlFlowBuilderBlock')#rVrWrXrYrZr[rrcrdr\rr! staticmethodrr)r-r1r6r;rFrIr>rArNrrrrrrrrrr r_rr$r r{r{/s@8 I()+ +/-4-4 -4 & -4 & -4-4)-4^-- ! !""  JO - BF    '  )6**. + 8:).+0& (a.  u*u8Hu (unr$r{)(rZ __future__rr]rtypingrrrrrr r qiskit._accelerate.circuitr rr qiskit.circuit.classicalr rrqiskit.circuit.exceptionsrqiskit.circuit.instructionr!qiskit.circuit.quantumcircuitdatarrr_builder_utilsrr TYPE_CHECKINGqiskitABCr NamedTuplerarir{rr$r r#s;#  TTT2#)322@1? ZSCGGZSz.6,,.*PG[#''PGfF3Fr$