Merge pull request #1120 from murrayrm/userguide-22Dec2024

murrayrm · web-flow · commit 9fb84cb190f4 · 2025-02-02T23:11:15.000-08:00
add information on _ssmatrix, _check_shape
diff --git a/README.rst b/README.rst
@@ -110,7 +110,7 @@ from the github repository or archive, unpack, and run from within the
 toplevel `python-control` directory::
 
   pip install .
-  
+
 Article and Citation Information
 ================================
 
@@ -129,7 +129,6 @@ the library is available on IEEE Explore. If the Python Control Systems Library
 
 or the GitHub site: https://github.com/python-control/python-control
 
-
 Development
 ===========
 
@@ -178,4 +177,3 @@ Your contributions are welcome!  Simply fork the GitHub repository and send a
 Please see the `Developer's Wiki`_ for detailed instructions.
 
 .. _Developer's Wiki: https://github.com/python-control/python-control/wiki
-
diff --git a/control/mateqn.py b/control/mateqn.py
@@ -606,6 +606,33 @@ def _slycot_or_scipy(method):
 
 # Utility function to check matrix dimensions
 def _check_shape(M, n, m, square=False, symmetric=False, name="??"):
+    """Check the shape and properties of a 2D array.
+
+    This function can be used to check to make sure a 2D array_like has the
+    right shape, along with other properties.  If not, an appropriate error
+    message is generated.
+
+    Parameters
+    ----------
+    M : array_like
+        Array to be checked.
+    n : int
+        Expected number of rows.
+    m : int
+        Expected number of columns.
+    square : bool, optional
+        If True, check to make sure the matrix is square.
+    symmetric : bool, optional
+        If True, check to make sure the matrix is symmetric.
+    name : str
+        Name of the matrix (for use in error messages).
+
+    Returns
+    -------
+    M : 2D array
+        Input array, converted to 2D if needed.
+
+    """
     M = np.atleast_2d(M)
 
     if (square or symmetric) and M.shape[0] != M.shape[1]:
diff --git a/control/statesp.py b/control/statesp.py
@@ -2269,13 +2269,15 @@ def _parse_list(signals, signame='input', prefix='u'):
 def _ssmatrix(data, axis=1, square=None, rows=None, cols=None, name=None):
     """Convert argument to a (possibly empty) 2D state space matrix.
 
-    The axis keyword argument makes it convenient to specify that if the
-    input is a vector, it is a row (axis=1) or column (axis=0) vector.
+    This function can be used to process the matrices that define a
+    state-space system. The axis keyword argument makes it convenient
+    to specify that if the input is a vector, it is a row (axis=1) or
+    column (axis=0) vector.
 
     Parameters
     ----------
     data : array, list, or string
-        Input data defining the contents of the 2D array
+        Input data defining the contents of the 2D array.
     axis : 0 or 1
         If input data is 1D, which axis to use for return object.  The
         default is 1, corresponding to a row matrix.
diff --git a/doc/develop.rst b/doc/develop.rst
@@ -629,7 +629,9 @@ processing and parsing operations:
    exception.pandas_check
    exception.slycot_check
    iosys._process_iosys_keywords
+   mateqn._check_shape
    statesp._convert_to_statespace
+   statesp._ssmatrix
    xferfcn._convert_to_transfer_function
 
 
