Introduction, prerequisites and downloads

Matholymp is software for creating and maintaining websites for mathematical olympiads, with online registration and support for various associated administrative functions.

Matholymp is free software, written in Python and available under the GNU General Public License, version 3.

Matholymp is written and maintained by Joseph Myers. It was originally developed for the European Girls’ Mathematical Olympiad. The following events are known to use matholymp; please let me know if you’re using it for your event and I’ll add it to the list.

The following prerequisite software should be installed to use matholymp:

  • Python, version 3.5 or later.
  • PyICU (which in turn requires ICU).
  • Roundup (used to provide a web interface for editing databases for the online registration system; the issue-tracking parts of Roundup, and the email interface, are not used; Roundup is not needed if the online registration system is not used). Use of the current version of Roundup, 2.0.0 as of this writing, is recommended; older versions will not work because of Roundup API changes. Some bugs relevant to some uses of matholymp are still present in 2.0.0, so you should consider applying the patches in the roundup-patches/ directory in the matholymp source distribution before installing Roundup. See Roundup patches for more details of those patches.
  • PyPDF2 (used in generating PDF documents from registration system data, and also required in the registration system whether document generation is used or not; not needed if those parts of matholymp are not used).
  • Pillow, built with support for JPEG and PNG files.
  • LaTeX; specifically, the pdflatex command (used in generating PDF documents from registration system data; not needed if that part of matholymp is not used).
  • A web server such as Apache, and a database server (MySQL or PostgreSQL), are also recommended for use with the online registration system. (For testing purposes, you can use Roundup’s built-in web server and its support for Python’s dbm.)
  • To generate the formatted documentation, Sphinx is needed. This is not needed simply to use matholymp. If you are reading this document online, note that it relates to version 2020.07.0; if you are using a different matholymp version (including if you are using the current development sources), you may wish to format the documentation for that version using Sphinx, which can be done with the provided mo-sphinx-build script, or read the documentation sources in the docs/ directory of the source distribution directly. (Run mo-sphinx-build with an empty working directory; it generates its output in the current directory.)
  • To run automated tests of the registration system, MechanicalSoup (which in turn has some other dependencies) is needed. Those tests are only expected to work on Unix-like operating systems.
  • To measure the code coverage of the automated tests, Coverage.py is needed. This is only relevant for developing matholymp, not for using it. The --coverage option to mo-run-tests is used for measuring coverage.

The matholymp code is intended to be independent of the operating system used. However, it has only been tested on GNU/Linux (specifically, various versions of Ubuntu) and so it is likely you will need to debug portability issues if not using it on a Unix-like operating system. (Other Unix-like operating systems are unlikely to be a problem. They may vary in the extent to which the prerequisites listed above are available prepackaged or have to be locally built. I have no recommendations regarding whether you should use packaged versions where available or build these prerequisites locally; that is a matter of personal preference.)

Releases of matholymp are available for download:

The current development sources of matholymp are available using Git:

git clone https://git.ukmt.org.uk/matholymp-py.git

or:

git clone git://git.ukmt.org.uk/git/matholymp-py.git

There is also a mirror on GitHub.

The matholymp code can be used directly from its source directory; no installation is required. If you run the provided scripts from the source directory, they will automatically find the Python modules in the matholymp/ directory. However, you will need to ensure these modules can be found when the Roundup registration system is run (for example, by creating a symbolic link from the site-packages/ directory where Roundup was installed to the matholymp/ directory, or by setting PYTHONPATH appropriately). Some parts of the matholymp code have a testsuite, which can be run with mo-run-tests; all tests should pass.

The matholymp functionality falls into three main areas. Although the software is designed as an integrated whole, you can also choose to use only parts of the functionality. Whichever parts of the system you use, you will be maintaining directories containing configuration files and other content such as photos on the static site and LaTeX and HTML templates. It is a good idea to maintain these directories in a version control system such as Git in case any problems arise and you need to undo a change made. You will also need to ensure that all these directories are included in your system’s backup arrangements, and ensure that databases for the registration system are backed up as well (which typically means the backup process running database dumps to ensure the backup contains a consistent state, rather than backing up the raw files containing the database).