Subsampling (qiskit_addon_sqd.subsampling)

Functions for creating batches of samples from a bitstring matrix.

subsample(bitstring_matrix, probabilities, samples_per_batch, num_batches, rand_seed=None)[source]

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) – A 2D array of bool representations of bit values such that each row represents a single bitstring.

  • probabilities (ndarray) – A 1D array specifying a probability distribution over the bitstrings

  • samples_per_batch (int) – The number of samples to draw for each batch

  • num_batches (int) – The number of batches to generate

  • rand_seed (Generator | int | None) – A seed to control random behavior

Returns:

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

Raises:

  • ValueError – The number of elements in probabilities must equal the number of rows in bitstring_matrix.

  • ValueError – Samples per batch and number of batches must be positive integers.

Return type:

list[ndarray]

partition_subsample(bitstring_matrix, probabilities, samples_per_batch, num_batches, rand_seed=None)[source]

Partition a subsampled pool of bit arrays into disjoint batches.

Unlike subsample(), which draws each batch independently, this function draws a single pool of samples_per_batch * num_batches bitstrings without replacement and divides it among the batches, so that no bitstring appears in more than one batch.

This is intended for use with a solver that screens the batches against one another and merges what they retain, such as TrimPolicy. Independently drawn batches overlap heavily, because the high-probability bitstrings are likely to be drawn into every batch. That both shrinks the pool of distinct candidates below samples_per_batch * num_batches and biases the screening, since a bitstring appearing in several batches gets several chances to survive. Disjoint batches give every candidate exactly one chance, and make the pool of distinct candidates as large as the batches can hold.

The pool is filled by weighted draw without replacement, then shuffled and dealt round-robin among the batches, so a batch is a uniformly random subset of the pool rather than a slice of it by probability.

If the input holds fewer than samples_per_batch * num_batches bitstrings, the whole input is used as the pool and the batches come out correspondingly smaller.

Note

What this makes disjoint is the bitstrings, and hence the configurations. The CI string arrays derived from them, one per spin sector, may still share strings between batches, since two different configurations can agree on one of their halves. Partitioning the per-spin arrays instead is a different scheme, with different consequences for how the requested and carryover strings are distributed, and is not what this function does.

Parameters:

  • bitstring_matrix (ndarray) – A 2D array of bool representations of bit values such that each row represents a single bitstring.

  • probabilities (ndarray) – A 1D array specifying a probability distribution over the bitstrings

  • samples_per_batch (int) – The number of samples in each batch

  • num_batches (int) – The number of batches to generate

  • rand_seed (Generator | int | None) – A seed to control random behavior

Returns:

A list of bitstring matrices, pairwise disjoint, subsampled from the input bitstring matrix.

Raises:

  • ValueError – The number of elements in probabilities must equal the number of rows in bitstring_matrix.

  • ValueError – Samples per batch and number of batches must be positive integers.

Return type:

list[ndarray]

postselect_and_subsample(bitstring_matrix, probabilities, *, hamming_right, hamming_left, samples_per_batch, num_batches, rand_seed=None)[source]

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) – A 2D array of bool representations of bit values such that each row represents a single bitstring.

  • probabilities (ndarray) – A 1D array specifying a probability distribution over the bitstrings

  • hamming_right (int) – The target hamming weight for the right half of sampled bitstrings

  • hamming_left (int) – The target hamming weight for the left half of sampled bitstrings

  • samples_per_batch (int) – The number of samples to draw for each batch

  • num_batches (int) – The number of batches to generate

  • rand_seed (Generator | 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 – The number of elements in probabilities must equal the number of rows in bitstring_matrix.

  • ValueError – Hamming weights must be non-negative integers.

  • ValueError – Samples per batch and number of batches must be positive integers.

Return type:

list[ndarray]

postselect_by_hamming_right_and_left(bitstring_matrix, probabilities, *, hamming_right, hamming_left)[source]

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

Parameters:

  • bitstring_matrix (ndarray) – A 2D array of bool representations of bit values such that each row represents a single bitstring.

  • probabilities (ndarray) – A 1D array specifying a probability distribution over the bitstrings

  • hamming_right (int) – The target hamming weight for the right half of sampled bitstrings

  • hamming_left (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 – Hamming weights must be non-negative integers.

  • ValueError – The number of columns in bitstring_matrix must be even.

  • ValueError – The number of elements in probabilities must equal the number of rows in bitstring_matrix.

Return type:

tuple[ndarray, ndarray]