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

"""

@file pobyso.py

Actual functions to use in Sage

@author S.T.

@date 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.

@note

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 and other

common types (error 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,

    SOLLYA_ABSOLUTE,

    SOLLYA_RELATIVE) = map(int,xrange(46))

sys.stderr.write("SOLLYA_RELATIVE = " + str(SOLLYA_RELATIVE) + "\n")

sys.stderr.write("Superficial pobyso check...\n")

#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():

    """

    Create an "absolute" Sollya object.

    """

    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_interval_sa_sa(lowerBound, upperBound):

    """

    Convert a pair of bounds into an interval (an element of

    a RealIntervalField).

    """

    # Minimal (not bullet-proof) check on bounds.

    if lowerBound > upperBound:

        return None

    # Try to get the maximum precision among the bounds.

    try:

        preclb = parent(lowerBound).precision()

        precub = parent(upperBound).precision()

        prec = max(preclb, precub)

    except AttributeError:

        prec = 53

    # Create the RealIntervalField and the interval (if possible).

    theRIF = RealIntervalField(prec)

    theRR  = RealField(prec)

    # Try convert the lower bound to a RealField element or fail.

    try:

        lowerBoundRF = theRR(lowerBound)

    except TypeError:

        try:

            lowerBoundRF = theRR(str(lowerBound))

        except TypeError:

            return None

    # Try convert the upper bound to a RealField element or fail.

    try:

        upperBoundRF = theRR(upperBound)

    except TypeError:

        try:

            upperBoundRF = theRR(str(upperBound))

        except TypeError:

            return None

    return theRIF(lowerBoundRF, upperBoundRF)

# End pobyso_bounds_to_interval_sa_sa

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_end_elliptic_list_so_so(*args):

    """

    From Sollya argument objects, create a Sollya end elliptic list.

    Elements of the list are "eaten" (should not be cleared individually,

    are cleared when the list is cleared).

    """

    if len(args) == 0:

        ## When called with an empty list, sollya_lib_build_end_elliptic_list,

        #  produces "error".

        return sollya_lib_build_list(None)

    index = 0

    ## One can not append elements to an elliptic list, prepend only is

    #  permitted.

    for argument in reversed(args):

        if index == 0:

            listSo = sollya_lib_build_end_elliptic_list(argument, None)

        else:

            listSo = sollya_lib_prepend(argument, listSo)

        index += 1

    return listSo

# End pobyso_build_end_elliptic_list_so_so

def pobyso_build_function_sub_so_so(exp1So, exp2So):

    return sollya_lib_build_function_sub(exp1So, exp2So)

def pobyso_build_list_of_ints_sa_so(*args):

    """

    Build a Sollya list from Sage integral arguments.

    """

    if len(args) == 0:

        return pobyso_build_list_so_so()

    ## Make a Sage list of integral constants.

    intsList = []

    for intElem in args:

        intsList.append(pobyso_constant_from_int_sa_so(intElem))

    return pobyso_build_list_so_so(*intsList)

def pobyso_build_list_so_so(*args):

    """

    Make a Sollya list out of Sollya objects passed as arguments.

    If one wants to call it with a list argument, should prepend a "*"

    before the list variable name.

    Elements of the list are "eaten" (should not be cleared individually,

    are cleared when the list is cleared).

    """

    if len(args) == 0:

        ## Called with an empty list produced "error".

        return sollya_lib_build_list(None)

    index = 0

    ## Append the Sollya elements one by one.

    for elementSo in args:

        if index == 0:

            listSo = sollya_lib_build_list(elementSo, None)

        else:

            listSo = sollya_lib_append(listSo, elementSo)

        index += 1

    return listSo

# End pobyso_build list_so_so

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_sa_sa(funcSa, degreeSa, intervalSa):

    """

    An chebyshevnorm call with Sage arguments that returns Sage objects.

    To the moment only the polynomial and the delta are returned.

    """

    # Check that funcSa is a function.

    if not \

     sage.symbolic.callable.is_CallableSymbolicExpressionRing(parent(funcSa)):

        return None

    # Check that funcSa is an integer.

    try:

        if degreeSa != int(degreeSa):

            print "degreeSa is not a valid integer."

            return None

    except ValueError:

        print "degreeSa is not a number."

        return None

    # Create the Sollya degree...

    degreeSo = pobyso_constant_from_int_sa_so(degreeSa)

    # ...and check it.

    if pobyso_is_error_so_sa(degreeSo):

        print "Could not correctly convert degreeSa to Sollya."

        return None

    # Check that intervalSa is an interval.

    try:

        intervalSa.upper()

    except AttributeError:

        print "intervalSa is not an interval."

        return None

    # Convert the Sage polynomial into a Sollya polynomial.

    # Convert the Sage function into a Sollya function.

    funcAsStringSa = funcSa._assume_str().replace('_SAGE_VAR_', '')

    funcSo = pobyso_parse_string_sa_so(funcAsStringSa)

    if not pobyso_obj_is_function_so_sa(funcSo):

        sollya_lib_clear_obj(funcSo)

        print "The Sollya object created from the function is not a function."

        return None

    #pobyso_autoprint(funcSo)

    # Convert the Sage interval into a Sollya range.

    rangeSo = pobyso_interval_to_range_sa_so(intervalSa)

    if not pobyso_is_range_so_sa(rangeSo):

        sollya_lib_clear_obj(funcSo)

        sollya_lib_clear_obj(rangeSo)

        print "The Sollya object created from the interval is not a range."

        return None

    #pobyso_autoprint(rangeSo)

    retValSo = sollya_lib_chebyshevform(funcSo,

                                        degreeSo,

                                        rangeSo,

                                        None)

    sollya_lib_clear_obj(funcSo)

    sollya_lib_clear_obj(degreeSo)

    sollya_lib_clear_obj(rangeSo)

    if pobyso_is_error_so_sa(retValSo):

        sollya_lib_clear_obj(retValSo)

        print "Could not compute the Chebyshev form."

        return None

    #pobyso_autoprint(retValSo)

    ## Get the list of Sollya objects returned by sollya_lib_chebyshevform

    retValSa = pobyso_get_list_elements_so_so(retValSo)

    if retValSa[1] != 4:

        print "Invalid number of elements in the Chebyshev form."

        sollya_lib_clear_obj(retValSo)

        return None

    ## Convert all the element of the retValSa[0] array of Sollya objects

    #  into their Sage counterparts.

    polySa = pobyso_float_poly_so_sa(retValSa[0][0])

    if not pobyso_is_poly_sa_sa(polySa):

        print "Conversion of the polynomial of the Chebyshev form failed."

        sollya_lib_clear_obj(retValSo)

        return None

    deltaSa  = pobyso_get_interval_from_range_so_sa(retValSa[0][2])

    if not pobyso_is_interval_sa_sa(deltaSa):

        print "Conversion of the delta interval of the Chebyshev form failed."

        sollya_lib_clear_obj(retValSo)

        return None

    sollya_lib_clear_obj(retValSo)

    return(polySa,deltaSa)

# End pobyso_chebyshevform_sa_sa.

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_full_list_elements_sa_so(objectListSaSo):

    """

    Clear the elements of list created by the

    pobyso_get_list_elements_so_so function.

    objectListSaSo is as follows:

    - objectListSaSo[0]: a list of Sollya objects;

    - objectListSaSo[1]: the number of elements of the previous list;

    - objectListSaSo[2]: an integer that if != 0 states that the list is

                         end-elliptic

    The objects to clear are the elements of the objectListSaSo[0] list.

    """

    for index in xrange(0, objectListSaSo[1]):

        sollya_lib_clear_obj(objectListSaSo[0][index])

# End pobyso_clear_full_list_elements_sa_so

def pobyso_clear_list_elements_sa_so(objectListSaSo):

    """

    Clear the elements of list of references to Sollya objects

    """

    for index in xrange(0, len(objectListSaSo)):

        sollya_lib_clear_obj(objectListSaSo[index])

# End pobyso_clear_list_elements_sa_so

def pobyso_clear_obj(objSo):

    """

    Free a Sollya object's memory.

    Very thin wrapper around sollya_lib_clear_obj().

    """

    sollya_lib_clear_obj(objSo)

# End pobyso_clear_obj.

def pobyso_clear_taylorform_sa_so(taylorFormSaSo):

    """

    This method is wrapper around pobyso_clear_list_elements_sa_so.

    It is a legacy method left here since it may be used in existing code

    where Taylor forms are used as Sage lists obtained by converting

    Sollya Taylor forms (a list made of:

    - a polynomial;

    - a list of intervals enclosing the errors accumulated when computing

      the polynomial coefficients;

    - a bound on the approximation error between the polynomial and the

      function.)

    A Taylor form directly obtained from pobyso_taylorform_so_so is cleared

    by sollya_lib_clear_obj.

    """

    pobyso_clear_list_elements_sa_so(taylorFormSaSo)

# End pobyso_clear_taylorform_sa_so

def pobyso_cmp(rnArgSa, cteSo):

    """

    Deprecated, use pobyso_cmp_sa_so_sa instead.

    """

    print "Deprecated, use pobyso_cmp_sa_so_sa instead."

    return pobyso_cmp_sa_so_sa(rnArgSa, cteSo)

# End  pobyso_cmp

def pobyso_cmp_sa_so_sa(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

    #  through a direct comparison of underlying MPFR numbers.

    return cmp_rn_value(rnArgSa, rnLocal)

# End pobyso_smp_sa_so_sa

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_compute_precision_decay_ratio_function_sa_so():

    """

    Compute the precision decay ratio function for polynomial

    coefficient progressive trucation.

    """

    functionText = """

    proc(deg, a, b, we, wq)

    {

      k = we * (exp(x/a)-1) + wq * (b*x)^2 + (1-we-wq) * x;

      return k/k(d);

    };

    """

    return pobyso_parse_string_sa_so(functionText)

# End  pobyso_compute_precision_decay_ratio_function.

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.

    The sollya_lib_constant() function creates a constant

    with the same precision as the source.

    """

    ## Precision stuff. If one wants to change precisions,

    #  everything takes place in Sage. This only makes

    #  sense if one wants to reduce the precision.

    # TODO: revisit precision stuff with new technique.

    # Check that rnArgSa is a realFiedl element.

    try:

        rnArgSa.ulp()

    except AttributeError:

        return pobyso_error_so()

    # If a different precision is wanted modify it.

    if not precisionSa is None:

        RRR = RealField(precisionSa)

        rnArgSa = RRR(rnArgSa)

    #print rnArgSa, rnArgSa.precision()

    # Sollya constant creation takes place here.

    return sollya_lib_constant(get_rn_value(rnArgSa))

# 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):

    """

    Make a Sollya constant from Sage rational.

    The Sollya constant is an unevaluated expression.

    Hence no precision argument is needed.

    It is better to leave this way since Sollya has its own

    optimized evaluation mecanism that tries very hard to

    return exact values or at least faithful ones.

    """

    ratExprSo = \

        sollya_lib_constant_from_mpq(sgmp_get_rational_value(rationalSa))

    return ratExprSo

# End pobyso_constant_from_mpq_sa_so.

def pobyso_constant_sollya_prec_sa_so(rnArgSa):

    """

    Create a Sollya constant from a Sage RealNumber at the

    current precision in Sollya.

    """

    currentSollyaPrecSa = pobyso_get_prec_so_sa()

    return pobyso_constant_sa_so(rnArgSa, currentSollyaPrecSa)

# End pobyso_constant_sollya_prec_sa_so

def pobyso_end_elliptic_list_so_sa_so(objectsListSo, intCountSa):

    """

    Create a Sollya end elliptic list made of the objectListSo[0] to

     objectsListSo[intCountSa-1] objects.

    """

    return sollya_lib_end_elliptic_list(objectSo, int(intCountSa))

def pobyso_error_so():

    return sollya_lib_error(None)

# End pobyso_error().

def pobyso_evaluate_so_sa(funcSo, argumentSo):

    """

    Evaluates funcSo for arguemntSo through sollya_lib_evaluate() and return

    the result as a Sage object

    """

    evalSo = sollya_lib_evaluate(funcSo, argumentSo)

    if pobyso_is_error_so_sa(evalSo):

        return None

    if pobyso_is_range_so_sa(evalSo):

        retVal = pobyso_range_to_interval_so_sa(evalSo)

    else:

        retVal = pobyso_get_constant_as_rn(evalSo)

    sollya_lib_clear_obj(evalSo)

    return retVal

# End pobyso_evaluate_so_sa.

def pobyso_evaluate_so_so(funcSo, argumentSo):

    """

    Evaluates funcSo for arguemntSo through sollya_lib_evaluate().

    """

    return sollya_lib_evaluate(funcSo, argumentSo)

# End pobyso_evaluate_so_so.

#

def pobyso_diff_so_so(funcSo):

    """

    Very thin wrapper around sollya_lib_diff.

    """

    ## TODO: add a check to make sure funcSo is a functional expression.

    return sollya_lib_diff(funcSo)

def pobyso_dirty_find_zeros_so_so(funcSo, rangeSo):

    """

    Thin wrapper over sollya_lib_dirtyfindzeros()

    """

    return sollya_lib_dirtyfindzeros(funcSo, rangeSo)

# End pobys_dirty_find_zeros

def pobyso_dirty_inf_norm_so_so(funcSo, rangeSo, preSo=None):

    """

    Thin wrapper around sollya_dirtyinfnorm().

    """

    # TODO: manage the precision change.

    return sollya_lib_dirtyinfnorm(funcSo, rangeSo)

# End pobyso_dirty_inf_norm_so_so

def pobyso_find_zeros_so_so(funcSo, rangeSo):

    """

    Thin wrapper over sollya_lib_findzeros()

    """

    return sollya_lib_findzeros(funcSo, rangeSo)

# End pobys_find_zeros

def pobyso_float_list_so_sa(listSo):

    """

    Return a Sollya list of floating-point numbers as a Sage list of

    floating-point numbers.

    TODO: add a test to make sure that each element of the list is a constant.

    """

    listSa   = []

    ## The function returns none if the list is empty or an error has happened.

    retVal = pobyso_get_list_elements_so_so(listSo)

    if retVal is None:

        return listSa

    ## Just in case the interface is changed and an empty list is returned

    #  instead of None.

    elif len(retVal) == 0:

        return listSa

    else:

        ## Remember pobyso_get_list_elements_so_so returns more information

        #  than just the elements of the list (# elements, is_elliptic)

        listSaSo, numElements, isEndElliptic = retVal

    ## Return an empty list.

    if numElements == 0:

        return listSa

    ## Search first for the maximum precision of the elements

    maxPrecSa = 0

    for floatSo in listSaSo:

        #pobyso_autoprint(floatSo)

        curPrecSa =  pobyso_get_prec_of_constant_so_sa(floatSo)

        if curPrecSa > maxPrecSa:

            maxPrecSa = curPrecSa

    ##

    RF = RealField(maxPrecSa)

    ##

    for floatSo in listSaSo:

        listSa.append(pobyso_get_constant_as_rn_with_rf_so_sa(floatSo))

    return listSa

# End pobyso_float_list_so_sa

def pobyso_float_poly_sa_so(polySa, precSa = None):

    """

    Create a Sollya polynomial from a Sage RealField polynomial.

    """

    ## TODO: filter arguments.

    ## Precision. If a precision is given, convert the polynomial

    #  into the right polynomial field. If not convert it straight

    #  to Sollya.

    sollyaPrecChanged = False

    (initialSollyaPrecSo, initialSollyaPrecSa) = pobyso_get_prec_so_so_sa()

    if precSa is None:

        precSa = polySa.parent().base_ring().precision()

    if (precSa > initialSollyaPrecSa):

        assert precSa >= 2, "Precision change <2 requested"

        if precSa <= 2:

            print inspect.stack()[0][3], ": precision change <= 2 requested"

        precSo = pobyso_constant_from_int(precSa)

        pobyso_set_prec_so_so(precSo)

        sollya_lib_clear_obj(precSo)

        sollyaPrecChanged = True

    ## Free variable stuff.

    freeVariableNameChanged = False

    polyFreeVariableNameSa = \

        str(polySa.variables()[0])

    currentFreeVariableNameSa = pobyso_get_free_variable_name_so_sa()

    if polyFreeVariableNameSa != currentFreeVariableNameSa:

        #print "Free variable names do not match.", polyFreeVariableNameSa

        sollya_lib_name_free_variable(polyFreeVariableNameSa)

        freeVariableNameChanged = True

    ## Get exponents and coefficients.

    exponentsSa     = polySa.exponents()

    coefficientsSa  = polySa.coefficients()

    ## Build the polynomial.

    polySo = None

    for coefficientSa, exponentSa in zip(coefficientsSa, exponentsSa):

        #print coefficientSa.n(prec=precSa), exponentSa

        coefficientSo = \

            pobyso_constant_sa_so(coefficientSa)

        #pobyso_autoprint(coefficientSo)

        exponentSo = \

            pobyso_constant_from_int_sa_so(exponentSa)

        #pobyso_autoprint(exponentSo)

        monomialSo = sollya_lib_build_function_pow(

                       sollya_lib_build_function_free_variable(),

                       exponentSo)

        polyTermSo = sollya_lib_build_function_mul(coefficientSo,

                                                       monomialSo)

        if polySo is None:

            polySo = polyTermSo

        else:

            polySo = sollya_lib_build_function_add(polySo, polyTermSo)

    if sollyaPrecChanged:

        pobyso_set_prec_so_so(initialSollyaPrecSo)

    sollya_lib_clear_obj(initialSollyaPrecSo)

    ## Do not set back the free variable name in Sollya to its initial value:

    #  it will change it back, in the Sollya polynomial, to what it was in the

    #  first place.

    return polySo

# End pobyso_float_poly_sa_so

def pobyso_float_poly_so_sa(polySo, realFieldSa=None):

    """

    Convert a Sollya polynomial into a Sage floating-point polynomial.

    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

    """

    if realFieldSa is None:

        expressionPrecSa = pobyso_get_max_prec_of_exp_so_sa(polySo)

        #print "Maximum precision of Sollya polynomial coefficients:", expressionPrecSa

        if expressionPrecSa < 2 or expressionPrecSa > 2147483391:

            print "Maximum degree of expression:", expressionPrecSa

        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)

    #polyCoeffsListSa = polynomialSa.coefficients()

    #for coeff in polyCoeffsListSa:

    #    print coeff.abs().n()

    return polynomialSa

# End pobyso_float_poly_so_sa

def pobyso_free_variable():

    """

    Ultra thin wrapper around the sollya_lib_function_build_free_variable function.

    """

    return sollya_lib_build_function_free_variable()

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: