1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
|
\subsection{library}
\label{lablibrary}
\noindent Name: \textbf{library}\\
\phantom{aaa}binds an external mathematical function to a variable in \sollya\\[0.2cm]
\noindent Library names:\\
\verb| sollya_obj_t sollya_lib_libraryfunction(sollya_obj_t, char *,|\\
\verb| int (*)(mpfi_t, mpfi_t, int))|\\
\verb| sollya_obj_t sollya_lib_build_function_libraryfunction(sollya_obj_t, char *,|\\
\verb| int (*)(mpfi_t,|\\
\verb| mpfi_t, int))|\\
\verb| sollya_obj_t sollya_lib_libraryfunction_with_data(|\\
\verb| sollya_obj_t, char *,|\\
\verb| int (*)(mpfi_t, mpfi_t, int, void *),|\\
\verb| void *, void (*)(void *))|\\
\verb| sollya_obj_t sollya_lib_build_function_libraryfunction_with_data(|\\
\verb| sollya_obj_t, char *,|\\
\verb| int (*)(mpfi_t,|\\
\verb| mpfi_t, int, void *),|\\
\verb| void *, void (*)(void *))|\\[0.2cm]
\noindent Usage:
\begin{center}
\textbf{library}(\emph{path}) : \textsf{string} $\rightarrow$ \textsf{function}\\
\end{center}
\noindent Description: \begin{itemize}
\item The command \textbf{library} lets you extend the set of mathematical
functions known to \sollya.
By default, \sollya knows the most common mathematical functions such
as \textbf{exp}, \textbf{sin}, \textbf{erf}, etc. Within \sollya, these functions may be
composed. This way, \sollya should satisfy the needs of a lot of
users. However, for particular applications, one may want to
manipulate other functions such as Bessel functions, or functions
defined by an integral or even a particular solution of an ODE.
\item \textbf{library} makes it possible to let \sollya know about new functions. In
order to let it know, you have to provide an implementation of the
function you are interested in. This implementation is a C file containing
a function of the form:
\begin{verbatim} int my_ident(sollya_mpfi_t result, sollya_mpfi_t op, int n)\end{verbatim}
The semantic of this function is the following: it is an implementation of
the function and its derivatives in interval arithmetic.
\verb|my_ident(result, I, n)| shall store in \verb|result| an enclosure
of the image set of the $n$-th derivative
of the function f over \verb|I|: $f^{(n)}(I) \subseteq \mathrm{result}$.
\item The integer value returned by the function implementation currently has no
meaning.
\item You do not need to provide a working implementation for any \verb|n|. Most
functions of \sollya requires a relevant implementation only for $f$,
$f'$ and $f''$. For higher derivatives, its is not so critical and the
implementation may just store $[-\infty,\,+\infty]$ in result whenever $n>2$.
\item Note that you should respect somehow interval-arithmetic standards in your
implementation: \verb|result| has its own precision and you should perform the
intermediate computations so that \verb|result| is as tight as possible.
\item You can include sollya.h in your implementation and use library
functionnalities of \sollya for your implementation. However, this requires to
have compiled \sollya with \texttt{-fPIC} in order to make the \sollya executable code
position independent and to use a system on with programs, using \texttt{dlopen} to
open dynamic routines can dynamically open themselves. \textbf{Important notice:} as
the code will be run in a context where a sollya session is already opened,
the library functions must be used directly, without calling \verb|sollya_lib_init|
and \verb|sollya_lib_close| (calling these functions would conflict with the
current session, leading to weird and hard to debug behaviors).
\item To bind your function into \sollya, you must use the same identifier as the
function name used in your implementation file (\verb|my_ident| in the previous
example). Once the function code has been bound to an identifier, you can use
a simple assignment to assign the bound identifier to yet another identifier.
This way, you may use convenient names inside \sollya even if your
implementation environment requires you to use a less convenient name.
\item The dynamic object file whose name is given to \textbf{library} for binding of an
external library function may also define a destructor function
\verb|int sollya_external_lib_close(void)|.
If \sollya finds such a destructor function in the dynamic object file, it
will call that function when closing the dynamic object file again.
This happens when \sollya is terminated or when the current \sollya session
is restarted using \textbf{restart}.
The purpose of the destructor function is to allow the dynamically bound code
to free any memory that it might have allocated before \sollya is terminated
or restarted.
The dynamic object file is not necessarily needed to define a destructor
function. This ensure backward compatibility with older \sollya external
library function object files.
When defined, the destructor function is supposed to return an integer
value indicating if an error has happened. Upon success, the destructor
functions is to return a zero value, upon error a non-zero value.
\end{itemize}
\noindent Example 1:
\begin{center}\begin{minipage}{15cm}\begin{Verbatim}[frame=single]
> bashexecute("gcc -fPIC -Wall -c libraryexample.c -I$HOME/.local/include");
> bashexecute("gcc -shared -o libraryexample libraryexample.o -lgmp -lmpfr");
> myownlog = library("./libraryexample");
> evaluate(log(x), 2);
0.69314718055994530941723212145817656807550013436025
> evaluate(myownlog(x), 2);
0.69314718055994530941723212145817656807550013436025
\end{Verbatim}
\end{minipage}\end{center}
See also: \textbf{function} (\ref{labfunction}), \textbf{bashexecute} (\ref{labbashexecute}), \textbf{externalproc} (\ref{labexternalproc}), \textbf{externaldata} (\ref{labexternaldata}), \textbf{externalplot} (\ref{labexternalplot}), \textbf{diff} (\ref{labdiff}), \textbf{evaluate} (\ref{labevaluate}), \textbf{libraryconstant} (\ref{lablibraryconstant})
|
