Change math.py docstrings to numpydoc style

Author: KybernetikJo

slycot/math.py

@@ -36,80 +36,85 @@ def mb03rd(n, A, X=None, jobx='U', sort='N', pmax=1.0, tol=0.0):
 
     Parameters
     ----------
-        n : int
-            The order of the matrices `A` and `X`.  `n` >= 0.
-        A : (n, n) array_like
-            The matrix `A` to be block-diagonalized, in real Schur form.
-        X : (n, n) array_like, optional
-            A given matrix `X`, for accumulation of transformations (only if
-            `jobx`='U'). Default value is identity matrix of order `n`.
-        jobx : {'N', 'U'}, optional
-            Specifies whether or not the transformations are
-            accumulated, as follows:
-
-            := 'N': The transformations are not accumulated
-            := 'U': The transformations are accumulated in `Xr` (default)
-
-        sort : {'N', 'S', 'C', 'B'}, optional
-            Specifies whether or not the diagonal blocks of the real
-            Schur form are reordered, as follows:
-
-            := 'N':  The diagonal blocks are not reordered (default);
-            := 'S':  The diagonal blocks are reordered before each
-                     step of reduction, so that clustered eigenvalues
-                     appear in the same block;
-            := 'C':  The diagonal blocks are not reordered, but the
-                     "closest-neighbour" strategy is used instead of
-                     the standard "closest to the mean" strategy
-                     (see Notes_);
-            := 'B':  The diagonal blocks are reordered before each
-                     step of reduction, and the "closest-neighbour"
-                     strategy is used (see Notes_).
-
-        pmax : float, optional
-            An upper bound for the infinity norm of elementary
-            submatrices of the individual transformations used for
-            reduction (see Notes_).  `pmax` >= 1.0
-        tol : float, optional
-            The tolerance to be used in the ordering of the diagonal
-            blocks of the real Schur form matrix.
-            If the user sets `tol` > 0, then the given value of `tol` is
-            used as an absolute tolerance: a block `i` and a temporarily
-            fixed block 1 (the first block of the current trailing
-            submatrix to be reduced) are considered to belong to the
-            same cluster if their eigenvalues satisfy
-
-            .. math:: | \\lambda_1 - \\lambda_i | <= tol.
-
-            If the user sets `tol` < 0, then the given value of tol is
-            used as a relative tolerance: a block i and a temporarily
-            fixed block 1 are considered to belong to the same cluster
-            if their eigenvalues satisfy, for ``j = 1, ..., n``
-
-            .. math:: | \\lambda_1 - \\lambda_i | <= | tol | * \\max | \\lambda_j |.
-
-            If the user sets `tol` = 0, then an implicitly computed,
-            default tolerance, defined by ``tol = SQRT( SQRT( EPS ) )``
-            is used instead, as a relative tolerance, where `EPS` is
-            the machine precision (see LAPACK Library routine DLAMCH).
-            If `sort` = 'N' or 'C', this parameter is not referenced.
+    n : int
+        The order of the matrices `A` and `X`.  `n` >= 0.
+    A : (n, n) array_like
+        The matrix `A` to be block-diagonalized, in real Schur form.
+    X : (n, n) array_like, optional
+        A given matrix `X`, for accumulation of transformations (only if
+        `jobx`='U'). Default value is identity matrix of order `n`.
+    jobx : {'N', 'U'}, optional
+        Specifies whether or not the transformations are
+        accumulated, as follows:
+
+        := 'N': The transformations are not accumulated
+        := 'U': The transformations are accumulated in `Xr` (default)
+
+    sort : {'N', 'S', 'C', 'B'}, optional
+        Specifies whether or not the diagonal blocks of the real
+        Schur form are reordered, as follows:
+
+        := 'N':  The diagonal blocks are not reordered (default);
+        := 'S':  The diagonal blocks are reordered before each
+                    step of reduction, so that clustered eigenvalues
+                    appear in the same block;
+        := 'C':  The diagonal blocks are not reordered, but the
+                    "closest-neighbour" strategy is used instead of
+                    the standard "closest to the mean" strategy
+                    (see Notes_);
+        := 'B':  The diagonal blocks are reordered before each
+                    step of reduction, and the "closest-neighbour"
+                    strategy is used (see Notes_).
+
+    pmax : float, optional
+        An upper bound for the infinity norm of elementary
+        submatrices of the individual transformations used for
+        reduction (see Notes_).  `pmax` >= 1.0
+    tol : float, optional
+        The tolerance to be used in the ordering of the diagonal
+        blocks of the real Schur form matrix.
+        If the user sets `tol` > 0, then the given value of `tol` is
+        used as an absolute tolerance: a block `i` and a temporarily
+        fixed block 1 (the first block of the current trailing
+        submatrix to be reduced) are considered to belong to the
+        same cluster if their eigenvalues satisfy
+
+        .. math:: | \\lambda_1 - \\lambda_i | <= tol.
+
+        If the user sets `tol` < 0, then the given value of tol is
+        used as a relative tolerance: a block i and a temporarily
+        fixed block 1 are considered to belong to the same cluster
+        if their eigenvalues satisfy, for ``j = 1, ..., n``
+
+        .. math:: | \\lambda_1 - \\lambda_i | <= | tol | * \\max | \\lambda_j |.
+
+        If the user sets `tol` = 0, then an implicitly computed,
+        default tolerance, defined by ``tol = SQRT( SQRT( EPS ) )``
+        is used instead, as a relative tolerance, where `EPS` is
+        the machine precision (see LAPACK Library routine DLAMCH).
+        If `sort` = 'N' or 'C', this parameter is not referenced.
 
     Returns
     -------
-        Ar : (n, n) ndarray
-            Contains the computed block-diagonal matrix, in real Schur
-            canonical form. The non-diagonal blocks are set to zero.
-        Xr : (n, n) ndarray or None
-            Contains the product of the given matrix `X` and the
-            transformation matrix that reduced `A` to block-diagonal
-            form. The transformation matrix is itself a product of
-            non-orthogonal similarity transformations having elements
-            with magnitude less than or equal to `pmax`.
-            If `jobx` = 'N', this array is returned as None
-        blsize : (n,) ndarray
-            The orders of the resulting diagonal blocks of the matrix `Ar`.
-        W : (n,) complex ndarray
-            Contains the complex eigenvalues of the matrix `A`.
+    Ar : (n, n) ndarray
+        Contains the computed block-diagonal matrix, in real Schur
+        canonical form. The non-diagonal blocks are set to zero.
+    Xr : (n, n) ndarray or None
+        Contains the product of the given matrix `X` and the
+        transformation matrix that reduced `A` to block-diagonal
+        form. The transformation matrix is itself a product of
+        non-orthogonal similarity transformations having elements
+        with magnitude less than or equal to `pmax`.
+        If `jobx` = 'N', this array is returned as None
+    blsize : (n,) ndarray
+        The orders of the resulting diagonal blocks of the matrix `Ar`.
+    W : (n,) complex ndarray
+        Contains the complex eigenvalues of the matrix `A`.
+
+    Raises
+    ------
+    SlycotParameterError
+        :info = -i: the i-th argument had an illegal value;
 
     Notes
     -----
@@ -260,11 +265,9 @@ def mb03vd(n, ilo, ihi, A):
 
     Parameters
     ----------
-
     n : int
             The order of the square matrices A_1, A_2, ..., A_p.
             n >= 0.
-
     ilo, ihi : int
             It is assumed that all matrices A_j, j = 2, ..., p, are
             already upper triangular in rows and columns [:ilo-1] and
@@ -274,15 +277,12 @@ def mb03vd(n, ilo, ihi, A):
             If this is not the case, ilo and ihi should be set to 1
             and n, respectively.
             1 <= ilo <= max(1,n); min(ilo,n) <= ihi <= n.
-
     A : ndarray
             A[:n,:n,:p] must contain the matrices of factors to be reduced;
             specifically, A[:,:,j-1] must contain A_j, j = 1, ..., p.
 
-
     Returns
     -------
-
     HQ : ndarray
             3D array with same shape as A. The upper triangle and the first
             subdiagonal of HQ[:n,:n,0] contain the upper Hessenberg
@@ -295,16 +295,19 @@ def mb03vd(n, ilo, ihi, A):
             below the diagonal, with the j-th column of the array TAU
             represent the orthogonal matrix Q_j as a product of
             elementary reflectors. See FURTHER COMMENTS.
-
     Tau : ndarray
             2D array with shape (max(1, n-1), p).
             The leading n-1 elements in the j-th column contain the
             scalar factors of the elementary reflectors used to form
             the matrix Q_j, j = 1, ..., p. See FURTHER COMMENTS.
 
-    Further Comments
-    ----------------
+    Raises
+    ------
+    SlycotParameterError
+        :info = -i: the i-th argument had an illegal value;
 
+    Notes
+    -----
     Each matrix Q_j is represented as a product of (ihi-ilo)
     elementary reflectors,
 
@@ -377,38 +380,36 @@ def mb03vy(n, ilo, ihi, A, Tau, ldwork=None):
 
     Parameters
     ----------
-
     n : int
             The order of the matrices Q_1, Q_2, ..., Q_p.  N >= 0.
-
     ilo, ihi : int
             The values of the indices ilo and ihi, respectively, used
             in the previous call of the SLICOT Library routine MB03VD.
             1 <= ilo <= max(1,n); min(ilo,n) <= ihi <= n.
-
     A : ndarray
             A[:n,:n,j-1] must contain the vectors which define the
             elementary reflectors used for reducing A_j, as returned
             by SLICOT Library routine MB03VD, j = 1, ..., p.
-
     Tau : ndarray
             The leading N-1 elements in the j-th column must contain
             the scalar factors of the elementary reflectors used to
             form the matrix Q_j, as returned by SLICOT Library routine
             MB03VD.
-
     ldwork : int, optional
             The length of the internal array DWORK.  ldwork >= max(1, n).
             For optimum performance ldwork should be larger.
 
 
     Returns
     -------
-
     Q : ndarray
             3D array with same shape as A. Q[:n,:n,j-1] contains the
             N-by-N orthogonal matrix Q_j, j = 1, ..., p.
 
+    Raises
+    ------
+    SlycotParameterError
+        :info = -i: the i-th argument had an illegal value;
     """
 
     hidden = ' (hidden by the wrapper)'
@@ -460,7 +461,7 @@ def mb03wd(job, compz, n, ilo, ihi, iloz, ihiz, H, Q, ldwork=None):
             = 'E':  Compute the eigenvalues only;
             = 'S':  Compute the factors T_1, ..., T_p of the full
                     Schur form, T = T_1*T_2*...*T_p.
-   compz : {'N', 'I', 'V'}
+    compz : {'N', 'I', 'V'}
             Indicates whether or not the user wishes to accumulate
             the matrices Z_1, ..., Z_p, as follows:
             = 'N':  The matrices Z_1, ..., Z_p are not required;
@@ -526,6 +527,11 @@ def mb03wd(job, compz, n, ilo, ihi, iloz, ihiz, H, Q, ldwork=None):
             If JOB = 'S', the eigenvalues are stored in the same order
             as on the diagonal of the Schur form returned in H.
 
+    Raises
+    ------
+    SlycotParameterError
+        :info = -i: the i-th argument had an illegal value;
+
     Warns
     -----
     SlycotResultWarning
@@ -623,6 +629,11 @@ def mb05md(a, delta, balanc='N'):
         appear consecutively with the eigenvalue having positive
         imaginary part first.
 
+    Raises
+    ------
+    SlycotParameterError
+        :info = -i: the i-th argument had an illegal value;
+
     Warns
     ------
     SlycotResultWarning
@@ -687,6 +698,8 @@ def mb05nd(a, delta, tol=1e-7):
 
     Raises
     ------
+    SlycotParameterError
+        :info = -i: the i-th argument had an illegal value;
     SlycotArithmeticError
         :1 < info <=n:
             the ({info},{info}) element of the denominator of
@@ -730,7 +743,6 @@ def mc01td(dico, dp, p):
 
         = 'C':  continuous-time case;
         = 'D':  discrete-time case.
-
     dp : int
         The degree of the polynomial `P(x)`.  ``dp >= 0``.
     p : (dp+1, ) array_like
@@ -747,6 +759,11 @@ def mc01td(dico, dp, p):
     nz : int
         The number of unstable zeros.
 
+    Raises
+    ------
+    SlycotParameterError
+        :info = -i: the i-th argument had an illegal value;
+
     Warns
     -----
     SlycotResultWarning