Author: Johannes Borgqvist
Date: 2022-02-09
Welcome to the git repository "symSys_1st_ODEs". This is a Python and LaTeX based project which conducts automated symbolic calculations of the symmetries of systems of first order ODEs using SymPy. This repository is linked to the article (Reference to future article) and the aim of this repository is that users should be able to reproduce the presented symmetries in an automated way. Let's describe the project and the way all relevant packages are installed.
One of the great difficulties with calculating symmetries of systems of differential equations is the high dimension of the resulting symmetry calculations. This is due to the fact that symmetry methods view differential equations from a geometrical perspective where each variable (e.g. time t and space x) and each state correspond to a variable in a high-dimensional geometrical manifold being the solution space (i.e. the set of all solutions) of the system of differential equations in question. Technically, to find the symmetries of a system of differential equations we must solve a system of high-dimensional PDEs where the dimension of these PDEs is determined by the number of variables plus the number of states and the number of derivatives in the differential equation at hand. In general, there is no theory for solving such high-dimensional systems analytically and thus the task of finding symmetries is really complicated. Therefore, symmetry methods are often restricted to low-dimensional differential equations where all calculations can be made by hand. The aim of this project is to try to automate the involved symmetry calculations using a symbolic solver and here we focus on systems of first order ODEs which are common in mathematical biology and the context for this article. One system of such ODEs is what we refer to as Hydon's model given by
Now the aim of this project is that the user should be able to find the generators, such as the scaling generator to Hydon's system above, to a given system of first order ODEs without having to do any calculations by hand. This is an attempt at automating these calculations, and all you have to do is to provide your model in an xlsx-file in the Input folder. Then by running the Python-script launch_symmetry_calculations.py in the Code folder, the symmetries of the defined model will be returned in the output folder. This might sound quite amazing, but there are some serious limitations to this implementation which will be described next. Also, we will describe how to install all libraries properly in order to run the scripts, but let's start with the limitations of the implemented symbolic solver for calculating the symmetries of systems of first order ODEs.
We want to emphasise from the outset that this implementation works for the specific models we have chosen for this implementation, and it cannot necessarily calculate the symmetries of other systems. In theory, as we describe in the article, the implementation should work for any system of first order ODEs where the right-hand sides, or the reaction terms if you will, are rational functions of the states. What the script does is to use a set of polynomial ans"atze for the component parts of the generator called the tangents, and then the resulting system of PDEs decomposes into a system of first order ODEs and a linear system of algebraic equations. The linear system of ODEs is solved by calculating the Jordan decomposition of the matrix in the right-hand side, and then the exponential of this matrix scaled by the time is calculated. Now, it is these steps that causes the implementation not to work for most systems in practice, and thus the implementation is by no means a perfect automated implementation for finding the system of a given first order system of ODEs. This is due to the fact that matrix calculations in sympy are notoriously slow, and thus for many systems we have tested the script gets stuck when the ODE system is solved. More precisely, the scripts gets stuck either at the step where the Jordan form is calculated or where the exponential matrix of the Jordan matrix scaled by the time is calculated. Therefore, we have chosen models that we know that the script will find the symmetries to, and if you want to test other models the script terminates after two hours in the current implementation. However, this time limit can be altered by the user, and for more information on that go to the README files in the folders Code, Input and Output, respectively.
Now we will describe how all required libraries are installed in order to execute the scripts.
The scripts have been developed on a laptop with the following operating system:
Ubuntu 20.10
with the following properties:
Kernel: Linux 5.8.0-53-generic
Architecture: x86-64.
The programming has been done in Python, and as an output the script generates a LaTeX-file with the calculated generator. The versions of packages required for the programming scripts are the following:
- python, version 3.8.3,
- SymPy, version 1.8,
- pandas, version 1.0.5,
- notebook, version 6.0.3,
- anaconda, version 2020.07 (not required but convenient).
The script also generates a LaTeX report with pdflatex. The version of pdflatex that has been used for this project is the following:
pdfTeX 3.14159265-2.6-1.40.21 (TeX Live 2020/Debian),
kpathsea version 6.3.2,
Copyright 2020 Han The Thanh (pdfTeX) et al.
To run all scripts and generate a report, a bash script called "run_all.sh" has been created. It might be neccessary to get permission to run the file first which can be done by typing "chmod +x run_all.sh" and then the script is executed with the command "./run_all.sh".
We have tested these scripts on the three OS:s Linux, Mac and Windows. In Linux using Ubuntu all steps including generating the report using pdflatex works. On Mac and Windows, all the computations with Python works but there were issues with either generating the report using pdflatex and even opening the resulting pdf with the pdf-reader evince or in the case of Windows there were some mistakes in the conversion from ubuntu where certain backslashes had been converted into forward slashes. Thus, if you are running the code on Mac or Windows, you might have to modify the produced tex-report called "summary_report.tex" in the Output-folder in order to see the results.
The easiest way to get the scripts to work properly is to install anaconda. When anaconda is installed, create an environment for the project using the file "sym_sys_1st_ODEs.yml" in the following way:
"conda env create -f sym_sys_1st_ODEs.yml"
which creates an anaconda environment called "sym_sys_1st_ODEs". After this, the environment is activated with the command:
conda activate sym_sys_1st_ODEs,
or if this does not work you can activate the environment using the command
source activate sym_sys_1st_ODEs,
and this environment is deactivated using
conda deactivate.
Alternatively, all the packages could be installed manually in the following way:
conda create -n sym_sys_1st_ODEs python sympy pandas scipy
conda install -n sym_sys_1st_ODEs -c conda-forge pickle5
conda install -n sym_sys_1st_ODEs -c anaconda csvkit
conda install -n sym_sys_1st_ODEs -c anaconda more-itertools
conda install -n sym_sys_1st_ODEs -c conda-forge multiprocess