Control and Linear Systems tools

Created on Thu Nov 30 14:01:27 2023

@author: felipe

Functions:

`RST`(desired_eigvalues, Az, Bz[, d])
`build_Characteristic`(A, eigvalues, dt)	Build the characteristic matrix using the coefficients of the characteristic polinomy and the A matrix as independent 'variable'.
`build_Hankel`(x[, q])
`build_J`(N, r)	J matrix of Ackerman
`build_K_Ackerman`(A, B, eigvalues, dt, r[, N])	Return the Ackerman vector of gains.
`build_MC`(A, B)	Controllability matrix
`build_MO`(A, C)	Observability matrix
`build_R`(e_p, N, r[, driving_nodes])	Build the regularization matrix R for u[k]=R x[k] using pole localization.
`build_den`(eigvalues, dt)	Convolution used for polinomial product.
`build_den_noTransform`(z_eigvalues)	Convolution used for polinomial product Prodcut of all roots as [1z,-lambda] Return a polinomy of grade r+1, starting at index 0 with highest grade z^r and ending at index r in z^0
`build_num`(eigvalues, amplitudes, modes, dt)	Convolution used for polinomial product.
`build_tf_canonical`(eigvalues, amplitudes, ...)	Build the canonical controllable state-space matrices from the DMD eigvalues Omega, ampplitudes b, and modes Phi with sampling time dt :param eigvalues: eigenvalues or poles of the LTI system :type eigvalues: 1D complex array :param amplitudes: amplitudes or weights of each mode :type amplitudes: 1D float array :param modes: spatial modes from DMD decomposition of shape N x r :type modes: 2D complex array :param dt: Sampling time :type dt: float
`build_tf_diagonal`(eigvalues, amplitudes, ...)	Build the diagonal state-space matrices from the DMD eigvalues Omega, ampplitudes b, and modes Phi with sampling time dt :param eigvalues: eigenvalues or poles of the LTI system :type eigvalues: 1D complex array :param amplitudes: amplitudes or weights of each mode :type amplitudes: 1D float array :param modes: spatial modes from DMD decomposition of shape N x r :type modes: 2D complex array :param dt: Sampling time :type dt: float
`build_tf_integrator`(eigvalues, amplitudes, ...)
`c2d`(b, a, dt[, method])
`canonical_step_numerator`(num, den)	The canonical controllable form of a system with impulse response
`eval_polinomy`(polinomy, x)	Evalute the polinomy dependent in x, P(x)=p_{r}x^{r}+p_{r-1}x^{r-1}+...+p_1x+p_0.
`expand_input_matrix`(B, SC)	scale the inputs of B by the structural connectivity (delays) matrix
`expand_output_matrix`(C, SC)	scale the inputs of C by the structural connectivity (delays) matrix
`indexes_untilN_remove_m`(N, m[, zero_index])	This function returns a serie from zero_index until N-1, without m.
`lowDimensionalCC`(matrix[, target, drivers, ...])	% Function Header % Author: Remy Ben Messaoud % Function Name: low_dimensional_control_centrality % Associated Work: "Low-dimensional controllability of brain networks" % Reference: Messaoud, R.
`response_2ndOrder`(Mp, tss, dt)	Discrete time transfer function for a 2nd order system with overimpulse peak amplitude Mp and stabilization time tss.
`simulateLTI`(A, B, C, D, dt, Tend[, K, R, S, ...])
`tile_col_matrix`(B[, N])	scale the inputs of B by the structural connectivity (delays) matrix

analysis.control.RST(desired_eigvalues, Az, Bz, d=0)

analysis.control.build_Characteristic(A, eigvalues, dt)

Build the characteristic matrix using the coefficients of the characteristic polinomy and the A matrix as independent ‘variable’.

Parameters

A (2D complex array) – State-space matrix A.
eigvalues (1D complex array) – Desired poles of the matrix Phi.
dt (float) – Sampling time.

Returns

Phi – Matrix which eigenvalues correspond to ‘eigenvalues’ from a linear combination of the matrix A.

Return type

2D complex array

analysis.control.build_Hankel(x, q=None)

analysis.control.build_J(N, r)

J matrix of Ackerman

Parameters

N (int) – Observable outputs of the system.
r (int) – Number of modes/states for each output of the system.

Returns

J – Matrix of zeros with shape N x Nr, with ones at the positions n, n*r+r-1 for n in the range 0 to N.

Return type

2D float array

analysis.control.build_K_Ackerman(A, B, eigvalues, dt, r, N=1)

Return the Ackerman vector of gains.

Parameters

A (2D complex array) – State-space matrix A.
B (2D complex array) – State-space matrix B.
eigvalues (1D complex array) – Desired poles.
dt (float) – Sampling time.
r (TYPE) – Number of modes/states for each output.
N (int) – Number of outputs. The default is 1 as the A, and B matrix are the same for any of the N outputs. Also Ackerman gains are defined for systems wiht a single output.

Returns

0 if the system is no controllable
ELSE
K (1D float array) – Vector of gains of u[k]=Kx[k] to achieve the desired poles.
Phi (2D complex array) – The characteristic matrix (the desired state-space matrix A).

analysis.control.build_MC(A, B)

Controllability matrix

Parameters

A (2D float array) – State-space matrix A with shape Nr x Nr.
B (2D float array) – State-space matrix B with shape Nr x N.

Returns

Mc (2D float array) – Controllability matrix of shape Nr x Nr.
controllability (float) – Determinant of the matrix Mc. The system is controllable if and only if controllability !=0.

analysis.control.build_MO(A, C)

Observability matrix

Parameters

A (2D float array) – State-space matrix A with shape Nr x Nr.
C (2D float array) – State-space matrix B with shape N x Nr.

Returns

Mo (2D float array) – Observability matrix of shape Nr x Nr.
controllability (float) – Determinant of the matrix Mo. The system is observable if and only if observability !=0.

analysis.control.build_R(e_p, N, r, driving_nodes='all')

Build the regularization matrix R for u[k]=R x[k] using pole localization. The system representation in the state-space must be the the controllable canonical form.

Parameters

e_p (1D float array) – Difference of desired denominator coeficients - uncontrolled system denominator coeficients.
N (int) – Number of inputs.
r (int) – Number of modes.
driving_nodes (int o 1D int array, optional) – Indices of the input nodes. The default is ‘all’.

Returns

R – Regularization matrix for pole localization.

Return type

2 float array

analysis.control.build_den(eigvalues, dt)

Convolution used for polinomial product. Prodcut of all roots as [1z,-exp(lambda*dt)] Return a polinomy of grade r+1, starting at index 0 with highest grade z^r and ending at index r in z^0 Use this is function if the roots come from the continuous representation to get the discrete representation (casual).

Parameters

eigvalues (1D complex array) –
system. (Roots of a polinomy. Usually the zeros or poles of a linear) –
dt (float) –
time (Sampling) –

Returns

den – Coeficients of the polinomy, starting for the highest grade, which roots are ‘exp(eigvalues*dt)’. [z^N z^{N-1} … z^{1} 1]

Return type

1D float array

analysis.control.build_den_noTransform(z_eigvalues)

Convolution used for polinomial product Prodcut of all roots as [1z,-lambda] Return a polinomy of grade r+1, starting at index 0 with highest grade z^r and ending at index r in z^0

Parameters

z_eigvalues (1D complex array) –
system. (Roots of a polinomy. Usually the zeros or the poles of a linear) –

Returns

den – Coeficients of the polinomy, starting for the highest grade, which roots are ‘z_eigvalues’. [z^N z^{N-1} … z^{1} 1]

Return type

1D float array

analysis.control.build_num(eigvalues, amplitudes, modes, dt)

Convolution used for polinomial product. Prodcut of all roots as b phi [1z,-exp(lambda*dt)]

Parameters

eigvalues (1D complex array) – roots of the numerator polinomy in the form
amplitudes (1D float array) – coeficients or weights of each mode
modes (2D complex array) – Spatial modes with shape N x r, where N is the number of states or outputs of the system and r is the number of modes.
dt (float) – Sampling time.

Returns

num – numerator polinomy(ies).

Return type

1D complex array

analysis.control.build_tf_canonical(eigvalues, amplitudes, modes, dt)

Build the canonical controllable state-space matrices from the DMD eigvalues Omega, ampplitudes b, and modes Phi with sampling time dt :param eigvalues: eigenvalues or poles of the LTI system :type eigvalues: 1D complex array :param amplitudes: amplitudes or weights of each mode :type amplitudes: 1D float array :param modes: spatial modes from DMD decomposition of shape N x r :type modes: 2D complex array :param dt: Sampling time :type dt: float

Returns

The linear-time invariant system
x[k+1]=Ax[k]+Bu[k]
y[k]=Cx[k]+Du[k]
A (2D float array) – Matriz A with shape Nr x Nr.
B (2D float array) – Matrix B with shape Nr x N.
C (2D float array) – Matrix C with shape N x Nr.
D (2D float array) – Matrix D with shape N x N.

analysis.control.build_tf_diagonal(eigvalues, amplitudes, modes, dt)

Build the diagonal state-space matrices from the DMD eigvalues Omega, ampplitudes b, and modes Phi with sampling time dt :param eigvalues: eigenvalues or poles of the LTI system :type eigvalues: 1D complex array :param amplitudes: amplitudes or weights of each mode :type amplitudes: 1D float array :param modes: spatial modes from DMD decomposition of shape N x r :type modes: 2D complex array :param dt: Sampling time :type dt: float

Returns

The linear-time invariant system
x[k+1]=Ax[k]+Bu[k]
y[k]=Cx[k]+Du[k]
A (2D complex array) – Matriz A with shape Nr x Nr.
B (2D float array) – Matrix B with shape Nr x N.
C (2D complex array) – Matrix C with shape N x Nr.
D (2D float array) – Matrix D with shape N x N.

analysis.control.build_tf_integrator(eigvalues, amplitudes, modes, dt)

analysis.control.c2d(b, a, dt, method='zoh')

analysis.control.canonical_step_numerator(num, den)

The canonical controllable form of a system with impulse response b_0 +

rac{b_1 z^{-1} +b_2 z^{-2}+ … +b_{r-1}z^{r-1}}{1+a_1 z^{-1} +a_2 z^{-2}+ … +a_{r-1}z^{r-1}}

is the state-space matrix representation x[k+1]=Ax[k]+Bu[k], y[k]=Cx[k]+Du[k] with A=[[0 1 0 … 0],[0 0 1 … 0], …,[0 0 … 1],[-a_{r-1} -a_{r-2} … -a_1]] B=[0, 0, 0, 0, …, b_0] C=[ b_{r-1} b_{r-2} … b_1] D=[b_0]

However, is more usual to have the linear IIR filter representation Y(z)=B’(Z)/A(Z) X(Z), then we need to recalculate the numerator polinomy coefficients to get the canonical B(z).

Parameters

num1D complex array: coefficients of the numerator polinomy
den1D complex array: coefficients of the denominatro polinomy

Returns

num_canon1D complex array: Canonical numerator [b_1, b_2, …, b_{r-1}]
num_indcomplex: Independent term of the states, or the element of the matrix D (external input weight)

analysis.control.eval_polinomy(polinomy, x)

Evalute the polinomy dependent in x, P(x)=p_{r}x^{r}+p_{r-1}x^{r-1}+…+p_1x+p_0.

Parameters

polinomy (1D complex array) – Coefficients of the polinomy.
x (complex) – Value of x to evalaute P(x).

Returns

value – Value of P(x).

Return type

complex

analysis.control.expand_input_matrix(B, SC): scale the inputs of B by the structural connectivity (delays) matrix

analysis.control.expand_output_matrix(C, SC): scale the inputs of C by the structural connectivity (delays) matrix

analysis.control.indexes_untilN_remove_m(N, m, zero_index=0)

This function returns a serie from zero_index until N-1, without m. Useful to select all but one element from an array. Python indexing: range from 0 to N is the natural numbers’ serie from 0 to N-1

Example 1: indexes_untilN_remove_m(N=5,m=2,zero_index=0) returns [0,1,3,4] Example 2: indexes_untilN_remove_m(N=6,m=4,zero_index=2) returns [2,3,5]

Parameters

N (int) – Final value of the serie.
m (int) – Element to remove
zero_index (int, optional) – The starting number of the serie. The default is 0.

Returns

indexes – A list with N-zero_index-1 elements starting at ‘zero_index’, finishing at ‘N-1’, and without ‘m’.

Return type

list

analysis.control.lowDimensionalCC(matrix, target=None, drivers=None, r_dim=5)

% Function Header % Author: Remy Ben Messaoud % Function Name: low_dimensional_control_centrality % Associated Work: “Low-dimensional controllability of brain networks” % Reference: Messaoud, R. B., Du, V. L., Kaufmann, B. C., Couvy-Duchesne, B., Migliaccio, L., Bartolomeo, P., … & Fallani, F. D. V. (2023). Low-dimensional controllability of brain networks. arXiv preprint arXiv:2311.11132. % Description: Translated to Python 3.8 by Felipe A. Torres

Parameters

matrix (2D float Array) – Adjacency matrix of the network
target (1D int array) – Vector of indices of nodes composing the target network. Default: The entire network
drivers (1D int array) – Vector of indices of nodes to to check as drivers and compute their control centrality. Default: The entire network
r_dim (TYPE) – The low-dimension of the output control, i. e. number of eigenmaps. Default r_dim=5.

Returns

lowCC – vector of size 1xnDrivers that returns the low-dimensional control centrality for each driver.

Return type

1D float array

analysis.control.response_2ndOrder(Mp, tss, dt)

Discrete time transfer function for a 2nd order system with overimpulse peak amplitude Mp and stabilization time tss. Using dt as sampling time.

Parameters

Mp (float) – Overimpulse peak amplitude.
tss (float) – stabilization time.
dt (float) – sampling time.

Returns

b (1D float array) – Numerator coeffcients of the system.
a (1D float array) – Denominator coeficcient of the system.

analysis.control.simulateLTI(A, B, C, D, dt, Tend, K=None, R=None, S=None, T=None, u=None, r=None, x_init=None)

analysis.control.tile_col_matrix(B, N=90): scale the inputs of B by the structural connectivity (delays) matrix