% $Date: 2003/09/15 16:37:45 $ $Author: nthiery $ $Revision: 1.1.1.1 $

\begin{Mhelppage}{ListPerm}{V. Prosper}%
  \begin{MInfo}
    \eng{generates all permutations}
  \end{MInfo}

  \MDeclareOption{\type}{type}
  \MDeclareOption{\nb}{}
  \MDeclareOption{\level}{level}
  \MDeclareOption{\code}{code}

  \begin{MCalls}
    \Mcall{l}
    \Mcall{n \Mopt{,\type,\code,\level} \Mopt{,\nb}}
  \end{MCalls}

  \begin{MParameters}
    \param{n}
    \eng{degree of a symmetric group (positive integer)}
    \param{l}
    \eng{a list of values}
  \end{MParameters}
  \begin{MOptions}
    \option{\code}
    \eng{codes instead of permutations}
    \option{\level}
    \eng{by level in the permutohedron}
    \option{\nb}
    \eng{only counts objects}
    \option{\type=lexic,cixel,vexillary,dominant,grassmannian}
  \end{MOptions}

  \begin{MIntro}
    \eng{The {\Mthis} function generates permutations.
      
      If the first argument is a list or a set \Mex{l}, it generates
      all distinct permutations of the elements of \Mex{l}.
      
      If the first argument is an integer, say \Mex{n}, then the
      function returns the list of all permutations of the symmetric
      group of degree \Mex{n}. In this case, using \Mex{n=0} is also
      allowed.
      
      \Mex{\Mthis(n, lexic)} or \Mex{\Mthis(n, cixel)} returns all
      permutations in lexicographic or reverse lexicographic order.
      
      \Mex{\Mthis(n, hold(level))} returns a list of lists. First list
      contains all permutations with 0 inversion, second one contains
      all permutations with 1 inversion, ..., last one contains all
      permutations with \Mmath{n*(n-1)/2}{n(n-1)/2} inversions.
      
      \Mex{\Mthis(n, \Mpar{type})}, where \Mpar{type} is either
      \Mex{dominant}, \Mex{grassmannian} or \Mex{vexillary}, returns
      the list of all dominant, grassmannian or vexillary permutations
      of the symmetric group of degree \Mex{n}.  Vexillary
      permutations are generated using an algorithm due to J. West.
 
      When the first argument is an integer, one can use another
      argument \Mex{code}, to produce Lehmer codes instead of
      permutations. When generating dominant permutations, it is
      faster to produce codes. One can also add the argument \Mex{nb}
      to count instead of producing permutations.  }
  \end{MIntro}

\begin{MExample}{ex1}
\begin{Mexin}
muEC::SG::ListPerm([1,1,3,3]);
\end{Mexin}
\begin{Mexout}
[[1, 1, 3, 3], [1, 3, 1, 3], [1, 3, 3, 1], [3, 1, 1, 3],

   [3, 1, 3, 1], [3, 3, 1, 1]]
\end{Mexout}
\begin{Mexin}
muEC::SG::ListPerm(3, cixel);
\end{Mexin}
\begin{Mexout}
[[3, 2, 1], [2, 3, 1], [3, 1, 2], [1, 3, 2], [2, 1, 3],

   [1, 2, 3]]
\end{Mexout}
\begin{Mexin}
muEC::SG::ListPerm(3, hold(level));
\end{Mexin}
\begin{Mexout}
[[[1, 2, 3]], [[1, 3, 2], [2, 1, 3]], [[3, 1, 2], [2, 3, 1]],

   [[3, 2, 1]]]
\end{Mexout}
\begin{Mexin}
muEC::SG::ListPerm(3, hold(level), code);
\end{Mexin}
\begin{Mexout}
[[[0, 0, 0]], [[0, 1, 0], [1, 0, 0]], [[2, 0, 0], [1, 1, 0]],

   [[2, 1, 0]]]
\end{Mexout}
\begin{Mexin}
muEC::SG::ListPerm(4, vexillary, nb);
\end{Mexin}
\begin{Mexout}
                              23
\end{Mexout}
\begin{Mexin}
muEC::SG::ListPerm(5, vexillary, nb, hold(level));
\end{Mexin}
\begin{Mexout}
            [1, 4, 6, 11, 16, 18, 18, 15, 9, 4, 1]
\end{Mexout}
\begin{Mexin}
muEC::SG::ListPerm(5, nb, hold(level));
\end{Mexin}
\begin{Mexout}
            [1, 4, 9, 15, 20, 22, 20, 15, 9, 4, 1]
\end{Mexout}
\end{MExample}

\MRelatedFunctions{GenPerm,IsPerm}
\end{Mhelppage}
%End of ListPerm.tex
