Package org.apache.commons.rng.sampling

Class PermutationSampler

java.lang.Object

org.apache.commons.rng.sampling.PermutationSampler

All Implemented Interfaces:

ObjectSampler<int[]>, SharedStateObjectSampler<int[]>, SharedStateSampler<SharedStateObjectSampler<int[]>>

public class PermutationSampler
extends Object
implements SharedStateObjectSampler<int[]>

Class for representing permutations of a sequence of integers.

Sampling uses UniformRandomProvider.nextInt(int).

This class also contains utilities for shuffling an int[] array in-place.

Constructor Summary

Constructors

Constructor	Description
PermutationSampler(UniformRandomProvider rng, int n, int k)	Creates a generator of permutations.

Method Summary

Modifier and Type	Method	Description
static int[]	natural(int n)	Creates an array representing the natural number n.
int[]	sample()	Create a sample.
static void	shuffle(UniformRandomProvider rng, int[] list)	Shuffles the entries of the given array.
static void	shuffle(UniformRandomProvider rng, int[] list, int start, boolean towardHead)	Shuffles the entries of the given array, using the Fisher-Yates algorithm.
PermutationSampler	withUniformRandomProvider(UniformRandomProvider rng)	Create a new instance of the sampler with the same underlying state using the given uniform random provider as the source of randomness.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PermutationSampler

public PermutationSampler(UniformRandomProvider rng,
                          int n,
                          int k)

Creates a generator of permutations.

The sample() method will generate an integer array of length k whose entries are selected randomly, without repetition, from the integers 0, 1, ..., n-1 (inclusive). The returned array represents a permutation of n taken k.

Parameters:

rng - Generator of uniformly distributed random numbers.

n - Domain of the permutation.

k - Size of the permutation.

Throws:

IllegalArgumentException - if n <= 0 or k <= 0 or k > n.

Method Detail

sample

public int[] sample()

Description copied from interface: ObjectSampler

Create a sample.

Specified by:

sample in interface ObjectSampler<int[]>

Returns:

a random permutation.

See Also:

PermutationSampler(UniformRandomProvider,int,int)

withUniformRandomProvider

public PermutationSampler withUniformRandomProvider(UniformRandomProvider rng)

Create a new instance of the sampler with the same underlying state using the given uniform random provider as the source of randomness.

Specified by:

withUniformRandomProvider in interface SharedStateSampler<SharedStateObjectSampler<int[]>>

Parameters:

rng - Generator of uniformly distributed random numbers.

Returns:

the sampler

Since:

1.3

shuffle

public static void shuffle(UniformRandomProvider rng,
                           int[] list)

Shuffles the entries of the given array.

Parameters:

rng - Random number generator.

list - Array whose entries will be shuffled (in-place).

See Also:

shuffle(UniformRandomProvider,int[],int,boolean)

shuffle

public static void shuffle(UniformRandomProvider rng,
                           int[] list,
                           int start,
                           boolean towardHead)

Shuffles the entries of the given array, using the Fisher-Yates algorithm. The start and towardHead parameters select which part of the array is randomized and which is left untouched.

Sampling uses UniformRandomProvider.nextInt(int).

Parameters:

rng - Random number generator.

list - Array whose entries will be shuffled (in-place).

start - Index at which shuffling begins.

towardHead - Shuffling is performed for index positions between start and either the end (if false) or the beginning (if true) of the array.

natural

public static int[] natural(int n)

Creates an array representing the natural number n.

Parameters:

n - Natural number.

Returns:

an array whose entries are the numbers 0, 1, ..., n-1. If n == 0, the returned array is empty.