gwpdZddlmZddlZddlZddlZddlmZmZmZm Z m Z m Z m Z ddl mZddlmZddlmZmZddlmZdd lmZdd lmZdd lmZmZdd lmZd dlm Z m!Z!ej"rddl#Z#Gddej$Z%Gddej&Z'Gddeej$Z(Gdde%Z)dS)z4Builder types for the basic control-flow constructs.) annotationsN) CollectionIterable FrozenSetTupleUnionOptionalSequence) CircuitData)expr)ClbitClassicalRegister CircuitError) Instruction)CircuitInstruction)QubitQuantumRegister)Register)condition_resourcesnode_resourcesc<eZdZdZdZeejddZejdddd Z ejdd Z ejddZ ejd dZ ejd dZ ejd dZejd!dZdS)"CircuitScopeInterfaceaAn 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. returnSequence[CircuitInstruction]cdS)zIIndexable view onto the :class:`.CircuitInstruction`s backing this scope.Nrselfs X/granary/edev/quantum/lib/python3.11/site-packages/qiskit/circuit/controlflow/builder.py instructionsz"CircuitScopeInterface.instructions6F_standard_gate instructionrcdS)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 r'r&s r!appendzCircuitScopeInterface.append;r#r$datar cdS)zwAppends all instructions from ``data`` to the scope. Args: data: The instruction listing. Nr)r r*s r!extendzCircuitScopeInterface.extendLr#r$ specifierClbit | ClassicalRegister | intClbit | ClassicalRegistercdS)aCResolve 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 r-s r!resolve_classical_resourcez0CircuitScopeInterface.resolve_classical_resourceTr#r$varexpr.VarcdS)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. Nrr r2s r!add_uninitialized_varz+CircuitScopeInterface.add_uninitialized_varmr#r$cdS)ajRemove a variable from the locals of this scope. This is only called in the case that an exception occurred while initializing the variable, and is not exposed to users. Args: var: the variable to remove. It can be assumed that this was already the subject of an :meth:`add_uninitialized_var` call. Nrr5s r! remove_varz CircuitScopeInterface.remove_var|r#r$cdS)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. Returns: the same variable. Raises: CircuitError: if the variable is not valid for this scope. Nrr5s r!use_varzCircuitScopeInterface.use_varr#r$namestrOptional[expr.Var]cdS)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``. Nr)r r;s r!get_varzCircuitScopeInterface.get_varr#r$N)rr)r'rrrr*r )r-r.rr/r2r3)r;r<rr=)__name__ __module__ __qualname____doc__ __slots__propertyabcabstractmethodr"r)r,r1r6r8r:r?rr$r!rr*s^I XXXXX AF                0                   $         r$rcLeZdZUdZdZded<dZded<dZded<dZd ed <d S) InstructionResourcesa#The 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) rBrCrDrErL__annotations__rMrNrOrr$r!rKrKsb  !#F"""" "F"""")+E+++++-E------r$rKcneZdZdZdZejdd Zejdd ZddZ dZ dZ dS)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) qc.break_loop().c_if(0, 0) since ``qc.break_loop()`` needs to return a (mostly) functional :obj:`~qiskit.circuit.Instruction` in order for :meth:`.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. TrLFrozenSet[Qubit]rMFrozenSet[Clbit]r(Tuple[Instruction, InstructionResources]ct)aGet 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`. Any condition added in by a call to :obj:`.Instruction.c_if` will be propagated through, but set properties like ``duration`` will not; it doesn't make sense for control-flow operations to have pulse scheduling on them. 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)r rLrMs r!concrete_instructionz+InstructionPlaceholder.concrete_instructions <"!r$rKct)aZGet 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. rWrs r!placeholder_resourcesz,InstructionPlaceholder.placeholder_resourcess "!r$r'rc|j|_|S)aCopy mutable properties from ourselves onto a non-placeholder instruction. The mutable properties are expected to be things like ``condition``, added onto a placeholder by the :meth:`c_if` method. This mutates ``instruction``, and returns the same instance that was passed. This is mostly intended to make writing concrete versions of :meth:`.concrete_instruction` easy. The complete list of mutations is: * ``condition``, added by :meth:`c_if`. Args: instruction: the concrete instruction instance to be mutated. Returns: The same instruction instance that was passed, but mutated to propagate the tracked changes to this class. ) _condition)r r's r!_copy_mutable_propertiesz/InstructionPlaceholder._copy_mutable_properties s&"& r$c td)Nz*Cannot assemble a placeholder instruction.rrs r!assemblezInstructionPlaceholder.assemble%sGHHHr$c td)Nz(Cannot repeat a placeholder instruction.r)r ns r!repeatzInstructionPlaceholder.repeat(sEFFFr$N)rLrSrMrTrrU)rrK)r'rrr) rBrCrDrE _directiverHrIrYr[r^r`rcrr$r!rRrRs4J"""">  " " " "2IIIGGGGGr$rRceZdZdZdZddddd>dZdZdZedZ edZ e dZ ddd?dZ d@d"Zd#ZdAd&ZdAd'ZdBd*ZdAd+Zd,Zd-ZdCd.ZdCd/ZdDd2ZdEd5ZdFd;ZdGd=ZdS)HControlFlowBuilderBlockaA 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_capturerTN)rh allow_jumpsforbidden_messagerLIterable[Qubit]rMIterable[Clbit]parentrrhIterable[Register]rpboolrq Optional[str]ct|||_t||_d|_i|_i|_||_||_d|_ ||_ dS)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 rgsetrhrirnrorjrkrlrm)r rLrMrtrhrprqs r!__init__z ControlFlowBuilderBlock.__init__Us`F)88Y'  "3r$c4t|jjS)z-The set of qubits associated with this scope.)ryr"rLrs r!rLzControlFlowBuilderBlock.qubits4$+,,,r$c4t|jjS)z-The set of clbits associated with this scope.)ryr"rMrs r!rMzControlFlowBuilderBlock.clbitsr|r$c|jS)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. )rjrs r!rpz#ControlFlowBuilderBlock.allow_jumpss   r$c|jSN)rgrs r!r"z$ControlFlowBuilderBlock.instructionss !!r$cddlm}m}ddlm}m}||||f}t ||rtd|jddS)Nr) BreakLoopOpBreakLoopPlaceholder)ContinueLoopOpContinueLoopPlaceholderz)The current builder scope cannot take a 'z' because it is not in a loop.) break_looprr continue_looprr isinstancerr;) operationrrrr forbiddens r!_raise_on_jumpz&ControlFlowBuilderBlock._raise_on_jumps BAAAAAAAJJJJJJJJ "6H_` i + + 0IN000   r$Fr%r'rr&rcJ|jt|j|js||j|jD]}|j|d|jD]}|j |d|j ||SNFstrict) rmrrjrrrLr" add_qubitrM add_clbitrgr))r r'r&bs r!r)zControlFlowBuilderBlock.appends  " .t677 7  7    5 6 6 6# 9 9A   ' '% ' 8 8 8 8# 9 9A   ' '% ' 8 8 8 8 !!+...r$r*r c|jt|j|js||j|\}}|jD]"}||vr|j|d#|j D]"}||vr|j |d#|j |dSr) rmrrj foreach_opr active_bitsrLr"rrMrr,)r r* active_qubits active_clbitsrs r!r,zControlFlowBuilderBlock.extends  " .t677 7  1 OOD/ 0 0 0'+'7'7'9'9$ } = =AM!!!++Ae+<<< = =AM!!!++Ae+<<<   &&&&&r$c|jrtd|j|}t |t r||fn|||S)N4Cannot add resources after the scope has been built.)rlrrkr1rr add_bits add_register)r r-resources r!r1z2ControlFlowBuilderBlock.resolve_classical_resourcess ; WUVV V<::9EE h & & ( MM8+ & & & &   h ' ' 'r$r2r3c8|jrtd|j|jx}/||krtd|dtd|d|d|j|jvrtd|d|d||j|j<dS)Nr'z!' is already present in the scopez cannot add 'z$' as its name shadows the existing ')rlrrngetr;ro)r r2previouss r!r6z-ControlFlowBuilderBlock.add_uninitialized_vars ; WUVV V(,,SX66 6H C3"#Ms#M#M#MNNNbcbbW_bbbcc c 8t) ) )bcbbW_bbbcc c%("""r$cp|jrtd|j|jdS)Nz7exception handler 'remove_var' called after scope built)rl RuntimeErrorrnpopr;r5s r!r8z"ControlFlowBuilderBlock.remove_vars; ; ZXYY Y SX&&&&&r$r;r<cr|j|x}|S|j|Sr)rnrrkr?)r r;outs r!r?zControlFlowBuilderBlock.get_vars9#''-- -C :J|##D)))r$c|j|jx}||krdStd|d|d|j|j|krdS|j|j|krtd|d|j|||j|j<dS)Nz cannot use 'z"' which is shadowed by the local 'rzcannot close over 'z', which is not in scope)rnrr;rrorkr?r:)r r2locals r!r:zControlFlowBuilderBlock.use_vars%))#(33 3E @||]c]]UZ]]]^^ ^   ! !#( + +s 2 2 F <   ) )S 0 0RSRRRSS S S!!!'*38$$$r$c4|jS)z=Iterator over the variables currently declared in this scope.)rnvaluesrs r!iter_local_varsz'ControlFlowBuilderBlock.iter_local_varss&&(((r$c4|jS)z=Iterator over the variables currently captured in this scope.)rorrs r!iter_captured_varsz*ControlFlowBuilderBlock.iter_captured_varss!((***r$cH|jstd|jdS)zAGet the value of the most recent instruction tuple in this scope.$This scope contains no instructions.)rgrrs r!peekzControlFlowBuilderBlock.peeks+! GEFF F!"%%r$c`|jstd|jS)zcGet the value of the most recent instruction in this scope, and remove it from this object.r)rgrrrs r!rzControlFlowBuilderBlock.pops4! GEFF F!%%'''r$bitsIterable[Union[Qubit, Clbit]]c|D]x}t|tr|j|d4t|tr|j|dft d|ddS)aAdd extra bits to this scope that are not associated with any concrete instruction yet. This is useful for expanding a scope's resource width when it may contain ``break`` or ``continue`` statements, or when its width needs to be expanded to match another scope's width (as in the case of :obj:`.IfElseOp`). Args: bits: The qubits and clbits that should be added to a scope. It is not an error if there are duplicates, either within the iterable or with the bits currently in scope. Raises: TypeError: if the provided bit is of an incorrect type. Frz5Can only add qubits or classical bits, but received 'z'.N)rrr"rr r TypeError)r rbits r!rz ControlFlowBuilderBlock.add_bits s a aC#u%% a!++C+>>>>C'' a!++C+>>>> _X[ _ _ _```  a ar$registerrcz||jvrdS|j|||dS)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)rhaddr)r rs r!rz$ControlFlowBuilderBlock.add_register sD t~ % % F 8$$$ hr$ all_qubitsrS all_clbitsrT'qiskit.circuit.QuantumCircuit'c& ddlm}m d_jt dt z t z |j jj jgj Rj j d j D]} |i  fd}j |j }| j j D] \}}|||< | S)a Build 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 SwitchCaseOpTNz.update_registersjs"455 3 " 7 7 J O O Iy/00y/001CBPV1W1W'.$11!1!>!>v!F!FJ!1(:::FFF Z000#11!1!>!>v!F!FJ!1(:::FFF Z000 )  Q Q33Ht~55))(333((222r<..: 3BM B B H33Ht~55))(333((22233B -- 3fe,,D')$$(9::D(.y$$'5f'='='C$ 033Ht~55))(333((222 3 333r$)qiskit.circuitrrrlrmrryrLrMrgrhrirorrnr6foreach_op_indexedcopy replace_bitsitems_current_scoper,)r rrrr2rout_datair'rrrrrs``` @@@@@r!buildzControlFlowBuilderBlock.build-s< @???????   " .]^^ ^z??T[[]]:z??T[[]]:n   %   % ^  *'..00    #**,, + +C  % %c * * * *#%( 3( 3( 3( 3( 3( 3( 3( 3( 3( 3( 3( 3V --.>???%**,,cj#*5555;;== & &NA{%HQKK ##H--- r$'ControlFlowBuilderBlock'ct|t|}|j|_|j|_|j|_|j|_|j|_|j|_|j |_ |j |_ |S)a@Return 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__rgrrhrirnrorkrjrm)r rs r!rzControlFlowBuilderBlock.copys4jj  d,, .3355++-- ,*//11 .3355l ,!%!8 r$) rLrrrMrsrtrrhrurprvrqrw)r'rr&rvrrr@rA)r;r<)rr)rr)rr)rrSrrTrr)rr)rBrCrDrErFrzrLrMrGrpr" staticmethodrr)r,r1r6r8r?r:rrrrrrrrrr$r!rfrf,s8 I$)+ +/+4+4+4+4+4+4Z------ ! !X !""X"  \ JO       ' ' ' '    ) ) ) )'''' **** + + + +)))+++&&&& ((((aaaa.     rrrrhr$rf)*rE __future__rrHrtypingrrrrrr r qiskit._accelerate.circuitr qiskit.circuit.classicalr qiskit.circuit.classicalregisterr rqiskit.circuit.exceptionsrqiskit.circuit.instructionr!qiskit.circuit.quantumcircuitdatarqiskit.circuit.quantumregisterrrqiskit.circuit.registerr_builder_utilsrr TYPE_CHECKINGqiskitABCr NamedTuplerKrRrfrr$r!rs;:#"""""  TTTTTTTTTTTTTTTTTT222222))))))EEEEEEEE222222222222@@@@@@AAAAAAAA,,,,,,???????? MMM} } } } } CG} } } @.....6,...*jGjGjGjGjG[#'jGjGjGZGGGGG3GGGGGr$