GPoM : Generate

Convention used to describe a polynomial

The polynomial description is based on a convention defined in the function regOrd that provides the order of the polynomial terms. This convention depends on the model dimension (that is the number nVar of state variables), and on the maximum polynomial degree chosen for the formulation (defined by the parameter dMax). This order can be visualized with the regLabs function. For instance, for nVar = 3 and dMax = 2, the convention used to formulate a polynomial will be as follows:

    poLabs(nVar = 3, dMax = 2)

##  [1] "ct"     "X3 "    "X3^2 "  "X2 "    "X2 X3 " "X2^2 "  "X1 "   
##  [8] "X1 X3 " "X1 X2 " "X1^2 "

This formulation has pMax = 10 terms:

    pMax =  d2pMax(nVar, dMax)

Based on this convention, one single ordinary differential equation (ODE) in polynomial form with nVar variables and of maximum polynomial degree dMax can be formulated as one single vector using the convention given by regOrd(nVar, dMax). As an example, the equation :

\(dX_1/dt = 1 + 2 X_1 - 3 X_1X_3 + 4 X_2^2\)

has three variables (it requires at least nVar = 3) and is of maximum polynomial degree two (it requires at least dMax = 2). Following the convention defined by regLabs(nVar = 3, dMax = 2), it will require the definition of the following vector of parameter:

    param <- c(1, 0, 0, 0, 0, 4, 2, -3, 0, 0)

Indeed:

    nVar = 3
    dMax = 2
    cbind(param, poLabs(nVar, dMax))

##       param         
##  [1,] "1"   "ct"    
##  [2,] "0"   "X3 "   
##  [3,] "0"   "X3^2 " 
##  [4,] "0"   "X2 "   
##  [5,] "0"   "X2 X3 "
##  [6,] "4"   "X2^2 " 
##  [7,] "2"   "X1 "   
##  [8,] "-3"  "X1 X3 "
##  [9,] "0"   "X1 X2 "
## [10,] "0"   "X1^2 "

The same convention will be used for any other equations. Note that, by default, notation is X. However, to facilitate the analysis, alternative notations may also be used using the optional parameter Xnote:

  poLabs(3, 2, Xnote = 'y')

##  [1] "ct"     "y3 "    "y3^2 "  "y2 "    "y2 y3 " "y2^2 "  "y1 "   
##  [8] "y1 y3 " "y1 y2 " "y1^2 "

or also:

  poLabs(3, 2, Xnote = c('x','W','y'))

##  [1] "ct"     "y3 "    "y3^2 "  "W2 "    "W2 y3 " "W2^2 "  "x1 "   
##  [8] "x1 y3 " "x1 W2 " "x1^2 "

Definition of a set of polynomial ODE

A set of \(N\) equations will thus require the definition of \(N\) parameter vectors and will thus be represented as a matrix of pMax lines by nVar columns. For example, the Rössler system¹ is defined by a set of three equations

\(dx/dt = - y - z\)

\(dy/dt = x + a y\)

\(dz/dt = b + z (x - c)\).

For \((a = 0.52, b = 2, c = 4)\), this system can be decribed by a matrix M built as follows:

    # parameters
    a = 0.52
    b = 2
    c = 4
    # equations
    Eq1 <- c(0,-1, 0,-1, 0, 0, 0, 0, 0, 0)
    Eq2 <- c(0, 0, 0, a, 0, 0, 1, 0, 0, 0)
    Eq3 <- c(b,-c, 0, 0, 0, 0, 0, 1, 0, 0)

The model formulation is obtained by concatenating the vectors of the three equations into the matrix K that contains all the coefficients of the model:

    K = cbind(Eq1, Eq2, Eq3)

The corresponding model equations can be edited in a mathematical form using the function visuEq()

    visuEq(nVar, dMax, K)

## dX1/dt = -X3  -X2  
## 
## dX2/dt = 0.52 X2  + X1  
## 
## dX3/dt = 2  -4 X3  + X1 X3

By default, the notation used in GPoM is X with an index, such as X1, X2, etc. Alternative notation can be used to edit the equations with the visuEq function by using the option parameter substit. For substit = 1, single letters are automatically chosen such as

    visuEq(nVar, dMax, K, substit = 1)

## dx/dt = -z  -y  
## 
## dy/dt = 0.52 y  + x  
## 
## dz/dt = 2  -4 z  + x z

The notation can be defined also manually, such as:

    visuEq(nVar, dMax, K, substit = c("U", "V", "W"))

## dU/dt = -W  -V  
## 
## dV/dt = 0.52 V  + U  
## 
## dW/dt = 2  -4 W  + U W

Numerical integration

The numerical integration of model M can be done using the numicano function that requires the use of the external package deSolve. The following parameters are required:

    # The initial conditions of the system variables
    v0 <- c(-0.6, 0.6, 0.4)
    # the model formulation K (see former section)
    # the number of integration steps `Istep`
    # the time step length `onestep`
    # the model dimension `nVar`
    # the maximum polynomial degree `dMax`

The numerical integration is launched as follows:

    outNumi <- numicano(nVar, dMax, Istep = 5000, onestep = 1/50, KL = K, v0 = v0)

The output of the function numicano is a list that contains (1) $K a memory of the model parameters

    outNumi$K

from which nVar and dMax (required to reformulate the equations) can be retrieved

    # nVar
    dim(outNumi$K)[2]
    # dMax
    pMax <- dim(outNumi$K)[1]
    p2dMax(nVar, pMaxKnown = pMax)

and (2) the simulations $reconstr. This matrix contains nVar + 1 columns. The first one is the time, the other ones correspond to the variables of the system \((X_1, X_2, X_3, ...)\) that is \((x,y,z)\) in our case.

Note that all other input parameters used in numicano can be retrieved from these output conditions:

    # initial conditions
    head(outNumi$reconstr, 1)[2:(nVar+1)]
    # time step
    diff(outNumi$reconstr[1:2,1])
    # number of integration time step
    dim(outNumi$reconstr)[1]

The simulated time series can be plotted as follows:

    plot(outNumi$reconstr[,1], outNumi$reconstr[,2], type='l',
          main='time series', xlab='t', ylab = 'x(t)')

and the plot of the phase portrait aswell:

  plot(outNumi$reconstr[,2], outNumi$reconstr[,3], type='l',
     main='phase portrait', xlab='x(t)', ylab = 'y(t)')

Next steps

The aim of the GPoM package is to retreive ODEs from time series using global modelling. Such type of modelling can require a careful data preprocessing. Simple examples of preprocessing are given in the next vignette II_Preprocessing. Examples for applying global modelling from time series will be presented in vignette III_Modelling.