\section{IPERMUTE Array Inverse Permutation Function}

\subsection{Usage}

The \verb|ipermute| function rearranges the contents of an array according
to the inverse of the specified permutation vector.  The syntx for 
its use is
\begin{verbatim}
   y = ipermute(x,p)
\end{verbatim}
where \verb|p| is a permutation vector - i.e., a vector containing the 
integers \verb|1...ndims(x)| each occuring exactly once.  The resulting
array \verb|y| contains the same data as the array \verb|x|, but ordered
according to the inverse of the given permutation.  This function and
the \verb|permute| function are inverses of each other.
\subsection{Example}

First we create a large multi-dimensional array, then permute it
 and then inverse permute it, to retrieve the original array:
\begin{verbatim}
--> A = randn(13,5,7,2);
--> size(A)
ans = 
  <uint32>  - size: [1 4]
 
Columns 1 to 4
 13   5   7   2  
--> B = permute(A,[3,4,2,1]);
--> size(B)
ans = 
  <uint32>  - size: [1 4]
 
Columns 1 to 4
  7   2   5  13  
--> C = ipermute(B,[3,4,2,1]);
--> size(C)
ans = 
  <uint32>  - size: [1 4]
 
Columns 1 to 4
 13   5   7   2  
--> any(A~=C)
ans = 
  <logical>  - size: [1 1]
 0  

\end{verbatim}
