[doc] misc fix & improvements
[scilab.git] / scilab / modules / elementary_functions / help / en_US / matrixoperations / cumsum.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) 2010 - Serge Steer - INRIA
5  *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
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:db="http://docbook.org/ns/docbook" xml:id="cumsum">
19     <refnamediv>
20         <refname>cumsum</refname>
21         <refpurpose>partial cumulative sums of the elements of an array</refpurpose>
22     </refnamediv>
23     <refsynopsisdiv>
24         <title>Syntax</title>
25         <synopsis>
26             y = cumsum(x)
27             y = cumsum(x, outtype)
28             y = cumsum(x, orientation)
29             y = cumsum(x, orientation, outtype)
30         </synopsis>
31     </refsynopsisdiv>
32
33     <refsection role="parameters">
34         <title>Arguments</title>
35         <variablelist>
36             <varlistentry>
37                 <term>x</term>
38                 <listitem>
39                     <para>
40                         array of booleans, integers, real or complex numbers, polynomials, or
41                         rational fractions.
42                         Hypermatrices or sparse boolean or numerical matrices are supported as well.
43                     </para>
44                 </listitem>
45             </varlistentry>
46             <varlistentry>
47                 <term>orientation</term>
48                 <listitem>
49                     <para>This argument can be</para>
50                     <itemizedlist>
51                         <listitem>
52                             <para>
53                                 either a string with possible values <literal>"*"</literal>,
54                                 <literal>"r"</literal>, <literal>"c"</literal> or <literal>"m"</literal>
55                             </para>
56                         </listitem>
57                         <listitem>
58                             <para>
59                               positive integer 1 ≤ orientation ≤ ndims(x): the index of the
60                               dimension along which the cumulative sum must be computed.
61                               1 and "r", and 2 and "c", are equivalent.
62                             </para>
63                         </listitem>
64                     </itemizedlist>
65                 </listitem>
66             </varlistentry>
67             <varlistentry>
68                 <term>outtype</term>
69                 <listitem>
70                     <para>
71                         Word <literal>"native"</literal> or <literal>"double"</literal>.
72                     </para>
73                 </listitem>
74             </varlistentry>
75             <varlistentry>
76                 <term>y</term>
77                 <listitem>
78                     <para>Array of size equal to that of <varname>x</varname>.</para>
79                 </listitem>
80             </varlistentry>
81         </variablelist>
82     </refsection>
83
84     <refsection role="description">
85         <title>Description</title>
86         <para>
87             <emphasis role="bold">y = cumsum(x)</emphasis> computes and provides the partial
88             cumulative sums <literal>y(i)=sum(x(1:i))</literal>, <emphasis role="italic">i.e.</emphasis>:
89         </para>
90         <para>
91             <latex alt="y(i) = ∑u=1→i x(u)"><![CDATA[ y(i) = \sum_{u=1}^i x(u)]]></latex>
92         </para>
93         <para>
94             <emphasis role="bold">y = cumsum(x, orientation)</emphasis> returns the partial
95             cumulative sums of <term>x</term> along the dimension given by <term>orientation</term>:
96         </para>
97         <itemizedlist>
98             <listitem>
99                 <para>
100                     if <term>orientation</term> is equal to 1 or "r" then:
101                 </para>
102                 <para>
103                     <latex alt="y(i,j) = ∑u=1→i x(u,j)"><![CDATA[
104                         y(\mathbf{i},j) = \sum_{u=1}^{\mathbf{i}} x(\mathbf{u},j)   ]]>
105                     </latex>, or for a N-Dimensional array:
106                 </para>
107                 <para>
108                     <latex alt="y(i,j,k,…) = ∑u=1→i x(u,j,k,…)"><![CDATA[
109                         y(\mathbf{i},j,k,\ldots) = \sum_{u=1}^{\mathbf{i}} x(\mathbf{u},j,k,\ldots)  ]]>
110                     </latex>
111                 </para>
112             </listitem>
113             <listitem>
114                 <para>
115                     if <term>orientation</term> is equal to 2 or "c" then:
116                 </para>
117                 <para>
118                     <latex alt="y(i,j) = ∑u=1→j x(i,u)"><![CDATA[
119                         y(i,\mathbf{j}) = \sum_{u=1}^{\mathbf{j}} x(i,{\mathbf{u})  ]]>
120                     </latex>, or for a N-Dimensional array:
121                 </para>
122                 <para>
123                     <latex alt="y(i,j,k,…) = ∑u=1→j x(i,u,k,…)"><![CDATA[
124                         y(i,\mathbf{j},k,\ldots) = \sum_{u=1}^{\mathbf{j}} x(i,\mathbf{u},k,\ldots) ]]>
125                     </latex>
126                 </para>
127             </listitem>
128             <listitem>
129                 <para>
130                     if <term>orientation</term> is equal to n then:
131                 </para>
132                 <para>
133                     <latex alt="y(i₁,…,iₙ₋₁, iₙ,iₙ₊₁,…) = ∑u=1…iₙ  x(i₁,…,iₙ₋₁, u,iₙ₊₁,…)"><![CDATA[
134                         y(i_1,\ldots,i_{n-1},\mathbf{i_{n}},i_{n+1},\ldots) =
135                         \sum_{u=1}^{\mathbf{i_n}} x(i_1,\ldots,i_{n-1},\mathbf{u},i_{n+1},\ldots) ]]>
136                     </latex>
137                 </para>
138             </listitem>
139             <listitem>
140                 <para>
141                     <emphasis role="bold">y = cumsum(x, "*")</emphasis> is equivalent to
142                     <literal>y = cumsum(x)</literal>
143                 </para>
144             </listitem>
145             <listitem>
146                 <para>
147                     <emphasis role="bold">y = cumsum(x, "m")</emphasis> is equivalent to
148                     <literal>y = cumsum(x, orientation)</literal> where <term>orientation</term>
149                     is the index of the first dimension of <term>x</term> that is greater than 1.
150                     This option is used for Matlab compatibility.
151                 </para>
152             </listitem>
153         </itemizedlist>
154         <para/>
155         <para>
156             The <term>outtype</term> argument rules the way the summations are done:
157         </para>
158         <itemizedlist>
159             <listitem>
160                 <para>
161                     For arrays of floats, of polynomials, of rational fractions, the evaluation
162                     is always done using floating points computations. The <literal>"double"</literal>
163                     or <literal>"native"</literal> options are equivalent.
164                 </para>
165             </listitem>
166             <listitem>
167                 <para>For arrays of integers,</para>
168                 <para>
169                     if <literal>outtype="native"</literal> the evaluation is done using integer
170                     computations (modulo 2^b, where b is the number of bits used),
171                 </para>
172                 <para>
173                     if <literal>outtype="double"</literal> the evaluation is done using floating
174                     point computations.
175                 </para>
176                 <para>
177                     The default value is <literal>outtype="native"</literal>.
178                 </para>
179             </listitem>
180             <listitem>
181                 <para>For arrays of booleans,</para>
182                 <para>
183                     if <literal>outtype="native"</literal> the evaluation is done using boolean
184                     computations ( + is replaced with |),
185                 </para>
186                 <para>
187                     if <literal>outtype="double"</literal> the evaluation is done using floating
188                     point computations (%t values are replaced by 1 and %f values by 0).
189                 </para>
190                 <para>
191                     The default value is <literal>outtype="double"</literal>.
192                 </para>
193             </listitem>
194         </itemizedlist>
195         <warning>
196             When the input <varname>x</varname> is sparse, please keep in mind that the density
197             of the result <varname>y</varname> will be almost always close to 100%.
198         </warning>
199     </refsection>
200
201     <refsection role="examples">
202         <title>Examples</title>
203         <programlisting role="example"><![CDATA[
204 A = [1,2;3,4];
205 cumsum(A)
206 cumsum(A,1)
207
208 I = uint8([2 95 103 ; 254 9 0])
209 cumsum(I) // native evaluation
210 cumsum(I,"double")
211 cumsum(I,2,"double")
212
213 s = poly(0,"s");
214 P = [s, %i+s ; s^2 , 1];
215 cumsum(P)
216 cumsum(P, 2)
217
218 B = [%t %t %f %f];
219 cumsum(B)          // evaluation in float
220 cumsum(B,"native") // similar to or(B)
221  ]]></programlisting>
222     </refsection>
223
224     <refsection role="see also">
225         <title>See also</title>
226         <simplelist type="inline">
227             <member>
228                 <link linkend="sum">sum</link>
229             </member>
230             <member>
231                 <link linkend="cumprod">cumprod</link>
232             </member>
233         </simplelist>
234     </refsection>
235 </refentry>