mathmaker_dev/obj/__init__.py

# -*- coding: utf-8 -*-

# Mathmaker creates automatically maths exercises sheets
# with their answers
# Copyright 2006-2009 Nicolas Hainaux <nico_h@users.sourceforge.net>

# This file is part of Mathmaker.

# Mathmaker is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3 of the License, or
# any later version.

# Mathmaker is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.

# You should have received a copy of the GNU General Public License
# along with Mathmaker; if not, write to the Free Software
# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

import __
import math
import randomly
import is_
import alphabet
import default
import error
import debug



MAX_VALUE = 20

# The following tables come from the fractions' calculations sheets...
# which is a shame : this code must be factorized
FRACTIONS_SUMS_TABLE = [([1, 2], 15),
                        ([1, 3], 15),
                        ([1, 4], 15),
                        ([1, 5], 15),
                        ([1, 6], 15),
                        ([1, 7], 15),
                        ([2, 3], 17),
                        ([2, 5], 10),
                        ([2, 7], 7),
                        ([3, 4], 9),
                        ([3, 5], 7),
                        ([3, 7], 5),
                        ([4, 5], 5),
                        ([4, 7], 3),
                        ([5, 6], 4),
                        ([5, 7], 4),
                        ([6, 7], 3)]

FRACTIONS_SUMS_SCALE_TABLE = [0.02,  #(1, 2)
                              0.02,
                              0.02,
                              0.01,
                              0.005,
                              0.005,  #(1, 7)
                              0.21,  #(2, 3)
                              0.14,  #(2, 5)
                              0.02,  #(2, 7)
                              0.21,  #(3, 4)
                              0.14,  #(3, 5)
                              0.01,  #(3, 7)
                              0.16,  #(4, 5)
                              0.01,  #(4, 7)
                              0.01,  #(5, 6)
                              0.005,  #(5, 7)
                              0.005]  #(6, 7)



# -----------------------------------------------------------------------------
# --------------------------------------------------- PACKAGE:   obj ----------
# -----------------------------------------------------------------------------
##
# @package obj
# @brief Contains obj.Printable, obj.calc.*, obj.geo.*


# -----------------------------------------------------------------------------
# --------------------------------------------- CLASS: obj.Printable ----------
# -----------------------------------------------------------------------------
##
# @class Printable
# @brief All Printable objects : Exponenteds & others (Equations...)
# Any Printable must reimplement the make_string() method
class Printable(object):





    # ----------------- FUNCTION CREATING THE ML STRING OF THE OBJECT ---------
    ##
    #   @brief Creates a string of the given object in the given ML
    #   @param markup The markup dictionary to use
    #   @param options Any options
    #   @return The formated string
    def make_string(self, markup, **options):
        raise error.MethodShouldBeRedefined(self, 'make_string')








# -----------------------------------------------------------------------------
# --------------------------------------- CLASS: obj.NamedExpression ----------
# -----------------------------------------------------------------------------
##
# @class NamedExpression
# @brief These are object of the kind : Name = Exponented
class NamedExpression(Printable):





    # -------------------------------------------------- CONSTRUCTOR ----------
    ##
    #   @brief Constructor
    #   @warning Might raise an UncompatibleType exception.
    #   @param integer_or_letter A string or an integer
    #   @param objct The Exponented that will be at the right hand side
    #   @return One instance of obj.NamedExpression
    def __init__(self, integer_or_letter, objct):
        # just check if the given arguments are right
        if not (is_.a_string(integer_or_letter)                               \
                or is_.an_integer(integer_or_letter)):
        #___
            raise error.UncompatibleType(integer_or_letter,                   \
                                         "integer_or_letter")

        if not (is_.a_calculable(objct) or objct == None):
            raise error.UncompatibleType(objct, "Exponented")

        self.name = integer_or_letter
        self.right_hand_side = objct.deep_copy()





    # ----------------- FUNCTION CREATING THE ML STRING OF THE OBJECT ---------
    ##
    #   @brief Creates a string of the given object in the given ML
    #   @param markup The markup dictionary to use
    #   @param options Any options
    #   @return The formated string
    def make_string(self, markup, **options):
        global expression_begins
        # NamedExpression objects displaying
        if is_.an_integer(self.name):
            i = self.name
            if i < len(alphabet.UPPERCASE):
                final_name = alphabet.UPPERCASE[i]
            else:
                nb_letters = len(alphabet.UPPERCASE)
                final_name = alphabet.UPPERCASE[i -
                                                    nb_letters
                                                    *
                                                    int(i/nb_letters)
                                                ]                             \
                             + markup['opening_subscript']                    \
                             + str(int(i/nb_letters))                         \
                             + markup['closing_subscript']

        elif is_.a_string(self.name):
            final_name = self.name

        expression_begins = True

        return final_name                                                     \
               + markup['equal']                                              \
               + self.right_hand_side.make_string(markup,
                                                  force_expression_begins=True,
                                                  **options)






    # --------- CREATE THE ML STRING OF ITS OWN EXPANSION & REDUCTION ---------
    ##
    #   @brief Create a string of the expression's exp. & red. in the given ML
    #   @param markup The markup dictionary to use
    #   @param options Any options
    #   @return The formated string of the expression's resolution
    def auto_expansion_and_reduction(self, markup, **options):
        global expression_begins
        aux_expr = self.right_hand_side
        result = ""

        #DEBUG
        # print aux_expr.make_string(markup)


        # Complete expansion & reduction of any expression :o)
        while aux_expr != None:
            result += markup['opening_expression'] \
                      + NamedExpression(self.name,
                                        aux_expr).make_string(markup) \
                      + markup['closing_expression'] \
                      + markup['newline'] \
                      + "\n"
            #DEBUG
            #print "\n ++ " + str(aux_expr) + " ++ \n"
            #print "\n ++ " + str(type(aux_expr)) + " ++ \n"
            aux_expr = aux_expr.expand_and_reduce_next_step()

        return result





# -----------------------------------------------------------------------------
# ---------------------------------------------- CLASS: obj.Equality ----------
# -----------------------------------------------------------------------------
##
# @class Equality
# @brief These are object of the kind : Exponented = Exponented [= ...]
class Equality(Printable):





    # -------------------------------------------------- CONSTRUCTOR ----------
    ##
    #   @brief Constructor
    #   @warning Might raise an UncompatibleType exception.
    #   @param objcts is a [Exponented] of 2 elements at least
    #   @option equal_signs Contains a list of equal/not equal signs. Must be
    #   @option             long as len(objcts) - 1. The signs are "=" or "neq"
    #   @return One instance of obj.Equality
    def __init__(self, objcts, **options):
        # just check if the given arguments are right
        if not (isinstance(objcts, list)):
            raise error.UncompatibleType(objcts,                   \
                            "should be a LIST (of two Exponenteds at least)")

        if not len(objcts) >= 2:
            raise error.UncompatibleType(objcts,                       \
                            "should be a list of TWO Exponenteds AT LEAST")

        for i in xrange(len(objcts)):
            if not isinstance(objcts[i], calc.Exponented):
                raise error.UncompatibleType(objcts[i],                    \
                                            "should be a Exponented")

        if 'equal_signs' in options:
            if not type(options['equal_signs']) == list:
                raise error.UncompatibleType(options['equal_signs'],                    \
                                            "should be a list")
            if not len(options['equal_signs']) == len(objcts) - 1:
                raise error.UncompatibleType(options['equal_signs'],                    \
                                            "should contain " \
                                            + str(len(objcts) - 1) \
                                            + " elements.")

            for i in xrange(len(options['equal_signs'])):
                if not (options['equal_signs'][i] == '=' \
                        or options['equal_signs'][i] == 'neq'):
                #___
                    raise error.UncompatibleType(options['equal_signs'][i],                    \
                                                    " should be '=' or 'neq'")


        self.elements = []
        self.equal_signs = []

        for i in xrange(len(objcts)):
            self.elements.append(objcts[i].deep_copy())

            if 'equal_signs' in options:

                if i < len(options['equal_signs']):
                    sign_to_add = None

                    if options['equal_signs'][i] == '=':
                        sign_to_add = 'equal'
                    else:
                        sign_to_add = 'not_equal'

                    self.equal_signs.append(sign_to_add)

            else:
                self.equal_signs.append('equal')





    # ----------------- FUNCTION CREATING THE ML STRING OF THE OBJECT ---------
    ##
    #   @brief Creates a string of the given object in the given ML
    #   @param markup The markup dictionary to use
    #   @param options Any options
    #   @return The formated string
    def make_string(self, markup, **options):
        global expression_begins
        # Equality objects displaying

        expression_begins = True

        result = ''

        if 'force_expression_markers' in options\
            and options['force_expression_markers'] == 'yes':
        #___
            result += markup['opening_expression']


        result += self.elements[0].make_string(markup,
                                              force_expression_begins=True,
                                              **options)

        for i in xrange(len(self.elements) - 1):
            result += markup[self.equal_signs[i]] \
                      + self.elements[i+1].make_string(markup,
                                                 force_expression_begins=True,
                                                 **options)

        if 'force_expression_markers' in options\
            and options['force_expression_markers'] == 'yes':
        #___
            result += markup['closing_expression']

        return result





    # --------------------------------------------------- INDEXATION ----------
    ##
    #   @brief It is possible to index an Equality
    def __getitem__(self, i):
        return self.elements[i]


    def __setitem__(self, i, data):
        if not isinstance(data, Exponented):
            raise error.UncompatibleType(data, "should be a Exponented")

        self.elements[i] = data.deep_copy()





    # --------------------------------------------- EQUALITY'S LENGTH ----------
    ##
    #   @brief Returns the number of elements of the Equality
    def __len__(self):
        return len(self.elements)





# -----------------------------------------------------------------------------
# ---------------------------------------------- CLASS: obj.Equation ----------
# -----------------------------------------------------------------------------
##
# @class Equation
# @brief One degree one variable. Sum=Sum. Name, number, left/right hand side.
class Equation(Printable):





    # -------------------------------------------------- CONSTRUCTOR ----------
    ##
    #   @brief Constructor
    #   @warning Might raise an UncompatibleType exception.
    #   @param arg Equation|(Exponented, Exponented)|(__.RANDOMLY, ...)
    #   @return One instance of obj.Equation
    def __init__(self, arg, **options):
        self.name = default.EQUATION_NAME
        self.number = ''
        self.left_hand_side = None
        self.right_hand_side = None
        self.variable_letter = default.MONOMIAL_LETTER

        # First determine name and number of the equation
        if 'name' in options and is_.a_string(options['name']):
            self.name = options['name']

        if 'number' in options and is_.an_integer(options['number']):
            self.number = options['number']

        # Then the letter
        if 'variable_letter_name' in options \
           and is_.a_string(options['variable_letter_name']):
        #___
            self.variable_letter = options['variable_letter_name'][0]

        # Then determine its left & right hand sides
        if type(arg) == tuple and len(arg) == 2:

            # 1st CASE
            # Given objects
            if is_.a_calculable(arg[0]) and is_.a_calculable(arg[1]):
                if isinstance(arg[0], calc.Sum):
                    # TO FIX ?
                    # this could be secured by checking the given Sum
                    # is not containing only one term which would be also
                    # a Sum
                    self.left_hand_side = arg[0]
                else:
                    self.left_hand_side = calc.Sum(arg[0])

                if isinstance(arg[1], calc.Sum):
                    # TO FIX ?
                    # this could be secured by checking the given Sum
                    # is not containing only one term which would be also
                    # a Sum
                    self.right_hand_side = arg[1]
                else:
                    self.right_hand_side = calc.Sum(arg[1])

            # 2d CASE
            # RANDOMLY !
            elif arg[0] == __.RANDOMLY:
                if arg[1] == 'basic_addition':
                    self.left_hand_side = calc.Polynomial([
                                          calc.Monomial(('+',
                                                         1,
                                                         1)),
                                          calc.Monomial((randomly.sign(),
                                                         randomly.integer(1,
                                                                    MAX_VALUE),
                                                         0))
                                                          ])

                    self.right_hand_side = calc.Sum(calc.Item((randomly.sign(),
                                                      randomly.integer(1,
                                                                    MAX_VALUE)
                                                     ))
                                                   )


                    self.left_hand_side.term[0].set_letter(
                                                          self.variable_letter)


                elif arg[1] == 'basic_addition_r':
                    self.right_hand_side = calc.Polynomial([
                                          calc.Monomial(('+',
                                                         1,
                                                         1)),
                                          calc.Monomial((randomly.sign(),
                                                         randomly.integer(1,
                                                                    MAX_VALUE),
                                                         0))
                                                          ])

                    self.left_hand_side = calc.Sum(calc.Item((randomly.sign(),
                                                      randomly.integer(1,
                                                                    MAX_VALUE)
                                                     ))
                                                  )


                    self.right_hand_side.term[0].set_letter(
                                                          self.variable_letter)
                elif arg[1] == 'any_basic_addition':
                    cst_list = list()
                    m1 = calc.Monomial((randomly.sign(plus_signs_ratio=0.8),
                                        1,
                                        1))

                    m1.set_letter(self.variable_letter)

                    m2 = calc.Monomial((randomly.sign(),
                                        randomly.integer(1,MAX_VALUE),
                                        0))

                    m3 = calc.Monomial((randomly.sign(),
                                        randomly.integer(1,MAX_VALUE),
                                        0))

                    cst_list.append(m2)
                    cst_list.append(m3)

                    drawn_to_be_with_x = randomly.pop(cst_list)

                    polyn_list = list()
                    polyn_list.append(m1)
                    polyn_list.append(drawn_to_be_with_x)

                    polyn = calc.Polynomial([randomly.pop(polyn_list),
                                             randomly.pop(polyn_list)])
                    sides = list()
                    sides.append(polyn)
                    sides.append(calc.Sum(randomly.pop(cst_list)))

                    self.left_hand_side = randomly.pop(sides)
                    self.right_hand_side = randomly.pop(sides)

                elif arg[1] == 'basic_multiplication':
                    self.left_hand_side = calc.Sum(
                                          calc.Monomial(( \
                                          randomly.sign(plus_signs_ratio=0.75),
                                          randomly.integer(2, MAX_VALUE),
                                          1))
                                                  )


                    self.right_hand_side = calc.Sum(
                                          calc.Item(( \
                                          randomly.sign(plus_signs_ratio=0.75),
                                          randomly.integer(1, MAX_VALUE),
                                          1))
                                                   )


                    self.left_hand_side.term[0].\
                                        set_letter(self.variable_letter)

                elif arg[1] == 'basic_multiplication_r':
                    self.right_hand_side = calc.Sum(
                                          calc.Monomial(( \
                                          randomly.sign(plus_signs_ratio=0.75),
                                          randomly.integer(2, MAX_VALUE),
                                          1))
                                                   )


                    self.left_hand_side = calc.Sum(
                                          calc.Item(( \
                                          randomly.sign(plus_signs_ratio=0.75),
                                          randomly.integer(1, MAX_VALUE),
                                          1))
                                                  )


                    self.right_hand_side.term[0].\
                                        set_letter(self.variable_letter)

                elif arg[1] == 'any_basic_multiplication':
                    m1 = calc.Monomial((randomly.sign(plus_signs_ratio=0.75),
                                        randomly.integer(2, MAX_VALUE),
                                        1))
                    m1.set_letter(self.variable_letter)

                    m2 = calc.Item((randomly.sign(plus_signs_ratio=0.75),
                                    randomly.integer(1, MAX_VALUE),
                                    1))

                    items_list = list()
                    items_list.append(calc.Sum(m1))
                    items_list.append(calc.Sum(m2))

                    self.left_hand_side = randomly.pop(items_list)
                    self.right_hand_side = randomly.pop(items_list)

                elif arg[1] == 'any_basic': # code duplication... done quickly
                    if randomly.heads_or_tails():
                        m1 = calc.Monomial((randomly.sign(plus_signs_ratio= \
                                                                         0.75),
                                            randomly.integer(2, MAX_VALUE),
                                            1))
                        m1.set_letter(self.variable_letter)

                        m2 = calc.Item((randomly.sign(plus_signs_ratio=0.75),
                                        randomly.integer(1, MAX_VALUE),
                                        1))

                        items_list = list()
                        items_list.append(calc.Sum(m1))
                        items_list.append(calc.Sum(m2))

                        self.left_hand_side = randomly.pop(items_list)
                        self.right_hand_side = randomly.pop(items_list)
                    else:
                        cst_list = list()
                        m1 = calc.Monomial((randomly.sign(plus_signs_ratio= \
                                                                          0.8),
                                            1,
                                            1))
                        m1.set_letter(self.variable_letter)

                        m2 = calc.Monomial((randomly.sign(),
                                            randomly.integer(1,MAX_VALUE),
                                            0))
                        m3 = calc.Monomial((randomly.sign(),
                                            randomly.integer(1,MAX_VALUE),
                                            0))

                        cst_list.append(m2)
                        cst_list.append(m3)

                        drawn_to_be_with_x = randomly.pop(cst_list)

                        polyn_list = list()
                        polyn_list.append(m1)
                        polyn_list.append(drawn_to_be_with_x)

                        polyn = calc.Polynomial([randomly.pop(polyn_list),
                                                 randomly.pop(polyn_list)])
                        sides = list()
                        sides.append(polyn)
                        sides.append(calc.Sum(randomly.pop(cst_list)))

                        self.left_hand_side = randomly.pop(sides)
                        self.right_hand_side = randomly.pop(sides)

                elif arg[1] == 'classic' \
                     or arg[1] == 'classic_r' \
                     or arg[1] == 'classic_x_twice' \
                     or arg[1] == 'any_classic':
                #___
                    # Let's build
                    # classic : ax + b = d | b + ax = d
                    # classic_r : d = ax + b | d = b + ax
                    # classic_x_twice : ax + b = cx + d | ax + b = cx |
                    #                   cx = ax + b | b + ax = cx + d etc.
                    box = list()
                    ax = calc.Monomial((randomly.sign(plus_signs_ratio=0.65),
                                        randomly.integer(1,MAX_VALUE),
                                        1))
                    ax.set_letter(self.variable_letter)

                    b = calc.Monomial((randomly.sign(),
                                        randomly.integer(1,MAX_VALUE),
                                        0))
                    cx = calc.Monomial((randomly.sign(plus_signs_ratio=0.65),
                                        randomly.integer(1,MAX_VALUE),
                                        1))
                    cx.set_letter(self.variable_letter)

                    d = calc.Monomial((randomly.sign(),
                                        randomly.integer(1,MAX_VALUE),
                                        0))

                    box.append(ax)
                    box.append(b)

                    polyn1 = calc.Polynomial([randomly.pop(box),
                                             randomly.pop(box)])

                    if arg[1] == 'classic' or arg[1] == 'classic_r':
                        polyn2 = calc.Polynomial([d])
                    elif arg[1] == 'classic_x_twice':
                        if randomly.decimal_0_1() > 0.3:
                            box = list()
                            box.append(cx)
                            box.append(d)
                            polyn2 = calc.Polynomial([randomly.pop(box),
                                                      randomly.pop(box)])
                        else:
                            polyn2 = calc.Polynomial([cx])

                    elif arg[1] == 'any_classic':
                        box = list()
                        random_nb = randomly.decimal_0_1()
                        if random_nb < 0.4:
                            box.append(cx)
                            box.append(d)
                            polyn2 = calc.Polynomial([randomly.pop(box),
                                                      randomly.pop(box)])
                        elif random_nb < 0.7:
                            polyn2 = calc.Polynomial([d])

                        else:
                            polyn2 = calc.Polynomial([cx])

                    if arg[1] == 'classic':
                        self.left_hand_side = polyn1
                        self.right_hand_side = polyn2
                    elif arg[1] == 'classic_r':
                        self.left_hand_side = polyn2
                        self.right_hand_side = polyn1
                    elif arg[1] == 'classic_x_twice' \
                         or arg[1] == 'any_classic':
                        box = list()
                        box.append(polyn1)
                        box.append(polyn2)
                        self.left_hand_side = randomly.pop(box)
                        self.right_hand_side = randomly.pop(box)

                elif arg[1] == 'classic_with_fractions':
                    # the following code is copied from Calculation.py
                    # -> must be factorized
                    randomly_position = randomly.integer(0,
                                                    16,
                                                    weighted_table=\
                                                    FRACTIONS_SUMS_SCALE_TABLE)

                    chosen_seed_and_generator = FRACTIONS_SUMS_TABLE[\
                                                             randomly_position]


                    seed = randomly.integer(2, chosen_seed_and_generator[1])

                    # The following test is only intended to avoid having "high"
                    # results too often. We just check if the common denominator
                    # will be higher than 75 (arbitrary) and if yes, we
                    # redetermine
                    # it once. We don't do it twice since we don't want to
                    # totally
                    # forbid high denominators.
                    if seed * chosen_seed_and_generator[0][0] \
                            * chosen_seed_and_generator[0][1] >= 75:
                    #___
                        seed = randomly.integer(2, chosen_seed_and_generator[1])

                    lil_box = [0, 1]
                    gen1 = chosen_seed_and_generator[0][lil_box.pop()]
                    gen2 = chosen_seed_and_generator[0][lil_box.pop()]

                    den1 = calc.Item(gen1*seed)
                    den2 = calc.Item(gen2*seed)

                    temp1 = randomly.integer(1, 20)
                    temp2 = randomly.integer(1, 20)

                    num1 = calc.Item(temp1 / calc.lib.gcd(temp1, gen1*seed))
                    num2 = calc.Item(temp2 / calc.lib.gcd(temp2, gen2*seed))

                    f1 = calc.Fraction((randomly.sign(plus_signs_ratio=0.7),
                                  num1,
                                  den1))
                    f2 = calc.Fraction((randomly.sign(plus_signs_ratio=0.7),
                                  num2,
                                  den2))

                    # END OF COPIED CODE ---------------------------------------

                    box = list()
                    ax = calc.Monomial((calc.Fraction((randomly.sign(\
                                                          plus_signs_ratio=0.7),
                                                  calc.Item(randomly.integer(1,
                                                                        10)),
                                                  calc.Item(randomly.integer(2,
                                                                        10))
                                                  )).simplified(),
                                        1))
                    ax.set_letter(self.variable_letter)

                    b = calc.Monomial((f1.simplified(), 0))
                    d = calc.Monomial((f2.simplified(), 0))

                    box.append(ax)
                    box.append(b)

                    self.left_hand_side = calc.Polynomial([randomly.pop(box),
                                                           randomly.pop(box)])

                    self.right_hand_side = calc.Sum([d])


                elif arg[1] == 'any_simple_expandable' \
                    or arg[1] == 'any_double_expandable':
                #___
                    # SIMPLE :
                    # a monom0_polyn1 or a ±(...) on one side
                    # + one Monomial with the monom0_polyn1
                    # and one or two Monomials on the other side
                    # DOUBLE :
                    # The same plus another expandable.

                    # Creation of the expandables, to begin with...
                    if randomly.decimal_0_1() <= 0.8:
                        aux_expd_1 = calc.Expandable((__.RANDOMLY,
                                                      'monom0_polyn1'),
                                                      max_coeff=9)
                        expd_kind = 'monom0_polyn1'

                    else:
                        sign = randomly.sign()
                        aux_expd_1 = calc.Expandable(( \
                                            calc.Monomial((sign,
                                                           1,
                                                           0)),
                                            calc.Polynomial((__.RANDOMLY,
                                                             9,
                                                             1,
                                                             2))
                                                ))
                        if sign == '+':
                            expd_kind = '+(...)'
                        else:
                            expd_kind = 'monom0_polyn1'

                    # Now we fill the boxes to draw from
                    box_1 = []
                    box_2 = []

                    additional_Monomial = calc.Monomial((__.RANDOMLY,
                                                         9,
                                                         1))
                    additional_Monomial2 = calc.Monomial((__.RANDOMLY,
                                                          9,
                                                          1))

                    if additional_Monomial.degree == 0:
                        additional_Monomial2.set_degree(1)

                    box_1.append(aux_expd_1)

                    if expd_kind == '+(...)' or randomly.decimal_0_1() <= 0.5:
                        box_1.append(additional_Monomial)

                    box_2.append(calc.Monomial((__.RANDOMLY, 9, 1)))

                    if randomly.decimal_0_1() <= 0.25:
                    #___
                        box_2.append(additional_Monomial2)

                    if arg[1] == 'any_double_expandable':
                        if randomly.decimal_0_1() <= 0.8:
                            aux_expd_2 = calc.Expandable((__.RANDOMLY,
                                                          'monom0_polyn1'),
                                                          max_coeff=9)

                        else:
                            sign = randomly.sign()
                            aux_expd_2 = calc.Expandable(( \
                                                calc.Monomial((sign,
                                                               1,
                                                               0)),
                                                calc.Polynomial((__.RANDOMLY,
                                                                 9,
                                                                 1,
                                                                 2))
                                                    ))

                        if randomly.decimal_0_1() <= 0.5:
                            box_1.append(aux_expd_2)
                        else:
                            box_2.append(aux_expd_2)

                    boxes = [box_1, box_2]
                    box_left = randomly.pop(boxes)
                    box_right = randomly.pop(boxes)

                    left_list = list()
                    right_list = list()

                    for i in xrange(len(box_left)):
                        left_list.append(randomly.pop(box_left))

                    for i in xrange(len(box_right)):
                        right_list.append(randomly.pop(box_right))

                    self.left_hand_side = calc.Sum(left_list)
                    self.right_hand_side = calc.Sum(right_list)



            # All other unforeseen cases : an exception is raised.
            else:
                raise error.UncompatibleType(arg,
                                             "(Exponented, Exponented)|" \
                                             + "(__.RANDOMLY, <option>)")

        # Another Equation to copy
        elif isinstance(arg, Equation):
            self.name = arg.name
            self.number = arg.number
            self.left_hand_side = arg.left_hand_side.deep_copy()
            self.right_hand_side = arg.right_hand_side.deep_copy()
            self.variable_letter = arg.variable_letter

        else:
            raise error.UncompatibleType(arg, "Equation|tuple")




    # ------------------------------------------------------- SETTER ----------
    ##
    #   @brief Setter for hand sides
    #   @warning Might raise an UncompatibleType exception.
    #   @return Nothing, just sets the given argument to the left hand side,
    #           turned into a Sum if necessary
    def set_hand_side(self, left_or_right, arg):

        if not (left_or_right == "left" or left_or_right == "right"):
            raise error.UncompatibleType(left_or_right,
                                         '"left" or "right"')

        if is_.a_calculable(arg):
            if isinstance(arg, calc.Sum):
                # TO FIX ?
                # this could be secured by checking the given Sum
                # is not containing only one term which would be also
                # a Sum
                if left_or_right == "left":
                    self.left_hand_side = arg
                else:
                    self.right_hand_side = arg
            else:
                if left_or_right == "left":
                    self.left_hand_side = calc.Sum(arg)
                else:
                    self.right_hand_side = calc.Sum(arg)

        else:
            raise error.UncompatibleType(arg, "Equation|tuple")





    # -------------------------------------------------- RAW DISPLAY ----------
    ##
    #   @brief Raw display of the Equation (debugging method)
    #   @return A string containing "type : sign coeff × X ^ degree"
    def __str__(self):
        return "\nEquation : " + str(self.name) \
               + " " + str(self.number) \
               + "\n Left hand side : " + str(self.left_hand_side) \
               + "\n Right hand side : " + str(self.right_hand_side) \
               + "\n Variable : " + str(self.variable_letter)





    # ---------------------------- ONE STEP RESOLUTION OF AN EQUATION ---------
    ##
    #   @brief Creates the next Equation object in the resolution
    #   @todo Expandables (which have to get checked first, btw) !
    #   @todo check the case -x = -7 where the - belongs to the Item's value
    #   @return An Equation
    def solve_next_step(self, **options):
        new_eq = Equation(self)
        #DEBUG
        debug.write("\nEntering [solve_next_step] " \
                               + "with Equation :\n" \
                               + str(new_eq) + "\n",
                               case=debug.solve_next_step)

        # CASE 0 : preparing the Equation : getting recursively rid of
        #          imbricated Sums
        if isinstance(new_eq.left_hand_side.term[0], calc.Sum) \
           and len(new_eq.left_hand_side) == 1:
        #___
            #DEBUG
            debug.write("\n[solve_next_step] CASE-0s-left\n",
                        case=debug.solve_next_step)
            new_eq.left_hand_side = new_eq.left_hand_side.term[0]
            return new_eq.solve_next_step(**options)

        elif isinstance(new_eq.right_hand_side.term[0], calc.Sum) \
           and len(new_eq.right_hand_side) == 1:
        #___
            #DEBUG
            debug.write("\n[solve_next_step] CASE-0s-right\n",
                        case=debug.solve_next_step)
            new_eq.right_hand_side = new_eq.right_hand_side.term[0]
            return new_eq.solve_next_step(**options)

        if isinstance(new_eq.left_hand_side.term[0], calc.Product) \
           and len(new_eq.left_hand_side) == 1 \
           and len(new_eq.left_hand_side.term[0]) == 1:
        #___
            #DEBUG
            debug.write("\n[solve_next_step] CASE-0p-left\n",
                        case=debug.solve_next_step)
            new_eq.left_hand_side = \
                            calc.Sum(new_eq.left_hand_side.term[0].factor[0])
            return new_eq.solve_next_step(**options)

        elif isinstance(new_eq.right_hand_side.term[0], calc.Product) \
           and len(new_eq.right_hand_side) == 1 \
           and len(new_eq.right_hand_side.term[0]) == 1:
        #___
            #DEBUG
            debug.write("\n[solve_next_step] CASE-0p-right\n",
                        case=debug.solve_next_step)
            new_eq.right_hand_side = \
                            calc.Sum(new_eq.right_hand_side.term[0].factor[0])
            return new_eq.solve_next_step(**options)

        next_left_X = new_eq.left_hand_side.expand_and_reduce_next_step()
        next_right_X = new_eq.right_hand_side.expand_and_reduce_next_step()
        #next_left_C = new_eq.left_hand_side.calculate_next_step()
        #next_right_C = new_eq.right_hand_side.calculate_next_step()

        if debug.ENABLED and debug.solve_next_step:
            debug.write("\n[solve_next_step] " \
                        + "'decimal_result' is in options : " \
                        + str('decimal_result' in options) \
                        + " len(new_eq.left_hand_side) == " \
                        + str(len(new_eq.left_hand_side)) \
                        + "\nnext_left_X is : " \
                        + str(next_left_X) \
                        + "\nnew_eq.left_hand_side.term[0].is_literal() : " \
                        + str(new_eq.left_hand_side.term[0].is_literal()) \
                        + " len(new_eq.right_hand_side) == " \
                        + str(len(new_eq.right_hand_side)) \
                        + "\nisinstance(new_eq.right_hand_side.term[0], " \
                        + "calc.Fraction)" \
                        + str(isinstance(new_eq.right_hand_side.term[0],
                                         calc.Fraction)) \
                        + "\n",
                        case=debug.solve_next_step)

        if 'decimal_result' in options \
             and len(new_eq.left_hand_side)  == 1 \
             and next_left_X == None \
             and not new_eq.left_hand_side.term[0].is_numeric() \
             and len(new_eq.right_hand_side) == 1 \
             and (isinstance(new_eq.right_hand_side.term[0], calc.Fraction) \
               or isinstance(new_eq.right_hand_side.term[0], calc.SquareRoot)):
        #___
            #DEBUG
            debug.write("\n[solve_next_step] Decimal Result CASE\n",
                                   case=debug.solve_next_step)
            new_eq.set_hand_side("right",
                                 new_eq.\
                                    right_hand_side.\
                                    expand_and_reduce_next_step(**options))

        # 1st CASE
        # Expand & reduce each side of the Equation, whenever possible
        elif (next_left_X != None) or (next_right_X != None):
        #___
            #DEBUG
            debug.write("\n[solve_next_step] 1st CASE\n",
                                   case=debug.solve_next_step)
            if next_left_X != None:
            #___
                new_eq.set_hand_side("left", next_left_X)

            if next_right_X != None:
            #___
                new_eq.set_hand_side("right", next_right_X)


        # 2d CASE
        # Irreducible SUMS, like 3 + x = 5 or x - 2 = 3x + 7
        # It seems useless to test if one side is reducible, if it was,
        # then it would have been treated in the first case.
        # After that case is treated, every literal term will be moved
        # to the left, and every numeric term moved to the right.
        elif (len(new_eq.left_hand_side) >= 2) \
              or (len(new_eq.right_hand_side) >= 2) \
              or (len(new_eq.right_hand_side) == 1 \
                  and not new_eq.right_hand_side.term[0].is_numeric()):
        #___
            #DEBUG
            debug.write("\n[solve_next_step] 2d CASE\n",
                                   case=debug.solve_next_step)
            # All the literal objects will be moved to the left,
            # all numeric will be moved to the right
            #DEBUG
            debug.write("\néquation en cours : " \
                                   + str(self) + "\n",
                                   case=debug.solve_next_step)

            left_collected_terms = new_eq.left_hand_side.get_numeric_terms()
            right_collected_terms = new_eq.right_hand_side.get_literal_terms()

            #DEBUG
            if debug.ENABLED and debug.solve_next_step:
                debug.write("\nleft content : " \
                                   + str(self.left_hand_side),
                                   case=debug.solve_next_step)
                debug.write("\nright content : " \
                                   + str(self.right_hand_side),
                                   case=debug.solve_next_step)

                lstring = "\nleft collected terms : "

                for t in left_collected_terms:
                    lstring += str(t)

                debug.write(lstring,
                            case=debug.solve_next_step)

                rstring = "\nright collected terms : "

                for t in right_collected_terms:
                    rstring += str(t)

                debug.write(rstring + "\n",
                            case=debug.solve_next_step)

            # Special case of equations like 5 = x - 9
            # which should become x = 5 + 9 at the next line, instead of
            # -x = -5 - 9 (not suited for Pythagorean Equations)
            if new_eq.left_hand_side.is_numeric() \
               and not new_eq.right_hand_side.is_numeric() \
               and len(new_eq.right_hand_side) == 2 \
               and len(right_collected_terms) == 1:
            #___
                # DEBUG
                debug.write("\nEntered in the Special Case [part of 2d Case]",
                                   case=debug.solve_next_step)
                debug.write("\nisinstance(right_collected_terms[0], " \
                            + "calc.Product) is " \
                            + str(isinstance(right_collected_terms[0], \
                                             calc.Product)) \
                            + "\nlen(right_collected_terms[0]) == 2 is " \
                            + str(len(right_collected_terms[0]) == 2) \
                            + "\nright_collected_terms[0][0] is " \
                            #+ str(right_collected_terms[0][0]) \
                            + "\nlen(right_collected_terms[0]) == 1 is " \
                            + str(len(right_collected_terms[0]) == 1) \
                            + "\nisinstance(right_collected_terms[0], " \
                            + "calc.Item) is " \
                            + str(isinstance(right_collected_terms[0], \
                                             calc.Item)),
                            case=debug.solve_next_step)

                if (isinstance(right_collected_terms[0], calc.Product) \
                    and len(right_collected_terms[0]) == 2 \
                    and right_collected_terms[0][0].is_positive()) \
                   or (isinstance(right_collected_terms[0], calc.Product) \
                    and len(right_collected_terms[0]) == 1) \
                   or (isinstance(right_collected_terms[0], calc.Item) \
                       and right_collected_terms[0].is_positive()):
                #___
                    # DEBUG
                    debug.write("\nSpecial Case [part 2]",
                                   case=debug.solve_next_step)

                    return Equation((new_eq.right_hand_side,
                                     new_eq.left_hand_side)).solve_next_step()


            # Special Case 2 :
            # of Equations like 9 = 3x which should become x = 9/3
            # and not -3x = -9
            if new_eq.left_hand_side.is_numeric() \
               and not new_eq.right_hand_side.is_numeric() \
               and len(new_eq.right_hand_side) == 1 \
               and isinstance(right_collected_terms[0], calc.Product):
            #___
                # DEBUG
                debug.write("\nSpecial Case [part 3]",
                               case=debug.solve_next_step)

                return Equation((new_eq.right_hand_side,
                                 new_eq.left_hand_side)).solve_next_step()


            #DEBUG
            #debug.write("\nleft_collected_terms : ",
                       # case=debug.solve_next_step)

            for term in left_collected_terms:
                #DEBUG
                #debug.write("\n" + str(term) + "\n",
                #            case=debug.solve_next_step)
                new_eq.left_hand_side.remove(term)
                term.set_sign(calc.lib.sign_of_product(['-', term.sign]))
                new_eq.set_hand_side("right",
                                     new_eq.right_hand_side.plus(term)
                                     )
                #DEBUG
                debug.write("\nNow, right_hand_side looks like : " \
                            + str(new_eq.right_hand_side) + "\n",
                            case=debug.solve_next_step)

            #DEBUG
            #debug.write("\nright_collected_terms : \n",
            #            case=debug.solve_next_step)

            for term in right_collected_terms:
                #DEBUG
                #debug.write("\n" + str(term) + "\n",
                #                       case=debug.solve_next_step)
                new_eq.right_hand_side.remove(term)
                #term.set_sign(calc.lib.sign_of_product(['-', term.sign]))
                term = term.times(calc.Item(-1)).reduce_()
                new_eq.set_hand_side("left", new_eq.left_hand_side.plus(term))

            new_eq.left_hand_side.reduce_()
            new_eq.right_hand_side.reduce_()
            #DEBUG
            #debug.write("\nafter reduction, "\
            #                       + "right_hand_side looks like : " \
            #                       + str(new_eq.right_hand_side) + "\n",
            #                       case=debug.solve_next_step)



        # 3rd CASE
        # Weird cases like 0 = 1 or 2 = 2
        elif (new_eq.left_hand_side.term[0].is_numeric() \
             and (new_eq.right_hand_side.term[0].is_numeric())
             ):
        #___
            #DEBUG
            debug.write("\n[solve_next_step] 3rd CASE\n",
                                   case=debug.solve_next_step)
            if new_eq.left_hand_side.term[0].value == \
                new_eq.right_hand_side.term[0].value \
               and new_eq.left_hand_side.get_sign() == \
                    new_eq.right_hand_side.get_sign():
            #___
                return _( \
            "Any value of %(variable_name)s is solution of the equation.") \
            % {'variable_name':new_eq.variable_letter}

            else:
                return _("This equation has no solution.")




        # 4th CASE
        # Irreducible PRODUCTS ax = b or -x = b or x = b,
        # where a and b are Exponenteds.
        # The Product in the left side can't be numeric, or it would
        # have been already treated before
        elif isinstance(new_eq.left_hand_side.term[0], calc.Product):
        #___
            #DEBUG
            debug.write("\n[solve_next_step] 4th CASE\n",
                                   case=debug.solve_next_step)

            # Let's replace the possibly remaining Monomial of degree 0
            # at the right by an equivalent Item or Fraction
            if isinstance(new_eq.right_hand_side.term[0], calc.Monomial):
                if isinstance(new_eq.right_hand_side.term[0].factor[0],
                              calc.Item):
                #___
                    new_eq.right_hand_side.set_term(0,
                                calc.Item(new_eq.right_hand_side.term[0])
                                                    )
                elif isinstance(new_eq.right_hand_side.term[0].factor[0],
                                calc.Fraction):
                #___
                    new_eq.right_hand_side.set_term(0,
                                calc.Fraction(new_eq.right_hand_side.term[0])
                                                    )



            # Let's get the numeric Exponented to remove from the left :
            coefficient = new_eq.left_hand_side.term[0].factor[0]

            if coefficient.is_equivalent_to_a_single_1():
                new_eq.set_hand_side("left",
                                     calc.Item(new_eq.left_hand_side.term[0]\
                                                                    .factor[1]))
                return new_eq.solve_next_step(**options)

            elif coefficient.is_equivalent_to_a_single_minus_1():
                new_eq.left_hand_side.term[0].set_opposite_sign()
                new_eq.right_hand_side.term[0].set_opposite_sign()

            elif isinstance(coefficient, calc.Item)\
                 and isinstance(new_eq.right_hand_side.term[0], calc.Item):
            #___
                new_eq.left_hand_side.term[0].set_factor(0, calc.Item(1))
                new_eq.set_hand_side("right",
                                calc.Fraction(('+',
                                              new_eq.right_hand_side.term[0],
                                              calc.Item(coefficient)
                                              ))
                                                )
                new_eq.right_hand_side.term[0].set_down_numerator_s_minus_sign()

            else:
                new_eq.left_hand_side.term[0].set_factor(0, calc.Item(1))
                new_eq.right_hand_side.set_term(0,
                                calc.Quotient(('+',
                                              new_eq.right_hand_side.term[0],
                                              coefficient
                                              ),
                                              use_divide_symbol = 'yes')
                                                )

        # 5th CASE
        # Literal Items -x = b (or -x² = b) or x = b, or x² = b
        # where a and b are (reduced/simplified) Exponenteds.
        # The Item at the left can't be numeric, the case should have
        # been treated before
        elif isinstance(new_eq.left_hand_side.term[0], calc.Item) \
             and new_eq.left_hand_side.term[0].is_literal():
        #___
            if new_eq.left_hand_side.term[0].get_sign() == '-':
                new_eq.left_hand_side.term[0].set_opposite_sign()
                new_eq.right_hand_side.term[0].set_opposite_sign()
            else:
                # CASES x² = b
                if new_eq.left_hand_side.term[0].exponent == calc.Value(2):

                    if new_eq.right_hand_side.term[0].is_negative():
                        return _("This equation has no solution.")

                    elif new_eq.left_hand_side.is_equivalent_to_a_single_0():
                        new_eq.left_hand_side.term[0].exponent = calc.Value(1)

                    else:
                        temp_sqrt1 = calc.SquareRoot(new_eq.\
                                                     right_hand_side.term[0])
                        temp_sqrt2 = calc.SquareRoot(temp_sqrt1)
                        temp_sqrt2.set_sign('-')
                        temp_item = calc.Item(new_eq.left_hand_side.term[0])
                        temp_item.exponent = calc.Value(1)
                        new_eq1 = Equation((temp_item,
                                            temp_sqrt1))
                        new_eq2 = Equation((temp_item,
                                            temp_sqrt2))

                        if 'pythagorean_mode' in options:
                            new_eq2 = " " + _("because") + " " \
                                      + temp_item.make_string(\
                                        options['pythagorean_mode'],
                                        force_expression_begins=True) \
                                      + " " + _("is positive.")

                        return (new_eq1, new_eq2)


                # Now the exponent must be equivalent to a single 1
                # or the algorithm just doesn't know how to solve further.
                else:
                    return None


        #DEBUG
        #debug.write("\nBefore having thrown away the neutrals : " \
        #                       + "\n" \
        #                       + str(new_eq) + "\n",
        #                       case=debug.solve_next_step)

        # throwing away the possibly zeros left..
        new_eq.set_hand_side("left",
                             new_eq.left_hand_side.throw_away_the_neutrals()
                            )
        new_eq.set_hand_side("right",
                             new_eq.right_hand_side.throw_away_the_neutrals()
                            )

        #DEBUG
        #debug.write("\nafter having thrown away the neutrals,"
        #                       + " right_hand_side looks like : " \
        #                       + str(new_eq.right_hand_side) + "\n",
        #                       case=debug.solve_next_step)

        #DEBUG
        debug.write("\nLeaving [solve_next_step] " \
                               + "with Equation :\n" \
                               + str(new_eq) + "\n",
                               case=debug.solve_next_step)
        return new_eq





    # ----------------- FUNCTION CREATING THE ML STRING OF THE OBJECT ---------
    ##
    #   @brief Creates a string of the given object in the given ML
    #   @param markup The markup dictionary to use
    #   @param options Any options
    #   @return The formated string
    def make_string(self, markup, **options):
        global expression_begins
        # Equation objects displaying
        beginning = ''

        if 'display_name' in options:
            if self.number == '':
                beginning = markup['opening_bracket'] \
                           + self.name \
                           + markup['closing_bracket'] \
                           + markup['colon'] \
                           + markup['space']
            else:
                beginning = markup['opening_bracket'] \
                           + self.name \
                           + markup['opening_subscript'] \
                           + str(self.number) \
                           + markup['closing_subscript'] \
                           + markup['closing_bracket'] \
                           + markup['colon'] \
                           + markup['space']

        left = self.left_hand_side.make_string(markup,
                                               force_expression_begins=True)

        right = self.right_hand_side.make_string(markup,
                                                 force_expression_begins=True)

        egal_sign = markup['equal']

        if self.left_hand_side.contains_a_rounded_number() \
           or self.right_hand_side.contains_a_rounded_number():
        #___
            egal_sign = markup['simeq']

        return beginning \
               + left \
               + egal_sign \
               + right





    # --------- FUNCTION CREATING THE ML STRING OF ITS OWN RESOLUTION ---------
    ##
    #   @brief Creates a string of the equation's resolution in the given ML
    #   @param markup The markup dictionary to use
    #   @param options Any options
    #   @return The formated string of the equation's resolution
    def auto_resolution(self, markup, **options):
        global expression_begins

        # Complete resolution of the equation :o)
        result = ""

        if not 'dont_display_equations_name' in options:
            if self.number == '':
                result = markup['opening_expression'] \
                         + markup['opening_bracket'] \
                         + self.name \
                         + markup['closing_bracket'] \
                         + markup['colon'] \
                         + markup['space'] \
                         + markup['closing_expression']
            else:
                result = markup['opening_expression'] \
                         + markup['opening_bracket'] \
                         + self.name \
                         + markup['opening_subscript'] \
                         + str(self.number) \
                         + markup['closing_subscript'] \
                         + markup['closing_bracket'] \
                         + markup['colon'] \
                         + markup['space'] \
                         + markup['closing_expression']

        #result += markup['newline']

        eq_aux = Equation(self)
        eq_aux1 = None
        eq_aux2 = None
        equation_did_split_in_two = False
        go_on = True

        while go_on:
            if not equation_did_split_in_two:

                next_eq_aux = eq_aux.solve_next_step(**options)

                if next_eq_aux == None and 'unit' in options:
                    result += markup['opening_math'] \
                           + eq_aux.make_string(markup) \
                           + " " + str(options['unit']) \
                           + markup['closing_math']
                else:
                    result += markup['opening_math'] \
                           + eq_aux.make_string(markup) \
                           + markup['closing_math']

                if next_eq_aux == None or type(next_eq_aux) == str \
                    or isinstance(next_eq_aux, tuple):
                #___
                    eq_aux = next_eq_aux
                else:
                    eq_aux = Equation(next_eq_aux)

                if isinstance(eq_aux, tuple):
                    (eq_aux1, eq_aux2) = eq_aux
                    equation_did_split_in_two = True

                elif isinstance(eq_aux, str) or eq_aux == None:
                    go_on = False

            else:
                if isinstance(eq_aux1, Equation):
                    next_eq_aux1 = eq_aux1.solve_next_step(**options)

                if isinstance(eq_aux2, Equation):
                    next_eq_aux2 = eq_aux2.solve_next_step(**options)

                if eq_aux1 != None or eq_aux2 != None:
                    result += markup['opening_math']

                if isinstance(eq_aux1, Equation):
                    result += eq_aux1.make_string(markup)

                    if next_eq_aux1 == None and 'unit' in options:
                        result += " " + str(options['unit'])

                    if isinstance(eq_aux2, Equation):
                        result += " " + _("or") + " "

                elif eq_aux1 != None:
                    result += eq_aux1

                if isinstance(eq_aux2, Equation):
                    result += eq_aux2.make_string(markup)

                    if next_eq_aux2 == None and 'unit' in options:
                        result += " " + str(options['unit'])

                elif eq_aux2 != None:
                    result += eq_aux2
                    eq_aux2 = None

                if not isinstance(eq_aux1, Equation) \
                   and not isinstance(eq_aux2, Equation):
                #___
                    go_on = False

                if eq_aux1 != None or eq_aux2 != None:
                    result += markup['closing_math']

                if isinstance(eq_aux1, Equation):
                    eq_aux1 = eq_aux1.solve_next_step(**options)

                if isinstance(eq_aux2, Equation):
                    eq_aux2 = eq_aux2.solve_next_step(**options)




        if (not equation_did_split_in_two):
            if eq_aux == None:
                pass
            else:
                result += eq_aux + markup['newline']
        else:
            if eq_aux1 == None and eq_aux2 == None:
                pass
            else:
                if eq_aux1 == None:
                    result += eq_aux2 + markup['newline']
                else:
                    result += eq_aux1 + markup['newline']

        return result

---