\section{DOTPOWER Element-wise Power Operator}

\subsection{Usage}

Raises one numerical array to another array (elementwise).  There are three operators all with the same general syntax:
\begin{verbatim}
  y = a .^ b
\end{verbatim}
The result \verb|y| depends on which of the following three situations applies to the arguments \verb|a| and \verb|b|:
\begin{enumerate}
\item  \verb|a| is a scalar, \verb|b| is an arbitrary \verb|n|-dimensional numerical array, in which case the output is \verb|a| raised to the power of each element of \verb|b|, and the output is the same size as \verb|b|.

\item  \verb|a| is an \verb|n|-dimensional numerical array, and \verb|b| is a scalar, then the output is the same size as \verb|a|, and is defined by each element of \verb|a| raised to the power \verb|b|.

\item  \verb|a| and \verb|b| are both \verb|n|-dimensional numerical arrays of \emph{the same size}.  In this case, each element of the output is the corresponding element of \verb|a| raised to the power defined by the corresponding element of \verb|b|.

\end{enumerate}
The output follows the standard type promotion rules, although types are not generally preserved under the power operation.  In particular, integers are automatically converted to \verb|double| type, and negative numbers raised to fractional powers can return complex values.
\subsection{Function Internals}

There are three formulae for this operator.  For the first form
\[
y(m_1,\ldots,m_d) = a^{b(m_1,\ldots,m_d)},
\]
and the second form
\[
y(m_1,\ldots,m_d) = a(m_1,\ldots,m_d)^b,
\]
and in the third form
\[
y(m_1,\ldots,m_d) = a(m_1,\ldots,m_d)^{b(m_1,\ldots,m_d)}.
\]
\subsection{Examples}

We demonstrate the three forms of the dot-power operator using some simple examples.  First, the case of a scalar raised to a series of values.
\begin{verbatim}
--> a = 2
a = 
  <int32>  - size: [1 1]
 2  
--> b = 1:4
b = 
  <int32>  - size: [1 4]
 
Columns 1 to 4
 1  2  3  4  
--> c = a.^b
c = 
  <double>  - size: [1 4]
 
Columns 1 to 4
  2   4   8  16  

\end{verbatim}
The second case shows a vector raised to a scalar.
\begin{verbatim}
--> c = b.^a
c = 
  <double>  - size: [1 4]
 
Columns 1 to 4
  1   4   9  16  

\end{verbatim}
The third case shows the most general use of the dot-power operator.
\begin{verbatim}
--> A = [1,2;3,2]
A = 
  <int32>  - size: [2 2]
 
Columns 1 to 2
 1  2  
 3  2  
--> B = [2,1.5;0.5,0.6]
B = 
  <double>  - size: [2 2]
 
Columns 1 to 2
 2.0  1.5  
 0.5  0.6  
--> C = A.^B
C = 
  <double>  - size: [2 2]
 
Columns 1 to 2
 1.0000000000000000  2.8284271247461903  
 1.7320508075688772  1.5157165665103980  

\end{verbatim}
