Skip to content

qubic.abstract_runner

AbstractCircuitRunner

Bases: ABC

Defines interface for loading and running batches of compiled circuits. Used primarily by job_manager and other higher level software requiring a circuit runner as input. Current implementations include qubic.run.CircuitRunner (for running circuits/submitted jobs locally on the RFSoC), and qubic.rpc_client (for submitting/running circuits over RPC)

Source code in qubic/abstract_runner.py 
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
class AbstractCircuitRunner(ABC):
    """
    Defines interface for loading and running batches of compiled circuits. Used primarily
    by `job_manager` and other higher level software requiring a circuit runner as input. 
    Current implementations include qubic.run.CircuitRunner (for running circuits/submitted jobs
    locally on the RFSoC), and qubic.rpc_client (for submitting/running circuits over RPC)
    """

    def __init__(self):
        pass


    @abstractmethod
    def run_circuit_batch(self, 
                          raw_asm_list: List[Dict], 
                          n_total_shots: int, 
                          reads_per_shot: int | Dict = 1, 
                          timeout_per_shot: int = 8,
                          reload_cmd: bool = True, 
                          reload_freq: bool = True, 
                          reload_env: bool = True, 
                          zero_between_reload: bool = True) -> Dict:
        """
        Runs a batch of circuits given by a list of raw_asm "binaries". Each circuit is run n_total_shots
        times. `reads_per_shot`, `n_total_shots`, and `delay_per_shot` are passed directly into `run_circuit`, and must
        be the same for all circuits in the batch. The parameters reload_cmd, reload_freq, reload_env, and 
        `zero_between_reload` control which of these fields is rewritten circuit-to-circuit (everything is 
        rewritten initially). Leave these all at `True` (default) for maximum safety, to ensure that QubiC 
        is in a clean state before each run. Depending on the circuits, some of these can be turned off 
        to save time.

        Parameters
        ----------
         raw_asm_list : list
             list of raw_asm binaries to run
         n_total_shots : int
             number of shots per circuit
         reads_per_shot : int | dict
             number of values per shot per channel to read back from accbuf. If dict, indexed
             by str(channel_number) (same indices as raw_asm_list). If int, assumed to be 
             the same across channels. Unless multiple circuits were rastered pre-compilation or 
             there is mid-circuit measurement involved this is typically 1
         timeout_per_shot : float
             job will time out if time to take a single shot exceeds this value in seconds 
             (this likely means the job is hanging due to timing issues in the program or gateware)
         delay_per_shot : float (WILL BE REMOVED)
             delay time (in seconds) per single shot of the circuit
         reload_cmd : bool
             if True, reload command buffer between circuits
         reload_freq : bool
             if True, reload freq buffer between circuits
         reload_env: bool
             if True, reload env buffer between circuits

        Returns
        -------
        dict:
            Complex IQ shots for each accbuf in chanlist; each array has 
            shape `(len(raw_asm_list), n_total_shots, reads_per_shot)`
        """
        pass

    @abstractmethod
    def load_and_run_acq(self, 
                         raw_asm_prog: List[Dict], 
                         n_total_shots: int = 1, 
                         nsamples: int = 8192, 
                         acq_chans: Dict = {'0': 0, '1': 1}, 
                         trig_delay: float = 0, 
                         decimator: int = 0, 
                         return_acc: bool = False) -> tuple | Dict:
        """
        Load the program given by raw_asm_prog and acquire raw (or downconverted) adc traces.

        Parameters
        ----------
        raw_asm_prog : dict
            ASM binary to run. See load_circuit for details.
        n_total_shots : int
            number of shots to run. Program is restarted from the beginning 
            for each new shot
        nsamples : int
            number of samples to read from the acq buffer
        acq_chans : dict
            current channel mapping is:
                '0': ADC_237_2 (main readout ADC)
                '1': ADC_237_0 (other ADC connected in gateware)
                TODO: figure out DLO channels, etc and what they mean
        trig_delay : float
            time to delay acquisition, relative to circuit start.
            NOTE: this value, when converted to units of clock cycles, is a 
            16-bit value. So, it maxes out at `CLK_PERIOD*(2**16) = 131.072e-6`
        decimator : int
            decimation interval when sampling. e.g. 0 means full sample rate, 1
            means capture every other sample, 2 means capture every third sample, etc
        return_acc : bool
            if True, return a single acc (integrated + accumulated readout) value per shot,
            on each loaded channel. Default is `False`.

        Returns
        -------
        if `return_acc` is `False`:
            dict:
                array of acq samples for each channel in acq_chans with shape `(n_total_shots, nsamples)`

        if `return_acc` is `True`:
            tuple:
                dict:
                    array of acq samples for each channel in acq_chans with shape `(n_total_shots, nsamples)`
                dict:
                    array of acc values for each loaded channel with length `n_total_shots`

        """
        pass

load_and_run_acq(raw_asm_prog, n_total_shots=1, nsamples=8192, acq_chans={'0': 0, '1': 1}, trig_delay=0, decimator=0, return_acc=False) abstractmethod

Load the program given by raw_asm_prog and acquire raw (or downconverted) adc traces.

Parameters:

Name Type Description Default
raw_asm_prog dict

ASM binary to run. See load_circuit for details.

 required
n_total_shots int

number of shots to run. Program is restarted from the beginning for each new shot

 1
nsamples int

number of samples to read from the acq buffer

 8192
acq_chans dict

current channel mapping is: '0': ADC_237_2 (main readout ADC) '1': ADC_237_0 (other ADC connected in gateware) TODO: figure out DLO channels, etc and what they mean

 {'0': 0, '1': 1}
trig_delay float

time to delay acquisition, relative to circuit start. NOTE: this value, when converted to units of clock cycles, is a 16-bit value. So, it maxes out at CLK_PERIOD*(2**16) = 131.072e-6

 0
decimator int

decimation interval when sampling. e.g. 0 means full sample rate, 1 means capture every other sample, 2 means capture every third sample, etc

 0
return_acc bool

if True, return a single acc (integrated + accumulated readout) value per shot, on each loaded channel. Default is False.

 False

Returns:

Type Description
if `return_acc` is `False`:

dict: array of acq samples for each channel in acq_chans with shape (n_total_shots, nsamples)
if `return_acc` is `True`:

tuple: dict: array of acq samples for each channel in acq_chans with shape (n_total_shots, nsamples) dict: array of acc values for each loaded channel with length n_total_shots
Source code in qubic/abstract_runner.py 
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
@abstractmethod
def load_and_run_acq(self, 
                     raw_asm_prog: List[Dict], 
                     n_total_shots: int = 1, 
                     nsamples: int = 8192, 
                     acq_chans: Dict = {'0': 0, '1': 1}, 
                     trig_delay: float = 0, 
                     decimator: int = 0, 
                     return_acc: bool = False) -> tuple | Dict:
    """
    Load the program given by raw_asm_prog and acquire raw (or downconverted) adc traces.

    Parameters
    ----------
    raw_asm_prog : dict
        ASM binary to run. See load_circuit for details.
    n_total_shots : int
        number of shots to run. Program is restarted from the beginning 
        for each new shot
    nsamples : int
        number of samples to read from the acq buffer
    acq_chans : dict
        current channel mapping is:
            '0': ADC_237_2 (main readout ADC)
            '1': ADC_237_0 (other ADC connected in gateware)
            TODO: figure out DLO channels, etc and what they mean
    trig_delay : float
        time to delay acquisition, relative to circuit start.
        NOTE: this value, when converted to units of clock cycles, is a 
        16-bit value. So, it maxes out at `CLK_PERIOD*(2**16) = 131.072e-6`
    decimator : int
        decimation interval when sampling. e.g. 0 means full sample rate, 1
        means capture every other sample, 2 means capture every third sample, etc
    return_acc : bool
        if True, return a single acc (integrated + accumulated readout) value per shot,
        on each loaded channel. Default is `False`.

    Returns
    -------
    if `return_acc` is `False`:
        dict:
            array of acq samples for each channel in acq_chans with shape `(n_total_shots, nsamples)`

    if `return_acc` is `True`:
        tuple:
            dict:
                array of acq samples for each channel in acq_chans with shape `(n_total_shots, nsamples)`
            dict:
                array of acc values for each loaded channel with length `n_total_shots`

    """
    pass

run_circuit_batch(raw_asm_list, n_total_shots, reads_per_shot=1, timeout_per_shot=8, reload_cmd=True, reload_freq=True, reload_env=True, zero_between_reload=True) abstractmethod

Runs a batch of circuits given by a list of raw_asm "binaries". Each circuit is run n_total_shots times. reads_per_shot, n_total_shots, and delay_per_shot are passed directly into run_circuit, and must be the same for all circuits in the batch. The parameters reload_cmd, reload_freq, reload_env, and zero_between_reload control which of these fields is rewritten circuit-to-circuit (everything is rewritten initially). Leave these all at True (default) for maximum safety, to ensure that QubiC is in a clean state before each run. Depending on the circuits, some of these can be turned off to save time.

Returns:

Name Type Description
dict Dict

Complex IQ shots for each accbuf in chanlist; each array has shape (len(raw_asm_list), n_total_shots, reads_per_shot)
Source code in qubic/abstract_runner.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
@abstractmethod
def run_circuit_batch(self, 
                      raw_asm_list: List[Dict], 
                      n_total_shots: int, 
                      reads_per_shot: int | Dict = 1, 
                      timeout_per_shot: int = 8,
                      reload_cmd: bool = True, 
                      reload_freq: bool = True, 
                      reload_env: bool = True, 
                      zero_between_reload: bool = True) -> Dict:
    """
    Runs a batch of circuits given by a list of raw_asm "binaries". Each circuit is run n_total_shots
    times. `reads_per_shot`, `n_total_shots`, and `delay_per_shot` are passed directly into `run_circuit`, and must
    be the same for all circuits in the batch. The parameters reload_cmd, reload_freq, reload_env, and 
    `zero_between_reload` control which of these fields is rewritten circuit-to-circuit (everything is 
    rewritten initially). Leave these all at `True` (default) for maximum safety, to ensure that QubiC 
    is in a clean state before each run. Depending on the circuits, some of these can be turned off 
    to save time.

    Parameters
    ----------
     raw_asm_list : list
         list of raw_asm binaries to run
     n_total_shots : int
         number of shots per circuit
     reads_per_shot : int | dict
         number of values per shot per channel to read back from accbuf. If dict, indexed
         by str(channel_number) (same indices as raw_asm_list). If int, assumed to be 
         the same across channels. Unless multiple circuits were rastered pre-compilation or 
         there is mid-circuit measurement involved this is typically 1
     timeout_per_shot : float
         job will time out if time to take a single shot exceeds this value in seconds 
         (this likely means the job is hanging due to timing issues in the program or gateware)
     delay_per_shot : float (WILL BE REMOVED)
         delay time (in seconds) per single shot of the circuit
     reload_cmd : bool
         if True, reload command buffer between circuits
     reload_freq : bool
         if True, reload freq buffer between circuits
     reload_env: bool
         if True, reload env buffer between circuits

    Returns
    -------
    dict:
        Complex IQ shots for each accbuf in chanlist; each array has 
        shape `(len(raw_asm_list), n_total_shots, reads_per_shot)`
    """
    pass