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 whose set_counter accepts its counter type, 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).

rng is left in a substantially different state than a purely sequential implementation would leave it, in both builds: this function draws from it to derive a base seed and then re-seeds it (and, for a counter-based engine, re-keys it per work item), so it is not merely advanced by the number of values consumed. Callers who continue to draw from the same generator afterwards should not assume any particular number of values was consumed.

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.