From 7a057cb9eb635e2a04f41d40613c0198fa6e2b0c Mon Sep 17 00:00:00 2001 From: Johannes Kaisinger Date: Sun, 27 Aug 2023 10:42:34 +0200 Subject: [PATCH] Change mb03rd docstring sections to numpydoc style --- slycot/math.py | 142 ++++++++++++++++++++++++------------------------- 1 file changed, 71 insertions(+), 71 deletions(-) diff --git a/slycot/math.py b/slycot/math.py index ae9aab18..2ac9d139 100644 --- a/slycot/math.py +++ b/slycot/math.py @@ -36,80 +36,80 @@ 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`. Notes -----