DynamicsBackend#

class DynamicsBackend(solver, target=None, **options)[source]#

Bases: BackendV2

Pulse-level simulator backend.

This class provides a BackendV2 interface wrapper around a Solver instance setup to simulate pulse schedules. The backend can be configured to take advantage of standard transpilation infrastructure to describe pulse-level simulations in terms of QuantumCircuits. Results are returned as Result instances.

A minimal DynamicsBackend requires specifying only a Solver instance and a list of subsystem dimensions, indicating the subsystem decomposition of the model in Solver. For example, the following code builds a DynamicsBackend around a Solver and indicates that the system specified by the Solver decomposes as two 3 dimensional subsystems.

backend = DynamicsBackend(
    solver=solver, subsystem_dims=[3, 3]
)

Without further configuration, the above backend can be used to simulate either Schedule or ScheduleBlock instances.

Pulse-level simulations defined in terms of QuantumCircuit instances can also be performed if each gate in the circuit has a corresponding pulse-level definition, either as an attached calibration, or as an instruction contained in backend.target.

Additionally, a DynamicsBackend can be instantiated from an existing backend using the DynamicsBackend.from_backend() method, utilizing the additional subsystem_list argument to specify which qubits to include in the model:

backend = DynamicsBackend.from_backend(backend, subsystem_list=[0, 1])

Supported options

The behaviour of the backend can be configured via the following options. These can either be passed as optional keyword arguments at construction, set with the DynamicsBackend.set_options() method after construction, or passed as runtime arguments to DynamicsBackend.run().

shots: Number of shots per experiment. Defaults to 1024.
solver: The Qiskit Dynamics Solver instance used for simulation.
solver_options: Dictionary containing optional kwargs for passing to Solver.solve(), indicating solver methods and options. Defaults to the empty dictionary {}.
subsystem_dims: Dimensions of subsystems making up the system in solver. Defaults to [solver.model.dim].
meas_map: Measurement map. Defaults to [[idx] for idx in range(len(subsystem_dims))].
control_channel_map: A dictionary mapping control channel labels to indices, to be used for control channel index lookup in the DynamicsBackend.control_channel() method.
initial_state: Initial state for simulation, either the string "ground_state", indicating that the ground state for the system Hamiltonian should be used, or an arbitrary Statevector or DensityMatrix. Defaults to "ground_state".
normalize_states: Boolean indicating whether to normalize states before computing outcome probabilities, and normalize probablities before sampling. Defaults to True. Setting to False can result in errors if the solution tolerance results in probabilities with significant numerical deviation from a proper probability distribution.
meas_level: Form of measurement output. Supported values are 1 and 2. 1 returns IQ points and 2 returns counts. Defaults to meas_level == 2.
meas_return: Level of measurement data to return. For meas_level = 1 "single" returns output from every shot. "avg" returns average over shots of measurement output. Defaults to "avg".
iq_centers: Centers for IQ distribution when using meas_level==1 results. Must have type List[List[List[float, float]]] formatted as iq_centers[subsystem][level] = [I, Q]. If None, the iq_centers are dynamically generated to be equally spaced points on a unit circle with ground-state at (1, 0). The default is None.
iq_width: Standard deviation of IQ distribution around the centers for meas_level==1. Must be a positive float. Defaults to 0.2.
max_outcome_level: For meas_level == 2, the maximum outcome for each subsystem. Values will be rounded down to be no larger than max_outcome_level. Must be a positive integer or None. If None, no rounding occurs. Defaults to 1.
memory: Boolean indicating whether to return a list of explicit measurement outcomes for every experimental shot. Defaults to True.
seed_simulator: Seed to use in random sampling. Defaults to None.
experiment_result_function: Function for computing the ExperimentResult for each simulated experiment. This option defaults to default_experiment_result_function(), and any other function set to this option must have the same signature. Note that the default utilizes various other options that control results computation, and hence changing it will impact the meaning of other options.
configuration: A PulseBackendConfiguration instance or None. This option defaults to None, and is not required for the functioning of this class, but is provided for compatibility. A set configuration will be returned by DynamicsBackend.configuration().
defaults: A PulseDefaults instance or None. This option defaults to None, and is not required for the functioning of this class, but is provided for compatibility. A set defaults will be returned by DynamicsBackend.defaults().

Instantiate with a Solver instance and additional options.

Parameters:

solver (Solver) – Solver instance configured for pulse simulation.
target (Optional[Target]) – Target object.
options – Additional configuration options for the simulator.

Raises:

QiskitError – If any instantiation arguments fail validation checks.

Methods

acquire_channel(qubit)[source]#

Return the measure channel for a given qubit.

Return type:: AcquireChannel

configuration()[source]#

Get the backend configuration.

Return type:: PulseBackendConfiguration

control_channel(qubits)[source]#

Return the control channel with a given label specified by qubits.

This method requires the control_channel_map option is set, and otherwise will raise a NotImplementedError.

Parameters:

qubits (Union[Tuple[int, int], List[Tuple[int, int]]]) – The label for the control channel, or a list of labels.

Return type:

List[ControlChannel]

Returns:

A list containing the control channels specified by qubits.

Raises:

NotImplementedError – If the control_channel_map option is not set for this backend.
QiskitError – If a requested channel is not in the control_channel_map.

defaults()[source]#

Get the backend defaults.

Return type:: PulseDefaults

drive_channel(qubit)[source]#

Return the drive channel for a given qubit.

Return type:: DriveChannel

classmethod from_backend(backend, subsystem_list=None, rotating_frame='auto', array_library=None, vectorized=False, rwa_cutoff_freq=None, **options)[source]#

Construct a DynamicsBackend instance from an existing Backend instance.

Warning

Due to inevitable model inaccuracies, gates calibrated on a real backend will not have the same performance on the DynamicsBackend instance returned by this method. As such, gates and calibrations are not be copied into the constructed DynamicsBackend.

The backend must contain sufficient information in the target, configuration, and/or defaults attributes to be able to run simulations. The following table indicates which parameters are required, along with their primary and secondary sources:

Table 3 Backend parameter locations#
Parameter	Primary source	Secondary source
`hamiltonian` dictionary.	`configuration.hamiltonian`	N/A
Control channel frequency specification.	`configuration.u_channel_lo`	N/A
Number of qubits in the backend model.	`target.num_qubits`	`configuration.n_qubits`
Pulse schedule sample size `dt`.	`target.dt`	`configuration.dt`
Drive channel frequencies.	`target.qubit_properties`	`defaults.qubit_freq_est`
Measurement channel frequencies, if measurement channels explicitly appear in the model.	`defaults.meas_freq_est`	N/A

Note

The target, configuration, and defaults attributes of the original backend are not copied into the constructed DynamicsBackend instance, only the required data stored within these attributes will be extracted. If necessary, these attributes can be set and configured by the user.

The optional argument subsystem_list specifies which subset of qubits to model in the constructed DynamicsBackend. All other qubits are dropped from the model.

Configuration of the underlying Solver is controlled via the rotating_frame, array_library, vectorized, and rwa_cutoff_freq options. In contrast to Solver initialization, rotating_frame defaults to the string "auto", which allows this method to choose the rotating frame based on array_library:

If a dense array_library is chosen, the rotating frame will be set to the static_hamiltonian indicated by the Hamiltonian in backend.configuration().
If a sparse array_library is chosen, the rotating frame will be set to the diagonal of static_hamiltonian.

Otherwise the rotating_frame, array_library, vectorized, and rwa_cutoff_freq are passed directly to the Solver initialization.

Parameters:

backend (BackendV1) – The Backend instance to build the DynamicsBackend from. Note that while the type hint indicates that backend should be a BackendV1 instance, this method also works for BackendV2 instances that have been set up with sufficiently populated configuration and defaults for backwards compatibility.
subsystem_list (Optional[List[int]]) – The list of qubits in the backend to include in the model.
rotating_frame (Union[ndarray, number, int, float, complex, Tracer, Array, Array, spmatrix, BCOO, list, RotatingFrame, str, None]) – Rotating frame argument for the internal Solver. Defaults to "auto", allowing this method to pick a rotating frame.
array_library (Optional[str]) – Array library with which to store the operators in the Solver. See the model evaluation section of the Models API documentation for a more detailed description of this argument.
vectorized (Optional[bool]) – If a Lindblad terms are present, whether or not to build the Solver in a vectorized mode.
rwa_cutoff_freq (Optional[float]) – Rotating wave approximation argument for the internal Solver.
**options – Additional options to be applied in construction of the DynamicsBackend.

Return type:

DynamicsBackend

Returns:

DynamicsBackend

Raises:

QiskitError – If any required parameters are missing from the passed backend.

measure_channel(qubit)[source]#

Return the measure channel for a given qubit.

Return type:: MeasureChannel

qubit_properties(qubit)#

Return QubitProperties for a given qubit.

If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented.

Parameters:: qubit (Union[int, List[int]]) – The qubit to get the QubitProperties object for. This can be a single integer for 1 qubit or a list of qubits and a list of QubitProperties objects will be returned in the same order
Return type:: Union[QubitProperties, List[QubitProperties]]
Returns:: The QubitProperties object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be None.
Raises:: NotImplementedError – if the backend doesn’t support querying the qubit properties

run(run_input, validate=True, **options)[source]#

Run a list of simulations.

Parameters:

run_input (List[Union[QuantumCircuit, Schedule, ScheduleBlock]]) – A list of simulations, specified by QuantumCircuit, Schedule, or ScheduleBlock instances.
validate (Optional[bool]) – Whether or not to run validation checks on the input.
**options – Additional run options to temporarily override current backend options.

Return type:

DynamicsJob

Returns:

DynamicsJob object containing results and status.

Raises:

QiskitError – If invalid options are set.

set_options(**fields)[source]#: Set options for DynamicsBackend.

solve(solve_input, t_span, y0=None, convert_results=True, validate=True)[source]#

Simulate a list of QuantumCircuit, Schedule, or ScheduleBlock instances and return the OdeResult.

This method is analogous to Solver.solve(), however it additionally utilizes transpilation and the backend configuration to convert QuantumCircuit instances into pulse-level schedules for simulation. The options for the solver will be drawn from self.options.solver_options, and if y0 is not specified, it will be set from self.options.initial_state.

Parameters:

t_span (Union[ndarray, number, int, float, complex, Tracer, Array, Array, spmatrix, BCOO, list]) – Time interval to integrate over.
y0 (Union[ndarray, number, int, float, complex, Tracer, Array, Array, spmatrix, BCOO, list, QuantumState, BaseOperator, None]) – Initial state.
solve_input (List[Union[QuantumCircuit, Schedule, ScheduleBlock]]) – Time evolution of the system in terms of quantum circuits or qiskit pulse schedules.
convert_results (Optional[bool]) – If True, convert returned solver state results to the same class as y0. If False, states will be returned in the native array type used by the specified solver method.
validate (Optional[bool]) – Whether or not to run validation checks on the input.

Returns:

object with formatted output types.

Return type:

OdeResult

Attributes

coupling_map#: Return the CouplingMap object

dt#

Return the system time resolution of input signals

This is required to be implemented if the backend supports Pulse scheduling.

Returns:: The input signal timestep in seconds. If the backend doesn’t define dt, None will be returned.

dtm#

Return the system time resolution of output signals

Returns:: The output signal timestep in seconds.
Raises:: NotImplementedError – if the backend doesn’t support querying the output signal timestep

instruction_durations#: Return the InstructionDurations object.

instruction_schedule_map#: Return the InstructionScheduleMap for the instructions defined in this backend’s target.

instructions#: A list of Instruction tuples on the backend of the form (instruction, (qubits)

max_circuits#

meas_map#

num_qubits#: Return the number of qubits the backend has.

operation_names#: A list of instruction names that the backend supports.

operations#: A list of Instruction instances that the backend supports.

options#

Return the options for the backend

The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the run() method.

provider#

Return the backend Provider.

Returns:: the Provider responsible for the backend.
Return type:: Provider

target#

version = 2#

name#: Name of the backend.

description#: Optional human-readable description.

online_date#: Date that the backend came online.

backend_version#: Version of the backend being provided. This is not the same as BackendV2.version, which is the version of the Backend abstract interface.