change ag08bd docstring sections to numpydoc style

Author: KybernetikJo

slycot/analysis.py

@@ -1903,75 +1903,80 @@ def ag08bd(l,n,m,p,A,E,B,C,D,equil='N',tol=0.0,ldwork=None):
     and left Kronecker indices, and the multiplicities of infinite
     eigenvalues.
 
-    Required arguments:
-        l : input int
-            The number of rows of matrices A, B, and E.  l >= 0.
-        n : input int
-            The number of columns of matrices A, E, and C.  n >= 0.
-        m : input int
-            The number of columns of matrix B.  m >= 0.
-        p : input int
-            The number of rows of matrix C.  p >= 0.
-        A : rank-2 array('d') with bounds (l,n)
-            The leading l-by-n part of this array must
-            contain the state dynamics matrix A of the system.
-        E : rank-2 array('d') with bounds (l,n)
-            The leading l-by-n part of this array must
-            contain the descriptor matrix E of the system.
-        B : rank-2 array('d') with bounds (l,m)
-            The leading l-by-m part of this array must
-            contain the input/state matrix B of the system.
-        C : rank-2 array('d') with bounds (p,n)
-            The leading p-by-n part of this array must
-            contain the state/output matrix C of the system.
-        D : rank-2 array('d') with bounds (p,m)
-            The leading p-by-m part of this array must contain the
-            direct transmission matrix D of the system.
-    Optional arguments:
-        equil := 'N' input string(len=1)
-            Specifies whether the user wishes to balance the system
-            matrix as follows:
-            = 'S':  Perform balancing (scaling);
-            = 'N':  Do not perform balancing.
-        tol := 0 input float
-            A tolerance used in rank decisions to determine the
-            effective rank, which is defined as the order of the
-            largest leading (or trailing) triangular submatrix in the
-            QR (or RQ) factorization with column (or row) pivoting
-            whose estimated condition number is less than 1/TOL.
-            If the user sets TOL <= 0, then default tolerances are
-            used instead, as follows: TOLDEF = L*N*EPS in TG01FD
-            (to determine the rank of E) and TOLDEF = (L+P)*(N+M)*EPS
-            in the rest, where EPS is the machine precision
-            (see LAPACK Library routine DLAMCH).  TOL < 1.
-        ldwork : input int
-            The length of the cache array.
-            ldwork >= max( 4*(l,n), ldw ), if equil = 'S',
-            ldwork >= ldw,                 if equil = 'N', where
-            ldw = max(l+p,m+n)*(m+n) + max(1,5*max(l+p,m+n)).
-            For optimum performance ldwork should be larger.
-    Return objects:
-        Af : rank-2 array('d')
-            the leading NFZ-by-NFZ part of this array
-            contains the matrix Af of the reduced pencil.
-        Ef : rank-2 array('d')
-            the leading NFZ-by-NFZ part of this array
-            contains the matrix Ef of the reduced pencil.
-        nrank : output int
-            The normal rank of the system pencil.
-        niz : output int
-            The number of infinite zeros.
-        infz : rank-1 array('i')
-            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 : rank-1 array('i')
-            The leading NKROR elements of this array contain the
-            right Kronecker (column) indices.
-        infe : rank-1 array('i')
-            The leading NINFE elements of infe contain the
-            multiplicities of infinite eigenvalues.
+    Parameters
+    ----------
+    l : int
+        The number of rows of matrices A, B, and E.  l >= 0.
+    n : int
+        The number of columns of matrices A, E, and C.  n >= 0.
+    m : int
+        The number of columns of matrix B.  m >= 0.
+    p : int
+        The number of rows of matrix C.  p >= 0.
+    A : (l, n) array_like
+        The leading l-by-n part of this array must
+        contain the state dynamics matrix A of the system.
+    E : (l, n) array_like
+        The leading l-by-n part of this array must
+        contain the descriptor matrix E of the system.
+    B : (l, m) array_like
+        The leading l-by-m part of this array must
+        contain the input/state matrix B of the system.
+    C : (p, n) array_like
+        The leading p-by-n part of this array must
+        contain the state/output matrix C of the system.
+    D : (p, m) array_like
+        The leading p-by-m part of this array must contain the
+        direct transmission matrix D of the system.
+    equil : {'S', 'N'}, optional
+        Specifies whether the user wishes to balance the system
+        matrix as follows:
+        = 'S':  Perform balancing (scaling);
+        = 'N':  Do not perform balancing.
+        Default is `N`
+    tol : float, optional
+        A tolerance used in rank decisions to determine the
+        effective rank, which is defined as the order of the
+        largest leading (or trailing) triangular submatrix in the
+        QR (or RQ) factorization with column (or row) pivoting
+        whose estimated condition number is less than 1/TOL.
+        If the user sets TOL <= 0, then default tolerances are
+        used instead, as follows: TOLDEF = L*N*EPS in TG01FD
+        (to determine the rank of E) and TOLDEF = (L+P)*(N+M)*EPS
+        in the rest, where EPS is the machine precision
+        (see LAPACK Library routine DLAMCH).  TOL < 1.
+        Default is 0.
+    ldwork : int, optional
+        The length of the cache array.
+        ldwork >= max( 4*(l,n), ldw ), if equil = 'S',
+        ldwork >= ldw,                 if equil = 'N', where
+        ldw = max(l+p,m+n)*(m+n) + max(1,5*max(l+p,m+n)).
+        For optimum performance ldwork should be larger.
+        Default is None.
+
+    Returns
+    -------
+    Af : (nfz, nfz) ndarray
+        the leading NFZ-by-NFZ part of this array
+        contains the matrix Af of the reduced pencil.
+    Ef : (nfz, nfz) ndarray
+        the leading NFZ-by-NFZ part of this array
+        contains the matrix Ef of the reduced pencil.
+    nrank : int
+        The normal rank of the system pencil.
+    niz : int
+        The number of infinite zeros.
+    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
+        The leading NKROR elements of this array contain the
+        right Kronecker (column) indices.
+    infe : (1+min(l+p,n+m)) ndarray
+        The leading NINFE elements of infe contain the
+        multiplicities of infinite eigenvalues.
     """
     hidden = ' (hidden by the wrapper)'
     arg_list = ['equil', 'l', 'n', 'm', 'p',