update flatsys() documentation

murrayrm · murrayrm · commit 319a8eaf541d · 2024-12-20T11:58:52.000-08:00
diff --git a/control/flatsys/flatsys.py b/control/flatsys/flatsys.py
@@ -17,8 +17,30 @@ class FlatSystem(NonlinearIOSystem):
     """Base class for representing a differentially flat system.
 
     The FlatSystem class is used as a base class to describe differentially
-    flat systems for trajectory generation.  The output of the system does not
-    need to be the differentially flat output.
+    flat systems for trajectory generation.  The output of the system does
+    not need to be the differentially flat output.  Flat systems are
+    usually created with the :func:`~control.flatsys.flatsys` factory
+    function.
+
+    Parameters
+    ----------
+    forward : callable
+        A function to compute the flat flag given the states and input.
+    reverse : callable
+        A function to compute the states and input given the flat flag.
+    dt : None, True or float, optional
+        System timebase.
+
+    Attributes
+    ----------
+    ninputs, noutputs, nstates : int
+        Number of input, output and state variables.
+    shape : tuple
+        2-tuple of I/O system dimension, (noutputs, ninputs).
+    input_labels, output_labels, state_labels : list of str
+        Names for the input, output, and state variables.
+    name : string, optional
+        System name.
 
     Notes
     -----
@@ -197,10 +219,9 @@ def flatsys(*args, updfcn=None, outfcn=None, **kwargs):
         Description of the system states.  Same format as `inputs`.
 
     dt : None, True or float, optional
-        System timebase.  None (default) indicates continuous
-        time, True indicates discrete time with undefined sampling
-        time, positive number is discrete time with specified
-        sampling time.
+        System timebase.  None (default) indicates continuous time, True
+        indicates discrete time with undefined sampling time, positive
+        number is discrete time with specified sampling time.
 
     params : dict, optional
         Parameter values for the systems.  Passed to the evaluation
diff --git a/control/tests/docstrings_test.py b/control/tests/docstrings_test.py
@@ -272,7 +272,7 @@ def test_deprecated_functions(module, prefix):
 
 # Dictionary of factory functions associated with primary classes
 class_factory_function = {
-    # fs.FlatSystem: fs.flatsys,
+    fs.FlatSystem: fs.flatsys,
     ct.FrequencyResponseData: ct.frd,
     ct.InterconnectedSystem: ct.interconnect,
     ct.LinearICSystem: ct.interconnect,
@@ -283,7 +283,7 @@ def test_deprecated_functions(module, prefix):
 
 # List of arguments described in class docstrings
 class_args = {
-    # fs.FlatSystem: ['forward', 'reverse', 'updfcn', 'outfcn'],
+    fs.FlatSystem: ['forward', 'reverse'],
     ct.FrequencyResponseData: ['response', 'omega', 'dt'],
     ct.NonlinearIOSystem: [
         'updfcn', 'outfcn', 'inputs', 'outputs', 'states', 'params', 'dt'],
@@ -297,7 +297,7 @@ def test_deprecated_functions(module, prefix):
 
 # List of attributes defined for specific I/O systems
 class_attributes = {
-    # fs.FlatSystem: [],
+    fs.FlatSystem: [],
     ct.FrequencyResponseData: [],
     ct.NonlinearIOSystem: [],
     ct.StateSpace: ['nstates', 'state_labels'],
@@ -315,7 +315,7 @@ def test_deprecated_functions(module, prefix):
 # List of arguments described (only) in factory function docstrings
 std_factory_args = ['inputs', 'outputs', 'name']
 factory_args = {
-    # fs.flatsys: [],
+    fs.flatsys: [],
     ct.frd: ['sys'],
     ct.nlsys: [],
     ct.ss: ['sys', 'states'],
@@ -337,7 +337,7 @@ def test_iosys_primary_classes(cls, fcn, args):
     # Make sure we reference the factory function
     if re.search(
             r"created.*(with|by|using).*the[\s]*"
-            f":func:`~control.{fcn.__name__}`"
+            f":func:`~control\\..*{fcn.__name__}`"
             r"[\s]factory[\s]function", docstring, re.DOTALL) is None:
         pytest.fail(
             f"{cls.__name__} does not reference factory function "
@@ -357,6 +357,7 @@ def test_iosys_attribute_lists(cls, ignore_future_warning):
 
     # Create a system that we can scan for attributes
     sys = ct.rss(2, 1, 1)
+    ignore_args = []
     match fcn:
         case ct.tf:
             sys = ct.tf(sys)
@@ -366,9 +367,9 @@ def test_iosys_attribute_lists(cls, ignore_future_warning):
             ignore_args = ['state_labels']
         case ct.nlsys:
             sys = ct.nlsys(sys)
-            ignore_args = []
-        case _:
-            ignore_args = []
+        case fs.flatsys:
+            sys = fs.flatsys(sys)
+            sys = fs.flatsys(sys.forward, sys.reverse)
 
     docstring = inspect.getdoc(cls)
     for name, obj in inspect.getmembers(sys):
