\section{MAX Maximum Function}

\subsection{Usage}

Computes the maximum of an array along a given dimension, or alternately, 
computes two arrays (entry-wise) and keeps the smaller value for each array.
As a result, the \verb|max| function has a number of syntaxes.  The first
one computes the maximum of an array along a given dimension.
The first general syntax for its use is either
\begin{verbatim}
   [y,n] = max(x,[],d)
\end{verbatim}
where \verb|x| is a multidimensional array of numerical type, in which case the
output \verb|y| is the maximum of \verb|x| along dimension \verb|d|.  
The second argument \verb|n| is the index that results in the maximum.
In the event that multiple maxima are present with the same value,
the index of the first maximum is used. 
The second general syntax for the use of the \verb|max| function is
\begin{verbatim}
   [y,n] = max(x)
\end{verbatim}
In this case, the maximum is taken along the first non-singleton 
dimension of \verb|x|.  For complex data types,
the maximum is based on the magnitude of the numbers.  NaNs are
ignored in the calculations.
The third general syntax for the use of the \verb|max| function is as 
a comparison function for pairs of arrays.  Here, the general syntax is
\begin{verbatim}
   y = max(x,z)
\end{verbatim}
where \verb|x| and \verb|z| are either both numerical arrays of the same dimensions,
or one of the two is a scalar.  In the first case, the output is the 
same size as both arrays, and is defined elementwise by the smaller of the
two arrays.  In the second case, the output is defined elementwise by the 
smaller of the array entries and the scalar.
\subsection{Function Internals}

In the general version of the \verb|max| function which is applied to
a single array (using the \verb|max(x,[],d)| or \verb|max(x)| syntaxes),
The output is computed via
\[
y(m_1,\ldots,m_{d-1},1,m_{d+1},\ldots,m_{p}) = 
\max_{k} x(m_1,\ldots,m_{d-1},k,m_{d+1},\ldots,m_{p}),
\]
and the output array \verb|n| of indices is calculated via
\[
n(m_1,\ldots,m_{d-1},1,m_{d+1},\ldots,m_{p}) = \arg
\max_{k} x(m_1,\ldots,m_{d-1},k,m_{d+1},\ldots,m_{p})
\]
In the two-array version (\verb|max(x,z)|), the single output is computed as
\[
  y(m_1,\ldots,m_{d-1},1,m_{d+1},\ldots,m_{p}) = 
\begin{cases}
  x(m_1,\ldots,m_{d-1},k,m_{d+1},\ldots,m_{p}) & x(\cdots) \leq z(\cdots) \\
  z(m_1,\ldots,m_{d-1},k,m_{d+1},\ldots,m_{p}) & z(\cdots) < x(\cdots).
\end{cases}
\]
\subsection{Example}

The following piece of code demonstrates various uses of the maximum
function.  We start with the one-array version.
\begin{verbatim}
--> A = [5,1,3;3,2,1;0,3,1]

A = 

 5 1 3 
 3 2 1 
 0 3 1 


\end{verbatim}
We first take the maximum along the columns, resulting in a row vector.
\begin{verbatim}
--> max(A)

ans = 

 5 3 3 


\end{verbatim}
Next, we take the maximum along the rows, resulting in a column vector.
\begin{verbatim}
--> max(A,[],2)

ans = 

 5 
 3 
 3 


\end{verbatim}
When the dimension argument is not supplied, \verb|max| acts along the first non-singular dimension.  For a row vector, this is the column direction:
\begin{verbatim}
--> max([5,3,2,9])

ans = 

 9 


\end{verbatim}

For the two-argument version, we can compute the smaller of two arrays,
as in this example:
\begin{verbatim}
--> a = int8(100*randn(4))

a = 

    0  115   15  -20 
  -26  127    1  -41 
  -12    5  -84   52 
   85 -108   -7 -100 

--> b = int8(100*randn(4))

b = 

 -30  14 -33 -69 
 -62 -71  48   8 
 -52   2 -95  75 
  40  44 120  -4 

--> max(a,b)

ans = 

   0 115  15 -20 
 -26 127  48   8 
 -12   5 -84  75 
  85  44 120  -4 


\end{verbatim}
Or alternately, we can compare an array with a scalar
\begin{verbatim}
--> a = randn(2)

a = 

    2.2822   -0.9318 
   -0.3667    0.5529 

--> max(a,0)

ans = 

    2.2822         0 
         0    0.5529 


\end{verbatim}
