* Bug 9130 fixed [doc]: SigBuilder page: missing parameters description
[scilab.git] / scilab / modules / xcos / help / en_US / palettes / Sources_pal / Sigbuilder.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) 2019 - Samuel GOUGEON
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"
26         xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
27         xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
28         xml:id="Sigbuilder" xml:lang="en_US">
29     <refnamediv>
30         <refname>Sigbuilder</refname>
31         <refpurpose>Signal creator/generator</refpurpose>
32     </refnamediv>
33     <refsection>
34         <title>Block Screenshot</title>
35         <inlinemediaobject>
36             <imageobject>
37                 <imagedata fileref="../../../../images/palettes/Sigbuilder.png" align="center"/>
38             </imageobject>
39         </inlinemediaobject>
40     </refsection>
41
42     <refsection id="Contents_Sigbuilder">
43         <title>Contents</title>
44         <itemizedlist>
45             <listitem>
46                 <xref linkend="Description_Sigbuilder">Description</xref>
47             </listitem>
48             <listitem>
49                 <xref linkend="Dialogbox_Sigbuilder">Parameters</xref>
50             </listitem>
51             <listitem>
52                 <xref linkend="Defaultproperties_Sigbuilder">Default properties</xref>
53             </listitem>
54             <listitem>
55                 <xref linkend="Interfacingfunction_Sigbuilder">Interfacing function</xref>
56             </listitem>
57             <listitem>
58                 <xref linkend="Sigbuilder">Compiled Super Block content</xref>
59             </listitem>
60         </itemizedlist>
61     </refsection>
62
63     <refsection id="Description_Sigbuilder">
64         <title>Description</title>
65         <para>
66             The Signal Builder block is a superblock containing a block whose output event
67             port is connected to its input event port. This event feedback gives
68             the possibility to generate events at discontinuous point of the
69             signal. The generated events automatically restart the numerical
70             solver and avoids numerical problems. The generated event is also made
71             available to the user for possible use. Remind that if higher
72             interpolation methods are used, the events are generated only at the
73             beginning and at the end of the signal.
74         </para>
75     </refsection>
76
77     <refsection id="Dialogbox_Sigbuilder">
78         <title>Parameters</title>
79         <inlinemediaobject>
80             <imageobject>
81                 <imagedata fileref="../../../../images/gui/Sigbuilder_gui.gif"
82                            align="center" style="float:right"/>
83                     <!-- align => Javahelp, style => Online -->
84             </imageobject>
85         </inlinemediaobject>
86         <itemizedlist>
87             <listitem>
88                 <para>
89                     <emphasis role="bold">Spline method (0…7)</emphasis> :
90                     Accepted values are 0, 1, 2, 3, 4, 5, 6 or 7. This parameter defines the spline
91                     method for interpolating the points. The Signal builder block computes a linear
92                     or a cubic spline or sub-spline <emphasis>S</emphasis> which interpolates the
93                     (x<subscript>i</subscript>,y<subscript>i</subscript>)
94                     points, i.e., we have
95                     S(x<subscript>i</subscript>) = y<subscript>i</subscript>
96                     for all <emphasis>i=1,…,n</emphasis>. Available methods are described here-below:
97                 </para>
98                 <para><!-- 0 -->
99                     <emphasis role="bold">0 : "Zero order method"</emphasis>.
100                     This method generates a piecewise constant signal. i.e., for
101                     t<subscript>i</subscript> ≤ t &lt; t<subscript>i+1</subscript>,
102                     y(t) = y<subscript>i</subscript>.
103                     This method is available for all data types.
104                 </para>
105                 <orderedlist>
106                     <listitem><!-- 1 -->
107                         <para>
108                             <emphasis role="bold">Linear method</emphasis>. This
109                             method generates a piecewise linear signal, i.e., for
110                                 t<subscript>i</subscript> ≤ t &lt; t<subscript>i+1</subscript>,
111                                 y(t) = y<subscript>i</subscript> +
112                                 (y<subscript>i+1</subscript> - y<subscript>i</subscript>)
113                                 (t - t<subscript>i</subscript>) /
114                                 (t<subscript>i+1</subscript> - t<subscript>i</subscript>).
115                         </para>
116                     </listitem>
117                     <listitem><!-- 2 -->
118                         <para>
119                             <emphasis role="bold">NATURAL method</emphasis>.
120                             The interpolation is done by passing 2-order polynomials between
121                             (x<subscript>i</subscript>, y<subscript>i</subscript>)
122                             and
123                             (x<subscript>i+1</subscript>, y<subscript>i+1</subscript>).
124                             The Derivative at
125                             (x<subscript>i</subscript>, y<subscript>i</subscript>)
126                             is identical for two adjacent polynomials. The derivative at
127                             (x<subscript>1</subscript>, y<subscript>1</subscript>)
128                             can be selected arbitrary: It is selected such that the sum of derivatives
129                             at all points be minimum. This condition provides a less fluctuated signal.
130                         </para>
131                     </listitem>
132                     <listitem><!-- 3 -->
133                         <para>
134                             <emphasis role="bold">NOT_A_KNOT method</emphasis>.
135                             The cubic spline is computed by using the following conditions
136                             (considering <emphasis>n</emphasis> points
137                             x<subscript>i</subscript>, …, x<subscript>n</subscript>) :
138                             <table align="center">
139                                 <tr><td>
140                                     S<superscript>(3)</superscript>
141                                         (x<subscript>2</subscript><superscript>-</superscript>)
142                                     =
143                                     S<superscript>(3)</superscript>
144                                         (x<subscript>2</subscript><superscript>+</superscript>)
145                                     </td>
146                                 </tr>
147                                 <tr><td>
148                                     S<superscript>(3)</superscript>
149                                         (x<subscript>n-1</subscript><superscript>-</superscript>)
150                                     =
151                                     S<superscript>(3)</superscript>
152                                         (x<subscript>n-1</subscript><superscript>+</superscript>)
153                                     </td>
154                                 </tr>
155                             </table>
156                         </para>
157                     </listitem>
158                     <listitem><!-- 4 -->
159                         <para>
160                             <emphasis role="bold">Periodic</emphasis>.
161                             A periodic cubic spline is computed (<emphasis>y</emphasis> must verify
162                             <emphasis>y<subscript>1</subscript>=y<subscript>n</subscript></emphasis>)
163                             by using the conditions:
164                             x<subscript>i</subscript>, …, x<subscript>n</subscript> :
165                             <table align="center">
166                                 <tr><td align="center">
167                                     S′(x<subscript>1</subscript>) = S′(x<subscript>n</subscript>)
168                                     </td>
169                                 </tr>
170                                 <tr><td align="center">
171                                     S″(x<subscript>1</subscript>) = S″(x<subscript>n</subscript>)
172                                     </td>
173                                 </tr>
174                             </table>
175                         </para>
176                         <para>
177                         In this case, the value of <emphasis>y<subscript>n</subscript></emphasis>
178                         is ignored and <emphasis>y<subscript>1</subscript></emphasis> is used instead.
179                         Note that, in order to generate a periodic signal, the
180                         <emphasis>Periodic</emphasis> flag must be activated.
181                         </para>
182                     </listitem>
183                     <listitem><!-- 5 -->
184                         <para>
185                             <emphasis role="bold">Monotone</emphasis>.
186                             In this case a sub-spline (<emphasis>S</emphasis> is only 1-continuously
187                             differentiable) is computed such that <emphasis>S</emphasis> is monotone
188                             on each interval:
189                             <itemizedlist>
190                                 <listitem>
191                                     if y<subscript>i</subscript> ≤ y<subscript>i+1</subscript> :
192                                     <emphasis>S</emphasis> is increasing on
193                                     [x<subscript>i</subscript>, x<subscript>i+1</subscript>]
194                                 </listitem>
195                                 <listitem>
196                                     Otherwise: <emphasis>S</emphasis> is decreasing on
197                                        [x<subscript>i</subscript>, x<subscript>i+1</subscript>]
198                                 </listitem>
199                             </itemizedlist>
200                         </para>
201                     </listitem>
202                     <listitem><!-- 6 -->
203                         <para>
204                             <emphasis role="bold">Clamped</emphasis>.
205                             In this case, the cubic spline <emphasis>S</emphasis> is computed by
206                             using the end points derivatives which are set to zero, i.e.
207                             <table align="center">
208                                 <tr><td>
209                                     S′(x<subscript>1</subscript>) = S′(x<subscript>n</subscript>) = 0
210                                 </td></tr>
211                             </table>
212                         </para>
213                     </listitem>
214                     <listitem><!-- 7 -->
215                         <para>
216                         <emphasis role="bold">Fast</emphasis>.
217                         In this case, a sub-spline is computed by using a simple local scheme
218                         for the derivative at <emphasis>x<subscript>i</subscript></emphasis>
219                         of the interpolation polynomial of [
220                         (x<subscript>i-1</subscript>, y<subscript>i-1</subscript>),
221                         (x<subscript>i</subscript>, y<subscript>i</subscript>),
222                         (x<subscript>i+1</subscript>, y<subscript>i+1</subscript>) ],
223                         except for the end points (derivative at these points are computed from
224                         the 3 left most points and the 3 right most points).
225                         </para>
226                     </listitem>
227                 </orderedlist>
228             </listitem>
229             <listitem>
230                 <para>
231                     <emphasis role="bold">x :</emphasis> Row or column vector of abscissae (X-axis),
232                     as decimal numbers. This vector can be also defined in the Scicos context.
233                     It can be specified by a Scilab expression.
234                 </para>
235             </listitem>
236             <listitem>
237                 <para>
238                     <emphasis role="bold">y :</emphasis> Row or column vector of ordinates (Y-axis),
239                     as decimal numbers. This vector can be also defined in the Scicos context.
240                     It can be specified by a Scilab expression.
241                 </para>
242             </listitem>
243             <listitem>
244                 <para>
245                     <emphasis role="bold">Periodic signal (y/n) </emphasis>: If <literal>y</literal>
246                     is selected, the created signal will be periodic with the period of
247                     <emphasis>t<subscript>n</subscript></emphasis>. Note that if the
248                     <emphasis>Periodic</emphasis> spline method is selected, the output signal
249                     will be a continuous signal. Otherwise, the signal will be discontinuous at
250                     endpoints.
251                 </para>
252             </listitem>
253             <listitem>
254                 <para>
255                     <emphasis role="bold">Launch graphical window (y/n) </emphasis>:
256                     If <literal>y</literal> is selected, clicking on the <literal>OK</literal>
257                     button opens a graphical window, in whch the user can edit data points:
258                     <table>
259                         <tr><td>Mouse left click on the window</td><td>:</td>
260                             <td>Adds a new data point</td>
261                         </tr>
262                         <tr><td>Mouse right click on the window</td><td>:</td>
263                             <td>Removes a data point.</td>
264                         </tr>
265                         <tr><td>Mouse left double-click on a data point</td><td>:</td>
266                             <td>Edits a point's coordinates</td>
267                         </tr>
268                         <tr><td>Mouse left button press/drag/release</td><td>:</td>
269                             <td>Moves a data point</td>
270                         </tr>
271                         <tr><td>Autoscale menu</td><td>:</td><td>
272                             Rescales the window to show all data points properly.</td>
273                         </tr>
274                         <tr><td>Spline/Method menu</td><td>:</td>
275                             <td>Selects the spline interpolation method.</td>
276                         </tr>
277                         <tr><td>Data/Clear menu</td><td>:</td>
278                             <td>Removes all data points.</td>
279                         </tr>
280                         <tr><td>Data/Data_Bounds menu</td><td>:</td>
281                             <td>Changes the window size.</td>
282                         </tr>
283                         <tr><td>Data/Load_from_text_file menu</td><td>:</td>
284                             <td>Reads data points from a text data file (using C data format).</td>
285                         </tr>
286                         <tr><td>Data/save_to_text_file menu</td><td>:</td>
287                             <td>Saves the data points to a text data file (using C data format).</td>
288                         </tr>
289                         <tr><td>Data/Load_from_excel menu</td><td>:</td>
290                             <td>Reads data from an excel file.</td>
291                         </tr>
292                         <tr><td>Data/Periodic_signal menu</td><td>:</td>
293                             <td>Specifies weather the created signal is periodic or not.
294                                 If the signal is not periodic, the signal stays constant beyond
295                                 <emphasis>t<subscript>n</subscript></emphasis>.
296                                 Otherwise it is clamped to
297                                 <emphasis>y<subscript>1</subscript></emphasis> at
298                                 <emphasis>t<subscript>n</subscript></emphasis>.
299                             </td>
300                         </tr>
301                         <tr><td>Standards/Functions menu</td><td>:</td>
302                             <td>Chooses a Sine, Sawtooth, Pulse, or random signal.</td>
303                         </tr>
304                         <tr><td>Exit/Help menu</td><td>:</td>
305                             <td>Short help on the graphic window commands.</td>
306                         </tr>
307                         <tr><td>Exit/Exit_without_save menu</td><td>:</td>
308                             <td>Closes the graphical window, discarding all modifications in data.</td>
309                         </tr>
310                         <tr><td>Exit/Exit_with_save menu</td><td>:</td>
311                             <td>Closes the graphical window and saving data points.</td>
312                         </tr>
313                     </table>
314                 </para>
315             </listitem>
316         </itemizedlist>
317     </refsection>
318
319     <refsection id="Defaultproperties_Sigbuilder">
320         <title>Default properties</title>
321         <itemizedlist>
322             <listitem>
323                 <para>
324                     <emphasis role="bold">always active:</emphasis> no
325                 </para>
326             </listitem>
327             <listitem>
328                 <para>
329                     <emphasis role="bold">direct-feedthrough:</emphasis> no
330                 </para>
331             </listitem>
332             <listitem>
333                 <para>
334                     <emphasis role="bold">zero-crossing:</emphasis> no
335                 </para>
336             </listitem>
337             <listitem>
338                 <para>
339                     <emphasis role="bold">mode:</emphasis> no
340                 </para>
341             </listitem>
342             <listitem>
343                 <para>
344                     <emphasis role="bold">regular outputs:</emphasis>
345                 </para>
346                 <para>
347                     <emphasis role="bold">- port 1 : size [-1,1] / type 1</emphasis>
348                 </para>
349             </listitem>
350             <listitem>
351                 <para>
352                     <emphasis role="bold">number/sizes of activation inputs:</emphasis> 0
353                 </para>
354             </listitem>
355             <listitem>
356                 <para>
357                     <emphasis role="bold">number/sizes of activation outputs:</emphasis> 1
358                 </para>
359             </listitem>
360             <listitem>
361                 <para>
362                     <emphasis role="bold">continuous-time state:</emphasis> no
363                 </para>
364             </listitem>
365             <listitem>
366                 <para>
367                     <emphasis role="bold">discrete-time state:</emphasis> no
368                 </para>
369             </listitem>
370             <listitem>
371                 <para>
372                     <emphasis role="bold">object discrete-time state:</emphasis> no
373                 </para>
374             </listitem>
375             <listitem>
376                 <para>
377                     <emphasis role="bold">name of computational function:</emphasis>
378                     <emphasis role="italic">csuper</emphasis>
379                 </para>
380             </listitem>
381         </itemizedlist>
382         <para/>
383     </refsection>
384
385     <refsection id="Interfacingfunction_Sigbuilder">
386         <title>Interfacing function</title>
387         <itemizedlist>
388             <listitem>
389                 <para> SCI/modules/scicos_blocks/macros/Sources/Sigbuilder.sci</para>
390             </listitem>
391         </itemizedlist>
392     </refsection>
393 </refentry>