reorganize functions.rst, classes.rst

murrayrm · murrayrm · commit 322dba6ec23d · 2025-02-02T20:39:22.000-08:00
diff --git a/doc/classes.rst b/doc/classes.rst
@@ -5,6 +5,9 @@
 Control system classes
 **********************
 
+Input/output system classes
+===========================
+
 The classes listed below are used to represent models of input/output
 systems (both linear time-invariant and nonlinear).  They are usually
 created from factory functions such as :func:`tf` and :func:`ss`, so the
@@ -13,13 +16,14 @@ user should normally not need to instantiate these directly.
 .. autosummary::
    :toctree: generated/
    :template: custom-class-template.rst
+   :nosignatures:
 
    InputOutputSystem
+   NonlinearIOSystem
    LTI
    StateSpace
    TransferFunction
    FrequencyResponseData
-   NonlinearIOSystem
    InterconnectedSystem
    LinearICSystem
 
@@ -30,17 +34,39 @@ another:
 .. image:: figures/classes.pdf
   :width: 800
 
-Additional classes
-==================
 
-.. todo:: Break these up into more useful sections
+Response and plotting classes
+=============================
+
+These classes are used as the outputs of `_response`, `_map`, and
+`_plot` functions:
 
 .. autosummary::
    :toctree: generated/
    :template: custom-class-template.rst
    :nosignatures:
 
    ControlPlot
+   FrequencyResponseData
+   TimeResponseData
+   NyquistResponseData
+   PoleZeroData
+
+More informaton on the functions used to create these classes can be
+found in the :ref:iosys-module chapter.
+
+
+Nonlinear system classes
+========================
+
+These classes are used for various nonlinear input/output system
+operations:
+
+.. autosummary::
+   :toctree: generated/
+   :template: custom-class-template.rst
+   :nosignatures:
+
    DescribingFunctionNonlinearity
    DescribingFunctionResponse
    flatsys.BasisFamily
@@ -50,16 +76,11 @@ Additional classes
    flatsys.LinearFlatSystem
    flatsys.PolyFamily
    flatsys.SystemTrajectory
-   FrequencyResponseList
-   NyquistResponseData
    OperatingPoint
    optimal.OptimalControlProblem
    optimal.OptimalControlResult
    optimal.OptimalEstimationProblem
    optimal.OptimalEstimationResult
-   PoleZeroData
-   TimeResponseData
-   TimeResponseList
 
-The use of these classes is described in more detail in the
-:ref:`flatsys-module` module and the :ref:`optimal-module` module
+More informaton on the functions used to create these classes can be
+found in the :ref:nonlinear-systems chapter.
diff --git a/doc/functions.rst b/doc/functions.rst
@@ -14,8 +14,8 @@ Function reference
 System creation
 ===============
 
-The control toolbox makes use of "factory functions" to create input/output
-systems of different types (classes):
+Functions that create input/output systems from a description of the
+system properties:
 
 .. autosummary::
    :toctree: generated/
@@ -25,10 +25,11 @@ systems of different types (classes):
     frd
     nlsys
     zpk
+    pade
     rss
     drss
 
-Systems can also be created by transforming existing systems:
+Functions that transform systems from one form to another:
 
 .. autosummary::
    :toctree: generated/
@@ -38,7 +39,6 @@ Systems can also be created by transforming existing systems:
     observable_form
     reachable_form
     similarity_transform
-    pade
     ss2tf
     tf2ss
     tfdata
@@ -64,8 +64,9 @@ System interconnections
     combine_tf
     split_tf
 
-Time domain simulation
-======================
+
+Time response
+=============
 
 .. autosummary::
    :toctree: generated/
@@ -78,6 +79,12 @@ Time domain simulation
     step_response
     time_response_plot
     combine_time_responses
+
+Additional functions for customizing phase plots:
+
+.. autosummary::
+   :toctree: generated/
+
     phaseplot.boxgrid
     phaseplot.circlegrid
     phaseplot.equilpoints
@@ -104,52 +111,84 @@ Frequency response
     nichols_plot
     nichols_grid
 
+
 Control system analysis
 =======================
+
+Time domain analysis:
+
 .. autosummary::
    :toctree: generated/
 
-    bandwidth
     damp
+    step_info
+
+Frequency domain analysis:
+
+.. autosummary::
+   :toctree: generated/
+
+    bandwidth
     dcgain
-    get_input_ff_index
-    get_output_fb_index
-    ispassive
     linfnorm
     margin
-    solve_passivity_LMI
     stability_margins
-    step_info
     system_norm
     phase_crossover_frequencies
+    singular_values_plot
+    singular_values_response
+    sisotool
+
+Pole/zero-based analysis:
+
+.. autosummary::
+   :toctree: generated/
+
     poles
     zeros
     pole_zero_map
     pole_zero_plot
     pole_zero_subplots
     root_locus_map
     root_locus_plot
-    singular_values_plot
-    singular_values_response
-    sisotool
+
+Passive systems analysis:
+
+.. autosummary::
+   :toctree: generated/
+
+    get_input_ff_index
+    get_output_fb_index
+    ispassive
+    solve_passivity_LMI
 
 
 Control system synthesis
 ========================
+
+State space synthesis:
+
 .. autosummary::
    :toctree: generated/
 
     acker
     create_statefbk_iosystem
     dlqr
-    h2syn
-    hinfsyn
     lqr
-    mixsyn
     place
     place_varga
+
+Frequency domain synthesis:
+
+.. autosummary::
+   :toctree: generated/
+
+    h2syn
+    hinfsyn
+    mixsyn
     rootlocus_pid_designer
 
+
 System ID and model reduction
 =============================
 .. autosummary::
@@ -162,6 +201,7 @@ System ID and model reduction
     eigensys_realization
     markov
 
+
 Nonlinear system support
 ========================
 .. autosummary::
@@ -170,19 +210,27 @@ Nonlinear system support
     find_operating_point
     linearize
 
-Stochastic system support
-=========================
+Describing functions
+--------------------
 .. autosummary::
    :toctree: generated/
 
-    correlation
-    create_estimator_iosystem
-    dlqe
-    lqe
-    white_noise
+   describing_function
+   friction_backlash_nonlinearity
+   relay_hysteresis_nonlinearity
+   saturation_nonlinearity
+
+Differentially flat systems
+---------------------------
+.. autosummary::
+   :toctree: generated/
+
+   flatsys.flatsys
+   flatsys.point_to_point
+   flatsys.solve_flat_ocp
 
 Optimal control
-===============
+---------------
 .. autosummary::
    :toctree: generated/
 
@@ -200,24 +248,17 @@ Optimal control
    optimal.state_range_constraint
 
 
-Describing functions
-====================
+Stochastic system support
+=========================
 .. autosummary::
    :toctree: generated/
 
-   describing_function
-   friction_backlash_nonlinearity
-   relay_hysteresis_nonlinearity
-   saturation_nonlinearity
-
-Differentially flat systems
-===========================
-.. autosummary::
-   :toctree: generated/
+    correlation
+    create_estimator_iosystem
+    dlqe
+    lqe
+    white_noise
 
-   flatsys.flatsys
-   flatsys.point_to_point
-   flatsys.solve_flat_ocp
 
 Matrix computations
 ===================
diff --git a/doc/nonlinear.rst b/doc/nonlinear.rst
@@ -1,3 +1,5 @@
+.. _nonlinear-systems:
+
 ***********************************************
 Nonlinear System Modeling, Analysis, and Design
 ***********************************************

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+.. _nonlinear-systems:`
	`2`	`+`
`1`	`3`	`***********************************************`
`2`	`4`	`Nonlinear System Modeling, Analysis, and Design`
`3`	`5`	`***********************************************`