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 thetoarray
method is availablen
– dimension on state-spacek
– order of the systemord
– order of the \(p\)-th norm, for \(1 \leq p < \infty\), andp='inf'
for \(p=\infty\)
OUTPUT:
Dictionary
c
containingnorm_Fi_inf
,log_norm_F1_inf
andbeta0_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 formatN
– integer; truncation orderx0
– list; initial point
OUTPUT:
Ts
– convergence time computed from the reduced quadratic systemerror
– 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 formattarget_filename
– string with the name of the output file in MAT formatN
– truncation orderx0
– 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 formatN
– truncation orderx0
– initial point, a listTfrac
– (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’sn
– integer, system’s dimensionk
– 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 truncationF
– list, sequence of matrices \(F_j\)n
– the dimension of the state-spacek
– the order of the polynomial vector field. It is equal tolen(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 truncationinput_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)