.. _phases_chunking: Phases and Chunking =================== .. currentmodule:: atomiq.atomiq Very fast experiments with a high repetition rate (>1 Hertz) are challenging. A particular problem are the time it takes the core device to switch from one run/kernel to the next. Atomiq tries to reduce this overhead by grouping together different runs in so-called chunks. Runs within a chuck are packed into the same ARTIQ kernel and are thus executed back-to-back (even without breaking real-time if you like) without the timing overhead of starting a new kernel. In principle one would like to pack all runs into a single kernel, but memory on the core device is limited, and thus we have to compromise and find a reasonable :attr:`AtomiqExperiment.CHUNKSIZE` that can be overwritten as a class-level attribute for your experiment class .. raw:: html :file: img/chunking.svg Atomiq implements several phases during the original ARTIQ `run` phase to optimally embed chunking and provide a fast, yet flexible interface. Each of these phases can be used in a user experiment by implementing a method of the corresponding name. .. note:: All phases can be implemented also in :ref:`blocks`. They are executed automatically just like the ones in the main experiment. One exception is the :code:`step` method, which is not automatically called. An overview of the available phases and their order and timings is shown in the following visualization. .. epigraph:: .. raw:: html :file: img/phases.svg The color of each phase indicates if they are realtime phases on the ARTIQ hardware (green) or non-realtime phases on the host machine running the ARTIQ master (blue). If an exception occurs anywhere during the run phase, the :code:`postfail` phases are executed to allow the user to shut down or reset critical components, like for example magnetic field coils. If an RTIO underflow (or a kernel error) occurs during a chunk, the :code:`prerun` phase is called again before continuing with the next chunk. Note, that only the :code:`prerun` method is called and individual :code:`prerun` methods of included blocks are ignored. .. warning:: Atomiq uses the `build` and `prepare` phases for internal preparation. If you want to use these phases for your own code, make sure to call the atomiq code by running :code:`super().prepare()` or :code:`super().build()` in your methods. .. _phases_scan_point: Accessing Scan Point Information ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The chunk and step phases provide information about the current scan point(s) via the argument :code:`point` (or :code:`points` for the chunk phases). Under the hood, atomiq uses the `ARTIQ multiscan manager `_ , thus the :code:`point` argument is an instance of :code:`ScanPoint`. The values of experiment arguments of the current step can then be accessed via :code:`point.my_argument`. Additionally, the following attributes are provided: * :code:`point.step_counter`: The overall sequential number of the point, starting from 0. * :code:`point.run_id`: The ARTIQ RID, the overall sequential number of the experiment. * :code:`point.identifier`: A unique identifier of the run. All three values are also send to the experiment master and are available to host calls as attributes of the experiment (e.q. :code:`self.step_counter`) .. hint:: The :code:`step_counter` is also broadcast to the *dataset DB* and is available in dashboards and applets as dataset. The :code:`ScanPoint` objects of each step in a chunk are passed as a list to the chunk phases as the :code:`points` argument. Available Phases ^^^^^^^^^^^^^^^^ .. warning:: All **kernel** phases in your experiment (and your blocks) must be decorated with the :code:`@kernel` decorator. .. py:method:: AtomiqExperiment.prerun() :canonical: atomiq.atomiq :no-index: **Kernel** phase which is executed once at the beginning of the run phase of an experiment. This is also executed again before continuing with the next chunk if an error occured during the experiment. .. admonition:: Example usage Send a trigger to indicate an experiment started. .. py:method:: AtomiqExperiment.prerun_host() :canonical: atomiq.atomiq :no-index: **Host** phase which is executed once at the beginning of the run phase of an experiment. .. admonition:: Example usage Configure a camera device whith constant parameters over the whole experiment. .. py:method:: AtomiqExperiment.postrun() :canonical: atomiq.atomiq :no-index: **Kernel** phase which is executed once at the end of the run phase of an experiment. .. admonition:: Example usage Bring hardware into a safe state. .. py:method:: AtomiqExperiment.postrun_host() :canonical: atomiq.atomiq :no-index: **Host** phase which is executed once at the end of the run phase of an experiment. .. admonition:: Example usage Disconnect or power down external devices used during the experiment. .. py:method:: AtomiqExperiment.prechunk(points) :canonical: atomiq.atomiq :no-index: **Kernel** phase which is executed before a chunk. :param points: A list of the scan steps included in the chunk. .. admonition:: Example usage Run a fast callibration .. py:method:: AtomiqExperiment.prechunk_host(points) :canonical: atomiq.atomiq :no-index: **Host** phase which is executed before processing each chunk of the experiment. :param points: A list of the scan steps included in the chunk. .. admonition:: Example usage Configure external devices like a camera for the upcoming chunk. .. py:method:: AtomiqExperiment.postchunk(points) :canonical: atomiq.atomiq :no-index: **Kernel** phase which is executed after processing each chunk of the experiment. :param points: A list of the scan steps included in the chunk. See :ref:`phases_scan_point`. .. admonition:: Example usage Save data collected during the chunk or perform chunk-specific cleanup. .. py:method:: AtomiqExperiment.postchunk_host(points) :canonical: atomiq.atomiq :no-index: **Host** phase which is executed after processing each chunk of the experiment. :param points: A list of the scan steps included in the chunk. See :ref:`phases_scan_point`. .. admonition:: Example usage Reset or adjust external devices after the chunk is completed. .. py:method:: AtomiqExperiment.prestep(point) :canonical: atomiq.atomiq :no-index: **Kernel** phase which is executed before each step. :param points: Includes information and variables of a scan step. See :ref:`phases_scan_point`. .. admonition:: Example usage Reset laser stabilization (SuServo) integrators. .. py:method:: AtomiqExperiment.step(point) :canonical: atomiq.atomiq :no-index: Main **kernel** phase. :param points: Includes information and variables of the scan step. See :ref:`phases_scan_point`. .. admonition:: Example usage Main part of the experiment, like loading a MOT, imaging atoms in tweezers or whatever you want to do. .. py:method:: AtomiqExperiment.poststep(point) :canonical: atomiq.atomiq :no-index: **Kernel** phase which is executed after each step. :param points: Includes information and variables of the scan step. See :ref:`phases_scan_point`. .. admonition:: Example usage Save data collected during the step.