398b87bd2da57a90fc0ee6ff19a844e91cf7fc7f
[scilab.git] / scilab / modules / elementary_functions / help / en_US / matrixoperations / cumprod.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  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at    
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  -->
13 <refentry version="5.0-subset Scilab" xml:id="cumprod" xml:lang="en"
14           xmlns="http://docbook.org/ns/docbook"
15           xmlns:xlink="http://www.w3.org/1999/xlink"
16           xmlns:svg="http://www.w3.org/2000/svg"
17           xmlns:ns5="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML"
19           xmlns:db="http://docbook.org/ns/docbook">
20   <info>
21     <pubdate>$LastChangedDate$</pubdate>
22   </info>
23
24   <refnamediv>
25     <refname>cumprod</refname>
26
27     <refpurpose>cumulative product of array elements</refpurpose>
28   </refnamediv>
29
30   <refsynopsisdiv>
31     <title>Calling Sequence</title>
32
33     <synopsis>y=cumprod(x)
34     y=cumprod(x,orientation)
35     y=cumprod(x,outtype)
36     y=cumprod(x,orientation,outtype)
37     </synopsis>
38   </refsynopsisdiv>
39
40   <refsection>
41     <title>Arguments</title>
42
43     <variablelist>
44       <varlistentry>
45         <term>x</term>
46
47         <listitem>
48           <para>
49             an array of  reals, complex, booleans,  polynomials or
50             rational fractions.
51           </para>
52         </listitem>
53       </varlistentry>
54       <varlistentry>
55         <term>orientation</term>
56         <listitem>
57           <para>
58             it can be either </para>
59             <itemizedlist>
60               <listitem>
61                 <para>a string with possible values <literal>"*"</literal>, <literal>"r"</literal>, 
62                 <literal>"c"</literal> or  <literal>"m"</literal></para>
63               </listitem>
64               <listitem>
65                 <para>a number with positive integer value</para>
66               </listitem>
67           </itemizedlist>
68         </listitem>
69       </varlistentry>
70       <varlistentry>
71         <term>outtype</term>
72         <listitem>
73           <para>
74             a string with possible values <literal>"native"</literal> or <literal>"double"</literal>. </para>
75         </listitem>
76       </varlistentry>
77
78       <varlistentry>
79         <term>y</term>
80
81         <listitem>
82           <para>scalar or array</para>
83         </listitem>
84       </varlistentry>
85     </variablelist>
86   </refsection>
87
88   <refsection>
89     <title>Description</title>
90
91     <para>For an array <literal>x</literal>,
92     <literal>y=cumprod(x)</literal> returns in the scalar <literal>y</literal> the
93     cumulative product of all the elements of <literal>x</literal>.</para>
94
95     <para><literal>y=cumprod(x,orientation)</literal> returns in
96     <literal>y</literal> the cumulative product of <literal>x</literal> along the
97     dimension given by <literal>orientation</literal>:</para>
98
99     <itemizedlist>
100  <listitem>
101         <para>if <literal>orientation</literal> is equal to 1 or "r" then</para>
102         <para><latex> <![CDATA[ y(\mathbf{l},j) = \prod_{\mathbf{i}=1}^l x(\mathbf{i},j)]]> </latex></para> 
103         <para>or </para> 
104         <para><latex> <![CDATA[ y(\mathbf{l},j,k,\ldots) = \prod_{\mathbf{i}=1}^l x(\mathbf{i},j,k,\ldots)]]> </latex> </para>
105       </listitem>
106       <listitem>
107         <para>Si <literal>orientation</literal>  est égal à  2 ou "c" alors:</para>
108         <para><latex><![CDATA[ y(i,\mathbf{l}) = \prod_{\mathbf{j}=1}^l x(i,{\mathbf{j})]]> </latex></para> 
109         <para> or </para> 
110         <para><latex><![CDATA[ y(i,\mathbf{l},k,\ldots) = \prod_{\mathbf{j}=1}^l x(i,\mathbf{j},k,\ldots)]]> </latex> </para>
111       </listitem>
112       <listitem>
113         <para>if <literal>orientation</literal> is equal to n  then</para>
114         <para><latex><![CDATA[ y(i_1,\ldots,i_{n-1},\mathbf{l},i_{n+1},\ldots) = \prod_{\mathbf{i_n}=1}^l x(i_1,\ldots,i_{n-1},\mathbf{i_n},i_{n+1},\ldots)]]> </latex> </para>
115       </listitem>
116       <listitem>
117         <para><literal>y=cumprod(x,"*")</literal> is equivalent to <literal>y=cumprod(x)</literal> </para>
118       </listitem>
119       <listitem>
120         <para><literal>y=cumprod(x,"m")</literal> is equivalent to
121         <literal>y=cumprod(x,orientation)</literal> where
122         <literal>orientation</literal> is the index of the
123         first dimension of  <literal>x</literal> that is greater than 1. This option is used for
124          Matlab compatibility.</para>
125       </listitem>
126     </itemizedlist>
127
128     <para></para>
129     <para>The <literal>outtype</literal>  argument rules the way the product is done:</para>
130     <itemizedlist>
131       <listitem>
132         <para>For arrays of floats, of polynomials, of rational
133         fractions, the evaluation is always done using floating points
134         computations. The <literal>"double"</literal> or <literal>"native"</literal> options are equivalent.</para>
135       </listitem>
136       <listitem>
137         <para>For arrays of integers,</para>
138         <para> if <literal>outtype="native"</literal> the evaluation is done using integer
139         computations (modulo 2^b, where b is the number of bits used),</para>
140          <para> if <literal>outtype="double"</literal> the evaluation is done using floating point
141         computations.</para>
142         <para>The default value is <literal>outtype="native"</literal>.</para>
143       </listitem>
144       <listitem>
145         <para>For arrays of booleans,</para>
146         <para> if <literal>outtype="native"</literal> the evaluation is done using boolean
147         computations ( + is replaced by |),</para>
148          <para> if <literal>outtype="double"</literal> the evaluation is done using floating point
149         computations (%t values are replaced by 1 and %f values by 0).</para>
150          <para>The default value is <literal>outtype="double"</literal>.</para>
151       </listitem>
152
153     </itemizedlist>
154   </refsection>
155
156   <refsection>
157     <title>Remark</title>
158     <para>This function applies, with identical rules to <link
159     linkend="sparse">sparse matrices</link> and <link
160     linkend="hypermat">hypermatrices</link>.</para>
161   </refsection>
162
163   <refsection>
164     <title>Examples</title>
165
166     <programlisting role="example"><![CDATA[ 
167 A=[1,2;3,4];
168 cumprod(A)
169 cumprod(A,1)
170
171 I=uint8([2 95 103;254 9 0])
172 cumprod(I) //native evaluation
173 cumprod(I,"double")
174 cumprod(I,2,"double")
175
176 s=poly(0,"s");
177 P=[s,%i+s;s^2,1];
178 cumprod(P),
179 cumprod(P,2)
180
181 B=[%t %t %f %f];
182 cumprod(B) //evaluation in float
183 cumprod(B,"native") //similar to or(B)
184  ]]></programlisting>
185   </refsection>
186
187   <refsection role="see also">
188 <title>See Also</title>
189     <simplelist type="inline">
190       <member><link linkend="prod">prod</link></member>
191       <member><link linkend="cumsum">cumsum</link></member>
192     </simplelist>
193   </refsection>
194 </refentry>