Subsampling

Functions

This library provides functions for subsampling either a single batch or multiple batches from a pool of bitstrings.

template<typename BitstringVectorType, typename WeightVectorType, std::uniform_random_bit_generator RNGType>
BitstringVectorType Qiskit::addon::sqd::subsample(const BitstringVectorType &bitstrings, const WeightVectorType &weights, unsigned int samples_per_batch, RNGType &rng)

Subsample a single batch of bitstrings.

Note: You must de-duplicate the bitstrings before calling this, otherwise you may get duplicate bitstrings in the output.

Parameters:

  • bitstrings – [in] Population of bitstrings.

  • weights – [in] Relative weight of each bitstring (need not be normalized to 1). Must be the same length as bitstrings and contain only non-negative values.

  • samples_per_batch – [in] Number of samples to return in batch. Cannot be greater than the number of bitstrings.

  • rng – [inout] Random number generator to use for sampling.

Template Parameters:

  • BitstringVectorType – Type of bitstrings, compatible with std::vector<boost::dynamic_bitset<>>.

  • WeightVectorType – Type of weights, compatible with std::vector<double>.

  • RNGType – Type of random number generator.

Returns:

The subsampled bitstrings.

template<typename BatchVectorType, typename BitstringVectorType, typename WeightVectorType, std::uniform_random_bit_generator RNGType>
void Qiskit::addon::sqd::subsample(BatchVectorType &batch, const BitstringVectorType &bitstrings, const WeightVectorType &weights, unsigned int samples_per_batch, RNGType &rng)

Subsample a single batch of bitstrings (mutating version)

This version can be useful if you want to avoid reallocation by re-using an existing batch vector.

Note: You must de-duplicate the bitstrings before calling this, otherwise you may get duplicate bitstrings in the output.

Parameters:

  • batch – [out] This will be cleared and overwritten with the subsampled bitstrings.

  • bitstrings – [in] Population of bitstrings.

  • weights – [in] Relative weight of each bitstring (need not be normalized to 1). Must be the same length as bitstrings and contain only non-negative values.

  • samples_per_batch – [in] Number of samples to return in batch. Cannot be greater than the number of bitstrings.

  • rng – [inout] Random number generator to use for sampling.

Template Parameters:

  • BatchVectorType – Type of batch, must be compatible with std::vector<boost::dynamic_bitset<>>.

  • BitstringVectorType – Type of bitstrings, compatible with std::vector<boost::dynamic_bitset<>>.

  • WeightVectorType – Type of weights, compatible with std::vector<double>.

  • RNGType – Type of random number generator.

template<typename BitstringVectorType, typename WeightVectorType, std::uniform_random_bit_generator RNGType>
std::vector<BitstringVectorType> Qiskit::addon::sqd::subsample_multiple_batches(const BitstringVectorType &bitstrings, const WeightVectorType &weights, unsigned int samples_per_batch, unsigned int num_batches, RNGType &rng)

Subsample multiple batches of bitstrings.

Note: You must de-duplicate the bitstrings before calling this, otherwise you may get duplicate bitstrings in the output.

Parameters:

  • bitstrings – [in] Population of bitstrings.

  • weights – [in] Relative weight of each bitstring (need not be normalized to 1). Must be the same length as bitstrings and contain only non-negative values.

  • samples_per_batch – [in] Number of samples to return per batch. Cannot be greater than the number of bitstrings.

  • num_batches – [in] Number of batches.

  • rng – [inout] Random number generator to use for sampling.

Template Parameters:

  • BitstringVectorType – Type of bitstrings, compatible with std::vector<boost::dynamic_bitset<>>.

  • WeightVectorType – Type of weights, compatible with std::vector<double>.

  • RNGType – Type of random number generator.

Returns:

The batches of subsampled bitstrings.

template<typename BatchesVectorType, typename BitstringVectorType, typename WeightVectorType, std::uniform_random_bit_generator RNGType>
void Qiskit::addon::sqd::subsample_multiple_batches(BatchesVectorType &batches, const BitstringVectorType &bitstrings, const WeightVectorType &weights, unsigned int samples_per_batch, unsigned int num_batches, RNGType &rng)

Subsample multiple batches of bitstrings (mutating version)

This version can be useful if you want to avoid reallocation by re-using existing batch vectors.

Note: You must de-duplicate the bitstrings before calling this, otherwise you may get duplicate bitstrings in the output.

Parameters:

  • batches – [out] This will be overwritten with the batches of subsampled bitstrings.

  • bitstrings – [in] Population of bitstrings.

  • weights – [in] Relative weight of each bitstring (need not be normalized to 1). Must be the same length as bitstrings and contain only non-negative values.

  • samples_per_batch – [in] Number of samples to return per batch. Cannot be greater than the number of bitstrings.

  • num_batches – [in] Number of batches.

  • rng – [inout] Random number generator to use for sampling.

Template Parameters:

  • BatchesVectorType – Type of batches, must be compatible with std::vector<std::vector<boost::dynamic_bitset<>>>.

  • BitstringVectorType – Type of bitstrings, compatible with std::vector<boost::dynamic_bitset<>>.

  • WeightVectorType – Type of weights, compatible with std::vector<double>.

  • RNGType – Type of random number generator.