scilab/modules/elementary_functions/help/en_US/matrixoperations/sign.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) 2015, 2016, 2018 - Samuel GOUGEON
   6  *
   7  * Copyright (C) 2012 - 2016 - Scilab Enterprises
   8  *
   9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
  10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  11  * This file was originally licensed under the terms of the CeCILL v2.1,
  12  * and continues to be available under such terms.
  13  * For more information, see the COPYING file which you should have received
  14  * along with this program.
  15  *
  16  -->
  17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
  18         xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
  19         xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
  20         xmlns:scilab="http://www.scilab.org" xml:id="sign" xml:lang="en">
  21     <refnamediv>
  22         <refname>sign</refname>
  23         <refpurpose>signum function</refpurpose>
  24     </refnamediv>
  25     <refsynopsisdiv>
  26         <title>Syntax</title>
  27         <synopsis>X = sign(A)</synopsis>
  28     </refsynopsisdiv>
  29     <refsection role="parameters">
  30         <title>Arguments</title>
  31         <variablelist>
  32             <varlistentry>
  33                 <term>А</term>
  34                 <listitem>
  35                     <para>
  36                         matrix of encoded integers, decimal numbers, or complex numbers.
  37                         <varname>A</varname> may be sparse.
  38                     </para>
  39                 </listitem>
  40             </varlistentry>
  41             <varlistentry>
  42                 <term>X</term>
  43                 <listitem>
  44                     <para>
  45                         matrix of the same size and data type as <varname>A</varname>.
  46                     </para>
  47                 </listitem>
  48             </varlistentry>
  49         </variablelist>
  50     </refsection>
  51     <refsection role="description">
  52         <title>Description</title>
  53         <para>
  54             If <varname>X</varname> are integers or real numbers,
  55             <itemizedlist>
  56                 <listitem>
  57                     <literal>X(i) = -1</literal> where <literal>A(i)&lt;0</literal>
  58                 </listitem>
  59                 <listitem>
  60                     <literal>X(i) = 0</literal> where <literal>A(i)==0</literal>
  61                 </listitem>
  62                 <listitem>
  63                     <literal>X(i) = 1</literal> where <literal>A(i)>0</literal>
  64                 </listitem>
  65                 <listitem>
  66                     <literal>X(i)= %nan</literal> where <literal>A(i)</literal> is NaN.
  67                 </listitem>
  68             </itemizedlist>
  69         </para>
  70         <para>
  71             If <varname>X</varname> is complex encoded: <literal>sign(A==0) = 0</literal>.
  72             Elsewhere, <literal>sign(A) = A./abs(A)</literal>.
  73         </para>
  74     </refsection>
  75     <refsection role="examples">
  76         <title>Examples</title>
  77         <para>With decimal numbers:</para>
  78         <programlisting role="example"><![CDATA[
  79 m  = [ 1.25  -2.5  -%inf   2.75
  80        0.     1.    0.75   %inf
  81        %nan   0.   -1.5   -2.5 ]; m
  82 sign(m)
  83  ]]></programlisting>
  84     <screen><![CDATA[
  85 --> m  =
  86    1.25  -2.5  -Inf    2.75
  87    0.     1.    0.75   Inf
  88    Nan    0.   -1.5   -2.5
  89
  90 --> sign(m)
  91  ans  =
  92    1.   -1.  -1.   1.
  93    0.    1.   1.   1.
  94    Nan   0.  -1.  -1.
  95 ]]></screen>
  96     <para>With complex numbers:</para>
  97     <programlisting role="example"><![CDATA[
  98 i = %i;
  99 c = [-1, -i, -3+4*i
 100       1,  i,  3+4*i
 101       3,  0,  3-4*i
 102      -4, 4*i,-4-3*i ];
 103 c
 104 sign(c)
 105  ]]></programlisting>
 106     <screen><![CDATA[
 107 --> c  =
 108   -1.  -i     -3. + 4.i
 109    1.   i      3. + 4.i
 110    3.   0.     3. - 4.i
 111   -4.   4.i   -4. - 3.i
 112
 113 --> sign(c)
 114  ans  =
 115   -1.  -i     -0.6 + 0.8i
 116    1.   i      0.6 + 0.8i
 117    1.   0.     0.6 - 0.8i
 118   -1.   i     -0.8 - 0.6i
 119 ]]></screen>
 120     <para>With a sparse matrix:</para>
 121     <programlisting role="example"><![CDATA[
 122 sign(sprand(8,3,0.3,"normal"))
 123  ]]></programlisting>
 124     </refsection>
 125     <refsection role="see also">
 126         <title>See also</title>
 127         <simplelist type="inline">
 128             <member>
 129                 <link linkend="abs">abs</link>
 130             </member>
 131             <member>
 132                 <link linkend="csgn">csgn</link>
 133             </member>
 134             <member>
 135                 <link linkend="signm">signm</link>
 136             </member>
 137         </simplelist>
 138     </refsection>
 139     <refsection role="history">
 140         <title>History</title>
 141         <revhistory>
 142             <revision>
 143                 <revnumber>6.0</revnumber>
 144                 <revdescription>Extension to sparse matrices
 145                 </revdescription>
 146             </revision>
 147         </revhistory>
 148     </refsection>
 149 </refentry>