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	✘	✘	✘	✘	✘	✘	✔	✘