<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2016, 2018 - Samuel GOUGEON
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
          xmlns:scilab="http://www.scilab.org" xml:id="linspace" xml:lang="en">
    <refnamediv>
        <refname>linspace</refname>
        <refpurpose>generates linearly spaced numbers between 2 reached bounds</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            row = linspace(x1, x2)
            row = linspace(x1, x2, n)
            Matrix = linspace(Col1, Col2)
            Matrix = linspace(Col1, Col2, n)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>x1, x2</term>
                <listitem>
                    <para>
                        Real or complex scalars, or encoded integer scalars:
                        Bounds between which values must be generated.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Col1, Col2</term>
                <listitem>
                    <para>
                        Column vectors of real or complex numbers, or of encoded integers,
                        of same heights.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>n</term>
                <listitem>
                    <para>
                        integer number of requested values or columns.
                        Default value: 100
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>row</term>
                <listitem>
                    <para>
                        row vector of <literal>n</literal> numbers.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Matrix</term>
                <listitem>
                    <para>
                        Matrix with <literal>n</literal> columns of numbers.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <literal>linspace(x1, x2)</literal>
            generates a row vector of <literal>n</literal> equally spaced
            values ranging exactly from <literal>x1</literal> to <literal>x2</literal>.
        </para>
        <note>
            <para>
                The syntax <literal>y1:y2</literal> or <literal>y1:step:y2</literal>
                like <literal>1:0.1:%pi</literal> does the same but fixes the
                starting bound <literal>y1</literal> and
                <emphasis role="bold">the step</emphasis>. The <literal>y2</literal>
                is used as stopping bound to not be overstepped. The last value
                actually generated may not reach it.
                <literal>y2</literal> is then not included in the result.
            </para>
            <para>
                Instead of fixing the step to a given value, <literal>linspace</literal>
                fixes the final bound <literal>x2</literal> to be exactly
                <emphasis role="bold">reached</emphasis>, and computes the step
                accordingly.
            </para>
        </note>
        <para>
            If <literal>x1</literal> or <literal>x2</literal> are complex numbers,
            then <literal>linspace(x1,x2)</literal> interpolates separately the real and
            the imaginary parts of <literal>x1</literal> and <literal>x2</literal>.
        </para>
        <para>
            If some column vectors <literal>Col1</literal> and <literal>Col2</literal>
            are provided, <literal>linspace</literal> works in a row-wise way:
            the resulting <literal>Matrix</literal> has the same number of rows,
            and <literal>n</literal> columns. We get
            <literal>Matrix(i,:) = linspace(Col1(i), Col2(i), n)</literal>.
        </para>
        <warning>
            When specified bounds are encoded integers, the actual step may vary by one unit
            along the generated series.
        </warning>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
linspace(1, %pi, 0)         // n = 0
linspace(1, 2, 10)          // x2 > x1 : increasing values
linspace(2, 1, 10)          // x2 < x1 : decreasing values
linspace(1+%i, 2-2*%i, 5)     // with complex numbers
linspace([1:4]', [5:8]', 10)  // with input columns
 ]]></programlisting>
        <screen><![CDATA[
--> linspace(1, %pi, 0)    // n = 0
 ans  =
    []

--> linspace(1, 2, 10)    // x2 > x1 : increasing values
 ans  =
   1.   1.111   1.222   1.333   1.444   1.556   1.667   1.778   1.889   2.

--> linspace(2, 1, 10)    // x2 &lt; x1 : decreasing values
 ans  =
   2.   1.889   1.778   1.667   1.556   1.444   1.333   1.222   1.111   1.

--> linspace(1+%i, 2-2*%i, 5)      // with complex numbers
 ans  =
   1. +i     1.25 +0.25i   1.5 -0.5i   1.75 -1.25i   2. -2.i

--> linspace([1:4]', [5:8]', 10)   // with input columns
 ans  =
   1.   1.444   1.889   2.333   2.778   3.222   3.667   4.111   4.556   5.
   2.   2.444   2.889   3.333   3.778   4.222   4.667   5.111   5.556   6.
   3.   3.444   3.889   4.333   4.778   5.222   5.667   6.111   6.556   7.
   4.   4.444   4.889   5.333   5.778   6.222   6.667   7.111   7.556   8.
]]></screen>
    <para/>
    <para>
        <emphasis role="bold">With encoded integers:</emphasis>
        The step may vary by one unit along the series:
    </para>
        <programlisting role="example"><![CDATA[
x = linspace(int8([5;127]), int8([127;5]), 10)
x(:,1:$-1) - x(:,2:$)
 ]]></programlisting>
        <screen><![CDATA[
--> x = linspace(int8([5;127]), int8([127;5]), 10)
 ans  =
    5   18   32  45  59  72  86  99  113  127
  127  114  100  87  73  60  46  33   19    5

--> x(:,1:$-1) - x(:,2:$)
 ans  =
 -13 -14 -13 -14 -13 -14 -13 -14 -14
  13  14  13  14  13  14  13  14  14
]]></screen>
        <programlisting role="example"><![CDATA[
// shape interpolation between a sphere and a cone
[T,P]=meshgrid(linspace(0,2*%pi,32),linspace(-%pi/2,%pi/2,32));
X=cos(T).*cos(P);
Y=sin(T).*cos(P);

Z=linspace(sin(P),cos(P)-1,100);

h=uicontrol("style","slider","units","normalized",...
"position",[0.2 0.03 0.6 0.05],"min",1,"max",100,...
"callback",...
"drawlater;delete(gca().children);mesh(X,Y,Z(:,:,h.value));isoview;drawnow")

execstr(h.callback)
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="colon">colon</link>
            </member>
            <member>
                <link linkend="logspace">logspace</link>
            </member>
            <member>
                <link linkend="grand">grand</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.4.0</revnumber>
                <revremark>
                    <itemizedlist>
                        <listitem>Column vectors can now be provided.
                        </listitem>
                        <listitem>The third input argument (n) must be an integer value.
                        </listitem>
                    </itemizedlist>
                </revremark>
            </revision>
            <revision>
                <revnumber>6.0</revnumber>
                <revremark>
                    <itemizedlist>
                        <listitem>linspace(a, b, n&lt;=0) now returns [] instead of b.
                        </listitem>
                        <listitem>bounds are now checked against %inf or %nan values.
                        </listitem>
                    </itemizedlist>
                </revremark>
            </revision>
            <revision>
                <revnumber>6.0.2</revnumber>
                <revremark>
                    linspace() can now be reliably used for series of encoded integers.
                </revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
