[elementary_functions] linspace() c++ gateway gives tremendous speedup
[scilab.git] / scilab / modules / elementary_functions / help / en_US / elementarymatrices / linspace.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2008 - INRIA
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2016, 2018 - Samuel GOUGEON
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
19           xmlns:scilab="http://www.scilab.org" xml:id="linspace" xml:lang="en">
20     <refnamediv>
21         <refname>linspace</refname>
22         <refpurpose>generates linearly spaced numbers between 2 reached bounds</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             row = linspace(x1, x2)
28             row = linspace(x1, x2, n)
29             Matrix = linspace(Col1, Col2)
30             Matrix = linspace(Col1, Col2, n)
31         </synopsis>
32     </refsynopsisdiv>
33     <refsection>
34         <title>Arguments</title>
35         <variablelist>
36             <varlistentry>
37                 <term>x1, x2</term>
38                 <listitem>
39                     <para>
40                         Real or complex scalars, or encoded integer scalars:
41                         Bounds between which values must be generated.
42                     </para>
43                 </listitem>
44             </varlistentry>
45             <varlistentry>
46                 <term>Col1, Col2</term>
47                 <listitem>
48                     <para>
49                         Column vectors of real or complex numbers, or of encoded integers,
50                         of same heights.
51                     </para>
52                 </listitem>
53             </varlistentry>
54             <varlistentry>
55                 <term>n</term>
56                 <listitem>
57                     <para>
58                         integer number of requested values or columns.
59                         Default value: 100
60                     </para>
61                 </listitem>
62             </varlistentry>
63             <varlistentry>
64                 <term>row</term>
65                 <listitem>
66                     <para>
67                         row vector of <literal>n</literal> numbers.
68                     </para>
69                 </listitem>
70             </varlistentry>
71             <varlistentry>
72                 <term>Matrix</term>
73                 <listitem>
74                     <para>
75                         Matrix with <literal>n</literal> columns of numbers.
76                     </para>
77                 </listitem>
78             </varlistentry>
79         </variablelist>
80     </refsection>
81     <refsection>
82         <title>Description</title>
83         <para>
84             <literal>linspace(x1, x2)</literal>
85             generates a row vector of <literal>n</literal> equally spaced
86             values ranging exactly from <literal>x1</literal> to <literal>x2</literal>.
87         </para>
88         <note>
89             <para>
90                 The syntax <literal>y1:y2</literal> or <literal>y1:step:y2</literal>
91                 like <literal>1:0.1:%pi</literal> does the same but fixes the
92                 starting bound <literal>y1</literal> and
93                 <emphasis role="bold">the step</emphasis>. The <literal>y2</literal>
94                 is used as stopping bound to not be overstepped. The last value
95                 actually generated may not reach it.
96                 <literal>y2</literal> is then not included in the result.
97             </para>
98             <para>
99                 Instead of fixing the step to a given value, <literal>linspace</literal>
100                 fixes the final bound <literal>x2</literal> to be exactly
101                 <emphasis role="bold">reached</emphasis>, and computes the step
102                 accordingly.
103             </para>
104         </note>
105         <para>
106             If <literal>x1</literal> or <literal>x2</literal> are complex numbers,
107             then <literal>linspace(x1,x2)</literal> interpolates separately the real and
108             the imaginary parts of <literal>x1</literal> and <literal>x2</literal>.
109         </para>
110         <para>
111             If some column vectors <literal>Col1</literal> and <literal>Col2</literal>
112             are provided, <literal>linspace</literal> works in a row-wise way:
113             the resulting <literal>Matrix</literal> has the same number of rows,
114             and <literal>n</literal> columns. We get
115             <literal>Matrix(i,:) = linspace(Col1(i), Col2(i), n)</literal>.
116         </para>
117         <warning>
118             When specified bounds are encoded integers, the actual step may vary by one unit
119             along the generated series.
120         </warning>
121     </refsection>
122     <refsection>
123         <title>Examples</title>
124         <programlisting role="example"><![CDATA[
125 linspace(1, %pi, 0)         // n = 0
126 linspace(1, 2, 10)          // x2 > x1 : increasing values
127 linspace(2, 1, 10)          // x2 < x1 : decreasing values
128 linspace(1+%i, 2-2*%i, 5)     // with complex numbers
129 linspace([1:4]', [5:8]', 10)  // with input columns
130  ]]></programlisting>
131         <screen><![CDATA[
132 --> linspace(1, %pi, 0)    // n = 0
133  ans  =
134     []
135
136 --> linspace(1, 2, 10)    // x2 > x1 : increasing values
137  ans  =
138    1.   1.111   1.222   1.333   1.444   1.556   1.667   1.778   1.889   2.
139
140 --> linspace(2, 1, 10)    // x2 &lt; x1 : decreasing values
141  ans  =
142    2.   1.889   1.778   1.667   1.556   1.444   1.333   1.222   1.111   1.
143
144 --> linspace(1+%i, 2-2*%i, 5)      // with complex numbers
145  ans  =
146    1. +i     1.25 +0.25i   1.5 -0.5i   1.75 -1.25i   2. -2.i
147
148 --> linspace([1:4]', [5:8]', 10)   // with input columns
149  ans  =
150    1.   1.444   1.889   2.333   2.778   3.222   3.667   4.111   4.556   5.
151    2.   2.444   2.889   3.333   3.778   4.222   4.667   5.111   5.556   6.
152    3.   3.444   3.889   4.333   4.778   5.222   5.667   6.111   6.556   7.
153    4.   4.444   4.889   5.333   5.778   6.222   6.667   7.111   7.556   8.
154 ]]></screen>
155     <para/>
156     <para>
157         <emphasis role="bold">With encoded integers:</emphasis>
158         The step may vary by one unit along the series:
159     </para>
160         <programlisting role="example"><![CDATA[
161 x = linspace(int8([5;127]), int8([127;5]), 10)
162 x(:,1:$-1) - x(:,2:$)
163  ]]></programlisting>
164         <screen><![CDATA[
165 --> x = linspace(int8([5;127]), int8([127;5]), 10)
166  ans  =
167     5   18   32  45  59  72  86  99  113  127
168   127  114  100  87  73  60  46  33   19    5
169
170 --> x(:,1:$-1) - x(:,2:$)
171  ans  =
172  -13 -14 -13 -14 -13 -14 -13 -14 -14
173   13  14  13  14  13  14  13  14  14
174 ]]></screen>
175         <programlisting role="example"><![CDATA[
176 // shape interpolation between a sphere and a cone
177 [T,P]=meshgrid(linspace(0,2*%pi,32),linspace(-%pi/2,%pi/2,32));
178 X=cos(T).*cos(P);
179 Y=sin(T).*cos(P);
180
181 Z=linspace(sin(P),cos(P)-1,100);
182
183 h=uicontrol("style","slider","units","normalized",...
184 "position",[0.2 0.03 0.6 0.05],"min",1,"max",100,...
185 "callback",...
186 "drawlater;delete(gca().children);mesh(X,Y,Z(:,:,h.value));isoview;drawnow")
187
188 execstr(h.callback)
189  ]]></programlisting>
190     </refsection>
191     <refsection role="see also">
192         <title>See also</title>
193         <simplelist type="inline">
194             <member>
195                 <link linkend="colon">colon</link>
196             </member>
197             <member>
198                 <link linkend="logspace">logspace</link>
199             </member>
200             <member>
201                 <link linkend="grand">grand</link>
202             </member>
203         </simplelist>
204     </refsection>
205     <refsection>
206         <title>History</title>
207         <revhistory>
208             <revision>
209                 <revnumber>5.4.0</revnumber>
210                 <revremark>
211                     <itemizedlist>
212                         <listitem>Column vectors can now be provided.
213                         </listitem>
214                         <listitem>The third input argument (n) must be an integer value.
215                         </listitem>
216                     </itemizedlist>
217                 </revremark>
218             </revision>
219             <revision>
220                 <revnumber>6.0</revnumber>
221                 <revremark>
222                     <itemizedlist>
223                         <listitem>linspace(a, b, n&lt;=0) now returns [] instead of b.
224                         </listitem>
225                         <listitem>bounds are now checked against %inf or %nan values.
226                         </listitem>
227                     </itemizedlist>
228                 </revremark>
229             </revision>
230             <revision>
231                 <revnumber>6.0.2</revnumber>
232                 <revremark>
233                     linspace() can now be reliably used for series of encoded integers.
234                 </revremark>
235             </revision>
236         </revhistory>
237     </refsection>
238 </refentry>