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: Callable) -> Callable

   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:attribute:: profile


   .. py:attribute:: parent_ic


   .. py:attribute:: plot
      :value: None



   .. py:method:: add_component(component: quantify_scheduler.instrument_coordinator.components.InstrumentCoordinatorComponentBase) -> 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: quantify_scheduler.schedules.schedule.CompiledSchedule) -> 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() -> None

      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: bool = False) -> None

      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() -> xarray.Dataset

      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) -> None

      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:attribute:: profile


   .. py:attribute:: plot
      :value: None



   .. py:attribute:: instr_coordinator
      :type:  quantify_scheduler.instrument_coordinator.instrument_coordinator.InstrumentCoordinator


   .. py:attribute:: profiled_instr_coordinator


   .. py:method:: _compile(sched: quantify_scheduler.schedules.schedule.Schedule) -> None

      Overwrite compile step for profiling.



   .. py:method:: close() -> None

      Cleanup new profiling instruments to avoid future conflicts.



   .. py:method:: log_profile(obj: object = None, path: str = 'profiling_logs', filename: str | None = None, indent: int = 4, separators: tuple[str, str] | None = None) -> dict

      Store profiling logs to json file.



   .. py:method:: plot_profile(path: str | None = None, filename: str = 'average_runtimes.pdf') -> None

      Create barplot of accumulated profiling data.