\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 = 
  <int32>  - size: [1 1]
 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 = 
  <double>  - size: [1 1]
 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 = 
  <double>  - size: [1 1]
 6.2  

\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 = 
  <dcomplex>  - size: [1 1]
  3+ 4i  
--> b = a .* 2.0f
b = 
  <dcomplex>  - size: [1 1]
  6+ 8i  

\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 = 
  <dcomplex>  - size: [1 1]
  6+ 8i  

\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 = 
  <int32>  - size: [2 2]
 
Columns 1 to 2
 1  2  
 3  4  
--> b = [2,3;6,7]
b = 
  <int32>  - size: [2 2]
 
Columns 1 to 2
 2  3  
 6  7  
--> c = a .* b
c = 
  <int32>  - size: [2 2]
 
Columns 1 to 2
  2   6  
 18  28  

\end{verbatim}
Then the scalar versions
\begin{verbatim}
--> c = a .* 3
c = 
  <int32>  - size: [2 2]
 
Columns 1 to 2
  3   6  
  9  12  
--> c = 3 .* a
c = 
  <int32>  - size: [2 2]
 
Columns 1 to 2
  3   6  
  9  12  

\end{verbatim}
