Function: _header_transcendental
Class: header
Section: transcendental
Doc:
 \section{Transcendental functions}\label{se:trans}

 These functions will always return an inexact object: a real number,
 a complex number, a $p$-adic number or a power series.  All these objects
 have a certain finite precision. By default, these functions are complex
 valued, see each individual function help for the definition of the branch
 cuts and choice of principal value. They operate in the following way:

 \item If the argument involves a floating point component
 (like \kbd{1.0 + I} or \kbd{Pi*I} but not \kbd{2 - 3*I}), then the
 computation is done at the precision of the argument.
 In the example below, changing the precision to $50$ digits does
 not matter, because $x$ only had a precision of $19$ digits to start with.
 \bprog
 ? \p 15
    realprecision = 19 significant digits (15 digits displayed)
 ? x = Pi/4
 %1 = 0.785398163397448
 ? \p 50
    realprecision = 57 significant digits (50 digits displayed)
 ? sin(x)
 %2 = 0.7071067811865475244
 @eprog

 \item If the argument is exact (an integer, a rational number,
 an exact complex number or a quadratic number), the result is computed
 at the current \idx{precision}, which can be
 viewed and changed using the defaults \tet{realprecision} (in decimal
 digits) or \tet{realbitprecision} (in bits). This precision can be changed
 globally

 \item in decimal digits: use \b{p} or \kbd{default(realprecision,...)}.

 \item in bits: use \b{pb} or \kbd{default(realbitprecision,...)}.

 After this conversion, the computation proceeds as above for real or complex
 arguments. The precision may also changed locally inside a given dynamic
 scope using \kbd{localprec} (decimal digits) or \kbd{localbitprec} (bits).

 In library mode, \kbd{realprecision} is ignored; instead the
 precision is taken from the \emph{positive} \kbd{prec} parameter, which
 every transcendental function has, and stands for the bit precision of a real
 number, i.e., the bit length of its mantissa. As in \kbd{gp}, this
 \kbd{prec} is not used when the argument to a function is already inexact.

 Some functions are actually bit-precise and their argument is
 called \kbd{bitprec} or \kbd{bit} in the documentation to emphasize this. But
 most functions operate on mantissas at the \emph{word}
 level and round \kbd{prec} to the next multiple of \kbd{BITS\_IN\_LONG}.

 \item If the argument is a polmod, representing an algebraic number,
 then the function is evaluated for every possible complex embedding of that
 algebraic number.  A column vector of results is returned, with one component
 for each complex embedding.  Therefore, the number of components equals
 the degree of the \typ{POLMOD} modulus.

 \item If the argument is an intmod or a $p$-adic, at present only a
 few functions like \kbd{sqrt} (square root), \kbd{sqr} (square), \kbd{log},
 \kbd{exp}, powering, \kbd{teichmuller} (Teichm\"uller character) and
 \kbd{agm} (arithmetic-geometric mean) are implemented.

 Note that in the case of a $2$-adic number, $\kbd{sqr}(x)$ may not be
 identical to $x*x$: for example if $x = 1+O(2^{5})$ and $y = 1+O(2^{5})$ then
 $x*y = 1+O(2^{5})$ while $\kbd{sqr}(x) = 1+O(2^{6})$. Here, $x * x$ yields the
 same result as $\kbd{sqr}(x)$ since the two operands are known to be
 \emph{identical}. The same statement holds true for $p$-adics raised to the
 power $n$, where $v_{p}(n) > 0$.

 \misctitle{Remark} If we wanted to be strictly consistent with
 the PARI philosophy, we should have $x*y = (4 \mod 8)$ and $\kbd{sqr}(x) =
 (4 \mod 32)$ when both $x$ and $y$ are congruent to $2$ modulo $4$.
 However, since intmod is an exact object, PARI assumes that the modulus
 must not change, and the result is hence $(0\, \mod\, 4)$ in both cases. On
 the other hand, $p$-adics are not exact objects, hence are treated
 differently.

 \item If the argument is a polynomial, a power series or a rational function
 in main variable $X$,
 it is, if necessary, first converted to a power series using the current
 series precision, held in the default \tet{seriesprecision}. This precision
 (the number of significant terms) can be changed using \b{ps} or
 \kbd{default(seriesprecision,...)}. Then the Taylor series expansion of the
 function around $X=0$ is computed to a number of terms depending on the
 number of terms of the argument and the function being computed.

 Under \kbd{gp} this again is transparent to the user. When programming in
 library mode, however, it is \emph{strongly} advised to perform an explicit
 conversion to a power series first, as in
 \bprog
   x = gtoser(x, gvar(x), seriesprec)
 @eprog\noindent
 where the number of significant terms \kbd{seriesprec} is specified
 explicitly. If you do not do this, a global variable \kbd{precdl} is used
 instead, to convert polynomials and rational functions to a power series with
 a reasonable number of terms; tampering with the value of this global
 variable is \emph{deprecated} and strongly discouraged.

 \item If the argument is a vector or a matrix, the result is the
 \emph{componentwise} evaluation of the function. In particular, transcendental
 functions on square matrices, are not built-in. For this you can use the
 following technique, which is neither very efficient nor numerical stable,
 but is often good enough provided we restrict to diagonalizable matrices:
 \bprog
 mateval(f, M) =
 { my([L, H] = mateigen(M, 1));
   H * matdiagonal(f(L)) * H^(-1);
 }
 ? A = [13,2;10,14];
 ? \pb 192
   realbitprecision = 192 significant bits (50 decimal digits displayed)
 ? a = mateval(sqrt, A) /*@Ccom approximates $\sqrt{A}$ */
 %2 =
 [3.5522847498307933... 0.27614237491539669...]

 [1.3807118745769834... 3.69035593728849174...]

 ? exponent(a^2 - A)
 %3 = -186 \\ OK

 ? b = mateval(exp, A);
 ? exponent(mateval(log, b) - A)
 %5 = -180 \\ tolerable

 @eprog The absolute error depends on the condition number of the base
 change matrix $H$ and on the largest $|f(\lambda)|$, where $\lambda$ runs
 through the eigenvalues. If $M$ is real symmetric, you may use
 \kbd{qfjacobi} instead of \kbd{mateigen}.

 Of course when the input is not diagonalizable, this function produces junk:
 \bprog
 ? mateval(sqrt, [0,1;0,0])
 %6 =    \\ oops ...
 [0.E-57 0]

 [     0 0]
 @eprog
