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

"""

Actual functions to use in Sage

ST 2012-11-13

Command line syntax:

  use from Sage (via the "load" or the "attach" commands)

pobyso functions come in five flavors:

- the _so_so (arguments and returned objects are pointers to Sollya objects,

  includes the void function and the no arguments function that return a

  pointer to a Sollya object);

- the _so_sa (argument are pointers to Sollya objects, returned objects are

  Sage/Python objects or, more generally, information is transfered from the

  Sollya world to Sage/Python world; e.g. functions without arguments that

  return a Sage/Python object);

- the _sa_so (arguments are Sage/Python objects, returned objects are

  pointers to Sollya objects);

- the sa_sa (arguments and returned objects are all Sage/Python objects);

- a catch all flavor, without any suffix, (e. g. functions that have no argument

  nor return value).

This classification is not always very strict. Conversion functions from Sollya

to Sage/Python are sometimes decorated with Sage/Python arguments to set

the precision. These functions remain in the so_sa category.

NOTES:

Reported errors in Eclipse come from the calls to

the Sollya library

ToDo (among other things):

 -memory management.

"""

from ctypes import *

import re

from sage.symbolic.expression_conversions import polynomial

from sage.symbolic.expression_conversions import PolynomialConverter

"""

Create the equivalent to an enum for the Sollya function types.

"""

(SOLLYA_BASE_FUNC_ABS,

SOLLYA_BASE_FUNC_ACOS,

    SOLLYA_BASE_FUNC_ACOSH,

    SOLLYA_BASE_FUNC_ADD,

    SOLLYA_BASE_FUNC_ASIN,

    SOLLYA_BASE_FUNC_ASINH,

    SOLLYA_BASE_FUNC_ATAN,

    SOLLYA_BASE_FUNC_ATANH,

    SOLLYA_BASE_FUNC_CEIL,

    SOLLYA_BASE_FUNC_CONSTANT,

    SOLLYA_BASE_FUNC_COS,

    SOLLYA_BASE_FUNC_COSH,

    SOLLYA_BASE_FUNC_DIV,

    SOLLYA_BASE_FUNC_DOUBLE,

    SOLLYA_BASE_FUNC_DOUBLEDOUBLE,

    SOLLYA_BASE_FUNC_DOUBLEEXTENDED,

    SOLLYA_BASE_FUNC_ERF,

    SOLLYA_BASE_FUNC_ERFC,

    SOLLYA_BASE_FUNC_EXP,

    SOLLYA_BASE_FUNC_EXP_M1,

    SOLLYA_BASE_FUNC_FLOOR,

    SOLLYA_BASE_FUNC_FREE_VARIABLE,

    SOLLYA_BASE_FUNC_HALFPRECISION,

    SOLLYA_BASE_FUNC_LIBRARYCONSTANT,

    SOLLYA_BASE_FUNC_LIBRARYFUNCTION,

    SOLLYA_BASE_FUNC_LOG,

    SOLLYA_BASE_FUNC_LOG_10,

    SOLLYA_BASE_FUNC_LOG_1P,

    SOLLYA_BASE_FUNC_LOG_2,

    SOLLYA_BASE_FUNC_MUL,

    SOLLYA_BASE_FUNC_NEARESTINT,

    SOLLYA_BASE_FUNC_NEG,

    SOLLYA_BASE_FUNC_PI,

    SOLLYA_BASE_FUNC_POW,

    SOLLYA_BASE_FUNC_PROCEDUREFUNCTION,

    SOLLYA_BASE_FUNC_QUAD,

    SOLLYA_BASE_FUNC_SIN,

    SOLLYA_BASE_FUNC_SINGLE,

    SOLLYA_BASE_FUNC_SINH,

    SOLLYA_BASE_FUNC_SQRT,

    SOLLYA_BASE_FUNC_SUB,

    SOLLYA_BASE_FUNC_TAN,

    SOLLYA_BASE_FUNC_TANH,

SOLLYA_BASE_FUNC_TRIPLEDOUBLE) = map(int,xrange(44))

print "\nSuperficial pobyso check..."

print "First constant - SOLLYA_BASE_FUNC_ABS: ", SOLLYA_BASE_FUNC_ABS

print "Last constant  - SOLLYA_BASE_FUNC_TRIPLEDOUBLE: ", SOLLYA_BASE_FUNC_TRIPLEDOUBLE

pobyso_max_arity = 9

def pobyso_absolute_so_so():

    return(sollya_lib_absolute(None))

def pobyso_autoprint(arg):

    sollya_lib_autoprint(arg,None)

def pobyso_autoprint_so_so(arg):

    sollya_lib_autoprint(arg,None)

def pobyso_bounds_to_range_sa_so(rnLowerBoundSa, rnUpperBoundSa, \

                                 precisionSa=None):

    """

    Return a Sollya range from to 2 RealField Sage elements.

    The Sollya range element has a sufficient precision to hold all

    the digits of the widest of the Sage bounds.

    """

    # Sanity check.

    if rnLowerBoundSa > rnUpperBoundSa:

        return None

    # Precision stuff.

    if precisionSa is None:

        # Check for the largest precision.

        lbPrecSa = rnLowerBoundSa.parent().precision()

        ubPrecSa = rnLowerBoundSa.parent().precision()

        maxPrecSa = max(lbPrecSa, ubPrecSa)

    else:

        maxPrecSa = precisionSa

    # From Sage to Sollya bounds.

#    lowerBoundSo = sollya_lib_constant(get_rn_value(rnLowerBoundSa),

#                                       maxPrecSa)

    lowerBoundSo = pobyso_constant_sa_so(rnLowerBoundSa,

                                         maxPrecSa)

    upperBoundSo = pobyso_constant_sa_so(rnUpperBoundSa,

                                       maxPrecSa)

    # From Sollya bounds to range.

    rangeSo = sollya_lib_range(lowerBoundSo, upperBoundSo)

    # Back to original precision.

    # Clean up

    sollya_lib_clear_obj(lowerBoundSo)

    sollya_lib_clear_obj(upperBoundSo)

    return rangeSo

# End pobyso_bounds_to_range_sa_so

def pobyso_build_function_sub_so_so(exp1So, exp2So):

    return(sollya_lib_build_function_sub(exp1So, exp2So))

def pobyso_change_var_in_function_so_so(funcSo, chvarExpSo):

    """

    Variable change in a function.

    """

    return(sollya_lib_evaluate(funcSo,chvarExpSo))

# End pobyso_change_var_in_function_so_so

def pobyso_chebyshevform_so_so(functionSo, degreeSo, intervalSo):

    resultSo = sollya_lib_chebyshevform(functionSo, degreeSo, intervalSo)

    return(resultSo)

# End pobyso_chebyshevform_so_so.

def pobyso_clear_taylorform_sa_so(taylorFormSaSo):

    """

    This method is necessary to correctly clean up the memory from Taylor forms.

    These are made of a Sollya object, a Sollya object list, a Sollya object.

    For no clearly understood reason, sollya_lib_clear_object_list crashed

    when applied to the object list.

    Here, we decompose it into Sage list of Sollya objects references and we

     clear them one by one.

    """

    sollya_lib_clear_obj(taylorFormSaSo[0])

    (coefficientsErrorsListSaSo, numElementsSa, isEndEllipticSa) = \

        pobyso_get_list_elements_so_so(taylorFormSaSo[1])

    for element in coefficientsErrorsListSaSo:

        sollya_lib_clear_obj(element)

    sollya_lib_clear_obj(taylorFormSaSo[1])

    sollya_lib_clear_obj(taylorFormSaSo[2])

# End pobyso_clear_taylorform_sa_so

def pobyso_cmp(rnArgSa, cteSo):

    """

    Compare the MPFR value a RealNumber with that of a Sollya constant.

    Get the value of the Sollya constant into a RealNumber and compare

    using MPFR. Could be optimized by working directly with a mpfr_t

    for the intermediate number.

    """

    # Get the precision of the Sollya constant to build a Sage RealNumber

    # with enough precision.to hold it.

    precisionOfCte = c_int(0)

    # From the Sollya constant, create a local Sage RealNumber.

    sollya_lib_get_prec_of_constant(precisionOfCte, cteSo)

    #print "Precision of constant: ", precisionOfCte

    RRRR = RealField(precisionOfCte.value)

    rnLocalSa = RRRR(0)

    sollya_lib_get_constant(get_rn_value(rnLocalSa), cteSo)

    #

    ## Compare the Sage RealNumber version of the Sollya constant with rnArg.

    return(cmp_rn_value(rnArgSa, rnLocal))

# End pobyso_smp

def pobyso_compute_pos_function_abs_val_bounds_sa_sa(funcSa, lowerBoundSa, \

                                                     upperBoundSa):

    """

    TODO: completely rework and test.

    """

    pobyso = pobyso_name_free_variable_sa_so(funcSa.variables()[0])

    funcSo = pobyso_parse_string(funcSa._assume_str().replace('_SAGE_VAR_', ''))

    rangeSo = pobyso_range_sa_so(lowerBoundSa, upperBoundSa)

    infnormSo = pobyso_infnorm_so_so(funcSo,rangeSo)

    # Sollya return the infnorm as an interval.

    fMaxSa = pobyso_get_interval_from_range_so_sa(infnormSo)

    # Get the top bound and compute the binade top limit.

    fMaxUpperBoundSa = fMaxSa.upper()

    binadeTopLimitSa = 2**ceil(fMaxUpperBoundSa.log2())

    # Put up together the function to use to compute the lower bound.

    funcAuxSo = pobyso_parse_string(str(binadeTopLimitSa) +  \

                                    '-(' + f._assume_str().replace('_SAGE_VAR_', '') + ')')

    pobyso_autoprint(funcAuxSo)

    # Clear the Sollya range before a new call to infnorm and issue the call.

    sollya_lib_clear_obj(infnormSo)

    infnormSo = pobyso_infnorm_so_so(funcAuxSo,rangeSo)

    fMinSa = pobyso_get_interval_from_range_so_sa(infnormSo)

    sollya_lib_clear_obj(infnormSo)

    fMinLowerBoundSa = binadeTopLimitSa - fMinSa.lower()

    # Compute the maximum of the precisions of the different bounds.

    maxPrecSa = max([fMinLowerBoundSa.parent().precision(), \

                     fMaxUpperBoundSa.parent().precision()])

    # Create a RealIntervalField and create an interval with the "good" bounds.

    RRRI = RealIntervalField(maxPrecSa)

    imageIntervalSa = RRRI(fMinLowerBoundSa, fMaxUpperBoundSa)

    # Free the unneeded Sollya objects

    sollya_lib_clear_obj(funcSo)

    sollya_lib_clear_obj(funcAuxSo)

    sollya_lib_clear_obj(rangeSo)

    return(imageIntervalSa)

# End pobyso_compute_pos_function_abs_val_bounds_sa_sa

def pobyso_constant(rnArg):

    """ Legacy function. See pobyso_constant_sa_so. """

    return(pobyso_constant_sa_so(rnArg))

def pobyso_constant_sa_so(rnArgSa, precisionSa=None):

    """

    Create a Sollya constant from a Sage RealNumber.

    """

    # Precision stuff

    if precisionSa is None:

        precisionSa = rnArgSa.parent().precision()

    currentSollyaPrecisionSo = sollya_lib_get_prec()

    currentSollyaPrecisionSa = \

        pobyso_constant_from_int(currentSollyaPrecisionSo)

    # Sollya constant creation takes place here.

    if precisionSa > currentSollyaPrecisionSa:

        pobyso_set_prec_sa_so(precisionSa)

        constantSo = sollya_lib_constant(get_rn_value(rnArgSa))

        pobyso_set_prec_so_so(currentSollyaPrecisionSo)

    else:

        constantSo = sollya_lib_constant(get_rn_value(rnArgSa))

    sollya_lib_clear_obj(currentSollyaPrecisionSo)

    return constantSo

# End pobyso_constant_sa_so

def pobyso_constant_0_sa_so():

    """

    Obvious.

    """

    return(pobyso_constant_from_int_sa_so(0))

def pobyso_constant_1():

    """

    Obvious.

    Legacy function. See pobyso_constant_so_so.

    """

    return(pobyso_constant_1_sa_so())

def pobyso_constant_1_sa_so():

    """

    Obvious.

    """

    return(pobyso_constant_from_int_sa_so(1))

def pobyso_constant_from_int(anInt):

    """ Legacy function. See pobyso_constant_from_int_sa_so. """

    return(pobyso_constant_from_int_sa_so(anInt))

def pobyso_constant_from_int_sa_so(anInt):

    """

    Get a Sollya constant from a Sage int.

    """

    return(sollya_lib_constant_from_int64(long(anInt)))

def pobyso_constant_from_int_so_sa(constSo):

    """

    Get a Sage int from a Sollya int constant.

    Usefull for precision or powers in polynomials.

    """

    constSa = c_long(0)

    sollya_lib_get_constant_as_int64(byref(constSa), constSo)

    return(constSa.value)

# End pobyso_constant_from_int_so_sa

def pobyso_constant_from_mpq_sa_so(rationalSa, precision = None):

    """

    Make a Sollya constant from Sage rational.

    A bit convoluted to take into account precision and the fact

    that mpq constants in Sollya a non-evaluated expressions.

    Function building and evaluation is needed to make it a "real"

    evaluated constant.

    """

    ## Deal with precision stuff.

    curPrecSa = None

    curPrecSo = None

    if not precision is None:

        curPrecSo = pobyso_get_prec_so()

        curPrecSaSa = c_int(0)

        sollya_lib_get_constant_as_int(byref(curPrecSaSa), curPrecSo)

        curPrecSa = int(curPrecSaSa.value)

        if curPrecSa != precision:

            pobyso_set_prec_sa_so(precision)

    ## In Sollya mpq constants are non-evaluated expressions.

    #  We must force evaluation.

    zeroSo    = pobyso_constant_0_sa_so()

    oneSo     = pobyso_constant_1_sa_so()

    ratExprSo = \

        sollya_lib_constant_from_mpq(sgmp_get_rational_value(rationalSa))

    addExprSo = sollya_lib_build_function_add(zeroSo, ratExprSo)

    constSo   = sollya_lib_evaluate(addExprSo,oneSo)

    ## Clears expression and arguments, as the former was created with a

    #  "build" variant.

    sollya_lib_clear_obj(addExprSo)

    sollya_lib_clear_obj(oneSo)

    if curPrecSa != precision:

        pobyso_set_prec_so_so(curPrecSo)

        sollya_lib_clear_obj(curPrecSo)

    return constSo

# End pobyso_constant_from_mpq_sa_so.

def pobyso_error_so():

    return sollya_lib_error(None)

# End pobyso_error().

def pobyso_function_type_as_string(funcType):

    """ Legacy function. See pobyso_function_type_as_string_so_sa. """

    return(pobyso_function_type_as_string_so_sa(funcType))

def pobyso_function_type_as_string_so_sa(funcType):

    """

    Numeric Sollya function codes -> Sage mathematical function names.

    Notice that pow -> ^ (a la Sage, not a la Python).

    """

    if funcType == SOLLYA_BASE_FUNC_ABS:

        return "abs"

    elif funcType == SOLLYA_BASE_FUNC_ACOS:

        return "arccos"

    elif funcType == SOLLYA_BASE_FUNC_ACOSH:

        return "arccosh"

    elif funcType == SOLLYA_BASE_FUNC_ADD:

        return "+"

    elif funcType == SOLLYA_BASE_FUNC_ASIN:

        return "arcsin"

    elif funcType == SOLLYA_BASE_FUNC_ASINH:

        return "arcsinh"

    elif funcType == SOLLYA_BASE_FUNC_ATAN:

        return "arctan"

    elif funcType == SOLLYA_BASE_FUNC_ATANH:

        return "arctanh"

    elif funcType == SOLLYA_BASE_FUNC_CEIL:

        return "ceil"

    elif funcType == SOLLYA_BASE_FUNC_CONSTANT:

        return "cte"

    elif funcType == SOLLYA_BASE_FUNC_COS:

        return "cos"

    elif funcType == SOLLYA_BASE_FUNC_COSH:

        return "cosh"

    elif funcType == SOLLYA_BASE_FUNC_DIV:

        return "/"

    elif funcType == SOLLYA_BASE_FUNC_DOUBLE:

        return "double"

    elif funcType == SOLLYA_BASE_FUNC_DOUBLEDOUBLE:

        return "doubleDouble"

    elif funcType == SOLLYA_BASE_FUNC_DOUBLEEXTENDED:

        return "doubleDxtended"

    elif funcType == SOLLYA_BASE_FUNC_ERF:

        return "erf"

    elif funcType == SOLLYA_BASE_FUNC_ERFC:

        return "erfc"

    elif funcType == SOLLYA_BASE_FUNC_EXP:

        return "exp"

    elif funcType == SOLLYA_BASE_FUNC_EXP_M1:

        return "expm1"

    elif funcType == SOLLYA_BASE_FUNC_FLOOR:

        return "floor"

    elif funcType == SOLLYA_BASE_FUNC_FREE_VARIABLE:

        return "freeVariable"

    elif funcType == SOLLYA_BASE_FUNC_HALFPRECISION:

        return "halfPrecision"

    elif funcType == SOLLYA_BASE_FUNC_LIBRARYCONSTANT:

        return "libraryConstant"

    elif funcType == SOLLYA_BASE_FUNC_LIBRARYFUNCTION:

        return "libraryFunction"

    elif funcType == SOLLYA_BASE_FUNC_LOG:

        return "log"

    elif funcType == SOLLYA_BASE_FUNC_LOG_10:

        return "log10"

    elif funcType == SOLLYA_BASE_FUNC_LOG_1P:

        return "log1p"

    elif funcType == SOLLYA_BASE_FUNC_LOG_2:

        return "log2"

    elif funcType == SOLLYA_BASE_FUNC_MUL:

        return "*"

    elif funcType == SOLLYA_BASE_FUNC_NEARESTINT:

        return "round"

    elif funcType == SOLLYA_BASE_FUNC_NEG:

        return "__neg__"

    elif funcType == SOLLYA_BASE_FUNC_PI:

        return "pi"

    elif funcType == SOLLYA_BASE_FUNC_POW:

        return "^"

    elif funcType == SOLLYA_BASE_FUNC_PROCEDUREFUNCTION:

        return "procedureFunction"

    elif funcType == SOLLYA_BASE_FUNC_QUAD:

        return "quad"

    elif funcType == SOLLYA_BASE_FUNC_SIN:

        return "sin"

    elif funcType == SOLLYA_BASE_FUNC_SINGLE:

        return "single"

    elif funcType == SOLLYA_BASE_FUNC_SINH:

        return "sinh"

    elif funcType == SOLLYA_BASE_FUNC_SQRT:

        return "sqrt"

    elif funcType == SOLLYA_BASE_FUNC_SUB:

        return "-"

    elif funcType == SOLLYA_BASE_FUNC_TAN:

        return "tan"

    elif funcType == SOLLYA_BASE_FUNC_TANH:

        return "tanh"

    elif funcType == SOLLYA_BASE_FUNC_TRIPLEDOUBLE:

        return "tripleDouble"

    else:

        return None

def pobyso_get_constant(rnArgSa, constSo):

    """ Legacy function. See pobyso_get_constant_so_sa. """

    return(pobyso_get_constant_so_sa(rnArgSa, constSo))

def pobyso_get_constant_so_sa(rnArgSa, constSo):

    """

    Set the value of rnArgSo to the value of constSo in MPFR_RNDN mode.

    rnArg must already exist and belong to some RealField.

    We assume that constSo points to a Sollya constant.

    """

    return(sollya_lib_get_constant(get_rn_value(rnArgSa), constSo))

def pobyso_get_constant_as_rn(ctExpSo):

    """

    Legacy function. See pobyso_get_constant_as_rn_so_sa.

    """

    return(pobyso_get_constant_as_rn_so_sa(ctExpSo))

def pobyso_get_constant_as_rn_so_sa(constExpSo):

    """

    Get a Sollya constant as a Sage "real number".

    The precision of the floating-point number returned is that of the Sollya

    constant.

    """

    precisionSa  = pobyso_get_prec_of_constant_so_sa(constExpSo)

    RRRR = RealField(precisionSa)

    rnSa = RRRR(0)

    sollya_lib_get_constant(get_rn_value(rnSa), constExpSo)

    return(rnSa)

# End pobyso_get_constant_as_rn_so_sa

def pobyso_get_constant_as_rn_with_rf(ctExp, realField):

    """

    Legacy function. See pobyso_get_constant_as_rn_with_rf_so_sa.

    """

    return(pobyso_get_constant_as_rn_with_rf_so_sa(ctExp, realField))

def pobyso_get_constant_as_rn_with_rf_so_sa(ctExpSo, realFieldSa = None):

    """

    Get a Sollya constant as a Sage "real number".

    If no real field is specified, the precision of the floating-point number

    returned is that of the Sollya constant.

    Otherwise is is that of the real field. Hence rounding may happen.

    """

    if realFieldSa is None:

        sollyaPrecSa = pobyso_get_prec_of_constant_so_sa(ctExpSo)

        realFieldSa = RealField(sollyaPrecSa)

    rnSa = realFieldSa(0)

    sollya_lib_get_constant(get_rn_value(rnSa), ctExpSo)

    return(rnSa)

# End pobyso_get_constant_as_rn_with_rf_so_sa

def pobyso_get_float_poly_sa_so(polySa, realFieldSa=None):

    """

    Create a Sollya polynomial from a Sage polynomial.

    """

    pass

# End get_float_poly_sa_so.

def pobyso_get_free_variable_name():

    """

    Legacy function. See pobyso_get_free_variable_name_so_sa.

    """

    return(pobyso_get_free_variable_name_so_sa())

def pobyso_get_free_variable_name_so_sa():

    return(sollya_lib_get_free_variable_name())

def pobyso_get_function_arity(expressionSo):

    """

    Legacy function. See pobyso_get_function_arity_so_sa.

    """

    return(pobyso_get_function_arity_so_sa(expressionSo))

def pobyso_get_function_arity_so_sa(expressionSo):

    arity = c_int(0)

    sollya_lib_get_function_arity(byref(arity),expressionSo)

    return(int(arity.value))

def pobyso_get_head_function(expressionSo):

    """

    Legacy function. See pobyso_get_head_function_so_sa.

    """

    return(pobyso_get_head_function_so_sa(expressionSo))

def pobyso_get_head_function_so_sa(expressionSo):

    functionType = c_int(0)

    sollya_lib_get_head_function(byref(functionType), expressionSo, None)

    return(int(functionType.value))

def pobyso_get_interval_from_range_so_sa(soRange, realIntervalFieldSa = None ):

    """

    Return the Sage interval corresponding to the Sollya range argument.

    If no reaIntervalField is passed as an argument, the interval bounds are not

    rounded: they are elements of RealIntervalField of the "right" precision

    to hold all the digits.

    """

    prec = c_int(0)

    if realIntervalFieldSa is None:

        retval = sollya_lib_get_prec_of_range(byref(prec), soRange, None)

        if retval == 0:

            return(None)

        realIntervalFieldSa = RealIntervalField(prec.value)

    intervalSa = realIntervalFieldSa(0,0)

    retval = \

        sollya_lib_get_interval_from_range(get_interval_value(intervalSa),\

                                           soRange)

    if retval == 0:

        return(None)

    return(intervalSa)

# End pobyso_get_interval_from_range_so_sa

def pobyso_get_list_elements(soObj):

    """ Legacy function. See pobyso_get_list_elements_so_so. """

    return(pobyso_get_list_elements_so_so(soObj))

def pobyso_get_list_elements_so_so(objectListSo):

    """

    Get the Sollya list elements as a Sage/Python array of Sollya objects.

    INPUT:

    - objectListSo: a Sollya list of Sollya objects.

    OUTPUT:

    - a Sage/Python tuple made of:

      - a Sage/Python list of Sollya objects,

      - a Sage/Python int holding the number of elements,

      - a Sage/Python int stating (!= 0) that the list is end-elliptic.

    NOTE::

        We recover the addresses of the Sollya object from the list of pointers

        returned by sollya_lib_get_list_elements. The list itself is freed.

    TODO::

        Figure out what to do with numElements since the number of elements

        can easily be recovered from the list itself.

        Ditto for isEndElliptic.

    """

    listAddress = POINTER(c_longlong)()

    numElements = c_int(0)

    isEndElliptic = c_int(0)

    listAsSageList = []

    result = sollya_lib_get_list_elements(byref(listAddress),\

                                          byref(numElements),\

                                          byref(isEndElliptic),\

                                          objectListSo)

    if result == 0 :

        return None

    for i in xrange(0, numElements.value, 1):

       #listAsSageList.append(sollya_lib_copy_obj(listAddress[i]))

       listAsSageList.append(listAddress[i])

       # Clear each of the elements returned by Sollya.

       #sollya_lib_clear_obj(listAddress[i])

    # Free the list itself.

    sollya_lib_free(listAddress)

    return(listAsSageList, numElements.value, isEndElliptic.value)

def pobyso_get_max_prec_of_exp(soExp):

    """ Legacy function. See pobyso_get_max_prec_of_exp_so_sa. """

    return(pobyso_get_max_prec_of_exp_so_sa(soExp))

def pobyso_get_max_prec_of_exp_so_sa(expSo):

    """

    Get the maximum precision used for the numbers in a Sollya expression.

    Arguments:

    soExp -- a Sollya expression pointer

    Return value:

    A Python integer

    TODO:

    - error management;

    - correctly deal with numerical type such as DOUBLEEXTENDED.

    """

    maxPrecision = 0

    minConstPrec = 0

    currentConstPrec = 0

    operator = pobyso_get_head_function_so_sa(expSo)

    if (operator != SOLLYA_BASE_FUNC_CONSTANT) and \

    (operator != SOLLYA_BASE_FUNC_FREE_VARIABLE):

        (arity, subexpressions) = pobyso_get_subfunctions_so_sa(expSo)

        for i in xrange(arity):

            maxPrecisionCandidate = \

                pobyso_get_max_prec_of_exp_so_sa(subexpressions[i])

            if maxPrecisionCandidate > maxPrecision:

                maxPrecision = maxPrecisionCandidate

        return(maxPrecision)

    elif operator == SOLLYA_BASE_FUNC_CONSTANT:

        #minConstPrec = pobyso_get_min_prec_of_constant_so_sa(expSo)

        #currentConstPrec = pobyso_get_min_prec_of_constant_so_sa(soExp)

        #print minConstPrec, " - ", currentConstPrec

        return(pobyso_get_min_prec_of_constant_so_sa(expSo))

    elif operator == SOLLYA_BASE_FUNC_FREE_VARIABLE:

        return(0)

    else:

        print "pobyso_get_max_prec_of_exp_so_sa: unexepected operator."

        return(0)

def pobyso_get_min_prec_of_constant_so_sa(constExpSo):

    """

    Get the minimum precision necessary to represent the value of a Sollya

    constant.

    MPFR_MIN_PREC and powers of 2 are taken into account.

    We assume that constExpSo is a point

    """

    constExpAsRnSa = pobyso_get_constant_as_rn_so_sa(constExpSo)

    return(min_mpfr_size(get_rn_value(constExpAsRnSa)))

def pobyso_get_poly_so_sa(polySo, realFieldSa=None):

    """

    Convert a Sollya polynomial into a Sage polynomial.

    We assume that the polynomial is in canonical form.

    If no realField is given, a RealField corresponding to the maximum

    precision of the coefficients is internally computed.

    The real field is not returned but can be easily retrieved from

    the polynomial itself.

    ALGORITHM:

    - (optional) compute the RealField of the coefficients;

    - convert the Sollya expression into a Sage expression;

    - convert the Sage expression into a Sage polynomial

    TODO: the canonical thing for the polynomial.

    """

    if realFieldSa is None:

        expressionPrecSa = pobyso_get_max_prec_of_exp_so_sa(polySo)

        realFieldSa = RealField(expressionPrecSa)

    #print "Sollya expression before...",

    #pobyso_autoprint(polySo)

    expressionSa = pobyso_get_sage_exp_from_sollya_exp_so_sa(polySo, \

                                                             realFieldSa)

    #print "...Sollya expression after.",

    #pobyso_autoprint(polySo)

    polyVariableSa = expressionSa.variables()[0]

    polyRingSa = realFieldSa[str(polyVariableSa)]

    #print polyRingSa

    # Do not use the polynomial(expressionSa, ring=polyRingSa) form!

    polynomialSa = polyRingSa(expressionSa)

    return(polynomialSa)

# End pobyso_get_poly_so_sa

def pobyso_get_prec():

    """ Legacy function. See pobyso_get_prec_so_sa(). """

    return(pobyso_get_prec_so_sa())

def pobyso_get_prec_so():

    """

    Get the current default precision in Sollya.

    The return value is a Sollya object.

    Usefull when modifying the precision back and forth by avoiding

    extra conversions.

    """

    return(sollya_lib_get_prec(None))

def pobyso_get_prec_so_sa():

    """

    Get the current default precision in Sollya.

    The return value is Sage/Python int.

    """

    precSo = sollya_lib_get_prec(None)

    precSa = c_int(0)

    sollya_lib_get_constant_as_int(byref(precSa), precSo)

    sollya_lib_clear_obj(precSo)

    return int(precSa.value)

# End pobyso_get_prec_so_sa.

def pobyso_get_prec_of_constant(ctExpSo):

    """ Legacy function. See pobyso_get_prec_of_constant_so_sa. """

    return(pobyso_get_prec_of_constant_so_sa(ctExpSo))

def pobyso_get_prec_of_constant_so_sa(ctExpSo):

    """

    Tries to find a precision to represent ctExpSo without rounding.

    If not possible, returns None.

    """

    prec = c_int(0)

    retc = sollya_lib_get_prec_of_constant(byref(prec), ctExpSo, None)

    if retc == 0:

        return(None)

    return(int(prec.value))

def pobyso_get_prec_of_range_so_sa(rangeSo):

    """

    Returns the number of bits elements of a range are coded with.

    """

    prec = c_int(0)

    retc = sollya_lib_get_prec_of_range(byref(prec), rangeSo, None)

    if retc == 0:

        return(None)

    return(int(prec.value))

# End pobyso_get_prec_of_range_so_sa()

def pobyso_get_rat_poly_sa_so(polySa, precSa = None):

    """

    Create a Sollya polynomial from a Sage rational polynomial.

    """

    ## TODO: filter arguments.

    ##

    if not precSa is None:

        initialPrecSo = pobyso_get_prec_so()

    coefficients = polySa.coefficients()

    exponents    = polySa.exponents()

    ## TODO: deal with variables names.

    ## If necessary, return Sollya to its initial default precision.

    if not precSa is None:

        pobyso_set_prec_so_so(initialPrecSo)

# End pobyso_get_rat_poly_sa_so

def pobyso_get_sage_exp_from_sollya_exp(sollyaExpSo, realField = RR):

    """ Legacy function. See pobyso_get_sage_exp_from_sollya_exp_so_sa. """

    return(pobyso_get_sage_exp_from_sollya_exp_so_sa(sollyaExpSo, \

                                                     realField = RR))

def pobyso_get_sage_exp_from_sollya_exp_so_sa(sollyaExpSo, realFieldSa = RR):

    """

    Get a Sage expression from a Sollya expression.

    Currently only tested with polynomials with floating-point coefficients.

    Notice that, in the returned polynomial, the exponents are RealNumbers.

    """

    #pobyso_autoprint(sollyaExp)

    operatorSa = pobyso_get_head_function_so_sa(sollyaExpSo)

    sollyaLibFreeVariableName = sollya_lib_get_free_variable_name()

    # Constants and the free variable are special cases.

    # All other operator are dealt with in the same way.

    if (operatorSa != SOLLYA_BASE_FUNC_CONSTANT) and \

       (operatorSa != SOLLYA_BASE_FUNC_FREE_VARIABLE):

        (aritySa, subexpressionsSa) = pobyso_get_subfunctions_so_sa(sollyaExpSo)

        if aritySa == 1:

            sageExpSa = eval(pobyso_function_type_as_string_so_sa(operatorSa) + \

            "(" + pobyso_get_sage_exp_from_sollya_exp_so_sa(subexpressionsSa[0], \

            realFieldSa) + ")")

        elif aritySa == 2:

            # We do not get through the preprocessor.

            # The "^" operator is then a special case.

            if operatorSa == SOLLYA_BASE_FUNC_POW:

                operatorAsStringSa = "**"

            else:

                operatorAsStringSa = \

                    pobyso_function_type_as_string_so_sa(operatorSa)

            sageExpSa = \

              eval("pobyso_get_sage_exp_from_sollya_exp_so_sa(subexpressionsSa[0], realFieldSa)"\

              + " " + operatorAsStringSa + " " + \

                   "pobyso_get_sage_exp_from_sollya_exp_so_sa(subexpressionsSa[1], realFieldSa)")

        # We do not know yet how to deal with arity >= 3

        # (is there any in Sollya anyway?).

        else:

            sageExpSa = eval('None')

        return(sageExpSa)

    elif operatorSa == SOLLYA_BASE_FUNC_CONSTANT:

        #print "This is a constant"

        return pobyso_get_constant_as_rn_with_rf_so_sa(sollyaExpSo, realFieldSa)

    elif operatorSa == SOLLYA_BASE_FUNC_FREE_VARIABLE:

        #print "This is free variable"

        return(eval(sollyaLibFreeVariableName))

    else:

        print "Unexpected"

        return eval('None')

# End pobyso_get_sage_exp_from_sollya_exp_so_sa

def pobyso_get_subfunctions(expressionSo):

    """ Legacy function. See pobyso_get_subfunctions_so_sa. """

    return(pobyso_get_subfunctions_so_sa(expressionSo))

# End pobyso_get_subfunctions.

def pobyso_get_subfunctions_so_sa(expressionSo):

    """

    Get the subfunctions of an expression.

    Return the number of subfunctions and the list of subfunctions addresses.