Fix rubberbox coordinates
[scilab.git] / scilab / modules / xcos / help / en_US / scilab_data_structures / blocks / scicos_model.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scicos
4  * 
5  * Copyright (C) INRIA - METALAU Project <scicos@inria.fr> (HTML version)
6  * Copyright (C) DIGITEO - Scilab Consortium (XML Docbook version)
7  * 
8  * This program is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU General Public License as published by
10  * the Free Software Foundation; either version 2 of the License, or
11  *  (at your option) any later version.
12  * 
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  * 
18  * You should have received a copy of the GNU General Public License
19  * along with this program; if not, write to the Free Software
20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
21  * 
22  * See the file ./license.txt
23  -->
24 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="scicos_model">
25     <refnamediv>
26         <refname>scicos_model</refname>
27         <refpurpose>Define a model structure</refpurpose>
28     </refnamediv>
29     <refsection id="Module_scicos_model">
30         <title>Module</title>
31         <itemizedlist>
32             <listitem>
33                 <para>
34                     <link linkend="xcos">xcos</link>
35                 </para>
36             </listitem>
37         </itemizedlist>
38     </refsection>
39     <refsection id="model_scicos_model">
40         <title>model</title>
41         <para>
42             Scilab list that contains the features
43             of the block used for the compilation.
44         </para>
45         <para>
46         </para>
47         <para>
48         </para>
49         <para>
50             Size : 23.
51         </para>
52         <para>
53             Type : Scilab list.
54         </para>
55         <para>
56             
57         </para>
58         <itemizedlist>
59             <listitem>
60                 <para>
61                     <emphasis role="bold">sim</emphasis>
62                 </para>
63                 <para> A list containing two elements. The first element is a string containing the name of the computational function (C, Fortran,or Scilab). The second element is an integer specifying the type of the computational function. Currently type 4 and 5 are used, but older types continue to work to ensure backward compatibility.</para>
64                 <para> For some older case, sim can be a single string and that means that the type is supposed to be 0.</para>
65                 <para> 
66                     Size : 2.
67                 </para>
68                 <para>
69                     Type : Scilab list.
70                 </para>
71             </listitem>
72             <listitem>
73                 <para>
74                     <emphasis role="bold">in</emphasis>
75                 </para>
76                 <para> A vector specifying the number and size of the first dimension of regular input ports indexed from top to bottom of the block. If no input port exist in==[].</para>
77                 <para> 
78                     The size can be negative, equal to zero or positive :
79                     
80                     
81                 </para>
82                 <itemizedlist>
83                     <listitem>
84                         <para>If a size is less than zero, the compiler will
85                             try to find the appropriate size.
86                         </para>
87                         <para>
88                             
89                         </para>
90                     </listitem>
91                     <listitem>
92                         <para>If a size is equal to zero, the compiler will
93                             affect this dimension by added all positive size
94                             found in that vector
95                             
96                             
97                         </para>
98                     </listitem>
99                     <listitem>
100                         <para>If a size is greater than zero, then the size is
101                             explicitly given.
102                         </para>
103                         <para>
104                         </para>
105                         <para>           
106                         </para>
107                     </listitem>
108                 </itemizedlist>
109                 <para> 
110                     Size : number of regular input ports.
111                 </para>
112                 <para>
113                     Type : column vector of integer numbers.
114                 </para>
115             </listitem>
116             <listitem>
117                 <para>
118                     <emphasis role="bold">in2</emphasis>
119                 </para>
120                 <para> A vector specifying the second dimension of regular input ports indexed from top to bottom of the block.</para>
121                 <para> in with in2 formed then the regular input sizes matrix.</para>
122                 <para> For compatibility, this dimension can stay empty ([]).</para>
123                 <para> That means that the dimensions of input ports will be in,1
124                     The size can be negative, equal to zero or positive :
125                     
126                     
127                 </para>
128                 <itemizedlist>
129                     <listitem>
130                         <para>If a size is less than zero, the compiler will
131                             try to find the appropriate size.
132                         </para>
133                         <para>
134                             
135                         </para>
136                     </listitem>
137                     <listitem>
138                         <para>If a size is equal to zero, the compiler will
139                             affect this dimension by added all positive size
140                             found in that vector.
141                         </para>
142                         <para>
143                             
144                         </para>
145                     </listitem>
146                     <listitem>
147                         <para>If a size is greater than zero, then the size is
148                             explicitly given.
149                         </para>
150                         <para>
151                         </para>
152                         <para>           
153                         </para>
154                     </listitem>
155                 </itemizedlist>
156                 <para> 
157                     Size : number of regular input ports.
158                 </para>
159                 <para>
160                     Type : column vector of integer numbers.
161                 </para>
162             </listitem>
163             <listitem>
164                 <para>
165                     <emphasis role="bold">intyp</emphasis>
166                 </para>
167                 <para> A vector specifying the types of regular input ports.</para>
168                 <para> Its sizes is equal to the sizes of in.</para>
169                 <para> The types of regular input ports can be :
170                     
171                 </para>
172                 <itemizedlist>
173                     <listitem>
174                         <para>1  real matrix,
175                         </para>
176                     </listitem>
177                     <listitem>
178                         <para>2  complex matrix,
179                         </para>
180                     </listitem>
181                     <listitem>
182                         <para>3  int32 matrix,
183                         </para>
184                     </listitem>
185                     <listitem>
186                         <para>4  int16 matrix,
187                         </para>
188                     </listitem>
189                     <listitem>
190                         <para>5  int8 matrix,
191                         </para>
192                     </listitem>
193                     <listitem>
194                         <para>6  uint32 matrix,
195                         </para>
196                     </listitem>
197                     <listitem>
198                         <para>7  uint16 matrix,
199                         </para>
200                     </listitem>
201                     <listitem>
202                         <para>8  uint8 matrix.
203                         </para>
204                         <para>
205                         </para>
206                         <para>           
207                         </para>
208                     </listitem>
209                 </itemizedlist>
210                 <para> 
211                     Size : number of regular input ports.
212                 </para>
213                 <para>
214                     Type : column vector of integer numbers.
215                 </para>
216             </listitem>
217             <listitem>
218                 <para>
219                     <emphasis role="bold">out</emphasis>
220                 </para>
221                 <para> 
222                     A vector specifying the number and size of the first
223                     dimension of regular output ports indexed from top to
224                     bottom of the block. If no output port exist out==[].
225                 </para>
226                 <para> 
227                     The size can be negative, equal to zero or positive :
228                     
229                     
230                 </para>
231                 <itemizedlist>
232                     <listitem>
233                         <para>If a size is less than zero, the compiler will
234                             try to find the appropriate size.
235                         </para>
236                         <para>
237                             
238                         </para>
239                     </listitem>
240                     <listitem>
241                         <para>If a size is equal to zero, the compiler will
242                             affect this dimension by added all positive size
243                             found in that vector
244                             
245                             
246                         </para>
247                     </listitem>
248                     <listitem>
249                         <para>If a size is greater than zero, then the size is
250                             explicitly given.
251                         </para>
252                         <para>
253                         </para>
254                         <para>           
255                         </para>
256                     </listitem>
257                 </itemizedlist>
258                 <para> 
259                     Size : number of regular output ports.
260                 </para>
261                 <para>
262                     Type : column vector of integer numbers.
263                 </para>
264             </listitem>
265             <listitem>
266                 <para>
267                     <emphasis role="bold">out2</emphasis>
268                 </para>
269                 <para> A vector specifying the second dimension of regular output ports indexed from top to bottom of the block.</para>
270                 <para> out with out2 formed then the regular output sizes matrix.</para>
271                 <para> For compatibility, this dimension can stay empty ([]). That means that the dimensions of output ports will be out,1
272                     That dimension can be negative, equal to zero or positive :
273                     
274                     
275                 </para>
276                 <itemizedlist>
277                     <listitem>
278                         <para>If a size is less than zero, the compiler will
279                             try to find the appropriate size.
280                         </para>
281                         <para>
282                             
283                         </para>
284                     </listitem>
285                     <listitem>
286                         <para>If a size is equal to zero, the compiler will
287                             affect this dimension by added all positive size
288                             found in that vector.
289                         </para>
290                         <para>
291                             
292                         </para>
293                     </listitem>
294                     <listitem>
295                         <para>If a size is greater than zero, then the size is
296                             explicitly given.
297                         </para>
298                         <para>
299                         </para>
300                         <para>           
301                         </para>
302                     </listitem>
303                 </itemizedlist>
304                 <para> 
305                     Size : number of regular output ports.
306                 </para>
307                 <para>
308                     Type : column vector of integer numbers.
309                 </para>
310             </listitem>
311             <listitem>
312                 <para>
313                     <emphasis role="bold">outtyp</emphasis>
314                 </para>
315                 <para> A vector specifying the types of regular output ports.</para>
316                 <para> Its sizes is equal to the sizes of out.</para>
317                 <para> The types of regular output ports can be :
318                     
319                 </para>
320                 <itemizedlist>
321                     <listitem>
322                         <para>1  real matrix,
323                         </para>
324                     </listitem>
325                     <listitem>
326                         <para>2  complex matrix,
327                         </para>
328                     </listitem>
329                     <listitem>
330                         <para>3  int32 matrix,
331                         </para>
332                     </listitem>
333                     <listitem>
334                         <para>4  int16 matrix,
335                         </para>
336                     </listitem>
337                     <listitem>
338                         <para>5  int8 matrix,
339                         </para>
340                     </listitem>
341                     <listitem>
342                         <para>6  uint32 matrix,
343                         </para>
344                     </listitem>
345                     <listitem>
346                         <para>7  uint16 matrix,
347                         </para>
348                     </listitem>
349                     <listitem>
350                         <para>8  uint8 matrix.
351                         </para>
352                         <para>
353                         </para>
354                         <para>           
355                         </para>
356                     </listitem>
357                 </itemizedlist>
358                 <para> 
359                     Size : number of regular output ports.
360                 </para>
361                 <para>
362                     Type : column vector of integer numbers.
363                 </para>
364             </listitem>
365             <listitem>
366                 <para>
367                     <emphasis role="bold">evtin</emphasis>
368                 </para>
369                 <para> A vector specifying the number and sizes of activation inputs. Currently activation ports can be only of size one.</para>
370                 <para> If no event input port exists evtin must be equal to [].</para>
371                 <para> 
372                     Size : number of input event ports.
373                 </para>
374                 <para>
375                     Type : column vector of integer numbers.
376                 </para>
377             </listitem>
378             <listitem>
379                 <para>
380                     <emphasis role="bold">evtout</emphasis>
381                 </para>
382                 <para> A vector specifying the number and sizes of activation outputs.</para>
383                 <para> Currently activation ports can be only of size one.</para>
384                 <para> If no event output port exists evtout must be equal to [].</para>
385                 <para> 
386                     Size : number of output event ports.
387                 </para>
388                 <para>
389                     Type : column vector of integer numbers.
390                 </para>
391             </listitem>
392             <listitem>
393                 <para>
394                     <emphasis role="bold">state</emphasis>
395                 </para>
396                 <para> Vector containing initial values of continuous-time state.</para>
397                 <para> Must be [] if no continuous state.</para>
398                 <para> 
399                     Size : number of continuous-time state.
400                 </para>
401                 <para>
402                     Type : column vector of real numbers.
403                 </para>
404             </listitem>
405             <listitem>
406                 <para>
407                     <emphasis role="bold">dstate</emphasis>
408                 </para>
409                 <para> Vector containing initial values of discrete-time state.</para>
410                 <para> Must be [] if no discrete state.</para>
411                 <para> 
412                     Size : number of discrete-time state.
413                 </para>
414                 <para>
415                     Type : column vector of real numbers.
416                 </para>
417             </listitem>
418             <listitem>
419                 <para>
420                     <emphasis role="bold">odstate</emphasis>
421                 </para>
422                 <para> List containing initial values of objects state.</para>
423                 <para> Must be list() if no objects state.</para>
424                 <para> 
425                     Objects state can be any types of scilab variable.
426                 </para>
427                 <para>
428                     In the computational function case of type 4 (C blocks)
429                     only elements containing matrix of real, complex,
430                     int32, int16 ,int8 ,uint32, uit16 and uint8 will be correctly
431                     provided for readind/writing.
432                 </para>
433                 <para>
434                 </para>
435                 <para> 
436                     Size : number of objects state.
437                 </para>
438                 <para>
439                     Type : scilab list of scilab objects.
440                 </para>
441             </listitem>
442             <listitem>
443                 <para>
444                     <emphasis role="bold">rpar</emphasis>
445                 </para>
446                 <para> The vector of floating point block parameters.</para>
447                 <para> Must be [] if no floating point parameters.</para>
448                 <para> 
449                     Size : number of real parameters.
450                 </para>
451                 <para>
452                     Type : column vector of real numbers.
453                 </para>
454             </listitem>
455             <listitem>
456                 <para>
457                     <emphasis role="bold">ipar</emphasis>
458                 </para>
459                 <para> The vector of integer block parameters.</para>
460                 <para> Must be [] if no integer parameters.</para>
461                 <para> 
462                     Size : number of integer parameters.
463                 </para>
464                 <para>
465                     Type : column vector of integer numbers.
466                 </para>
467             </listitem>
468             <listitem>
469                 <para>
470                     <emphasis role="bold">opar</emphasis>
471                 </para>
472                 <para> List of objects block parameters. Must be list() if no objects parameters.</para>
473                 <para> 
474                     Objects parameters can be any types of scilab variable.
475                 </para>
476                 <para>
477                     In the computational function case of type 4 (C blocks)
478                     only elements containing matrix of real, complex,
479                     int32, int16 ,int8 ,uint32, uit16 and uint8 will be correctly
480                     provided for reading.
481                 </para>
482                 <para>
483                 </para>
484                 <para> 
485                     Size : number of objetcs parameters.
486                 </para>
487                 <para>
488                     Type : list of scilab object.
489                 </para>
490             </listitem>
491             <listitem>
492                 <para>
493                     <emphasis role="bold">blocktype</emphasis>
494                 </para>
495                 <para> Character that can be set to 'c' or 'd' indifferently for standard blocks. 'x' is used if we want to force the computational function to be called during the simulation phase even if the block does not contribute to computation of the state derivative.</para>
496                 <para> 'l', 'm' and 's' are reserved. Not to be used.</para>
497                 <para> 
498                     Size : 1.
499                 </para>
500                 <para>
501                     Type : Character.
502                 </para>
503             </listitem>
504             <listitem>
505                 <para>
506                     <emphasis role="bold">firing</emphasis>
507                 </para>
508                 <para> Vector of initial event firing times of size equal to the number of activation output ports (see evout). It contains output initial event dates (Events generated before any input event arises). Negative values stands for no initial event on the corresponding port.
509                     Size : number of output event ports.
510                 </para>
511                 <para>
512                     Type : column vector of real numbers.
513                 </para>
514             </listitem>
515             <listitem>
516                 <para>
517                     <emphasis role="bold">dep_ut</emphasis>
518                 </para>
519                 <para> Boolean vector [dep_u, dep_t].</para>
520                 <para> 
521                     
522                 </para>
523                 <itemizedlist>
524                     <listitem>
525                         <para>
526                             <emphasis role="bold">dep_t</emphasis>
527                         </para>
528                         <para>
529                             true if block is always active.
530                         </para>
531                         <para>
532                             Output depends continuously of the time.
533                             For instance, the GENSIN_f block computes <code>y=sin(t)</code> so <code>dep_ut=[%f %t]</code>.
534                         </para>
535                     </listitem>
536                     <listitem>
537                         <para>
538                             <emphasis role="bold">dep_u</emphasis>
539                         </para>
540                         <para>
541                             true if block has direct feed-through,
542                             i.e., at least one of the outputs depends
543                             directly (not through the states) on one
544                             of the inputs.   
545                             In other words, when the computational
546                             function is called with flag 1, the value 
547                             of an input is used to compute the output.
548                             For instance, the SUM_f block computes <code>y=u1+u2</code> so <code>dep_ut=[%t %f]</code>.
549                         </para>
550                         <para>
551                         </para>
552                         <para>           
553                         </para>
554                     </listitem>
555                 </itemizedlist>
556                 <para> 
557                     Size : 2.
558                 </para>
559                 <para>
560                     Type : Boolean vector.
561                 </para>
562             </listitem>
563             <listitem>
564                 <para>
565                     <emphasis role="bold">label</emphasis>
566                 </para>
567                 <para> String that defines a label. It can be used to identify a block in order to access or modify its parameters during simulation.</para>
568                 <para> 
569                     Size : 1.
570                 </para>
571                 <para>
572                     Type : string.
573                 </para>
574             </listitem>
575             <listitem>
576                 <para>
577                     <emphasis role="bold">nzcross</emphasis>
578                 </para>
579                 <para> Number of zero-crossing surfaces.</para>
580                 <para> 
581                     Size : Number of zero-crossing surfaces.
582                 </para>
583                 <para>
584                     Type : column vector of integer numbers.
585                 </para>
586             </listitem>
587             <listitem>
588                 <para>
589                     <emphasis role="bold">nmode</emphasis>
590                 </para>
591                 <para> Length of the mode register. Note that this gives the size of the vector mode and not the total number of modes in which a block can operate in. Suppose a block has 3 modes and each mode can take two values, then the block can have up to 23=8 modes.</para>
592                 <para> 
593                     Size : Number of modes.
594                 </para>
595                 <para>
596                     Type : column vector of integer numbers.
597                 </para>
598             </listitem>
599             <listitem>
600                 <para>
601                     <emphasis role="bold">equations</emphasis>
602                 </para>
603                 <para> Used in case of implicit blocks.</para>
604                 <para> Data structure of type modelica which contains modelica code description if any. That list contains four entries :
605                     
606                 </para>
607                 <itemizedlist>
608                     <listitem>
609                         <para>
610                             <emphasis role="bold">model</emphasis>
611                         </para>
612                         <para>
613                             a string given the name of the file that contains
614                             the modelica function.
615                         </para>
616                         <para>
617                             
618                         </para>
619                     </listitem>
620                     <listitem>
621                         <para>
622                             <emphasis role="bold">inputs</emphasis>
623                         </para>
624                         <para>
625                             a colunm vector of strings that contains the names of
626                             the modelica variables used as inputs.
627                         </para>
628                         <para>
629                             
630                         </para>
631                     </listitem>
632                     <listitem>
633                         <para>
634                             <emphasis role="bold">outputs</emphasis>
635                         </para>
636                         <para>
637                             a colunm vector of strings that contains the names of
638                             the modelica variables used as outputs.
639                         </para>
640                         <para>
641                             
642                         </para>
643                     </listitem>
644                     <listitem>
645                         <para>
646                             <emphasis role="bold">parameters</emphasis>
647                         </para>
648                         <para>
649                             a list with two entries. The first is a vector of strings
650                             for the name of modelica variable names used as parameters
651                             and the second entries is a list that contains the value of
652                             parameters.
653                         </para>
654                         <para>
655                             Names of modelica states can also be informed with
656                             parameters. In that case a third entry is used to do the
657                             difference between parameters and states.
658                         </para>
659                         <para>
660                             For i,e :
661                             mo.parameters=list(['C','v'],list(C,v),[0,1])
662                             means that 'C' is a parameter(0) of value C, and 'v'
663                             is a state(1) with initial value v.
664                         </para>
665                         <para>
666                         </para>
667                         <para>           
668                         </para>
669                     </listitem>
670                 </itemizedlist>
671                 <para> 
672                     Size : 5.
673                 </para>
674                 <para>
675                     Type : scilab list.
676                 </para>
677             </listitem>
678             <listitem>
679                 <para>
680                     <emphasis role="bold">uid</emphasis>
681                 </para>
682                 <para>Unique identifier string of the block (2^16 per host)</para>
683                 <para>This identifier will be only set using the Xcos GUI. To set a specific value at bloc allocation, use the following code:</para>
684                 <programlisting role="example">
685                     jimport("java.rmi.server.UID");
686                     juid =  jnewInstance("java.rmi.server.UID");
687                     uid = juid.toString()
688                 </programlisting>
689                 <para> 
690                     Size : 1x1.
691                 </para>
692                 <para>
693                     Type : String.
694                 </para>
695             </listitem>
696         </itemizedlist>
697     </refsection>
698     <refsection id="Filecontent_scicos_model">
699         <title>File content</title>
700         <itemizedlist>
701             <listitem>
702                 <para> SCI/modules/scicos/macros/scicos_scicos/scicos_model.sci</para>
703             </listitem>
704         </itemizedlist>
705     </refsection>
706 </refentry>