Description:

• When a given function f is to be evaluated at several points of a given interval I to a given precision, it might be useful to precompute a good approximant g of f and further evaluate it instead of f when the approximation is good enough to provide the desire precision. If f is a complicated expression, whereas g is, e.g., a polynomial of low degree, the cost of precomputing g can be well compensated by the gain of time in each subsequent evaluation. The purpose of annotatefunction is to provide such a mechanism to the user.
• When using annotatefunction(f, g, I, d, x0), resp. annotatefunction(f, g, I, d) (where x0 is assumed to be zero), it is assumed that forall x in I, f(x) - g(x - x0) in d. It is the user responsability to ensure this property. Otherwise, any subsequent use of f on points of I might lead to incorrect values.
• A call to annotatefunction(f, g, I, d, x0) annotates the given Sollya function object f with the approximation g. In further use, when asked to evaluate f on a point x of I, Sollya will first evaluate g on x-x0 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-x0) belongs to d). If not (and only in this case), an evaluation of the expression of f on x is performed.
• The approximation g can be any Sollya function but particular performance is expected when g is a polynomial. Upon annotation with a polynomial, precomputations are performed to analyze certain properties of the given approximation polynomial.
• annotatefunction updates the internal representation of f so as to persistently keep this information attached with the Sollya object representing f. In particular, the annotation is persistent through copy or use of f as a subexpression to build up bigger expressions. Notice however, that there is no way of deducing an annotation for the derivative of f from an annotation of f. So, in general, it should not be expected that diff(f) will be automatically annotated (notice, however that f might be a subexpression of its derivative, e.g., for f=exp or f=tan, in which case the corresponding subexpressions of the derivative could inherit the annotations from f. It is currently not specified whether Sollya does this automatically or not).
• annotatefunction really is an imperative statement that modifies the internal representation of f. However, for convenience annotatefunction returns f itself.
• 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 x.