updated flatsys documentation

murrayrm · murrayrm · commit 2901cbe4e386 · 2022-08-22T22:25:56.000-07:00
diff --git a/control/flatsys/__init__.py b/control/flatsys/__init__.py
@@ -46,7 +46,9 @@
 defined using the :class:`~control.flatsys.BasisFamily` class.  The resulting
 trajectory is return as a :class:`~control.flatsys.SystemTrajectory` object
 and can be evaluated using the :func:`~control.flatsys.SystemTrajectory.eval`
-member function.
+member function.  Alternatively, the :func:`~control.flatsys.solve_flat_ocp`
+function can be used to solve an optimal control problem with trajectory and
+final costs or constraints.
 
 """
 
diff --git a/control/flatsys/basis.py b/control/flatsys/basis.py
@@ -79,6 +79,7 @@ def var_ncoefs(self, var):
         return self.N if self.nvars is None else self.coef_length[var]
 
     def eval(self, coeffs, tlist, var=None):
+        """Compute function values given the coefficients and time points."""
         if self.nvars is None and var != None:
             raise SystemError("multi-variable call to a scalar basis")
 
@@ -108,4 +109,5 @@ def eval(self, coeffs, tlist, var=None):
                 for t in tlist])
 
     def eval_deriv(self, i, j, t, var=None):
+        """Evaluate the kth derivative of the ith basis function at time t."""
         raise NotImplementedError("Internal error; improper basis functions")
diff --git a/control/flatsys/bezier.py b/control/flatsys/bezier.py
@@ -48,15 +48,23 @@ class BezierFamily(BasisFamily):
     This class represents the family of polynomials of the form
 
     .. math::
-         \phi_i(t) = \sum_{i=0}^n {n \choose i}
-             \left( \frac{t}{T_\text{f}} - t \right)^{n-i}
-             \left( \frac{t}{T_f} \right)^i
+         \phi_i(t) = \sum_{i=0}^N {N \choose i}
+             \left( \frac{t}{T} - t \right)^{N-i}
+             \left( \frac{t}{T} \right)^i
+
+    Parameters
+    ----------
+    N : int
+        Degree of the Bezier curve.
+
+    T : float
+        Final time (used for rescaling).
 
     """
     def __init__(self, N, T=1):
         """Create a polynomial basis of order N."""
         super(BezierFamily, self).__init__(N)
-        self.T = T                      # save end of time interval
+        self.T = float(T)       # save end of time interval
 
     # Compute the kth derivative of the ith basis function at time t
     def eval_deriv(self, i, k, t, var=None):
diff --git a/control/flatsys/bspline.py b/control/flatsys/bspline.py
@@ -14,40 +14,35 @@ class BSplineFamily(BasisFamily):
     """B-spline basis functions.
 
     This class represents a B-spline basis for piecewise polynomials defined
-    across a set of breakpoints with given order and smoothness.
+    across a set of breakpoints with given degree and smoothness.  On each
+    interval between two breakpoints, we have a polynomial of a given degree
+    and the spline is continuous up to a given smoothness at interior
+    breakpoints.
+
+    Parameters
+    ----------
+    breakpoints : 1D array or 2D array of float
+        The breakpoints for the spline(s).
+
+    degree : int or list of ints
+        For each spline variable, the degree of the polynomial between
+        breakpoints.  If a single number is given and more than one spline
+        variable is specified, the same degree is used for each spline
+        variable.
+
+    smoothness : int or list of ints
+        For each spline variable, the smoothness at breakpoints (number of
+        derivatives that should match).
+
+    vars : None or int, optional
+        The number of spline variables.  If specified as None (default),
+        then the spline basis describes a single variable, with no indexing.
+        If the number of spine variables is > 0, then the spline basis is
+        index using the `var` keyword.
 
     """
     def __init__(self, breakpoints, degree, smoothness=None, vars=None):
-        """Create a B-spline basis for piecewise smooth polynomials
-
-        Define B-spline polynomials for a set of one or more variables.
-        B-splines are used as a basis for a set of piecewise smooth
-        polynomials joined at breakpoints. On each interval we have a
-        polynomial of a given order and the spline is continuous up to a
-        given smoothness at interior breakpoints.
-
-        Parameters
-        ----------
-        breakpoints : 1D array or 2D array of float
-            The breakpoints for the spline(s).
-
-        degree : int or list of ints
-            For each spline variable, the degree of the polynomial between
-            break points.  If a single number is given and more than one
-            spline variable is specified, the same order is used for each
-            spline variable.
-
-        smoothness : int or list of ints
-            For each spline variable, the smoothness at breakpoints (number
-            of derivatives that should match).
-
-        vars : None or int, optional
-            The number of spline variables.  If specified as None (default),
-            then the spline basis describes a single variable, with no
-            indexing.  If the number of spine variables is > 0, then the
-            spline basis is index using the `var` keyword.
-
-        """
+        """Create a B-spline basis for piecewise smooth polynomials."""
         # Process the breakpoints for the spline */
         breakpoints = np.array(breakpoints, dtype=float)
         if breakpoints.ndim == 2:
@@ -71,19 +66,19 @@ def __init__(self, breakpoints, degree, smoothness=None, vars=None):
             self.nvars = nvars
 
         #
-        # Process B-spline parameters (order, smoothness)
+        # Process B-spline parameters (degree, smoothness)
         #
         # B-splines are defined on a set of intervals separated by
         # breakpoints.  On each interval we have a polynomial of a certain
-        # order and the spline is continuous up to a given smoothness at
+        # degree and the spline is continuous up to a given smoothness at
         # breakpoints.  The code in this section allows some flexibility in
         # the way that all of this information is supplied, including using
         # scalar values for parameters (which are then broadcast to each
         # output) and inferring values and dimensions from other
         # information, when possible.
         #
 
-        # Utility function for broadcasting spline params (order, smoothness)
+        # Utility function for broadcasting spline params (degree, smoothness)
         def process_spline_parameters(
             values, length, allowed_types, minimum=0,
             default=None, name='unknown'):
diff --git a/control/flatsys/flatsys.py b/control/flatsys/flatsys.py
@@ -61,8 +61,10 @@ class FlatSystem(NonlinearIOSystem):
     ----------
     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.
+
     updfcn : callable, optional
         Function returning the state update function
 
@@ -73,13 +75,15 @@ class FlatSystem(NonlinearIOSystem):
         time, and `param` is an optional dict containing the values of
         parameters used by the function.  If not specified, the state
         space update will be computed using the flat system coordinates.
+
     outfcn : callable
         Function returning the output at the given state
 
             `outfcn(t, x, u[, param]) -> array`
 
         where the arguments are the same as for `upfcn`.  If not
         specified, the output will be the flat outputs.
+
     inputs : int, list of str, or None
         Description of the system inputs.  This can be given as an integer
         count or as a list of strings that name the individual signals.
@@ -88,19 +92,24 @@ class FlatSystem(NonlinearIOSystem):
         this parameter is not given or given as `None`, the relevant
         quantity will be determined when possible based on other
         information provided to functions using the system.
+
     outputs : int, list of str, or None
         Description of the system outputs.  Same format as `inputs`.
+
     states : int, list of str, or None
         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.
+
     params : dict, optional
         Parameter values for the systems.  Passed to the evaluation
         functions for the system as default values, overriding internal
         defaults.
+
     name : string, optional
         System name (used for specifying signals)
 
@@ -638,7 +647,7 @@ def solve_flat_ocp(
     -----
     1. Additional keyword parameters can be used to fine tune the behavior
        of the underlying optimization function.  See `minimize_*` keywords
-       in :func:`OptimalControlProblem` for more information.
+       in :func:`~control.optimal.OptimalControlProblem` for more information.
 
     2. The return data structure includes the following additional attributes:
            * success : bool indicating whether the optimization succeeded
diff --git a/control/flatsys/poly.py b/control/flatsys/poly.py
@@ -47,13 +47,21 @@ class PolyFamily(BasisFamily):
     This class represents the family of polynomials of the form
 
     .. math::
-         \phi_i(t) = t^i
+         \phi_i(t) = \left( \frac{t}{T} \right)^i
+
+    Parameters
+    ----------
+    N : int
+        Degree of the Bezier curve.
+
+    T : float
+        Final time (used for rescaling).
 
     """
-    def __init__(self, N, T=1.):
+    def __init__(self, N, T=1):
         """Create a polynomial basis of order N."""
         super(PolyFamily, self).__init__(N)
-        self.T = T
+        self.T = float(T)       # save end of time interval
 
     # Compute the kth derivative of the ith basis function at time t
     def eval_deriv(self, i, k, t, var=None):
diff --git a/control/tests/flatsys_test.py b/control/tests/flatsys_test.py
@@ -12,6 +12,7 @@
 import pytest
 import scipy as sp
 import re
+import warnings
 
 import control as ct
 import control.flatsys as fs
@@ -590,8 +591,10 @@ def test_solve_flat_ocp_errors(self):
         cost_fcn = opt.quadratic_cost(
             flat_sys, np.diag([1, 1]), 1, x0=xf, u0=uf)
 
-        # Solving without basis specified should be OK
-        traj = fs.solve_flat_ocp(flat_sys, timepts, x0, u0, cost_fcn)
+        # 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)
         x, u = traj.eval(timepts)
         np.testing.assert_array_almost_equal(x0, x[:, 0])
         if not traj.success:
diff --git a/doc/conf.py b/doc/conf.py
@@ -87,7 +87,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
diff --git a/doc/flatsys.rst b/doc/flatsys.rst

Original file line number	Diff line number	Diff line change
`@@ -87,7 +87,7 @@`
`87`	`87`	`#`
`88`	`88`	`# This is also used if you do content translation via gettext catalogs.`
`89`	`89`	`# Usually you set "language" from the command line for these cases.`
`90`		`-language = None`
	`90`	`+language = 'en'`
`91`	`91`
`92`	`92`	`# List of patterns, relative to source directory, that match files and`
`93`	`93`	`# directories to ignore when looking for source files.`