address doc-related TODOs; rename optimal_{ocp,oep}

Author: murrayrm

control/flatsys/__init__.py

@@ -16,7 +16,7 @@
 using the `BasisFamily` class.  The resulting trajectory is return
 as a `SystemTrajectory` object and can be evaluated using the
 `SystemTrajectory.eval` member function.  Alternatively, the
-`solve_flat_ocp` function can be used to solve an optimal control
+`solve_flat_optimal` function can be used to solve an optimal control
 problem with trajectory and final costs or constraints.
 
 The docstring examples assume that the following import commands::
@@ -32,7 +32,8 @@
 from .bezier import BezierFamily
 from .bspline import BSplineFamily
 # Package functions
-from .flatsys import FlatSystem, flatsys, point_to_point, solve_flat_ocp
+from .flatsys import FlatSystem, flatsys, point_to_point, solve_flat_ocp, \
+    solve_flat_optimal
 from .linflat import LinearFlatSystem
 from .poly import PolyFamily
 # Classes

control/flatsys/flatsys.py

@@ -656,7 +656,7 @@ def traj_const(null_coeffs):
 
 
 # Solve a point to point trajectory generation problem for a flat system
-def solve_flat_ocp(
+def solve_flat_optimal(
         sys, timepts, x0=0, u0=0, trajectory_cost=None, basis=None,
         terminal_cost=None, trajectory_constraints=None,
         initial_guess=None, params=None, **kwargs):
@@ -997,3 +997,7 @@ def traj_const(null_coeffs):
 
     # Return a function that computes inputs and states as a function of time
     return systraj
+
+
+# Convenience aliases
+solve_flat_ocp = solve_flat_optimal

control/flatsys/systraj.py

@@ -18,7 +18,7 @@ class SystemTrajectory:
 
     The `SystemTrajectory` class is used to represent the trajectory
     of a (differentially flat) system.  Used by the `point_to_point`
-    and `solve_flat_ocp` functions to return a trajectory.
+    and `solve_flat_optimal` functions to return a trajectory.
 
     Parameters
     ----------

control/lti.py

@@ -40,7 +40,6 @@ def __init__(self, inputs=1, outputs=1, states=None, name=None, **kwargs):
         super().__init__(
             name=name, inputs=inputs, outputs=outputs, states=states, **kwargs)
 
-    # TODO: update ss, tf docstrings to use this one as the primary
     def __call__(self, x, squeeze=None, warn_infinite=True):
         """Evaluate system transfer function at point in complex plane.
 

control/optimal.py

@@ -7,13 +7,14 @@
 
 This module provides support for optimization-based controllers for
 nonlinear systems with state and input constraints.  An optimal
-control problem can be solved using the `solve_ocp` function or set up
-using the `OptimalControlProblem` class and then solved using the
-`~OptimalControlProblem.compute_trajectory` method.  Utility functions
-are available to define common cost functions and input/state
-constraints.  Optimal estimation problems can be solved using the
-`solve_oep` function or by using the `OptimalEstimationProblem` class
-and the `~OptimalEstimationProblem.compute_estimate` method..
+control problem can be solved using the `solve_optimal_trajectory`
+function or set up using the `OptimalControlProblem` class and then
+solved using the `~OptimalControlProblem.compute_trajectory` method.
+Utility functions are available to define common cost functions and
+input/state constraints.  Optimal estimation problems can be solved
+using the `solve_optimal_estimate` function or by using the
+`OptimalEstimationProblem` class and the
+`~OptimalEstimationProblem.compute_estimate` method..
 
 The docstring examples assume the following import commands::
 
@@ -762,7 +763,6 @@ 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):
@@ -1019,7 +1019,7 @@ def __init__(
 
 
 # Compute the input for a nonlinear, (constrained) optimal control problem
-def solve_ocp(
+def solve_optimal_trajectory(
         sys, timepts, X0, cost, trajectory_constraints=None,
         terminal_cost=None, terminal_constraints=None, initial_guess=None,
         basis=None, squeeze=None, transpose=None, return_states=True,
@@ -1222,7 +1222,7 @@ def create_mpc_iosystem(
 
     constraints : list of tuples, optional
         List of constraints that should hold at each point in the time
-        vector.  See `solve_ocp` for more details.
+        vector.  See `solve_optimal_trajectory` for more details.
 
     terminal_cost : callable, optional
         Function that returns the terminal cost given the final state
@@ -2022,7 +2022,7 @@ def __init__(
 
 
 # Compute the finite horizon estimate for a nonlinear system
-def solve_oep(
+def solve_optimal_estimate(
         sys, timepts, Y, U, trajectory_cost, X0=None,
         trajectory_constraints=None, initial_guess=None,
         squeeze=None, print_summary=True, **kwargs):
@@ -2049,7 +2049,7 @@ def solve_oep(
         Mean value of the initial condition (defaults to 0).
     trajectory_constraints : list of tuples, optional
         List of constraints that should hold at each point in the time
-        vector.  See `solve_ocp` for more information.
+        vector.  See `solve_optimal_trajectory` for more information.
     control_indices : int, slice, or list of int or string, optional
         Specify the indices in the system input vector that correspond to
         the control inputs.  For more information on possible values, see
@@ -2546,3 +2546,8 @@ def _process_constraints(clist, name):
                  constraint.lb, constraint.ub))
 
     return constraint_list
+
+
+# Convenience aliases
+solve_ocp = solve_optimal_trajectory
+solve_oep = solve_optimal_estimate

control/statesp.py

@@ -785,34 +785,7 @@ def __call__(self, x, squeeze=None, warn_infinite=True):
         in the complex plane, where `x` is `s` for continuous-time systems
         and `z` for discrete-time systems.
 
-        By default, a (complex) scalar will be returned for SISO systems
-        and a p x m array will be return for MIMO systems with m inputs and
-        p outputs.  This can be changed using the `squeeze` keyword.
-
-        To evaluate at a frequency `omega` in radians per second,
-        enter ``x = omega * 1j`` for continuous-time systems,
-        ``x = exp(1j * omega * dt)`` for discrete-time systems, or
-        use the `~LTI.frequency_response` method.
-
-        Parameters
-        ----------
-        x : complex or complex 1D array_like
-            Complex value(s) at which transfer function will be evaluated.
-        squeeze : bool, optional
-            Squeeze output, as described below.  Default value can be set
-            using `config.defaults['control.squeeze_frequency_response']`.
-        warn_infinite : bool, optional If set to False, turn off
-            divide by zero warning.
-
-        Returns
-        -------
-        fresp : complex ndarray
-            The value of the system transfer function at `x`.  If the system
-            is SISO and `squeeze` is not True, the shape of the array matches
-            the shape of `x`.  If the system is not SISO or `squeeze` is
-            False, the first two dimensions of the array are indices for the
-            output and input and the remaining dimensions match `x`.  If
-            `squeeze` is True then single-dimensional axes are removed.
+        See `LTI.__call__` for details.
 
         Examples
         --------

control/stochsys.py

@@ -430,7 +430,7 @@ def create_estimator_iosystem(
     References
     ----------
     .. [1] R. M. Murray, `Optimization-Based Control
-       <https://fbswiki.org/OBC`_, 2013.
+       <https://fbswiki.org/OBC>`_, 2013.
 
     """
 

control/tests/docstrings_test.py

@@ -48,7 +48,8 @@
 keyword_skiplist = {
     control.input_output_response: ['method'],
     control.nyquist_plot: ['color'],                        # separate check
-    control.optimal.solve_ocp: ['method', 'return_x'],      # deprecated
+    control.optimal.solve_optimal_trajectory:
+      ['method', 'return_x'],                               # deprecated
     control.sisotool: ['kvect'],                            # deprecated
     control.nyquist_response: ['return_contour'],           # deprecated
     control.create_estimator_iosystem: ['state_labels'],    # deprecated
@@ -61,7 +62,7 @@
     control.flatsys.point_to_point: [
         'method', 'options',                                # minimize_kwargs
     ],
-    control.flatsys.solve_flat_ocp: [
+    control.flatsys.solve_flat_optimal: [
         'method', 'options',                                # minimize_kwargs
     ],
     control.optimal.OptimalControlProblem: [

control/tests/flatsys_test.py

@@ -198,7 +198,7 @@ def test_kinematic_car_ocp(
         with warnings.catch_warnings():
             warnings.filterwarnings(
                 'ignore', message="unable to solve", category=UserWarning)
-            traj_ocp = fs.solve_flat_ocp(
+            traj_ocp = fs.solve_flat_optimal(
                 vehicle_flat, timepts, x0, u0,
                 trajectory_cost=traj_cost,
                 trajectory_constraints=input_constraints,
@@ -384,7 +384,7 @@ def test_flat_solve_ocp(self, basis):
         terminal_cost = opt.quadratic_cost(
             flat_sys, 1e3, 1e3, x0=xf, u0=uf)
 
-        traj_cost = fs.solve_flat_ocp(
+        traj_cost = fs.solve_flat_optimal(
             flat_sys, timepts, x0, u0,
             terminal_cost=terminal_cost, basis=basis)
 
@@ -398,7 +398,7 @@ def test_flat_solve_ocp(self, basis):
         # Solve with trajectory and terminal cost functions
         trajectory_cost = opt.quadratic_cost(flat_sys, 0, 1, x0=xf, u0=uf)
 
-        traj_cost = fs.solve_flat_ocp(
+        traj_cost = fs.solve_flat_optimal(
             flat_sys, timepts, x0, u0, terminal_cost=terminal_cost,
             trajectory_cost=trajectory_cost, basis=basis)
 
@@ -421,7 +421,7 @@ def test_flat_solve_ocp(self, basis):
         assert np.any(x_cost[0, :] < lb[0]) or np.any(x_cost[0, :] > ub[0]) \
             or np.any(x_cost[1, :] < lb[1]) or np.any(x_cost[1, :] > ub[1])
 
-        traj_const = fs.solve_flat_ocp(
+        traj_const = fs.solve_flat_optimal(
             flat_sys, timepts, x0, u0,
             terminal_cost=terminal_cost, trajectory_cost=trajectory_cost,
             trajectory_constraints=constraints, basis=basis,
@@ -444,7 +444,7 @@ def test_flat_solve_ocp(self, basis):
         # Use alternative keywords as well
         nl_constraints = [
             (sp.optimize.NonlinearConstraint, lambda x, u: x, lb, ub)]
-        traj_nlconst = fs.solve_flat_ocp(
+        traj_nlconst = fs.solve_flat_optimal(
             flat_sys, timepts, x0, u0,
             trajectory_cost=trajectory_cost, terminal_cost=terminal_cost,
             trajectory_constraints=nl_constraints, basis=basis,
@@ -640,7 +640,7 @@ def test_solve_flat_ocp_errors(self):
         # Solving without basis specified should be OK (may generate warning)
         with warnings.catch_warnings():
             warnings.simplefilter("ignore")
-            traj = fs.solve_flat_ocp(flat_sys, timepts, x0, u0, cost_fcn)
+            traj = fs.solve_flat_optimal(flat_sys, timepts, x0, u0, cost_fcn)
         x, u = traj.eval(timepts)
         np.testing.assert_array_almost_equal(x0, x[:, 0])
         if not traj.success:
@@ -653,40 +653,40 @@ def test_solve_flat_ocp_errors(self):
 
         # Solving without a cost function generates an error
         with pytest.raises(TypeError, match="cost required"):
-            traj = fs.solve_flat_ocp(flat_sys, timepts, x0, u0)
+            traj = fs.solve_flat_optimal(flat_sys, timepts, x0, u0)
 
         # Try to optimize with insufficient degrees of freedom
         with pytest.raises(ValueError, match="basis set is too small"):
-            traj = fs.solve_flat_ocp(
+            traj = fs.solve_flat_optimal(
                 flat_sys, timepts, x0, u0, trajectory_cost=cost_fcn,
                 basis=fs.PolyFamily(2))
 
         # Solve with the errors in the various input arguments
         with pytest.raises(ValueError, match="Initial state: Wrong shape"):
-            traj = fs.solve_flat_ocp(
+            traj = fs.solve_flat_optimal(
                 flat_sys, timepts, np.zeros(3), u0, cost_fcn)
         with pytest.raises(ValueError, match="Initial input: Wrong shape"):
-            traj = fs.solve_flat_ocp(
+            traj = fs.solve_flat_optimal(
                 flat_sys, timepts, x0, np.zeros(3), cost_fcn)
 
         # Constraint that isn't a constraint
         with pytest.raises(TypeError, match="must be a list"):
-            traj = fs.solve_flat_ocp(
+            traj = fs.solve_flat_optimal(
                 flat_sys, timepts, x0, u0, cost_fcn,
                 trajectory_constraints=np.eye(2), basis=fs.PolyFamily(8))
 
         # Unknown constraint type
         with pytest.raises(TypeError, match="unknown constraint type"):
-            traj = fs.solve_flat_ocp(
+            traj = fs.solve_flat_optimal(
                 flat_sys, timepts, x0, u0, cost_fcn,
                 trajectory_constraints=[(None, 0, 0, 0)],
                 basis=fs.PolyFamily(8))
 
         # Method arguments, parameters
-        traj_method = fs.solve_flat_ocp(
+        traj_method = fs.solve_flat_optimal(
             flat_sys, timepts, x0, u0, trajectory_cost=cost_fcn,
             basis=fs.PolyFamily(6), minimize_method='slsqp')
-        traj_kwarg = fs.solve_flat_ocp(
+        traj_kwarg = fs.solve_flat_optimal(
             flat_sys, timepts, x0, u0, trajectory_cost=cost_fcn,
             basis=fs.PolyFamily(6), minimize_kwargs={'method': 'slsqp'})
         np.testing.assert_allclose(
@@ -695,7 +695,7 @@ def test_solve_flat_ocp_errors(self):
 
         # Unrecognized keywords
         with pytest.raises(TypeError, match="unrecognized keyword"):
-            traj_method = fs.solve_flat_ocp(
+            traj_method = fs.solve_flat_optimal(
                 flat_sys, timepts, x0, u0, cost_fcn, solve_ivp_method=None)
 
     @pytest.mark.parametrize(

control/tests/kwargs_test.py

@@ -308,11 +308,15 @@ def test_response_plot_kwargs(data_fcn, plot_fcn, mimo):
     'zpk': test_unrecognized_kwargs,
     'flatsys.point_to_point':
         flatsys_test.TestFlatSys.test_point_to_point_errors,
+    'flatsys.solve_flat_optimal':
+        flatsys_test.TestFlatSys.test_solve_flat_ocp_errors,
     'flatsys.solve_flat_ocp':
         flatsys_test.TestFlatSys.test_solve_flat_ocp_errors,
     'flatsys.FlatSystem.__init__': test_unrecognized_kwargs,
     'optimal.create_mpc_iosystem': optimal_test.test_mpc_iosystem_rename,
+    'optimal.solve_optimal_trajectory': optimal_test.test_ocp_argument_errors,
     'optimal.solve_ocp': optimal_test.test_ocp_argument_errors,
+    'optimal.solve_optimal_estimate': optimal_test.test_oep_argument_errors,
     'optimal.solve_oep': optimal_test.test_oep_argument_errors,
     'ControlPlot.set_plot_title': freqplot_test.test_suptitle,
     'FrequencyResponseData.__init__':