<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2018 - Samuel GOUGEON
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
        xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
        xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
        xmlns:scilab="http://www.scilab.org" xml:id="max" xml:lang="en">
    <refnamediv>
        <refname>max</refname>
        <refpurpose>maximum</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            m = max(A)
            Col = max(A, 'c')
            Row = max(A, 'r'|'m')
            M = max(A1, A2,..., An)
            M = max(list(A1, A2,..., An))
            [.., K] = max(..)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>A, A1, ..., An</term>
                <listitem>
                    <para>
                        scalars, vectors, matrices or hypermatrices of encoded integers or of real
                        numbers, in dense or sparse format. They must have the same sizes, or be
                        mixed with scalars (scalars are then implicitly expanded to the arrays sizes).
                        Sparse arrays can't be mixed with dense ones, except with dense scalars.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>m</term>
                <listitem>
                    <para>
                        single number = maximum of all values of <varname>A</varname> elements.
                        Always in dense format, even when <varname>A</varname> is sparse encoded.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Col</term>
                <listitem>
                    <para>
                        column vector if <varname>A</varname> is a 2D matrix, or hypermatrix of
                        size(A) with size(A,2) set to 1: Maxima over columns (for each row).
                        If <varname>A</varname> is sparse, then <varname>Col</varname> is sparse
                        as well.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Row</term>
                <listitem>
                    <para>
                        row vector if <varname>A</varname> is a 2D matrix, or hypermatrix of
                        size(A) with size(A,1) set to 1: Maxima over rows (for each column).
                        If <varname>A</varname> is sparse, then <varname>Row</varname> is sparse
                        as well.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>M</term>
                <listitem>
                    <para>
                        Array of size = <literal>size(A1)</literal>, such that for any q
                        <literal>M(q) = max(A1(q),A2(q),..An(q))</literal>
                        If <varname>A</varname>,..,<varname>An</varname> are sparse, then
                        <varname>M</varname> is sparse as well.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>K</term>
                <listitem>
                    <para>
                        Indices in <varname>A</varname>.. of the (first) maximum found.
                        When <literal>[m,K]=max(A)</literal> is used,
                        <itemizedlist>
                            <listitem>
                                If <literal>A</literal> is a vector, K is a scalar.
                            </listitem>
                            <listitem>
                                Otherwise, <varname>K</varname> is a row vector [i,j,..] of subscripts.
                            </listitem>
                        </itemizedlist>
                    </para>
                    <para>
                        For other syntaxes, <varname>K</varname> has the shape and sizes of
                        <varname>Col</varname>, <varname>Row</varname>, and <varname>M</varname>.
                    </para>
                    <para>
                        With the <literal>[M,K] = max(A1,A2,..,An)</literal> syntax, we have,
                        for any linear index q:
                        <literal>[M(q),K(q)] = max([A1(q) A2(q) .. An(q)])</literal>.
                    </para>
                    <para>
                        <warning>
                            <varname>K</varname> is always in dense format, even when
                            <varname>A, A1,..,An</varname> are sparse-encoded. Hence, when the
                            <literal>[M,K]=max(A1,A2,..)</literal> syntax is used with huge but
                            sparse matrices, this may lead to a huge <emphasis>dense</emphasis>
                            <varname>K</varname> matrix. The user must check that enough memory
                            is available for it.
                        </warning>
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            For <literal>A</literal>, a real vector or matrix, <literal>max(A)</literal> is the
            greatest element of <literal>A</literal>.
        </para>
        <para>
            <literal>[m,K]=max(A)</literal> gives in addition the indices of the first maximum.
        </para>
        <para>
            A second argument of type string <literal>'r'</literal> or
            <literal>'c'</literal> can be used : <literal>'r'</literal> is used to get
            a row vector <literal>Row</literal> such that <literal>Row(j)</literal>
            contains the maximum of the <literal>j</literal>th column <literal>A(:,j)</literal>,
            <literal>K(j)</literal> gives the index of the row
            which contains the maximum, for the column #<literal>j</literal>.
        </para>
        <para>
            <literal>'c'</literal> is used for the dual operation on the rows of
            <literal>A</literal>. <literal>'m'</literal> is used for compatibility with Matlab.
        </para>
        <para>
            <literal>[M,K]=max(list(A1,...,An))</literal> is an equivalent
            syntax of <literal>[M,K]=max(A1,A2,...,An)</literal>.
        </para>
        <note>
            <itemizedlist>
                <listitem>
                    max() ignores NaN values (unless there are only NaN values).
                </listitem>
                <listitem>
                    <literal>max([])</literal> returns
                    <literal>[]</literal> for values and <varname>K</varname>.
                </listitem>
            </itemizedlist>
        </note>
        <warning>
          If <literal>max(A1, A2,..., An)</literal> is used with a huge input sparse matrix of
          low density, together with a strictly positive scalar input, the sparse result will no longer
          have any 0 value: It will be a sparse array with density=1, that may lead to a memory failure.
        </warning>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
[m, k] = max([])
[m, k] = max([1 5 ; 3 %nan])
[m, k] = max([1 5 ; 3 %nan], 2.5)
[m, k] = max([5 -1 1], [1 0 3], [2 1 3])
[m, k] = max(list([5 -1 1], [1 0 3], [2 1 3]))
 ]]></programlisting>
    <screen><![CDATA[
--> [m, k] = max([])
 m  =
    []
 k  =
    []

--> [m, k] = max([1 5 ; 3 %nan])
 m  =
   5.

 k  =
   1.   2.

--> [m, k] = max([1 5 ; 3 %nan], 2.5)
 m  =
   2.5   5.
   3.    2.5

 k  =
   2.   1.
   1.   2.

--> [m, k] = max([5 -1 1], [1 0 3], [2 1 3])
 m  =
   5.   1.   3.

 k  =
   1.   3.   2.
]]></screen>
        <para>
            <emphasis role="bold">With the "r" or "c" options</emphasis>:
        </para>
        <programlisting role="example"><![CDATA[
A = grand(4,6,"uin",0,30); A(3,4) = %nan
[Row, K] = max(A, "r")
[Col, K] = max(A, "c")
 ]]></programlisting>
    <screen><![CDATA[
--> A = grand(4,6,"uin",0,30); A(3,4) = %nan
 A  =
   18.   3.    22.   0.    13.   28.
   16.   20.   25.   6.    10.   1.
   25.   26.   20.   Nan   2.    21.
   5.    9.    16.   15.   24.   25.

--> [Row, K] = max(A, "r")
 Row  =
   25.   26.   25.   15.   24.   28.

 K  =
   3.   3.   2.   4.   4.   1.

--> [Col, K] = max(A, "c")
 Col  =
   28.
   25.
   26.
   25.

 K  =
   6.
   3.
   2.
   6.
]]></screen>
        <para>
            <emphasis role="bold">With sparse inputs</emphasis>:
        </para>
        <programlisting role="example"><![CDATA[
s = sprand(5,4,0.5); k = s~=0; s(k) = round((s(k)-0.5)*10), full(s)
[Row, K] = max(s, "r")
[Col, K] = max(s, "c")
[M, K] = max(s, -1);   [full(s)  ones(s(:,1))*%nan  full(M)]
issparse(M)
K
 ]]></programlisting>
    <screen><![CDATA[
--> s = sprand(5,4,0.5); k = s~=0; s(k) = round((s(k)-0.5)*10), full(s)
 s  =
(  5,  4) sparse matrix
(  1,  2)    -2.
(  1,  3)    -4.
(  1,  4)     3.
(  2,  1)    -5.
(  2,  4)     3.
(  3,  2)    -2.
(  3,  3)    -4.
(  4,  2)     4.
(  4,  4)     2.
(  5,  2)    -5.
(  5,  3)     5.
(  5,  4)    -4.

 ans  =
   0.  -2.  -4.   3.
  -5.   0.   0.   3.
   0.  -2.  -4.   0.
   0.   4.   0.   2.
   0.  -5.   5.  -4.

--> [Row, K] = max(s, "r")
 Row  =
(  1,  4) sparse matrix
(  1,  2)     4.
(  1,  3)     5.
(  1,  4)     3.

 K  =
   1.   4.   5.   1.

--> [Col, K] = max(s, "c")
 Col  =
(  5,  1) sparse matrix
(  1,  1)     3.
(  2,  1)     3.
(  4,  1)     4.
(  5,  1)     5.

 K  =
   4.
   4.
   1.
   2.
   3.

--> [M, K] = max(s, -1);   [full(s)  ones(s(:,1))*%nan  full(M)]
 ans  =
   0.  -2.  -4.   3.   Nan   0.  -1.  -1.   3.
  -5.   0.   0.   3.   Nan  -1.   0.   0.   3.
   0.  -2.  -4.   0.   Nan   0.  -1.  -1.   0.
   0.   4.   0.   2.   Nan   0.   4.   0.   2.
   0.  -5.   5.  -4.   Nan   0.  -1.   5.  -1.

--> issparse(M)
 ans  =
   1.

--> K
 K  =
   1.   2.   2.   1.
   2.   1.   1.   1.
   1.   2.   2.   1.
   1.   1.   1.   1.
   1.   2.   1.   2.
]]></screen>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="min">min</link>
            </member>
            <member>
                <link linkend="strange">strange</link>
            </member>
            <member>
                <link linkend="mean">mean</link>
            </member>
            <member>
                <link linkend="gsort">gsort</link>
            </member>
            <member>
                <link linkend="find">find</link>
            </member>
            <member>
                <link linkend="full">full</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>6.0.2</revnumber>
                <revdescription>
                    max() now actually works with sparse matrices
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
