class StarkRamseyXYAmpScan(physical_qubits, backend=None, **experiment_options)[source]#

A fast characterization of Stark frequency shift by varying Stark tone amplitude.


This experiment scans Stark tone amplitude at a fixed tone duration. The experimental circuits are identical to the StarkRamseyXY experiment except that the Stark pulse amplitude is the scanned parameter rather than the pulse width.

(Ramsey X)  The pulse before measurement rotates by pi-half around the X axis

      q: ┤ √X ├┤ StarkV(stark_amp) ├┤ X ├┤ StarkU(stark_amp) ├┤ Rz(-π) ├┤ √X ├┤M├
    c: 1/══════════════════════════════════════════════════════════════════════╩═

(Ramsey Y) The pulse before measurement rotates by pi-half around the Y axis

      q: ┤ √X ├┤ StarkV(stark_amp) ├┤ X ├┤ StarkU(stark_amp) ├┤ Rz(-3π/2) ├┤ √X ├┤M├
    c: 1/═════════════════════════════════════════════════════════════════════════╩═

The AC Stark effect can be used to shift the frequency of a qubit with a microwave drive. To calibrate a specific frequency shift, the StarkRamseyXY experiment can be run to scan the Stark pulse duration at every amplitude, but such a two dimensional scan of the tone duration and amplitude may require many circuit executions. To avoid this overhead, the StarkRamseyXYAmpScan experiment fixes the tone duration and scans only amplitude.

Recall that an observed Ramsey oscillation in each quadrature may be represented by

\[\begin{split}{\cal E}_X(\Omega, t_S) = A e^{-t_S/\tau} \cos \left( 2\pi f_S(\Omega) t_S \right), \\ {\cal E}_Y(\Omega, t_S) = A e^{-t_S/\tau} \sin \left( 2\pi f_S(\Omega) t_S \right),\end{split}\]

where \(f_S(\Omega)\) denotes the amount of Stark shift at a constant tone amplitude \(\Omega\), and \(t_S\) is the duration of the applied tone. For a fixed tone duration, one can still observe the Ramsey oscillation by scanning the tone amplitude. However, since \(f_S\) is usually a higher order polynomial of \(\Omega\), one must manage to fit the y-data for trigonometric functions with phase which non-linearly changes with the x-data. The StarkRamseyXYAmpScan experiment thus drastically reduces the number of circuits to run in return for greater complexity in the fitting model.

User manual

AC Stark Effect

Analysis class reference


Experiment options

These options can be set by the set_experiment_options() method.

  • Defined in the class StarkRamseyXYAmpScan:

    • stark_channel (PulseChannel)

      Default value: None
      Pulse channel on which to apply Stark tones. If not provided, the same channel with the qubit drive is used. See Stark tone channel for details.
    • stark_freq_offset (float)

      Default value: 80000000.0
      Offset of Stark tone frequency from the qubit frequency. This offset should be sufficiently large so that the Stark pulse does not Rabi drive the qubit. See Stark tone frequency for details.
    • stark_sigma (float)

      Default value: 1.5e-08
      Gaussian sigma of the rising and falling edges of the Stark tone, in seconds.
    • stark_risefall (float)

      Default value: 2
      Ratio of sigma to the duration of the rising and falling edges of the Stark tone.
    • stark_length (float)

      Default value: 5e-08
      Time to accumulate Stark shifted phase in seconds.
    • min_stark_amp (float)

      Default value: -1.0
      Minimum Stark tone amplitude.
    • max_stark_amp (float)

      Default value: 1.0
      Maximum Stark tone amplitude.
    • num_stark_amps (int)

      Default value: 101
      Number of Stark tone amplitudes to scan.
    • stark_amps (list[float])

      Default value: None
      The list of amplitude that will be scanned in the experiment. If not set, then num_stark_amps evenly spaced amplitudes between min_stark_amp and max_stark_amp are used. If stark_amps is set, these parameters are ignored.
  • Defined in the class BaseExperiment:

    • max_circuits (Optional[int])

      Default value: None
      The maximum number of circuits per job when running an experiment on a backend.

See also

qiskit_experiments.library.driven_freq_tuning.ramsey.StarkRamseyXY qiskit_experiments.library.characterization.ramsey_xy.RamseyXY


Create new experiment.

  • physical_qubits (Sequence[int]) – Sequence with the index of the physical qubit.

  • backend (Backend | None) – Optional, the backend to run the experiment on.

  • experiment_options – Experiment options. See the class documentation or self._default_experiment_options for descriptions.



Return the analysis instance for the experiment


Return the backend for the experiment


Return the options for the experiment.


Return experiment type.


Return the number of qubits for the experiment.


Return the device qubits for the experiment.


Return options values for the experiment run() method.


Return the transpiler options for the run() method.



Create circuits.


A list of circuits with a variable Stark tone amplitudes.

Return type:



Return the config dataclass for this experiment

Return type:



Return a copy of the experiment

Return type:


classmethod from_config(config)#

Initialize an experiment from experiment config

Return type:



Get information about job distribution for the experiment on a specific backend.


backend (Backend) – Optional, the backend for which to get job distribution information. If not specified, the experiment must already have a set backend.


A dictionary containing information about job distribution.

  • ”Total number of circuits in the experiment”: Total number of circuits in the experiment.

  • ”Maximum number of circuits per job”: Maximum number of circuits in one job based on backend and experiment settings.

  • ”Total number of jobs”: Number of jobs needed to run this experiment on the currently set backend.

Return type:



QiskitError – if backend is not specified.


Create circuits with parameters for Ramsey XY experiment with Stark tone.


Quantum template circuits for Ramsey X and Ramsey Y experiment.

Return type:

tuple[QuantumCircuit, …]


Stark tone amplitudes to use in circuits.


The list of amplitudes to use for the different circuits based on the experiment options.

Return type:


run(backend=None, analysis='default', timeout=None, **run_options)#

Run an experiment and perform analysis.

  • backend (Backend | None) – Optional, the backend to run the experiment on. This will override any currently set backends for the single execution.

  • analysis (BaseAnalysis | None) – Optional, a custom analysis instance to use for performing analysis. If None analysis will not be run. If "default" the experiments analysis() instance will be used if it contains one.

  • timeout (float | None) – Time to wait for experiment jobs to finish running before cancelling.

  • run_options – backend runtime options used for circuit execution.


The experiment data object.


QiskitError – If experiment is run with an incompatible existing ExperimentData container.

Return type:



Set the experiment options.


fields – The fields to update the options


AttributeError – If the field passed in is not a supported options


Set options values for the experiment run() method.


fields – The fields to update the options

See also

The Setting options for your experiment guide for code example.


Set the transpiler options for run() method.


fields – The fields to update the options


QiskitError – If initial_layout is one of the fields.

See also

The Setting options for your experiment guide for code example.