# Functional description Here we describe the functionality of the Presto microwave platform, with a special focus on the relation between the different methods of the [Presto API](source/presto) and the specific function. For a more detailed description of the digital Presto platform, you might be interested in the [Presto paper](#presto-paper). (sch-pls-output)= ## Pulsed output The image below shows a schematic, functional representation of one output channel of Vivace/Presto during {mod}`.pulsed` operation. The same configuration is then repeated independently on each of the 8/16 output channels. This section provides a summary of how the methods of the {class}`.Pulsed` class interact with the hardware. ```{image} images/pulsed_output_mixed.svg :align: center :width: 640 ``` When instantiating the {class}`.Pulsed` class, outputs can be configured in two modes: _mixed mode_ (`dac_mode` is one of {class}`DacMode.Mixedxx <.hardware.DacMode>`) or _direct mode_ (`dac_mode` is {class}`DacMode.Direct <.hardware.DacMode>`). In mixed mode, signals generated in the intermediate-frequency (IF) domain are then upconverted to the radio-frequency domain (RF) using a built-in *digital* IQ mixer and numerically-controlled oscillator (NCO). In direct mode, the digital up-conversion stage is bypassed and IF signals are output directly. Each output has 16 slots to store output templates, divided in two groups of 8 templates each. Each template can be programmed with up to 1022 ns of data at {meth}`get_fs('dac') <.Pulsed.get_fs>` sampling rate. When using digital up-conversion (mixed mode), that is 1022 complex-valued data points (real part stored in "pulses I" and imaginary in "pulses Q") at 1 GS/s. In direct mode, that is 2044 real-valued data points at 2 GS/s. The vertical resolution is 16 bits and spans values from -1 to 1. Templates can be output directly, or can be used as envelopes to modulate the two IF carrier generators. The first 8 templates can modulate the first IF generator (group 0), the last 8 templates can modulate the second IF generator (group 1). The method {meth}`~.Pulsed.setup_template` is used to program the templates into one of the groups and to choose whether they should be used as envelopes. The method also takes care of splitting templates that are too long into shorter, concatenated templates. In the case of long but "flat-top" signals, the convenience method {meth}`~.Pulsed.setup_long_drive` can be used to create arbitrarily long pulses using as little as one template. Another advantage of a {class}`.LongDrive` is that it can be resized with its {meth}`~.LongDrive.set_total_duration` method. Templates can be output all together, or at different times, with {meth}`~.Pulsed.get_clk_T` resolution (typically `2 ns`) using the {meth}`~.Pulsed.output_pulse` method. Each IF generator has 40 bits frequency and phase resolution, equivalent to `2 mHz` and `6 prad`, respectively. They can each be programmed with up to 512 `frequencies` and `phases` (and `phases_q` in mixed mode) with the method {meth}`~.Pulsed.setup_freq_lut`. During the experiment, the generators can quickly step through the programmed frequencies and phases with the methods {meth}`~.Pulsed.select_frequency` and {meth}`~.Pulsed.next_frequency`. The change can be made with {meth}`~.Pulsed.get_clk_T` resolution (typically `2 ns`). The output of all active pulses in each group is then summed, and there is a dedicated scale stage. The output scaler has 17 bit resolution and can be programmed with up to 512 values (in the range -1 to 1) with the method {meth}`~.Pulsed.setup_scale_lut`. The scale can be changed during the experiment with {meth}`~.Pulsed.get_clk_T` resolution (typically `2 ns`) with {meth}`~.Pulsed.select_scale` and {meth}`~.Pulsed.next_scale`. The output of each group scaler is finally combined and sent to the either I or Q port of the digital mixer when using digital up-conversion (in mixed mode) or it is directly sent to the digital-to-analog converter (DAC) when in direct mode. The frequency of the numerically-controlled oscillator (NCO) fed to the LO port of the digital mixer is set using {meth}`hardware.configure_mixer <.Hardware.configure_mixer>`. (sch-pls-input)= ## Pulsed input The image below shows a schematic, functional representation of the input channels of Vivace/Presto during {mod}`.pulsed` operation. This section provides a summary of how the methods of the {class}`.Pulsed` class interact with the hardware. ```{image} images/pulsed_input.svg :align: center :alt: Alternative text :width: 640 ``` When instantiating the {class}`.Pulsed` class, inputs can be configured in two modes: _mixed mode_ (`adc_mode` is {class}`AdcMode.Mixed <.hardware.AdcMode>`) or _direct mode_ (`adc_mode` is {class}`AdcMode.Direct <.hardware.AdcMode>`). In mixed mode, the signal sampled in the radio-frequency domain (RF) is down-converted to the intermediate-frequency (IF) domain using a built-in *digital* IQ mixer and numerically-controlled oscillator (NCO). In direct mode, the digital down-conversion stage is bypassed and the sampled signal is analyzed directly. The ports from which to store data are selected by {meth}`~.Pulsed.set_store_ports` and the length of each store window by {meth}`~.Pulsed.set_store_duration`. The timing of the sampling windows is decided by calling {meth}`~.Pulsed.store`. The sampled data is then averaged interleaved and when the sequence is done the averaged traces are transferred to the computer by calling {meth}`~.Pulsed.get_store_data`. When using direct mode the returned data is real valued (`dtype=np.float64`); when using digital down-conversion (mixed mode), the returned data is complex valued (`dtype=np.complex128`). It is also possible to match each sampled trace with a pair of reference templates (128 templates available in total). The template pairs and the threshold ($T$) are defined in {meth}`~.Pulsed.setup_template_matching_pair`. Reference templates are real valued in direct mode and complex valued in mixed mode, while the threshold is always a real number. The timing of each matching event is decided in {meth}`~.Pulsed.match`. The result of a template matching event is the scalar product of the sampled trace with a reference template and is therefore a real number $M$. When matching with a pair of templates, we get two results, $M_1$ and $M_2$. After the sequence is done the values of all the template-matching events can be retrieved with {meth}`~.Pulsed.get_template_matching_data`. Template-matching results can be used to conditionally output pulses, thus implementing low-latency feedback. The "success" of a match event is determined by $M_1 + M_2 - T > 0$. It is then possible to output conditional pulses based on the outcome (success or failure) of one or more matching events by using {meth}`~.Pulsed.setup_condition`.