66fc1484458c1f03f5b7198e63e744666b8ce0c3
[scilab.git] / scilab / modules / elementary_functions / help / en_US / exponential / log2.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) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2019 - 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="log2" xml:lang="en">
20     <refnamediv>
21         <refname>log2</refname>
22         <refpurpose>
23             Base-2 logarithm. Base-2 exponents and mantissae of some decimal numbers
24         </refpurpose>
25     </refnamediv>
26     <refsynopsisdiv>
27         <title>Syntax</title>
28         <synopsis>
29             y = log2(x)
30             [m,e] = log2(u)
31         </synopsis>
32     </refsynopsisdiv>
33     <refsection>
34         <title>Arguments</title>
35         <variablelist>
36             <varlistentry>
37                 <term>x, y</term>
38                 <listitem>
39                     <para>
40                         arrays of decimal or complex numbers, such that <literal>2.^y = x</literal>.
41                     </para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>u, m, e</term>
46                 <listitem>
47                     <para>arrays of decimal numbers such that <literal>u = m .* 2.^e</literal>,
48                         with <literal>sign(m)=sign(u)</literal> and <literal>0.5 ≤ abs(m) &lt; 1</literal>.
49                     </para>
50                 </listitem>
51             </varlistentry>
52         </variablelist>
53     </refsection>
54     <refsection>
55         <title>Description</title>
56         <para>
57             <literal>y = log2(x)</literal> is the "element-wise" base 2 logarithm, with
58             <literal>y(i,j) = log2(x(i,j))</literal>.
59             <note>
60                 <literal>log2(-%inf) == %inf + log2(-1)</literal>
61             </note>
62         </para>
63         <para>
64             <literal>[m,e]=log2(u)</literal> computes in an element-wise way the base-2 mantissa
65             <varname>m</varname> and exponent <varname>e</varname> of every elements of
66             <varname>u</varname>. Hence, for any index <literal>k</literal> we have
67             <literal>u(k) = m(k) .* 2.^e(k)</literal> with <literal>0.5 ≤ |m(k)| &lt; 1</literal>.
68             <note>
69                 <itemizedlist>
70                     <listitem>
71                         <literal>[m,e]=log2([0 %nan -%inf %inf])</literal> returns
72                         <literal>m=[0  NaN -Inf Inf]</literal> and <literal>e=[0 0 0 0]</literal>.
73                     </listitem>
74                     <listitem>
75                         This syntax corresponds to the ANSI C function frexp().
76                     </listitem>
77                 </itemizedlist>
78             </note>
79         </para>
80     </refsection>
81     <refsection>
82         <title>Examples</title>
83         <para>
84             Base-2 logarithm:
85         </para>
86         <programlisting role="example"><![CDATA[
87 L = log2([-1, 1, 2, %i, -%i])
88 clean(2.^L)
89 L = log2([0 %nan %inf])
90 2 .^ L
91 L = log2([0 %nan %inf -%inf]) // -%inf<0 turns the result to complex
92 2 .^ L                        // -Inf is not retrieved
93  ]]></programlisting>
94     <screen><![CDATA[
95 --> L = log2([-1, 1, 2, %i, -%i])
96  L  =
97    4.5323601i   0.   1.   2.2661801i  -2.2661801i
98
99 --> clean(2.^L)
100  ans  =
101   -1.   1.   2.   i   -i
102
103 --> L = log2([0 %nan %inf])
104  L  =
105   -Inf   Nan   Inf
106
107 --> 2 .^ L
108  ans  =
109    0.   Nan   Inf
110
111 --> L = log2([0 %nan %inf -%inf]) // -%inf<0 turns the result to complex
112  L  =
113   -Inf   Nan + Nani   Inf   Inf + 4.5323601i
114
115 --> 2 .^ L                        // -Inf is not retrieved
116  ans  =
117    0.   Nan + Nani   Inf   Nan + Nani
118 ]]></screen>
119         <para/>
120         <para>
121             Base-2 mantissa + exponent decomposition:
122         </para>
123         <programlisting role="example"><![CDATA[
124 [m, e] = log2([-3, -1.5, -1, 0, 4, 1e20])
125 m .* 2.^e
126  ]]></programlisting>
127     <screen><![CDATA[
128 --> [m, e] = log2([-3, -1.5, -1, 0, 4, 1e20])
129  e  =
130    2.     1.     1.    0.   3.   67.
131  m  =
132   -0.75  -0.75  -0.5   0.   0.5   0.6776264
133
134 --> m .* 2.^e
135  ans  =
136   -3.  -1.5  -1.   0.   4.   1.000D+20
137 ]]></screen>
138     <para/>
139         <programlisting role="example"><![CDATA[
140 np = number_properties;
141 x = [%eps np("tiniest") np("tiny") np("huge")]
142 [m, e] = log2(x)
143  ]]></programlisting>
144     <screen><![CDATA[
145 --> x = [%eps np("tiniest") np("tiny") np("huge")]
146  x  =
147     2.220D-16    4.94D-324    2.22D-308    1.79D+308
148
149 --> [m, e] = log2(x)
150  e  =
151   - 51.  - 1073.  - 1021.    1024.
152  m  =
153     0.5    0.5    0.5    1.
154 ]]></screen>
155     <para/>
156         <programlisting role="example"><![CDATA[
157 [m, e] = log2([0 %nan -%inf %inf])
158 m .* 2.^e
159  ]]></programlisting>
160     <screen><![CDATA[
161 -->[m, e] = log2([0 %nan -%inf %inf])
162  e  =
163     0.    0.    0.    0.
164  m  =
165     0.    Nan  - Inf    Inf
166
167 -->m .* 2.^e
168  ans  =
169     0.    Nan  - Inf    Inf
170 ]]></screen>
171     </refsection>
172     <refsection role="see also">
173         <title>See also</title>
174         <simplelist type="inline">
175             <member>
176                 <link linkend="log">log</link>
177             </member>
178             <member>
179                 <link linkend="log10">log10</link>
180             </member>
181             <member>
182                 <link linkend="nextpow2">nextpow2</link>
183             </member>
184             <member>
185                 <link linkend="bitstring">bitstring</link>
186             </member>
187             <member>
188                 <link linkend="hat">hat</link>
189             </member>
190         </simplelist>
191     </refsection>
192 </refentry>