fix regression of min(sparseScalar) max(sparseScalar)
[scilab.git] / scilab / modules / elementary_functions / help / en_US / matrixoperations / max.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2008 - INRIA
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2018 - Samuel GOUGEON
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17         xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
18         xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
19         xmlns:scilab="http://www.scilab.org" xml:id="max" xml:lang="en">
20     <refnamediv>
21         <refname>max</refname>
22         <refpurpose>maximum</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             m = max(A)
28             Col = max(A, 'c')
29             Row = max(A, 'r'|'m')
30             M = max(A1, A2,..., An)
31             M = max(list(A1, A2,..., An))
32             [.., K] = max(..)
33         </synopsis>
34     </refsynopsisdiv>
35     <refsection>
36         <title>Arguments</title>
37         <variablelist>
38             <varlistentry>
39                 <term>A, A1, ..., An</term>
40                 <listitem>
41                     <para>
42                         scalars, vectors, matrices or hypermatrices of encoded integers or of real
43                         numbers, in dense or sparse format. They must have the same sizes, or be
44                         mixed with scalars (scalars are then implicitly expanded to the arrays sizes).
45                         Sparse arrays can't be mixed with dense ones, except with dense scalars.
46                     </para>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>m</term>
51                 <listitem>
52                     <para>
53                         single number = maximum of all values of <varname>A</varname> elements.
54                         Always in dense format, even when <varname>A</varname> is sparse encoded.
55                     </para>
56                 </listitem>
57             </varlistentry>
58             <varlistentry>
59                 <term>Col</term>
60                 <listitem>
61                     <para>
62                         column vector if <varname>A</varname> is a 2D matrix, or hypermatrix of
63                         size(A) with size(A,2) set to 1: Maxima over columns (for each row).
64                         If <varname>A</varname> is sparse, then <varname>Col</varname> is sparse
65                         as well.
66                     </para>
67                 </listitem>
68             </varlistentry>
69             <varlistentry>
70                 <term>Row</term>
71                 <listitem>
72                     <para>
73                         row vector if <varname>A</varname> is a 2D matrix, or hypermatrix of
74                         size(A) with size(A,1) set to 1: Maxima over rows (for each column).
75                         If <varname>A</varname> is sparse, then <varname>Row</varname> is sparse
76                         as well.
77                     </para>
78                 </listitem>
79             </varlistentry>
80             <varlistentry>
81                 <term>M</term>
82                 <listitem>
83                     <para>
84                         Array of size = <literal>size(A1)</literal>, such that for any q
85                         <literal>M(q) = max(A1(q),A2(q),..An(q))</literal>
86                         If <varname>A</varname>,..,<varname>An</varname> are sparse, then
87                         <varname>M</varname> is sparse as well.
88                     </para>
89                 </listitem>
90             </varlistentry>
91             <varlistentry>
92                 <term>K</term>
93                 <listitem>
94                     <para>
95                         Indices in <varname>A</varname>.. of the (first) maximum found.
96                         When <literal>[m,K]=max(A)</literal> is used,
97                         <itemizedlist>
98                             <listitem>
99                                 If <literal>A</literal> is a vector, K is a scalar.
100                             </listitem>
101                             <listitem>
102                                 Otherwise, <varname>K</varname> is a row vector [i,j,..] of subscripts.
103                             </listitem>
104                         </itemizedlist>
105                     </para>
106                     <para>
107                         For other syntaxes, <varname>K</varname> has the shape and sizes of
108                         <varname>Col</varname>, <varname>Row</varname>, and <varname>M</varname>.
109                     </para>
110                     <para>
111                         With the <literal>[M,K] = max(A1,A2,..,An)</literal> syntax, we have,
112                         for any linear index q:
113                         <literal>[M(q),K(q)] = max([A1(q) A2(q) .. An(q)])</literal>.
114                     </para>
115                     <para>
116                         <warning>
117                             <varname>K</varname> is always in dense format, even when
118                             <varname>A, A1,..,An</varname> are sparse-encoded. Hence, when the
119                             <literal>[M,K]=max(A1,A2,..)</literal> syntax is used with huge but
120                             sparse matrices, this may lead to a huge <emphasis>dense</emphasis>
121                             <varname>K</varname> matrix. The user must check that enough memory
122                             is available for it.
123                         </warning>
124                     </para>
125                 </listitem>
126             </varlistentry>
127         </variablelist>
128     </refsection>
129     <refsection>
130         <title>Description</title>
131         <para>
132             For <literal>A</literal>, a real vector or matrix, <literal>max(A)</literal> is the
133             greatest element of <literal>A</literal>.
134         </para>
135         <para>
136             <literal>[m,K]=max(A)</literal> gives in addition the indices of the first maximum.
137         </para>
138         <para>
139             A second argument of type string <literal>'r'</literal> or
140             <literal>'c'</literal> can be used : <literal>'r'</literal> is used to get
141             a row vector <literal>Row</literal> such that <literal>Row(j)</literal>
142             contains the maximum of the <literal>j</literal>th column <literal>A(:,j)</literal>,
143             <literal>K(j)</literal> gives the index of the row
144             which contains the maximum, for the column #<literal>j</literal>.
145         </para>
146         <para>
147             <literal>'c'</literal> is used for the dual operation on the rows of
148             <literal>A</literal>. <literal>'m'</literal> is used for compatibility with Matlab.
149         </para>
150         <para>
151             <literal>[M,K]=max(list(A1,...,An))</literal> is an equivalent
152             syntax of <literal>[M,K]=max(A1,A2,...,An)</literal>.
153         </para>
154         <note>
155             <itemizedlist>
156                 <listitem>
157                     max() ignores NaN values (unless there are only NaN values).
158                 </listitem>
159                 <listitem>
160                     <literal>max([])</literal> returns
161                     <literal>[]</literal> for values and <varname>K</varname>.
162                 </listitem>
163             </itemizedlist>
164         </note>
165         <warning>
166           If <literal>max(A1, A2,..., An)</literal> is used with a huge input sparse matrix of
167           low density, together with a strictly positive scalar input, the sparse result will no longer
168           have any 0 value: It will be a sparse array with density=1, that may lead to a memory failure.
169         </warning>
170     </refsection>
171     <refsection>
172         <title>Examples</title>
173         <programlisting role="example"><![CDATA[
174 [m, k] = max([])
175 [m, k] = max([1 5 ; 3 %nan])
176 [m, k] = max([1 5 ; 3 %nan], 2.5)
177 [m, k] = max([5 -1 1], [1 0 3], [2 1 3])
178 [m, k] = max(list([5 -1 1], [1 0 3], [2 1 3]))
179  ]]></programlisting>
180     <screen><![CDATA[
181 --> [m, k] = max([])
182  m  =
183     []
184  k  =
185     []
186
187 --> [m, k] = max([1 5 ; 3 %nan])
188  m  =
189    5.
190
191  k  =
192    1.   2.
193
194 --> [m, k] = max([1 5 ; 3 %nan], 2.5)
195  m  =
196    2.5   5.
197    3.    2.5
198
199  k  =
200    2.   1.
201    1.   2.
202
203 --> [m, k] = max([5 -1 1], [1 0 3], [2 1 3])
204  m  =
205    5.   1.   3.
206
207  k  =
208    1.   3.   2.
209 ]]></screen>
210         <para>
211             <emphasis role="bold">With the "r" or "c" options</emphasis>:
212         </para>
213         <programlisting role="example"><![CDATA[
214 A = grand(4,6,"uin",0,30); A(3,4) = %nan
215 [Row, K] = max(A, "r")
216 [Col, K] = max(A, "c")
217  ]]></programlisting>
218     <screen><![CDATA[
219 --> A = grand(4,6,"uin",0,30); A(3,4) = %nan
220  A  =
221    18.   3.    22.   0.    13.   28.
222    16.   20.   25.   6.    10.   1.
223    25.   26.   20.   Nan   2.    21.
224    5.    9.    16.   15.   24.   25.
225
226 --> [Row, K] = max(A, "r")
227  Row  =
228    25.   26.   25.   15.   24.   28.
229
230  K  =
231    3.   3.   2.   4.   4.   1.
232
233 --> [Col, K] = max(A, "c")
234  Col  =
235    28.
236    25.
237    26.
238    25.
239
240  K  =
241    6.
242    3.
243    2.
244    6.
245 ]]></screen>
246         <para>
247             <emphasis role="bold">With sparse inputs</emphasis>:
248         </para>
249         <programlisting role="example"><![CDATA[
250 s = sprand(5,4,0.5); k = s~=0; s(k) = round((s(k)-0.5)*10), full(s)
251 [Row, K] = max(s, "r")
252 [Col, K] = max(s, "c")
253 [M, K] = max(s, -1);   [full(s)  ones(s(:,1))*%nan  full(M)]
254 issparse(M)
255 K
256  ]]></programlisting>
257     <screen><![CDATA[
258 --> s = sprand(5,4,0.5); k = s~=0; s(k) = round((s(k)-0.5)*10), full(s)
259  s  =
260 (  5,  4) sparse matrix
261 (  1,  2)    -2.
262 (  1,  3)    -4.
263 (  1,  4)     3.
264 (  2,  1)    -5.
265 (  2,  4)     3.
266 (  3,  2)    -2.
267 (  3,  3)    -4.
268 (  4,  2)     4.
269 (  4,  4)     2.
270 (  5,  2)    -5.
271 (  5,  3)     5.
272 (  5,  4)    -4.
273
274  ans  =
275    0.  -2.  -4.   3.
276   -5.   0.   0.   3.
277    0.  -2.  -4.   0.
278    0.   4.   0.   2.
279    0.  -5.   5.  -4.
280
281 --> [Row, K] = max(s, "r")
282  Row  =
283 (  1,  4) sparse matrix
284 (  1,  2)     4.
285 (  1,  3)     5.
286 (  1,  4)     3.
287
288  K  =
289    1.   4.   5.   1.
290
291 --> [Col, K] = max(s, "c")
292  Col  =
293 (  5,  1) sparse matrix
294 (  1,  1)     3.
295 (  2,  1)     3.
296 (  4,  1)     4.
297 (  5,  1)     5.
298
299  K  =
300    4.
301    4.
302    1.
303    2.
304    3.
305
306 --> [M, K] = max(s, -1);   [full(s)  ones(s(:,1))*%nan  full(M)]
307  ans  =
308    0.  -2.  -4.   3.   Nan   0.  -1.  -1.   3.
309   -5.   0.   0.   3.   Nan  -1.   0.   0.   3.
310    0.  -2.  -4.   0.   Nan   0.  -1.  -1.   0.
311    0.   4.   0.   2.   Nan   0.   4.   0.   2.
312    0.  -5.   5.  -4.   Nan   0.  -1.   5.  -1.
313
314 --> issparse(M)
315  ans  =
316    1.
317
318 --> K
319  K  =
320    1.   2.   2.   1.
321    2.   1.   1.   1.
322    1.   2.   2.   1.
323    1.   1.   1.   1.
324    1.   2.   1.   2.
325 ]]></screen>
326     </refsection>
327     <refsection role="see also">
328         <title>See also</title>
329         <simplelist type="inline">
330             <member>
331                 <link linkend="min">min</link>
332             </member>
333             <member>
334                 <link linkend="strange">strange</link>
335             </member>
336             <member>
337                 <link linkend="mean">mean</link>
338             </member>
339             <member>
340                 <link linkend="gsort">gsort</link>
341             </member>
342             <member>
343                 <link linkend="find">find</link>
344             </member>
345             <member>
346                 <link linkend="full">full</link>
347             </member>
348         </simplelist>
349     </refsection>
350     <refsection role="history">
351         <title>History</title>
352         <revhistory>
353             <revision>
354                 <revnumber>6.0.2</revnumber>
355                 <revdescription>
356                     max() now actually works with sparse matrices
357                 </revdescription>
358             </revision>
359         </revhistory>
360     </refsection>
361 </refentry>