[doc] misc. fix & improvements
[scilab.git] / scilab / modules / elementary_functions / help / en_US / trigonometry / atanh.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  *
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="atanh" xml:lang="en">
20     <refnamediv>
21         <refname>atanh</refname>
22         <refpurpose>hyperbolic tangent inverse</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>t = atanh(x)</synopsis>
27     </refsynopsisdiv>
28     <refsection>
29         <title>Arguments</title>
30         <variablelist>
31             <varlistentry>
32                 <term>x</term>
33                 <listitem>
34                     <para>a real or complex vector/matrix.</para>
35                 </listitem>
36             </varlistentry>
37             <varlistentry>
38                 <term>t</term>
39                 <listitem>
40                     <para>a real or complex vector/matrix.</para>
41                 </listitem>
42             </varlistentry>
43         </variablelist>
44     </refsection>
45     <refsection>
46         <title>Description</title>
47         <para>
48             The components of vector <varname>t</varname> are the hyperbolic
49             tangent inverse of the corresponding entries of vector
50             <varname>x</varname>. Definition domain is <literal>[-1,1]</literal> for
51             the real function (see Remark).
52         </para>
53     </refsection>
54     <refsection>
55         <title>Remark</title>
56         <para>
57             In Scilab (as in some others numerical software) when you try to
58             evaluate an elementary mathematical function outside its definition domain
59             in the real case, then the complex extension is used (with a complex
60             result). The most famous example being the <function>sqrt</function> function (try
61             <code>sqrt(-1)</code>!).
62         </para>
63         <para>
64             This approach has some drawbacks when you
65             evaluate the function at a singular point which may lead to different
66             results when the point is considered as real or complex.
67         </para>
68         <para>
69             For <literal>atanh()</literal>, this occurs for <literal>-1</literal> and
70             <literal>1</literal>, because at these points the imaginary part does not
71             converge and so <literal>atanh(1) = +Inf + i NaN</literal> while
72             <literal>atanh(1) = +Inf</literal> for the real case (as lim <literal>x-&gt;1</literal>
73             of <code>atanh(x)</code>).
74         </para>
75         <para>
76             So when you evaluate this function on the vector <literal>[1 2]</literal>
77             then like <literal>2</literal> is outside the definition
78             domain, the complex extension is used for all the vector and you get
79             <literal>atanh(1) = +Inf + i NaN</literal> while you get
80             <literal>atanh(1) = +Inf</literal> with <literal>[1, 0.5]</literal> for instance.
81         </para>
82     </refsection>
83     <refsection>
84         <title>Examples</title>
85         <programlisting role="example"><![CDATA[
86 // example 1
87 x=[0,%i,-%i]
88 tanh(atanh(x))
89
90 // example 2
91 x = [-%inf -3 -2 -1 0 1 2 3 %inf]
92 ieee(2)
93 atanh(tanh(x))
94
95 // example 3 (see Remark)
96 ieee(2)
97 atanh([1 2])
98 atanh([1 0.5])
99  ]]></programlisting>
100     </refsection>
101     <refsection role="see also">
102         <title>See also</title>
103         <simplelist type="inline">
104             <member>
105                 <link linkend="tanh">tanh</link>
106             </member>
107             <member>
108                 <link linkend="ieee">ieee</link>
109             </member>
110         </simplelist>
111     </refsection>
112 </refentry>