From 7aa877a3a21540324d9dc5aa3027fc08b6fc2783 Mon Sep 17 00:00:00 2001
From: Johannes Kaisinger <johannes.kaisinger@gmail.com>
Date: Sat, 29 Jul 2023 19:38:21 +0200
Subject: [PATCH] Add docstring, Change parameter name from type_bn to type_t

---
 slycot/analysis.py      | 66 +++++++++++++++++++++++++++++++++++++----
 slycot/src/analysis.pyf |  4 +--
 2 files changed, 63 insertions(+), 7 deletions(-)

diff --git a/slycot/analysis.py b/slycot/analysis.py
index d2edb67e..7da8eae8 100644
--- a/slycot/analysis.py
+++ b/slycot/analysis.py
@@ -139,19 +139,75 @@ def ab01nd(n, m, A, B, jobz='N', tol=0, ldwork=None):
         Z = None
     return Ac, Bc, ncont, indcon, nblk, Z, tau
 
-def ab04md(type_bn, n, m, p, A, B, C, D, alpha=1.0, beta=1.0, ldwork=None):
-    """ a,b,c,d = ab04md()
+def ab04md(type_t, n, m, p, A, B, C, D, alpha=1.0, beta=1.0, ldwork=None):
+    """ At,Bt,Ct,Dt = ab04md(type_bn, n, m, p, A, B, C, D, [alpha, beta,ldwork])
+
+    Parameters
+    ----------
+    type_t : {'D','C'}
+            Indicates the type of the original system and the
+            transformation to be performed as follows:
+            = 'D':  discrete-time   -> continuous-time;
+            = 'C':  continuous-time -> discrete-time.
+    n : input int
+        The order of the matrix A, the number of rows of matrix B and
+        the number of columns of matrix C. It represents the dimension of
+        the state vector.  n > 0.        
+    m : input int
+        The number of columns of matrix B. It represents the dimension of
+        the input vector.  m > 0.
+    p : input int
+        The number of rows of matrix C. It represents the dimension of
+        the output vector.  p > 0.
+    A : input rank-2 array('d') with bounds (n,n)
+        The leading n-by-n part of this array must contain the system state
+        matrix A.
+    B : input rank-2 array('d') with bounds (n,m)
+        The leading n-by-m part of this array must contain the system input
+        matrix B.
+    C : input rank-2 array('d') with bounds (p,n)
+        The leading p-by-n part of this array must contain the system output
+        matrix C.
+    D : input rank-2 array('d') with bounds (p,m)
+        The leading p-by-m part of this array must contain the system direct
+        transmission matrix D.
+    alpha : double
+        Parameter specifying the bilinear transformation.
+        Recommended values for stable systems: alpha = 1, alpha != 0,
+    beta : double
+        Parameter specifying the bilinear transformation.
+        Recommended values for stable systems: beta = 1, beta != 0,
+    ldwork : int
+        The length of the cache array.
+        ldwork >= max(1, n)
+    Returns
+    -------
+    At : output rank-2 array('d') with bounds (n,n)
+        The state matrix At of the transformed system.
+    Bt : output rank-2 array('d') with bounds (n,m)
+        The input matrix Bt of the transformed system.
+    Ct : output rank-2 array('d') with bounds (p,n)
+        The output matrix Ct of the transformed system.
+    Dt : output rank-2 array('d') with bounds (p,m)
+        The transmission matrix Dt of the transformed system.
+    Raises
+    ------
+    SlycotArithmeticError
+        :info == 1: 
+            If the matrix (ALPHA*I + A) is exactly singular
+        :info == 2: 
+            If the matrix  (BETA*I - A) is exactly singular.
     """
 
     hidden = ' (hidden by the wrapper)'  
-    arg_list = ['type_bn', 'n', 'm', 'p', 'alpha', 'beta', 
+    arg_list = ['type_t', 'n', 'm', 'p', 'alpha', 'beta', 
                 'A', 'LDA'+hidden, 'B', 'LDB'+hidden, 'C', 'LDC'+hidden, 'D', 'LDD'+hidden,
                 'IWORK'+hidden, 'DWORK'+hidden, 'ldwork', 'info'+hidden]
 
     if ldwork is None:
-        ldwork = max(n, 3*m)
+        ldwork = max(1, n)
 
-    out = _wrapper.ab04md(type_bn, n, m, p, alpha, beta, A, B, C, D, ldwork=ldwork)
+    out = _wrapper.ab04md(type_t, n, m, p, alpha, beta, A, B, C, D, ldwork=ldwork)
     info=out[-1]
     raise_if_slycot_error(info, arg_list)
 
diff --git a/slycot/src/analysis.pyf b/slycot/src/analysis.pyf
index 28629e38..b2bb5a12 100644
--- a/slycot/src/analysis.pyf
+++ b/slycot/src/analysis.pyf
@@ -19,8 +19,8 @@ subroutine ab01nd(jobz,n,m,a,lda,b,ldb,ncont,indcon,nblk,z,ldz,tau,tol,iwork,dwo
     integer :: ldwork = max(n,3*m)
     integer intent(out) :: info
 end subroutine ab01nd
-subroutine ab04md(type_bn,n,m,p,alpha,beta,a,lda,b,ldb,c,ldc,d,ldd,iwork,dwork,ldwork,info) ! in AB04MD.f
-    character :: type_bn
+subroutine ab04md(type_t,n,m,p,alpha,beta,a,lda,b,ldb,c,ldc,d,ldd,iwork,dwork,ldwork,info) ! in AB04MD.f
+    character :: type_t
     integer check(n>=0) :: n
     integer check(m>=0) :: m
     integer check(p>=0) :: p