Recent changes to General Introduction

General Introduction modified by Nicolas Hainaux

Nicolas Hainaux — Sun, 02 Feb 2014 08:16:13 -0000

--- v3
+++ v4
@@ -1,10 +1,18 @@
 /!\ this is a first draft
+
+It is utmost important to understand that mathmaker is not a software intended to *compute* mathematical stuff, but to *display* it. For instance, the aim of mathmaker is not to resolve a first-degree equation, because we don't need any computer to do it, and because other softwares can do that certainly, no, mathmaker will determine and display the steps of this resolution. Sometimes, mathmaker will also try to mimic the pupils' way of doing things.
+
+For instance, it won't automatically simplify a fraction to make it irreducible in one step, but will try to reproduce the steps that pupils usually need to simplify the fraction. So the GCD is only used to check when the fraction is irreducible and for the cases where there's no other choice, but not as the mean to simplify a fraction directly (not before pupils learn how to use it, at least).
+
+Another example is the need of mathmaker to control the displaying of decimal and integer numbers perfectly. Of course, most of the time, it doesn't matter when a computer tells that 5.2*5.2 = 27.040000000000003 or 3.9*3.9 = 15.209999999999999 because everyone knows that the correct results are 27.04 and 15.21 and because the difference is not so important, so in many situations, this precision will be sufficient. But, can we tell kids that the result of 5.2*5.2 is 27.040000000000003 ? And simply round the result is not always the good solution to this problem !
+
+Also, the human rules we use to write maths are full of exceptions and strange details we don't notice usually because we're familiar to them. We would never write +2x² + 1x - 1(+5 - 1x) but instead 2x² + x - (5 - x). There are many conventions in the human way to write maths and many exceptions.
+
+These are the reasons why the core is quite complex : re-create these writing rules and habits on a computer and let the result be readable by pupils is not always simple.

 Mathmaker creates Sheets of maths Exercises. Each Exercise contains Questions. Each Question uses objects from the core, that embbed enough information to compute and write the text of the Question and also the answer.

 The informations embedded by the core objects are independant from the output format. For instance, a Question about Pythagora's theorem would embed an object RightTriangle (which itself embeds information on its sides' lengths for instance ; and enough methods to create a picture of it) but also fields telling if the figure should be drawn in the Question's text or if only a description of the figure should be given ; if the hypotenuse should be calculated or another side ; if the result should be a rounded decimal and how precise it should be etc.
-
-It is utmost important to understand that mathmaker is not a software intended to *compute* mathematical stuff, but to *display* it. This is the reason why the core is quite complex : the human rules we use to write maths are full of exceptions and strange details we don't notice usually because we're familiar to them. To re-create these writing rules on a computer is not really simple !

 When a new Sheet is created, all objects it contains are created randomly (following some rules, though...).

General Introduction modified by Nicolas Hainaux

Nicolas Hainaux — Thu, 30 Jan 2014 22:16:54 -0000

--- v2
+++ v3
@@ -3,6 +3,8 @@
 Mathmaker creates Sheets of maths Exercises. Each Exercise contains Questions. Each Question uses objects from the core, that embbed enough information to compute and write the text of the Question and also the answer.

 The informations embedded by the core objects are independant from the output format. For instance, a Question about Pythagora's theorem would embed an object RightTriangle (which itself embeds information on its sides' lengths for instance ; and enough methods to create a picture of it) but also fields telling if the figure should be drawn in the Question's text or if only a description of the figure should be given ; if the hypotenuse should be calculated or another side ; if the result should be a rounded decimal and how precise it should be etc.
+
+It is utmost important to understand that mathmaker is not a software intended to *compute* mathematical stuff, but to *display* it. This is the reason why the core is quite complex : the human rules we use to write maths are full of exceptions and strange details we don't notice usually because we're familiar to them. To re-create these writing rules on a computer is not really simple !

 When a new Sheet is created, all objects it contains are created randomly (following some rules, though...).

General Introduction modified by Nicolas Hainaux

Nicolas Hainaux — Thu, 30 Jan 2014 20:08:12 -0000

--- v1
+++ v2
@@ -1,49 +1,23 @@
 /!\ this is a first draft

-Here are some hints about the whole design :
+Mathmaker creates Sheets of maths Exercises. Each Exercise contains Questions. Each Question uses objects from the core, that embbed enough information to compute and write the text of the Question and also the answer.

-Mathmaker creates Sheets of maths Exercises. Each Exercise contains Questions. Each Question uses specific objects and fields, that embbed enough information to write the text of the Question and also the answer. The informations embedded by these objects are independant from the output format. For instance, a Question about Pythagora's theorem would embed an object RightTriangle (which itself embeds information on its sides' lengths for instance ; and enough information to create a picture of it) but also fields telling if the figure should be drawn in the Question's text or if only a description of the figure should be given ; if the hypotenuse should be calculated or another side ; if the result shouldn't need to be rounded (either integer or decimal) ; if the result should be a rounded decimal and how precise it should be rounded etc. When a new Sheet is created, all objects it contains are created randomly (following some rules, though...).
+The informations embedded by the core objects are independant from the output format. For instance, a Question about Pythagora's theorem would embed an object RightTriangle (which itself embeds information on its sides' lengths for instance ; and enough methods to create a picture of it) but also fields telling if the figure should be drawn in the Question's text or if only a description of the figure should be given ; if the hypotenuse should be calculated or another side ; if the result should be a rounded decimal and how precise it should be etc.
+
+When a new Sheet is created, all objects it contains are created randomly (following some rules, though...).

 The "Machine" object can be seen as a typewriter : it takes the mathematical objects and turns them into the output format (LaTeX, so far) ; it draws figures from the geometrical objects (using eukleides) etc. The Sheet object given to a Machine is a guideline for the Machine to type what is expected on output.

-So, the main executable, mathmaker, just creates a (LaTeX) Machine and let it "type" the sheet the user is asking for (given in parameter).
+So, the main executable, mathmaker, just creates a (LaTeX) Machine and let it "type" the sheet the user has given as parameter.

-All content created by mathmaker is written in stdin (except debugging informations, which are written in stderr)
+All content created by mathmaker is written in stdin (except debugging informations, which are written in stderr).

 Some details before diving into core : 

-* mathmaker.cfg contains some variable the user might like to change easily without having to dive into the code
+* The file mathmaker.cfg contains some variable the user might like to change easily without having to dive into the code

-* lib contains various methods and variables
+* The lib directory contains various methods and variables

-* locale contains all stuff related to internationalization (here are the po files to edit with poedit)
+* The locale directory contains all stuff related to internationalization (here are the po files to edit with poedit)

-* the maintenance directory contains anything related to debugging and to tests.
---> Turn ENABLED to True in debug.py will let mathmaker write debugging informations to stderr. The methods that give output informations can be chosen among the different variable below (into_str_in_item, into_str_in_product etc.). All objects have a special (small) method called dbg_str() which is used to clearly identify the objects and their classes. (I can see in your snip : {+1^.1.} and {-0^.1.}, which represent Item(1) and Item(0), so there was some debugging stuff enabled there)
---> The autotest-mathmaker executable in the main directory uses the tests present in maintenance/autotest
-These tests have been written either before writing the code (unit tests) or after a bug has been found.
-Some uses of autotest-mathmaker :
-- without options, will provide a short summary after having executed all the tests.
-- autotest-mathmaker -v will give more informations (but not really useful, maybe it should be deleted)
-- autotest-mathmaker -V will give alot of informations (number of the test which failed, plus which result was expected and which result was found instead)
-- You can also use autotest-mathmaker on some units instead of them all
-- autotest-mathmaker short-test-run will execute each sheet once. Just to check there's no big bug somewhere.
-- autotest-mathmaker long-test-run=n will execute each sheet n times. (warms the processor...). to detect more rare bugs.
-- autotest-mathmaker --help will give you some more hints
-
-Now, here are some details about the core :
-* The most important thing is that mathmaker is not a software intended to *compute* mathematical stuff, but to *display* it. This is the reason why the core is quite complex : the human rules we use to write maths are full of exceptions and strange details we don't notice usually because we're familiar to them. To re-create these writing rules on a computer is not really simple !
-* So, all objects of the core are mathematical objects which can be represented, either as figures or as mathematical formulas
-* Hence, all objects are not conceived according to their mathematical properties first, but according to their "displaying rules"
-* base.py contains the most abstract classes :
-- Copiable, mother class of all objects. Provides a deep_copy() method which ensures to create a new object completely identical to the given one
-- Drawable, mother class of all geometrical objects. Provides the into_pic() method, which creates a picture of the object. All geometrical objects must implement a into_euk() method, which will create the eukleides file (.euk) to draw them. This method is used by Drawable.into_pic() to create the picture.
-- Printable, mother class of all calculus objects. They all must implement the into_str() method, which tells how to display them (independently from the output's format). Note that Drawable was thought to be a Printable too, so that geometrical objects would have to implement into_str() as well. But this feature does not seem to be useful. So probably Drawable will only inherit from Copiable.
-* 
-
-
-
-
-
-
-I should certainly also update the documentation (I use doxygen), this would be of help...
+* The maintenance directory contains anything related to debugging and to tests.

General Introduction modified by Nicolas Hainaux

Nicolas Hainaux — Wed, 29 Jan 2014 06:17:18 -0000

/!\ this is a first draft

Here are some hints about the whole design :

Mathmaker creates Sheets of maths Exercises. Each Exercise contains Questions. Each Question uses specific objects and fields, that embbed enough information to write the text of the Question and also the answer. The informations embedded by these objects are independant from the output format. For instance, a Question about Pythagora's theorem would embed an object RightTriangle (which itself embeds information on its sides' lengths for instance ; and enough information to create a picture of it) but also fields telling if the figure should be drawn in the Question's text or if only a description of the figure should be given ; if the hypotenuse should be calculated or another side ; if the result shouldn't need to be rounded (either integer or decimal) ; if the result should be a rounded decimal and how precise it should be rounded etc. When a new Sheet is created, all objects it contains are created randomly (following some rules, though...).

The "Machine" object can be seen as a typewriter : it takes the mathematical objects and turns them into the output format (LaTeX, so far) ; it draws figures from the geometrical objects (using eukleides) etc. The Sheet object given to a Machine is a guideline for the Machine to type what is expected on output.

So, the main executable, mathmaker, just creates a (LaTeX) Machine and let it "type" the sheet the user is asking for (given in parameter).

All content created by mathmaker is written in stdin (except debugging informations, which are written in stderr)

Some details before diving into core :

mathmaker.cfg contains some variable the user might like to change easily without having to dive into the code
lib contains various methods and variables
locale contains all stuff related to internationalization (here are the po files to edit with poedit)
the maintenance directory contains anything related to debugging and to tests.
--> Turn ENABLED to True in debug.py will let mathmaker write debugging informations to stderr. The methods that give output informations can be chosen among the different variable below (into_str_in_item, into_str_in_product etc.). All objects have a special (small) method called dbg_str() which is used to clearly identify the objects and their classes. (I can see in your snip : {+1^.1.} and {-0^.1.}, which represent Item(1) and Item(0), so there was some debugging stuff enabled there)
--> The autotest-mathmaker executable in the main directory uses the tests present in maintenance/autotest
These tests have been written either before writing the code (unit tests) or after a bug has been found.
Some uses of autotest-mathmaker :
without options, will provide a short summary after having executed all the tests.
autotest-mathmaker -v will give more informations (but not really useful, maybe it should be deleted)
autotest-mathmaker -V will give alot of informations (number of the test which failed, plus which result was expected and which result was found instead)
You can also use autotest-mathmaker on some units instead of them all
autotest-mathmaker short-test-run will execute each sheet once. Just to check there's no big bug somewhere.
autotest-mathmaker long-test-run=n will execute each sheet n times. (warms the processor...). to detect more rare bugs.
autotest-mathmaker --help will give you some more hints

Now, here are some details about the core :
The most important thing is that mathmaker is not a software intended to compute mathematical stuff, but to display it. This is the reason why the core is quite complex : the human rules we use to write maths are full of exceptions and strange details we don't notice usually because we're familiar to them. To re-create these writing rules on a computer is not really simple !
So, all objects of the core are mathematical objects which can be represented, either as figures or as mathematical formulas
Hence, all objects are not conceived according to their mathematical properties first, but according to their "displaying rules"
base.py contains the most abstract classes :
- Copiable, mother class of all objects. Provides a deep_copy() method which ensures to create a new object completely identical to the given one
- Drawable, mother class of all geometrical objects. Provides the into_pic() method, which creates a picture of the object. All geometrical objects must implement a into_euk() method, which will create the eukleides file (.euk) to draw them. This method is used by Drawable.into_pic() to create the picture.
- Printable, mother class of all calculus objects. They all must implement the into_str() method, which tells how to display them (independently from the output's format). Note that Drawable was thought to be a Printable too, so that geometrical objects would have to implement into_str() as well. But this feature does not seem to be useful. So probably Drawable will only inherit from Copiable.
*

I should certainly also update the documentation (I use doxygen), this would be of help...