Skip to content

Commit

Permalink
Update docstrings, add SlycotParameterError and other fixes
Browse files Browse the repository at this point in the history
  • Loading branch information
@KybernetikJo
KybernetikJo committed Aug 28, 2023
1 parent d160a79 commit 44286b6
Showing 1 changed file with 64 additions and 61 deletions.
125 changes: 64 additions & 61 deletions slycot/analysis.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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',
Expand All @@ -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).
Expand Down Expand Up @@ -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',
Expand Down

0 comments on commit 44286b6

Please sign in to comment.