353 lines
21 KiB
Plaintext
353 lines
21 KiB
Plaintext
---
|
||
title: AerSimulator (v0.29)
|
||
description: API reference for qiskit.providers.aer.AerSimulator in qiskit v0.29
|
||
in_page_toc_min_heading_level: 1
|
||
python_api_type: class
|
||
python_api_name: qiskit.providers.aer.AerSimulator
|
||
---
|
||
|
||
# AerSimulator
|
||
|
||
<Class id="qiskit.providers.aer.AerSimulator" isDedicatedPage={true} github="https://github.com/qiskit/qiskit-aer/tree/stable/0.8/qiskit/providers/aer/backends/aer_simulator.py" signature="AerSimulator(configuration=None, properties=None, provider=None, **backend_options)" modifiers="class">
|
||
Bases: `qiskit.providers.aer.backends.aerbackend.AerBackend`
|
||
|
||
Noisy quantum circuit simulator backend.
|
||
|
||
**Configurable Options**
|
||
|
||
The AerSimulator supports multiple simulation methods and configurable options for each simulation method. These may be set using the appropriate kwargs during initialization. They can also be set of updated using the [`set_options()`](qiskit.providers.aer.AerSimulator#set_options "qiskit.providers.aer.AerSimulator.set_options") method.
|
||
|
||
Run-time options may also be specified as kwargs using the [`run()`](qiskit.providers.aer.AerSimulator#run "qiskit.providers.aer.AerSimulator.run") method. These will not be stored in the backend and will only apply to that execution. They will also override any previously set options.
|
||
|
||
For example, to configure a density matrix simulator with a custom noise model to use for every execution
|
||
|
||
```python
|
||
noise_model = NoiseModel.from_backend(backend)
|
||
backend = AerSimulator(method='density_matrix',
|
||
noise_model=noise_model)
|
||
```
|
||
|
||
**Simulating an IBMQ Backend**
|
||
|
||
The simulator can be automatically configured to mimic an IBMQ backend using the [`from_backend()`](qiskit.providers.aer.AerSimulator#from_backend "qiskit.providers.aer.AerSimulator.from_backend") method. This will configure the simulator to use the basic device `NoiseModel` for that backend, and the same basis gates and coupling map.
|
||
|
||
```python
|
||
backend = AerSimulator.from_backend(backend)
|
||
```
|
||
|
||
**Returning the Final State**
|
||
|
||
The final state of the simulator can be saved to the returned `Result` object by appending the [`save_state()`](qiskit.providers.aer.library.save_state "qiskit.providers.aer.library.save_state") instruction to a quantum circuit. The format of the final state will depend on the simulation method used. Additional simulation data may also be saved using the other save instructions in `qiskit.provider.aer.library`.
|
||
|
||
**Simulation Method Option**
|
||
|
||
The simulation method is set using the `method` kwarg. A list supported simulation methods can be returned using [`available_methods()`](qiskit.providers.aer.AerSimulator#available_methods "qiskit.providers.aer.AerSimulator.available_methods"), these are
|
||
|
||
* `"automatic"`: Default simulation method. Select the simulation method automatically based on the circuit and noise model.
|
||
* `"statevector"`: A dense statevector simulation that can sample measurement outcomes from *ideal* circuits with all measurements at end of the circuit. For noisy simulations each shot samples a randomly sampled noisy circuit from the noise model.
|
||
* `"density_matrix"`: A dense density matrix simulation that may sample measurement outcomes from *noisy* circuits with all measurements at end of the circuit.
|
||
* `"stabilizer"`: An efficient Clifford stabilizer state simulator that can simulate noisy Clifford circuits if all errors in the noise model are also Clifford errors.
|
||
* `"extended_stabilizer"`: An approximate simulated for Clifford + T circuits based on a state decomposition into ranked-stabilizer state. The number of terms grows with the number of non-Clifford (T) gates.
|
||
* `"matrix_product_state"`: A tensor-network statevector simulator that uses a Matrix Product State (MPS) representation for the state. This can be done either with or without truncation of the MPS bond dimensions depending on the simulator options. The default behaviour is no truncation.
|
||
* `"unitary"`: A dense unitary matrix simulation of an ideal circuit. This simulates the unitary matrix of the circuit itself rather than the evolution of an initial quantum state. This method can only simulate gates, it does not support measurement, reset, or noise.
|
||
* `"superop"`: A dense superoperator matrix simulation of an ideal or noisy circuit. This simulates the superoperator matrix of the circuit itself rather than the evolution of an initial quantum state. This method can simulate ideal and noisy gates, and reset, but does not support measurement.
|
||
|
||
**GPU Simulation**
|
||
|
||
By default all simulation methods run on the CPU, however select methods also support running on a GPU if qiskit-aer was installed with GPU support on a compatible NVidia GPU and CUDA version.
|
||
|
||
| Method | GPU Supported |
|
||
| ------------------------- | ------------- |
|
||
| `automatic` | Sometimes |
|
||
| `statevector` | Yes |
|
||
| `density_matrix` | Yes |
|
||
| `stabilizer` | No |
|
||
| “matrix\_product\_state\` | No |
|
||
| `extended_stabilizer` | No |
|
||
| `unitary` | Yes |
|
||
| `superop` | No |
|
||
|
||
Running a GPU simulation is done using `device="GPU"` kwarg during initialization or with [`set_options()`](qiskit.providers.aer.AerSimulator#set_options "qiskit.providers.aer.AerSimulator.set_options"). The list of supported devices for the current system can be returned using [`available_devices()`](qiskit.providers.aer.AerSimulator#available_devices "qiskit.providers.aer.AerSimulator.available_devices").
|
||
|
||
**Additional Backend Options**
|
||
|
||
The following simulator specific backend options are supported
|
||
|
||
* `method` (str): Set the simulation method (Default: `"automatic"`).
|
||
* `device` (str): Set the simulation device (Default: `"CPU"`).
|
||
* `precision` (str): Set the floating point precision for certain simulation methods to either `"single"` or `"double"` precision (default: `"double"`).
|
||
* `zero_threshold` (double): Sets the threshold for truncating small values to zero in the result data (Default: 1e-10).
|
||
* `validation_threshold` (double): Sets the threshold for checking if initial states are valid (Default: 1e-8).
|
||
* `max_parallel_threads` (int): Sets the maximum number of CPU cores used by OpenMP for parallelization. If set to 0 the maximum will be set to the number of CPU cores (Default: 0).
|
||
* `max_parallel_experiments` (int): Sets the maximum number of qobj experiments that may be executed in parallel up to the max\_parallel\_threads value. If set to 1 parallel circuit execution will be disabled. If set to 0 the maximum will be automatically set to max\_parallel\_threads (Default: 1).
|
||
* `max_parallel_shots` (int): Sets the maximum number of shots that may be executed in parallel during each experiment execution, up to the max\_parallel\_threads value. If set to 1 parallel shot execution will be disabled. If set to 0 the maximum will be automatically set to max\_parallel\_threads. Note that this cannot be enabled at the same time as parallel experiment execution (Default: 0).
|
||
* `max_memory_mb` (int): Sets the maximum size of memory to store a state vector. If a state vector needs more, an error is thrown. In general, a state vector of n-qubits uses 2^n complex values (16 Bytes). If set to 0, the maximum will be automatically set to the system memory size (Default: 0).
|
||
* `optimize_ideal_threshold` (int): Sets the qubit threshold for applying circuit optimization passes on ideal circuits. Passes include gate fusion and truncation of unused qubits (Default: 5).
|
||
* `optimize_noise_threshold` (int): Sets the qubit threshold for applying circuit optimization passes on ideal circuits. Passes include gate fusion and truncation of unused qubits (Default: 12).
|
||
|
||
These backend options only apply when using the `"statevector"` simulation method:
|
||
|
||
* `statevector_parallel_threshold` (int): Sets the threshold that the number of qubits must be greater than to enable OpenMP parallelization for matrix multiplication during execution of an experiment. If parallel circuit or shot execution is enabled this will only use unallocated CPU cores up to max\_parallel\_threads. Note that setting this too low can reduce performance (Default: 14).
|
||
* `statevector_sample_measure_opt` (int): Sets the threshold that the number of qubits must be greater than to enable a large qubit optimized implementation of measurement sampling. Note that setting this two low can reduce performance (Default: 10)
|
||
|
||
These backend options only apply when using the `"stabilizer"` simulation method:
|
||
|
||
* `stabilizer_max_snapshot_probabilities` (int): set the maximum qubit number for the \~qiskit.providers.aer.extensions.SnapshotProbabilities instruction (Default: 32).
|
||
|
||
These backend options only apply when using the `"extended_stabilizer"` simulation method:
|
||
|
||
* `extended_stabilizer_sampling_methid` (string): Choose how to simulate measurements on qubits. The performance of the simulator depends significantly on this choice. In the following, let n be the number of qubits in the circuit, m the number of qubits measured, and S be the number of shots. (Default: resampled\_metropolis)
|
||
|
||
* `"metropolis"`: Use a Monte-Carlo method to sample many output strings from the simulator at once. To be accurate, this method requires that all the possible output strings have a non-zero probability. It will give inaccurate results on cases where the circuit has many zero-probability outcomes. This method has an overall runtime that scales as n^\{2} + (S-1)n.
|
||
* `"resampled_metropolis"`: A variant of the metropolis method, where the Monte-Carlo method is reinitialised for every shot. This gives better results for circuits where some outcomes have zero probability, but will still fail if the output distribution is sparse. The overall runtime scales as Sn^\{2}.
|
||
* `"norm_estimation"`: An alternative sampling method using random state inner products to estimate outcome probabilites. This method requires twice as much memory, and significantly longer runtimes, but gives accurate results on circuits with sparse output distributions. The overall runtime scales as Sn^\{3}m^\{3}.
|
||
|
||
* `extended_stabilizer_metropolis_mixing_time` (int): Set how long the monte-carlo method runs before performing measurements. If the output distribution is strongly peaked, this can be decreased alongside setting extended\_stabilizer\_disable\_measurement\_opt to True (Default: 5000).
|
||
|
||
* `"extended_stabilizer_approximation_error"` (double): Set the error in the approximation for the extended\_stabilizer method. A smaller error needs more memory and computational time (Default: 0.05).
|
||
|
||
* `extended_stabilizer_norm_estimation_samples` (int): The default number of samples for the norm estimation sampler. The method will use the default, or 4m^\{2} samples where m is the number of qubits to be measured, whichever is larger (Default: 100).
|
||
|
||
* `extended_stabilizer_norm_estimation_repetitions` (int): The number of times to repeat the norm estimation. The median of these reptitions is used to estimate and sample output strings (Default: 3).
|
||
|
||
* `extended_stabilizer_parallel_threshold` (int): Set the minimum size of the extended stabilizer decomposition before we enable OpenMP parallelization. If parallel circuit or shot execution is enabled this will only use unallocated CPU cores up to max\_parallel\_threads (Default: 100).
|
||
|
||
* `extended_stabilizer_probabilities_snapshot_samples` (int): If using the metropolis or resampled\_metropolis sampling method, set the number of samples used to estimate probabilities in a probabilities snapshot (Default: 3000).
|
||
|
||
These backend options only apply when using the `"matrix_product_state"` simulation method:
|
||
|
||
* `matrix_product_state_max_bond_dimension` (int): Sets a limit on the number of Schmidt coefficients retained at the end of the svd algorithm. Coefficients beyond this limit will be discarded. (Default: None, i.e., no limit on the bond dimension).
|
||
* `matrix_product_state_truncation_threshold` (double): Discard the smallest coefficients for which the sum of their squares is smaller than this threshold. (Default: 1e-16).
|
||
* `mps_sample_measure_algorithm` (str): Choose which algorithm to use for `"sample_measure"`. `"mps_probabilities"` means all state probabilities are computed and measurements are based on them. It is more efficient for a large number of shots, small number of qubits and low entanglement. `"mps_apply_measure"` creates a copy of the mps structure and makes a measurement on it. It is more effients for a small number of shots, high number of qubits, and low entanglement. If the user does not specify the algorithm, a heuristic algorithm is used to select between the two algorithms. (Default: “mps\_heuristic”).
|
||
|
||
These backend options apply in circuit optimization passes:
|
||
|
||
* `fusion_enable` (bool): Enable fusion optimization in circuit optimization passes \[Default: True]
|
||
* `fusion_verbose` (bool): Output gates generated in fusion optimization into metadata \[Default: False]
|
||
* `fusion_max_qubit` (int): Maximum number of qubits for a operation generated in a fusion optimization \[Default: 5]
|
||
* `fusion_threshold` (int): Threshold that number of qubits must be greater than or equal to enable fusion optimization \[Default: 14]
|
||
|
||
Aer class for backends.
|
||
|
||
This method should initialize the module and its configuration, and raise an exception if a component of the module is not available.
|
||
|
||
**Parameters**
|
||
|
||
* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration.
|
||
* **properties** ([*BackendProperties*](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties") *or None*) – Optional, backend properties.
|
||
* **defaults** ([*PulseDefaults*](qiskit.providers.models.PulseDefaults "qiskit.providers.models.PulseDefaults") *or None*) – Optional, backend pulse defaults.
|
||
* **available\_methods** (*list or None*) – Optional, the available simulation methods if backend supports multiple methods.
|
||
* **provider** ([*Provider*](qiskit.providers.Provider "qiskit.providers.Provider")) – Optional, provider responsible for this backend.
|
||
* **backend\_options** (*dict or None*) – Optional set custom backend options.
|
||
|
||
**Raises**
|
||
|
||
[**AerError**](qiskit.providers.aer.AerError "qiskit.providers.aer.AerError") – if there is no name in the configuration
|
||
|
||
## Methods
|
||
|
||
<span id="qiskit-providers-aer-aersimulator-available-devices" />
|
||
|
||
### available\_devices
|
||
|
||
<Function id="qiskit.providers.aer.AerSimulator.available_devices" signature="AerSimulator.available_devices()">
|
||
Return the available simulation methods.
|
||
</Function>
|
||
|
||
<span id="qiskit-providers-aer-aersimulator-available-methods" />
|
||
|
||
### available\_methods
|
||
|
||
<Function id="qiskit.providers.aer.AerSimulator.available_methods" signature="AerSimulator.available_methods()">
|
||
Return the available simulation methods.
|
||
</Function>
|
||
|
||
<span id="qiskit-providers-aer-aersimulator-clear-options" />
|
||
|
||
### clear\_options
|
||
|
||
<Function id="qiskit.providers.aer.AerSimulator.clear_options" signature="AerSimulator.clear_options()">
|
||
Reset the simulator options to default values.
|
||
</Function>
|
||
|
||
<span id="qiskit-providers-aer-aersimulator-configuration" />
|
||
|
||
### configuration
|
||
|
||
<Function id="qiskit.providers.aer.AerSimulator.configuration" signature="AerSimulator.configuration()">
|
||
Return the simulator backend configuration.
|
||
|
||
**Returns**
|
||
|
||
the configuration for the backend.
|
||
|
||
**Return type**
|
||
|
||
[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")
|
||
</Function>
|
||
|
||
<span id="qiskit-providers-aer-aersimulator-defaults" />
|
||
|
||
### defaults
|
||
|
||
<Function id="qiskit.providers.aer.AerSimulator.defaults" signature="AerSimulator.defaults()">
|
||
Return the simulator backend pulse defaults.
|
||
|
||
**Returns**
|
||
|
||
**The backend pulse defaults or `None` if the**
|
||
|
||
backend does not support pulse.
|
||
|
||
**Return type**
|
||
|
||
[PulseDefaults](qiskit.providers.models.PulseDefaults "qiskit.providers.models.PulseDefaults")
|
||
</Function>
|
||
|
||
<span id="qiskit-providers-aer-aersimulator-from-backend" />
|
||
|
||
### from\_backend
|
||
|
||
<Function id="qiskit.providers.aer.AerSimulator.from_backend" signature="AerSimulator.from_backend(backend, **options)" modifiers="classmethod">
|
||
Initialize simulator from backend.
|
||
</Function>
|
||
|
||
<span id="qiskit-providers-aer-aersimulator-name" />
|
||
|
||
### name
|
||
|
||
<Function id="qiskit.providers.aer.AerSimulator.name" signature="AerSimulator.name()">
|
||
Format backend name string for simulator
|
||
</Function>
|
||
|
||
<span id="qiskit-providers-aer-aersimulator-properties" />
|
||
|
||
### properties
|
||
|
||
<Function id="qiskit.providers.aer.AerSimulator.properties" signature="AerSimulator.properties()">
|
||
Return the simulator backend properties if set.
|
||
|
||
**Returns**
|
||
|
||
**The backend properties or `None` if the**
|
||
|
||
backend does not have properties set.
|
||
|
||
**Return type**
|
||
|
||
[BackendProperties](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties")
|
||
</Function>
|
||
|
||
<span id="qiskit-providers-aer-aersimulator-provider" />
|
||
|
||
### provider
|
||
|
||
<Function id="qiskit.providers.aer.AerSimulator.provider" signature="AerSimulator.provider()">
|
||
Return the backend Provider.
|
||
|
||
**Returns**
|
||
|
||
the Provider responsible for the backend.
|
||
|
||
**Return type**
|
||
|
||
[Provider](qiskit.providers.Provider "qiskit.providers.Provider")
|
||
</Function>
|
||
|
||
<span id="qiskit-providers-aer-aersimulator-run" />
|
||
|
||
### run
|
||
|
||
<Function id="qiskit.providers.aer.AerSimulator.run" signature="AerSimulator.run(circuits, backend_options=None, validate=False, **run_options)">
|
||
Run a qobj on the backend.
|
||
|
||
**Parameters**
|
||
|
||
* **circuits** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or list*) – The QuantumCircuit (or list of QuantumCircuit objects) to run
|
||
* **backend\_options** (*dict or None*) – DEPRECATED dictionary of backend options for the execution (default: None).
|
||
* **validate** (*bool*) – validate the Qobj before running (default: False).
|
||
* **run\_options** (*kwargs*) – additional run time backend options.
|
||
|
||
**Returns**
|
||
|
||
The simulation job.
|
||
|
||
**Return type**
|
||
|
||
[AerJob](qiskit.providers.aer.AerJob "qiskit.providers.aer.AerJob")
|
||
|
||
#### Additional Information:
|
||
|
||
* kwarg options specified in `run_options` will temporarily override any set options of the same name for the current run.
|
||
* The entries in the `backend_options` will be combined with the `Qobj.config` dictionary with the values of entries in `backend_options` taking precedence. This kwarg is deprecated and direct kwarg’s should be used for options to pass them to `run_options`.
|
||
</Function>
|
||
|
||
<span id="qiskit-providers-aer-aersimulator-set-option" />
|
||
|
||
### set\_option
|
||
|
||
<Function id="qiskit.providers.aer.AerSimulator.set_option" signature="AerSimulator.set_option(key, value)">
|
||
Special handling for setting backend options.
|
||
|
||
This method should be extended by sub classes to update special option values.
|
||
|
||
**Parameters**
|
||
|
||
* **key** (*str*) – key to update
|
||
* **value** (*any*) – value to update.
|
||
|
||
**Raises**
|
||
|
||
[**AerError**](qiskit.providers.aer.AerError "qiskit.providers.aer.AerError") – if key is ‘method’ and val isn’t in available methods.
|
||
</Function>
|
||
|
||
<span id="qiskit-providers-aer-aersimulator-set-options" />
|
||
|
||
### set\_options
|
||
|
||
<Function id="qiskit.providers.aer.AerSimulator.set_options" signature="AerSimulator.set_options(**fields)">
|
||
Set the options fields for the backend
|
||
|
||
This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options.
|
||
|
||
**Parameters**
|
||
|
||
**fields** – The fields to update the options
|
||
|
||
**Raises**
|
||
|
||
**AttributeError** – If the field passed in is not part of the options
|
||
</Function>
|
||
|
||
<span id="qiskit-providers-aer-aersimulator-status" />
|
||
|
||
### status
|
||
|
||
<Function id="qiskit.providers.aer.AerSimulator.status" signature="AerSimulator.status()">
|
||
Return backend status.
|
||
|
||
**Returns**
|
||
|
||
the status of the backend.
|
||
|
||
**Return type**
|
||
|
||
[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus")
|
||
</Function>
|
||
|
||
## Attributes
|
||
|
||
### options
|
||
|
||
<Attribute id="qiskit.providers.aer.AerSimulator.options">
|
||
Return the options for the backend
|
||
|
||
The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](qiskit.providers.aer.AerSimulator#run "qiskit.providers.aer.AerSimulator.run") method.
|
||
</Attribute>
|
||
|
||
### version
|
||
|
||
<Attribute id="qiskit.providers.aer.AerSimulator.version" attributeValue="1" />
|
||
</Class>
|
||
|