License Header change: Removed the LICENSE_END before beta
[scilab.git] / scilab / modules / api_scilab / help / en_US / legacy / low_level_functions / poly_reading_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  * 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" 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" xmlns:scilab="http://www.scilab.org" xml:id="Polynomial_management_reading_API" xml:lang="en">
17     <refnamediv>
18         <refname>Polynomial reading (Scilab gateway)</refname>
19         <refpurpose>
20             How to read matrices of polynomials in a gateway.
21         </refpurpose>
22     </refnamediv>
23     <refsynopsisdiv>
24         <title>Calling Sequence</title>
25         <para>Input argument profile:</para>
26         <synopsis>SciErr getMatrixOfPoly(void* _pvCtx, int* _piAddress, int* _piRows, int* _piCols, int* _piNbCoef, double** _pdblReal)</synopsis>
27         <synopsis>SciErr getComplexMatrixOfPoly(void* _pvCtx, int* _piAddress, int* _piRows, int* _piCols, int* _piNbCoef, double** _pdblReal, double** _pdblImg)</synopsis>
28         <para>Named variable profile:</para>
29         <synopsis>SciErr readNamedMatrixOfPoly(void* _pvCtx, const char* _pstName, int* _piRows, int* _piCols, int* _piNbCoef, double** _pdblReal)</synopsis>
30         <synopsis>SciErr readNamedComplexMatrixOfPoly(void* _pvCtx, const char* _pstName, int* _piRows, int* _piCols, int* _piNbCoef, double** _pdblReal, double** _pdblImg)</synopsis>
31     </refsynopsisdiv>
32     <refsection>
33         <title>Arguments</title>
34         <variablelist>
35             <varlistentry>
36                 <term>_pvCtx</term>
37                 <listitem>
38                     <para>
39                         Scilab environment pointer, pass in "pvApiCtx" provided by api_scilab.h.
40                     </para>
41                 </listitem>
42             </varlistentry>
43             <varlistentry>
44                 <term>_piAddress</term>
45                 <listitem>
46                     <para>
47                         Address of the Scilab variable.
48                     </para>
49                 </listitem>
50             </varlistentry>
51             <varlistentry>
52                 <term>_pstName</term>
53                 <listitem>
54                     <para>
55                         Name of the variable for "named" functions.
56                     </para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>_piRows</term>
61                 <listitem>
62                     <para>
63                         Return number of rows.
64                     </para>
65                 </listitem>
66             </varlistentry>
67             <varlistentry>
68                 <term>_piCols</term>
69                 <listitem>
70                     <para>
71                         Return number of columns.
72                     </para>
73                 </listitem>
74             </varlistentry>
75             <varlistentry>
76                 <term>_piNbCoef</term>
77                 <listitem>
78                     <para>
79                         Return number of coefficient for each polynomial. (must be allocated)
80                     </para>
81                 </listitem>
82             </varlistentry>
83             <varlistentry>
84                 <term>_pdblReal</term>
85                 <listitem>
86                     <para>
87                         Address of array of double* with imaginary part of coefficient (size: _iCols * _iRows, must be allocated)
88                     </para>
89                 </listitem>
90             </varlistentry>
91             <varlistentry>
92                 <term>_pdblImg</term>
93                 <listitem>
94                     <para>
95                         Address of array of double* with imaginary part of coefficient (size: _iCols * _iRows, must be allocated)
96                     </para>
97                 </listitem>
98             </varlistentry>
99             <varlistentry>
100                 <term>SciErr</term>
101                 <listitem>
102                     <para>
103                         Error structure where is stored errors messages history and first error number.
104                     </para>
105                 </listitem>
106             </varlistentry>
107         </variablelist>
108     </refsection>
109     <refsection>
110         <title>Description</title>
111         <para>This help describes how matrix of polynomials can be handled through the Scilab API.</para>
112     </refsection>
113     <refsection>
114         <!--File_gateway: SCI/modules/api_scilab/tests/unit_tests/poly_reading_api.c-->
115         <!--File_scilab: SCI/modules/api_scilab/tests/unit_tests/poly_reading_api.tst-->
116         <!--Lib_name: poly_reading-->
117         <!--Func_list: read_poly-->
118         <title>Gateway Source</title>
119         <programlisting role="code_gateway"><![CDATA[ 
120 #include "api_scilab.h"
121 int read_poly(char *fname,void* pvApiCtx)
122 {
123         SciErr sciErr;
124         int i,j;
125         //variable info
126         int iRows                       = 0;
127         int iCols                       = 0;
128         int iVarLen                     = 0;
129         int* piAddr                     = NULL;
130         int* piNbCoef           = NULL;
131         double** pdblReal       = NULL;
132         double** pdblImg        = NULL;
133         char* pstVarname        = NULL;
134
135         //check input and output arguments
136     CheckInputArgument(pvApiCtx, 1, 1);
137     CheckOutputArgument(pvApiCtx, 1, 1);
138
139         sciErr = getVarAddressFromPosition(pvApiCtx, 1, &piAddr);
140         if(sciErr.iErr)
141         {
142                 printError(&sciErr, 0);
143                 return 0;
144         }
145
146         if(isVarComplex(pvApiCtx, piAddr) == FALSE)
147         {
148                 //Error
149                 return 0;
150         }
151
152         //get variable name length
153         sciErr = getPolyVariableName(pvApiCtx, piAddr, NULL, &iVarLen);
154         if(sciErr.iErr)
155         {
156                 printError(&sciErr, 0);
157                 return 0;
158         }
159
160         //alloc buff to receive variable name
161         pstVarname = (char*)malloc(sizeof(char) * (iVarLen + 1));//1 for null termination
162
163         //get variable name
164         sciErr = getPolyVariableName(pvApiCtx, piAddr, pstVarname, &iVarLen);
165         if(sciErr.iErr)
166         {
167                 printError(&sciErr, 0);
168                 return 0;
169         }
170
171         //First call: retrieve dimmension
172         sciErr = getComplexMatrixOfPoly(pvApiCtx, piAddr, &iRows, &iCols, NULL, NULL, NULL);
173         if(sciErr.iErr)
174         {
175                 printError(&sciErr, 0);
176                 return 0;
177         }
178
179         //alloc array of coefficient
180         piNbCoef = (int*)malloc(sizeof(int) * iRows * iCols);
181
182         //Second call: retrieve coefficient
183         sciErr = getComplexMatrixOfPoly(pvApiCtx, piAddr, &iRows, &iCols, piNbCoef, NULL, NULL);
184         if(sciErr.iErr)
185         {
186                 printError(&sciErr, 0);
187                 return 0;
188         }
189
190         //alloc arrays of data
191         pdblReal    = (double**)malloc(sizeof(double*) * iRows * iCols);
192         pdblImg     = (double**)malloc(sizeof(double*) * iRows * iCols);
193
194         for(i = 0 ; i < iRows * iCols ; i++)
195         {
196                 pdblReal[i] = (double*)malloc(sizeof(double) * piNbCoef[i]);
197                 pdblImg[i] = (double*)malloc(sizeof(double) * piNbCoef[i]);
198         }
199
200         //Third call: retrieve data
201         sciErr = getComplexMatrixOfPoly(pvApiCtx, piAddr, &iRows, &iCols, piNbCoef, pdblReal, pdblImg);
202         if(sciErr.iErr)
203         {
204                 printError(&sciErr, 0);
205                 return 0;
206         }
207
208         //Do something with Data
209         //Invert polynomials in the matrix and invert coefficients
210         for(i = 0 ; i < (iRows * iCols) / 2 ; i++)
211         {
212                 int iPos1                       = iRows * iCols - 1 - i;
213                 double* pdblSave        = NULL;
214                 int iNbCoefSave         = 0;
215                 //switch array of coefficient
216                 pdblSave                        = pdblReal[i];
217                 pdblReal[i]                     = pdblReal[iPos1];
218                 pdblReal[iPos1]         = pdblSave;
219                 pdblSave                        = pdblImg[i];
220                 pdblImg[i]                      = pdblImg[iPos1];
221                 pdblImg[iPos1]          = pdblSave;
222                 //switch number of coefficient
223                 iNbCoefSave                     = piNbCoef[i];
224                 piNbCoef[i]                     = piNbCoef[iPos1];
225                 piNbCoef[iPos1]         = iNbCoefSave;
226         }
227
228         //switch coefficient
229         for(i = 0 ; i < iRows * iCols ; i++)
230         {
231                 for(j = 0 ; j < piNbCoef[i] /2 ; j++)
232                 {
233                         int iPos2                       = piNbCoef[i] - 1 - j;
234                         double dblVal           = pdblReal[i][j];
235                         pdblReal[i][j]          = pdblReal[i][iPos2];
236                         pdblReal[i][iPos2]      = dblVal;
237                         dblVal                          = pdblImg[i][j];
238                         pdblImg[i][j]           = pdblImg[i][iPos2];
239                         pdblImg[i][iPos2]       = dblVal;
240                 }
241         }
242
243         sciErr = createComplexMatrixOfPoly(pvApiCtx, nbInputArgument(pvApiCtx) + 1, pstVarname, iRows, iCols, piNbCoef, pdblReal, pdblImg);
244         if(sciErr.iErr)
245         {
246                 printError(&sciErr, 0);
247                 return 0;
248         }
249
250         //free OS memory
251         free(pstVarname);
252         free(piNbCoef);
253         for(i = 0 ; i < iRows * iCols ; i++)
254         {
255                 free(pdblReal[i]);
256                 free(pdblImg[i]);
257         }
258         free(pdblReal);
259         free(pdblImg);
260         //assign allocated variables to Lhs position
261         AssignOutputVariable(pvApiCtx, 1) = nbInputArgument(pvApiCtx) + 1;
262         return 0;
263 }
264  ]]></programlisting>
265     </refsection>
266     <refsection>
267         <title>Scilab test script</title>
268         <programlisting role="code_scilab"><![CDATA[ 
269 coeff1 = [ ..
270 29*%i,22*%i,16*%i,11*%i,7*%i,30,23,17,12,8,-31*%i,-24*%i,-18*%i,-13*%i,-9*%i,32,25,19,14,10,-33*%i,-26*%i,-20*%i,-15*%i,0,34,27,21,0,0,0,-28*%i,0,0,0,36-35*%i,0,0,0,0; ..
271 4*%i,2*%i,%i,22,16,5,-3,0,-23*%i,-17*%i,-6*%i,0,0,24,18,0,0,0,-25*%i,-19*%i,0,0,0,26,20,0,0,0,-27*%i,-21*%i,0,0,0,28,0,0,0,0,0,0; ..
272 11,7,4,2,1,-12*%i,-8*%i,-5*%i,3*%i,0,13,9,6,0,0,-14*%i,-10*%i,0,0,0,15,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
273
274 x = poly(0, "x");
275 p1  = 1;
276 p2  = 2 * x + 3 * %i;
277 p3  = 4 * x**2 - 5 * %i * x + 6;
278 p4  = 7 * x**3 - 8 * %i * x**2 + 9 * x - 10 * %i;
279 p5  = 11 * x**4 - 12 * %i * x**3 + 13 * x**2 - 14 * %i * x + 15;
280 p6  = 16 * x**5 - 17 * %i * x**4 + 18 * x**3 - 19 * %i * x**2 + 20 * x  - 21 * %i;
281 p7  = 22 * x**6 - 23 * %i * x**5 + 24 * x**4 - 25 * %i * x**3 + 26 * x**2 - 27 * %i * x + 28;
282 p8  = %i;
283 p9  = 2 * %i * x - 3;
284 p10 = 4 * %i * x**2 + 5 * x - 6 * %i;
285 p11 = 7 * %i * x**3 + 8 * x**2 - 9 * %i * x + 10;
286 p12 = 11 * %i * x**4 + 12 * x**3 - 13 * %i * x**2 + 14 * x - 15 * %i;
287 p13 = 16 * %i * x**5 + 17 * x**4 - 18 * %i * x**3 + 19 * x**2 - 20 * %i * x  + 21;
288 p14 = 22 * %i * x**6 + 23 * x**5 - 24 * %i * x**4 + 25 * x**3 - 26 * %i * x**2 + 27 * x - 28 * %i;
289 p15 = 29 * %i * x**7 + 30 * x**6 - 31 * %i * x**5 + 32 * x**4 - 33 * %i * x**3 + 34 * x**2 - 35 * %i + 36;
290 p = [p1, p2, p3, p4, p5 ; p6, p7, p8, p9 ,p10 ; p11, p12, p13, p14, p15];
291
292 p1 = read_poly(p);
293 coeff2 = coeff(p1);
294 if or(coeff2 <> coeff1) then error("failed"), end
295  ]]></programlisting>
296     </refsection>
297 </refentry>