Package org.apache.commons.rng.sampling

Class PermutationSampler

java.lang.Object

org.apache.commons.rng.sampling.PermutationSampler

public class PermutationSampler
extends java.lang.Object

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()
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.

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:

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

Method Detail

sample

public int[] sample()

Returns:

a random permutation.

See Also:

PermutationSampler(UniformRandomProvider,int,int)

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.