Add or format some examples in Xcos
[scilab.git] / scilab / modules / xcos / help / en_US / batch_functions / steadycos.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="steadycos">
25     <refnamediv>
26         <refname>steadycos</refname>
27         <refpurpose>Finds an equilibrium state of a general dynamical system described by a xcos diagram</refpurpose>
28     </refnamediv>
29     <refsynopsisdiv>
30         <title>Calling Sequence</title>
31         <synopsis>[X,U,Y,XP]=steadycos(scs_m,X,U,Y,Indx,Indu,Indy [,Indxp [,param ] ])</synopsis>
32     </refsynopsisdiv>
33     <refsection id="Module_steadycos">
34         <title>Module</title>
35         <itemizedlist>
36             <listitem>
37                 <para>
38                     <link linkend="xcos">xcos</link>
39                 </para>
40             </listitem>
41         </itemizedlist>
42     </refsection>
43     <refsection id="Description_steadycos">
44         <title>Description</title>
45         <para>
46             This function finds the steady state for a given system described by a xcos diagram or <link linkend="SUPER_f">sub-diagram</link>. The diagram should have <link linkend="IN_f">inputs</link> and <link linkend="OUT_f">outputs</link>.The steady state concern only the continuous-time dynamics.  
47         </para>
48     </refsection>
49     <refsection>
50         <title>Examples</title>
51         <programlisting role="example"><![CDATA[
52 // loading data
53 exec("SCI/modules/xcos/tests/unit_tests/PENDULUM_ANIM.sci");
54 exec("SCI/modules/xcos/tests/unit_tests/anim_pen.sci");
55 importXcosDiagram("SCI/modules/xcos/tests/unit_tests/pendulum_anim45.xcos");
56
57 // configure the context
58 M  = 10;
59 m  = 3;
60 l  = 3;
61 ph = 0.1;
62
63 // look for the specific sub-diagram to work on
64 for i=1:length(scs_m.objs)
65     if typeof(scs_m.objs(i))=="Block" & scs_m.objs(i).gui=="SUPER_f" then
66         scs_m = scs_m.objs(i).model.rpar;
67         break;
68     end
69 end
70
71 [X,U,Y,XP] = steadycos(scs_m,[],[],[],[],1,1:$);
72  ]]></programlisting>
73     </refsection>
74     <refsection id="Parameters_steadycos">
75         <title>Arguments</title>
76         <itemizedlist>
77             <listitem>
78                 <para>
79                     <emphasis role="bold">scs_m :</emphasis> a xcos data structure
80                 </para>
81             </listitem>
82             <listitem>
83                 <para>
84                     <emphasis role="bold">X:</emphasis> column vector. Continuous state. Can be set to [] if zero.
85                 </para>
86             </listitem>
87             <listitem>
88                 <para>
89                     <emphasis role="bold">U:</emphasis> column vector. Input. Can be set to [] if zero.
90                 </para>
91             </listitem>
92             <listitem>
93                 <para>
94                     <emphasis role="bold">Y:</emphasis> column vector. Output. Can be set to [] if zero.
95                 </para>
96             </listitem>
97             <listitem>
98                 <para>
99                     <emphasis role="bold">Indx :</emphasis> index of entries of X that are not fixed. If all can vary, set to 1:$
100                 </para>
101             </listitem>
102             <listitem>
103                 <para>
104                     <emphasis role="bold">Indu :</emphasis> index of entries of U that are not fixed. If all can vary, set to 1:$
105                 </para>
106             </listitem>
107             <listitem>
108                 <para>
109                     <emphasis role="bold">Indy :</emphasis> index of entries of Y that are not fixed. If all can vary, set to 1:$
110                 </para>
111             </listitem>
112             <listitem>
113                 <para>
114                     <emphasis role="bold">Indxp :</emphasis> index of entries of XP (derivative of x) that need not be zero. If all can vary, set to 1:$. Default [].
115                 </para>
116             </listitem>
117             <listitem>
118                 <para>
119                     <emphasis role="bold">param :</emphasis> list with two elements (default list(1.d-6,0)). param(1): scalar. Perturbation level for linearization; the following variation is used del([x;u])_i = param(1)+param(1)*1d-4*abs([x;u])_i. param(2): scalar. Time t.
120                 </para>
121             </listitem>
122             <listitem>
123                 <para>
124                     <emphasis role="bold">X:</emphasis> steady state X
125                 </para>
126             </listitem>
127             <listitem>
128                 <para>
129                     <emphasis role="bold">U:</emphasis> stationary input U
130                 </para>
131             </listitem>
132             <listitem>
133                 <para>
134                     <emphasis role="bold">Y:</emphasis> output corresponding to steady state found
135                 </para>
136             </listitem>
137             <listitem>
138                 <para>
139                     <emphasis role="bold">XP :</emphasis> derivative of the state corresponding to steady state found
140                 </para>
141             </listitem>
142         </itemizedlist>
143     </refsection>
144     <refsection id="Filecontent_steadycos">
145         <title>File content</title>
146         <itemizedlist>
147             <listitem>
148                 <para> SCI/modules/scicos/macros/scicos_auto/steadycos.sci</para>
149             </listitem>
150         </itemizedlist>
151     </refsection>
152     <refsection id="SeeAlso_steadycos">
153         <title>See Also</title>
154         <itemizedlist>
155             <listitem>
156                 <para>
157                     <link linkend="lincos">lincos - Constructs by linearization a linear state-space model from a general dynamical system described by a xcos diagram (Scilab Function)</link>
158                 </para>
159             </listitem>
160             <listitem>
161                 <para>
162                     <link linkend="scicos_simulate">scicos_simulate - Function for running xcos simulation in batch mode (Scilab Function)</link>
163                 </para>
164             </listitem>
165             <listitem>
166                 <para>
167                     <link linkend="xcos">xcos - Block diagram editor and GUI for the hybrid simulator (Scilab Function)</link>
168                 </para>
169             </listitem>
170         </itemizedlist>
171     </refsection>
172 </refentry>