Users' manual for the Sollya tool - Release 6.0

License

The Sollya tool is Copyright © 2006-2016 by

Laboratoire de l'Informatique du Parallélisme UMR CNRS - ENS Lyon - UCB Lyon 1 - INRIA 5668 Lyon, France,
LORIA (CNRS, INPL, INRIA, UHP, U-Nancy 2), Nancy, France,
Laboratoire d'Informatique de Paris 6 - Équipe PEQUAN Sorbonne Universités UPMC Univ Paris 06 UMR 7606, LIP6 Boîte Courrier 169 4, place Jussieu F-75252 Paris Cedex 05 France,
CNRS, LIP6, UPMC Sorbonne Universités, UPMC Univ Paris 06 CNRS, LIP6 UMR 7606, 4 place Jussieu 75005 Paris,
and by

INRIA Sophia-Antipolis Méditerranée, APICS Team, Sophia-Antipolis, France.
All rights reserved.

This software is governed by the CeCILL-C license under French law and abiding by the rules of distribution of free software. You can use, modify and/ or redistribute the software under the terms of the CeCILL-C license as circulated by CEA, CNRS and INRIA at the following URL http://www.cecill.info.

As a counterpart to the access to the source code and rights to copy, modify and redistribute granted by the license, users are provided only with a limited warranty and the software's author, the holder of the economic rights, and the successive licensors have only limited liability.

In this respect, the user's attention is drawn to the risks associated with loading, using, modifying and/or developing or reproducing the software by the user in light of its specific status of free software, that may mean that it is complicated to manipulate, and that also therefore means that it is reserved for developers and experienced professionals having in-depth computer knowledge. Users are therefore encouraged to load and test the software's suitability as regards their requirements in conditions enabling the security of their systems and/or data to be ensured and, more generally, to use and operate it in the same conditions as regards security.

The fact that you are presently reading this means that you have had knowledge of the CeCILL-C license and that you accept its terms.

This program is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Direct access to the list of available commands

1 - Compilation and installation of Sollya

Sollya comes in two flavors:

• Either as an interactive tool. This is achieved by running the Sollya executable file.
• Or as a C library that provides all the features of the tool within the C programming language.

The installation of the tool and the library follow the same steps, desribed below. The present documentation focuses more on the interactive tool. As a matter of fact, the library works exactly the same way as the tool, so it is necessary to know a little about the tool in order to correctly use the library. The reader who is only interested in the library should at least read the following Sections Introduction, General Principles and Data Types. A documentation specifically describing the library usage is available in Appendix the Sollya library at the end of the present documentation.

1.1 - Compilation dependencies

The Sollya distribution can be compiled and installed using the usual ./configure, make, make install procedure. Besides a C and a C++ compiler, Sollya needs the following software libraries and tools to be installed. The ./configure script checks for the installation of the libraries. However Sollya will build without error if some of its external tools are not installed. In this case an error will be displayed at runtime.

• GMP
• MPFR
• MPFI
• fplll
• libxml2
• gnuplot (external tool)

The use of the external tool rlwrap is highly recommended but not required to use the Sollya interactive tool. Use the -A option of rlwrap for correctly displayed ANSI X3.64/ ISO/IEC 6429 colored prompts (see below).

1.2 - Sollya command line options

Sollya can read input on standard input or in a file whose name is given as an argument when Sollya is invoked. The tool will always produce its output on standard output, unless specificly instructed by a particular Sollya command that writes to a file. The following lines are valid invocations of Sollya, assuming that bash is used as a shell:

If a file given as an input does not exist, an error message is displayed.

All configurations of the internal state of the tool are done by commands given on the Sollya prompt or in Sollya scripts. Nevertheless, some command line options are supported; they work at a very basic I/O-level and can therefore not be implemented as commands.

The following options are supported when calling Sollya:

• --args: This special argument indicates to Sollya that subsequent command line arguments are no longer to be interpreted but are to be passed as-is to the predefined Sollya variable __argv. The --args argument is implicitly assumed if a Sollya script filename has already been specified with a preceding command line argument and none of the subsequent command line arguments is one of the special options given in this list.
• --donotmodifystacksize: When invoked, Sollya trys to increase the stack size that is available to a user process to the maximum size supported by the kernel. On some systems, the correspondent ioctl does not work properly. Use the option to prevent Sollya from changing the stack size.
• --flush: When this option is given, Sollya will flush all its input and output buffers after parsing and executing each command resp. sequence of commands. This option is needed when pipes are used to communicate with Sollya from another program.
• --help: Prints help on the usage of the tool and quits.
• --nocolor: Sollya supports coloring of the output using ANSI X3.64/ ISO/IEC 6429 escape sequences. Coloring is deactivated when Sollya is connected on standard input to a file that is not a terminal. This option forces the deactivation of ANSI coloring. This might be necessary on very old grey-scale terminals or when encountering problems with old versions of rlwrap.
• --noprompt: Sollya prints a prompt symbol when connected on standard input to a pseudo-file that is a terminal. The option deactivates the prompt.
• --oldautoprint: The behaviour of an undocumented feature for displaying values has changed in Sollya from version 1.1 to version 2.0. The old feature is deprecated. If you wish to use it nevertheless, use this deprecated option.
• --oldexternalprocprint: The behavior of an undocumented feature for displaying Sollya objects representing external procedures upon automatic printing at the Sollya prompt has been changed in Sollya from version 4.1 to version 5.0. The old feature is deprecated. If you wish to use it nevertheless, use this deprecated option.
• --oldrlwrapcompatible: This option is deprecated. It makes Sollya emit a non ANSI X3.64 compliant coloring escape sequence for making it compatible with versions of rlwrap that do not support the -A option. The option is considered a hack since it is known to garble the output of the tool under some particular circumstances.
• --warninfile[append] <file>: Normally, Sollya emits warning and information messages together with all other displayed information on either standard output or standard error. This option allows all warning and information messages to get redirected to a file. The filename to be used must be given after the option. When --warninfile is used, the existing content (if any) of the file is first removed before writing to the file. With --warninfileappend, the messages are appended to an existing file. Even if coloring is used for the displaying all other Sollya output, no coloring sequences are ever written to the file. Let us emphasize on the fact that any file of a unixoid system can be used for output, for instance also a named pipe. This allows for error messaging to be performed on a separate terminal. The use of this option is mutually exclusive with the --warnonstderr option.
• --warnonstderr: Normally, Sollya prints warning and information messages on standard output, using a warning color when coloring is activated. When this option is given, Sollya will output all warning and information messages on standard error. Coloring will be used even on standard error, when activated. The use of this option is mutually exclusive with the --warninfile[append] option.

2 - Introduction

Sollya is an interactive tool for handling numerical functions and working with arbitrary precision. It can evaluate functions accurately, compute polynomial approximations of functions, automatically implement polynomials for use in math libraries, plot functions, compute infinity norms, etc. Sollya is also a full-featured script programming language with support for procedures etc.

Let us begin this manual with an example. Sollya does not allow command line edition; since this may quickly become uncomfortable, we highly suggest to use the rlwrap tool with Sollya:

Sollya manipulates only functions in one variable. The first time that an unbound variable is used, this name is fixed. It will be used to refer to the free variable. For instance, try

Now, the name 'x' can only be used to refer to the free variable:

If you really want to unbind 'x', you can use the rename command and change the name of the free variable:

Sollya has a reserved keyword that can always be used to refer to the free variable. This keyword is _x_. This is particularly useful in contexts when the name of the variable is not known: typically when refering to the free variable in a pattern matching or inside a procedure.

As you have seen, you can name functions and easily work with them. The basic thing to do with a function is to evaluate it at some point:

The printed value is generally a faithful rounding of the exact value at the working precision (i.e., one of the two floating-point numbers enclosing the exact value). Internally Sollya represents numbers as floating-point numbers in arbitrary precision with radix 2: the fact that a faithful rounding is performed in binary does not imply much on the exactness of the digits displayed in decimal. The working precision is controlled by the global variable prec:

Sometimes a faithful rounding cannot easily be computed. In such a case, a value is printed that was obtained using floating-point approximations without control on the final accuracy:

The philosophy of Sollya is: Whenever something is not exact, print a warning. This explains the warnings in the previous examples. If the result can be shown to be exact, there is no warning:

Let us finish this Section with a small complete example that shows a bit of what can be done with Sollya:

In this example, we define a function f, an interval d and we compute the best degree-2 polynomial approximation of f on d with respect to the infinity norm. In other words, max {|p(x)-f(x)|, x in d} is minimal amongst polynomials with degree not greater than 2. Then, we compute the list of the zeros of the derivative of p-f and add the bounds of d to this list. Finally, we evaluate |p-f| for each point in the list and store the maximum and the point where it is reached. We conclude by printing the result in a formatted way.

Let us mention as a sidenote that you do not really need to use such a script for computing an infinity norm; as we will see, the command dirtyinfnorm does this for you.

3 - General principles

The first purpose of Sollya is to help people using numerical functions and numerical algorithms in a safe way. It is first designed to be used interactively but it can also be used in scripts (remark: some of the behaviors of Sollya slightly change when it is used in scripts. For example, no prompt is printed).

One of the particularities of Sollya is to work with multi-precision arithmetic (it uses the MPFR library). For safety purposes, Sollya knows how to use interval arithmetic. It uses interval arithmetic to produce tight and safe results with the precision required by the user.

The general philosophy of Sollya is: When you can perform a computation exactly and sufficiently quickly, do it; when you cannot, do not, unless you have been explicitly asked for.

The precision of the tool is set by the global variable prec. In general, the variable prec determines the precision of the outputs of commands: more precisely, the command will internally determine how much precision should be used during the computations in order to ensure that the output is a faithfully rounded result with prec bits.

For decidability and efficiency reasons, this general principle cannot be applied every time, so be careful. Moreover certain commands are known to be unsafe: they give in general excellent results and give almost prec correct bits in output for everyday examples. However they are merely based on heuristics and should not be used when the result must be safe. See the documentation of each command to know precisely how confident you can be with their result.

A second principle (that comes together with the first one) is the following one: When a computation leads to inexact results, inform the user with a warning. This can be quite irritating in some circumstances: in particular if you are using Sollya within other scripts. The global variable verbosity lets you change the level of verbosity of Sollya. When the variable is set to 0, Sollya becomes completely silent on standard output and prints only very important messages on standard error. Increase verbosity if you want more information about what Sollya is doing. Please keep in mind that when you affect a value to a global variable, a message is always printed even if verbosity is set to 0. In order to silently affect a global variable, use !:

For conviviality reasons, values are displayed in decimal by default. This lets a normal human being understand the numbers they manipulate. But since constants are internally represented in binary, this causes permanent conversions that are sources of roundings. Thus you are loosing in accuracy and Sollya is always complaining about inexact results. If you just want to store or communicate your results (to another tools for instance) you can use bit-exact representations available in Sollya. The global variable display defines the way constants are displayed. Here is an example of the five available modes:

Please keep in mind that it is possible to maintain the general verbosity level at some higher setting while deactivating all warnings on roundings. This feature is controlled using the roundingwarnings global variable. It may be set to on or off. By default, the warnings are activated (roundingwarnings = on) when Sollya is connected on standard input to a pseudo-file that represents a terminal. They are deactivated when Sollya is connected on standard input to a real file. See roundingwarnings for further details; the behavior is illustrated with examples there.

As always, the symbol e means (* 10^x). The same way the symbol b means (* 2^x). The symbol p means (* 16^x) and is used only with the 0x prefix. The prefix 0x indicates that the digits of the following number until a symbol p or white-space are hexadecimal. The suffix _2 indicates to Sollya that the previous number has been written in binary. Sollya can parse these notations even if you are not in the corresponding display mode, so you can always use them.

You can also use memory-dump hexadecimal notation frequently used to represent IEEE 754 double and single precision numbers. Since this notation does not allow for exactly representing numbers with arbitrary precision, there is no corresponding display mode. However, the commands printdouble respectively printsingle round the value to the nearest double respectively single. The number is then printed in hexadecimal as the integer number corresponding to the memory representation of the IEEE 754 double or single number:

Sollya can parse these memory-dump hexadecimal notation back in any display mode. The difference of this memory-dump notation with the hexadecimal notation (as defined above) is made by the presence or absence of a p indicator.

4 - Variables

As already explained, Sollya can manipulate variate functional expressions in one variable. These expressions contain a unique free variable the name of which is fixed by its first usage in an expression that is not a left-hand-side of an assignment. This global and unique free variable is a variable in the mathematical sense of the term.

Sollya also provides variables in the sense programming languages give to the term. These variables, which must be different in their name from the global free variable, may be global or declared and attached to a block of statements, i.e., a begin-end-block. These programming language variables may hold any object of the Sollya language, as for example functional expressions, strings, intervals, constant values, procedures, external functions and procedures, etc.

Global variables need not to be declared. They start existing, i.e., can be correctly used in expressions that are not left-hand-sides of assignments, when they are assigned a value in an assignment. Since they are global, this kind of variables is recommended only for small Sollya scripts. Larger scripts with code reuse should use declared variables in order to avoid name clashes for example in loop variables.

Declared variables are attached to a begin-end-block. The block structure builds scopes for declared variables. Declared variables in inner scopes shadow (global and declared) variables of outer scopes. The global free variable, i.e., the mathematical variable for variate functional expressions in one variable, cannot be shadowed. Variables are declared using the var keyword. See Section var for details on its usage and semantic.

The following code examples illustrate the use of variables.

Let us state that a variable identifier, just as every identifier in Sollya, contains at least one character, starts with a ASCII letter and continues with ASCII letters or numerical digits.

Two predefined variables exist when Sollya is started:

• __argv : This variable contains, on Sollya startup and after the execution of the restart command, a list of character strings that correspond to the command line options given to Sollya after the (implicit) command line argument --args (see above).
• __unique_id : This variable contains, on Sollya startup and after the execution of the restart command, a character string that uniquely identifies the given Sollya session on a system. It hence allows for concurrent execution of Sollya scripts that use temporary files for communication with other tools. The character string is made of alphanumeric characters ([0-9a-zA-Z]) and dashes (-) and underscores (_). In particular, it does not contain any space. After the execution of the restart command, the __unique_id variable is refreshed with a new, unique value.

Even though these variables exist upon Sollya startup with predefined values, they behave like any other variable: the predefined value can be overwritten by assigning any new value to the variables, the variables can be shadowed by declared, local variables of the same name and so on.

5 - Data types

Sollya has a (very) basic system of types. If you try to perform an illicit operation (such as adding a number and a string, for instance), you will get a typing error. Let us see the available data types.

5.1 - Booleans

There are two special values true and false. Boolean expressions can be constructed using the boolean connectors && (and), || (or), ! (not), and cosmparisons.

The comparison operators <, <=, > and >= can only be used between two numbers or constant expressions.

The comparison operators == and != are polymorphic. You can use them to compare any two objects, like two strings, two intervals, etc. As a matter of fact, polymorphism is allowed on both sides: it is possible to compare objects of different type. Such objects of different type, as they can never be syntactically equal, will always compare unequal (see exception for error, Section error) and never equal. It is important to remember that testing the equality between two functions will return true if and only if the expression trees representing the two functions are exactly the same or automatic simplification is activated and both functions are polynomials that are equal. See error for an exception concerning the special object error. Example:

5.2 - Numbers

Sollya represents numbers as binary multi-precision floating-point values. For integer values and values in dyadic, binary, hexadecimal or memory dump notation, it automatically uses a precision needed for representing the value exactly (unless this behaviour is overridden using the syntax given below). Additionally, automatic precision adaption takes place for all integer values (even in decimal notation) written without the exponent sign e or with the exponent sign e and an exponent sufficiently small that they are less than 10^999. Otherwise the values are represented with the current precision prec. When a number must be rounded, it is rounded to the precision prec before the expression get evaluated:

As a matter of fact, each variable has its own precision that corresponds to its intrinsic precision or, if it cannot be represented, to the value of prec when the variable was set. Thus you can work with variables having a precision higher than the current precision.

The same way, if you define a function that refers to some constant, this constant is stored in the function with the current precision and will keep this value in the future, even if prec becomes smaller.

If you define a function that refers to some variable, the precision of the variable is kept, independently of the current precision:

In some rare cases, it is necessary to read in decimal constants with a particular precision being used in the conversion to the binary floating-point format, which Sollya uses. Setting prec to that precision may prove to be an insufficient means for doing so, for example when several different precisions have to be used in one expression. For these rare cases, Sollya provides the following syntax: decimal constants may be written %precision%constant, where precision is a constant integer, written in decimal, and constant is the decimal constant. Sollya will convert the constant constant with precision precision, regardless of the global variable prec and regardless if constant is an integer or would otherwise be representable.

Sollya is an environment that uses floating-point arithmetic. The IEEE 754-2008 standard on floating-point arithmetic does not only define floating-point numbers that represent real numbers but also floating-point data representing infinities and Not-a-Numbers (NaNs). Sollya also supports infinities and NaNs in the spirit of the IEEE 754-2008 standard without taking the standard's choices literally.

• Signed infinities are available through the Sollya objects infty, -infty, @Inf@ and -@Inf@.
• Not-a-Numbers are supported through the Sollya objects NaN and @NaN@. Sollya does not have support for NaN payloads, signaling or quiet NaNs or signs of NaNs. Signaling NaNs are supported on input for single and double precision memory notation (see Section General Principles). However, they immediately get converted to plain Sollya NaNs.

The evaluation of an expression involving a NaN or the evaluation of a function at a point being NaN always results in a NaN.

Infinities are considered to be the limits of expressions tending to infinity. They are supported as bounds of intervals in some cases. However, particular commands might prohibit their use even though there might be a mathematical meaning attached to such expressions. For example, while Sollya will evaluate expressions such as the limit of e^x when x goes to -infinity, expressed e.g., through evaluate(exp(x),[-infty;0]), it will not accept to compute the (finite) value of the integral of e^x between -infinity and 0.

The following examples give an idea of what can be done with Sollya infinities and NaNs. Here is what can be done with infinities:

And the following example illustrates NaN behavior.

5.3 - Rational numbers and rational arithmetic

The Sollya tool is mainly based on floating-point arithmetic: wherever possible, floating-point algorithms, including algorithms using interval arithmetic, are used to produce approximate but safe results. For some particular cases, floating-point arithmetic is not sufficient: some algorithms just require natural and rational numbers to be handled exactly. More importantly, for these applications, it is required that rational numbers be displayed as such.

Sollya implements a particular mode that offers a lightweight support for rational arithmetic. When needed, it can be enabled by assigning on to the global variable rationalmode. It is disabled by assigning off; the default is off.

When the mode for rational arithmetic is enabled, Sollya's behavior will change as follows:

• When a constant expression is given at the Sollya prompt, Sollya will first try to simplify the expression to a rational number. If such an evaluation to a rational number is possible, Sollya will display that number as an integer or a fraction of two integers. Only if Sollya is not able to simplify the constant expression to a rational number, it will launch the default behavior of evaluating constant expressions to floating-point numbers that are generally faithful roundings of the expressions.
• When the global mode autosimplify is on, which is the default, Sollya will additionally use rational arithmetic while trying to simplify expressions given in argument of commands.

Even when rationalmode is on, Sollya will not be able to exhibit integer ratios between transcendental quantities. For example, Sollya will not display 1/6 for arcsin(1/2)/pi but 0.16666... Sollya's evaluator for rational arithmetic is only able to simplify rational expressions based on addition, subtraction, multiplication, division, negation, perfect squares (for square root) and integer powers.

The following example illustrates what can and what cannot be done with Sollya's mode for rational arithmetic:

5.4 - Intervals and interval arithmetic

Sollya can manipulate intervals that are closed subsets of the real numbers. Several ways of defining intervals exist in Sollya. There is the most common way where intervals are composed of two numbers or constant expressions representing the lower and the upper bound. These values are separated either by commas or semi-colons. Interval bound evaluation is performed in a way that ensures the inclusion property: all points in the original, unevaluated interval will be contained in the interval with its bounds evaluated to floating-point numbers.

Sollya has a mode for printing intervals that are that thin that their bounds have a number of decimal digits in common when printed. That mode is called midpointmode; see below for an introduction and Section midpointmode for details. As Sollya must be able to parse back its own output, a syntax is provided to input intervals in midpoint mode. However, please pay attention to the fact that the notation used in midpoint mode generally increases the width of intervals: hence when an interval is displayed in midpoint mode and read again, the resulting interval may be wider than the original interval.

In some cases, intervals become infinitely thin in theory, in which case one tends to think of point intervals even if their floating-point representation is not infinitely thin. Sollya provides a very covenient way for input of such point intervals. Instead of writing [a;a], it is possible to just write [a]. Sollya will expand the notation while making sure that the inclusion property is satisfied:

When the mode midpointmode is set to on (see midpointmode), Sollya will display intervals that are provably reduced to one point in this extended interval syntax. It will use midpointmode syntax for intervals that are sufficiently thin but not reduced to one point (see Section midpointmode for details):

Sollya intervals are internally represented with floating-point numbers as bounds; rational numbers are not supported here. If bounds are defined by constant expressions, these are evaluated to floating-point numbers using the current precision. Numbers or variables containing numbers keep their precision for the interval bounds.

Constant expressions get evaluated to floating-point values immediately; this includes pi and rational numbers, even when rationalmode is on (see Section Rational numbers and rational arithmetic for this mode).

You can get the upper-bound (respectively the lower-bound) of an interval with the command sup (respectively inf). The middle of the interval can be computed with the command mid. Let us also mention that these commands can also be used on numbers (in that case, the number is interpreted as an interval containing only one single point. In that case the commands inf, mid and sup are just the identity):

Let us mention that the mid operator never provokes a rounding. It is rewritten as an unevaluated expression in terms of inf and sup.

Sollya permits intervals to also have non-real bounds, such as infinities or NaNs. When evaluating certain expressions, in particular given as interval bounds, Sollya will itself generate intervals containing infinities or NaNs. When evaluation yields an interval with a NaN bound, the given expression is most likely undefined or numerically unstable. Such results should not be trusted; a warning is displayed.

While computations on intervals with bounds being NaN will always fail, Sollya will try to interpret infinities in the common way as limits. However, this is not guaranteed to work, even if it is guaranteed that no unsafe results will be produced. See also section Numbers for more detail on infinities in Sollya. The behavior of interval arithmetic on intervals containing infinities or NaNs is subject to debate; moreover, there is no complete consensus on what should be the result of the evaluation of a function f over an interval I containing points where f is not defined. Sollya has its own philosophy regarding these questions. This philosophy is explained in Appendix interval arithmetic philosophy in Sollya at the end of this document.

Sollya internally uses interval arithmetic extensively to provide safe answers. In order to provide for algorithms written in the Sollya language being able to use interval arithmetic, Sollya offers native support of interval arithmetic. Intervals can be added, subtracted, multiplied, divided, raised to powers, for short, given in argument to any Sollya function. The tool will apply the rules of interval arithmetic in order to compute output intervals that safely encompass the hull of the image of the function on the given interval:

When such expressions involving intervals are given, Sollya will follow the rules of interval arithmetic in precision prec for immediately evaluating them to interval enclosures. While Sollya's evaluator always guarantees the inclusion property, it also applies some optimisations in some cases in order to make the image interval as thin as possible. For example, Sollya will use a Taylor expansion based evaluation if a composed function, call it f, is applied to an interval. In other words, in this case Sollya will behave as if the evaluate command (see Section evaluate) were implicitly used. In most cases, the result will be different from the one obtained by replacing all occurences of the free variable of a function by the interval the function is to be evaluated on:

5.5 - Functions

Sollya knows only about functions with one single variable. The first time in a session that an unbound name is used (without being assigned) it determines the name used to refer to the free variable.

The basic functions available in Sollya are the following:

• +, -, *, /, ^
• sqrt
• abs
• sin, cos, tan, sinh, cosh, tanh
• asin, acos, atan, asinh, acosh, atanh
• exp, expm1 (defined as expm1(x) = exp(x)-1)
• log (natural logarithm), log2 (binary logarithm), log10 (decimal logarithm), log1p (defined as log1p(x) = log(1+x))
• erf, erfc
• halfprecision, single, double, doubleextended, doubledouble, quad, tripledouble (see sections halfprecision, single, double, doubleextended, doubledouble, quad and tripledouble)
• HP, SG, D, DE, DD, QD, TD (see sections halfprecision, single, double, doubleextended, doubledouble, quad and tripledouble)
• floor, ceil, nearestint.

The constant pi is available through the keyword pi as a 0-ary function:

The reader may wish to see Sections library and function for ways of dynamically adding other base functions to Sollya.

5.6 - Strings

Anything written between quotes is interpreted as a string. The infix operator @ concatenates two strings. To get the length of a string, use the length function. You can access the i-th character of a string using brackets (see the example below). There is no character type in Sollya: the i-th character of a string is returned as a string itself.

Strings may contain the following escape sequences: \\, \“, \?, \', \n, \t, \a, \b, \f, \r, \v, \x[hexadecimal number] and \[octal number]. Refer to the C99 standard for their meaning.

5.7 - Particular values

Sollya knows about some particular values. These values do not really have a type. They can be stored in variables and in lists. A (possibly not exhaustive) list of such values is the following one:

• on, off (see sections on and off)
• dyadic, powers, binary, decimal, hexadecimal (see sections dyadic, powers, binary, decimal and hexadecimal)
• file, postscript, postscriptfile (see sections file, postscript and postscriptfile)
• RU, RD, RN, RZ (see sections ru, rd, rn and rz)
• absolute, relative (see sections absolute and relative)
• floating, fixed (see sections floating and fixed)
• halfprecision, single, double, doubleextended, doubledouble, quad, tripledouble (see sections halfprecision, single, double, doubleextended, doubledouble, quad and tripledouble)
• HP, SG, D, DE, DD, QD, TD (see sections halfprecision, single, double, doubleextended, doubledouble, quad and tripledouble)
• perturb (see Section perturb)
• honorcoeffprec (see Section honorcoeffprec)
• default (see Section default)
• error (see Section error)
• void (see Section void)

5.8 - Lists

Objects can be grouped into lists. A list can contain elements with different types. As for strings, you can concatenate two lists with @. The function length also gives the length of a list.

You can prepend an element to a list using .: and you can append an element to a list using :.
The following example illustrates some features:

Lists can be considered arrays and elements of lists can be referenced using brackets. Possible indices start at 0. The following example illustrates this point:

Lists may contain ellipses indicated by ,..., between elements that are constant and evaluate to integers that are incrementally ordered. Sollya translates such ellipses to the full list upon evaluation. The use of ellipses between elements that are not constants is not allowed. This feature is provided for ease of programming; remark that the complexity for expanding such lists is high. For illustration, see the following example:

Lists may be continued to infinity by means of the ... indicator after the last element given. At least one element must explicitly be given. If the last element given is a constant expression that evaluates to an integer, the list is considered as continued to infinity by all integers greater than that last element. If the last element is another object, the list is considered as continued to infinity by re-duplicating this last element. Let us remark that bracket notation is supported for such end-elliptic lists even for implicitly given elements. However, evaluation complexity is high. Combinations of ellipses inside a list and in its end are possible. The usage of lists described here is best illustrated by the following examples:

5.9 - Structures

In a similar way as in lists, Sollya allows data to be grouped in – untyped – structures. A structure forms an object to which other objects can be added as elements and identified by their names. The elements of a structure can be retrieved under their name and used as usual. The following sequence shows that point:

Structures can also be defined literally using the syntax illustrated in the next example. They will also be printed in that syntax.

If the variable a is bound to an existing structure, it is possible to use the “dot notation” a.b to assign the value of the field b of the structure a. This works even if b is not yet a field of a: in this case a new field is created inside the structure a.

Besides, the dot notation can be used even when a is unassigned. In this case a new structure is created with a field b, and this structure is bound to a. However, the dot notation cannot be used if a is already bound to something that is not a structure.

These principles apply recursively: for instance, if a is a structure that contains only one field d, the command a.b.c = 3 creates a new field named b inside the structure a; this field itself is a structure containing the field c. The command a.d.c = 3 is allowed if a.d is already a structure, but forbidden otherwise (e.g., if a.d was equal to sin(x)). This is summed up in the following example.

When printed, the elements of a structure are not sorted in any manner. They get printed in an arbitrary order that just maintains the order given in the definition of literate structures. That said, when compared, two structures compare equal iff they contain the same number of identifiers, with the same names and iff the elements of corresponding names all compare equal. This means the order does not matter in comparisons and otherwise does only for printing.

The following example illustrates this matter:

6 - Iterative language elements: assignments, conditional statements and loops

6.1 - Blocks

Statements in Sollya can be grouped in blocks, so-called begin-end-blocks. This can be done using the key tokens { and }. Blocks declared this way are considered to be one single statement. As already explained in Section Variables, using begin-end-blocks also opens the possibility of declaring variables through the keyword var.

6.2 - Assignments

Sollya has two different assignment operators, = and :=. The assignment operator = assigns its right-hand-object “as is”, i.e., without evaluating functional expressions. For instance, i = i + 1; will dereferentiate the identifier i with some content, notate it y, build up the expression (function) y + 1 and assign this expression back to i. In the example, if i stood for the value 1000, the statement i = i + 1; would assign “1000 + 1” – and not “1001” – to i. The assignment operator := evaluates constant functional expressions before assigning them. On other expressions it behaves like =. Still in the example, the statement i := i + 1; really assigns 1001 to i.

Both Sollya assignment operators support indexing of lists or strings elements using brackets on the left-hand-side of the assignment operator. The indexed element of the list or string gets replaced by the right-hand-side of the assignment operator. When indexing strings this way, that right-hand side must evaluate to a string of length 1. End-elliptic lists are supported with their usual semantic for this kind of assignment. When referencing and assigning a value in the implicit part of the end-elliptic list, the list gets expanded to the corresponding length.

The following examples well illustrate the behavior of assignment statements:

The indexing of lists on left-hand sides of assignments is reduced to the first order. Multiple indexing of lists of lists on assignment is not supported for complexity reasons. Multiple indexing is possible in right-hand sides.

6.3 - Conditional statements

Sollya supports conditional statements expressed with the keywords if, then and optionally else. Let us mention that only conditional statements are supported and not conditional expressions.

The following examples illustrate both syntax and semantic of conditional statements in Sollya. Concerning syntax, be aware that there must not be any semicolon before the else keyword.

6.4 - Loops

Sollya supports three kinds of loops. General while-condition loops can be expressed using the keywords while and do. One has to be aware of the fact that the condition test is executed always before the loop, there is no do-until-condition loop. Consider the following examples for both syntax and semantic:

The second kind of loops are loops on a variable ranging from a numerical start value and a end value. These kind of loops can be expressed using the keywords for, from, to, do and optionally by. The by statement indicates the width of the steps on the variable from the start value to the end value. Once again, syntax and semantic are best explained with an example:

The third kind of loops are loops on a variable ranging on values contained in a list. In order to ensure the termination of the loop, that list must not be end-elliptic. The loop is expressed using the keywords for, in and do as in the following examples:

For both types of for loops, assigning the loop variable is allowed and possible. When the loop terminates, the loop variable will contain the value that made the loop condition fail. Consider the following examples:

7 - Functional language elements: procedures and pattern matching

7.1 - Procedures

Sollya has some elements of functional languages. In order to avoid confusion with mathematical functions, the associated programming objects are called procedures in Sollya.

Sollya procedures are common objects that can be, for example, assigned to variables or stored in lists. Procedures are declared by the proc keyword; see Section proc for details. The returned procedure object must then be assigned to a variable. It can hence be applied to arguments with common application syntax. The procedure keyword provides an abbreviation for declaring and assigning a procedure; see Section procedure for details.

Sollya procedures can return objects using the return keyword at the end of the begin-end-block of the procedure. Section return gives details on the usage of return. Procedures further can take any type of object in argument, in particular also other procedures that are then applied to arguments. Procedures can be declared inside other procedures.

Common Sollya procedures are declared with a certain number of formal parameters. When the procedure is applied to actual parameters, a check is performed if the right number of actual parameters is given. Then the actual parameters are applied to the formal parameters. In some cases, it is required that the number of parameters of a procedure be variable. Sollya provides support for the case with procedures with an arbitrary number of actual arguments. When the procedure is called, those actual arguments are gathered in a list which is applied to the only formal list parameter of a procedure with an arbitrary number of arguments. See Section procedure for the exact syntax and details; an example is given just below.

Let us remark that declaring a procedure does not involve any evaluation or other interpretation of the procedure body. In particular, this means that constants are evaluated to floating-point values inside Sollya when the procedure is applied to actual parameters and the global precision valid at this moment.

Sollya procedures are well illustrated with the following examples:

Let us note that, when writing a procedure, one does not know what will be the name of the free variable at run-time. This is typically the context when one should use the special keyword _x_:

Sollya also supports external procedures, i.e., procedures written in C (or some other language) and dynamically bound to Sollya identifiers. See externalproc for details.

7.2 - Pattern matching

Starting with version 3.0, Sollya supports matching expressions with expression patterns. This feature is important for an extended functional programming style. Further, and most importantly, it allows expression trees to be recursively decomposed using native constructs of the Sollya language. This means no help from external procedures or other compiled-language mechanisms is needed here anymore.

Basically, pattern matching supports relies on one Sollya construct:

That construct has the following semantic: try to match the expression expr with the patterns pattern1 through patternN, proceeding in natural order. If a pattern patternI is found that matches, evaluate the whole match ... with construct to the return expression return-exprI associated with the matching pattern patternI. If no matching pattern is found, display an error warning and return error. Note that the parentheses around the expressions return-exprI are mandatory.

Matching a pattern means the following:

• If a pattern does not contain any programming-language-level variables (different from the free mathematical variable), it matches expressions that are syntactically equal to itself. For instance, the pattern exp(sin(3 * x)) will match the expression exp(sin(3 * x)), but it does not match exp(sin(x * 3)) because the expressions are not syntactically equal.
• If a pattern does contain variables, it matches an expression expr if these variables can be bound to subexpressions of expr such that once the pattern is evaluated with that variable binding, it becomes syntactically equal to the expression expr. For instance, the pattern exp(sin(a * x)) will match the expression exp(sin(3 * x)) as it is possible to bind a to 3 such that exp(sin(a * x)) evaluates to exp(sin(3 * x)).

If a pattern patternI with variables is matched in a match ... with construct, the variables in the pattern stay bound during the evaluation of the corresponding return expression return-exprI. This allows subexpressions to be extracted from expressions and/or recursively handled as needed.

The following examples illustrate the basic principles of pattern matching in Sollya. One can remark that it is useful to use the keyword _x_ when one wants to be sure to refer to the free variable in a pattern matching:

As Sollya is not a purely functional language, the match ... with construct can also be used in a more imperative style, which makes it become closer to constructs like switch in C or Perl. In lieu of a simple return expression, a whole block of imperative statements can be given. The expression to be returned by that block is indicated in the end of the block, using the return keyword. That syntax is illustrated in the next example:

In the case when no return statement is indicated for a statement-block in a match ... with construct, the construct evaluates to the special value void if that pattern matches.

In order to well understand pattern matching in Sollya, it is important to realize the meaning of variables in patterns. This meaning is different from the one usually found for variables. In a pattern, variables are never evaluated to whatever they might have set before the pattern is executed. In contrast, all variables in patterns are new, free variables that will freshly be bound to subexpressions of the matching expression. If a variable of the same name already exists, it will be shadowed during the evaluation of the statement block and the return expression corresponding to the matching expression. This type of semantic implies that patterns can never be computed at run-time, they must always be hard-coded beforehand. However this is necessary to make pattern matching context-free.

As a matter of course, all variables figuring in the expression expr to be matched are evaluated before pattern matching is attempted. In fact, expr is a usual Sollya expression, not a pattern.

In Sollya, the use of variables in patterns does not need to be linear. This means the same variable might appear twice or more in a pattern. Such a pattern will only match an expression if it contains the same subexpression, associated with the variable, in all places indicated by the variable in the pattern.

The following examples illustrate the use of variables in patterns in detail:

Pattern matching is meant to be a means to decompose expressions structurally. For this reason and in an analogous way to variables, no evaluation is performed at all on (sub-)expressions that form constant functions. As a consequence, patterns match constant expressions only if they are structurally identical. For example 5+1 only matches 5+1 and not 1+5, 3+3 nor 6.

This general rule on constant expressions admits one exception. Intervals in Sollya can be defined using constant expressions as bounds. These bounds are immediately evaluated to floating-point constants, though. In order to permit pattern matching on intervals, constant expressions given as bounds of intervals that form patterns are evaluated before pattern matching. However, in order not conflict with the rules of no evaluation of variables, these constant expressions as bounds of intervals in patterns must not contain free variables.

The Sollya keyword default has a special meaning in patterns. It acts like a wild-card, matching any (sub-)expression, as long as the whole expression stays correctly typed. Upon matching with default, no variable gets bound. This feature is illustrated in the next example:

In Sollya, pattern matching is possible on the following Sollya types and operations defined on them:

• Expressions that define univariate functions, as explained above,
• Intervals with one, two or no bound defined in the pattern by a variable,
• Character sequences, literate or defined using the @ operator, possibly with a variable on one of the sides of the @ operator,
• Lists, literate, literate with variables or defined using the .:, :. and @ operators, possibly with a variable on one of the sides of the @ operator or one or two variables for .: and :.,
• Structures, literate or literate with variables, and
• All other Sollya objects, matchable with themselves (DE matches DE, on matches on, perturb matches perturb etc.)

Concerning intervals, please pay attention to the fact that expressions involving intervals are immediately evaluated and that structural pattern matching on functions on intervals is not possible. This point is illustrated in the next example:

With respect to pattern matching on lists or character sequences defined using the @ operator, the following is to be mentionned:

• Patterns like a @ b are not allowed as they would need to perform an ambiguous cut of the list or character sequence to be matched. This restriction is maintained even if the variables (here a and b) are constrained by other occurrences in the pattern (for example in a list) which would make the cut unambiguous.
• Recursive use of the @ operator (even mixed with the operators .: and :.) is possible under the condition that there must not exist any other parenthezation of the term in concatenations (@) such that the rule of one single variable for @ above gets violated. For instance, ( [| 1 |] @ a) @ (b @ [| 4 |]) is not possible as it can be re-parenthesized [| 1 |] @ (a @ b) @ [| 4 |], which exhibits the ambiguous case.

These points are illustrated in this example:

As mentionned above, pattern matching on Sollya structures is possible. Patterns for such a match are given in a literately, i.e., using the syntax { .a = exprA, .b = exprB, ... }. A structure pattern sp will be matched by a structure s iff that structure s contains at least all the elements (like .a, .b etc.) of the structure pattern sp and iff each of the elements of the structure s matches the pattern in the corresponding element of the structure pattern sp. The user should be aware of the fact that the structure to be matched is only supposed to have at least the elements of the pattern but that it may contain more elements is a particular Sollya feature. For instance with pattern matching, it is hence possible to ensure that access to particular elements will be possible in a particular code segment. The following example is meant to clarify this point:

8 - Commands and functions

The list of commands of Sollya is available in two flavours:

• As a single page containing the description of all the commands.
• Or with each command on a different page (faster to load).

9 - Appendix: interval arithmetic philosophy in Sollya

Although it is currently based on the MPFI library, Sollya has its own way of interpreting interval arithmetic when infinities or NaN occur, or when a function is evaluated on an interval containing points out of its domain, etc. This philosophy may differ from the one applied in MPFI. It is also possible that the behavior of Sollya does not correspond to the behavior that one would expect, e.g., as a natural consequence of the IEEE-754 standard.

The topology that we consider is always the usual topology of R bar: R U {-infinity, +infinity}. For any function, if one of its arguments is empty (respectively NaN), we return empty (respectively NaN).

9.1 - Univariate functions

Let f be a univariate basic function and I an interval. We denote by J the result of the interval evaluation of f over I in Sollya. If I is completely included in the domain of f, J will usually be the smallest interval (at the current precision) containing the exact image f(I) However, in some cases, it may happen that J is not as small as possible. It is guaranteed however, that J tends to f(I) when the precision of the tool tends to infinity.

When f is not defined at some point x but is defined on a neighborhood of x, we consider that the “value” of f at x is the convex hull of the limit points of f around x. For instance, consider the evaluation of f= tan on [0, Pi]. It is not defined at Pi/2 (and only at this point). The limit points of f around Pi/2 are -infinity and +infinity, so, we return [-infinity, +infinity]. Another example: f=sin on [+infinity]. The function has no limit at this point, but all points of [-1, 1] are limit points. So, we return [-1,1].

Finally, if I contains a subinterval on which f is not defined, we return [NaN, NaN] (example: sqrt([-1, 2])).

9.2 - Bivariate functions

Let f be a bivariate function and I1 and I2 be intervals. If I1=[x] and I2=[y] are both point-intervals, we return the convex hull of the limit points of f around (x, y) if it exists. In particular, if f is defined at (x, y) we return its value (or a small interval around it, if it is not exactly representable). As an example [1]/[+infinity] returns [0]. Also, [1]/[0] returns [-infinity, +infinity] (note that Sollya does not consider signed zeros). If it is not possible to give a meaning to the expression f(I1, I2), we return NaN: for instance [0]/[0] or [0]*[+infinity].

If one and only one of the intervals is a point-interval (say I1 = [x]), we consider the partial function g: y -> f(x,y) and return the value that would be obtained when evaluating g on I2. For instance, in order to evaluate [0]/I2, we consider the function g defined for every y != 0 by g(y)=0/y=0. Hence, g(I2) = [0] (even if I2 contains 0, by the argument of limit-points). In particular, please note that [0]/[-1, 1] returns [0] even though [0]/[0] returns NaN. This rule even holds when g can only be defined as limit points: for instance, in the case I1/[0] we consider g: x -> x/0. This function cannot be defined stricto sensu, but we can give it a meaning by considering 0 as a limit. Hence g is multivalued and its value is {-infinity, +infinity} for every x. Hence, I1/[0] returns [-infinity, +infinity] when I1 is not a point-interval.

Finally, if neither I1 nor I2 are point-intervals, we try to give a meaning to f(I1, I2) by an argument of limit-points when possible. For instance [1, 2] / [0, 1] returns [1, +infinity].

As a special exception to these rules, [0]^[0] returns [1].

10 - Appendix: the Sollya library

10.1 - Introduction

The header file of the Sollya library is sollya.h. Its inclusion may provoke the inclusion of other header files, such as gmp.h, mpfr.h or mpfi.h.

The library provides a virtual Sollya session that is perfectly similar to an interactive session: global variables such as verbosity, prec, display, midpointmode, etc. are maintained and affect the behavior of the library, warning messages are displayed when something is not exact, etc. Please notice that the Sollya library currently is not re-entrant and can only be opened once. A process using the library must hence not be multi-threaded and is limited to one single virtual Sollya session.

In order to get started with the Sollya library, the first thing to do is hence to initialize this virtual session. This is performed with the sollya_lib_init function. Accordingly, one should close the session at the end of the program (which has the effect of releasing all the memory used by Sollya). Please notice that Sollya uses its own allocation functions and registers them to GMP using the custom allocation functions provided by GMP. Particular precautions should hence be taken when using the Sollya library in a program that also registers its own functions to GMP: in that case sollya_lib_init_with_custom_memory_functions should be used instead of sollya_lib_init for initializing the library. This is discussed in a specific section.

In the usual case when Sollya is used in a program that does not register allocation functions to GMP, a minimal file using the library is hence the following.

Suppose that this code is saved in a file called foo.c. The compilation is performed as usual without forgetting to link against libsollya (since the libraries libgmp, libmpfr and libmpfi are dependencies of Sollya, it might also be necessary to explicitly link against them):

10.2 - Sollya object data-type

The library provides a single data type called sollya_obj_t that can contain any Sollya object (a Sollya object is anything that can be stored in a variable within the interactive tool. See Section Data Types of the present documentation for details). Please notice that sollya_obj_t is in fact a pointer type; this has two consequences:

• NULL is a placeholder that can be used as a sollya_obj_t in some contexts. This placeholder is particularly useful as an end marker for functions with a variable number of arguments (see Sections Lists and Commands and functions.
• An assignment with the “=” sign does not copy an object but only copies the reference to it. In order to perform a (deep) copy, the sollya_lib_copy_obj() function is available.

Except for a few functions for which the contrary is explicitly specified, the following conventions are used:

• A function does not touch its arguments. Hence if sollya_lib_foo is a function of the library, a call to sollya_lib_foo(a) leaves the object referenced by a unchanged (the notable exceptions to that rule are the functions containing build in their name, e.g., sollya_lib_build_foo).
• A function that returns a sollya_obj_t creates a new object (this means that memory is dynamically allocated for that object). The memory allocated for that object should manually be cleared when the object is no longer used and all references to it (on the stack) get out of reach, e.g., on a function return: this is performed by the sollya_lib_clear_obj() function. By convenience sollya_lib_clear_obj(NULL) is a valid call, which just does nothing.

In general, except if the user perfectly knows what they are doing, the following rules should be applied (here a and b are C variables of type sollya_obj_t, and sollya_lib_foo and sollya_lib_bar are functions of the library):

• One should never write a = b. Instead, use a = sollya_lib_copy_obj(b).
• One should never write a = sollya_lib_foo(a) because one loses the reference to the object initially referenced by the variable a (which is hence not cleared).
• One should never chain function calls such as, e.g., a = sollya_lib_foo(sollya_lib_bar(b)) (the reference to the object created by sollya_lib_bar(b) would be lost and hence not cleared).
• A variable a should never be used twice at the left-hand side of the “=” sign (or as an lvalue in general) without performing sollya_lib_clear_obj(a) in-between.
• In an assignment of the form “a = ...”, the right-hand side should always be a function call (i.e., something like a = sollya_lib_foo(...);).

Please notice that sollya_lib_close() clears the memory allocated by the virtual Sollya session but not the objects that have been created and stored in C variables. All the sollya_obj_t created by function calls should be cleared manually.

We can now write a simple Hello World program using the Sollya library:

A universal function allows the user to execute any expression, as if it were given at the prompt of the Sollya tool, and to get a sollya_obj_t containing the result of the evaluation: this function is sollya_lib_parse_string("some expression here"). This is very convenient, and indeed, any script written in the Sollya language, could easily be converted into a C program by intensively using sollya_lib_parse_string. However, this should not be the preferred way if efficiency is targeted because (as its name suggests) this function uses a parser to decompose its argument, then constructs intermediate data structures to store the abstract interpretation of the expression, etc. Low-level functions are provided for efficiently creating Sollya objects; they are detailed in the next Section.

10.3 - Conventions in use in the library

The library follows some conventions that are useful to remember:

• When a function is a direct transposition of a command or function available in the interactive tool, it returns a sollya_obj_t. This is true, even when it would sound natural to return, e.g., an int. For instance sollya_lib_get_verbosity() returns a sollya_obj_t, whose integer value must then be recovered with sollya_lib_get_constant_as_int. This forces the user to declare (and clear afterwards) a temporary sollya_obj_t to store the value, but this is the price of homogeneity in the library.
• When a function returns an integer, this integer generally is a boolean in the usual C meaning, i.e., 0 represents false and any non-zero value represents true. In many cases, the integer returned by the function indicates a status of success or failure: the convention is “false means failure” and “true means success”. In case of failure, the convention is that the function did not touch any of its arguments.
• When a function would need to return several things, or when a function would need to return something together with a status of failure or success, the convention is that pointers are given as the first arguments of the function. These pointers shall point to valid addresses where the function will store the results. This can sometimes give obscure signatures, when the function would in principle returns a pointer and actually takes as argument a pointer to a pointer (this typically happens when the function allocates a segment of memory and should return a pointer to that segment of memory).

10.4 - Displaying Sollya objects and numerical values

Within the interactive tool, the most simple way of displaying the content of a variable or the value of an expression is to write the name of the variable or the expression, followed by the character “;”. As a result, Sollya evaluates the expression or the variable and displays the result. Alternatively, a set of objects can be displayed the same way, separating the objects with commas. In library mode, the same behavior can be reproduced using the function void sollya_lib_autoprint(sollya_obj_t, ...). Please notice that this function has a variable number of arguments: they are all displayed, until an argument equal to NULL is found. The NULL argument is mandatory, even if only one object shall be displayed (the function has no other way to know if other arguments follow or not). So, if only one argument should be displayed, the correct function call is sollya_lib_autoprint(arg, NULL). Accordingly, if two arguments should be displayed, the function call is sollya_lib_autoprint(arg1, arg2, NULL), etc. The function void sollya_lib_v_autoprint(sollya_obj_t, va_list) is the same, but it takes a va_list argument instead of a variable number of arguments.

Further, there is another way of printing formatted strings containing Sollya objects, using a printf-like syntax. Eight functions are provided, namely:

• sollya_lib_printf, sollya_lib_v_printf,
• sollya_lib_fprintf, sollya_lib_v_fprintf,
• sollya_lib_sprintf, sollya_lib_v_sprintf,
• sollya_lib_snprintf and sollya_lib_v_snprintf.

Each one of these functions overloads the usual function (respectively, printf, vprintf, fprintf, vfprintf, sprintf, vsprintf, snprintf and vsnprintf). The full syntax of conversions specifiers supported with the usual functions is handled (please note that the style using '$' – as in %3$ or %*3$ – is not handled though. It is not included in the C99 standard anyway). Additionally, the following conversion specifiers are provided:

• %b: corresponds to a sollya_obj_t argument. There is no precision modifier support.
• %v: corresponds to a mpfr_t argument. An optional precision modifier can be applied (e.g., %.5v).
• %w: corresponds to a mpfi_t argument. An optional precision modifier can be applied (e.g., %.5w).
• %r: corresponds to a mpq_t argument. There is no precision modifier support.
• %k: corresponds to a mpz_t argument. There is no precision modifier support.

When one of the above conversion specifiers is used, the corresponding argument is displayed as it would be within the interactive tool: i.e., the way the argument is displayed depends on Sollya environment variables, such as prec, display, midpointmode, etc. When a precision modifier n is used, the argument is first rounded to a binary precision of roughly log2(10)*n bits (i.e., roughly equivalent to n decimal digits) before being displayed. As with traditional printf, the precision modifier can be replaced with * which causes the precision to be determined by an additional int argument.

Flag characters (e.g., ‘#’, ‘0’, etc.) are allowed but have no effect, except flag character ‘-’ that is supported with its usual meaning of left-aligning the converted value. The full syntax for minimum field width is supported: it can be given directly as an integer in the format string (e.g., %22b) or it can be replaced with *, which causes the field width to be determined by an additional int argument. As usual, a negative field width is taken as a ‘-’ flag followed by a positive width.

As a special (and sometimes convenient) case, %b accepts that its corresponding sollya_obj_t argument be NULL: in this particular case, the string “NULL” is used in the displayed string. Please notice that, except for the particular case of NULL, the behavior of sollya_lib_printf is completely undefined if the argument of %b is not a valid Sollya object.

The sollya_lib_printf functions return an integer with the same meaning as the traditional printf functions. It indicates the number of characters that have been output (excluding the final \0 character). Similarly, the conversion specifier %n can be used, even together with the Sollya conversion specifiers %b, %v, %w, %r and %k. The functions sollya_lib_snprintf and sollya_lib_v_snprintf will never write more characters than indicated by their size argument (including the final \0 character). If the output gets truncated due to this limit, they will return the number of characters (excluding the final \0 character) that would have been output if there had not been any truncation. In case of error, all sollya_lib_printf functions return a negative value.

10.5 Creating Sollya objects

Sollya objects conceptually fall into one of five categories: numerical constants (e.g., 1 or 1.5), functional expressions (they might contain numerical constants, e.g., sin(cos(x+1.5))), other simple objects (intervals, strings, built-in constants such as dyadic, etc.), lists of objects (e.g., [|1, "Hello"|]) and structures (e.g., {.a = 1; .b = "Hello"}).

10.5.1 - Numerical constants

Table Creating numerical constants lists the different functions available to construct numerical constants. A Sollya constant is always created without rounding (whatever the value of global variable prec is at the moment of the function call): a sufficient precision is always allocated so that the constant is stored exactly. All these functions return a constant floating-point number except sollya_lib_constant_from_mpq that may return a constant expression if the value of the rational number given as argument is not exactly representable as a floating-point number at some precision. The returned expression is of the form p/q in this case.

The objects returned by these functions are newly allocated and copies of the argument. For instance, after the instruction a = sollya_lib_constant(b), the user will eventually have to clear a (with sollya_lib_clear(a)) and b (with mpfr_clear(b)).

The function sollya_lib_constant_from_double (or more conveniently its shortcut SOLLYA_CONST) is probably the preferred way for constructing numerical constants. As the name indicates it, its argument is a double; however, due to implicit casting in C, it is perfectly possible to give an int as argument: it will be converted into a double (without rounding if the integer fits on 53 bits) before being passed to SOLLYA_CONST. On the contrary, the user should be aware of the fact that if decimal non-integer constants are given, C rules of rounding (to double) are applied, regardless of the setting of the Sollya precision variable prec.

10.5.2 - Functional expressions

Functional expressions are built by composition of basic functions with constants and the free mathematical variable. Since it is convenient to build such expressions by chaining function calls, the library provides functions that “eat up” their arguments (actually embedding them in a bigger expression). The convention is that functions that eat up their arguments are prefixed by sollya_lib_build_. For the purpose of building expressions, shortcut macros for the corresponding functions exist. They are all listed in Table Building functional expressions.

It is worth mentioning that, although SOLLYA_X_ and SOLLYA_PI are used without parentheses (as if they denoted constants), they are in fact function calls that create a new object each time they are used. The absence of parentheses is just more convenient for constructing expressions, such as, e.g., SOLLYA_COS(SOLLYA_X_).

For each function of the form sollya_lib_build_function_foo, there exists a function called sollya_lib_foo. There are two differences between them:

• First, sollya_lib_foo does not “eat up” its argument. This can sometimes be useful, e.g., if one has an expression stored in a variable a and one wants to build the expression exp(a) without loosing the reference to the expression represented by a.
• Second, while sollya_lib_build_function_foo mechanically constructs an expression, function sollya_lib_foo also evaluates it, as far as this is possible without rounding.
  For instance, after the instructions a = SOLLYA_CONST(0); b = sollya_lib_exp(a); the variable b contains the number 1, whereas it would have contained the expression "exp(0)" if it had been created by b = sollya_lib_build_function_exp(a).

Actually, sollya_lib_foo has exactly the same behavior as writing an expression at the prompt within the interactive tool. In particular, it is possible to give a range as an argument to sollya_lib_foo: the returned object will be the result of the evaluation of function foo on that range by interval arithmetic. In contrast, trying to use sollya_lib_build_function_foo on a range would result in a typing error.

Alternatively, one may create functional expressions with the functions
   int sollya_lib_construct_function(sollya_obj_t *res, sollya_base_function_t type, ...)
   int sollya_lib_v_construct_function(sollya_obj_t *, sollya_base_function_t, va_list).
The advantage of these functions with respect to the others presented above lies in the fact that they offer a way to create any functional expression, the basic function that one wants to construct being provided with the argument type. Since these functions are indeed doing the exact contrary of sollya_lib_decompose_function, they are described in details in the corresponding Section Decomposing a functional expression.

10.5.3 - Other simple objects

Other simple objects are created with functions listed in Table Creating Sollya objects from scratch. The functions with a name of the form sollya_lib_something follow the same convention as sollya_lib_constant: they build a new object from a copy of their argument, and the conversion is always exact, whatever the value of prec is.

Please note that in the interactive tool, D either denotes the discrete mathematical function that maps a real number to its closest double number, or is used as a symbolic constant to indicate that the double format must be used (as an argument of round for instance). In the library, they are completely distinct objects, the mathematical function being obtained with sollya_lib_build_function_double and the symbolic constant with sollya_lib_double_obj. The same holds for other formats (DD, SG, etc.)

In the last lines of the table, a is a mpfi_t containing the interval [1, 3.5], b and c are mpfr_t respectively containing the numbers 1 and 3.5, and d and e are sollya_obj_t respectively containing the numbers 1 and 3.5. Conversion from a mpfi_t or a mpfr_t to a sollya_obj_t is always exact.

10.5.4 - Lists

There are actually two kinds of lists: regular lists (such as, e.g., [|1, 2, 3|]) and semi-infinite lists (such as, e.g., [|1, 2...|]). Withing the interactive tool, the ellipsis “...” can sometimes be used as a shortcut to define regular lists, e.g., [|1, 2, ..., 10|].

In the library, there is no symbol for the ellipsis, and there are two distinct types: one for regular lists and one for semi-infinite lists (called end-elliptic). Defining a regular list with an ellipsis is not possible in the library (except of course with sollya_lib_parse_string).

Constructing regular lists is achieved through three functions:

• sollya_obj_t sollya_lib_list(sollya_obj_t[] L, int n): this function returns a new object that is a list the elements of which are copies of L[0], ..., L[n-1].
• sollya_obj_t sollya_lib_build_list(sollya_obj_t obj1, ...): this function accepts a variable number of arguments. The last one must be NULL. It “eats up” its arguments and returns a list containing the objects given as arguments. Since arguments are eaten up, they may be directly produced by function calls, without being stored in variables. A typical use could be
  sollya_lib_build_list(SOLLYA_CONST(1), SOLLYA_CONST(2), SOLLYA_CONST(3), NULL);
  
• sollya_obj_t sollya_lib_v_build_list(va_list): the same as the previous functions, but with a va_list.

Following the same conventions, end-elliptic lists can be constructed with the following functions:

• sollya_obj_t sollya_lib_end_elliptic_list(sollya_obj_t[] L, int n).
• sollya_obj_t sollya_lib_build_end_elliptic_list(sollya_obj_t obj1, ...).
• sollya_obj_t sollya_lib_v_build_end_elliptic_list(va_list).

10.5.5 - Structures

Sollya structures are also available in library mode as any other Sollya object. The support for Sollya structures is however minimal and creating them might seem cumbersome (users are encouraged to make well-founded feature requests if they feel the need for better support of structures). The only function available to create structures is
int sollya_lib_create_structure(sollya_obj_t *res, sollya_obj_t s, char *name,
                                sollya_obj_t val).

This function returns a boolean integer: false means failure, and true means success. Three cases of success are possible. In all cases, the function creates a new object and stores it at the address referred to by res.

• If s is NULL: *res is filled with a structure with only one field. This field is named after the string name and contains a copy of the object val.
• If s is an already existing structure that has a field named after the string name: *res is filled with a newly created structure. This structure is the same as s except that the field corresponding to name contains a copy of val.
• If s is an already existing structure that does not have a field named after the string name: *res is filled with a newly created structure. This structure is the same as s except that it has been augmented with a field corresponding to name and that contains a copy of val.

Please notice that s is not changed by this function: the structure stored in *res is a new one that does not refer to any of the components of s. As a consequence, one should not forget to explicitly clear s as well as *res when they become useless.

10.5.6 - Library functions, library constants and procedure functions

In addition to the mathematical base functions and constants provided by Sollya and listed in the Section above, the user may bind other mathematical functions and constants to Sollya objects under the condition that they can provide code to evaluate these functions or constants. The mechanism behind is similar to the one available in interactive Sollya through the library, libraryconstant and function commands (see commands library, libraryconstant and function).

With the Sollya library, this binding is done through one of the following functions:

• Binding of a (non-constant) mathematical function for which evaluation code is available through a C pointer to a function:
  sollya_obj_t sollya_lib_libraryfunction(sollya_obj_t e,
                                        char *name,
                                        int (*f)(mpfi_t, mpfi_t, int));
sollya_obj_t sollya_lib_build_function_libraryfunction(sollya_obj_t e,
                                        char *name,
                                        int (*f)(mpfi_t, mpfi_t, int));
sollya_obj_t sollya_lib_libraryfunction_with_data(
                                        sollya_obj_t e,
                                        char *name,
                                        int (*f)(mpfi_t, mpfi_t, int, void *),
                                        void *data,
                                        void (*dealloc_func)(void *));
sollya_obj_t sollya_lib_build_function_libraryfunction_with_data(
                                        sollya_obj_t e,
                                        char *name,
                                        int (*f)(mpfi_t, mpfi_t, int, void *),
                                        void *data,
                                        void (*dealloc_func)(void *));

  These four functions construct a Sollya object representing f(e) where e is given as the Sollya object e and f is given as the pointer to a function f(mpfi_t y, mpfi_t x, int n) (resp. f(mpfi_t y, mpfi_t x, int n, void *data)). This code must evaluate the n-th derivative of f over the interval x, yielding y.

  As usual, the functions whose name contains _build_function_ “eat up” the object e, while the corresponding functions (without _build_function_ in their name) do not.

  The name argument of the function is taken as a suggestion to the name the Sollya object representing the function should be printed as when displayed. The user may choose to provide NULL instead. In any case, upon the binding, the Sollya library will determine a unique displaying name for the function. If it is not yet taken as a name (for some other Sollya object or Sollya keyword), the suggested name will be used. If no suggested name is provided, the name of the dynamic object behind the pointer to the function will be used if it can be determined. Otherwise, a more-or-less random name is used. If the (suggested) base name is already taken, the name is unified appending an underscore and a unique number to it. The name argument is never “eaten up”, i.e., it is up to the user to free any memory allocated to that pointer.

  The functions whose name contains _with_data allow for the same binding of an external function to a Sollya object as the corresponding functions (without _with_data in their name), but additionnally permit an opaque data pointer data to be registered together with the function pointer f. The data pointer data will be represented to the function f on each call, in an additional (last) argument of type void * that the function f is supposed to take.

  Such opaque data pointers may be used, e.g., to distinguish between several different external procedure objects when only unique function pointer is available and the actual procedural code is contained in a closure represented thru the data pointer.

  As the data field the data pointer points to may require deallocation once the Sollya object built thru invokation of the functions described inhere and all of its copies eventually get deallocated, a data-field-deallocation function dealloc_func may be registered together with the data field. That function will be called with the data pointer in argument when the Sollya object is deallocated. When the user does not need such a deallocation function, they may provide NULL as the dealloc_func argument to the sollya_lib_libraryfunction_with_data function or sollya_lib_build_function_libraryfunction_with_data function, in which case the argument is ignored and no deallocation function gets called for the Sollya object built.

• Binding of a mathematical constant for which evaluation code is available through a C pointer to a function:
  sollya_obj_t sollya_lib_libraryconstant(char *name,
                                        void (*c)(mpfr_t, mp_prec_t));
sollya_obj_t sollya_lib_build_function_libraryconstant(char *name,
                                        void (*c)(mpfr_t, mp_prec_t));
sollya_obj_t sollya_lib_libraryconstant_with_data(
                                        char *name,
                                        void (*c)(mpfr_t, mp_prec_t, void *),
                                        void *data,
                                        void (*dealloc_func)(void *));
sollya_obj_t sollya_lib_build_function_libraryconstant_with_data(
                                        char *name,
                                        void (*c)(mpfr_t, mp_prec_t, void *),
                                        void *data,
                                        void (*dealloc_func)(void *));

  These four functions construct a Sollya object representing the mathematical constant c for which a pointer to a function c(mpfr_t rop, mp_prec_t prec) (resp. c(mpfr_t rop, mp_prec_t prec, void *data)) is provided. This code must evaluate the constant to precision prec and affect the result to rop. See command libraryconstant for details with respect to prec.

  The same remark as above concerning the suggested displaying name of the Sollya object applies for the name argument. In the same manner, the same remarks as above concerning the functions taking a data field pointer data apply.

• Binding of a mathematical function for which evaluation code is available through a Sollya object representing a Sollya procedure:
  sollya_obj_t sollya_lib_procedurefunction(sollya_obj_t e, sollya_obj_t f);
sollya_obj_t sollya_lib_build_function_procedurefunction(sollya_obj_t e,
                                                         sollya_obj_t f);
  

  These two functions construct a Sollya library object representing f(e) where e corresponds to the mathematical function (or constant) given with argument e and where f is given as a Sollya procedure f(x, n, p) evaluating the n-th derivative of f over the interval x with precision p. See command function concerning details of the arguments of that Sollya procedure.

  As usual, sollya_lib_build_function_procedurefunction “eats up” its arguments e and f while sollya_obj_t sollya_lib_procedurefunction does not.

  Currently, the only way of constructing a Sollya library object representing a Sollya procedure is to use sollya_lib_parse_string.

10.5.7 - External procedures

Similarly to library functions or library constants, the binding of which is discussed in Section Library functions, library constants and procedure functions, Sollya allows external procedural code to be bound and then used inside Sollya in a procedure-like manner. This is provided in the interactive tool with the externalproc command, described in command externalproc. The same mechanism is available in the Sollya library thanks to the following functions:

• To bind a function pointer p as a procedure named name, having arity arity, returning a result of type res_type and accepting arguments of types arg_types[0] thru arg_types[arity - 1], the function
  sollya_obj_t
    sollya_lib_externalprocedure(sollya_externalprocedure_type_t res_type,
                                 sollya_externalprocedure_type_t *arg_types,
                                 int arity,
                                 char *name,
                                 void *p);
  may be used.

  The name argument of the function is only taken as a suggestion to the name the Sollya object representing the function should be printed as when displayed. The user may choose to provide NULL instead. In any case, upon the binding, the Sollya library will determine a unique displaying name for the procedure. If it is not yet taken as a name (for some other Sollya object or Sollya keyword), the suggested name will be used. If no suggested name is provided, the name of the dynamic object behind the pointer to the function will be used if it can be determined. Otherwise, a more-or-less random name is used. If the (suggested) base name is already taken, the name is unified appending an underscore and a unique number to it. The name argument is never ``eaten up'', i.e., it is up to the user to free any memory allocated for that pointer.

  The result type res_type as well as the argument types arg_types take one of the values defined by the enumeration type sollya_externalprocedure_type_t, detailed in Table Possible return and argument types for external procedures. The array (resp. pointer) to the argument types arg_types provided to the sollya_lib_externalprocedure function is not ``eaten up'' by the function, i.e., it is up to the user to free any memory allocated for that pointer (where applicable). When the external procedure does not take any argument, its arity is to be set to zero. In this case, the argument type pointer arg_types is ignored by the sollya_lib_externalprocedure function; it hence may be invalid or NULL in this case.

  The actual C function to be bound is supposed to have a function type corresponding to the result and argument types indicated. It is supposed to be provided to the sollya_lib_externalprocedure function as a void * function pointer, though, for the sake of unification of the Sollya library interface. A detailed description of the actual type of the C function is given in command externalproc.

• In addition to the basic binding function described above, the
  sollya_obj_t
    sollya_lib_externalprocedure_with_data(
                            sollya_externalprocedure_type_t res_type,
                            sollya_externalprocedure_type_t *arg_types,
                            int arity,
                            char *name,
                            void *p,
                            void *data,
                            void (*dealloc_func)(void *));
  function allows for the same binding of an external procedure to a Sollya object but additionnally permits an opaque data pointer data to be registered together with the function pointer p. The data pointer data will be represented to the function p on each call, in an additional (last) argument of type void * that the function p is supposed to take. Such opaque data pointers may be used, e.g., to distinguish between several different external procedure objects when only unique function pointer is available and the actual procedural code is contained in a closure represented thru the data pointer. As the data field the data pointer points to may require deallocation once the Sollya object built thru invokation of the sollya_lib_externalprocedure_with_data and all of its copies eventually get deallocated, a data-field-deallocation function dealloc_func may be registered together with the data field. That function will be called with the data pointer in argument when the Sollya object is deallocated. When the user does not need such a deallocation function, they may provide NULL as the dealloc_func argument to the sollya_lib_externalprocedure_with_data function, in which case the argument is ignored and no deallocation function gets called for the Sollya object built.

10.6 - Getting the type of an object

Functions are provided that allow the user to test the type of a Sollya object. They are listed in Table Testing the type of a Sollya object. They all return an int interpreted as the boolean result of the test. Please note that from a typing point of view, a mathematical constant and a non-constant functional expression are both functions.

10.7 - Recovering the value of a range

If a sollya_obj_t is a range, it is possible to recover the values corresponding to the bounds of the range. The range can be recovered either as a mpfi_t or as two mpfr_t (one per bound). This is achieved with the following conversion functions:

• int sollya_lib_get_interval_from_range(mpfi_t res, sollya_obj_t arg),
• int sollya_lib_get_bounds_from_range(mpfr_t res_left, mpfr_t res_right,
                                     sollya_obj_t arg).

They return a boolean integer: false means failure (i.e., if the sollya_obj_t is not a range) and true means success. These functions follow the same conventions as those of the MPFR and MPFI libraries: the variables res, res_left and res_right must be initialized beforehand, and are used to store the result of the conversion. Also, the functions sollya_lib_get_something_from_range do not change the internal precision of res, res_left and res_right. If the internal precision is sufficient to perform the conversion without rounding, then it is guaranteed to be exact. If, on the contrary, the internal precision is not sufficient, the actual bounds of the range stored in arg will be rounded at the target precision using a rounding mode that ensures that the inclusion property remains valid, i.e., arg is a subset of res (resp. arg is a subset of [res_left, res_right]).

Function int sollya_lib_get_prec_of_range(mp_prec_t *prec, sollya_obj_t arg) stores at *prec a precision that is guaranteed to be sufficient to represent the range stored in arg without rounding. The returned value of this function is a boolean that follows the same convention as above. In conclusion, this is an example of a completely safe conversion:

10.8 - Recovering the value of a numerical constant or a constant expression

From a conceptual point of view, a numerical constant is nothing but a very simple constant functional expression. Hence there is no difference in Sollya between the way constants and constant expressions are handled. The functions presented in this section allow one to recover the value of such constants or constant expressions into usual C data types.

A constant expression being given, three cases are possible:

• When naively evaluated at the current global precision, the expression always leads to provably exact computations (i.e., at each step of the evaluation, no rounding happens). For instance numerical constants or simple expressions such as (exp(0)+5)/16 fall in this category.
• The constant expressions would be exactly representable at some precision but this is not straightforward from a naive evaluation at the current global precision. An example would be sin(pi/3)/sqrt(3) or even 1 + 2^(-prec-10).
• Finally, a third possibility is that the value of the expression is not exactly representable at any precision on a binary floating-point number. Possible examples are pi or 1/10.

From now on, we suppose that arg is a sollya_obj_t that contains a constant expression (or, as a particular case, a numerical constant). The general scheme followed by the conversion functions is the following: Sollya chooses an initial working precision greater than the target precision. If the value of arg is easily proved to be exactly representable at that precision, Sollya first computes this exact value and then rounds it to the nearest number of the target format (ties-to-even). Otherwise, Sollya tries to adapt the working precision automatically in order to ensure that the result of the conversion is one of both numbers in the target format that are closest to the exact value (a faithful rounding). A warning message indicates that the conversion is not exact and that a faithful rounding has been performed. In some cases really hard to evaluate, the algorithm can even fail to find a faithful rounding. In that case, too, a warning message is emitted indicating that the result of the conversion should not be trusted. Let us remark that these messages can be caught instead of being displayed and adapted handling can be provided by the user of the library at each emission of a warning (see Section Warning messages in library mode).

The conversion functions are the following. They return a boolean integer: false means failure (i.e., arg is not a constant expression) and true means success.

• int sollya_lib_get_constant_as_double(double *res, sollya_obj_t arg)
• int sollya_lib_get_constant_as_int(int *res, sollya_obj_t arg): any value too big to be represented (this includes -Inf and +Inf) is converted to INT_MIN or INT_MAX and a warning is emitted. NaN is converted to 0 with a specific warning.
• int sollya_lib_get_constant_as_int64(int64_t *res, sollya_obj_t arg): any value too big to be represented (this includes -Inf and +Inf) is converted to INT64_MIN or INT64_MAX and a warning is emitted. NaN is converted to 0 with a specific warning.
• int sollya_lib_get_constant_as_uint64(uint64_t *res, sollya_obj_t arg): negative values are converted to 0 with a warning. Any value too big to be represented (this includes +Inf) is converted to UINT64_MAX and a warning is emitted. NaN is converted to 0 with a specific warning.
• int sollya_lib_get_constant_as_mpz(mpz_t res, sollya_obj_t arg): the result of the conversion is stored in res. Please note that res must be initialized beforehand. Infinities and NaN are converted to 0 with specific warnings.
• int sollya_lib_get_constant_as_mpq(mpq_t res, sollya_obj_t arg): the result of the conversion is stored in res. Please note that res must be initialized beforehand. If arg cannot be proved to be exactly a floating-point number or the ratio of two floating-point numbers at some precision, the function returns false and res is left unchanged.
• int sollya_lib_get_constant(mpfr_t res, sollya_obj_t arg): the result of the conversion is stored in res. Please note that res must be initialized beforehand and that its internal precision is not modified by the algorithm.

Function int sollya_lib_get_prec_of_constant(mp_prec_t *prec, sollya_obj_t arg) tries to find a precision that would be sufficient to exactly represent the value of arg without rounding. If it manages to find such a precision, it stores it at *prec and returns true. If it does not manage to find such a precision, or if arg is not a constant expression, it returns false and *prec is left unchanged.

In conclusion, here is an example of use for converting a constant expression to a mpfr_t:

10.9 - Converting a string from Sollya to C

If arg is a sollya_obj_t that contains a string, that string can be recovered using
int sollya_lib_get_string(char **res, sollya_obj_t arg).
If arg really is a string, this function allocates enough memory on the heap to store the corresponding string, it copies the string at that newly allocated place, and sets *res so that it points to it. The function returns a boolean integer: false means failure (i.e., arg is not a string) and true means success.

Since this function allocates memory on the heap, this memory should manually be cleared by the user with sollya_lib_free once it becomes useless.

10.10 - Recovering the contents of a Sollya list

It is possible to recover the i-th element of a list arg (as one would do using arg[i] withing Sollya) with the following function:
int sollya_lib_get_element_in_list(sollya_obj_t *res, sollya_obj_t arg, int i).
It returns a boolean integer: false means failure (i.e., arg is not a list or the index is out of range) and true means success. In case of success, a copy of the i-th element of arg is stored at the address referred to by res. Since it is a copy, it should be cleared with sollya_lib_clear_obj when it becomes useless. Please notice that this function works with regular lists as well as with end-elliptic lists, just as within the interactive tool.

Another function allows user to recover all elements of a list in a single call. This function returns a C array of sollya_obj_t objects and has the following signature:
int sollya_lib_get_list_elements(sollya_obj_t **L, int *n, int *end_ell,
                                 sollya_obj_t arg).
Three cases are possible:

• If arg is a regular list of length N, the function allocates memory on the heap for N sollya_obj_t, sets *L so that it points to that memory segment, and copies each of the elements N of arg to (*L)[0], ..., (*L)[N-1]. Finally, it sets *n to N, *end_ell to zero and returns true. A particular case is when arg is the empty list: everything is the same except that no memory is allocated and *L is left unchanged.
• If arg is an end-elliptic list containing N elements plus the ellipsis. The function allocates memory on the heap for N sollya_obj_t, sets *L so that it points to that memory segment, and copies each of the elements N of arg at (*L)[0], ..., (*L)[N-1]. Finally, it sets *n to N, *end_ell to a non-zero value and returns true. The only difference between a regular list and an end-elliptic list containing the same elements is hence that *end_ell is set to a non-zero value in the latter.
• If arg is neither a regular nor an end-elliptic list, *L, *n and *end_ell are left unchanged and the function returns false.

In case of success, please notice that (*L)[0], ..., (*L)[N-1] should manually be cleared with sollya_lib_clear_obj when they become useless. Also, the pointer *L itself should be cleared with sollya_lib_free since it points to a segment of memory allocated on the heap by Sollya.

10.11 - Recovering the contents of a Sollya structure

If arg is a sollya_obj_t that contains a structure, the contents of a given field can be recovered using
int sollya_lib_get_element_in_structure(sollya_obj_t *res, char *name,
                                        sollya_obj_t arg).
If arg really is a structure and if that structure has a field named after the string name, this function copies the contents of that field into the Sollya object *res. The function returns a boolean integer: false means failure (i.e., if arg is not a structure or if it does not have a field named after name) and true means success.

It is also possible to get all the field names and their contents. This is achieved through the function
int sollya_lib_get_structure_elements(char ***names, sollya_obj_t **objs, int *n,
                                      sollya_obj_t arg).
If arg really is a structure, say with N fields called “fieldA”, ..., “fieldZ”, this functions sets *n to N, allocates and fills an array of N strings and sets *names so that it points to that segment of memory (hence (*names)[0] is the string “fieldA”, ..., (*names)[N-1] is the string “fieldZ”). Moreover, it allocates memory for N sollya_obj_t, sets *objs so that it points on that memory segment, and copies the contents of each of the N fields at (*objs)[0], ..., (*objs)[N-1]. Finally it returns true. If arg is not a structure, the function simply returns false without doing anything. Please note that since *names and *objs point to memory segments that have been dynamically allocated, they should manually be cleared by the user with sollya_lib_free once they become useless.

10.12 - Decomposing a functional expression

If a sollya_obj_t contains a functional expression, one can decompose the expression tree using the following functions. These functions all return a boolean integer: true in case of success (i.e., if the sollya_obj_t argument really contains a functional expression) and false otherwise.

• int sollya_lib_get_function_arity(int *n, sollya_obj_t f): it stores the arity of the head function in f at the address referred to by n. Currently, the mathematical functions handled in Sollya are at most dyadic. Mathematical constants are considered as 0-adic functions. The free variable is regarded as the identity function applied to the free variable: its arity is hence 1.
• int sollya_lib_get_head_function(sollya_base_function_t *type, sollya_obj_t f):
  it stores the type of f at the address referred to by type. The sollya_base_function_t is an enum type listing all possible cases (see Table List of values defined in type sollya_base_function_t).
• int sollya_lib_get_subfunctions(sollya_obj_t f, int *n, ...): let us denote by g_1, ..., g_k the arguments following the argument n. They must be of type sollya_obj_t *. The function stores the arity of f at the address referred to by n (except if n is NULL, in which case, sollya_lib_get_subfunctions simply ignores it and goes on). Suppose that f contains an expression of the form f₀(f₁,...,f_s) (as a particular case, if f is just the free variable, it is regarded in this context as the identity function applied to the free variable, so both f₀ and f₁ are the free variable). For each i from 1 to s, the expression corresponding to f_i is stored at the address referred to by g_i, unless one of the g_i is NULL in which case the function returns when encountering it. In practice, it means that the user should always put NULL as last argument, in order to prevent the case when they would not provide enough variables g_i. They can check afterwards that they provided enough variables by checking the value contained at the address referred to by n. If the user does not put NULL as last argument and do not provide enough variables g_i, the algorithm will continue storing arguments at random places in the memory (on the contrary, providing more arguments than necessary does not harm: useless arguments are simply ignored and left unchanged). In the case when f₀ is a library function, a constant (i.e., represented by the sollya_base_function_t SOLLYA_BASE_FUNC_CONSTANT), a library constant, the constant pi (i.e., represented by the sollya_base_function_t SOLLYA_BASE_FUNC_PI) or a procedure function, and if the user provides a non-NULL argument g_t after g_s, additionnal information is returned in the remaining argument:
  • If f₀ is a library function, a Sollya object corresponding to the expression f₀(x) is stored at the address referred to by g_t. This allows the user to get a Sollya object corresponding to function f₀. This object can further be used to evaluate f₀ at points or to build new expressions involving f₀. Please notice that a library function object is not necessarily the result of a call to the library command: it can also be, e.g., the derivative of a function created by a call to library.
  • If f₀ is a procedure function, a Sollya object corresponding to the expression f₀(x) is stored at the address referred to by g_t. The same remarks as above apply.
  • If f₀ is a constant, the constant pi, or a library constant, f₀ itself is stored at the address referred to by g_t. In this particular case, t=1 and the object referred to by g_t simply gets a copy of f. This (somehow useless) mechanism is made only to handle the cases of library functions, procedure functions, constants and library constants in a unified way.
  Please note that the objects that have been stored in variables g_i must manually be cleared once they become useless.
• int sollya_lib_v_get_subfunctions(sollya_obj_t f, int *n, va_list va): the same as the previous function, but with a va_list argument.
• int sollya_lib_get_nth_subfunction(sollya_obj_t *res, sollya_obj_t f, int m): while sollya_lib_get_subfunctions allows the user to retrieve all the subtrees of a functional expression (including an extra subtree in the case of a constant, the constant pi, a library constant, a library function or a procedure function), this function allows the user to retrieve only one of them. More precisely (using the same notations as in the documentation of sollya_lib_get_subfunctions above) if sollya_lib_get_subfunctions would put something at the address referred to by variable g_m, then sollya_lib_get_nth_subfunction(res, f, m) would put the same thing at the address referred to by res and return a boolean integer representing true. In any other case, it would let res unchanged and return a boolean integer representing false. Notice that the subfunctions are numbered starting from 1 (as opposed to, e.g., arrays in C), hence in the expression f = e₁ + e₂, the subexpression e₁ corresponds to m=1 and the subexpression e₂ corresponds to m=2. Accordingly, in an expression like f = sin(e), the subexpression e corresponds to m=1.
• int sollya_lib_decompose_function(sollya_obj_t f, sollya_base_function_t *type,
                                  int *n, ...):
  this function is a all-in-one function equivalent to using sollya_lib_get_head_function and sollya_lib_get_subfunctions in only one function call.
• int sollya_lib_v_decompose_function(sollya_obj_t f, sollya_base_function_t *type,
                                    int *n, va_list va):
  the same as the previous function, but with a va_list.

To construct a functional expression, functions are provided that precisely undo what sollya_lib_decompose_function does. These functions are the following:

• int sollya_lib_construct_function(sollya_obj_t *res, sollya_base_function_t type, ...): let us denote by g_1, ..., g_k the arguments following the argument type. They must be of type sollya_obj_t. The function creates a functional expression whose head function corresponds to the basic function represented by variable type and whose arguments are g_1, ..., g_s where s denotes the arity of the considered basic function. It is the responsibility of the user to provide enough arguments with respect to the required arity. As a particular case, when the desired type corresponds to a library function, a constant, the constant pi, a library constant or a procedure function, the user must provide an extra argument g_t after g_s corresponding to what sollya_lib_decompose_function would store in this extra argument on such a case (namely, a Sollya object corresponding to the expression f₀(x) in the case of a library function or procedure function, and f₀ itself in the case of a constant, the constant pi or a library constant). As a particular case, and to make it more useful in practice, the argument g_t is allowed to be equal to NULL whenever type is equal to SOLLYA_BASE_FUNC_PI, in which case the function will succeed, even though g_t does not contain the constant pi as it theoretically should. Notice however that any other value than NULL leads to a failure if it does not contain the constant pi itself. If everything goes well the functional expression is created and stored at the address referred to by res and a boolean integer representing true is returned. Notice that the arguments g_1, ..., g_k are not eaten up by this function and the user must subsequently manually clear these objects. If something goes wrong (bad number of arguments, arguments not having the proper type, etc.) res is left unchanged and a boolean integer representing false is returned.
• int sollya_lib_v_construct_function(sollya_obj_t *res, sollya_base_function_t type,
                                                  va_list varlist):
  the same as the previous function, but with a va_list.

As an example of use of the functions described in the present section, the following code returns 1 if f denotes a functional expression made only of constants (i.e., without the free variable), and returns 0 otherwise:

Functions are provided to allow the user to retrieve further information from library function, library constant, procedure function and external procedure objects:

• int sollya_lib_decompose_libraryfunction(int (**f)(mpfi_t, mpfi_t, int),
                                                          int *deriv, sollya_obj_t *e,
                                                          sollya_obj_t g):
  assume that g represents an expression f₀(f₁) where f₀ is a library function. Then, f₀ is the n-th derivative (for some n) of a function provided within Sollya via an external C function int func(mpfi_t, mpfi_t, int).
  As a result of a call to sollya_lib_decompose_libraryfunction, the value n is stored at the address referred to by deriv, a pointer to func is stored at the address referred to by f and a Sollya object representing f₁ is stored at the address referred to by e. Please notice that the object stored in e must manually be cleared once it becomes useless. Upon success, a boolean integer representing true is returned. If g is not a library function object, nothing happens and false is returned.
• int sollya_lib_decompose_libraryfunction_with_data(int (**f)(mpfi_t, mpfi_t, int, void *),
                                                                        int *deriv, sollya_obj_t *e,
                                                                        void **data, void (**dealloc)(void *),
                                                                        sollya_obj_t g):
  works exactly as the previous function but additionnally returns a pointer to the void * data field and the pointer to the deallocation function that had been provided when the library function was created. Notice that, in the case when g represents an expression f₀(f₁) where f₀ is indeed a library function, but has been constructed with sollya_lib_libraryfunction or sollya_lib_build_function_libraryfunction and not with one of the _with_data variants, this function will fail and return false without touching any of its argument.
• int sollya_lib_decompose_procedurefunction(sollya_obj_t *f, int *deriv,
                                                             sollya_obj_t *e, sollya_obj_t g):
  assume that g represents an expression f₀(f₁) where f₀ is a procedure function. Then, f₀ is the n-th derivative (for some n) of a function provided within Sollya via a procedure proc(X, n, p) {...}.
  As a result of a call to sollya_lib_decompose_procedurefunction, the value n is stored at the address referred to by deriv, a Sollya object representing the procedure is stored at the address referred to by f, a Sollya object representing f₁ is stored at the address referred to by e. Please notice that the objects stored in f and e must manually be cleared once they become useless. Upon success, a boolean integer representing true is returned. If g is not a procedure function object, nothing happens and false is returned.
• int sollya_lib_decompose_libraryconstant(void (**f)(mpfr_t, mp_prec_t),
                                                          sollya_obj_t c):
  assume that c is a constant provided via an external C function void func(mpfr_t, mp_prec_t). As a result of a call to sollya_lib_decompose_libraryconstant, a pointer to func is stored at the address referred to by f and a boolean integer representing true is returned. Otherwise, nothing happens and false is returned.
• int sollya_lib_decompose_libraryconstant_with_data(void (**f)(mpfr_t, mp_prec_t, void *),
                                                                        void **data, void (**dealloc)(void *),
                                                                        sollya_obj_t c):
  works exactly as the previous function but additionnally returns a pointer to the void * data field and the pointer to the deallocation function that had been provided when the library constant was created. Similarly to sollya_lib_decompose_libraryfunction_with_data, this function fails on library constants that have been created with sollya_lib_libraryconstant or sollya_lib_build_function_libraryconstant instead of using the _with_data variant of these constructors.
• int sollya_lib_decompose_externalprocedure(sollya_externalprocedure_type_t *res,
                                                             sollya_externalprocedure_type_t **args,
                                                             int *arity, void **f,
                                                             sollya_obj_t p):
  assume that p is an external procedure provided via an external C function func (of appropriate type) bound to Sollya by one of the means provided for that purpose. As a result of a call to sollya_lib_decompose_externalprocedure, a pointer to func is stored at the address pointed to by f, the result type of the external procedure is stored at res, an array of its argument types is allocated, filled and stored at the address pointed to by args (unless the procedure function takes no argument in which case the args argument is ignored), the arity of the external procedure (and hence number of elements of the array allocated and stored at args) is stored at the integer pointed by arity and true is returned. If p is no external procedure object, nothing happens and false is returned.
• int sollya_lib_decompose_externalprocedure_with_data(sollya_externalprocedure_type_t *res,
                                                                           sollya_externalprocedure_type_t **args,
                                                                           int *arity, void **f,
                                                                           void **data, void (**dealloc)(void *),
                                                                           sollya_obj_t p):
  works exactly as the previous function but additionnally returns a pointer to the void * data field and the pointer to the deallocation function that had been provided when the external procedure was created. The same remark as with sollya_lib_decompose_libraryfunction_with_data and sollya_lib_decompose_libraryconstant_with_data also applies: this function fails when used on an external procedure that has been constructed without the _with_data variant of the constructor.

10.13 - Faithfully evaluate a functional expression

Let us suppose that f is a functional expression and a is a numerical value or a constant expression. One of the very convenient features of the interactive tool is that the user can simply write f(a) at the prompt: the tool automatically adapts its internal precision in order to compute a value that is a faithful rounding (at the current tool precision) of the true value f(a). Sometimes it does not achieve to find a faithful rounding, but in any case, if the result is not proved to be exact, a warning is displayed explaining how confident one should be with respect to the returned value. The object a can also be an interval, in which case Sollya automatically performs the evaluation using an enhanced interval arithmetic, e.g., using L'Hopital's rule to produce finite (yet valid of course) enclosures even in cases when f exhibits removable singularities (for instance sin(x)/x over an interval containing 0). This behavior is reproduced in the library with the sollya_lib_apply function (this function is in fact to be used to reproduce any construction of the form obj1(obj2, obj3, ...) within the library; for instance obj1 might also be a procedure. See Section Commands and functions for a more detailed description of this function). More precisely if f and a are two sollya_obj_t representing respectively a univariate function and a constant or an interval, the following call returns a new sollya_obj_t representing the object that would be produced as a result of typing f(a); at the interactive prompt:
b = sollya_lib_apply(f, a, NULL);

However, when using the library, it might be interesting to have access to this feature when the argument a is not a Sollya object but rather directly a multiprecision constant of type mpfr_t or mpfi_t. Also, in this case, one may want to have a finer-grain access to the evaluation algorithm, e.g., to correctly react to cases where a faithful rounding has not been achieved without having to catch warning messages emitted by Sollya. This is the reason why the library proposes the following functions.

To evaluate a unary function at a constant expression or constant value, the library provides the two following functions:

• sollya_fp_result_t
  sollya_lib_evaluate_function_at_constant_expression(mpfr_t res, sollya_obj_t f,
                                                      sollya_obj_t a,
                                                      mpfr_t *cutoff),
• sollya_fp_result_t
  sollya_lib_evaluate_function_at_point(mpfr_t res, sollya_obj_t f,
                                        mpfr_t a, mpfr_t *cutoff).

In the former, the argument a is any sollya_obj_t containing a numerical constant or a constant expression, while in the latter a is a constant already stored in a mpfr_t. These functions store the result in res and return a sollya_fp_result_t which is an enum type described in Table List of values defined in type sollya_fp_result_t). In order to understand the role of the cutoff parameter and the value returned by the function, it is necessary to describe the algorithm in a nutshell:

Input: a functional expression f, a constant expression a, a target precision q, a parameter epsilon.

Choose an initial working precision p.

Evaluate a with interval arithmetic, performing the computations at precision p.

Replace the occurrences of the free variable in f by the interval obtained at step 2. Evaluate the resulting expression with interval arithmetic, performing the computations at precision p. This yields an interval I = [x,y].

Examine the following cases successively (RN denotes rounding to nearest at precision q):

1. If RN(x) = RN(y), set res to that value and return.
2. If I does not contain any floating-point number at precision q, set res to one of both floating-point numbers enclosing I and return.
3. If I contains exactly one floating-point number at precision q, set res to that number and return.
4. If all numbers in I are smaller than epsilon in absolute value, then set res to 0 and return.
5. If p has already been increased many times, then set res to some value in I and return.
6. Otherwise, increase p and go back to step 2.

The target precision q is chosen to be the precision of the mpfr_t variable res. The parameter epsilon corresponds to the parameter cutoff. The reason why cutoff is a pointer is that, most of the time, the user may not want to provide it, and using a pointer makes it possible to pass NULL instead. So, if NULL is given, epsilon is set to 0. If cutoff is not NULL, the absolute value of *cutoff is used as value for epsilon. Using a non-zero value for epsilon can be useful when one does not care about the precise value of f(a) whenever its absolute value is below a given threshold. Typically, if one wants to compute the maximum of |f(a₁)|, ..., |f(a_n)|, it is not necessary to spend too much effort on the computation of |f(a_i)| if one already knows that it is smaller than epsilon = max {|f(a₁)|,...,|f(a_i-1)|}.

To evaluate a unary function on an interval, the following function is provided:
int sollya_lib_evaluate_function_over_interval(mpfi_t res, sollya_obj_t f, mpfi_t a).

This function returns a boolean integer: false means failure (i.e., f is not a functional expression), in which case res is left unchanged, and true means success, in which case res contains the result of the evaluation. The function might succeed, and yet res might contain something useless such as an unbounded interval or even [NaN, NaN] (this happens for instance when a contains points that lie in the interior of the complement of the definition domain of f). It is the user's responsibility to check afterwards whether the computed interval is bounded, unbounded or NaN.

10.14 - Comparing objects structurally and computing hashes on Sollya objects

The library provides function
int sollya_lib_cmp_objs_structurally(sollya_obj_t obj1, sollya_obj_t obj2)
to allow the user to perform a structural comparison of any two Sollya objects. It returns an integer (interpreted as a boolean) that is true if and only if obj1 and obj2 are syntactically the same (as opposed to mathematically). For instance the fractions 2/3 and 4/6 are recognized as mathematically equal by Sollya when compared with == (or sollya_lib_cmp_equal with the library) but are syntactically different.

Certain language bindings require hashes to be available for any object represented. In order to help with such language bindings, the Sollya library supports a function that computes a 64 bit unsigned integer as a hash for a given Sollya object:
uint64_t sollya_lib_hash(sollya_obj_t obj).
The Sollya library guarantees that any two objects that are syntactically equal (as when compared with sollya_lib_cmp_objs_structurally) will have the same hash value. For some particular objects (e.g., polynomials) Sollya can normalize the expression before computing the hash value and in this case two objects that are mathematically equal (even though they are not structurally equal) will have the same hash value. However, except in such particular cases, two objects that are syntactically different are likely to have different hashes (although this is not guaranteed, of course).

Computing the hash of an object takes a time proportional to the size of the directed acyclic graph internally used to represent that object. However, Sollya will cache an object's hash value for further use after it has been computed, so the cost of computing the hash of a given object is paid only once.

The user should also be aware that the hash value for a given object is currently not guaranteed to be portable between platforms nor over consecutive Sollya versions.

10.15 - Executing Sollya procedures

Objects representing procedures written in Sollya language (see also Section Procedures) can be created using the Sollya library functions sollya_lib_parse_string and sollya_lib_parse or through execution of a Sollya script using sollya_lib_execute.

In order to execute such procedure objects on arguments, available as Sollya objects, too, the functions

• sollya_obj_t sollya_lib_execute_procedure(sollya_obj_t proc, ...) and
• sollya_obj_t sollya_lib_v_execute_procedure(sollya_obj_t proc, va_list arglist)

may be used. These functions apply the given procedure proc on the following arguments (or the elements in the argument list arglist). If no argument is needed to execute the procedure, the variadic argument list shall immediately be terminated using NULL; otherwise the argument list shall be terminated with an extra NULL argument. An arity test is performed by Sollya before the procedure is executed: if the arity of the given procedure does not correspond to the actual number of given arguments (and the Sollya procedure is not variadic), an error object is returned instead of the procedure's result.

When the functions are used to execute procedures that return a Sollya object, the object is returned by the function. When the procedure does not use the Sollya return statement or returns the Sollya void object, a Sollya void object is returned. The user should not forget to deallocate that void object.

10.16 - Name of the free variable

The default name for the free variable is the same in the library and in the interactive tool: it is _x_. In the interactive tool, this name is automatically changed at the first use of an undefined symbol. Accordingly in library mode, if an object is defined by sollya_lib_parse_string with an expression containing an undefined symbol, that symbol will become the free variable name if it has not already been changed before. But what if one does not use sollya_lib_parse_string (because it is not efficient) but one wants to change the name of the free variable? The name can be changed with sollya_lib_name_free_variable("some_name").

It is possible to get the current name of the free variable with sollya_lib_get_free_variable_name(). This function returns a char * containing the current name of the free variable. Please note that this char * is dynamically allocated on the heap and should be cleared after its use with sollya_lib_free() (see below).

10.17 - Commands and functions

Besides some exceptions, every command and every function available in the Sollya interactive tool has its equivalent (with a very close syntax) in the library. Section List of available commands of the present documentation gives the library syntax as well as the interactive tool syntax of each commands and functions. The same information is available within the interactive tool by typing help some_command. So if one knows the name of a command or function in the interactive tool, it is easy to recover its library name and signature.

There are some commands and functions available in interactive mode which, for syntactical reasons, have a different function name in the Sollya library:

• The Sollya language construction (obj1)(obj2, obj3, ...) which applies the object obj1 to the objects obj2, obj3, etc. is expressed in the Sollya library through a call to
  sollya_obj_t sollya_lib_apply(sollya_obj_t obj1, sollya_obj_t obj2, ...)
  resp. sollya_obj_t sollya_lib_v_apply(sollya_obj_t obj1, sollya_obj_t obj2, va_list).

A particular point is worth mentioning: some functions of the tool such as remez for instance have a variable number of arguments. For instance, one might call remez(exp(x), 4, [0,1]) or remez(1, 4, [0,1], 1/exp(x)). This feature is rendered in the C library by the use of variadic functions (functions with an arbitrary number of arguments), as they are permitted by the C standard. The notable difference is that there must always be an explicit NULL argument at the end of the function call. Hence one can write sollya_lib_remez(a, b, c, NULL) or sollya_lib_remez(a, b, c, d, NULL). It is very easy to forget the NULL argument and to use for instance sollya_lib_remez(a, b, c). This is completely wrong because the memory will be read until a NULL pointer is found. In the best case, this will lead to an error or a result obviously wrong, but it could also lead to subtle, not-easy-to-debug errors. The user is advised to be particularly careful with respect to this point.

Each command or function accepting a variable number of arguments comes in a sollya_lib_v_ version accepting a va_list parameter containing the list of optional arguments. For instance, one might write a function that takes as arguments a function f, an interval I, optionally a weight function w, optionally a quality parameter q. That function would display the minimax obtained when approximating f over I (possibly with weight w and quality q) by polynomials of degree n=2 to 20. So, that function would get a variable number of arguments (i.e., a va_list in fact) and pass them straight to remez. In that case, one needs to use the v_remez version, as the following code shows:

10.18 - Warning messages in library mode

10.18.1 - Catching warning messages

The philosophy of Sollya is “whenever something is not exact, explicitly warn about that”. This is a nice feature since this ensures that the user always perfectly knows the degree of confidence they can have in a result (is it exact? or only faithful? or even purely numerical, without any warranty?) However, it is sometimes desirable to hide some (or all) of these messages. This is especially true in library mode where messages coming from Sollya are intermingled with the messages of the main program. The library hence provides a specific mechanism to catch all messages emitted by the Sollya core and handle each of them specifically: installation of a callback for messages.

Before describing the principle of the message callback, it seems appropriate to recall that several mechanisms are available in the interactive tool to filter the messages emitted by Sollya. These mechanisms are also available in library mode for completeness. When a message is emitted, it has two characteristics: a verbosity level and an id (a number uniquely identifying the message). After it has been emitted, it passes through the following steps where it can be filtered. If it has not been filtered (and only in this case) it is displayed.

1. If the verbosity level of the message is greater than the value of the environment variable verbosity, it is filtered.
2. If the environment variable roundingwarnings is set to off and if the message informs the user that a rounding occurred, it is filtered.
3. If the id of the message has been registered with the suppressmessage command, the message is filtered.
4. If a message callback has been installed and if the message has not been previously filtered, it is handled by the callback, which decides to filter it or to permit its displaying.

A message callback is a function of the form int my_callback(sollya_msg_t msg, void *data). It receives as input an object representing the message and a user-defined pointer. It performs whatever treatment seems appropriate and returns an integer interpreted as a boolean. If the returned value is false, the message is not displayed. If, on the contrary, the returned value is true, the message is displayed as usual. By default, no callback is installed and all messages are displayed. To install a callback, use sollya_lib_install_msg_callback(my_callback, data). The (void *) pointer data is arbitrary (it can be NULL) and is simply transmitted as second argument at each call of the callback. It can be used, e.g., to point to a segment of memory where some information should be stored from a call of the callback to another.

Please remember that, if a message is filtered because of one of the three other mechanisms, it will never be transmitted to the callback. Hence, in library mode, if one wants to catch every single message through the callback, one should set the value of verbosity to MAX_INT, set roundingwarnings to on (this is the default anyway) and one should not use the suppressmessage mechanism.

It is possible to come back to the default behavior, using sollya_lib_uninstall_msg_callback(). Please notice that callbacks do not stack over each other: i.e., if some callback callback1 is installed, and if one installs another one callback2, then the effect of sollya_lib_uninstall_msg_callback() is to come back to the default behavior, and not to come back to callback callback1.

Both sollya_lib_install_msg_callback and sollya_lib_uninstall_msg_callback return an integer interpreted as a boolean: false means failure and true means success.

It is possible to get the currently installed callback using sollya_lib_get_msg_callback(cb_ptr, data_ptr). This stores the current callback at the address referred to by cb_ptr (the type of cb_ptr is hence int (**)(sollya_msg_t, void *)) and stores the current data pointer at the address referred to by data_ptr (which has hence (void **) type). The arguments cb_ptr and data_ptr can be NULL in which case the corresponding argument is not retrieved (please take care of the difference between data_ptr being NULL and data_ptr pointing to a (void *) pointer which value is NULL). If no callback is currently installed, the NULL value is stored at the addresses referred to by cb_ptr and data_ptr.

The type sollya_msg_t is indeed a pointer and its content is only accessible during the callback call: it does not make sense to keep it for further use after the callback call. Currently the type has only two accessors:

• int sollya_lib_get_msg_id(sollya_msg_t msg) returns an integer that identifies the type of the message. The message types are listed in the file sollya-messages.h. Please note that this file not only lists the possible identifiers but also defines meaningful names to each possible message number (e.g., SOLLYA_MSG_UNDEFINED_ERROR is an alias for the number 2 but is more meaningful to understand what the message is about). It is recommended to use these names instead of numerical values.
• char *sollya_lib_msg_to_text(sollya_msg_t msg) returns a generic string briefly summarizing the contents of the message. Please note that this char * is dynamically allocated on the heap and should manually be cleared with sollya_lib_free when it becomes useless.

In the future, other accessors could be added (to get the verbosity level at which the message has been emitted, to get data associated with the message, etc.) The developers of Sollya are open to suggestions and feature requests on this subject.

As an illustration let us give a few examples of possible use of callbacks:

Example 1: A callback that filters everything.

Example 2: filter everything but the messages indicating that a comparison is uncertain.

Example 3: ensuring perfect silence for a particular function call (uses the callback defined in Example 1).

Example 4: using the (void *) data argument to store information from a call to another.

More involved examples are possible: for instance, instead of setting a flag, it is possible to keep in some variable what the last message was. One may even implement a stack mechanism and store the messages in a stack, in order to handle them later. (Please remember however that sollya_msg_t is a pointer type and that the sollya_msg_t object received as argument of a callback call has no more meaning once the callback call returned. If a stack mechanism is implemented it should store information such as the message ID, or the message text, as given by sollya_lib_get_msg_id and sollya_lib_msg_to_text, but not the sollya_msg_t object itself.)

10.18.2 - Emitting warning messages

The Sollya library offers a way to print a message, as if it were produced by the Sollya core. Such a message will go through the entire process described in the previous section, and can eventually provoke a callback call if a callback is installed. The function supporting this feature is
void sollya_lib_printlibrarymessage(int verb, const char *str).
The first argument verb is the least verbosity level at which that warning shall be displayed. The second argument str is the message to be displayed.

When a message is produced with this function, its message ID (when caught by a callback) is SOLLYA_MSG_GENERIC_SOLLYA_LIBRARY_MSG. An important notice is that the character string returned by sollya_lib_msg_to_text when such a message is caught by a callback is currently not the argument str provided to sollya_lib_printlibrarymessage, but is instead a generic message. This behavior might change in the future.

10.19 - Using Sollya in a program that has its own allocation functions

Sollya uses its own allocation functions: as a consequence, pointers that have been allocated by Sollya functions must be freed using sollya_lib_free instead of the usual free function. Another consequence is that Sollya registers its own allocation functions to the GMP library, using the mechanism provided by GMP, so that GMP also uses Sollya allocation functions behind the scene, when the user performs a call to, e.g., mpz_init, mpfr_init2, etc.

In general, this is completely harmless and the user might even not notice it. However, this is a problem if Sollya is used in a program that also uses its own allocation functions and that has already registered these functions to GMP. Actually:

• If the main program has already registered allocation functions to GMP and if Sollya is naively initialized with sollya_lib_init(), Sollya will register its own allocation functions, thus overriding the previously registered functions.
• If the user initializes first Sollya, and then registers its own allocation functions to GMP, the exact opposite happens: Sollya allocation functions are overridden by those of the user, and this will likely cause Sollya to crash (or worst, silently behave not reliably).

In order to solve this issue, Sollya provides a chaining mechanism that we are now going to describe. The idea is the following: suppose that the main program should use a function custom_malloc. The user should not use mp_set_memory_functions as usual, but should instead initialize Sollya with the initializing function described above. This will cause Sollya to register an allocation function sollya_lib_malloc to GMP. This function overloads custom_malloc: when called, it uses custom_malloc to perform the actual allocation and does nothing else but some internal accounting and verification for that allocation. To repeat, the actual allocation is done by custom_malloc; hence from the point of view of the user, the mechanism is completely transparent and equivalent to directly registering custom_malloc to GMP. The same holds for all other allocation functions: in particular, this is true for free as well: if a function custom_free is given at the initialization of Sollya, then the function sollya_lib_free eventually uses custom_free to free the memory.

The initialization function providing this mechanism is:
int sollya_lib_init_with_custom_memory_functions(
         void *(*custom_malloc)(size_t),
         void *(*custom_calloc)(size_t, size_t),
         void *(*custom_realloc)(void *, size_t),
         void (*custom_free)(void *),
         void *(*custom_realloc_with_size)(void *, size_t, size_t),
         void (*custom_free_with_size)(void *, size_t)).
None of the arguments is mandatory: if the user does not want to provide an argument, they may use NULL as a placeholder for that argument. In that case, the corresponding Sollya default function will be used. Indeed, the default initializing function sollya_lib_init() is just an alias to sollya_lib_init_with_custom_memory_functions(NULL, NULL, NULL, NULL, NULL, NULL).

Please notice, that if custom_malloc is provided, then the function sollya_lib_malloc will be defined as an overloaded version of custom_malloc. Hence, custom_malloc will eventually be used for all the allocations performed by Sollya (including the allocation of memory for its own purpose). This is true also for custom_calloc, custom_realloc and custom_free. However, this is not the case for custom_realloc_with_size and custom_free_with_size: these functions are only required for the registration to GMP and are not used by Sollya itself (except of course when Sollya allocates function through a call to a GMP, MPFR or MPFI function). Thus, to sum up:

• If the user only wants to register their own functions to GMP through Sollya, they only need to provide custom_malloc, custom_realloc_with_size and custom_free_with_size at the initialization of Sollya (actually an overloaded version will be registered to GMP but this is transparent for the user, as explained above).
• If the user also wants Sollya to use their custom allocation functions for all allocations of memory by Sollya, then they also need to provide custom_calloc, custom_realloc and custom_free.

Of course, even if the user registers custom_malloc, custom_free, etc., at the initialization of Sollya, they stay free to use them for their own allocation needs: only allocations performed by GMP (and consequently MPFR and MPFI) and allocations performed by Sollya have to use the chaining mechanism. However, for the convenience of the user, the library also provides access to the allocation functions of Sollya. They are the following:

• void sollya_lib_free(void *)
• void *sollya_lib_malloc(size_t)
• void *sollya_lib_calloc(size_t, size_t)
• void *sollya_lib_realloc(void *, size_t).

No access to the overloaded version of custom_realloc_with_size and custom_free_with_size is provided, but if the user really wants to retrieve them, they can do it with mp_get_memory_functions since they are registered to GMP.