Skip to content

laboneq_applications.analysis.time_traces

This module defines the analysis for a time-traces experiment.

The experiment is defined in laboneq_applications.experiments.

In this analysis, we extract the optimal integration kernels from the raw time traces. The kernels allow maximal discrimination between the qubit states which were used to measure the time traces. Then, we optionally apply a low-pass filter to the kernels with a cut-off frequency chosen by the user to remove any spurious signals in the kernels (for example, the down-converted TWPA pump tone). We then create the dictionary with qubit parameters to update, and finally we plot the time traces and the kernels.

ExtractSamplingRateOptions

Options class for the extract_sampling_rate task.

Attributes:

Name Type Description
sampling_rate float | None

The sampling rate of the acquisition instrument that was used to measure the time traces. If None, the sampling rate is derived from the acquired raw traces and rounded to the nearest whole GSa/s. Default: None.

FilterIntegrationKernelsOptions

Options class for the filter_integration_kernels task.

Attributes:

Name Type Description
filter_cutoff_frequency float | None

The cut-off frequency of the low-pass filter for the kernels. Only used if filter_kernels is True in TimeTracesAnalysisWorkflowOptions. Default: None.
do_fitting

Whether to perform the fit. Default: True.

PlotKernelsFFTOptions

Options class for the filter_integration_kernels task.

Attributes:

Name Type Description
filter_cutoff_frequency float | None

The cut-off frequency of the low-pass filter for the kernels. Only used if filter_kernels is True in TimeTracesAnalysisWorkflowOptions. Default: None.
save_figures

Whether to save the figures. Default: True.
close_figures

Whether to close the figures. Default: True.

TimeTracesAnalysisWorkflowOptions

Option class for the time-traces analysis workflow.

Attributes:

Name Type Description
filter_kernels bool

Whether to filter the integration kernels. Default: 'False'.
do_fitting bool

Whether to perform the fit. Default: True.
do_plotting bool

Whether to create plots. Default: 'True'.
do_plotting_time_traces bool

Whether to create the time-traces plots. Default: 'True'.
do_plotting_kernels_traces bool

Whether to create the integration-kernel plots. Default: 'True'.
do_plotting_kernels_fft bool

Whether to create the kernels-FFT plots. Default: 'True'.

TruncateTimeTracesOptions

Options class for the truncate_time_traces task.

Attributes:

Name Type Description
granularity int

The granularity of the acquisition instrument in samples. Used to truncate the time traces to align them to the granularity grid. The default value of 16 is the granularity of the SHFQA. Default: 16.
do_fitting

Whether to perform the fit. Default: True.

analysis_workflow(result, qubits, states, options=None)

The time-traces analysis Workflow.

The workflow consists of the following tasks:

Changed in version 26.10.0

The sampling rate of the acquisition instrument is now derived from the acquired raw traces instead of being assumed to be 2 GSa/s. It can still be set explicitly via the sampling_rate option. The extract_sampling_rate task has been added to the workflow.

Parameters:

Name Type Description Default
result RunExperimentResults

The experiment results returned by the run_experiment task.

 required
qubits QuantumElements

The qubits on which to run the analysis. May be either a single qubit or a list of qubits. The UIDs of these qubits must exist in the result.

 required
states Sequence[Literal['g', 'e', 'f']]

The qubit basis states for which the time traces were measured. May be either a string, e.g. "gef", or a list of letters, e.g. ["g","e","f"].

 required
options TimeTracesAnalysisWorkflowOptions | None

The options for building the workflow as an instance of TimeTracesAnalysisWorkflowOptions. See the docstring of this class for more details.

 None

Returns:

Name Type Description
WorkflowBuilder None

The builder for the analysis workflow.
Example 
options = analysis_workflow.options()
options.close_figures(False)
analysis_result = analysis_workflow(
    result=result,
    qubits=[q0, q1],
    states="ge",
    options=options,
).run()

extract_kernels_thresholds(qubits, truncated_time_traces, options=None)

Extract the integration kernels and discrimination thresholds.

Parameters:

Name Type Description Default
qubits QuantumElements

The qubits on which to run the task. May be either a single qubit or a list of qubits. The UIDs of these qubits must exist in the keys of the truncated_time_traces dictionary.

 required
truncated_time_traces dict[str, list[NDArray]]

The dictionary of truncated time traces for each qubit as returned by truncate_time_traces.

 required
options DoFittingOption | None

The options for this task as an instance of DoFittingOption. See the docstring of this class for more details.

 None

Returns:

Type Description
tuple[dict[str, list[ArrayLike]] | None, dict[str, list[float]] | None]

a tuple with the list of integration kernel arrays and a list with the corresponding discrimination thresholds.

extract_qubit_parameters(qubits, discrimination_thresholds, integration_kernels, integration_kernels_filtered, options=None)

Extract the qubit parameters to be updated.

These parameters are readout_integration_kernels and readout_integration_discrimination_thresholds.

Parameters:

Name Type Description Default
qubits QuantumElements

The qubits on which to run the task. May be either a single qubit or a list of qubits. The UIDs of these qubits must exist in the keys of the dictionaries discrimination_thresholds, integration_kernels and integration_kernels_filtered.

 required
discrimination_thresholds dict[str, list] | None

The dictionary with the discrimination thresholds corresponding to the integration kernels, as returned by extract_kernels_thresholds.

 required
integration_kernels dict[str, list] | None

The dictionary with the arrays of integration kernels for each qubit as returned by extract_kernels_thresholds.

 required
integration_kernels_filtered dict[str, list] | None

The dictionary with the arrays of filtered integration kernels for each qubit as returned by filter_integration_kernels.

 required
options DoFittingOption | None

The options for this task as an instance of DoFittingOption. See the docstring of this class for more details.

 None

Returns:

Type Description
dict[str, dict[str, dict[str, list]]]

dict with extracted qubit parameters and the previous values for those qubit parameters. The dictionary has the following form:

{
    "new_parameter_values": {
        q.uid: {qb_param_name: qb_param_value},
    },
    "old_parameter_values": {
        q.uid: {qb_param_name: qb_param_value},
    },
}

If integration_kernels, integration_kernels_filtered, discrimination_thresholds are all None, then the new_parameter_values are not extracted and the function only returns the old_parameter_values.

extract_sampling_rate(qubits, result, states, options=None)

Extract the sampling rate of the acquisition instrument.

Unless the sampling rate is given via the options, it is derived from the acquired raw traces of the first qubit: in raw-acquisition mode, the number of acquired samples is the acquisition length requested by the measure operation, which is the qubit parameter readout_integration_length, times the sampling rate of the acquisition instrument.

The derived sampling rate is then rounded to the nearest whole GSa/s. To use a different sampling rate, please set the sampling_rate option explicitly.

Parameters:

Name Type Description Default
qubits QuantumElements

The qubits on which to run the task. May be either a single qubit or a list of qubits.

 required
result RunExperimentResults

The experiment results returned by the run_experiment task.

 required
states Sequence[Literal['g', 'e', 'f']]

The basis states the qubits were prepared in. May be either a string, e.g. "gef", or a list of letters, e.g. ["g","e","f"].

 required
options ExtractSamplingRateOptions | None

The options for this task as an instance of ExtractSamplingRateOptions. See the docstring of this class for more details.

 None

Returns:

Type Description
float

The sampling rate of the acquisition instrument in Sa/s.

Raises:

Type Description
ValueError

If the sampling rate is not given via the options and the first qubit has no readout_integration_length parameter to derive it from.

filter_integration_kernels(qubits, integration_kernels, sampling_rate, options=None)

Applies a low-pass filter to the kernels.

Changed in version 26.10.0

The sampling_rate argument has been added and the sampling_rate option has been removed. The sampling rate is now resolved by the extract_sampling_rate task.

Parameters:

Name Type Description Default
qubits QuantumElements

The qubits on which to run the task. May be either a single qubit or a list of qubits. The UIDs of these qubits must exist in the keys of the integration_kernels dictionary.

 required
integration_kernels dict[str, list[ArrayLike]]

A dictionary with qubit uids as keys and the list of arrays of optimal integration kernels as values.

 required
sampling_rate float

The sampling rate of the acquisition instrument in Sa/s, as returned by extract_sampling_rate.

 required
options FilterIntegrationKernelsOptions | None

The options for this task as an instance of FilterIntegrationKernelsOptions. See the docstring of this class for more details.

 None

Returns:

Type Description
dict[str, list]

a list with the arrays of filtered integration kernels

Raises:

Type Description
ValueError

If the filter_cutoff_frequency is None.

plot_kernels_fft(qubits, discrimination_thresholds, integration_kernels, sampling_rate, integration_kernels_filtered=None, options=None)

Create the plots of the FFT of the integration kernels.

Changed in version 26.10.0

The sampling_rate argument has been added. The frequency axis of the plots was previously calculated assuming a sampling rate of 2 GSa/s.

Parameters:

Name Type Description Default
qubits QuantumElements

The qubits on which to run the task. May be either a single qubit or a list of qubits. The UIDs of these qubits must exist in the keys of the dictionaries discrimination_thresholds, integration_kernels and integration_kernels_filtered.

 required
discrimination_thresholds dict[str, list]

The dictionary with the discrimination thresholds corresponding to the integration kernels, as returned by extract_kernels_thresholds.

 required
integration_kernels dict[str, list]

The dictionary with the arrays of integration kernels for each qubit as returned by extract_kernels_thresholds.

 required
sampling_rate float

The sampling rate of the acquisition instrument in Sa/s, as returned by extract_sampling_rate.

 required
integration_kernels_filtered dict[str, list] | None

The dictionary with the arrays of filtered integration kernels for each qubit as returned by filter_integration_kernels. If None, only the integration_kernels are plotted.

 None
options PlotKernelsFFTOptions | None

The options for this task as an instance of PlotKernelsFFTOptions. See the docstring of this class for more details.

 None

Returns:

Type Description
dict[str, Figure]

dict with qubit UIDs as keys and the figures for each qubit as values.

plot_kernels_traces(qubits, discrimination_thresholds, integration_kernels, integration_kernels_filtered=None, options=None)

Create the plots of the integration kernels.

Parameters:

Name Type Description Default
qubits QuantumElements

The qubits on which to run the task. May be either a single qubit or a list of qubits. The UIDs of these qubits must exist in the keys of the dictionaries discrimination_thresholds, integration_kernels and integration_kernels_filtered.

 required
discrimination_thresholds dict[str, list]

The dictionary with the discrimination thresholds corresponding to the integration kernels, as returned by extract_kernels_thresholds.

 required
integration_kernels dict[str, list]

The dictionary with the arrays of integration kernels for each qubit as returned by extract_kernels_thresholds.

 required
integration_kernels_filtered dict[str, list] | None

The dictionary with the arrays of filtered integration kernels for each qubit as returned by filter_integration_kernels. If None, only the integration_kernels are plotted.

 None
options BasePlottingOptions | None

The options for this task as an instance of BasePlottingOptions. See the docstring of this class for more details.

 None

Returns:

Type Description
dict[str, Figure]

dict with qubit UIDs as keys and the figures for each qubit as values.

plot_time_traces(qubits, states, truncated_time_traces, options=None)

Create the time-traces plots.

Parameters:

Name Type Description Default
qubits QuantumElements

The qubits on which to run the task. May be either a single qubit or a list of qubits. The UIDs of these qubits must exist in the keys of the truncated_time_traces dictionary.

 required
states Sequence[str]

The qubit basis states for which the time traces were measured. May be either a string, e.g. "gef", or a list of letters, e.g. ["g","e","f"].

 required
truncated_time_traces dict[str, list]

The dictionary of truncated time traces for each qubit as returned by truncate_time_traces.

 required
options BasePlottingOptions | None

The options for this task as an instance of BasePlottingOptions. See the docstring of this class for more details.

 None

Returns:

Type Description
dict[str, Figure]

dict with qubit UIDs as keys and the figures for each qubit as values.

truncate_time_traces(qubits, result, states, options=None)

Truncate the time traces to align on the granularity grid.

The granularity is passed via the options and is typically 16 samples (default).

Parameters:

Name Type Description Default
qubits QuantumElements

The qubits on which to run the analysis. May be either a single qubit or a list of qubits.

 required
result RunExperimentResults

The experiment results returned by the run_experiment task.

 required
states Sequence[Literal['g', 'e', 'f']]

The basis states the qubits should be prepared in. May be either a string, e.g. "gef", or a list of letters, e.g. ["g","e","f"].

 required
options TruncateTimeTracesOptions | None

The options for this task as an instance of TruncateTimeTracesOptions. See the docstring of this class for more details.

 None

Returns:

Type Description
dict[str, list[ArrayLike]]

dict with qubit UIDs as keys and the list of truncated time-traces for each qubit as keys.