Available Transformations

Carleman linearization of polynomial differential equations in SageMath.

Reduction methods

quadratic_reduction() Reduce from any order in standard form to quadratic order
transfer_matrices() Compute the higher order transfer matrices \(A^{i}_{i+j-1}\)

Linearization

linearize() Compute Carleman linearization and export to a MAT file
truncated_matrix() Finite order \(N\) Carleman linearization

Kronecker power and linear algebra

get_index_from_key() Return first occurrence of given key over a Kronecker power
get_key_from_index() Return multi-index of Kronecker power given an index and the order
kron_prod() Compute the Kronecker product of x and y
kron_power() Receives a \(n\times 1\) vector and computes its Kronecker power \(x^{[i]}\)
log_norm() Compute the logarithmic norm of a matrix

Error computation

characteristics() Information about the norms of the matrices in \(F\)
error_function() Compute the error function of a truncated ODE
plot_error_function() Plot the estimated error of the linearized ODE as a function of time

AUTHOR:

  • Marcelo Forets (Dec 2016 at VERIMAG - France)

MF acknowledges the hospitality at Max-Planck Institute for Software Systems, Saarbrucken, Germany, where part of this package was written (Apr 2016).

carlin.transformation.characteristics(F, n, k, ord=inf)

Information about the norms of the matrices in \(F\).

INPUT:

  • F – list of matrices in some NumPy sparse format, for which the toarray method is available
  • n – dimension on state-space
  • k – order of the system
  • ord – order of the \(p\)-th norm, for \(1 \leq p < \infty\), and p='inf' for \(p=\infty\)

OUTPUT:

Dictionary c containing norm_Fi_inf, log_norm_F1_inf and beta0_const.

carlin.transformation.error_function(model, N, x0)

Compute the error function of a truncated ODE.

INPUT:

  • model – Polynomial ODE or string containing the model in text format
  • N – integer; truncation order
  • x0 – list; initial point

OUTPUT:

  • Ts – convergence time computed from the reduced quadratic system
  • error – function of \(t\), the estimated truncation error in the supremum norm

EXAMPLES:

sage: from carlin.transformation import error_function
sage: from carlin.library import quadratic_scalar as P
sage: Ts, error = error_function(P(0.5, 2), 2, [0, 0.5])
sage: Ts
0.8109...
sage: error
0.5*(2.0*e^(0.5*t) - 2.0)^2*e^(0.5*t)/(-2.0*e^(0.5*t) + 3.0)
carlin.transformation.linearize(model, target_filename, N, x0, **kwargs)

Compute Carleman linearization and export to a MAT file.

INPUT:

  • mode – model as a PolynomialODE or a string containing the model in text format
  • target_filename – string with the name of the output file in MAT format
  • N – truncation order
  • x0 – initial point, can be either a list or a polyhedron; see the code for further details

NOTES:

This function is self-contained; it transforms to canonical quadratic form, then computes Carleman linearization together with the error estimates and exports the resulting matrix \(A_N\) and characteristics to a MAT file.

carlin.transformation.plot_error_function(model_filename, N, x0, Tfrac=0.8)

Plot the estimated error of the linearized ODE as a function of time.

INPUT:

  • model_filename – string containing the model in text format
  • N – truncation order
  • x0 – initial point, a list
  • Tfrac – (optional, default: \(0.8\)): fraction of the convergence radius, to specify the plotting range in the time axis

NOTE:

This function calls error_function for the error computations.

carlin.transformation.quadratic_reduction(F, n, k)

Reduce a \(k\)-th order system of polynomial ODE’s into a quadratic one.

INPUT:

  • F – list of matrices defining the system of polynomial ODE’s
  • n – integer, system’s dimension
  • k – integer, order of the polynomial ODE

OUTPUT:

The list [F_tilde, nquad, kquad] corresponding to the reduced list of \(F_j\)‘s, dimension and order respectively.

EXAMPLES:

Consider the following two-dimensional system:

sage: from carlin.library import quadratic_scalar
sage: P = quadratic_scalar(1, -1); P.funcs()
[-x0^2 + x0]
sage: from carlin.io import get_Fj_from_model
sage: (F, n, k) = get_Fj_from_model(P.funcs(), P.dim(), P.degree())
sage: (n, k)
(1, 2)
sage: [matrix(Fi.toarray()) for Fi in F]
[[1.0], [-1.0]]

Since it is already quadratic, the reduction does nothing:

sage: from carlin.transformation import quadratic_reduction
sage: (Fred, nred, kred) = quadratic_reduction(F, n, k)
sage: nred, kred
(1, 2)
sage: [matrix(Fi.toarray()) for Fi in F]
[[1.0], [-1.0]]

Now consider the more interesting case of a cubic system:

sage: from carlin.library import cubic_scalar
sage: P = cubic_scalar(1, -1); P.funcs()
[-x0^3 + x0]
sage: from carlin.io import get_Fj_from_model
sage: (F, n, k) = get_Fj_from_model(P.funcs(), P.dim(), P.degree())
sage: (n, k)
(1, 3)
sage: [matrix(Fi.toarray()) for Fi in F]
[[1.0], [0.0], [-1.0]]

Introducing the auxiliary variables \(\tilde{x}_1 := x\) and \(\tilde{x}_2:=x^2\), the corresponding quadratic system in \(\tilde{x} := (\tilde{x}_1, \tilde{x}_2)\) is:

sage: (Fred, nred, kred) = quadratic_reduction(F, n, k)
sage: nred, kred
(2, 2)
sage: matrix(Fred[0].toarray())
[1.0  0.0]
[0.0  2.0]
sage: matrix(Fred[1].toarray())
[ 0.0 -1.0  0.0  0.0]
[ 0.0  0.0  0.0 -2.0]
carlin.transformation.transfer_matrices(N, F, n, k)

Higher order transfer matrices \(A^{i}_{i+j-1}\).

INPUT:

  • N – order of truncation
  • F – list, sequence of matrices \(F_j\)
  • n – the dimension of the state-space
  • k – the order of the polynomial vector field. It is equal to len(F)

OUTPUT:

  • A – the transfer matrices \(A^{i}_{i+j-1}\) that correspond to \(i = 1, \ldots, N\).

    It is given as a list of lists. Each inner list has dimension \(k\).

carlin.transformation.truncated_matrix(N, *args, **kwargs)

Finite order Carleman linearization.

INPUT:

  • N – order of truncation
  • input_format – valid options are:
    • 'model_filename' – (default); file in text format
    • 'transfer_matrices' – for \((A, n, k)\), which should be given separately
    • 'Fj_matrices' – for \((F, n, k)\), which should be given separately

OUTPUT:

The transfer matrices \(A^{i}_{i+j-1}\) that correspond to \(i = 1, \ldots, N\). It is given as a list of lists, and each inner list has dimension \(k\).

EXAMPLES:

Conisder the polynomial ODE:

sage: from carlin.polynomial_ode import PolynomialODE
sage: x = polygens(QQ, ["x0", "x1"])
sage: f = [x[0]^3*x[1], -2*x[0]+2*x[1]^2]
sage: P = PolynomialODE(f, 2, 4)

Compute the Carleman matrix arising from linearization at order \(N=2\):

sage: from carlin.transformation import get_Fj_from_model, truncated_matrix
sage: Fj = get_Fj_from_model(P.funcs(), P.dim(), P.degree())
sage: matrix(truncated_matrix(2, *Fj, input_format="Fj_matrices").toarray())
[ 0.0  0.0  0.0  0.0  0.0  0.0]
[-2.0  0.0  0.0  0.0  0.0  2.0]
[ 0.0  0.0  0.0  0.0  0.0  0.0]
[ 0.0  0.0 -2.0  0.0  0.0  0.0]
[ 0.0  0.0 -2.0  0.0  0.0  0.0]
[ 0.0  0.0  0.0 -2.0 -2.0  0.0]

Try a higher truncation order:

sage: matrix(truncated_matrix(4, *Fj, input_format="Fj_matrices").toarray())
30 x 30 dense matrix over Real Double Field (use the '.str()' method to see the entries)