Additional circuit methods#

On import, Aer adds several simulation-specific methods to QuantumCircuit for convenience. These methods are not available until Aer is imported (import qiskit_aer).

Setting a custom simulator state#

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

QuantumCircuit.set_density_matrix(state)#

Set the density matrix state of the simulator.

Parameters:

state (DensityMatrix) – a density matrix.

Returns:

with attached instruction.

Return type:

QuantumCircuit

Raises:

ValueError – If the density matrix is the incorrect size for the current circuit.

QuantumCircuit.set_stabilizer(state)#

Set the Clifford stabilizer state of the simulator.

Parameters:

state (Clifford) – A clifford operator.

Returns:

with attached instruction.

Return type:

QuantumCircuit

Raises:

ValueError – If the state is the incorrect size for the current circuit.

QuantumCircuit.set_unitary(state)#

Set the state state of the simulator.

Parameters:

state (Operator) – A state matrix.

Returns:

with attached instruction.

Return type:

QuantumCircuit

Raises:

  • ValueError – If the state is the incorrect size for the current circuit.

  • ValueError – if the input matrix is not unitary.

QuantumCircuit.set_superop(state)#

Set the superop state of the simulator.

Parameters:

state (QuantumChannel) – A CPTP quantum channel.

Returns:

with attached instruction.

Return type:

QuantumCircuit

Raises:

  • ValueError – If the state is the incorrect size for the current circuit.

  • ValueError – if the input QuantumChannel is not CPTP.

QuantumCircuit.set_matrix_product_state(state)#

Set the matrix product state of the simulator.

Parameters:

state (Tuple[List[Tuple[np.array[complex_t]]]], List[List[float]]) – A matrix_product_state.

Returns:

with attached instruction.

Return type:

QuantumCircuit

Raises:

ValueError – If the structure of the state is incorrect

Saving Simulator Data#

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.

QuantumCircuit.save_amplitudes(params, label='amplitudes', pershot=False, conditional=False)#

Save complex statevector amplitudes.

Parameters:

  • params (List[int] or List[str]) – the basis states to return amplitudes for.

  • label (str) – the key for retrieving saved data from results.

  • pershot (bool) – if True save a list of amplitudes vectors for each shot of the simulation rather than the a single amplitude vector [Default: False].

  • conditional (bool) – if True save the amplitudes vector conditional on the current classical register values [Default: False].

Returns:

with attached instruction.

Return type:

QuantumCircuit

Raises:

ValueError – if params is invalid for the specified number of qubits.

QuantumCircuit.save_amplitudes_squared(params, label='amplitudes_squared', unnormalized=False, pershot=False, conditional=False)#

Save squared statevector amplitudes (probabilities).

Parameters:

  • params (List[int] or List[str]) – the basis states to return amplitudes for.

  • label (str) – the key for retrieving saved data from results.

  • unnormalized (bool) – If True return save the unnormalized accumulated probabilities over all shots [Default: False].

  • pershot (bool) – if True save a list of probability vectors for each shot of the simulation rather than the a single amplitude vector [Default: False].

  • conditional (bool) – if True save the probability vector conditional on the current classical register values [Default: False].

Returns:

with attached instruction.

Return type:

QuantumCircuit

Raises:

ValueError – if params is invalid for the specified number of qubits.

QuantumCircuit.save_clifford(label='clifford', pershot=False)#

Save the current stabilizer simulator quantum state as a Clifford.

Parameters:

  • label (str) – the key for retrieving saved data from results.

  • pershot (bool) – if True save a list of Cliffords for each shot of the simulation [Default: False].

Returns:

with attached instruction.

Return type:

QuantumCircuit

Note

This instruction is always defined across all qubits in a circuit.

QuantumCircuit.save_density_matrix(qubits=None, label='density_matrix', unnormalized=False, pershot=False, conditional=False)#

Save the current simulator quantum state as a density matrix.

Parameters:

  • qubits (list or None) – the qubits to save reduced density matrix on. If None the full density matrix of qubits will be saved [Default: None].

  • label (str) – the key for retrieving saved data from results.

  • unnormalized (bool) – If True return save the unnormalized accumulated or conditional accumulated density matrix over all shots [Default: False].

  • pershot (bool) – if True save a list of density matrices for each shot of the simulation rather than the average over all shots [Default: False].

  • conditional (bool) – if True save the average or pershot data conditional on the current classical register values [Default: False].

Returns:

with attached instruction.

Return type:

QuantumCircuit

QuantumCircuit.save_expectation_value(operator, qubits, label='expectation_value', unnormalized=False, pershot=False, conditional=False)#

Save the expectation value of a Hermitian operator.

Parameters:

  • operator (Pauli or SparsePauliOp or Operator) – a Hermitian operator.

  • qubits (list) – circuit qubits to apply instruction.

  • label (str) – the key for retrieving saved data from results.

  • unnormalized (bool) – If True return save the unnormalized accumulated or conditional accumulated expectation value over all shot [Default: False].

  • pershot (bool) – if True save a list of expectation values for each shot of the simulation rather than the average over all shots [Default: False].

  • conditional (bool) – if True save the average or pershot data conditional on the current classical register values [Default: False].

Returns:

with attached instruction.

Return type:

QuantumCircuit

Raises:

  • ValueError – if the input operator is not Hermitian.

  • TypeError – if the input operator is of invalid type.

Note

This method appends a SaveExpectationValue instruction to the quantum circuit.

QuantumCircuit.save_expectation_value_variance(operator, qubits, label='expectation_value_variance', unnormalized=False, pershot=False, conditional=False)#

Save the expectation value of a Hermitian operator.

Parameters:

  • operator (Pauli or SparsePauliOp or Operator) – a Hermitian operator.

  • qubits (list) – circuit qubits to apply instruction.

  • label (str) – the key for retrieving saved data from results.

  • unnormalized (bool) – If True return save the unnormalized accumulated or conditional accumulated expectation value and variance over all shot [Default: False].

  • pershot (bool) – if True save a list of expectation values and variances for each shot of the simulation rather than the average over all shots [Default: False].

  • conditional (bool) – if True save the data conditional on the current classical register values [Default: False].

Returns:

with attached instruction.

Return type:

QuantumCircuit

Raises:

  • ValueError – if the input operator is not Hermitian.

  • TypeError – if the input operator is of invalid type.

Note

This method appends a SaveExpectationValueVariance instruction to the quantum circuit.

QuantumCircuit.save_matrix_product_state(label='matrix_product_state', pershot=False, conditional=False)#

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

Parameters:

  • label (str) – the key for retrieving saved data from results.

  • pershot (bool) – if True save the mps for each shot of the simulation [Default: False].

  • conditional (bool) – if True save pershot data conditional on the current classical register values [Default: False].

Returns:

with attached instruction.

Return type:

QuantumCircuit

QuantumCircuit.save_probabilities(qubits=None, label='probabilities', unnormalized=False, pershot=False, conditional=False)#

Save measurement outcome probabilities vector.

Parameters:

  • qubits (list or None) – the qubits to apply snapshot to. If None all qubits will be snapshot [Default: None].

  • label (str) – the key for retrieving saved data from results.

  • unnormalized (bool) – If True return save the unnormalized accumulated probabilities over all shots [Default: False].

  • pershot (bool) – if True save a list of probabilities for each shot of the simulation rather than the average over all shots [Default: False].

  • conditional (bool) – if True save the probabilities data conditional on the current classical register values [Default: False].

Returns:

with attached instruction.

Return type:

QuantumCircuit

QuantumCircuit.save_probabilities_dict(qubits=None, label='probabilities', unnormalized=False, pershot=False, conditional=False)#

Save measurement outcome probabilities vector.

Parameters:

  • qubits (list or None) – the qubits to apply snapshot to. If None all qubits will be snapshot [Default: None].

  • label (str) – the key for retrieving saved data from results.

  • unnormalized (bool) – If True return save the unnormalized accumulated probabilities over all shots [Default: False].

  • pershot (bool) – if True save a list of probabilities for each shot of the simulation rather than the average over all shots [Default: False].

  • conditional (bool) – if True save the probabilities data conditional on the current classical register values [Default: False].

Returns:

with attached instruction.

Return type:

QuantumCircuit

QuantumCircuit.save_stabilizer(label='stabilizer', pershot=False, conditional=False)#

Save the current stabilizer simulator quantum state as a StabilizerState.

Parameters:

  • label (str) – the key for retrieving saved data from results.

  • pershot (bool) – if True save a list of StabilizerStates for each shot of the simulation [Default: False].

  • conditional (bool) – if True save pershot data conditional on the current classical register values [Default: False].

Returns:

with attached instruction.

Return type:

QuantumCircuit

Note

This instruction is always defined across all qubits in a circuit.

QuantumCircuit.save_state(label=None, pershot=False, conditional=False)#

Save the current simulator quantum state.

Parameters:

  • label (str or None) – Optional, the key for retrieving saved data from results. If None the key will be the state type of the simulator.

  • pershot (bool) – if True save a list of statevectors for each shot of the simulation [Default: False].

  • conditional (bool) – if True save pershot data conditional on the current classical register values [Default: False].

Returns:

with attached instruction.

Return type:

QuantumCircuit

QuantumCircuit.save_statevector(label='statevector', pershot=False, conditional=False)#

Save the current simulator quantum state as a statevector.

Parameters:

  • pershot (bool) – if True save a list of statevectors for each shot of the simulation [Default: False].

  • label (str) – the key for retrieving saved data from results.

  • conditional (bool) – if True save pershot data conditional on the current classical register values [Default: False].

Returns:

with attached instruction.

Return type:

QuantumCircuit

Note

This instruction is always defined across all qubits in a circuit.

QuantumCircuit.save_statevector_dict(label='statevector', pershot=False, conditional=False)#

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

Parameters:

  • label (str) – the key for retrieving saved data from results.

  • pershot (bool) – if True save a list of statevectors for each shot of the simulation [Default: False].

  • conditional (bool) – if True save pershot data conditional on the current classical register values [Default: False].

Returns:

with attached instruction.

Return type:

QuantumCircuit

Note

This instruction is always defined across all qubits in a circuit.

QuantumCircuit.save_superop(label='superop', pershot=False)#

Save the current state of the superop simulator.

Parameters:

  • label (str) – the key for retrieving saved data from results.

  • pershot (bool) – if True save a list of SuperOp matrices for each shot of the simulation [Default: False].

Returns:

with attached instruction.

Return type:

QuantumCircuit

Note

This instruction is always defined across all qubits in a circuit.

QuantumCircuit.save_unitary(label='unitary', pershot=False)#

Save the current state of the unitary simulator.

Parameters:

  • label (str) – the key for retrieving saved data from results.

  • pershot (bool) – if True save a list of unitaries for each shot of the simulation [Default: False].

Returns:

with attached instruction.

Return type:

QuantumCircuit

Note

This instruction is always defined across all qubits in a circuit.