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

# Subsampling

`qiskit_addon_sqd.subsampling`

Functions for creating batches of samples from a bitstring matrix.

### subsample

`subsample(bitstring_matrix, probabilities, samples_per_batch, num_batches, rand_seed=None)`

[GitHub](https://github.com/Qiskit/qiskit-addon-sqd/tree/stable/0.12/qiskit_addon_sqd/subsampling.py#L147-L211)

Subsample batches of bit arrays from an input `bitstring_matrix`.

Each individual batch will be sampled without replacement from the input `bitstring_matrix`. Samples will be replaced after creation of each batch, so different batches may contain identical samples.

**Parameters**

- **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring.
- **probabilities** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)) – A 1D array specifying a probability distribution over the bitstrings
- **samples\_per\_batch** ([*int*](https://docs.python.org/3/library/functions.html#int)) – The number of samples to draw for each batch
- **num\_batches** ([*int*](https://docs.python.org/3/library/functions.html#int)) – The number of batches to generate
- **rand\_seed** ([*Generator*](https://numpy.org/doc/stable/reference/random/generator.html#numpy.random.Generator)  *|*[*int*](https://docs.python.org/3/library/functions.html#int) *| None*) – A seed to control random behavior

**Returns**

A list of bitstring matrices subsampled from the input bitstring matrix.

**Raises**

- [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – The number of elements in `probabilities` must equal the number of rows in `bitstring_matrix`.
- [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – Samples per batch and number of batches must be positive integers.

**Return type**

[list](https://docs.python.org/3/library/stdtypes.html#list)\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)]

### postselect\_and\_subsample

`postselect_and_subsample(bitstring_matrix, probabilities, *, hamming_right, hamming_left, samples_per_batch, num_batches, rand_seed=None)`

[GitHub](https://github.com/Qiskit/qiskit-addon-sqd/tree/stable/0.12/qiskit_addon_sqd/subsampling.py#L24-L93)

Subsample batches of bit arrays with correct hamming weight from an input `bitstring_matrix`.

Bitstring samples with incorrect hamming weight on either their left or right half will not be sampled.

Each individual batch will be sampled without replacement from the input `bitstring_matrix`. Samples will be replaced after creation of each batch, so different batches may contain identical samples.

> **Deprecated since version 0.12.0**
>
> The function `qiskit_addon_sqd.subsampling.postselect_and_subsample()` is deprecated as of qiskit-addon-sqd 0.12.0. It will be removed no earlier than v0.13.0. Instead, use the `postselect_by_hamming_right_and_left` and `subsample` functions.

**Parameters**

- **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring.
- **probabilities** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)) – A 1D array specifying a probability distribution over the bitstrings
- **hamming\_right** ([*int*](https://docs.python.org/3/library/functions.html#int)) – The target hamming weight for the right half of sampled bitstrings
- **hamming\_left** ([*int*](https://docs.python.org/3/library/functions.html#int)) – The target hamming weight for the left half of sampled bitstrings
- **samples\_per\_batch** ([*int*](https://docs.python.org/3/library/functions.html#int)) – The number of samples to draw for each batch
- **num\_batches** ([*int*](https://docs.python.org/3/library/functions.html#int)) – The number of batches to generate
- **rand\_seed** ([*Generator*](https://numpy.org/doc/stable/reference/random/generator.html#numpy.random.Generator)  *|*[*int*](https://docs.python.org/3/library/functions.html#int) *| None*) – A seed to control random behavior

**Returns**

A list of bitstring matrices with correct hamming weight subsampled from the input bitstring matrix

**Raises**

- [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – The number of elements in `probabilities` must equal the number of rows in `bitstring_matrix`.
- [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – Hamming weights must be non-negative integers.
- [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – Samples per batch and number of batches must be positive integers.

**Return type**

[list](https://docs.python.org/3/library/stdtypes.html#list)\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)]

### postselect\_by\_hamming\_right\_and\_left

`postselect_by_hamming_right_and_left(bitstring_matrix, probabilities, *, hamming_right, hamming_left)`

[GitHub](https://github.com/Qiskit/qiskit-addon-sqd/tree/stable/0.12/qiskit_addon_sqd/subsampling.py#L96-L144)

Postselect bitstrings based on desired Hamming weight on right and left halves.

**Parameters**

- **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring.
- **probabilities** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)) – A 1D array specifying a probability distribution over the bitstrings
- **hamming\_right** ([*int*](https://docs.python.org/3/library/functions.html#int)) – The target hamming weight for the right half of sampled bitstrings
- **hamming\_left** ([*int*](https://docs.python.org/3/library/functions.html#int)) – The target hamming weight for the left half of sampled bitstrings

**Returns**

Postselected bitstring matrix and probabilities. The new bitstring matrix contains only those bitstrings from the original matrix that have the desired Hamming weight on the right and left halves, and the new probabilities are constructed by taking the original probabilities corresponding to the postselected bitstrings and rescaling them to sum to one.

**Raises**

- [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – Hamming weights must be non-negative integers.
- [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – The number of columns in `bitstring_matrix` must be even.
- [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – The number of elements in `probabilities` must equal the number of rows in `bitstring_matrix`.

**Return type**

[tuple](https://docs.python.org/3/library/stdtypes.html#tuple)\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray), [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)]