\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 = 

 2 

--> b = 1:4

b = 

 1 2 3 4 

--> c = a.^b

c = 

  2  4  8 16 


\end{verbatim}
The second case shows a vector raised to a scalar.
\begin{verbatim}
--> c = b.^a

c = 

  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 = 

 1 2 
 3 2 

--> B = [2,1.5;0.5,0.6]

B = 

    2.0000    1.5000 
    0.5000    0.6000 

--> C = A.^B

C = 

    1.0000    2.8284 
    1.7321    1.5157 


\end{verbatim}
