Phases and Chunking

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 AtomiqExperiment.CHUNKSIZE that can be overwritten as a class-level attribute for your experiment class

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 Blocks. They are executed automatically just like the ones in the main experiment. One exception is the step method, which is not automatically called.

An overview of the available phases and their order and timings is shown in the following visualization.

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 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 prerun phase is called again before continuing with the next chunk. Note, that only the prerun method is called and individual 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 super().prepare() or super().build() in your methods.

Accessing Scan Point Information

The chunk and step phases provide information about the current scan point(s) via the argument point (or points for the chunk phases). Under the hood, atomiq uses the ARTIQ multiscan manager , thus the point argument is an instance of ScanPoint. The values of experiment arguments of the current step can then be accessed via point.my_argument. Additionally, the following attributes are provided:

• point.step_counter: The overall sequential number of the point, starting from 0.

• point.run_id: The ARTIQ RID, the overall sequential number of the experiment.

• 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. self.step_counter)

Hint

The step_counter is also broadcast to the dataset DB and is available in dashboards and applets as dataset.

The ScanPoint objects of each step in a chunk are passed as a list to the chunk phases as the points argument.

Available Phases

Warning

All kernel phases in your experiment (and your blocks) must be decorated with the @kernel decorator.

AtomiqExperiment.prerun()

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.

Example usage

Send a trigger to indicate an experiment started.

AtomiqExperiment.prerun_host()

Host phase which is executed once at the beginning of the run phase of an experiment.

Example usage

Configure a camera device whith constant parameters over the whole experiment.

AtomiqExperiment.postrun()

Kernel phase which is executed once at the end of the run phase of an experiment.

Example usage

Bring hardware into a safe state.

AtomiqExperiment.postrun_host()

Host phase which is executed once at the end of the run phase of an experiment.

Example usage

Disconnect or power down external devices used during the experiment.

AtomiqExperiment.prechunk(points)

Kernel phase which is executed before a chunk.

Parameters:

points -- A list of the scan steps included in the chunk.

Example usage

Run a fast callibration

AtomiqExperiment.prechunk_host(points)

Host phase which is executed before processing each chunk of the experiment.

Parameters:

points -- A list of the scan steps included in the chunk.

Example usage

Configure external devices like a camera for the upcoming chunk.

AtomiqExperiment.postchunk(points)

Kernel phase which is executed after processing each chunk of the experiment.

Parameters:

points -- A list of the scan steps included in the chunk. See Accessing Scan Point Information.

Example usage

Save data collected during the chunk or perform chunk-specific cleanup.

AtomiqExperiment.postchunk_host(points)

Host phase which is executed after processing each chunk of the experiment.

Parameters:

points -- A list of the scan steps included in the chunk. See Accessing Scan Point Information.

Example usage

Reset or adjust external devices after the chunk is completed.

AtomiqExperiment.prestep(point)

Kernel phase which is executed before each step.

Parameters:

points -- Includes information and variables of a scan step. See Accessing Scan Point Information.

Example usage

Reset laser stabilization (SuServo) integrators.

AtomiqExperiment.step(point)

Main kernel phase.

Parameters:

points -- Includes information and variables of the scan step. See Accessing Scan Point Information.

Example usage

Main part of the experiment, like loading a MOT, imaging atoms in tweezers or whatever you want to do.

AtomiqExperiment.poststep(point)

Kernel phase which is executed after each step.

Parameters:

points -- Includes information and variables of the scan step. See Accessing Scan Point Information.

Example usage

Save data collected during the step.