clean up docstrings, examples

murrayrm · murrayrm · commit aed5706b5bf9 · 2024-11-07T22:06:08.000-08:00
diff --git a/control/nlsys.py b/control/nlsys.py
@@ -32,7 +32,8 @@
 
 __all__ = ['NonlinearIOSystem', 'InterconnectedSystem', 'nlsys',
            'input_output_response', 'find_eqpt', 'linearize',
-           'interconnect', 'connection_table', 'find_operating_point']
+           'interconnect', 'connection_table', 'OperatingPoint',
+           'find_operating_point']
 
 
 class NonlinearIOSystem(InputOutputSystem):
@@ -92,7 +93,7 @@ class NonlinearIOSystem(InputOutputSystem):
         generic name <sys[id]> is generated with a unique integer id.
 
     params : dict, optional
-        Parameter values for the system.  Passed to the evaluation functions
+       Parameter values for the system.  Passed to the evaluation functions
         for the system as default values, overriding internal defaults.
 
     See Also
@@ -1685,6 +1686,8 @@ class OperatingPoint(object):
         State vector at the operating point.
     inputs : array
         Input vector at the operating point.
+    outputs : array, optional
+        Output vector at the operating point.
     result : :class:`scipy.optimize.OptimizeResult`, optional
         Result from the :func:`scipy.optimize.root` function, if available.
 
@@ -1740,7 +1743,7 @@ def find_operating_point(
     for the desired inputs, outputs, states, or state updates of the system.
 
     In its simplest form, `find_operating_point` finds an equilibrium point
-    given either the desired input or desired output:
+    given either the desired input or desired output::
 
         xeq, ueq = find_operating_point(sys, x0, u0)
         xeq, ueq = find_operating_point(sys, x0, u0, y0)
@@ -1810,19 +1813,15 @@ def find_operating_point(
 
     Returns
     -------
-    states : array of states
-        Value of the states at the equilibrium point, or `None` if no
-        equilibrium point was found and `return_result` was False.
-    inputs : array of input values
-        Value of the inputs at the equilibrium point, or `None` if no
-        equilibrium point was found and `return_result` was False.
-    outputs : array of output values, optional
-        If `return_y` is True, returns the value of the outputs at the
-        equilibrium point, or `None` if no equilibrium point was found and
-        `return_result` was False.
-    result : :class:`scipy.optimize.OptimizeResult`, optional
-        If `return_result` is True, returns the `result` from the
-        :func:`scipy.optimize.root` function.
+    op_point : OperatingPoint
+        The solution represented as an `OperatingPoint` object.  The main
+        attributes are `states` and `inputs`, which represent the state
+        and input arrays at the operating point.  See
+        :class:`OperatingPoint` for a description of other attributes.
+
+        If accessed as a tuple, returns `states`, `inputs`, and optionally
+        `outputs` and `result` based on the `return_y` and `return_result`
+        parameters.
 
     Notes
     -----
@@ -1839,7 +1838,7 @@ def find_operating_point(
     `False`, the returned state and input for the operating point will be
     `None`.  If `return_result` is `True`, then the return values from
     :func:`scipy.optimize.root` will be returned (but may not be valid).
-    If `root_method` is set to `lm`, then the least squares solution (in
+    If `root_method` is set to 'lm', then the least squares solution (in
     the free variables) will be returned.
 
     """
@@ -1956,8 +1955,8 @@ def rootfun(z):
         # * output_vars: indices of outputs that must be constrained
         #
         # This index lists can all be precomputed based on the `iu`, `iy`,
-        # `ix`, and `idx` lists that were passed as arguments to `find_eqpt`
-        # and were processed above.
+        # `ix`, and `idx` lists that were passed as arguments to
+        # `find_operating_point` and were processed above.
 
         # Get the states and inputs that were not listed as fixed
         state_vars = (range(nstates) if not len(ix)
diff --git a/control/phaseplot.py b/control/phaseplot.py
@@ -39,7 +39,8 @@
 from .ctrlplot import ControlPlot, _add_arrows_to_line2D, _get_color, \
     _process_ax_keyword, _update_plot_title
 from .exception import ControlNotImplemented
-from .nlsys import NonlinearIOSystem, find_eqpt, input_output_response
+from .nlsys import NonlinearIOSystem, find_operating_point, \
+    input_output_response
 
 __all__ = ['phase_plane_plot', 'phase_plot', 'box_grid']
 
@@ -853,7 +854,7 @@ def _find_equilpts(sys, points, params=None):
     equilpts = []
     for i, x0 in enumerate(points):
         # Look for an equilibrium point near this point
-        xeq, ueq = find_eqpt(sys, x0, 0, params=params)
+        xeq, ueq = find_operating_point(sys, x0, 0, params=params)
 
         if xeq is None:
             continue            # didn't find anything
diff --git a/control/tests/iosys_test.py b/control/tests/iosys_test.py
@@ -2142,6 +2142,10 @@ def test_operating_point():
     np.testing.assert_allclose(linsys_orig.C, linsys_oppt.C)
     np.testing.assert_allclose(linsys_orig.D, linsys_oppt.D)
 
+    # Call find_operating point with method and keyword arguments
+    op_point = ct.find_operating_point(
+        sys, 0, 0, root_method='lm', root_kwargs={'tol': 1e-6})
+
 
 def test_iosys_sample():
     csys = ct.rss(2, 1, 1)
diff --git a/doc/iosys.rst b/doc/iosys.rst
@@ -544,6 +544,7 @@ Module classes and functions
    ~control.InterconnectedSystem
    ~control.LinearICSystem
    ~control.NonlinearIOSystem
+   ~control.OperatingPoint
 
 .. autosummary::
    :toctree: generated/
diff --git a/examples/cruise-control.py b/examples/cruise-control.py
@@ -165,7 +165,7 @@ def motor_torque(omega, params={}):
 
 for m in (1200, 1600, 2000):
     # Compute the equilibrium state for the system
-    X0, U0 = ct.find_eqpt(
+    X0, U0 = ct.find_operating_point(
         cruise_tf, [0, vref[0]], [vref[0], gear[0], theta0[0]], 
         iu=[1, 2], y0=[vref[0], 0], iy=[0], params={'m': m})
 
@@ -347,7 +347,7 @@ def cruise_plot(sys, t, y, label=None, t_hill=None, vref=20, antiwindup=False,
 
 # Compute the equilibrium throttle setting for the desired speed (solve for x
 # and u given the gear, slope, and desired output velocity)
-X0, U0, Y0 = ct.find_eqpt(
+X0, U0, Y0 = ct.find_operating_point(
     cruise_pi, [vref[0], 0], [vref[0], gear[0], theta0[0]],
     y0=[0, vref[0]], iu=[1, 2], iy=[1], return_y=True)
 
