Skip to content

Commit 2901cbe

Browse files
murrayrmmurrayrm
committed
updated flatsys documentation
1 parent e65c4f2 commit 2901cbe

9 files changed

Lines changed: 137 additions & 60 deletions

File tree

‎control/flatsys/__init__.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,9 @@
4646
defined using the :class:`~control.flatsys.BasisFamily` class. The resulting
4747
trajectory is return as a :class:`~control.flatsys.SystemTrajectory` object
4848
and can be evaluated using the :func:`~control.flatsys.SystemTrajectory.eval`
49-
member function.
49+
member function. Alternatively, the :func:`~control.flatsys.solve_flat_ocp`
50+
function can be used to solve an optimal control problem with trajectory and
51+
final costs or constraints.
5052
5153
"""
5254

‎control/flatsys/basis.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,7 @@ def var_ncoefs(self, var):
7979
return self.N if self.nvars is None else self.coef_length[var]
8080

8181
def eval(self, coeffs, tlist, var=None):
82+
"""Compute function values given the coefficients and time points."""
8283
if self.nvars is None and var != None:
8384
raise SystemError("multi-variable call to a scalar basis")
8485

@@ -108,4 +109,5 @@ def eval(self, coeffs, tlist, var=None):
108109
for t in tlist])
109110

110111
def eval_deriv(self, i, j, t, var=None):
112+
"""Evaluate the kth derivative of the ith basis function at time t."""
111113
raise NotImplementedError("Internal error; improper basis functions")

‎control/flatsys/bezier.py‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -48,15 +48,23 @@ class BezierFamily(BasisFamily):
4848
This class represents the family of polynomials of the form
4949
5050
.. math::
51-
\phi_i(t) = \sum_{i=0}^n {n \choose i}
52-
\left( \frac{t}{T_\text{f}} - t \right)^{n-i}
53-
\left( \frac{t}{T_f} \right)^i
51+
\phi_i(t) = \sum_{i=0}^N {N \choose i}
52+
\left( \frac{t}{T} - t \right)^{N-i}
53+
\left( \frac{t}{T} \right)^i
54+
55+
Parameters
56+
----------
57+
N : int
58+
Degree of the Bezier curve.
59+
60+
T : float
61+
Final time (used for rescaling).
5462
5563
"""
5664
def __init__(self, N, T=1):
5765
"""Create a polynomial basis of order N."""
5866
super(BezierFamily, self).__init__(N)
59-
self.T = T # save end of time interval
67+
self.T = float(T) # save end of time interval
6068

6169
# Compute the kth derivative of the ith basis function at time t
6270
def eval_deriv(self, i, k, t, var=None):

‎control/flatsys/bspline.py‎

Lines changed: 29 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -14,40 +14,35 @@ class BSplineFamily(BasisFamily):
1414
"""B-spline basis functions.
1515
1616
This class represents a B-spline basis for piecewise polynomials defined
17-
across a set of breakpoints with given order and smoothness.
17+
across a set of breakpoints with given degree and smoothness. On each
18+
interval between two breakpoints, we have a polynomial of a given degree
19+
and the spline is continuous up to a given smoothness at interior
20+
breakpoints.
21+
22+
Parameters
23+
----------
24+
breakpoints : 1D array or 2D array of float
25+
The breakpoints for the spline(s).
26+
27+
degree : int or list of ints
28+
For each spline variable, the degree of the polynomial between
29+
breakpoints. If a single number is given and more than one spline
30+
variable is specified, the same degree is used for each spline
31+
variable.
32+
33+
smoothness : int or list of ints
34+
For each spline variable, the smoothness at breakpoints (number of
35+
derivatives that should match).
36+
37+
vars : None or int, optional
38+
The number of spline variables. If specified as None (default),
39+
then the spline basis describes a single variable, with no indexing.
40+
If the number of spine variables is > 0, then the spline basis is
41+
index using the `var` keyword.
1842
1943
"""
2044
def __init__(self, breakpoints, degree, smoothness=None, vars=None):
21-
"""Create a B-spline basis for piecewise smooth polynomials
22-
23-
Define B-spline polynomials for a set of one or more variables.
24-
B-splines are used as a basis for a set of piecewise smooth
25-
polynomials joined at breakpoints. On each interval we have a
26-
polynomial of a given order and the spline is continuous up to a
27-
given smoothness at interior breakpoints.
28-
29-
Parameters
30-
----------
31-
breakpoints : 1D array or 2D array of float
32-
The breakpoints for the spline(s).
33-
34-
degree : int or list of ints
35-
For each spline variable, the degree of the polynomial between
36-
break points. If a single number is given and more than one
37-
spline variable is specified, the same order is used for each
38-
spline variable.
39-
40-
smoothness : int or list of ints
41-
For each spline variable, the smoothness at breakpoints (number
42-
of derivatives that should match).
43-
44-
vars : None or int, optional
45-
The number of spline variables. If specified as None (default),
46-
then the spline basis describes a single variable, with no
47-
indexing. If the number of spine variables is > 0, then the
48-
spline basis is index using the `var` keyword.
49-
50-
"""
45+
"""Create a B-spline basis for piecewise smooth polynomials."""
5146
# Process the breakpoints for the spline */
5247
breakpoints = np.array(breakpoints, dtype=float)
5348
if breakpoints.ndim == 2:
@@ -71,19 +66,19 @@ def __init__(self, breakpoints, degree, smoothness=None, vars=None):
7166
self.nvars = nvars
7267

7368
#
74-
# Process B-spline parameters (order, smoothness)
69+
# Process B-spline parameters (degree, smoothness)
7570
#
7671
# B-splines are defined on a set of intervals separated by
7772
# breakpoints. On each interval we have a polynomial of a certain
78-
# order and the spline is continuous up to a given smoothness at
73+
# degree and the spline is continuous up to a given smoothness at
7974
# breakpoints. The code in this section allows some flexibility in
8075
# the way that all of this information is supplied, including using
8176
# scalar values for parameters (which are then broadcast to each
8277
# output) and inferring values and dimensions from other
8378
# information, when possible.
8479
#
8580

86-
# Utility function for broadcasting spline params (order, smoothness)
81+
# Utility function for broadcasting spline params (degree, smoothness)
8782
def process_spline_parameters(
8883
values, length, allowed_types, minimum=0,
8984
default=None, name='unknown'):

‎control/flatsys/flatsys.py‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,8 +61,10 @@ class FlatSystem(NonlinearIOSystem):
6161
----------
6262
forward : callable
6363
A function to compute the flat flag given the states and input.
64+
6465
reverse : callable
6566
A function to compute the states and input given the flat flag.
67+
6668
updfcn : callable, optional
6769
Function returning the state update function
6870
@@ -73,13 +75,15 @@ class FlatSystem(NonlinearIOSystem):
7375
time, and `param` is an optional dict containing the values of
7476
parameters used by the function. If not specified, the state
7577
space update will be computed using the flat system coordinates.
78+
7679
outfcn : callable
7780
Function returning the output at the given state
7881
7982
`outfcn(t, x, u[, param]) -> array`
8083
8184
where the arguments are the same as for `upfcn`. If not
8285
specified, the output will be the flat outputs.
86+
8387
inputs : int, list of str, or None
8488
Description of the system inputs. This can be given as an integer
8589
count or as a list of strings that name the individual signals.
@@ -88,19 +92,24 @@ class FlatSystem(NonlinearIOSystem):
8892
this parameter is not given or given as `None`, the relevant
8993
quantity will be determined when possible based on other
9094
information provided to functions using the system.
95+
9196
outputs : int, list of str, or None
9297
Description of the system outputs. Same format as `inputs`.
98+
9399
states : int, list of str, or None
94100
Description of the system states. Same format as `inputs`.
101+
95102
dt : None, True or float, optional
96103
System timebase. None (default) indicates continuous
97104
time, True indicates discrete time with undefined sampling
98105
time, positive number is discrete time with specified
99106
sampling time.
107+
100108
params : dict, optional
101109
Parameter values for the systems. Passed to the evaluation
102110
functions for the system as default values, overriding internal
103111
defaults.
112+
104113
name : string, optional
105114
System name (used for specifying signals)
106115
@@ -638,7 +647,7 @@ def solve_flat_ocp(
638647
-----
639648
1. Additional keyword parameters can be used to fine tune the behavior
640649
of the underlying optimization function. See `minimize_*` keywords
641-
in :func:`OptimalControlProblem` for more information.
650+
in :func:`~control.optimal.OptimalControlProblem` for more information.
642651
643652
2. The return data structure includes the following additional attributes:
644653
* success : bool indicating whether the optimization succeeded

‎control/flatsys/poly.py‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,13 +47,21 @@ class PolyFamily(BasisFamily):
4747
This class represents the family of polynomials of the form
4848
4949
.. math::
50-
\phi_i(t) = t^i
50+
\phi_i(t) = \left( \frac{t}{T} \right)^i
51+
52+
Parameters
53+
----------
54+
N : int
55+
Degree of the Bezier curve.
56+
57+
T : float
58+
Final time (used for rescaling).
5159
5260
"""
53-
def __init__(self, N, T=1.):
61+
def __init__(self, N, T=1):
5462
"""Create a polynomial basis of order N."""
5563
super(PolyFamily, self).__init__(N)
56-
self.T = T
64+
self.T = float(T) # save end of time interval
5765

5866
# Compute the kth derivative of the ith basis function at time t
5967
def eval_deriv(self, i, k, t, var=None):

‎control/tests/flatsys_test.py‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
import pytest
1313
import scipy as sp
1414
import re
15+
import warnings
1516

1617
import control as ct
1718
import control.flatsys as fs
@@ -590,8 +591,10 @@ def test_solve_flat_ocp_errors(self):
590591
cost_fcn = opt.quadratic_cost(
591592
flat_sys, np.diag([1, 1]), 1, x0=xf, u0=uf)
592593

593-
# Solving without basis specified should be OK
594-
traj = fs.solve_flat_ocp(flat_sys, timepts, x0, u0, cost_fcn)
594+
# Solving without basis specified should be OK (may generate warning)
595+
with warnings.catch_warnings():
596+
warnings.simplefilter("ignore")
597+
traj = fs.solve_flat_ocp(flat_sys, timepts, x0, u0, cost_fcn)
595598
x, u = traj.eval(timepts)
596599
np.testing.assert_array_almost_equal(x0, x[:, 0])
597600
if not traj.success:

‎doc/conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@
8787
#
8888
# This is also used if you do content translation via gettext catalogs.
8989
# Usually you set "language" from the command line for these cases.
90-
language = None
90+
language = 'en'
9191

9292
# List of patterns, relative to source directory, that match files and
9393
# directories to ignore when looking for source files.

0 commit comments

Comments
 (0)