Laboratoire de l'Informatique et du Parallélisme » Pobyso

/** @file pobyso.h

 * Integration of Sollya to C programs

 * @author S.T.

 * @date 2011-10-11

 * @note pobyso stands for POwered BY SOllya.

 * @todo                        --      -- --

 */

/******************************************************************************/

/*

 * Add below all the headers needed to get this header work.

 */

/* <stdio.h> is needed *before* <mpfr.h> for all MPFR input/output functions

 * prototypes be defined. */

#include <string.h>

#include <stdio.h>

#include <sollya.h>

#include <mpfr.h>

#ifndef POBYSO_h

/* Typedefs to make code more readable. */

typedef sollya_obj_t pobyso_constant_t;

typedef sollya_obj_t pobyso_error_t;

typedef sollya_obj_t pobyso_func_exp_t;

typedef sollya_obj_t pobyso_on_off_t;

typedef mpfr_prec_t  pobyso_precision_t;

typedef sollya_obj_t pobyso_range_t;

#define POBYSO_ABSOLUTE (1)

#define POBYSO_RELATIVE (2)

#define POBYSO_UNFAITHFUL (129)

#define POBYSO_NAN (130)

#define POBYSO_OFF (0)

#define POBYSO_ON (1)

/* Mimic the default behavior of interactive Sollya. */

#define POBYSO_DEFAULT_POINTS 501

#define POBYSO_INF_NORM_NUM_POINTS (POBYSO_DEFAULT_POINTS)

#define POBYSO_GUESS_DEGREE_BOUND 1024

/* Very thin wrappers around a lot of Sollya functions.

 */

static inline pobyso_error_t pobyso_error(void)

{return(sollya_lib_error());}

static inline int pobyso_is_error(sollya_obj_t errorCandidate)

{return(sollya_lib_obj_is_error(errorCandidate));}

static inline int pobyso_is_function(sollya_obj_t functionCandidate)

{return(sollya_lib_obj_is_function(functionCandidate));}

/**

 * Print an object to stdout.

 * A very thin wrapper around the lib_sollya_autoprint() function.

 */

void

pobyso_autoprint(sollya_obj_t objSo);

/**

 * Print object(s) to stdout: the va_list companion function.

 * A very thin wrapper around the lib_sollya_v_autoprint() function.

 * The last argument in the va_list should be NULL.

 */

void

pobyso_autoprint_v(va_list va);

/** A very thin wrapper around the sollya_lib_clear_obj

 * function.

 * @param objSo: the Sollya object to free.

 */

void

pobyso_clear_obj(sollya_obj_t objSo);

/**

 * A wrapper around the Sollya dirtyfindzeros function.

 * Find the numerical values of the zeroes of the funcExpSo expression over

 * the [lowerBoundMp, upperBoundMp] interval.

 * @param funcExpSo:    a Sollya functional expression;

 * @param lowerBoundMp: the lower bound as an MPFR number;

 * @param upperBoundMp: the upper bound as an MPFR number;

 * @param zerosCount: a pointer to the int where the number of zeros will be

 *                    stored;

 * @return a (possibly empty) list of the zeroes of the function or NULL if

 *         something goes wrong or there are no zeroes. *zerosCount should

 *         always be tested first.

 *         If *zeroCounts == 0 the function returns NULL. No deallocation is

 *         needed.

 *         If *zeroCounts >= 0, the list must be deallocated by the caller

 *         after each of the elements has been "mpfr_cleared".

 *         if something goes wrong *zeroCounts < 0.

 */

mpfr_t *

pobyso_dirty_find_zeros_bounds(pobyso_func_exp_t funcExpSo,

                              mpfr_t lowerBoundMp,

                              mpfr_t upperBoundMp,

                              int* zerosCount);

/**

 * Get the current verbosity level.

 * @return an integer at the current verbosity level.

 */

int

pobyso_get_verbosity();

/**

 * Evaluate an expression for a constant.

 *

 * The result of the evaluation must be "inited" by the caller.

 * Its contents is modified only if the evaluation yields some useful

 * result. In this case, its precision may change too.

 *@param functionSo : the function to evaluate;

 *@param argumentMp : the argument used for the evaluation;

 *@param evalutionMp: the result of the evaluation.

 *@return 0 if 0K, 1 in case of a "generic" error or POBYSO_UNFAITHFULL

 *        if the result is the mean of the two bound of the range

 *        encompassing it and POBYSO_NAN if the result of the evaluation

 *        is not a number.

 */

int

pobyso_evaluate_constant(pobyso_func_exp_t functionSo,

                         mpfr_t argumentMp,

                         mpfr_t evaluationMp);

/**

 * Check if a sollya object is a constant expression.

 * @return 1 if true and zero otherwise

 */

int

pobyso_is_constant_expression(sollya_obj_t objToTestSo);

/**

 * Check if an expression is a monomial (the free variable to an integer

 * positive or null power.

 * @param exprSo: a Sollya functional expression object;

 * @return 1 if exprSo is a monomial (as defined above), 0 otherwise.

 */

int pobyso_is_monomial(pobyso_func_exp_t exprSo);

/**

 * Check if an expression is a polynomial term (monome)

 * (a constant * the free variable to an integer positive or null power or

 *  the free variable to an integer positive or null power * a constant).

 * @param exprSo: a Sollya functional expression object;

 * @return 1 if exprSo is a polynomial term (as defined above), 0 otherwise.

 */

int pobyso_is_polynomial_term(pobyso_func_exp_t exprSo);

/**

 * Check if an expression is an integer.

 */

int

pobyso_is_int(pobyso_func_exp_t exprSo);

/**

 * Create a Sollya monomial from a Sollya constant,

 * the coefficient, and an integer, the exponent.

 * @param coefficient must be a non NULL constant expression;

 * @param degree must be a non negative integer;

 * @return a Sollya functional expression if successes, or a Sollya error

 * if fails.

 */

pobyso_func_exp_t

pobyso_new_monomial(pobyso_func_exp_t coefficient, long degree);

/**

 * Create a Sollya "off" object. */

pobyso_on_off_t

pobyso_on();

/**

 * Create a Sollya "on" object. */

pobyso_on_off_t

pobyso_off();

/**

 * A wrapper around the Sollya Remez function.

 */

/**

 * Parse a string to create a Sollya object.

 * A very thin wrapper around the sollya_lib_parse_string() function.

 * If the final ";" is forgotten in the expression, it is added by the

 * function.

 * @return a Sollya functional expression if successes, or a Sollya error

 * if fails.

 */

pobyso_func_exp_t

pobyso_parse_string(const char* expression);

/** Disable the console output from Sollya.

 * @return a Sollya constant holding the current verbosity level

 *         when Sollya was silenced or NULL, if something goes wrong.*/

pobyso_constant_t

pobyso_quiet();

/** Create a Sollya range from two MPFR bounds.

 * A wrapper around sollya_lib_range_from_bounds.

 */

pobyso_range_t

pobyso_range_from_bounds(mpfr_t lowerBound, mpfr_t upperBound);

/**

 * A wrapper around the Sollya Remez function with the canonical monomials

 * base.

 */

pobyso_func_exp_t

pobyso_remez_canonical_monomials_base(pobyso_func_exp_t function,

                                      long int degree,

                                      pobyso_range_t interval,

                                      pobyso_func_exp_t weight,

                                      double quality,

                                      pobyso_range_t bounds);

/**

 * A wrapper around the Sollya Remez function with the a sparse monomials

 * base.

 */

pobyso_func_exp_t

pobyso_remez_sparse_monomials_base(pobyso_func_exp_t);

/**

 * A wrapper around the Sollya Remez function with the canonical monomials

 * base.

 */

pobyso_func_exp_t

pobyso_remez_arbitrary_base(pobyso_func_exp_t);

/**

 * Set the canonical mode.

 */

int

pobyso_set_canonical_on(void);

/**

 * Set the verbosity mode off (level 0).

 * The current level of verbosity is returned.

 */

int

pobyso_set_verbosity_off(void);

/**

 * Set the verbosity level to newVerbosityLevel.

 * @param newVerbosityLevel must be a Sollya object corresponding to an

 *        integer constant.

 */

int

pobyso_set_verbosity_to(int newVerbosityLevel);

/**

 * Wrapper around the sollya_lib_subpoly Sollya function.

 */

pobyso_func_exp_t

pobyso_subpoly(pobyso_func_exp_t polynomial, long expsNum, long* expsList);

#if 0

/**

 * Create the canonical (non sparse) base of monomials for a given degree.

 */

chain*

pobyso_create_canonical_monomials_base(const unsigned int degree);

/**

 * Create a chain from an array of int.

 */

sollya_int_list

pobyso_create_int_list_from_int_Array(int* intArray,

                                    const unsigned int arrayLength);

/**

 * Create a chain from an array of int.

 */

sollya_int_list_t

pobyso_create_int_list_from_unsigned_int_array(unsigned int* intArray,

                                            const unsigned int arrayLength);

/**

 * Differentiation of a function.

 * A slim wrapper around the Sollya differentiate function.

 * @param functionNode - the Sollya node to differentiate;

 * @return a node representing the function differentiated or NULL, if

 *         something goes wrong.

 */

sollya_obj_t

pobyso_diff(sollya_obj_t function);

/**

 * A match to the Sollya dirtyinfnorm.

 * A slim wrapper around the Sollya function.

 * @param infnorm - out parameter to return the result, must be "inited"

 *                  and "cleared" by the caller;

 * @param functionNode - the Sollya node to compute the infinite norm of;

 * @param lowerBound - the lower bound of the interval;

 * @param upperBound - the upper bound of the interval;

 * @param precision  - the internal precision Sollya must use.

 * @return 0 if everything is OK, != 0 if something goes wrong.

 */

int

pobyso_dirty_infnorm(mpfr_t infNorm,

                      node *functionNode,

                      mpfr_t lowerBound,

                      mpfr_t upperBound,

                      mp_prec_t precision);

/**

 * Faithful evaluation of an expression.

 *

 * @param faithfulEvaluation - holds the result, must be "inited" by the

 *                             caller;

 */

int

pobyso_evaluate_faithful(mpfr_t faithfulEvaluation,

                          node *nodeToEvaluate,

                          mpfr_t argument,

                          mpfr_prec_t precision);

/**

 * Find the zeros of a function on a given interval.

 */

chain*

pobyso_find_zeros(node *function,

                  mpfr_t *lowerBound,

                  mpfr_t *upperBound);

/**

 * Free a chain of node.

 * All elements of the chain have to be nodes.

 */

void

pobyso_free_chain_of_nodes(chain *theChain);

/**

 * Free a range.

 * It involves clearing the mpfr_t elements and deallocating the

 * pointers.

 */

void

pobyso_free_range(rangetype range);

/**

 * Computes a good polynomial approximation with fixed-point or floating-point

 * coefficients.

 */

node*

pobyso_fp_minimax_canonical_monomials_base(node *function,

                                          int degree,

                                          chain *formats,

                                          chain *points,

                                          mpfr_t lowerBound,

                                          mpfr_t upperBound,

                                          int fpFixedArg,

                                          int absRel,

                                          node *constPart,

                                          node *minimax);

/**

 * Parses a string to build the node representing the function.

 * In fact, does nothing for the moment: the string must be a correct function

 * definition. No error correction takes place here.

 */

node*

pobyso_parse_function(char *functionString,

                      char *freeVariableNameString);

/** Compute a polynomial approximation in the canonical monomials basis for

 *  a function, for a given precision. The returned polynomial has the minimal

 *  degree to achieve the required precision.

 */

node*

pobyso_remez_approx_canonical_monomials_base_for_error(node *functionNode,

                                                      unsigned int mode,

                                                      mpfr_t lowerBound,

                                                      mpfr_t upperBound,

                                                      mpfr_t eps);

/**

 * Computes a the remez approximation of a function.

 * @param function   - the node holding the function to approximate;

 * @param weight     - the node holding the weight function, can be NULL. In

 *                     this case a default weight of "1" will be provided and

 *                     the approximation is related is with respect to the

 *                     absolute error.

 * @param degree     - the degree of the approximation polynomial;

 * @param lowerBound - the lower bound of the approximation interval;

 * @param upperBound - the upper bound of the approximation interval;

 * @param quality    - quality = (eps - eps*) / eps*; the search stop when the required

 *                     quality is achieved.

 *

 * @return a node holding the approximation polynomial in Horner form.

 */

node*

pobyso_remez_canonical_monomials_base(node *function,

                                       node *weight,

                                       unsigned int degree,

                                       mpfr_t lowerBound,

                                       mpfr_t upperBound,

                                       mpfr_t quality);

#endif

#define POBYSO_h

#endif