diff --git a/slycot/analysis.py b/slycot/analysis.py index fb98aedb..6ab2667b 100644 --- a/slycot/analysis.py +++ b/slycot/analysis.py @@ -75,7 +75,6 @@ def ab01nd(n, m, A, B, jobz='N', tol=0, ldwork=None): Indicates whether the user wishes to accumulate in a matrix Z the orthogonal similarity transformations for reducing the system, as follows: - := 'N': Do not form Z and do not store the orthogonal transformations; (default) := 'F': Do not form Z, but store the orthogonal transformations in @@ -106,10 +105,10 @@ def ab01nd(n, m, A, B, jobz='N', tol=0, ldwork=None): indcon : int The controllability index of the controllable part of the system representation. - nblk : (n,) int ndarray + nblk : (n, ) int ndarray The leading indcon elements of this array contain the the orders of the diagonal blocks of Acont. - Z : (n,n) ndarray + Z : (n, n) ndarray - If jobz = 'I', then the leading N-by-N part of this array contains the matrix of accumulated orthogonal similarity transformations which reduces the given system to orthogonal canonical form. @@ -456,6 +455,11 @@ def ab07nd(n,m,A,B,C,D,ldwork=None): The estimated reciprocal condition number of the feedthrough matrix D of the original system. + Raises + ------ + SlycotParameterError + :info = -i: the i-th argument had an illegal value + Warns ----- SlycotResultWarning @@ -538,14 +542,14 @@ def ab08nd(n,m,p,A,B,C,D,equil='N',tol=0,ldwork=None): The number of right Kronecker indices. nkrol : int The number of left Kronecker indices. - infz : (n) ndarray + infz : (n, ) ndarray The leading dinfz elements of infz contain information on the infinite elementary divisors as follows: the system has infz(i) infinite elementary divisors of degree i, where i = 1,2,...,dinfz. - kronr :(max(n,m)+1) ndarray + kronr :(max(n,m)+1, ) ndarray the leading nkror elements of this array contain the right kronecker (column) indices. - kronl : (max(n,p)+1) ndarray + kronl : (max(n,p)+1, ) ndarray the leading nkrol elements of this array contain the left kronecker (row) indices. Af : (max(1,n+m), n+min(p,m)) ndarray @@ -644,14 +648,14 @@ def ab08nz(n, m, p, A, B, C, D, equil='N', tol=0., lzwork=None): The number of right Kronecker indices. nkrol : int The number of left Kronecker indices. - infz : (n) ndarray + infz : (n, ) ndarray The leading dinfz elements of infz contain information on the infinite elementary divisors as follows: the system has infz(i) infinite elementary divisors of degree i, where i = 1,2,...,dinfz. - kronr : (max(n,m)+1) ndarray + kronr : (max(n,m)+1, ) ndarray the leading nkror elements of this array contain the right kronecker (column) indices. - kronl : (max(n,p)+1) ndarray + kronl : (max(n,p)+1, ) ndarray the leading nkrol elements of this array contain the left kronecker (row) indices. Af : (max(1,n+m), n+min(p,m)) ndarray @@ -768,7 +772,7 @@ def ab09ad(dico,job,equil,n,m,p,A,B,C,nr=None,tol=0,ldwork=None): Cr : (p, nr) ndarray This array contains the state/output matrix `Cr` of the reduced order system. - hsv : (n) ndarray + hsv : (n, ) ndarray If ``INFO = 0``, it contains the Hankel singular values of the original system ordered decreasingly. ``HSV(1)`` is the Hankel norm of the system. @@ -896,7 +900,7 @@ def ab09ax(dico,job,n,m,p,A,B,C,nr=None,tol=0.0,ldwork=None): Cr : (p, nr) ndarray This array contains the state/output matrix `Cr` of the reduced order system. - hsv : (n) ndarray + hsv : (n, ) ndarray If ``INFO = 0``, it contains the Hankel singular values of the original system ordered decreasingly. ``HSV(1)`` is the Hankel norm of the system. @@ -1046,7 +1050,7 @@ def ab09bd(dico,job,equil,n,m,p,A,B,C,D,nr=None,tol1=0,tol2=0,ldwork=None): Dr : (p, m) ndarray the leading p-by-m part of this array contains the input/output matrix Dr of the reduced order system. - hsv : (n) ndarray + hsv : (n, ) ndarray If info = 0, it contains the Hankel singular values of the original system ordered decreasingly. hsv(1) is the Hankel norm of the system. @@ -1211,7 +1215,7 @@ def ab09md(dico,job,equil,n,m,p,A,B,C,alpha=None,nr=None,tol=0,ldwork=None): order system. ns : int The dimension of the alpha-stable subsystem. - hsv : (n) array_like + hsv : (n, ) array_like If info = 0, the leading ns elements of hsv contain the Hankel singular values of the alpha-stable part of the original system ordered decreasingly. @@ -1380,7 +1384,7 @@ def ab09nd(dico,job,equil,n,m,p,A,B,C,D,alpha=None,nr=None,tol1=0,tol2=0,ldwork= input/output matrix Dr of the reduced order system. ns : int The dimension of the alpha-stable subsystem. - hsv : (n) ndarray + hsv : (n, ) ndarray If info = 0, it contains the Hankel singular values of the original system ordered decreasingly. hsv(1) is the Hankel norm of the system. @@ -1737,6 +1741,21 @@ def ab13fd(n, A, tol = 0.0): The value of w such that the smallest singular value of (A - jwI) equals beta(A). + Raises + ------ + SlycotParameterError + :info = -i: the i-th argument had an illegal value + SlycotArithmeticError + :info = 2: + Either the QR or SVD algorithm fails to converge + + Warns + ----- + SlycotResultWarning + :info = 1: + Failed to compute beta(A) within the specified tolerance. + Nevertheless, the returned value is an upper bound on beta(A); + Notes ----- In the presence of rounding errors, the computed function value @@ -1752,21 +1771,6 @@ def ab13fd(n, A, tol = 0.0): AB13FD to fail for smaller values of tol, nevertheless, it usually succeeds. Regardless of success or failure, the first inequality holds. - - Raises - ------ - SlycotParameterError - :info = -i: the i-th argument had an illegal value - SlycotArithmeticError - :info = 2: - Either the QR or SVD algorithm fails to converge - - Warns - ----- - SlycotResultWarning - :info = 1: - Failed to compute beta(A) within the specified tolerance. - Nevertheless, the returned value is an upper bound on beta(A); """ hidden = ' (hidden by the wrapper)' arg_list = ['n', 'A', 'lda' + hidden, 'beta' + hidden, 'omega' + hidden, 'tol', @@ -1786,39 +1790,33 @@ def ab13md(Z, nblock, itype, x=None): Parameters ---------- Z : (n, n) array_like - Matrix to find structured singular value upper bound of - - nblock : (m,) array_like - The size of the block diagonals of the uncertainty structure; - i.e., nblock(i)=p means that the ith block is pxp. - - itype : (m,) array_like - The type of each block diagonal uncertainty defined in nblock. - itype(i)==1 means that the ith block is real, while itype(i)==2 - means the the ith block is complex. Real blocks must be 1x1, - i.e., if itype(i)==1, nblock(i) must be 1. - - x : (q,) array_like, optional - If not None, must be the output of a previous call to ab13md. - The previous call must have been with the same values of n, - nblock, and itype; and the previous call's Z should be "close" - to the current call's Z. - - q is determined by the block structure; see SLICOT AB13MD for - details. Default is None. + Matrix to find structured singular value upper bound of + nblock : (m, ) array_like + The size of the block diagonals of the uncertainty structure; + i.e., nblock(i)=p means that the ith block is pxp. + itype : (m, ) array_like + The type of each block diagonal uncertainty defined in nblock. + itype(i)==1 means that the ith block is real, while itype(i)==2 + means the the ith block is complex. Real blocks must be 1x1, + i.e., if itype(i)==1, nblock(i) must be 1. + x : (q, ) array_like, optional + If not None, must be the output of a previous call to ab13md. + The previous call must have been with the same values of n, + nblock, and itype; and the previous call's Z should be "close" + to the current call's Z. + q is determined by the block structure; see SLICOT AB13MD for + details. Default is None. Returns ------- mubound : non-negative real scalar - Upper bound on structure singular value for given arguments - - d, g : (n,) ndarray - Real arrays such that if D=np.diag(g), G=np.diag(G), and ZH = Z.T.conj(), then - ZH @ D**2 @ Z + 1j * (G@Z - ZH@G) - mu**2 * D**2 - will be negative semi-definite. - - xout : (q,) ndarray - For use as ``x`` argument in subsequent call to ``ab13md``. + Upper bound on structure singular value for given arguments + d, g : (n, ) ndarray + Real arrays such that if D=np.diag(g), G=np.diag(G), and ZH = Z.T.conj(), then + ZH @ D**2 @ Z + 1j * (G@Z - ZH@G) - mu**2 * D**2 + will be negative semi-definite. + xout : (q, ) ndarray + For use as ``x`` argument in subsequent call to ``ab13md``. For scalar Z and real uncertainty (ntype=1, itype=1), returns 0 instead of abs(Z). @@ -1966,17 +1964,22 @@ def ag08bd(l,n,m,p,A,E,B,C,D,equil='N',tol=0.0,ldwork=None): The normal rank of the system pencil. niz : int The number of infinite zeros. - infz : (n+1) ndarray + infz : (n+1, ) ndarray The leading DINFZ elements of infz contain information on the infinite elementary divisors as follows: the system has infz(i) infinite elementary divisors of degree i in the Smith form, where i = 1,2,...,DINFZ. - kronr : (n+m+1) ndarray + kronr : (n+m+1, ) ndarray The leading NKROR elements of this array contain the right Kronecker (column) indices. - infe : (1+min(l+p,n+m)) ndarray + infe : (1+min(l+p,n+m), ) ndarray The leading NINFE elements of infe contain the multiplicities of infinite eigenvalues. + + Raises + ------ + SlycotParameterError + :info = -i: the i-th argument had an illegal value """ hidden = ' (hidden by the wrapper)' arg_list = ['equil', 'l', 'n', 'm', 'p',