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>