c08a8e129bc83cd3ce8232a3c4d6d2c0528da44e
[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  *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
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>Create a complex number.</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             c=complex(a)
28             c=complex(a,b)
29         </synopsis>
30     </refsynopsisdiv>
31     <refsection>
32         <title>Arguments</title>
33         <variablelist>
34             <varlistentry>
35                 <term>a</term>
36                 <listitem>
37                     <para>
38                         a 1-by-1 or a n-by-m real matrix of doubles, the real part.
39                         If <literal>a</literal> has an imaginary part, an error
40                         is generated.
41                     </para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>b</term>
46                 <listitem>
47                     <para>
48                         a 1-by-1 or a n-by-m real matrix of doubles, the imaginary part (default b=0).
49                         If <literal>b</literal> has an imaginary part, an error
50                         is generated.
51                     </para>
52                 </listitem>
53             </varlistentry>
54             <varlistentry>
55                 <term>c</term>
56                 <listitem>
57                     <para>a n-by-m complex matrix of doubles, the complex number.</para>
58                 </listitem>
59             </varlistentry>
60         </variablelist>
61     </refsection>
62     <refsection>
63         <title>Description</title>
64         <para>
65             c=complex(a) creates a complex number from its real part <literal>a</literal>
66             and zero as the imaginary part.
67         </para>
68         <para>
69             c=complex(a,b) creates a complex number from its real part <literal>a</literal>
70             and imaginary part <literal>b</literal>.
71         </para>
72         <para>
73             This function is a substitute for expressions such as <literal>a+%i*b</literal>,
74             especially in cases where the complex arithmetic interferes with particular
75             floating point numbers such as <literal>%inf</literal> or
76             <literal>%nan</literal>.
77         </para>
78     </refsection>
79     <refsection>
80         <title>Examples</title>
81         <para>
82             In the following example, we create a complex number from
83             its real and imaginary parts.
84         </para>
85         <programlisting role="example"><![CDATA[
86 complex(1,2)
87 complex([1 2],[3 4])
88  ]]></programlisting>
89         <para>
90             If <literal>a</literal> only is specified, then the imaginary
91             part is set to zero.
92         </para>
93         <programlisting role="example"><![CDATA[
94 complex([1 2 3])
95  ]]></programlisting>
96         <para>
97             If <literal>a</literal> is a scalar and <literal>b</literal>
98             is a matrix, then the result <literal>c</literal> has the same
99             size as <literal>b</literal>.
100             Similarly, if <literal>b</literal> is a scalar and <literal>a</literal>
101             is a matrix, then the result <literal>c</literal> has the same
102             size as <literal>a</literal>.
103         </para>
104         <programlisting role="example"><![CDATA[
105 c = complex([1 2 3], 4)
106 c = complex(1, [2 3 4])
107  ]]></programlisting>
108         <para>
109             If <literal>a</literal> and <literal>b</literal> are two
110             matrices with different sizes, an error is generated, as in the
111             following session.
112         </para>
113         <screen><![CDATA[
114 -->complex(ones(2,3),ones(4,5))
115  !--error 10000
116 complex: Incompatible input arguments #1 and #2: Same sizes expected.
117 at line      33 of function complex called by :
118 complex(ones(2,3),ones(4,5))
119  ]]></screen>
120         <para>
121             The purpose of the <literal>complex</literal> function is to manage
122             IEEE floating point numbers such as Nans or Infinities.
123             In the following example, we show that creating a complex number where
124             the real and imaginary parts are complex is not straightforward if
125             we use the complex arithmetic.
126             This is because the product <literal>%i</literal> times <literal>%inf</literal>
127             is evaluated as <literal>(0+%i) * (%inf+%i*0)</literal>.
128             This produces the intermediate expression <literal>0*%inf</literal>,
129             which is <literal>%nan</literal>.
130         </para>
131         <screen><![CDATA[
132 -->%inf+%i*%inf
133  ans  =
134     Nan + Inf
135  ]]></screen>
136         <para>
137             The solution of this issue is to use the <literal>complex</literal>
138             function.
139         </para>
140         <screen><![CDATA[
141 -->complex(%inf,%inf)
142  ans  =
143     Inf + Inf
144  ]]></screen>
145     </refsection>
146     <refsection role="see also">
147         <title>See also</title>
148         <simplelist type="inline">
149             <member>
150                 <link linkend="percenti">%i</link>
151             </member>
152             <member>
153                 <link linkend="imult">imult</link>
154             </member>
155         </simplelist>
156     </refsection>
157 </refentry>