Update docstrings, add SlycotParameterError and other fixes

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',