~ubuntu-branches/ubuntu/dapper/gsl-ref-html/dapper : contents of gsl-ref

~ubuntu-branches/ubuntu/dapper/gsl-ref-html/dapper : (revision 4)
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.54+ (gsl)
     from /home/bjg/gsl.redhat/doc/gsl-ref.texi on 14 September 2005 -->

<TITLE>GNU Scientific Library -- Reference Manual - Permutations</TITLE>
<link href="gsl-ref_10.html" rel=Next>
<link href="gsl-ref_8.html" rel=Previous>
<link href="gsl-ref_toc.html" rel=ToC>

</HEAD>
<BODY>
<p>Go to the <A HREF="gsl-ref_1.html">first</A>, <A HREF="gsl-ref_8.html">previous</A>, <A HREF="gsl-ref_10.html">next</A>, <A HREF="gsl-ref_50.html">last</A> section, <A HREF="gsl-ref_toc.html">table of contents</A>.
<P><HR><P>


<H1><A NAME="SEC188" HREF="gsl-ref_toc.html#TOC188">Permutations</A></H1>
<P>
<A NAME="IDX949"></A>

</P>
<P>
This chapter describes functions for creating and manipulating
permutations. A permutation p is represented by an array of
n integers in the range 0 to 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).   

</P>
<P>
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.

</P>
<P>
The functions described in this chapter are defined in the header file
<TT>`gsl_permutation.h'</TT>.

</P>



<H2><A NAME="SEC189" HREF="gsl-ref_toc.html#TOC189">The Permutation struct</A></H2>

<P>
A permutation is defined 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 <CODE>size_t</CODE>.  The
<CODE>gsl_permutation</CODE> structure looks like this,

</P>

<PRE>
typedef struct
{
  size_t size;
  size_t * data;
} gsl_permutation;
</PRE>

<P>

</P>


<H2><A NAME="SEC190" HREF="gsl-ref_toc.html#TOC190">Permutation allocation</A></H2>

<P>
<DL>
<DT><U>Function:</U> gsl_permutation * <B>gsl_permutation_alloc</B> <I>(size_t <VAR>n</VAR>)</I>
<DD><A NAME="IDX950"></A>
This function allocates memory for a new permutation of size <VAR>n</VAR>.
The permutation is not initialized and its elements are undefined.  Use
the function <CODE>gsl_permutation_calloc</CODE> 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.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> gsl_permutation * <B>gsl_permutation_calloc</B> <I>(size_t <VAR>n</VAR>)</I>
<DD><A NAME="IDX951"></A>
This function allocates memory for a new permutation of size <VAR>n</VAR> and
initializes it to the identity. A null pointer is returned if
insufficient memory is available to create the permutation.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gsl_permutation_init</B> <I>(gsl_permutation * <VAR>p</VAR>)</I>
<DD><A NAME="IDX952"></A>
<A NAME="IDX953"></A>
This function initializes the permutation <VAR>p</VAR> to the identity, i.e.
(0,1,2,...,n-1).
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gsl_permutation_free</B> <I>(gsl_permutation * <VAR>p</VAR>)</I>
<DD><A NAME="IDX954"></A>
This function frees all the memory used by the permutation <VAR>p</VAR>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_permutation_memcpy</B> <I>(gsl_permutation * <VAR>dest</VAR>, const gsl_permutation * <VAR>src</VAR>)</I>
<DD><A NAME="IDX955"></A>
This function copies the elements of the permutation <VAR>src</VAR> into the
permutation <VAR>dest</VAR>.  The two permutations must have the same size.
</DL>

</P>


<H2><A NAME="SEC191" HREF="gsl-ref_toc.html#TOC191">Accessing permutation elements</A></H2>

<P>
The following functions can be used to access and manipulate
permutations.

</P>
<P>
<DL>
<DT><U>Function:</U> size_t <B>gsl_permutation_get</B> <I>(const gsl_permutation * <VAR>p</VAR>, const size_t <VAR>i</VAR>)</I>
<DD><A NAME="IDX956"></A>
This function returns the value of the <VAR>i</VAR>-th element of the
permutation <VAR>p</VAR>.  If <VAR>i</VAR> lies outside the allowed range of 0 to
<VAR>n</VAR>-1 then the error handler is invoked and 0 is returned.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_permutation_swap</B> <I>(gsl_permutation * <VAR>p</VAR>, const size_t <VAR>i</VAR>, const size_t <VAR>j</VAR>)</I>
<DD><A NAME="IDX957"></A>
<A NAME="IDX958"></A>
<A NAME="IDX959"></A>
This function exchanges the <VAR>i</VAR>-th and <VAR>j</VAR>-th elements of the
permutation <VAR>p</VAR>.
</DL>

</P>


<H2><A NAME="SEC192" HREF="gsl-ref_toc.html#TOC192">Permutation properties</A></H2>

<P>
<DL>
<DT><U>Function:</U> size_t <B>gsl_permutation_size</B> <I>(const gsl_permutation * <VAR>p</VAR>)</I>
<DD><A NAME="IDX960"></A>
This function returns the size of the permutation <VAR>p</VAR>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> size_t * <B>gsl_permutation_data</B> <I>(const gsl_permutation * <VAR>p</VAR>)</I>
<DD><A NAME="IDX961"></A>
This function returns a pointer to the array of elements in the
permutation <VAR>p</VAR>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_permutation_valid</B> <I>(gsl_permutation * <VAR>p</VAR>)</I>
<DD><A NAME="IDX962"></A>
<A NAME="IDX963"></A>
<A NAME="IDX964"></A>
This function checks that the permutation <VAR>p</VAR> is valid.  The <VAR>n</VAR>
elements should contain each of the numbers 0 to <VAR>n</VAR>-1 once and only
once.
</DL>

</P>


<H2><A NAME="SEC193" HREF="gsl-ref_toc.html#TOC193">Permutation functions</A></H2>

<P>
<DL>
<DT><U>Function:</U> void <B>gsl_permutation_reverse</B> <I>(gsl_permutation * <VAR>p</VAR>)</I>
<DD><A NAME="IDX965"></A>
<A NAME="IDX966"></A>
This function reverses the elements of the permutation <VAR>p</VAR>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_permutation_inverse</B> <I>(gsl_permutation * <VAR>inv</VAR>, const gsl_permutation * <VAR>p</VAR>)</I>
<DD><A NAME="IDX967"></A>
<A NAME="IDX968"></A>
This function computes the inverse of the permutation <VAR>p</VAR>, storing
the result in <VAR>inv</VAR>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_permutation_next</B> <I>(gsl_permutation * <VAR>p</VAR>)</I>
<DD><A NAME="IDX969"></A>
<A NAME="IDX970"></A>
This function advances the permutation <VAR>p</VAR> to the next permutation
in lexicographic order and returns <CODE>GSL_SUCCESS</CODE>.  If no further
permutations are available it returns <CODE>GSL_FAILURE</CODE> and leaves
<VAR>p</VAR> unmodified.  Starting with the identity permutation and
repeatedly applying this function will iterate through all possible
permutations of a given order.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_permutation_prev</B> <I>(gsl_permutation * <VAR>p</VAR>)</I>
<DD><A NAME="IDX971"></A>
This function steps backwards from the permutation <VAR>p</VAR> to the
previous permutation in lexicographic order, returning
<CODE>GSL_SUCCESS</CODE>.  If no previous permutation is available it returns
<CODE>GSL_FAILURE</CODE> and leaves <VAR>p</VAR> unmodified.
</DL>

</P>


<H2><A NAME="SEC194" HREF="gsl-ref_toc.html#TOC194">Applying Permutations</A></H2>

<P>
<DL>
<DT><U>Function:</U> int <B>gsl_permute</B> <I>(const size_t * <VAR>p</VAR>, double * <VAR>data</VAR>, size_t <VAR>stride</VAR>, size_t <VAR>n</VAR>)</I>
<DD><A NAME="IDX972"></A>
This function applies the permutation <VAR>p</VAR> to the array <VAR>data</VAR> of
size <VAR>n</VAR> with stride <VAR>stride</VAR>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_permute_inverse</B> <I>(const size_t * <VAR>p</VAR>, double * <VAR>data</VAR>, size_t <VAR>stride</VAR>, size_t <VAR>n</VAR>)</I>
<DD><A NAME="IDX973"></A>
This function applies the inverse of the permutation <VAR>p</VAR> to the
array <VAR>data</VAR> of size <VAR>n</VAR> with stride <VAR>stride</VAR>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_permute_vector</B> <I>(const gsl_permutation * <VAR>p</VAR>, gsl_vector * <VAR>v</VAR>)</I>
<DD><A NAME="IDX974"></A>
This function applies the permutation <VAR>p</VAR> to the elements of the
vector <VAR>v</VAR>, considered as a row-vector acted on by a permutation
matrix from the right, v' = v P.  The j-th column of the
permutation matrix P is given by the p_j-th column of the
identity matrix. The permutation <VAR>p</VAR> and the vector <VAR>v</VAR> must
have the same length.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_permute_vector_inverse</B> <I>(const gsl_permutation * <VAR>p</VAR>, gsl_vector * <VAR>v</VAR>)</I>
<DD><A NAME="IDX975"></A>
This function applies the inverse of the permutation <VAR>p</VAR> to the
elements of the vector <VAR>v</VAR>, considered as a row-vector acted on by
an inverse permutation matrix from the right, v' = v P^T.  Note
that for permutation matrices the inverse is the same as the transpose.
The j-th column of the permutation matrix P is given by
the p_j-th column of the identity matrix. The permutation <VAR>p</VAR>
and the vector <VAR>v</VAR> must have the same length.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_permutation_mul</B> <I>(gsl_permutation * <VAR>p</VAR>, const gsl_permutation * <VAR>pa</VAR>, const gsl_permutation * <VAR>pb</VAR>)</I>
<DD><A NAME="IDX976"></A>
This function combines the two permutations <VAR>pa</VAR> and <VAR>pb</VAR> into a
single permutation <VAR>p</VAR>, where p = pa . pb. The permutation
<VAR>p</VAR> is equivalent to applying pb first and then <VAR>pa</VAR>.
</DL>

</P>


<H2><A NAME="SEC195" HREF="gsl-ref_toc.html#TOC195">Reading and writing permutations</A></H2>

<P>
The library provides functions for reading and writing permutations to a
file as binary data or formatted text.

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_permutation_fwrite</B> <I>(FILE * <VAR>stream</VAR>, const gsl_permutation * <VAR>p</VAR>)</I>
<DD><A NAME="IDX977"></A>
This function writes the elements of the permutation <VAR>p</VAR> to the
stream <VAR>stream</VAR> in binary format.  The function returns
<CODE>GSL_EFAILED</CODE> 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.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_permutation_fread</B> <I>(FILE * <VAR>stream</VAR>, gsl_permutation * <VAR>p</VAR>)</I>
<DD><A NAME="IDX978"></A>
This function reads into the permutation <VAR>p</VAR> from the open stream
<VAR>stream</VAR> in binary format.  The permutation <VAR>p</VAR> must be
preallocated with the correct length since the function uses the size of
<VAR>p</VAR> to determine how many bytes to read.  The function returns
<CODE>GSL_EFAILED</CODE> 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.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_permutation_fprintf</B> <I>(FILE * <VAR>stream</VAR>, const gsl_permutation * <VAR>p</VAR>, const char * <VAR>format</VAR>)</I>
<DD><A NAME="IDX979"></A>
This function writes the elements of the permutation <VAR>p</VAR>
line-by-line to the stream <VAR>stream</VAR> using the format specifier
<VAR>format</VAR>, which should be suitable for a type of <VAR>size_t</VAR>.  On a
GNU system the type modifier <CODE>Z</CODE> represents <CODE>size_t</CODE>, so
<CODE>"%Zu\n"</CODE> is a suitable format.  The function returns
<CODE>GSL_EFAILED</CODE> if there was a problem writing to the file.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_permutation_fscanf</B> <I>(FILE * <VAR>stream</VAR>, gsl_permutation * <VAR>p</VAR>)</I>
<DD><A NAME="IDX980"></A>
This function reads formatted data from the stream <VAR>stream</VAR> into the
permutation <VAR>p</VAR>.  The permutation <VAR>p</VAR> must be preallocated with
the correct length since the function uses the size of <VAR>p</VAR> to
determine how many numbers to read.  The function returns
<CODE>GSL_EFAILED</CODE> if there was a problem reading from the file.
</DL>

</P>


<H2><A NAME="SEC196" HREF="gsl-ref_toc.html#TOC196">Permutations in cyclic form</A></H2>

<P>
A permutation can be represented in both <I>linear</I> and <I>cyclic</I>
notations.  The functions described in this section convert between the
two forms.  The linear notation is an index mapping, and has already
been described above.  The cyclic notation expresses a permutation as a
series of circular rearrangements of groups of elements, or
<I>cycles</I>.

</P>
<P>
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 <I>singleton</I>.

</P>
<P>
It can be shown that every permutation can be decomposed into
combinations of cycles.  The decomposition is not unique, but can always
be rearranged into a standard <I>canonical form</I> by a reordering of
elements.  The library uses the canonical form defined in Knuth's
<CITE>Art of Computer Programming</CITE> (Vol 1, 3rd Ed, 1997) Section 1.3.3,
p.178.

</P>
<P>
The procedure for obtaining the canonical form given by Knuth is,

</P>

<OL>
<LI>Write all singleton cycles explicitly

<LI>Within each cycle, put the smallest number first

<LI>Order the cycles in decreasing order of the first number in the cycle.

</OL>

<P>
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.

</P>
<P>
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 has
many applications in the theory of permutations.

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_permutation_linear_to_canonical</B> <I>(gsl_permutation * <VAR>q</VAR>, const gsl_permutation * <VAR>p</VAR>)</I>
<DD><A NAME="IDX981"></A>
This function computes the canonical form of the permutation <VAR>p</VAR> and
stores it in the output argument <VAR>q</VAR>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_permutation_canonical_to_linear</B> <I>(gsl_permutation * <VAR>p</VAR>, const gsl_permutation * <VAR>q</VAR>)</I>
<DD><A NAME="IDX982"></A>
This function converts a permutation <VAR>q</VAR> in canonical form back into
linear form storing it in the output argument <VAR>p</VAR>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> size_t <B>gsl_permutation_inversions</B> <I>(const gsl_permutation * <VAR>p</VAR>)</I>
<DD><A NAME="IDX983"></A>
This function counts the number of inversions in the permutation
<VAR>p</VAR>.  An inversion is any pair of elements that are not in order.
For example, the permutation 2031 has three inversions, corresponding to
the pairs (2,0) (2,1) and (3,1).  The identity permutation has no
inversions.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> size_t <B>gsl_permutation_linear_cycles</B> <I>(const gsl_permutation * <VAR>p</VAR>)</I>
<DD><A NAME="IDX984"></A>
This function counts the number of cycles in the permutation <VAR>p</VAR>, given in linear form.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> size_t <B>gsl_permutation_canonical_cycles</B> <I>(const gsl_permutation * <VAR>q</VAR>)</I>
<DD><A NAME="IDX985"></A>
This function counts the number of cycles in the permutation <VAR>q</VAR>, given in canonical form.
</DL>

</P>



<H2><A NAME="SEC197" HREF="gsl-ref_toc.html#TOC197">Examples</A></H2>
<P>
The example program below creates a random permutation (by shuffling the
elements of the identity) and finds its inverse.

</P>

<PRE>
#include &#60;stdio.h&#62;
#include &#60;gsl/gsl_rng.h&#62;
#include &#60;gsl/gsl_randist.h&#62;
#include &#60;gsl/gsl_permutation.h&#62;

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-&#62;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;
}
</PRE>

<P>
Here is the output from the program,

</P>

<PRE>
$ ./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
</PRE>

<P>
The random permutation <CODE>p[i]</CODE> and its inverse <CODE>q[i]</CODE> are
related through the identity <CODE>p[q[i]] = i</CODE>, which can be verified
from the output.

</P>
<P>
The next example program steps forwards through all possible third order
permutations, starting from the identity,

</P>

<PRE>
#include &#60;stdio.h&#62;
#include &#60;gsl/gsl_permutation.h&#62;

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;
}
</PRE>

<P>
Here is the output from the program,

</P>

<PRE>
$ ./a.out 
 0 1 2
 0 2 1
 1 0 2
 1 2 0
 2 0 1
 2 1 0
</PRE>

<P>
The permutations are generated in lexicographic order.  To reverse the
sequence, begin with the final permutation (which is the reverse of the
identity) and replace <CODE>gsl_permutation_next</CODE> with
<CODE>gsl_permutation_prev</CODE>.

</P>


<H2><A NAME="SEC198" HREF="gsl-ref_toc.html#TOC198">References and Further Reading</A></H2>

<P>
The subject of permutations is covered extensively in Knuth's
<CITE>Sorting and Searching</CITE>,

</P>

<UL>
<LI>

Donald E. Knuth, <CITE>The Art of Computer Programming: Sorting and
Searching</CITE> (Vol 3, 3rd Ed, 1997), Addison-Wesley, ISBN 0201896850.
</UL>

<P>
For the definition of the <I>canonical form</I> see,

</P>

<UL>
<LI>

Donald E. Knuth, <CITE>The Art of Computer Programming: Fundamental
Algorithms</CITE> (Vol 1, 3rd Ed, 1997), Addison-Wesley, ISBN 0201896850.
Section 1.3.3, <CITE>An Unusual Correspondence</CITE>, p.178--179.
</UL>

<P><HR><P>
<p>Go to the <A HREF="gsl-ref_1.html">first</A>, <A HREF="gsl-ref_8.html">previous</A>, <A HREF="gsl-ref_10.html">next</A>, <A HREF="gsl-ref_50.html">last</A> section, <A HREF="gsl-ref_toc.html">table of contents</A>.
</BODY>
</HTML>