Xcos: add hooks pre/post simulation
[scilab.git] / scilab / modules / xcos / help / en_US / batch_functions / xcos_simulate.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <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" version="5.0-subset Scilab" xml:id="xcos_simulate">
3   <refnamediv>
4     <refname>xcos_simulate</refname>
5     <refpurpose>Function for running xcos simulation in batch mode</refpurpose>
6   </refnamediv>
7   <refsynopsisdiv>
8     <title>Calling Sequence</title>
9     <synopsis>Info=xcos_simulate(scs_m, needcompile)</synopsis>
10   </refsynopsisdiv>
11   <refsection id="Parameters_xcos_simulate">
12     <title>Arguments</title>
13     <variablelist>
14       <varlistentry>
15         <term>scs_m</term>: A diagram data structure (see <link linkend="scicos_diagram">scs_m structure</link>).
16         <para/>
17       </varlistentry>
18       <varlistentry>
19         <term>needcompile</term>: An integer. If it equals 4,
20         then the simulator will perform a complete compilation of the diagram.
21         If not, it will use cached value of %cpr. DEPRECATED
22       </varlistentry>
23     </variablelist>
24   </refsection>
25   <refsection id="Module_xcos_simulate">
26     <title>Module</title>
27     <itemizedlist>
28       <listitem>
29         <para>
30           <link linkend="xcos">xcos</link>
31         </para>
32       </listitem>
33     </itemizedlist>
34   </refsection>
35   <refsection id="Description_xcos_simulate">
36     <title>Description</title>
37     This function is used to simulate xcos diagrams in batch
38     mode. It requires the <link linkend="scicos_diagram">scs_m
39     structure</link>which can be obtained by loading in Scilab the
40     <literal>.xcos</literal> file (see <link linkend="importXcosDiagram">
41     importXcosDiagram</link>).
42
43     <para>
44       User can also define <literal>pre_xcos_simulate</literal>
45       function that will run before simulation.
46       <programlisting role="example"><![CDATA[
47       function continueSimulation = pre_xcos_simulate(scs_m, needcompile)
48       // Do nothing
49       continueSimulation = %t;
50       endfunction
51       ]]></programlisting>
52       If this function fails the error will be trapped and the simulation aborted.
53       If <literal>continueSimulation</literal> is set to false, the simulation will stop.
54     </para>
55     <para>
56       User can also define <literal>post_xcos_simulate</literal>
57       function that will run after simulation.
58       <programlisting role="example"><![CDATA[
59       function post_xcos_simulate(%cpr, scs_m, needcompile)
60       // Do Nothing
61       endfunction
62       ]]></programlisting>
63       If this function fails the error will be trapped.
64     </para>
65   </refsection>
66   <refsection id="Filecontent_xcos_simulate">
67     <title>File content</title>
68     <itemizedlist>
69       <listitem>
70         <para> SCI/modules/xcos/macros/xcos_simulate.sci</para>
71       </listitem>
72     </itemizedlist>
73   </refsection>
74   <refsection id="Examples_xcos_simulate">
75     <title>Examples</title>
76     <para>
77       The xcos diagram in <literal>SCI/modules/xcos/demos/batch_simulation.xcos</literal>
78       <mediaobject><imageobject><imagedata align="center" fileref="../../images/batch_simulation.png"/></imageobject></mediaobject>
79       Simulate this diagram in batch mode and change some context values.
80       <programlisting role="example"><![CDATA[
81       importXcosDiagram("SCI/modules/xcos/demos/batch_simulation.xcos")
82
83       typeof(scs_m) //The diagram data structure
84
85       //This diagram uses 3 context variables :
86       //  Amplitude : the sin function amplitude
87       //  Pulsation : the sin function pulsation
88       //  Tf        : the final simulation time
89       scs_m.props.context //the embedded definition
90
91       //first batch simulation with the parameters embedded in the diagram
92       xcos_simulate(scs_m, 4);
93
94       // Change the final time value
95       scs_m.props.context = ["Amplitude=2" "Pulsation=3" "Tf=10"];
96       xcos_simulate(scs_m, 4);
97
98       // Now Change pulsation
99       scs_m.props.context = ["Amplitude=2" "Pulsation=9" "Tf=10"];
100       xcos_simulate(scs_m, 4);
101       //get the variable created by the "from workspace block"
102       counter
103
104       ]]></programlisting>
105     </para>
106     <para>
107       Statistic analysis of the diagram using pre_xcos_simulate function.
108       <programlisting role="example"><![CDATA[
109 importXcosDiagram("SCI/modules/xcos/demos/batch_simulation.xcos")
110
111 typeof(scs_m) //The diagram data structure
112
113 // Declare pre_xcos_simulation to only analyze Diagram.
114
115 function continueSimulation=pre_xcos_simulate(scs_m, needcompile)
116     // Retrieve all objects
117     objs = scs_m.objs;
118
119     links = 0;
120     blocks = 0;
121     other = 0;
122     // Count Links and Blocks
123     for i = 1:size(objs)
124         currentType = typeof(objs(i));
125         select (currentType)
126         case "Link"
127             links = links + 1;
128         case "Block"
129             blocks = blocks + 1;
130         else
131             other = other + 1;
132         end
133     end
134
135         // Diplay Diagram analisys.
136         disp("Diagram Analysis:")
137         disp("Found "+string(blocks)+" Blocks.")
138         disp("Found "+string(links)+" Links.")
139         disp("Found "+string(other)+" Other component.")
140
141         // We do not want any simulation, just analyze Diagram
142         continueSimulation = %f;
143     endfunction
144
145     //first batch simulation with the parameters embedded in the diagram
146     xcos_simulate(scs_m, 4);
147       ]]></programlisting>
148     </para>
149     <para>
150       The xcos diagram: <literal>SCI/modules/xcos/demos/Command.xcos</literal>
151       <mediaobject><imageobject><imagedata align="center" fileref="../../images/Command.png"/></imageobject></mediaobject>
152       Simulate this diagram in batch mode and perform bode plotting of transfert function using post_xcos_simulate,
153       <programlisting role="example"><![CDATA[
154 importXcosDiagram("SCI/modules/xcos/demos/Command.xcos")
155
156 // Clear any pre_xcos_simulation;
157 clear pre_xcos_simulate;
158
159 function post_xcos_simulate(%cpr, scs_m, needcompile)
160     // Retrieve all objects
161     objs = scs_m.objs;
162
163     clrBlock = [];
164     //Looking for CLR block
165     for i=1:size(objs)
166         if objs(i).gui == "CLR" then
167             clrBlock = objs(i);
168             break;
169         end
170     end
171
172     // Check if we found some CLR
173     if isempty(clrBlock) then
174         disp("No CLR block found.")
175         return
176     end
177
178     // Retrieve exprs
179     exprs = clrBlock.graphics.exprs;
180     s = poly(0,'s');
181     num = eval(exprs(1));
182     den = eval(exprs(2));
183     h = syslin('c', num/den);
184     // Open new figure then plot Bode
185     scf(max(winsid())+1);
186     bode(h, 0.01, 100);
187 endfunction
188
189 xcos_simulate(scs_m, 4);
190
191       ]]></programlisting>
192     </para>
193    <para>
194       The xcos diagram: <literal>SCI/modules/xcos/demos/Command_bode.xcos</literal>
195       <mediaobject><imageobject><imagedata align="center" fileref="../../images/Command_bode.png"/></imageobject></mediaobject>
196       Simulate this diagram in batch mode and perform bode plotting of transfert function using post_xcos_simulate,
197       <programlisting role="example"><![CDATA[
198 importXcosDiagram("SCI/modules/xcos/demos/Command_bode.xcos")
199
200 // Clear any post_xcos_simulation;
201 clear post_xcos_simulate;
202
203 function continueSimulation = pre_xcos_simulate(scs_m, needcompile)
204     // Retrieve all objects
205     objs = scs_m.objs;
206
207     clrBlock = [];
208     //Looking for CLR block
209     for i=1:size(objs)
210         if objs(i).gui == "CLR" then
211             clrBlock = objs(i);
212             break;
213         end
214     end
215
216     // Check if we found some CLR
217     if isempty(clrBlock) then
218         disp("No CLR block found.")
219         return
220     end
221
222     // Retrieve exprs
223     exprs = clrBlock.graphics.exprs;
224     s = poly(0,'s');
225     num = eval(exprs(1));
226     den = eval(exprs(2));
227     h = syslin('c', num/den);
228     // Open new figure then plot Bode
229     scf(max(winsid())+1);
230     bode(h, 0.01, 100);
231
232     // Stop after bode plot. We do not want any simulation.
233     continueSimulation = %f;
234 endfunction
235
236 xcos_simulate(scs_m, 4);
237
238       ]]></programlisting>
239     </para>
240   </refsection>
241   <refsection id="SeeAlso_xcos_simulate">
242     <title>See Also</title>
243     <simplelist type="inline">
244       <member>
245         <link linkend="scicos_diagram">scs_m structure</link>
246       </member>
247       <member>
248         <link linkend="importXcosDiagram"> importXcosDiagram</link>
249       </member>
250       <member>
251         <link linkend="scicosim">scicosim: xcos batch simulation function</link>
252       </member>
253       <member>
254         <link linkend="xcos">xcos: Block diagram editor and GUI for the hybrid simulator</link>
255       </member>
256       <member>
257         <link linkend="steadycos">steadycos: Finds an equilibrium state of an xcos diagram</link>
258       </member>
259       <member>
260         <link linkend="lincos">lincos: Constructs by linearization a linear state-space model from an xcos diagram</link>
261       </member>
262     </simplelist>
263   </refsection>
264 </refentry>