149 lines
9.2 KiB
Plaintext
149 lines
9.2 KiB
Plaintext
---
|
||
title: CircuitSampler
|
||
description: API reference for qiskit.aqua.operators.converters.CircuitSampler
|
||
in_page_toc_min_heading_level: 1
|
||
python_api_type: class
|
||
python_api_name: qiskit.aqua.operators.converters.CircuitSampler
|
||
---
|
||
|
||
<span id="qiskit-aqua-operators-converters-circuitsampler" />
|
||
|
||
# qiskit.aqua.operators.converters.CircuitSampler
|
||
|
||
<Class id="qiskit.aqua.operators.converters.CircuitSampler" isDedicatedPage={true} github="https://github.com/qiskit-community/qiskit-aqua/tree/stable/0.8/qiskit/aqua/operators/converters/circuit_sampler.py" signature="CircuitSampler(backend, statevector=None, param_qobj=False, attach_results=False)" modifiers="class">
|
||
The CircuitSampler traverses an Operator and converts any CircuitStateFns into approximations of the state function by a DictStateFn or VectorStateFn using a quantum backend. Note that in order to approximate the value of the CircuitStateFn, it must 1) send state function through a depolarizing channel, which will destroy all phase information and 2) replace the sampled frequencies with **square roots** of the frequency, rather than the raw probability of sampling (which would be the equivalent of sampling the **square** of the state function, per the Born rule.
|
||
|
||
The CircuitSampler aggressively caches transpiled circuits to handle re-parameterization of the same circuit efficiently. If you are converting multiple different Operators, you are better off using a different CircuitSampler for each Operator to avoid cache thrashing.
|
||
|
||
**Parameters**
|
||
|
||
* **backend** (`Union`\[`Backend`, `BaseBackend`, `QuantumInstance`]) – The quantum backend or QuantumInstance to use to sample the circuits.
|
||
* **statevector** (`Optional`\[`bool`]) – If backend is a statevector backend, whether to replace the CircuitStateFns with DictStateFns (from the counts) or VectorStateFns (from the statevector). `None` will set this argument automatically based on the backend.
|
||
* **attach\_results** (`bool`) – Whether to attach the data from the backend `Results` object for a given `` CircuitStateFn` `` to an `execution_results` field added the converted `DictStateFn` or `VectorStateFn`.
|
||
* **param\_qobj** (`bool`) – Whether to use Aer’s parameterized Qobj capability to avoid re-assembling the circuits.
|
||
|
||
**Raises**
|
||
|
||
**ValueError** – Set statevector or param\_qobj True when not supported by backend.
|
||
|
||
### \_\_init\_\_
|
||
|
||
<Function id="qiskit.aqua.operators.converters.CircuitSampler.__init__" signature="__init__(backend, statevector=None, param_qobj=False, attach_results=False)">
|
||
**Parameters**
|
||
|
||
* **backend** (`Union`\[`Backend`, `BaseBackend`, `QuantumInstance`]) – The quantum backend or QuantumInstance to use to sample the circuits.
|
||
* **statevector** (`Optional`\[`bool`]) – If backend is a statevector backend, whether to replace the CircuitStateFns with DictStateFns (from the counts) or VectorStateFns (from the statevector). `None` will set this argument automatically based on the backend.
|
||
* **attach\_results** (`bool`) – Whether to attach the data from the backend `Results` object for a given `` CircuitStateFn` `` to an `execution_results` field added the converted `DictStateFn` or `VectorStateFn`.
|
||
* **param\_qobj** (`bool`) – Whether to use Aer’s parameterized Qobj capability to avoid re-assembling the circuits.
|
||
|
||
**Raises**
|
||
|
||
**ValueError** – Set statevector or param\_qobj True when not supported by backend.
|
||
</Function>
|
||
|
||
## Methods
|
||
|
||
| | |
|
||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
|
||
| [`__init__`](#qiskit.aqua.operators.converters.CircuitSampler.__init__ "qiskit.aqua.operators.converters.CircuitSampler.__init__")(backend\[, statevector, param\_qobj, …]) | **type backend**`Union`\[`Backend`, `BaseBackend`, `QuantumInstance`] |
|
||
| [`convert`](#qiskit.aqua.operators.converters.CircuitSampler.convert "qiskit.aqua.operators.converters.CircuitSampler.convert")(operator\[, params]) | Converts the Operator to one in which the CircuitStateFns are replaced by DictStateFns or VectorStateFns. |
|
||
| [`sample_circuits`](#qiskit.aqua.operators.converters.CircuitSampler.sample_circuits "qiskit.aqua.operators.converters.CircuitSampler.sample_circuits")(\[circuit\_sfns, param\_bindings]) | Samples the CircuitStateFns and returns a dict associating their `id()` values to their replacement DictStateFn or VectorStateFn. |
|
||
| [`set_backend`](#qiskit.aqua.operators.converters.CircuitSampler.set_backend "qiskit.aqua.operators.converters.CircuitSampler.set_backend")(backend, \*\*kwargs) | Sets backend with configuration. |
|
||
|
||
## Attributes
|
||
|
||
| | |
|
||
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
|
||
| [`backend`](#qiskit.aqua.operators.converters.CircuitSampler.backend "qiskit.aqua.operators.converters.CircuitSampler.backend") | Returns the backend. |
|
||
| [`quantum_instance`](#qiskit.aqua.operators.converters.CircuitSampler.quantum_instance "qiskit.aqua.operators.converters.CircuitSampler.quantum_instance") | Returns the quantum instance. |
|
||
|
||
### backend
|
||
|
||
<Attribute id="qiskit.aqua.operators.converters.CircuitSampler.backend">
|
||
Returns the backend.
|
||
|
||
**Return type**
|
||
|
||
`Union`\[`Backend`, `BaseBackend`]
|
||
|
||
**Returns**
|
||
|
||
The backend used by the CircuitSampler
|
||
</Attribute>
|
||
|
||
### convert
|
||
|
||
<Function id="qiskit.aqua.operators.converters.CircuitSampler.convert" signature="convert(operator, params=None)">
|
||
Converts the Operator to one in which the CircuitStateFns are replaced by DictStateFns or VectorStateFns. Extracts the CircuitStateFns out of the Operator, caches them, calls `sample_circuits` below to get their converted replacements, and replaces the CircuitStateFns in operator with the replacement StateFns.
|
||
|
||
**Parameters**
|
||
|
||
* **operator** (`OperatorBase`) – The Operator to convert
|
||
* **params** (`Optional`\[`Dict`\[`Parameter`, `Union`\[`float`, `List`\[`float`], `List`\[`List`\[`float`]]]]]) – A dictionary mapping parameters to either single binding values or lists of binding values.
|
||
|
||
**Return type**
|
||
|
||
`OperatorBase`
|
||
|
||
**Returns**
|
||
|
||
The converted Operator with CircuitStateFns replaced by DictStateFns or VectorStateFns.
|
||
|
||
**Raises**
|
||
|
||
[**AquaError**](qiskit.aqua.AquaError "qiskit.aqua.AquaError") – if extracted circuits are empty.
|
||
</Function>
|
||
|
||
### quantum\_instance
|
||
|
||
<Attribute id="qiskit.aqua.operators.converters.CircuitSampler.quantum_instance">
|
||
Returns the quantum instance.
|
||
|
||
**Return type**
|
||
|
||
`QuantumInstance`
|
||
|
||
**Returns**
|
||
|
||
The QuantumInstance used by the CircuitSampler
|
||
</Attribute>
|
||
|
||
### sample\_circuits
|
||
|
||
<Function id="qiskit.aqua.operators.converters.CircuitSampler.sample_circuits" signature="sample_circuits(circuit_sfns=None, param_bindings=None)">
|
||
Samples the CircuitStateFns and returns a dict associating their `id()` values to their replacement DictStateFn or VectorStateFn. If param\_bindings is provided, the CircuitStateFns are broken into their parameterizations, and a list of StateFns is returned in the dict for each circuit `id()`. Note that param\_bindings is provided here in a different format than in `convert`, and lists of parameters within the dict is not supported, and only binding dicts which are valid to be passed into Terra can be included in this list.
|
||
|
||
**Parameters**
|
||
|
||
* **circuit\_sfns** (`Optional`\[`List`\[`CircuitStateFn`]]) – The list of CircuitStateFns to sample.
|
||
* **param\_bindings** (`Optional`\[`List`\[`Dict`\[`Parameter`, `List`\[`float`]]]]) – The parameterizations to bind to each CircuitStateFn.
|
||
|
||
**Return type**
|
||
|
||
`Dict`\[`int`, `Union`\[`StateFn`, `List`\[`StateFn`]]]
|
||
|
||
**Returns**
|
||
|
||
The dictionary mapping ids of the CircuitStateFns to their replacement StateFns.
|
||
|
||
**Raises**
|
||
|
||
[**AquaError**](qiskit.aqua.AquaError "qiskit.aqua.AquaError") – if extracted circuits are empty.
|
||
</Function>
|
||
|
||
### set\_backend
|
||
|
||
<Function id="qiskit.aqua.operators.converters.CircuitSampler.set_backend" signature="set_backend(backend, **kwargs)">
|
||
Sets backend with configuration.
|
||
|
||
**Raises**
|
||
|
||
**ValueError** – statevector or param\_qobj are True when not supported by backend.
|
||
|
||
**Return type**
|
||
|
||
`None`
|
||
</Function>
|
||
</Class>
|
||
|