Introduction to the software

Here follows a short introduction to the software structure.

The aim of this software is NOT to calculate anything but to DISPLAY maths formulas.

Of course, it needs to compute some expressions but it's always elementary maths, nothing really complicated.

The most complex thing that Mathmaker does is to reproduce the human writing rules of mathematical expressions, which are not always as simple as one could think before trying to implement them !

So, the software is divided into seven main parts :

• the main programm
• a configuration file
• the autotest
• some small libs
• the "machines"
• the mathematical objects
• the sheet objects

The main programm : file : mathmaker

It only deals with parsing the command line, setting the language and the output and calling the right functions and classes

The configuration file : file : mathmaker.cfg

Contains parameters the end-user could wish to set (like the output language, the output encoding format etc.)

The autotest : file : autotest

It is only used as a debugging help and to check that new bug corrections don't create new bugs elsewhere in the programm.

The small libs : files : __.py, alphabet.py, cfg.py, default.py, error.py, is_.py, latex.py, randomly.py and software.py, obj.calc.lib.py

They all contain "global" names.

• __.py contains constants to be used in the programm (ideally find another name or find a way to avoid using this file)
• alphabet.py, default.py, latex.py and software.py contain only constants related to their names.
• cfg.py contains data related to the configuration file (name, extension) and the function that gets a data from the configuration file
• error.py contains all exception classes specifically raised by mathmaker
• is_.py contains many "type asking for" functions, which is not really good programming. It is still there because couldn't find better solutions in some cases. Should be deleted.
• obj.calc.lib.py contains mathematical functions & utilities (like computing the gcd of two numbers, telling the sign of a product etc.)

The machines : files : machine.Structure, machine.LaTeX

These objects embed the specific implementation of functions producing output in a particular Markup Language, like writing the correct header or end of a document, writing a table, a mathematic formula etc. They also embed the related ML dictionary.

The mathematical objects : files : obj.__init__.py, obj.calc.__init__.py and yet to be written obj.geo.__init__.py

They contain the description of the different mathematical objects used by Mathmaker, like the equations, the expressions (which can be wether numeric or algebraic, Products or Sums) etc. Each mathematical object contains lots of methods telling how to display it or how to build the next object in a calculation or resolution process, for example. The matching methods are make_string() to display an object and a *_next_step() method to build the next object to be displayed. What this method exactly does depends on the object. For instance, the Equation objects have a resolve_next_step() method, which creates the next Equation object in the resolution process. The Calculable objects have a calculate_next_step() method and the Expandable objects have a expand_next_step() method. All the mathematical objects also have a lot of auxiliary methods, much related to display the objects correctly. You should check the inheritance diagram for obj::Printable in the Doxygen documentation. Note : the Value class has been introduced to simplify the problem of exponents being simple numbers sometimes. It embeds numbers and strings and also has some methods from the Calculable class to let these objects be compatible enough mainly to make tests on them as if they were objects and not just numbers. It doesn't implement all Calculable methods : otherwise it would be an Item. A Value can only be used as a number (or a String) and not as a term of a Sum or a factor of a Product for example : these must be Items. Value is then used as exponent (when the exponent isn't itself an Item) and to embed the value of the Item objects.

The sheet objects : files : many located in sheet/, sheet/exercise/ and sheet/exercise/question/

A question object contains basically a mathematical object, some other parameters (like the number of the question) and the way to display the object AND the solution to the question (the calculating steps being implemented in the mathematical objects). The greatest task for a question object is to build the mathematical objects according to certain specific parameters (e.g. please build an equation that's really basic or a little bit harder, or build an expression to expand of this kind or this another kind or randomly any kind etc.). The kind='something' parameter is not optionnal in the case of question objects.

The exercise objects contain lists of question objects plus the text of the exercise (like "Please reduce the following expressions :") and may have to deal with the kind of exercise desired. (For example, one question about calculating the Sum of two Fractions, another about calculating the Product of two Fractions, and a third one about dividing two Fractions). The Structure of exercises objects allows follow the same organization (the processing of optionnal arguments is done by the __init__() method of exercise.Structure and then there's a zone for preformatted exercises and another for the common case ; check the instructions at the bottom of the sheet/exercise/Model.py file). The kind='something' parameter is optionnal here.

The sheet objects finally gather a list of exercises objects plus layout details.

You should check the inheritance diagram for sheet::Structure::Structure in the Doxygen documentation.