Handling Input/Output

Carleman linearization input/output functions.

Load and export polynomial ODEs

export_model_to_mat() Export model to a MAT file as the sequence of sparse \(F_j\) matrices
load_model() Read an ODE system from a text file

Transformation functions

get_Fj_from_model() Transform a model into standard form as a sum of Kronecker products

Solve polynomial ODEs

solve_ode_exp() Solve Carleman linearized ODE.
plot_truncated() Solve and return the graphics in phase space.

AUTHOR:

  • Marcelo Forets (Dec 2016 at VERIMAG - UGA)
carlin.io.export_model_to_mat(model_filename, F=None, n=None, k=None, **kwargs)

Export ODE model to a Matlab .mat format.

INPUT:

The model can be given either as a model in text file, or as the tuple \((F, n, k)\).

  • model_filename – string with the model filename. If \((F, n, k)\) is not provided, then such model should be reachable from the current path
  • F – list of sparse matrices \(F_1, \ldots, F_k\)
  • n – dimension of state-space
  • k – order of the system

OUTPUT:

List containing the solution of the 1st order ODE \(x'(t) = A_N x(t)\), with initial condition \(x(0) = x_0\). The output filename is model_filename, replacing the .sage extension with the .mat extension.

carlin.io.get_Fj_from_model(model_filename=None, f=None, n=None, k=None)

Transform an input model of a polynomial vector field into standard form as a sum of Kronecker products.

The model can be given either as an external file (model_filename), or as the data \(f\), \(n\) and \(k\).

INPUT:

  • model_filename – string containing the filename

OUTPUT:

  • F – list of sparse matrices \(F_1, \ldots, F_k\). These are formatted in dictionary-of-keys (dok) form.
  • n – dimension of the state-space of the system
  • k – degree of the system

EXAMPLES:

Let’s create a two-dimensional system of second order:

sage: x = polygens(QQ, ['x0', 'x1'])
sage: f = [-2*x[0] + x[1] + x[0]**2, x[0] + 3/2*x[0]*x[1]]
sage: from carlin.polynomial_ode import PolynomialODE
sage: T = PolynomialODE(f, 2, 2); T
A Polynomial ODE in n = 2 variables

There are two \(F_j\) matrices in sparse representation, which can be visualizeda with the toarray method:

 sage: from carlin.io import get_Fj_from_model
 sage: F, _, _ = get_Fj_from_model(T.funcs(), T.dim(), T.degree())
 sage: F
 [<2x2 sparse matrix of type '<type 'numpy.float64'>'
         with 3 stored elements in Dictionary Of Keys format>,
  <2x4 sparse matrix of type '<type 'numpy.float64'>'
         with 2 stored elements in Dictionary Of Keys format>]
 sage: F[0].toarray()
 array([[-2.,  1.],
        [ 1.,  0.]])
sage: F[1].toarray()
array([[ 1. ,  0. ,  0. ,  0. ],
       [ 0. ,  1.5,  0. ,  0. ]])

TESTS:

Check if a polynomial with a non-numeric coefficient is allowed:

sage: from carlin.io import get_Fj_from_model sage: x = polygens(QQ, [“x0”]); mu = SR.var(“mu”) sage: from carlin.polynomial_ode import PolynomialODE sage: T = PolynomialODE([mu*x[0]^2 - x[0]], 1, 2) sage: get_Fj_from_model(T.funcs(), T.dim(), T.degree()) Traceback (most recent call last): ... NotImplementedError: the coefficients of the polynomial should be numeric

carlin.io.load_model(model_filename)

Read an input ODE system.

INPUT:

  • model_filename – string with the model filename

OUTPUT:

  • f – list of multivariate polynomials which describes the system of ODEs, each component in the polynomial ring \(\mathbb{Q}[x_1,\ldots,x_n]\)
  • n – integer, dimension of f
  • k – integer, degree of f
carlin.io.plot_truncated(model, N, x0, tini, T, NPOINTS, xcoord=0, ycoord=1, **kwargs)

Solve and return graphics in phase space of a given model.

INPUT:

  • model – PolynomialODE, defining the tuple \((f, n, k)\)
  • N – integer; truncation order
  • x0 – vector; initial condition
  • tini – initial time of simulation
  • T – final time of simulation
  • NPOINTS – number of points sampled
  • xcoord – (default: \(0\)), x-coordinate in plot
  • ycoord – (default: \(1\)), y coordinate in plot

NOTES:

By default, returns a plot in the plane \((x_1, x_2)\). All other keyword arguments passes are sent to the \(list_plot\) command (use to set line color, style, etc.)

EXAMPLES:

sage: from carlin.library import vanderpol
sage: from carlin.io import plot_truncated
sage: G = plot_truncated(vanderpol(1, 1), 2, [0.1, 0], 0, 5, 100)
sage: G.show(gridlines=True, axes_labels = ['$x_1$', '$x_2$']) # not tested
Graphics object consisting in 1 graphics primitive

All other keyword arguments are passed to the list_plot function. For example, specify color and maximum and minimum values for the axes:

sage: G = plot_truncated(vanderpol(1, 1), 2, [0.1, 0], 0, 5, 100, color='green', xmin=-1, xmax=1, ymin=-1, ymax=1)
sage: G.show(gridlines=True, axes_labels = ['$x_1$', '$x_2$']) # not tested
Graphics object consisting in 1 graphics primitive
carlin.io.solve_ode_exp(AN, x0, N, tini=0, T=1, NPOINTS=100)

Solve 1st order ODE with initial condition in Kronecker power form.

INPUT:

  • AN – matrix, it can be Sage dense or NumPy sparse in COO format
  • x0 – vector, initial point
  • N – integer, order of the truncation
  • tini – (optional, default: 0) initial time
  • T – (optional, default: 1) final time
  • NPOINTS – (optional, default: 100) number of points computed

OUTPUT:

List containing the solution of the 1st order ODE \(x'(t) = A_N x(t)\), with initial condition \(x(0) = x_0\). The solution is computed the matrix exponential \(e^{A_N t_i}\) directly.

NOTES:

For high-dimensional systems prefer using AN in sparse format. In this case, the matrix exponential is computed using scipy.sparse.linalg.expm_multiply.

EXAMPLES:

sage: from carlin.transformation import get_Fj_from_model, truncated_matrix
sage: from carlin.library import quadratic_scalar
sage: S = quadratic_scalar()
sage: (f, n, k) = S.funcs(), S.dim(), S.degree()
sage: Fjnk = get_Fj_from_model(f, n, k)

Consider a fourth order truncation:

sage: AN_sparse = truncated_matrix(4, *Fjnk, input_format="Fj_matrices")
sage: AN_sparse.toarray()
array([[ 1.,  1.,  0.,  0.],
       [ 0.,  2.,  2.,  0.],
       [ 0.,  0.,  3.,  3.],
       [ 0.,  0.,  0.,  4.]])

We can solve the linear ODE using the sparse matrix AN_sparse:

sage: from carlin.io import solve_ode_exp
sage: ans = solve_ode_exp(AN_sparse, x0=[0.1], N=4, tini=0, \
            T=1, NPOINTS=20)

It can also be solved using Sage matrices (although this is often less performant, since it works with dense matrices):

sage: AN_dense = matrix(AN_sparse.toarray())
sage: ans = solve_ode_exp(AN_dense, x0=[0.1], N=4, tini=0, \
            T=1, NPOINTS=20)