improved docstring checking + first round of fixes

murrayrm · murrayrm · commit 210ab452fffb · 2025-02-02T20:06:41.000-08:00
diff --git a/control/config.py b/control/config.py
@@ -381,7 +381,7 @@ def use_legacy_defaults(version):
 # exception is raised.
 #
 def _process_legacy_keyword(kwargs, oldkey, newkey, newval):
-    if kwargs.get(oldkey) is not None:
+    if oldkey in kwargs:
         warnings.warn(
             f"keyword '{oldkey}' is deprecated; use '{newkey}'",
             FutureWarning)
diff --git a/control/flatsys/flatsys.py b/control/flatsys/flatsys.py
@@ -9,6 +9,7 @@
 from .poly import PolyFamily
 from .systraj import SystemTrajectory
 from ..exception import ControlArgument
+from ..config import _process_legacy_keyword
 from ..nlsys import NonlinearIOSystem
 from ..timeresp import _check_convert_array
 
@@ -315,7 +316,7 @@ def point_to_point(
 
     Parameters
     ----------
-    flatsys : FlatSystem object
+    sys : FlatSystem object
         Description of the differentially flat system.  This object must
         define a function `flatsys.forward()` that takes the system state and
         produceds the flag of flat outputs and a system `flatsys.reverse()`
@@ -364,6 +365,20 @@ def point_to_point(
 
         The constraints are applied at each time point along the trajectory.
 
+    initial_guess : 2D array_like, optional
+        Initial guess for the trajectory coefficients (not implemented).
+
+    params : dict, optional
+        Parameter values for the system.  Passed to the evaluation
+        functions for the system as default values, overriding internal
+        defaults.
+
+    minimize_method : str, optional
+        Set the method used by :func:`scipy.optimize.minimize`.
+
+    minimize_options : str, optional
+        Set the options keyword used by :func:`scipy.optimize.minimize`.
+
     minimize_kwargs : str, optional
         Pass additional keywords to :func:`scipy.optimize.minimize`.
 
@@ -399,9 +414,8 @@ def point_to_point(
     T0 = timepts[0] if len(timepts) > 1 else T0
 
     # Process keyword arguments
-    if trajectory_constraints is None:
-        # Backwards compatibility
-        trajectory_constraints = kwargs.pop('constraints', None)
+    trajectory_constraints = _process_legacy_keyword(
+        kwargs, 'constraints', 'trajectory_constraints', trajectory_constraints)
 
     minimize_kwargs = {}
     minimize_kwargs['method'] = kwargs.pop('minimize_method', None)
@@ -632,7 +646,7 @@ def solve_flat_ocp(
 
     Parameters
     ----------
-    flatsys : FlatSystem object
+    sys : FlatSystem object
         Description of the differentially flat system.  This object must
         define a function `flatsys.forward()` that takes the system state and
         produceds the flag of flat outputs and a system `flatsys.reverse()`
@@ -684,6 +698,17 @@ def solve_flat_ocp(
     initial_guess : 2D array_like, optional
         Initial guess for the optimal trajectory of the flat outputs.
 
+    params : dict, optional
+        Parameter values for the system.  Passed to the evaluation
+        functions for the system as default values, overriding internal
+        defaults.
+
+    minimize_method : str, optional
+        Set the method used by :func:`scipy.optimize.minimize`.
+
+    minimize_options : str, optional
+        Set the options keyword used by :func:`scipy.optimize.minimize`.
+
     minimize_kwargs : str, optional
         Pass additional keywords to :func:`scipy.optimize.minimize`.
 
@@ -724,12 +749,10 @@ def solve_flat_ocp(
     T0 = timepts[0] if len(timepts) > 1 else 0
 
     # Process keyword arguments
-    if trajectory_constraints is None:
-        # Backwards compatibility
-        trajectory_constraints = kwargs.pop('constraints', None)
-    if trajectory_cost is None:
-        # Compatibility with point_to_point
-        trajectory_cost = kwargs.pop('cost', None)
+    trajectory_constraints = _process_legacy_keyword(
+        kwargs, 'constraints', 'trajectory_constraints', trajectory_constraints)
+    trajectory_cost = _process_legacy_keyword(
+        kwargs, 'cost', 'trajectory_cost', trajectory_cost)
 
     minimize_kwargs = {}
     minimize_kwargs['method'] = kwargs.pop('minimize_method', None)
diff --git a/control/iosys.py b/control/iosys.py
@@ -558,6 +558,12 @@ def update_names(self, **kwargs):
             Description of output signals; defaults to `y[i]`.
         states : int, list of str, int, or None, optional
             Description of system states; defaults to `x[i]`.
+        input_prefix : string, optional
+            Set the prefix for input signals.  Default = 'u'.
+        output_prefix : string, optional
+            Set the prefix for output signals.  Default = 'y'.
+        state_prefix : string, optional
+            Set the prefix for state signals.  Default = 'x'.
 
         """
         self.name = kwargs.pop('name', self.name)
diff --git a/control/lti.py b/control/lti.py
@@ -153,7 +153,7 @@ def bandwidth(self, dbdrop=-3):
 
         Parameters
         ----------
-        dpdrop : float, optional
+        dbdrop : float, optional
             A strictly negative scalar in dB (default = -3) defines the
             amount of gain drop for deciding bandwidth.
 
diff --git a/control/nlsys.py b/control/nlsys.py
@@ -462,30 +462,7 @@ def output(self, t, x, u, params=None):
             t, np.asarray(x).reshape(-1), np.asarray(u).reshape(-1))
 
     def feedback(self, other=1, sign=-1, params=None):
-        """Feedback interconnection between two input/output systems
-
-        Parameters
-        ----------
-        sys1: InputOutputSystem
-            The primary process.
-        sys2: InputOutputSystem
-            The feedback process (often a feedback controller).
-        sign: scalar, optional
-            The sign of feedback.  `sign` = -1 indicates negative feedback,
-            and `sign` = 1 indicates positive feedback.  `sign` is an optional
-            argument; it assumes a value of -1 if not specified.
-
-        Returns
-        -------
-        out: InputOutputSystem
-
-        Raises
-        ------
-        ValueError
-            if the inputs, outputs, or timebases of the systems are
-            incompatible.
-
-        """
+        """Feedback interconnection between two input/output systems."""
         # Convert sys2 to an I/O system if needed
         other = _convert_static_iosystem(other)
 
@@ -1045,11 +1022,10 @@ def set_output_map(self, output_map):
         self.noutputs = output_map.shape[0]
 
     def unused_signals(self):
-        """Find unused subsystem inputs and outputs
+        """Find unused subsystem inputs and outputs.
 
         Returns
         -------
-
         unused_inputs : dict
           A mapping from tuple of indices (isys, isig) to string
           '{sys}.{sig}', for all unused subsystem inputs.
@@ -1083,6 +1059,7 @@ def unused_signals(self):
         return ({inputs[i][:2]: inputs[i][2] for i in unused_sysinp},
                 {outputs[i][:2]: outputs[i][2] for i in unused_sysout})
 
+
     def connection_table(self, show_names=False, column_width=32):
         """Print table of connections inside an interconnected system model.
 
@@ -1183,6 +1160,8 @@ def _find_outputs_by_basename(self, basename):
                 for sig, isig in sys.output_index.items()
                 if sig == (basename)}
 
+    # TODO: change `warning` to `print_warning` or `warn_unsed`?
+    # TODO: change to internal function?  (not sure users need to see this)
     def check_unused_signals(
             self, ignore_inputs=None, ignore_outputs=None, warning=True):
         """Check for unused subsystem inputs and outputs
@@ -1207,6 +1186,9 @@ def check_unused_signals(
           If the 'sig' form is used, all subsystem outputs with that
           name are considered ignored.
 
+        warning : bool, optional
+            If `True`, print a warning listing any unused signals.
+
         Returns
         -------
         dropped_inputs: list of tuples
diff --git a/control/optimal.py b/control/optimal.py
@@ -748,6 +748,7 @@ def _simulate_states(self, x0, inputs):
     #
 
     # Compute the optimal trajectory from the current state
+    # TODO: update docstring to refer to primary function (?)
     def compute_trajectory(
             self, x, squeeze=None, transpose=None, return_states=True,
             initial_guess=None, print_summary=True, **kwargs):
@@ -757,6 +758,14 @@ def compute_trajectory(
         ----------
         x : array-like or number, optional
             Initial state for the system.
+        initial_guess : (tuple of) 1D or 2D array_like
+            Initial states and/or inputs to use as a guess for the optimal
+            trajectory.  For shooting methods, an array of inputs for each
+            time point should be specified.  For collocation methods, the
+            initial guess is either the input vector or a tuple consisting
+            guesses for the state and the input.  Guess should either be a
+            2D vector of shape (ninputs, ntimepts) or a 1D input of shape
+            (ninputs,) that will be broadcast by extension of the time axis.
         return_states : bool, optional
             If True (default), return the values of the state at each time.
         squeeze : bool, optional
@@ -768,6 +777,9 @@ def compute_trajectory(
             If True, assume that 2D input arrays are transposed from the
             standard format.  Used to convert MATLAB-style inputs to our
             format.
+        print_summary : bool, optional
+            If `True` (default), print a short summary of the computation.
+
 
         Returns
         -------
diff --git a/control/statesp.py b/control/statesp.py
@@ -863,20 +863,11 @@ def horner(self, x, warn_infinite=True):
         Expects inputs and outputs to be formatted correctly. Use ``sys(x)``
         for a more user-friendly interface.
 
-        Parameters
-        ----------
-        x : complex array_like or complex
-            Complex frequencies
-
-        Returns
-        -------
-        output : (self.noutputs, self.ninputs, len(x)) complex ndarray
-            Frequency response
-
         Notes
         -----
-        Attempts to use Laub's method from Slycot library, with a
-        fall-back to python code.
+        Attempts to use Laub's method from Slycot library, with a fall-back
+        to Python code.
+
         """
         # Make sure the argument is a 1D array of complex numbers
         x_arr = np.atleast_1d(x).astype(complex, copy=False)
@@ -1390,8 +1381,9 @@ def dcgain(self, warn_infinite=False):
         """
         return self._dcgain(warn_infinite)
 
+    # TODO: decide if we need this function (already in NonlinearIOSystem
     def dynamics(self, t, x, u=None, params=None):
-        """Compute the dynamics of the system
+        """Compute the dynamics of the system.
 
         Given input `u` and state `x`, returns the dynamics of the state-space
         system. If the system is continuous, returns the time derivative dx/dt
@@ -1439,6 +1431,7 @@ def dynamics(self, t, x, u=None, params=None):
             return (self.A @ x).reshape((-1,)) \
                 + (self.B @ u).reshape((-1,))  # return as row vector
 
+    # TODO: decide if we need this function (already in NonlinearIOSystem
     def output(self, t, x, u=None, params=None):
         """Compute the output of the system
 
diff --git a/control/tests/docstrings_test.py b/control/tests/docstrings_test.py
diff --git a/control/xferfcn.py b/control/xferfcn.py

Original file line number	Diff line number	Diff line change
`@@ -381,7 +381,7 @@ def use_legacy_defaults(version):`
`381`	`381`	`# exception is raised.`
`382`	`382`	`#`
`383`	`383`	`def _process_legacy_keyword(kwargs, oldkey, newkey, newval):`
`384`		`- if kwargs.get(oldkey) is not None:`
	`384`	`+ if oldkey in kwargs:`
`385`	`385`	`warnings.warn(`
`386`	`386`	`f"keyword '{oldkey}' is deprecated; use '{newkey}'",`
`387`	`387`	`FutureWarning)`