update nonlinear.rst and associated doc files

Author: murrayrm

doc/conf.py

@@ -29,7 +29,7 @@
 # -- Project information -----------------------------------------------------
 
 project = u'Python Control Systems Library'
-copyright = u'2023, python-control.org'
+copyright = u'2024, python-control.org'
 author = u'Python Control Developers'
 
 # Version information - read from the source code
@@ -285,7 +285,7 @@ def linkcode_resolve(domain, info):
 doctest_global_setup = """
 import numpy as np
 import control as ct
-import control.optimal as obc
+import control.optimal as opt
 import control.flatsys as fs
 import control.phaseplot as pp
 ct.reset_defaults()

doc/figures/servomech-diagram.png

@@ -1,34 +1,40 @@
+.. currentmodule:: control
+
 .. _flatsys-module:
 
-***************************
 Differentially flat systems
-***************************
+===========================
 
 .. automodule:: control.flatsys
+   :noindex:
    :no-members:
    :no-inherited-members:
    :no-special-members:
 
+
 Overview of differential flatness
-=================================
+---------------------------------
 
 A nonlinear differential equation of the form
 
 .. math::
+   
     \dot x = f(x, u), \qquad x \in R^n, u \in R^m
 
 is *differentially flat* if there exists a function :math:`\alpha` such that
 
 .. math::
+   
     z = \alpha(x, u, \dot u\, \dots, u^{(p)})
 
 and we can write the solutions of the nonlinear system as functions of
 :math:`z` and a finite number of derivatives
 
 .. math::
+    :label: flat2state
+	    
     x &= \beta(z, \dot z, \dots, z^{(q)}) \\
     u &= \gamma(z, \dot z, \dots, z^{(q)}).
-    :label: flat2state
 
 For a differentially flat system, all of the feasible trajectories for
 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
 generate a feasible trajectory for the nonlinear system
 
 .. math::
+   
     \dot x = f(x, u), \qquad x(0) = x_0,\, x(T) = x_f.
 
 If the system is differentially flat then
 
 .. math::
+   
     x(0) &= \beta\bigl(z(0), \dot z(0), \dots, z^{(q)}(0) \bigr) = x_0, \\
     x(T) &= \gamma\bigl(z(T), \dot z(T), \dots, z^{(q)}(T) \bigr) = x_f,
 
@@ -64,6 +72,7 @@ trajectory of the system.  We can parameterize the flat output trajectory
 using a set of smooth basis functions :math:`\psi_i(t)`:
 
 .. math::
+   
   z(t) = \sum_{i=1}^N c_i \psi_i(t), \qquad c_i \in R
 
 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
 the derivatives of the basis functions:
 
 .. math::
+   
   \dot z(t) &= \sum_{i=1}^N c_i \dot \psi_i(t) \\
   &\,\vdots \\
   \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
 derivatives as
 
 .. math::
+   
   \begin{bmatrix}
     \psi_1(0) & \psi_2(0) & \dots & \psi_N(0) \\
     \dot \psi_1(0) & \dot \psi_2(0) & \dots & \dot \psi_N(0) \\
@@ -99,6 +110,7 @@ derivatives as
 This equation is a *linear* equation of the form
 
 .. math::
+   
    M c = \begin{bmatrix} \bar z(0) \\ \bar z(T) \end{bmatrix}
 
 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
 solves the trajectory generation problem.
 
 Module usage
-============
+------------
 
 To create a trajectory for a differentially flat system, a
 :class:`~flatsys.FlatSystem` object must be created.  This is done
@@ -138,7 +150,7 @@ and their derivatives up to order :math:`q_i`:
 The number of flat outputs must match the number of system inputs.
 
 For a linear system, a flat system representation can be generated by
-passing a :class:`~control.StateSpace` system to the
+passing a :class:`StateSpace` system to the
 :func:`~flatsys.flatsys` factory function::
 
     sys = fs.flatsys(linsys)
@@ -180,7 +192,7 @@ where `T` is a list of times on which the trajectory should be evaluated
 
 The :func:`~flatsys.point_to_point` function also allows the
 specification of a cost function and/or constraints, in the same
-format as :func:`~control.optimal.solve_ocp`.
+format as :func:`optimal.solve_ocp`.
 
 The :func:`~flatsys.solve_flat_ocp` function can be used to
 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
 function for the final point in the trajectory.
 
 Example
-=======
+-------
 
 To illustrate how we can use a two degree-of-freedom design to improve the
 performance of the system, consider the problem of steering a car to change
@@ -309,9 +321,7 @@ cost:`
     x, u = traj.eval(t)
 
 Module classes and functions
-============================
-
-.. currentmodule:: control
+----------------------------
 
 .. autosummary::
    :template: custom-class-template.rst

doc/flatsys.rst

@@ -1,38 +1,19 @@
 .. _iosys-module:
 
-********************
-Input/output systems
-********************
+**************************
+Interconnected I/O Systems
+**************************
 
-Module usage
-============
+Operator overloading
+====================
 
-An input/output system is defined as a dynamical system that has a system
-state as well as inputs and outputs (either inputs or states can be empty).
-The dynamics of the system can be in continuous or discrete time.  To simulate
-an input/output system, use the :func:`~control.input_output_response`
-function::
 
-  resp = ct.input_output_response(io_sys, T, U, X0, params)
-  t, y, x = resp.time, resp.outputs, resp.states
+Block diagram algebra
+=====================
 
-An input/output system can be linearized around an equilibrium point
-to obtain a :class:`~control.StateSpace` linear system.  Use the
-:func:`~control.find_operating_point` function to obtain an
-equilibrium point and the :func:`~control.linearize` function to
-linearize about that equilibrium point::
 
-  xeq, ueq = ct.find_operating_point(io_sys, X0, U0)
-  ss_sys = ct.linearize(io_sys, xeq, ueq)
-
-Input/output systems are automatically created for state space LTI systems
-when using the :func:`~control.ss` function.  Nonlinear input/output
-systems can be created using the :func:`~control.nlsys` function, which
-requires the definition of an update function (for the right hand side of
-the differential or different equation) and an output function (computes
-the outputs from the state)::
-
-  io_sys = ct.nlsys(updfcn, outfcn, inputs=M, outputs=P, states=N)
+Signal-based interconnection
+============================
 
 More complex input/output systems can be constructed by using the
 :func:`~control.interconnect` function, which allows a collection of
@@ -556,25 +537,3 @@ bottom of the file).
 
 Integral action and state estimation can also be used with gain
 scheduled controllers.
-
-
-Module classes and functions
-============================
-
-.. autosummary::
-   :template: custom-class-template.rst
-
-   ~control.InputOutputSystem
-   ~control.InterconnectedSystem
-   ~control.LinearICSystem
-   ~control.NonlinearIOSystem
-   ~control.OperatingPoint
-
-.. autosummary::
-
-   ~control.find_operating_point
-   ~control.interconnect
-   ~control.input_output_response
-   ~control.linearize
-   ~control.nlsys
-   ~control.summing_junction

doc/iosys.rst

@@ -1,11 +1,160 @@
+..currentmodule control
+
 Nonlinear system models
 =======================
 
+Nonlinear input/output systems are represented as state space systems
+of the form
+
+.. math::
+
+   \frac{dx}{dt} &= f(t, x, u, \theta) \\
+   y &= h(t, x, u, \theta)
+
+where :math:`t` represents the current time, :math:`x` is the system
+state, math:`u` is the system input, :math:`y` is the system output,
+and :math:`\theta` represents a set of parameters.
+
+Discrete time systems are also supported and have dynamics of the form
+
 Creating nonlinear models
 -------------------------
 
+A nonlinear system is created using the :func:`nlsys` factory function::
+
+  sys = ct.nlsys(
+      updfcn[, outfcn], inputs=m, states=n, outputs=p, [, params=params])
+
+The `updfcn` argument is a function returning the state update function::
+  
+  updfcn(t, x, u, params) -> array
+
+where `x` is a 1-D array with shape (n,), `u` is a 1-D array
+with shape (m,), `t` is a float representing the currrent time,
+and `params` is a dict containing the values of parameters used by the
+function.  The dynamics of the system can be in continuous or discrete
+time (use the `dt` keyword to create a discrte time system).
+
+The output function `outfcn` is used to specify the outputs of the
+system and has the same calling signature as `updfcn`.  If it is not
+specified, then the output of the system is set equal to the system
+state.  Otherwise, it should return an output of shape (p,).
+
+Note that the number of states, inputs, and outputs should generally
+be explicitly specified, although some operations can infer the
+dimensions if they are not given when the system is created.  The
+`inputs`, `outputs`, and `states` keywords can also be given as lists
+of strings, in which case the various signals will be given the
+appropriate names.
+
+To illustrate the creation of a nonlinear I/O system model, consider a
+simple model of a spring loaded arm driven by a motor:
+
+.. image:: figures/servomech-diagram.png
+  :width: 240
+
+The dynamics of this system can be modeling using the following code::
+
+  # Parameter values
+  servomech_params = {
+      'J': 100,             # Moment of inertia of the motor
+      'b': 10,              # Angular damping of the arm
+      'k': 1,               # Spring constant
+      'r': 1,               # Location of spring contact on arm
+      'l': 2,               # Distance to the read head
+      'eps': 0.01,          # Magnitude of velocity-dependent perturbation
+  }
+  
+  # State derivative
+  def servomech_update(t, x, u, params):
+      # Extract the configuration and velocity variables from the state vector
+      theta = x[0]                # Angular position of the disk drive arm
+      thetadot = x[1]             # Angular velocity of the disk drive arm
+      tau = u[0]                  # Torque applied at the base of the arm
+  
+      # Get the parameter values
+      J, b, k, r = map(params.get, ['J', 'b', 'k', 'r'])
+  
+      # Compute the angular acceleration
+      dthetadot = 1/J * (
+          -b * thetadot - k * r * np.sin(theta) + tau)
+  
+      # Return the state update law
+      return np.array([thetadot, dthetadot])
+  
+  # System output (tip radial position + angular velocity)
+  def servomech_output(t, x, u, params):
+      l = params['l']
+      return np.array([l * x[0], x[1]])
+  
+  # System dynamics
+  servomech = ct.nlsys(
+      servomech_update, servomech_output, name='servomech',
+      params=servomech_params, states=['theta', 'thdot'],
+      outputs=['y', 'thdot'], inputs=['tau'])
+
+A summary of the model can be obtained using the string representation
+of the model (via the Python `print()` function)::
+
+  >>> print(servomech)
+  <NonlinearIOSystem>: servomech
+  Inputs (1): ['tau']
+  Outputs (2): ['y', 'thdot']
+  States (2): ['theta', 'thdot']
+  Parameters: ['J', 'b', 'k', 'r', 'l', 'eps']
+  
+  Update: <function servomech_update at 0x117a17f60>
+  Output: <function servomech_output at 0x1354e3d80>
+  
+
 Operating points and linearization
 ----------------------------------
 
+A nonlinear input/output system can be linearized around an equilibrium point
+to obtain a :class:`~control.StateSpace` linear system::
+
+  sys_ss = ct.linearize(sys_nl, xeq, ueq)
+
+If the equilibrium point is not known, the
+:func:`find_operating_point` function can be used to obtain an
+equilibrium point. In its simplest form, `find_operating_point` finds
+an equilibrium point 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)
+
+The first form finds an equilibrium point for a given input `u0` based
+on an initial guess `x0`.  The second form fixes the desired output
+values `y0` and uses x0 and u0 as an initial guess to find the
+equilibrium point.  If no equilibrium point can be found, the function
+returns the operating point that minimizes the state update (state
+derivative for continuous time systems, state difference for discrete
+time systems).
+
+More complex operating points can be found by specifying which states,
+inputs, or outputs should be used in computing the operating point, as
+well as desired values of the states, inputs, outputs, or state
+updates.  See the :func:`find_operating_point` documentation for more deatils.
+
+
 Simulations and plotting
 ------------------------
+
+To simulate an input/output system, use the
+:func:`~control.input_output_response` function::
+
+  resp = ct.input_output_response(io_sys, T, U, x0, params)
+  t, y, x = resp.time, resp.outputs, resp.states
+
+Time responses can be plotted using the :func:`time_response_plot`
+function or (equivalently) the :func:`TimeResponseData.plot`
+method::
+
+  cplt = ct.time_response_plot(resp)
+
+The resulting :class:`ControlPlot` object can be used to access
+different plot elements. The :func:`combine_time_responses` function
+an be used to combine multiple time responses into a single
+`TimeResponseData` object.  See the :ref:`response-chapter` chapter
+for more information on this functionality.