PyParti (Python for Partitions) is a tool based on Python (3.6+) and computational mathematics software SageMath (9.0+) to experiment with integer partitions, Young diagrams, and related concepts in combinatorics. This repository contains:
- Jupyter/SageMath notebooks for experimenting with partitions and generating functions
- Python/SageMath source code and unit tests to extend the existing
Partition
class with functionality relating to generalised core partitions
- Python code/programs to produce LaTeX files which compile to publication-quality labelled diagrams of partitions for educational/research purposes.
py2tikz.py
py2tikz-demo.ipynb
- See this repository for tools to compile TikZ diagram instructions directly to .png files for portability.
This repository and individual notebooks can be run online without the need for any local installation and configuration by following the links to notebooks above or by clicking on the badge below to launch a Jupyter server accessed in the browser.
This is facilitated by mybinder.org, a public instance of the BinderHub service. BinderHub allows many users to start Binder sessions: within a session, BinderHub creates a per-session software environment on demand on remote hardware (using repo2docker) then starts a Jupyter service within that environment.
As an end user, all you need to start a BinderHub session is
- The URL of an accessible Git repository that contains a software environment definition
(e.g. a Python
requirements.txt
file, Condaenvironment.yml
or a DockerDockerfile
); - The branch, tag or commit that you’d like to access within that repository;
- (Optional) a relative path within that directory to a Notebook you’d like to run. These parameters can be supplied via a web form (as at mybinder.org) or as URL parameters (allowing someone to just follow a link to start a Binder session).
Another way to avoid installing the SageMath distribution dependencies on your local machine is to create a project on CoCalc and clone the repository contents there
For development purposes, you may wish to install a copy of the SageMath distribution locally to your machine from sagemath.org. Multiple download options exist including installers, binaries, compiling from source, Docker containers, and using package managers such as Conda.
If your issue (feature request or bug) has not already been filed in the PyParti GitHub repository (list of all open issues) then please file a new Issue against the PyParti GitHub repository.
On each Pull Request or push made to the master
branch of the PyParti GitHub repository
we trigger a GitHub Actions continuous integration (CI) workflow.
Each invocation of the workflow runs a set of user-defined tasks in an isolated execution environment, logs output from those tasks, quits early if an error is encountered and reports the exit status on completion of the job.
The GitHub Actions dashboard for the project shows job exit statuses and logs: https://github.com/edwardmpearce/pyparti/actions
Benefits:
- Tests are run automatically without needing to be manually triggered and the results inspected by developers;
- If pull requests are made from feature branches against the
master
branch then you will be notified that tests fail before you merge any changes intomaster
. - You can concentrate on other things whilst the CI/CD service is running tests on your behalf.
The GitHub Actions CI configuration is in the file .github/workflows/test_build.yml
. In short, this:
- Spawns a job on a remote machine running a particular operating system (say, the latest version of Ubuntu Linux or MacOS) and version of Python
- Checks out (a.k.a. copies) the repository to the remote machine
- Installs Miniconda to be used as a package management tool
- Uses conda to install the dependencies required for testing, as specified in the
sage-test-env.yml
conda environment file - Uses
flake8
for code linting, i.e. checking code syntax and style for Python.py
files in the repository - Calls
pytest
to search for tests according to standard Python test discovery procedures, then run them whilst recording code coverage data usingpytest-cov
to produce anxml
report- Informative testing logs should be produced by
pytest
in the case of test failure
- Informative testing logs should be produced by
- Upload code coverage data (i.e. proportion of the code which is covered by the tests) to CodeCov service (see Coverage badge with link above)
- The
sage
package on conda-forge is only available for Linux and MacOS, but not Windows. - The
tox
package for further virtual environment and testing configuration was considered, but ultimately not used in the current testing setup. - The module
sage.all
is imported at the start of Python files relying on SageMath functionality to avoid import errors when using a Python kernel/interpreter, as is the case during the automatic testing workflow. However these import statements are unnecessary when running a Sage kernel (for example on CoCalc or in the provided Binder image)- Alternative solutions to the SageMath test environment setup problem could include:
- Move testing functionality into Jupyter notebooks where use of a Sage kernel could be specified in notebook metadata
- Find a way to run
pytest
from the SageMath shell/interpreter whilst retaining code coverage functionality to fix import issues.- Change file extension to
.sage
and change hashbang#!
instructions at start of files usingsage
functions and classes
- Change file extension to
- Follow the
doctest
framework used by other SageMath modules
- Alternative solutions to the SageMath test environment setup problem could include:
An introduction to the mathematics of partitions and Young diagrams and relevant existing SageMath functionality