complex() extended to sparses
[scilab.git] / scilab / modules / elementary_functions / help / en_US / complex / complex.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) 2011 - DIGITEO - Michael Baudin
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2020 - 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="complex" xml:lang="en">
20     <refnamediv>
21         <refname>complex</refname>
22         <refpurpose>Build an array of complex numbers from their parts</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             c = complex(u)
28             c = complex(a, b)
29         </synopsis>
30     </refsynopsisdiv>
31     <refsection>
32         <title>Arguments</title>
33         <variablelist>
34             <varlistentry>
35                 <term>u, a, b</term>
36                 <listitem>
37                     scalars, vectors, matrices or hypermatrices of real numbers.
38                     If both <varname>a</varname> and <varname>b</varname> are not
39                     scalars, they must have the same sizes.
40                     <para/>
41                 </listitem>
42             </varlistentry>
43             <varlistentry>
44                 <term>c</term>
45                 <listitem>
46                     array of complex numbers, of the size of <varname>u</varname> or of
47                     <varname>a</varname> and <varname>b</varname>.
48                     If <varname>u</varname> is sparse, or if <varname>a</varname> and
49                     <varname>b</varname> have the same sizes and both are sparse,
50                     then <varname>c</varname> is also sparse.
51                     Otherwise <varname>c</varname> is dense-encoded.
52                     <para/>
53                 </listitem>
54             </varlistentry>
55         </variablelist>
56     </refsection>
57     <refsection>
58         <title>Description</title>
59         <para>
60             <emphasis role="bold">c = complex(u)</emphasis> creates an array
61             of complex numbers from their real parts <varname>u</varname>,
62             and zero as imaginary parts.
63         </para>
64         <para>
65             <emphasis role="bold">c = complex(a,b)</emphasis> creates an array
66             of complex numbers from their respective real parts <varname>a</varname>
67             and their imaginary parts <varname>b</varname>.
68         </para>
69         <para>
70             This function is equivalent to <literal>a + imult(b)</literal>, which
71             handles properly special Inf and NaN real and imaginary parts.
72         </para>
73     </refsection>
74     <refsection>
75         <title>Examples</title>
76         <para>
77             In the following example, we create a complex number from
78             its real and imaginary parts.
79         </para>
80         <programlisting role="example"><![CDATA[
81 complex(1,2)
82 complex([1 2],[3 4])
83  ]]></programlisting>
84         <para>
85             If <varname>a</varname> only is specified, then the imaginary
86             part is set to zero.
87         </para>
88         <programlisting role="example"><![CDATA[
89 complex([1 2 3])
90  ]]></programlisting>
91         <para>
92             If <varname>a</varname> is a scalar and <varname>b</varname>
93             is a matrix, then the result <varname>c</varname> has the same
94             size as <varname>b</varname>.
95             Similarly, if <varname>b</varname> is a scalar and <varname>a</varname>
96             is a matrix, then the result <varname>c</varname> has the same
97             size as <varname>a</varname>.
98         </para>
99         <programlisting role="example"><![CDATA[
100 c = complex([1 2 3], 4)
101 c = complex(1, [2 3 4])
102  ]]></programlisting>
103         <para>
104             If <varname>a</varname> and <varname>b</varname> are two
105             matrices with different sizes, an error is generated, as in the
106             following session.
107         </para>
108         <screen><![CDATA[
109 -->complex(ones(2,3),ones(4,5))
110  !--error 10000
111 complex: Incompatible input arguments #1 and #2: Same sizes expected.
112 at line      33 of function complex called by :
113 complex(ones(2,3),ones(4,5))
114  ]]></screen>
115         <para>
116             With special real or/and imaginary parts:
117         </para>
118         <programlisting role="example"><![CDATA[
119 r = [0   0    0 %inf %inf %inf %nan %nan %nan].';
120 i = [0 %inf %nan  0  %inf %nan   0  %inf %nan].';
121 [r, i]
122
123 // Then let's compare complex(r, i) with r + i*%i :
124 [complex(r,i), r+i*%i]
125  ]]></programlisting>
126         <screen><![CDATA[
127 --> [r, i]
128  ans  =
129    0.    0.
130    0.    Inf
131    0.    Nan
132    Inf   0.
133    Inf   Inf
134    Inf   Nan
135    Nan   0.
136    Nan   Inf
137    Nan   Nan
138
139 // Then let's compare complex(r, i) with r + i*%i :
140 --> [complex(r,i), r+i*%i]
141  ans  =
142    0.  + 0.i    0.  + 0.i
143    0.  + Infi   Nan + Infi
144    0.  + Nani   Nan + Nani
145    Inf + 0.i    Inf + 0.i
146    Inf + Infi   Nan + Infi
147    Inf + Nani   Nan + Nani
148    Nan + 0.i    Nan + 0.i
149    Nan + Infi   Nan + Infi
150    Nan + Nani   Nan + Nani
151  ]]></screen>
152     </refsection>
153     <refsection role="see also">
154         <title>See also</title>
155         <simplelist type="inline">
156             <member>
157                 <link linkend="percenti">%i</link>
158             </member>
159             <member>
160                 <link linkend="imult">imult</link>
161             </member>
162         </simplelist>
163     </refsection>
164     <refsection role="history">
165         <title>History</title>
166         <revhistory>
167             <revision>
168                 <revnumber>6.1.1</revnumber>
169                 <revdescription>Extension to sparse arrays.
170                 </revdescription>
171             </revision>
172         </revhistory>
173     </refsection>
174 </refentry>