gettables_profiled
==================

.. py:module:: quantify_scheduler.gettables_profiled 

.. autoapi-nested-parse::

   This module represents the Q-Profile quantum control electronics profiler.

   Profiling of the control electronics is enabled by using the
   :class:`ProfiledScheduleGettable` in place of
   :class:`~.ScheduleGettable`.

   .. note::

       The :class:`ProfiledScheduleGettable` is currently only tested to support Qblox hardware.



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   quantify_scheduler.gettables_profiled.ProfiledInstrumentCoordinator
   quantify_scheduler.gettables_profiled.ProfiledScheduleGettable



Functions
~~~~~~~~~

.. autoapisummary::

   quantify_scheduler.gettables_profiled.profiler



.. py:function:: profiler(func)

   Decorator that reports the execution time of the decorated function
   and stores this in ``ProfiledInstrumentCoordinator.profile``.

   :param func: Target function to be profiled.
   :type func: Callable


.. py:class:: ProfiledInstrumentCoordinator(name: str, parent_ic: quantify_scheduler.instrument_coordinator.instrument_coordinator.InstrumentCoordinator)


   Bases: :py:obj:`quantify_scheduler.instrument_coordinator.instrument_coordinator.InstrumentCoordinator`

   Subclass of :class:`~.InstrumentCoordinator` that implements a profiling tool to log
   timing results. Time results are stored in ``ProfiledInstrumentCoordinator.profile``.

   :class:`ProfiledInstrumentCoordinator` is set up to be used when using
   :class:`ProfiledScheduleGettable`, code example:

   .. code-block:: python

       ic = InstrumentCoordinator(name="instrument_coordinator")

       quantum_device = QuantumDevice(name="quantum_device")
       quantum_device.instr_instrument_coordinator(ic.name)

       profiled_gettable = ProfiledScheduleGettable(
           quantum_device=quantum_device,
           schedule_function=...,
           schedule_kwargs=...,
       )

       profiled_gettable.initialize()
       profiled_ic = (
           profiled_gettable.quantum_device.instr_instrument_coordinator.get_instr()
       )

   :param name: Name of :class:`ProfiledInstrumentCoordinator` instance.
   :type name: str
   :param parent_ic: Original :class:`~.InstrumentCoordinator`.
   :type parent_ic: InstrumentCoordinator

   .. py:method:: add_component(component) -> None

      Adds a component to the components collection.

      :param component: The component to add.

      :raises ValueError: If a component with a duplicated name is added to the collection.
      :raises TypeError: If :code:`component` is not an instance of the base component.


   .. py:method:: prepare(compiled_schedule) -> None

      Prepares each component for execution of a schedule.

      It attempts to configure all instrument coordinator components for which
      compiled instructions, typically consisting of a combination of sequence
      programs, waveforms and other instrument settings, are available in the
      compiled schedule.


      :param compiled_schedule: A schedule containing the information required to execute the program.

      :raises KeyError: If the compiled schedule contains instructions for a component
          absent in the instrument coordinator.
      :raises TypeError: If the schedule provided is not a valid :class:`.CompiledSchedule`.


   .. py:method:: start()

      Start all of the components that appear in the compiled instructions.

      The instruments will be started in the order in which they were added to the
      instrument coordinator.


   .. py:method:: stop(allow_failure=False)

      Stops all components.

      The components are stopped in the order in which they were added.

      :param allow_failure: By default it is set to `False`. When set to `True`, the AttributeErrors
                            raised by a component are demoted to warnings to allow other
                            components to stop.


   .. py:method:: retrieve_acquisition()

      Retrieves the latest acquisition results of the components with acquisition capabilities.

      :returns: The acquisition data in an :code:`xarray.Dataset`.
                For each acquisition channel it contains an :code:`xarray.DataArray`.


   .. py:method:: wait_done(timeout_sec: int = 10)

      Awaits each component until it is done.

      The timeout in seconds specifies the allowed amount of time to run before
      it times out.

      :param timeout_sec: The maximum amount of time in seconds before a timeout.



.. py:class:: ProfiledScheduleGettable(*args, **kwargs)


   Bases: :py:obj:`quantify_scheduler.gettables.ScheduleGettable`

   To be used in place of :class:`~.ScheduleGettable` to enable profiling of the
   compilation. Logged execution times can be read from ``self.profile``, and plotted
   via :func:`plot_profile`.

   .. py:method:: _compile(sched)

      Overwrite compile step for profiling.


   .. py:method:: close()

      Cleanup new profiling instruments to avoid future conflicts.


   .. py:method:: log_profile(obj=None, path='profiling_logs', filename=None, indent: int = 4, separators=None)

      Store profiling logs to json file.


   .. py:method:: plot_profile(path=None, filename='average_runtimes.pdf')

      Create barplot of accumulated profiling data.