Go to the first, previous, next, last section, table of contents.
This chapter describes functions for creating and manipulating permutations. A permutation p is represented by an array of n integers in the range 0 .. n-1, where each value p_i occurs once and only once. The application of a permutation p to a vector v yields a new vector v' where v'_i = v_{p_i}. For example, the array (0,1,3,2) represents a permutation which exchanges the last two elements of a four element vector. The corresponding identity permutation is (0,1,2,3).
Note that the permutations produced by the linear algebra routines correspond to the exchange of matrix columns, and so should be considered as applying to row-vectors in the form v' = v P rather than column-vectors, when permuting the elements of a vector.
The functions described in this chapter are defined in the header file 'gsl_permutation.h'.
A permutation is stored by a structure containing two components, the size
of the permutation and a pointer to the permutation array. The elements
of the permutation array are all of type size_t. The
gsl_permutation structure looks like this,
typedef struct
{
size_t size;
size_t * data;
} gsl_permutation;
gsl_permutation_calloc if you want to create a
permutation which is initialized to the identity. A null pointer is
returned if insufficient memory is available to create the permutation.
The following functions can be used to access and manipulate permutations.
GSL_SUCCESS. If no further
permutations are available it returns GSL_FAILURE and leaves
p unmodified. Starting with the identity permutation and
repeatedly applying this function will iterate through all possible
permutations of a given order.
GSL_SUCCESS. If no previous permutation is available it returns
GSL_FAILURE and leaves p unmodified.
The library provides functions for reading and writing permutations to a file as binary data or formatted text.
GSL_EFAILED if there was a problem writing to the file. Since the
data is written in the native binary format it may not be portable
between different architectures.
GSL_EFAILED if there was a problem reading from the file. The
data is assumed to have been written in the native binary format on the
same architecture.
Z represents size_t, so
"%Zu\n" is a suitable format. The function returns
GSL_EFAILED if there was a problem writing to the file.
GSL_EFAILED if there was a problem reading from the file.
A permutation can be represented in both linear and cyclic notations. The functions described in this section can be used to convert between the two forms.
The linear notation is an index mapping, and has already been described above. The cyclic notation represents a permutation as a series of circular rearrangements of groups of elements, or cycles.
Any permutation can be decomposed into a combination of cycles. For example, under the cycle (1 2 3), 1 is replaced by 2, 2 is replaced by 3 and 3 is replaced by 1 in a circular fashion. Cycles of different sets of elements can be combined independently, for example (1 2 3) (4 5) combines the cycle (1 2 3) with the cycle (4 5), which is an exchange of elements 4 and 5. A cycle of length one represents an element which is unchanged by the permutation and is referred to as a singleton.
The cyclic notation for a permutation is not unique, but can be rearranged into a unique canonical form by a reordering of elements. The library uses the canonical form defined in Knuth's Art of Computer Programming (Vol 1, 3rd Ed, 1997) Section 1.3.3, p.178.
The procedure for obtaining the canonical form given by Knuth is,
For example, the linear representation (2 4 3 0 1) is represented as (1 4) (0 2 3) in canonical form. The permutation corresponds to an exchange of elements 1 and 4, and rotation of elements 0, 2 and 3.
The important property of the canonical form is that it can be reconstructed from the contents of each cycle without the brackets. In addition, by removing the brackets it can be considered as a linear representation of a different permutation. In the example given above the permutation (2 4 3 0 1) would become (1 4 0 2 3). This mapping between linear permutations defined by the canonical form has many important uses in the theory of permutations.
The example program below creates a random permutation by shuffling and finds its inverse.
#include <stdio.h>
#include <gsl/gsl_rng.h>
#include <gsl/gsl_randist.h>
#include <gsl/gsl_permutation.h>
int
main (void)
{
const size_t N = 10;
const gsl_rng_type * T;
gsl_rng * r;
gsl_permutation * p = gsl_permutation_alloc (N);
gsl_permutation * q = gsl_permutation_alloc (N);
gsl_rng_env_setup();
T = gsl_rng_default;
r = gsl_rng_alloc (T);
printf ("initial permutation:");
gsl_permutation_init (p);
gsl_permutation_fprintf (stdout, p, " %u");
printf ("\n");
printf (" random permutation:");
gsl_ran_shuffle (r, p->data, N, sizeof(size_t));
gsl_permutation_fprintf (stdout, p, " %u");
printf ("\n");
printf ("inverse permutation:");
gsl_permutation_inverse (q, p);
gsl_permutation_fprintf (stdout, q, " %u");
printf ("\n");
return 0;
}
Here is the output from the program,
bash$ ./a.out initial permutation: 0 1 2 3 4 5 6 7 8 9 random permutation: 1 3 5 2 7 6 0 4 9 8 inverse permutation: 6 0 3 1 7 2 5 4 9 8
The random permutation p[i] and its inverse q[i] are
related through the identity p[q[i]] = i, which can be verified
from the output.
The next example program steps forwards through all possible 3-rd order permutations, starting from the identity,
#include <stdio.h>
#include <gsl/gsl_permutation.h>
int
main (void)
{
gsl_permutation * p = gsl_permutation_alloc (3);
gsl_permutation_init (p);
do
{
gsl_permutation_fprintf (stdout, p, " %u");
printf ("\n");
}
while (gsl_permutation_next(p) == GSL_SUCCESS);
return 0;
}
Here is the output from the program,
bash$ ./a.out 0 1 2 0 2 1 1 0 2 1 2 0 2 0 1 2 1 0
All 6 permutations are generated in lexicographic order. To reverse the
sequence, begin with the final permutation (which is the reverse of the
identity) and replace gsl_permutation_next with
gsl_permutation_prev.
The subject of permutations is covered extensively in Knuth's Sorting and Searching,
For the definition of the canonical form see,
Go to the first, previous, next, last section, table of contents.