Revert "Update of messages"
[scilab.git] / scilab / modules / api_scilab / help / en_US / sparse_writing_api.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) 2009  - DIGITEO - Antoine ELIAS
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="Sparse_management_writing_API"
14           xml:lang="en" 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
21     <refnamediv>
22         <refname>Sparse writing (Scilab gateway)</refname>
23
24         <refpurpose>
25             How to write sparse matrix in a gateway.
26         </refpurpose>
27     </refnamediv>
28     <refsection>
29         <title>Description</title>
30         <para>This help describes how to add sparse matrix.</para>
31         <para>There are 2 types of functions which can be used to write in the memory of Scilab.</para>
32     </refsection>
33     <refsection>
34         <title>Create from existing data</title>
35         <programlisting><![CDATA[
36 int createSparseMatrix(int _iVar, int _iRows, int _iCols, int _iNbItem, int* _piNbItemRow, int* _piColPos, double* _pdblReal)
37 int createComplexSparseMatrix(int _iVar, int _iRows, int _iCols, int _iNbItem, int* _piNbItemRow, int* _piColPos, double* _pdblReal, double* _pdblImg)
38 ]]></programlisting>
39     </refsection>
40     <refsection>
41         <title>Parameters</title>
42         <variablelist>
43             <varlistentry>
44                 <term>_iVar</term>
45                 <listitem>
46                     <para>
47                         Position in the Scilab memory where you want to put the variable.
48                     </para>
49                 </listitem>
50             </varlistentry>
51             <varlistentry>
52                 <term>_iRows</term>
53                 <listitem>
54                     <para>
55                         Number of rows of the new variable.
56                     </para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>_iCols</term>
61                 <listitem>
62                     <para>
63                         Number of columns of the new variable.
64                     </para>
65                 </listitem>
66             </varlistentry>
67             <varlistentry>
68                 <term>_iNbItem</term>
69                 <listitem>
70                     <para>
71                         Number of non zero itmes in the sparse.
72                     </para>
73                 </listitem>
74             </varlistentry>
75             <varlistentry>
76                 <term>_piNbItemRow</term>
77                 <listitem>
78                     <para>
79                         Number of item in each rows (size: _iRows).
80                     </para>
81                 </listitem>
82             </varlistentry>
83             <varlistentry>
84                 <term>_piColPos</term>
85                 <listitem>
86                     <para>
87                         Column position for each item (size: _iNbItem).
88                     </para>
89                 </listitem>
90             </varlistentry>
91             <varlistentry>
92                 <term>_pdblReal</term>
93                 <listitem>
94                     <para>
95                         Address of real data array (size: _iNbItem).
96                     </para>
97                 </listitem>
98             </varlistentry>
99             <varlistentry>
100                 <term>_pdblImg</term>
101                 <listitem>
102                     <para>
103                         Address of imaginary data array (size: _iNbItem).
104                     </para>
105                 </listitem>
106             </varlistentry>
107         </variablelist>
108     </refsection>
109     <refsection>
110         <title>Write directly in Scilab memory</title>
111         <programlisting><![CDATA[
112 int allocSparseMatrix(int _iVar, int _iRows, int _iCols, int _iNbItem, int** _piNbItemRow, int** _piColPos, double** _pdblReal)
113 int allocComplexSparseMatrix(int _iVar, int _iRows, int _iCols, int _iNbItem, int** _piNbItemRow, int** _piColPos, double** _pdblReal, double** _pdblImg)
114 ]]></programlisting>
115     </refsection>
116     <refsection>
117         <title>Parameters</title>
118         <variablelist>
119             <varlistentry>
120                 <term>_iVar</term>
121                 <listitem>
122                     <para>
123                         Position in the Scilab memory where you want to put the variable.
124                     </para>
125                 </listitem>
126             </varlistentry>
127             <varlistentry>
128                 <term>_iRows</term>
129                 <listitem>
130                     <para>
131                         Number of rows of the new variable.
132                     </para>
133                 </listitem>
134             </varlistentry>
135             <varlistentry>
136                 <term>_iCols</term>
137                 <listitem>
138                     <para>
139                         Number of columns of the new variable.
140                     </para>
141                 </listitem>
142             </varlistentry>
143             <varlistentry>
144                 <term>_iNbItem</term>
145                 <listitem>
146                     <para>
147                         Number of non zero itmes in the sparse.
148                     </para>
149                 </listitem>
150             </varlistentry>
151             <varlistentry>
152                 <term>_piNbItemRow</term>
153                 <listitem>
154                     <para>
155                         Return address of number of item in each rows (size: _iRows).
156                     </para>
157                 </listitem>
158             </varlistentry>
159             <varlistentry>
160                 <term>_piColPos</term>
161                 <listitem>
162                     <para>
163                         Return address of column position for each item (size: _iNbItem).
164                     </para>
165                 </listitem>
166             </varlistentry>
167             <varlistentry>
168                 <term>_pdblReal</term>
169                 <listitem>
170                     <para>
171                         Reddurn address of real data array (size: _iNbItem).
172                     </para>
173                 </listitem>
174             </varlistentry>
175             <varlistentry>
176                 <term>_pdblImg</term>
177                 <listitem>
178                     <para>
179                         Address of imaginary data array (size: _iNbItem).
180                     </para>
181                 </listitem>
182             </varlistentry>
183         </variablelist>
184     </refsection>
185     <refsection>
186         <!--File_gateway: SCI/modules/core/tests/unit_tests/sparse_writing_api.c-->
187         <!--File_scilab: SCI/modules/core/tests/unit_tests/sparse_writing_api.tst-->
188         <!--Lib_name: sparse_writing-->
189         <!--Func_list: write_sparse-->
190         <title>Gateway Source</title>
191         <programlisting role="code_gateway">
192             <![CDATA[
193 int write_sparse(char *fname,unsigned long fname_len)
194 {
195     int iRet                = 0;
196
197     int piNbItemRow[]       = {1,2,1};
198     int piColPos[]          = {8,4,7,2};
199     double pdblSReal[]      = {1,2,3,4};
200     double pdblSImg[]       = {4,3,2,1};
201     int iNbItem             = 4;
202     
203     iRet = createComplexSparseMatrix(Rhs + 1, 3, 10, iNbItem, piNbItemRow, piColPos, pdblSReal, pdblSImg);
204     if(iRet)
205     {
206         return 1;
207     }
208
209     LhsVar(1) = 1;
210     return 0;
211 }
212         ]]>
213         </programlisting>
214     </refsection>
215
216     <refsection>
217         <title>Scilab test script</title>
218         <programlisting role="code_scilab">
219             <![CDATA[
220 sp_ref = sparse([1,8;2,4;2,7;3,2],[1+4*%i,2+3*%i,3+2*%i,4+%i], [3,10]);
221 sp = tonio();
222 if or(sp <> sp_ref) then error("failed"), end
223             ]]>
224         </programlisting>
225     </refsection>
226 </refentry>