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 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.