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.

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


   .. 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 has stopped running or
      until it has exceeded the amount of time to run.

      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.