\section{DOTTIMES Element-wise Multiplication Operator}

\subsection{Usage}

Multiplies two numerical arrays (elementwise).  There are two forms
for its use, both with the same general syntax:
\begin{verbatim}
  y = a .* b
\end{verbatim}
where \verb|a| and \verb|b| are \verb|n|-dimensional arrays of numerical type.  In the
first case, the two arguments are the same size, in which case, the 
output \verb|y| is the same size as the inputs, and is the element-wise
product of \verb|a| and \verb|b|.  In the second case, either \verb|a| or \verb|b| is a scalar, 
in which case \verb|y| is the same size as the larger argument,
and is the product of the scalar with each element of the other argument.

The type of \verb|y| depends on the types of \verb|a| and \verb|b| using type 
promotion rules. All of the types are preserved under multiplication except
 for integer types, which are promoted to \verb|int32| prior to 
multiplication (same as \verb|C|).
\subsection{Function Internals}

There are three formulae for the dot-times operator, depending on the
sizes of the three arguments.  In the most general case, in which 
the two arguments are the same size, the output is computed via:
\[
y(m_1,\ldots,m_d) = a(m_1,\ldots,m_d) \times b(m_1,\ldots,m_d)
\]
If \verb|a| is a scalar, then the output is computed via
\[
y(m_1,\ldots,m_d) = a \times b(m_1,\ldots,m_d).
\]
On the other hand, if \verb|b| is a scalar, then the output is computed via
\[
y(m_1,\ldots,m_d) = a(m_1,\ldots,m_d) \times b.
\]
\subsection{Examples}

Here are some examples of using the dottimes operator.  First, a 
straight-forward usage of the \verb|.*| operator.  The first example
is straightforward:
\begin{verbatim}
--> 3 .* 8

ans = 

 24 


\end{verbatim}
Note, however, that because of the way that input is parsed, eliminating
the spaces \verb|3.*8| results in the input being parsed as \verb|3. * 8|,
which yields a \verb|double| result:
\begin{verbatim}
--> 3.*8

ans = 

 24 


\end{verbatim}
This is really an invokation of the \verb|times| operator.

Next, we use the floating point syntax to force one of the arguments
to be a \verb|double|, which results in the output being \verb|double|:
\begin{verbatim}
--> 3.1 .* 2

ans = 

    6.2000 


\end{verbatim}
Note that if one of the arguments is complex-valued, the output will be
complex also.
\begin{verbatim}
--> a = 3 + 4*i

a = 

    3.0000 +  4.0000i 

--> b = a .* 2.0f

b = 

    6.0000 +  8.0000i 


\end{verbatim}
If a \verb|complex| value is multiplied by a \verb|double|, the result is 
promoted to \verb|dcomplex|.
\begin{verbatim}
--> b = a .* 2.0

b = 

    6.0000 +  8.0000i 


\end{verbatim}
We can also demonstrate the three forms of the dottimes operator.  First
the element-wise version:
\begin{verbatim}
--> a = [1,2;3,4]

a = 

 1 2 
 3 4 

--> b = [2,3;6,7]

b = 

 2 3 
 6 7 

--> c = a .* b

c = 

  2  6 
 18 28 


\end{verbatim}
Then the scalar versions
\begin{verbatim}
--> c = a .* 3

c = 

  3  6 
  9 12 

--> c = 3 .* a

c = 

  3  6 
  9 12 


\end{verbatim}
