Mathmaker creates elementary maths worksheets with detailed solutions.
The output documents can be compiled into pdf files by lualatex. Examples of available themes are: first degree equations, pythagorean theorem, fractions calculation...
It can run from command line, but can be controlled via http requests too.
Required (non python) dependencies are python >=3.4, euktoeps >=1.5.4, xmllint, msgfmt, lualatex, luaotfload-tool and a bunch of LaTeX packages(1)
To install them:
on Ubuntu, python3.4 is already installed, so:
$ sudo apt-get install eukleides libxml2-utils gettext texlive-latex-base
And for the yet missing LaTeX packages: you can either install the complete texlive distribution (takes some room on the hard disk): run
$ sudo apt-get install texlive-full, or install only the necessary packages:
$ sudo apt-get install texlive-luatex texlive-latex-recommended texlive-xetex texlive-pstricks texlive-font-utils texlive-latex-extra texlive-base texlive-science texlive-pictures texlive-generic-recommended texlive-fonts-recommended texlive-fonts-extra
$ sudo pkg install python34 py34-sqlite3 gettext eukleides libxml2 texlive-full $ rehash
Check how to fix eukleides install in the complete documentation
Once you’re done, you can proceed installing mathmaker:
$ pip3 install mathmaker
(this will automatically install three extra python3 libraries too: polib, PyYAML and python-daemon).
FreeBSD users, check how to fix mathmaker install if it stops with an error in python-daemon install, in the complete documentation
$ mathmaker pythagorean-theorem-short-test > out.tex $ lualatex out.tex
$ mathmaker pythagorean-theorem-short-test --pdf > out.pdf
Get the list of all provided sheets(3):
$ mathmaker list
mathmaker --help to see which settings can be changed as command line arguments.
Some more settings can be overriden by user defined values in
~/.config/mathmaker/user_config.yaml. Read the complete
documentation for more information.
You can contribute to mathmaker:
As a wordings contributor¶
Mathmaker needs contexts for problems wordings. There are already some, but the more there is, the better. Existing wordings can be found here. You can submit any new idea as an enhancement proposal there (should be written in english, french or german).
Any question can be sent to nh dot techn (hosted at gmail dot com).
As a translator¶
You can help translating mathmaker to your language (or any language you like, if you have enough elementary maths vocabulary for that).
If the translation to your language isn’t started yet, there are several pot files to get here (see explanations about their respective roles there). You can use an editor like poedit or any other you like better, to create po files from them and start to translate.
If you want to add missing translations, or to correct some, you can find the po files in the subdirectories here.
Once you’re done, you can make a pull request here.
Any question can be sent to nh dot techn (hosted at gmail dot com).
- Lead developer: Nicolas Hainaux
- Developers: Vaibhav Gupta
- Clever advices: Olivier Cecillon
- French: Nicolas Hainaux
Patience and chocolate cakes¶
New in version 0.7.1dev5 (2017-05-04)¶
- Issue warnings instead of exceptions when the version of a dependency could not be determined.
New in version 0.7.1dev4 (2017-05-03)¶
- New sheets about trigonometry: - vocabulary in the right triangle - write the correct formulae - calculate a length - calculate an angle
New in version 0.7.1dev3 (2016-10-21)¶
- New sheets: - intercept theorem: “butterfly” configuration - intercept theorem: converse
New in version 0.7.1dev2 (2016-10-13)¶
- New sheets: - expansion of simple brackets (declined in two versions) - clever multiplications (mental calculation) - intercept theorem: write the correct quotients’ equalities - intercept theorem: solve simple exercises
These sheets and all future sheets will be defined in xml files.
New in version 0.7.1dev1 (2016-09-14)¶
- A new sheet (declined in two versions): expansion of double brackets. Defined in an xml sheet as for mental calculation sheets.
New in version 0.7.0-6 (2016-08-19)¶
- Added a setting to let the user change mathmaker’s path (to be used by the daemon)
New in version 0.7.0-5 (2016-08-19)¶
New in version 0.7.0-4 (2016-08-19)¶
- If an IP address is passed as parameter to mathmaker’s daemon, it will return a 429 http status code (too many requests) if the last request from the same address is not older than 10 seconds.
New in version 0.7.0-3 (2016-07-18)¶
- Fixed the install of locale files and font listing file
New in version 0.7 (2016-07-15)¶
- Standardized structure (
mathmakerbecomes pip3-installable, available on PyPI and github; its documentation is hosted on readthedocs; tests are made with py.test)
- A daemon is added (
mathmakerd) to provide communication with
mathmakerthrough http connections.
- A bunch of mental calculation sheets
- The use of XML frameworks for the sheets (yet only for mental calculation, so far)
- Complete list of recommended LaTeX packages:
|CTAN Package Name||Package name (Ubuntu 14.04 )|
pkg, you’ll have to install
texlive-full; if you wish to install only the relevant LaTeX packages, you’ll have to browse the ports, I haven’t done this yet so cannot tell you exactly which ones are necessary.
- Complete list of provided sheets:
The default settings are following:
PATHS: EUKTOEPS: euktoeps XMLLINT: xmllint LUALATEX: lualatex LUAOTFLOAD_TOOL: luaotfload-tool MSGFMT: msgfmt OUTPUT_DIR: ./ LOCALES: # Available values can be checked in the locale directory. LANGUAGE: en_US ENCODING: UTF-8 # Values can be 'euro', 'sterling', 'dollar' CURRENCY: dollar LATEX: FONT: ROUND_LETTERS_IN_MATH_EXPR: False
PATHS:section is here to provide a mean to change the paths to
xmllintmainly. In case one of them is not reachable the way it is set in this section, you can change that easily.
PATHS:section contains also an
OUTPUT_DIR:entry. This is the directory where
mathmakerwill store the possible picture files (.euk and .eps). Default value is “current directory”. You can set another value, at your liking.
- The entries under
LOCALES:allow to change the language, encoding, and default currency used.
LATEX:section contains an entry to set the font to use (be sure it is available on your system). The
ROUND_LETTERS_IN_MATH_EXPR:entry is disabled by default (set to False). If you set it to True, a special font will be used in math expressions, that will turn all letters (especially the ‘x’) into a rounded version. This is actually the
lxfontsLaTeX package. It doesn’t fit well with any font. Using “Ubuntu” as font and setting
ROUND_LETTERS_IN_MATH_EXPR:to True gives a nice result though.
Your settings file must be
Several command-line options correspond to settings that are defined in
~/.config/mathmaker/user_config.yaml. Any option redefined in command-line options will override the setting from the configuration file.
mathmaker --help to get information on these command-line options.
http server (mathmakerd)¶
Once everything is installed, it’s possible to run a server to communicate with mathmaker through a web browser.
Run the server:
$ mathmakerd start
Then go to your web browser and as url, you can enter:
<sheetname> by an available sheet’s name (from
mathmaker list), for instance:
mathmaker will create the new sheet, compile it and return the pdf result to be displayed in the web browser.
At the moment,
mathmakerd stop doesn’t work correctly, you’ll have to
kill it directly (
ps aux | grep mathmakerd then
kill with the appropriate pid).
It’s possible to pass an IP address in an extra parameter named
In this case,
mathmakerd will check if the last request is older than 10 seconds (this is hardcoded, so far) and if not, then a http status 429 will be returned. In order to do that,
mathmakerd uses a small database that it erases when the last request is older than one hour (also hardcoded, so far).
As a directive to mathmaker it is possible to give a path to an xml file.
Creating a new xml file that can be used as a model by
mathmaker is more for advanced users, though it’s not that difficult.
At the moment (version 0.7), it’s only possible to create mental calculation sheets this way. So there’s not much to change from a raw model.
Let’s have a look at
<?xml version="1.0" encoding="UTF-8"?> <sheet header="" title="Mental calculation" subtitle="Divisions" text="" answers_title="Answers"> <!-- Default values: type="std" unit="cm" font_size_offset="0" --> <!-- Available layout types: std|short_test|mini_test|equations|mental --> <layout type="mental" font_size_offset="-1"> <exc> <line nb="None"> <exercises>all</exercises> </line> </exc> <ans> <line nb="None"> <exercises>all</exercises> </line> </ans> </layout> <!-- Default value: id='generic' No default for kind and subkind, they must be given --> <!-- Available kinds for mental calculation: tabular, slideshow --> <exercise id="mental_calculation" kind="tabular"> <!--No default for kind and subkind, they must be given --> <question kind="divi" subkind="direct"> <nb source="intpairs_2to9">20</nb> </question> </exercise> </sheet>
<sheet> tag has attributes that let you easily change the title of the sheet, a subtitle etc.
<layout> part can’t be changed (yet) except the
font_size_offset attributes. The later one is especially practical to resize the whole sheet at once.
<exercise> part is the one you can change alot. Keep the
kind="tabular" attributes though (they can’t be changed yet) but you can put the questions you like inside.
Each question is defined this way:
<question kind="divi" subkind="direct"> <nb source="intpairs_2to9">20</nb> </question>
You must set at least a
kind and a
subkind attributes. Then inside the question, you set at least one numbers’ source. This question says: “I want 20 questions about direct division (i.e. each one will be of the form a ÷ b = ?) the numbers being integers between 2 and 9”. (For divisions the pair of integers will be b and the solution; mathmaker will compute a automatically).
Another example, taken from
<question kind="addi" subkind="direct" context="mini_problem"> <nb source="intpairs_5to20">5</nb> </question>
You see you can set the lower and upper values as you like. Just respect the syntax (if you write
intpairs_5_to_20 this won’t work). And this time a context is added to the question. So it means “I want 5 simple additive problems, the numbers being integers between 5 and 20”.
Note that you can put several different numbers’ sources inside one
<question>. For instance:
<question kind="multi" subkind="direct"> <nb source="intpairs_2to9">1</nb> <nb source="table_11">1</nb> <nb source="decimal_and_one_digit">1</nb> </question>
This means there will be three questions, all being direct multiplications, but one pair of numbers will be integers between 2 and 9; one pair will be from the table of 11 (like 34 × 11), and one will be a decimal number and a one digit number (like 150,3 × 0.01).
Last explained feature: in some sheets you’ll find
<mix> sections, like this one, taken from
<mix> <question kind="area" subkind="rectangle" picture="true"></question> <question kind="multi" subkind="direct"></question> <question kind="multi" subkind="direct"></question> <question kind="vocabulary" subkind="multi"></question> <nb source="table_15">1</nb> <nb source="table_11">1</nb> <nb source="intpairs_2to9" variant="decimal1">1</nb> <nb source="intpairs_2to9" variant="decimal2">1</nb> </mix>
It means the numbers’ sources will be randomly attributed to the questions. Each time a new sheet is generated from this framework, the numbers from table of 15 will be attributed . The rules to follow for a
<mix> section are:
- Put as many numbers’ sources as there are questions. For instance in the example above we could have written this too:
<mix> <question kind="area" subkind="rectangle" picture="true"></question> <question kind="multi" subkind="direct"></question> <question kind="multi" subkind="direct"></question> <question kind="vocabulary" subkind="multi"></question> <nb source="table_15">3</nb> <nb source="intpairs_2to9" variant="decimal1">1</nb> </mix>
- Any numbers’ source must be assignable to any of the questions.
Now the question is: how to know about the questions kinds and subkinds, and the possible contexts, variants or whatever other attributes? Well it is planned to add an easy way to know that (like a special directive) but there’s nothing yet. The better, so far, may be to look at the provided sheets in
mathmaker/data/framworks/mental_calculation/ and see what’s in there.
eukleides currently does not work out of the box. The pkg-installed version has a functional euktoeps script, it is required, so keep it somewhere. Then do
pkg remove eukleides and re-install it from source:
get the 1.5.4 source from http://www.eukleides.org/, for instance
tar xvzf eukleides-1.5.4.tar.bz2
then possibly modify the prefix for install in the
Configfile, at your liking
remove the making of documentation and manpages from the
installtarget in the
Makefile(they cause errors)
install the required dependencies to compile eukleides:
pkg install bison flex gmake gcc
gmake install. This will provide functional binaries.
replace the euktoeps script by the one you did get from the pkg installed version.
if necessary (if
lualatexcomplains about not finding
# mkdir /usr/local/share/texmf-dist/tex/latex/eukleides # cp /usr/local/share/texmf/tex/latex/eukleides/eukleides.* /usr/local/share/texmf-dist/tex/latex/eukleides/ # mktexlsr
python-daemon error at install¶
You might get an error before the end of
/usr/local/venv/mm0/lib/python3.4/site-packages/setuptools/dist.py:294: UserWarning: The version specified ('UNKNOWN') is an invalid version, this may not work as expected with newer versions of setuptools, pip, and PyPI. Please see PEP 440 for more details. "details." % self.metadata.version creating /usr/local/venv/mm0/lib/python3.4/site-packages/python_daemon-UNKNOWN-py3.4.egg Extracting python_daemon-UNKNOWN-py3.4.egg to /usr/local/venv/mm0/lib/python3.4/site-packages Adding python-daemon UNKNOWN to easy-install.pth file Installed /usr/local/venv/mm0/lib/python3.4/site-packages/python_daemon-UNKNOWN-py3.4.egg error: The 'python-daemon>=2.1.1' distribution was not found and is required by mathmaker [mm0] root@testmm0:/usr/local/src/mathmaker #
Fix it this way:
# pip3 install python-daemon --upgrade
And finish the install:
# pip3 install mathmaker