BackendTiming

class BackendTiming(backend, *, acquire_alignment=None, granularity=None, min_length=None, pulse_alignment=None, dt=None)[source]

Helper for calculating pulse and delay times for an experiment

The methods and properties provided by this class help with calculating delay timing that depends on the timing constraints of the backend.

When designing qubit characterization experiments, it is often necessary to deal with precise timing of delays. The fact that physical backends (i.e. not simulators) only support sampling time at intervals of dt complicates this process as times must be rounded. Besides the sampling time, there can be additional constraints like a granularity, which specifies the allowed increments of a delay length in samples (i.e., for a granularity of 16, delay lengths of 64 and 80 samples are valid but not any number in between).

Here are some specific problems that can occur when dealing with timing constraints for pulses and delays:

  • An invalid delay length could be rounded by the backend, and this rounding could lead to error in analysis that assumes the unrounded value.

  • An invalid delay length that requires rounding could trigger a new scheduling pass of a circuit during transpilation, which is a computationally expensive process. Scheduling the circuit with valid timing to start out can avoid this rescheduling.

As an example use-case for BackendTiming, consider a T1 experiment where delay times are specified in seconds in a qiskit_experiments.framework.BaseExperiment.circuits() method as follows:

def circuits(self):
    # Pass backend to BackendTiming
    timing = BackendTiming(self.backend)

    circuits = []
    # delays is a list of delay values in seconds
    for delay in self.experiment_options.delays:
        circ = QuantumCircuit(1, 1)
        circ.x(0)
        # Convert delay into appropriate units for backend and also set
        # those units with delay_unit
        circ.delay(timing.round_delay(time=delay), 0, timing.delay_unit)
        circ.measure(0, 0)

        # Use delay_time to get the actual value in seconds that was
        # set on the backend for the xval rather than the delay
        # variable's nominal value.
        circ.metadata = {
            "unit": "s",
            "xval": timing.delay_time(time=delay),
        }

        circuits.append(circ)

Initialize backend timing object

Note

Backend may not accept user defined constraint value. One may want to provide these values when the constraints data is missing in the backend, or in some situation you can intentionally ignore the constraints. Invalid constraint values may break experiment circuits, resulting in the failure in or unexpected results from the execution.

Parameters:

  • backend (Backend) – the backend to provide timing help for.

  • acquire_alignment (int | None) – Optional. Deprecated and unused.

  • granularity (int | None) – Optional. Constraint for the pulse samples granularity in units of dt. Defaults to the backend value.

  • min_length (int | None) – Optional. Deprecated and unused.

  • pulse_alignment (int | None) – Optional. Deprecated and unused.

  • dt (float | None) – Optional. Time interval of pulse samples. Default to the backend value.

Attributes

delay_unit

The delay unit for the current backend

“dt” is used if dt is present in the backend configuration. Otherwise “s” is used.

dt

The backend’s dt value, copied to BackendTiming for convenience

Methods

delay_time(*, time=None, samples=None)[source]

The closest valid delay time in seconds to the input

If the backend reports dt, this method uses BackendTiming.round_delay() and converts the result back into seconds. Otherwise, if time was passed, it is returned directly.

Parameters:

  • time (float | None) – The nominal delay time to convert in seconds

  • samples (int | float | None) – The nominal delay time to convert in samples

Returns:

The realizable delay time in seconds

Raises:

QiskitError – If either both time and samples are passed or neither is passed.

Return type:

float

round_delay(*, time=None, samples=None)[source]

Delay duration closest to input and consistent with timing constraints

This method produces the value to pass for the duration of a Delay instruction of a QuantumCircuit so that the delay fills the time until the next valid pulse, assuming the Delay instruction begins on a sample that is also valid for a pulse to begin on.

The pulse timing constraints of the backend are considered in order to give the number of samples closest to the input (either time or samples) for the start of a pulse in a subsequent instruction to be valid. The delay value in samples is rounded to the least common multiple of the pulse and acquire alignment values in order to ensure that either type of pulse will be aligned.

If BackendTiming.delay_unit() is s, time is returned directly. Typically, this is the case for a simulator where converting to sample number is not needed.

Parameters:

  • time (float | None) – The nominal delay time to convert in seconds

  • samples (int | float | None) – The nominal delay time to convert in samples

Returns:

The delay duration in samples if BackendTiming.delay_unit() is dt. Otherwise return time.

Raises:

QiskitError – If either both time and samples are passed or neither is passed.

Return type:

int | float