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