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