Skip to content

Commit 01e8c3c

Browse files
murrayrmmurrayrm
committed
update nonlinear.rst and associated doc files
1 parent aa05537 commit 01e8c3c

11 files changed

Lines changed: 315 additions & 255 deletions

File tree

‎control/flatsys/__init__.py‎

Lines changed: 1 addition & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,9 @@
11
# flatsys/__init__.py: flat systems package initialization file
22
#
3-
# Copyright (c) 2019 by California Institute of Technology
4-
# All rights reserved.
5-
#
6-
# Redistribution and use in source and binary forms, with or without
7-
# modification, are permitted provided that the following conditions
8-
# are met:
9-
#
10-
# 1. Redistributions of source code must retain the above copyright
11-
# notice, this list of conditions and the following disclaimer.
12-
#
13-
# 2. Redistributions in binary form must reproduce the above copyright
14-
# notice, this list of conditions and the following disclaimer in the
15-
# documentation and/or other materials provided with the distribution.
16-
#
17-
# 3. Neither the name of the California Institute of Technology nor
18-
# the names of its contributors may be used to endorse or promote
19-
# products derived from this software without specific prior
20-
# written permission.
21-
#
22-
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
23-
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
24-
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
25-
# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL CALTECH
26-
# OR THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
27-
# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
28-
# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
29-
# USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
30-
# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
31-
# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
32-
# OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33-
# SUCH DAMAGE.
34-
#
353
# Author: Richard M. Murray
364
# Date: 1 Jul 2019
375

38-
r"""Differentially flat systems sub-package.
39-
40-
The :mod:`control.flatsys` sub-package contains a set of classes and
6+
r"""The :mod:`control.flatsys` sub-package contains a set of classes and
417
functions to compute trajectories for differentially flat systems.
428
439
A differentially flat system is defined by creating an object using the

‎doc/conf.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@
2929
# -- Project information -----------------------------------------------------
3030

3131
project = u'Python Control Systems Library'
32-
copyright = u'2023, python-control.org'
32+
copyright = u'2024, python-control.org'
3333
author = u'Python Control Developers'
3434

3535
# Version information - read from the source code
@@ -285,7 +285,7 @@ def linkcode_resolve(domain, info):
285285
doctest_global_setup = """
286286
import numpy as np
287287
import control as ct
288-
import control.optimal as obc
288+
import control.optimal as opt
289289
import control.flatsys as fs
290290
import control.phaseplot as pp
291291
ct.reset_defaults()

‎doc/descfcn.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
.. _descfcn-module:
2-
31
.. currentmodule:: control
42

3+
.. _descfcn-module:
4+
55
Describing functions
66
====================
77

‎doc/figures/servomech-diagram.png‎

51.9 KB
Loading

‎doc/flatsys.rst‎

Lines changed: 21 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,40 @@
11
.. _flatsys-module:
22

3-
***************************
43
Differentially flat systems
5-
***************************
4+
===========================
65

76
.. automodule:: control.flatsys
7+
:noindex:
88
:no-members:
99
:no-inherited-members:
1010
:no-special-members:
1111

12+
.. currentmodule:: control
13+
14+
1215
Overview of differential flatness
13-
=================================
16+
---------------------------------
1417

1518
A nonlinear differential equation of the form
1619

1720
.. math::
21+
1822
\dot x = f(x, u), \qquad x \in R^n, u \in R^m
1923
2024
is *differentially flat* if there exists a function :math:`\alpha` such that
2125

2226
.. math::
27+
2328
z = \alpha(x, u, \dot u\, \dots, u^{(p)})
2429
2530
and we can write the solutions of the nonlinear system as functions of
2631
:math:`z` and a finite number of derivatives
2732

2833
.. math::
34+
:label: flat2state
35+
2936
x &= \beta(z, \dot z, \dots, z^{(q)}) \\
3037
u &= \gamma(z, \dot z, \dots, z^{(q)}).
31-
:label: flat2state
3238
3339
For a differentially flat system, all of the feasible trajectories for
3440
the system can be written as functions of a flat output :math:`z(\cdot)` and
@@ -42,11 +48,13 @@ space, and then map these to appropriate inputs. Suppose we wish to
4248
generate a feasible trajectory for the nonlinear system
4349

4450
.. math::
51+
4552
\dot x = f(x, u), \qquad x(0) = x_0,\, x(T) = x_f.
4653
4754
If the system is differentially flat then
4855

4956
.. math::
57+
5058
x(0) &= \beta\bigl(z(0), \dot z(0), \dots, z^{(q)}(0) \bigr) = x_0, \\
5159
x(T) &= \gamma\bigl(z(T), \dot z(T), \dots, z^{(q)}(T) \bigr) = x_f,
5260
@@ -64,6 +72,7 @@ trajectory of the system. We can parameterize the flat output trajectory
6472
using a set of smooth basis functions :math:`\psi_i(t)`:
6573

6674
.. math::
75+
6776
z(t) = \sum_{i=1}^N c_i \psi_i(t), \qquad c_i \in R
6877
6978
We seek a set of coefficients :math:`c_i`, :math:`i = 1, \dots, N` such
@@ -72,6 +81,7 @@ that :math:`z(t)` satisfies the boundary conditions for :math:`x(0)` and
7281
the derivatives of the basis functions:
7382

7483
.. math::
84+
7585
\dot z(t) &= \sum_{i=1}^N c_i \dot \psi_i(t) \\
7686
&\,\vdots \\
7787
\dot z^{(q)}(t) &= \sum_{i=1}^N c_i \psi^{(q)}_i(t).
@@ -80,6 +90,7 @@ We can thus write the conditions on the flat outputs and their
8090
derivatives as
8191

8292
.. math::
93+
8394
\begin{bmatrix}
8495
\psi_1(0) & \psi_2(0) & \dots & \psi_N(0) \\
8596
\dot \psi_1(0) & \dot \psi_2(0) & \dots & \dot \psi_N(0) \\
@@ -99,6 +110,7 @@ derivatives as
99110
This equation is a *linear* equation of the form
100111

101112
.. math::
113+
102114
M c = \begin{bmatrix} \bar z(0) \\ \bar z(T) \end{bmatrix}
103115
104116
where :math:`\bar z` is called the *flat flag* for the system.
@@ -107,7 +119,7 @@ column rank, we can solve for a (possibly non-unique) :math:`\alpha` that
107119
solves the trajectory generation problem.
108120

109121
Module usage
110-
============
122+
------------
111123

112124
To create a trajectory for a differentially flat system, a
113125
:class:`~flatsys.FlatSystem` object must be created. This is done
@@ -138,7 +150,7 @@ and their derivatives up to order :math:`q_i`:
138150
The number of flat outputs must match the number of system inputs.
139151

140152
For a linear system, a flat system representation can be generated by
141-
passing a :class:`~control.StateSpace` system to the
153+
passing a :class:`StateSpace` system to the
142154
:func:`~flatsys.flatsys` factory function::
143155

144156
sys = fs.flatsys(linsys)
@@ -180,7 +192,7 @@ where `T` is a list of times on which the trajectory should be evaluated
180192

181193
The :func:`~flatsys.point_to_point` function also allows the
182194
specification of a cost function and/or constraints, in the same
183-
format as :func:`~control.optimal.solve_ocp`.
195+
format as :func:`optimal.solve_ocp`.
184196

185197
The :func:`~flatsys.solve_flat_ocp` function can be used to
186198
solve an optimal control problem without a final state::
@@ -195,7 +207,7 @@ vector. The `terminal_cost` parameter can be used to specify a cost
195207
function for the final point in the trajectory.
196208

197209
Example
198-
=======
210+
-------
199211

200212
To illustrate how we can use a two degree-of-freedom design to improve the
201213
performance of the system, consider the problem of steering a car to change
@@ -309,9 +321,7 @@ cost:`
309321
x, u = traj.eval(t)
310322

311323
Module classes and functions
312-
============================
313-
314-
.. currentmodule:: control
324+
----------------------------
315325

316326
.. autosummary::
317327
:template: custom-class-template.rst

‎doc/iosys.rst‎

Lines changed: 9 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,19 @@
11
.. _iosys-module:
22

3-
********************
4-
Input/output systems
5-
********************
3+
**************************
4+
Interconnected I/O Systems
5+
**************************
66

7-
Module usage
8-
============
7+
Operator overloading
8+
====================
99

10-
An input/output system is defined as a dynamical system that has a system
11-
state as well as inputs and outputs (either inputs or states can be empty).
12-
The dynamics of the system can be in continuous or discrete time. To simulate
13-
an input/output system, use the :func:`~control.input_output_response`
14-
function::
1510

16-
resp = ct.input_output_response(io_sys, T, U, X0, params)
17-
t, y, x = resp.time, resp.outputs, resp.states
11+
Block diagram algebra
12+
=====================
1813

19-
An input/output system can be linearized around an equilibrium point
20-
to obtain a :class:`~control.StateSpace` linear system. Use the
21-
:func:`~control.find_operating_point` function to obtain an
22-
equilibrium point and the :func:`~control.linearize` function to
23-
linearize about that equilibrium point::
2414

25-
xeq, ueq = ct.find_operating_point(io_sys, X0, U0)
26-
ss_sys = ct.linearize(io_sys, xeq, ueq)
27-
28-
Input/output systems are automatically created for state space LTI systems
29-
when using the :func:`~control.ss` function. Nonlinear input/output
30-
systems can be created using the :func:`~control.nlsys` function, which
31-
requires the definition of an update function (for the right hand side of
32-
the differential or different equation) and an output function (computes
33-
the outputs from the state)::
34-
35-
io_sys = ct.nlsys(updfcn, outfcn, inputs=M, outputs=P, states=N)
15+
Signal-based interconnection
16+
============================
3617

3718
More complex input/output systems can be constructed by using the
3819
:func:`~control.interconnect` function, which allows a collection of
@@ -556,25 +537,3 @@ bottom of the file).
556537

557538
Integral action and state estimation can also be used with gain
558539
scheduled controllers.
559-
560-
561-
Module classes and functions
562-
============================
563-
564-
.. autosummary::
565-
:template: custom-class-template.rst
566-
567-
~control.InputOutputSystem
568-
~control.InterconnectedSystem
569-
~control.LinearICSystem
570-
~control.NonlinearIOSystem
571-
~control.OperatingPoint
572-
573-
.. autosummary::
574-
575-
~control.find_operating_point
576-
~control.interconnect
577-
~control.input_output_response
578-
~control.linearize
579-
~control.nlsys
580-
~control.summing_junction

0 commit comments

Comments
 (0)