BareStateSpace

Defined in module: wield.control.ss_bare.ss.BareStateSpace

class BareStateSpace(A, B, C, D, E, *, hermitian: bool = True, time_symm: bool = False, flags={}, algorithm_choices=None, algorithm_ranking=None, dt=None)

Bases: object

State space class to represent MIMO Transfer functions using dense matrix representations

This class uses raw matrix representations and should not generally be used by users.

It is used internally by the SISO.SISOStateSpace and MIMO.MIMOStateSpace classes

__init__(A, B, C, D, E, *, hermitian: bool = True, time_symm: bool = False, flags={}, algorithm_choices=None, algorithm_ranking=None, dt=None)

Methods

L2_norm([mode, scale, tol])	Using slycot ab13dd Return objects: The L2 or H2 norm of the system
Linf_norm([scale, tol])	Using slycot ab13dd Return objects: gpeak : float The L-infinity norm of the system, i.e., the peak gain of the frequency response (as measured by the largest singular value in the MIMO case). fpeak : float The frequency where the gain of the frequency response achieves its peak value gpeak, i.e.,.
__init__(A, B, C, D, E, *[, hermitian, ...])
adjoint()	Return the transpose and conjugate (time-reversal) of the system TODO, adjust flags
balance([permute, which, Bidx, Cidx, Dl, ...])	Return a version of this statespace where A has been balanced for numerical stability.
balanceABC([which])	Uses the slycot balancer tb01id or tg01ad
balance_and_truncate([rescale_io])
balance_and_truncate_unscaled([method, nr, ...])	To compute a reduced order model (Ar,Br,Cr,Dr) for an original state-space representation (A,B,C,D) by using either the square-root or the balancing-free square-root Singular Perturbation Approximation (SPA) model reduction method for the alpha-stable part of the system.
balance_grammian([which, pow2])	which must be 'b' to balance on both evenly or 'c' for controllable, or 'o' for observable.
block_diagonalize([condition_number, ...])
conjugate()
covariance_chol_inputs([already_Schur])	Return the covariance matrix of the statespace system outputs as cholesky factors.
covariance_chol_outputs([already_Schur])	Return the covariance matrix of the statespace system outputs as cholesky factors.
feedbackD(D[, concentrate])	Feedback linkage for a single statespace.
feedbackDE(D)	Feedback linkage for a single statespace.
fresponse_raw(*[, f, w, s, z, use_laub])
fromD(D)
gramian_chol_inputs([already_Schur])	Utilize slycot sb03od to compute the upper-triangular cholesky factor U of the input gramian X=UU' where XA+A'X + BB' = 0
gramian_chol_outputs([already_Schur])	Utilize slycot sb03od to compute the upper-triangual cholesky factor U of the output gramian X=UU' where XA'+XA + C'C = 0
grammian_order_reduction([method, Bidx, ...])
inv()	Invert statespace, by converting to a descriptor system
inv_proper()	Invert statespace, assuming that the D matrix is full rank
is_square()
minreal([job, scale, rescale_in, ...])	Calculate a minimal realization, removes unobservable and uncontrollable states.
permute_UT()	TODO remove
print_nonzero()
reduceE([invertE])	Utilize slycot tg01fd to reduce the statespace to a simpler form
reduceE2()	Utilize slycot tg01gd to reduce the statespace to a simpler form
reduceE3()	Utilize slycot tg01gd to reduce the statespace to a simpler form
rescale()	performs a naive rescale of the columns and rows of A and E to make them order-1
scale_io(idx_in, scale_in, idx_out, scale_out)	Scale input and output IO
schur_form([exact, sort, invertE])	Return a version of this statespace where A has been converted to a Schur triangular form.
set_algorithm_choices(algorithm_choices)
similarity_diagonal(D[, direction])	Apply a diagonal similarity transform from the left.
similarity_triangular_left(S[, avg])	Apply a triangular matrix as a similarity transform.
similarity_triangular_right(S[, avg])	Apply a triangular matrix as a similarity transform.
square_size()
stochastic_balance_and_truncate([method, ...])	To compute a reduced order model (Ar,Br,Cr,Dr) for an original state-space representation (A,B,C,D) by using either the square-root or the balancing-free square-root Singular Perturbation Approximation (SPA) model reduction method for the alpha-stable part of the system.
time_reversal()	Return the time reversal of the system
topological_sort()	Apply a topological sort to the state matrices A and E.
transpose()	Return the transpose of the system

Attributes

ABCD
ABCDE
ABCDe
Ninputs
Noutputs
Nstates
as_controlLTI
e
p
poles

set_algorithm_choices(algorithm_choices)

classmethod fromD(D)

property ABCDE

property e

property ABCDe

property Ninputs

property Noutputs

property Nstates

property as_controlLTI

property ABCD

time_reversal()

Return the time reversal of the system

TODO, adjust flags

conjugate()

transpose()

Return the transpose of the system

TODO, adjust flags

adjoint()

Return the transpose and conjugate (time-reversal) of the system TODO, adjust flags

print_nonzero()

property poles

property p

fresponse_raw(*, f=None, w=None, s=None, z=None, use_laub=True, **kwargs)

reduceE(invertE=True)

Utilize slycot tg01fd to reduce the statespace to a simpler form

reduceE2()

Utilize slycot tg01gd to reduce the statespace to a simpler form

reduceE3()

Utilize slycot tg01gd to reduce the statespace to a simpler form

similarity_diagonal(D, direction='left')

Apply a diagonal similarity transform from the left. D should be a list.

B’ = D @ B A’ = D @ A @ D^{-1} C’ = C @ D^{-1}

similarity_triangular_left(S, avg=True)

Apply a triangular matrix as a similarity transform.

This applies the similarity matrix ‘S’ multiplying from the left,

B’ = S @ B A’ = S @ A @ S^{-1} C’ = C @ S^{-1}

Assumes that the triangular matrix is upper

similarity_triangular_right(S, avg=True)

Apply a triangular matrix as a similarity transform.

This

B’ = S^{-1} @ B A’ = S^{-1} @ A @ S C’ = C @ S

Assumes that the triangular matrix is upper

gramian_chol_inputs(already_Schur=False)

Utilize slycot sb03od to compute the upper-triangular cholesky factor U of the input gramian X=UU’ where XA+A’X + BB’ = 0

returns: Bunch(U:np.array, scale:float)

the actual results is U*scale, but is factored to prevent overflow.

TODO: The already_Schur flag indicates that the system matrix is already factored to Schur form. This flag should be maintained within the statespace system.

NOTE! this can only be called on stable systems

gramian_chol_outputs(already_Schur=False)

Utilize slycot sb03od to compute the upper-triangual cholesky factor U of the output gramian X=UU’ where XA’+XA + C’C = 0

returns: Bunch(U:np.array, scale:float)

the actual results is U*scale, but is factored to prevent overflow

NOTE: this outputs a lower-triangular matrix

TODO: The already_Schur flag indicates that the system matrix is already factored to Schur form. This flag should be maintained within the statespace system.

NOTE! this can only be called on stable systems

covariance_chol_outputs(already_Schur=False)

Return the covariance matrix of the statespace system outputs as cholesky factors.

computed using Cov_u = C @ (self.gramian_chol_inputs.U*scale)

returns: Cov_u

the basis of rows of the output upper triangular matrix is given by self.outputs. The covariance matrix can be constructed using Cov_u @ Cov_u’

TODO: test iterative rescaling where the grammian diagonal is scaled near one to see if it improves. It may avoid the need (i.e. provide an alternative to) cholesky decomposition, allowing the use of the scipy/lapack solver

covariance_chol_inputs(already_Schur=False)

Return the covariance matrix of the statespace system outputs as cholesky factors.

computed using Cov_u = C @ (self.gramian_chol_inputs.U*scale)

returns: Cov_u

the basis of rows of the output upper triangular matrix is given by self.outputs. The covariance matrix can be constructed using Cov_u @ Cov_u’

TODO: test iterative rescaling where the grammian diagonal is scaled near one to see if it improves. It may avoid the need (i.e. provide an alternative to) cholesky decomposition, allowing the use of the scipy/lapack solver

balanceABC(which='A')

Uses the slycot balancer tb01id or tg01ad

https://github.com/python-control/Slycot/blob/master/slycot/transform.py#L25

NOTE: there seems to be an error where it is giving bad output except for which=ABC TODO, move to balance_method.py

topological_sort()

Apply a topological sort to the state matrices A and E. This is particularly useful after making new connections, to best preserve an upper-triangular form.

TODO: add permutation heuristics for the strongly-connected components as well.

rescale()

performs a naive rescale of the columns and rows of A and E to make them order-1

balance(permute=False, which='ABC', Bidx=None, Cidx=None, Dl=None, Dr=None, as_descriptor=False)

Return a version of this statespace where A has been balanced for numerical stability.

as_descriptor : bool defaults False, will promote the statespace to descriptor form, as it forces left/right unequal balancing that will make E non-identity.

Dl and Dr are arrays for the left and right diagonal balancing (may not be inverses if treated as a descriptor system). This array should have length self.Nstates. It is modified in-place to report the balancing.

scale_io(idx_in, scale_in, idx_out, scale_out)

Scale input and output IO

grammian_order_reduction(method='sqrt', Bidx=None, Cidx=None, nr=None, tol=0)

balance_grammian(which='b', pow2=True)

which must be ‘b’ to balance on both evenly or ‘c’ for controllable, or ‘o’ for observable.

c or o will cause the diagonals of the respective gramians to become 1 or close to 1. b will cause the diagonals of both grammians to be the same and generally smaller.

pow2 is whether to round to the nearest power of two (recommended).

Note that this currently doesn’t check if system is stable and will fail if unstable modes are present.

schur_form(exact=False, sort=None, invertE=False)

Return a version of this statespace where A has been converted to a Schur triangular form.

if exact is False, then it applies the Schur and keeps the small lower diagonal terms.

block_diagonalize(condition_number=1000000000000.0, Tright=None, debug_printing=False)

permute_UT()

TODO remove

stochastic_balance_and_truncate(method='bfsqrt', equil=True, nr=None, alpha=None, beta=0.0001, tol1=0, tol2=0)

To compute a reduced order model (Ar,Br,Cr,Dr) for an original state-space representation (A,B,C,D) by using either the square-root or the balancing-free square-root Singular Perturbation Approximation (SPA) model reduction method for the alpha-stable part of the system. - From SLYCOT Documentation for ab09nd

Parameters:

• sys (Bunch) – Bunch system with mod as attribute

• method (str, optional) – Method to use for balancing. ‘sqrt’: use the square-root SPA method. ‘bfsqrt’: use the balancing-free square-root SPA method. Defaults to ‘sqrt’.

• equil (bool, optional) – If True, preliminarily equilibrates the triplet (A,B,C). Defaults to True.

• iod (dict, optional) – input/output dictionary. Defaults to None.

Returns:

a similar StateSpace

balance_and_truncate_unscaled(method='sqrt', nr=None, alpha=None, equil=True, tol1=0, tol2=0)

To compute a reduced order model (Ar,Br,Cr,Dr) for an original state-space representation (A,B,C,D) by using either the square-root or the balancing-free square-root Singular Perturbation Approximation (SPA) model reduction method for the alpha-stable part of the system. - From SLYCOT Documentation for ab09nd

Parameters:

• sys (Bunch) – Bunch system with mod as attribute

• method (str, optional) – Method to use for balancing. ‘sqrt’: use the square-root SPA method. ‘bfsqrt’: use the balancing-free square-root SPA method. Defaults to ‘sqrt’.

• equil (bool, optional) – If True, preliminarily equilibrates the triplet (A,B,C). Defaults to True.

• iod (dict, optional) – input/output dictionary. Defaults to None.

Returns:

a similar StateSpace

balance_and_truncate(rescale_io=True, **kwargs)

minreal(job='minimal', scale=True, rescale_in=False, rescale_out=False, which_in=None, which_out=None, tol=None, as_descriptor=None)

Calculate a minimal realization, removes unobservable and uncontrollable states.

which_in: None or a set of inputs to utilize (not yet implemented TODO) which_out: None or a set of outputs to utilize (not yet implemented TODO)

Standard statespace code originally from python-control.

Descriptor statespace code using tg01jd is new to wield.control

L2_norm(mode='L2', scale=True, tol=1e-14)

Using slycot ab13dd Return objects:

The L2 or H2 norm of the system

Does not work with descriptor systems

Linf_norm(scale=True, tol=1e-10)

Using slycot ab13dd Return objects:

gpeakfloat

The L-infinity norm of the system, i.e., the peak gain of the frequency response (as measured by the largest singular value in the MIMO case).

fpeakfloat

The frequency where the gain of the frequency response achieves its peak value gpeak, i.e.,

|| G ( j*fpeak ) || = gpeak , if dico = ‘C’, or

j*fpeak

|| G ( e ) || = gpeak , if dico = ‘D’.

Works with descriptor systems

feedbackD(D, concentrate=False)

Feedback linkage for a single statespace.

concentrate attempts an experimental method to sum the connections in a numerically preferred basis

feedbackDE(D)

Feedback linkage for a single statespace.

extend the space and uses descriptor methods, thus extends the A and E matrices.

TODO, rearrange D to minimize rank (or make another function that calls this one). Such a rearrangement can require a rank determination.

is_square()

square_size()

inv_proper()

Invert statespace, assuming that the D matrix is full rank

inv()

Invert statespace, by converting to a descriptor system