Configuration recovery

Functions

This library provides a single public function for performing configuration recovery.

template<typename BitstringVectorType, typename WeightVectorType, std::uniform_random_bit_generator RNGType>
std::pair<BitstringVectorType, WeightVectorType> Qiskit::addon::sqd::recover_configurations(const BitstringVectorType &bitstrings, const WeightVectorType &probabilities, const std::array<std::vector<double>, 2> &avg_occupancies, std::array<std::uint64_t, 2> num_elec, RNGType &rng)

Refine bitstrings based on average orbital occupancy and a target Hamming weight.

When compiled with OpenMP enabled, the per-bitstring correction runs in parallel. In that case rng is used to seed independent per-work-item random streams rather than being drawn from sequentially, so the numerical output differs from a purely sequential run. The degree of reproducibility depends on the generator:

  • A counter-based engine (one with set_counter, such as the C++26 std::philox_engine) is keyed by bitstring index, so the result – including the order of the returned vectors – is identical for any number of threads.

  • Any other engine must be seedable (have seed()); each thread then uses an independently seeded copy. Results are valid but depend on the thread count. A generator that is neither counter-based nor seedable is rejected at compile time under OpenMP (it remains usable in a serial build).

Parameters:

  • bitstrings – [in] A container (e.g., std::vector) of bitstrings.

  • probabilities – [in] A 1D array specifying a probability distribution over the bitstrings. Must contain the same number of elements as bitstrings.

  • avg_occupancies – [in] Size-2 std::array of std::vector<double>s holding the mean occupancy of the spin-up and spin-down orbitals, respectively. Each vector’s size must be half the size of a single bitstring.

  • num_elec – [in] Size-2 std::array containing the number of spin-up and spin-down electrons in the system, respectively.

  • rng – [inout] Random number generator.

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:

A refined std::vector of unique bitstrings and a parallel, updated probability array.