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.

TimeTracesAnalysisOptions

Option class for the tasks in the time-traces analysis workflows.

Attributes:

Name Type Description
granularity int

The granularity of the acquisition instrument. Used to truncate the time traces to align them to the granularity grid. Default: 16.
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.
sampling_rate float

The sampling rate of the acquisition instrument that was used to measure the time-traces. The sampling_rate is used when applying a low-pass filter to the kernels if filter_kernels is True in TimeTracesAnalysisWorkflowOptions. Default: 2e9.
do_fitting bool

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

Whether to save the figures. Default: True.
close_figures bool

Whether to close the figures. Default: True.

close_figures: bool = workflow.option_field(True, description='Whether to close the figures.') class-attribute instance-attribute

do_fitting: bool = workflow.option_field(True, description='Whether to perform the fit.') class-attribute instance-attribute

filter_cutoff_frequency: float | None = workflow.option_field(None, description='The cut-off frequency.') class-attribute instance-attribute

granularity: int = workflow.option_field(16, description='The granularity of the acquisition.') class-attribute instance-attribute

sampling_rate: float = workflow.option_field(2000000000.0, description='The sampling rate.') class-attribute instance-attribute

save_figures: bool = workflow.option_field(True, description='Whether to save the figures.') class-attribute instance-attribute

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'.

do_fitting: bool = workflow.option_field(True, description='Whether to perform the fit.') class-attribute instance-attribute

do_plotting: bool = workflow.option_field(True, description='Whether to create plots.') class-attribute instance-attribute

do_plotting_kernels_fft: bool = workflow.option_field(True, description='Whether to create the kernels-FFT plots.') class-attribute instance-attribute

do_plotting_kernels_traces: bool = workflow.option_field(True, description='Whether to create the integration-kernel plots.') class-attribute instance-attribute

do_plotting_time_traces: bool = workflow.option_field(True, description='Whether to create time-traces plots.') class-attribute instance-attribute

filter_kernels: bool = workflow.option_field(False, description='Whether to filter the kernels.') class-attribute instance-attribute

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

The time-traces analysis Workflow.

The workflow consists of the following tasks:

Parameters:

Name Type Description Default
result RunExperimentResults

The experiment results returned by the run_experiment task.

 required
qubits Qubits

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)
result = analysis_workflow(
    results=results
    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 Qubits

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 TimeTracesAnalysisOptions | None

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

 None

Returns:

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

a tuple with the list of integration kernel arrays and a list with the
dict[str, list[float]] | None

corresponding discrimination thresholds.

extract_qubit_parameters(qubits, discrimination_thresholds, integration_kernels, integration_kernels_filtered)

Extract the qubit parameters to be updated.

These parameters are readout_integration_kernels and readout_integration_discrimination_thresholds.

Parameters:

Name Type Description Default
qubits Qubits

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

Returns:

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

dict with extracted qubit parameters and the previous values for those qubit
dict[str, dict[str, dict[str, list]]]

parameters. The dictionary has the following form:
dict[str, dict[str, dict[str, list]]]

```python
dict[str, dict[str, dict[str, list]]]

{ "new_parameter_values": { q.uid: { qb_param_name: qb_param_value }, } "old_parameter_values": { q.uid: { qb_param_name: qb_param_value }, }
dict[str, dict[str, dict[str, list]]]

}
dict[str, dict[str, dict[str, list]]]

```
dict[str, dict[str, dict[str, list]]]

If integration_kernels, integration_kernels_filtered, discrimination_thresholds
dict[str, dict[str, dict[str, list]]]

are all None, then the new_parameter_values are not extracted and the function
dict[str, dict[str, dict[str, list]]]

only returns the old_parameter_values.

filter_integration_kernels(qubits, integration_kernels, options=None)

Applies a low-pass filter to the kernels.

Parameters:

Name Type Description Default
qubits Qubits

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
options TimeTracesAnalysisOptions | None

The options for building the workflow as an instance of [TimeTracesAnalysisOptions]. 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, integration_kernels_filtered=None, options=None)

Create the plots of the FFT of the integration kernels.

Parameters:

Name Type Description Default
qubits Qubits

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 TimeTracesAnalysisOptions | None

The options for building the workflow as an instance of [TimeTracesAnalysisOptions]. 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 Qubits

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 TimeTracesAnalysisOptions | None

The options for building the workflow as an instance of [TimeTracesAnalysisOptions]. 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 Qubits

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 TimeTracesAnalysisOptions | None

The options for building the workflow as an instance of [TimeTracesAnalysisOptions]. 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 Qubits

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 TimeTracesAnalysisOptions | None

The options for building the workflow as an instance of [TimeTracesAnalysisOptions]. 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
dict[str, list[ArrayLike]]

qubit as keys.