CLUE (Constrained LUmping for differential Equations)

CLUE is a Python implementation of the algorithm from the paper ''CLUE: Exact maximal reduction of kinetic models by constrained lumping of differential equations'' (by A.Ovchinnikov, I. Pérez Verona, G. Pogudin, M. Tribastone).

This software also includes the extension of this algorithm to rational systems from the paper ''Lumping with rational rhs'' (by J. Jacob, A. Jiménez-Pastor, G. Pogudin).

What is constrained lumping?

Constrained lumping as type of exact order reduction for models defined by a system of ordinary differential equations (ODEs) with polynomial right-hand side. We will explain it using a toy example. Consider the system

$\begin{cases} \dot{x}_1 = x_2^2 + 4x_2x_3 + 4x_3^2,\ \dot{x}_2 = 4x_3 - 2x_1,\ \dot{x}_3 = x_1 + x_2 \end{cases}$

Assume that we are interested only in the dynamics of the variable $x_1$ . An example of constrained lumping in this case would be the following set of new variables

$y_1 = x_1 \quad \text{ and } y_2 = x_2 + 2x_3$

The crucial feature of these variables is their derivatives can be written in terms of $y_1$ and $y_2$ only:

$\dot{y}_1 = \dot{x}_1 = (x_2 + 2x_3)^2 = y_2^2,$

$\dot{y}_2 = \dot{x}_2 + 2\dot{x}_3 = 2x_2 + 4x_3 = 2y_2.$

Therefore, the original system can be reduced exactly to the following system while keeping the variable of interest:

$\begin{cases} \dot{y}_1 = y_2^2,\ \dot{y}_2 = 2y_2. \end{cases}$

In general, constrained lumping is an exact model reduction by linear transformation that preserves a prescribed set of linear combinations of the unknown functions. For precise definition and more details, we refer to Section 2 of the paper.

Lumping on rational systems

This software also works with differential systems. As a toy example, consider the following differential system:

$\begin{cases}\dot{x}=\frac{y}{x-y}\\dot{y}=\frac{x}{x-y}\end{cases}$

Here we can consider the new variable

$z = x - y$

and then the derivative of this variable can be wrtiten as follows:

$\dot{z} = \frac{y - x}{x - y} = 1$

What does CLUE do and how to use it?

For an interactive version of this minitutorial, see this jupyter notebook.

CLUE implements an algorithm that takes as input

a system of ODEs with polynomial or rational right-hand side
a list of linear combinations of the unknown functions to be preserved (observables)

and returns the maximal exact reduction of the system by a linear transformation that preserves given combinations.

We will demonstrate the usage of CLUE on the example above. For more details on usage including reading models from *.ode files, see tutorial (jupyter, html)

import relevant functions from sympy and the class representing systems:

from sympy import vring, QQ
from clue import FODESystem

Introduce the variables $x_1, x_2, x_3$ by defining the ring of polynomials in these variables (QQ refers to the fact that the coefficients are rational numbers, for other options see the tutorial)

R = vring(["x1", "x2", "x3"], QQ)

Construct the ODE. The right-hand sides must be in the same order as the variables on the definition of the ring

ode = FODESystem([
    x2**2 + 4 * x2 * x3 + 4 * x3**2, # derivative of x1
    4 * x3 - 2 * x1,                 # derivative of x2
    x1 + x2                          # derivative of x3
    ], variables=['x1','x2','x3'])

Call the method lumping providing the combinations to preserve, that is, [x1]

ode.lumping([x1])

You will get the following result

New variables:
y0 = x1
y1 = x2 + 2*x3
Lumped system:
y0' = y1**2
y1' = 2*y1

which is the same as we have seen earlier.

Large examples

Examples of reductions obtained over large systems appearing in the literature (including the ones discussed in the paper) are contained in the examples folder. For additional information, see readme.

Installing the software

The package CLUE can be install locally by running

pip install .

in the folder where the repository is downloaded.

clue-developers/CLUE