105 lines
5.3 KiB
Plaintext
105 lines
5.3 KiB
Plaintext
---
|
||
title: CircuitSampler
|
||
description: API reference for qiskit.opflow.converters.CircuitSampler
|
||
in_page_toc_min_heading_level: 1
|
||
python_api_type: class
|
||
python_api_name: qiskit.opflow.converters.CircuitSampler
|
||
---
|
||
|
||
# CircuitSampler
|
||
|
||
<Class id="qiskit.opflow.converters.CircuitSampler" isDedicatedPage={true} github="https://github.com/qiskit/qiskit/tree/stable/0.18/qiskit/opflow/converters/circuit_sampler.py" signature="CircuitSampler(backend, statevector=None, param_qobj=False, attach_results=False, caching='last')" modifiers="class">
|
||
Bases: `qiskit.opflow.converters.converter_base.ConverterBase`
|
||
|
||
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.
|
||
* **caching** (`str`) – The caching strategy. Can be ‘last’ (default) to store the last operator that was converted, set to ‘all’ to cache all processed operators.
|
||
|
||
**Raises**
|
||
|
||
**ValueError** – Set statevector or param\_qobj True when not supported by backend.
|
||
|
||
## Methods Defined Here
|
||
|
||
### clear\_cache
|
||
|
||
<Function id="qiskit.opflow.converters.CircuitSampler.clear_cache" signature="CircuitSampler.clear_cache()">
|
||
Clear the cache of sampled operator expressions.
|
||
|
||
**Return type**
|
||
|
||
`None`
|
||
</Function>
|
||
|
||
### convert
|
||
|
||
<Function id="qiskit.opflow.converters.CircuitSampler.convert" signature="CircuitSampler.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**
|
||
|
||
[**OpflowError**](qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – if extracted circuits are empty.
|
||
</Function>
|
||
|
||
### sample\_circuits
|
||
|
||
<Function id="qiskit.opflow.converters.CircuitSampler.sample_circuits" signature="CircuitSampler.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`, `float`]]]) – The parameterizations to bind to each CircuitStateFn.
|
||
|
||
**Return type**
|
||
|
||
`Dict`\[`int`, `List`\[`StateFn`]]
|
||
|
||
**Returns**
|
||
|
||
The dictionary mapping ids of the CircuitStateFns to their replacement StateFns.
|
||
|
||
**Raises**
|
||
|
||
[**OpflowError**](qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – if extracted circuits are empty.
|
||
</Function>
|
||
|
||
## Attributes
|
||
|
||
### quantum\_instance
|
||
|
||
<Attribute id="qiskit.opflow.converters.CircuitSampler.quantum_instance">
|
||
Returns the quantum instance.
|
||
|
||
**Return type**
|
||
|
||
`QuantumInstance`
|
||
|
||
**Returns**
|
||
|
||
The QuantumInstance used by the CircuitSampler
|
||
</Attribute>
|
||
</Class>
|
||
|