Skip to content

Commit

Permalink
Change math.py docstrings to numpydoc style
Browse files Browse the repository at this point in the history
  • Loading branch information
@KybernetikJo
KybernetikJo committed Aug 29, 2023
1 parent 60a5c71 commit 48bca92
Showing 1 changed file with 104 additions and 87 deletions.
191 changes: 104 additions & 87 deletions slycot/math.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
-----
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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,
Expand Down Expand Up @@ -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)'
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down

0 comments on commit 48bca92

Please sign in to comment.