Instruction Library (qiskit_aer.library)#

This library contains custom qiskit QuantumCircuit Instruction subclasses that can be used with the Aer circuit simulator backends.

Setting a Custom Simulator State#

The following instruction classes can be used to set the specific simulator methods to a custom state. Note that these instructions are only valid when applied to all qubits in a circuit. Applying to a subset of qubits will raise an exception during execution.

Instruction Classes#

SetStatevector(state)

Set the statevector state of the simulator

SetDensityMatrix(state)

Set density matrix state of the simulator

SetStabilizer(state)

Set the Clifford stabilizer state of the simulator

SetSuperOp(state)

Set superop state of the simulator

SetUnitary(state)

Set unitary state of the simulator

SetMatrixProductState(state)

Set the matrix product state of the simulator

QuantumCircuit Methods#

The set instructions can also be added to circuits by using the following QuantumCircuit methods which are patched when importing Aer.

set_statevector(self, state)

Set the statevector state of the simulator.

set_density_matrix(self, state)

Set the density matrix state of the simulator.

set_stabilizer(self, state)

Set the Clifford stabilizer state of the simulator.

set_unitary(self, state)

Set the state state of the simulator.

set_superop(self, state)

Set the superop state of the simulator.

set_matrix_product_state(self, state)

Set the matrix product state of the simulator.

Saving Simulator Data#

Simulator State Save Instruction Classes#

The following instructions can be used to save the state of the simulator into the returned result object. The SaveState instruction will automatically select the format based on the simulation method (eg. SaveStatevector for statevector method, SaveDensityMatrix for density matrix method etc.).

SaveState(num_qubits[, label, pershot, ...])

Save simulator state

SaveStatevector(num_qubits[, label, ...])

Save statevector

SaveStatevectorDict(num_qubits[, label, ...])

Save statevector as ket-form dictionary.

SaveDensityMatrix(num_qubits[, label, ...])

Save a reduced density matrix.

SaveMatrixProductState(num_qubits[, label, ...])

Save matrix product state instruction

SaveClifford(num_qubits[, label, pershot])

Save Clifford instruction

SaveStabilizer(num_qubits[, label, pershot, ...])

Save Stabilizer instruction

SaveSuperOp(num_qubits[, label, pershot])

Save a SuperOp matrix.

SaveUnitary(num_qubits[, label, pershot])

Save Unitary

Note

The SaveDensityMatrix instruction can be used to save the reduced densit matrix of a subset of qubits for supported simulation methods, however all other save state instructions must be applied to all qubits in a run circuit.

Note

The StatevectorSimulator (and UnitarySimulator) backend automatically append every run circuit with the a SaveStatevector`() (SaveUnitary`()) instruction using the default label. Hence adding any additional save instructions of that type will require specifying a custom label for those instructions.

Simulator Derived Data Save Instruction Classes#

The following classes can be used to directly save data derived from the simulator state to the returned result object. One some are compatible with certain simulation methods.

For convenience the save instructions can be accessed using custom QuantumCircuit methods

SaveExpectationValue(operator[, label, ...])

Save expectation value of an operator.

SaveExpectationValueVariance(operator[, ...])

Save expectation value and variance of an operator.

SaveProbabilities(num_qubits[, label, ...])

Save measurement outcome probabilities vector.

SaveProbabilitiesDict(num_qubits[, label, ...])

Save measurement outcome probabilities dict.

SaveAmplitudes(num_qubits, params[, label, ...])

Save complex statevector amplitudes.

SaveAmplitudesSquared(num_qubits, params[, ...])

Save squared statevector amplitudes (probabilities).

Note

When saving pershot data by using the pershot=True kwarg in the above instructions, the resulting list may only contain a single value rather than the number of shots. This happens when a run circuit supports measurement sampling because it is either

  1. An ideal simulation with all measurements at the end.

2. A noisy simulation using the density matrix method with all measurements at the end.

In both these cases only a single shot is actually simulated and measurement samples for all shots are calculated from the final state.

QuantumCircuit Methods#

The save instructions can also be added to circuits by using the following QuantumCircuit methods which are patched when importing Aer.

Note

Each save method has a default label for accessing from the circuit result data, however duplicate labels in results will result in an exception being raised. If you use more than 1 instance of a specific save instruction you must set a custom label for the additional instructions.

save_amplitudes(self, params[, label, ...])

Save complex statevector amplitudes.

save_amplitudes_squared(self, params[, ...])

Save squared statevector amplitudes (probabilities).

save_clifford(self[, label, pershot])

Save the current stabilizer simulator quantum state as a Clifford.

save_density_matrix(self[, qubits, label, ...])

Save the current simulator quantum state as a density matrix.

save_expectation_value(self, operator, qubits)

Save the expectation value of a Hermitian operator.

save_expectation_value_variance(self, ...[, ...])

Save the expectation value of a Hermitian operator.

save_matrix_product_state(self[, label, ...])

Save the current simulator quantum state as a matrix product state.

save_probabilities(self[, qubits, label, ...])

Save measurement outcome probabilities vector.

save_probabilities_dict(self[, qubits, ...])

Save measurement outcome probabilities vector.

save_stabilizer(self[, label, pershot, ...])

Save the current stabilizer simulator quantum state as a StabilizerState.

save_state(self[, label, pershot, conditional])

Save the current simulator quantum state.

save_statevector(self[, label, pershot, ...])

Save the current simulator quantum state as a statevector.

save_statevector_dict(self[, label, ...])

Save the current simulator quantum state as a statevector as a dict.

save_superop(self[, label, pershot])

Save the current state of the superop simulator.

save_unitary(self[, label, pershot])

Save the current state of the unitary simulator.

Method Compatibility#

The following table summarizes which instructions are compatible with which simulation methods

Instruction

Automatic

Statevector

Density Matrix

MPS

Stabilizer

Ext. Stabilizer

Unitary

SuperOp

SaveAmplitudes

SaveAmplitudesSquared

SaveClifford

SaveDensityMatrix

SaveExpectationValue

SaveExpectationValueVariance

SaveMatrixProductState

SaveProbabilities

SaveProbabilitiesDict

SaveStabilizer

SaveState

SaveStatevector

SaveStatevectorDict

SaveSuperOp

SaveUnitary

SetDensityMatrix

SetStabilizer

SetStatevector

SetUnitary