* Bug 15934 fixed [doc]: ^rectangular yields an error
[scilab.git] / scilab / modules / core / help / en_US / 1_keywords / hat.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) 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:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="hat">
17     <refnamediv>
18         <refname>hat</refname>
19         <refpurpose>(^) exponentiation</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Syntax</title>
23         <synopsis>A^b</synopsis>
24     </refsynopsisdiv>
25     <refsection>
26         <title>Description</title>
27         <para>
28             Exponentiation of matrices or vectors by a constant vector.
29         </para>
30         <para>
31             If <literal>A</literal> is a vector, the exponentiation is done
32             element-wise, with the usual meaning.
33         </para>
34         <para>
35             For a square <literal>A</literal> matrix, the exponentiation is done in the matrix sense.
36         </para>
37         <para>
38             For boolean, polynomial and rational matrices, the exponent must be an
39             integer.
40         </para>
41         <refsection>
42             <title>Remarks </title>
43             <para>
44                 <literal>123.^b</literal> is interpreted as <literal>(123).^b</literal>. In such
45                 cases dot is part of the operator, not of the number.
46             </para>
47             <para>
48                 For two real or complex numbers <literal>x1</literal> and
49                 <literal>x2</literal> the value of  <literal>x1^x2</literal> is the "principal value"
50                 determined by <literal>x1^x2 = exp(x2*log(x1))</literal>.
51             </para>
52             <para>
53                 <warning>
54                     Exponentiation is right-associative in Scilab contrarily to MatlabĀ® and Octave.
55                    For example 2^3^4 is equal to 2^(3^4) in Scilab but is equal to (2^3)^4 in MatlabĀ®
56                    and Octave.
57                 </warning>
58             </para>
59         </refsection>
60     </refsection>
61     <refsection>
62         <title>Examples</title>
63         <programlisting role="example"><![CDATA[
64 2^4
65 (-0.5)^(1/3)
66 [1 2;2 4]^(1+%i)
67 s=poly(0,"s");
68 [1 2 s]^4
69 [s 1;1  s]^(-1)
70  ]]></programlisting>
71     </refsection>
72     <refsection role="see also">
73         <title>See also</title>
74         <simplelist type="inline">
75             <member>
76                 <link linkend="power">power</link>
77             </member>
78             <member>
79                 <link linkend="exp">exp</link>
80             </member>
81             <member>
82                 <link linkend="log">log</link>
83             </member>
84             <member>
85                 <link linkend="log2">log2</link>
86             </member>
87             <member>
88                 <link linkend="inv">inv</link>
89             </member>
90         </simplelist>
91     </refsection>
92 </refentry>