\subsection{annotatefunction}
\label{labannotatefunction}
\noindent Name: \textbf{annotatefunction}\\
\phantom{aaa}Annotates a \sollya function object with an approximation that is faster to evaluate\\[0.2cm]
\noindent Library names:\\
\verb|   sollya_obj_t sollya_lib_annotatefunction(sollya_obj_t, sollya_obj_t,|\\
\verb|                                            sollya_obj_t, sollya_obj_t, ...);|\\
\verb|   sollya_obj_t sollya_lib_v_annotatefunction(sollya_obj_t, sollya_obj_t,|\\
\verb|                                              sollya_obj_t, sollya_obj_t,|\\
\verb|                                              va_list);|\\[0.2cm]
\noindent Usage: 
\begin{center}
\textbf{annotatefunction}(\emph{f}, \emph{g}, \emph{I}, \emph{d}) : (\textsf{function}, \textsf{function}, \textsf{range}, \textsf{range}) $\rightarrow$ \textsf{function}\\
\textbf{annotatefunction}(\emph{f}, \emph{g}, \emph{I}, \emph{d}, \emph{$x_0$}) : (\textsf{function}, \textsf{function}, \textsf{range}, \textsf{range}, \textsf{constant}) $\rightarrow$ \textsf{function}\\
\end{center}
Parameters: 
\begin{itemize}
\item \emph{f} is a function.
\item \emph{g} is a function, in most cases a polynomial.
\item \emph{I} is an interval.
\item \emph{d} is an interval.
\item \emph{$x_0$} is a constant (default value is $0$ when not provided).
\end{itemize}
\noindent Description: \begin{itemize}

\item When a given function \emph{f} is to be evaluated at several points of a given
   interval \emph{I} to a given precision, it might be useful to precompute a good
   approximant \emph{g} of \emph{f} and further evaluate it instead of \emph{f} when the
   approximation is good enough to provide the desire precision. If \emph{f} is a
   complicated expression, whereas \emph{g} is, \emph{e.g.}, a polynomial of low degree,
   the cost of precomputing \emph{g} can be well compensated by the gain of time in
   each subsequent evaluation. The purpose of \textbf{annotatefunction} is to provide
   such a mechanism to the user.

\item When using \textbf{annotatefunction}(\emph{f}, \emph{g}, \emph{I}, \emph{d}, \emph{$x_0$}),
   resp. \textbf{annotatefunction}(\emph{f}, \emph{g}, \emph{I}, \emph{d}) (where \emph{$x_0$} is assumed to be
   zero), it is assumed that
   $$\forall x \in I, f(x) - g(x - x_0) \in d.$$
   It is the user responsibility to ensure this property. Otherwise, any
   subsequent use of \emph{f} on points of \emph{I} might lead to incorrect values.

\item A call to \textbf{annotatefunction}(\emph{f}, \emph{g}, \emph{I}, \emph{d}, \emph{$x_0$}) annotates the given
   \sollya function object \emph{f} with the approximation \emph{g}. In further use, when
   asked to evaluate \emph{f} on a point $x$ of \emph{I}, \sollya will first evaluate \emph{g}
   on $x-x_0$ and check if the result is accurate enough in the given context
   (accounting for the fact that the error of approximation between the true
   value and $g(x-x_0)$ belongs to \emph{d}). If not (and only in this case), an
   evaluation of the expression of \emph{f} on $x$ is performed.

\item The approximation \emph{g} can be any \sollya function but particular
   performance is expected when \emph{g} is a polynomial. Upon annotation with a
   polynomial, precomputations are performed to analyze certain properties of
   the given approximation polynomial.

\item \textbf{annotatefunction} updates the internal representation of \emph{f} so as to
   persistently keep this information attached with the \sollya object
   representing \emph{f}. In particular, the annotation is persistent through copy
   or use of \emph{f} as a subexpression to build up bigger expressions. Notice
   however, that there is no way of deducing an annotation for the derivative
   of \emph{f} from an annotation of \emph{f}. So, in general, it should not be expected
   that \textbf{diff}(\emph{f}) will be automatically annotated (notice, however that \emph{f}
   might be a subexpression of its derivative, \emph{e.g.}, for \emph{f}=\textbf{exp} or \emph{f}=\textbf{tan}, in
   which case the corresponding subexpressions of the derivative could inherit
   the annotations from \emph{f}. It is currently not specified whether \sollya does
   this automatically or not).

\item \textbf{annotatefunction} really is an imperative statement that modifies the
   internal representation of~\emph{f}. However, for convenience \textbf{annotatefunction}
   returns \emph{f} itself.

\item \sollya function objects can be annotated more than once with different
   approximations on different domains, that do not need to be disjoint. Upon
   evaluation of the annotated function object, \sollya chooses an
   approximation annotation (if any) that provides for sufficient accuracy at
   the evaluation point. It is not specified in which order \sollya tries
   different possible annotations when several are available for a given
   point \emph{x}.
\end{itemize}
\noindent Example 1: 
\begin{center}\begin{minipage}{15cm}\begin{Verbatim}[frame=single]
> verbosity=1!;
> procedure EXP(X,n,p) {
            var res, oldPrec;
            oldPrec = prec;
            prec = p!;
            "Using procedure function exponential with X=" @ X @ ", n=" @ n @ ",
 and p=" @ p;
            res = exp(X);
            prec = oldPrec!;
            return res;
       };
> g = function(EXP);
> p = 46768052394588893382516870161332864698044514954899b-165 + x * (23384026197
294446691258465802074096632225783601255b-164 + x * (58460065493236116729484266
13035653821819225877423b-163 + x * (389733769954907444862769649080681513731982
1946501b-164 + x * (7794675399098148717422744621371434831048848817417b-167 + x
 * (24942961277114075921122941174178849425809856036737b-171 + x * (83143204257
04876115613838900105097456456371179471b-172 + x * (190041609730397013715793569
91645932289422670402995b-176 + x * (190041609726693241489121222544499121560039
26801563b-179 + x * (33785175062542597526738679493857229456702396042255b-183 +
 x * (6757035113643674378393625988264926886191860669891b-184 + x * (9828414707
511252769908089206114262766633532289937b-188 + x * (26208861108003813314724515
233584738706961162212965b-193 + x * (32257064253325954315953742396999456577223
350602741b-197 + x * (578429089657689569703509185903214676926704485495b-195 + 
x * 2467888542176675658523627105540996778984959471957b-201))))))))))))));
> h = annotatefunction(g, p, [-1/2;1/2], [-475294848522543b-124;475294848522543b
-124]);
> h == g;
true
> prec = 24;
The precision has been set to 24 bits.
> h(0.25);
Warning: rounding has happened. The value displayed is a faithful rounding to 24
 bits of the true result.
Warning: For at least 1 of the constants displayed in decimal, rounding has happ
ened.
1.2840254
> prec = 165;
The precision has been set to 165 bits.
> h(0.25);
Using procedure function exponential with X=[0.25;0.25], n=0, and p=185
Warning: rounding has happened. The value displayed is a faithful rounding to 16
5 bits of the true result.
Warning: For at least 1 of the constants displayed in decimal, rounding has happ
ened.
1.28402541668774148407342056806243645833628086528147
\end{Verbatim}
\end{minipage}\end{center}
See also: \textbf{chebyshevform} (\ref{labchebyshevform}), \textbf{taylorform} (\ref{labtaylorform}), \textbf{remez} (\ref{labremez}), \textbf{supnorm} (\ref{labsupnorm}), \textbf{infnorm} (\ref{labinfnorm})
