---
title: result (latest version)
description: API reference for qiskit.result in the latest version of qiskit
source: https://eu-de.quantum.cloud.ibm.com/docs/en/api/qiskit/result
---

# Experiment Results

`qiskit.result`

## Core classes

|                                                                                                                       |                                                            |
| --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [`Result`](/docs/api/qiskit/qiskit.result.Result "qiskit.result.Result")(\*\[, backend\_name, backend\_version, ...]) | Model for Results.                                         |
| [`ResultError`](/docs/api/qiskit/qiskit.result.ResultError "qiskit.result.ResultError")(error)                        | Exceptions raised due to errors in result output.          |
| [`Counts`](/docs/api/qiskit/qiskit.result.Counts "qiskit.result.Counts")(data\[, time\_taken, creg\_sizes, ...])      | A class to store a counts result from a circuit execution. |

## Marginalization

### marginal\_counts

`qiskit.result.marginal_counts(result, indices=None, inplace=False, format_marginal=False, marginalize_memory=True)`

[GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/result/utils.py#L33-L99)

Marginalize counts from an experiment over some indices of interest.

**Parameters**

- **result** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict)  *|*[*Result*](/docs/api/qiskit/qiskit.result.Result "qiskit.result.result.Result")) – result to be marginalized (a Result object or a dict(str, int) of counts).
- **indices** ([*list*](https://docs.python.org/3/library/stdtypes.html#list)*\[*[*int*](https://docs.python.org/3/library/functions.html#int)*] | None*) – The bit positions of interest to marginalize over. If `None` (default), do not marginalize at all.
- **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – Default: False. Operates on the original Result argument if True, leading to loss of original Job Result. It has no effect if `result` is a dict.
- **format\_marginal** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – Default: False. If True, takes the output of marginalize and formats it with placeholders between cregs and for non-indices.
- **marginalize\_memory** ([*bool*](https://docs.python.org/3/library/functions.html#bool) *| None*) – If True, then also marginalize the memory field (if present). If False, remove the memory field from the result. If None, leave the memory field as is.

**Returns**

**A Result object or a dictionary with**

the observed counts, marginalized to only account for frequency of observations of bits of interest.

**Return type**

[Result](/docs/api/qiskit/qiskit.result.Result "qiskit.result.Result") or [dict](https://docs.python.org/3/library/stdtypes.html#dict)([str](https://docs.python.org/3/library/stdtypes.html#str), [int](https://docs.python.org/3/library/functions.html#int))

**Raises**

[**QiskitError**](/docs/api/qiskit/exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – in case of invalid indices to marginalize over.

### marginal\_distribution

`qiskit.result.marginal_distribution(counts, indices=None, format_marginal=False)`

[GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/result/utils.py#L199-L243)

Marginalize counts from an experiment over some indices of interest.

Unlike [`marginal_counts()`](#qiskit.result.marginal_counts "qiskit.result.marginal_counts") this function respects the order of the input `indices`. If the input `indices` list is specified then the order the bit indices are specified will be the output order of the bitstrings in the marginalized output.

**Parameters**

- **counts** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict)) – result to be marginalized
- **indices** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)*\[*[*int*](https://docs.python.org/3/library/functions.html#int)*] | None*) – The bit positions of interest to marginalize over. If `None` (default), do not marginalize at all.
- **format\_marginal** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – Default: False. If True, takes the output of marginalize and formats it with placeholders between cregs and for non-indices.

**Returns**

A marginalized dictionary

**Return type**

[dict](https://docs.python.org/3/library/stdtypes.html#dict)([str](https://docs.python.org/3/library/stdtypes.html#str), [int](https://docs.python.org/3/library/functions.html#int))

**Raises**

- [**QiskitError**](/docs/api/qiskit/exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If any value in `indices` is invalid or the `counts` dict
- **is invalid.** –

### marginal\_memory

`qiskit.result.marginal_memory(memory, indices=None, int_return=False, hex_return=False, avg_data=False, parallel_threshold=1000)`

[GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/result/utils.py#L128-L196)

Marginalize shot memory

This function is multithreaded and will launch a thread pool with threads equal to the number of CPUs by default. You can tune the number of threads with the `RAYON_NUM_THREADS` environment variable. For example, setting `RAYON_NUM_THREADS=4` would limit the thread pool to 4 threads.

**Parameters**

- **memory** ([*list*](https://docs.python.org/3/library/stdtypes.html#list)*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str)*] |* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)) – The input memory list, this is either a list of hexadecimal strings to be marginalized representing measure level 2 memory or a numpy array representing level 0 measurement memory (single or avg) or level 1 measurement memory (single or avg).
- **indices** ([*list*](https://docs.python.org/3/library/stdtypes.html#list)*\[*[*int*](https://docs.python.org/3/library/functions.html#int)*] | None*) – The bit positions of interest to marginalize over. If `None` (default), do not marginalize at all.
- **int\_return** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – If set to `True` the output will be a list of integers. By default the return type is a bit string. This and `hex_return` are mutually exclusive and can not be specified at the same time. This option only has an effect with memory level 2.
- **hex\_return** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – If set to `True` the output will be a list of hexadecimal strings. By default the return type is a bit string. This and `int_return` are mutually exclusive and can not be specified at the same time. This option only has an effect with memory level 2.
- **avg\_data** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – If a 2 dimensional numpy array is passed in for `memory` this can be set to `True` to indicate it’s a avg level 0 data instead of level 1 single data.
- **parallel\_threshold** ([*int*](https://docs.python.org/3/library/functions.html#int)) – The number of elements in `memory` to start running in multiple threads. If `len(memory)` is >= this value, the function will run in multiple threads. By default this is set to 1000.

**Returns**

The list of marginalized memory

**Return type**

marginal\_memory

**Raises**

[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – if both `int_return` and `hex_return` are set to `True`

## Distributions

|                                                                                                                                |                                                          |
| ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
| [`ProbDistribution`](/docs/api/qiskit/qiskit.result.ProbDistribution "qiskit.result.ProbDistribution")(data\[, shots])         | A generic dict-like class for probability distributions. |
| [`QuasiDistribution`](/docs/api/qiskit/qiskit.result.QuasiDistribution "qiskit.result.QuasiDistribution")(data\[, shots, ...]) | A dict-like class for representing quasi-probabilities.  |

## Expectation values

### sampled\_expectation\_value

`qiskit.result.sampled_expectation_value(dist, oper)`

[GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/result/sampled_expval.py#L37-L90)

Computes expectation value from a sampled distribution

Note that passing a raw dict requires bit-string keys.

**Parameters**

- **dist** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict)  *|*[*result.Counts*](/docs/api/qiskit/qiskit.result.Counts "qiskit.result.Counts")  *|*[*QuasiDistribution*](/docs/api/qiskit/qiskit.result.QuasiDistribution "qiskit.result.QuasiDistribution")  *|*[*ProbDistribution*](/docs/api/qiskit/qiskit.result.ProbDistribution "qiskit.result.ProbDistribution")) – Input sampled distribution.
- **oper** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)  *|*[*quantum\_info.Pauli*](/docs/api/qiskit/qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli")  *|*[*quantum\_info.SparsePauliOp*](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")  *|*[*quantum\_info.SparseObservable*](/docs/api/qiskit/qiskit.quantum_info.SparseObservable "qiskit.quantum_info.SparseObservable")) – The operator for the observable.

**Returns**

The expectation value.

**Raises**

[**QiskitError**](/docs/api/qiskit/exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input distribution or operator is an invalid type

**Return type**

[float](https://docs.python.org/3/library/functions.html#float)