g"E*dZddlmZddlmZddlmZmZmZddlm Z m Z ddl m Z ddl mZmZddlmZmZdd lmZdd lmZmZdd lmZmZdd lmZdd lmZmZm Z GddZ!Gdde!Z"Gdde!Z#GddZ$dS)a"Management of pulse program parameters. Background ========== In contrast to ``QuantumCircuit``, in pulse programs, parameter objects can be stored in multiple places at different layers, for example - program variables: ``ScheduleBlock.alignment_context._context_params`` - instruction operands: ``ShiftPhase.phase``, ... - operand parameters: ``pulse.parameters``, ``channel.index`` ... This complexity is due to the tight coupling of the program to an underlying device Hamiltonian, i.e. the variance of physical parameters between qubits and their couplings. If we want to define a program that can be used with arbitrary qubits, we should be able to parametrize every control parameter in the program. Implementation ============== Managing parameters in each object within a program, i.e. the ``ParameterTable`` model, makes the framework quite complicated. With the ``ParameterManager`` class within this module, the parameter assignment operation is performed by a visitor instance. The visitor pattern is a way of separating data processing from the object on which it operates. This removes the overhead of parameter management from each piece of the program. The computational complexity of the parameter assignment operation may be increased from the parameter table model of ~O(1), however, usually, this calculation occurs only once before the program is executed. Thus this doesn't hurt user experience during pulse programming. On the contrary, it removes parameter table object and associated logic from each object, yielding smaller object creation cost and higher performance as the data amount scales. Note that we don't need to write any parameter management logic for each object, and thus this parameter framework gives greater scalability to the pulse module. ) annotations)copy)AnyMappingSequence)ParameterVectorParameterVectorElement) Parameter)ParameterExpressionParameterValueType) instructionschannels) PulseError) SymbolicPulseWaveform)Schedule ScheduleBlock) AlignmentKind)format_parameter_value_validate_parameter_vector_validate_parameter_valuec8eZdZdZd dZdZd dZdd Zd d Zd S) NodeVisitora5A node visitor base class that walks instruction data in a pulse program and calls visitor functions for every node. Though this class implementation is based on Python AST, each node doesn't have a dedicated node class due to the lack of an abstract syntax tree for pulse programs in Qiskit. Instead of parsing pulse programs, this visitor class finds the associated visitor function based on class name of the instruction node, i.e. ``Play``, ``Call``, etc... The `.visit` method recursively checks superclass of given node since some parametrized components such as ``DriveChannel`` may share a common superclass with other subclasses. In this example, we can just define ``visit_Channel`` method instead of defining the same visitor function for every subclasses. Some instructions may have special logic or data structure to store parameter objects, and visitor functions for these nodes should be individually defined. Because pulse programs can be nested into another pulse program, the visitor function should be able to recursively call proper visitor functions. If visitor function is not defined for a given node, ``generic_visit`` method is called. Usually, this method is provided for operating on object defined outside of the Qiskit Pulse module. noderc\|t|}||S)z Visit a node.) _get_visitortype)selfrvisitors T/granary/edev/quantum/lib/python3.11/site-packages/qiskit/pulse/parameter_manager.pyvisitzNodeVisitor.visit_s)##DJJ//wt}}c|tkr|jS t|d|jS#t$r||jcYSwxYw)zGA helper function to recursively investigate superclass visitor method.visit_)object generic_visitgetattr__name__AttributeErrorr__base__)r node_classs r rzNodeVisitor._get_visitordso   % % :4!?**=!?!?@@ @ : : :$$Z%899 9 9 9 :s,$AArctzVisit ``ScheduleBlock``. Recursively visit context blocks and overwrite. .. note:: ``ScheduleBlock`` can have parameters in blocks and its alignment. NotImplementedErrorrrs r visit_ScheduleBlockzNodeVisitor.visit_ScheduleBlockos "!r"rct)FVisit ``Schedule``. Recursively visit schedule children and overwrite.r.r0s r visit_SchedulezNodeVisitor.visit_Schedulev!!r"ct)z9Called if no explicit visitor function exists for a node.r.r0s r r&zNodeVisitor.generic_visitzr5r"Nrrrrrr) r( __module__ __qualname____doc__r!rr1r4r&r"r rrHs}, : : :""""""""""""""r"rcjeZdZdZddZddZdd Zdd Zd d Zd!dZ d"dZ d#dZ d$dZ d%dZ d&dZdS)'ParameterSetterzNode visitor for parameter binding. This visitor is initialized with a dictionary of parameters to be assigned, and assign values to operands of nodes found. param_map-dict[ParameterExpression, ParameterValueType]c||_dSN) _param_map)rr@s r __init__zParameterSetter.__init__s #r"rrc||j|_|jD]}|||||Sr-)visit_AlignmentKindalignment_context_alignment_context_blocksr!_update_parameter_manager)rrelms r r1z#ParameterSetter.visit_ScheduleBlocksX #'":":4;Q"R"R<  C JJsOOOO &&t,,, r"rcfd|jD|_|||S)r3cDg|]\}}||fSr=r!).0t0schedrs r z2ParameterSetter.visit_Schedule..s.#_#_#_ ERE):):$;#_#_#_r")r _Schedule__children_renew_timeslotsrKr0s` r r4zParameterSetter.visit_SchedulesP$`#_#_#_TM^#_#_#_   &&t,,, r"rcVtfd|jD}||_|S)z=Assign parameters to block's ``AlignmentKind`` specification.c3BK|]}|VdSrCrO)rPparamrs r z6ParameterSetter.visit_AlignmentKind..s/SSUtzz%00SSSSSSr")tuple_context_params)rrnew_parameterss` r rGz#ParameterSetter.visit_AlignmentKinds5SSSSd>RSSSSS- r"instructions.Instructioncz|r%tfd|jD|_|S)zAssign parameters to general pulse instruction. .. note:: All parametrized object should be stored in the operands. Otherwise parameter cannot be detected. c3BK|]}|VdSrCrO)rPoprs r rYz4ParameterSetter.visit_Instruction..s-"J"Jb4::b>>"J"J"J"J"J"Jr")is_parameterizedrZoperands _operandsr0s` r visit_Instructionz!ParameterSetter.visit_InstructionsE  " " K""J"J"J"JDM"J"J"JJJDN r"channels.Channelc |ro||j}t|ts*t|t r|dkrt d||S|S)z(Assign parameters to ``Channel`` object.rz+Channel index must be a nonnegative integer)index)ra_assign_parameter_expressionrg isinstancer intr __class__)rr new_indexs r visit_ChannelzParameterSetter.visit_Channels  " " 399$*EEIi)<== T!)S11TY]]$%RSSS>> >22 2 r"rcl|rt|jtr||j|_|jD]C}|j|}t|tr||}||j|<D|js||S)z.Assign parameters to ``SymbolicPulse`` object.)raridurationr rh_paramsdisable_validationvalidate_parameters)rrnamepvalnew_vals r visit_SymbolicPulsez#ParameterSetter.visit_SymbolicPulses  " " +$-)<== Q $ A A$- P P   1 1|D)d$7881"??EEG)0DL&* +((*** r"rc|S)zzAssign parameters to ``Waveform`` object. .. node:: No parameter can be assigned to ``Waveform`` object. r=r0s r visit_WaveformzParameterSetter.visit_Waveforms  r"rcZt|tr||S|S)zGAssign parameters to object that doesn't belong to Qiskit Pulse module.)rir rhr0s r r&zParameterSetter.generic_visits. d/ 0 0 44T:: :Kr" param_exprr ct|}|j|jz}|D]#}|||j|}$t |}|S)zDA helper function to assign parameter value to parameter expression.)r parametersrDkeysassignr)rrz new_valueupdatedrXs r rhz,ParameterSetter._assign_parameter_expressionsl$$ '$/*>*>*@*@@ H HE!((0FGGII*955 r"Schedule | ScheduleBlockczt|dstd|jjd|j}|j|jz}t}|jD]H}||vr| ||j|}t|tr ||jz}I||_ dS)z?A helper function to update parameter manager of pulse program._parameter_managerz Node type z has no parameter manager.N) hasattrrrkr(rr|rDr}setaddrir _parameters)rr param_managerrr\rXrs r rKz)ParameterSetter._update_parameter_managerst122 _]$.*A]]]^^ ^/ *T_-A-A-C-CC"- 7 7EG##""5))).I)%899 7)"66$2 !!!r"N)r@rAr8r9rrrr]rrerrrrr7)rzr )rr)r(r:r;r<rEr1r4rGrdrmrvrxr&rhrKr=r"r r?r?s $$$$            "333333r"r?cXeZdZdZdZddZddZdd Zdd Zdd Z ddZ ddZ ddZ dS)ParameterGetterzNode visitor for parameter finding. This visitor initializes empty parameter array, and recursively visits nodes and add parameters found to the array. c,t|_dSrC)rr|rs r rEzParameterGetter.__init__s%%r"rrc:|xj|jjzc_dS)zVisit ``ScheduleBlock``. Recursively visit context blocks and search parameters. .. note:: ``ScheduleBlock`` can have parameters in blocks and its alignment. N)r|rr0s r r1z#ParameterGetter.visit_ScheduleBlock s 42==r"rc0|xj|jzc_dS)zNVisit ``Schedule``. Recursively visit schedule children and search parameters.Nr|r0s r r4zParameterGetter.visit_Schedule 4?*r"rcn|jD],}t|tr|xj|jzc_-dS)zs5 d/ 0 0 / OOt .OOOO / /r"Nr8r9rrrrrr7) r(r:r;r<rEr1r4rGrdrmrvrxr&r=r"r rrs    >>>>++++4444++++7777     //////r"rc^eZdZdZdZeddZdZddZdd Z ddZ ddZ ddZ dS)ParameterManageraHelper class to manage parameter objects associated with arbitrary pulse programs. This object is implicitly initialized with the parameter object storage that stores parameter objects added to the parent pulse program. Parameter assignment logic is implemented based on the visitor pattern. Instruction data and its location are not directly associated with this object. c,t|_dS)z.Create new parameter table for pulse programs.N)rrrs r rEzParameterManager.__init__Ns55r"returnset[Parameter]c|jS)z1Parameters which determine the schedule behavior.)rrs r r|zParameterManager.parametersRs r"c8|jdS)z-Remove the parameters linked to this manager.N)rclearrs r rzParameterManager.clearWs      r"boolc*t|jS)z1Return True iff the instruction is parameterized.)rr|rs r raz!ParameterManager.is_parameterized[sDO$$$r"parameter_namestrlist[Parameter]c*fd|jDS)afGet parameter object bound to this schedule by string name. Because different ``Parameter`` objects can have the same name, this method returns a list of ``Parameter`` s for the provided name. Args: parameter_name: Name of parameter. Returns: Parameter objects that have corresponding name. c*g|]}|jk |Sr=rs)rPrXrs r rSz3ParameterManager.get_parameters..ks%SSS%ejN6R6R6R6R6Rr"r)rrs `r get_parameterszParameterManager.get_parameters_s"TSSS4?SSSSr" pulse_programr value_dictddict[ParameterExpression | ParameterVector | str, ParameterValueType | Sequence[ParameterValueType]]c||fd|jzD}|r%t|}||S|S)aqModify and return program data with parameters assigned according to the input. Args: pulse_program: Arbitrary pulse program associated with this manager instance. value_dict: A mapping from Parameters to either numeric values or another Parameter expression. Returns: Updated program data. c"i|] }|| Sr=r=)rPkunrolled_value_dicts r z6ParameterManager.assign_parameters..s.   *+A"1%   r")r@)_unroll_param_dictr}rr?r!)rrr valid_maprrs @r assign_parametersz"ParameterManager.assign_parametersms$#55jAA    /B/G/G/I/IDL\/\     0% :::G==// /r"new_nodecvt}|||xj|jzc_dS)zA helper function to update parameter table with given data node. Args: new_node: A new data node to be added. N)rr!rr|)rrrs r update_parameter_tablez'ParameterManager.update_parameter_tables> "## h G..r"parameter_binds]Mapping[Parameter | ParameterVector | str, ParameterValueType | Sequence[ParameterValueType]]&Mapping[Parameter, ParameterValueType]ci}d|jD}|jD]"}||j|#d|jD}|D]4}||vr"||||(||g||<5|D]\}}t |t r4t|||t||Nt |trG||D]=}t||} | r$|t||8|||<>|||<|S)z Unroll parameter dictionary to a map from parameter to value. Args: parameter_binds: A dictionary from parameter to value or a list of values. Returns: A dictionary from parameter to value. ci|] }|jg Sr=rrPrXs r rz7ParameterManager._unroll_param_dict..sGGGe5:rGGGr"c\i|])}t|t|jj|j*Sr=)rir vectorrsrs r rz7ParameterManager._unroll_param_dict..sB   %!788 L u|   r") r|rsappendr}itemsrirrupdateziprr) rroutparam_name_dictrXparam_vec_dictrs parametervalueis_vecs r rz#ParameterManager._unroll_param_dictsGGtGGG_ 6 6E EJ ' . .u 5 5 5 5      #'')) ? ?D&&%,,^D-ABBBB)7)=(>%% / 5 5 7 7 ' ' Iu)_55 '*9e<<< 3y%001111Is++ ',Y7++E6ueDDF+ 3ue#4#45555%*E +"'I r"N)rr)rr)rrrr)rrrrrr)rr)rrrr) r(r:r;r<rEpropertyr|rrarrrrr=r"r rrDs!!!   X !!!%%%% T T T T6////++++++r"rN)%r< __future__rrtypingrrrqiskit.circuit.parametervectorrr qiskit.circuit.parameterr "qiskit.circuit.parameterexpressionr r qiskit.pulser rqiskit.pulse.exceptionsrqiskit.pulse.libraryrrqiskit.pulse.schedulerr"qiskit.pulse.transforms.alignmentsrqiskit.pulse.utilsrrrrr?rrr=r"r rs%%L#"""""))))))))))RRRRRRRR......VVVVVVVV////////......8888888899999999<<<<<<4"4"4"4"4"4"4"4"n33333k333D@/@/@/@/@/k@/@/@/Fyyyyyyyyyyr"