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