thrust::shuffle_iterator

Defined in thrust/iterator/shuffle_iterator.h

template<class IndexType, class BijectionFunc = thrust::detail::random_bijection<IndexType>>
class shuffle_iterator

shuffle_iterator is an iterator which generates a sequence of values representing a random permutation. This iterator is useful for working with random permutations of a range without explicitly storing them in memory. The shuffle iterator is also useful for sampling from a range by selecting only a subset of the elements in the permutation.

The following code snippet demonstrates how to create a shuffle_iterator which generates a random permutation of a vector.

#include <thrust/iterator/shuffle_iterator.h>
...
// create a shuffle iterator
thrust::shuffle_iterator<int> iterator(4, thrust::default_random_engine(0xDEADBEEF));
// iterator[0] returns 1
// iterator[1] returns 3
// iterator[2] returns 2
// iterator[3] returns 0

thrust::device_vector<int> vec = {0, 10, 20, 30};
thrust::device_vector<int> shuffled(4);
thrust::gather(iterator, iterator + 4, vec.begin(), shuffled.begin());
// shuffled returns {10, 30, 20, 0}

This next example demonstrates how to use a shuffle_iterator to randomly sample from a vector.

#include <thrust/iterator/shuffle_iterator.h>
...
// create a shuffle iterator
thrust::shuffle_iterator<int> iterator(100, thrust::default_random_engine(0xDEADBEEF));

// iterator[0] returns 38
// iterator[1] returns 50
// iterator[2] returns 18
// iterator[3] returns 12

// create a vector of size 100
thrust::device_vector<int> vec(100);
thrust::device_vector<int> sample(4);

// fill vec with random values
thrust::sequence(vec.begin(), vec.end(), 100);

// sample 4 random values from vec
thrust::gather(iterator, iterator + 4, vec.begin(), sample.begin());
// sample returns {138, 150, 118, 112}

See also

make_shuffle_iterator

Public Functions

template<class URBG, class Enable = ::cuda::std::enable_if_t<::cuda::std::is_constructible_v<BijectionFunc, IndexType, URBG&&>>>
inline shuffle_iterator(IndexType n, URBG &&g)

Constructs a shuffle_iterator with a given number of elements and a URBG. The parameters will be forwarded to the bijection constructor.

Parameters
  • n – The number of elements in the permutation.

  • g – The URBG used to generate the random permutation. This is only invoked during construction of the shuffle_iterator.

inline shuffle_iterator(BijectionFunc bijection)

Constructs a shuffle_iterator with a given bijection.

Parameters

bijection – The bijection to use.