Xcos help: add notes about the use of scicos_simulate
[scilab.git] / scilab / modules / xcos / help / en_US / batch_functions / scicos_simulate.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  * Copyright (C) INRIA - Serge Steer - (format standardized, context argument explained, example added)
8  * 
9  * This program is free software; you can redistribute it and/or modify
10  * it under the terms of the GNU General Public License as published by
11  * the Free Software Foundation; either version 2 of the License, or
12  *  (at your option) any later version.
13  * 
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17  * GNU General Public License for more details.
18  * 
19  * You should have received a copy of the GNU General Public License
20  * along with this program; if not, write to the Free Software
21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
22  * 
23  * See the file ./license.txt
24  -->
25 <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_simulate">
26     <refnamediv>
27         <refname>scicos_simulate</refname>
28         <refpurpose>Function for running xcos simulation in batch mode</refpurpose>
29     </refnamediv>
30     <refsynopsisdiv>
31         <title>Calling Sequence</title>
32         <synopsis>Info=scicos_simulate(scs_m)</synopsis>
33         <synopsis>Info=scicos_simulate(scs_m,Info)</synopsis>
34         <synopsis>Info=scicos_simulate(scs_m,context)</synopsis>
35         <synopsis>Info=scicos_simulate(scs_m,flag)</synopsis>
36         <synopsis>Info=scicos_simulate(scs_m ,Info [, context] [,flag])</synopsis>
37     </refsynopsisdiv>
38     <refsection id="Parameters_scicos_simulate">
39         <title>Arguments</title>
40         <variablelist>
41             <varlistentry>
42                 <term>scs_m</term>: A diagram data structure (see <link linkend="scicos_diagram">scs_m structure</link>).
43                 <para/>
44             </varlistentry>
45             <varlistentry>
46                 <term>Info</term>: A list. It must be set to <literal>list()</literal> at
47                 the first call, then use output <literal>Info</literal> as
48                 input <literal>Info</literal> for the next
49                 calls. <literal>Info</literal> contains compilation and
50                 simulation information and is used to avoid recompilation when
51                 not needed.
52                 <para/>
53             </varlistentry>
54             <varlistentry>
55                 <term>ContextValues</term>: A Scilab struct containing values of symbolic variables
56                 used in the context and xcos blocks.
57                 <para/>
58             </varlistentry>
59             <varlistentry>
60                 <term>flag</term>: A string. If it equals 'nw' (no window),
61                 then blocks using graphical windows are not executed. Note
62                 that the list of such blocks must be updated as new blocks are
63                 added.
64             </varlistentry>
65         </variablelist>
66     </refsection>
67     <refsection id="Module_scicos_simulate">
68         <title>Module</title>
69         <itemizedlist>
70             <listitem>
71                 <para>
72                     <link linkend="xcos">xcos</link>
73                 </para>
74             </listitem>
75         </itemizedlist>
76     </refsection>
77     <refsection id="Description_scicos_simulate">
78         <title>Description</title>
79         <para>
80             This function is used to simulate xcos diagrams in batch
81             mode. It requires the <link linkend="scicos_diagram">scs_m
82                 structure
83             </link>
84             which can be obtained by loading in Scilab the
85             <literal>.zcos</literal> file (see <link linkend="importXcosDiagram">
86                 importXcosDiagram
87             </link>
88             ).
89         </para>
90         <para>
91             Note that before being able to simulate you should first load the block library using <literal>loadXcosLibs()</literal>.
92         </para>
93         <para>
94             The <literal>ContextValues</literal> may be used to change
95             the main parameters value set in the main diagram
96             context. example: if the variable <literal>A</literal> is set to 1
97             in the main context of the diagram. One can change the
98             <literal>A</literal> value for a <literal>scicos_simulate</literal> simulation by setting
99             <programlisting role="example"><![CDATA[
100     ContextValues.A=2 
101     ]]></programlisting>
102         </para>
103         <para> It is also possible to use variables defined inside Scilab
104             directly without using the <literal>ContextValues</literal>
105             argument, but for such a use the context definition must allow
106             this: example, if one wants to allow simulation use the
107             <literal>A</literal> Scilab variable value for the parameter
108             <literal>A</literal> the diagram context definition should contain
109             <programlisting role="example"><![CDATA[
110     if ~exists('A') then  A=1,end
111     ]]></programlisting> Note that this second solution is
112             fragile because it rely on the current value of
113             <literal>A</literal> in Scilab.
114         </para>
115     </refsection>
116     <refsection id="Filecontent_scicos_simulate">
117         <title>File content</title>
118         <itemizedlist>
119             <listitem>
120                 <para> SCI/modules/scicos/macros/scicos_auto/scicos_simulate.sci</para>
121             </listitem>
122         </itemizedlist>
123     </refsection>
124     <refsection id="Examples_scicos_simulate">
125         <title>Examples</title>
126         <para>
127             The xcos diagram in <link type="scilab" linkend="scilab.xcos/xcos/demos/batch_simulation.zcos">SCI/modules/xcos/demos/batch_simulation.zcos</link>.
128             <mediaobject>
129                 <imageobject>
130                     <imagedata align="center" fileref="../../../demos/batch_simulation.zcos"/>
131                 </imageobject>
132             </mediaobject>
133         </para>
134         <programlisting role="example"><![CDATA[
135 // load the blocks library and the simulation engine
136 loadXcosLibs(); loadScicos();
137
138 importXcosDiagram("SCI/modules/xcos/demos/batch_simulation.zcos")
139
140 typeof(scs_m) //The diagram data structure
141
142 //This diagram uses 3 context variables : 
143 //  Amplitude : the sin function amplitude
144 //  Pulsation : the sin function pulsation
145 //  Tf        : the final simulation time
146 scs_m.props.context; //the embedded definition
147
148 //first batch simulation with the parameters embedded in the diagram 
149 scicos_simulate(scs_m);
150 // Change the final time value
151 Context.Tf=10;
152 scicos_simulate(scs_m,Context);
153 // without display
154 Context.Tf=10;
155 Context.Pulsation=9;
156 scicos_simulate(scs_m,list(),Context,'nw');
157 //get the variable created by the "from workspace block"
158 counter 
159
160     ]]></programlisting>
161     </refsection>
162     <refsection id="SeeAlso_scicos_simulate">
163         <title>See Also</title>
164         <simplelist type="inline">
165             <member>
166                 <link linkend="scicos_diagram">scs_m structure</link>
167             </member>
168             <member>
169                 <link linkend="importXcosDiagram">importXcosDiagram</link>
170             </member>
171             <member>
172                 <link linkend="loadXcosLibs">loadXcosLibs</link>
173             </member>
174             <member>
175                 <link linkend="scicosim">scicosim: xcos batch simulation function</link>
176             </member>
177             <member>
178                 <link linkend="xcos">xcos: Block diagram editor and GUI for the hybrid simulator</link>
179             </member>
180             <member>
181                 <link linkend="steadycos">steadycos: Finds an equilibrium state of a Xcos diagram</link>
182             </member>
183             <member>
184                 <link linkend="lincos">lincos: Constructs by linearization a linear state-space model from a Xcos diagram</link>
185             </member>
186         </simplelist>
187     </refsection>
188 </refentry>